Skip to content

Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.

52.4 KB
Raw Blame
"""Downloads codebase-memory-mcp on first run, then runs its native entry point."""

import errno
import hashlib
import json
import os
import platform
import re
import secrets
import shutil
import stat
import subprocess
import sys
import tempfile
import threading
import time
import urllib.error
import urllib.parse
import urllib.request
from pathlib import Path

REPO = "DeusData/codebase-memory-mcp"
_WINDOWS_BINARY_NAME = "codebase-memory-mcp.exe"
_UNIX_ARCHIVE_NAMES = (
    "codebase-memory-mcp",
    "LICENSE",
    "install.sh",
    "THIRD_PARTY_NOTICES.md",
)
_WINDOWS_ARCHIVE_NAMES = (
    _WINDOWS_BINARY_NAME,
    "LICENSE",
    "install.ps1",
    "THIRD_PARTY_NOTICES.md",
)

# Security: only permit https fetches. urllib's default handlers accept
# file://, ftp://, and custom schemes — a redirect or tainted URL source
# could otherwise turn a download into an arbitrary-local-file read.
_ALLOWED_SCHEMES = frozenset({"https"})
# install.sh's loopback pattern: plain HTTP only to an exact loopback
# authority, for local smoke tests (CBM_DOWNLOAD_URL).
_LOOPBACK_HTTP_URL = re.compile(
    r"http://(localhost|127\.0\.0\.1|\[::1\])(:[0-9]+)?([/?#].*)?"
)
_LOOPBACK_HOSTNAMES = frozenset({"localhost", "127.0.0.1", "::1"})
_MAX_REDIRECTS = 5
_NETWORK_TIMEOUT_SECONDS = 120
_CANDIDATE_TIMEOUT_SECONDS = 15
# Entry-count guard for the archive namespace check. Keep in sync with the
# Go wrapper (pkg/go/cmd/codebase-memory-mcp/main.go) and the npm wrapper.
_MAX_ARCHIVE_MEMBERS = 64
_ARCHIVE_COPY_CHUNK_BYTES = 64 * 1024
_REDIRECT_CODES = frozenset({301, 302, 303, 307, 308})
_RUNTIME_LOCK_NAME = ".codebase-memory-mcp-runtime.lock"
_RUNTIME_LOCK_WAIT_SECONDS = 45
_RUNTIME_OWNERLESS_STALE_SECONDS = 30
_RUNTIME_LOCK_POLL_SECONDS = 0.025
_RUNTIME_LOCK_LEASE_SECONDS = 300
_RUNTIME_LOCK_HEARTBEAT_SECONDS = 20
_RUNTIME_LEGACY_STALE_SECONDS = 3600
_RUNTIME_BACKUP_PREFIX = ".cbm-runtime-backup-"
_RUNTIME_BACKUP_RE = re.compile(r"\.cbm-runtime-backup-[0-9a-f]{32}\Z")
_RUNTIME_BACKUP_RETIRED_MARKER = ".retirement-complete"
_RUNTIME_BACKUP_CLEANUP_MARKER = ".cleanup-only"
_WINDOWS_SYNCHRONIZE = 0x00100000
_WINDOWS_WAIT_OBJECT_0 = 0x00000000
_WINDOWS_WAIT_TIMEOUT = 0x00000102
_WINDOWS_ERROR_INVALID_PARAMETER = 87
_runtime_lock_claim_observer = None


class _NoRedirectHandler(urllib.request.HTTPRedirectHandler):
    """Expose redirects to _download_file for explicit per-hop validation."""

    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None


_HTTPS_OPENER = urllib.request.build_opener(_NoRedirectHandler())
# A loopback fetch never goes through a proxy.
_LOOPBACK_OPENER = urllib.request.build_opener(
    urllib.request.ProxyHandler({}), _NoRedirectHandler()
)


def _download_base(version: str, environ=None):
    """Return (base, loopback) for release downloads.

    CBM_DOWNLOAD_URL replaces the release download base (for testing), with
    install.sh's policy: HTTPS, or plain HTTP to an exact loopback authority.
    """
    env = os.environ if environ is None else environ
    override = env.get("CBM_DOWNLOAD_URL")
    if not override:
        return f"https://github.com/{REPO}/releases/download/v{version}", False
    if override.startswith("https://"):
        return override, False
    if _LOOPBACK_HTTP_URL.fullmatch(override):
        return override, True
    sys.exit(
        f"codebase-memory-mcp: refusing non-HTTPS download URL "
        f"(CBM_DOWNLOAD_URL): {override}"
    )


def _validate_loopback_url(url: str) -> None:
    """Reject anything but plain HTTP to an exact loopback authority."""
    parsed = urllib.parse.urlparse(url)
    if (
        not _LOOPBACK_HTTP_URL.fullmatch(url)
        or parsed.scheme != "http"
        or parsed.hostname not in _LOOPBACK_HOSTNAMES
        or parsed.username is not None
        or parsed.password is not None
    ):
        sys.exit(f"codebase-memory-mcp: refusing non-loopback HTTP URL: {url}")


def _validate_url_scheme(url: str) -> None:
    """Reject non-https URLs before any network fetch."""
    parsed = urllib.parse.urlparse(url)
    if (
        parsed.scheme not in _ALLOWED_SCHEMES
        or not parsed.hostname
        or parsed.username is not None
        or parsed.password is not None
    ):
        sys.exit(
            f"codebase-memory-mcp: refusing to fetch invalid, credentialed, or "
            f"non-https URL: {url}"
        )


def _validate_download_url(url: str, loopback: bool) -> None:
    if loopback:
        _validate_loopback_url(url)
    else:
        _validate_url_scheme(url)


