python-delphi-lsp 2.2.0__tar.gz → 2.3.1__tar.gz

{python_delphi_lsp-2.2.0/python_delphi_lsp.egg-info → python_delphi_lsp-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-delphi-lsp
-Version: 2.2.0
+Version: 2.3.1
 Summary: Python Delphi/Object Pascal parser, semantic indexer, and language server.
 Author: Dark Light
 License-Expression: MPL-2.0
@@ -42,7 +42,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.2.0 is authored by Dark Light and supports Windows, macOS, and Linux.
+Version 2.3.1 is authored by Dark Light and supports Windows, macOS, and Linux.
 
 ## Install and quick start
 
@@ -257,6 +257,13 @@ to measure it. 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.
 
+Detached navigation shards are also stored as versioned, content-addressed JSON
+under `.delphi-lsp/agent-cache/navigation-v1`. A restarted CLI or OpenCode cache
+daemon reuses unchanged units without parsing them again. Source content,
+conditional defines, or a shard-schema change produces a cache miss; malformed
+or incompatible JSON is ignored and rebuilt. The disk cache contains no pickle
+payloads and does not count against the retained-RAM budget.
+
 Cache prewarming builds the navigation registry directly without constructing
 an empty-query result, symbol cards, pagination, or JSON payloads. Up to sixteen
 recent ranked queries are retained in a small LRU so alternating CLI and
@@ -276,7 +283,8 @@ The daemon tracks a 30-minute idle timeout; idle state shows in JSON status (`ca
 Workspace state appears in status as `requests`, `warm_hits`, `rebuilds`, `invalidations`,
 `evictions`, and `cache_state`. Parallel prewarm status adds
 `workers_configured`, `workers_effective`, `parallel_files_completed`,
-`prewarm_seconds`, `parallel_seconds`, and `parallel_fallbacks`.
+`prewarm_seconds`, `parallel_seconds`, `parallel_fallbacks`,
+`navigation_disk_hits`, and `navigation_disk_misses`.
 
 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.2.0 → python_delphi_lsp-2.3.1}/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.2.0 is authored by Dark Light and supports Windows, macOS, and Linux.
+Version 2.3.1 is authored by Dark Light and supports Windows, macOS, and Linux.
 
 ## Install and quick start
 
@@ -217,6 +217,13 @@ to measure it. 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.
 
+Detached navigation shards are also stored as versioned, content-addressed JSON
+under `.delphi-lsp/agent-cache/navigation-v1`. A restarted CLI or OpenCode cache
+daemon reuses unchanged units without parsing them again. Source content,
+conditional defines, or a shard-schema change produces a cache miss; malformed
+or incompatible JSON is ignored and rebuilt. The disk cache contains no pickle
+payloads and does not count against the retained-RAM budget.
+
 Cache prewarming builds the navigation registry directly without constructing
 an empty-query result, symbol cards, pagination, or JSON payloads. Up to sixteen
 recent ranked queries are retained in a small LRU so alternating CLI and
@@ -236,7 +243,8 @@ The daemon tracks a 30-minute idle timeout; idle state shows in JSON status (`ca
 Workspace state appears in status as `requests`, `warm_hits`, `rebuilds`, `invalidations`,
 `evictions`, and `cache_state`. Parallel prewarm status adds
 `workers_configured`, `workers_effective`, `parallel_files_completed`,
-`prewarm_seconds`, `parallel_seconds`, and `parallel_fallbacks`.
+`prewarm_seconds`, `parallel_seconds`, `parallel_fallbacks`,
+`navigation_disk_hits`, and `navigation_disk_misses`.
 
 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.3.1/delphi_lsp/_version.py

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

{python_delphi_lsp-2.2.0 → python_delphi_lsp-2.3.1}/delphi_lsp/agent_cache.py

@@ -45,6 +45,88 @@ _WATCHED_SUFFIXES = frozenset(
 )
 
 
+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.
 
@@ -280,6 +362,23 @@ def _safe_metadata_path(root: str | Path, *, create: bool = False) -> Path:
     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)}
 
@@ -543,12 +642,17 @@ def _read_startup_tail(diagnostics: object, *, max_bytes: int = _STARTUP_DIAGNOS
 class _CacheService:
     def __init__(self, metadata: CacheMetadata) -> None:
         self.metadata = metadata
+        self._rss_baseline_bytes = current_process_rss_bytes()
         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,
+            navigation_cache_dir=navigation_cache_path(
+                metadata.root,
+                create=True,
+            ),
         )
         self.budget = CacheBudget(metadata.max_memory_bytes)
         self.stats = CacheStats()
