@hominis/fireforge 0.47.1 → 0.49.0

package/CHANGELOG.md

@@ -1,5 +1,88 @@
 # 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
+
+- `download --force` asks before it discards work. It replaced `engine/` and deleted the backup without checking for applied patches, unexported edits or local commits. When the engine has changed paths or a HEAD off the recorded base commit, it now names the loss (changed paths, how many match the patch queue) and prompts. A non-interactive run refuses with exit 8 and prints the `--yes` form. A clean engine is replaced silently, as before.
+
+### Builds
+
+- `fireforge build` regenerates `engine/mozconfig` before its auto-configure, and a mozconfig that differs from the last successful build's is itself a configure trigger. Configure used to read the previous mozconfig, so a fix in `configs/*.mozconfig` (such as pinning `--with-macos-sdk` after the Xcode 27.0 update) could never take effect. The notice names the trigger. A baseline without `mozconfigHash` falls back to whether this run rewrote the file.
+
+### Smoke runs
+
+- **Default change:** `run --smoke-exit` launches on a fresh temporary profile unless `--profile <path>` names one. It ran against the developer's live profile, so leftover profile state could fail the release gate with nothing wrong in the tree.
+- New `run --profile <path>` and `run --temp-profile`, with or without `--smoke-exit`. FireForge creates the temporary profile, seeds the prefs `mach run` would, and removes it when the run ends, including on failure and SIGINT/SIGTERM. The next `run` sweeps one left by a SIGKILLed run.
+- For the record: mach's own flags are not forwarded. Desktop `mach run` has no `--profile`, and its `--temp-profile` leaks a directory in the objdir on every run.
+
+### Rebase
+
+- `rebase --dry-run` is real. It printed a patch count and exited 0 without testing a hunk. It now replays the queue onto the engine's HEAD in a throwaway index, walking the real run's context ladder, prints a verdict per patch (clean, reduced context, or reject with the files) and a tally, and exits 6 on any reject. `engine/` is never written.
+- The "from" version is the semantically oldest patch stamp, not the lexically smallest, so `153.10.0esr` no longer counts as older than `153.2.0esr`. A queue with several stamps prints the spread.
+- The header warns when `state.json`'s `downloadedVersion` is not the pinned target, meaning the download step has not run yet.
+
+### Performance
+
+- The worktree ownership scan behind `status`, `verify`, `doctor`, `import` and `discard` runs four git processes instead of one or more per managed file. On the Hominis tree (1,606 managed files) that was 1,625 spawns. `status --ownership` went from 13 to 16 s down to 5.7 s, and `verify` from 15 s to 7.6 s. Output is byte-identical to 0.47.1.
+- The batched untracked listing uses `ls-files -z`, so a non-ASCII name inside a collapsed directory is no longer expanded to a quoted path that names no file.
+
+### Typecheck and checkJs
+
+- The per-test-file checkJs programs share one parse of each lib, shim and helper file per run. On the Hominis queue (467 programs) the pass went from 66 to 85 s down to 22 to 25 s, with identical findings. This speeds up `typecheck` and every `lint --per-patch`, `export` or `re-export` that misses the lint cache.
+- `fireforge typecheck` keeps incremental build info per project in `.fireforge/typecheck/`, keyed so a shim, compiler or FireForge change never replays a stale verdict. New `typecheck --no-cache` checks from scratch and writes nothing. Nothing is written under `engine/`.
+- On the Hominis tree `typecheck` went from 93.8 s to 30.2 s.
+- For the record: the projects are not run in a worker pool. They took 6 of the 93.8 s; the per-file checkJs pass was the cost.
+
+### Re-export
+
+- A one-patch `re-export` roots its checkJs program at the patches it re-exports, as `lint --per-patch --patches` already did, instead of type-checking the whole queue. Cross-patch imports still resolve. On Hominis a cold `re-export <patch> --dry-run` went from 76.7 s to 8.0 s.
+- The queue lint context parses each patch once instead of once per created file: 3 to 4.4 s down to 0.3 s on 401 patches. Shared by `lint --per-patch`, `re-export`, `export` and `typecheck`.
+- `re-export` names its lint scope before the wait and prints a line when it builds a checkJs program. The elapsed time now includes the context build.
+
+### Patch queue and lint
+
+- New opt-in `patchLint.forwardRegistration: "extended"` widens `forward-registration` beyond test-manifest `support-files` to jar.mn lines, moz.build path tokens, test-manifest sections and `head`, and `customElements.js` chrome URLs. On the Hominis queue it finds 937 edges across 6 patches. The default (`"support-files"`) is unchanged. Each finding prints a `patch staged-dependency --add --kind registration` command, tested to quiet the queue without leaving `staged-dependency-unused` behind.
+- New public `findForwardRegistrations(patchesDir, { scope })` returns the same census as structured records.
+- New `lint --per-patch --notices summary|full`. `summary` prints one line per check instead of every NOTICE row (about 430 on a green Hominis queue). `full` stays the default and is unchanged. Errors, warnings and `--report` JSON are unaffected.
+
+### Programmatic API
+
+- New public `filesMeasuredByFileTooLarge(patchText)`: the files the `file-too-large` rule measures, which the rule itself now uses. A size-waiver audit can use the rule's own predicate. It covers the JS files a patch creates, not every created file, so `detectNewFilesInDiff` was not exported for this.
+
+### Doctor
+
+- New macOS `doctor` check: can the bootstrapped clang link against the SDK the build will use? Xcode 27.0 ships a `libSystem.tbd` the Mozilla clang/lld 21.1.8 rejects, and `mach configure` died with exit 5 without naming the cause. The check resolves the SDK from `engine/mozconfig` the way mach does, links a one-line C program, and on failure warns with clang's first error and the installed SDKs. It does nothing off macOS or without a bootstrapped clang.
+
 ## 0.47.0
 
 ### Test preflight

