Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

50.4 KB
Raw Blame
"""App-private agent backend installation for the self-contained desktop app."""

from __future__ import annotations

import json
import logging
import math
import os
import platform
import re
import shutil
import signal
import subprocess
import tempfile
import threading
import time
import uuid
from collections.abc import Callable, Mapping
from dataclasses import dataclass
from pathlib import Path, PurePosixPath
from typing import Any

import psutil

from config import paths
from config.atomic_io import write_atomic
from vibe.cli_health import cli_version
from core.process_isolation import (
    KILL_SIGNAL,
    PROCESS_IDENTITY_ENV,
    PersistedProcessIdentity,
    capture_spawned_process_identity,
    fingerprint_process_marker,
    is_valid_worker_fingerprint,
    isolated_subprocess_kwargs,
    new_process_identity_marker,
    process_group_exists,
    processes_carrying_marker,
    process_identity_from_payload,
    reap_marked_processes,
    reap_orphaned_process_tree,
    serialize_process_identity,
    signal_process_tree,
)
from storage.lock import MigrationFileLock, MigrationLockTimeout
from vibe.desktop_runtime import (
    DESKTOP_INSTALLER_OWNER_ENV,
    DESKTOP_INSTALLER_ROLE,
    DESKTOP_ROLE_ENV,
    DESKTOP_RUNTIME_ID_ENV,
    desktop_runtime_id,
    private_desktop_backends_root,
    private_desktop_node_bin,
    private_desktop_npm_cli,
)


logger = logging.getLogger(__name__)

CURRENT_DESCRIPTOR_SCHEMA_VERSION = 1
MAX_DESCRIPTOR_BYTES = 16 * 1024
MAX_INSTALL_OUTPUT_CHARS = 8192
NPM_REGISTRY = "https://registry.npmjs.org/"
DESKTOP_BACKEND_LOCK_TIMEOUT_SECONDS = 30.0
# Removal runs once the Runtime has stopped, when no install should be left to
# wait for.
DESKTOP_BACKEND_REMOVAL_LOCK_TIMEOUT_SECONDS = 5.0
DESKTOP_BACKEND_INSTALL_TIMEOUT_SECONDS = 300.0
DESKTOP_BACKEND_PROBE_TIMEOUT_SECONDS = 15.0
DESKTOP_BACKEND_PROCESS_DRAIN_TIMEOUT_SECONDS = 10.0
# Per phase of stopping an installer tree. Two phases fit inside the grace a
# managed stop gives the owning UI before it escalates to SIGKILL (5 s).
DESKTOP_BACKEND_TERMINATE_TIMEOUT_SECONDS = 1.5
DESKTOP_BACKEND_INSTALL_LABEL = "desktop backend install"
INSTALL_RECORD_SCHEMA_VERSION = 1


@dataclass(frozen=True)
class DesktopBackendSpec:
    package: str
    package_path: tuple[str, ...]


@dataclass(frozen=True)
class DesktopBackendToolchain:
    runtime_root: Path
    backends_root: Path
    node: Path
    npm_cli: Path


@dataclass(frozen=True)
class DesktopBackendInstallResult:
    backend: str
    package: str
    version: str
    path: str
    output: str | None


class DesktopBackendError(RuntimeError):
    def __init__(self, message: str, *, code: str, output: str | None = None):
        super().__init__(message)
        self.code = code
        self.output = output


BACKEND_SPECS: dict[str, DesktopBackendSpec] = {
    "codex": DesktopBackendSpec(
        package="@openai/codex",
        package_path=("@openai", "codex"),
    ),
    "claude": DesktopBackendSpec(
        package="@anthropic-ai/claude-code",
        package_path=("@anthropic-ai", "claude-code"),
    ),
    "opencode": DesktopBackendSpec(
        package="opencode-ai",
        package_path=("opencode-ai",),
    ),
}


ActivationCallback = Callable[[str], None]


def desktop_backend_toolchain(
    base_env: Mapping[str, str] | None = None,
) -> DesktopBackendToolchain | None:
    """Return the complete launcher-supplied private install contract."""

    from vibe.desktop_runtime import private_desktop_runtime_root

    runtime_root = private_desktop_runtime_root(base_env)
    backends_root = private_desktop_backends_root(base_env)
    node = private_desktop_node_bin(base_env)
    npm_cli = private_desktop_npm_cli(base_env)
    if runtime_root is None or backends_root is None or node is None or npm_cli is None:
        return None
    return DesktopBackendToolchain(
        runtime_root=runtime_root,
        backends_root=backends_root,
        node=node,
        npm_cli=npm_cli,
    )


def resolve_published_desktop_backend(
    backend: str,
    base_env: Mapping[str, str] | None = None,
) -> str | None:
    """Resolve one verified executable from its bounded ``current.json``."""

    if backend not in BACKEND_SPECS:
        return None
    root = private_desktop_backends_root(base_env)
    if root is None:
        return None
    backend_root = root / backend
    descriptor_path = backend_root / "current.json"
    try:
        if descriptor_path.is_symlink() or not descriptor_path.is_file():
            return None
        if descriptor_path.stat().st_size > MAX_DESCRIPTOR_BYTES:
            return None
        payload = json.loads(descriptor_path.read_text(encoding="utf-8"))
    except (OSError, UnicodeError, json.JSONDecodeError):
        return None
    if not isinstance(payload, dict):
        return None

    spec = BACKEND_SPECS[backend]
    if (
        payload.get("schema_version") != CURRENT_DESCRIPTOR_SCHEMA_VERSION
        or payload.get("backend") != backend
        or payload.get("package") != spec.package
        or not isinstance(payload.get("version"), str)
    ):
        return None

    executable = _descriptor_relative_path(payload.get("executable"))
    if executable is None or not executable.parts or executable.parts[0] != backend:
        return None
    candidate = root / executable
    if not _verified_direct_executable(candidate, root=backend_root, require_native=True):
        return None
    try:
        _backend_runtime_path_entries(backend, candidate, root=backend_root)
    except DesktopBackendError:
        return None
    return str(candidate.resolve(strict=True))


