@hominis/fireforge 0.49.2 → 0.51.0

package/dist/src/commands/patch/removal-created-files.d.ts

@@ -0,0 +1,48 @@
+/**
+ * What `patch delete` and `patch retire` do to the files the removed patch
+ * claims, shared so both commands say and do the same.
+ *
+ * A file the patch modifies stays in the engine with its edits, unmanaged.
+ * A file the patch creates is different: once the patch is gone nothing
+ * owns it, so a created file still on disk turns into an unmanaged file the
+ * engine-clean gate reports. The summary names each such file (in the dry
+ * run and at the prompt), and `--delete-created` removes them as part of
+ * the confirmed operation.
+ */
+import type { PatchQueueContext } from '../../core/patch-lint.js';
+import type { PatchMetadata } from '../../types/commands/index.js';
+/** The summary lines for a removal's claimed files, and what to delete. */
+export interface ClaimedFilePlan {
+    /** One summary line per claimed file, plus a header. */
+    summary: string[];
+    /** Created files still on disk that the removal will delete. */
+    deleteOnCommit: string[];
+}
+/**
+ * Plans the claimed-file half of a removal.
+ *
+ * @param ctx - Queue context built before the removal
+ * @param target - The patch about to leave the queue
+ * @param engineDir - Engine directory
+ * @param deleteCreated - Whether `--delete-created` was passed
+ */
+export declare function planClaimedFiles(ctx: PatchQueueContext, target: PatchMetadata, engineDir: string, deleteCreated: boolean): Promise<ClaimedFilePlan>;
+/**
+ * Deletes the created files a confirmed removal planned to delete.
+ *
+ * @param engineDir - Engine directory
+ * @param files - Engine-relative paths from {@link planClaimedFiles}
+ */
+export declare function deleteCreatedFiles(engineDir: string, files: readonly string[]): Promise<void>;
+/**
+ * Runs a removal's locked commit, inside the engine-session lock as well
+ * when it will delete engine files, so no engine-mutating peer runs while
+ * created files disappear under it.
+ *
+ * @param projectRoot - Project root directory
+ * @param command - Command name for lock attribution
+ * @param plan - The claimed-file plan
+ * @param waitLockSeconds - Wait budget for the engine lock
+ * @param operation - The patch-directory-locked commit
+ */
+export declare function withCreatedFileLock(projectRoot: string, command: string, plan: ClaimedFilePlan, waitLockSeconds: number | undefined, operation: () => Promise<void>): Promise<void>;

