@hominis/fireforge 0.48.0 → 0.49.0

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

@@ -71,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 inspect\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    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";
+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 {
     /**

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

@@ -70,6 +70,7 @@ import { BuildError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, writeText } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
+import { PROFILE_MERGE_PYTHON } from './test-profile-files.js';
 /**
  * Prefix of the per-user directory (under the OS temp dir) holding the
  * PYTHONPATH fallback. The uid (or, on Windows, the username) is appended:
@@ -99,6 +100,7 @@ import collections
 import inspect
 import sys
 import warnings
+${PROFILE_MERGE_PYTHON}
 
 # Any psutil degradation observed in this process. Once set, monitors are
 # kept inert (start never spawns the collector child) — on a flapping host a

package/dist/src/core/marionette-port.d.ts

@@ -38,6 +38,8 @@ export interface RunningBundleProcess {
      * exactly the wrong attribution for a peer session's long-lived browser.
      */
     elapsedSeconds: number;
+    parentPid?: number;
+    owner?: string;
 }
 /**
  * Pure parser kept exported so platform output handling is

package/dist/src/core/marionette-port.js

@@ -30,6 +30,8 @@ import { toError } from '../utils/errors.js';
 import { getPlatform } from '../utils/platform.js';
 import { exec } from '../utils/process.js';
 import { formatPsDuration, parsePsDuration } from '../utils/ps-duration.js';
+import { waitForPreflight } from './preflight-wait.js';
+import { isOrphanedHarness, isStillOrphanedProcess, readProcessOwner } from './process-owner.js';
 /** Default Marionette control port set by `-marionette`. */
 export const DEFAULT_MARIONETTE_PORT = 2828;
 /** Basenames of browser binaries that ship a Marionette listener. */
@@ -98,7 +100,9 @@ export function parseProcessList(stdout, launchableBinary) {
         const commandLine = Number.isNaN(elapsedSeconds)
             ? `${maybeElapsed} ${match[3] ?? ''}`.trim()
             : (match[3] ?? '');
-        if (!commandLine.includes(launchableBinary))
+        if (!(commandLine === launchableBinary ||
+            commandLine.startsWith(launchableBinary + ' ') ||
+            commandLine.startsWith('"' + launchableBinary + '" ')))
             continue;
         matches.push({ pid, commandLine, elapsedSeconds });
     }
