@hominis/fireforge 0.43.0 → 0.44.0

package/dist/src/core/destructive.js

@@ -15,7 +15,7 @@
 import { appendFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { confirm } from '@clack/prompts';
-import { InvalidArgumentError } from '../errors/base.js';
+import { CancellationError, InvalidArgumentError } from '../errors/base.js';
 import { ensureDir } from '../utils/fs.js';
 import { info, isCancel, warn } from '../utils/logger.js';
 /** Filename of the audit log, relative to the patches directory. */
@@ -40,16 +40,20 @@ function printConflicts(conflicts) {
     }
 }
 /**
- * True when BOTH standard handles are real TTYs, i.e. a `confirm()` prompt
+ * True when BOTH standard handles are real TTYs, i.e. an interactive prompt
  * can actually be answered.
  *
+ * Named for the condition rather than for confirmation specifically: many
+ * call sites gate a `text()` / `multiselect()` input prompt or a mode
+ * switch, not a destructive confirmation.
+ *
  * Node types `isTTY` as `boolean`, but at runtime it is `true | undefined`
  * (absent when the handle is not a TTY). Unusual harnesses (vitest stdio
  * capture, CI spawners, mocked pipes) can also leave it unset on only one
  * handle, so every falsy variant — false, undefined, a null-patched mock —
  * must route to the non-interactive path.
  */