@@ -561,6 +665,15 @@ class _CacheService:
         self.prewarm_seconds = 0.0
         self.shutdown = threading.Event()
 
+    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()
         try:
@@ -571,7 +684,7 @@ class _CacheService:
                 raise
             self.cache_state = "ready"
         self.last_budget = self.budget.enforce(
-            measure=lambda: self.context.estimated_cache_bytes,
+            measure=self._measure_retained_bytes,
             evict_auxiliary=self.context.evict_auxiliary_caches,
             evict_navigation=self.context.evict_navigation_caches,
         )
@@ -612,7 +725,7 @@ class _CacheService:
             if before != after:
                 self.stats.invalidations += 1
             self.last_budget = self.budget.enforce(
-                measure=lambda: self.context.estimated_cache_bytes,
+                measure=self._measure_retained_bytes,
                 evict_auxiliary=self.context.evict_auxiliary_caches,
                 evict_navigation=self.context.evict_navigation_caches,
             )
@@ -648,6 +761,8 @@ class _CacheService:
             "prewarm_seconds": self.prewarm_seconds,
             "parallel_seconds": self.context.parallel_stats.elapsed_seconds,
             "parallel_fallbacks": self.stats.parallel_fallbacks,
+            "navigation_disk_hits": self.context.navigation_disk_hits,
+            "navigation_disk_misses": self.context.navigation_disk_misses,
             "idle_timeout": self.metadata.idle_timeout, "idle_remaining": max(0.0, self.metadata.idle_timeout - idle),
             "workspace_revision": self.last_revision,
         }
@@ -657,21 +772,34 @@ def _watch_filter(_change: object, path: str) -> bool:
     return Path(path).suffix.casefold() in _WATCHED_SUFFIXES
 
 
-def _watch_workspace(service: _CacheService) -> None:
+def watch_workspace_changes(
+    root: str | Path,
+    *,
+    stop_event: threading.Event,
+    on_change: Callable[[], None],
+) -> None:
     try:
         for changes in watch(
-            service.metadata.root,
+            root,
             watch_filter=_watch_filter,
-            stop_event=service.shutdown,
+            stop_event=stop_event,
             debounce=50,
             step=20,
             recursive=True,
             raise_interrupt=False,
         ):
             if changes:
-                service.context.invalidate_revision_cache()
+                on_change()
     except (OSError, RuntimeError):
-        service.context.invalidate_revision_cache()
+        on_change()
+
+
+def _watch_workspace(service: _CacheService) -> None:
+    watch_workspace_changes(
+        service.metadata.root,
+        stop_event=service.shutdown,
+        on_change=service.context.invalidate_revision_cache,
+    )
 
 
 def _serve_connection(connection: socket.socket, service: _CacheService) -> None:
@@ -849,6 +977,8 @@ def start_cache(
 ) -> 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.")
     with _start_lock(root, startup_timeout):
@@ -912,7 +1042,7 @@ def main(argv: list[str] | None = None) -> int:
     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)
+    serve.add_argument("--idle-timeout", type=_positive_integer, default=DEFAULT_IDLE_TIMEOUT)
     args = parser.parse_args(argv)
     if args.command == "serve":
         run_cache_daemon(
@@ -925,5 +1055,12 @@ def main(argv: list[str] | None = None) -> int:
     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())

{python_delphi_lsp-2.2.0 → python_delphi_lsp-2.3.1}/delphi_lsp/agent_cli.py

@@ -5,6 +5,7 @@ import json
 import math
 import os
 import sys
+import threading
 from pathlib import Path
 from typing import BinaryIO, TextIO
 
@@ -15,15 +16,17 @@ from .agent_cache import (
     DEFAULT_MAX_MEMORY_BYTES,
     DEFAULT_STARTUP_TIMEOUT,
     parse_memory_size,
+    navigation_cache_path,
     query_cache,
     run_cache_daemon,
     start_cache,
     stop_cache,
+    watch_workspace_changes,
 )
 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
+from .parallel_outline import ParallelOutlineError, parse_worker_setting
 
 
 _MAX_WORKER_RECORD_BYTES = 1024 * 1024
