@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/core/mach-python.js

@@ -1,131 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { join } from 'node:path';
-import { PythonNotFoundError } from '../errors/build.js';
-import { toError } from '../utils/errors.js';
-import { pathExists, readText } from '../utils/fs.js';
-import { verbose } from '../utils/logger.js';
-import { exec, executableExists } from '../utils/process.js';
-/** Cached Python resolution state */
-/**
- * The resolved interpreter and the requirement range it was resolved for.
- * `undefined` means "not resolved yet". The two always move together, so
- * one nullable record beats two independently-deletable fields.
- */
-let pythonCache;
-const DEFAULT_MACH_PYTHON_REQUIREMENTS = {
-    min: { major: 3, minor: 8 },
-    max: { major: 3, minor: 12 },
-};
-function formatPythonMinor(version) {
-    return `${version.major}.${version.minor}`;
-}
-function formatRequirementsKey(requirements) {
-    return `${formatPythonMinor(requirements.min)}-${formatPythonMinor(requirements.max)}`;
-}
-function comparePythonVersions(left, right) {
-    if (left.major !== right.major)
-        return left.major - right.major;
-    if (left.minor !== right.minor)
-        return left.minor - right.minor;
-    return (left.micro ?? 0) - (right.micro ?? 0);
-}
-function isVersionWithinRequirements(version, requirements) {
-    return (comparePythonVersions({ major: version.major, minor: version.minor }, requirements.min) >= 0 &&
-        comparePythonVersions({ major: version.major, minor: version.minor }, requirements.max) <= 0);
-}
-function parsePythonVersion(output) {
-    const match = /(\d+)\.(\d+)\.(\d+)/.exec(output.trim());
-    if (!match)
-        return undefined;
-    return {
-        major: Number(match[1]),
-        minor: Number(match[2]),
-        micro: Number(match[3]),
-    };
-}
-async function readMachPythonRequirements(engineDir) {
-    if (!engineDir) {
-        return DEFAULT_MACH_PYTHON_REQUIREMENTS;
-    }
-    const machPath = join(engineDir, 'mach');
-    if (!(await pathExists(machPath))) {
-        return DEFAULT_MACH_PYTHON_REQUIREMENTS;
-    }
-    try {
-        const machContent = await readText(machPath);
-        const minMatch = /MIN_PYTHON_VERSION\s*=\s*\((\d+),\s*(\d+)\)/.exec(machContent);
-        const maxMatch = /MAX_PYTHON_VERSION_TO_CONSIDER\s*=\s*\((\d+),\s*(\d+)\)/.exec(machContent);
-        if (!minMatch || !maxMatch) {
-            return DEFAULT_MACH_PYTHON_REQUIREMENTS;
-        }
-        return {
-            min: { major: Number(minMatch[1]), minor: Number(minMatch[2]) },
-            max: { major: Number(maxMatch[1]), minor: Number(maxMatch[2]) },
-        };
-    }
-    catch (error) {
-        verbose(`Using default mach python requirements because engine/mach could not be read: ${toError(error).message}`);
-        return DEFAULT_MACH_PYTHON_REQUIREMENTS;
-    }
-}
-function buildPythonCandidates(requirements) {
-    const candidates = [];
-    for (let minor = requirements.max.minor; minor >= requirements.min.minor; minor--) {
-        candidates.push(`python${requirements.min.major}.${minor}`);
-    }
-    candidates.push(`python${requirements.min.major}`, 'python');
-    return [...new Set(candidates)];
-}
-/**
- * Resets the resolved Python executable. Primarily useful for testing.
- *
- * @internal Exported only so tests can reach it. Not part of the public
- * surface.
- */
-export function resetResolvedPython() {
-    pythonCache = undefined;
-}
-/**
- * Dynamically resolves the python executable and ensures it is available.
- * Checks the Python version range declared by engine/mach when available.
- * @throws PythonNotFoundError if no suitable python is installed
- */
-export async function ensurePython(engineDir) {
-    const requirements = await readMachPythonRequirements(engineDir);
-    const requirementsKey = formatRequirementsKey(requirements);
-    if (pythonCache?.requirementsKey === requirementsKey) {
-        return;
-    }
-    const candidates = buildPythonCandidates(requirements);
-    for (const candidate of candidates) {
-        if (await executableExists(candidate)) {
-            try {
-                const { stdout } = await exec(candidate, [
-                    '-c',
-                    'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}")',
-                ]);
-                const version = parsePythonVersion(stdout);
-                if (version && isVersionWithinRequirements(version, requirements)) {
-                    pythonCache = { python: candidate, requirementsKey };
-                    return;
-                }
-            }
-            catch (error) {
-                verbose(`Python candidate ${candidate} was not usable: ${toError(error).message}`);
-            }
-        }
-    }
-    throw new PythonNotFoundError(formatPythonMinor(requirements.min), formatPythonMinor(requirements.max));
-}
-/**
- * Gets the resolved Python executable name.
- * @param engineDir - Optional engine directory for engine-specific Python requirements
- * @returns The resolved Python executable name
- */
-export async function getPython(engineDir) {
-    await ensurePython(engineDir);
-    if (pythonCache === undefined) {
-        throw new PythonNotFoundError();
-    }
-    return pythonCache.python;
-}

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