def is_desktop_backend_path(
    path: str | os.PathLike[str] | None,
    base_env: Mapping[str, str] | None = None,
) -> bool:
    """Whether *path* is contained by the mutable private backend root."""

    if not path:
        return False
    root = private_desktop_backends_root(base_env)
    if root is None:
        return False
    candidate = Path(path).expanduser()
    if not candidate.is_absolute():
        return False
    try:
        candidate.resolve(strict=False).relative_to(root)
    except (OSError, ValueError):
        return False
    return True


def desktop_backend_subprocess_environment(
    backend: str,
    executable: str | os.PathLike[str],
    base_env: Mapping[str, str] | None = None,
) -> dict[str, str] | None:
    """Return the launch environment required by an app-private backend.

    The desktop shell starts before a backend may be installed, so mutable
    backend support directories cannot be added to the Runtime's process-wide
    ``PATH``. Derive them from the exact configured executable at the backend
    process boundary instead.
    """

    source = os.environ if base_env is None else base_env
    root = private_desktop_backends_root(source)
    if (
        backend not in BACKEND_SPECS
        or root is None
        or not is_desktop_backend_path(executable, source)
    ):
        return None
    backend_root = root / backend
    candidate = Path(executable).expanduser()
    if not _verified_direct_executable(candidate, root=backend_root, require_native=True):
        raise DesktopBackendError(
            f"Published {backend} executable failed validation.",
            code="invalid_executable",
        )
    runtime_paths = _backend_runtime_path_entries(backend, candidate, root=backend_root)
    environment = dict(source)
    if runtime_paths:
        _prepend_path_entries(environment, runtime_paths)
    return environment


def install_desktop_backend(
    backend: str,
    *,
    base_env: Mapping[str, str] | None = None,
    activate: ActivationCallback | None = None,
    timeout_seconds: float = DESKTOP_BACKEND_INSTALL_TIMEOUT_SECONDS,
) -> DesktopBackendInstallResult:
    """Install or update one backend and atomically publish its descriptor.

    ``activate`` lets the config owner persist the final executable while the
    cross-process install lock is still held. The descriptor is published first
    so configuration can never point at an unpublished release.
    """

    spec = BACKEND_SPECS.get(backend)
    if spec is None:
        raise DesktopBackendError(
            f"Unknown desktop backend: {backend}",
            code="unknown_backend",
        )
    toolchain = desktop_backend_toolchain(base_env)
    if toolchain is None:
        raise DesktopBackendError(
            "The desktop backend installer is unavailable.",
            code="desktop_toolchain_unavailable",
        )

    backend_root = toolchain.backends_root / backend
    _prepare_backend_root(toolchain.backends_root, backend_root)
    lock = _claim_backend_root(backend_root, timeout_seconds=DESKTOP_BACKEND_LOCK_TIMEOUT_SECONDS)

    staging = backend_root / f".staging-{uuid.uuid4().hex}"
    # The lock says "no installer is working in this root". An installer tree
    # that could not be shown gone may still be writing into staging, so both
    # the lock and staging stay as they are until this process exits.
    installer_undrained = False
    try:
        staging.mkdir(mode=0o700)
        user_config = staging / "npm-user.conf"
        global_config = staging / "npm-global.conf"
        user_config.write_text("", encoding="utf-8")
        global_config.write_text("", encoding="utf-8")
        command = [
            str(toolchain.node),
            str(toolchain.npm_cli),
            "install",
            "--prefix",
            str(staging),
            "--no-save",
            "--package-lock=false",
            "--omit=dev",
            "--ignore-scripts",
            "--no-audit",
            "--no-fund",
            f"--registry={NPM_REGISTRY}",
            spec.package,
        ]
        logger.info("Installing desktop backend package %s", spec.package)
        completed = _run_command(
            command,
            cwd=staging,
            env=_npm_environment(toolchain, staging, user_config, global_config, base_env),
            timeout_seconds=timeout_seconds,
        )
        output = _bounded_output(completed.stdout, completed.stderr)
        if completed.returncode != 0:
            raise DesktopBackendError(
                f"Desktop backend install failed (exit code {completed.returncode})",
                code="npm_install_failed",
                output=output,
            )
        _remove_internal_directory(staging / ".npm-cache", staging)
        user_config.unlink(missing_ok=True)
        global_config.unlink(missing_ok=True)

        package_dir = staging / "node_modules" / Path(*spec.package_path)
        version = _installed_package_version(package_dir, spec.package)
        executable = _installed_native_executable(backend, spec, staging, package_dir)
        runtime_paths = _backend_runtime_path_entries(backend, executable, root=staging)
        _verify_backend_executable(
            backend,
            executable,
            root=staging,
            env=_backend_command_environment(
                toolchain,
                base_env,
                runtime_paths=runtime_paths,
            ),
        )

        releases_root = backend_root / "releases"
        releases_root.mkdir(mode=0o700, exist_ok=True)
        release_root = releases_root / uuid.uuid4().hex
        os.replace(staging, release_root)
        published_executable = release_root / executable.relative_to(staging)

        relative_executable = published_executable.relative_to(toolchain.backends_root).as_posix()
        descriptor = {
            "schema_version": CURRENT_DESCRIPTOR_SCHEMA_VERSION,
            "backend": backend,
            "package": spec.package,
            "version": version,
            "executable": relative_executable,
        }
        descriptor_path = backend_root / "current.json"
        previous_descriptor = _read_descriptor_bytes(descriptor_path)
        try:
            # The descriptor is the publication boundary. Configuration may
            # point at a release only after this atomic replacement succeeds,
            # so a crash can never activate an unpublished executable.
            _write_current_descriptor(descriptor_path, descriptor)
            if activate is not None:
                activate(str(published_executable))
        except Exception:
            _restore_descriptor_bytes(descriptor_path, previous_descriptor)
            # Once staging has been renamed, the outer cleanup can no longer
            # reach it. Remove the release only after restoring the descriptor;
            # if restoration itself fails, retaining the files is safer than a
            # descriptor that points at a deleted executable.
            _remove_staging_directory(release_root, backend_root)
            raise

        return DesktopBackendInstallResult(
            backend=backend,
            package=spec.package,
            version=version,
            path=str(published_executable),
            output=output,
        )
    except DesktopBackendError as exc:
        installer_undrained = exc.code == "install_drain_failed"
        raise
    except Exception as exc:
        raise DesktopBackendError(
            f"Desktop backend install failed: {exc}",
            code="desktop_install_failed",
        ) from exc
    finally:
        if installer_undrained:
            logger.error(
                "Keeping %s held: a %s process tree could not be shown to have exited",
                lock.lock_path,
                DESKTOP_BACKEND_INSTALL_LABEL,
            )
        else:
            # The record goes only with its staging, and both before the lock.
            if _remove_staging_directory(staging, backend_root):
                _forget_installer_record(_installer_record_path(staging))
            lock.release()


