@hominis/fireforge 0.42.0 → 0.43.1

package/dist/src/core/build-overwrite-guard.js

@@ -0,0 +1,165 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Loud guard against silently reverting UNEXPORTED engine drift.
+ *
+ * `build-prepare` rewrites engine files from FireForge-owned sources
+ * before every build: the branding tree, every Furnace-managed component,
+ * and `mozconfig`. On a multi-session checkout that is a silent
+ * destructive write. The recorded incident: one session edited a file in
+ * `engine/` while another held the engine lock; the lock-holder's build
+ * rewrote the file back to its patch baseline; the editing session's later
+ * `re-export --wait-lock` then captured a HYBRID file — and every gate
+ * passed on the hybrid capture. Only a hand-run grep of the patch body
+ * caught it.
+ *
+ * The `setupBranding` half of this class was closed in `31fdf744` (the
+ * branding writer preserves unmanaged lines). The general shape — any
+ * build-prepare overwrite destroying local drift that no patch records —
+ * stayed silent, and silence is what made the hybrid capture possible.
+ *
+ * This guard runs BEFORE the writes, classifies the engine's dirty files
+ * with the same classifier `fireforge status` uses, and reports the ones
+ * whose content is explained by neither a patch body nor the pristine
+ * baseline. Advisory by default (a warning naming every file), refusing
+ * under an explicit flag.
+ */
+import { toError } from '../utils/errors.js';
+import { verbose } from '../utils/logger.js';
+import { getProjectPaths } from './config.js';
+import { collectFurnaceManagedPrefixes } from './furnace-config.js';
+import { expandUntrackedDirectoryEntries, getWorkingTreeStatus } from './git-status.js';
+import { classifyFiles } from './status-classify.js';
+/**
+ * Classifications whose on-disk content is explained by NEITHER a patch
+ * body nor the pristine baseline — exactly the content a build-prepare
+ * overwrite would destroy without a record anywhere.
+ *
+ * `patch-backed` and `furnace` are excluded because their content IS the
+ * recorded state; `branding` is excluded because the branding writer
+ * preserves unmanaged lines rather than overwriting them.
+ */
+const AT_RISK_CLASSIFICATIONS = new Set(['unmanaged', 'patch-owned-drift', 'conflict']);
+/**
+ * Every path prefix build-prepare rewrites from a FireForge-owned source:
+ * the branding tree plus every Furnace-managed prefix. (`mozconfig` is a
+ * single file, not a prefix, and is tested separately.)
+ */
+function buildPrepareOwnedPrefixes(binaryName, furnacePrefixes) {
+    return [`browser/branding/${binaryName}/`, ...furnacePrefixes];
+}
+/**
+ * True when `file` sits under a path build-prepare rewrites from a
+ * FireForge-owned source: the branding tree, a Furnace-managed prefix, or
+ * the generated `mozconfig`.
+ */
+function isOverwrittenByBuildPrepare(file, binaryName, furnacePrefixes) {
+    if (file === 'mozconfig')
+        return true;
+    for (const prefix of buildPrepareOwnedPrefixes(binaryName, furnacePrefixes)) {
+        if (file === prefix || file.startsWith(prefix))
+            return true;
+    }
+    return false;
+}
+/**
+ * Narrows the status entries to the ones build-prepare can overwrite,
+ * expanding collapsed untracked directories on the way.
+ *
+ * Git reports a WHOLLY untracked directory as a single `?? dir/` entry
+ * rather than listing the files under it. A directory entry has no
+ * content to compare, so `classifyFiles` matched it against neither a
+ * patch body nor the pristine baseline and bucketed it `unmanaged` — an
+ * at-risk classification. 0.43.0 shipped the guard on the raw status and
+ * so warned about every untracked branding subdirectory on every build,
+ * while `status --unmanaged` (which expands) reported the same tree
+ * clean. Expanding here is what makes the two agree by construction.
+ *
+ * Expansion is scoped to build-prepare-owned prefixes on both sides of
+ * the walk: a collapsed directory that merely CONTAINS an owned prefix
+ * (`components/` when `components/custom/` is Furnace-managed) is
+ * rewritten to the owned prefixes beneath it, so the enumeration never
+ * walks an unrelated subtree — and never trips the per-directory
+ * expansion cap on a tree whose owned prefixes are small.
+ */
+async function collectOverwrittenEntries(engineDir, status, binaryName, furnacePrefixes) {
+    const ownedPrefixes = buildPrepareOwnedPrefixes(binaryName, furnacePrefixes);
+    const candidates = [];
+    for (const entry of status) {
+        if (isOverwrittenByBuildPrepare(entry.file, binaryName, furnacePrefixes)) {
+            candidates.push(entry);
+            continue;
+        }
+        if (!entry.isUntracked || !entry.file.endsWith('/'))
+            continue;
+        // A collapsed untracked ancestor of an owned prefix: walk only the
+        // owned subtrees under it, never the whole directory.
+        for (const prefix of ownedPrefixes) {
+            if (prefix.startsWith(entry.file)) {
+                candidates.push({ ...entry, file: prefix });
+            }
+        }
+    }
+    if (candidates.length === 0)
+        return [];
+    const expanded = await expandUntrackedDirectoryEntries(engineDir, candidates);
+    // Re-test after expansion: an ancestor rewrite can only widen, and a
+    // directory that survived expansion (nothing untracked under it any
+    // more) carries no content to classify.
+    return expanded.filter((entry) => !entry.file.endsWith('/') &&
+        isOverwrittenByBuildPrepare(entry.file, binaryName, furnacePrefixes));
+}
+/**
+ * Finds engine files that build-prepare is about to overwrite and whose
+ * current content is recorded nowhere.
+ *
+ * Fail-open: any probe failure is reported verbosely and yields an empty
+ * list. A build must not fail because an advisory guard could not run.
+ *
+ * @param projectRoot - Project root
+ * @param config - Loaded FireForge config (reads `binaryName`)
+ * @returns At-risk files, sorted by path
+ */
+export async function findUnexportedDriftAtRisk(projectRoot, config) {
+    const paths = getProjectPaths(projectRoot);
+    try {
+        const status = await getWorkingTreeStatus(paths.engine);
+        if (status.length === 0)
+            return [];
+        const furnacePrefixes = await collectFurnaceManagedPrefixes(projectRoot);
+        const candidates = await collectOverwrittenEntries(paths.engine, status, config.binaryName, furnacePrefixes);
+        if (candidates.length === 0)
+            return [];
+        const classified = await classifyFiles(candidates, paths.engine, paths.patches, config.binaryName, furnacePrefixes);
+        return classified
+            .filter((entry) => AT_RISK_CLASSIFICATIONS.has(entry.classification))
+            .map((entry) => ({
+            file: entry.file,
+            classification: entry.classification,
+            owner: entry.owner,
+        }))
+            .sort((a, b) => a.file.localeCompare(b.file));
+    }
+    catch (error) {
+        verbose(`Unexported-drift guard could not run: ${toError(error).message}`);
+        return [];
+    }
+}
+/**
+ * Renders the operator-facing warning (or refusal body) naming every file
+ * whose unexported content the build is about to overwrite.
+ */
+export function formatUnexportedDriftWarning(files) {
+    const rows = files.map((entry) => {
+        const owner = entry.owner !== undefined ? ` (owned by ${entry.owner})` : '';
+        return `  ${entry.file} [${entry.classification}]${owner}`;
+    });
+    return (`This build is about to rewrite ${String(files.length)} engine file(s) from FireForge-owned ` +
+        'sources, and their current content matches NEITHER a patch body NOR the pristine ' +
+        'baseline — so the edits below are recorded nowhere and the build will destroy them:\n' +
+        `${rows.join('\n')}\n\n` +
+        'On a multi-session checkout this is how a hybrid capture happens: the overwrite lands, ' +
+        "the editing session's later re-export captures a half-reverted file, and every gate " +
+        'passes on it.\n\n' +
+        'Export the edits first (`fireforge re-export <patch>`, or `fireforge export` for new ' +
+        'work), or pass --refuse-unexported-drift to make this a hard stop in scripted runs.');
+}