package/dist/src/commands/patch/removal-created-files.js

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * What `patch delete` and `patch retire` do to the files the removed patch
+ * claims, shared so both commands say and do the same.
+ *
+ * A file the patch modifies stays in the engine with its edits, unmanaged.
+ * A file the patch creates is different: once the patch is gone nothing
+ * owns it, so a created file still on disk turns into an unmanaged file the
+ * engine-clean gate reports. The summary names each such file (in the dry
+ * run and at the prompt), and `--delete-created` removes them as part of
+ * the confirmed operation.
+ */
+import { join } from 'node:path';
+import { withEngineSessionLock } from '../../core/engine-session-lock.js';
+import { pathExists, removeFile } from '../../utils/fs.js';
+/**
+ * Plans the claimed-file half of a removal.
+ *
+ * @param ctx - Queue context built before the removal
+ * @param target - The patch about to leave the queue
+ * @param engineDir - Engine directory
+ * @param deleteCreated - Whether `--delete-created` was passed
+ */
+export async function planClaimedFiles(ctx, target, engineDir, deleteCreated) {
+    const created = ctx.entries.find((entry) => entry.filename === target.filename)?.createdFiles;
+    const summary = [`files currently claimed by this patch (${target.filesAffected.length}):`];
+    const deleteOnCommit = [];
+    let lingering = 0;
+    for (const file of target.filesAffected) {
+        if (created?.has(file) !== true) {
+            summary.push(`  ${file}  → will become unmanaged`);
+            continue;
+        }
+        if (!(await pathExists(join(engineDir, file)))) {
+            summary.push(`  ${file}  → created by this patch; already gone`);
+            continue;
+        }
+        if (deleteCreated) {
+            deleteOnCommit.push(file);
+            summary.push(`  ${file}  → created by this patch; will be deleted (--delete-created)`);
+        }
+        else {
+            lingering++;
+            summary.push(`  ${file}  → created by this patch and still on disk: will become unmanaged`);
+        }
+    }
+    if (lingering > 0) {
+        summary.push(`${lingering} created file(s) are still on disk. Delete them first, or pass ` +
+            '--delete-created to remove them with the patch; otherwise status reports them as unmanaged.');
+    }
+    return { summary, deleteOnCommit };
+}
+/**
+ * Deletes the created files a confirmed removal planned to delete.
+ *
+ * @param engineDir - Engine directory
+ * @param files - Engine-relative paths from {@link planClaimedFiles}
+ */
+export async function deleteCreatedFiles(engineDir, files) {
+    for (const file of files) {
+        await removeFile(join(engineDir, file));
+    }
+}
+/**
+ * Runs a removal's locked commit, inside the engine-session lock as well
+ * when it will delete engine files, so no engine-mutating peer runs while
+ * created files disappear under it.
+ *
+ * @param projectRoot - Project root directory
+ * @param command - Command name for lock attribution
+ * @param plan - The claimed-file plan
+ * @param waitLockSeconds - Wait budget for the engine lock
+ * @param operation - The patch-directory-locked commit
+ */
+export async function withCreatedFileLock(projectRoot, command, plan, waitLockSeconds, operation) {
+    if (plan.deleteOnCommit.length === 0) {
+        await operation();
+        return;
+    }
+    await withEngineSessionLock(projectRoot, command, operation, {
+        ...(waitLockSeconds !== undefined ? { waitLockSeconds } : {}),
+    });
+}

package/dist/src/commands/patch/removal-dependents.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The dependency scan `patch delete` and `patch retire` share: which later
+ * patches import a file the removed patch creates, and which staged
+ * declarations name it as their owner. Both commands take the patch out of
+ * the queue, so both must refuse and warn on exactly the same evidence.
+ */
+import type { ConflictReport } from '../../core/destructive.js';
+import { type PatchQueueContext } from '../../core/patch-lint.js';
+import type { PatchMetadata } from '../../types/commands/index.js';
+/**
+ * Lists every later patch site that imports a file `target` creates.
+ *
+ * Both source-site maps are covered: `newFiles` (files the later patch
+ * creates) and `modifiedFileAdditions` (added lines against files that
+ * already exist). Scanning only newFiles misses a later patch adding
+ * `import "./TargetHelper.sys.mjs"` to an existing file. Uses the shared
+ * specifier extractor so dynamic `import()` and
+ * `ChromeUtils.defineESModuleGetters` are picked up: the forward-import lint
+ * rule already covers those forms, and removal safety must match the same
+ * set or it silently drops dependencies.
+ *
+ * @param baseCtx - Queue context built before the removal
+ * @param target - The patch about to leave the queue
+ * @param command - Names for the "queue changed" refusal, e.g.
+ *   `{ noun: 'deletion', verb: 'delete' }`
+ * @returns One description per dependent patch
+ */
+export declare function collectRemovalDependents(baseCtx: PatchQueueContext, target: PatchMetadata, command: {
+    noun: string;
+    verb: string;
+}): string[];
+/**
+ * Warns once per patch whose staged forward-import names `target` as its
+ * owner. The dangling reference also surfaces via cross-patch lint later,
+ * but warning here puts the exact cleanup command in front of the operator
+ * at decision time.
+ *
+ * @param baseCtx - Queue context built before the removal
+ * @param target - The patch about to leave the queue
+ * @param verb - Command name used in the warning ("delete", "retire")
+ */
+export declare function warnDanglingStagedOwners(baseCtx: PatchQueueContext, target: PatchMetadata, verb: string): void;
+/**
+ * The structural conflict a removal with dependents raises.
+ *
+ * The wording spells out the runtime impact: `git apply` does not resolve
+ * imports and succeeds even when a later patch imports a file the target
+ * created, so the queue re-imports cleanly. The breakage surfaces at
+ * browser startup when `ChromeUtils.importESModule` cannot locate the
+ * deleted module. Operators who plan to re-introduce the imported files
+ * (rename, refactor) need to know this is the impact model rather than a
+ * patch-application failure.
+ *
+ * @param dependents - Result of {@link collectRemovalDependents}
+ * @param target - The patch about to leave the queue
+ */
+export declare function removalConflict(dependents: readonly string[], target: PatchMetadata): ConflictReport | null;
+/**
+ * Snapshot of the queue inputs a removal's dependency scan read, compared
+ * again under the lock so a change between the prompt and the commit
+ * refuses instead of committing an unreviewed removal.
+ */
+export declare function queueSnapshot(context: PatchQueueContext): string;