def _prepare_backend_root(root: Path, backend_root: Path) -> None:
    root.mkdir(mode=0o700, parents=True, exist_ok=True)
    if root.is_symlink() or not root.is_dir():
        raise DesktopBackendError("Invalid desktop backend root.", code="invalid_backend_root")
    backend_root.mkdir(mode=0o700, exist_ok=True)
    if backend_root.is_symlink() or not backend_root.is_dir():
        raise DesktopBackendError("Invalid desktop backend directory.", code="invalid_backend_root")
    if os.name != "nt":
        root.chmod(0o700)
        backend_root.chmod(0o700)


def _npm_environment(
    toolchain: DesktopBackendToolchain,
    staging: Path,
    user_config: Path,
    global_config: Path,
    base_env: Mapping[str, str] | None,
) -> dict[str, str]:
    source = os.environ if base_env is None else base_env
    env = _safe_process_environment(source)
    path_entries = [entry for entry in env.get("PATH", "").split(os.pathsep) if entry]
    node_dir = str(toolchain.node.parent)
    env["PATH"] = os.pathsep.join([node_dir, *(entry for entry in path_entries if entry != node_dir)])
    env.update(
        {
            "NPM_CONFIG_PREFIX": str(staging),
            "NPM_CONFIG_CACHE": str(staging / ".npm-cache"),
            "NPM_CONFIG_USERCONFIG": str(user_config),
            "NPM_CONFIG_GLOBALCONFIG": str(global_config),
            "NPM_CONFIG_REGISTRY": NPM_REGISTRY,
            "NPM_CONFIG_AUDIT": "false",
            "NPM_CONFIG_FUND": "false",
            "NPM_CONFIG_UPDATE_NOTIFIER": "false",
        }
    )
    return env


def _backend_command_environment(
    toolchain: DesktopBackendToolchain,
    base_env: Mapping[str, str] | None,
    *,
    runtime_paths: tuple[Path, ...] = (),
) -> dict[str, str]:
    source = os.environ if base_env is None else base_env
    env = _safe_process_environment(source)
    entries = [entry for entry in env.get("PATH", "").split(os.pathsep) if entry]
    node_dir = str(toolchain.node.parent)
    env["PATH"] = os.pathsep.join([node_dir, *(entry for entry in entries if entry != node_dir)])
    _prepend_path_entries(env, runtime_paths)
    return env


def _prepend_path_entries(environment: dict[str, str], paths: tuple[Path, ...]) -> None:
    entries = [entry for entry in environment.get("PATH", "").split(os.pathsep) if entry]
    prefixes = [str(path) for path in paths]
    environment["PATH"] = os.pathsep.join(
        [*prefixes, *(entry for entry in entries if entry not in prefixes)]
    )


def _safe_process_environment(source: Mapping[str, str]) -> dict[str, str]:
    allowed = {
        "APPDATA",
        "COMSPEC",
        "HOME",
        "HTTP_PROXY",
        "HTTPS_PROXY",
        "LANG",
        "LOCALAPPDATA",
        "NODE_EXTRA_CA_CERTS",
        "NO_PROXY",
        "PATH",
        "PATHEXT",
        "SSL_CERT_DIR",
        "SSL_CERT_FILE",
        "SYSTEMROOT",
        "TEMP",
        "TMP",
        "TMPDIR",
        "USERPROFILE",
        "WINDIR",
        "http_proxy",
        "https_proxy",
        "no_proxy",
    }
    return {
        key: value
        for key, value in source.items()
        if key in allowed or key.startswith("LC_")
    }


def _run_command(
    command: list[str],
    *,
    cwd: Path,
    env: Mapping[str, str],
    timeout_seconds: float,
) -> subprocess.CompletedProcess[str]:
    owned = _spawn_owned_installer(command, cwd=cwd, env=env)
    process = owned.process
    try:
        try:
            stdout, stderr = process.communicate(timeout=timeout_seconds)
        except subprocess.TimeoutExpired as exc:
            signal_process_tree(process, KILL_SIGNAL, logger, DESKTOP_BACKEND_INSTALL_LABEL)
            stdout, stderr = process.communicate(
                timeout=DESKTOP_BACKEND_PROCESS_DRAIN_TIMEOUT_SECONDS,
            )
            raise DesktopBackendError(
                "Desktop backend install timed out.",
                code="install_timeout",
                output=_bounded_output(stdout, stderr),
            ) from exc
    finally:
        # npm exiting is not its tree exiting: anything it started is still
        # in its process group, or at least still carries the marker.
        if not _settle_owned_installer(owned):
            raise DesktopBackendError(
                "Desktop backend installer processes did not exit.",
                code="install_drain_failed",
            )
    return subprocess.CompletedProcess(command, process.returncode, stdout, stderr)


@dataclass
class _OwnedInstaller:
    """An installer tree this process started, and so must see gone."""

    process: subprocess.Popen[str]
    worker_fingerprint: str
    identity: PersistedProcessIdentity | None
    settled: bool = False


# The owner-side registry. Its lock is held across spawn and registration, so
# a drain that starts meanwhile waits and then sees the new tree too.
_OWNED_INSTALLERS: dict[str, _OwnedInstaller] = {}
_OWNED_INSTALLERS_LOCK = threading.RLock()
_INSTALLERS_CLOSED = False


