@hominis/fireforge 0.35.0 → 0.37.0

package/dist/src/core/test-path-scope.js

@@ -6,45 +6,50 @@
  * so `fireforge test browser/base/content/test/hominis` silently also
  * ran the sibling directory `browser/base/content/test/hominis-tiles`
  * (152.0b7 → 153.0b8 source-refresh drill: 1224 tests instead of ~200,
- * with no indication the scope widened). A trailing separator makes the
- * prefix match exact — `hominis/` cannot prefix `hominis-tiles/…`.
+ * with no indication the scope widened).
  *
  * FireForge therefore treats a directory argument as meaning EXACTLY
- * that directory: {@link analyzeTestPathScopes} returns a trailing-`/`
- * dispatch form for every existing directory, plus the sibling
- * directories the raw prefix would have swept in so the command layer
- * can tell the operator what was excluded. Note FireForge already
- * rejects non-existent paths up front, so raw prefix-widening was never
- * something an operator could invoke deliberately — it only ever
- * happened by accident.
+ * that directory: {@link analyzeTestPathScopes} enumerates the test
+ * files of exactly that directory and dispatches THAT explicit file
+ * list to mach — a file list cannot prefix-match anything. (0.35.0
+ * instead normalized the directory with a trailing `/`, assuming the
+ * separator makes the prefix match exact; field verification on Firefox
+ * 153 showed mach still swept in the prefix-named sibling, so the
+ * trailing-slash mechanism was cosmetic and its exclusion echo was
+ * wrong.) The prefix-matching sibling directories are still reported so
+ * the command layer can tell the operator what was excluded. Note
+ * FireForge already rejects non-existent paths up front, so raw
+ * prefix-widening was never something an operator could invoke
+ * deliberately — it only ever happened by accident.
  */
 import { readdir, stat } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
 /** Test implementation files as mozbuild manifests name them. */
-const TEST_FILE_PATTERN = /^(?:browser|test)_.*\.m?js$/;
+const TEST_FILE_PATTERN = /^(?:browser|test)_.*\.(?:m?js|x?html)$/;
 /**
- * Recursively counts test-implementation files under a directory.
- * Returns 0 when the directory cannot be read — the count feeds an
- * informational notice, never a decision.
+ * Recursively enumerates test-implementation files under a directory,
+ * returned engine-relative and sorted for deterministic dispatch order.
+ * Returns [] when the directory cannot be read — the caller then falls
+ * back to the directory form and mach owns the failure.
  */