@@ -32,6 +35,14 @@ _INVALID_ENCODING_MESSAGE = "Invalid UTF-8 request."
 _REQUEST_TOO_LARGE_MESSAGE = "Request exceeds the 1 MiB limit."
 _INTERNAL_ERROR_MESSAGE = "Internal request error."
 _SOURCE_UNAVAILABLE_MESSAGE = "Selected source is unavailable."
+_WORKER_REVISION_CHECK_INTERVAL_SECONDS = 30.0
+
+
+class _CliError(RuntimeError):
+    def __init__(self, code: str, message: str) -> None:
+        self.code = code
+        self.message = message
+        super().__init__(message)
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -120,7 +131,7 @@ def build_parser() -> argparse.ArgumentParser:
     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.add_argument("--idle-timeout", type=_positive_integer, required=True)
     cache_serve.set_defaults(func=_cache_serve)
 
     query = subcommands.add_parser("query", help="Send an ergonomic request to a running cache daemon.")
@@ -131,8 +142,8 @@ def build_parser() -> argparse.ArgumentParser:
     query.add_argument("--detail", choices=SUPPORTED_DETAILS, default="summary")
     query.add_argument("--relation", choices=SUPPORTED_RELATIONS)
     query.add_argument("--cursor", default="")
-    query.add_argument("--max-items", type=int, default=12)
-    query.add_argument("--max-chars", type=int, default=12000)
+    query.add_argument("--max-items", type=_max_items, default=12)
+    query.add_argument("--max-chars", type=_max_chars, default=12000)
     query.set_defaults(func=_query)
 
     return parser
@@ -143,7 +154,7 @@ def _add_cache_start_arguments(parser: argparse.ArgumentParser) -> None:
     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("--idle-timeout", type=_positive_integer, default=DEFAULT_IDLE_TIMEOUT)
     parser.add_argument("--startup-timeout", type=_positive_float, default=DEFAULT_STARTUP_TIMEOUT)
 
 
@@ -154,6 +165,27 @@ def _positive_float(value: str) -> float:
     return parsed
 
 
+def _positive_integer(value: str) -> int:
+    parsed = int(value)
+    if parsed <= 0:
+        raise argparse.ArgumentTypeError("value must be greater than zero")
+    return parsed
+
+
+def _max_items(value: str) -> int:
+    parsed = int(value)
+    if not 1 <= parsed <= 50:
+        raise argparse.ArgumentTypeError("value must be between 1 and 50")
+    return parsed
+
+
+def _max_chars(value: str) -> int:
+    parsed = int(value)
+    if not 256 <= parsed <= 40000:
+        raise argparse.ArgumentTypeError("value must be between 256 and 40000")
+    return parsed
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = build_parser()
     args = parser.parse_args(argv)
@@ -161,9 +193,23 @@ def main(argv: list[str] | None = None) -> int:
         result = args.func(args)
         if not getattr(sys.stdout, "closed", False):
             sys.stdout.flush()
+    except _CliError as error:
+        sys.stderr.write(f"cli_error:{error.code}: {error.message}\n")
+        sys.stderr.flush()
+        return 1
+    except CacheClientError as error:
+        return _cache_error(error)
+    except ParallelOutlineError as error:
+        sys.stderr.write(f"cli_error:parallel_failed: {error}\n")
+        sys.stderr.flush()
+        return 1
     except BrokenPipeError:
         _discard_broken_stdout()
         os._exit(1)
+    except OSError as error:
+        sys.stderr.write(f"cli_error:io_error: {error}\n")
+        sys.stderr.flush()
+        return 1
     return result if isinstance(result, int) else 0
 
 
@@ -189,6 +235,7 @@ def _discard_broken_stdout() -> None:
 
 
 def _view(args: argparse.Namespace) -> None:
+    args.root = _workspace_root(args.root)
     index = build_codebase_index(
         args.root,
         project_file=args.project_file,
@@ -199,6 +246,7 @@ def _view(args: argparse.Namespace) -> None:
 
 
 def _index(args: argparse.Namespace) -> None:
+    args.root = _workspace_root(args.root)
     index = build_codebase_index(
         args.root,
         project_file=args.project_file,
@@ -216,33 +264,72 @@ def _index(args: argparse.Namespace) -> None:
 
 
 def _skill_install(args: argparse.Namespace) -> None:
-    skill_path = install_skill(args.target, force=args.force)
+    try:
+        skill_path = install_skill(args.target, force=args.force)
+    except FileExistsError as error:
+        raise _CliError("install_conflict", str(error)) from None
     print(skill_path)
 
 
 def _opencode_install(args: argparse.Namespace) -> None:
-    skill_path, plugin_path, agent_path = install_opencode_support(
-        args.target,
-        python_executable=args.python,
-        force=args.force,
-        write_config=args.write_config,
-    )
+    try:
+        skill_path, plugin_path, agent_path = install_opencode_support(
+            args.target,
+            python_executable=args.python,
+            force=args.force,
+            write_config=args.write_config,
+        )
+    except FileExistsError as error:
+        raise _CliError("install_conflict", str(error)) from None
     print(skill_path)
     print(plugin_path)
     print(agent_path)
 
 
 def _worker(args: argparse.Namespace) -> None:
-    context = AgentContext.open(args.root, args.project_file, workers=args.workers)
+    args.root = _workspace_root(args.root)
+    context = _open_worker_context(args.root, args.project_file, args.workers)
+    watcher_stop = threading.Event()
+    watcher = threading.Thread(
+        target=watch_workspace_changes,
+        kwargs={
+            "root": args.root,
+            "stop_event": watcher_stop,
+            "on_change": context.invalidate_revision_cache,
+        },
+        name="delphi-worker-watcher",
+        daemon=True,
+    )
+    watcher.start()
     try:
         _serve_worker(context, sys.stdin.buffer, sys.stdout.buffer, sys.stderr)
     finally:
+        watcher_stop.set()
+        watcher.join(timeout=2.0)
         try:
             sys.stdout.close()
         except (BrokenPipeError, OSError) as error:
             raise BrokenPipeError from error
 
 
+def _open_worker_context(
+    root: Path,
+    project_file: Path | None,
+    workers: int,
+) -> AgentContext:
+    try:
+        cache_dir: Path | None = navigation_cache_path(root, create=True)
+    except (CacheClientError, OSError):
+        cache_dir = None
+    return AgentContext.open(
+        root,
+        project_file,
+        workers=workers,
+        revision_check_interval_seconds=_WORKER_REVISION_CHECK_INTERVAL_SECONDS,
+        navigation_cache_dir=cache_dir,
+    )
+
+
 def _write_json(payload: object) -> None:
     sys.stdout.write(json.dumps(payload, ensure_ascii=False, sort_keys=True, separators=(",", ":")) + "\n")
 
@@ -260,6 +347,7 @@ def _cache_error(error: CacheClientError) -> int:
 
 
 def _cache_start(args: argparse.Namespace) -> int:
+    args.root = _workspace_root(args.root)
     try:
         start_cache(
             args.root,
@@ -278,6 +366,7 @@ def _cache_start(args: argparse.Namespace) -> int:
 
 
 def _cache_status(args: argparse.Namespace) -> int:
+    args.root = _workspace_root(args.root)
     try:
         response = query_cache(args.root, {"action": "status"})
     except CacheClientError as error:
@@ -295,6 +384,7 @@ def _cache_status(args: argparse.Namespace) -> int:
 
 
 def _cache_stop(args: argparse.Namespace) -> int:
+    args.root = _workspace_root(args.root)
     try:
         response = query_cache(args.root, {"action": "status"})
     except CacheClientError as error:
@@ -316,6 +406,7 @@ def _cache_stop(args: argparse.Namespace) -> int:
 
 
 def _cache_serve(args: argparse.Namespace) -> int:
+    args.root = _workspace_root(args.root)
     run_cache_daemon(
         args.root,
         project_file=str(args.project_file or ""),
@@ -327,6 +418,7 @@ def _cache_serve(args: argparse.Namespace) -> int:
 
 
 def _query(args: argparse.Namespace) -> int:
+    args.root = _workspace_root(args.root)
     request: dict[str, object] = {"action": args.action}
     if args.value:
         if args.action in {"find", "metrics"}:
@@ -350,6 +442,21 @@ def _query(args: argparse.Namespace) -> int:
     return 0
 
 
+def _workspace_root(value: str | Path) -> Path:
+    root = Path(value).expanduser()
+    if not root.exists():
+        raise _CliError(
+            "workspace_not_found",
+            f"Workspace root does not exist: {root}",
+        )
+    if not root.is_dir():
+        raise _CliError(
+            "workspace_not_directory",
+            f"Workspace root is not a directory: {root}",
+        )
+    return root.resolve()
+
+
 def _serve_worker(context: AgentContext, input_stream: BinaryIO, output_stream: BinaryIO, error_stream: TextIO) -> None:
     discarding_oversize_record = False
     while True: