python-delphi-lsp 2.0.5__tar.gz → 2.1.0__tar.gz

{python_delphi_lsp-2.0.5 → python_delphi_lsp-2.1.0}/.github/workflows/ci.yml

@@ -2,6 +2,7 @@ name: CI
 
 on:
   push:
+    branches: [main]
   pull_request:
 
 jobs:

{python_delphi_lsp-2.0.5 → python_delphi_lsp-2.1.0}/MANIFEST.in

@@ -6,6 +6,7 @@ include scripts/check_ornith_cache.py
 include scripts/audit_delphi_language_features.py
 include scripts/build_github_performance_corpus.py
 include scripts/benchmark_github_corpus.py
+include scripts/benchmark_parallel_cache.py
 include scripts/bootstrap_vllm_opencode_test.py
 include scripts/bootstrap_vllm_codebase_skill_test.py
 include scripts/bootstrap_vllm_opencode_test.ps1

{python_delphi_lsp-2.0.5/python_delphi_lsp.egg-info → python_delphi_lsp-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-delphi-lsp
-Version: 2.0.5
+Version: 2.1.0
 Summary: Python Delphi/Object Pascal parser, semantic indexer, and language server.
 Author: Dark Light
 License-Expression: MPL-2.0
@@ -41,7 +41,7 @@ Dynamic: license-file
 
 `python-delphi-lsp` parses Delphi/Object Pascal, builds semantic and project
 indexes, serves LSP, and provides bounded codebase navigation for agents.
-Version 2.0.5 is authored by Dark Light and supports Windows, macOS, and Linux.
+Version 2.1.0 is authored by Dark Light and supports Windows, macOS, and Linux.
 
 ## Install and quick start
 
@@ -186,12 +186,15 @@ problems; paths are not guessed.
 
 ```text
 delphi-lsp-agent cache start --root PATH [--project-file FILE] [--max-memory 512M]
+                                  [--workers auto|N] [--startup-timeout 120]
                                   [--idle-timeout 1800]
 delphi-lsp-agent cache status --root PATH [--format text|json]
 delphi-lsp-agent cache stop --root PATH
 delphi-lsp-agent view --root PATH [--project-file FILE] --layer LAYER
                       [--query TEXT] [--format markdown|json] [--deep-projects]
+                      [--workers auto|N]
 delphi-lsp-agent index --root PATH [--project-file FILE] [--out FILE]
+                       [--workers auto|N]
 delphi-lsp-agent query --root PATH ACTION [VALUE]
                       [--project-id FILE] [--detail summary|declaration|members|context|body|implementations]
                       [--relation references|callers|callees|uses|used_by|inherits|implements]
@@ -199,7 +202,7 @@ delphi-lsp-agent query --root PATH ACTION [VALUE]
 delphi-lsp-agent skill install [--target PATH] [--force]
 delphi-lsp-agent opencode install [--target PATH] [--python PYTHON]
                                   [--force] [--write-agent|--write-config]
-delphi-lsp-agent worker --root PATH [--project-file FILE]
+delphi-lsp-agent worker --root PATH [--project-file FILE] [--workers auto|N]
 ```
 
 The `cache` commands manage one daemon per canonical root. Use these:
@@ -233,6 +236,27 @@ fast. The cache retained-cache budget is `512 MiB` by default and tracks retaine
 cache usage only, not a hard RSS/parse peak. Warnings are emitted on stderr at or
 above 80 percent.
 
+Cold builds parse independent source units in short-lived processes created with
+the cross-platform `spawn` method. `--workers auto|N` defaults to `auto`.
+Automatic selection uses at most four worker processes, leaves one detected CPU
+free, never exceeds the source task count, and—for the cache daemon—allows one
+worker per `128 MiB` of retained-cache budget. `view` and `index` use the same
+task, CPU, and four-worker caps without the cache-budget term. An explicit value
+from 1 through 32 overrides the automatic CPU and memory caps but is still
+limited by the number of tasks.
+
+Worker processes exit before retained-cache accounting. Their models and source
+text are streamed into the parent, so transient worker memory is separate from
+the retained navigation structures and the existing 80-percent warning. If an
+automatic pool fails before accepting a result, one automatic serial fallback
+is attempted; explicit worker counts fail instead of silently changing the
+requested configuration.
+
+`cache start` waits up to `--startup-timeout 120` seconds by default for a large
+workspace to prewarm. The timeout belongs to the starting client and does not
+change daemon compatibility or idle shutdown. Starting a live root with a
+different worker configuration reports a configuration conflict.
+
 Eviction is ordered: auxiliary caches are evicted first, navigation caches second.
 If compaction removes navigable data, the daemon rebuilds the navigation state on demand
 while preserving focus state for the next request.
@@ -240,7 +264,9 @@ while preserving focus state for the next request.
 The daemon tracks a 30-minute idle timeout; idle state shows in JSON status (`cache status`).
 `source revision` changes on source edits and invalidate reused request caches.
 Workspace state appears in status as `requests`, `warm_hits`, `rebuilds`, `invalidations`,
-`evictions`, and `cache_state`.
+`evictions`, and `cache_state`. Parallel prewarm status adds
+`workers_configured`, `workers_effective`, `parallel_files_completed`,
+`prewarm_seconds`, `parallel_seconds`, and `parallel_fallbacks`.
 
 Metadata is stored in `.delphi-lsp/agent-cache/daemon.json` with owner-only token and
 permissions (`daemon.json` mode 600 and parent 700). Do not copy or share this token

{python_delphi_lsp-2.0.5 → python_delphi_lsp-2.1.0}/README.md

@@ -2,7 +2,7 @@
 
 `python-delphi-lsp` parses Delphi/Object Pascal, builds semantic and project
 indexes, serves LSP, and provides bounded codebase navigation for agents.
-Version 2.0.5 is authored by Dark Light and supports Windows, macOS, and Linux.
+Version 2.1.0 is authored by Dark Light and supports Windows, macOS, and Linux.
 
 ## Install and quick start
 
@@ -147,12 +147,15 @@ problems; paths are not guessed.
 
 ```text
 delphi-lsp-agent cache start --root PATH [--project-file FILE] [--max-memory 512M]
+                                  [--workers auto|N] [--startup-timeout 120]
                                   [--idle-timeout 1800]
 delphi-lsp-agent cache status --root PATH [--format text|json]
 delphi-lsp-agent cache stop --root PATH
 delphi-lsp-agent view --root PATH [--project-file FILE] --layer LAYER
                       [--query TEXT] [--format markdown|json] [--deep-projects]
+                      [--workers auto|N]
 delphi-lsp-agent index --root PATH [--project-file FILE] [--out FILE]
+                       [--workers auto|N]
 delphi-lsp-agent query --root PATH ACTION [VALUE]
                       [--project-id FILE] [--detail summary|declaration|members|context|body|implementations]
                       [--relation references|callers|callees|uses|used_by|inherits|implements]
@@ -160,7 +163,7 @@ delphi-lsp-agent query --root PATH ACTION [VALUE]
 delphi-lsp-agent skill install [--target PATH] [--force]
 delphi-lsp-agent opencode install [--target PATH] [--python PYTHON]
                                   [--force] [--write-agent|--write-config]
-delphi-lsp-agent worker --root PATH [--project-file FILE]
+delphi-lsp-agent worker --root PATH [--project-file FILE] [--workers auto|N]
 ```
 
 The `cache` commands manage one daemon per canonical root. Use these:
@@ -194,6 +197,27 @@ fast. The cache retained-cache budget is `512 MiB` by default and tracks retaine
 cache usage only, not a hard RSS/parse peak. Warnings are emitted on stderr at or
 above 80 percent.
 
+Cold builds parse independent source units in short-lived processes created with
+the cross-platform `spawn` method. `--workers auto|N` defaults to `auto`.
+Automatic selection uses at most four worker processes, leaves one detected CPU
+free, never exceeds the source task count, and—for the cache daemon—allows one
+worker per `128 MiB` of retained-cache budget. `view` and `index` use the same
+task, CPU, and four-worker caps without the cache-budget term. An explicit value
+from 1 through 32 overrides the automatic CPU and memory caps but is still
+limited by the number of tasks.
+
+Worker processes exit before retained-cache accounting. Their models and source
+text are streamed into the parent, so transient worker memory is separate from
+the retained navigation structures and the existing 80-percent warning. If an
+automatic pool fails before accepting a result, one automatic serial fallback
+is attempted; explicit worker counts fail instead of silently changing the
+requested configuration.
+
+`cache start` waits up to `--startup-timeout 120` seconds by default for a large
+workspace to prewarm. The timeout belongs to the starting client and does not
+change daemon compatibility or idle shutdown. Starting a live root with a
+different worker configuration reports a configuration conflict.
+
 Eviction is ordered: auxiliary caches are evicted first, navigation caches second.
 If compaction removes navigable data, the daemon rebuilds the navigation state on demand
 while preserving focus state for the next request.
@@ -201,7 +225,9 @@ while preserving focus state for the next request.
 The daemon tracks a 30-minute idle timeout; idle state shows in JSON status (`cache status`).
 `source revision` changes on source edits and invalidate reused request caches.
 Workspace state appears in status as `requests`, `warm_hits`, `rebuilds`, `invalidations`,
-`evictions`, and `cache_state`.
+`evictions`, and `cache_state`. Parallel prewarm status adds
+`workers_configured`, `workers_effective`, `parallel_files_completed`,
+`prewarm_seconds`, `parallel_seconds`, and `parallel_fallbacks`.
 
 Metadata is stored in `.delphi-lsp/agent-cache/daemon.json` with owner-only token and
 permissions (`daemon.json` mode 600 and parent 700). Do not copy or share this token

python_delphi_lsp-2.1.0/delphi_lsp/_version.py

@@ -0,0 +1 @@
+__version__ = "2.1.0"

{python_delphi_lsp-2.0.5 → python_delphi_lsp-2.1.0}/delphi_lsp/agent_cache.py

@@ -6,6 +6,7 @@ import argparse
 import contextlib
 import hmac
 import json
+import math
 import os
 from pathlib import Path
 import secrets
@@ -26,13 +27,15 @@ from .agent_protocol import AgentProtocolError
 
 DEFAULT_MAX_MEMORY_BYTES = 512 * 1024**2
 WARNING_THRESHOLD_PERCENT = 80
-DAEMON_SCHEMA = 1
+DAEMON_SCHEMA = 2
 DEFAULT_IDLE_TIMEOUT = 1800
+DEFAULT_STARTUP_TIMEOUT = 120.0
 _MAX_MESSAGE_BYTES = 1024 * 1024
 _CONNECTION_TIMEOUT = 2.0
 _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
 
 
 def estimate_deep_size(value: object) -> int:
@@ -72,6 +75,7 @@ class CacheStats:
     rebuilds: int = 0
     invalidations: int = 0
     evictions: int = 0
+    parallel_fallbacks: int = 0
 
 
 @dataclass(frozen=True)
@@ -232,6 +236,7 @@ class CacheMetadata:
     version: str
     project_file: str
     max_memory_bytes: int
+    workers: int
     idle_timeout: int
     started_at: float
 
@@ -291,7 +296,7 @@ def _write_metadata(metadata: CacheMetadata) -> None:
             os.unlink(temporary)
 
 
-def _read_metadata(root: str | Path) -> CacheMetadata | None:
+def _read_metadata_record(root: str | Path) -> object | None:
     path = _safe_metadata_path(root)
     if not path.exists():
         return None
@@ -309,15 +314,36 @@ def _read_metadata(root: str | Path) -> CacheMetadata | None:
         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)}
     if not isinstance(raw, dict) or set(raw) != required:
         return None
-    values = tuple(raw[name] for name in ("schema", "root", "pid", "port", "token", "version", "project_file", "max_memory_bytes", "idle_timeout", "started_at"))
+    values = tuple(
+        raw[name]
+        for name in (
+            "schema",
+            "root",
+            "pid",
+            "port",
+            "token",
+            "version",
+            "project_file",
+            "max_memory_bytes",
+            "workers",
+            "idle_timeout",
+            "started_at",
+        )
+    )
     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 values[8] <= 0 or type(values[9]) not in (int, float)):
+            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)):
         return None
     canonical = str(Path(root).resolve())
     if values[1] != canonical:
@@ -325,15 +351,56 @@ def _read_metadata(root: str | Path) -> CacheMetadata | 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)
-    current = _read_metadata(metadata.root)
-    if current is not None and current.pid == metadata.pid and hmac.compare_digest(current.token, metadata.token):
+    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:
@@ -341,15 +408,41 @@ def _pid_alive(pid: int) -> bool:
     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):
+def _start_lock(root: str | Path, timeout: float):
     path = _start_lock_path(root)
     token = secrets.token_urlsafe(24)
-    deadline = time.monotonic() + 10
+    deadline = time.monotonic() + timeout
     while True:
         try:
             descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
@@ -361,14 +454,7 @@ def _start_lock(root: str | Path):
                 os.close(descriptor)
             break
         except FileExistsError:
-            try:
-                record = json.loads(path.read_text(encoding="utf-8"))
-                owner = record.get("pid") if isinstance(record, dict) else None
-                started = record.get("started_at") if isinstance(record, dict) else None
-                stale = type(owner) is not int or not _pid_alive(owner) or type(started) not in (int, float) or time.time() - started > 30
-            except (OSError, ValueError, UnicodeError):
-                stale = True
-            if stale:
+            if _start_lock_is_stale(path):
                 with contextlib.suppress(FileNotFoundError):
                     path.unlink()
                 continue
@@ -450,7 +536,12 @@ def _read_startup_tail(diagnostics: object, *, max_bytes: int = _STARTUP_DIAGNOS
 class _CacheService:
     def __init__(self, metadata: CacheMetadata) -> None:
         self.metadata = metadata
-        self.context = AgentContext.open(metadata.root, metadata.project_file or None)
+        self.context = AgentContext.open(
+            metadata.root,
+            metadata.project_file or None,
+            workers=metadata.workers,
+            worker_memory_budget_bytes=metadata.max_memory_bytes,
+        )
         self.budget = CacheBudget(metadata.max_memory_bytes)
         self.stats = CacheStats()
         self.lock = threading.Lock()
@@ -459,9 +550,11 @@ class _CacheService:
         self.cache_state = "warming"
         self.last_revision = self.context.workspace.workspace_revision
         self.last_budget = BudgetResult(0, 0.0, 0.0, False, False, False)
+        self.prewarm_seconds = 0.0
         self.shutdown = threading.Event()
 
     def prewarm(self) -> None:
+        started = time.monotonic()
         try:
             self.context.handle({"action": "find", "query": "", "max_items": 1, "max_chars": 256})
             self.last_revision = self.context.workspace.workspace_revision
@@ -478,6 +571,8 @@ class _CacheService:
         if self.last_budget.compacted:
             self.stats.evictions += 1
             self.cache_state = "compact"
+        self.prewarm_seconds = time.monotonic() - started
+        self.stats.parallel_fallbacks = self.context.parallel_stats.fallbacks
 
     def request(self, request: dict[str, object]) -> CacheClientResponse:
         with self.lock:
@@ -506,6 +601,7 @@ class _CacheService:
                 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
             self.last_budget = self.budget.enforce(
@@ -539,6 +635,12 @@ class _CacheService:
             "warning_active": self.last_budget.warning_active, "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": self.context.parallel_stats.effective_workers,
+            "parallel_files_completed": self.context.parallel_stats.files_completed,
+            "prewarm_seconds": self.prewarm_seconds,
+            "parallel_seconds": self.context.parallel_stats.elapsed_seconds,
+            "parallel_fallbacks": self.stats.parallel_fallbacks,
             "idle_timeout": self.metadata.idle_timeout, "idle_remaining": max(0.0, self.metadata.idle_timeout - idle),
             "workspace_revision": self.context.workspace.workspace_revision,
         }
@@ -562,14 +664,33 @@ def _serve_connection(connection: socket.socket, service: _CacheService) -> None
         connection.sendall(json.dumps(response, separators=(",", ":")).encode("utf-8") + b"\n")
 
 
-def run_cache_daemon(root: str | Path, *, project_file: str = "", max_memory_bytes: int = DEFAULT_MAX_MEMORY_BYTES, idle_timeout: int = DEFAULT_IDLE_TIMEOUT) -> None:
+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,
+) -> 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, idle_timeout, time.time())
+    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(),
+    )
     try:
         service = _CacheService(metadata)
         service.prewarm()