@@ -118,40 +122,24 @@ export async function ensureLaunchableBrowserNotRunning(launchableBinary, option
     const holder = parent ?? processes[0];
     if (!holder)
         return;
-    if (options.killStaleBrowser) {
+    const ownership = await readProcessOwner(holder.pid);
+    if (ownership)
+        Object.assign(holder, ownership);
+    const orphan = isOrphanedHarness(holder.commandLine, holder.parentPid);
+    if (options.killStaleBrowser && orphan) {
+        if (!(await isStillOrphanedProcess(holder.pid, holder.commandLine))) {
+            throw new PreflightRefusalError(`Browser PID ${holder.pid} changed identity or ownership; re-run the preflight before requesting cleanup.`, 'browser-busy');
+        }
         try {
-            if (process.platform === 'win32') {
-                await exec('powershell.exe', [
-                    '-NoProfile',
-                    '-NonInteractive',
-                    '-Command',
-                    `Stop-Process -Id ${holder.pid} -Force`,
-                ]);
-            }
-            else {
-                process.kill(holder.pid, 'SIGTERM');
-            }
+            process.kill(holder.pid, 'SIGTERM');
+            await waitForPreflight(() => ensureLaunchableBrowserNotRunning(launchableBinary), 2);
             return;
         }
         catch (error) {
             throw new PreflightRefusalError(`A browser from this objdir is still running (PID ${holder.pid}), but FireForge could not terminate it: ${toError(error).message}`, 'stale-browser-kill-failed');
         }
     }
-    throw new PreflightRefusalError(describeRunningBundleRefusal(holder), 'stale-browser');
-}
-/**
- * True when the process was launched by a test harness, i.e. its command
- * line carries `-marionette` (the control channel every `fireforge test`
- * browser is started with) or a harness `-profile`.
- *
- * This is the distinction the refusal turns on. The objdir-bundle probe
- * matches any process running this project's binary, which on a shared
- * checkout includes a peer session's live browser and a developer's own
- * interactive one. Only a marionette-driven browser is safely
- * attributable to an interrupted run.
- */
-function isHarnessDrivenBrowser(commandLine) {
-    return /\s-marionette(?:\s|$)/.test(commandLine) || /\s-profile(?:\s|=)/.test(commandLine);
+    throw new PreflightRefusalError(describeRunningBundleRefusal(holder), orphan ? 'stale-browser' : 'browser-busy');
 }
 /**
  * Builds the refusal for a running objdir browser.
@@ -177,9 +165,10 @@ export function describeRunningBundleRefusal(holder) {
         : `kill ${holder.pid}  # or "kill -9 ${holder.pid}" if it doesn't exit`;
     const elapsed = formatPsDuration(holder.elapsedSeconds);
     const age = elapsed !== undefined ? ` running for ${elapsed}` : '';
-    const harnessDriven = isHarnessDrivenBrowser(holder.commandLine);
+    const harnessDriven = isOrphanedHarness(holder.commandLine, holder.parentPid);
     const evidence = `A browser from this project's objdir is already running (PID ${holder.pid}${age}).\n` +
-        `  command: ${holder.commandLine}\n`;
+        `  command: ${holder.commandLine}\n` +
+        `  owner: parent ${holder.parentPid ?? 'unknown'} (${holder.owner ?? 'unavailable'})\n`;
     if (harnessDriven) {
         return (evidence +
             '  This one carries harness arguments (-marionette/-profile), so it is very likely an orphan ' +
@@ -187,11 +176,8 @@ export function describeRunningBundleRefusal(holder) {
             `  Stop it with "${killHint}", or retry with "--kill-stale-marionette".`);
     }
     return (evidence +
-        '  This one carries NO harness arguments (-marionette/-profile), so it is not a test browser — ' +
-        "it is more likely a developer's own window, or another session sharing this checkout.\n" +
-        '  "--kill-stale-marionette" is deliberately NOT suggested here: FireForge cannot tell an orphan ' +
-        "from someone else's live browser. Confirm the owner (start time above, and the command line), " +
-        `then stop it yourself with "${killHint}" if it is in fact yours.`);
+        '  This browser is busy; its ownership does not prove a harness orphan. ' +
+        'FireForge will not terminate it. Use --wait-browser [seconds] to queue behind the owner.');
 }
 /**
  * Returns `true` when the holder's command basename or command-line
@@ -347,14 +333,14 @@ export async function assertMarionettePortAvailable(port = DEFAULT_MARIONETTE_PO
         return;
     const holder = probe.holder;
     if (isBrowserMarionettePortHolder(holder, options.binaryName)) {
-        const killHint = process.platform === 'win32'
-            ? `Stop-Process -Id ${holder.pid} -Force`
-            : `kill ${holder.pid}  # or "kill -9 ${holder.pid}" if it doesn't exit`;
+        const owner = await readProcessOwner(holder.pid);
+        const orphan = isOrphanedHarness(holder.commandLine, owner?.parentPid);
         throw new PreflightRefusalError(`Marionette port ${port} is already in use by ${holder.command} (PID ${holder.pid}). ` +
-            `This is usually a browser left running by a previously interrupted "fireforge test" run. ` +
-            `Kill it with "${killHint}", then retry. ` +
-            `(If you expected ${holder.command} to be running on ${port}, stop it manually or pass ` +
-            `"--marionette-port <port>" to launch mach test on a different port.)`, 'marionette-port-busy');
+            `Owner: parent ${owner?.parentPid ?? 'unknown'} (${owner?.owner ?? 'unavailable'}). ` +
+            (orphan
+                ? 'The harness parent exited; retry with --kill-stale-marionette to reap this orphan. '
+                : 'A live peer may own it; FireForge will not suggest terminating it. ') +
+            'Use --wait-port [seconds] to queue, or --marionette-port <port> to use a different port.', 'marionette-port-busy');
     }
     // Non-browser holder: mach test will still fail to bind, but the
     // cause is not a stale FireForge-launched browser. Flag it
@@ -377,23 +363,22 @@ export async function ensureMarionettePortAvailable(port = DEFAULT_MARIONETTE_PO
         await assertMarionettePortAvailable(port, options);
         return;
     }
+    const owner = await readProcessOwner(holder.pid);
+    if (!isOrphanedHarness(holder.commandLine, owner?.parentPid)) {
+        await assertMarionettePortAvailable(port, options);
+        return;
+    }
+    if (!(await isStillOrphanedProcess(holder.pid, holder.commandLine))) {
+        throw new PreflightRefusalError(`Marionette listener PID ${holder.pid} changed identity or ownership; re-run the preflight before requesting cleanup.`, 'marionette-port-busy');
+    }
     try {
-        if (process.platform === 'win32') {
-            await exec('powershell.exe', [
-                '-NoProfile',
-                '-NonInteractive',
-                '-Command',
-                `Stop-Process -Id ${holder.pid} -Force`,
-            ]);
-        }
-        else {
-            process.kill(holder.pid, 'SIGTERM');
-        }
+        process.kill(holder.pid, 'SIGTERM');
     }
     catch (error) {
         throw new PreflightRefusalError(`Marionette port ${port} is held by stale browser ${holder.command} (PID ${holder.pid}), ` +
             `but FireForge could not terminate it: ${toError(error).message}`, 'stale-browser-kill-failed');
     }
+    await waitForPreflight(() => assertMarionettePortAvailable(port, options), 2);
 }
 /**
  * Extracts a `--marionette-port=N` (or `--marionette-port N`) argument from

package/dist/src/core/mochitest-server-port.d.ts

@@ -78,4 +78,4 @@ export declare function ensureMochitestServerPortAvailable(port: number | undefi
  * @param holder - The listener found on it
  * @param holderClass - Whose harness `server.js` it is, if it is one at all
  */
-export declare function describeMochitestServerRefusal(port: number, holder: MarionettePortHolder, holderClass: MochitestServerHolderClass): string;
+export declare function describeMochitestServerRefusal(port: number, holder: MarionettePortHolder, holderClass: MochitestServerHolderClass, parentPid?: number): string;

package/dist/src/core/mochitest-server-port.js

@@ -22,10 +22,11 @@
  * the missing half, and it reuses {@link probeMarionettePort}, which is
  * port-generic, rather than growing a second probe.
  */
-import { GeneralError } from '../errors/base.js';
+import { PreflightRefusalError } from '../errors/base.js';
 import { isExplicitAbsolutePath, isPathInsideRoot } from '../utils/paths.js';
-import { exec } from '../utils/process.js';
 import { probeMarionettePort } from './marionette-port.js';
+import { waitForPreflight } from './preflight-wait.js';
+import { isStillOrphanedProcess, readProcessOwner } from './process-owner.js';
 /** Default port the mochitest harness binds its httpd to. */
 export const DEFAULT_MOCHITEST_SERVER_PORT = 8888;
 /**
@@ -109,19 +110,17 @@ export async function ensureMochitestServerPortAvailable(port = DEFAULT_MOCHITES
         return;
     const holder = probe.holder;
     const holderClass = classifyMochitestServerHolder(holder, options.engineDir);
-    if (holderClass === 'this-checkout' && options.killStaleServer === true) {
+    const owner = await readProcessOwner(holder.pid);
+    if (holderClass === 'this-checkout' &&
+        owner?.parentPid === 1 &&
+        options.killStaleServer === true &&
+        (await isStillOrphanedProcess(holder.pid, holder.commandLine))) {
         try {
-            if (process.platform === 'win32') {
-                await exec('powershell.exe', [
-                    '-NoProfile',
-                    '-NonInteractive',
-                    '-Command',
-                    `Stop-Process -Id ${holder.pid} -Force`,
-                ]);
-            }
-            else {
-                process.kill(holder.pid, 'SIGTERM');
-            }
+            process.kill(holder.pid, 'SIGTERM');
+            await waitForPreflight(async () => {
+                if ((await probeMarionettePort(port)).inUse)
+                    throw new PreflightRefusalError(`Mochitest port ${port} remains busy after orphan cleanup; wait for the holder to exit.`, 'mochitest-port-busy');
+            }, 2);
             return;
         }
         catch {
@@ -130,7 +129,8 @@ export async function ensureMochitestServerPortAvailable(port = DEFAULT_MOCHITES
             // pretending the port is now free.
         }
     }
-    throw new GeneralError(describeMochitestServerRefusal(port, holder, holderClass));
+    throw new PreflightRefusalError(describeMochitestServerRefusal(port, holder, holderClass, owner?.parentPid) +
+        `\n  Parent: ${owner?.parentPid ?? 'unknown'} (${owner?.owner ?? 'unavailable'}). Use --wait-port [seconds] to queue.`, 'mochitest-port-busy');
 }
 /**
  * Builds the operator-facing refusal. Exported for direct unit testing.
@@ -139,7 +139,7 @@ export async function ensureMochitestServerPortAvailable(port = DEFAULT_MOCHITES
  * @param holder - The listener found on it
  * @param holderClass - Whose harness `server.js` it is, if it is one at all
  */
-export function describeMochitestServerRefusal(port, holder, holderClass) {
+export function describeMochitestServerRefusal(port, holder, holderClass, parentPid) {
     const killHint = process.platform === 'win32'
         ? `Stop-Process -Id ${holder.pid} -Force`
         : `kill -9 ${holder.pid}`;
@@ -150,9 +150,12 @@ export function describeMochitestServerRefusal(port, holder, holderClass) {
         'manifest — the run would stall before TEST_START and die on the no-output timeout with ' +
         '"Ran 0 checks".\n';
     if (holderClass === 'this-checkout') {
+        if (parentPid !== 1)
+            return (evidence +
+                '  This checkout has a live or unattributed harness server. Wait for its owner to finish; --wait-port [seconds] queues behind it.');
         return (evidence +
             "  This is the mochitest harness's own server.js from THIS checkout's objdir, so it is " +
-            'debris from an interrupted run. Retry with "--kill-stale-marionette" to have FireForge ' +
+            'possibly debris from an interrupted run. For a dead parent, retry with "--kill-stale-marionette" to have FireForge ' +
             `stop it, or stop it yourself with "${killHint}" (a wedged httpd can ignore SIGTERM).`);
     }
     if (holderClass === 'foreign-checkout') {

package/dist/src/core/objdir-maintenance.d.ts

@@ -0,0 +1,10 @@
+/** Refuses an objdir that writes through a directory alias into a different checkout. */
+export declare function assertLocalObjdir(engineDir: string, objDir: string): Promise<void>;
+/** Repairs copied links and dependency metadata BEFORE configure can consume config.track. */
+export declare function relocateObjdirProducts(engineDir: string, objDir: string, oldRoot: string): Promise<void>;
+/** Finds a link still consulting the previous source tree after relocation/configure. */
+export declare function findStaleObjdirLink(engineDir: string, objDir: string, oldRoot: string): Promise<string | undefined>;
+/** Prunes only dangling _tests symlinks; never descends through a symlink. */
+export declare function pruneDanglingTestLinks(engineDir: string, objDir: string): Promise<number>;
+/** Names a partial-config group whose entire persisted value set was nulled. */
+export declare function assertHealthyPartialConfig(engineDir: string, objDir: string): Promise<void>;

package/dist/src/core/objdir-maintenance.js

@@ -0,0 +1,151 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { lstat, readdir, readFile, readlink, realpath, rename, rm, symlink, } from 'node:fs/promises';
+import { dirname, join, resolve, sep } from 'node:path';
+import { GeneralError } from '../errors/base.js';
+import { getNodeErrorCode } from '../utils/errors.js';
+import { writeText } from '../utils/fs.js';
+/** Visits objdir entries without following directory symlinks into another tree. */
+async function walk(dir, visit) {
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory())
+            await walk(path, visit);
+        else
+            await visit(path, entry.isSymbolicLink());
+    }
+}
+/** Refuses an objdir that writes through a directory alias into a different checkout. */
+export async function assertLocalObjdir(engineDir, objDir) {
+    if (!/^[^/\\:]+$/.test(objDir) || objDir === '.' || objDir === '..') {
+        throw new GeneralError(`Objdir ${objDir} must be a local directory name.`);
+    }
+    const expected = resolve(engineDir, objDir);
+    if ((await realpath(expected)) !== resolve(await realpath(engineDir), objDir) ||
+        !(await lstat(expected)).isDirectory()) {
+        throw new GeneralError(`Objdir ${expected} resolves outside its local directory. Refusing to configure or rewrite it.`);
+    }
+}
+function replacePrefix(value, oldRoot, newRoot) {
+    return value === oldRoot || value.startsWith(oldRoot + sep)
+        ? newRoot + value.slice(oldRoot.length)
+        : value;
+}
+function isDependencyMetadata(path) {
+    return (/\.(?:pp|d)$/.test(path) ||
+        /[/\\]faster[/\\]/.test(path) ||
+        /[/\\]config\.statusd[/\\].*[/\\]config\.track$/.test(path) ||
+        /[/\\]\.fingerprint[/\\].*\.json$/.test(path));
+}
+/** Repairs copied links and dependency metadata BEFORE configure can consume config.track. */
+export async function relocateObjdirProducts(engineDir, objDir, oldRoot) {
+    await assertLocalObjdir(engineDir, objDir);
+    const root = resolve(engineDir, objDir);
+    const newRoot = resolve(engineDir);
+    const canonicalRoot = await realpath(root);
+    // Configure writes these groups. Even a local objdir can contain a copied
+    // directory alias into a peer, so validate each parent before touching it.
+    for (const directory of ['config.statusd', 'config.statusd/substs', 'config.statusd/defines']) {
+        const path = join(root, directory);
+        try {
+            if (!(await lstat(path)).isDirectory() ||
+                (await realpath(path)) !== join(canonicalRoot, directory))
+                throw new GeneralError(`Partial-config directory ${path} is aliased. Refusing relocation before configure.`);
+        }
+        catch (error) {
+            if (getNodeErrorCode(error) !== 'ENOENT')
+                throw error;
+        }
+    }
+    await walk(root, async (path, link) => {
+        // Remove tracking symlinks too, without following their write targets.
+        if (/[/\\]config\.statusd[/\\].*[/\\]config\.track$/.test(path)) {
+            await rm(path);
+            return;
+        }
+        if (link) {
+            const target = await readlink(path);
+            const absolute = resolve(dirname(path), target);
+            const relocated = replacePrefix(absolute, oldRoot, newRoot);
+            if (relocated !== absolute) {
+                const temp = `${path}.relocate-${process.pid}`;
+                await symlink(relocated, temp);
+                try {
+                    await rename(temp, path);
+                }
+                finally {
+                    await rm(temp, { force: true });
+                }
+            }
+        }
+        else if (isDependencyMetadata(path)) {
+            const content = await readFile(path, 'utf8');
+            const rewritten = content.replaceAll(oldRoot + sep, newRoot + sep);
+            if (content !== rewritten)
+                await writeText(path, rewritten);
+        }
+    });
+}
+/** Finds a link still consulting the previous source tree after relocation/configure. */
+export async function findStaleObjdirLink(engineDir, objDir, oldRoot) {
+    let violation;
+    await walk(resolve(engineDir, objDir), async (path, link) => {
+        if (!link || violation)
+            return;
+        const target = resolve(dirname(path), await readlink(path));
+        const canonical = await realpath(path).catch(() => target);
+        if ([target, canonical].some((value) => value === oldRoot || value.startsWith(oldRoot + sep))) {
+            violation = `${path} still links to the previous engine ${oldRoot}`;
+        }
+    });
+    return violation;
+}
+/** Prunes only dangling _tests symlinks; never descends through a symlink. */
+export async function pruneDanglingTestLinks(engineDir, objDir) {
+    let removed = 0;
+    const root = join(engineDir, objDir, '_tests');
+    try {
+        if (!(await lstat(root)).isDirectory())
+            return 0;
+        await assertLocalObjdir(engineDir, objDir);
+        await walk(root, async (path, link) => {
+            if (!link)
+                return;
+            try {
+                await realpath(path);
+            }
+            catch (error) {
+                if (getNodeErrorCode(error) !== 'ENOENT')
+                    throw error;
+                await rm(path);
+                removed++;
+            }
+        });
+    }
+    catch (error) {
+        if (getNodeErrorCode(error) !== 'ENOENT')
+            throw error;
+    }
+    return removed;
+}
+/** Names a partial-config group whose entire persisted value set was nulled. */
+export async function assertHealthyPartialConfig(engineDir, objDir) {
+    for (const group of ['substs', 'defines']) {
+        const dir = join(engineDir, objDir, 'config.statusd', group);
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch (error) {
+            if (getNodeErrorCode(error) === 'ENOENT')
+                continue;
+            throw error;
+        }
+        const files = entries.filter((entry) => entry.isFile() && entry.name !== 'config.track');
+        if (files.length === 0)
+            continue;
+        const values = await Promise.all(files.map((entry) => readFile(join(dir, entry.name), 'utf8')));
+        if (values.every((value) => value.trim() === 'null')) {
+            throw new GeneralError(`All ${files.length} partial-config ${group} values in ${dir} are null. Repair with "cd engine && python3 ./mach configure", then retry the full build.`);
+        }
+    }
+}

package/dist/src/core/patch-lint-checkjs.js

@@ -30,6 +30,7 @@ import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { normalizePathSlashes } from '../utils/paths.js';
+import { withGeckoDomTypes } from './gecko-dom-types.js';
 import { withSharedSourceFiles } from './patch-lint-checkjs-cache.js';
 import { collectUnmanagedCompanions, retargetUnmanagedCompanionHints, } from './patch-lint-unmanaged-companion.js';
 import { composeShimSource, SHIM_FILENAME, SUPPRESSED_DIAGNOSTIC_CODES, TEST_HARNESS_SHIM, UNDEFINED_IDENTIFIER_CODES, UNDEFINED_IDENTIFIER_HINT, } from './typecheck-shim.js';
@@ -295,7 +296,7 @@ export async function runCheckJsGrouped(input) {
     // Custom compiler host: reads patch-owned files from disk, returns
     // the shim for the shim path, and returns empty content for
     // anything else to avoid reading the full Firefox tree.
-    const defaultHost = ts.createCompilerHost(options);
+    const defaultHost = withGeckoDomTypes(ts, ts.createCompilerHost(options));
     // Files pulled in via a reviewed `paths` mapping: outside the owned set
     // but read from disk so the resolver's targets actually type-check.
     const pathsResolved = new Set();

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

@@ -0,0 +1,2 @@
+/** Waits for a busy browser or port without changing or terminating its owner. */
+export declare function waitForPreflight(action: () => Promise<void>, seconds?: number): Promise<void>;

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

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { PreflightRefusalError } from '../errors/base.js';
+import { info } from '../utils/logger.js';
+import { sleep } from '../utils/sleep.js';
+/** Waits for a busy browser or port without changing or terminating its owner. */
+export async function waitForPreflight(action, seconds) {
+    const deadline = Date.now() + (seconds ?? 0) * 1000;
+    let announced = false;
+    for (;;) {
+        try {
+            await action();
+            return;
+        }
+        catch (error) {
+            if (!(error instanceof PreflightRefusalError) || Date.now() >= deadline)
+                throw error;
+            if (!announced) {
+                info(`Waiting up to ${seconds} seconds: ${error.message}`);
+                announced = true;
+            }
+            await sleep(Math.min(500, Math.max(1, deadline - Date.now())));
+        }
+    }
+}

package/dist/src/core/process-owner.d.ts

@@ -0,0 +1,9 @@
+/** Parent evidence; an unreadable parent is never proof of an orphan. */
+export declare function readProcessOwner(pid: number): Promise<{
+    parentPid: number;
+    owner: string;
+} | undefined>;
+/** Harness arguments alone never prove abandonment: require a dead parent too. */
+export declare function isOrphanedHarness(commandLine: string, parentPid?: number): boolean;
+/** Refreshes the exact command and orphan evidence immediately before signaling. */
+export declare function isStillOrphanedProcess(pid: number, commandLine: string): Promise<boolean>;

package/dist/src/core/process-owner.js

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { exec } from '../utils/process.js';
+/** Parent evidence; an unreadable parent is never proof of an orphan. */
+export async function readProcessOwner(pid) {
+    if (process.platform === 'win32')
+        return undefined;
+    try {
+        const result = await exec('ps', ['-p', String(pid), '-o', 'ppid='], { timeout: 5000 });
+        const parentPid = Number(result.stdout.trim());
+        if (result.exitCode !== 0 || !Number.isSafeInteger(parentPid) || parentPid < 1)
+            return undefined;
+        if (parentPid === 1)
+            return { parentPid, owner: 'init/launchd (parent exited)' };
+        const parent = await exec('ps', ['-p', String(parentPid), '-o', 'args='], { timeout: 5000 });
+        if (parent.exitCode !== 0 || !parent.stdout.trim())
+            return undefined;
+        return { parentPid, owner: parent.stdout.trim() };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Harness arguments alone never prove abandonment: require a dead parent too. */
+export function isOrphanedHarness(commandLine, parentPid) {
+    return (parentPid === 1 &&
+        (/\s-marionette(?:\s|$)/.test(commandLine) ||
+            /\s-profile(?:\s|=)[^\n]*(?:fireforge-|mochitest|rust_mozprofile)/.test(commandLine)));
+}
+/** Refreshes the exact command and orphan evidence immediately before signaling. */
+export async function isStillOrphanedProcess(pid, commandLine) {
+    // Windows ownership has no verified implementation; never infer it from
+    // command-line appearance or enable a destructive PowerShell fallback.
+    if (process.platform === 'win32')
+        return false;
+    try {
+        const result = await exec('ps', ['-p', String(pid), '-o', 'ppid=,args='], { timeout: 5000 });
+        const match = /^\s*(\d+)\s+(.+?)\s*$/.exec(result.stdout);
+        return result.exitCode === 0 && match?.[1] === '1' && match[2] === commandLine;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/core/test-harness-crash.d.ts

@@ -25,7 +25,7 @@ export type { HarnessCrashSignature } from './test-harness-signature.js';
 import type { HarnessCrashSignature } from './test-harness-signature.js';
 export { headedDisplayAsleepVerdictNote, headedNoOutputTimeoutHint } from './test-stall-triage.js';
 /** How a completed harness run should be interpreted. */
-export type HarnessRunClassification = 'tests-ran-ok' | 'test-failures' | 'harness-crash' | 'no-tests';
+export type HarnessRunClassification = 'tests-ran-ok' | 'test-failures' | 'harness-crash' | 'harness-arguments' | 'no-tests';
 /** Numeric counts parsed from the harness's embedded result summary. */
 export interface HarnessSummaryCounts {
     /** Total checks the suite ran (`Ran N checks`), when the summary prints one. */