@hominis/fireforge 0.43.0 → 0.44.0

package/dist/src/commands/lint.js

@@ -4,39 +4,37 @@ import { join } from 'node:path';
 import { Command } from 'commander';
 import { isBrandingManagedPath } from '../core/branding.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
+import { assertEngineGitReady } from '../core/engine-precondition.js';
 import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
-import { getStatusWithCodes, hasChanges, isGitRepository } from '../core/git.js';
+import { getStatusWithCodes, hasChanges } from '../core/git.js';
 import { getAllDiff, getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { expandUntrackedDirectoryEntries, getModifiedFilesInDir, getUntrackedFiles, getUntrackedFilesInDir, getWorkingTreeStatus, } from '../core/git-status.js';
-import { clearPerPatchLintCache } from '../core/lint-cache.js';
 import { extractAffectedFiles } from '../core/patch-apply.js';
 import { buildPatchQueueContext, countNonBinaryDiffLines, formatPatchLintIssue, lintExportedPatch, lintPatchQueue, lintPatchSize, } from '../core/patch-lint.js';
+import { clearPerPatchLintCache } from '../core/patch-lint-cache.js';
 import { collectDiffFilePaths, tagLintIssues } from '../core/patch-lint-diff-tag.js';
-import { GeneralError } from '../errors/base.js';
+import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
 import { info, intro, outro, success, warn } from '../utils/logger.js';
 import { stripEnginePrefix } from '../utils/paths.js';
 import { lintPerPatch } from './lint-per-patch.js';
 /**
  * Resolves the diff the lint command should run against. Returns `null` when
- * there is nothing to lint (e.g. no matching files, clean tree, or empty
- * diff content) — callers treat that as the early-exit signal and stop.
+ * there is nothing to lint (no matching files, clean tree, or empty diff
+ * content) — callers treat that as the early-exit signal and stop.
  *
  * Extracted from {@link lintCommand} so that function stays under the
- * per-function LOC budget as the command grows; the two file-mode and
- * aggregate-mode branches share no state with the post-lint reporting
- * pipeline, so the split is a pure rename rather than a refactor.
+ * per-function LOC budget; the two file-mode and aggregate-mode branches
+ * share no state with the post-lint reporting pipeline.
  *
- * When `binaryName` is provided, the aggregate-mode branch (no
- * explicit file list) excludes paths under `browser/branding/<binaryName>/`
- * from the diff. `status` classifies those paths as `branding` —
- * tool-managed material the operator did not author directly — and
- * the 2026-04-21 eval (Finding #2) reported that `fireforge lint` on
- * a fresh project immediately failed `large-patch-lines` /
- * `large-patch-files` / `missing-license-header` on the generated
- * branding tree. File-list mode (explicit paths) preserves the
- * previous behaviour: passing a branding file explicitly still lints
- * it, so operators who need to audit branding content can do so.
+ * When `binaryName` is provided, the aggregate-mode branch (no explicit file
+ * list) excludes paths under `browser/branding/<binaryName>/` from the diff.
+ * `status` classifies those paths as `branding` — tool-managed material the
+ * operator did not author directly — and without the exclusion
+ * `fireforge lint` on a fresh project immediately fails `large-patch-lines`
+ * / `large-patch-files` / `missing-license-header` on the generated branding
+ * tree. File-list mode (explicit paths) is unaffected: passing a branding
+ * file explicitly still lints it.
  */
 async function resolveLintDiff(engineDir, files, binaryName, furnacePrefixes) {
     if (files.length > 0) {
@@ -44,12 +42,12 @@ async function resolveLintDiff(engineDir, files, binaryName, furnacePrefixes) {
         let fileStatuses;
         let untrackedFiles;
         // Strip a leading `engine/` segment up-front so the rest of the lookup
-        // pipeline (directory stat, modified-files-in-dir, status probe) all
-        // see the engine-relative form. Without this, passing
-        // `engine/browser/base/content/foo.js` fell through to "No modified
-        // files found in the specified paths." because git sees every path
+        // pipeline (directory stat, modified-files-in-dir, status probe) sees the
+        // engine-relative form. Without it, passing
+        // `engine/browser/base/content/foo.js` falls through to "No modified
+        // files found in the specified paths.", because git sees every path
         // relative to engine/. The same normalization runs in `register`,
-        // `test`, and `export` via `stripEnginePrefix`.
+        // `test`, and `export`.
         const normalizedFiles = files.map((inputPath) => stripEnginePrefix(inputPath));
         for (const inputPath of normalizedFiles) {
             const fullInputPath = join(engineDir, inputPath);
@@ -98,21 +96,18 @@ async function resolveLintDiff(engineDir, files, binaryName, furnacePrefixes) {
         outro('Nothing to lint');
         return null;
     }
-    // Aggregate-mode branding exclusion. A fresh-setup workspace (after
-    // `fireforge setup` + `download` + `bootstrap` + `build`) carries a
-    // large tool-managed branding diff that the operator did not
-    // author; running the default lint against it fires size and
-    // license-header rules on content that was never intended to
-    // survive in the patch queue as-is. The exclusion mirrors the
-    // `branding` bucket in `fireforge status` so the two views stay
-    // consistent.
+    // Aggregate-mode branding exclusion. A fresh-setup workspace carries a
+    // large tool-managed branding diff the operator did not author; running
+    // the default lint against it fires size and license-header rules on
+    // content that was never intended to survive in the patch queue as-is. The
+    // exclusion mirrors the `branding` bucket in `fireforge status` so the two
+    // views stay consistent.
     //
-    // `expandUntrackedDirectoryEntries` promotes collapsed `?? dir/`
-    // status rows to individual file entries before the diff pass.
-    // Without it, a patch that introduces a new directory shows up as
-    // `?? browser/modules/<fork>/` and `getDiffForFilesAgainstHead`
-    // crashed with EISDIR reading the directory as if it were a file
-    // (eval finding: aggregate lint unusable on a real imported queue).
+    // `expandUntrackedDirectoryEntries` promotes collapsed `?? dir/` status
+    // rows to individual file entries before the diff pass. Without it, a
+    // patch that introduces a new directory shows up as
+    // `?? browser/modules/<fork>/` and `getDiffForFilesAgainstHead` crashes
+    // with EISDIR reading the directory as if it were a file.
     if (binaryName) {
         const rawStatus = await getWorkingTreeStatus(engineDir);
         const expanded = await expandUntrackedDirectoryEntries(engineDir, rawStatus);
@@ -120,12 +115,11 @@ async function resolveLintDiff(engineDir, files, binaryName, furnacePrefixes) {
         const nonBrandingPaths = allPaths.filter((path) => !isBrandingManagedPath(path, binaryName));
         const brandingExcluded = allPaths.length - nonBrandingPaths.length;
         // Drop Furnace-managed paths the same way branding is dropped: their
-        // contents are tool output (overrides, custom widgets, preview-
-        // generated stories) that the operator did not author and never
-        // intended to land on the patch queue. Without this carve-out, a
-        // post-`furnace preview` aggregate `lint` failed with one
-        // `missing-license-header` error per generated story file (eval
-        // Finding 19) — each story is intentionally header-less because it's
+        // contents are tool output (overrides, custom widgets, preview-generated
+        // stories) that the operator did not author and never intended to land
+        // on the patch queue. Without the carve-out, a post-`furnace preview`
+        // aggregate `lint` fails with one `missing-license-header` error per
+        // generated story file — each is intentionally header-less because it is
         // re-generated from component metadata on every preview run.
         const filteredPaths = furnacePrefixes
             ? nonBrandingPaths.filter((path) => ![...furnacePrefixes].some((p) => path.startsWith(p)))
@@ -150,10 +144,8 @@ async function resolveLintDiff(engineDir, files, binaryName, furnacePrefixes) {
         }
         return diff;
     }
-    // Fallback path: no binaryName available (e.g. a legacy caller
-    // without a loaded config). Retain the pre-0.16.0 behaviour of
-    // linting the full diff so the lint surface is at least as broad
-    // as before.
+    // Fallback path: no binaryName available (a caller without a loaded
+    // config). Lint the full diff so the lint surface stays at least as broad.
     const diff = await getAllDiff(engineDir);
     if (!diff.trim()) {
         info('No diff content to lint.');
@@ -169,25 +161,24 @@ function buildMaxWarningsMessage(count, maxWarnings, scope) {
         ' If this is a release gate, run with --per-patch to identify the owning patch. For intentional staged imports, use patch staged-dependency; for ownership repairs, preview patch move-files, patch reorder --dry-run, or re-export --files --dry-run; add scoped lintIgnore only after review.');
 }
 /**
- * Filters aggregate-mode lint issues against per-patch `lintIgnore`
- * lists drawn from the manifest. An issue is dropped when at least one
- * patch whose `filesAffected` covers `issue.file` lists `issue.check`
- * in its `lintIgnore`.
+ * Filters aggregate-mode lint issues against per-patch `lintIgnore` lists
+ * drawn from the manifest. An issue is dropped when at least one patch whose
+ * `filesAffected` covers `issue.file` lists `issue.check` in its
+ * `lintIgnore`.
  *
- * Mirrors the per-patch contract: `--per-patch` mode threads each
- * patch's `lintIgnore` directly into `lintExportedPatch`, so a check
- * the operator explicitly waived in `patches.json` does not surface.
- * Aggregate `--since` mode previously rediscovered the suppressed
- * warning every CI run because the diff was treated as a single unit
- * with no patch-level scope. Attributing each issue's file to its
+ * Mirrors the per-patch contract: `--per-patch` mode threads each patch's
+ * `lintIgnore` directly into `lintExportedPatch`, so a check the operator
+ * explicitly waived in `patches.json` does not surface. Aggregate `--since`
+ * mode has no patch-level scope of its own and would otherwise rediscover
+ * the suppressed warning every CI run. Attributing each issue's file to its
  * owning patch via `filesAffected` re-establishes the same suppression
- * semantics. Cross-patch findings (forward-import, duplicate-creation)
- * still attribute via `issue.file` because the `file` field is the
- * offending site, which is owned by some patch.
+ * semantics. Cross-patch findings (forward-import, duplicate-creation) also
+ * attribute via `issue.file`, which is the offending site and is owned by
+ * some patch.
  *
- * Multiple owners: an issue is dropped if **any** owning patch waived
- * the rule. Conservative — never adds new findings, only drops
- * already-explicitly-waived ones.
+ * Multiple owners: an issue is dropped if **any** owning patch waived the
+ * rule. Conservative — never adds new findings, only drops already-waived
+ * ones.
  *
  * @param issues - Issues collected from the aggregate lint run.
  * @param ctx - Patch queue context used to attribute file → patch.
@@ -233,17 +224,17 @@ function validateLintFlags(options) {
     }
     if (options.maxWarnings !== undefined &&
         (!Number.isInteger(options.maxWarnings) || options.maxWarnings < 0)) {
-        throw new GeneralError('--max-warnings must be a non-negative integer.');
+        throw new InvalidArgumentError('--max-warnings must be a non-negative integer.', '--max-warnings');
     }
     // `--patches` only means something in per-patch mode (it filters the
     // queue); in aggregate/file-list mode there is no patch loop to narrow.
     if (options.patches !== undefined && !options.perPatch) {
-        throw new GeneralError('--patches requires --per-patch.');
+        throw new InvalidArgumentError('--patches requires --per-patch.', '--patches');
     }
     // The JSON report is a per-patch artifact (per-patch size metrics and
     // suppressed issues); aggregate mode has no per-patch rows to report.
     if (options.report !== undefined && !options.perPatch) {
-        throw new GeneralError('--report requires --per-patch.');
+        throw new InvalidArgumentError('--report requires --per-patch.', '--report');
     }
 }
 /**
@@ -272,17 +263,16 @@ function downgradeAggregateSizeRules(issues, files, ctx) {
  * for an ad-hoc explicit-file-list lint, scoped to each file's **owning
  * patch** rather than the combined file list.
  *
- * The default file-list path used to feed every passed file to
- * `lintExportedPatch` as one synthetic patch, so a cross-patch selection of
- * eight files belonging to four patches reported `Patch affects 8 files`
- * even though no single owning patch was oversized. This helper instead
- * groups the affected files by their owning patch (via the manifest's
- * `filesAffected`), then runs `lintPatchSize` against each owner's real file
- * count + diff, honouring that owner's `tier` and `lintIgnore` — so
- * `lint <files>`, `lint --per-patch`, and `re-export --dry-run` agree on the
- * same size findings for the same files. Files no patch claims are evaluated
- * together as one prospective new patch, preserving the pre-export
- * oversized-change warning.
+ * Feeding every passed file to `lintExportedPatch` as one synthetic patch
+ * makes a cross-patch selection of eight files belonging to four patches
+ * report `Patch affects 8 files` even though no single owning patch is
+ * oversized. This helper groups the affected files by their owning patch
+ * (via the manifest's `filesAffected`), then runs `lintPatchSize` against
+ * each owner's real file count + diff, honouring that owner's `tier` and
+ * `lintIgnore` — so `lint <files>`, `lint --per-patch`, and
+ * `re-export --dry-run` agree on the same size findings for the same files.
+ * Files no patch claims are evaluated together as one prospective new patch,
+ * preserving the pre-export oversized-change warning.
  *
  * @param engineDir - Absolute engine directory
  * @param filesAffected - Engine-relative files touched by the ad-hoc diff
@@ -382,7 +372,7 @@ async function reportLintOutcome(engineDir, issues, options) {
     // Exit-code scope: `--only-introduced` narrows the failure criterion to
     // issues tagged `introduced`. Cumulative errors still print so the
     // operator sees the full queue state, but do not fail lint — the
-    // motivating case is a branch whose own diff is clean but whose repo
+    // case this serves is a branch whose own diff is clean but whose repo
     // already carries pre-existing queue errors from older patches.
     const failingErrors = options.onlyIntroduced
         ? errors.filter((i) => i.tag === 'introduced')
@@ -398,13 +388,12 @@ async function reportLintOutcome(engineDir, issues, options) {
         outro('Lint failed');
         throw new GeneralError(buildMaxWarningsMessage(warnings.length, options.maxWarnings));
     }
-    // Notices are advisory and don't count as warnings — emitting "passed
+    // Notices are advisory and do not count as warnings — emitting "passed
     // with warnings" when only notices fired contradicts the preceding
-    // `0 warning(s)` summary line and reads as a regression. Distinguish
-    // the three pass states explicitly. Errors suppressed by
-    // --only-introduced still warrant the "with warnings" outro — they
-    // print as ERROR rows but no longer fail the run, which is the same
-    // contract the operator gets from a real warning.
+    // `0 warning(s)` summary line and reads as a regression. Errors suppressed
+    // by --only-introduced still warrant the "with warnings" outro: they print
+    // as ERROR rows but no longer fail the run, which is the same contract the
+    // operator gets from a real warning.
     const suppressedErrors = options.onlyIntroduced && errors.length > 0;
     if (warnings.length > 0 || suppressedErrors) {
         outro('Lint passed with warnings');
@@ -426,12 +415,7 @@ export async function lintCommand(projectRoot, files, options = {}) {
     intro('FireForge Lint');
     validateLintFlags(options);
     const paths = getProjectPaths(projectRoot);
-    if (!(await pathExists(paths.engine))) {
-        throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
-    }
-    if (!(await isGitRepository(paths.engine))) {
-        throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
-    }
+    await assertEngineGitReady(paths.engine);
     if (options.perPatch) {
         // Positional arguments in per-patch mode select PATCHES through the
         // same alias resolution as --patches — a non-matching
@@ -441,11 +425,8 @@ export async function lintCommand(projectRoot, files, options = {}) {
         await lintPerPatch(projectRoot, paths, perPatchOptions);
         return;
     }
-    // Load the config before resolving the diff so we can pass
-    // `binaryName` into the aggregate-mode branding exclusion in
-    // `resolveLintDiff`. The config was previously loaded only after
-    // the diff was resolved; hoisting it is cheap and keeps the two
-    // call sites close together.
+    // Load the config before resolving the diff so `binaryName` can be passed
+    // into the aggregate-mode branding exclusion in `resolveLintDiff`.
     const config = await loadConfig(projectRoot);
     // Pull the Furnace-managed prefix set up-front so aggregate lint can
     // mirror the branding exclusion for Furnace material — without it,
@@ -469,7 +450,10 @@ export async function lintCommand(projectRoot, files, options = {}) {
     // selection synthesises a phantom oversized patch from the file count.
     const fileListMode = files.length > 0 && ctx !== undefined;
     let issues = [
-        ...(await lintExportedPatch(paths.engine, filesAffected, diff, config, ctx, undefined, undefined, fileListMode ? { skipPatchSize: true } : undefined)),
+        ...(await lintExportedPatch(paths.engine, filesAffected, diff, config, {
+            ...(ctx ? { patchQueueCtx: ctx } : {}),
+            ...(fileListMode ? { skipPatchSize: true } : {}),
+        })),
     ];
     if (files.length > 0 && ctx) {
         issues.push(...(await lintOwningPatchSizes(paths.engine, filesAffected, ctx)));
@@ -481,11 +465,11 @@ export async function lintCommand(projectRoot, files, options = {}) {
         issues.push(...lintPatchQueue(ctx));
     }
     // Honor per-patch `lintIgnore` in aggregate mode by attributing each
-    // issue's file to its owning patches via the manifest's
-    // `filesAffected`. Per-patch mode threads `lintIgnore` directly into
-    // `lintExportedPatch`; aggregate mode previously had no patch-level
-    // scope to consult, so a check an operator had explicitly waived in
-    // `patches.json` re-surfaced on every `--since` run (CI default).
+    // issue's file to its owning patches via the manifest's `filesAffected`.
+    // Per-patch mode threads `lintIgnore` directly into `lintExportedPatch`;
+    // aggregate mode has no patch-level scope to consult, so a check an
+    // operator explicitly waived in `patches.json` re-surfaces on every
+    // `--since` run (the CI default).
     if (ctx) {
         const result = applyAggregateLintIgnoreSuppression(issues, ctx);
         issues = result.issues;
@@ -532,7 +516,7 @@ export function registerLint(program, { getProjectRoot, withErrorHandling }) {
         if (options.maxWarnings !== undefined) {
             const maxWarnings = Number(options.maxWarnings);
             if (!Number.isInteger(maxWarnings) || maxWarnings < 0) {
-                throw new GeneralError('--max-warnings must be a non-negative integer.');
+                throw new InvalidArgumentError('--max-warnings must be a non-negative integer.', '--max-warnings');
             }
             lintOptions.maxWarnings = maxWarnings;
         }

package/dist/src/commands/package.js

@@ -3,12 +3,11 @@ import { Command } from 'commander';
 import { validateBrandOverride } from '../core/brand-validation.js';
 import { prepareBuildEnvironment } from '../core/build-prepare.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
+import { assertEngineExists } from '../core/engine-precondition.js';
 import { hasBuildArtifacts, machPackageCapture } from '../core/mach.js';
 import { assertBuildArtifacts } from '../core/mach-build-artifacts.js';
 import { explainMachError } from '../core/mach-error-hints.js';
-import { GeneralError } from '../errors/base.js';
 import { BuildError } from '../errors/build.js';
-import { pathExists } from '../utils/fs.js';
 import { error, info, intro, outro, verbose } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
 /**
@@ -24,9 +23,7 @@ export async function packageCommand(projectRoot, options) {
     const paths = getProjectPaths(projectRoot);
     validateBrandOverride(config.binaryName, options.brand);
     // Check if engine exists
-    if (!(await pathExists(paths.engine))) {
-        throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
-    }
+    await assertEngineExists(paths.engine);
     const buildCheck = await hasBuildArtifacts(paths.engine);
     assertBuildArtifacts(paths.engine, buildCheck, {
         label: 'Package',
@@ -48,12 +45,10 @@ export async function packageCommand(projectRoot, options) {
     let result;
     try {
         // `machPackageCapture` streams output live AND captures the tail for
-        // post-run diagnostics. Previously `machPackage` inherited stdio
-        // only, so a targeted hint translator could not see the failure text.
-        // The captured stderr is fed through `explainMachError` below so
-        // recognised failure modes (notably the `packager.py` NoneType trip
-        // the evaluator hit on `mybrowser/`) get an actionable hint prepended
-        // to the raw mach output the operator already saw.
+        // post-run diagnostics; an inherit-only dispatch leaves the hint
+        // translator unable to see the failure text. The captured stderr is fed
+        // through `explainMachError` below so recognised failure modes get an
+        // actionable hint prepended to the raw mach output.
         result = await machPackageCapture(paths.engine);
     }
     catch (error) {

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

@@ -143,7 +143,7 @@ export async function patchCompactCommand(projectRoot, options = {}) {
         outro('Dry run complete — no changes made');
         return;
     }
-    if (decision === 'cancelled') {
+    if (decision === 'declined') {
         outro('Compact cancelled');
         return;
     }

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

@@ -35,15 +35,10 @@ export async function patchDeleteCommand(projectRoot, identifier, options = {})
     // Build the full queue context once so we can scan each patch's newFiles
     // without re-parsing for the dependency check below.
     const baseCtx = await buildPatchQueueContext(paths.patches);
-    // Hard refusal: run the forward-import rule against the projected state.
-    // Any issue that names the target patch in its message still applies; any
-    // new forward-import that appears *only because the target is gone* means
-    // another patch was depending on the target's newly-created files.
-    // Simpler check: run the rule on the *original* context and look for
-    // imports that resolve into the target's new files from earlier patches.
-    // Even simpler: an import owned by a later patch pointing at any of the
-    // target's newly-created files is a dependency on the target. We build
-    // that check directly from baseCtx.
+    // Hard refusal: an import owned by a LATER patch that points at any of
+    // the target's newly-created files is a dependency on the target. That
+    // check is built directly from `baseCtx` rather than by diffing lint runs
+    // over a projected state.
     const targetEntry = baseCtx.entries.find((e) => e.filename === target.filename);
     const targetNewFileLeaves = new Set();
     if (targetEntry) {
@@ -53,17 +48,15 @@ export async function patchDeleteCommand(projectRoot, identifier, options = {})
     }
     // Scan every later patch's new files AND its added lines on pre-existing
     // files for import specifiers that resolve to a leaf owned by the target.
-    // Uses the shared specifier extractor so dynamic import() and
-    // ChromeUtils.defineESModuleGetters are picked up — the forward-import
-    // lint rule already covers those forms and delete safety must match the
+    // Uses the shared specifier extractor so dynamic `import()` and
+    // `ChromeUtils.defineESModuleGetters` are picked up — the forward-import
+    // lint rule already covers those forms, and delete safety must match the
     // same set or it silently drops dependencies.
     //
-    // We cover both source-site maps: `newFiles` (files the later patch
+    // Both source-site maps are covered: `newFiles` (files the later patch
     // creates) and `modifiedFileAdditions` (added lines against files that
-    // already exist). Scanning only newFiles was the second-degree miss
-    // that motivated this change — a later patch could add
-    // `import "./TargetHelper.sys.mjs"` to an existing file and the delete
-    // guard would never see the dependency.
+    // already exist). Scanning only newFiles misses a later patch adding
+    // `import "./TargetHelper.sys.mjs"` to an existing file.
     const dependents = [];
     const scanSite = (entryFilename, sitePath, content) => {
         if (!isForwardImportableFile(sitePath))
@@ -117,14 +110,13 @@ export async function patchDeleteCommand(projectRoot, identifier, options = {})
     const conflicts = dependents.length > 0
         ? {
             // Wording deliberately clarifies the *runtime* impact: `git apply`
-            // doesn't resolve imports and will succeed even when a later patch
-            // imports a file the target created (the eval observed this
-            // directly — forcing the delete and re-importing the remaining
-            // 20-patch queue was clean). The breakage surfaces at browser
-            // startup when `ChromeUtils.importESModule` can't locate the
-            // deleted module. Operators who deliberately plan to re-introduce
-            // the imported files (rename, refactor) need to know this is the
-            // impact model, not a patch-application failure.
+            // 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 deliberately plan to re-introduce the imported
+            // files (rename, refactor) need to know this is the impact model,
+            // not a patch-application failure.
             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,
         }
@@ -150,19 +142,18 @@ export async function patchDeleteCommand(projectRoot, identifier, options = {})
         outro('Dry run complete — no changes made');
         return;
     }
-    if (decision === 'cancelled') {
+    if (decision === 'declined') {
         outro('Delete cancelled');
         return;
     }
     // Proceed: remove under the patch directory lock so concurrent exports
     // cannot race us into the same manifest row. The history append lives
-    // inside the same lock so two concurrent deletes cannot interleave
-    // history records beyond what POSIX O_APPEND atomicity guarantees for a
-    // single record, and so a crash between mutation and history write
-    // cannot leave a committed mutation with no audit trail alongside a
-    // concurrent mutation's record appearing first. A history append
-    // failure is warned but not re-thrown: by that point the mutation
-    // has committed and reporting failure to the caller would mislead.
+    // inside the same lock so two concurrent deletes cannot interleave history
+    // records beyond what POSIX O_APPEND guarantees for a single record, and
+    // so a crash between mutation and history write cannot leave a committed
+    // mutation with no audit trail. A history append failure is warned but not
+    // re-thrown: by that point the mutation has committed, and reporting
+    // failure to the caller would mislead.
     await withPatchDirectoryLock(paths.patches, async () => {
         await removePatchFileAndManifest(paths.patches, target.filename);
         try {

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

@@ -1,10 +1,9 @@
 /**
- * `fireforge patch <verb>` parent command. Groups single-patch
- * mutations and planners (`compact`, `delete`, `lint-ignore`, `move-files`,
- * `rename`, `reorder`, `staged-dependency`, `tier`) so they do not clutter the top-level command
- * list.
- * Queue-level verbs like `lint`, `export`, `verify`, and `status` stay
- * flat.
+ * `fireforge patch <verb>` parent command. Groups single-patch mutations and
+ * planners (`compact`, `delete`, `lint-ignore`, `move-files`, `rename`,
+ * `reorder`, `staged-dependency`, `tier`) so they do not clutter the
+ * top-level command list. Queue-level verbs like `lint`, `export`, `verify`,
+ * and `status` stay flat.
  */
 import { Command } from 'commander';
 import type { CommandContext } from '../../types/cli.js';

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

@@ -1,11 +1,10 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * `fireforge patch <verb>` parent command. Groups single-patch
- * mutations and planners (`compact`, `delete`, `lint-ignore`, `move-files`,
- * `rename`, `reorder`, `staged-dependency`, `tier`) so they do not clutter the top-level command
- * list.
- * Queue-level verbs like `lint`, `export`, `verify`, and `status` stay
- * flat.
+ * `fireforge patch <verb>` parent command. Groups single-patch mutations and
+ * planners (`compact`, `delete`, `lint-ignore`, `move-files`, `rename`,
+ * `reorder`, `staged-dependency`, `tier`) so they do not clutter the
+ * top-level command list. Queue-level verbs like `lint`, `export`, `verify`,
+ * and `status` stay flat.
  */
 import { Command } from 'commander';
 import { registerPatchCompact } from './compact.js';
@@ -27,12 +26,11 @@ export function registerPatch(program, context) {
     const patch = program
         .command('patch')
         .description('Manage individual patches in the queue (compact, delete, lint-ignore, move-files, rename, reorder, staged-dependency, tier)')
-        // Match `fireforge furnace`'s no-args contract: print the group's help and
-        // exit 0. Without this default action, commander routes `fireforge patch`
-        // (no subcommand) through its own help-then-exit-1 path, so scripts that
-        // probe the CLI surface see a misleading non-zero exit for a purely
-        // informational invocation. The action prints the exact same help commander
-        // would otherwise print, but returns successfully.
+        // Match `fireforge furnace`'s no-args contract: print the group's help
+        // and exit 0. Without this default action, commander routes
+        // `fireforge patch` (no subcommand) through its own help-then-exit-1
+        // path, so scripts probing the CLI surface see a misleading non-zero
+        // exit for a purely informational invocation.
         .action(() => {
         patch.outputHelp();
     });

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

@@ -25,14 +25,14 @@ import { mutatePatchMetadata } from '../../core/patch-export.js';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { toError } from '../../utils/errors.js';
 import { info, intro, outro, warn } from '../../utils/logger.js';
-import { stringListOption } from '../../utils/options.js';
+import { addWaitLockOption, resolveWaitLockSeconds, stringListOption, } from '../../utils/options.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.
+ * commonly audit lintIgnore lists against a reviewed allow-map — discovering
+ * that the map also needs updating otherwise costs a full downstream gate
+ * run.
  */
 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 ' +
@@ -121,10 +121,9 @@ export async function patchLintIgnoreCommand(projectRoot, identifier, options =
     const target = requirePatchTarget(identifier, manifest.patches);
     // Destructive-operation contract (docs/lifecycle-invariants.md): manifest
     // metadata mutations get summary + dry-run + confirmation/--yes + history
-    // uniformly. This command used to accept --yes without ever prompting, so
-    // the flag only appeared in the history record — and suppressing lint
-    // findings is precisely the mutation an operator should consciously
-    // approve.
+    // uniformly. Accepting --yes without ever prompting makes the flag appear
+    // only in the history record — and suppressing lint findings is precisely
+    // the mutation an operator should consciously approve.
     const currentList = target.lintIgnore ?? [];
     const projectedList = applyMode(currentList, mode, values) ?? [];
     const addsNewIds = mode === 'add' && projectedList.length > currentList.length;
@@ -143,7 +142,7 @@ export async function patchLintIgnoreCommand(projectRoot, identifier, options =
         outro('Dry run complete — no changes made');
         return;
     }
-    if (decision === 'cancelled') {
+    if (decision === 'declined') {
         outro('Cancelled — no changes made');
         return;
     }
@@ -155,7 +154,7 @@ export async function patchLintIgnoreCommand(projectRoot, identifier, options =
         // in the typed `Partial<PatchMetadata>`, and the unset list is
         // applied via `delete` after spread.
         return next !== undefined ? { set: { lintIgnore: next } } : { unset: ['lintIgnore'] };
-    });
+    }, { waitLockSeconds: resolveWaitLockSeconds(options.waitLock), command: 'patch lint-ignore' });
     if (!result) {
         // Race: target vanished between the manifest read above and the
         // locked mutate. Surfacing as a hard error rather than a silent
@@ -195,15 +194,15 @@ export async function patchLintIgnoreCommand(projectRoot, identifier, options =
  */
 export function registerPatchLintIgnore(parent, context) {
     const { getProjectRoot, withErrorHandling } = context;
-    parent
+    const command = parent
         .command('lint-ignore <name>')
         .description('Edit PatchMetadata.lintIgnore on a single patch (no .patch body rewrite). One mode per invocation.')
         .option('--add <check-id>', 'Lint check ID to add to the patch lintIgnore list (repeatable)', ...stringListOption())
         .option('--remove <check-id>', 'Lint check ID to remove from the patch lintIgnore list (repeatable)', ...stringListOption())
         .option('--clear', 'Drop the lintIgnore field entirely')
         .option('--dry-run', 'Show what would change without writing')
-        .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)')
-        .action(withErrorHandling(async (name, options) => {
+        .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)');
+    addWaitLockOption(command).action(withErrorHandling(async (name, options) => {
         // Commander defaults `--add`/`--remove` to `[]` so they appear in
         // the options object even when unused. Strip empty arrays so
         // `pickDefined` sees them as absent — otherwise the mode-count
@@ -219,6 +218,8 @@ export function registerPatchLintIgnore(parent, context) {
             normalized.dryRun = true;
         if (options.yes === true)
             normalized.yes = true;
+        if (options.waitLock !== undefined)
+            normalized.waitLock = options.waitLock;
         await patchLintIgnoreCommand(getProjectRoot(), name, normalized);
     }));
 }