@hominis/fireforge 0.48.0 → 0.49.1

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.49.0
+
+### Furnace and builds
+
+- Safer Furnace deployment and objdir cloning protect component sources and peer checkouts from shared files and directory aliases. Failed copies finish before rollback; cloned build metadata is relocated and verified.
+- Build and test preflight detect broken partial configuration, stale artifacts and invalid build baselines. Scoped builds retain coverage only while their inputs remain unchanged, and builds remove dangling test links.
+
+### Test harness
+
+- Added `test --wait-browser [seconds]`, `--wait-port [seconds]` and repeatable `--profile-file source=destination`. Browser ownership checks protect running builds; orphan cleanup waits for process and port release.
+- Test verdicts include host load and perf power-source information. Power changes make perf results inconclusive. Seeded shuffle reproduces shard order; native file shuffle remains unseeded.
+
+### Typecheck and lint
+
+- Project typecheck uses fresh diagnostics with consistent cached and uncached results. Gecko constructor shims support instance narrowing and pen input; selected test scripts receive configured checkJs checks before pre-test builds.
+- Improved Lit accessibility checks and token category parsing. Doctor checks engine source pins and reports missing engine-local ESLint setup early.
+
+### Patch queue
+
+- Added `re-export --expect-removed <path>` for safely retiring deleted patch-created files. Patch deletion rechecks the approved queue under lock.
+
+### Command reliability
+
+- Fixed leaf-command `--wait-lock` handling, JSON error reporting and watch retries. Process tracking and independent cleanup preserve the original run outcome through cancellation and cleanup failures.
+
+### Tooling
+
+- Full-Firefox integration preserves existing workspace files and Git index state, and fails on incomplete recovery. Build identity includes untracked contents and binary changes. Release checks enforce the pinned toolchain and additional module coverage floors.
+
 ## 0.48.0
 
 ### Engine lifecycle

package/dist/build-info.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "version": "0.48.0",
-  "commit": "9215c35e3907f14cc03379fb04c867ebd954085a",
-  "shortCommit": "9215c35e3907",
+  "version": "0.49.1",
+  "commit": "6348d3cae2e93096039d40ce0b52bfce0a0b9308",
+  "shortCommit": "6348d3cae2e9",
   "dirty": false,
   "dirtyHash": null,
-  "buildTime": "2026-09-22T21:34:33.874Z"
+  "buildTime": "2026-10-04T15:20:41.231Z"
 }

package/dist/src/cli.js

