python-delphi-lsp 2.0.5__py3-none-any.whl → 2.2.0__py3-none-any.whl

delphi_lsp/_version.py

@@ -1 +1 @@
-__version__ = "2.0.5"
+__version__ = "2.2.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
@@ -19,6 +20,8 @@ import threading
 import time
 from types import ModuleType
 
+from watchfiles import watch
+
 from ._version import __version__
 from .agent_context import AgentContext
 from .agent_protocol import AgentProtocolError
@@ -26,13 +29,20 @@ 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
+_CLIENT_RESPONSE_TIMEOUT = 120.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
+_CACHE_REVISION_CHECK_INTERVAL_SECONDS = 3600.0
+_WATCHED_SUFFIXES = frozenset(
+    {".pas", ".pp", ".inc", ".dpr", ".dpk", ".dproj", ".cfg"}
+)
 
 
 def estimate_deep_size(value: object) -> int:
@@ -72,6 +82,7 @@ class CacheStats:
     rebuilds: int = 0
     invalidations: int = 0
     evictions: int = 0
+    parallel_fallbacks: int = 0
 
 
 @dataclass(frozen=True)
@@ -232,6 +243,7 @@ class CacheMetadata:
     version: str
     project_file: str
     max_memory_bytes: int
+    workers: int
     idle_timeout: int
     started_at: float
 
@@ -291,7 +303,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 +321,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 +358,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 +415,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 +461,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
@@ -389,7 +482,7 @@ def _start_lock(root: str | Path):
 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(3)
+            connection.settimeout(_CLIENT_RESPONSE_TIMEOUT)
             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)
@@ -450,7 +543,13 @@ 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,
+            revision_check_interval_seconds=_CACHE_REVISION_CHECK_INTERVAL_SECONDS,
+        )
         self.budget = CacheBudget(metadata.max_memory_bytes)
         self.stats = CacheStats()
         self.lock = threading.Lock()
@@ -459,25 +558,28 @@ 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
+            self.last_revision = self.context.prewarm_navigation()
             self.cache_state = "warm"
         except AgentProtocolError as error:
             if error.code != "project_required":
                 raise
             self.cache_state = "ready"
         self.last_budget = self.budget.enforce(
-            measure=lambda: estimate_deep_size(self.context.cache_roots()),
+            measure=lambda: self.context.estimated_cache_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"
+        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,10 +608,11 @@ 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(
-                measure=lambda: estimate_deep_size(self.context.cache_roots()),
+                measure=lambda: self.context.estimated_cache_bytes,
                 evict_auxiliary=self.context.evict_auxiliary_caches,
                 evict_navigation=self.context.evict_navigation_caches,
             )
@@ -539,11 +642,38 @@ 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,
+            "workspace_revision": self.last_revision,
         }
 
 
+def _watch_filter(_change: object, path: str) -> bool:
+    return Path(path).suffix.casefold() in _WATCHED_SUFFIXES
+
+
+def _watch_workspace(service: _CacheService) -> None:
+    try:
+        for changes in watch(
+            service.metadata.root,
+            watch_filter=_watch_filter,
+            stop_event=service.shutdown,
+            debounce=50,
+            step=20,
+            recursive=True,
+            raise_interrupt=False,
+        ):
+            if changes:
+                service.context.invalidate_revision_cache()
+    except (OSError, RuntimeError):
+        service.context.invalidate_revision_cache()
+
+
 def _serve_connection(connection: socket.socket, service: _CacheService) -> None:
     try:
         line = _read_line(connection)
@@ -562,17 +692,44 @@ 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(),
+    )
+    watcher: threading.Thread | None = None
     try:
         service = _CacheService(metadata)
         service.prewarm()
+        watcher = threading.Thread(
+            target=_watch_workspace,
+            args=(service,),
+            name="delphi-cache-watcher",
+            daemon=True,
+        )
+        watcher.start()
         _write_metadata(metadata)
         while not service.shutdown.is_set() and time.monotonic() - service.last_activity < idle_timeout:
             try:
@@ -583,11 +740,23 @@ def run_cache_daemon(root: str | Path, *, project_file: str = "", max_memory_byt
                 connection.settimeout(_CONNECTION_TIMEOUT)
                 _serve_connection(connection, service)
     finally:
+        if "service" in locals():
+            service.shutdown.set()
+        if watcher is not None:
+            watcher.join(timeout=2.0)
         listener.close()
         _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 +765,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 +801,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 +838,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 +880,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 +891,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 +911,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
 
 

delphi_lsp/agent_cli.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import math
 import os
 import sys
 from pathlib import Path
@@ -12,6 +13,7 @@ from .agent_cache import (
     CacheClientError,
     DEFAULT_IDLE_TIMEOUT,
     DEFAULT_MAX_MEMORY_BYTES,
+    DEFAULT_STARTUP_TIMEOUT,
     parse_memory_size,
     query_cache,
     run_cache_daemon,
@@ -21,6 +23,7 @@ from .agent_cache import (
 from .agent_layers import build_codebase_index, layer_payload, render_layer
 from .agent_protocol import AgentProtocolError, SUPPORTED_ACTIONS, SUPPORTED_DETAILS, SUPPORTED_RELATIONS
 from .agent_templates import install_opencode_support, install_skill
+from .parallel_outline import parse_worker_setting
 
 
 _MAX_WORKER_RECORD_BYTES = 1024 * 1024
@@ -60,12 +63,14 @@ def build_parser() -> argparse.ArgumentParser:
     view.add_argument("--query", default="")
     view.add_argument("--format", default="markdown", choices=["markdown", "json"])
     view.add_argument("--deep-projects", action="store_true", help="Deep-parse project dependencies for the projects layer.")
+    view.add_argument("--workers", type=parse_worker_setting, default=0)
     view.set_defaults(func=_view)
 
     index = subcommands.add_parser("index", help="Materialize a JSON codebase index.")
     index.add_argument("--root", type=Path, default=Path("."))
     index.add_argument("--project-file", type=Path)
     index.add_argument("--out", type=Path, default=Path(".delphi-lsp") / "agent-index" / "index.json")
+    index.add_argument("--workers", type=parse_worker_setting, default=0)
     index.set_defaults(func=_index)
 
     skill = subcommands.add_parser("skill", help="Install agent skill templates.")
@@ -95,6 +100,7 @@ def build_parser() -> argparse.ArgumentParser:
     worker = subcommands.add_parser("worker", help="Serve Protocol v2 NDJSON requests.")
     worker.add_argument("--root", type=Path, required=True)
     worker.add_argument("--project-file", type=Path)
+    worker.add_argument("--workers", type=parse_worker_setting, default=0)
     worker.set_defaults(func=_worker)
 
     cache = subcommands.add_parser("cache", help="Manage the shared Protocol v2 cache daemon.")
@@ -113,6 +119,7 @@ def build_parser() -> argparse.ArgumentParser:
     cache_serve.add_argument("--root", type=Path, required=True)
     cache_serve.add_argument("--project-file", type=Path)
     cache_serve.add_argument("--max-memory", type=parse_memory_size, required=True)
+    cache_serve.add_argument("--workers", type=parse_worker_setting, required=True)
     cache_serve.add_argument("--idle-timeout", type=int, required=True)
     cache_serve.set_defaults(func=_cache_serve)
 
@@ -135,7 +142,16 @@ def _add_cache_start_arguments(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("--root", type=Path, default=Path("."))
     parser.add_argument("--project-file", type=Path)
     parser.add_argument("--max-memory", type=parse_memory_size, default=DEFAULT_MAX_MEMORY_BYTES)
+    parser.add_argument("--workers", type=parse_worker_setting, default=0)
     parser.add_argument("--idle-timeout", type=int, default=DEFAULT_IDLE_TIMEOUT)
+    parser.add_argument("--startup-timeout", type=_positive_float, default=DEFAULT_STARTUP_TIMEOUT)
+
+
+def _positive_float(value: str) -> float:
+    parsed = float(value)
+    if not math.isfinite(parsed) or parsed <= 0:
+        raise argparse.ArgumentTypeError("value must be greater than zero")
+    return parsed
 
 
 def main(argv: list[str] | None = None) -> int:
@@ -173,12 +189,22 @@ def _discard_broken_stdout() -> None:
 
 
 def _view(args: argparse.Namespace) -> None:
-    index = build_codebase_index(args.root, project_file=args.project_file, index_projects=args.deep_projects)
+    index = build_codebase_index(
+        args.root,
+        project_file=args.project_file,
+        index_projects=args.deep_projects,
+        workers=args.workers,
+    )
     sys.stdout.write(render_layer(index, args.layer, query=args.query, output_format=args.format))
 
 
 def _index(args: argparse.Namespace) -> None:
-    index = build_codebase_index(args.root, project_file=args.project_file, index_projects=True)
+    index = build_codebase_index(
+        args.root,
+        project_file=args.project_file,
+        index_projects=True,
+        workers=args.workers,
+    )
     payload = {
         "overview": layer_payload(index, "overview"),
         "projects": layer_payload(index, "projects"),
@@ -207,7 +233,7 @@ def _opencode_install(args: argparse.Namespace) -> None:
 
 
 def _worker(args: argparse.Namespace) -> None:
-    context = AgentContext.open(args.root, args.project_file)
+    context = AgentContext.open(args.root, args.project_file, workers=args.workers)
     try:
         _serve_worker(context, sys.stdin.buffer, sys.stdout.buffer, sys.stderr)
     finally:
@@ -235,7 +261,14 @@ def _cache_error(error: CacheClientError) -> int:
 
 def _cache_start(args: argparse.Namespace) -> int:
     try:
-        start_cache(args.root, project_file=args.project_file, max_memory_bytes=args.max_memory, idle_timeout=args.idle_timeout)
+        start_cache(
+            args.root,
+            project_file=args.project_file,
+            max_memory_bytes=args.max_memory,
+            workers=args.workers,
+            idle_timeout=args.idle_timeout,
+            startup_timeout=args.startup_timeout,
+        )
         response = query_cache(args.root, {"action": "status"})
     except CacheClientError as error:
         return _cache_error(error)
@@ -283,7 +316,13 @@ def _cache_stop(args: argparse.Namespace) -> int:
 
 
 def _cache_serve(args: argparse.Namespace) -> int:
-    run_cache_daemon(args.root, project_file=str(args.project_file or ""), max_memory_bytes=args.max_memory, idle_timeout=args.idle_timeout)
+    run_cache_daemon(
+        args.root,
+        project_file=str(args.project_file or ""),
+        max_memory_bytes=args.max_memory,
+        workers=args.workers,
+        idle_timeout=args.idle_timeout,
+    )
     return 0