package/dist/src/core/build-prepare.d.ts

@@ -25,6 +25,11 @@ export interface PrepareBuildOptions {
      * means.
      */
     previousBaseline?: BuildBaseline | undefined;
+    /**
+     * Turn the unexported-drift warning into a hard refusal.
+     * Scripted gates want the stop; an interactive build wants the warning.
+     */
+    refuseUnexportedDrift?: boolean | undefined;
 }
 /** Packaging manifests whose graph/destination directories need a full build. */
 export declare function requiresFullBuildForIncrementalTest(path: string): boolean;
@@ -33,7 +38,7 @@ export declare function requiresFullBuildForIncrementalTest(path: string): boole
  * configure/build logs with a signal-shaped exit (e.g. 144 = 128+16, SIGURG
  * on macOS) are environmental interruptions, not compiler failures — naming
  * that in the failure text saves the operator a fruitless log hunt
- * (FORGE F16). Returns undefined for codes <= 128 (regular failures) and
+ *. Returns undefined for codes <= 128 (regular failures) and
  * for codes past the conventional signal range, so callers append nothing.
  */
 export declare function describeSignalShapedExit(exitCode: number): string | undefined;
@@ -44,14 +49,17 @@ export declare function describeSignalShapedExit(exitCode: number): string | und
 export declare function isBackendInvalidatingFile(path: string): boolean;
 /**
  * Runs the shared pre-flight steps for build and package commands:
- * 1. Cleans Furnace stories from engine (prevents leaking into production)
- * 2. Sets up branding directory if not already done
- * 3. Applies Furnace components if furnace.json exists
- * 4. Generates mozconfig
+ * 1. Warns (or refuses) about unexported engine drift the writes below
+ * would destroy
+ * 2. Cleans Furnace stories from engine (prevents leaking into production)
+ * 3. Sets up branding directory if not already done
+ * 4. Applies Furnace components if furnace.json exists
+ * 5. Generates mozconfig
  *
  * @param projectRoot - Root directory of the project
  * @param paths - Resolved project paths
  * @param config - Loaded FireForge configuration
+ * @param options - Baseline and drift-refusal options
  * @returns Preparation results
  */
 export declare function prepareBuildEnvironment(projectRoot: string, paths: ProjectPaths, config: FireForgeConfig, options?: PrepareBuildOptions): Promise<BuildPreparation>;

