python-delphi-lsp 3.6.0__cp310-abi3-win_amd64.whl

delphi_lsp/agent_cache.py

@@ -0,0 +1,1574 @@
+from __future__ import annotations
+
+import argparse
+import contextlib
+import hmac
+import json
+import math
+import os
+import re
+import secrets
+import select
+import signal
+import socket
+import stat
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+from collections.abc import Callable, Collection, Mapping
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, fields, is_dataclass, replace
+from functools import lru_cache
+from pathlib import Path
+from types import FrameType, ModuleType
+
+from watchfiles import watch
+
+from ._version import __version__
+from .agent_context import AgentContext
+from .agent_protocol import AgentProtocolError
+from .project_config import ProjectPathConfig, load_project_path_config
+from .project_discovery import SKIP_DIRS
+
+DEFAULT_MAX_MEMORY_BYTES = 512 * 1024**2
+DEFAULT_MAX_DISK_CACHE_BYTES = 512 * 1024**2
+WARNING_THRESHOLD_PERCENT = 80
+DAEMON_SCHEMA = 2
+DEFAULT_IDLE_TIMEOUT = 1800
+DEFAULT_STARTUP_TIMEOUT = 120.0
+_MAX_MESSAGE_BYTES = 1024 * 1024
+_CONNECTION_TIMEOUT = 2.0
+_PREAUTH_CONNECTION_TIMEOUT = 0.25
+_CONNECTION_WORKERS = 8
+_CLIENT_RESPONSE_TIMEOUT = 120.0
+_MAX_CLIENT_RESPONSE_TIMEOUT = 600.0
+_CLIENT_SECONDS_PER_SOURCE = 0.25
+_MEMORY_SIZE = re.compile(r"^(?P<count>[1-9][0-9]*)(?P<suffix>[KMG]?)$", re.IGNORECASE)
+_STARTUP_DIAGNOSTIC_BYTES = 16 * 1024
+_STARTUP_TOKEN_RE = re.compile(r"(?i)(token\b[^\n\r]*?:?\s*['\"]?[A-Za-z0-9_-]+['\"]?|\b[a-zA-Z0-9_-]{32,})")
+_START_LOCK_INCOMPLETE_GRACE_SECONDS = 1.0
+_CACHE_REVISION_CHECK_INTERVAL_SECONDS = 3600.0
+_WATCHER_READY_TIMEOUT_SECONDS = 1.0
+_WATCHER_READY_POLL_MILLISECONDS = 50
+_STOP_TIMEOUT_SECONDS = 15.0
+_STOP_SIGNAL_DELAY_SECONDS = 3.0
+_STOP_FORCE_TIMEOUT_SECONDS = 2.0
+_WATCHED_SUFFIXES = frozenset(
+    {".pas", ".pp", ".inc", ".dpr", ".dpk", ".dproj", ".cfg"}
+)
+_PROCESS_START_LOCKS_GUARD = threading.Lock()
+_PROCESS_START_LOCKS: dict[str, tuple[threading.Lock, int]] = {}
+
+
+def current_process_rss_bytes() -> int:
+    """Return the current resident set size, or zero when unavailable."""
+    try:
+        if sys.platform == "darwin":
+            return _darwin_process_rss_bytes()
+        if sys.platform.startswith("linux"):
+            statm = Path("/proc/self/statm").read_text(encoding="ascii").split()
+            return int(statm[1]) * int(os.sysconf("SC_PAGE_SIZE"))
+        if os.name == "nt":
+            return _windows_process_rss_bytes()
+    except Exception:
+        pass
+    return 0
+
+
+def _darwin_process_rss_bytes() -> int:
+    import ctypes
+
+    class TimeValue(ctypes.Structure):
+        _fields_ = [("seconds", ctypes.c_int), ("microseconds", ctypes.c_int)]
+
+    class MachTaskBasicInfo(ctypes.Structure):
+        _fields_ = [
+            ("virtual_size", ctypes.c_uint64),
+            ("resident_size", ctypes.c_uint64),
+            ("resident_size_max", ctypes.c_uint64),
+            ("user_time", TimeValue),
+            ("system_time", TimeValue),
+            ("policy", ctypes.c_int),
+            ("suspend_count", ctypes.c_int),
+        ]
+
+    library = ctypes.CDLL(None)
+    library.mach_task_self.restype = ctypes.c_uint
+    library.task_info.argtypes = (
+        ctypes.c_uint,
+        ctypes.c_int,
+        ctypes.c_void_p,
+        ctypes.POINTER(ctypes.c_uint),
+    )
+    library.task_info.restype = ctypes.c_int
+    info = MachTaskBasicInfo()
+    count = ctypes.c_uint(ctypes.sizeof(info) // ctypes.sizeof(ctypes.c_int))
+    result = library.task_info(
+        library.mach_task_self(),
+        20,
+        ctypes.byref(info),
+        ctypes.byref(count),
+    )
+    return int(info.resident_size) if result == 0 else 0
+
+
+def _windows_process_rss_bytes() -> int:
+    import ctypes
+    from ctypes import wintypes
+
+    class ProcessMemoryCounters(ctypes.Structure):
+        _fields_ = [
+            ("cb", wintypes.DWORD),
+            ("PageFaultCount", wintypes.DWORD),
+            ("PeakWorkingSetSize", ctypes.c_size_t),
+            ("WorkingSetSize", ctypes.c_size_t),
+            ("QuotaPeakPagedPoolUsage", ctypes.c_size_t),
+            ("QuotaPagedPoolUsage", ctypes.c_size_t),
+            ("QuotaPeakNonPagedPoolUsage", ctypes.c_size_t),
+            ("QuotaNonPagedPoolUsage", ctypes.c_size_t),
+            ("PagefileUsage", ctypes.c_size_t),
+            ("PeakPagefileUsage", ctypes.c_size_t),
+        ]
+
+    counters = ProcessMemoryCounters()
+    counters.cb = ctypes.sizeof(counters)
+    process = ctypes.windll.kernel32.GetCurrentProcess()
+    if not ctypes.windll.psapi.GetProcessMemoryInfo(
+        process,
+        ctypes.byref(counters),
+        counters.cb,
+    ):
+        return 0
+    return int(counters.WorkingSetSize)
+
+
+def estimate_deep_size(value: object) -> int:
+    """Estimate the memory retained by an owned object graph.
+
+    The traversal is intentionally best-effort: unsupported or opaque values
+    still count themselves, but do not cause cache accounting to fail.
+    """
+    total = 0
+    seen: set[int] = set()
+    pending: list[object] = [value]
+
+    while pending:
+        current = pending.pop()
+        if isinstance(current, (ModuleType, type)) or callable(current):
+            continue
+        identifier = id(current)
+        if identifier in seen:
+            continue
+        seen.add(identifier)
+        try:
+            total += sys.getsizeof(current)
+        except Exception:
+            pass
+
+        try:
+            pending.extend(_children(current))
+        except Exception:
+            continue
+    return total
+
+
+@dataclass
+class CacheStats:
+    requests: int = 0
+    warm_hits: int = 0
+    rebuilds: int = 0
+    invalidations: int = 0
+    evictions: int = 0
+    parallel_fallbacks: int = 0
+
+
+@dataclass(frozen=True)
+class BudgetResult:
+    retained_bytes: int
+    utilization_percent: float
+    peak_utilization_percent: float
+    warning_active: bool
+    warning_triggered: bool
+    compacted: bool
+
+
+@dataclass(frozen=True)
+class CacheBudget:
+    max_bytes: int = DEFAULT_MAX_MEMORY_BYTES
+    warning_percent: int = WARNING_THRESHOLD_PERCENT
+
+    def __post_init__(self) -> None:
+        if self.max_bytes <= 0:
+            raise ValueError("max_bytes must be greater than zero.")
+        if not 0 < self.warning_percent <= 100:
+            raise ValueError("warning_percent must be between 1 and 100.")
+
+    def enforce(
+        self,
+        *,
+        measure: Callable[[], int],
+        evict_auxiliary: Callable[[], None],
+        evict_navigation: Callable[[], None],
+    ) -> BudgetResult:
+        initial_retained = measure()
+        initial_utilization_percent = initial_retained * 100.0 / self.max_bytes
+        compacted = False
+        retained = initial_retained
+
+        if initial_retained > self.max_bytes:
+            evict_auxiliary()
+            compacted = True
+            retained = measure()
+            if retained > self.max_bytes:
+                evict_navigation()
+                retained = measure()
+
+        current_utilization_percent = retained * 100.0 / self.max_bytes
+        return BudgetResult(
+            retained_bytes=retained,
+            utilization_percent=current_utilization_percent,
+            peak_utilization_percent=initial_utilization_percent,
+            warning_active=current_utilization_percent >= self.warning_percent,
+            warning_triggered=initial_utilization_percent >= self.warning_percent,
+            compacted=compacted,
+        )
+
+
+def parse_memory_size(value: str) -> int:
+    match = _MEMORY_SIZE.fullmatch(value.strip())
+    if match is None:
+        raise ValueError("Memory size must be a positive integer with optional K, M, or G suffix.")
+
+    multiplier = {
+        "": 1,
+        "K": 1024,
+        "M": 1024**2,
+        "G": 1024**3,
+    }
+    return int(match.group("count")) * multiplier[match.group("suffix").upper()]
+
+
+def cache_warning(result: BudgetResult, max_bytes: int) -> str:
+    if not result.warning_triggered:
+        return ""
+
+    if result.compacted:
+        state = (
+            f"Warning: Delphi cache peaked at {result.peak_utilization_percent:.1f}% of the {max_bytes} byte budget; "
+            f"{result.retained_bytes} bytes remain retained after compaction."
+            f"{' Cache compacted.' if result.compacted else ''}"
+        )
+    else:
+        state = (
+            f"Warning: Delphi cache currently at {result.utilization_percent:.1f}% of the {max_bytes} byte budget; "
+            f"{result.retained_bytes} bytes retained."
+        )
+    return (
+        f"{state} "
+        "Increase --max-memory, stop unused daemons, or allow compact mode."
+    )
+
+
+def _children(value: object) -> tuple[object, ...]:
+    children: list[object] = []
+    if isinstance(value, Mapping):
+        try:
+            for key, item in value.items():
+                children.extend((key, item))
+        except Exception:
+            pass
+    elif isinstance(value, Collection) and not isinstance(value, (str, bytes, bytearray)):
+        try:
+            children.extend(value)
+        except Exception:
+            pass
+
+    is_dataclass_instance = is_dataclass(value) and not isinstance(value, type)
+    dataclass_field_names: frozenset[str] = frozenset()
+    if is_dataclass_instance:
+        try:
+            dataclass_fields = fields(value)
+        except Exception:
+            dataclass_fields = ()
+        dataclass_field_names = frozenset(field.name for field in dataclass_fields)
+        for field in dataclass_fields:
+            try:
+                children.append(getattr(value, field.name))
+            except Exception:
+                continue
+    else:
+        try:
+            instance_values = vars(value)
+        except Exception:
+            instance_values = None
+        if isinstance(instance_values, Mapping):
+            children.extend(instance_values.values())
+
+    for slot in _slot_names(type(value)):
+        if slot in dataclass_field_names:
+            continue
+        try:
+            children.append(getattr(value, slot))
+        except Exception:
+            continue
+    return tuple(children)
+
+
+def _slot_names(value_type: type[object]) -> tuple[str, ...]:
+    names: list[str] = []
+    for base in value_type.__mro__:
+        try:
+            slots = getattr(base, "__slots__", ())
+        except Exception:
+            continue
+        if isinstance(slots, str):
+            slots = (slots,)
+        try:
+            names.extend(name for name in slots if isinstance(name, str))
+        except Exception:
+            continue
+    return tuple(names)
+
+
+@dataclass(frozen=True)
+class CacheMetadata:
+    schema: int
+    root: str
+    pid: int
+    port: int
+    token: str
+    version: str
+    project_file: str
+    max_memory_bytes: int
+    workers: int
+    idle_timeout: int
+    started_at: float
+    max_disk_cache_bytes: int = DEFAULT_MAX_DISK_CACHE_BYTES
+
+
+@dataclass(frozen=True)
+class CacheClientResponse:
+    payload: dict[str, object]
+    warning: str = ""
+
+
+class CacheClientError(RuntimeError):
+    def __init__(self, code: str, message: str) -> None:
+        self.code = code
+        self.message = message
+        super().__init__(message)
+
+
+class _RequestGuard:
+    def __init__(
+        self,
+        service: _CacheService,
+        connection: socket.socket,
+        *,
+        enforce_rss_budget: bool = True,
+    ) -> None:
+        self._service = service
+        self._connection = connection
+        self._enforce_rss_budget = enforce_rss_budget
+
+    def check(self) -> None:
+        if self._service.shutdown.is_set():
+            raise CacheClientError(
+                "request_cancelled",
+                "Cache request was cancelled.",
+            )
+        try:
+            readable, _, _ = select.select(
+                (self._connection,),
+                (),
+                (),
+                0,
+            )
+            if readable and not self._connection.recv(1, socket.MSG_PEEK):
+                raise CacheClientError(
+                    "client_disconnected",
+                    "Cache client disconnected.",
+                )
+        except CacheClientError:
+            raise
+        except (OSError, ValueError) as error:
+            raise CacheClientError(
+                "client_disconnected",
+                "Cache client disconnected.",
+            ) from error
+        if (
+            self._enforce_rss_budget
+            and self._service._measure_retained_bytes()
+            > self._service.metadata.max_memory_bytes
+        ):
+            raise CacheClientError(
+                "memory_budget_exceeded",
+                "Cache request exceeded the configured retained-memory budget.",
+            )
+
+
+def cache_metadata_path(root: str | Path) -> Path:
+    return Path(root).resolve() / ".delphi-lsp" / "agent-cache" / "daemon.json"
+
+
+def _safe_metadata_path(root: str | Path, *, create: bool = False) -> Path:
+    root_path = Path(root).resolve()
+    for path in (root_path / ".delphi-lsp", root_path / ".delphi-lsp" / "agent-cache"):
+        if path.exists() and path.is_symlink():
+            raise CacheClientError("unsafe_metadata", "Cache metadata path is unsafe.")
+        if create:
+            path.mkdir(mode=0o700, exist_ok=True)
+            if os.name != "nt":
+                os.chmod(path, 0o700)
+    result = root_path / ".delphi-lsp" / "agent-cache" / "daemon.json"
+    if result.exists() and result.is_symlink():
+        raise CacheClientError("unsafe_metadata", "Cache metadata path is unsafe.")
+    return result
+
+
+def _safe_navigation_cache_path(root: str | Path, *, create: bool = False) -> Path:
+    parent = _safe_metadata_path(root, create=create).parent
+    result = parent / "navigation-v1"
+    if result.exists() and result.is_symlink():
+        raise CacheClientError("unsafe_metadata", "Navigation cache path is unsafe.")
+    if create:
+        result.mkdir(mode=0o700, exist_ok=True)
+        if os.name != "nt":
+            os.chmod(result, 0o700)
+    return result
+
+
+def navigation_cache_path(root: str | Path, *, create: bool = False) -> Path:
+    """Return the validated persistent navigation-cache directory."""
+    return _safe_navigation_cache_path(root, create=create)
+
+
+def _metadata_mapping(metadata: CacheMetadata) -> dict[str, object]:
+    return {field.name: getattr(metadata, field.name) for field in fields(metadata)}
+
+
+def _write_metadata(metadata: CacheMetadata) -> None:
+    path = _safe_metadata_path(metadata.root, create=True)
+    data = json.dumps(_metadata_mapping(metadata), sort_keys=True, separators=(",", ":")).encode("utf-8")
+    descriptor, temporary = tempfile.mkstemp(prefix=".daemon-", dir=path.parent)
+    try:
+        if os.name != "nt":
+            os.fchmod(descriptor, 0o600)
+        with os.fdopen(descriptor, "wb") as stream:
+            stream.write(data)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temporary, path)
+        if os.name != "nt":
+            os.chmod(path, 0o600)
+    finally:
+        with contextlib.suppress(FileNotFoundError):
+            os.unlink(temporary)
+
+
+def _read_metadata_record(root: str | Path) -> object | None:
+    path = _safe_metadata_path(root)
+    if not path.exists():
+        return None
+    try:
+        flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)
+        descriptor = os.open(path, flags)
+        try:
+            info = os.fstat(descriptor)
+            if os.name != "nt" and (not stat.S_ISREG(info.st_mode) or info.st_uid != os.getuid() or info.st_mode & 0o077):
+                raise CacheClientError("unsafe_metadata", "Cache metadata path is unsafe.")
+            raw = json.loads(os.read(descriptor, _MAX_MESSAGE_BYTES).decode("utf-8"))
+        finally:
+            os.close(descriptor)
+    except CacheClientError:
+        raise
+    except (OSError, ValueError, UnicodeError):
+        return None
+    return raw
+
+
+def _read_metadata(root: str | Path) -> CacheMetadata | None:
+    raw = _read_metadata_record(root)
+    required = {field.name for field in fields(CacheMetadata)}
+    legacy_required = required - {"max_disk_cache_bytes"}
+    if not isinstance(raw, dict) or frozenset(raw) not in {
+        frozenset(required),
+        frozenset(legacy_required),
+    }:
+        return None
+    if "max_disk_cache_bytes" not in raw:
+        raw = {**raw, "max_disk_cache_bytes": DEFAULT_MAX_DISK_CACHE_BYTES}
+    values = tuple(
+        raw[name]
+        for name in (
+            "schema",
+            "root",
+            "pid",
+            "port",
+            "token",
+            "version",
+            "project_file",
+            "max_memory_bytes",
+            "workers",
+            "idle_timeout",
+            "started_at",
+            "max_disk_cache_bytes",
+        )
+    )
+    if (type(values[0]) is not int or values[0] != DAEMON_SCHEMA or not isinstance(values[1], str)
+            or type(values[2]) is not int or values[2] <= 0 or type(values[3]) is not int or not 0 < values[3] < 65536
+            or not isinstance(values[4], str) or len(values[4]) < 32 or not isinstance(values[5], str)
+            or not isinstance(values[6], str) or type(values[7]) is not int or values[7] <= 0
+            or type(values[8]) is not int or not 0 <= values[8] <= 32
+            or type(values[9]) is not int or values[9] <= 0 or type(values[10]) not in (int, float)
+            or type(values[11]) is not int or values[11] < 0):
+        return None
+    canonical = str(Path(root).resolve())
+    if values[1] != canonical:
+        return None
+    return CacheMetadata(*values)
+
+
+def _remove_incompatible_metadata_if_stale(root: str | Path) -> None:
+    path = _safe_metadata_path(root)
+    if not path.exists():
+        return
+    raw = _read_metadata_record(root)
+    canonical = str(Path(root).resolve())
+    pid = raw.get("pid") if isinstance(raw, dict) and raw.get("root") == canonical else None
+    if type(pid) is int and pid > 0 and _pid_alive(pid):
+        raise CacheClientError("unavailable", "Live cache daemon is unavailable.")
+    with contextlib.suppress(FileNotFoundError):
+        path.unlink()
+
+
+def _metadata_is_owned(metadata: CacheMetadata) -> bool:
+    current = _read_metadata(metadata.root)
+    return current is not None and current.pid == metadata.pid and hmac.compare_digest(current.token, metadata.token)
+
+
+def _remove_metadata_if_owned(metadata: CacheMetadata) -> None:
+    path = _safe_metadata_path(metadata.root)
+    if _metadata_is_owned(metadata):
+        with contextlib.suppress(FileNotFoundError):
+            path.unlink()
+
+
+def _windows_pid_alive(pid: int) -> bool:
+    import ctypes
+    from ctypes import wintypes
+
+    synchronize = 0x00100000
+    wait_timeout = 0x00000102
+    kernel32 = ctypes.windll.kernel32
+    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
+    handle = kernel32.OpenProcess(synchronize, False, pid)
+    if not handle:
+        return False
+    try:
+        return kernel32.WaitForSingleObject(handle, 0) == wait_timeout
+    finally:
+        kernel32.CloseHandle(handle)
+
+
+def _pid_alive(pid: int) -> bool:
+    if os.name == "nt":
+        return _windows_pid_alive(pid)
+    try:
+        os.kill(pid, 0)
+    except OSError:
+        return False
+    return True
+
+
+def _reap_child_if_exited(pid: int) -> bool:
+    waitpid = getattr(os, "waitpid", None)
+    nohang = getattr(os, "WNOHANG", None)
+    if not callable(waitpid) or nohang is None:
+        return False
+    try:
+        return waitpid(pid, nohang)[0] == pid
+    except (ChildProcessError, OSError):
+        return False
+
+
+def _start_lock_path(root: str | Path) -> Path:
+    return _safe_metadata_path(root, create=True).with_name("start.lock")
+
+
+def _start_lock_is_stale(path: Path) -> bool:
+    try:
+        age = max(0.0, time.time() - path.stat().st_mtime)
+    except OSError:
+        return True
+    try:
+        record = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError, UnicodeError):
+        return age >= _START_LOCK_INCOMPLETE_GRACE_SECONDS
+    owner = record.get("pid") if isinstance(record, dict) else None
+    if type(owner) is int and owner > 0:
+        return not _pid_alive(owner)
+    return age >= _START_LOCK_INCOMPLETE_GRACE_SECONDS
+
+
+@contextlib.contextmanager
+def _start_lock(root: str | Path, timeout: float):
+    path = _start_lock_path(root)
+    token = secrets.token_urlsafe(24)
+    deadline = time.monotonic() + timeout
+    while True:
+        try:
+            descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+            try:
+                payload = json.dumps({"pid": os.getpid(), "token": token, "started_at": time.time()}).encode("utf-8")
+                os.write(descriptor, payload)
+                os.fsync(descriptor)
+            finally:
+                os.close(descriptor)
+            break
+        except FileExistsError:
+            if _start_lock_is_stale(path):
+                with contextlib.suppress(FileNotFoundError):
+                    path.unlink()
+                continue
+            if time.monotonic() >= deadline:
+                raise CacheClientError("startup_locked", "Cache startup is busy.")
+            time.sleep(0.05)
+    try:
+        yield
+    finally:
+        try:
+            current = json.loads(path.read_text(encoding="utf-8"))
+            if isinstance(current, dict) and hmac.compare_digest(str(current.get("token", "")), token):
+                path.unlink()
+        except (OSError, ValueError, UnicodeError):
+            pass
+
+
+@contextlib.contextmanager
+def _process_start_lock(root: str | Path):
+    canonical = str(Path(root).resolve())
+    with _PROCESS_START_LOCKS_GUARD:
+        lock, users = _PROCESS_START_LOCKS.get(
+            canonical,
+            (threading.Lock(), 0),
+        )
+        _PROCESS_START_LOCKS[canonical] = (lock, users + 1)
+    try:
+        with lock:
+            yield
+    finally:
+        with _PROCESS_START_LOCKS_GUARD:
+            current_lock, current_users = _PROCESS_START_LOCKS[canonical]
+            if current_users == 1:
+                del _PROCESS_START_LOCKS[canonical]
+            else:
+                _PROCESS_START_LOCKS[canonical] = (
+                    current_lock,
+                    current_users - 1,
+                )
+
+
+def _client_exchange(metadata: CacheMetadata, request: dict[str, object]) -> CacheClientResponse:
+    try:
+        with socket.create_connection(("127.0.0.1", metadata.port), timeout=2) as connection:
+            connection.settimeout(_client_response_timeout(metadata, request))
+            request_without_token = {key: value for key, value in request.items() if key != "token"}
+            connection.sendall(json.dumps({"token": metadata.token, **request_without_token}, separators=(",", ":")).encode("utf-8") + b"\n")
+            response = _read_line(connection)
+    except OSError as error:
+        raise CacheClientError("unavailable", "Cache daemon is unavailable.") from error
+    try:
+        decoded = json.loads(response.decode("utf-8"))
+    except (UnicodeError, ValueError) as error:
+        raise CacheClientError("invalid_response", "Cache daemon returned an invalid response.") from error
+    if not isinstance(decoded, dict):
+        raise CacheClientError("invalid_response", "Cache daemon returned an invalid response.")
+    if "error" in decoded:
+        error = decoded["error"]
+        if isinstance(error, dict):
+            raise CacheClientError(str(error.get("code", "error")), str(error.get("message", "Cache request failed.")))
+        raise CacheClientError("error", "Cache request failed.")
+    payload = decoded.get("payload")
+    if not isinstance(payload, dict):
+        raise CacheClientError("invalid_response", "Cache daemon returned an invalid response.")
+    return CacheClientResponse(payload, str(decoded.get("warning", "")))
+
+
+def _client_response_timeout(
+    metadata: CacheMetadata,
+    request: Mapping[str, object],
+) -> float:
+    if request.get("action") in {"status", "stop"}:
+        return _CLIENT_RESPONSE_TIMEOUT
+    return min(
+        _MAX_CLIENT_RESPONSE_TIMEOUT,
+        _CLIENT_RESPONSE_TIMEOUT
+        + _workspace_source_count(metadata.root) * _CLIENT_SECONDS_PER_SOURCE,
+    )
+
+
+@lru_cache(maxsize=64)
+def _workspace_source_count(root: str) -> int:
+    count = 0
+    source_suffixes = {".pas", ".pp", ".inc", ".dpr", ".dpk"}
+    maximum_relevant_count = int(
+        (_MAX_CLIENT_RESPONSE_TIMEOUT - _CLIENT_RESPONSE_TIMEOUT)
+        / _CLIENT_SECONDS_PER_SOURCE
+    )
+    for _current, directories, files in os.walk(Path(root).expanduser().resolve()):
+        directories[:] = [
+            directory
+            for directory in directories
+            if directory not in SKIP_DIRS
+        ]
+        count += sum(
+            1
+            for file_name in files
+            if Path(file_name).suffix.casefold() in source_suffixes
+        )
+        if count >= maximum_relevant_count:
+            return maximum_relevant_count
+    return count
+
+
+def _read_line(connection: socket.socket) -> bytes:
+    chunks = bytearray()
+    while len(chunks) <= _MAX_MESSAGE_BYTES:
+        piece = connection.recv(min(65536, _MAX_MESSAGE_BYTES + 1 - len(chunks)))
+        if not piece:
+            break
+        chunks.extend(piece)
+        if b"\n" in piece:
+            line, _, _ = chunks.partition(b"\n")
+            return line
+    raise CacheClientError("invalid_response", "Cache daemon returned an invalid response.")
+
+
+def _truncate_and_sanitize_startup_diagnostics(raw: bytes, *, max_bytes: int = _STARTUP_DIAGNOSTIC_BYTES) -> str:
+    if not raw:
+        return ""
+    text = raw.decode("utf-8", "replace")
+    text = text.replace("\r\n", "\n").replace("\r", "\n")
+    if max_bytes > 0 and len(text) > max_bytes:
+        text = text[-max_bytes:]
+    text = re.sub(r"[\x00-\x09\x0b-\x1f\x7f-\x9f]", " ", text)
+    text = _STARTUP_TOKEN_RE.sub("<redacted>", text)
+    text = re.sub(r"\s+", " ", text).strip()
+    return text
+
+
+def _read_startup_tail(diagnostics: object, *, max_bytes: int = _STARTUP_DIAGNOSTIC_BYTES) -> bytes:
+    with contextlib.suppress(Exception):
+        diagnostics.seek(0, os.SEEK_END)
+        end = diagnostics.tell()
+        diagnostics.seek(max(0, end - max_bytes), os.SEEK_SET)
+        return diagnostics.read()
+    return b""
+
+
+def _daemon_process_options() -> dict[str, object]:
+    options: dict[str, object] = {
+        "stdin": subprocess.DEVNULL,
+        "stdout": subprocess.DEVNULL,
+    }
+    if os.name == "nt":
+        options["creationflags"] = (
+            subprocess.CREATE_NO_WINDOW
+            | subprocess.CREATE_NEW_PROCESS_GROUP
+        )
+    else:
+        options["start_new_session"] = True
+    return options
+
+
+class _CacheService:
+    def __init__(
+        self,
+        metadata: CacheMetadata,
+        *,
+        defer_context: bool = False,
+    ) -> None:
+        self.metadata = metadata
+        self._rss_baseline_bytes = current_process_rss_bytes()
+        self._context: AgentContext | None = None
+        self.context_ready = threading.Event()
+        self.watcher_ready = threading.Event()
+        self.watcher_failed = threading.Event()
+        self.budget = CacheBudget(metadata.max_memory_bytes)
+        self.stats = CacheStats()
+        self.lock = threading.Lock()
+        self._request_state_lock = threading.Lock()
+        self._active_requests = 0
+        self.started = time.monotonic()
+        self.last_activity = self.started
+        self.cache_state = "warming"
+        self.last_revision = ""
+        self.last_budget = BudgetResult(0, 0.0, 0.0, False, False, False)
+        self.prewarm_seconds = 0.0
+        self.startup_error = ""
+        self.shutdown = threading.Event()
+        self.prewarm_thread: threading.Thread | None = None
+        if not defer_context:
+            self._initialize_context()
+
+    @property
+    def context(self) -> AgentContext:
+        if self._context is None:
+            raise RuntimeError("Cache workspace is still being discovered.")
+        return self._context
+
+    def _initialize_context(self) -> AgentContext:
+        if self._context is None:
+            context = AgentContext.open(
+                self.metadata.root,
+                self.metadata.project_file or None,
+                workers=self.metadata.workers,
+                worker_memory_budget_bytes=self.metadata.max_memory_bytes,
+                revision_check_interval_seconds=_CACHE_REVISION_CHECK_INTERVAL_SECONDS,
+                navigation_cache_dir=navigation_cache_path(
+                    self.metadata.root,
+                    create=True,
+                ),
+                navigation_cache_max_bytes=self.metadata.max_disk_cache_bytes,
+            )
+            self._context = context
+            self.last_revision = context.workspace.workspace_revision
+        self.context_ready.set()
+        return self._context
+
+    def _measure_retained_bytes(self) -> int:
+        process_rss = current_process_rss_bytes()
+        process_growth = (
+            max(0, process_rss - self._rss_baseline_bytes)
+            if process_rss > 0 and self._rss_baseline_bytes > 0
+            else 0
+        )
+        return max(self.context.estimated_cache_bytes, process_growth)
+
+    def prewarm(self) -> None:
+        started = time.monotonic()
+        context = self._initialize_context()
+        try:
+            self.last_revision = context.prewarm_navigation()
+        except AgentProtocolError as error:
+            if error.code != "project_required":
+                raise
+        prewarm_rss = current_process_rss_bytes()
+        if prewarm_rss > 0:
+            # Parsing can leave a high allocator RSS watermark even though the
+            # retained navigation data is already covered by its own estimate.
+            # Track only subsequent, otherwise unaccounted-for RSS growth.
+            self._rss_baseline_bytes = prewarm_rss
+        self._enforce_budget()
+        self.prewarm_seconds = time.monotonic() - started
+        self.stats.parallel_fallbacks = context.parallel_stats.fallbacks
+
+    def start_prewarm(self) -> None:
+        def run() -> None:
+            try:
+                with self.lock:
+                    self.prewarm()
+            except Exception as error:
+                detail = _truncate_and_sanitize_startup_diagnostics(
+                    f"{type(error).__name__}: {error}".encode(
+                        "utf-8",
+                        "replace",
+                    )
+                )
+                self.startup_error = detail or type(error).__name__
+                self.cache_state = "failed"
+            finally:
+                self.context_ready.set()
+
+        self.prewarm_thread = threading.Thread(
+            target=run,
+            name="delphi-cache-prewarm",
+            daemon=True,
+        )
+        self.prewarm_thread.start()
+
+    def request(
+        self,
+        request: dict[str, object],
+        *,
+        cancel_check: Callable[[], None] | None = None,
+    ) -> CacheClientResponse:
+        action = request.get("action")
+        if action == "status":
+            warning = "" if request.get("_startup_probe") is True else self._consume_warning()
+            return CacheClientResponse(self.status(), warning)
+        if action == "stop":
+            self.shutdown.set()
+            return CacheClientResponse({"stopping": True})
+        if self.cache_state == "warming":
+            self.last_activity = time.monotonic()
+            raise CacheClientError(
+                "cache_warming",
+                "Cache is still warming. Retry after cache status reports ready.",
+            )
+        if self.cache_state == "failed":
+            detail = (
+                f" {self.startup_error}"
+                if self.startup_error
+                else ""
+            )
+            raise CacheClientError(
+                "cache_failed",
+                f"Cache workspace discovery or warm-up failed.{detail}",
+            )
+        self.watcher_ready.wait(timeout=_WATCHER_READY_TIMEOUT_SECONDS)
+        if self.watcher_failed.is_set():
+            self.context.invalidate_revision_cache()
+        with self._request_state_lock:
+            self._active_requests += 1
+        lock_acquired = False
+        try:
+            while not self.lock.acquire(timeout=0.05):
+                if self.shutdown.is_set():
+                    raise CacheClientError(
+                        "request_cancelled",
+                        "Cache request was cancelled.",
+                    )
+                if cancel_check is not None:
+                    cancel_check()
+            lock_acquired = True
+            if self.shutdown.is_set():
+                raise CacheClientError(
+                    "request_cancelled",
+                    "Cache request was cancelled.",
+                )
+            if cancel_check is not None:
+                cancel_check()
+            self.last_activity = time.monotonic()
+            before = self.last_revision
+            was_warm = self.context.navigation_cache_is_warm
+            request_aborted = False
+            try:
+                try:
+                    handled = (
+                        self.context.handle(request)
+                        if cancel_check is None
+                        else self.context.handle(
+                            request,
+                            cancel_check=cancel_check,
+                        )
+                    )
+                    if self.shutdown.is_set():
+                        raise CacheClientError(
+                            "request_cancelled",
+                            "Cache request was cancelled.",
+                        )
+                    if cancel_check is not None:
+                        cancel_check()
+                    response = handled.to_mapping()
+                except CacheClientError:
+                    request_aborted = True
+                    raise
+                except AgentProtocolError as error:
+                    raise CacheClientError(
+                        error.code,
+                        error.message,
+                    ) from None
+                except (OSError, UnicodeError):
+                    raise CacheClientError(
+                        "source_unavailable",
+                        "Source is unavailable.",
+                    ) from None
+                except Exception:
+                    raise CacheClientError(
+                        "internal_error",
+                        "Internal cache error.",
+                    ) from None
+            finally:
+                if not request_aborted and not self.shutdown.is_set():
+                    self._enforce_budget()
+            after = str(response["workspace_revision"])
+            self.last_revision = after
+            self.stats.requests += 1
+            if was_warm:
+                self.stats.warm_hits += 1
+            else:
+                self.stats.rebuilds += 1
+                self.stats.parallel_fallbacks += (
+                    self.context.parallel_stats.fallbacks
+                )
+            if before != after:
+                self.stats.invalidations += 1
+            return CacheClientResponse(
+                response,
+                self._consume_warning(),
+            )
+        finally:
+            if lock_acquired:
+                self.lock.release()
+            with self._request_state_lock:
+                self._active_requests -= 1
+
+    def _enforce_budget(self) -> None:
+        self.last_budget = self.budget.enforce(
+            measure=self._measure_retained_bytes,
+            evict_auxiliary=self.context.evict_auxiliary_caches,
+            evict_navigation=self.context.evict_navigation_caches,
+        )
+        if self.last_budget.compacted:
+            self.stats.evictions += 1
+            self.cache_state = "compact"
+        else:
+            self.cache_state = (
+                "warm"
+                if self.context.navigation_cache_is_warm
+                else "ready"
+            )
+
+    def _consume_warning(self) -> str:
+        warning = cache_warning(self.last_budget, self.budget.max_bytes)
+        if self.last_budget.warning_triggered and not self.last_budget.warning_active:
+            self.last_budget = replace(self.last_budget, warning_triggered=False)
+        return warning
+
+    def status(self) -> dict[str, object]:
+        now = time.monotonic()
+        idle = max(0.0, now - self.last_activity)
+        context = self._context
+        live_rss = current_process_rss_bytes()
+        current_bytes = (
+            live_rss
+            if live_rss > 0
+            else self.last_budget.retained_bytes
+        )
+        current_utilization = current_bytes * 100.0 / self.budget.max_bytes
+        peak_utilization = max(
+            self.last_budget.peak_utilization_percent,
+            current_utilization,
+        )
+        parallel_stats = (
+            context.parallel_stats
+            if context is not None
+            else None
+        )
+        with self._request_state_lock:
+            busy = self._active_requests > 0
+        return {
+            "pid": self.metadata.pid, "root": self.metadata.root, "project_file": self.metadata.project_file,
+            "version": self.metadata.version, "uptime": now - self.started, "idle_seconds": idle,
+            "last_activity_at": time.time() - idle,
+            "max_memory_bytes": self.budget.max_bytes, "current_bytes": current_bytes,
+            "current_utilization_percent": current_utilization,
+            "peak_utilization_percent": peak_utilization,
+            "warning_active": current_utilization >= self.budget.warning_percent,
+            "warning_threshold_percent": WARNING_THRESHOLD_PERCENT,
+            "cache_state": self.cache_state, "requests": self.stats.requests, "warm_hits": self.stats.warm_hits,
+            "rebuilds": self.stats.rebuilds, "invalidations": self.stats.invalidations, "evictions": self.stats.evictions,
+            "workers_configured": "auto" if self.metadata.workers == 0 else self.metadata.workers,
+            "workers_effective": parallel_stats.effective_workers if parallel_stats else 0,
+            "parallel_files_completed": parallel_stats.files_completed if parallel_stats else 0,
+            "prewarm_seconds": self.prewarm_seconds,
+            "parallel_seconds": parallel_stats.elapsed_seconds if parallel_stats else 0.0,
+            "parallel_fallbacks": self.stats.parallel_fallbacks,
+            "navigation_disk_hits": context.navigation_disk_hits if context else 0,
+            "navigation_disk_misses": context.navigation_disk_misses if context else 0,
+            "max_disk_cache_bytes": self.metadata.max_disk_cache_bytes,
+            "cpg_cache_entries": context.cpg_cache_entries if context else 0,
+            "cpg_cache_bytes": context.cpg_cache_bytes if context else 0,
+            "idle_timeout": self.metadata.idle_timeout, "idle_remaining": max(0.0, self.metadata.idle_timeout - idle),
+            "workspace_revision": self.last_revision,
+            "startup_error": self.startup_error,
+            "watcher_active": not self.watcher_failed.is_set(),
+            "busy": busy,
+        }
+
+
+def _watch_filter(_change: object, path: str) -> bool:
+    return Path(path).suffix.casefold() in _WATCHED_SUFFIXES
+
+
+def _workspace_watch_filter(
+    root: str | Path,
+    project_config: ProjectPathConfig | None,
+) -> Callable[[object, str], bool]:
+    root_path = Path(root).expanduser().resolve()
+
+    def include(change: object, path: str) -> bool:
+        candidate = Path(path)
+        try:
+            relative = candidate.relative_to(root_path)
+        except ValueError:
+            return False
+        if any(part in SKIP_DIRS for part in relative.parts):
+            return False
+        if (
+            project_config is not None
+            and project_config.excludes_workspace_path(candidate)
+        ):
+            return False
+        return _watch_filter(change, path)
+
+    return include
+
+
+def watch_workspace_changes(
+    root: str | Path,
+    *,
+    stop_event: threading.Event,
+    on_change: Callable[[], None],
+    on_ready: Callable[[], None] | None = None,
+    watch_filter: Callable[[object, str], bool] | None = None,
+) -> None:
+    ready = False
+    try:
+        for changes in watch(
+            root,
+            watch_filter=watch_filter or _watch_filter,
+            stop_event=stop_event,
+            debounce=50,
+            step=20,
+            rust_timeout=_WATCHER_READY_POLL_MILLISECONDS,
+            yield_on_timeout=True,
+            recursive=True,
+            raise_interrupt=False,
+        ):
+            if not ready:
+                ready = True
+                if on_ready is not None:
+                    on_ready()
+            if changes:
+                on_change()
+    except (OSError, RuntimeError):
+        on_change()
+    finally:
+        if not ready and on_ready is not None:
+            on_ready()
+
+
+def _watch_workspace(service: _CacheService) -> None:
+    service.context_ready.wait()
+    if service.shutdown.is_set() or service._context is None:
+        return
+    try:
+        watch_workspace_changes(
+            service.metadata.root,
+            stop_event=service.shutdown,
+            on_change=service._context.invalidate_revision_cache,
+            on_ready=service.watcher_ready.set,
+            watch_filter=_workspace_watch_filter(
+                service.metadata.root,
+                service._context.workspace.project_config,
+            ),
+        )
+    finally:
+        if not service.shutdown.is_set():
+            service.watcher_failed.set()
+
+
+def _serve_connection(connection: socket.socket, service: _CacheService) -> None:
+    try:
+        connection.settimeout(_PREAUTH_CONNECTION_TIMEOUT)
+        line = _read_line(connection)
+        connection.settimeout(_CONNECTION_TIMEOUT)
+        request = json.loads(line.decode("utf-8"))
+        if not isinstance(request, dict) or not hmac.compare_digest(str(request.pop("token", "")), service.metadata.token):
+            response: dict[str, object] = {"error": {"code": "authentication_failed", "message": "authentication failed"}}
+        else:
+            try:
+                action = request.get("action")
+                guard = None if action in {"status", "stop"} else _RequestGuard(
+                    service,
+                    connection,
+                    enforce_rss_budget=action in {"trace", "cpg"},
+                )
+                result = service.request(
+                    request,
+                    cancel_check=guard.check if guard is not None else None,
+                )
+                response = {"payload": result.payload, "warning": result.warning}
+            except CacheClientError as error:
+                response = {"error": {"code": error.code, "message": error.message}}
+    except Exception:
+        response = {"error": {"code": "invalid_request", "message": "Invalid cache request."}}
+    with contextlib.suppress(OSError):
+        connection.sendall(json.dumps(response, separators=(",", ":")).encode("utf-8") + b"\n")
+
+
+def _serve_owned_connection(
+    connection: socket.socket,
+    service: _CacheService,
+    slots: threading.BoundedSemaphore,
+) -> None:
+    try:
+        with connection:
+            _serve_connection(connection, service)
+    finally:
+        slots.release()
+
+
+def run_cache_daemon(
+    root: str | Path,
+    *,
+    project_file: str = "",
+    max_memory_bytes: int = DEFAULT_MAX_MEMORY_BYTES,
+    workers: int = 0,
+    idle_timeout: int = DEFAULT_IDLE_TIMEOUT,
+    max_disk_cache_bytes: int = DEFAULT_MAX_DISK_CACHE_BYTES,
+) -> None:
+    canonical = str(Path(root).resolve())
+    listener = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    listener.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    listener.bind(("127.0.0.1", 0))
+    listener.listen(16)
+    listener.settimeout(0.25)
+    metadata = CacheMetadata(
+        DAEMON_SCHEMA,
+        canonical,
+        os.getpid(),
+        listener.getsockname()[1],
+        secrets.token_urlsafe(32),
+        __version__,
+        project_file,
+        max_memory_bytes,
+        workers,
+        idle_timeout,
+        time.time(),
+        max_disk_cache_bytes,
+    )
+    watcher: threading.Thread | None = None
+    previous_sigterm: (
+        Callable[[int, FrameType | None], object]
+        | int
+        | None
+    ) = None
+    connection_slots = threading.BoundedSemaphore(_CONNECTION_WORKERS)
+    connection_pool = ThreadPoolExecutor(
+        max_workers=_CONNECTION_WORKERS,
+        thread_name_prefix="delphi-cache-client",
+    )
+    try:
+        service = _CacheService(metadata, defer_context=True)
+        if threading.current_thread() is threading.main_thread():
+            previous_sigterm = signal.getsignal(signal.SIGTERM)
+
+            def request_shutdown(
+                _signum: int,
+                _frame: FrameType | None,
+            ) -> None:
+                service.shutdown.set()
+
+            signal.signal(signal.SIGTERM, request_shutdown)
+        _write_metadata(metadata)
+        watcher = threading.Thread(
+            target=_watch_workspace,
+            args=(service,),
+            name="delphi-cache-watcher",
+            daemon=True,
+        )
+        watcher.start()
+        service.start_prewarm()
+        while (
+            not service.shutdown.is_set()
+            and time.monotonic() - service.last_activity < idle_timeout
+        ):
+            try:
+                connection, _ = listener.accept()
+            except TimeoutError:
+                continue
+            if not connection_slots.acquire(blocking=False):
+                connection.close()
+                continue
+            try:
+                connection_pool.submit(
+                    _serve_owned_connection,
+                    connection,
+                    service,
+                    connection_slots,
+                )
+            except RuntimeError:
+                connection_slots.release()
+                connection.close()
+    finally:
+        if "service" in locals():
+            service.shutdown.set()
+        listener.close()
+        connection_pool.shutdown(wait=True, cancel_futures=True)
+        _remove_metadata_if_owned(metadata)
+        if watcher is not None:
+            watcher.join(timeout=2.0)
+        if previous_sigterm is not None:
+            signal.signal(signal.SIGTERM, previous_sigterm)
+
+
+def _start_cache_unlocked(
+    root: str | Path,
+    *,
+    project_file: str | Path | None = None,
+    max_memory_bytes: int = DEFAULT_MAX_MEMORY_BYTES,
+    workers: int = 0,
+    idle_timeout: int = DEFAULT_IDLE_TIMEOUT,
+    startup_timeout: float = DEFAULT_STARTUP_TIMEOUT,
+    max_disk_cache_bytes: int = DEFAULT_MAX_DISK_CACHE_BYTES,
+) -> CacheMetadata:
+    canonical = str(Path(root).resolve())
+    project = str((Path(canonical) / project_file).resolve()) if project_file and not Path(project_file).is_absolute() else (str(Path(project_file).resolve()) if project_file else "")
+    existing = _read_metadata(canonical)
+    if existing and _pid_alive(existing.pid):
+        try:
+            _client_exchange(existing, {"action": "status", "_startup_probe": True})
+        except CacheClientError as error:
+            raise CacheClientError("unavailable", "Live cache daemon is unavailable.") from error
+        if (
+            existing.project_file,
+            existing.max_memory_bytes,
+            existing.workers,
+            existing.idle_timeout,
+            existing.max_disk_cache_bytes,
+        ) != (
+            project,
+            max_memory_bytes,
+            workers,
+            idle_timeout,
+            max_disk_cache_bytes,
+        ):
+            raise CacheClientError("configuration_conflict", "A live cache daemon has conflicting configuration.")
+        return existing
+    if existing:
+        _remove_metadata_if_owned(existing)
+    else:
+        _remove_incompatible_metadata_if_stale(canonical)
+    command = [
+        sys.executable,
+        "-m",
+        "delphi_lsp.agent_cache",
+        "serve",
+        "--root",
+        canonical,
+        "--max-memory",
+        str(max_memory_bytes),
+        "--workers",
+        str(workers),
+        "--idle-timeout",
+        str(idle_timeout),
+        "--max-disk-cache",
+        str(max_disk_cache_bytes),
+    ]
+    if project:
+        command.extend(("--project-file", project))
+    options = _daemon_process_options()
+    with tempfile.TemporaryFile() as diagnostics:
+        options["stderr"] = diagnostics
+        process = subprocess.Popen(command, **options)
+        deadline = time.monotonic() + startup_timeout
+        startup_ready = False
+        timed_out = False
+        return_code: int | None = None
+        try:
+            while time.monotonic() < deadline:
+                metadata = _read_metadata(canonical)
+                if metadata:
+                    try:
+                        _client_exchange(metadata, {"action": "status", "_startup_probe": True})
+                        startup_ready = True
+                        return metadata
+                    except CacheClientError:
+                        pass
+                if process.poll() is not None:
+                    break
+                time.sleep(0.05)
+            return_code = process.poll()
+            timed_out = return_code is None
+            if timed_out:
+                process.kill()
+            with contextlib.suppress(Exception):
+                return_code = process.wait()
+            metadata = _read_metadata(canonical)
+            if metadata and metadata.pid == process.pid:
+                _remove_metadata_if_owned(metadata)
+            diagnostics.seek(0)
+            raw = _read_startup_tail(diagnostics)
+            message = _truncate_and_sanitize_startup_diagnostics(raw)
+            base = "Cache daemon did not become ready."
+            if timed_out:
+                reason = (
+                    f" Startup timed out after {startup_timeout:.1f}s before "
+                    "readiness metadata was published."
+                )
+            else:
+                reason = (
+                    f" Child process exited with code {return_code} before "
+                    "readiness metadata was published."
+                )
+            if message:
+                raise CacheClientError(
+                    "startup_failed",
+                    f"{base}{reason} Child stderr: {message}",
+                )
+            raise CacheClientError(
+                "startup_failed",
+                (
+                    f"{base}{reason} No child diagnostics were emitted. "
+                    f"Python executable: {sys.executable}. Workspace: {canonical}."
+                ),
+            )
+        finally:
+            if not startup_ready:
+                if process.poll() is None:
+                    process.kill()
+                with contextlib.suppress(Exception):
+                    process.wait()
+
+
+def start_cache(
+    root: str | Path,
+    *,
+    project_file: str | Path | None = None,
+    max_memory_bytes: int = DEFAULT_MAX_MEMORY_BYTES,
+    workers: int = 0,
+    idle_timeout: int = DEFAULT_IDLE_TIMEOUT,
+    startup_timeout: float = DEFAULT_STARTUP_TIMEOUT,
+    max_disk_cache_bytes: int = DEFAULT_MAX_DISK_CACHE_BYTES,
+) -> CacheMetadata:
+    if type(workers) is not int or not 0 <= workers <= 32:
+        raise ValueError("workers must be auto or an integer from 1 through 32.")
+    if type(idle_timeout) is not int or idle_timeout <= 0:
+        raise ValueError("idle_timeout must be greater than zero.")
+    if not math.isfinite(startup_timeout) or startup_timeout <= 0:
+        raise ValueError("startup_timeout must be greater than zero.")
+    if (
+        isinstance(max_disk_cache_bytes, bool)
+        or not isinstance(max_disk_cache_bytes, int)
+        or max_disk_cache_bytes < 0
+    ):
+        raise ValueError("max_disk_cache_bytes must be non-negative.")
+    load_project_path_config(root)
+    with _process_start_lock(root), _start_lock(root, startup_timeout):
+        return _start_cache_unlocked(
+            root,
+            project_file=project_file,
+            max_memory_bytes=max_memory_bytes,
+            workers=workers,
+            idle_timeout=idle_timeout,
+            startup_timeout=startup_timeout,
+            max_disk_cache_bytes=max_disk_cache_bytes,
+        )
+
+
+def query_cache(root: str | Path, request: dict[str, object]) -> CacheClientResponse:
+    metadata = _read_metadata(root)
+    if metadata is None:
+        _remove_incompatible_metadata_if_stale(root)
+        raise CacheClientError("cache_not_running", "Cache daemon is not running.")
+    if not _pid_alive(metadata.pid):
+        _remove_metadata_if_owned(metadata)
+        raise CacheClientError("cache_not_running", "Cache daemon is not running.")
+    while True:
+        try:
+            return _client_exchange(metadata, request)
+        except CacheClientError as error:
+            if error.code != "cache_warming":
+                raise
+            time.sleep(0.05)
+
+
+def cache_status(root: str | Path) -> dict[str, object]:
+    return query_cache(root, {"action": "status"}).payload
+
+
+def stop_cache(root: str | Path) -> None:
+    metadata = _read_metadata(root)
+    if metadata is None:
+        _remove_incompatible_metadata_if_stale(root)
+        return
+    if not _pid_alive(metadata.pid):
+        _remove_metadata_if_owned(metadata)
+        return
+    try:
+        _client_exchange(metadata, {"action": "stop"})
+    except CacheClientError:
+        pass
+    started = time.monotonic()
+    deadline = started + _STOP_TIMEOUT_SECONDS
+    signal_sent = False
+    stopped = False
+    while True:
+        now = time.monotonic()
+        if now >= deadline:
+            break
+        if _reap_child_if_exited(metadata.pid):
+            stopped = True
+            break
+        if not _pid_alive(metadata.pid):
+            stopped = True
+            break
+        if (
+            not signal_sent
+            and os.name != "nt"
+            and now - started >= _STOP_SIGNAL_DELAY_SECONDS
+        ):
+            with contextlib.suppress(OSError):
+                os.kill(metadata.pid, signal.SIGTERM)
+            signal_sent = True
+        time.sleep(0.05)
+    if not stopped and _pid_alive(metadata.pid):
+        current = _read_metadata(root)
+        if current == metadata:
+            force_signal = (
+                signal.SIGKILL
+                if os.name != "nt" and hasattr(signal, "SIGKILL")
+                else signal.SIGTERM
+            )
+            with contextlib.suppress(OSError):
+                os.kill(metadata.pid, force_signal)
+            force_deadline = time.monotonic() + _STOP_FORCE_TIMEOUT_SECONDS
+            while time.monotonic() < force_deadline:
+                if _reap_child_if_exited(metadata.pid) or not _pid_alive(
+                    metadata.pid
+                ):
+                    stopped = True
+                    break
+                time.sleep(0.05)
+    if not stopped and _pid_alive(metadata.pid):
+        raise CacheClientError("stop_failed", "Cache daemon did not stop.")
+    _remove_metadata_if_owned(metadata)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser()
+    command = parser.add_subparsers(dest="command", required=True)
+    serve = command.add_parser("serve")
+    serve.add_argument("--root", required=True)
+    serve.add_argument("--project-file", default="")
+    serve.add_argument("--max-memory", type=int, default=DEFAULT_MAX_MEMORY_BYTES)
+    serve.add_argument("--workers", type=int, default=0)
+    serve.add_argument("--idle-timeout", type=_positive_integer, default=DEFAULT_IDLE_TIMEOUT)
+    serve.add_argument(
+        "--max-disk-cache",
+        type=int,
+        default=DEFAULT_MAX_DISK_CACHE_BYTES,
+    )
+    args = parser.parse_args(argv)
+    if args.command == "serve":
+        run_cache_daemon(
+            args.root,
+            project_file=args.project_file,
+            max_memory_bytes=args.max_memory,
+            workers=args.workers,
+            idle_timeout=args.idle_timeout,
+            max_disk_cache_bytes=args.max_disk_cache,
+        )
+    return 0
+
+
+def _positive_integer(value: str) -> int:
+    parsed = int(value)
+    if parsed <= 0:
+        raise argparse.ArgumentTypeError("value must be greater than zero")
+    return parsed
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())