@hominis/fireforge 0.43.1 → 0.44.1

package/dist/src/errors/codes.d.ts

@@ -48,6 +48,22 @@ export declare const ExitCode: {
      * missing profile, etc.).
      */
     readonly SMOKE_LAUNCH_FAILURE: 13;
+    /**
+     * A `fireforge test` run produced a harness result that cannot be trusted
+     * — `engine/` moved (or became unprobeable) while the tests ran. Distinct
+     * from BUILD_ERROR because the two are opposites: a 5 is a suite that
+     * FAILED, a 14 is a suite whose result was THROWN AWAY. A consumer should
+     * re-run a 14 (after settling the writers) and must not report it as red.
+     */
+    readonly INCONCLUSIVE: 14;
+    /**
+     * A lock wait expired: the run never started, because another FireForge
+     * process held the lock for the whole budget. Distinct from GENERAL_ERROR
+     * because nothing about the request was wrong — a consumer should re-queue
+     * it, with a larger `--wait-lock` budget, rather than treat it as a
+     * failure of the work it asked for.
+     */
+    readonly LOCK_TIMEOUT: 15;
     /**
      * The user cancelled an interactive prompt. 130 = 128 + SIGINT, the
      * conventional "interrupted by the user" code — scripts and CI can tell

package/dist/src/errors/codes.js

@@ -49,6 +49,22 @@ export const ExitCode = {
      * missing profile, etc.).
      */
     SMOKE_LAUNCH_FAILURE: 13,
+    /**
+     * A `fireforge test` run produced a harness result that cannot be trusted
+     * — `engine/` moved (or became unprobeable) while the tests ran. Distinct
+     * from BUILD_ERROR because the two are opposites: a 5 is a suite that
+     * FAILED, a 14 is a suite whose result was THROWN AWAY. A consumer should
+     * re-run a 14 (after settling the writers) and must not report it as red.
+     */
+    INCONCLUSIVE: 14,
+    /**
+     * A lock wait expired: the run never started, because another FireForge
+     * process held the lock for the whole budget. Distinct from GENERAL_ERROR
+     * because nothing about the request was wrong — a consumer should re-queue
+     * it, with a larger `--wait-lock` budget, rather than treat it as a
+     * failure of the work it asked for.
+     */
+    LOCK_TIMEOUT: 15,
     /**
      * The user cancelled an interactive prompt. 130 = 128 + SIGINT, the
      * conventional "interrupted by the user" code — scripts and CI can tell

package/dist/src/errors/furnace.d.ts

@@ -8,10 +8,10 @@ export declare class FurnaceError extends FireForgeError {
     constructor(message: string, component?: string | undefined, cause?: Error, options?: {
         /**
          * Suppresses the "run furnace validate" advice line. Set by callers
-         * whose message already tells the user to run validate (or that ARE
-         * the validate command) — an explicit flag, because the previous
-         * `message.includes('furnace validate')` sniffing dropped the advice
-         * from any error that merely MENTIONED the command.
+         * whose message already tells the user to run validate, or that ARE
+         * the validate command. An explicit flag rather than sniffing the
+         * message for `furnace validate`, which drops the advice from any
+         * error that merely MENTIONS the command.
          */
         omitValidateAdvice?: boolean;
     });

package/dist/src/errors/git.d.ts