package/dist/bin/fireforge.js

@@ -13,6 +13,7 @@ import { emitKilledVerdict } from '../src/commands/test-verdict.js';
 import { forceReleaseHeldLocksForSignal } from '../src/core/file-lock.js';
 import { forceReleaseFurnaceLocksForActiveOperations, isSignalRollbackInFlight, rollbackActiveOperationsForSignal, } from '../src/core/furnace-operation.js';
 import { closeActiveRunLog } from '../src/core/run-log.js';
+import { removeActiveRunProfiles } from '../src/core/run-profile.js';
 import { waitForActiveCriticalSections } from '../src/core/signal-critical.js';
 import { CommandError } from '../src/errors/base.js';
 import { waitForActiveChildShutdown } from '../src/utils/process.js';
@@ -114,6 +115,10 @@ function installFurnaceSignalHandler(signal, exitCode) {
             // loses the race to the exit below. Only a kill FireForge never saw
             // may leave the file behind.
             .then(() => removeActivePgidFile().catch(() => undefined))
+            // A `run --temp-profile` (the `--smoke-exit` default) owes the removal
+            // of its profile directory; the command's finally loses this race too.
+            // Runs after child shutdown, so the browser no longer holds the files.
+            .then(() => removeActiveRunProfiles())
             .finally(() => {
             exitAfterStdioFlush(exitCode);
         });

package/dist/build-info.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "version": "0.47.1",
-  "commit": "11b30621b46142df7a8035ae7b9e8a13936787bb",
-  "shortCommit": "11b30621b461",
+  "version": "0.49.0",
+  "commit": "09dd0a82fdad367fb2390b4311f785a975995acd",
+  "shortCommit": "09dd0a82fdad",
   "dirty": false,
   "dirtyHash": null,
-  "buildTime": "2026-09-13T19:20:10.389Z"
+  "buildTime": "2026-10-04T08:17:58.923Z"
 }

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.d.ts

@@ -0,0 +1,8 @@
+import type { DoctorCheck } from '../types/commands/index.js';
+import type { DoctorCheckDefinition } from './doctor-check-core.js';
+/** The bootstrapped clang mach uses on macOS. */
+export declare function bootstrappedClangPath(): string;
+/** Runs the check for one engine directory. */
+export declare function checkMacosSdkLink(engineDir: string): Promise<DoctorCheck>;
+/** Registry entry for the doctor runner. */
+export declare const MACOS_SDK_LINK_DOCTOR_CHECK: DoctorCheckDefinition;

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

