@hominis/fireforge 0.43.1 → 0.44.1

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

@@ -3,79 +3,64 @@
  *
  * 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 (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.
+ * `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.
  *
- * 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 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 itself covers the whole crash family:
+ * 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. Downstream report (0.34.0 cycle):
- *    mozsystemmonitor subscripts (`_build_meta` does
- *    `psutil.virtual_memory()[0]`) and iterates/unpacks the reading, so the
- *    zeroed fallback is a full namedtuple duck type; `cpu_percent` degrades
- *    to `0.0` because callers do arithmetic on it. Field report (0.34.1,
- *    flapping host): the fallback must ALSO be per-function arity-correct
- *    and reconstructible — mozsystemmonitor's parent captures reading types
- *    at `__init__` (`self._swap_type = type(psutil.swap_memory())`) and
- *    rebuilds each collector sample via `self._swap_type(*swap_mem)`, and an
- *    svmem-shaped (8-field) fallback in the swap (6-field `sswap`) position
- *    made the parent reject every sample ("failed to read the received
- *    data") and BREAK its drain loop, so the pipe filled, the collector
- *    child blocked in `send()` and never read the terminate sentinel, and
- *    mach hung forever in its atexit `waitpid`. Each wrapped function now
- *    degrades to a zeroed instance of psutil's own result namedtuple where
- *    resolvable, else a module-level guard-owned namedtuple with the exact
- *    macOS field order/arity for THAT function (module-level so readings
- *    pickle by reference across the collector pipe); `_DegradedReading`
- *    remains only as a documented last resort and now tolerates
- *    `type(reading)(*values)` reconstruction;
+ *    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
+ *    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` no longer dies on `usage["io"].read_bytes` after
- *    a fully successful compile);
+ *    (`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 can never wedge mach's
+ *    drains the pipe, so a malformed sample stream cannot wedge mach's
  *    shutdown even if a future shape mismatch slips through;
- *  - additionally 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.
- *
- * Why the 0.34.1 report saw `_DegradedReading` in the collector child even
- * though the psutil result classes resolve when probed directly: two guard
- * copies can load (PYTHONPATH `sitecustomize` in the bootstrap phase plus
- * the in-venv `.pth`), each with its own factory/classes, and flapping at
- * guard-import time can perturb `psutil._psplatform` attribute resolution
- * in the spawn child specifically. The fix is robust to either mechanism:
- * the guard-owned fallback classes never depend on psutil internals
- * resolving and are arity-correct in every position.
+ *  - 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`
@@ -86,7 +71,7 @@
  * 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 sys\nimport warnings\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. Field report (0.34.1): the\n    # parent also reconstructs readings via type(reading)(*values), so the\n    # constructor must tolerate 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 (field report 0.34.1: an\n# svmem-shaped fallback in the swap position made the parent reject every\n# sample, fill the pipe, block the collector child in send(), and wedge\n# 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 (field report\n    # 0.34.1: 'NoneType' object has no attribute 'read_bytes' failed the\n    # build with complete artifacts).\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    for _name in _MONITOR_METHOD_NAMES:\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";
+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 sys\nimport warnings\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    for _name in _MONITOR_METHOD_NAMES:\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 {
     /**

package/dist/src/core/mach-resource-shim.js

@@ -4,79 +4,64 @@
  *
  * 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 (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.
+ * `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.
  *
- * 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 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 itself covers the whole crash family:
+ * 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. Downstream report (0.34.0 cycle):
- *    mozsystemmonitor subscripts (`_build_meta` does
- *    `psutil.virtual_memory()[0]`) and iterates/unpacks the reading, so the
- *    zeroed fallback is a full namedtuple duck type; `cpu_percent` degrades
- *    to `0.0` because callers do arithmetic on it. Field report (0.34.1,
- *    flapping host): the fallback must ALSO be per-function arity-correct
- *    and reconstructible — mozsystemmonitor's parent captures reading types
- *    at `__init__` (`self._swap_type = type(psutil.swap_memory())`) and
- *    rebuilds each collector sample via `self._swap_type(*swap_mem)`, and an
- *    svmem-shaped (8-field) fallback in the swap (6-field `sswap`) position
- *    made the parent reject every sample ("failed to read the received
- *    data") and BREAK its drain loop, so the pipe filled, the collector
- *    child blocked in `send()` and never read the terminate sentinel, and
- *    mach hung forever in its atexit `waitpid`. Each wrapped function now
- *    degrades to a zeroed instance of psutil's own result namedtuple where
- *    resolvable, else a module-level guard-owned namedtuple with the exact
- *    macOS field order/arity for THAT function (module-level so readings
- *    pickle by reference across the collector pipe); `_DegradedReading`
- *    remains only as a documented last resort and now tolerates
- *    `type(reading)(*values)` reconstruction;
+ *    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
+ *    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` no longer dies on `usage["io"].read_bytes` after
- *    a fully successful compile);
+ *    (`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 can never wedge mach's
+ *    drains the pipe, so a malformed sample stream cannot wedge mach's
  *    shutdown even if a future shape mismatch slips through;
- *  - additionally 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.
- *
- * Why the 0.34.1 report saw `_DegradedReading` in the collector child even
- * though the psutil result classes resolve when probed directly: two guard
- * copies can load (PYTHONPATH `sitecustomize` in the bootstrap phase plus
- * the in-venv `.pth`), each with its own factory/classes, and flapping at
- * guard-import time can perturb `psutil._psplatform` attribute resolution
- * in the spawn child specifically. The fix is robust to either mechanism:
- * the guard-owned fallback classes never depend on psutil internals
- * resolving and are arity-correct in every position.
+ *  - 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.
  */
 import { readdir } from 'node:fs/promises';
 import { homedir, tmpdir } from 'node:os';
@@ -125,9 +110,9 @@ class _DegradedReading(object):
     # Last-resort duck type of psutil's namedtuple results (svmem field
     # order): mozsystemmonitor subscripts, iterates, and unpacks readings,
     # so the degraded fallback must survive r[0], list(r), len(r), r._fields
-    # and r._asdict(), not just attribute access. Field report (0.34.1): the
-    # parent also reconstructs readings via type(reading)(*values), so the
-    # constructor must tolerate the full positional field list. Normal
+    # and r._asdict(), not just attribute access. The parent also reconstructs
+    # readings via type(reading)(*values), so the constructor must tolerate
+    # the full positional field list. Normal
     # degraded paths use the per-function namedtuple fallbacks below; this
     # class only backstops a fallback that itself raised.
     _fields = ("total", "available", "percent", "used", "free", "active", "inactive", "wired")
@@ -160,10 +145,9 @@ class _DegradedReading(object):
 # orders/arities. Module-level on purpose: readings cross the
 # mozsystemmonitor collector pipe via pickle (by reference), and the parent
 # rebuilds each sample with type(reading)(*values) — so a swap fallback must
-# be 6-field sswap-shaped in every position (field report 0.34.1: an
-# svmem-shaped fallback in the swap position made the parent reject every
-# sample, fill the pipe, block the collector child in send(), and wedge
-# mach's atexit join forever).
+# be 6-field sswap-shaped in every position. An svmem-shaped fallback there
+# makes the parent reject every sample, fill the pipe, block the collector
+# child in send(), and wedge mach's atexit join forever.
 _FallbackVmem = collections.namedtuple(
     "_FallbackVmem",
     ("total", "available", "percent", "used", "free", "active", "inactive", "wired"),
@@ -323,9 +307,8 @@ def _monitor_per_cpu_requested(args, kwargs):
 def _monitor_degraded_result(name, args, kwargs):
     # Degraded aggregate methods return zeroed shapes, not None, where
     # callers subscript the result: mozbuild's log_resource_usage does
-    # usage["io"].read_bytes after a successful compile (field report
-    # 0.34.1: 'NoneType' object has no attribute 'read_bytes' failed the
-    # build with complete artifacts).
+    # usage["io"].read_bytes after a successful compile, so None there fails
+    # the build with complete artifacts already on disk.
     if name == "aggregate_io":
         return _zeroed(_FallbackDiskIO)
     if name == "aggregate_cpu_percent":

package/dist/src/core/mach.d.ts

@@ -86,21 +86,20 @@ export interface ProtectedMachBuildResult extends MachCommandResult {
 }
 /**
  * The single protected path every FireForge mach build dispatch routes
- * through (field report: `build --ui` and the pre-test `--build` step died
- * on the resource-monitor crash family while plain `build` survived,
- * because only some entries were protected and retry budgets differed):
+ * through — `build`, `build --ui`, and the pre-test `--build` step all use
+ * it, so no entry point is left unprotected with a different retry budget:
  *
  *  1. installs the resource-monitor degrade guard IN the mach virtualenvs
- *     (plus the PYTHONPATH fallback) — re-installed before every attempt,
- *     so a venv materialized by a crashed first attempt is guarded on the
- *     next one instead of every retry dying on the same wedged state;
+ *     (plus the PYTHONPATH fallback) — re-installed before every attempt, so
+ *     a venv materialized by a crashed first attempt is guarded on the next
+ *     one instead of every retry dying on the same wedged state;
  *  2. spawns a fresh mach process per attempt;
  *  3. retries ONLY the recognized harness-crash family (resource monitor /
  *     psutil startup tracebacks) up to the uniform budget — an ordinary
  *     compile error is never retried.
  *
- * The protected path never runs `mach configure`, never clobbers, and
- * never widens the requested build kind — a `faster` dispatch retries as
+ * The protected path never runs `mach configure`, never clobbers, and never
+ * widens the requested build kind — a `faster` dispatch retries as
  * `mach build faster`, so it cannot invalidate more of the objdir than the
  * command the operator asked for.
  */
@@ -129,32 +128,27 @@ export declare function build(engineDir: string, jobs?: number): Promise<Protect
  */
 export declare function buildUI(engineDir: string): Promise<ProtectedMachBuildResult>;
 /**
- * Runs an operation while holding a sidecar build lock keyed on the
- * project root. Concurrent `fireforge build` / `fireforge build --ui`
- * invocations against the same tree serialise instead of racing through
- * the mach obj-dir.
+ * Runs an operation while holding a sidecar build lock keyed on the project
+ * root. Concurrent `fireforge build` / `fireforge build --ui` invocations
+ * against the same tree serialise instead of racing through the mach
+ * obj-dir.
  *
- * Motivating case (2026-04-21 eval): a `fireforge build --ui` run
- * kicked off while a full `fireforge build` was still in flight against
- * the same engine tree accepted the command and handed off to `mach
- * build faster`, which failed almost immediately with `No rule to make
- * target 'XUL'`. The real problem is that the first build had not yet
- * materialised the full backend; the operator was left staring at a
- * low-level make error with no link to the actual cause (a concurrent
- * build in flight). The lock intercepts the second invocation before
- * it touches mach, and the refusal message names the PID currently
- * holding the lock so the operator can decide whether to wait or
- * investigate a hung process.
+ * Without it, a `build --ui` started while a full `build` is still in flight
+ * hands off to `mach build faster` and fails almost immediately with `No
+ * rule to make target 'XUL'` — the real problem being that the first build
+ * has not yet materialised the full backend, with nothing in the low-level
+ * make error pointing at the concurrent run. The lock intercepts the second
+ * invocation before it touches mach, and the refusal names the PID holding
+ * the lock so the operator can decide whether to wait or investigate.
  *
  * Stale-lock recovery: the lock stores the owner PID; a crashed build
- * (SIGINT, SIGTERM, or a kernel kill) leaves the lock dir behind but
- * not the owning process, and `withFileLock` removes the lock on the
- * next attempt when `process.kill(pid, 0)` shows the owner is gone.
+ * (SIGINT, SIGTERM, or a kernel kill) leaves the lock dir behind but not the
+ * owning process, and `withFileLock` removes the lock on the next attempt
+ * when `process.kill(pid, 0)` shows the owner is gone.
  *
- * The project-root variant is the right granularity: a single machine
- * may have several FireForge projects side by side, and nothing says
- * they cannot build in parallel. The lock serialises *within* one
- * project, not across unrelated ones.
+ * The project-root variant is the right granularity: a single machine may
+ * have several FireForge projects side by side and nothing says they cannot
+ * build in parallel. The lock serialises *within* one project.
  *
  * Returns whatever the inner operation returns.
  */
@@ -216,18 +210,17 @@ export declare function machPackageCapture(engineDir: string): Promise<MachComma
 export declare function watch(engineDir: string): Promise<number>;
 /**
  * Runs mach watch while preserving stdin and capturing emitted output.
+ *
+ * `env` is threaded through so the caller can prepend the resolved watchman
+ * directory to PATH in a way mach inherits: `fireforge watch` can locate
+ * `watchman` via `which`, but the mach subprocess spawns with the parent's
+ * PATH only — on macOS that typically omits `/opt/homebrew/bin`, so
+ * `mach watch` fails at the `watch-project` subscription step.
+ *
  * @param engineDir - Path to the engine directory
- * @param options - Optional environment overrides merged into the mach subprocess env
+ * @param options - Optional environment overrides merged into the mach
+ *   subprocess env
  * @returns Captured output and exit code
- *
- * 2026-04-24 eval Finding 12: the pre-0.18.1 shape accepted no options
- * and so never forwarded the detected watchman path into the mach
- * subprocess env. `fireforge watch` could locate `watchman` via PATH
- * (the probe's `which` succeeded) but the mach subprocess spawned with
- * the parent's PATH only — on macOS that typically omits
- * `/opt/homebrew/bin`, so `mach watch` failed at the `watch-project`
- * subscription step. Accepting `env` here lets the caller prepend the
- * resolved watchman directory to PATH in a way mach inherits.
  */
 export declare function watchWithOutput(engineDir: string, options?: {
     env?: Record<string, string>;
@@ -243,6 +236,9 @@ export declare function test(engineDir: string, testPaths?: string[], args?: str
 /**
  * Runs mach test while capturing streamed output for better diagnostics.
  *
+ * @param engineDir - Absolute path to the engine checkout
+ * @param testPaths - Test paths to pass to `mach test`; empty runs the default set
+ * @param args - Extra `mach test` arguments appended after the paths
  * @param env - Optional extra environment variables for the mach process
  *   (merged over `process.env` by the exec layer). Used by
  *   `fireforge test --perf-samples` to publish the artifact-path contract.
@@ -253,7 +249,7 @@ export declare function testWithOutput(engineDir: string, testPaths?: string[],
  * capturing output. Unlike the generic `mach test`, the suite-specific
  * commands degrade a broken mozlog resource monitor to a warning instead of
  * crashing at startup, so `fireforge test` dispatches single-suite runs here
- * to stay resilient to the host psutil failure (field report E1).
+ * to stay resilient to the host psutil failure.
  *
  * Signature mirrors {@link testWithOutput} so the two are interchangeable in
  * the dispatch path.