_STAGING_NAME = re.compile(r"\.staging-[0-9a-f]{32}")


def _installer_records_dir() -> Path:
    return paths.get_runtime_dir() / "desktop-backend-installs"


def _installer_record_path(staging: Path) -> Path:
    return _installer_records_dir() / f"{staging.name.removeprefix('.staging-')}.json"


def _write_installer_record(
    record_path: Path,
    *,
    worker_fingerprint: str,
    identity: PersistedProcessIdentity | None,
    staging: Path,
) -> None:
    payload = {
        "schema_version": INSTALL_RECORD_SCHEMA_VERSION,
        "worker_fingerprint": worker_fingerprint,
        "identity": None if identity is None else serialize_process_identity(identity),
        "staging": str(staging),
    }
    write_atomic(record_path, json.dumps(payload, separators=(",", ":")))


def _forget_installer_record(record_path: Path) -> None:
    try:
        record_path.unlink(missing_ok=True)
    except OSError:
        logger.warning("Could not remove %s record %s", DESKTOP_BACKEND_INSTALL_LABEL, record_path, exc_info=True)


def _spawn_owned_installer(
    command: list[str],
    *,
    cwd: Path,
    env: Mapping[str, str],
) -> _OwnedInstaller:
    # ``cwd`` is the install's staging directory. Its record names it, and goes
    # only with it: the install removes both, or a claim of the root does.
    marker = new_process_identity_marker()
    worker_fingerprint = fingerprint_process_marker(marker)
    record_path = _installer_record_path(cwd)
    child_env = dict(env)
    child_env[PROCESS_IDENTITY_ENV] = marker
    # Every member inherits these, so a process scan finds the whole tree and
    # its owner without its record: the stops and the claim decide by them.
    child_env[DESKTOP_ROLE_ENV] = DESKTOP_INSTALLER_ROLE
    child_env[DESKTOP_INSTALLER_OWNER_ENV] = _installer_owner()
    runtime_id = desktop_runtime_id()
    if runtime_id is not None:
        child_env[DESKTOP_RUNTIME_ID_ENV] = runtime_id
    with _OWNED_INSTALLERS_LOCK:
        if _INSTALLERS_CLOSED:
            raise DesktopBackendError(
                "Avibe is shutting down; the desktop backend install was not started.",
                code="install_shutting_down",
            )
        # Recorded before the spawn, so a stopper can find the tree by its
        # marker even if this process dies before it learns the pid.
        _write_installer_record(record_path, worker_fingerprint=worker_fingerprint, identity=None, staging=cwd)
        process = subprocess.Popen(
            command,
            cwd=cwd,
            env=child_env,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            text=True,
            **isolated_subprocess_kwargs(console=False),
        )
        identity = capture_spawned_process_identity(process.pid, marker)
        owned = _OwnedInstaller(process, worker_fingerprint, identity)
        _OWNED_INSTALLERS[worker_fingerprint] = owned
        if identity is not None:
            try:
                _write_installer_record(
                    record_path, worker_fingerprint=worker_fingerprint, identity=identity, staging=cwd
                )
            except OSError:
                # The marker alone still finds the tree; only the pid is lost.
                logger.warning("Could not record the %s pid=%s", DESKTOP_BACKEND_INSTALL_LABEL, process.pid, exc_info=True)
    return owned


def _stop_owned_installer_leader(process: subprocess.Popen[str]) -> bool:
    """Stop and reap the installer this process spawned, through its own handle.

    The handle is what makes this exact: ``wait`` reaps the leader, so the reap
    that follows never mistakes an unreaped zombie for a live member.
    """

    for sig in (signal.SIGTERM, KILL_SIGNAL):
        if process.poll() is not None:
            return True
        signal_process_tree(process, sig, logger, DESKTOP_BACKEND_INSTALL_LABEL)
        try:
            process.wait(timeout=DESKTOP_BACKEND_TERMINATE_TIMEOUT_SECONDS)
        except subprocess.TimeoutExpired:
            continue
        return True
    return process.poll() is not None


def _await_installer_group_exit(identity: PersistedProcessIdentity | None) -> None:
    """Give members the group signal reached their phase to exit and be reaped.

    Until its reaper collects it, an exited member still occupies the group
    and no longer shows its marker, which would leave the reap unable to
    confirm the group is ours or gone.
    """

    if identity is None or os.name == "nt":
        return
    deadline = time.monotonic() + DESKTOP_BACKEND_TERMINATE_TIMEOUT_SECONDS
    while process_group_exists(identity.pid, logger, DESKTOP_BACKEND_INSTALL_LABEL):
        if time.monotonic() >= deadline:
            return
        time.sleep(0.05)


def _reap_installer_tree(
    worker_fingerprint: str,
    identity: PersistedProcessIdentity | None,
) -> bool:
    """Stop whatever is left of an installer tree; True once it is shown gone."""

    outcomes = []
    if identity is not None:
        outcomes.append(
            reap_orphaned_process_tree(logger, DESKTOP_BACKEND_INSTALL_LABEL, expected_identity=identity)
        )
    # The marker is the authority: it also finds members that left the group.
    outcomes.append(
        reap_marked_processes(
            logger,
            DESKTOP_BACKEND_INSTALL_LABEL,
            worker_fingerprint=worker_fingerprint,
            terminate_timeout=DESKTOP_BACKEND_TERMINATE_TIMEOUT_SECONDS,
        )
    )
    return "unconfirmed" not in outcomes


def _settle_owned_installer(owned: _OwnedInstaller) -> bool:
    with _OWNED_INSTALLERS_LOCK:
        if owned.settled:
            return True
        try:
            gone = _stop_owned_installer_leader(owned.process)
            if gone:
                _await_installer_group_exit(owned.identity)
                gone = _reap_installer_tree(owned.worker_fingerprint, owned.identity)
        except Exception:
            logger.exception("Unexpected error stopping the %s tree", DESKTOP_BACKEND_INSTALL_LABEL)
            gone = False
        if not gone:
            logger.error(
                "Could not show the %s tree pid=%s exited; keeping its record",
                DESKTOP_BACKEND_INSTALL_LABEL,
                owned.process.pid,
            )
            return False
        owned.settled = True
        _OWNED_INSTALLERS.pop(owned.worker_fingerprint, None)
        return True