def _download_file(url: str, dest: str, loopback: bool = False) -> None:
    """Download into dest: HTTPS with checked redirects, or one loopback hop."""
    opener = _LOOPBACK_OPENER if loopback else _HTTPS_OPENER
    current_url = url
    for redirect_count in range(_MAX_REDIRECTS + 1):
        _validate_download_url(current_url, loopback)
        request = urllib.request.Request(
            current_url, headers={"User-Agent": "codebase-memory-mcp-installer"}
        )
        try:
            response = opener.open(request, timeout=_NETWORK_TIMEOUT_SECONDS)
        except urllib.error.HTTPError as exc:
            if exc.code not in _REDIRECT_CODES:
                raise
            location = exc.headers.get("Location")
            exc.close()
            if loopback:
                raise RuntimeError(
                    f"refusing redirect from loopback download: {current_url}"
                )
            if not location:
                raise RuntimeError(f"redirect has no Location: {current_url}")
            if redirect_count == _MAX_REDIRECTS:
                raise RuntimeError("too many redirects")
            current_url = urllib.parse.urljoin(current_url, location)
            _validate_url_scheme(current_url)
            continue

        with response:
            _validate_download_url(response.geturl(), loopback)
            deadline = time.monotonic() + _NETWORK_TIMEOUT_SECONDS
            try:
                with open(dest, "wb") as out:
                    while True:
                        if time.monotonic() >= deadline:
                            raise TimeoutError(
                                f"download hop timed out: {current_url}"
                            )
                        chunk = response.read(65536)
                        if not chunk:
                            return
                        out.write(chunk)
            except BaseException:
                # Never leave a partial download behind for a later step to
                # mistake for the complete asset.
                _remove_quietly(dest)
                raise

    raise RuntimeError("too many redirects")


def _remove_quietly(path) -> None:
    try:
        os.unlink(path)
    except OSError:
        pass


def _verify_candidate(path: Path) -> None:
    """Require a staged native candidate to execute successfully."""
    try:
        subprocess.run(
            [str(path), "--version"],
            stdin=subprocess.DEVNULL,
            stdout=subprocess.DEVNULL,
            stderr=subprocess.DEVNULL,
            check=True,
            timeout=_CANDIDATE_TIMEOUT_SECONDS,
        )
    except (OSError, subprocess.SubprocessError) as exc:
        raise RuntimeError(f"downloaded binary failed to run: {exc}") from exc


def _file_sha256(path: Path) -> str:
    digest = hashlib.sha256()
    with path.open("rb") as source:
        for chunk in iter(lambda: source.read(65536), b""):
            digest.update(chunk)
    return digest.hexdigest()


def _files_equal_sha256(left: Path, right: Path) -> bool:
    try:
        return (
            _regular_file(left)
            and _regular_file(right)
            and left.stat().st_size == right.stat().st_size
            and _file_sha256(left) == _file_sha256(right)
        )
    except OSError:
        return False


def _validate_archive_names(names, archive_names, casefold: bool = False):
    """Require the exact release root namespace."""
    required = tuple(archive_names)
    required_set = set(required)
    found = set()
    seen = set()
    for name in names:
        key = name.casefold() if casefold else name
        if key in seen:
            sys.exit(
                f"codebase-memory-mcp: refusing unsafe archive entry "
                f"(duplicate or case conflict: {name!r})"
            )
        seen.add(key)
        if name not in required_set:
            sys.exit(
                f"codebase-memory-mcp: archive must contain only the exact "
                f"root files: {', '.join(required)}"
            )
        found.add(name)
    if found != required_set or len(seen) != len(required):
        sys.exit(
            f"codebase-memory-mcp: archive must contain exactly one of each "
            f"required root file: {', '.join(required)}"
        )


def _require_regular_archive(archive_path: str) -> None:
    if not stat.S_ISREG(os.stat(archive_path).st_mode):
        sys.exit("codebase-memory-mcp: release archive is not a regular file")


def _require_member_count_within_limit(count: int, max_members: int) -> None:
    if count > max_members:
        sys.exit(
            f"codebase-memory-mcp: archive exceeds the {max_members}-member "
            f"safety limit"
        )


def _require_declared_size(name: str, size: int) -> None:
    if size < 0:
        sys.exit(
            f"codebase-memory-mcp: archive member has a negative declared "
            f"size: {name!r}"
        )


def _copy_archive_member(source, output, name: str, declared_size: int) -> int:
    """Copy a member, then require the declared size; return the bytes copied.

    The caller removes the target on failure.
    """
    copied = 0
    while True:
        chunk = source.read(_ARCHIVE_COPY_CHUNK_BYTES)
        if not chunk:
            break
        copied += len(chunk)
        output.write(chunk)
    if copied != declared_size:
        sys.exit(
            f"codebase-memory-mcp: archive member {name!r} actual size {copied} "
            f"does not match declared size {declared_size}"
        )
    return copied


def _write_archive_member(source, target: str, name: str, declared_size: int) -> int:
    try:
        with open(target, "xb") as output:
            return _copy_archive_member(source, output, name, declared_size)
    except BaseException:
        _remove_quietly(target)
        raise


def _safe_extract_tar(
    tf,
    dest: str,
    archive_names=(),
    extract_names=(),
    ui: bool = False,
    max_members: int = _MAX_ARCHIVE_MEMBERS,
):
    """Validate a tar namespace, then extract only its authenticated runtime set."""
    members = tf.getmembers()
    _require_member_count_within_limit(len(members), max_members)
    for member in members:
        if not member.isfile():
            sys.exit(
                f"codebase-memory-mcp: refusing unsafe tar entry "
                f"(not a regular root file: {member.name!r})"
            )
        _require_declared_size(member.name, member.size)
    _validate_archive_names([member.name for member in members], archive_names)
    runtime_names = list(extract_names)
    by_name = {member.name: member for member in members}
    dest_abs = os.path.abspath(dest)
    for name in runtime_names:
        source = tf.extractfile(by_name[name])
        if source is None:
            sys.exit(f"codebase-memory-mcp: could not read archive member: {name}")
        target = os.path.join(dest_abs, name)
        with source:
            _write_archive_member(source, target, name, by_name[name].size)
    return tuple(runtime_names)


