@hominis/fireforge 0.33.0 → 0.34.0

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

@@ -1,3 +1,29 @@
 import type { ReExportOptions } from '../types/commands/index.js';
+/** Result of {@link normalizeReExportFilesPositionals}. */
+export interface NormalizedReExportArguments {
+    patches: string[];
+    options: ReExportOptions;
+    /** Extra positionals that were folded into the `--files` list. */
+    foldedPaths: string[];
+}
+/**
+ * Accepts the `export`-style space-separated path shape for
+ * `re-export <patch> --files` (0.34.0 field report): commander's
+ * `--files <paths>` consumes one comma-separated value, so
+ * `re-export 006-x --files a/b.js c/d.js` used to park `c/d.js` in the
+ * positional patches and fail with "--files operates on exactly one
+ * target patch" — pointing at the wrong argument. When every positional
+ * beyond the first looks like a file path, fold them into the file list.
+ */
+export declare function normalizeReExportFilesPositionals(patches: readonly string[], options: ReExportOptions): NormalizedReExportArguments;
+/**
+ * Folding wrapper used by the command layer: applies
+ * {@link normalizeReExportFilesPositionals} and logs the folded paths so
+ * the operator sees exactly which positionals became file-list entries.
+ */
+export declare function applyReExportFilesPositionalFolding(patches: string[], options: ReExportOptions): {
+    patches: string[];
+    options: ReExportOptions;
+};
 /** Validates mutually exclusive `re-export` targeting and metadata options. */
 export declare function validateReExportOptionCombinations(patches: readonly string[], options: ReExportOptions): void;

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

@@ -1,5 +1,50 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { InvalidArgumentError } from '../errors/base.js';
+import { info } from '../utils/logger.js';
+/**
+ * Heuristic for `--files` positional folding: an extra positional that
+ * contains a path separator and is not a `.patch` filename is an engine
+ * file path, not a patch identifier.
+ */
+function looksLikeFilePath(value) {
+    return value.includes('/') && !value.endsWith('.patch');
+}
+/**
+ * Accepts the `export`-style space-separated path shape for
+ * `re-export <patch> --files` (0.34.0 field report): commander's
+ * `--files <paths>` consumes one comma-separated value, so
+ * `re-export 006-x --files a/b.js c/d.js` used to park `c/d.js` in the
+ * positional patches and fail with "--files operates on exactly one
+ * target patch" — pointing at the wrong argument. When every positional
+ * beyond the first looks like a file path, fold them into the file list.
+ */
+export function normalizeReExportFilesPositionals(patches, options) {
+    if (options.files === undefined || patches.length <= 1) {
+        return { patches: [...patches], options, foldedPaths: [] };
+    }
+    const [first, ...rest] = patches;
+    if (first !== undefined && rest.every(looksLikeFilePath)) {
+        return {
+            patches: [first],
+            options: { ...options, files: [...options.files, ...rest] },
+            foldedPaths: rest,
+        };
+    }
+    return { patches: [...patches], options, foldedPaths: [] };
+}
+/**
+ * Folding wrapper used by the command layer: applies
+ * {@link normalizeReExportFilesPositionals} and logs the folded paths so
+ * the operator sees exactly which positionals became file-list entries.
+ */
+export function applyReExportFilesPositionalFolding(patches, options) {
+    const normalized = normalizeReExportFilesPositionals(patches, options);
+    if (normalized.foldedPaths.length > 0) {
+        info(`--files: treating ${normalized.foldedPaths.length} extra positional path(s) as part ` +
+            `of the file list: ${normalized.foldedPaths.join(', ')}`);
+    }
+    return { patches: normalized.patches, options: normalized.options };
+}
 /** Validates mutually exclusive `re-export` targeting and metadata options. */
 export function validateReExportOptionCombinations(patches, options) {
     if (options.files !== undefined) {
@@ -10,7 +55,9 @@ export function validateReExportOptionCombinations(patches, options) {
             throw new InvalidArgumentError('--files cannot be combined with --scan-files.', '--files');
         }
         if (patches.length !== 1) {
-            throw new InvalidArgumentError('--files operates on exactly one target patch. Pass a single patch identifier.', '--files');
+            throw new InvalidArgumentError('--files operates on exactly one target patch. Pass a single patch identifier. ' +
+                'File paths can be passed space-separated after --files (path-shaped extras are folded ' +
+                'into the file list automatically) or as one comma-separated --files value.', '--files');
         }
     }
     if (options.scanFiles !== undefined) {

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

@@ -19,7 +19,7 @@ import { pickDefined } from '../utils/options.js';
 import { runPatchLint } from './export-shared.js';
 import { loadScanFilesAssignments, withDryRunReExportLock } from './re-export-bulk-scan.js';
 import { reExportFilesInPlace } from './re-export-files.js';
-import { validateReExportOptionCombinations } from './re-export-options.js';
+import { applyReExportFilesPositionalFolding, validateReExportOptionCombinations, } from './re-export-options.js';
 import { assertScanFileAdditionsHaveDiffHunks, confirmBroadScanAdditions, normalizeScanFiles, scanPatchFilesForReExport, } from './re-export-scan.js';
 async function findMissingFiles(engineDir, files) {
     const missingFiles = [];
@@ -286,6 +286,9 @@ export async function reExportCommand(projectRoot, patches, options) {
     }
     const isDryRun = options.dryRun === true;
     intro(isDryRun ? 'FireForge Re-export (dry run)' : 'FireForge Re-export');
+    // Accept export-style space-separated paths after --files by folding
+    // path-shaped extra positionals into the file list (0.34.0 field report).
+    ({ patches, options } = applyReExportFilesPositionalFolding(patches, options));
     validateReExportOptionCombinations(patches, options);
     const paths = getProjectPaths(projectRoot);
     // Check if engine exists

package/dist/src/commands/register.js

@@ -43,7 +43,9 @@ export async function registerCommand(projectRoot, filePath, options = {}) {
             throw new InvalidArgumentError(`File not found in engine: ${engineRelativePath}`, 'path');
         }
     }
-    const result = await registerFile(projectRoot, engineRelativePath, options.dryRun, options.after);
+    const result = await registerFile(projectRoot, engineRelativePath, options.dryRun, options.after, {
+        ...(options.createManifest !== undefined ? { createManifest: options.createManifest } : {}),
+    });
     if (options.dryRun) {
         // 2026-04-21 eval (Finding #8): dry-run always said "Would
         // register" even when the rule's idempotency check already knew
@@ -59,6 +61,9 @@ export async function registerCommand(projectRoot, filePath, options = {}) {
         info(`[dry-run] Would register ${engineRelativePath}`);
         info(`  manifest: ${result.manifest}`);
         info(`  entry: ${result.entry}`);
+        for (const action of result.scaffoldActions ?? []) {
+            info(`  scaffold: ${action.manifest} — ${action.change}`);
+        }
         if (result.previousEntry) {
             info(`  insert after: ${result.previousEntry}`);
         }
@@ -80,6 +85,9 @@ export async function registerCommand(projectRoot, filePath, options = {}) {
         }
         const position = result.previousEntry ? ` (after ${result.previousEntry})` : '';
         success(`Registered ${engineRelativePath} in ${result.manifest}${position}`);
+        for (const action of result.scaffoldActions ?? []) {
+            info(`  scaffold: ${action.manifest} — ${action.change}`);
+        }
         info("hint: Run 'fireforge build --ui' to make the new module available at runtime");
     }
     outro('Done');
@@ -91,6 +99,7 @@ export function registerRegister(program, { getProjectRoot, withErrorHandling })
         .description('Register a file in the appropriate build manifest')
         .option('--dry-run', 'Show what would be changed without writing')
         .option('--after <entry>', 'Place entry after line containing this substring (instead of alphabetical)')
+        .option('--create-manifest', 'Scaffold a missing manifest (directory moz.build with EXTRA_JS_MODULES / XPCSHELL_TESTS_MANIFESTS, or xpcshell.toml) and wire the parent DIRS chain instead of failing with "Manifest not found"')
         .action(withErrorHandling(async (path, options) => {
         await registerCommand(getProjectRoot(), path, pickDefined(options));
     }));

package/dist/src/commands/test-diagnose.js

@@ -183,6 +183,18 @@ export function finalizeSingleRunOutcome(outcome, normalizedPaths, binaryName, p
     if (outcome.verdict.kind === 'harness-crash' && outcome.verdict.signature) {
         throw new GeneralError(buildHarnessCrashMessage(outcome.verdict.signature, outcome.attempts));
     }
+    if (outcome.verdict.kind === 'tests-ran-ok') {
+        // The verdict is authoritative over the raw exit code: a completed
+        // green embedded summary overrides a non-zero exit caused by harness
+        // noise (field report: fully green --no-shard runs exited 1, forcing
+        // operators to parse embedded summaries by hand).
+        if (outcome.verdict.greenSummaryOverride) {
+            info(`Note: mach exited ${outcome.result.exitCode}, but the embedded suite summary completed ` +
+                'green (Unexpected results: 0). FireForge treats the run as passed; the non-zero exit ' +
+                'came from non-fatal harness noise (resource-monitor degradation / telemetry).');
+        }
+        return;
+    }
     if (outcome.verdict.kind === 'no-tests' && outcome.result.exitCode === 0) {
         // The silent false green: exit 0 plus a "Passed: 0"-style summary with
         // zero TEST-START lines must fail, not pass.

package/dist/src/commands/test.js

@@ -1,11 +1,12 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join, resolve } from 'node:path';
+import { readBuildBaseline } from '../core/build-baseline.js';
 import { prepareBuildEnvironment } from '../core/build-prepare.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
-import { buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, hasRunnableBundle, withBuildLock, } from '../core/mach.js';
+import { buildArtifactMismatchMessage, hasBuildArtifacts, hasRunnableBundle, runProtectedMachBuild, withBuildLock, } from '../core/mach.js';
 import { assertMarionettePortAvailable, extractForwardedMarionettePort, forwardedMachArgsIncludeMarionetteClient, shouldAutoForwardMarionettePortToMach, } from '../core/marionette-port.js';
 import { formatMarionettePreflightLine, reportMarionettePreflight, runMarionettePreflight, } from '../core/marionette-preflight.js';
-import { buildHarnessCrashMessage, detectHarnessCrashSignature, } from '../core/test-harness-crash.js';
+import { buildHarnessCrashMessage } from '../core/test-harness-crash.js';
 import { createPostRebuildFailureContext } from '../core/test-harness-output.js';
 import { checkStaleBuildForTest, formatStaleBuildWarning } from '../core/test-stale-check.js';
 import { findNearestXpcshellManifest } from '../core/xpcshell-appdir.js';
@@ -102,29 +103,35 @@ async function resolveLaunchablePathForTests(engineDir, binaryName, objDir) {
 }
 async function runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries) {
     await withBuildLock(projectRoot, async () => {
-        await prepareBuildEnvironment(projectRoot, paths, projectConfig);
+        // Pass the previous baseline exactly like `fireforge build` does, so
+        // auto-configure runs under the same conditions on both paths. The
+        // pre-test build must never invalidate more of the objdir than a plain
+        // `mach build faster` would (field incident: a failed pre-test build
+        // was followed by a ~64-minute full rebuild where an incremental one
+        // should have sufficed).
+        const previousBaseline = await readBuildBaseline(projectRoot);
+        await prepareBuildEnvironment(projectRoot, paths, projectConfig, { previousBaseline });
         const s = spinner('Running incremental build...');
-        // The pre-test build runs through mach too, so the same resource-monitor
-        // startup crash that aborts `mach test` can abort `mach build faster`.
-        // Run the harness-crash classifier over the build output and retry within
-        // the same `--harness-retries` budget rather than hard-failing with a
-        // bare "Pre-test build failed" (field report E2).
-        const maxAttempts = Math.max(1, harnessRetries + 1);
-        for (let attempt = 1;; attempt += 1) {
-            const buildResult = await buildUI(paths.engine);
-            if (buildResult.exitCode === 0) {
-                s.stop('Build complete');
-                return;
-            }
-            const signature = detectHarnessCrashSignature(`${buildResult.stdout}\n${buildResult.stderr}`);
-            if (signature && attempt < maxAttempts) {
+        // The pre-test build routes through the same protected mach dispatch as
+        // `fireforge build` / `build --ui`: in-venv resource-monitor guard plus
+        // the uniform recognized-crash retry budget, with a fresh mach process
+        // (and fresh guard install) per attempt. prepareBuildEnvironment runs
+        // ONCE, outside the retry loop — retries never re-run mach configure.
+        const result = await runProtectedMachBuild('faster', paths.engine, {
+            retries: harnessRetries,
+            onRetry: (signature, nextAttempt, maxAttempts) => {
                 s.message(`Pre-test build hit a harness crash (${signature.reason}); ` +
-                    `retrying (attempt ${attempt + 1} of ${maxAttempts})...`);
-                continue;
-            }
-            s.error('Pre-test build failed');
-            throw new BuildError(signature ? buildHarnessCrashMessage(signature, attempt) : 'Pre-test build failed', 'mach build faster');
+                    `retrying (attempt ${nextAttempt} of ${maxAttempts})...`);
+            },
+        });
+        if (result.exitCode === 0) {
+            s.stop('Build complete');
+            return;
         }
+        s.error('Pre-test build failed');
+        throw new BuildError(result.crashSignature
+            ? buildHarnessCrashMessage(result.crashSignature, result.attempts, 'mach build faster')
+            : 'Pre-test build failed', 'mach build faster');
     });
 }
 function logTestSelection(normalizedPaths) {

package/dist/src/core/furnace-registration.d.ts

@@ -71,6 +71,30 @@ export declare function removeLocaleFtlJarMnEntry(engineDir: string, jarMnRelPat
  * @param tagName - Custom element tag name whose entries should be removed
  */
 export declare function removeJarMnEntries(engineDir: string, tagName: string): Promise<void>;
+/** A jar.mn widget registration line whose source file no longer exists. */
+export interface StaleJarMnEntry {
+    /** Component tag name from the `(widgets/<tag>/<file>)` source mapping. */
+    tagName: string;
+    /** File name from the source mapping. */
+    fileName: string;
+    /** The full (trimmed) jar.mn line. */
+    line: string;
+}
+/**
+ * Scans jar.mn for widget registration lines `(widgets/<tag>/<file>)`
+ * whose workspace source file no longer exists (0.34.0 field report: a
+ * renamed component helper left the old line pointing at a deleted file,
+ * and every build failed at packaging). Only tags in `managedTags`
+ * (furnace-managed custom components) are inspected so upstream lines are
+ * never touched.
+ */
+export declare function findStaleJarMnEntries(engineDir: string, customDir: string, managedTags: readonly string[]): Promise<StaleJarMnEntry[]>;
+/**
+ * Removes every stale widget registration line found by
+ * {@link findStaleJarMnEntries}. Returns the removed entries. Used by
+ * `furnace validate --fix` and `doctor --repair-furnace`.
+ */
+export declare function pruneStaleJarMnEntries(engineDir: string, customDir: string, managedTags: readonly string[]): Promise<StaleJarMnEntry[]>;
 /**
  * Validates that jar.mn entries *could* be added without writing anything.
  * Used by dry-run to surface structural problems early.

package/dist/src/core/furnace-registration.js

@@ -224,14 +224,67 @@ export async function removeJarMnEntries(engineDir, tagName) {
     }
     let content = await readText(filePath);
     const lines = content.split('\n');
-    // Use a regex with word boundary so "moz-card" does not match "moz-card-group".
-    const pattern = new RegExp(`content/global/elements/${escapeForRegex(tagName)}\\.`);
-    const filtered = lines.filter((line) => !pattern.test(line));
+    // Match by the SOURCE MAPPING segment `(widgets/<tagName>/...)` so every
+    // line the component registered is removed regardless of the target
+    // basename — a helper `.mjs` whose name does not start with the tag
+    // (e.g. a renamed `foo-utils.mjs`) used to survive the remove pass and
+    // leave a stale registration that broke packaging (0.34.0 field
+    // report). The legacy target-path match is kept as an OR for lines
+    // written by older FireForge versions without a source mapping. Word
+    // boundaries keep "moz-card" from matching "moz-card-group".
+    const sourcePattern = new RegExp(`\\(widgets/${escapeForRegex(tagName)}/`);
+    const legacyTargetPattern = new RegExp(`content/global/elements/${escapeForRegex(tagName)}\\.`);
+    const filtered = lines.filter((line) => !sourcePattern.test(line) && !legacyTargetPattern.test(line));
     if (filtered.length === lines.length)
         return;
     content = filtered.join('\n');
     await writeText(filePath, content);
 }
+const WIDGET_SOURCE_MAPPING_PATTERN = /\(widgets\/([^/)]+)\/([^)]+)\)/;
+/**
+ * Scans jar.mn for widget registration lines `(widgets/<tag>/<file>)`
+ * whose workspace source file no longer exists (0.34.0 field report: a
+ * renamed component helper left the old line pointing at a deleted file,
+ * and every build failed at packaging). Only tags in `managedTags`
+ * (furnace-managed custom components) are inspected so upstream lines are
+ * never touched.
+ */
+export async function findStaleJarMnEntries(engineDir, customDir, managedTags) {
+    const filePath = join(engineDir, JAR_MN);
+    if (!(await pathExists(filePath)))
+        return [];
+    const managed = new Set(managedTags);
+    const stale = [];
+    for (const line of (await readText(filePath)).split('\n')) {
+        const match = WIDGET_SOURCE_MAPPING_PATTERN.exec(line);
+        if (!match)
+            continue;
+        const tagName = match[1] ?? '';
+        const fileName = match[2] ?? '';
+        if (!managed.has(tagName))
+            continue;
+        if (!(await pathExists(join(customDir, tagName, fileName)))) {
+            stale.push({ tagName, fileName, line: line.trim() });
+        }
+    }
+    return stale;
+}
+/**
+ * Removes every stale widget registration line found by
+ * {@link findStaleJarMnEntries}. Returns the removed entries. Used by
+ * `furnace validate --fix` and `doctor --repair-furnace`.
+ */
+export async function pruneStaleJarMnEntries(engineDir, customDir, managedTags) {
+    const stale = await findStaleJarMnEntries(engineDir, customDir, managedTags);
+    if (stale.length === 0)
+        return [];
+    const filePath = join(engineDir, JAR_MN);
+    const staleLines = new Set(stale.map((entry) => entry.line));
+    const lines = (await readText(filePath)).split('\n');
+    const filtered = lines.filter((line) => !staleLines.has(line.trim()));
+    await writeText(filePath, filtered.join('\n'));
+    return stale;
+}
 /**
  * Validates that jar.mn entries *could* be added without writing anything.
  * Used by dry-run to surface structural problems early.

package/dist/src/core/furnace-validate-registration.js

@@ -10,6 +10,7 @@ import { getProjectPaths, loadConfig } from './config.js';
 import { getFurnacePaths } from './furnace-config.js';
 import { CUSTOM_ELEMENTS_JS, FTL_DIR, JAR_MN } from './furnace-constants.js';
 import { expandCssFragments, listFragmentIncludes } from './furnace-css-fragments.js';
+import { findStaleJarMnEntries } from './furnace-registration.js';
 import { isTagInCorrectCustomElementsPlacement } from './furnace-registration-validate.js';
 import { getTokensCssPath } from './token-manager.js';
 /**
@@ -210,6 +211,23 @@ export async function validateJarMnEntries(root, config) {
             });
         }
     }
+    // Stale registrations: lines pointing at component files that no longer
+    // exist in the workspace (left behind by a rename/delete under an older
+    // FireForge). These break `mach build` at packaging ("File ... not
+    // found"), so they are errors and `--fix` prunes them (0.34.0 field
+    // report: both validate --fix and doctor --repair-furnace reported
+    // success without pruning).
+    const staleEntries = await findStaleJarMnEntries(engineDir, furnacePaths.customDir, Object.keys(config.custom));
+    for (const stale of staleEntries) {
+        issues.push({
+            component: stale.tagName,
+            severity: 'error',
+            check: 'stale-jar-registration',
+            message: `jar.mn registers ${stale.fileName} for ${stale.tagName}, but the source file no longer exists ` +
+                `(stale line: "${stale.line}"). Packaging will fail until the line is removed — run ` +
+                '"fireforge furnace validate --fix" or "fireforge doctor --repair-furnace" to prune it.',
+        });
+    }
     return issues;
 }
 /**

package/dist/src/core/mach-resource-shim.d.ts

@@ -1,21 +1,58 @@
 /**
- * Resource-monitor degrade shim for `mach build`.
+ * Resource-monitor degrade guard for mach dispatches.
  *
  * mozbuild's build resource monitor calls `psutil.virtual_memory()` at
- * startup (`start_resource_recording`). On some hosts (psutil vs Darwin 27)
- * that raises `RuntimeError: host_statistics64(HOST_VM_INFO64) syscall
- * failed`, which aborts `mach build` / `mach build faster` before any work
- * happens — so a raw `./mach build faster` dies while the build never
- * reaches the compiler. The suite-specific test commands sidestep the
- * monitor entirely, but the build commands have no such escape.
+ * startup (`start_resource_recording`) and again later from
+ * `mozbuild.base._run_make`. On some hosts (psutil vs Darwin 27) those
+ * raise `RuntimeError: host_statistics64(HOST_VM_INFO64) syscall failed`,
+ * and a `SystemResourceMonitor.__init__` that fails partway leaves an
+ * instance without `poll_interval`, so later polling dies with
+ * `AttributeError: ... poll_interval`. Any of these aborts `mach build` /
+ * `mach build faster` before the compiler ever runs.
  *
- * FireForge writes a tiny `sitecustomize.py` and points the mach
- * subprocess's `PYTHONPATH` at it. Python imports `sitecustomize` at
- * interpreter startup (before mach runs), so the shim wraps
- * `psutil.virtual_memory` / `swap_memory` to downgrade the host syscall
- * failure into a non-fatal `UserWarning` and return a zeroed reading. The
- * build then proceeds regardless of which mach entry point spawned it. When
- * psutil works normally the wrapper is a transparent pass-through.
+ * 0.33.0 injected a `sitecustomize.py` via the mach subprocess PYTHONPATH.
+ * Field report (0.34.0 cycle): mach re-execs itself into its private
+ * virtualenv and drops PYTHONPATH, so the env-var route never loads and
+ * the crash family escaped on every protected entry point. FireForge now
+ * owns the guard in-process on its mach dispatches by installing a
+ * `fireforge_mach_guard.pth` + module pair directly into every discovered
+ * mach virtualenv site-packages directory: `.pth` files execute at
+ * interpreter startup from the venv's own site-packages, which survives
+ * the re-exec. The PYTHONPATH `sitecustomize.py` is retained only as a
+ * belt-and-suspenders for the pre-venv bootstrap phase (first build, no
+ * `_virtualenvs` on disk yet).
+ *
+ * The guard itself covers the whole crash family:
+ *  - wraps `psutil.virtual_memory` / `swap_memory` / `cpu_percent` /
+ *    `cpu_times` / `disk_io_counters` module-wide, so every call site —
+ *    including the direct `psutil.virtual_memory()` in
+ *    `mozbuild.base._run_make` — degrades to a `UserWarning` and a zeroed
+ *    reading instead of aborting;
+ *  - guards `SystemResourceMonitor` CONSTRUCTION via an import hook:
+ *    `poll_interval` is pre-populated before the real `__init__` runs, a
+ *    failing `__init__` marks the instance degraded instead of raising,
+ *    and every monitor method no-ops on a degraded instance — so a
+ *    partially-constructed monitor can never surface the
+ *    `AttributeError: poll_interval` variant.
+ */
+/** Result of installing the mach resource guard before a dispatch. */
+export interface MachResourceGuardInstallation {
+    /**
+     * Env overlay for the mach subprocess: the PYTHONPATH sitecustomize
+     * fallback that covers the pre-venv bootstrap phase. Merged over
+     * `process.env` by the exec layer.
+     */
+    env: Record<string, string>;
+    /** site-packages directories the in-venv guard was written into. */
+    sitePackagesDirs: string[];
+}
+/**
+ * Installs the resource-monitor degrade guard for a mach dispatch:
+ * `fireforge_mach_guard.pth` + `fireforge_mach_guard.py` into every
+ * discovered mach virtualenv site-packages (survives mach's venv re-exec),
+ * plus the PYTHONPATH sitecustomize fallback for the pre-venv bootstrap
+ * phase. Idempotent and re-run before EVERY protected dispatch (including
+ * each retry) so a venv created by a crashed first attempt is guarded on
+ * the next one instead of re-dying on the same wedged state.
  */
-/** Ensures the shim exists and returns the mach `env` overlay that enables it. */
-export declare function resolveMachBuildEnv(): Promise<Record<string, string>>;
+export declare function installMachResourceGuard(engineDir: string): Promise<MachResourceGuardInstallation>;