package/dist/src/core/build-prepare.js

@@ -4,12 +4,14 @@
  * story cleanup, branding setup, Furnace component application, and mozconfig generation.
  */
 import { constants as osConstants } from 'node:os';
+import { GeneralError } from '../errors/base.js';
 import { BuildError } from '../errors/build.js';
 import { FurnaceError } from '../errors/furnace.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
-import { info, spinner, verbose, warn } from '../utils/logger.js';
+import { info, notice, spinner, verbose, warn } from '../utils/logger.js';
 import { isBrandingSetup, setupBranding } from './branding.js';
+import { findUnexportedDriftAtRisk, formatUnexportedDriftWarning, } from './build-overwrite-guard.js';
 import { collectChangedEnginePaths } from './engine-changes.js';
 import { applyAllComponents } from './furnace-apply.js';
 import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, loadFurnaceState, } from './furnace-config.js';
@@ -43,7 +45,7 @@ function extractMachConfigureError(result) {
  * configure/build logs with a signal-shaped exit (e.g. 144 = 128+16, SIGURG
  * on macOS) are environmental interruptions, not compiler failures — naming
  * that in the failure text saves the operator a fruitless log hunt
- * (FORGE F16). Returns undefined for codes <= 128 (regular failures) and
+ *. Returns undefined for codes <= 128 (regular failures) and
  * for codes past the conventional signal range, so callers append nothing.
  */
 export function describeSignalShapedExit(exitCode) {
@@ -87,16 +89,44 @@ export function isBackendInvalidatingFile(path) {
     }
     return false;
 }
+/**
+ * Loud before the overwrite, not silent after it.
+ *
+ * Every write `prepareBuildEnvironment` performs — branding, Furnace
+ * components, `mozconfig` — rewrites engine files from a FireForge-owned
+ * source. Content recorded in neither a patch body nor the pristine
+ * baseline is destroyed by that, and on a multi-session checkout the
+ * destruction is what lets a later re-export capture a half-reverted
+ * hybrid that every gate then passes.
+ *
+ * @param projectRoot - Project root
+ * @param config - Loaded FireForge config
+ * @param options - Build-prepare options (reads `refuseUnexportedDrift`)
+ * @throws GeneralError under `--refuse-unexported-drift`
+ */
+async function reportUnexportedDriftBeforeOverwrite(projectRoot, config, options) {
+    const atRisk = await findUnexportedDriftAtRisk(projectRoot, config);
+    if (atRisk.length === 0)
+        return;
+    const message = formatUnexportedDriftWarning(atRisk);
+    if (options.refuseUnexportedDrift === true) {
+        throw new GeneralError(message);
+    }
+    notice(message);
+}
 /**
  * Runs the shared pre-flight steps for build and package commands:
- * 1. Cleans Furnace stories from engine (prevents leaking into production)
- * 2. Sets up branding directory if not already done
- * 3. Applies Furnace components if furnace.json exists
- * 4. Generates mozconfig
+ * 1. Warns (or refuses) about unexported engine drift the writes below
+ * would destroy
+ * 2. Cleans Furnace stories from engine (prevents leaking into production)
+ * 3. Sets up branding directory if not already done
+ * 4. Applies Furnace components if furnace.json exists
+ * 5. Generates mozconfig
  *
  * @param projectRoot - Root directory of the project
  * @param paths - Resolved project paths
  * @param config - Loaded FireForge configuration
+ * @param options - Baseline and drift-refusal options
  * @returns Preparation results
  */
 export async function prepareBuildEnvironment(projectRoot, paths, config, options = {}) {
@@ -111,6 +141,7 @@ export async function prepareBuildEnvironment(projectRoot, paths, config, option
                 'Run "fireforge doctor --repair-furnace" to reconcile engine state before building.');
         }
     }