@@ -1,107 +0,0 @@
-/**
- * Resource-monitor degrade guard for mach dispatches.
- *
- * mozbuild's build resource monitor calls `psutil.virtual_memory()` at
- * startup (`start_resource_recording`) and again later from
- * `mozbuild.base._run_make`. On some hosts 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.
- *
- * The guard is installed as a `fireforge_mach_guard.pth` + module pair in
- * every discovered mach virtualenv site-packages directory. A PYTHONPATH
- * `sitecustomize.py` is not sufficient on its own: mach re-execs itself into
- * its private virtualenv and drops PYTHONPATH, so that route never loads.
- * `.pth` files execute at interpreter startup from the venv's own
- * site-packages, which survives the re-exec. The PYTHONPATH copy is retained
- * only for the pre-venv bootstrap phase (first build, no `_virtualenvs` on
- * disk yet).
- *
- * The guard 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.
- *
- *    The fallback must be per-function arity-correct and reconstructible:
- *    mozsystemmonitor captures reading types at `__init__`
- *    (`self._swap_type = type(psutil.swap_memory())`) and rebuilds each
- *    collector sample via `self._swap_type(*swap_mem)`. An svmem-shaped
- *    (8-field) fallback in the swap (6-field `sswap`) position makes the
- *    parent reject every sample and break its drain loop, so the pipe fills,
- *    the collector child blocks in `send()` and never reads the terminate
- *    sentinel, and mach hangs forever in its atexit `waitpid`. Each wrapped
- *    function therefore degrades to a zeroed instance of psutil's own result
- *    namedtuple where resolvable, else a module-level guard-owned namedtuple
- *    with the exact field order and arity for that function (module-level so
- *    readings pickle by reference across the collector pipe).
- *    `_DegradedReading` remains only as a documented last resort and
- *    tolerates `type(reading)(*values)` reconstruction. Guard-owned fallback
- *    classes never depend on psutil internals resolving, which also makes
- *    them safe when two guard copies load (PYTHONPATH `sitecustomize` in the
- *    bootstrap phase plus the in-venv `.pth`), each with its own classes.
- *  - 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. Degraded aggregate methods
- *    return zeroed shapes (not `None`) where callers subscript the result
- *    (`aggregate_io` → zeroed io reading, so mozbuild's `log_resource_usage`
- *    does not die on `usage["io"].read_bytes` after a successful compile).
- *  - suppresses the mozsystemmonitor collector child on degradation: once
- *    any psutil degradation is observed in the process, monitors are kept
- *    inert (`start` never spawns the collector), and a degraded transition
- *    or raising `stop` best-effort terminates a live collector child and
- *    drains the pipe, so a malformed sample stream cannot wedge mach's
- *    shutdown even if a future shape mismatch slips through.
- *  - wraps `mozbuild.controller.building.BuildMonitor.log_resource_usage` to
- *    warn-and-continue on any exception, so end-of-build resource reporting
- *    can never fail a build whose artifacts are complete.
- */
-/**
- * Python guard body, importable both as the in-venv `fireforge_mach_guard`
- * module (loaded by the sibling `.pth` at interpreter startup) and as the
- * PYTHONPATH `sitecustomize` fallback. Defensive throughout: a missing or
- * broken psutil/mozsystemmonitor leaves mach untouched, and every wrapper
- * only intercepts the failure path. Exported for the Python-executing
- * regression test (mach-resource-shim.python.test.ts), which asserts the
- * degraded readings' runtime behavior rather than string-matching the source.
- */
-export declare const GUARD_PYTHON_SOURCE = "# Generated by FireForge - do not edit.\n# Degrades the broken host resource monitor family (psutil vs Darwin) from\n# fatal startup errors into non-fatal warnings, so mach builds and tests\n# proceed. Installed into the mach virtualenv site-packages via a .pth file\n# (survives mach's venv re-exec, which drops PYTHONPATH).\nimport builtins\nimport collections\nimport inspect\nimport sys\nimport warnings\n\nimport os\nimport shutil\n_fireforge_profile_root = os.environ.get(\"FIREFORGE_PROFILE_MERGE_ROOT\")\nif _fireforge_profile_root and not getattr(shutil.copytree, \"_fireforge_profile_merge\", False):\n    _fireforge_copytree = shutil.copytree\n    def _fireforge_merge_copytree(src, dst, *args, **kwargs):\n        if os.path.realpath(src).startswith(os.path.realpath(_fireforge_profile_root) + os.sep):\n            # Python's recursive calls may supply dirs_exist_ok positionally.\n            if len(args) >= 5:\n                args = args[:4] + (True,) + args[5:]\n            else:\n                kwargs[\"dirs_exist_ok\"] = True\n        return _fireforge_copytree(src, dst, *args, **kwargs)\n    _fireforge_merge_copytree._fireforge_profile_merge = True\n    shutil.copytree = _fireforge_merge_copytree\n\n\n# Any psutil degradation observed in this process. Once set, monitors are\n# kept inert (start never spawns the collector child) \u2014 on a flapping host a\n# healthy-looking moment must not be trusted to start a sample stream that a\n# later degraded reading could malform.\n_fireforge_host_degraded = [False]\n\n\ndef _fireforge_degraded_notice(exc):\n    _fireforge_host_degraded[0] = True\n    warnings.warn(\n        \"FireForge: host resource monitor degraded (%s); continuing without resource monitoring.\" % exc\n    )\n\n\nclass _DegradedReading(object):\n    # Last-resort duck type of psutil's namedtuple results (svmem field\n    # order): mozsystemmonitor subscripts, iterates, and unpacks readings,\n    # so the degraded fallback must survive r[0], list(r), len(r), r._fields\n    # and r._asdict(), not just attribute access. The parent also reconstructs\n    # readings via type(reading)(*values), so the constructor must tolerate\n    # the full positional field list. Normal\n    # degraded paths use the per-function namedtuple fallbacks below; this\n    # class only backstops a fallback that itself raised.\n    _fields = (\"total\", \"available\", \"percent\", \"used\", \"free\", \"active\", \"inactive\", \"wired\")\n    total = available = used = free = active = inactive = wired = 0\n    percent = 0.0\n\n    def __init__(self, *_args, **_kwargs):\n        pass\n\n    def __getattr__(self, _name):\n        return 0\n\n    def _values(self):\n        return tuple(getattr(self, _field) for _field in self._fields)\n\n    def __getitem__(self, index):\n        return self._values()[index]\n\n    def __iter__(self):\n        return iter(self._values())\n\n    def __len__(self):\n        return len(self._fields)\n\n    def _asdict(self):\n        return dict(zip(self._fields, self._values()))\n\n\n# Per-function fallback result classes with the exact macOS field\n# orders/arities. Module-level on purpose: readings cross the\n# mozsystemmonitor collector pipe via pickle (by reference), and the parent\n# rebuilds each sample with type(reading)(*values) \u2014 so a swap fallback must\n# be 6-field sswap-shaped in every position. An svmem-shaped fallback there\n# makes the parent reject every sample, fill the pipe, block the collector\n# child in send(), and wedge mach's atexit join forever.\n_FallbackVmem = collections.namedtuple(\n    \"_FallbackVmem\",\n    (\"total\", \"available\", \"percent\", \"used\", \"free\", \"active\", \"inactive\", \"wired\"),\n)\n_FallbackSwap = collections.namedtuple(\n    \"_FallbackSwap\", (\"total\", \"used\", \"free\", \"percent\", \"sin\", \"sout\")\n)\n_FallbackCpuTimes = collections.namedtuple(\"_FallbackCpuTimes\", (\"user\", \"nice\", \"system\", \"idle\"))\n_FallbackDiskIO = collections.namedtuple(\n    \"_FallbackDiskIO\",\n    (\"read_count\", \"write_count\", \"read_bytes\", \"write_bytes\", \"read_time\", \"write_time\"),\n)\n\n_FALLBACK_CLASSES = {\n    \"virtual_memory\": _FallbackVmem,\n    \"swap_memory\": _FallbackSwap,\n    \"cpu_times\": _FallbackCpuTimes,\n    \"disk_io_counters\": _FallbackDiskIO,\n}\n\n# psutil result namedtuple per wrapped function, resolvable via getattr from\n# the platform module / _common without invoking the failing syscall.\n_PSUTIL_RESULT_CLASSES = {\n    \"virtual_memory\": \"svmem\",\n    \"swap_memory\": \"sswap\",\n    \"cpu_times\": \"scputimes\",\n    \"disk_io_counters\": \"sdiskio\",\n}\n\n\ndef _zeroed(cls):\n    return cls(*([0] * len(cls._fields)))\n\n\ndef _percpu_requested(args, kwargs, positional_index):\n    if \"percpu\" in kwargs:\n        return bool(kwargs[\"percpu\"])\n    return len(args) > positional_index and bool(args[positional_index])\n\n\ndef _degraded_result_factory(psutil, name):\n    # cpu_percent returns a plain float (or a per-CPU list) callers do\n    # arithmetic on.\n    if name == \"cpu_percent\":\n        def _cpu_percent_fallback(*args, **kwargs):\n            # cpu_percent(interval=None, percpu=False)\n            if _percpu_requested(args, kwargs, 1):\n                return []\n            return 0.0\n\n        return _cpu_percent_fallback\n    # The guard-owned class is always shape-correct for this function;\n    # psutil's own result namedtuple is still preferred when resolvable so\n    # type() captures stay identical to real readings on a flapping host.\n    _cls = _FALLBACK_CLASSES.get(name, _DegradedReading)\n    _cls_name = _PSUTIL_RESULT_CLASSES.get(name)\n    if _cls_name is not None:\n        for _mod in (getattr(psutil, \"_psplatform\", None), getattr(psutil, \"_common\", None)):\n            _real = getattr(_mod, _cls_name, None) if _mod is not None else None\n            if _real is not None and getattr(_real, \"_fields\", None):\n                _cls = _real\n                break\n    if name == \"cpu_times\":\n        def _cpu_times_fallback(*args, **kwargs):\n            # cpu_times(percpu=False); the collector child samples per-CPU.\n            if _percpu_requested(args, kwargs, 0):\n                return []\n            return _zeroed(_cls)\n\n        return _cpu_times_fallback\n\n    def _reading_fallback(*_args, **_kwargs):\n        return _zeroed(_cls)\n\n    return _reading_fallback\n\n\ndef _guard_psutil():\n    try:\n        import psutil\n    except Exception:\n        return\n\n    def _wrap(orig, fallback):\n        def wrapper(*args, **kwargs):\n            try:\n                return orig(*args, **kwargs)\n            except Exception as exc:  # noqa: BLE001\n                _fireforge_degraded_notice(exc)\n                try:\n                    return fallback(*args, **kwargs)\n                except Exception:  # noqa: BLE001\n                    return _DegradedReading()\n\n        return wrapper\n\n    for _name in (\"virtual_memory\", \"swap_memory\", \"cpu_percent\", \"cpu_times\", \"disk_io_counters\"):\n        _orig = getattr(psutil, _name, None)\n        if _orig is not None and not getattr(_orig, \"_fireforge_guarded\", False):\n            try:\n                _fallback = _degraded_result_factory(psutil, _name)\n            except Exception:  # noqa: BLE001\n                _fallback = _DegradedReading\n            _wrapped = _wrap(_orig, _fallback)\n            _wrapped._fireforge_guarded = True\n            setattr(psutil, _name, _wrapped)\n\n\n_MONITOR_METHOD_NAMES = (\n    \"start\",\n    \"stop\",\n    \"record_event\",\n    \"record_marker\",\n    \"begin_phase\",\n    \"finish_phase\",\n    \"aggregate_cpu_percent\",\n    \"aggregate_cpu_times\",\n    \"aggregate_io\",\n    \"min_memory_available\",\n    \"as_dict\",\n)\n\n\ndef _fireforge_stop_collector(monitor):\n    # Best-effort: terminate a live collector child and drain the parent end\n    # of the pipe, so a child blocked in send() on a full pipe can never\n    # keep mach's atexit join (os.waitpid) waiting forever. Attribute names\n    # follow upstream resourcemonitor.py (self._process / self._pipe); a\n    # miss on a refactored upstream is harmless \u2014 the shape-correct\n    # fallbacks above still keep the sample stream well-formed.\n    try:\n        proc = getattr(monitor, \"_process\", None)\n        if proc is not None and getattr(proc, \"is_alive\", lambda: False)():\n            proc.terminate()\n            proc.join(1)\n    except Exception:  # noqa: BLE001\n        pass\n    try:\n        pipe = getattr(monitor, \"_pipe\", None)\n        if pipe is not None:\n            while pipe.poll(0):\n                pipe.recv()\n    except Exception:  # noqa: BLE001\n        pass\n\n\ndef _monitor_per_cpu_requested(args, kwargs):\n    # aggregate_cpu_percent/aggregate_cpu_times(start=None, end=None,\n    # phase=None, per_cpu=True) \u2014 self already stripped from args.\n    if \"per_cpu\" in kwargs:\n        return bool(kwargs[\"per_cpu\"])\n    if len(args) > 3:\n        return bool(args[3])\n    return True\n\n\ndef _monitor_degraded_result(name, args, kwargs):\n    # Degraded aggregate methods return zeroed shapes, not None, where\n    # callers subscript the result: mozbuild's log_resource_usage does\n    # usage[\"io\"].read_bytes after a successful compile, so None there fails\n    # the build with complete artifacts already on disk.\n    if name == \"aggregate_io\":\n        return _zeroed(_FallbackDiskIO)\n    if name == \"aggregate_cpu_percent\":\n        return [] if _monitor_per_cpu_requested(args, kwargs) else 0.0\n    if name == \"aggregate_cpu_times\":\n        return [] if _monitor_per_cpu_requested(args, kwargs) else _zeroed(_FallbackCpuTimes)\n    return None\n\n\ndef _patch_monitor_class(cls):\n    if cls is None or getattr(cls, \"_fireforge_guarded\", False):\n        return\n    orig_init = cls.__init__\n\n    def guarded_init(self, *args, **kwargs):\n        # Pre-populate the attributes a partially-constructed instance is\n        # later polled for, so a failing __init__ can never surface\n        # AttributeError: poll_interval.\n        self.poll_interval = kwargs.get(\"poll_interval\") or 1.0\n        self._fireforge_degraded = False\n        try:\n            orig_init(self, *args, **kwargs)\n        except Exception as exc:  # noqa: BLE001\n            self._fireforge_degraded = True\n            _fireforge_degraded_notice(exc)\n        if _fireforge_host_degraded[0] and not self._fireforge_degraded:\n            # Host already degraded once: keep the monitor inert so the\n            # collector child never spawns on a flapping host.\n            self._fireforge_degraded = True\n        if self._fireforge_degraded:\n            _fireforge_stop_collector(self)\n\n    cls.__init__ = guarded_init\n\n    def _wrap_method(name, orig):\n        def wrapper(self, *args, **kwargs):\n            if (\n                name == \"start\"\n                and _fireforge_host_degraded[0]\n                and not getattr(self, \"_fireforge_degraded\", False)\n            ):\n                self._fireforge_degraded = True\n                _fireforge_stop_collector(self)\n            if getattr(self, \"_fireforge_degraded\", False):\n                if name == \"stop\":\n                    _fireforge_stop_collector(self)\n                return _monitor_degraded_result(name, args, kwargs)\n            try:\n                return orig(self, *args, **kwargs)\n            except Exception as exc:  # noqa: BLE001\n                self._fireforge_degraded = True\n                _fireforge_degraded_notice(exc)\n                # A raising stop (or any degraded transition) must still\n                # take the collector child down, or the parent's atexit\n                # join hangs on a child blocked writing to a full pipe.\n                _fireforge_stop_collector(self)\n                return _monitor_degraded_result(name, args, kwargs)\n\n        return wrapper\n\n    def _wrap_unbound(name, func):\n        # Upstream declares record_event/record_marker as @staticmethods (and\n        # may declare others as @classmethods). Those take no receiver, so\n        # they cannot use the per-instance degraded flag and must not have one\n        # threaded in \u2014 see the descriptor dispatch below.\n        def wrapper(*args, **kwargs):\n            if _fireforge_host_degraded[0]:\n                return _monitor_degraded_result(name, args, kwargs)\n            try:\n                return func(*args, **kwargs)\n            except Exception as exc:  # noqa: BLE001\n                _fireforge_degraded_notice(exc)\n                return _monitor_degraded_result(name, args, kwargs)\n\n        return wrapper\n\n    for _name in _MONITOR_METHOD_NAMES:\n        # getattr_static returns the raw class attribute, so a staticmethod\n        # is still a staticmethod object here. Plain getattr would hand back\n        # the underlying function, and re-setting THAT on the class rebinds\n        # it as an instance method: the receiver is then passed through as an\n        # extra leading positional and every call raises\n        # \"takes N positional arguments but N+1 were given\". Re-apply the\n        # descriptor the attribute actually had.\n        try:\n            _raw = inspect.getattr_static(cls, _name)\n        except AttributeError:\n            continue\n        if isinstance(_raw, staticmethod):\n            setattr(cls, _name, staticmethod(_wrap_unbound(_name, _raw.__func__)))\n            continue\n        if isinstance(_raw, classmethod):\n            setattr(cls, _name, classmethod(_wrap_unbound(_name, _raw.__func__)))\n            continue\n        _orig = getattr(cls, _name, None)\n        if _orig is not None:\n            setattr(cls, _name, _wrap_method(_name, _orig))\n    cls._fireforge_guarded = True\n\n\ndef _patch_build_monitor_class(cls):\n    # mozbuild's BuildMonitor is not a SystemResourceMonitor; only\n    # log_resource_usage needs guarding \u2014 end-of-build resource reporting\n    # must never fail a build whose artifacts are complete. No __init__\n    # replacement, no degraded-instance gating.\n    if cls is None or getattr(cls, \"_fireforge_guarded\", False):\n        return\n    _orig = getattr(cls, \"log_resource_usage\", None)\n    if _orig is not None:\n        def _guarded_log_resource_usage(self, *args, **kwargs):\n            try:\n                return _orig(self, *args, **kwargs)\n            except Exception as exc:  # noqa: BLE001\n                _fireforge_degraded_notice(exc)\n                return None\n\n        cls.log_resource_usage = _guarded_log_resource_usage\n    cls._fireforge_guarded = True\n\n\n_MONITOR_CLASS_PATCHES = (\n    (\"mozsystemmonitor.resourcemonitor\", \"SystemResourceMonitor\", _patch_monitor_class),\n    (\"mozbuild.resources\", \"SystemResourceMonitor\", _patch_monitor_class),\n    (\"mozbuild.controller.building\", \"BuildMonitor\", _patch_build_monitor_class),\n)\n\n\ndef _patch_loaded_monitor_modules():\n    for _mod_name, _cls_name, _patcher in _MONITOR_CLASS_PATCHES:\n        _mod = sys.modules.get(_mod_name)\n        if _mod is not None:\n            try:\n                _patcher(getattr(_mod, _cls_name, None))\n            except Exception:  # noqa: BLE001\n                pass\n\n\ndef _install_import_hook():\n    _orig_import = builtins.__import__\n    if getattr(_orig_import, \"_fireforge_guarded\", False):\n        return\n\n    def _guarding_import(name, *args, **kwargs):\n        _module = _orig_import(name, *args, **kwargs)\n        try:\n            _patch_loaded_monitor_modules()\n        except Exception:  # noqa: BLE001\n            pass\n        return _module\n\n    _guarding_import._fireforge_guarded = True\n    builtins.__import__ = _guarding_import\n\n\ntry:\n    _guard_psutil()\n    _patch_loaded_monitor_modules()\n    _install_import_hook()\nexcept Exception:  # noqa: BLE001\n    pass\n";
-/** 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[];
-}
-/**
- * Refuses a shim directory that is not a private directory of the current
- * user. `lstat`, not `stat`: a symlink planted at the path would otherwise
- * be followed and the check would describe its target. On Windows only the
- * "is a real directory" half applies. There is no POSIX owner or mode bit
- * to read, and the per-user name is the isolation.
- *
- * @param dir - Shim directory that {@link ensureSitecustomizeFallback} created
- * @throws BuildError when the directory is a symlink/file, owned by another
- *   uid, or group/world-writable
- */
-export declare function assertPrivateShimDir(dir: string): Promise<void>;
-/**
- * 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.
- */
-export declare function installMachResourceGuard(engineDir: string): Promise<MachResourceGuardInstallation>;