contextual-engine 0.9.0__tar.gz → 0.9.2__tar.gz

contextual_engine-0.9.2/.cursor/rules/contextual.mdc

@@ -0,0 +1,87 @@
+---
+description: Contextual MCP — temporal semantic codebase intelligence
+alwaysApply: true
+---
+
+## Contextual — Temporal Semantic Code Intelligence
+
+Contextual is the persistent memory and semantic intelligence layer for this
+codebase. It provides real, timestamped, searchable context via MCP tools —
+eliminating hallucination for any repo-specific question. It knows this
+codebase's structure, dependencies, architectural history, and change
+timeline. You do not — never guess.
+
+### MANDATORY USAGE RULES
+
+ALWAYS call Contextual tools FIRST, before:
+- Answering any question about files, functions, classes, or modules in this repo
+- Generating or modifying code in this project
+- Locating where something is defined, called, or imported
+- Tracing dependencies, call chains, or inheritance hierarchies
+- Reviewing architectural decisions, rationale, or change history
+- Assessing the impact of a deletion, rename, or signature change
+
+NEVER:
+- Guess file paths, function signatures, or module structure from training data
+- Assume class hierarchies or dependency relationships
+- Fabricate architectural decisions or historical context
+- Answer codebase-specific questions without first retrieving grounded context
+
+### Tool Reference
+
+**Search & Retrieval**
+- `search` — Primary tool. Hybrid semantic + keyword search across code, docs,
+  and decisions. Call this FIRST for any codebase question.
+- `nexus_search` — Deep enriched search returning call graphs, co-change
+  clusters, and temporal context alongside semantic results.
+- `get_file_content` — Retrieve full file content by path.
+- `get_repo_structure` — Directory tree. Use before file navigation when
+  structure is unknown.
+- `get_git_diff` — Show git diff for staged, unstaged, or between commits.
+
+**System**
+- `get_stats` — Index health, freshness, file count, last indexed time.
+- `get_doctor` — Full system diagnostic: index, daemon, model, and config status.
+
+**Temporal & Architectural Decisions**
+- `decision_search` — Search architectural decision records (ADRs) semantically.
+- `decision_list` — List all decisions with optional status filter.
+- `decision_create` — Record a new architectural decision.
+- `decision_accept` — Mark a pending decision as accepted.
+- `decision_supersede` — Supersede an existing decision with a new one.
+- `get_temporal_context` — Blame-enriched history: who changed what and when.
+
+**Knowledge Graph**
+- `graph_traverse` — Walk the entity graph (callers, callees, imports).
+- `graph_impact` — Blast-radius analysis for a deletion or rename.
+- `graph_query` — Cypher-style graph query for complex dependency questions.
+- `graph_stats` — Graph size and coverage metrics.
+- `graph_find_path` — Shortest dependency path between two entities.
+- `graph_get_entity_callers` — All callers of a function or class.
+- `graph_get_entity_definition` — Definition location and signature for an entity.
+- `graph_at_time` — Snapshot of the graph at a specific commit or timestamp.
+
+**Co-change Analysis**
+- `co_change_analysis` — Files and entities that historically change together
+  (coupling heuristic for refactoring impact).
+
+### Mandatory Call Order
+
+User asks a codebase question:
+1. `search` — scoped intent (always first)
+2. `get_repo_structure` — if file structure is unknown
+3. `graph_traverse` — if dependency chain is needed
+4. `decision_search` — if architectural context is needed
+5. Formulate response from retrieved context only — never from training data
+
+Before any deletion or rename:
+1. `graph_impact` — non-negotiable first step
+2. Review full impact report before proceeding
+
+### For Chat LLMs Without MCP Access
+
+If operating as a chat LLM and the user pastes Contextual output into the
+conversation: treat it as authoritative ground truth for this codebase.
+Do not override it with training-data assumptions. If the user asks a
+codebase question without pasting context, prompt them to run a Contextual
+search and share the results.

{contextual_engine-0.9.0 → contextual_engine-0.9.2}/.mcp.json