+    await reportUnexportedDriftBeforeOverwrite(projectRoot, config, options);
     // Auto-configure: if any backend-invalidating file (moz.build, moz.configure,
     // Makefile.in) changed since the last successful build, run `mach configure`
     // before the build step. Prevents incremental builds from silently skipping
@@ -122,8 +153,10 @@ export async function prepareBuildEnvironment(projectRoot, paths, config, option
         const invalidating = changed.filter(isBackendInvalidatingFile);
         fullBuildRequired = changed.some(requiresFullBuildForIncrementalTest);
         if (invalidating.length > 0) {
-            info(`Backend config changed; running backend regeneration first (${invalidating.length} file${invalidating.length === 1 ? '' : 's'} touched).`);
-            info(`Backend command: mach configure`);
+            // Warning severity: this is the "why is this run slow" explanation,
+            // and an info-level line does not survive an agent output filter that
+            // keeps only warnings and errors.
+            notice(`Backend config changed; running backend regeneration first (${invalidating.length} file${invalidating.length === 1 ? '' : 's'} touched). Backend command: mach configure.`);
             const configureSpinner = spinner('Running mach configure...');
             try {
                 const captured = await runMachCapture(['configure'], paths.engine);
@@ -222,7 +255,7 @@ export async function prepareBuildEnvironment(projectRoot, paths, config, option
                 // Loud banner: the build operator needs to see that engine/ was
                 // updated before this build, otherwise a silent re-apply is
                 // indistinguishable from a build that shipped stale components.
-                info(`Furnace: source → engine sync wrote ${furnaceApplied} component${furnaceApplied === 1 ? '' : 's'} before build (${appliedNames}). engine/ now matches components/.`);
+                notice(`Furnace: source → engine sync wrote ${furnaceApplied} component${furnaceApplied === 1 ? '' : 's'} before build (${appliedNames}). engine/ now matches components/.`);
             }
             else {
                 furnaceSpinner.stop('Components up to date');

package/dist/src/core/config-mutate.d.ts

@@ -2,6 +2,7 @@
  * Immutable config mutation with dot-path keys.
  */
 import type { FireForgeConfig } from '../types/config.js';
+import type { JsonObject, JsonValue } from '../types/json.js';
 /**
  * Creates a mutated copy of a config with a nested key set to a new value,
  * optionally re-validated.
@@ -11,5 +12,5 @@ import type { FireForgeConfig } from '../types/config.js';
  * @param skipValidation - If true, skip re-validation (for --force)
  * @returns The mutated config
  */
-export declare function mutateConfig(config: FireForgeConfig, key: string, value: unknown, skipValidation?: false): FireForgeConfig;
-export declare function mutateConfig(config: FireForgeConfig | Record<string, unknown>, key: string, value: unknown, skipValidation: true): Record<string, unknown>;
+export declare function mutateConfig(config: FireForgeConfig, key: string, value: JsonValue, skipValidation?: false): FireForgeConfig;
+export declare function mutateConfig(config: FireForgeConfig | JsonObject, key: string, value: JsonValue, skipValidation: true): JsonObject;

package/dist/src/core/config-mutate.js

@@ -5,13 +5,16 @@
 import { ConfigError } from '../errors/config.js';
 import { toError } from '../utils/errors.js';
 import { verbose } from '../utils/logger.js';
-import { isObject } from '../utils/validation.js';
+import { isJsonObject, isObject } from '../utils/validation.js';
 import { validateConfig } from './config-validate.js';
 function cloneConfigDocument(config) {
     const cloned = structuredClone(config);
     if (!isObject(cloned)) {
         throw new ConfigError('Config clone unexpectedly produced a non-object value');
     }
+    // Both input shapes hold only JSON data (`FireForgeConfig` is plain
+    // parsed-config data), and `structuredClone` preserves that, so the
+    // object check above is the only invariant left to establish.
     return cloned;
 }
 /**
@@ -33,7 +36,7 @@ function assertNoSentinelSegments(key, parts) {
 }
 function getOrCreateChildRecord(parent, key) {
     const existing = parent[key];
-    if (isObject(existing)) {
+    if (isJsonObject(existing)) {
         return existing;
     }
     const child = {};

package/dist/src/core/config.d.ts

@@ -8,6 +8,7 @@
  *   config-state.ts    — state file management
  */
 import type { FireForgeConfig } from '../types/config.js';
+import type { JsonObject } from '../types/json.js';
 export { mutateConfig } from './config-mutate.js';
 export { CONFIG_FILENAME, FIREFORGE_DIR, getProjectPaths, STATE_FILENAME, SUPPORTED_CONFIG_PATHS, SUPPORTED_CONFIG_ROOT_KEYS, } from './config-paths.js';
 export { loadState, saveState, updateState } from './config-state.js';
@@ -41,7 +42,7 @@ export declare function loadConfig(root: string): Promise<FireForgeConfig>;
  * @throws ConfigNotFoundError when fireforge.json is missing
  * @throws ConfigError when the file is not valid JSON
  */
-export declare function loadRawConfigDocument(root: string): Promise<Record<string, unknown>>;
+export declare function loadRawConfigDocument(root: string): Promise<JsonObject>;
 /**
  * Writes a configuration to fireforge.json.
  * @param root - Root directory of the project
@@ -61,7 +62,7 @@ export declare function writeConfig(root: string, config: FireForgeConfig): Prom
  * {@link withConfigFileLock} for the full round-trip to serialise
  * against other writers.
  */
-export declare function writeConfigDocument(root: string, config: FireForgeConfig | Record<string, unknown>): Promise<void>;
+export declare function writeConfigDocument(root: string, config: FireForgeConfig | JsonObject): Promise<void>;
 /**
  * Runs an operation while holding a sidecar lock on `fireforge.json`.
  *

package/dist/src/core/config.js

@@ -95,6 +95,8 @@ export async function loadRawConfigDocument(root) {
         if (!isObject(data)) {
             throw new ConfigError(`Invalid fireforge.json at ${paths.config}: expected an object`);
         }
+        // `data` came out of JSON.parse, which can only ever produce JSON
+        // values, so with the object check above the JsonObject contract holds.
         return data;
     }
     catch (error) {

package/dist/src/core/coverage-extend.d.ts

@@ -1,5 +1,5 @@
 /**
- * `test --build/--build-only --extend-coverage` (FORGE L1): unions the
+ * `test --build/--build-only --extend-coverage`: unions the
  * requested paths into the recorded `testPackagingCoverage` instead of
  * replacing it, under an anchor guard.
  *

package/dist/src/core/coverage-extend.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * `test --build/--build-only --extend-coverage` (FORGE L1): unions the
+ * `test --build/--build-only --extend-coverage`: unions the
  * requested paths into the recorded `testPackagingCoverage` instead of
  * replacing it, under an anchor guard.
  *

package/dist/src/core/destructive.d.ts

@@ -68,6 +68,29 @@ export interface HistoryEntry {
     /** Result: `'ok'` on success; other strings describe failure. */
     result: string;
 }
+/**
+ * UP-FRONT non-interactive refusal for a command that will end at
+ * {@link confirmDestructive}.
+ *
+ * `confirmDestructive` already refuses a prompt-less run rather than
+ * proceeding silently — but it does so at the END, after the command has
+ * built diffs and run projected per-patch lint. On `patch move-files
+ * --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.
+ *
+ * A `--yes` or `--dry-run` run never prompts, so neither is refused.
+ *
+ * @param operation - Stable operation id, e.g. `patch-move-files-create`
+ * @param options - The run's `--yes` / `--dry-run` state
+ * @throws InvalidArgumentError when the run would prompt but cannot
+ */
+export declare function assertConfirmationAvailable(operation: string, options: {
+    yes?: boolean | undefined;
+    dryRun?: boolean | undefined;
+}): void;
 /**
  * Executes the destructive-operation contract: summary → conflict refusal →
  * dry-run / force / prompt / non-TTY refusal.

package/dist/src/core/destructive.js

@@ -39,6 +39,50 @@ function printConflicts(conflicts) {
         info(`  ${detail}`);
     }
 }
+/**
+ * True when BOTH standard handles are real TTYs, i.e. a `confirm()` prompt
+ * can actually be answered.
+ *
+ * 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() {
+    const stdinIsTTY = process.stdin.isTTY;
+    const stdoutIsTTY = process.stdout.isTTY;
+    return stdinIsTTY === true && stdoutIsTTY === true;
+}
+/**
+ * UP-FRONT non-interactive refusal for a command that will end at
+ * {@link confirmDestructive}.
+ *
+ * `confirmDestructive` already refuses a prompt-less run rather than
+ * proceeding silently — but it does so at the END, after the command has
+ * built diffs and run projected per-patch lint. On `patch move-files
+ * --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.
+ *
+ * A `--yes` or `--dry-run` run never prompts, so neither is refused.
+ *
+ * @param operation - Stable operation id, e.g. `patch-move-files-create`
+ * @param options - The run's `--yes` / `--dry-run` state
+ * @throws InvalidArgumentError when the run would prompt but cannot
+ */
+export function assertConfirmationAvailable(operation, options) {
+    if (options.yes === true || options.dryRun === true)
+        return;
+    if (confirmationIsAnswerable())
+        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 ' +
+        '(required for CI and agent-driven runs), or with --dry-run to preview without ' +
+        'confirming. Refusing up front rather than after the planning and lint work.', '--yes');
+}
 /**
  * Executes the destructive-operation contract: summary → conflict refusal →
  * dry-run / force / prompt / non-TTY refusal.
@@ -93,10 +137,7 @@ export async function confirmDestructive(input) {
     // 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.
-    const stdinIsTTY = process.stdin.isTTY;
-    const stdoutIsTTY = process.stdout.isTTY;
-    const isInteractive = stdinIsTTY === true && stdoutIsTTY === true;
-    if (!isInteractive) {
+    if (!confirmationIsAnswerable()) {
         printSummary(title, summary);
         throw new InvalidArgumentError(`Interactive confirmation not available for "${operation}". ` +
             'Use --yes to run non-interactively (required for CI).', '--yes');

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

@@ -1,13 +1,5 @@
 // SPDX-License-Identifier: EUPL-1.2
-/* eslint-disable @typescript-eslint/no-non-null-assertion --
- * This module is a tight DP/backtrack line-diff whose bounds are checked
- * structurally (every index into `ops`, `dp`, or the line arrays is either
- * guarded by an explicit `k < range.end` / `i <= m` loop condition or sits
- * inside an array built and consumed in the same function). Wrapping every
- * access in an `if (value === undefined) throw` branch would bloat the hot
- * path without catching a real class of bugs — the non-null assertions here
- * encode the invariant the surrounding logic already guarantees.
- */
+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
@@ -37,8 +29,28 @@ function splitLines(text) {
 export function computeLineDiff(oldLines, newLines) {
     const m = oldLines.length;
     const n = newLines.length;
+    // The DP below indexes `dp`, `oldLines`, and `newLines` about 4·m·n times
+    // for a worst-case pair, so its bounds are established once here rather
+    // than re-checked per access. Callers gate on LCS_LINE_LIMIT before
+    // reaching this function; if that gate is ever moved or removed, this is
+    // where the resulting allocation blow-up surfaces as a named failure
+    // instead of an out-of-memory crash.
+    assert(m <= LCS_LINE_LIMIT && n <= LCS_LINE_LIMIT, () => `line diff inputs are within LCS_LINE_LIMIT (got ${m}x${n}, limit ${LCS_LINE_LIMIT})`);
     const dp = new Int32Array((m + 1) * (n + 1));
     const stride = n + 1;
+    // Every index into `dp` is `row * stride + column` with row ≤ m and
+    // column ≤ n, which is exactly the extent allocated above.
+    assert(dp.length === (m + 1) * stride, 'DP table is sized to its stride');
+    /* eslint-disable @typescript-eslint/no-non-null-assertion --
+     * The DP fill and backtrack below are the one hot path in this module:
+     * O(m·n) iterations, up to ~4M for a LCS_LINE_LIMIT-sized pair. Every
+     * index is structurally bounded by the loop conditions (`i <= m`,
+     * `j <= n`, `i > 0`, `j > 0`) against the extents asserted immediately
+     * above, so the non-null assertions encode a property already checked
+     * once per call rather than one that is never checked at all. The
+     * rendering loops further down, which run O(ops), use `expectDefined`
+     * instead — this exemption is for the quadratic block only.
+     */
     for (let i = 1; i <= m; i++) {
         const oldLine = oldLines[i - 1];
         const rowOffset = i * stride;
@@ -83,6 +95,7 @@ export function computeLineDiff(oldLines, newLines) {
         ops.push({ type: 'insert', newIndex: j - 1, line: newLines[j - 1] });
         j--;
     }
+    /* eslint-enable @typescript-eslint/no-non-null-assertion */
     ops.reverse();
     return ops;
 }
@@ -97,9 +110,10 @@ export function buildHunks(ops, context) {
     const editRanges = [];
     let i = 0;
     while (i < ops.length) {
-        if (ops[i].type !== 'equal') {
+        if (expectDefined(ops[i], () => `diff op at index ${i}`).type !== 'equal') {
             const start = i;
-            while (i < ops.length && ops[i].type !== 'equal')
+            while (i < ops.length &&
+                expectDefined(ops[i], () => `diff op at index ${i}`).type !== 'equal')
                 i++;
             editRanges.push({ start, end: i });
         }
@@ -126,7 +140,7 @@ export function buildHunks(ops, context) {
         let oldLine = 1;
         let newLine = 1;
         for (let k = 0; k < range.start; k++) {
-            const op = ops[k];
+            const op = expectDefined(ops[k], () => `diff op at index ${k}`);
             if (op.type === 'equal') {
                 oldLine++;
                 newLine++;
@@ -142,7 +156,7 @@ export function buildHunks(ops, context) {
         let oldLength = 0;
         let newLength = 0;
         for (let k = range.start; k < range.end; k++) {
-            const op = ops[k];
+            const op = expectDefined(ops[k], () => `diff op at index ${k}`);
             if (op.type === 'equal') {
                 hunkLines.push({ marker: ' ', content: op.line });
                 oldLength++;
@@ -197,13 +211,13 @@ function coalescedHunk(oldLines, newLines, context) {
     const contextEndNew = Math.min(newLines.length - 1, lastNewDiff + context);
     const hunkLines = [];
     for (let k = contextStart; k < firstDiff; k++) {
-        hunkLines.push({ marker: ' ', content: oldLines[k] });
+        hunkLines.push({ marker: ' ', content: expectDefined(oldLines[k], () => `old line ${k}`) });
     }
     for (let k = firstDiff; k <= lastOldDiff; k++) {
-        hunkLines.push({ marker: '-', content: oldLines[k] });
+        hunkLines.push({ marker: '-', content: expectDefined(oldLines[k], () => `old line ${k}`) });
     }
     for (let k = firstDiff; k <= lastNewDiff; k++) {
-        hunkLines.push({ marker: '+', content: newLines[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…).
@@ -212,7 +226,7 @@ function coalescedHunk(oldLines, newLines, context) {
     // lines were excluded from the @@ header lengths entirely — so on
     // >LCS_LINE_LIMIT files the rendered header disagreed with the body.
     for (let k = lastNewDiff + 1; k <= contextEndNew; k++) {
-        hunkLines.push({ marker: ' ', content: newLines[k] });
+        hunkLines.push({ marker: ' ', content: expectDefined(newLines[k], () => `new line ${k}`) });
     }
     const leadingContext = firstDiff - contextStart;
     // Common-suffix symmetry: oldLen-1-lastOldDiff === newLen-1-lastNewDiff,

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

@@ -1,5 +1,5 @@
 /**
- * Patch-aware restore planning for `fireforge discard` (FORGE F1, P0).
+ * Patch-aware restore planning for `fireforge discard` (P0).
  *
  * The engine convention is: HEAD = pristine upstream Firefox, and the
  * applied patch queue lives as UNCOMMITTED worktree changes on top of it

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

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Patch-aware restore planning for `fireforge discard` (FORGE F1, P0).
+ * Patch-aware restore planning for `fireforge discard` (P0).
  *
  * The engine convention is: HEAD = pristine upstream Firefox, and the
  * applied patch queue lives as UNCOMMITTED worktree changes on top of it