@@ -48,17 +48,13 @@ export declare class GitIndexLockError extends GitError {
  */
 export declare function isGitIndexLockConflict(error: unknown): boolean;
 /**
- * Error thrown when `git add` (monolithic or chunked) exceeds the
- * configured timeout while indexing the Firefox source tree.
+ * Error thrown when `git add` (monolithic or chunked) exceeds the configured
+ * timeout while indexing the Firefox source tree.
  *
- * 2026-04-24 eval Finding 10: a 140.10.0esr bump on a previously-working
- * 140.9.0esr workspace aborted after ~854s with a generic
- * `AbortError: The operation was aborted`. The root cause was the
- * `git add` timeout firing, but the surfaced error was indistinguishable
- * from any other AbortError and gave the operator no actionable
- * direction. This typed error carries the elapsed budget and the
- * environment-variable override so the recovery path is
- * self-documenting.
+ * A bare `AbortError: The operation was aborted` after ~15 minutes is
+ * indistinguishable from any other AbortError and gives the operator no
+ * actionable direction. This typed error carries the elapsed budget and the
+ * environment-variable override so the recovery path is self-documenting.
  */
 export declare class GitIndexingTimeoutError extends GitError {
     readonly phase: 'monolithic' | 'chunked';

package/dist/src/errors/git.js

@@ -114,17 +114,13 @@ export function isGitIndexLockConflict(error) {
         /(unable to create|another git process seems to be running|file exists|locked)/i.test(error.message));
 }
 /**
- * Error thrown when `git add` (monolithic or chunked) exceeds the
- * configured timeout while indexing the Firefox source tree.
+ * Error thrown when `git add` (monolithic or chunked) exceeds the configured
+ * timeout while indexing the Firefox source tree.
  *
- * 2026-04-24 eval Finding 10: a 140.10.0esr bump on a previously-working
- * 140.9.0esr workspace aborted after ~854s with a generic
- * `AbortError: The operation was aborted`. The root cause was the
- * `git add` timeout firing, but the surfaced error was indistinguishable
- * from any other AbortError and gave the operator no actionable
- * direction. This typed error carries the elapsed budget and the
- * environment-variable override so the recovery path is
- * self-documenting.
+ * A bare `AbortError: The operation was aborted` after ~15 minutes is
+ * indistinguishable from any other AbortError and gives the operator no
+ * actionable direction. This typed error carries the elapsed budget and the
+ * environment-variable override so the recovery path is self-documenting.
  */
 export class GitIndexingTimeoutError extends GitError {
     phase;

package/dist/src/errors/patch.d.ts

@@ -2,13 +2,13 @@ import { FireForgeError } from './base.js';
 /**
  * Error thrown when `patches.json` exists but cannot be parsed or validated.
  *
- * This must be a HARD error on every mutating path. The historical behavior
- * collapsed "corrupt" into "absent" (`loadPatchesManifest` returned null for
- * both), so the next `fireforge export` would rebuild the manifest containing
- * only the new patch — silently destroying every other patch's metadata
- * (tiers, descriptions, lintIgnore, staged dependencies) — and a failed
- * export's rollback would then delete `patches.json` outright because the
- * "before" state looked absent (2026-07-05 review, finding H2).
+ * This must be a HARD error on every mutating path. Collapsing "corrupt"
+ * into "absent" — a `loadPatchesManifest` that returns null for both — makes
+ * the next `fireforge export` rebuild the manifest containing only the new
+ * patch, silently destroying every other patch's metadata (tiers,
+ * descriptions, lintIgnore, staged dependencies); a failed export's rollback
+ * then deletes `patches.json` outright, because the "before" state looked
+ * absent.
  */
 export declare class PatchManifestCorruptError extends FireForgeError {
     readonly manifestPath: string;

package/dist/src/errors/patch.js

@@ -4,13 +4,13 @@ import { ExitCode } from './codes.js';
 /**
  * Error thrown when `patches.json` exists but cannot be parsed or validated.
  *
- * This must be a HARD error on every mutating path. The historical behavior
- * collapsed "corrupt" into "absent" (`loadPatchesManifest` returned null for
- * both), so the next `fireforge export` would rebuild the manifest containing
- * only the new patch — silently destroying every other patch's metadata
- * (tiers, descriptions, lintIgnore, staged dependencies) — and a failed
- * export's rollback would then delete `patches.json` outright because the
- * "before" state looked absent (2026-07-05 review, finding H2).
+ * This must be a HARD error on every mutating path. Collapsing "corrupt"
+ * into "absent" — a `loadPatchesManifest` that returns null for both — makes
+ * the next `fireforge export` rebuild the manifest containing only the new
+ * patch, silently destroying every other patch's metadata (tiers,
+ * descriptions, lintIgnore, staged dependencies); a failed export's rollback
+ * then deletes `patches.json` outright, because the "before" state looked
+ * absent.
  */
 export class PatchManifestCorruptError extends FireForgeError {
     manifestPath;

package/dist/src/errors/rebase.d.ts

@@ -21,11 +21,11 @@ export declare class NoRebaseSessionError extends RebaseError {
 /**
  * Thrown when the session file exists but cannot be used.
  *
- * This case had no error of its own before 0.41.0 and was reported as
+ * Without an error of its own, this case is reported as
  * {@link NoRebaseSessionError} by `--continue`/`--abort` while `rebase`
- * reported {@link RebaseSessionExistsError} — a closed cycle in which each
- * command pointed at the other two. The message names the file so an operator
- * always has a way out, and `--abort` now clears a corrupt session rather than
+ * reports {@link RebaseSessionExistsError} — a closed cycle in which each
+ * command points at the other two. The message names the file so an operator
+ * always has a way out, and `--abort` clears a corrupt session rather than
  * refusing to run against one.
  */
 export declare class CorruptRebaseSessionError extends RebaseError {

package/dist/src/errors/rebase.js

@@ -35,11 +35,11 @@ export class NoRebaseSessionError extends RebaseError {
 /**
  * Thrown when the session file exists but cannot be used.
  *
- * This case had no error of its own before 0.41.0 and was reported as
+ * Without an error of its own, this case is reported as
  * {@link NoRebaseSessionError} by `--continue`/`--abort` while `rebase`
- * reported {@link RebaseSessionExistsError} — a closed cycle in which each
- * command pointed at the other two. The message names the file so an operator
- * always has a way out, and `--abort` now clears a corrupt session rather than
+ * reports {@link RebaseSessionExistsError} — a closed cycle in which each
+ * command points at the other two. The message names the file so an operator
+ * always has a way out, and `--abort` clears a corrupt session rather than
  * refusing to run against one.
  */
 export class CorruptRebaseSessionError extends RebaseError {

package/dist/src/index.d.ts

@@ -8,9 +8,15 @@
  * but may change between minor versions until 1.0 is released. Pin to an
  * exact version if you depend on the programmatic API.
  *
+ * **What belongs here:** a type earns a place on this surface only if it is
+ * reachable from the signature of an exported VALUE — i.e. a consumer needs
+ * it to name an argument or a return. Everything else stays internal to
+ * `src/types/`.
+ *
  * @packageDocumentation
  */
 export { loadConfig, validateConfig } from './core/config.js';
+export type { ApplyAllComponentsResult } from './core/furnace-apply.js';
 export { applyAllComponents } from './core/furnace-apply.js';
 export { ensureFurnaceConfig, loadFurnaceConfig, loadFurnaceState, saveFurnaceState, validateFurnaceConfig, } from './core/furnace-config.js';
 export { validateAllComponents, validateComponent } from './core/furnace-validate.js';
@@ -20,4 +26,4 @@ export type { AddTokenOptions, AddTokenResult, TokenMode } from './core/token-ma
 export { addToken, getTokensCssPath, validateTokenAdd } from './core/token-manager.js';
 export { CancellationError, CommandError, FireForgeError, GeneralError, InvalidArgumentError, ResolutionError, } from './errors/base.js';
 export { ExitCode } from './errors/codes.js';
-export type { ApplyResult, BuildConfig, BuildMode, BuildOptions, ComponentType, CustomComponentConfig, DiscardOptions, DoctorCheck, DownloadOptions, DryRunAction, ExportOptions, FireForgeConfig, FireForgeState, FirefoxConfig, FirefoxProduct, FurnaceConfig, FurnaceCreateOptions, FurnaceOverrideOptions, FurnaceRemoveOptions, FurnaceState, GlobalOptions, ImportOptions, ImportSummary, OverrideComponentConfig, OverrideType, PackageOptions, PatchCategory, PatchesManifest, PatchInfo, PatchLintIssue, PatchMetadata, PatchResult, ProjectLicense, ProjectPaths, ProjectStatus, ReExportOptions, RegistrationStatus, ResetOptions, RunOptions, ScannedComponent, SetupOptions, StepError, SyncResult, TestOptions, TokenCoverageFileEntry, TokenCoverageReport, ValidationIssue, WireConfig, } from './types/index.js';
+export type { ApplyResult, BuildConfig, ComponentType, CustomComponentConfig, DryRunAction, FireForgeConfig, FirefoxConfig, FirefoxProduct, FurnaceConfig, FurnaceState, OverrideComponentConfig, OverrideType, ProjectLicense, StepError, ValidationIssue, WireConfig, } from './types/index.js';

package/dist/src/index.js

@@ -9,6 +9,11 @@
  * but may change between minor versions until 1.0 is released. Pin to an
  * exact version if you depend on the programmatic API.
  *
+ * **What belongs here:** a type earns a place on this surface only if it is
+ * reachable from the signature of an exported VALUE — i.e. a consumer needs
+ * it to name an argument or a return. Everything else stays internal to
+ * `src/types/`.
+ *
  * @packageDocumentation
  */
 export { loadConfig, validateConfig } from './core/config.js';

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

@@ -1,6 +1,6 @@
 /**
  * Re-exports all command-related types from focused sub-modules.
  */
-export type { BuildOptions, DiscardOptions, DoctorOptions, DownloadOptions, ExportOptions, FurnaceApplyOptions, FurnaceCreateOptions, FurnaceDeployOptions, FurnaceOverrideOptions, FurnacePreviewOptions, FurnaceRefreshOptions, FurnaceRemoveOptions, FurnaceSyncOptions, FurnaceValidateOptions, GlobalOptions, ImportOptions, LintCommandOptions, PackageOptions, PatchCompactOptions, PatchDeleteOptions, PatchLintIgnoreOptions, PatchMoveFilesOptions, PatchRenameOptions, PatchReorderOptions, PatchSplitOptions, PatchStagedDependencyOptions, PatchTierOptions, RebaseOptions, ReExportOptions, RegisterOptions, ResetOptions, RunOptions, SetupOptions, SourceSetOptions, StatusOptions, TestOptions, TokenAddOptions, WireOptions, } from './options.js';
+export type { BuildOptions, DiscardOptions, DoctorOptions, DownloadOptions, ExportOptions, FurnaceApplyOptions, FurnaceCreateOptions, FurnaceDeployOptions, FurnaceOverrideOptions, FurnacePreviewOptions, FurnaceRefreshOptions, FurnaceRemoveOptions, FurnaceSyncOptions, FurnaceValidateOptions, ImportOptions, LintCommandOptions, PackageOptions, PatchCompactOptions, PatchDeleteOptions, PatchLintIgnoreOptions, PatchMoveFilesOptions, PatchRenameOptions, PatchReorderOptions, PatchSplitOptions, PatchStagedDependencyOptions, PatchTierOptions, RebaseOptions, ReExportOptions, RegisterOptions, ResetOptions, RunOptions, SetupOptions, SourceSetOptions, StatusOptions, TestOptions, TokenAddOptions, WireOptions, } from './options.js';
 export type { ImportSummary, PatchCategory, PatchesManifest, PatchInfo, PatchLintIssue, PatchMetadata, PatchResult, PatchStagedDependencies, PatchStagedForwardImport, PatchStagedRegistration, } from './patches.js';
-export type { DoctorCheck, ProjectStatus, TokenCoverageFileEntry, TokenCoverageReport, } from './project.js';
+export type { DoctorCheck, TokenCoverageFileEntry, TokenCoverageReport } from './project.js';

package/dist/src/types/commands/options.d.ts

@@ -68,8 +68,8 @@ export interface BuildOptions {
     rewriteMozinfo?: boolean;
     /**
      * Refuse the build (rather than warn) when it would overwrite engine
-     * content recorded in neither a patch body nor the pristine baseline
-     *. The default is a loud warning, because an interactive
+     * content recorded in neither a patch body nor the pristine baseline.
+     * The default is a loud warning, because an interactive
      * operator often means to discard the drift; a scripted gate on a
      * multi-session checkout wants the hard stop.
      */
@@ -170,8 +170,7 @@ export interface ResetOptions {
 export interface DiscardOptions {
     /**
      * Restore to pristine upstream (HEAD) instead of the patch-applied
-     * baseline; deletes patch-created files (the pre-0.39.0 semantics —
-     *).
+     * baseline, deleting patch-created files.
      */
     toUpstream?: boolean;
     /** Show what would be discarded without doing it */
@@ -190,6 +189,11 @@ export interface PackageOptions {
  * Options for the import command.
  */
 export interface ImportOptions {
+    /**
+     * Answer the engine-drift prompt non-interactively. Unlike `force`,
+     * this does NOT waive the patch-integrity gate.
+     */
+    yes?: boolean;
     /** Specific patches to apply (by name) */
     patches?: string[];
     /** Continue applying patches even if one fails */
@@ -272,13 +276,10 @@ export interface ReExportOptions {
      */
     tier?: 'branding';
     /**
-     * Lint check IDs to suppress, **appended** (union) to the patch's
-     * existing `lintIgnore` list. De-duplicated. Mutually exclusive with
-     * `--all`. To remove an entry or clear the list entirely, use the
-     * `fireforge patch lint-ignore` subcommand (which has explicit
-     * `--add` / `--remove` / `--clear` modes); re-export's append-only
-     * semantics match the operator's most common intent ("I want this
-     * patch to also suppress X").
+     * Lint check IDs to suppress, **appended** (union) to the patch's existing
+     * `lintIgnore` list. De-duplicated. Mutually exclusive with `--all`. To
+     * remove an entry or clear the list, use `fireforge patch lint-ignore`,
+     * which has explicit `--add` / `--remove` / `--clear` modes.
      */
     lintIgnore?: string[];
     /**
@@ -298,10 +299,9 @@ export interface ReExportOptions {
      */
     refuseAdjacentUnmanaged?: boolean;
     /**
-     * Bypass per-patch lint result cache reads AND writes for this
-     * invocation (`--no-cache`). The cache is what makes a repeat
-     * re-export of an unchanged patch skip the checkJs program build
-     * entirely.
+     * Bypass per-patch lint result cache reads AND writes for this invocation
+     * (`--no-cache`). The cache is what lets a repeat re-export of an unchanged
+     * patch skip the checkJs program build entirely.
      */
     noCache?: boolean;
     /**
@@ -317,9 +317,9 @@ export interface ReExportOptions {
      * Engine-relative files whose drift is EXPECTED (`--expect`, repeatable;
      * requires `--refuse-foreign-drift`). The content-based drift detector
      * cannot tell the exporting session's own slice edits from another
-     * session's, so a real slice export under the refusal flag
-     * names its intended files here: drift confined to expected files
-     * proceeds, drift anywhere else still refuses.
+     * session's, so a slice export under the refusal flag names its intended
+     * files here: drift confined to expected files proceeds, drift anywhere
+     * else still refuses.
      */
     expect?: string[];
 }
@@ -329,6 +329,11 @@ export interface ReExportOptions {
  * `.patch` file body — the manifest is the only thing that changes.
  */
 export interface PatchTierOptions {
+    /**
+     * Seconds to wait for the patch directory lock. This command mutates patch
+     * metadata under that lock.
+     */
+    waitLock?: number | boolean;
     /** Force the named tier on the patch. Only `"branding"` is recognised. */
     tier?: 'branding';
     /** Remove the `tier` override entirely, restoring auto-detection. */
@@ -344,6 +349,11 @@ export interface PatchTierOptions {
  * be set per invocation.
  */
 export interface PatchLintIgnoreOptions {
+    /**
+     * Seconds to wait for the patch directory lock. This command mutates patch
+     * metadata under that lock.
+     */
+    waitLock?: number | boolean;
     /** Lint check IDs to add to the patch's `lintIgnore` list (union, de-duped). */
     add?: string[];
     /** Lint check IDs to remove from the patch's `lintIgnore` list. */
@@ -361,6 +371,11 @@ export interface PatchLintIgnoreOptions {
  * declarations, or clear all staged dependencies from the patch.
  */
 export interface PatchStagedDependencyOptions {
+    /**
+     * Seconds to wait for the patch directory lock. This command mutates patch
+     * metadata under that lock.
+     */
+    waitLock?: number | boolean;
     /** Add a staged dependency declaration. */
     add?: boolean;
     /** Remove matching staged dependency declarations. */
@@ -455,6 +470,11 @@ export interface PatchMoveFilesOptions {
  * Options for the rebase command.
  */
 export interface RebaseOptions {
+    /**
+     * Seconds to wait for the patch directory lock. The rebase loop rewrites
+     * patch bodies under that lock.
+     */
+    waitLock?: number | boolean;
     /** Resume a previously interrupted rebase session */
     continue?: boolean;
     /** Cancel the current rebase session and restore engine */
@@ -525,20 +545,29 @@ export interface TestOptions {
      * Run the scoped pre-test build (packaging exactly the requested paths,
      * MIXED harnesses allowed) and exit without dispatching tests. One
      * ~10-minute build then covers both an xpcshell and a browser-chrome
-     * half of a slice; run each harness afterwards without `--build`
-     *. Emits `FIREFORGE-VERDICT: PASS` on success.
+     * half of a slice; run each harness afterwards without `--build`.
+     * Emits `FIREFORGE-VERDICT: PASS` on success.
      */
     buildOnly?: boolean;
     /**
      * Union the paths this build packages onto the recorded coverage claim
-     * instead of REPLACING it, so successive scoped builds
-     * accumulate and an earlier slice's build-less runs stay covered. Valid
-     * only with `--build`/`--build-only` and explicit paths. Refused
-     * fail-closed unless the build anchor is unchanged: same engine HEAD,
-     * same `engine/mozconfig`, and every previously fingerprinted packageable
-     * file byte-identical. See `src/core/coverage-extend.ts`.
+     * instead of REPLACING it, so successive scoped builds accumulate and an
+     * earlier slice's build-less runs stay covered. Valid only with
+     * `--build`/`--build-only` and explicit paths. Refused fail-closed unless
+     * the build anchor is unchanged: same engine HEAD, same `engine/mozconfig`,
+     * and every previously fingerprinted packageable file byte-identical. See
+     * `src/core/coverage-extend.ts`.
      */
     extendCoverage?: boolean;
+    /**
+     * Forwarded to the PRE-TEST build: refuse (rather than warn) when that
+     * build would overwrite engine content recorded in neither a patch body
+     * nor the pristine baseline. Same meaning as `fireforge build`'s flag of
+     * the same name — a scripted `test --build` is exactly the shape the
+     * multi-session hazard shows up in, and until now it was the one shape
+     * that could not arm the refusal. Valid only with `--build`/`--build-only`.
+     */
+    refuseUnexportedDrift?: boolean;
     /** Forward mach's pathless auto-selection mode. Valid only with no explicit paths. */
     auto?: boolean;
     /**
@@ -591,7 +620,7 @@ export interface TestOptions {
      * single-suite run auto-selects. Escape hatch for the rare case where a
      * suite-specific command misbehaves; on a healthy host the generic command
      * is equivalent. The default (auto suite dispatch) skips the mozlog
-     * resource monitor that crashes `mach test` on a broken host (E1).
+     * resource monitor that crashes `mach test` on a broken host.
      */
     genericMachTest?: boolean;
     /**
@@ -804,13 +833,11 @@ export interface PatchDeleteOptions {
     waitLock?: number | boolean;
 }
 /**
- * Options for the `fireforge patch rename` subcommand. Updates the
- * patch's filename, manifest `name`, and (optionally) `description`
- * atomically without rewriting the `.patch` file body. Companion to
- * `re-export --files` for the case where the body is already correct
- * but the patch's identity (filename + description) describes a
- * pre-shrink scope; before this verb existed the only workaround was
- * `delete` + re-export, which briefly dropped the patch from the queue.
+ * Options for the `fireforge patch rename` subcommand. Updates the patch's
+ * filename, manifest `name`, and (optionally) `description` atomically
+ * without rewriting the `.patch` file body. Companion to `re-export --files`
+ * for the case where the body is already correct but the patch's identity
+ * describes a pre-shrink scope.
  */
 export interface PatchRenameOptions {
     /**
@@ -915,9 +942,9 @@ export interface StatusOptions {
      * `ownership` block — the flat path→owning-patch rows plus
      * managed/unmanaged/conflict counts — so a gate reads ownership,
      * classification, and the check verdict from ONE scan instead of three
-     * back-to-back `status` invocations. A modifier, not a mode:
-     * exit semantics are unchanged, so ownership conflicts still fail only
-     * the human `--ownership` mode. Refused without `--json`.
+     * back-to-back `status` invocations. A modifier, not a mode: exit
+     * semantics are unchanged, so ownership conflicts still fail only the
+     * human `--ownership` mode. Refused without `--json`.
      */
     includeOwnership?: boolean;
     /**
@@ -955,7 +982,35 @@ export interface TokenAddOptions {
  * Options for the doctor command.
  */
 export interface DoctorOptions {
+    /**
+     * Seconds to wait for the patch directory lock. This command can mutate
+     * the patch manifest under that lock.
+     */
+    waitLock?: number | boolean;
+    /**
+     * Rebuild patches.json from the on-disk patch files, preserving every
+     * field the patch bodies cannot express. Refused when patches.json exists
+     * but cannot be parsed, unless `allowMetadataLoss` is also set.
+     */
     repairPatchesManifest?: boolean;
+    /**
+     * Repair only the `filesAffected` lists that disagree with their patch
+     * body. Narrower than `repairPatchesManifest`: it rewrites one field on the
+     * drifted rows and leaves every other row byte-identical, and it needs no
+     * project config, so it works on a project whose fireforge.json is broken.
+     */
+    repairFilesAffected?: boolean;
+    /**
+     * Accept the whole-manifest metadata reinvention that rebuilding an
+     * unparseable patches.json implies. Only meaningful with
+     * `repairPatchesManifest`.
+     */
+    allowMetadataLoss?: boolean;
+    /**
+     * Project what a requested repair would change and write nothing. Refused
+     * without a repair flag rather than accepted as a silent no-op.
+     */
+    dryRun?: boolean;
     /**
      * Clear a stale `pendingResolution` marker, but only after the same
      * read-only queue health checks used by `fireforge verify` report no
@@ -976,13 +1031,6 @@ export interface DoctorOptions {
     /** Run extra post-rebase checks for common Firefox registration surfaces. */
     postRebaseAudit?: boolean;
 }
-/**
- * Global CLI options available to all commands.
- */
-export interface GlobalOptions {
-    /** Enable verbose/debug output */
-    verbose?: boolean;
-}
 /** Options controlling how the lint command filters and tags its output. */
 export interface LintCommandOptions {
     /**
@@ -995,38 +1043,31 @@ export interface LintCommandOptions {
     since?: string;
     /**
      * When set together with {@link since}, scope the exit code to issues
-     * tagged `introduced`. Cumulative pre-existing errors still print (so
-     * the operator can still see the full queue state) but do not fail
-     * lint. Motivating case: a branch whose diff is clean but whose repo
-     * already carries unrelated `raw-color` / license-header errors from
-     * older patches. Without this flag, CI treats the clean branch as
-     * failing; with it, a branch "breaks the build" only when its own diff
-     * introduced a new error.
+     * tagged `introduced`. Cumulative pre-existing errors still print, so the
+     * operator sees the full queue state, but do not fail lint. This is for a
+     * branch whose own diff is clean but whose repo carries unrelated
+     * `raw-color` / license-header errors from older patches.
      *
-     * Requires {@link since}: without a revision to diff against there is
-     * no distinction between introduced and cumulative, so the flag is
-     * rejected up-front rather than silently ignored.
+     * Requires {@link since}: without a revision to diff against there is no
+     * distinction between introduced and cumulative, so the flag is rejected
+     * up-front rather than silently ignored.
      */
     onlyIntroduced?: boolean;
     /**
-     * Lint each patch in the queue as its own isolated diff, rather than
-     * the aggregate `git diff HEAD` across all applied patches.
+     * Lint each patch in the queue as its own isolated diff, rather than the
+     * aggregate `git diff HEAD` across all applied patches.
      *
-     * Motivating case: running `fireforge lint` (no args) on a repo where
-     * `fireforge import` or `fireforge rebase` has just applied the full
-     * patch queue produces an aggregate diff (every patch's changes
-     * summed). The patch-size advisory rules (`large-patch-lines`,
-     * `large-patch-files`) then fire against the sum — e.g. "Patch is
-     * 37529 lines" on a queue of 22 individually-fine patches — which
-     * reads as a task-specific regression when it is really an artefact
-     * of the aggregation. `--per-patch` rescopes the diff to each patch's
-     * own `filesAffected`, honours the patch's own `lintIgnore`, and runs
-     * the cross-patch rules once over the whole queue so queue-level
-     * findings (duplicate creations, forward imports) still surface.
+     * On a repo where `import` or `rebase` has just applied the full queue,
+     * the aggregate diff sums every patch's changes, and the patch-size
+     * advisory rules (`large-patch-lines`, `large-patch-files`) fire against
+     * that sum — "Patch is 37529 lines" for a queue of individually-fine
+     * patches. `--per-patch` rescopes the diff to each patch's own
+     * `filesAffected`, honours the patch's own `lintIgnore`, and runs the
+     * cross-patch rules once over the whole queue so queue-level findings
+     * still surface.
      *
-     * Positional file arguments change meaning under this flag: they are
-     * PATCH selectors resolved like {@link patches} entries, not engine
-     * file paths.
+     * Positional file arguments change meaning under this flag: they are PATCH
+     * selectors resolved like {@link patches} entries, not engine file paths.
      */
     perPatch?: boolean;
     /**

package/dist/src/types/commands/patches.d.ts

@@ -68,49 +68,39 @@ export interface PatchMetadata {
     /** Array of file paths affected by this patch */
     filesAffected: string[];
     /**
-     * Optional per-patch list of lint check IDs to suppress when this patch
-     * is the target of `export`, `export-all`, or `re-export`. Exists for
-     * the class of patch that is advisory-noisy by nature — a cohesive
-     * branding bundle, a localised-resource pack, an auto-generated
-     * manifest — where the generic `large-patch-lines` / `large-patch-files`
-     * thresholds do not apply but `--skip-lint` (which silences *all*
-     * errors, not just the one that does not apply) is too coarse a hammer.
+     * Optional per-patch list of lint check IDs to suppress when this patch is
+     * the target of `export`, `export-all`, or `re-export`. Exists for the
+     * class of patch that is advisory-noisy by nature — a cohesive branding
+     * bundle, a localised-resource pack, an auto-generated manifest — where
+     * the generic `large-patch-lines` / `large-patch-files` thresholds do not
+     * apply but `--skip-lint`, which silences every error rather than the one
+     * that does not apply, is too coarse.
      *
-     * Previously the only escape hatches were `--skip-lint` (blunt) or the
-     * full `rebase` flow (refreshes the same patch through a code path that
-     * silently skips `runPatchLint` — an asymmetry that forced operators
-     * through a multi-minute Firefox source re-download just to refresh
-     * one patch body).
-     *
-     * Values are free-form check IDs (e.g. `"large-patch-lines"`,
-     * `"large-patch-files"`). Checks not listed here still run normally.
-     * An entry for an unknown check ID is a no-op — the patch metadata
-     * documents the *intent* to suppress even if the check is later
-     * renamed or removed.
+     * Values are free-form check IDs (e.g. `"large-patch-lines"`). Checks not
+     * listed here still run normally. An entry for an unknown check ID is a
+     * no-op — the metadata documents the intent to suppress even if the check
+     * is later renamed or removed.
      */
     lintIgnore?: string[];
     /**
      * Optional per-patch threshold-tier override for the `large-patch-lines`
      * rule. Exists for branding patches that must touch a small number of
      * cross-cutting registration files alongside `browser/branding/<name>/`
-     * (notably `browser/moz.configure` to register the new branding flavor
-     * with the top-level configure). The narrow auto-detect allowlist in
-     * `isBrandingOnlyPatch` covers the canonical shape, but a fork whose
-     * branding patch also touches an unlisted sibling (for example a
-     * `browser/themes/<name>/` override or a vendor-specific icon
-     * resource) falls through to the general tier and trips the hard
-     * limit on what is legitimately one branding diff.
+     * (notably `browser/moz.configure`, which registers the new branding
+     * flavor with the top-level configure). The narrow auto-detect allowlist
+     * in `isBrandingOnlyPatch` covers the canonical shape; a fork whose
+     * branding patch also touches an unlisted sibling falls through to the
+     * general tier and trips the hard limit on what is legitimately one
+     * branding diff.
      *
-     * Declaring `tier: "branding"` here forces the branding thresholds
-     * (notice 8000 / warning 18000 / error 30000 lines, ≤60 files)
-     * regardless of `filesAffected`. The tier is the weaker claim than
-     * test — a patch of all-tests still lands in the test tier even if
-     * this field is set, because the test-tier thresholds are already
-     * more permissive and a test that is also branding-shaped is
-     * vanishingly rare.
+     * Declaring `tier: "branding"` forces the branding thresholds (notice
+     * 8000 / warning 18000 / error 30000 lines, ≤60 files) regardless of
+     * `filesAffected`. It is the weaker claim than test: an all-tests patch
+     * stays in the test tier even with this set, because those thresholds are
+     * already more permissive.
      *
-     * Only `"branding"` is currently recognised. Unknown values are
-     * rejected by the manifest validator, not silently stripped.
+     * Only `"branding"` is recognised. Unknown values are rejected by the
+     * manifest validator, not silently stripped.
      */
     tier?: 'branding';
     /**