def _safe_extract_zip(
    zf,
    dest: str,
    archive_names=(),
    extract_names=(),
    ui: bool = False,
    max_members: int = _MAX_ARCHIVE_MEMBERS,
):
    """Extract a zipfile after validating its Windows-style namespace.

    Windows treats paths case-insensitively. Rejecting duplicate/case-conflicting
    members before extraction prevents archive order from selecting the binary
    that a portable package-manager shim eventually executes.
    """
    dest_abs = os.path.abspath(dest)
    names = []
    infos = zf.infolist()
    _require_member_count_within_limit(len(infos), max_members)
    for info in infos:
        _require_declared_size(info.filename, info.file_size)
        raw_name = info.filename
        name = raw_name.replace("\\", "/")
        segments_name = name[:-1] if name.endswith("/") else name
        segments = segments_name.split("/")
        if (
            not segments_name
            or name.startswith("/")
            or ":" in name
            or any(segment in ("", ".", "..") for segment in segments)
            or any(segment.endswith((".", " ")) for segment in segments)
        ):
            sys.exit(
                f"codebase-memory-mcp: refusing unsafe zip entry "
                f"(invalid path: {raw_name!r})"
            )
        unix_type = stat.S_IFMT((info.external_attr >> 16) & 0xFFFF)
        if info.is_dir() or unix_type not in (0, stat.S_IFREG):
            sys.exit(
                f"codebase-memory-mcp: refusing unsafe zip entry "
                f"(not a regular root file: {raw_name!r})"
            )
        names.append(name)
        member_abs = os.path.abspath(os.path.join(dest_abs, *segments))
        if not (member_abs == dest_abs or member_abs.startswith(dest_abs + os.sep)):
            sys.exit(
                f"codebase-memory-mcp: refusing unsafe zip entry "
                f"(escapes dest: {raw_name!r})"
            )
    _validate_archive_names(names, archive_names, casefold=True)

    # Extract only the validated runtime files. This avoids relying on
    # platform-specific zip path rewriting and always creates regular files.
    runtime_names = list(extract_names)
    for name in runtime_names:
        target = os.path.join(dest_abs, name)
        with zf.open(name) as source:
            _write_archive_member(source, target, name, zf.getinfo(name).file_size)
    return tuple(runtime_names)


def _verify_checksum(
    archive_path: str, archive_name: str, base: str, loopback: bool = False
) -> None:
    """Verify SHA256 checksum against checksums.txt from the same base."""
    url = f"{base}/checksums.txt"
    tmp_path = None
    try:
        _validate_download_url(url, loopback)
        with tempfile.NamedTemporaryFile(suffix=".txt", delete=False) as tmp:
            tmp_path = tmp.name
        _download_file(url, tmp_path, loopback)
        expected = None
        with open(tmp_path, encoding="utf-8") as f:
            for line in f:
                fields = line.split()
                if len(fields) < 2 or fields[1] not in (
                    archive_name,
                    f"*{archive_name}",
                ):
                    continue
                digest = fields[0].lower()
                if len(digest) != 64 or any(
                    ch not in "0123456789abcdef" for ch in digest
                ):
                    sys.exit(
                        f"codebase-memory-mcp: invalid SHA256 checksum for "
                        f"{archive_name}"
                    )
                if expected is not None and expected != digest:
                    sys.exit(
                        f"codebase-memory-mcp: conflicting SHA256 checksums for "
                        f"{archive_name}"
                    )
                expected = digest
        if expected is None:
            sys.exit(
                f"codebase-memory-mcp: no checksum for {archive_name} in checksums.txt"
            )
        h = hashlib.sha256()
        with open(archive_path, "rb") as af:
            for chunk in iter(lambda: af.read(65536), b""):
                h.update(chunk)
        actual = h.hexdigest()
        if expected != actual:
            sys.exit(
                f"codebase-memory-mcp: CHECKSUM MISMATCH for {archive_name}\n"
                f"  expected: {expected}\n"
                f"  actual:   {actual}"
            )
        print("codebase-memory-mcp: checksum verified.", file=sys.stderr)
    except SystemExit:
        raise
    except Exception as exc:
        sys.exit(f"codebase-memory-mcp: checksum verification failed: {exc}")
    finally:
        if tmp_path is not None:
            try:
                os.unlink(tmp_path)
            except Exception:
                pass


def _version() -> str:
    try:
        from importlib.metadata import version
        return version("codebase-memory-mcp")
    except Exception:
        return "0.12.1"


def _os_name() -> str:
    p = sys.platform
    if p == "linux":
        return "linux"
    if p == "darwin":
        return "darwin"
    if p == "win32":
        return "windows"
    sys.exit(f"codebase-memory-mcp: unsupported platform: {p}")


def _arch() -> str:
    m = platform.machine().lower()
    if m in ("arm64", "aarch64"):
        return "arm64"
    if m in ("x86_64", "amd64"):
        return "amd64"
    sys.exit(f"codebase-memory-mcp: unsupported architecture: {m}")


def _cache_dir() -> Path:
    if sys.platform == "win32":
        base = Path(os.environ.get("LOCALAPPDATA", Path.home() / "AppData" / "Local"))
    elif sys.platform == "darwin":
        base = Path.home() / "Library" / "Caches"
    else:
        base = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache"))
    return base / "codebase-memory-mcp"


def _runtime_dir(version: str) -> Path:
    return _cache_dir() / version


def _bin_path(version: str) -> Path:
    # One binary per platform: the cached file is the executed file.
    name = (
        _WINDOWS_BINARY_NAME
        if sys.platform == "win32"
        else "codebase-memory-mcp"
    )
    return _runtime_dir(version) / name


def _execution_path(binary: Path, target_platform: str) -> Path:
    """The cached binary is executed directly on every platform."""
    return binary


def _regular_file(path: Path) -> bool:
    try:
        status = path.lstat()
        return (
            stat.S_ISREG(status.st_mode)
            and not stat.S_ISLNK(status.st_mode)
            and status.st_nlink == 1
        )
    except OSError:
        return False


def _runtime_set_names(directory: Path, binary_name: str):
    if not _regular_file(directory / binary_name):
        return None
    return (binary_name,)


def _runtime_set_ready(version: str, verifier=None) -> bool:
    binary = _bin_path(version)
    if _runtime_set_names(binary.parent, binary.name) is None:
        return False
    if verifier is not None:
        try:
            verifier(binary)
        except RuntimeError:
            return False
    return True


def _require_safe_runtime_directory(directory: Path):
    status = directory.lstat()
    if not stat.S_ISDIR(status.st_mode) or stat.S_ISLNK(status.st_mode):
        raise RuntimeError(f"refusing unsafe package-cache directory: {directory}")


def _runtime_set_ready_locked(version: str) -> bool:
    binary = _bin_path(version)
    binary.parent.mkdir(parents=True, exist_ok=True)
    _require_safe_runtime_directory(binary.parent)
    lock, _ = _acquire_runtime_lock(binary.parent)
    try:
        _refresh_runtime_lock(lock)
        _reconcile_runtime_backups(
            binary.parent, binary.name, _verify_candidate, lock
        )
        return _runtime_set_ready(version, _verify_candidate)
    finally:
        _release_runtime_lock(lock)