@@ -154,44 +154,32 @@ export function withErrorHandling(handler) {
             if (error instanceof CommandError) {
                 throw error;
             }
+            const normalizedError = toError(error);
+            const exitCode = error instanceof FireForgeError ? error.code : ExitCode.GENERAL_ERROR;
             if (error instanceof CancellationError) {
                 cancel('Operation cancelled');
-                // 130 (128+SIGINT) is the conventional "user interrupted" code, so
-                // scripts/CI can distinguish a prompt cancellation from a real
-                // failure (which exits 1).
-                throw new CommandError(ExitCode.USER_CANCELLED);
             }
-            // An invariant failure is the one FireForgeError whose stack is part
-            // of the report: the userMessage asks the operator to file the run,
-            // and without the stack there is nothing in it that locates the bug.
-            // console.error keeps it on stderr, so a --json payload stays intact.
-            if (error instanceof InternalInvariantError) {
+            else if (error instanceof InternalInvariantError) {
+                // Invariant failures always include their stack for a bug report.
                 logError(error.userMessage);
-                if (error.stack) {
+                if (error.stack)
                     console.error(error.stack);
-                }
-                throw new CommandError(error.code);
             }
-            if (error instanceof FireForgeError) {
-                // In machine mode the payload contract owes the consumer a parseable
-                // refusal on stdout, not just a non-zero exit. `logError` has already
-                // been routed to stderr by the mode, so the two do not collide.
+            else if (error instanceof FireForgeError) {
                 logError(error.userMessage);
                 printCauseChain(error);
-                // Not when a payload already owns stdout: `status --json --fail-on`
-                // writes its full document and then refuses, and appending an
-                // envelope would make that two JSON documents.
-                if (machineOutput && !isStdoutSealed()) {
-                    emitMachineError(machineErrorCode(error), error.message, error.code);
-                }
-                throw new CommandError(error.code);
             }
-            const normalizedError = toError(error);
-            logError(`Unexpected error: ${normalizedError.message}`);
-            if (normalizedError.stack) {
-                console.error(normalizedError.stack);
+            else {
+                logError(`Unexpected error: ${normalizedError.message}`);
+                if (normalizedError.stack)
+                    console.error(normalizedError.stack);
+            }
+            // One final sink covers every classification. A command that already
+            // sealed stdout owns its payload; appending an envelope would corrupt it.
+            if (machineOutput && !isStdoutSealed()) {
+                emitMachineError(error instanceof FireForgeError ? machineErrorCode(error) : 'unexpected-error', normalizedError.message, exitCode);
             }
-            throw new CommandError(ExitCode.GENERAL_ERROR);
+            throw new CommandError(exitCode);
         }
         finally {
             // Central machine-mode and stdout-seal reset. Commands leave both

package/dist/src/commands/build.js

@@ -1,4 +1,5 @@
 // SPDX-License-Identifier: EUPL-1.2
+import { join } from 'node:path';
 import { Command, InvalidArgumentError as CommanderInvalidArgumentError } from 'commander';
 import { validateBrandOverride } from '../core/brand-validation.js';
 import { auditBuildArtifacts } from '../core/build-audit.js';
@@ -8,6 +9,10 @@ import { getProjectPaths, loadConfig } from '../core/config.js';
 import { assertEngineExists } from '../core/engine-precondition.js';
 import { withEngineSessionLock } from '../core/engine-session-lock.js';
 import { attemptMozinfoRewrite, build, buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, hasRunnableBundle, runMach, withBuildLock, } from '../core/mach.js';
+import { findObjdirRelocationViolation } from '../core/mach-build-artifacts.js';
+import { ensureLaunchableBrowserNotRunning } from '../core/marionette-port.js';
+import { assertHealthyPartialConfig, pruneDanglingTestLinks } from '../core/objdir-maintenance.js';
+import { waitForPreflight } from '../core/preflight-wait.js';
 import { closeActiveRunLog, getActiveRunLogPath, openRunLog, setActiveRunLog, } from '../core/run-log.js';
 import { buildHarnessCrashMessage } from '../core/test-harness-crash.js';
 import { formatToolchainMismatchMessage, runToolchainPreflight, } from '../core/toolchain-preflight.js';
@@ -16,8 +21,8 @@ import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
 import { elapsedSince } from '../utils/elapsed.js';
 import { toError } from '../utils/errors.js';
 import { checkDiskSpace } from '../utils/fs.js';
-import { error, info, intro, outro, spinner, verbose, warn } from '../utils/logger.js';
-import { addWaitLockOption, pickDefined, resolveWaitLockSeconds } from '../utils/options.js';
+import { error, info, intro, notice, outro, spinner, verbose, warn } from '../utils/logger.js';
+import { addWaitLockOption, commanderArgParser, pickDefined, resolveWaitLockSeconds, } from '../utils/options.js';
 import { isPositiveInteger } from '../utils/validation.js';
 function parseJobCount(value) {
     const parsed = Number(value);
@@ -63,6 +68,13 @@ async function rewriteAndReconfigure(engineDir, objDir, mismatchMessage) {
         throw new BuildError(`mach configure exited non-zero (${exitCode}) after mozinfo rewrite; a clean rebuild is required.`, 'mach configure');
     }
     configureSpinner.stop('mach configure regenerated the backend');
+    const violation = await findObjdirRelocationViolation({
+        engineDir,
+        objDir,
+        forbiddenDir: rewrite.oldTopsrcdir ?? '',
+    });
+    if (violation)
+        throw new GeneralError(`Relocation incomplete: ${violation}`);
     info('Backend path-rewrite complete; continuing with the build.');
 }
 function resolveJobCount(options, configJobs) {
@@ -122,8 +134,6 @@ function extractLikelyFailingCommand(captured) {
             continue;
         if (isWarningOnlyLine(line))
             continue;
-        if (/^make(?:\[\d+\])?:/.test(line))
-            continue;
         if (/^g?make(?:\[\d+\])?:/.test(line))
             continue;
         if (/^Error running mach:/.test(line))
@@ -186,6 +196,20 @@ export async function buildCommand(projectRoot, options) {
             info(`Full build output: ${logPath}`);
     }
 }
+/** Checks objdir health and prevents deployments under a running browser. */
+async function preflightBuildObjdir(engineDir, binaryName, objDir, options) {
+    if (!objDir)
+        return;
+    await assertHealthyPartialConfig(engineDir, objDir);
+    const bundle = await hasRunnableBundle(engineDir, binaryName, objDir);
+    const expectedPath = bundle.expectedPath;
+    if (bundle.runnable && expectedPath) {
+        await waitForPreflight(() => ensureLaunchableBrowserNotRunning(join(engineDir, expectedPath)), options.waitBrowser === undefined ? undefined : resolveWaitLockSeconds(options.waitBrowser));
+    }
+    const pruned = await pruneDanglingTestLinks(engineDir, objDir);
+    if (pruned > 0)
+        notice(`Pruned ${pruned} dangling _tests symlink(s).`);
+}
 async function runBuildCommandBody(projectRoot, options) {
     const buildType = options.ui ? 'UI-only' : 'Full';
     // Load configuration
@@ -253,6 +277,7 @@ async function runBuildCommandBody(projectRoot, options) {
     // auto-configure step there can detect moz.build-family changes since the
     // last successful build. The post-build audit below reuses the same
     // baseline to diff engine changes against dist artifacts.
+    await preflightBuildObjdir(paths.engine, config.binaryName, buildCheck.objDir, options);
     const previousBaseline = await readBuildBaseline(projectRoot);
     // Shared pre-flight: branding, Furnace, mozconfig, auto-configure
     await prepareBuildEnvironment(projectRoot, paths, config, {
@@ -374,6 +399,7 @@ export function registerBuild(program, { getProjectRoot, withErrorHandling }) {
     const build = program
         .command('build')
         .description('Build the browser (auto-applies Furnace components first)')
+        .option('--wait-browser [seconds]', 'Wait for this objdir browser to exit before changing its build (default 60)', commanderArgParser((raw) => resolveWaitLockSeconds(raw)))
         .option('--ui', 'Fast UI-only rebuild')
         .option('-j, --jobs <n>', 'Number of parallel jobs', parseJobCount)
         .option('--brand <name>', 'Build specific brand')

package/dist/src/commands/doctor-engine-eslint.d.ts

@@ -0,0 +1,3 @@
+import type { DoctorCheckDefinition } from './doctor-check-core.js';
+/** Surfaces the source-refresh ESLint precondition before an expensive gate/build. */
+export declare const ENGINE_ESLINT_DOCTOR_CHECK: DoctorCheckDefinition;

package/dist/src/commands/doctor-engine-eslint.js

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { join } from 'node:path';
+import { pathExists } from '../utils/fs.js';
+import { ok, warning } from './doctor-check-core.js';
+/** Surfaces the source-refresh ESLint precondition before an expensive gate/build. */
+export const ENGINE_ESLINT_DOCTOR_CHECK = {
+    name: 'Engine ESLint installed',
+    skipIf: (ctx) => !ctx.engineExists,
+    run: async (ctx) => (await pathExists(join(ctx.paths.engine, 'node_modules/eslint/bin/eslint.js')))
+        ? ok('Engine ESLint installed')
+        : warning('Engine ESLint installed', 'Engine-local ESLint is missing after source extraction; an engine-eslint ratchet cannot run.', 'Run "cd engine && ./mach eslint --setup" after each source refresh, before building or running the gate.'),
+};

package/dist/src/commands/doctor-macos-sdk.js

@@ -13,12 +13,14 @@
  * selects, and on failure names the mismatch and lists the SDKs installed.
  *
  * darwin only, and only when a bootstrapped clang exists. A warning, never
- * a failure: the SDK may be one the operator is about to replace.
+ * a failure: the SDK may be one the operator is about to replace. Host SDK
+ * and mozconfig paths are built with `posix.join`: they are macOS paths
+ * whatever platform the module is loaded on.
  */
 import { existsSync } from 'node:fs';
 import { mkdtemp, readdir, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { join, posix } from 'node:path';
 import { mozbuildStateDir } from '../core/toolchain-preflight.js';
 import { toError } from '../utils/errors.js';
 import { exec } from '../utils/process.js';
@@ -45,7 +47,7 @@ const SDK_FROM_MOZCONFIG_SCRIPT = [
  * auto-detects when the mozconfig names none.
  */
 async function resolveSelectedSdk(engineDir) {
-    const mozconfig = join(engineDir, 'mozconfig');
+    const mozconfig = posix.join(engineDir, 'mozconfig');
     if (existsSync(mozconfig)) {
         const sourced = await exec('/bin/sh', ['-c', SDK_FROM_MOZCONFIG_SCRIPT, 'sh', mozconfig], {
             cwd: engineDir,
@@ -83,14 +85,14 @@ async function listInstalledSdks() {
     const roots = [mozbuildStateDir(), '/Library/Developer/CommandLineTools/SDKs'];
     const developer = await exec('xcode-select', ['-p'], { timeout: 10_000 });
     if (developer.exitCode === 0 && developer.stdout.trim().length > 0) {
-        roots.push(join(developer.stdout.trim(), 'Platforms/MacOSX.platform/Developer/SDKs'));
+        roots.push(posix.join(developer.stdout.trim(), 'Platforms/MacOSX.platform/Developer/SDKs'));
     }
     const found = [];
     for (const root of roots) {
         try {
             for (const entry of await readdir(root)) {
                 if (/^MacOSX.*\.sdk$/.test(entry))
-                    found.push(join(root, entry));
+                    found.push(posix.join(root, entry));
             }
         }
         catch {

package/dist/src/commands/doctor-source-pin.js

@@ -23,6 +23,7 @@
  */
 import { getFirefoxVersion } from '../core/firefox.js';
 import { toError } from '../utils/errors.js';
+import { exec } from '../utils/process.js';
 import { ok, warning } from './doctor-check-core.js';
 const CHECK_NAME = 'Source pin matches engine';
 /**
@@ -42,7 +43,13 @@ async function runSourcePinCheck(ctx) {
         // A blank or whitespace-only version.txt (a truncated write, a partial
         // extraction) carries no version to compare, so treat it as absent
         // rather than reporting the engine as being at version "".
-        actual = (await getFirefoxVersion(ctx.paths.engine))?.trim() || undefined;
+        const pristine = await exec('git', ['show', 'HEAD:browser/config/version.txt'], {
+            cwd: ctx.paths.engine,
+        }).catch(() => undefined);
+        actual =
+            (pristine?.exitCode === 0
+                ? pristine.stdout
+                : await getFirefoxVersion(ctx.paths.engine))?.trim() || undefined;
     }
     catch (error) {
         // Best-effort: an unreadable version.txt is not a pin mismatch, and a
@@ -52,7 +59,7 @@ async function runSourcePinCheck(ctx) {
     const downloaded = ctx.state.downloadedVersion;
     const mismatches = [];
     if (actual !== undefined && actual !== pinned) {
-        mismatches.push(`engine/browser/config/version.txt reads ${actual}`);
+        mismatches.push(`engine baseline browser/config/version.txt reads ${actual}`);
     }
     if (downloaded !== undefined && downloaded !== pinned) {
         mismatches.push(`the last download recorded ${downloaded}`);

package/dist/src/commands/doctor.js

@@ -15,6 +15,7 @@ import { error, info, intro, outro, success, warn } from '../utils/logger.js';
 import { addWaitLockOption } from '../utils/options.js';
 import { findExecutable } from '../utils/process.js';
 import { failure, ok, warning } from './doctor-check-core.js';
+import { ENGINE_ESLINT_DOCTOR_CHECK } from './doctor-engine-eslint.js';
 import { EXTERNAL_TOOLCHAIN_DOCTOR_CHECK } from './doctor-external-toolchains.js';
 import { FURNACE_DOCTOR_CHECKS } from './doctor-furnace.js';
 import { MACOS_SDK_LINK_DOCTOR_CHECK } from './doctor-macos-sdk.js';
@@ -211,6 +212,7 @@ const DOCTOR_CHECKS = [
         },
     },
     SOURCE_PIN_DOCTOR_CHECK,
+    ENGINE_ESLINT_DOCTOR_CHECK,
     {
         name: 'Engine is git repository',
         skipIf: (ctx) => !ctx.engineExists,

package/dist/src/commands/furnace/apply.js

@@ -94,6 +94,7 @@ async function runWatchLoop(projectRoot) {
     // because the post-apply checksum snapshot already reflects the edit so
     // the 30s poll also sees no diff.
     let pendingChange = false;
+    let retryNeeded = false;
     let lastChecksums = new Map();
     let pollTimer = null;
     const runApplyCycle = async () => {
@@ -102,18 +103,21 @@ async function runWatchLoop(projectRoot) {
             info('\nChange detected — re-applying...');
             const result = await runFurnaceMutation(projectRoot, 'apply-rollback', (ctx) => applyAllComponents(projectRoot, false, { operationContext: ctx }));
             logApplyResult(result, false);
+            if (result.errors.length > 0 || countEntriesWithBlockingStepErrors(result.applied) > 0) {
+                throw new FurnaceError('Watch apply did not complete; retrying on the next poll.');
+            }
             const applied = result.applied.length;
             const skipped = result.skipped.length;
             info(`Re-applied: ${applied} applied, ${skipped} skipped`);
+            retryNeeded = false;
+            lastChecksums = await snapshotWatchedChecksums(watchDirs);
         }
         catch (err) {
+            retryNeeded = true;
             warn(classifyWatchApplyError(err));
         }
         finally {
             applyInFlight = false;
-            // Update checksums after apply so the next poll does not re-trigger
-            // for changes that are already reflected in the engine.
-            lastChecksums = await snapshotWatchedChecksums(watchDirs);
         }
         // Another change arrived while we were applying, so run again and the
         // edit is not silently absorbed into the post-apply checksum bump.
@@ -224,7 +228,9 @@ async function runWatchLoop(projectRoot) {
                     return;
                 }
                 const current = await snapshotWatchedChecksums(watchDirs);
-                if (!checksumMapsEqual(current, lastChecksums)) {
+                // A failed apply remains dirty even if source checksums did not
+                // change. The polling interval bounds retries without a busy loop.
+                if (retryNeeded || !checksumMapsEqual(current, lastChecksums)) {
                     triggerApply();
                 }
             }

package/dist/src/commands/furnace/create-templates.js

@@ -80,9 +80,6 @@ class ${className} extends MozLitElement {
   /** @type {Record<string, unknown>} */
   static properties = {};
 
-  constructor() {
-    super();
-  }
 ${lifecycleHooks}
   render() {
     return html\`

package/dist/src/commands/lint.js

@@ -16,6 +16,7 @@ import { collectDiffFilePaths, tagLintIssues } from '../core/patch-lint-diff-tag
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
 import { info, intro, outro, success, warn } from '../utils/logger.js';
+import { addAcceptedWaitLockOption } from '../utils/options.js';
 import { stripEnginePrefix } from '../utils/paths.js';
 import { lintPerPatch } from './lint-per-patch.js';
 /**
@@ -538,6 +539,8 @@ export function registerLint(program, { getProjectRoot, withErrorHandling }) {
         }
         await lintCommand(getProjectRoot(), paths, lintOptions);
     }));
+    // This action also has subcommands; all its wait flags are accept-only.
+    addAcceptedWaitLockOption(lint);
     const lintCache = lint
         .command('cache')
         .description('Manage the per-patch lint result cache')
@@ -550,6 +553,7 @@ export function registerLint(program, { getProjectRoot, withErrorHandling }) {
             'To lint a directory named cache/, disambiguate with a trailing slash: "fireforge lint cache/".');
         return Promise.resolve();
     }));
+    addAcceptedWaitLockOption(lintCache);
     lintCache
         .command('clear')
         .description('Clear cached per-patch lint results')

package/dist/src/commands/manifest.d.ts

@@ -25,8 +25,7 @@ export interface CommandManifestEntry {
      */
     name: string;
     /**
-     * Short one-line group label, used purely for grouping in generated
-     * documentation. Not surfaced in the CLI itself.
+     * Group label used by the root CLI help and generated documentation.
      */
     group: 'project' | 'workflow' | 'engine' | 'diagnostics' | 'components';
     /** Registers the command (and any subcommands) on the Commander program. */

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

@@ -15,6 +15,7 @@ import { appendHistoryBestEffort } from '../../core/history-log.js';
 import { buildPatchQueueContext, extractImportSpecifiersWithLines, findForwardImportIgnoreLines, isForwardImportableFile, } from '../../core/patch-lint.js';
 import { withPatchDirectoryLock } from '../../core/patch-lock.js';
 import { removePatchFileAndManifest } from '../../core/patch-manifest.js';
+import { GeneralError } from '../../errors/base.js';
 import { info, intro, outro, warn } from '../../utils/logger.js';
 import { addWaitLockOption, pickDefined, resolveWaitLockSeconds } from '../../utils/options.js';
 import { proceedAfterDecision } from '../destructive-decision.js';
@@ -43,11 +44,12 @@ export async function patchDeleteCommand(projectRoot, identifier, options = {})
     // check is built directly from `baseCtx` rather than by diffing lint runs
     // over a projected state.
     const targetEntry = baseCtx.entries.find((e) => e.filename === target.filename);
+    if (!targetEntry || JSON.stringify(targetEntry.metadata) !== JSON.stringify(target)) {
+        throw new GeneralError('Patch queue changed while preparing deletion. Re-run patch delete to review the current target.');
+    }
     const targetNewFileLeaves = new Set();
-    if (targetEntry) {
-        for (const fullPath of targetEntry.newFiles.keys()) {
-            targetNewFileLeaves.add(basename(fullPath));
-        }
+    for (const fullPath of targetEntry.newFiles.keys()) {
+        targetNewFileLeaves.add(basename(fullPath));
     }
     // Scan every later patch's new files and its added lines on pre-existing
     // files for import specifiers that resolve to a leaf owned by the target.
@@ -161,6 +163,18 @@ export async function patchDeleteCommand(projectRoot, identifier, options = {})
     // re-thrown: by that point the mutation has committed, and reporting
     // failure to the caller would mislead.
     await withPatchDirectoryLock(paths.patches, async () => {
+        const current = await buildPatchQueueContext(paths.patches);
+        const snapshot = (context) => JSON.stringify(context.entries.map(({ filename, order, diff, metadata }) => ({
+            filename,
+            order,
+            diff,
+            metadata,
+        })));
+        // A changed body or manifest invalidates the dependency scan approved
+        // before the prompt. Recheck all of its inputs while holding the lock.
+        if (snapshot(current) !== snapshot(baseCtx)) {
+            throw new GeneralError('Patch queue changed while waiting for confirmation or the lock. Re-run patch delete to review the current dependencies.');
+        }
         await removePatchFileAndManifest(paths.patches, target.filename);
         await appendHistoryBestEffort(paths.patches, {
             operation: 'patch-delete',

package/dist/src/commands/re-export-options.js

@@ -63,8 +63,15 @@ function validateWhitelistFlagDependencies(options) {
         throw new InvalidArgumentError('--expect-unmanaged names approved exceptions to --refuse-adjacent-unmanaged and has no effect without it. Pass --refuse-adjacent-unmanaged, or drop --expect-unmanaged.', '--expect-unmanaged');
     }
 }
+function validateExpectedRemovalUsage(patches, options) {
+    if (options.expectRemoved?.length &&
+        (options.scan || options.all || options.files !== undefined || patches.length === 0)) {
+        throw new InvalidArgumentError('--expect-removed requires explicit selected patches and the scan-less path (no --scan, --files, or --all).', '--expect-removed');
+    }
+}
 /** Validates mutually exclusive `re-export` targeting and metadata options. */
 export function validateReExportOptionCombinations(patches, options) {
+    validateExpectedRemovalUsage(patches, options);
     if (options.files !== undefined) {
         if (options.all || options.scan) {
             throw new InvalidArgumentError('--files cannot be combined with --scan or --all.', '--files');

package/dist/src/commands/re-export-register.js

@@ -30,6 +30,7 @@ export function registerReExport(program, { getProjectRoot, withErrorHandling })
         .option('--refuse-foreign-drift', "Refuse a scan-less re-export (non-zero exit, patch not written) when the refreshed body would absorb engine lines not present in the old patch body — protects multi-session checkouts from silently capturing another session's uncommitted edits. Mutually exclusive with --scan and --files.")
         .option('--expect <path>', "With --refuse-foreign-drift, name an engine-relative file whose drift is this session's intended edit: drift confined to --expect files proceeds, drift anywhere else still refuses. Repeatable, and the whitelist applies across EVERY patch in this invocation, not per patch — so pass all the patches and all their --expect paths in one call rather than looping one patch at a time.", ...stringListOption())
         .option('--expect-unmanaged <path>', 'With --refuse-adjacent-unmanaged, name an engine-relative file that is a REVIEWED, recorded exception to the adjacency refusal: an approved unmanaged path is still listed, but no longer refuses. Repeatable, and the carve-out applies across EVERY patch in this invocation, not per patch. Use it to keep the belt armed for everything else instead of dropping --refuse-adjacent-unmanaged entirely.', ...stringListOption())
+        .option('--expect-removed <path>', 'Retire an absent file created by the selected patch while keeping scan-less refusals armed. Repeatable.', ...stringListOption())
         .option('--dry-run', 'Show what would change without writing')
         .option('--skip-lint', 'Skip patch lint checks (downgrade errors to warnings)')
         .option('--no-cache', 'Bypass per-patch lint result cache reads and writes for this re-export')

package/dist/src/commands/re-export-removed.d.ts

@@ -0,0 +1,4 @@
+import type { PatchMetadata, ReExportOptions } from '../types/commands/index.js';
+import type { ProjectPaths } from '../types/config.js';
+/** Validates every retirement before any patch is written; typos never silently grant a carve-out. */
+export declare function validateExpectedRemovals(paths: ProjectPaths, patches: PatchMetadata[], options: ReExportOptions): Promise<string[]>;

package/dist/src/commands/re-export-removed.js

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { lstat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { listTrackedInHead } from '../core/git-file-ops.js';
+import { parseDiffSections } from '../core/patch-parse.js';
+import { InvalidArgumentError } from '../errors/base.js';
+import { getNodeErrorCode } from '../utils/errors.js';
+import { readText } from '../utils/fs.js';
+import { normalizeEngineRelativeInput } from './re-export-scan.js';
+/** Validates every retirement before any patch is written; typos never silently grant a carve-out. */
+export async function validateExpectedRemovals(paths, patches, options) {
+    const removed = [
+        ...new Set((options.expectRemoved ?? []).map((file) => normalizeEngineRelativeInput(file, '--expect-removed'))),
+    ];
+    if (removed.length === 0)
+        return removed;
+    const tracked = await listTrackedInHead(paths.engine, removed);
+    for (const file of removed) {
+        const owners = patches.filter((patch) => patch.filesAffected.includes(file));
+        if (owners.length !== 1 ||
+            tracked.has(file) ||
+            (await removalPathPresent(join(paths.engine, file)))) {
+            throw new InvalidArgumentError(`--expect-removed ${file} must be absent, untracked in engine HEAD, and owned by exactly one selected patch.`, '--expect-removed');
+        }
+        const owner = owners[0];
+        if (!owner)
+            throw new InvalidArgumentError(`No selected owner for ${file}`, '--expect-removed');
+        const body = await readText(join(paths.patches, owner.filename));
+        if (!parseDiffSections(body).some((section) => section.targetPath === file && section.isNewFile)) {
+            throw new InvalidArgumentError(`--expect-removed ${file} was not created by its selected patch.`, '--expect-removed');
+        }
+        if (owner.filesAffected.every((path) => removed.includes(path))) {
+            throw new InvalidArgumentError('Retiring every file would empty the patch; use patch delete instead.', '--expect-removed');
+        }
+    }
+    return removed;
+}
+/** A dangling symlink is still an existing owned path, not an approved absence. */
+async function removalPathPresent(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (getNodeErrorCode(error) === 'ENOENT')
+            return false;
+        throw error;
+    }
+}

package/dist/src/commands/re-export-single.js

@@ -41,7 +41,10 @@ export async function reExportSinglePatchWithIndexLockRetry(args) {
 }
 async function reExportSinglePatch(args) {
     const { patch, paths, manifest, options, isDryRun, config, adjacentCtx, driftCtx, lintCtx } = args;
-    let currentFilesAffected = [...patch.filesAffected];
+    const removed = new Set(options.expectRemoved ?? []);
+    let currentFilesAffected = patch.filesAffected.filter((file) => !removed.has(file));
+    for (const file of patch.filesAffected.filter((path) => removed.has(path)))
+        info(`  - ${file} (--expect-removed)`);
     // --- Scan for new/removed files ---
     if (options.scan) {
         const scanResult = await scanPatchFilesForReExport({

package/dist/src/commands/re-export.js

@@ -15,6 +15,7 @@ import { warnUnseenExpectedDrift } from './re-export-drift.js';
 import { reExportFilesInPlace } from './re-export-files.js';
 import { buildReExportLintContext, finishReExportLint } from './re-export-lint.js';
 import { applyReExportFilesPositionalFolding, validateReExportOptionCombinations, } from './re-export-options.js';
+import { validateExpectedRemovals } from './re-export-removed.js';
 import { normalizeEngineRelativeInput, normalizeScanFiles } from './re-export-scan.js';
 import { reExportSinglePatchWithIndexLockRetry } from './re-export-single.js';
 async function resolveSelectedPatches(patches, options, manifest) {
@@ -98,6 +99,9 @@ export async function reExportCommand(projectRoot, patches, options) {
         outro('Nothing to re-export');
         return;
     }
+    const expectedRemovals = await validateExpectedRemovals(paths, selectedPatches, options);
+    if (expectedRemovals.length > 0)
+        options = { ...options, expectRemoved: expectedRemovals };
     if (scanFilesByPatch !== undefined) {
         info(`Bulk scan assignments from ${options.scanFilesManifest}`);
         for (const patch of selectedPatches) {

package/dist/src/commands/test-browser-preflight.d.ts

@@ -0,0 +1,28 @@
+import type { TestOptions } from '../types/commands/index.js';
+import type { FireForgeConfig } from '../types/config.js';
+/**
+ * Runs the `--doctor` marionette handshake probe. With no test paths the
+ * probe is the entire command (returns `'stop'` after reporting). With
+ * paths it gates the mach invocation, where a FAIL throws before mach runs.
+ */
+export declare function runDoctorPreflight(args: {
+    engineDir: string;
+    effectivePort: number | undefined;
+    hasTestPaths: boolean;
+    objDir: string | undefined;
+    binaryName: string;
+    launchablePath: string | undefined;
+}): Promise<'stop' | 'continue'>;
+/**
+ * Auto-forwards `--marionette-port` to mach (`--setpref=marionette.port`
+ * for the listener, `--marionette=127.0.0.1:<n>` for the mochitest
+ * client), skipping each piece the operator already forwarded via
+ * `--mach-arg` and the xpcshell flavor that ignores the pref entirely.
+ * Mutates `extraArgs` in place.
+ */
+export declare function appendMarionetteForwardingArgs(extraArgs: string[], options: TestOptions, forwardedPort: number | undefined, xpcshellOnly?: boolean): void;
+/** Prepares profile overlays and browser/port ownership preconditions. */
+export declare function ensureTestBrowserEnvironment(engineDir: string, launchablePath: string | undefined, xpcshellOnly: boolean, projectConfig: FireForgeConfig, options: TestOptions, objDir: string | undefined): Promise<{
+    forwardedPort: number | undefined;
+    effectivePort: number | undefined;
+}>;