package/dist/src/commands/patch/removal-dependents.js

@@ -0,0 +1,133 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The dependency scan `patch delete` and `patch retire` share: which later
+ * patches import a file the removed patch creates, and which staged
+ * declarations name it as their owner. Both commands take the patch out of
+ * the queue, so both must refuse and warn on exactly the same evidence.
+ */
+import { basename } from 'node:path';
+import { extractImportSpecifiersWithLines, findForwardImportIgnoreLines, isForwardImportableFile, } from '../../core/patch-lint.js';
+import { GeneralError } from '../../errors/base.js';
+import { warn } from '../../utils/logger.js';
+/**
+ * Lists every later patch site that imports a file `target` creates.
+ *
+ * Both source-site maps are covered: `newFiles` (files the later patch
+ * creates) and `modifiedFileAdditions` (added lines against files that
+ * already exist). Scanning only newFiles misses a later patch adding
+ * `import "./TargetHelper.sys.mjs"` to an existing file. Uses the shared
+ * specifier extractor so dynamic `import()` and
+ * `ChromeUtils.defineESModuleGetters` are picked up: the forward-import lint
+ * rule already covers those forms, and removal safety must match the same
+ * set or it silently drops dependencies.
+ *
+ * @param baseCtx - Queue context built before the removal
+ * @param target - The patch about to leave the queue
+ * @param command - Names for the "queue changed" refusal, e.g.
+ *   `{ noun: 'deletion', verb: 'delete' }`
+ * @returns One description per dependent patch
+ */
+export function collectRemovalDependents(baseCtx, target, command) {
+    const targetEntry = baseCtx.entries.find((e) => e.filename === target.filename);
+    if (!targetEntry || JSON.stringify(targetEntry.metadata) !== JSON.stringify(target)) {
+        throw new GeneralError(`Patch queue changed while preparing ${command.noun}. Re-run patch ${command.verb} to review the current target.`);
+    }
+    const targetNewFileLeaves = new Set();
+    for (const fullPath of targetEntry.newFiles.keys()) {
+        targetNewFileLeaves.add(basename(fullPath));
+    }
+    const dependents = [];
+    const scanSite = (entryFilename, sitePath, content) => {
+        if (!isForwardImportableFile(sitePath))
+            return false;
+        const ignoredLines = findForwardImportIgnoreLines(content);
+        const specifiers = extractImportSpecifiersWithLines(content);
+        for (const { specifier, line } of specifiers) {
+            if (ignoredLines.has(line))
+                continue;
+            const cleaned = specifier.split(/[?#]/)[0] ?? specifier;
+            const leaf = basename(cleaned);
+            if (!leaf || !isForwardImportableFile(leaf))
+                continue;
+            if (targetNewFileLeaves.has(leaf)) {
+                dependents.push(`${entryFilename} (${sitePath}) imports "${specifier}" which would be deleted`);
+                return true;
+            }
+        }
+        return false;
+    };
+    for (const entry of baseCtx.entries) {
+        if (entry.filename === target.filename)
+            continue;
+        if (entry.order < target.order)
+            continue;
+        let matched = false;
+        for (const [newFile, content] of entry.newFiles) {
+            if (scanSite(entry.filename, newFile, content)) {
+                matched = true;
+                break;
+            }
+        }
+        if (matched)
+            continue;
+        for (const [modifiedPath, addedContent] of entry.modifiedFileAdditions) {
+            if (scanSite(entry.filename, modifiedPath, addedContent))
+                break;
+        }
+    }
+    return dependents;
+}
+/**
+ * Warns once per patch whose staged forward-import names `target` as its
+ * owner. The dangling reference also surfaces via cross-patch lint later,
+ * but warning here puts the exact cleanup command in front of the operator
+ * at decision time.
+ *
+ * @param baseCtx - Queue context built before the removal
+ * @param target - The patch about to leave the queue
+ * @param verb - Command name used in the warning ("delete", "retire")
+ */
+export function warnDanglingStagedOwners(baseCtx, target, verb) {
+    const holders = baseCtx.entries.filter((entry) => entry.filename !== target.filename &&
+        (entry.metadata?.stagedDependencies?.forwardImports ?? []).some((fi) => fi.owner === target.filename));
+    for (const holder of holders) {
+        warn(`${holder.filename} declares a staged dependency with owner ${target.filename}; ` +
+            `after the ${verb}, update it via "fireforge patch staged-dependency ${holder.filename} --remove ..." ` +
+            'or re-point the owner at the patch that will create the file.');
+    }
+}
+/**
+ * The structural conflict a removal with dependents raises.
+ *
+ * The wording spells out the runtime impact: `git apply` does not resolve
+ * imports and succeeds even when a later patch imports a file the target
+ * created, so the queue re-imports cleanly. The breakage surfaces at
+ * browser startup when `ChromeUtils.importESModule` cannot locate the
+ * deleted module. Operators who plan to re-introduce the imported files
+ * (rename, refactor) need to know this is the impact model rather than a
+ * patch-application failure.
+ *
+ * @param dependents - Result of {@link collectRemovalDependents}
+ * @param target - The patch about to leave the queue
+ */
+export function removalConflict(dependents, target) {
+    if (dependents.length === 0)
+        return null;
+    return {
+        reason: `${dependents.length} later patch(es) contain import statements that reference files created by ${target.filename}. Patch application itself will still succeed, but runtime imports will fail at browser startup until those files are re-introduced.`,
+        details: [...dependents],
+    };
+}
+/**
+ * Snapshot of the queue inputs a removal's dependency scan read, compared
+ * again under the lock so a change between the prompt and the commit
+ * refuses instead of committing an unreviewed removal.
+ */
+export function queueSnapshot(context) {
+    return JSON.stringify(context.entries.map(({ filename, order, diff, metadata }) => ({
+        filename,
+        order,
+        diff,
+        metadata,
+    })));
+}

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

@@ -26,6 +26,7 @@ import { buildPatchQueueContext, formatPatchLintIssue, lintPatchQueue, } from '.
 import { withPatchDirectoryLock } from '../../core/patch-lock.js';
 import { loadPatchesManifest, rewriteStagedDependencyOwners, savePatchesManifest, } from '../../core/patch-manifest.js';
 import { buildProjectedManifest, enforcePatchPolicy, getPatchPolicyCategories, isCategoryAllowedByConfig, } from '../../core/patch-policy.js';
+import { carryReservedSlots, carryRetiredSlots } from '../../core/patch-retired.js';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { toError } from '../../utils/errors.js';
 import { pathExists } from '../../utils/fs.js';
@@ -115,6 +116,17 @@ async function commitRenameUnderLock(input) {
                 ...(descriptionChanging ? { description: newDescription ?? '' } : {}),
             };
         }
+        // A rename onto a retired or reserved order fills that slot.
+        const retired = carryRetiredSlots(fresh, fresh.patches);
+        if (retired === undefined)
+            delete fresh.retired;
+        else
+            fresh.retired = retired;
+        const reserved = carryReservedSlots(fresh, fresh.patches);
+        if (reserved === undefined)
+            delete fresh.reserved;
+        else
+            fresh.reserved = reserved;
         enforcePatchPolicy({
             config: input.config,
             manifest: buildProjectedManifest(fresh, fresh.patches),
@@ -299,11 +311,18 @@ export async function patchRenameCommand(projectRoot, identifier, options = {})
         command: 'patch rename',
         forceUnsafe: options.forceUnsafe === true,
     });
+    // A description-only edit renames nothing and moves no order, so it needs
+    // no confirmation: scripts may change a description without --yes.
+    const descriptionOnly = descriptionChanging &&
+        !filenameChanging &&
+        !nameChanging &&
+        !orderChanging &&
+        !categoryChanging;
     const decision = await confirmDestructive({
         operation: 'patch-rename',
         title: `Rename ${target.filename}`,
         summary,
-        yes: options.yes === true,
+        yes: options.yes === true || descriptionOnly,
         dryRun: isDryRun,
         conflicts: null,
     });

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

@@ -0,0 +1,33 @@
+/**
+ * `fireforge patch reserve <order>`: holds an order number for a patch a
+ * session has agreed to export but has not exported yet.
+ *
+ * The case it exists for: under `patchPolicy.allowGaps: false`, a session
+ * cannot `export --order 571` while a peer has claimed 569 and 570 but not
+ * exported them, because the unfilled orders read as a gap. A reservation
+ * is a placeholder in `patches.json#reserved` that the gap check counts as
+ * occupied and the earliest-legal-order search counts as taken. The export
+ * that lands on the order fills it (see `core/patch-retired.ts`), and
+ * `--release` drops a reservation whose patch will not come.
+ *
+ * Metadata-only: no `.patch` file is written and no row is added, so
+ * apply, lint and rebase never see a reservation.
+ */
+import { Command } from 'commander';
+import type { CommandContext } from '../../types/cli.js';
+import type { PatchReserveOptions } from '../../types/commands/index.js';
+/**
+ * Runs the `patch reserve` command.
+ *
+ * @param projectRoot - Project root directory
+ * @param order - Order number to reserve or release
+ * @param options - Command options
+ */
+export declare function patchReserveCommand(projectRoot: string, order: number, options?: PatchReserveOptions): Promise<void>;
+/**
+ * Registers the `patch reserve` subcommand on the `patch` parent.
+ *
+ * @param parent - Parent Commander command
+ * @param context - Shared CLI registration context
+ */
+export declare function registerPatchReserve(parent: Command, context: CommandContext): void;

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

@@ -0,0 +1,152 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge patch reserve <order>`: holds an order number for a patch a
+ * session has agreed to export but has not exported yet.
+ *
+ * The case it exists for: under `patchPolicy.allowGaps: false`, a session
+ * cannot `export --order 571` while a peer has claimed 569 and 570 but not
+ * exported them, because the unfilled orders read as a gap. A reservation
+ * is a placeholder in `patches.json#reserved` that the gap check counts as
+ * occupied and the earliest-legal-order search counts as taken. The export
+ * that lands on the order fills it (see `core/patch-retired.ts`), and
+ * `--release` drops a reservation whose patch will not come.
+ *
+ * Metadata-only: no `.patch` file is written and no row is added, so
+ * apply, lint and rebase never see a reservation.
+ */
+import { Command } from 'commander';
+import { getProjectPaths, loadConfig } from '../../core/config.js';
+import { appendHistoryBestEffort } from '../../core/history-log.js';
+import { withPatchDirectoryLock } from '../../core/patch-lock.js';
+import { loadPatchesManifestForWrite, savePatchesManifest } from '../../core/patch-manifest.js';
+import { formatPatchOrder } from '../../core/patch-parse.js';
+import { categoryRangeForOrder, categoryRangeLabel, isCategoryAllowedByConfig, } from '../../core/patch-policy.js';
+import { InvalidArgumentError } from '../../errors/base.js';
+import { info, intro, outro } from '../../utils/logger.js';
+import { addWaitLockOption, pickDefined, resolveWaitLockSeconds } from '../../utils/options.js';
+import { parsePositiveIntegerFlag } from '../../utils/validation.js';
+/**
+ * Refuses a reservation the manifest or the policy cannot hold: an order a
+ * patch, a retired slot or another reservation already takes, or one
+ * outside the category's configured ranges.
+ */
+function assertReservable(manifest, config, order, category) {
+    const label = formatPatchOrder(order);
+    const patch = manifest.patches.find((entry) => entry.order === order);
+    if (patch !== undefined) {
+        throw new InvalidArgumentError(`Order ${label} is taken by ${patch.filename}.`, '<order>');
+    }
+    if ((manifest.retired ?? []).some((slot) => slot.order === order)) {
+        throw new InvalidArgumentError(`Order ${label} is a retired slot; "fireforge export --order ${label}" fills it without a reservation.`, '<order>');
+    }
+    const held = manifest.reserved?.find((slot) => slot.order === order);
+    if (held !== undefined) {
+        throw new InvalidArgumentError(`Order ${label} is already reserved by ${held.owner} (since ${held.reservedAt}).`, '<order>');
+    }
+    const policy = config.patchPolicy;
+    if (policy !== undefined && categoryRangeForOrder(policy, category, order) === null) {
+        throw new InvalidArgumentError(`Order ${label} is outside the ${category} range (${categoryRangeLabel(policy.ranges, category)}).`, '<order>');
+    }
+}
+/**
+ * Runs the `patch reserve` command.
+ *
+ * @param projectRoot - Project root directory
+ * @param order - Order number to reserve or release
+ * @param options - Command options
+ */
+export async function patchReserveCommand(projectRoot, order, options = {}) {
+    const releasing = options.release === true;
+    const verb = releasing ? 'release' : 'reserve';
+    intro(options.dryRun ? `FireForge patch ${verb} (dry run)` : `FireForge patch ${verb}`);
+    const config = await loadConfig(projectRoot);
+    const label = formatPatchOrder(order);
+    let category;
+    let owner;
+    if (!releasing) {
+        category = options.category;
+        owner = options.owner?.trim();
+        if (category === undefined || owner === undefined || owner === '') {
+            throw new InvalidArgumentError('patch reserve requires --category and --owner (or --release to drop a reservation).', [category === undefined ? '--category' : '', owner ? '' : '--owner']
+                .filter(Boolean)
+                .join(', '));
+        }
+        if (!isCategoryAllowedByConfig(config, category)) {
+            throw new InvalidArgumentError(`Unknown patch category "${category}".`, '--category');
+        }
+    }
+    else if (options.category !== undefined || options.owner !== undefined) {
+        throw new InvalidArgumentError('--release takes only the order; --category and --owner apply when reserving.', '--release');
+    }
+    const { patches: patchesDir } = getProjectPaths(projectRoot);
+    await withPatchDirectoryLock(patchesDir, async () => {
+        const manifest = (await loadPatchesManifestForWrite(patchesDir)) ?? {
+            version: 1,
+            patches: [],
+        };
+        const reserved = manifest.reserved ?? [];
+        let slot;
+        let next;
+        if (releasing) {
+            const held = reserved.find((entry) => entry.order === order);
+            if (held === undefined) {
+                throw new InvalidArgumentError(`Order ${label} is not reserved.`, '<order>');
+            }
+            slot = held;
+            next = reserved.filter((entry) => entry.order !== order);
+        }
+        else {
+            assertReservable(manifest, config, order, category);
+            slot = {
+                order,
+                category: category,
+                owner: owner,
+                reservedAt: new Date().toISOString(),
+                ...(options.reason !== undefined ? { reason: options.reason } : {}),
+            };
+            next = [...reserved, slot].sort((a, b) => a.order - b.order);
+        }
+        const summary = releasing
+            ? `release order ${label} (reserved by ${slot.owner})`
+            : `reserve order ${label} for ${slot.owner} (category: ${slot.category})`;
+        if (options.dryRun === true) {
+            info(`[dry-run] ${summary}`);
+            return;
+        }
+        if (next.length > 0)
+            manifest.reserved = next;
+        else
+            delete manifest.reserved;
+        await savePatchesManifest(patchesDir, manifest);
+        await appendHistoryBestEffort(patchesDir, {
+            operation: releasing ? 'patch-reserve-release' : 'patch-reserve',
+            args: { ...slot },
+            result: 'ok',
+        }, `patch ${verb} committed (${label})`);
+        info(releasing
+            ? `Released order ${label}.`
+            : `Reserved order ${label} for ${slot.owner}; "fireforge export --order ${label}" fills it.`);
+    }, { waitLockSeconds: resolveWaitLockSeconds(options.waitLock), command: `patch ${verb}` });
+    outro(options.dryRun ? 'Dry run complete — no changes made' : `Patch ${verb} complete`);
+}
+/**
+ * Registers the `patch reserve` subcommand on the `patch` parent.
+ *
+ * @param parent - Parent Commander command
+ * @param context - Shared CLI registration context
+ */
+export function registerPatchReserve(parent, context) {
+    const { getProjectRoot, withErrorHandling } = context;
+    const command = parent
+        .command('reserve <order>')
+        .description('Hold an order number for a patch not exported yet, so patchPolicy.allowGaps: false ' +
+        'sees no gap; the export that takes the order fills it (metadata only)')
+        .option('--category <category>', 'Category the reserved patch will carry')
+        .option('--owner <label>', 'Who holds the reservation (a session label or planned filename)')
+        .option('--reason <text>', 'Rationale recorded on the reserved slot')
+        .option('--release', 'Drop the reservation at <order> instead of creating one')
+        .option('--dry-run', 'Show what would change without writing');
+    addWaitLockOption(command).action(withErrorHandling(async (rawOrder, options) => {
+        await patchReserveCommand(getProjectRoot(), parsePositiveIntegerFlag('<order>', rawOrder), pickDefined(options));
+    }));
+}

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

@@ -0,0 +1,34 @@
+/**
+ * `fireforge patch retire <name>`: removes a patch from the queue and keeps
+ * its order number spent as a retired slot in `patches.json#retired`.
+ *
+ * The case it exists for: a rename leaves a patch owning only files that no
+ * longer exist. `patch delete` opens a numeric gap that
+ * `patchPolicy.allowGaps: false` refuses, and `patch compact` renumbers
+ * every later patch, including ones a peer session has in flight. Retiring
+ * removes the patch file and row like a delete, and records the order as a
+ * placeholder the gap check counts as occupied. Nothing else reads the
+ * placeholder (see `core/patch-retired.ts`), and a later
+ * `export --order <n>` that takes the number fills it.
+ *
+ * Shares the delete's dependency refusal, dry-run, confirmation and history
+ * contract, so the two differ only in what happens to the order number.
+ */
+import { Command } from 'commander';
+import type { CommandContext } from '../../types/cli.js';
+import type { PatchRetireOptions } from '../../types/commands/index.js';
+/**
+ * Runs the `patch retire` command.
+ *
+ * @param projectRoot - Project root directory
+ * @param identifier - Patch filename, ordinal, or manifest name to retire
+ * @param options - Command options
+ */
+export declare function patchRetireCommand(projectRoot: string, identifier: string, options?: PatchRetireOptions): Promise<void>;
+/**
+ * Registers the `patch retire` subcommand on the `patch` parent.
+ *
+ * @param parent - Parent Commander command
+ * @param context - Shared CLI registration context
+ */
+export declare function registerPatchRetire(parent: Command, context: CommandContext): void;