-async function countTestFiles(dir) {
-    let count = 0;
+async function collectTestFiles(dir, relPrefix) {
+    const files = [];
     let entries;
     try {
         entries = await readdir(dir, { withFileTypes: true });
     }
     catch {
-        return 0;
+        return [];
     }
     for (const entry of entries) {
         if (entry.isDirectory()) {
-            count += await countTestFiles(join(dir, entry.name));
+            files.push(...(await collectTestFiles(join(dir, entry.name), `${relPrefix}${entry.name}/`)));
         }
         else if (entry.isFile() && TEST_FILE_PATTERN.test(entry.name)) {
-            count += 1;
+            files.push(`${relPrefix}${entry.name}`);
         }
     }
-    return count;
+    return files.sort();
 }
 /** Probes whether `path` is a directory, without throwing. */
 async function isDirectorySafe(path) {
@@ -65,7 +70,7 @@ async function analyzeTestPathScope(engineDir, requestedPath) {
     if (!(await isDirectorySafe(absolute))) {
         return {
             requestedPath,
-            dispatchPath: requestedPath,
+            dispatchPaths: [requestedPath],
             isDirectory: false,
             testFileCount: 0,
             siblingPrefixMatches: [],
@@ -82,7 +87,7 @@ async function analyzeTestPathScope(engineDir, requestedPath) {
             if (entry.name === base || !entry.name.startsWith(base))
                 continue;
             const siblingRel = parentRel === '.' ? entry.name : `${parentRel}/${entry.name}`;
-            const testFileCount = await countTestFiles(join(dirname(absolute), entry.name));
+            const testFileCount = (await collectTestFiles(join(dirname(absolute), entry.name), `${siblingRel}/`)).length;
             // A prefix-matching sibling with no test files never surfaces in a
             // mach run, so listing it would only add noise.
             if (testFileCount > 0) {
@@ -92,13 +97,16 @@ async function analyzeTestPathScope(engineDir, requestedPath) {
     }
     catch {
         // Unreadable parent: skip the sibling probe; exactness via the
-        // trailing separator is preserved regardless.
+        // explicit file list is preserved regardless.
     }
+    const testFiles = await collectTestFiles(absolute, `${stripped}/`);
     return {
         requestedPath,
-        dispatchPath: `${stripped}/`,
+        // The explicit file list is what makes the selection exact; an empty
+        // enumeration falls back to the directory form.
+        dispatchPaths: testFiles.length > 0 ? testFiles : [`${stripped}/`],
         isDirectory: true,
-        testFileCount: await countTestFiles(absolute),
+        testFileCount: testFiles.length,
         siblingPrefixMatches,
     };
 }
@@ -122,12 +130,19 @@ export async function analyzeTestPathScopes(engineDir, requestedPaths) {
 export function formatScopeNotice(scope) {
     if (!scope.isDirectory || scope.siblingPrefixMatches.length === 0)
         return undefined;
+    const requestedDir = scope.requestedPath.replace(/\/+$/, '');
     const siblings = scope.siblingPrefixMatches
         .map((s) => `${s.path}/ (${s.testFileCount} test file${s.testFileCount === 1 ? '' : 's'})`)
         .join(', ');
-    return (`Selected exactly ${scope.dispatchPath} (${scope.testFileCount} test file${scope.testFileCount === 1 ? '' : 's'}). ` +
-        `Excluded ${scope.siblingPrefixMatches.length} sibling director${scope.siblingPrefixMatches.length === 1 ? 'y' : 'ies'} ` +
-        `that a raw prefix match would also have run: ${siblings}. ` +
+    if (scope.testFileCount === 0) {
+        // Fallback dispatch: with nothing to enumerate, the raw directory
+        // form goes to mach, whose prefix matching CAN sweep the siblings in.
+        // Claiming exclusion here would repeat the 0.35.0 mistake.
+        return (`${requestedDir}/ contains no enumerable test files, so the directory is passed to mach ` +
+            `as-is — mach resolves paths by string prefix, which may also select: ${siblings}.`);
+    }
+    return (`Selected exactly ${requestedDir}/ by passing its ${scope.testFileCount} test file${scope.testFileCount === 1 ? '' : 's'} ` +
+        'explicitly to mach (an explicit file list cannot prefix-match a sibling). ' +
+        `Excluded ${scope.siblingPrefixMatches.length} prefix-named sibling director${scope.siblingPrefixMatches.length === 1 ? 'y' : 'ies'}: ${siblings}. ` +
         'Pass them as separate paths to include them.');
 }
-//# sourceMappingURL=test-path-scope.js.map

package/dist/src/core/test-stale-check.d.ts

@@ -1,4 +1,4 @@
-import type { BuildBaseline } from './build-baseline-types.js';
+import type { BuildBaseline, TestPackagingCoverage } from './build-baseline-types.js';
 /** Result of the stale-build preflight probe. */
 export interface StaleBuildResult {
     /** True when at least one packageable engine file changed since the baseline. */
@@ -40,3 +40,31 @@ export declare function checkStaleBuildForTest(projectRoot: string, engineDir: s
  * result without matching the rendered copy.
  */
 export declare function formatStaleBuildWarning(result: StaleBuildResult): string;
+/**
+ * Sentinel returned by {@link findUncoveredRequestPaths} when a full-suite
+ * request (no paths) is checked against a scoped coverage record.
+ */
+export declare const FULL_SUITE_REQUEST = "(entire suite)";
+/**
+ * Compares the requested test paths against the packaged runtime's coverage
+ * claim recorded in the baseline. Returns the requested paths the recorded
+ * packaging does NOT cover — the runs that would dispatch against missing
+ * `_tests/` support fixtures and hang rather than fail.
+ *
+ * Coverage semantics: `undefined` (pre-0.37.0 baseline) and `'full'` cover
+ * everything. A scoped list covers a request path when the request equals a
+ * covered entry or sits beneath a covered directory entry. Both sides are
+ * normalized to forward slashes so Windows-style CLI input cannot defeat
+ * the prefix rule (baseline paths are POSIX by convention). A request with
+ * no paths is a full-suite run and is never covered by a scoped list — the
+ * {@link FULL_SUITE_REQUEST} sentinel is returned so the refusal can name it.
+ */
+export declare function findUncoveredRequestPaths(coverage: TestPackagingCoverage | undefined, requestedPaths: readonly string[]): string[];
+/**
+ * Formats the refusal shown when a non-`--build` run requests paths the
+ * packaged runtime's scoped `test --build` coverage does not include —
+ * enforced on every such run, with or without `--allow-stale-build`. Kept
+ * separate from the matcher so tests can pin structure and copy
+ * independently (same split as {@link formatStaleBuildWarning}).
+ */
+export declare function formatTestCoverageRefusal(uncovered: string[], coverage: string[]): string;

package/dist/src/core/test-stale-check.js

@@ -112,4 +112,62 @@ export function formatStaleBuildWarning(result) {
         'packaged chrome / jar.mn resources, rerun with "fireforge test --build" (or ' +
         '"fireforge build --ui") first. Passing --build skips this check.');
 }
-//# sourceMappingURL=test-stale-check.js.map
+/**
+ * Sentinel returned by {@link findUncoveredRequestPaths} when a full-suite
+ * request (no paths) is checked against a scoped coverage record.
+ */
+export const FULL_SUITE_REQUEST = '(entire suite)';
+/**
+ * Compares the requested test paths against the packaged runtime's coverage
+ * claim recorded in the baseline. Returns the requested paths the recorded
+ * packaging does NOT cover — the runs that would dispatch against missing
+ * `_tests/` support fixtures and hang rather than fail.
+ *
+ * Coverage semantics: `undefined` (pre-0.37.0 baseline) and `'full'` cover
+ * everything. A scoped list covers a request path when the request equals a
+ * covered entry or sits beneath a covered directory entry. Both sides are
+ * normalized to forward slashes so Windows-style CLI input cannot defeat
+ * the prefix rule (baseline paths are POSIX by convention). A request with
+ * no paths is a full-suite run and is never covered by a scoped list — the
+ * {@link FULL_SUITE_REQUEST} sentinel is returned so the refusal can name it.
+ */
+export function findUncoveredRequestPaths(coverage, requestedPaths) {
+    if (coverage === undefined || coverage === 'full') {
+        return [];
+    }
+    const covered = coverage.map(normalizeCoveragePath).filter((p) => p.length > 0);
+    if (requestedPaths.length === 0) {
+        return [FULL_SUITE_REQUEST];
+    }
+    return requestedPaths.filter((requested) => {
+        const path = normalizeCoveragePath(requested);
+        return !covered.some((c) => path === c || path.startsWith(`${c}/`));
+    });
+}
+/** Normalizes a path for coverage comparison: forward slashes, no trailing slash. */
+function normalizeCoveragePath(path) {
+    return path.trim().replace(/\\/g, '/').replace(/\/+$/, '');
+}
+/**
+ * Formats the refusal shown when a non-`--build` run requests paths the
+ * packaged runtime's scoped `test --build` coverage does not include —
+ * enforced on every such run, with or without `--allow-stale-build`. Kept
+ * separate from the matcher so tests can pin structure and copy
+ * independently (same split as {@link formatStaleBuildWarning}).
+ */
+export function formatTestCoverageRefusal(uncovered, coverage) {
+    const cap = (paths) => {
+        const head = paths.slice(0, STALE_PATHS_LIMIT);
+        const truncated = paths.length - head.length;
+        return head.join(', ') + (truncated > 0 ? `, … (+${truncated} more)` : '');
+    };
+    const rebuildTargets = uncovered.filter((p) => p !== FULL_SUITE_REQUEST);
+    const rebuildHint = rebuildTargets.length > 0
+        ? `Rerun "fireforge test --build ${rebuildTargets.slice(0, STALE_PATHS_LIMIT).join(' ')}" to package them, or run "fireforge build" for full coverage.`
+        : 'Run "fireforge build" (or a path-less "fireforge test --build") for full coverage first.';
+    return (`The packaged test runtime was produced by a scoped "fireforge test --build" covering only: ${cap(coverage)}.\n` +
+        `The requested run needs ${cap(uncovered)}, which that packaging does not cover — support ` +
+        'fixtures for those manifests may be missing from obj-*/_tests/, and the run can hang ' +
+        `rather than fail. ${rebuildHint} ` +
+        '(--allow-stale-build does not bypass this check — it accepts stale content, not missing coverage.)');
+}

package/dist/src/core/test-stale-symlink.js

@@ -37,4 +37,3 @@ export async function tryRepairStaleXpcshellTestSymlink(engineDir, objDir, outpu
     warn(`Removed stale xpcshell harness symlink under ${objDir}/_tests and retrying mach test once: ${relative(resolve(engineDir), resolvedDestination)}`);
     return true;
 }
-//# sourceMappingURL=test-stale-symlink.js.map

package/dist/src/core/test-xpcshell-retry.js

@@ -20,4 +20,3 @@ export async function retryAfterXpcshellSymlinkRepair(engineDir, objDir, result,
     }
     return result;
 }
-//# sourceMappingURL=test-xpcshell-retry.js.map

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

@@ -95,4 +95,3 @@ export async function measureTokenCoverage(repoDir, cssFiles, projectRoot) {
         files: entries,
     };
 }
-//# sourceMappingURL=token-coverage.js.map

package/dist/src/core/token-dark-mode.js

@@ -167,4 +167,3 @@ export function findDarkMediaCloseIndex(lines) {
         return -1;
     return findBlockCloseIndex(stripped, darkMediaLine);
 }
-//# sourceMappingURL=token-dark-mode.js.map

package/dist/src/core/token-docs.js

@@ -98,4 +98,3 @@ export async function addTokenToDocs(engineDir, options, annotation) {
     await writeText(filePath, lines.join('\n'));
     return { docsAdded, unmappedAdded, countUpdated };
 }
-//# sourceMappingURL=token-docs.js.map

package/dist/src/core/token-manager.js

@@ -455,4 +455,3 @@ async function addTokenToCSS(engineDir, options, tokensCssPath) {
     await writeText(filePath, content);
     return { added: true, categoryCreated };
 }
-//# sourceMappingURL=token-manager.js.map

package/dist/src/core/token-scaffold.js

@@ -71,4 +71,3 @@ ${categoryBlocks}
 }
 `;
 }
-//# sourceMappingURL=token-scaffold.js.map

package/dist/src/core/token-variant.js

@@ -138,4 +138,3 @@ export function insertVariantDeclaration(lines, variant, declLine) {
     }
     lines.splice(findVariantBlockInsertionPoint(lines), 0, '', `:root${variant} {`, declLine, '}');
 }
-//# sourceMappingURL=token-variant.js.map

package/dist/src/core/toolchain-preflight.d.ts

@@ -14,22 +14,38 @@
  *     the downloaded major differs from the previously downloaded one.
  *  2. {@link runToolchainPreflight} — a cheap pre-build probe comparing
  *     the minimums the tree itself declares against the host binaries
- *     `mach configure` will resolve. Deliberately FAIL-SOFT: it reports
- *     a mismatch only when a minimum was positively parsed AND the host
- *     binary was found AND its version is definitively lower. Any
- *     uncertainty (file moved upstream, unparseable output, binary not
- *     on PATH) skips silently — the mach-error-hints translator still
- *     catches the real configure failure downstream.
+ *     `mach configure` will resolve, probing configure's own candidate
+ *     order: env override first, then the `~/.mozbuild` state-directory
+ *     copy bootstrap installs, then PATH (0.35.0 probed env-or-PATH
+ *     only, blocking builds whose current tool lived in the state dir
+ *     behind a stale PATH copy). Deliberately FAIL-SOFT: it reports a
+ *     mismatch only when a minimum was positively parsed AND at least
+ *     one candidate resolved AND every resolved candidate is
+ *     definitively lower. Any uncertainty (file moved upstream,
+ *     unparseable output, no candidate found) skips silently — the
+ *     mach-error-hints translator still catches the real configure
+ *     failure downstream.
  */
 /** Tools the preflight knows how to probe. */
 export type ToolchainTool = 'cbindgen' | 'rustc';
+/** One probed candidate binary for a tool. */
+export interface ToolchainCandidate {
+    /** Binary path (or bare name for the PATH candidate). */
+    binary: string;
+    /** Parsed version of the candidate. */
+    version: string;
+}
 /** One definitive host-vs-tree mismatch found by the preflight. */
 export interface ToolchainMismatch {
     tool: ToolchainTool;
-    hostVersion: string;
     minimumVersion: string;
     /** Engine-relative file the minimum was parsed from. */
     declaredIn: string;
+    /**
+     * Every candidate that resolved — all of them below the minimum
+     * (mach-resolution order: env override, mozbuild state dir, PATH).
+     */
+    candidates: ToolchainCandidate[];
 }
 /**
  * Returns the one-line notice to print after a download that hopped the
@@ -49,15 +65,20 @@ export declare function formatMajorVersionHopNotice(previousVersion: string | un
 export declare function readDeclaredToolchainMinimums(engineDir: string): Promise<Partial<Record<ToolchainTool, string>>>;
 /**
  * Compares the tree-declared toolchain minimums against the host binaries
- * `mach configure` will resolve. Returns only DEFINITIVE mismatches; every
- * uncertain probe passes silently (see module header for the rationale).
+ * `mach configure` will resolve, in configure's own candidate order (env
+ * override, mozbuild state dir, PATH). A tool fails ONLY when at least
+ * one candidate resolved and none of them meets the minimum; any single
+ * passing candidate passes the tool (configure will find it), and a tool
+ * with no resolvable candidate skips silently (see module header for the
+ * fail-soft rationale).
  *
  * @param engineDir - Path to the engine directory
  */
 export declare function runToolchainPreflight(engineDir: string): Promise<ToolchainMismatch[]>;
 /**
  * Formats the fail-fast message for definitive preflight mismatches,
- * naming `fireforge bootstrap` as the remedy (mach's own configure error
+ * listing every candidate probed (in mach's resolution order) and naming
+ * `fireforge bootstrap` as the remedy (mach's own configure error
  * suggests `./mach bootstrap`, which is the wrong entry point for a
  * FireForge-managed repo).
  */

package/dist/src/core/toolchain-preflight.js

@@ -15,17 +15,31 @@
  *     the downloaded major differs from the previously downloaded one.
  *  2. {@link runToolchainPreflight} — a cheap pre-build probe comparing
  *     the minimums the tree itself declares against the host binaries
- *     `mach configure` will resolve. Deliberately FAIL-SOFT: it reports
- *     a mismatch only when a minimum was positively parsed AND the host
- *     binary was found AND its version is definitively lower. Any
- *     uncertainty (file moved upstream, unparseable output, binary not
- *     on PATH) skips silently — the mach-error-hints translator still
- *     catches the real configure failure downstream.
+ *     `mach configure` will resolve, probing configure's own candidate
+ *     order: env override first, then the `~/.mozbuild` state-directory
+ *     copy bootstrap installs, then PATH (0.35.0 probed env-or-PATH
+ *     only, blocking builds whose current tool lived in the state dir
+ *     behind a stale PATH copy). Deliberately FAIL-SOFT: it reports a
+ *     mismatch only when a minimum was positively parsed AND at least
+ *     one candidate resolved AND every resolved candidate is
+ *     definitively lower. Any uncertainty (file moved upstream,
+ *     unparseable output, no candidate found) skips silently — the
+ *     mach-error-hints translator still catches the real configure
+ *     failure downstream.
  */
 import { execFile } from 'node:child_process';
+import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { pathExists, readText } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
+/**
+ * Resolves the mach state directory the same way mach itself does:
+ * `$MOZBUILD_STATE_PATH`, else `~/.mozbuild` (same resolution as
+ * `mach-resource-shim.ts`).
+ */
+function mozbuildStateDir() {
+    return process.env['MOZBUILD_STATE_PATH'] ?? join(homedir(), '.mozbuild');
+}
 /** Where each tool's minimum is declared inside the Firefox tree. */
 const MINIMUM_DECLARATIONS = {
     // build/moz.configure/bindgen.configure:
@@ -43,13 +57,30 @@ const MINIMUM_DECLARATIONS = {
         pattern: /MINIMUM_RUST_VERSION\s*=\s*["']([\d.]+)["']/,
     },
 };
-/** How each tool's host binary is resolved and its version parsed. */
+/**
+ * How each tool's host binary is resolved and its version parsed.
+ *
+ * `stateDirRelPaths` are the mach-state-directory locations `fireforge
+ * bootstrap` (via mozboot) installs the tool to. mach's configure tries
+ * the state directory BEFORE the PATH candidates (bindgen.configure's
+ * toolchain search path lists `~/.mozbuild/cbindgen/cbindgen` first — a
+ * configure log shows `trying cbindgen: ~/.mozbuild/cbindgen/cbindgen`
+ * ahead of PATH), so the probe must too. 0.35.0 probed only env-or-PATH,
+ * which failed a build configure would have accepted whenever an old
+ * `~/.cargo/bin/cbindgen` shadowed a current bootstrap-installed copy
+ * (field report: PATH 0.29.1 vs mozbuild 0.29.4, minimum 0.29.4). Rust
+ * has no state-dir install — rustup owns it — so its list is empty.
+ */
 const HOST_PROBES = {
     // `mach configure` honours the CBINDGEN env option (bindgen.configure's
     // `option(env="CBINDGEN", ...)`), so the probe must too — otherwise the
     // preflight could veto a build configure would have accepted.
-    cbindgen: { envVar: 'CBINDGEN', versionPattern: /cbindgen\s+(\d+(?:\.\d+)*)/ },
-    rustc: { envVar: 'RUSTC', versionPattern: /rustc\s+(\d+(?:\.\d+)*)/ },
+    cbindgen: {
+        envVar: 'CBINDGEN',
+        versionPattern: /cbindgen\s+(\d+(?:\.\d+)*)/,
+        stateDirRelPaths: ['cbindgen/cbindgen'],
+    },
+    rustc: { envVar: 'RUSTC', versionPattern: /rustc\s+(\d+(?:\.\d+)*)/, stateDirRelPaths: [] },
 };
 /**
  * Parses a dotted version string into numeric components. Trailing
@@ -126,29 +157,54 @@ export async function readDeclaredToolchainMinimums(engineDir) {
     return minimums;
 }
 /** Runs `<binary> --version` and parses the leading version number. */
-async function probeHostToolVersion(tool) {
-    const probe = HOST_PROBES[tool];
-    const binary = process.env[probe.envVar] ?? tool;
+async function probeBinaryVersion(binary, versionPattern) {
     const output = await new Promise((resolvePromise) => {
         execFile(binary, ['--version'], { timeout: 10_000 }, (err, stdout) => {
             resolvePromise(err ? undefined : stdout);
         });
     });
-    if (output === undefined) {
-        verbose(`Toolchain preflight: "${binary} --version" failed or not found; skipping ${tool}.`);
+    if (output === undefined)
         return undefined;
-    }
-    const match = probe.versionPattern.exec(output);
+    const match = versionPattern.exec(output);
     if (!match?.[1]) {
-        verbose(`Toolchain preflight: could not parse ${tool} version from "${output.trim()}".`);
+        verbose(`Toolchain preflight: could not parse a version from "${output.trim()}" (${binary}).`);
         return undefined;
     }
     return match[1];
 }
+/**
+ * Probes every candidate binary for a tool in mach's resolution order:
+ * the env override (which, when set, is the ONLY candidate — configure
+ * uses it even when a better binary exists elsewhere), then the mozbuild
+ * state-directory copy bootstrap installs, then PATH. Candidates that
+ * fail to run or to parse are dropped silently.
+ */
+async function probeHostToolCandidates(tool) {
+    const probe = HOST_PROBES[tool];
+    const envOverride = process.env[probe.envVar];
+    const binaries = envOverride
+        ? [envOverride]
+        : [...probe.stateDirRelPaths.map((rel) => join(mozbuildStateDir(), rel)), tool];
+    const candidates = [];
+    for (const binary of binaries) {
+        const version = await probeBinaryVersion(binary, probe.versionPattern);
+        if (version !== undefined) {
+            candidates.push({ binary, version });
+        }
+        else {
+            verbose(`Toolchain preflight: "${binary} --version" failed or not found; skipping.`);
+        }
+    }
+    return candidates;
+}
 /**
  * Compares the tree-declared toolchain minimums against the host binaries
- * `mach configure` will resolve. Returns only DEFINITIVE mismatches; every
- * uncertain probe passes silently (see module header for the rationale).
+ * `mach configure` will resolve, in configure's own candidate order (env
+ * override, mozbuild state dir, PATH). A tool fails ONLY when at least
+ * one candidate resolved and none of them meets the minimum; any single
+ * passing candidate passes the tool (configure will find it), and a tool
+ * with no resolvable candidate skips silently (see module header for the
+ * fail-soft rationale).
  *
  * @param engineDir - Path to the engine directory
  */
@@ -159,37 +215,42 @@ export async function runToolchainPreflight(engineDir) {
         const minimum = parseVersionComponents(minimumVersion);
         if (!minimum)
             continue;
-        const hostVersion = await probeHostToolVersion(tool);
-        if (hostVersion === undefined)
+        const candidates = await probeHostToolCandidates(tool);
+        const parsed = candidates.filter((c) => parseVersionComponents(c.version) !== undefined);
+        if (parsed.length === 0)
             continue;
-        const host = parseVersionComponents(hostVersion);
-        if (!host)
+        const satisfying = parsed.find((c) => {
+            const components = parseVersionComponents(c.version);
+            return components !== undefined && !isVersionLower(components, minimum);
+        });
+        if (satisfying) {
+            verbose(`Toolchain preflight: ${tool} ${satisfying.version} (${satisfying.binary}) satisfies minimum ${minimumVersion}.`);
             continue;
-        if (isVersionLower(host, minimum)) {
-            mismatches.push({
-                tool,
-                hostVersion,
-                minimumVersion,
-                declaredIn: MINIMUM_DECLARATIONS[tool].relPath,
-            });
-        }
-        else {
-            verbose(`Toolchain preflight: ${tool} ${hostVersion} satisfies minimum ${minimumVersion}.`);
         }
+        mismatches.push({
+            tool,
+            minimumVersion,
+            declaredIn: MINIMUM_DECLARATIONS[tool].relPath,
+            candidates: parsed,
+        });
     }
     return mismatches;
 }
 /**
  * Formats the fail-fast message for definitive preflight mismatches,
- * naming `fireforge bootstrap` as the remedy (mach's own configure error
+ * listing every candidate probed (in mach's resolution order) and naming
+ * `fireforge bootstrap` as the remedy (mach's own configure error
  * suggests `./mach bootstrap`, which is the wrong entry point for a
  * FireForge-managed repo).
  */
 export function formatToolchainMismatchMessage(mismatches) {
-    const lines = mismatches.map((m) => `  - ${m.tool} ${m.hostVersion} is older than the minimum ${m.minimumVersion} declared by this Firefox source (engine/${m.declaredIn})`);
+    const lines = mismatches.map((m) => {
+        const probed = m.candidates.map((c) => `${c.version} (${c.binary})`).join(', ');
+        return (`  - ${m.tool}: no resolvable candidate meets the minimum ${m.minimumVersion} declared by ` +
+            `this Firefox source (engine/${m.declaredIn}); probed in mach's resolution order: ${probed}`);
+    });
     return ('Toolchain preflight found host tools older than what this Firefox source requires:\n' +
         `${lines.join('\n')}\n\n` +
         'This typically happens after "fireforge download --force" moved the engine to a new ' +
         'Firefox major version. Run "fireforge bootstrap" to update the toolchain, then retry the build.');
 }
-//# sourceMappingURL=toolchain-preflight.js.map

package/dist/src/core/typecheck-shim.js

@@ -60,6 +60,7 @@ interface ChromeUtilsShim {
   defineESModuleGetters(target: any, modules: Record<string, string>): void;
   importESModule(specifier: string): any;
   import(specifier: string): any;
+  registerWindowActor(name: string, options: Record<string, any>): void;
   defineModuleGetter(target: any, name: string, specifier: string): void;
   defineLazyGetter(target: any, name: string, getter: () => any): void;
   generateQI(interfaces: any[]): Function;
@@ -85,6 +86,18 @@ declare var gBrowser: any;
 declare var gURLBar: any;
 declare var gNavigatorBundle: any;
 declare var AppConstants: any;
+declare class JSWindowActorChild {
+  readonly browsingContext: any;
+  readonly contentWindow: any;
+  readonly document: any;
+  sendAsyncMessage(name: string, data?: any, transfers?: any[]): void;
+  sendQuery(name: string, data?: any, transfers?: any[]): Promise<any>;
+}
+declare class JSWindowActorParent {
+  readonly browsingContext: any;
+  sendAsyncMessage(name: string, data?: any, transfers?: any[]): void;
+  sendQuery(name: string, data?: any, transfers?: any[]): Promise<any>;
+}
 // Fluent localization — a stable chrome global. Members stay loose (any),
 // but the constructor shape is declared so "new Localization([...])" and
 // "new Localization([...], true)" typecheck without a local cast. Both
@@ -213,4 +226,3 @@ export async function composeShimSource(projectRoot, extraShimPath) {
         extraShimAppended: true,
     };
 }
-//# sourceMappingURL=typecheck-shim.js.map

package/dist/src/core/typecheck.js

@@ -327,4 +327,3 @@ export function relativeForDisplay(projectRoot, absoluteFile) {
         return absoluteFile;
     return rel;
 }
-//# sourceMappingURL=typecheck.js.map

package/dist/src/core/wire-destroy.js

@@ -121,4 +121,3 @@ export async function addDestroyToBrowserInit(engineDir, expression, marker = DE
     await writeText(filePath, value);
     return true;
 }
-//# sourceMappingURL=wire-destroy.js.map

package/dist/src/core/wire-dom-fragment.js

@@ -181,4 +181,3 @@ export async function addDomFragment(engineDir, domFilePath, targetPath = DEFAUL
     await writeText(targetAbsPath, value);
     return true;
 }
-//# sourceMappingURL=wire-dom-fragment.js.map

package/dist/src/core/wire-init.js

@@ -231,4 +231,3 @@ export async function addInitToBrowserInit(engineDir, expression, after, marker
     await writeText(filePath, value);
     return true;
 }
-//# sourceMappingURL=wire-init.js.map

package/dist/src/core/wire-subscript.js

@@ -144,4 +144,3 @@ export async function addSubscriptToBrowserMain(engineDir, name, marker = DEFAUL
     await writeText(filePath, value);
     return true;
 }
-//# sourceMappingURL=wire-subscript.js.map

package/dist/src/core/wire-targets.js

@@ -6,4 +6,3 @@ export { addDestroyToBrowserInit } from './wire-destroy.js';
 export { addDomFragment } from './wire-dom-fragment.js';
 export { addInitToBrowserInit } from './wire-init.js';
 export { addSubscriptToBrowserMain } from './wire-subscript.js';
-//# sourceMappingURL=wire-targets.js.map

package/dist/src/core/wire-utils.js

@@ -349,4 +349,3 @@ export function findMethodBody(ast, methodName) {
     });
     return found;
 }
-//# sourceMappingURL=wire-utils.js.map