@@ -587,7 +708,15 @@ def run_cache_daemon(root: str | Path, *, project_file: str = "", max_memory_byt
         _remove_metadata_if_owned(metadata)
 
 
-def _start_cache_unlocked(root: str | Path, *, project_file: str | Path | None = None, max_memory_bytes: int = DEFAULT_MAX_MEMORY_BYTES, idle_timeout: int = DEFAULT_IDLE_TIMEOUT) -> CacheMetadata:
+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,
+) -> 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)
@@ -596,12 +725,32 @@ def _start_cache_unlocked(root: str | Path, *, project_file: str | Path | None =
             _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.idle_timeout) != (project, max_memory_bytes, idle_timeout):
+        if (existing.project_file, existing.max_memory_bytes, existing.workers, existing.idle_timeout) != (
+            project,
+            max_memory_bytes,
+            workers,
+            idle_timeout,
+        ):
             raise CacheClientError("configuration_conflict", "A live cache daemon has conflicting configuration.")
         return existing
     if existing:
         _remove_metadata_if_owned(existing)
-    command = [sys.executable, "-m", "delphi_lsp.agent_cache", "serve", "--root", canonical, "--max-memory", str(max_memory_bytes), "--idle-timeout", str(idle_timeout)]
+    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),
+    ]
     if project:
         command.extend(("--project-file", project))
     options: dict[str, object] = {"stdin": subprocess.DEVNULL, "stdout": subprocess.DEVNULL}
