hermes-agent/hermes_cli/desktop_build_lock.py

"""Cross-process serialization for the mutable Desktop build preflight."""

from __future__ import annotations

import hashlib
import os
from pathlib import Path
from typing import IO


class DesktopBuildLock:
    """Advisory lock held while npm installs and packages Hermes Desktop.

    ``node_modules`` and ``apps/desktop/release`` are checkout-scoped even
    when two commands use different Hermes profiles.  The lock therefore
    lives under the profile-common Hermes root and is keyed by the resolved
    checkout path.  Keeping it out of the checkout preserves ``--skip-build``
    launches from read-only/prebuilt source trees.  The open handle owns the
    lock, so the OS releases it automatically if a builder crashes.

    The build also writes the checkout an update writes, so the lock first takes the
    checkout lock every updater holds (``update_lock``; review C5), then its own: one lock
    order (checkout, then desktop build) for a direct ``hermes desktop`` build and for the
    update's build (which already holds the checkout lock and only joins it again), and no
    gap in which an updater could take the checkout while npm still writes.  Holding the
    checkout lock also puts the build in the update custody (``update_custody``): its
    descendants hold the checkout until they exit.
    """

    def __init__(self, project_root: Path) -> None:
        from hermes_constants import get_default_hermes_root

        resolved = os.path.normcase(str(project_root.resolve(strict=False)))
        checkout_key = hashlib.sha256(resolved.encode("utf-8")).hexdigest()[:24]
        self.path = get_default_hermes_root() / "locks" / f"desktop-build-{checkout_key}.lock"
        self.project_root = project_root
        self._handle: IO[str] | None = None
        self._checkout = None

    def acquire(self, *, wait: bool = False) -> bool:
        """Acquire the lock; queue behind the current holder when ``wait``.

        Returns ``False`` only when another process owns the lock and ``wait``
        is unset.  Filesystem errors propagate so callers fail explicitly
        instead of silently falling back to the corrupting concurrent
        behavior.
        """
        if self._handle is not None:
            return True
        if not self._acquire_checkout(wait=wait):
            return False
        try:
            acquired = self._acquire_build_lock(wait=wait)
        except BaseException:
            self._release_checkout()
            raise
        if not acquired:
            self._release_checkout()
        return acquired

    def _acquire_checkout(self, *, wait: bool) -> bool:
        """Take (or, inside an update, join) the checkout lock before the build lock (C5)."""
        import time

        from hermes_cli import update_lock

        held, wanted = update_lock._HELD, update_lock.checkout_lock_path(self.project_root)
        if held is not None and held["path"] != str(wanted):
            # This process holds a checkout lock under another path. Another spelling of this
            # checkout's lock file (a symlinked install root) is this update's own custody: build
            # inside it, since a second acquire would wait on its own lock. Any other checkout's
            # lock proves nothing about this one (review Q2), and a process records one hold only.
            if not (wanted.exists() and os.path.samefile(held["path"], wanted)):
                raise OSError(f"this process holds the update lock of another checkout ({held['path']}), "
                              f"so it cannot also lock {self.project_root} for its build")
            return True
        lock = update_lock.UpdateLock(install_root=self.project_root, checkout_first=False)
        announced = False
        while not lock.acquire_checkout(self.project_root):
            if lock.holder is not None and lock.holder.reason:
                raise OSError(lock.holder.reason)  # never build unserialized; the caller says so
            if not wait:
                return False
            if not announced:
                print("→ Waiting for a running Hermes update to release this checkout...")
                announced = True
            time.sleep(1.0)
        self._checkout = lock
        return True

    def _release_checkout(self) -> None:
        lock, self._checkout = self._checkout, None
        if lock is not None:
            lock.release()

    def _acquire_build_lock(self, *, wait: bool) -> bool:
        from gateway.status import _try_acquire_file_lock

        self.path.parent.mkdir(parents=True, exist_ok=True)
        handle = self.path.open("a+", encoding="utf-8")
        if _try_acquire_file_lock(handle):
            self._handle = handle
            return True
        if not wait:
            handle.close()
            return False

        # Blocking mode queues behind the holder; say so instead of appearing
        # to hang with no output (the update path would rather wait for the
        # in-flight build it depends on than fail the update).
        print("→ Waiting for another Hermes desktop dependency install or build to finish...")
        print(f"  Lock: {self.path}")
        from gateway.status import _release_file_lock

        try:
            import fcntl

            fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
        except ImportError:
            # Windows has no fcntl; gateway.status's non-blocking try below is
            # the best-effort serialization there (msvcrt.locking), so poll it.
            import time

            while True:
                if _try_acquire_file_lock(handle):
                    self._handle = handle
                    return True
                _release_file_lock(handle)
                time.sleep(1.0)
        self._handle = handle
        return True

    def release(self) -> None:
        """Release the lock when held.  Safe to call more than once."""
        handle = self._handle
        if handle is None:
            return
        self._handle = None

        try:
            from gateway.status import _release_file_lock

            _release_file_lock(handle)
        finally:
            try:
                handle.close()
            finally:
                self._release_checkout()  # the narrower lock first: the order is checkout, build

    def __enter__(self) -> DesktopBuildLock:
        if not self.acquire():
            raise RuntimeError("desktop build lock is already held")
        return self

    def __exit__(self, *_exc: object) -> None:
        self.release()