-function confirmationIsAnswerable() {
+export function stdioIsInteractive() {
     const stdinIsTTY = process.stdin.isTTY;
     const stdoutIsTTY = process.stdout.isTTY;
     return stdinIsTTY === true && stdoutIsTTY === true;
@@ -64,8 +68,7 @@ function confirmationIsAnswerable() {
  * --create` that is minutes of work before a scripted run learns it needed
  * `--yes`, and the failure reads as an obscure late error rather than a
  * usage problem. Calling this at command entry turns it into a usage
- * refusal that names the flag, in the same shape as the 0.41.0
- * `move-files --create` / `--description` refusal.
+ * refusal that names the flag.
  *
  * A `--yes` or `--dry-run` run never prompts, so neither is refused.
  *
@@ -76,7 +79,7 @@ function confirmationIsAnswerable() {
 export function assertConfirmationAvailable(operation, options) {
     if (options.yes === true || options.dryRun === true)
         return;
-    if (confirmationIsAnswerable())
+    if (stdioIsInteractive())
         return;
     throw new InvalidArgumentError(`"${operation}" ends in an interactive confirmation, but this run has no TTY to answer it ` +
         '(stdin/stdout are not both terminals). Re-run with --yes to confirm non-interactively ' +
@@ -87,14 +90,14 @@ export function assertConfirmationAvailable(operation, options) {
  * Executes the destructive-operation contract: summary → conflict refusal →
  * dry-run / force / prompt / non-TTY refusal.
  *
- * Returns the decision for the caller to act on; callers must not execute the
- * mutation when the result is `'dry-run'` or `'cancelled'`, and must call
- * {@link appendHistory} only after the mutation succeeds (never on dry-run or
- * cancellation).
+ * Returns the decision for the caller to act on; callers must not execute
+ * the mutation when the result is `'dry-run'` or `'declined'`, and must call
+ * {@link appendHistory} only after the mutation succeeds (never on dry-run
+ * or decline).
  *
  * @param input - Operation description, flags, and optional conflict report
  * @returns `'proceed'` to execute, `'dry-run'` to skip execution, or
- *   `'cancelled'` when the user declined the prompt
+ *   `'declined'` when the user declined the prompt
  */
 export async function confirmDestructive(input) {
     const { operation, title, summary, yes, dryRun, unsafeOverride, conflicts } = input;
@@ -129,31 +132,31 @@ export async function confirmDestructive(input) {
         printSummary(title, summary);
         return 'proceed';
     }
-    // Non-TTY without --yes: refuse with a clear message pointing at --yes.
-    // Never silently proceed.
-    // Node types `isTTY` as `boolean`, but at runtime it is `true | undefined`
-    // (absent when the handle is not a TTY). Unusual harnesses (vitest stdio
-    // capture, CI spawners, mocked pipes) can also leave it unset on only
-    // one handle. We cast to the real runtime type and compare against
-    // literal `true` so any falsy variant — false, undefined, or a
-    // null-patched mock — routes to the non-interactive path.
-    if (!confirmationIsAnswerable()) {
+    // Non-TTY without --yes: refuse with a message pointing at --yes rather
+    // than silently proceeding.
+    if (!stdioIsInteractive()) {
         printSummary(title, summary);
         throw new InvalidArgumentError(`Interactive confirmation not available for "${operation}". ` +
             'Use --yes to run non-interactively (required for CI).', '--yes');
     }
     // Interactive path: print the summary first so the user sees the full
-    // picture, then prompt. Cancellation and negative answer both map to
-    // 'cancelled' so the caller can return without running anything.
+    // picture, then prompt.
     printSummary(title, summary);
     const confirmed = await confirm({
         message: `${title} — proceed?`,
         initialValue: false,
     });
-    // `isCancel` narrows the clack sentinel away, leaving a plain boolean —
-    // the defensive `!== true` this replaced is now provably redundant.
-    if (isCancel(confirmed) || !confirmed) {
-        return 'cancelled';
+    // An INTERRUPT and a "no" are different outcomes and must not share an
+    // exit code. Esc / Ctrl+C is a real interrupt — 130 is 128+SIGINT and is
+    // what a script needs to tell "the operator aborted" from "the operator
+    // considered it and declined". Answering "no" is a successful run.
+    //
+    // `isCancel` narrows the clack sentinel away, leaving a plain boolean.
+    if (isCancel(confirmed)) {
+        throw new CancellationError();
+    }
+    if (!confirmed) {
+        return 'declined';
     }
     return 'proceed';
 }

package/dist/src/core/diff-hunks.js

@@ -1,12 +1,11 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { assert, expectDefined } from '../utils/assert.js';
 /**
- * Maximum combined LCS table side-length before we bail out of the exact
- * O(m·n) diff and fall back to the simpler single-region coalesce. Chosen so
- * the worst-case Int32Array allocation stays under ~16 MB. Typical Firefox
- * widget files are a few hundred lines, so the fast path handles the
- * everyday case; the fallback exists purely to keep the command usable if
- * someone overrides a very large file.
+ * Maximum combined LCS table side-length before bailing out of the exact
+ * O(m·n) diff and falling back to the simpler single-region coalesce. Chosen
+ * so the worst-case Int32Array allocation stays under ~16 MB. Typical
+ * Firefox widget files are a few hundred lines, so the fast path handles the
+ * everyday case; the fallback keeps the command usable on a very large file.
  */
 const LCS_LINE_LIMIT = 2000;
 /** Splits a string on `\n`, discarding a single trailing empty line from a terminal newline. */
@@ -219,12 +218,11 @@ function coalescedHunk(oldLines, newLines, context) {
     for (let k = firstDiff; k <= lastNewDiff; k++) {
         hunkLines.push({ marker: '+', content: expectDefined(newLines[k], () => `new line ${k}`) });
     }
-    // Trailing context comes from the common suffix, which lives at
-    // DIFFERENT indices on each side (lastOldDiff+1… vs lastNewDiff+1…).
-    // The previous mixed-coordinate loop (max() of both sides indexing
-    // newLines) emitted wrong context on asymmetric edits, and the trailing
-    // lines were excluded from the @@ header lengths entirely — so on
-    // >LCS_LINE_LIMIT files the rendered header disagreed with the body.
+    // Trailing context comes from the common suffix, which lives at DIFFERENT
+    // indices on each side (lastOldDiff+1… vs lastNewDiff+1…). Mixing the two
+    // coordinate spaces emits wrong context on asymmetric edits and drops the
+    // trailing lines from the @@ header lengths, so the rendered header
+    // disagrees with the body.
     for (let k = lastNewDiff + 1; k <= contextEndNew; k++) {
         hunkLines.push({ marker: ' ', content: expectDefined(newLines[k], () => `new line ${k}`) });
     }

package/dist/src/core/discard-baseline.d.ts

@@ -1,18 +1,18 @@
 /**
- * Patch-aware restore planning for `fireforge discard` (P0).
+ * Patch-aware restore planning for `fireforge discard`.
  *
  * The engine convention is: HEAD = pristine upstream Firefox, and the
  * applied patch queue lives as UNCOMMITTED worktree changes on top of it
  * (`git apply` without `--index` → patch-edited tracked files are unstaged
- * modifications, patch-created files are untracked). The pre-0.39.0
- * `discard` was purely git-mechanical — it restored to HEAD and deleted
- * untracked files, silently reverting patch-backed files PAST their owning
- * patch and deleting patch-created files outright.
+ * modifications, patch-created files are untracked). A purely git-mechanical
+ * discard — restore to HEAD, delete untracked files — therefore reverts
+ * patch-backed files PAST their owning patch and deletes patch-created files
+ * outright.
  *
  * This module classifies each status entry against the patch manifest's
  * ownership claims and plans the correct restore target: the PATCH-APPLIED
  * baseline (HEAD content folded through every affecting patch in order) for
- * claimed files, and the legacy git mechanics for unmanaged ones.
+ * claimed files, and the plain git mechanics for unmanaged ones.
  */
 import type { GitStatusEntry } from './git-base.js';
 /** How one status entry's canonical path will be restored. */
@@ -35,8 +35,8 @@ export declare function planUpstreamDiscards(entries: readonly GitStatusEntry[])
 /**
  * Plans the restore target for each status entry. Entries claimed by the
  * patch manifest restore to the patch-applied baseline; unclaimed entries
- * keep the legacy git mechanics. A missing patches dir or empty manifest
- * degrades every plan to `unmanaged` (identical to pre-0.39.0 behavior).
+ * keep the plain git mechanics. A missing patches dir or empty manifest
+ * degrades every plan to `unmanaged`.
  *
  * A corrupt manifest or an unreconstructible patch baseline REFUSES with a
  * GeneralError naming `--to-upstream` — silently falling back to pristine

package/dist/src/core/discard-baseline.js

@@ -1,19 +1,19 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Patch-aware restore planning for `fireforge discard` (P0).
+ * Patch-aware restore planning for `fireforge discard`.
  *
  * The engine convention is: HEAD = pristine upstream Firefox, and the
  * applied patch queue lives as UNCOMMITTED worktree changes on top of it
  * (`git apply` without `--index` → patch-edited tracked files are unstaged
- * modifications, patch-created files are untracked). The pre-0.39.0
- * `discard` was purely git-mechanical — it restored to HEAD and deleted
- * untracked files, silently reverting patch-backed files PAST their owning
- * patch and deleting patch-created files outright.
+ * modifications, patch-created files are untracked). A purely git-mechanical
+ * discard — restore to HEAD, delete untracked files — therefore reverts
+ * patch-backed files PAST their owning patch and deletes patch-created files
+ * outright.
  *
  * This module classifies each status entry against the patch manifest's
  * ownership claims and plans the correct restore target: the PATCH-APPLIED
  * baseline (HEAD content folded through every affecting patch in order) for
- * claimed files, and the legacy git mechanics for unmanaged ones.
+ * claimed files, and the plain git mechanics for unmanaged ones.
  */
 import { join } from 'node:path';
 import { GeneralError } from '../errors/base.js';
@@ -31,8 +31,8 @@ export function planUpstreamDiscards(entries) {
 /**
  * Plans the restore target for each status entry. Entries claimed by the
  * patch manifest restore to the patch-applied baseline; unclaimed entries
- * keep the legacy git mechanics. A missing patches dir or empty manifest
- * degrades every plan to `unmanaged` (identical to pre-0.39.0 behavior).
+ * keep the plain git mechanics. A missing patches dir or empty manifest
+ * degrades every plan to `unmanaged`.
  *
  * A corrupt manifest or an unreconstructible patch baseline REFUSES with a
  * GeneralError naming `--to-upstream` — silently falling back to pristine
@@ -85,17 +85,18 @@ export async function planDiscardBaselines(patchesDir, engineDir, entries) {
                     sections = parseDiffSections(await readText(join(patchesDir, owner)));
                 }
                 catch (error) {
-                    // Fail closed. Swallowing this yielded no sections, which falls
+                    // Fail closed. Swallowing this yields no sections, which falls
                     // through to `return false` — "not deleted at baseline" — so a path
                     // the owning patch DELETES would be restored as present, i.e.
                     // rewritten instead of removed: silent data loss on the command
-                    // whose header promises a refusal for exactly this class of failure.
+                    // whose header promises a refusal for exactly this class of
+                    // failure.
                     //
-                    // In the current flow `computeExpected` above reads the same patch
-                    // first and refuses, so this is defence-in-depth against a TOCTOU
-                    // (the patch file removed or made unreadable mid-plan) rather than a
-                    // reachable branch today. It refuses with the same remediation as
-                    // its sibling so the two cannot drift into disagreeing.
+                    // `computeExpected` above reads the same patch first and refuses,
+                    // so this is defence-in-depth against a TOCTOU (the patch file
+                    // removed or made unreadable mid-plan) rather than a reachable
+                    // branch today. It uses the same remediation as its sibling so the
+                    // two cannot drift into disagreeing.
                     throw new GeneralError(`Cannot read the owning patch ${owner} to determine the baseline for ${path} ` +
                         `(${toError(error).message}). ` +
                         'Fix the owning patch, or pass --to-upstream to explicitly revert to pristine ' +

package/dist/src/core/display-state.d.ts

@@ -2,21 +2,20 @@
  * macOS display power-state probe for the headed no-output stall.
  *
  * `TIMEOUT … application timed out after N seconds with no output` /
- * `Ran 0 checks` has three recorded causes, and one of them is purely
- * environmental: a HEADED run on an unattended machine whose display is
- * asleep or locked. A headed Firefox on a sleeping display never paints,
- * never reaches its first test, and dies at the no-output timeout —
- * indistinguishable, from the log alone, from a product hang.
+ * `Ran 0 checks` has three known causes, one of them purely environmental:
+ * a HEADED run on an unattended machine whose display is asleep or locked.
+ * A headed Firefox on a sleeping display never paints, never reaches its
+ * first test, and dies at the no-output timeout — indistinguishable, from
+ * the log alone, from a product hang.
  *
  * `caffeinate -disu` does not cure it. It PREVENTS sleep; it cannot WAKE a
  * display that is already asleep, so wrapping the run changes nothing once
- * the machine has already dimmed. `fireforge test` defaults to headed, so
- * an unattended run walks straight into this and the operator burns whole
- * cycles hunting a product cause.
+ * the machine has dimmed. `fireforge test` defaults to headed, so an
+ * unattended run walks straight into this.
  *
  * The probe is advisory and fail-open: anything unexpected reports
- * `'unknown'` and the caller degrades to the generic triage list rather
- * than asserting an environment it could not measure.
+ * `'unknown'` and the caller degrades to the generic triage list rather than
+ * asserting an environment it could not measure.
  */
 /** Measured display power state, or `'unknown'` when nothing was measured. */
 export type DisplaySleepState = 'asleep' | 'awake' | 'unknown';
@@ -41,10 +40,9 @@ export type DisplaySleepState = 'asleep' | 'awake' | 'unknown';
  */
 export declare function parseDisplayPowerState(stdout: string): DisplaySleepState;
 /**
- * Probes the display's power state. Non-darwin platforms report
- * `'unknown'` without spawning anything — the stall shape this serves is
- * a macOS field report and no equivalent single-command probe is wired for
- * other platforms.
+ * Probes the display's power state. Non-darwin platforms report `'unknown'`
+ * without spawning anything — the stall shape this serves is macOS-specific
+ * and no equivalent single-command probe is wired for other platforms.
  *
  * @param platform - `process.platform`-style id (injected for testability)
  * @returns The measured state, or `'unknown'` when unmeasurable

package/dist/src/core/display-state.js

@@ -3,21 +3,20 @@
  * macOS display power-state probe for the headed no-output stall.
  *
  * `TIMEOUT … application timed out after N seconds with no output` /
- * `Ran 0 checks` has three recorded causes, and one of them is purely
- * environmental: a HEADED run on an unattended machine whose display is
- * asleep or locked. A headed Firefox on a sleeping display never paints,
- * never reaches its first test, and dies at the no-output timeout —
- * indistinguishable, from the log alone, from a product hang.
+ * `Ran 0 checks` has three known causes, one of them purely environmental:
+ * a HEADED run on an unattended machine whose display is asleep or locked.
+ * A headed Firefox on a sleeping display never paints, never reaches its
+ * first test, and dies at the no-output timeout — indistinguishable, from
+ * the log alone, from a product hang.
  *
  * `caffeinate -disu` does not cure it. It PREVENTS sleep; it cannot WAKE a
  * display that is already asleep, so wrapping the run changes nothing once
- * the machine has already dimmed. `fireforge test` defaults to headed, so
- * an unattended run walks straight into this and the operator burns whole
- * cycles hunting a product cause.
+ * the machine has dimmed. `fireforge test` defaults to headed, so an
+ * unattended run walks straight into this.
  *
  * The probe is advisory and fail-open: anything unexpected reports
- * `'unknown'` and the caller degrades to the generic triage list rather
- * than asserting an environment it could not measure.
+ * `'unknown'` and the caller degrades to the generic triage list rather than
+ * asserting an environment it could not measure.
  */
 import { toError } from '../utils/errors.js';
 import { verbose } from '../utils/logger.js';
@@ -61,10 +60,9 @@ export function parseDisplayPowerState(stdout) {
     return 'unknown';
 }
 /**
- * Probes the display's power state. Non-darwin platforms report
- * `'unknown'` without spawning anything — the stall shape this serves is
- * a macOS field report and no equivalent single-command probe is wired for
- * other platforms.
+ * Probes the display's power state. Non-darwin platforms report `'unknown'`
+ * without spawning anything — the stall shape this serves is macOS-specific
+ * and no equivalent single-command probe is wired for other platforms.
  *
  * @param platform - `process.platform`-style id (injected for testability)
  * @returns The measured state, or `'unknown'` when unmeasurable

package/dist/src/core/engine-changes.d.ts

@@ -1,9 +1,7 @@
 /**
  * Shared collector for "what changed in the engine tree since the last
- * successful build". Three preflight/audit paths previously carried their
- * own copy of this logic (`build-audit`, `build-prepare`,
- * `test-stale-check`), differing only in the verbose-log label; they all
- * call this module now.
+ * successful build", used by `build-audit`, `build-prepare` and
+ * `test-stale-check`.
  */
 import type { BuildBaseline } from './build-baseline-types.js';
 /**

package/dist/src/core/engine-changes.js

@@ -1,10 +1,8 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
  * Shared collector for "what changed in the engine tree since the last
- * successful build". Three preflight/audit paths previously carried their
- * own copy of this logic (`build-audit`, `build-prepare`,
- * `test-stale-check`), differing only in the verbose-log label; they all
- * call this module now.
+ * successful build", used by `build-audit`, `build-prepare` and
+ * `test-stale-check`.
  */
 import { toError } from '../utils/errors.js';
 import { verbose } from '../utils/logger.js';

package/dist/src/core/engine-precondition.d.ts

@@ -2,28 +2,43 @@
  * Shared engine precondition ladder for commands that read or mutate
  * `engine/` through git.
  *
- * Five commands carried their own copy of this three-rung check, and **two of
- * them were truncated**: `resolve.ts` and `token-coverage.ts` stopped after
- * the `isGitRepository` rung and omitted the unborn-HEAD guard entirely
- * (neither even imported `getHead`/`isMissingHeadError`). Both then went on to
- * enumerate working-tree status, and against an unborn HEAD the whole
- * ~300k-file Firefox tree reads as untracked — so an engine left half
- * initialised by an interrupted `download` produced a nonsensical result
- * rather than the actionable refusal the other three commands gave.
+ * The rungs matter in order. Skipping the unborn-HEAD guard and going
+ * straight to enumerating working-tree status makes the whole ~300k-file
+ * Firefox tree read as untracked, so an engine left half-initialised by an
+ * interrupted `download` produces a nonsensical result instead of an
+ * actionable refusal.
  *
- * The remediation paragraph also existed in three independently-editable
- * copies that had already drifted. It lives here once now.
+ * The remediation wording lives here once so the callers cannot drift apart.
  */
 /** Options for {@link assertEngineGitReady}. */
 export interface EngineGitReadyOptions {
     /**
      * Appended to the unborn-HEAD remediation, e.g. `', then retry the rebase.'`
-     * Preserves the one deliberate wording divergence between the copies. The
-     * base message deliberately ends WITHOUT punctuation so the suffix reads as
-     * one sentence; callers that pass nothing get a plain full stop.
+     * The base message deliberately ends WITHOUT punctuation so the suffix
+     * reads as one sentence; callers that pass nothing get a plain full stop.
      */
     unbornHeadSuffix?: string;
 }
+/**
+ * Error factory for callers whose domain uses a class other than
+ * `GeneralError`. The furnace family raises `FurnaceError`, which carries
+ * its own `userMessage` and exit code 9, so a helper hardcoding
+ * `GeneralError` would silently change both.
+ */
+export type PreconditionErrorFactory = (message: string) => Error;
+/**
+ * Asserts only that the engine checkout EXISTS.
+ *
+ * The first rung of {@link assertEngineGitReady}. Most callers want exactly
+ * this rung and no more: `build`, `run`, `test`, `package`, `watch`,
+ * `import` and `bootstrap` never run git against the engine and each has its
+ * own richer follow-up gate, so promoting them to the full three-rung ladder
+ * would refuse runs that work today.
+ *
+ * @param engineDir - Absolute path to the engine checkout
+ * @param errorFactory - Optional domain-specific error constructor
+ */
+export declare function assertEngineExists(engineDir: string, errorFactory?: PreconditionErrorFactory): Promise<void>;
 /**
  * Asserts that `engineDir` exists, is a git repository, and has a baseline
  * commit — in that order, so the operator gets the most specific applicable

package/dist/src/core/engine-precondition.js

@@ -3,17 +3,13 @@
  * Shared engine precondition ladder for commands that read or mutate
  * `engine/` through git.
  *
- * Five commands carried their own copy of this three-rung check, and **two of
- * them were truncated**: `resolve.ts` and `token-coverage.ts` stopped after
- * the `isGitRepository` rung and omitted the unborn-HEAD guard entirely
- * (neither even imported `getHead`/`isMissingHeadError`). Both then went on to
- * enumerate working-tree status, and against an unborn HEAD the whole
- * ~300k-file Firefox tree reads as untracked — so an engine left half
- * initialised by an interrupted `download` produced a nonsensical result
- * rather than the actionable refusal the other three commands gave.
+ * The rungs matter in order. Skipping the unborn-HEAD guard and going
+ * straight to enumerating working-tree status makes the whole ~300k-file
+ * Firefox tree read as untracked, so an engine left half-initialised by an
+ * interrupted `download` produces a nonsensical result instead of an
+ * actionable refusal.
  *
- * The remediation paragraph also existed in three independently-editable
- * copies that had already drifted. It lives here once now.
+ * The remediation wording lives here once so the callers cannot drift apart.
  */
 import { GeneralError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
@@ -24,6 +20,25 @@ const UNBORN_HEAD_REMEDIATION = 'Engine repository has no baseline commit yet
     // No terminating period: the suffix below supplies its own punctuation, and
     // hardcoding one here rendered as "…cleanly., then retry the rebase."
     'Re-run "fireforge download --force" to recreate the baseline repository cleanly';
+/** Default factory: the message every non-furnace command already used. */
+const defaultErrorFactory = (message) => new GeneralError(message);
+/**
+ * Asserts only that the engine checkout EXISTS.
+ *
+ * The first rung of {@link assertEngineGitReady}. Most callers want exactly
+ * this rung and no more: `build`, `run`, `test`, `package`, `watch`,
+ * `import` and `bootstrap` never run git against the engine and each has its
+ * own richer follow-up gate, so promoting them to the full three-rung ladder
+ * would refuse runs that work today.
+ *
+ * @param engineDir - Absolute path to the engine checkout
+ * @param errorFactory - Optional domain-specific error constructor
+ */
+export async function assertEngineExists(engineDir, errorFactory = defaultErrorFactory) {
+    if (!(await pathExists(engineDir))) {
+        throw errorFactory('Firefox source not found. Run "fireforge download" first.');
+    }
+}
 /**
  * Asserts that `engineDir` exists, is a git repository, and has a baseline
  * commit — in that order, so the operator gets the most specific applicable

package/dist/src/core/engine-session-lock.d.ts

@@ -2,12 +2,22 @@ import { type LockStatusSnapshot } from './file-lock.js';
 export interface EngineSessionLockOptions {
     /**
      * Wait up to this many seconds for the engine session lock instead of the
-     * legacy ~1 s fail-fast. Enables exponential poll backoff (100 ms → 2 s)
-     * and a holder-identified progress line roughly every 5 s. `undefined`
-     * preserves the historical fail-fast behavior exactly.
+     * ~1 s fail-fast. Enables exponential poll backoff (100 ms → 2 s) and a
+     * holder-identified progress line roughly every 5 s. `undefined` keeps the
+     * fail-fast behaviour.
      */
     waitLockSeconds?: number | undefined;
 }
+/**
+ * Formats the notice printed when the wait budget is EXTENDED because the
+ * queue advanced.
+ *
+ * Exported for direct unit testing. It names both figures — the requested
+ * budget and the one now in force — because the whole point is that the two
+ * have diverged, and an operator comparing the elapsed time against the
+ * number they typed would otherwise conclude the timeout is broken.
+ */
+export declare function formatWaitExtendedLine(ahead: number, budgetMs: number, requestedMs: number): string;
 /**
  * Runs `operation` while holding the project's engine-session lock, so only
  * one engine-mutating FireForge command touches `engine/` at a time.
@@ -25,7 +35,7 @@ export declare function readEngineSessionLockStatus(projectRoot: string): Promis
  * Renders the engine-session lock snapshot as operator-facing lines.
  * Pure, so the wording is unit-testable without a lock on disk.
  */
-export declare function formatEngineSessionLockStatus(snapshot: LockStatusSnapshot): string[];
+export declare function formatEngineSessionLockStatus(snapshot: LockStatusSnapshot, holderCpuSeconds?: number): string[];
 /**
  * Captures an opaque token describing the engine's current commit and working
  * tree, for comparison by {@link assertEngineGenerationUnchanged}.
@@ -49,30 +59,46 @@ export declare function isIndexLockError(error: unknown): boolean;
 export declare function isUnavailableGenerationToken(token: string): boolean;
 /** Strips the marker prefix off an unavailable token for display. */
 export declare function unavailableGenerationReason(token: string): string;
+/**
+ * Describes what moved between two generation tokens, in operator terms.
+ *
+ * The refusal used to say only THAT the engine changed, which left the
+ * operator to reconstruct the writer by hand — `find -newermt` against the
+ * run window, minus the objdir, minus git's own bookkeeping. Everything
+ * needed to answer it is already in the two tokens, so the refusal answers
+ * it. Pure and total: an unparseable token yields an empty list rather than
+ * an exception, because a diagnostic must never convert a refusal into a
+ * crash.
+ *
+ * @param before - Token captured before the run
+ * @param after - Token captured after the run
+ * @returns Human-readable lines describing the delta; empty when nothing
+ *   could be attributed
+ */
+export declare function describeEngineGenerationDelta(before: string, after: string): string[];
 /**
  * Throws when the engine's generation token differs from `before`, i.e. the
  * engine was mutated by another writer while a test run was in flight.
  *
- * **An unmeasurable engine warns rather than throws.** `engine/` is not always
- * a git checkout — `fireforge download` extracts a source tarball — so a
- * failed probe is a legitimate state and must not fail the run.
+ * **An unmeasurable engine warns rather than throws.** `engine/` is not
+ * always a git checkout — `fireforge download` extracts a source tarball —
+ * so a failed probe is a legitimate state and must not fail the run.
  *
- * What it must also not do is pass *silently*. Before 0.41.0 the failure token
- * was `unavailable:<message>` and was compared for equality like any other, so
- * a git failure that reproduced across both probes (unreadable `.git`, a
- * permissions problem, a corrupt index) produced identical tokens, took the
- * `after === before` early return, and blessed a verdict the guard had never
- * verified — the precise outcome this guard exists to prevent. Two *differing*
- * failure messages were worse still: they fell through to the mutation branch
- * and reported a spurious "engine/ changed".
+ * What it must also not do is pass *silently*. A failure token compared for
+ * equality like any other would let a git failure that reproduces across
+ * both probes (unreadable `.git`, a permissions problem, a corrupt index)
+ * take the `after === before` early return and bless a verdict the guard
+ * never verified. Two *differing* failure messages are worse still: they
+ * fall through to the mutation branch and report a spurious
+ * "engine/ changed". Hence the prefix comparison rather than a token
+ * comparison — the token embeds the error message, and two genuine failures
+ * rarely phrase it identically.
  *
  * The tolerance is deliberately limited to a probe that failed *both* times:
  * that is the steady state of a non-git `engine/`, and it warns. A one-sided
- * transition is not that state. `engine/` that was measurable and then was not
- * means the second probe measured nothing about a checkout that demonstrably
- * had something to measure; the reverse means there was never a baseline to
- * compare against. Neither is a run whose verdict can be trusted, so both
- * throw. Compare on the prefix rather than the token, because the token embeds
- * the error message and two genuine failures rarely phrase it identically.
+ * transition is not that state. An `engine/` that was measurable and then
+ * was not means the second probe measured nothing about a checkout that
+ * demonstrably had something to measure; the reverse means there was never a
+ * baseline to compare against. Neither verdict can be trusted, so both throw.
  */
 export declare function assertEngineGenerationUnchanged(engineDir: string, before: string): Promise<void>;