@@ -0,0 +1,158 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Doctor check: can the bootstrapped clang link against the macOS SDK the
+ * build will use?
+ *
+ * An Xcode update can ship an SDK whose `.tbd` stubs the pinned toolchain
+ * cannot read (Xcode 27.0's `libSystem.tbd` lists `arm64e.x1-macos`
+ * targets that clang/lld 21.1.8 rejects as "unknown architecture"). `mach
+ * configure` then dies at "checking what kind of list files are supported
+ * by the linker" with exit 5, and neither `build` nor `doctor` named the
+ * cause: the operator had to read `config.log`. This check links a trivial
+ * C program with the bootstrapped clang against the SDK the mozconfig
+ * 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. 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, posix } from 'node:path';
+import { mozbuildStateDir } from '../core/toolchain-preflight.js';
+import { toError } from '../utils/errors.js';
+import { exec } from '../utils/process.js';
+import { ok, warning } from './doctor-check-core.js';
+const CHECK_NAME = 'macOS SDK links with the bootstrapped clang';
+/** The bootstrapped clang mach uses on macOS. */
+export function bootstrappedClangPath() {
+    return join(mozbuildStateDir(), 'clang', 'bin', 'clang');
+}
+/**
+ * Sources a mozconfig with `ac_add_options` stubbed to print the
+ * `--with-macos-sdk=` value, which is how mach reads it. A mozconfig is a
+ * shell script: an SDK chosen by shell logic (the first of several
+ * candidates that exists) has no literal value to grep.
+ */
+const SDK_FROM_MOZCONFIG_SCRIPT = [
+    'ac_add_options() { for a in "$@"; do case "$a" in --with-macos-sdk=*) printf "%s\\n" "${a#--with-macos-sdk=}";; esac; done; }',
+    'mk_add_options() { :; }',
+    '. "$1"',
+].join('\n');
+/**
+ * Resolves the SDK the generated mozconfig selects (`--with-macos-sdk`),
+ * falling back to `xcrun --show-sdk-path`, which is what configure
+ * auto-detects when the mozconfig names none.
+ */
+async function resolveSelectedSdk(engineDir) {
+    const mozconfig = posix.join(engineDir, 'mozconfig');
+    if (existsSync(mozconfig)) {
+        const sourced = await exec('/bin/sh', ['-c', SDK_FROM_MOZCONFIG_SCRIPT, 'sh', mozconfig], {
+            cwd: engineDir,
+            env: { topsrcdir: engineDir },
+            timeout: 10_000,
+        });
+        if (sourced.exitCode !== 0) {
+            return {
+                error: `engine/mozconfig failed while selecting the SDK: ${firstLine(sourced.stderr) ?? `exit ${sourced.exitCode}`}`,
+            };
+        }
+        const selected = sourced.stdout
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0)
+            .pop();
+        if (selected !== undefined)
+            return { sdk: selected, source: 'mozconfig' };
+    }
+    const xcrun = await exec('xcrun', ['--show-sdk-path'], { timeout: 10_000 });
+    const path = xcrun.stdout.trim();
+    if (xcrun.exitCode !== 0 || path.length === 0) {
+        return { error: `xcrun --show-sdk-path failed: ${firstLine(xcrun.stderr) ?? 'no output'}` };
+    }
+    return { sdk: path, source: 'xcrun' };
+}
+function firstLine(text) {
+    return text
+        .split('\n')
+        .map((line) => line.trim())
+        .find((line) => line.length > 0);
+}
+/** Every macOS SDK directory on the host FireForge knows where to look for. */
+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(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(posix.join(root, entry));
+            }
+        }
+        catch {
+            // A root that does not exist lists nothing.
+        }
+    }
+    return found;
+}
+/**
+ * Links `int main(void){return 0;}` with the bootstrapped clang (through
+ * its bundled lld, as the build does) against `sdk`, in a temp directory.
+ * @returns undefined on success, else the first error line clang printed
+ */
+async function probeSdkLink(clang, sdk) {
+    const dir = await mkdtemp(join(tmpdir(), 'fireforge-sdk-probe-'));
+    try {
+        await writeFile(join(dir, 'probe.c'), 'int main(void) { return 0; }\n');
+        const lld = existsSync(join(clang, '..', 'ld64.lld')) ? ['-fuse-ld=lld'] : [];
+        const linked = await exec(clang, ['-isysroot', sdk, ...lld, '-o', join(dir, 'probe'), join(dir, 'probe.c')], { timeout: 30_000 });
+        if (linked.exitCode === 0)
+            return undefined;
+        const output = `${linked.stderr}\n${linked.stdout}`;
+        return (output
+            .split('\n')
+            .map((line) => line.trim())
+            .find((line) => /error:/.test(line)) ??
+            firstLine(output) ??
+            `exit ${linked.exitCode}`);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}
+/** Runs the check for one engine directory. */
+export async function checkMacosSdkLink(engineDir) {
+    const selected = await resolveSelectedSdk(engineDir);
+    const fix = 'Pin an SDK the bootstrapped toolchain can link in configs/darwin.mozconfig ' +
+        '(ac_add_options --with-macos-sdk=<path>), then run fireforge build.';
+    if ('error' in selected) {
+        return warning(CHECK_NAME, selected.error, fix);
+    }
+    let failure;
+    try {
+        failure = await probeSdkLink(bootstrappedClangPath(), selected.sdk);
+    }
+    catch (error) {
+        failure = toError(error).message;
+    }
+    if (failure === undefined) {
+        return ok(CHECK_NAME, `OK (${selected.sdk}, from ${selected.source})`);
+    }
+    const installed = await listInstalledSdks();
+    return warning(CHECK_NAME, `The bootstrapped clang cannot link against ${selected.sdk} (from ${selected.source}): ${failure}. ` +
+        `mach configure fails at its linker probe the same way. Installed SDKs: ` +
+        (installed.length > 0 ? installed.join(', ') : 'none found') +
+        '.', fix);
+}
+/** Registry entry for the doctor runner. */
+export const MACOS_SDK_LINK_DOCTOR_CHECK = {
+    name: CHECK_NAME,
+    skipIf: (ctx) => process.platform !== 'darwin' || !ctx.engineExists || !existsSync(bootstrappedClangPath()),
+    run: (ctx) => checkMacosSdkLink(ctx.paths.engine),
+};

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,8 +15,10 @@ 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';
 import { ORPHANED_HARNESS_DOCTOR_CHECK } from './doctor-orphaned-harness.js';
 import { PATCH_MANIFEST_CONSISTENCY_CHECK } from './doctor-patch-manifest.js';
 import { POST_REBASE_AUDIT_CHECK } from './doctor-post-rebase-audit.js';
@@ -210,6 +212,7 @@ const DOCTOR_CHECKS = [
         },
     },
     SOURCE_PIN_DOCTOR_CHECK,