def _runtime_set_fingerprint(directory: Path, binary_name: str):
    """Identify one complete set so a lock waiter can preserve its winner."""
    names = _runtime_set_names(directory, binary_name)
    if names is None:
        return None
    try:
        return tuple(
            (name, _file_sha256(directory / name)) for name in names
        )
    except OSError:
        return None


def _staged_runtime_names(staged_paths, binary_name: str):
    names = set(staged_paths)
    required = {binary_name}
    if names != required or not _regular_file(staged_paths[binary_name]):
        raise RuntimeError("staged package cache is incomplete")
    return (binary_name,)


def _windows_process_api():
    import ctypes
    from ctypes import wintypes

    kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
    kernel32.OpenProcess.argtypes = (
        wintypes.DWORD,
        wintypes.BOOL,
        wintypes.DWORD,
    )
    kernel32.OpenProcess.restype = wintypes.HANDLE
    kernel32.WaitForSingleObject.argtypes = (
        wintypes.HANDLE,
        wintypes.DWORD,
    )
    kernel32.WaitForSingleObject.restype = wintypes.DWORD
    kernel32.CloseHandle.argtypes = (wintypes.HANDLE,)
    kernel32.CloseHandle.restype = wintypes.BOOL
    return kernel32, ctypes.get_last_error


def _windows_process_is_alive(pid: int) -> bool:
    if pid > 0xFFFFFFFF:
        # Avoid truncating an unprobeable owner identifier into another PID.
        return True
    try:
        kernel32, get_last_error = _windows_process_api()
        handle = kernel32.OpenProcess(_WINDOWS_SYNCHRONIZE, False, pid)
    except Exception:
        return True
    if not handle:
        try:
            error = get_last_error()
        except Exception:
            return True
        # OpenProcess documents ERROR_INVALID_PARAMETER for a PID that no
        # longer identifies a process. Access denial remains evidence of a
        # potentially live owner and must not authorize lock reclamation.
        return error != _WINDOWS_ERROR_INVALID_PARAMETER
    try:
        try:
            wait_result = kernel32.WaitForSingleObject(handle, 0)
        except Exception:
            return True
        if wait_result == _WINDOWS_WAIT_OBJECT_0:
            return False
        if wait_result == _WINDOWS_WAIT_TIMEOUT:
            return True
        return True
    finally:
        try:
            kernel32.CloseHandle(handle)
        except Exception:
            pass


def _process_is_alive(pid: int) -> bool:
    if not isinstance(pid, int) or isinstance(pid, bool) or pid <= 0:
        return False
    if os.name == "nt":
        return _windows_process_is_alive(pid)
    try:
        os.kill(pid, 0)
        return True
    except ProcessLookupError:
        return False
    except PermissionError:
        return True
    except OSError as exc:
        return exc.errno != errno.ESRCH


def _runtime_lock_status(lock_path: Path):
    try:
        return lock_path.lstat()
    except OSError:
        return None


def _same_runtime_lock_object(left, right):
    return (
        left is not None
        and right is not None
        and left.st_dev == right.st_dev
        and left.st_ino == right.st_ino
        and stat.S_IFMT(left.st_mode) == stat.S_IFMT(right.st_mode)
    )


def _read_runtime_lock_owner(lock_path: Path):
    try:
        status = lock_path.lstat()
        if stat.S_ISLNK(status.st_mode) or not (
            stat.S_ISREG(status.st_mode) or stat.S_ISDIR(status.st_mode)
        ):
            return None
        owner_path = lock_path / "owner.json" if stat.S_ISDIR(status.st_mode) else lock_path
        owner = json.loads(owner_path.read_text(encoding="utf-8"))
    except (OSError, ValueError, TypeError):
        return None
    pid = owner.get("pid")
    token = owner.get("token")
    if (
        not isinstance(pid, int)
        or isinstance(pid, bool)
        or pid <= 0
        or not isinstance(token, str)
        or re.fullmatch(r"[0-9a-f]{32}", token) is None
    ):
        return None
    lease_expires = owner.get("lease_expires_ms")
    if not isinstance(lease_expires, (int, float)) or isinstance(
        lease_expires, bool
    ):
        lease_expires = None
    return pid, token, lease_expires


def _restore_displaced_runtime_lock(reclaimed: Path, lock_path: Path, status):
    if status is None or not stat.S_ISREG(status.st_mode):
        return
    try:
        os.link(reclaimed, lock_path)
        reclaimed.unlink()
    except OSError:
        # A newer owner holds the canonical name. Preserve the displaced lock;
        # never delete a lock whose identity was not the one inspected.
        pass


def _try_reclaim_runtime_lock(lock_path: Path, contender_token: str):
    """Return whether to retry now and whether a contender released the lock."""
    observed_status = _runtime_lock_status(lock_path)
    if observed_status is None:
        return True, True
    if stat.S_ISLNK(observed_status.st_mode) or not (
        stat.S_ISREG(observed_status.st_mode)
        or stat.S_ISDIR(observed_status.st_mode)
    ):
        return False, False
    owner = _read_runtime_lock_owner(lock_path)
    reclaim = owner is not None and not _process_is_alive(owner[0])
    if owner is None:
        reclaim = (
            time.time() - observed_status.st_mtime
            >= _RUNTIME_OWNERLESS_STALE_SECONDS
        )
    if not reclaim:
        return False, False
    reclaimed = lock_path.with_name(
        f"{lock_path.name}.reclaimed-{contender_token}"
    )
    try:
        os.rename(lock_path, reclaimed)
    except FileNotFoundError:
        return True, True
    except OSError:
        return False, False
    moved_status = _runtime_lock_status(reclaimed)
    if not _same_runtime_lock_object(observed_status, moved_status):
        _restore_displaced_runtime_lock(reclaimed, lock_path, moved_status)
        return False, False
    moved_owner = _read_runtime_lock_owner(reclaimed)
    still_reclaimable = (
        time.time() - moved_status.st_mtime >= _RUNTIME_OWNERLESS_STALE_SECONDS
        if moved_owner is None
        else not _process_is_alive(moved_owner[0])
    )
    if not still_reclaimable:
        _restore_displaced_runtime_lock(reclaimed, lock_path, moved_status)
        return False, False
    if stat.S_ISDIR(moved_status.st_mode):
        shutil.rmtree(reclaimed)
    else:
        reclaimed.unlink()
    return True, False