def drain_desktop_backend_installs() -> bool:
    """Stop every installer tree this process started, before it exits.

    For the owning process's shutdown: after this call it starts no new
    installer. Returns False when a tree could not be shown gone. Its durable
    record stays either way until the install removes its staging; one left
    behind is cleared by the next claim of its backend root.
    """

    global _INSTALLERS_CLOSED
    with _OWNED_INSTALLERS_LOCK:
        _INSTALLERS_CLOSED = True
        owned = list(_OWNED_INSTALLERS.values())
    drained = True
    for installer in owned:
        drained = _settle_owned_installer(installer) and drained
    return drained


@dataclass(frozen=True)
class _InstallerRecord:
    path: Path
    worker_fingerprint: str
    identity: PersistedProcessIdentity | None
    staging: Path

    @property
    def backend_root(self) -> Path:
        return self.staging.parent


def _recorded_staging(value: Any) -> Path | None:
    """The staging directory a record names, if an install could have made it.

    Only ``<backends root>/<backend>/.staging-<hex>`` qualifies, so removing a
    recorded staging directory can never reach a release, a descriptor or
    anything outside a backend root.
    """

    if not isinstance(value, str) or os.path.normpath(value) != value:
        return None
    staging = Path(value)
    if not staging.is_absolute() or not _STAGING_NAME.fullmatch(staging.name):
        return None
    return staging if staging.parent.name in BACKEND_SPECS else None


def _read_installer_record(record_path: Path) -> _InstallerRecord | None:
    """The record at ``record_path``, or ``None`` when what it holds is invalid.

    Raises ``OSError`` when it cannot be read: such a record is unknown, not
    invalid, and must not be discarded.
    """

    text = record_path.read_bytes()
    try:
        payload = json.loads(text.decode("utf-8"))
    except (UnicodeError, json.JSONDecodeError):
        return None
    if not isinstance(payload, dict) or payload.get("schema_version") != INSTALL_RECORD_SCHEMA_VERSION:
        return None
    worker_fingerprint = payload.get("worker_fingerprint")
    raw_identity = payload.get("identity")
    staging = _recorded_staging(payload.get("staging"))
    if not is_valid_worker_fingerprint(worker_fingerprint) or staging is None:
        return None
    identity = None
    if raw_identity is not None:
        identity = process_identity_from_payload(
            raw_identity,
            raw_identity.get("pid") if isinstance(raw_identity, dict) else None,
        )
        if identity is None or identity.worker_fingerprint != worker_fingerprint:
            return None
    return _InstallerRecord(record_path, worker_fingerprint, identity, staging)


def _installer_records() -> list[_InstallerRecord]:
    """Every valid installer record, for a claim to clear the staging it names.

    Raises ``OSError`` when the directory or a record in it cannot be read:
    the listing is then unknown and nothing is discarded. A record proven
    invalid is discarded only once every record has been read.
    """

    try:
        with os.scandir(_installer_records_dir()) as entries:
            record_paths = sorted(Path(entry.path) for entry in entries if entry.name.endswith(".json"))
    except FileNotFoundError:
        # No install has recorded anything yet.
        return []
    records: list[_InstallerRecord] = []
    invalid: list[Path] = []
    for record_path in record_paths:
        try:
            record = _read_installer_record(record_path)
        except FileNotFoundError:
            # Its install finished after the listing.
            continue
        if record is None:
            invalid.append(record_path)
        else:
            records.append(record)
    for record_path in invalid:
        # Nothing in it can identify a process, so it authorises nothing.
        logger.warning("Discarding invalid %s record %s", DESKTOP_BACKEND_INSTALL_LABEL, record_path)
        _forget_installer_record(record_path)
    return records


def _clear_abandoned_install(record: _InstallerRecord) -> bool:
    """Reap a recorded installer tree, then remove its staging and its record.

    True once the tree is shown gone. The record stays until its staging is.
    """

    try:
        gone = _reap_installer_tree(record.worker_fingerprint, record.identity)
    except Exception:
        logger.exception("Unexpected error stopping the %s recorded in %s", DESKTOP_BACKEND_INSTALL_LABEL, record.path)
        gone = False
    if not gone:
        logger.error("Could not stop the %s recorded in %s", DESKTOP_BACKEND_INSTALL_LABEL, record.path)
        return False
    if _remove_staging_directory(record.staging, record.backend_root):
        _forget_installer_record(record.path)
    return True


# The owner value an installer tree carries: this prefix, the owner's pid and
# its start token. A value without it is the ``pid:create_time`` a released
# build wrote.
_INSTALLER_OWNER_PREFIX = "v2:"


def _installer_owner() -> str:
    from vibe import runtime

    start_token = runtime.process_start_token(os.getpid())
    if start_token is None:
        raise DesktopBackendError(
            "Avibe could not identify itself as the owner of a desktop backend install.",
            code="desktop_install_failed",
        )
    return f"{_INSTALLER_OWNER_PREFIX}{os.getpid()}:{start_token}"


def _installer_owner_gone(owner: str, runtime_id: str | None) -> bool | None:
    """Whether the process named by the owner value of a ``runtime_id`` tree has exited.

    The owner is gone when its pid is not alive, and alive while that pid
    keeps its start token, which no clock adjustment moves: another token
    means the pid was reused. A released build's value carries a create time
    instead, which macOS can shift for a process that keeps running, so
    another one alone proves nothing there: that pid was reused only when the
    process now holding it is readable and is not a UI of that Runtime, as
    every owner is. ``None`` when the value is malformed, or the owner's
    identity cannot be read now.
    """

    from vibe import runtime

    if owner.startswith(_INSTALLER_OWNER_PREFIX):
        pid_text, _, start_token = owner.removeprefix(_INSTALLER_OWNER_PREFIX).partition(":")
        try:
            pid = int(pid_text)
        except ValueError:
            return None
        if pid <= 0 or not start_token:
            return None
        if not runtime.pid_alive(pid):
            return True
        current = runtime.process_start_token(pid)
        if current is None:
            return None if runtime.pid_alive(pid) else True
        return current != start_token

    pid_text, _, started_text = owner.partition(":")
    try:
        pid, started_at = int(pid_text), float(started_text)
    except ValueError:
        return None
    if pid <= 0 or not math.isfinite(started_at):
        return None
    if not runtime.pid_alive(pid):
        return True
    if runtime.process_create_time(pid) == started_at:
        return False
    is_ui = runtime.is_desktop_ui(pid, runtime_id)
    return None if is_ui is None else not is_ui