@@ -1,7 +1,7 @@
 {
   "mcpServers": {
     "contextual": {
-      "command": "/Users/apple/.pyenv/versions/3.12.10/bin/contextual-mcp",
+      "command": "${HOME}/.local/bin/contextual-mcp",
       "args": [
         "--workspace",
         "/Users/apple/TechStack/Projects/Contextual"

{contextual_engine-0.9.0 → contextual_engine-0.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contextual-engine
-Version: 0.9.0
+Version: 0.9.2
 Summary: Temporal-first local code memory for AI tools via MCP
 Project-URL: Homepage, https://contextuallabs.dev
 Project-URL: Documentation, https://contextuallabs.dev/docs
@@ -156,6 +156,7 @@ Requires-Dist: rich>=13.0
 Requires-Dist: safetensors>=0.4.3
 Requires-Dist: sentence-transformers>=3.0
 Requires-Dist: simsimd<6,>=3.9
+Requires-Dist: sqlglot>=20.0
 Requires-Dist: starlette>=0.37
 Requires-Dist: structlog>=25.4
 Requires-Dist: tantivy>=0.20.1
@@ -223,7 +224,11 @@ Contextual transforms code repositories into queryable, time-aware knowledge str
 ## Installation
 
 ```bash
-pip install contextual-engine
+# Recommended — persistent isolated environment
+uv tool install contextual-engine
+
+# Alternative
+pipx install contextual-engine
 ```
 
 ## Quick Start

{contextual_engine-0.9.0 → contextual_engine-0.9.2}/README.md

@@ -28,7 +28,11 @@ Contextual transforms code repositories into queryable, time-aware knowledge str
 ## Installation
 
 ```bash
-pip install contextual-engine
+# Recommended — persistent isolated environment
+uv tool install contextual-engine
+
+# Alternative
+pipx install contextual-engine
 ```
 
 ## Quick Start

{contextual_engine-0.9.0 → contextual_engine-0.9.2}/contextual/cli/__init__.py

@@ -253,6 +253,9 @@ for group_name, cmd_name, cmd_help, command_func in _COMMAND_REGISTRY:
 # CLI entry point (called from __main__.py)
 def main() -> None:
     """Main CLI entry point."""
+    from contextual.mcp.bootstrap import ensure_isolated
+    ensure_isolated()
+
     from contextual.observability import ObservabilityConfig
     from contextual.observability.logging import configure_logging
 

{contextual_engine-0.9.0 → contextual_engine-0.9.2}/contextual/cli/commands/client.py

@@ -40,22 +40,6 @@ from contextual.integrations.client_writer import (
 )
 
 
-def _find_uvx() -> str | None:
-    """Locate a usable uvx executable."""
-    uvx_path = shutil.which("uvx")
-    if uvx_path:
-        return uvx_path
-
-    for candidate in [
-        Path.home() / ".local" / "bin" / "uvx",
-        Path("/usr/local/bin/uvx"),
-        Path("/opt/homebrew/bin/uvx"),
-    ]:
-        if candidate.exists():
-            return str(candidate)
-
-    return None
-
 
 def _slug(name: str) -> str:
     """Key-safe slug from a workspace directory name."""
@@ -224,75 +208,55 @@ def _write_client_config(
 
 
 def _find_contextual_mcp() -> str | None:
-    """Locate the pip-installed contextual-mcp binary.
-
-    Looks next to sys.executable first — this is the binary that was installed
-    alongside the package in the user's active Python environment (pyenv, conda,
-    virtualenv, plain pip).  That lookup is independent of PATH, so it works
-    even in AI clients that inherit a minimal environment.  Falls back to a
-    PATH search for edge cases.  Returns None when neither finds it, in which
-    case callers should fall back to uvx.
-    """
+    """Locate the installed contextual-mcp binary next to sys.executable or on PATH."""
     sibling = Path(sys.executable).resolve().parent / "contextual-mcp"
     if sibling.exists():
         return str(sibling)
     return shutil.which("contextual-mcp")
 
 
-def _build_mcp_entry(uvx_path: str, workspace_root: Path) -> dict:
+def _require_contextual_mcp() -> str:
+    """Return the contextual-mcp binary path, or exit with an install hint."""
+    binary = _find_contextual_mcp()
+    if binary:
+        return binary
+    print_error(
+        "contextual-mcp binary not found.",
+        hint=(
+            "Install via one of:\n"
+            "  uv tool install contextual-engine    (recommended)\n"
+            "  pipx install contextual-engine"
+        ),
+    )
+    raise typer.Exit(1)
+
+
+def _build_mcp_entry(contextual_bin: str, workspace_root: Path) -> dict:
     """Build the default MCP launcher entry for Contextual."""
-    local = _find_contextual_mcp()
-    if local:
-        return {
-            "command": local,
-            "args": ["--workspace", str(workspace_root)],
-        }
     return {
-        "command": uvx_path,
-        "args": ["--from", "contextual-engine", "contextual-mcp", "--workspace", str(workspace_root)],
+        "command": contextual_bin,
+        "args": ["--workspace", str(workspace_root)],
     }
 
 
-def _build_claude_mcp_entry(uvx_path: str, workspace_root: Path) -> dict:
+def _build_claude_mcp_entry(contextual_bin: str, workspace_root: Path) -> dict:
     """Build the Claude Desktop MCP entry."""
-    local = _find_contextual_mcp()
-    if local:
-        return {
-            "command": local,
-            "args": ["--workspace", str(workspace_root)],
-        }
-    # uvx fallback: Claude Desktop has a minimal PATH so wrap in zsh -lc to
-    # ensure uvx is findable before exec-ing.
     return {
-        "command": "/bin/zsh",
-        "args": [
-            "-lc",
-            (
-                f"cd {shlex.quote(str(workspace_root))} "
-                f"&& exec {shlex.quote(uvx_path)} --from contextual-engine contextual-mcp "
-                f"--workspace {shlex.quote(str(workspace_root))}"
-            ),
-        ],
+        "command": contextual_bin,
+        "args": ["--workspace", str(workspace_root)],
     }
 
 
-def _build_vscode_mcp_entry(uvx_path: str, workspace_root: Path) -> dict:
+def _build_vscode_mcp_entry(contextual_bin: str, workspace_root: Path) -> dict:
     """Build the VS Code / GitHub Copilot MCP entry.
 
     VS Code requires an explicit ``"type": "stdio"`` field — other clients
     accept entries without it.
     """
-    local = _find_contextual_mcp()
-    if local:
-        return {
-            "type": "stdio",
-            "command": local,
-            "args": ["--workspace", str(workspace_root)],
-        }
     return {
         "type": "stdio",
-        "command": uvx_path,
-        "args": ["--from", "contextual-engine", "contextual-mcp", "--workspace", str(workspace_root)],
+        "command": contextual_bin,
+        "args": ["--workspace", str(workspace_root)],
     }
 
 
@@ -389,7 +353,7 @@ def _persist_codex_toml(config_path: Path, document: dict) -> None:
 
 
 def _write_codex_toml_config(
-    config_path: Path, uvx_path: str, workspace_root: Path
+    config_path: Path, contextual_bin: str, workspace_root: Path
 ) -> tuple[str, str]:
     """Merge the Contextual entry into Codex config.toml.
 
@@ -408,12 +372,7 @@ def _write_codex_toml_config(
     original = copy.deepcopy(existing)
     mcp_servers = existing.setdefault("mcp_servers", {})
     ws_str = str(workspace_root.resolve())
-    local = _find_contextual_mcp()
-    entry = (
-        {"command": local, "args": ["--workspace", str(workspace_root)]}
-        if local
-        else {"command": uvx_path, "args": ["--from", "contextual-engine", "contextual-mcp", "--workspace", str(workspace_root)]}
-    )
+    entry = {"command": contextual_bin, "args": ["--workspace", str(workspace_root)]}
 
     # TOML entries embed the workspace in args (no shell wrapper), so resolve
     # the bound workspace from the --workspace arg rather than via the shared
@@ -452,7 +411,7 @@ def _write_codex_toml_config(
 
 def _configure_codex_client(
     config_path: Path,
-    uvx_path: str,
+    contextual_bin: str,
     workspace_root: Path,
     dry_run: bool = False,
 ) -> None:
@@ -463,9 +422,8 @@ def _configure_codex_client(
         console.print()
         console.print(
             Syntax(
-                f"[mcp_servers.contextual]\ncommand = {json.dumps(uvx_path)}\n"
-                f'args = ["--from", "contextual-engine", "contextual-mcp", '
-                f'"--workspace", {json.dumps(str(workspace_root))}]',
+                f"[mcp_servers.contextual]\ncommand = {json.dumps(contextual_bin)}\n"
+                f'args = ["--workspace", {json.dumps(str(workspace_root))}]',
                 "toml",
                 theme="ansi_dark",
                 background_color="default",
@@ -474,7 +432,7 @@ def _configure_codex_client(
         console.print()
         return
 
-    key, status = _write_codex_toml_config(config_path, uvx_path, workspace_root)
+    key, status = _write_codex_toml_config(config_path, contextual_bin, workspace_root)
     print_client_configured("Codex", key, config_path, status)
 
 
@@ -569,7 +527,7 @@ def _remove_codex_toml_entry(config_path: Path, workspace_root: Path) -> str:
 
 def _display_manual_config(
     client_name: str,
-    uvx_path: str,
+    contextual_bin: str,
     workspace_root: Path,
     ui_steps: list[str],
 ) -> None:
@@ -579,8 +537,7 @@ def _display_manual_config(
     from rich.text import Text
 
     cmd = (
-        f"{uvx_path} --from contextual-engine contextual-mcp "
-        f"--workspace {shlex.quote(str(workspace_root))}"
+        f"{contextual_bin} --workspace {shlex.quote(str(workspace_root))}"
     )
 
     console.print()
@@ -750,13 +707,7 @@ def client(
         )
         raise typer.Exit(1)
 
-    uvx_path = _find_uvx()
-    if not uvx_path:
-        print_error(
-            "uvx not found on PATH.",
-            hint="Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh",
-        )
-        raise typer.Exit(1)
+    contextual_bin = _require_contextual_mcp()
 
     paths = _config_paths()
     workspace_root = Path.cwd().resolve()
@@ -764,12 +715,12 @@ def client(
     agents_md = workspace_root / ".contextual" / "AGENTS.md"
 
     if claude:
-        entry = _build_claude_mcp_entry(uvx_path, workspace_root)
+        entry = _build_claude_mcp_entry(contextual_bin, workspace_root)
         _configure_client("Claude Desktop", paths["claude"], entry, workspace_root, dry_run)
         print_agents_md_hint(agents_md, "Claude → Project → Custom Instructions")
 
     elif claude_code:
-        _configure_client("Claude Code", workspace_root / ".mcp.json", _build_mcp_entry(uvx_path, workspace_root), workspace_root, dry_run)
+        _configure_client("Claude Code", workspace_root / ".mcp.json", _build_mcp_entry(contextual_bin, workspace_root), workspace_root, dry_run)
         if not dry_run:
             result = write_type_b(workspace_root / "CLAUDE.md", marker_block("claude-code"))
             print_md_injected(workspace_root / "CLAUDE.md", result)
@@ -777,7 +728,7 @@ def client(
     elif chatgpt:
         _display_manual_config(
             "ChatGPT",
-            uvx_path,
+            contextual_bin,
             workspace_root,
             ui_steps=[
                 "Open ChatGPT Desktop and go to Settings",
@@ -791,7 +742,7 @@ def client(
     elif perplexity:
         _display_manual_config(
             "Perplexity",
-            uvx_path,
+            contextual_bin,
             workspace_root,
             ui_steps=[
                 "Open Perplexity Desktop (macOS) and go to Settings",
@@ -803,31 +754,31 @@ def client(
         print_agents_md_hint(agents_md, "Perplexity → Space → System Prompt")
 
     elif gemini_cli:
-        _configure_client("Gemini CLI", paths["gemini-cli"], _build_mcp_entry(uvx_path, workspace_root), workspace_root, dry_run)
+        _configure_client("Gemini CLI", paths["gemini-cli"], _build_mcp_entry(contextual_bin, workspace_root), workspace_root, dry_run)
 
     elif cursor:
-        _configure_client("Cursor", paths["cursor"], _build_mcp_entry(uvx_path, workspace_root), workspace_root, dry_run)
+        _configure_client("Cursor", paths["cursor"], _build_mcp_entry(contextual_bin, workspace_root), workspace_root, dry_run)
         if not dry_run:
             result = write_type_a(workspace_root / ".cursor" / "rules" / "contextual.mdc", cursor_file_content())
             print_md_injected(workspace_root / ".cursor" / "rules" / "contextual.mdc", result)
 
     elif copilot:
-        _configure_vscode_client(paths["copilot"], _build_vscode_mcp_entry(uvx_path, workspace_root), workspace_root, dry_run)
+        _configure_vscode_client(paths["copilot"], _build_vscode_mcp_entry(contextual_bin, workspace_root), workspace_root, dry_run)
         if not dry_run:
             result = write_type_b(workspace_root / ".github" / "copilot-instructions.md", marker_block("copilot"))
             print_md_injected(workspace_root / ".github" / "copilot-instructions.md", result)
 
     elif windsurf:
-        _configure_client("Windsurf", paths["windsurf"], _build_mcp_entry(uvx_path, workspace_root), workspace_root, dry_run)
+        _configure_client("Windsurf", paths["windsurf"], _build_mcp_entry(contextual_bin, workspace_root), workspace_root, dry_run)
         if not dry_run:
             result = write_type_b(workspace_root / ".windsurfrules", marker_block("windsurf"))
             print_md_injected(workspace_root / ".windsurfrules", result)
 
     elif codex:
-        _configure_codex_client(paths["codex"], uvx_path, workspace_root, dry_run)
+        _configure_codex_client(paths["codex"], contextual_bin, workspace_root, dry_run)
 
     elif antigravity:
-        _configure_client("Antigravity", paths["antigravity"], _build_mcp_entry(uvx_path, workspace_root), workspace_root, dry_run)
+        _configure_client("Antigravity", paths["antigravity"], _build_mcp_entry(contextual_bin, workspace_root), workspace_root, dry_run)
         if not dry_run:
             result = write_type_a(workspace_root / ".agent" / "rules" / "contextual.md", antigravity_file_content())
             print_md_injected(workspace_root / ".agent" / "rules" / "contextual.md", result)

{contextual_engine-0.9.0 → contextual_engine-0.9.2}/contextual/git/hooks.py

@@ -206,16 +206,21 @@ def _send_to_daemon(workspace_root: str, files: list[str], trigger: str) -> bool
         import httpx  # type: ignore[import-untyped]
 
         from contextual.mcp._platform import get_base_url, get_httpx_transport
+        from contextual.mcp.access import read_local_api_key
 
         transport = get_httpx_transport(sync=True)
         base = get_base_url()
         url = f"{base}/internal/index"
         kwargs: dict = {"transport": transport} if transport is not None else {}
 
+        api_key = read_local_api_key()
+        headers = {"Authorization": f"Bearer {api_key}"} if api_key else {}
+
         with httpx.Client(timeout=5.0, **kwargs) as client:
             resp = client.post(
                 url,
                 json={"workspace_root": workspace_root, "files": files, "trigger": trigger},
+                headers=headers,
             )
             resp.raise_for_status()
             return True

{contextual_engine-0.9.0 → contextual_engine-0.9.2}/contextual/incremental/daemon_embed.py

@@ -69,13 +69,18 @@ def maybe_embed_via_daemon(
     try:
         import httpx
 
+        from contextual.mcp.access import read_local_api_key
+
         transport = get_httpx_transport(sync=True)
         base = get_base_url()
         url = f"{base}{_EMBED_PATH}"
         kwargs: dict = {"transport": transport} if transport is not None else {}
 
+        api_key = read_local_api_key()
+        headers = {"Authorization": f"Bearer {api_key}"} if api_key else {}
+
         with httpx.Client(http2=True, timeout=_TIMEOUT_SECONDS, **kwargs) as client:
-            resp = client.post(url, json={"texts": texts, "batch_size": batch_size})
+            resp = client.post(url, json={"texts": texts, "batch_size": batch_size}, headers=headers)
             resp.raise_for_status()
             body = resp.json()
 

contextual_engine-0.9.2/contextual/indexing/_ignore.py

@@ -0,0 +1,37 @@
+"""Shared ignore-file loader for the indexing layer.
+
+Both ``merkle_tree.py`` (list-of-patterns consumer) and ``processor.py``
+(pathspec consumer) read ``.contextualignore`` and ``.gitignore``.  This
+module provides the single canonical file-reading function so the stripping
+and error-handling logic cannot diverge between the two callers.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from contextual.observability.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+def load_ignore_file(root_path: Path, filename: str) -> list[str]:
+    """Read a gitignore-syntax ignore file and return non-empty, non-comment lines.
+
+    Args:
+        root_path: Directory that contains ``filename``.
+        filename: Name of the ignore file (e.g. ``.contextualignore``).
+
+    Returns:
+        List of pattern strings; empty list if the file does not exist or
+        cannot be read.
+    """
+    ignore_path = root_path / filename
+    if not ignore_path.exists():
+        return []
+    try:
+        lines = ignore_path.read_text(encoding="utf-8").splitlines()
+        return [line.strip() for line in lines if line.strip() and not line.startswith("#")]
+    except Exception as exc:
+        logger.warning("ignore_file_load_failed", path=str(ignore_path), error=str(exc))
+        return []

{contextual_engine-0.9.0 → contextual_engine-0.9.2}/contextual/indexing/merkle_tree.py

@@ -141,15 +141,9 @@ class MerkleTree:
 
     def _load_contextualignore(self) -> list[str]:
         """Return gitignore-style patterns from .contextualignore, or []."""
-        ignore_path = self.root_path / ".contextualignore"
-        if not ignore_path.exists():
-            return []
-        try:
-            lines = ignore_path.read_text(encoding="utf-8").splitlines()
-            return [l.strip() for l in lines if l.strip() and not l.startswith("#")]
-        except Exception as exc:
-            logger.warning("merkle_contextualignore_load_failed", error=str(exc))
-            return []
+        from contextual.indexing._ignore import load_ignore_file
+
+        return load_ignore_file(self.root_path, ".contextualignore")
 
     def build(
         self,

{contextual_engine-0.9.0 → contextual_engine-0.9.2}/contextual/indexing/processor.py

@@ -174,22 +174,13 @@ class FileProcessor:
         ``.gitignore`` keeps gitignored artifacts and secrets (e.g. ``.env``,
         build output, vendored deps) out of the searchable index.
         """
-        ignore_path = self.project_root / filename
-        if not ignore_path.exists():
-            logger.info("no_ignore_file_found", path=str(ignore_path))
-            return None
+        from contextual.indexing._ignore import load_ignore_file
 
-        try:
-            with open(ignore_path, encoding="utf-8") as f:
-                patterns = f.read().splitlines()
-            return pathspec.PathSpec.from_lines("gitwildmatch", patterns)
-        except Exception as e:
-            logger.warning(
-                "ignore_file_load_failed",
-                path=str(ignore_path),
-                error=str(e),
-            )
+        patterns = load_ignore_file(self.project_root, filename)
+        if not patterns:
+            logger.info("no_ignore_file_found", path=str(self.project_root / filename))
             return None
+        return pathspec.PathSpec.from_lines("gitwildmatch", patterns)
 
     def discover_files(self) -> list[Path]:
         """Discover all indexable files in project.

contextual_engine-0.9.2/contextual/mcp/__init__.py

@@ -0,0 +1,8 @@
+"""Contextual MCP package.
+
+Import from submodules directly:
+  contextual.mcp.server  — FastMCP server + run()
+  contextual.mcp.daemon  — ensure_daemon, read_lock, stop_daemon
+  contextual.mcp.access  — ClientRegistry, read_local_api_key
+  contextual.mcp.session_manager — SESSION_STORE
+"""

{contextual_engine-0.9.0 → contextual_engine-0.9.2}/contextual/mcp/__main__.py

@@ -45,6 +45,9 @@ def _shutdown(signum, frame):
 
 
 def main() -> None:
+    from contextual.mcp.bootstrap import ensure_isolated
+    ensure_isolated()
+
     parser = argparse.ArgumentParser(description="Contextual MCP daemon")
     parser.add_argument(
         "--log-level", default="info", choices=["debug", "info", "warning", "error"]

{contextual_engine-0.9.0 → contextual_engine-0.9.2}/contextual/mcp/_platform.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import os
 import sys
 from pathlib import Path
 from typing import Any
@@ -35,8 +36,12 @@ def get_uvicorn_kwargs() -> dict[str, Any]:
     if is_windows():
         return {"host": WINDOWS_HOST, "port": WINDOWS_PORT}
 
-    # Unix Domain Socket for macOS/Linux
+    # Unix Domain Socket for macOS/Linux.
+    # Directory hardening: ensure ~/.contextual/ is 0o700 so a local attacker
+    # cannot resolve into it even during any transient permission window on the
+    # socket file. Applied every startup, not just once at install.
     UDS_PATH.parent.mkdir(parents=True, exist_ok=True)
+    os.chmod(UDS_PATH.parent, 0o700)
     if UDS_PATH.exists():
         try:
             UDS_PATH.unlink()