def _write_runtime_lock_owner(owner_fd: int, token: str):
    record = (
        json.dumps(
            {
                "pid": os.getpid(),
                "token": token,
                "lease_expires_ms": int(
                    (time.time() + _RUNTIME_LOCK_LEASE_SECONDS) * 1000
                ),
            },
            separators=(",", ":"),
        )
        + "\n"
    ).encode()
    os.ftruncate(owner_fd, 0)
    os.lseek(owner_fd, 0, os.SEEK_SET)
    offset = 0
    while offset < len(record):
        offset += os.write(owner_fd, record[offset:])
    os.fsync(owner_fd)


def _assert_runtime_lock_owner(lock):
    lock_path, token, owner_fd = lock
    descriptor_status = os.fstat(owner_fd)
    canonical_status = _runtime_lock_status(lock_path)
    owner = _read_runtime_lock_owner(lock_path)
    if (
        not _same_runtime_lock_object(descriptor_status, canonical_status)
        or owner is None
        or owner[:2] != (os.getpid(), token)
    ):
        raise RuntimeError("package-cache publication lock ownership changed")


def _open_validated_runtime_lock(lock_path: Path, token: str, expected_status):
    """Reopen a lock name and prove it still names the expected owner object."""
    try:
        owner_fd = os.open(lock_path, os.O_RDWR)
    except OSError as exc:
        raise RuntimeError(
            "package-cache publication lock ownership changed"
        ) from exc
    try:
        descriptor_status = os.fstat(owner_fd)
        canonical_status = _runtime_lock_status(lock_path)
        owner = _read_runtime_lock_owner(lock_path)
        if (
            not _same_runtime_lock_object(expected_status, descriptor_status)
            or not _same_runtime_lock_object(
                descriptor_status, canonical_status
            )
            or owner is None
            or owner[:2] != (os.getpid(), token)
        ):
            raise RuntimeError(
                "package-cache publication lock ownership changed"
            )
    except BaseException:
        os.close(owner_fd)
        raise
    return owner_fd


def _refresh_runtime_lock(lock):
    _assert_runtime_lock_owner(lock)
    _write_runtime_lock_owner(lock[2], lock[1])
    _assert_runtime_lock_owner(lock)


def _acquire_runtime_lock(directory: Path):
    token = secrets.token_hex(16)
    lock_path = directory / _RUNTIME_LOCK_NAME
    claim_path = lock_path.with_name(f"{lock_path.name}.claim-{token}")
    deadline = time.monotonic() + _RUNTIME_LOCK_WAIT_SECONDS
    contended = False
    while True:
        owner_fd = None
        try:
            owner_fd = os.open(
                claim_path,
                os.O_RDWR | os.O_CREAT | os.O_EXCL,
                0o600,
            )
            try:
                _write_runtime_lock_owner(owner_fd, token)
                if _runtime_lock_claim_observer is not None:
                    _runtime_lock_claim_observer()
                os.link(claim_path, lock_path)
                linked_status = os.fstat(owner_fd)
                if not _same_runtime_lock_object(
                    linked_status, _runtime_lock_status(lock_path)
                ):
                    raise RuntimeError(
                        "package-cache publication lock ownership changed"
                    )
                # Windows does not grant delete sharing to this descriptor.
                # Close it before removing the claim name, then reopen the
                # canonical name and revalidate identity plus owner record.
                os.close(owner_fd)
                owner_fd = None
                claim_path.unlink()
                owner_fd = _open_validated_runtime_lock(
                    lock_path, token, linked_status
                )
            except BaseException:
                if owner_fd is not None:
                    os.close(owner_fd)
                    owner_fd = None
                try:
                    claim_path.unlink()
                except OSError:
                    pass
                raise
            return (lock_path, token, owner_fd), contended
        except FileExistsError:
            retry, released_by_contender = _try_reclaim_runtime_lock(
                lock_path, token
            )
            contended = contended or released_by_contender
            if retry:
                continue
            contended = True
            if time.monotonic() >= deadline:
                raise RuntimeError(
                    "timed out waiting for package-cache publication lock"
                )
            time.sleep(_RUNTIME_LOCK_POLL_SECONDS)


def _release_runtime_lock(lock):
    lock_path, token, owner_fd = lock
    try:
        _assert_runtime_lock_owner(lock)
    except Exception:
        os.close(owner_fd)
        raise
    descriptor_status = os.fstat(owner_fd)
    # Path mutation while this descriptor is open fails on Windows. Close it,
    # then reopen the canonical name to prove no object or owner substitution
    # occurred before releasing the name.
    os.close(owner_fd)
    validated_fd = _open_validated_runtime_lock(
        lock_path, token, descriptor_status
    )
    os.close(validated_fd)
    released = lock_path.with_name(f"{lock_path.name}.released-{token}")
    os.rename(lock_path, released)
    released_status = _runtime_lock_status(released)
    try:
        validated_fd = _open_validated_runtime_lock(
            released, token, descriptor_status
        )
    except Exception:
        _restore_displaced_runtime_lock(released, lock_path, released_status)
        raise
    os.close(validated_fd)
    released.unlink()


# A grouped backup is a small crash journal. The retired marker separates a
# partial retirement from partial publication; cleanup-only makes deletion
# retryable after the destination has been accepted or restored.
def _runtime_backup_target_name(name: str, binary_name: str) -> bool:
    return name == binary_name


def _create_runtime_backup_directory(directory: Path) -> Path:
    for _ in range(128):
        backup = directory / f"{_RUNTIME_BACKUP_PREFIX}{secrets.token_hex(16)}"
        try:
            backup.mkdir(mode=0o700)
            return backup
        except FileExistsError:
            continue
    raise RuntimeError("could not reserve a package-cache backup transaction")