def reap_abandoned_desktop_backend_installs(runtime_id: str | None = None) -> bool:
    """Stop every installer tree of a Runtime whose owner has exited.

    ``runtime_id`` defaults to this process's. Installs run only in the UI,
    which drains its own trees as it exits; one killed first leaves its tree
    running. A process scan finds such trees by the role and Runtime id every
    member inherits, and each tree names its owner, so no record or pidfile
    decides, whichever process asks. Staging and records stay for the next
    claim of their backend root. Returns False when a tree could not be shown
    gone, or its owner could not be told alive or gone.
    """

    if runtime_id is None:
        runtime_id = desktop_runtime_id()
    abandoned: set[str] = set()
    for process in processes_carrying_marker(
        fingerprint_process_marker(DESKTOP_INSTALLER_ROLE),
        marker_env=DESKTOP_ROLE_ENV,
    ):
        try:
            env = process.environ()
        except psutil.NoSuchProcess:
            continue
        except (psutil.Error, OSError):
            logger.error("Could not inspect the %s pid=%s", DESKTOP_BACKEND_INSTALL_LABEL, process.pid, exc_info=True)
            return False
        if desktop_runtime_id(env) != runtime_id:
            continue
        marker = env.get(PROCESS_IDENTITY_ENV, "")
        if not marker or not marker.isascii():
            logger.error("The %s pid=%s carries no identity marker", DESKTOP_BACKEND_INSTALL_LABEL, process.pid)
            return False
        gone = _installer_owner_gone(env.get(DESKTOP_INSTALLER_OWNER_ENV, ""), runtime_id)
        if gone is None:
            logger.error("Could not tell whether the owner of the %s pid=%s is alive", DESKTOP_BACKEND_INSTALL_LABEL, process.pid)
            return False
        if gone:
            abandoned.add(fingerprint_process_marker(marker))
    # By its marker, which also finds members started since the scan.
    return all([_reap_installer_tree(fingerprint, None) for fingerprint in sorted(abandoned)])


def _claim_backend_root(backend_root: Path, *, timeout_seconds: float) -> MigrationFileLock:
    """Take ``backend_root``'s install lock, with no abandoned installer left in it.

    Every acquisition of ``.install.lock`` goes through here. Liveness comes
    from the process scan: every abandoned installer tree of this Runtime is
    reaped first. An install holds the lock from before its record exists
    until after it has removed its staging and then its record, so a record
    for this root seen under the lock names an install whose owner died
    first; its tree is reaped by its marker and its staging removed. When the
    records cannot be listed or read, nothing is removed; then, or when a
    tree cannot be shown gone, the lock is released and ``install_locked``
    raised. So is it when removal deleted the lock file while this waited.
    """

    lock_path = backend_root / ".install.lock"
    removed: list[bool] = []

    def names_the_lock_path(handle) -> bool:
        # Removal deletes a lock file while it holds it, so a waiter that gets
        # the lock then holds a file no other install would lock.
        try:
            same = os.path.samestat(os.fstat(handle.fileno()), os.stat(lock_path))
        except FileNotFoundError:
            same = False
        if not same:
            removed.append(True)
        return same

    lock = MigrationFileLock(lock_path, timeout_seconds=timeout_seconds, _handle_validator=names_the_lock_path)
    try:
        lock.acquire()
    except MigrationLockTimeout as exc:
        raise DesktopBackendError(
            f"Another {backend_root.name} install is already running.",
            code="install_locked",
        ) from exc
    except OSError as exc:
        if not removed:
            raise
        raise DesktopBackendError(
            f"The {backend_root.name} backend directory is being removed.",
            code="install_locked",
        ) from exc
    try:
        records = [record for record in _installer_records() if record.backend_root == backend_root]
        settled = reap_abandoned_desktop_backend_installs() and all(
            [_clear_abandoned_install(record) for record in records]
        )
    except OSError as exc:
        lock.release()
        raise DesktopBackendError(
            f"The {backend_root.name} install records could not be read.",
            code="install_locked",
        ) from exc
    except BaseException:
        lock.release()
        raise
    if not settled:
        lock.release()
        raise DesktopBackendError(
            f"A previous {backend_root.name} install could not be shown to have stopped.",
            code="install_locked",
        )
    return lock


def remove_desktop_backends(base_env: Mapping[str, str] | None = None) -> None:
    """Delete the app-private backend root once no installer can be writing into it.

    Every backend directory is claimed the way an install claims it, which
    reaps the installer trees abandoned in it, and nothing is deleted until all
    of them are held. Nothing is deleted recursively once a lock is released,
    so an install that begins meanwhile keeps its files, and fails the
    removal. Raises ``DesktopBackendError``: ``install_locked`` with nothing
    deleted, and any other code when part of the root may remain.
    """

    root = private_desktop_backends_root(base_env)
    if root is None:
        raise DesktopBackendError("The desktop backend root is unavailable.", code="invalid_backend_root")
    if not os.path.lexists(root):
        return
    if root.is_symlink() or not root.is_dir():
        raise DesktopBackendError("Invalid desktop backend root.", code="invalid_backend_root")
    claimed: list[tuple[Path, MigrationFileLock]] = []
    try:
        try:
            entries = sorted(root.iterdir())
            for entry in entries:
                if entry.is_dir() and not entry.is_symlink():
                    lock = _claim_backend_root(entry, timeout_seconds=DESKTOP_BACKEND_REMOVAL_LOCK_TIMEOUT_SECONDS)
                    claimed.append((entry, lock))
            for entry in entries:
                if entry.is_dir() and not entry.is_symlink():
                    for member in entry.iterdir():
                        if member.name != ".install.lock":
                            _remove_path(member)
                else:
                    _remove_path(entry)
            for entry, lock in claimed:
                # A waiter that then gets the lock finds its file gone, and
                # refuses. Windows deletes no open file, so the lock file goes
                # once released, and stays while any installer has it open.
                if os.name == "nt":
                    lock.release()
                (entry / ".install.lock").unlink(missing_ok=True)
                entry.rmdir()
            # A directory an install created since the listing keeps the root.
            root.rmdir()
        finally:
            for _entry, lock in reversed(claimed):
                lock.release()
    except OSError as exc:
        raise DesktopBackendError(
            f"The desktop backend root could not be removed: {exc}",
            code="backend_removal_failed",
        ) from exc