+    ENGINE_ESLINT_DOCTOR_CHECK,
     {
         name: 'Engine is git repository',
         skipIf: (ctx) => !ctx.engineExists,
@@ -258,6 +261,7 @@ const DOCTOR_CHECKS = [
         },
     },
     ORPHANED_HARNESS_DOCTOR_CHECK,
+    MACOS_SDK_LINK_DOCTOR_CHECK,
     {
         name: 'Patches directory exists',
         run: async (ctx) => {

package/dist/src/commands/download.js

@@ -9,7 +9,7 @@ import { downloadFirefoxSource, formatBytes, sweepOrphanedEngineWorkDirs, } from
 import { clearAppliedFurnaceState } from '../core/furnace-config.js';
 import { getHead, initRepository, isGitRepository, isMissingHeadError, resumeRepository, } from '../core/git.js';
 import { restoreTrackedPath } from '../core/git-file-ops.js';
-import { getDirtyFiles } from '../core/git-status.js';
+import { getDirtyFiles, getWorkingTreeStatus } from '../core/git-status.js';
 import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { formatMajorVersionHopNotice } from '../core/toolchain-preflight.js';
 import { EngineExistsError, PartialEngineExistsError } from '../errors/download.js';
@@ -17,6 +17,7 @@ import { toError } from '../utils/errors.js';
 import { checkDiskSpace, ensureDir, pathExists, pathExistsStrict, removeDir } from '../utils/fs.js';
 import { info, intro, outro, spinner, verbose, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
+import { confirmDirtyEngineReset } from './rebase/confirm.js';
 /**
  * Collects the set of patch-touched files from the manifest.
  * Returns an empty set when the patches directory or manifest is absent.
@@ -35,6 +36,47 @@ async function getPatchTouchedFiles(patchesDir) {
     }
     return files;
 }
+/**
+ * Describes what a forced replacement would discard from an existing
+ * engine: changed paths against HEAD (tracked edits, applied patches, new
+ * untracked files; ignored paths such as the objdir are not work), and a
+ * HEAD that moved off the recorded base commit. Returns `undefined` when
+ * nothing would be lost, including an engine that is not a git repository
+ * or has no commit yet: that is the broken tree `--force` exists to replace.
+ */
+async function describeForcedReplacementLoss(engineDir, patchesDir, baseCommit) {
+    if (!(await isGitRepository(engineDir)))
+        return undefined;
+    let head;
+    try {
+        head = await getHead(engineDir);
+    }
+    catch (error) {
+        if (isMissingHeadError(error))
+            return undefined;
+        throw error;
+    }
+    const entries = await getWorkingTreeStatus(engineDir);
+    const headMoved = baseCommit !== undefined && head !== baseCommit;
+    if (entries.length === 0 && !headMoved)
+        return undefined;
+    const parts = [];
+    if (entries.length > 0) {
+        const patchFiles = [...(await getPatchTouchedFiles(patchesDir))];
+        const claimed = entries.filter((entry) => entry.file.endsWith('/')
+            ? patchFiles.some((file) => file.startsWith(entry.file))
+            : patchFiles.includes(entry.file)).length;
+        const unclaimed = entries.length - claimed;
+        parts.push(`engine/ has ${entries.length} changed path(s) against HEAD: ` +
+            `${claimed} match the patch queue, ${unclaimed} do not` +
+            (unclaimed > 0 ? ' (unexported work that exists nowhere else).' : '.'));
+    }
+    if (headMoved) {
+        parts.push(`engine/ HEAD ${head.slice(0, 12)} is not the recorded base commit ${baseCommit.slice(0, 12)}, so commits made in engine/ are discarded too.`);
+    }
+    parts.push('--force replaces the whole directory.');
+    return parts.join(' ');
+}
 /**
  * Restores patch-touched files to their committed (HEAD) state so that a
  * subsequent `fireforge import` does not see spurious uncommitted changes.
@@ -279,7 +321,8 @@ export async function downloadCommand(projectRoot, options) {
     const paths = getProjectPaths(projectRoot);
     // Captured before any state update so the post-download major-hop
     // notice compares against what was actually on disk until now.
-    const previousVersion = (await loadState(projectRoot)).downloadedVersion;
+    const previousState = await loadState(projectRoot);
+    const previousVersion = previousState.downloadedVersion;
     info(`Firefox version: ${version}`);
     await checkDiskSpace(projectRoot, 5 * 1024 * 1024 * 1024, warn);
     // A legitimate holder of this lock runs for 10+ minutes (download +
@@ -381,6 +424,23 @@ export async function downloadCommand(projectRoot, options) {
                 }
                 throw new EngineExistsError(paths.engine);
             }
+            // The replacement deletes the old tree once the new one is active,
+            // so anything not in patches/ is gone for good. Ask before fetching.
+            const loss = await describeForcedReplacementLoss(paths.engine, paths.patches, previousState.baseCommit);
+            if (loss !== undefined &&
+                !(await confirmDirtyEngineReset({
+                    engineDir: paths.engine,
+                    yes: options.yes ?? false,
+                    dirty: true,
+                    refusalDetail: loss,
+                    nonInteractiveCommand: 'fireforge download --force --yes',
+                    argumentName: '--yes',
+                    warningMessage: loss,
+                    promptMessage: 'Discard the existing engine/ and download a fresh one?',
+                    cancelMessage: 'Download cancelled; engine/ left untouched',
+                }))) {
+                return;
+            }
             replacementEngineDir = `${paths.engine}.replacement-${randomUUID()}`;
             backupEngineDir = `${paths.engine}.backup-${randomUUID()}`;
             installEngineDir = replacementEngineDir;
@@ -436,7 +496,8 @@ export function registerDownload(program, { getProjectRoot, withErrorHandling })
     program
         .command('download')
         .description('Download Firefox source')
-        .option('-f, --force', 'Force re-download, removing existing source')
+        .option('-f, --force', 'Force re-download; discards engine/ including applied patches and unexported edits')
+        .option('-y, --yes', 'With --force: replace a dirty engine/ without the confirmation prompt')
         .action(withErrorHandling(async (options) => {
         await downloadCommand(getProjectRoot(), pickDefined(options));
     }));