@@ -612,7 +761,7 @@ def _start_cache_unlocked(root: str | Path, *, project_file: str | Path | None =
     with tempfile.TemporaryFile() as diagnostics:
         options["stderr"] = diagnostics
         process = subprocess.Popen(command, **options)
-        deadline = time.monotonic() + 10
+        deadline = time.monotonic() + startup_timeout
         startup_ready = False
         try:
             while time.monotonic() < deadline:
@@ -649,14 +798,34 @@ def _start_cache_unlocked(root: str | Path, *, project_file: str | Path | None =
                     process.wait()
 
 
-def start_cache(root: str | Path, *, project_file: str | Path | None = None, max_memory_bytes: int = DEFAULT_MAX_MEMORY_BYTES, idle_timeout: int = DEFAULT_IDLE_TIMEOUT) -> CacheMetadata:
-    with _start_lock(root):
-        return _start_cache_unlocked(root, project_file=project_file, max_memory_bytes=max_memory_bytes, idle_timeout=idle_timeout)
+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,
+) -> 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 not math.isfinite(startup_timeout) or startup_timeout <= 0:
+        raise ValueError("startup_timeout must be greater than zero.")
+    with _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,
+        )
 
 
 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)
@@ -671,6 +840,7 @@ def cache_status(root: str | Path) -> dict[str, object]:
 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)
@@ -681,11 +851,13 @@ def stop_cache(root: str | Path) -> None:
         pass
     deadline = time.monotonic() + 3
     stopped = False
-    while _pid_alive(metadata.pid) and time.monotonic() < deadline:
-        with contextlib.suppress(ChildProcessError):
-            if os.waitpid(metadata.pid, os.WNOHANG)[0] == metadata.pid:
-                stopped = True
-                break
+    while time.monotonic() < deadline:
+        if _reap_child_if_exited(metadata.pid):
+            stopped = True
+            break
+        if 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.")
@@ -699,10 +871,17 @@ def main(argv: list[str] | None = None) -> int:
     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=int, default=DEFAULT_IDLE_TIMEOUT)
     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, idle_timeout=args.idle_timeout)
+        run_cache_daemon(
+            args.root,
+            project_file=args.project_file,
+            max_memory_bytes=args.max_memory,
+            workers=args.workers,
+            idle_timeout=args.idle_timeout,
+        )
     return 0