def _remove_path(path: Path) -> None:
    if path.is_dir() and not path.is_symlink():
        shutil.rmtree(path)
    else:
        path.unlink(missing_ok=True)


def _installed_package_version(package_dir: Path, expected_package: str) -> str:
    manifest = package_dir / "package.json"
    try:
        if manifest.is_symlink() or manifest.stat().st_size > MAX_DESCRIPTOR_BYTES:
            raise ValueError("invalid package manifest")
        payload = json.loads(manifest.read_text(encoding="utf-8"))
    except (OSError, UnicodeError, json.JSONDecodeError, ValueError) as exc:
        raise DesktopBackendError(
            "Installed package metadata is missing or invalid.",
            code="invalid_package",
        ) from exc
    name = payload.get("name") if isinstance(payload, dict) else None
    version = payload.get("version") if isinstance(payload, dict) else None
    if name != expected_package or not isinstance(version, str) or not version or len(version) > 128:
        raise DesktopBackendError(
            "Installed package identity does not match the requested backend.",
            code="invalid_package",
        )
    return version


def _installed_native_executable(
    backend: str,
    spec: DesktopBackendSpec,
    staging: Path,
    package_dir: Path,
) -> Path:
    os_name, arch = _native_target()
    if backend == "codex":
        executable_name = "codex.exe" if os_name == "win32" else "codex"
        target_package = staging / "node_modules" / "@openai" / f"codex-{os_name}-{arch}"
        target_roots = [target_package, package_dir / "node_modules" / "@openai" / target_package.name]
        candidates = [
            candidate
            for target_root in target_roots
            for candidate in target_root.glob(f"vendor/*/bin/{executable_name}")
        ]
    elif backend == "claude":
        executable_name = "claude.exe" if os_name == "win32" else "claude"
        target_package = staging / "node_modules" / "@anthropic-ai" / f"claude-code-{os_name}-{arch}"
        target_roots = [target_package, package_dir / "node_modules" / "@anthropic-ai" / target_package.name]
        candidates = [target_root / executable_name for target_root in target_roots]
    elif backend == "opencode":
        target_os = "windows" if os_name == "win32" else os_name
        executable_name = "opencode.exe" if os_name == "win32" else "opencode"
        target_package = staging / "node_modules" / f"opencode-{target_os}-{arch}"
        target_roots = [target_package, package_dir / "node_modules" / target_package.name]
        candidates = [target_root / "bin" / executable_name for target_root in target_roots]
    else:  # BACKEND_SPECS and callers keep this unreachable.
        candidates = []

    unique: dict[Path, Path] = {}
    for candidate in candidates:
        try:
            unique[candidate.resolve(strict=True)] = candidate
        except OSError:
            continue
    if len(unique) != 1:
        raise DesktopBackendError(
            f"Installed {backend} package contains no unique target-native executable.",
            code="native_executable_missing",
        )
    executable = next(iter(unique))
    if not _verified_direct_executable(executable, root=staging, require_native=True):
        raise DesktopBackendError(
            f"Installed {backend} executable failed validation.",
            code="invalid_executable",
        )
    return executable


def _backend_runtime_path_entries(
    backend: str,
    executable: Path,
    *,
    root: Path,
) -> tuple[Path, ...]:
    if backend != "codex":
        return ()

    windows = os.name == "nt"
    target_root = executable.parent.parent
    executable_paths = [
        target_root
        / "bin"
        / ("codex-code-mode-host.exe" if windows else "codex-code-mode-host"),
        target_root / "codex-path" / ("rg.exe" if windows else "rg"),
    ]
    if windows:
        executable_paths.extend(
            [
                target_root / "codex-resources" / "codex-command-runner.exe",
                target_root / "codex-resources" / "codex-windows-sandbox-setup.exe",
            ]
        )
    else:
        executable_paths.append(
            target_root / "codex-resources" / "zsh" / "bin" / "zsh"
        )
        if platform.system().lower() == "linux":
            executable_paths.append(target_root / "codex-resources" / "bwrap")

    package_manifest = target_root / "codex-package.json"
    if not _verified_direct_regular_file(package_manifest, root=root) or not all(
        _verified_direct_executable(path, root=root, require_native=True)
        for path in executable_paths
    ):
        raise DesktopBackendError(
            "Installed Codex package is missing a required native runtime helper.",
            code="incomplete_backend_runtime",
        )
    return (executable_paths[1].parent.resolve(strict=True),)


def _verify_backend_executable(
    backend: str,
    executable: Path,
    *,
    root: Path,
    env: Mapping[str, str],
) -> None:
    if not _verified_direct_executable(executable, root=root, require_native=True):
        raise DesktopBackendError(
            f"Installed {backend} executable failed validation.",
            code="invalid_executable",
        )
    # Spawned as an installer, so the probe is owned, recorded and scanned
    # like the npm tree before it: no stop or drain can miss it.
    try:
        result = _run_command(
            [str(executable), "--version"],
            cwd=root,
            env=env,
            timeout_seconds=DESKTOP_BACKEND_PROBE_TIMEOUT_SECONDS,
        )
    except DesktopBackendError as exc:
        if exc.code != "install_timeout":
            raise
        raise DesktopBackendError(
            f"Installed {backend} executable did not report a version in time.",
            code="executable_probe_failed",
            output=exc.output,
        ) from exc
    except OSError as exc:
        raise DesktopBackendError(
            f"Installed {backend} executable could not be started.",
            code="executable_probe_failed",
        ) from exc
    if result.returncode != 0 or not cli_version(backend, result.stdout, result.stderr):
        raise DesktopBackendError(
            f"Installed {backend} executable did not report a valid version.",
            code="executable_probe_failed",
            output=_bounded_output(result.stdout, result.stderr),
        )