def _create_runtime_backup_marker(backup: Path, name: str):
    descriptor = os.open(backup / name, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
    try:
        os.fsync(descriptor)
    finally:
        os.close(descriptor)


def _inspect_runtime_backup(directory: Path, entry_name: str, binary_name: str):
    backup_path = directory / entry_name
    try:
        directory_status = backup_path.lstat()
    except OSError as exc:
        raise RuntimeError(
            f"refusing unsafe package-cache backup: {backup_path}"
        ) from exc
    if not stat.S_ISDIR(directory_status.st_mode) or stat.S_ISLNK(
        directory_status.st_mode
    ):
        raise RuntimeError(f"refusing unsafe package-cache backup: {backup_path}")
    backup = {
        "path": backup_path,
        "retired": False,
        "cleanup_only": False,
        "files": {},
    }
    for candidate in sorted(backup_path.iterdir(), key=lambda path: path.name):
        status = candidate.lstat()
        if candidate.name in (
            _RUNTIME_BACKUP_RETIRED_MARKER,
            _RUNTIME_BACKUP_CLEANUP_MARKER,
        ):
            if (
                not stat.S_ISREG(status.st_mode)
                or stat.S_ISLNK(status.st_mode)
                or status.st_nlink != 1
                or status.st_size != 0
            ):
                raise RuntimeError(
                    f"refusing unsafe package-cache backup marker: {candidate}"
                )
            if candidate.name == _RUNTIME_BACKUP_RETIRED_MARKER:
                backup["retired"] = True
            else:
                backup["cleanup_only"] = True
            continue
        if (
            not _runtime_backup_target_name(candidate.name, binary_name)
            or not stat.S_ISREG(status.st_mode)
            or stat.S_ISLNK(status.st_mode)
            or status.st_nlink != 1
        ):
            raise RuntimeError(
                f"refusing unsafe package-cache backup member: {candidate}"
            )
        backup["files"][candidate.name] = (candidate, _file_sha256(candidate))
    return backup


def _list_runtime_backups(directory: Path, binary_name: str):
    names = sorted(
        path.name
        for path in directory.iterdir()
        if _RUNTIME_BACKUP_RE.fullmatch(path.name) is not None
    )
    return [
        _inspect_runtime_backup(directory, name, binary_name) for name in names
    ]


def _current_runtime_targets(directory: Path, binary_name: str):
    targets = {}
    for target in sorted(directory.iterdir(), key=lambda path: path.name):
        if not _runtime_backup_target_name(target.name, binary_name):
            continue
        status = target.lstat()
        if (
            not stat.S_ISREG(status.st_mode)
            or stat.S_ISLNK(status.st_mode)
            or status.st_nlink != 1
        ):
            raise RuntimeError(f"refusing unsafe package-cache target: {target}")
        targets[target.name] = target
    return targets


def _runtime_set_ready_at(directory: Path, binary_name: str, verifier=None) -> bool:
    if _runtime_set_names(directory, binary_name) is None:
        return False
    if verifier is not None:
        try:
            verifier(directory / binary_name)
        except (OSError, RuntimeError):
            return False
    return True


def _cleanup_runtime_backup(backup, lock):
    _assert_runtime_lock_owner(lock)
    if not backup["cleanup_only"]:
        _create_runtime_backup_marker(
            backup["path"], _RUNTIME_BACKUP_CLEANUP_MARKER
        )
        backup["cleanup_only"] = True
    for name in sorted(backup["files"]):
        _assert_runtime_lock_owner(lock)
        member, digest = backup["files"][name]
        if not _path_matches_digest(member, digest):
            raise RuntimeError(
                f"package-cache backup member changed during cleanup: {name}"
            )
        _assert_runtime_lock_owner(lock)
        member.unlink()
    if backup["retired"]:
        _assert_runtime_lock_owner(lock)
        (backup["path"] / _RUNTIME_BACKUP_RETIRED_MARKER).unlink()
    _assert_runtime_lock_owner(lock)
    (backup["path"] / _RUNTIME_BACKUP_CLEANUP_MARKER).unlink()
    backup["path"].rmdir()


def _copy_runtime_backup_file(
    member: Path, target: Path, expected_digest: str, executable: bool, lock
):
    descriptor, staged_name = tempfile.mkstemp(
        dir=str(target.parent), prefix=".cbm-runtime-recovery-"
    )
    staged = Path(staged_name)
    last_refresh = time.monotonic()
    try:
        with member.open("rb") as source, os.fdopen(descriptor, "wb") as output:
            descriptor = None
            while True:
                block = source.read(1024 * 1024)
                if not block:
                    break
                output.write(block)
                if time.monotonic() - last_refresh >= _RUNTIME_LOCK_HEARTBEAT_SECONDS:
                    _refresh_runtime_lock(lock)
                    last_refresh = time.monotonic()
            output.flush()
            os.fsync(output.fileno())
        staged.chmod(0o755 if executable else 0o644)
        if _file_sha256(staged) != expected_digest:
            raise RuntimeError(
                "package-cache backup changed while it was being restored"
            )
        _assert_runtime_lock_owner(lock)
        os.replace(staged, target)
    finally:
        if descriptor is not None:
            os.close(descriptor)
        try:
            staged.unlink()
        except FileNotFoundError:
            pass


def _reconcile_runtime_backups(directory: Path, binary_name: str, verifier, lock):
    _refresh_runtime_lock(lock)
    backups = _list_runtime_backups(directory, binary_name)
    for backup in [item for item in backups if item["cleanup_only"]]:
        _cleanup_runtime_backup(backup, lock)
    backups = [item for item in backups if not item["cleanup_only"]]
    if not backups:
        return

    if _runtime_set_ready_at(directory, binary_name, verifier):
        for backup in backups:
            _cleanup_runtime_backup(backup, lock)
        return
    if not backups:
        return

    for backup in [
        item
        for item in backups
        if not item["retired"] and not item["files"]
    ]:
        _cleanup_runtime_backup(backup, lock)
    backups = [
        item for item in backups if item["retired"] or item["files"]
    ]
    if not backups:
        return
    if len(backups) != 1:
        raise RuntimeError(
            "multiple package-cache backup transactions require manual recovery"
        )

    backup = backups[0]
    targets = _current_runtime_targets(directory, binary_name)
    if not backup["retired"]:
        for name, (_, digest) in backup["files"].items():
            target = targets.get(name)
            if target is not None and not _path_matches_digest(target, digest):
                raise RuntimeError(
                    f"package-cache backup conflicts with current target: {name}"
                )
    else:
        binary_target = targets.pop(binary_name, None)
        if binary_target is not None:
            _assert_runtime_lock_owner(lock)
            binary_target.unlink()
        for name in sorted(targets):
            _assert_runtime_lock_owner(lock)
            targets[name].unlink()

    restore_names = sorted(
        name for name in backup["files"] if name != binary_name
    )
    if binary_name in backup["files"]:
        restore_names.append(binary_name)
    for name in restore_names:
        member, digest = backup["files"][name]
        target = directory / name
        if not _path_matches_digest(target, digest):
            _copy_runtime_backup_file(
                member, target, digest, name == binary_name, lock
            )
    for name, (_, digest) in backup["files"].items():
        if not _path_matches_digest(directory / name, digest):
            raise RuntimeError(
                f"package-cache backup restoration failed: {name}"
            )
    _cleanup_runtime_backup(backup, lock)


def _path_matches_digest(path: Path, expected: str) -> bool:
    try:
        return _regular_file(path) and _file_sha256(path) == expected
    except OSError:
        return False


def _publish_runtime_set(
    staged_paths,
    dest: Path,
    binary_name: str,
    replace_file=None,
    verifier=None,
):
    """Publish sidecars first, retaining exact-byte backups for recovery."""
    runtime_names = _staged_runtime_names(staged_paths, binary_name)
    if replace_file is None:
        replace_file = os.replace
    _require_safe_runtime_directory(dest.parent)
    initial_fingerprint = _runtime_set_fingerprint(dest.parent, binary_name)
    lock, contended = _acquire_runtime_lock(dest.parent)
    operation_error = None
    try:
        _refresh_runtime_lock(lock)
        _reconcile_runtime_backups(dest.parent, binary_name, verifier, lock)
        # Preserve a complete set that appeared or changed while this publisher
        # waited. An unchanged pre-existing set may still be repaired/replaced,
        # with its bytes retained below for rollback.
        locked_fingerprint = _runtime_set_fingerprint(dest.parent, binary_name)
        if (
            locked_fingerprint is not None
            and (contended or locked_fingerprint != initial_fingerprint)
        ):
            return

        backup_directory = None
        try:
            backup_directory = _create_runtime_backup_directory(dest.parent)
            retire_names = (binary_name,)
            retired = set()
            # Retire the executable first: until the final rename, readiness is false.
            for name in retire_names:
                _assert_runtime_lock_owner(lock)
                if name in retired:
                    continue
                retired.add(name)
                target = dest.parent / name
                try:
                    status = target.lstat()
                except FileNotFoundError:
                    continue
                if (
                    not stat.S_ISREG(status.st_mode)
                    or stat.S_ISLNK(status.st_mode)
                    or status.st_nlink != 1
                ):
                    raise RuntimeError(
                        f"refusing unsafe package-cache target: {target}"
                    )
                replace_file(target, backup_directory / name)
            _assert_runtime_lock_owner(lock)
            _create_runtime_backup_marker(
                backup_directory, _RUNTIME_BACKUP_RETIRED_MARKER
            )

            for name in runtime_names:
                _assert_runtime_lock_owner(lock)
                target = dest.parent / name
                try:
                    replace_file(staged_paths[name], target)
                    staged_paths.pop(name)
                except OSError as publish_error:
                    if not _files_equal_sha256(staged_paths[name], target):
                        raise publish_error
            if _runtime_set_names(dest.parent, binary_name) is None:
                raise RuntimeError("published package cache is incomplete")
            if verifier is not None:
                verifier(dest.parent / binary_name)
            _assert_runtime_lock_owner(lock)
        except Exception as publication_error:
            _assert_runtime_lock_owner(lock)
            # Preserve a complete non-cooperating winner; never delete its bytes.
            preserve_winner = _runtime_set_ready_at(dest.parent, binary_name, verifier)
            if backup_directory is not None:
                try:
                    _reconcile_runtime_backups(dest.parent, binary_name, verifier, lock)
                except Exception as recovery_error:
                    raise RuntimeError(
                        f"{publication_error}; package-cache recovery failed: "
                        f"{recovery_error}"
                    ) from recovery_error
            if preserve_winner:
                return
            raise
        else:
            backup = _inspect_runtime_backup(
                dest.parent, backup_directory.name, binary_name
            )
            _cleanup_runtime_backup(backup, lock)
    except Exception as exc:
        operation_error = exc
        raise
    finally:
        try:
            _release_runtime_lock(lock)
        except Exception:
            if operation_error is None:
                raise


def _download(version: str) -> Path:
    os_name = _os_name()
    arch = _arch()
    ext = "zip" if os_name == "windows" else "tar.gz"
    # Linux ships a fully-static "-portable" build; the standard linux binary
    # dynamically links glibc 2.38+ and fails on older distros. macOS/Windows
    # have no such variant. Keep in sync with install.sh / install.js / cli.c.
    portable = "-portable" if os_name == "linux" else ""
    archive = f"codebase-memory-mcp-{os_name}-{arch}{portable}.{ext}"
    base, loopback = _download_base(version)
    url = f"{base}/{archive}"
    _validate_download_url(url, loopback)

    dest = _bin_path(version)
    dest.parent.mkdir(parents=True, exist_ok=True)

    print(
        f"codebase-memory-mcp: downloading v{version} for {os_name}/{arch}...",
        file=sys.stderr,
    )

    with tempfile.TemporaryDirectory() as tmp:
        tmp_archive = os.path.join(tmp, f"cbm.{ext}")
        try:
            _download_file(url, tmp_archive, loopback)
        except (OSError, RuntimeError, urllib.error.URLError) as e:
            sys.exit(
                f"codebase-memory-mcp: download failed ({e})\n"
                f"URL: {url}\n"
                f"See https://github.com/{REPO}/releases for available versions."
            )

        _verify_checksum(tmp_archive, archive, base, loopback)
        _require_regular_archive(tmp_archive)

        bin_name = (
            _WINDOWS_BINARY_NAME if os_name == "windows" else "codebase-memory-mcp"
        )
        extraction_names = (bin_name,)
        archive_names = (
            _WINDOWS_ARCHIVE_NAMES
            if os_name == "windows"
            else _UNIX_ARCHIVE_NAMES
        )
        if ext == "tar.gz":
            import tarfile
            with tarfile.open(tmp_archive) as tf:
                runtime_names = _safe_extract_tar(
                    tf,
                    tmp,
                    archive_names,
                    extraction_names,
                )
        else:
            import zipfile
            with zipfile.ZipFile(tmp_archive) as zf:
                runtime_names = _safe_extract_zip(
                    zf,
                    tmp,
                    archive_names,
                    extraction_names,
                )

        extracted_paths = {}
        for name in runtime_names:
            extracted_path = Path(tmp) / name
            if not _regular_file(extracted_path):
                sys.exit(
                    f"codebase-memory-mcp: required runtime member not found after "
                    f"extraction: {name}"
                )
            if name == bin_name:
                current = extracted_path.stat().st_mode
                extracted_path.chmod(
                    current | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH
                )
            extracted_paths[name] = extracted_path
        if _runtime_set_names(Path(tmp), bin_name) is None:
            sys.exit(
                "codebase-memory-mcp: extracted runtime set failed content "
                "verification"
            )
        try:
            _verify_candidate(extracted_paths[bin_name])
        except (OSError, RuntimeError) as exc:
            sys.exit(f"codebase-memory-mcp: {exc}")

        staged_paths = {}
        try:
            for name in runtime_names:
                staged_suffix = (
                    ".tmp.exe"
                    if sys.platform == "win32" and name == bin_name
                    else ".tmp"
                )
                with tempfile.NamedTemporaryFile(
                    dir=str(dest.parent),
                    prefix=f".{name}.",
                    suffix=staged_suffix,
                    delete=False,
                ) as staged:
                    staged_path = Path(staged.name)
                shutil.copy2(extracted_paths[name], staged_path)
                if name == bin_name:
                    staged_mode = staged_path.stat().st_mode
                    staged_path.chmod(
                        staged_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH
                    )
                staged_paths[name] = staged_path

            # A crash during publication leaves an incomplete cache, which
            # readiness rejects and the next invocation repairs.
            _publish_runtime_set(
                staged_paths,
                dest,
                bin_name,
                verifier=_verify_candidate,
            )
            _verify_candidate(dest)
        except (OSError, RuntimeError) as exc:
            sys.exit(f"codebase-memory-mcp: {exc}")
        finally:
            for staged_path in staged_paths.values():
                try:
                    staged_path.unlink()
                except OSError:
                    pass

    return dest


def main() -> None:
    version = _version()
    bin_path = _bin_path(version)
    mutation = _runtime_mutation_action(sys.argv[1:])
    if mutation == "update":
        print(
            "This PyPI copy is maintained by pip. Update it with "
            '"python -m pip install --upgrade codebase-memory-mcp". '
            "For a managed standalone installation, run "
            '"codebase-memory-mcp install --yes".',
            file=sys.stderr,
        )
        raise SystemExit(2)

    cache_ready = _runtime_set_ready_locked(version)
    if not cache_ready:
        bin_path = _download(version)

    execution_path = _execution_path(bin_path, sys.platform)

    # args is a list (not a shell string), so exec/subprocess treat each
    # element as a discrete argv entry — no shell interpretation, no
    # injection vector. sys.argv forwarding is the whole point of this
    # shim, so tainted-input suppression is intentional.
    forwarded = _native_args(sys.argv[1:])
    args = [str(execution_path)] + forwarded

    if mutation in ("install", "uninstall"):
        result = _run_cache_sensitive_mutation(version, execution_path, forwarded)
        if sys.platform == "win32" and result != 0 and mutation == "uninstall":
            print(
                'This PyPI Windows copy is portable. Use '
                '"python -m pip uninstall codebase-memory-mcp" for package maintenance. '
                "To create or repair a managed standalone installation, run "
                '"codebase-memory-mcp install --yes".',
                file=sys.stderr,
            )
        raise SystemExit(result)

    if sys.platform != "win32":
        os.execv(str(execution_path), args)  # noqa: S606 — list form, no shell
    else:
        result = subprocess.run(args)  # noqa: S603 — list form, no shell=True
        sys.exit(result.returncode)


def _runtime_mutation_action(args):
    for argument in args:
        if argument in ("--help", "-h", "--version"):
            return None
        if argument.startswith("-"):
            continue
        if argument in ("install", "update", "uninstall"):
            return argument
        if argument in ("cli", "hook-augment", "config"):
            return None
        return None
    return None


def _default_managed_install_dir() -> Path:
    if sys.platform != "win32":
        return Path.home() / ".local" / "bin"
    local_app_data = Path(
        os.environ.get("LOCALAPPDATA", Path.home() / "AppData" / "Local")
    )
    return local_app_data / "Programs" / "codebase-memory-mcp"


def _native_args(args):
    result = list(args)
    if _runtime_mutation_action(result) == "uninstall" and not any(
        argument == "--dir" or argument.startswith("--dir=")
        for argument in result
    ):
        result.extend(("--dir", str(_default_managed_install_dir())))
    return result


def _run_cache_sensitive_mutation(version: str, executable: Path, args) -> int:
    directory = executable.parent
    _require_safe_runtime_directory(directory)
    lock, _ = _acquire_runtime_lock(directory)
    stop = threading.Event()
    heartbeat_errors = []

    def heartbeat():
        while not stop.wait(_RUNTIME_LOCK_HEARTBEAT_SECONDS):
            try:
                _refresh_runtime_lock(lock)
            except Exception as exc:  # surfaced on the launcher thread
                heartbeat_errors.append(exc)
                return

    try:
        _refresh_runtime_lock(lock)
        if not _runtime_set_ready(version, _verify_candidate):
            raise RuntimeError(
                "cached runtime assets changed before mutation launch"
            )
        thread = threading.Thread(
            name="cbm-cache-lock-heartbeat", target=heartbeat, daemon=True
        )
        thread.start()
        process = subprocess.Popen(  # noqa: S603 — argv list, no shell
            [str(executable), *args]
        )
        while process.poll() is None:
            if heartbeat_errors:
                process.terminate()
                process.wait()
                raise RuntimeError(
                    f"package-cache lock lost during mutation: "
                    f"{heartbeat_errors[0]}"
                )
            time.sleep(0.05)
        return process.returncode
    finally:
        stop.set()
        if "thread" in locals():
            thread.join(timeout=1)
        _release_runtime_lock(lock)