def _verified_direct_executable(path: Path, *, root: Path, require_native: bool) -> bool:
    try:
        if path.is_symlink() or not path.is_file():
            return False
        resolved = path.resolve(strict=True)
        resolved.relative_to(root.resolve(strict=True))
        relative = path.relative_to(root)
        cursor = root
        for part in relative.parts:
            cursor = cursor / part
            if cursor.is_symlink():
                return False
        if path.suffix.lower() in {".cmd", ".ps1", ".js"}:
            return False
        if os.name != "nt" and not os.access(resolved, os.X_OK):
            return False
        return not require_native or _has_native_magic(resolved)
    except (OSError, ValueError):
        return False


def _verified_direct_regular_file(path: Path, *, root: Path) -> bool:
    try:
        if path.is_symlink() or not path.is_file():
            return False
        resolved = path.resolve(strict=True)
        resolved.relative_to(root.resolve(strict=True))
        relative = path.relative_to(root)
        cursor = root
        for part in relative.parts:
            cursor = cursor / part
            if cursor.is_symlink():
                return False
        return True
    except (OSError, ValueError):
        return False


def _has_native_magic(path: Path) -> bool:
    try:
        with path.open("rb") as handle:
            magic = handle.read(4)
    except OSError:
        return False
    return magic.startswith(b"MZ") or magic == b"\x7fELF" or magic in {
        b"\xfe\xed\xfa\xce",
        b"\xfe\xed\xfa\xcf",
        b"\xce\xfa\xed\xfe",
        b"\xcf\xfa\xed\xfe",
        b"\xca\xfe\xba\xbe",
        b"\xbe\xba\xfe\xca",
    }


def _native_target() -> tuple[str, str]:
    if os.name == "nt":
        os_name = "win32"
    elif platform.system().lower() == "darwin":
        os_name = "darwin"
    elif platform.system().lower() == "linux":
        os_name = "linux"
    else:
        raise DesktopBackendError("Unsupported desktop platform.", code="unsupported_platform")
    machine = platform.machine().lower()
    if machine in {"amd64", "x86_64"}:
        arch = "x64"
    elif machine in {"arm64", "aarch64"}:
        arch = "arm64"
    else:
        raise DesktopBackendError("Unsupported desktop architecture.", code="unsupported_platform")
    return os_name, arch


def _descriptor_relative_path(value: Any) -> Path | None:
    if not isinstance(value, str) or not value or len(value) > 4096 or "\\" in value:
        return None
    relative = PurePosixPath(value)
    if relative.is_absolute() or ".." in relative.parts or "." in relative.parts:
        return None
    if any(not part or ":" in part for part in relative.parts):
        return None
    return Path(*relative.parts)


def _write_current_descriptor(path: Path, payload: dict[str, Any]) -> None:
    encoded = (json.dumps(payload, sort_keys=True) + "\n").encode("utf-8")
    if len(encoded) > MAX_DESCRIPTOR_BYTES:
        raise ValueError("desktop backend descriptor exceeds size limit")
    _write_descriptor_bytes(path, encoded)


def _read_descriptor_bytes(path: Path) -> bytes | None:
    try:
        if path.is_symlink() or not path.is_file() or path.stat().st_size > MAX_DESCRIPTOR_BYTES:
            return None
        return path.read_bytes()
    except OSError:
        return None


def _restore_descriptor_bytes(path: Path, previous: bytes | None) -> None:
    if previous is None:
        path.unlink(missing_ok=True)
        return
    _write_descriptor_bytes(path, previous)


def _write_descriptor_bytes(path: Path, encoded: bytes) -> None:
    if len(encoded) > MAX_DESCRIPTOR_BYTES:
        raise ValueError("desktop backend descriptor exceeds size limit")
    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
    fd, temporary_name = tempfile.mkstemp(prefix=".current-", suffix=".json", dir=path.parent)
    temporary = Path(temporary_name)
    try:
        with os.fdopen(fd, "wb") as handle:
            handle.write(encoded)
            handle.flush()
            os.fsync(handle.fileno())
        os.replace(temporary, path)
        if os.name != "nt":
            directory_fd = os.open(path.parent, os.O_RDONLY)
            try:
                os.fsync(directory_fd)
            finally:
                os.close(directory_fd)
    finally:
        temporary.unlink(missing_ok=True)


def _remove_staging_directory(staging: Path, backend_root: Path) -> bool:
    """Remove ``staging`` if it lies under ``backend_root``; True once it is gone."""

    try:
        staging.relative_to(backend_root)
    except ValueError:
        return False
    try:
        if staging.is_symlink():
            staging.unlink(missing_ok=True)
        elif staging.exists():
            shutil.rmtree(staging)
    except OSError:
        logger.warning("Failed to remove desktop backend staging directory %s", staging)
    return not os.path.lexists(staging)


def _remove_internal_directory(path: Path, root: Path) -> None:
    try:
        path.relative_to(root)
    except ValueError:
        return
    if path.is_symlink():
        path.unlink(missing_ok=True)
    elif path.exists():
        shutil.rmtree(path)


def _bounded_output(stdout: str | None, stderr: str | None) -> str | None:
    output = (stdout or "") + ("\n" + stderr if stderr else "")
    output = output.strip()
    if len(output) > MAX_INSTALL_OUTPUT_CHARS:
        output = "...(truncated)\n" + output[-MAX_INSTALL_OUTPUT_CHARS:]
    return output or None