codegraph-engine 2.1.7__tar.gz → 2.2.0__tar.gz

{codegraph_engine-2.1.7 → codegraph_engine-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codegraph-engine
-Version: 2.1.7
+Version: 2.2.0
 Summary: Deep deterministic repository intelligence for AI coding agents (code, dependencies, databases, and runtime observations)
 Author: CodeGraph contributors
 License-Expression: MIT
@@ -35,23 +35,24 @@ Dynamic: license-file
   <img src="docs/assets/codegraph_logo.jpg" alt="CodeGraph MCP — Deep Deterministic Repository Intelligence for AI Coding Agents" width="500" />
 </p>
 
-<h1 align="center">CodeGraph Engine (v2.1.7)</h1>
+<h1 align="center">CodeGraph-MCP Engine (v2.2.0)</h1>
 
 <p align="center">
   <strong>Deep deterministic repository intelligence for AI coding agents.</strong>
 </p>
 
 <p align="center">
-  <a href="https://github.com/raghurammrsd/CODE_GRAPH_MCP"><img src="https://img.shields.io/badge/package-codegraph--engine%20v2.1.7-blue.svg" alt="Package: codegraph-engine v2.1.7" /></a>
+  <a href="https://pypi.org/project/codegraph-engine/2.2.0/"><img src="https://img.shields.io/badge/pypi-codegraph--engine%20v2.2.0-blue.svg" alt="PyPI: codegraph-engine v2.2.0" /></a>
   <a href="pyproject.toml"><img src="https://img.shields.io/badge/python-3.12%20%7C%203.13-3776AB.svg" alt="Python 3.12 | 3.13" /></a>
   <a href="src/codegraph/mcp/server.py"><img src="https://img.shields.io/badge/MCP-14%20default%20%7C%2056%20full%20tools-2ea043.svg" alt="MCP Tools: 14 default | 56 full" /></a>
-  <a href="tests/"><img src="https://img.shields.io/badge/pytest-842%20passed-brightgreen.svg" alt="Tests: 842 passed" /></a>
+  <a href="tests/"><img src="https://img.shields.io/badge/pytest-861%20passed-brightgreen.svg" alt="Tests: 861 passed" /></a>
   <a href="pyproject.toml"><img src="https://img.shields.io/badge/ruff-0%20errors-success.svg" alt="Ruff: 0 errors" /></a>
-  <a href="src/codegraph/"><img src="https://img.shields.io/badge/mypy-0%20issues%20(77%20files)-blue.svg" alt="Mypy: strict" /></a>
+  <a href="src/codegraph/"><img src="https://img.shields.io/badge/mypy-0%20issues%20(80%20files)-blue.svg" alt="Mypy: strict" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
 </p>
 
 <p align="center">
+  <a href="https://pypi.org/project/codegraph-engine/2.2.0/"><strong>PyPI (v2.2.0)</strong></a> •
   <a href="#2-quickstart-30-second-setup"><strong>Quickstart</strong></a> •
   <a href="#1-built-for-aiml-and-backend-heavy-repositories"><strong>Built For</strong></a> •
   <a href="#5-database-intelligence"><strong>Database Intelligence</strong></a> •
@@ -125,7 +126,7 @@ pip install "codegraph-engine[mcp]"
 
 ### Step 2: Configure Your AI Coding Agents (`codegraph install`)
 
-CodeGraph includes an interactive, idempotent onboarding installer ([`src/codegraph/installer.py`](src/codegraph/installer.py)) that detects installed AI coding agents (**Claude Code**, **Cursor**, **Antigravity**, **Codex CLI**, **Gemini CLI**, and **Cline**), configures `mcpServers.codegraph`, installs marker-bounded routing instructions (`<!-- CODEGRAPH:START -->` … `<!-- CODEGRAPH:END -->`), and verifies MCP server startup:
+CodeGraph-MCP includes an interactive, idempotent onboarding installer ([`src/codegraph/installer.py`](src/codegraph/installer.py)) that detects installed AI coding agents (**Claude Code**, **Cursor**, **Antigravity**, **Codex CLI**, **Gemini CLI**, and **Cline**), configures `mcpServers.codegraph`, installs marker-bounded routing instructions (`<!-- CODEGRAPH:START -->` … `<!-- CODEGRAPH:END -->`), and verifies MCP server startup:
 
 ```bash
 # Interactive setup (detects installed agents, previews planned changes, asks confirmation)
@@ -147,18 +148,31 @@ codegraph status
 codegraph doctor
 ```
 
-### Managing Installation & Project Index Lifecycle
+> **Dynamic Index Hot-Reloading:** If your AI coding agent launches `codegraph mcp serve` before you run `codegraph init`, you do **not** need to restart your IDE or MCP session. As soon as `codegraph init` or `codegraph index` creates or updates `.codegraph.sqlite3`, the running MCP server automatically detects the updated database on the next tool call and refreshes its in-memory graph cache (`get_repository_status(reload=True, reindex=True)` can also be invoked directly by the agent).
 
-CodeGraph cleanly separates agent configuration from project index files:
+### Managing Installation, Process & Project Index Lifecycle
+
+CodeGraph cleanly separates agent configuration, process lifecycle, and project index files:
 
 | Command | Scope | What It Does |
 | :--- | :--- | :--- |
-| `codegraph install` | Agent configuration | Configures MCP server + marker-managed rules/skills for selected AI agents. |
-| `codegraph init` | Project repository | Initializes `.codegraph.sqlite3` and indexes the current repository. |
+| `codegraph install` | Agent configuration | Configures MCP server + marker-managed rules/skills for selected AI agents (ASCII-safe on Windows `cp1252`). |
+| `codegraph init` | Project repository | Initializes `.codegraph.sqlite3` and indexes the current repository (hot-reloaded automatically by running MCP servers). |
 | `codegraph index` | Project repository | Incrementally indexes modified files (`--verbose`, `--quiet`, `--json`). |
-| `codegraph uninstall` | Agent configuration | Removes only CodeGraph-managed MCP entries and instruction blocks (preserves user config and project index). |
+| `codegraph stop` | Process lifecycle | Safely stops running CodeGraph-owned MCP background processes (`--all`, `--repo`, `--json`) and releases file locks. |
+| `codegraph doctor --processes` | Process lifecycle | Lists active CodeGraph MCP processes, parent PIDs, orphan status, and cleans stale PID files. |
+| `codegraph uninstall` | Agent configuration | Stops active workspace MCP processes and removes CodeGraph-managed MCP entries and instruction blocks. |
 | `codegraph uninit` | Project repository | Removes only `.codegraph.sqlite3` and `.codegraph/` in the project (never touches source code or Git history). |
 
+### Safe Upgrading on Windows (`WinError 32` Prevention)
+
+On Windows, running `pip install --upgrade codegraph-engine` while an IDE or agent still holds `codegraph.exe` open can trigger `WinError 32`. Before upgrading on Windows, run:
+
+```bash
+codegraph stop --all
+pip install --upgrade "codegraph-engine[mcp]"
+```
+
 ---
 
 ## 3. Core Workflow & Architecture
@@ -218,7 +232,7 @@ InferenceService.run_inference
                                    db:table:postgresql.public.prediction_logs
 ```
 
-**What CodeGraph structurally proves**:
+**What CodeGraph-MCP structurally proves**:
 - `find_routes(path="/v1/predict")` resolves composed router prefixes (`MOUNTS`) to `predict_endpoint`.
 - `trace_path(from_symbol="predict_endpoint", to_symbol="log_prediction")` proves the multi-hop execution chain across DI injection, preprocessing, model execution, and persistence.
 - `get_db_impact(symbol="InferenceService.run_inference")` identifies downstream writes to `prediction_logs`.
@@ -236,7 +250,7 @@ TrainingPipeline.run
       └──►CALLS (AST_VERIFIED) ──► Evaluator.compute_metrics
 ```
 
-**What CodeGraph structurally proves**:
+**What CodeGraph-MCP structurally proves**:
 - `find_callees(symbol="TrainingPipeline.run")` enumerates every stage of the pipeline with exact file and line ranges.
 - `find_tests(symbol="Evaluator.compute_metrics")` locates the unit and regression tests covering metric calculation.
 - When a transform or model class is dynamically instantiated from a YAML string (`getattr(models, cfg.arch)`), CodeGraph explicitly records `POSSIBLE_CALLS` (`POSSIBLE`) or `UNRESOLVED_REFERENCE` (`UNKNOWN`) rather than fabricating a false static call edge.
@@ -255,7 +269,7 @@ AgentRunner.execute_step
       └──►CALLS (AST_VERIFIED)           ──► ModelProviderClient.generate
 ```
 
-**What CodeGraph structurally proves**:
+**What CodeGraph-MCP structurally proves**:
 - Tracks decorator and call-based registrations (`@tool_registry.register("search_orders")`) via `REGISTERS` and `REGISTERED_HANDLER` edges.
 - Tracks environment variable dependencies (`os.getenv("OPENAI_API_KEY")`) as `READS_ENV` edges with the variable name only—never indexing or exposing secret values.
 
@@ -419,20 +433,23 @@ Rather than claiming a single universal token reduction percentage across all po
 | **Compression at `budget = 200 tokens`** | `85.6%` reduction | [`benchmarks/baselines/context_baseline.json`](benchmarks/baselines/context_baseline.json) |
 | **Compression at `budget = 600 tokens`** | `56.3%` reduction | [`benchmarks/baselines/context_baseline.json`](benchmarks/baselines/context_baseline.json) |
 | **Cold vs. Warm `get_context` Latency (`p50`)** | `20.0 ms` cold → `0.67 ms` warm (`30.0x`) | [`benchmarks/baselines/context_baseline.json`](benchmarks/baselines/context_baseline.json) |
+| **Single-Tool Query Latency (Indexed SQLite)** | `1 ms – 15 ms` | Local SQLite B-tree / FTS5 lookup |
 | **FACT / UNKNOWN / AMBIGUITY Correctness** | `100.0%` / `98.0%` / `100.0%` | [`benchmarks/baselines/v2_0_verified.json`](benchmarks/baselines/v2_0_verified.json) |
 
 ### Results from the 32-Task Internal Evaluation ([`src/codegraph/tool_selection_eval.py`](src/codegraph/tool_selection_eval.py))
 
-The table below reports results from the **32-task internal evaluation harness** (`run_tool_selection_ab_benchmark()`) comparing Mode A (unassisted exploration without CodeGraph routing rules) against Mode B (CodeGraph MCP + agent routing rules) on the same 32 tasks:
+The table below reports results from the **32-task internal evaluation harness** (`run_tool_selection_ab_benchmark()`) comparing Mode A (unassisted `grep` + full-file reading without CodeGraph routing rules) against Mode B (CodeGraph MCP + agent routing rules) on the same 32 tasks:
 
-| Metric (32-Task Internal Evaluation) | Mode A (Baseline) | Mode B (CodeGraph MCP) | Delta |
+| Metric (32-Task Internal Evaluation) | Mode A (Without CodeGraph) | Mode B (With CodeGraph MCP) | Measured Improvement |
 | :--- | ---: | ---: | :--- |
-| **Total Tool Calls** | `164` | `71` | `-93 calls (-56.7%)` |
-| **Direct Full-File Reads** | `161` | `7` | `-154 file reads (-95.7%)` |
-| **First-Tool Selection Accuracy** | `9.38%` | `100.0%` | `+90.62%` |
-| **Unsupported Claims** | `11 (34.38%)` | `0 (0.00%)` | `-11 claims` |
-| **Task Accuracy** | `59.84%` | `100.0%` | `+40.16%` |
-| **12-Prompt Natural-Language Routing Eval** | — | `12 / 12 (100.0%)` | `12/12 on this evaluation set` |
+| **Total Tool Calls (32 Tasks)** | `164 calls` (`~5.1 / task`) | `71 calls` (`~2.2 / task`) | **`-93 calls (-56.7% fewer tool calls)`** |
+| **Direct Full-File Reads** | `161 full-file reads` | `7 bounded slice reads` | **`-154 file reads (-95.7% fewer file reads)`** |
+| **Context Tokens per Task** | `3,000 – 12,000+ tokens` (full files) | `~542 tokens` avg (`get_context`) | **`65.0% – 85.6% token reduction`** |
+| **Query Latency (`p50`)** | Hundreds of ms (multi-step `grep` + reads) | `20.0 ms` cold / `0.67 ms` warm (`30.0x`) | **Sub-20ms indexed lookup** |
+| **First-Tool Selection Accuracy** | `9.38%` | `100.0%` | **`+90.62%`** |
+| **Unsupported Claims (Hallucinated Edges)** | `11 (34.38%)` | `0 (0.00%)` | **`-11 claims (0% unsupported)`** |
+| **Task Accuracy** | `59.84%` | `100.0%` | **`+40.16%`** |
+| **12-Prompt Natural-Language Routing Eval** | — | `12 / 12 (100.0%)` | **`12/12 on this evaluation set`** |
 
 ![CodeGraph — Measured Context & Exploration Efficiency](docs/assets/performance_comparison.svg)
 
@@ -540,6 +557,12 @@ codegraph index . --verbose                                # Incremental index w
 codegraph index . --json                                   # Output structured JSON phase telemetry
 codegraph uninit --dry-run                                 # Preview removal of .codegraph.sqlite3
 
+# Process Lifecycle & Upgrade Lock Safety
+codegraph stop                                             # Safely stop CodeGraph MCP server for current repo
+codegraph stop --all                                       # Stop all CodeGraph-owned MCP processes across repos
+codegraph stop --repo /path/to/repo --json                 # Stop MCP processes for a specific repo (JSON output)
+codegraph doctor --processes                               # Inspect active MCP processes, parent PIDs, & stale locks
+
 # Health, Integrity & Privacy Diagnostics
 codegraph status .                                         # Show index freshness and graph counts
 codegraph doctor . --database --resources                  # Verify SQLite integrity, FKs, FTS, and memory
@@ -567,8 +590,10 @@ codegraph memory list -r .                                 # Inspect repository-
 codegraph benchmark -r .                                   # Run deterministic benchmark suite
 
 # MCP Server Subcommands
-codegraph mcp serve .                                      # Start stdio MCP server
+codegraph mcp serve .                                      # Start stdio MCP server (with parent/EOF lifecycle guard)
 codegraph mcp serve . --profile full                       # Start stdio MCP server with all 56 tools
+codegraph mcp stop                                         # Alias for codegraph stop
+codegraph mcp kill                                         # Alias for codegraph stop (1s graceful timeout)
 codegraph mcp doctor .                                     # End-to-end MCP startup & query check
 codegraph mcp config-check .                               # Read-only MCP config validation
 codegraph mcp capabilities                                 # Print machine-readable capability manifest

{codegraph_engine-2.1.7 → codegraph_engine-2.2.0}/README.md

@@ -2,23 +2,24 @@
   <img src="docs/assets/codegraph_logo.jpg" alt="CodeGraph MCP — Deep Deterministic Repository Intelligence for AI Coding Agents" width="500" />
 </p>
 
-<h1 align="center">CodeGraph Engine (v2.1.7)</h1>
+<h1 align="center">CodeGraph-MCP Engine (v2.2.0)</h1>
 
 <p align="center">
   <strong>Deep deterministic repository intelligence for AI coding agents.</strong>
 </p>
 
 <p align="center">
-  <a href="https://github.com/raghurammrsd/CODE_GRAPH_MCP"><img src="https://img.shields.io/badge/package-codegraph--engine%20v2.1.7-blue.svg" alt="Package: codegraph-engine v2.1.7" /></a>
+  <a href="https://pypi.org/project/codegraph-engine/2.2.0/"><img src="https://img.shields.io/badge/pypi-codegraph--engine%20v2.2.0-blue.svg" alt="PyPI: codegraph-engine v2.2.0" /></a>
   <a href="pyproject.toml"><img src="https://img.shields.io/badge/python-3.12%20%7C%203.13-3776AB.svg" alt="Python 3.12 | 3.13" /></a>
   <a href="src/codegraph/mcp/server.py"><img src="https://img.shields.io/badge/MCP-14%20default%20%7C%2056%20full%20tools-2ea043.svg" alt="MCP Tools: 14 default | 56 full" /></a>
-  <a href="tests/"><img src="https://img.shields.io/badge/pytest-842%20passed-brightgreen.svg" alt="Tests: 842 passed" /></a>
+  <a href="tests/"><img src="https://img.shields.io/badge/pytest-861%20passed-brightgreen.svg" alt="Tests: 861 passed" /></a>
   <a href="pyproject.toml"><img src="https://img.shields.io/badge/ruff-0%20errors-success.svg" alt="Ruff: 0 errors" /></a>
-  <a href="src/codegraph/"><img src="https://img.shields.io/badge/mypy-0%20issues%20(77%20files)-blue.svg" alt="Mypy: strict" /></a>
+  <a href="src/codegraph/"><img src="https://img.shields.io/badge/mypy-0%20issues%20(80%20files)-blue.svg" alt="Mypy: strict" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
 </p>
 
 <p align="center">
+  <a href="https://pypi.org/project/codegraph-engine/2.2.0/"><strong>PyPI (v2.2.0)</strong></a> •
   <a href="#2-quickstart-30-second-setup"><strong>Quickstart</strong></a> •
   <a href="#1-built-for-aiml-and-backend-heavy-repositories"><strong>Built For</strong></a> •
   <a href="#5-database-intelligence"><strong>Database Intelligence</strong></a> •
@@ -92,7 +93,7 @@ pip install "codegraph-engine[mcp]"
 
 ### Step 2: Configure Your AI Coding Agents (`codegraph install`)
 
-CodeGraph includes an interactive, idempotent onboarding installer ([`src/codegraph/installer.py`](src/codegraph/installer.py)) that detects installed AI coding agents (**Claude Code**, **Cursor**, **Antigravity**, **Codex CLI**, **Gemini CLI**, and **Cline**), configures `mcpServers.codegraph`, installs marker-bounded routing instructions (`<!-- CODEGRAPH:START -->` … `<!-- CODEGRAPH:END -->`), and verifies MCP server startup:
+CodeGraph-MCP includes an interactive, idempotent onboarding installer ([`src/codegraph/installer.py`](src/codegraph/installer.py)) that detects installed AI coding agents (**Claude Code**, **Cursor**, **Antigravity**, **Codex CLI**, **Gemini CLI**, and **Cline**), configures `mcpServers.codegraph`, installs marker-bounded routing instructions (`<!-- CODEGRAPH:START -->` … `<!-- CODEGRAPH:END -->`), and verifies MCP server startup:
 
 ```bash
 # Interactive setup (detects installed agents, previews planned changes, asks confirmation)
@@ -114,18 +115,31 @@ codegraph status
 codegraph doctor
 ```
 
-### Managing Installation & Project Index Lifecycle
+> **Dynamic Index Hot-Reloading:** If your AI coding agent launches `codegraph mcp serve` before you run `codegraph init`, you do **not** need to restart your IDE or MCP session. As soon as `codegraph init` or `codegraph index` creates or updates `.codegraph.sqlite3`, the running MCP server automatically detects the updated database on the next tool call and refreshes its in-memory graph cache (`get_repository_status(reload=True, reindex=True)` can also be invoked directly by the agent).
 
-CodeGraph cleanly separates agent configuration from project index files:
+### Managing Installation, Process & Project Index Lifecycle
+
+CodeGraph cleanly separates agent configuration, process lifecycle, and project index files:
 
 | Command | Scope | What It Does |
 | :--- | :--- | :--- |
-| `codegraph install` | Agent configuration | Configures MCP server + marker-managed rules/skills for selected AI agents. |
-| `codegraph init` | Project repository | Initializes `.codegraph.sqlite3` and indexes the current repository. |
+| `codegraph install` | Agent configuration | Configures MCP server + marker-managed rules/skills for selected AI agents (ASCII-safe on Windows `cp1252`). |
+| `codegraph init` | Project repository | Initializes `.codegraph.sqlite3` and indexes the current repository (hot-reloaded automatically by running MCP servers). |
 | `codegraph index` | Project repository | Incrementally indexes modified files (`--verbose`, `--quiet`, `--json`). |
-| `codegraph uninstall` | Agent configuration | Removes only CodeGraph-managed MCP entries and instruction blocks (preserves user config and project index). |
+| `codegraph stop` | Process lifecycle | Safely stops running CodeGraph-owned MCP background processes (`--all`, `--repo`, `--json`) and releases file locks. |
+| `codegraph doctor --processes` | Process lifecycle | Lists active CodeGraph MCP processes, parent PIDs, orphan status, and cleans stale PID files. |
+| `codegraph uninstall` | Agent configuration | Stops active workspace MCP processes and removes CodeGraph-managed MCP entries and instruction blocks. |
 | `codegraph uninit` | Project repository | Removes only `.codegraph.sqlite3` and `.codegraph/` in the project (never touches source code or Git history). |
 
+### Safe Upgrading on Windows (`WinError 32` Prevention)
+
+On Windows, running `pip install --upgrade codegraph-engine` while an IDE or agent still holds `codegraph.exe` open can trigger `WinError 32`. Before upgrading on Windows, run:
+
+```bash
+codegraph stop --all
+pip install --upgrade "codegraph-engine[mcp]"
+```
+
 ---
 
 ## 3. Core Workflow & Architecture
@@ -185,7 +199,7 @@ InferenceService.run_inference
                                    db:table:postgresql.public.prediction_logs
 ```
 
-**What CodeGraph structurally proves**:
+**What CodeGraph-MCP structurally proves**:
 - `find_routes(path="/v1/predict")` resolves composed router prefixes (`MOUNTS`) to `predict_endpoint`.
 - `trace_path(from_symbol="predict_endpoint", to_symbol="log_prediction")` proves the multi-hop execution chain across DI injection, preprocessing, model execution, and persistence.
 - `get_db_impact(symbol="InferenceService.run_inference")` identifies downstream writes to `prediction_logs`.
@@ -203,7 +217,7 @@ TrainingPipeline.run
       └──►CALLS (AST_VERIFIED) ──► Evaluator.compute_metrics
 ```
 
-**What CodeGraph structurally proves**:
+**What CodeGraph-MCP structurally proves**:
 - `find_callees(symbol="TrainingPipeline.run")` enumerates every stage of the pipeline with exact file and line ranges.
 - `find_tests(symbol="Evaluator.compute_metrics")` locates the unit and regression tests covering metric calculation.
 - When a transform or model class is dynamically instantiated from a YAML string (`getattr(models, cfg.arch)`), CodeGraph explicitly records `POSSIBLE_CALLS` (`POSSIBLE`) or `UNRESOLVED_REFERENCE` (`UNKNOWN`) rather than fabricating a false static call edge.
@@ -222,7 +236,7 @@ AgentRunner.execute_step
       └──►CALLS (AST_VERIFIED)           ──► ModelProviderClient.generate
 ```
 
-**What CodeGraph structurally proves**:
+**What CodeGraph-MCP structurally proves**:
 - Tracks decorator and call-based registrations (`@tool_registry.register("search_orders")`) via `REGISTERS` and `REGISTERED_HANDLER` edges.
 - Tracks environment variable dependencies (`os.getenv("OPENAI_API_KEY")`) as `READS_ENV` edges with the variable name only—never indexing or exposing secret values.
 
@@ -386,20 +400,23 @@ Rather than claiming a single universal token reduction percentage across all po
 | **Compression at `budget = 200 tokens`** | `85.6%` reduction | [`benchmarks/baselines/context_baseline.json`](benchmarks/baselines/context_baseline.json) |
 | **Compression at `budget = 600 tokens`** | `56.3%` reduction | [`benchmarks/baselines/context_baseline.json`](benchmarks/baselines/context_baseline.json) |
 | **Cold vs. Warm `get_context` Latency (`p50`)** | `20.0 ms` cold → `0.67 ms` warm (`30.0x`) | [`benchmarks/baselines/context_baseline.json`](benchmarks/baselines/context_baseline.json) |
+| **Single-Tool Query Latency (Indexed SQLite)** | `1 ms – 15 ms` | Local SQLite B-tree / FTS5 lookup |
 | **FACT / UNKNOWN / AMBIGUITY Correctness** | `100.0%` / `98.0%` / `100.0%` | [`benchmarks/baselines/v2_0_verified.json`](benchmarks/baselines/v2_0_verified.json) |
 
 ### Results from the 32-Task Internal Evaluation ([`src/codegraph/tool_selection_eval.py`](src/codegraph/tool_selection_eval.py))
 
-The table below reports results from the **32-task internal evaluation harness** (`run_tool_selection_ab_benchmark()`) comparing Mode A (unassisted exploration without CodeGraph routing rules) against Mode B (CodeGraph MCP + agent routing rules) on the same 32 tasks:
+The table below reports results from the **32-task internal evaluation harness** (`run_tool_selection_ab_benchmark()`) comparing Mode A (unassisted `grep` + full-file reading without CodeGraph routing rules) against Mode B (CodeGraph MCP + agent routing rules) on the same 32 tasks:
 
-| Metric (32-Task Internal Evaluation) | Mode A (Baseline) | Mode B (CodeGraph MCP) | Delta |
+| Metric (32-Task Internal Evaluation) | Mode A (Without CodeGraph) | Mode B (With CodeGraph MCP) | Measured Improvement |
 | :--- | ---: | ---: | :--- |
-| **Total Tool Calls** | `164` | `71` | `-93 calls (-56.7%)` |
-| **Direct Full-File Reads** | `161` | `7` | `-154 file reads (-95.7%)` |
-| **First-Tool Selection Accuracy** | `9.38%` | `100.0%` | `+90.62%` |
-| **Unsupported Claims** | `11 (34.38%)` | `0 (0.00%)` | `-11 claims` |
-| **Task Accuracy** | `59.84%` | `100.0%` | `+40.16%` |
-| **12-Prompt Natural-Language Routing Eval** | — | `12 / 12 (100.0%)` | `12/12 on this evaluation set` |
+| **Total Tool Calls (32 Tasks)** | `164 calls` (`~5.1 / task`) | `71 calls` (`~2.2 / task`) | **`-93 calls (-56.7% fewer tool calls)`** |
+| **Direct Full-File Reads** | `161 full-file reads` | `7 bounded slice reads` | **`-154 file reads (-95.7% fewer file reads)`** |
+| **Context Tokens per Task** | `3,000 – 12,000+ tokens` (full files) | `~542 tokens` avg (`get_context`) | **`65.0% – 85.6% token reduction`** |
+| **Query Latency (`p50`)** | Hundreds of ms (multi-step `grep` + reads) | `20.0 ms` cold / `0.67 ms` warm (`30.0x`) | **Sub-20ms indexed lookup** |
+| **First-Tool Selection Accuracy** | `9.38%` | `100.0%` | **`+90.62%`** |
+| **Unsupported Claims (Hallucinated Edges)** | `11 (34.38%)` | `0 (0.00%)` | **`-11 claims (0% unsupported)`** |
+| **Task Accuracy** | `59.84%` | `100.0%` | **`+40.16%`** |
+| **12-Prompt Natural-Language Routing Eval** | — | `12 / 12 (100.0%)` | **`12/12 on this evaluation set`** |
 
 ![CodeGraph — Measured Context & Exploration Efficiency](docs/assets/performance_comparison.svg)
 
@@ -507,6 +524,12 @@ codegraph index . --verbose                                # Incremental index w
 codegraph index . --json                                   # Output structured JSON phase telemetry
 codegraph uninit --dry-run                                 # Preview removal of .codegraph.sqlite3
 
+# Process Lifecycle & Upgrade Lock Safety
+codegraph stop                                             # Safely stop CodeGraph MCP server for current repo
+codegraph stop --all                                       # Stop all CodeGraph-owned MCP processes across repos
+codegraph stop --repo /path/to/repo --json                 # Stop MCP processes for a specific repo (JSON output)
+codegraph doctor --processes                               # Inspect active MCP processes, parent PIDs, & stale locks
+
 # Health, Integrity & Privacy Diagnostics
 codegraph status .                                         # Show index freshness and graph counts
 codegraph doctor . --database --resources                  # Verify SQLite integrity, FKs, FTS, and memory
@@ -534,8 +557,10 @@ codegraph memory list -r .                                 # Inspect repository-
 codegraph benchmark -r .                                   # Run deterministic benchmark suite
 
 # MCP Server Subcommands
-codegraph mcp serve .                                      # Start stdio MCP server
+codegraph mcp serve .                                      # Start stdio MCP server (with parent/EOF lifecycle guard)
 codegraph mcp serve . --profile full                       # Start stdio MCP server with all 56 tools
+codegraph mcp stop                                         # Alias for codegraph stop
+codegraph mcp kill                                         # Alias for codegraph stop (1s graceful timeout)
 codegraph mcp doctor .                                     # End-to-end MCP startup & query check
 codegraph mcp config-check .                               # Read-only MCP config validation
 codegraph mcp capabilities                                 # Print machine-readable capability manifest

{codegraph_engine-2.1.7 → codegraph_engine-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codegraph-engine"
-version = "2.1.7"
+version = "2.2.0"
 description = "Deep deterministic repository intelligence for AI coding agents (code, dependencies, databases, and runtime observations)"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -61,6 +61,7 @@ disable_error_code = ["untyped-decorator"]
 ignore_missing_imports = true
 
 [[tool.mypy.overrides]]
-module = ["psutil.*", "psutil"]
+module = ["psutil.*", "psutil", "yaml.*", "yaml"]
 ignore_missing_imports = true
+disable_error_code = ["import-untyped"]
 

{codegraph_engine-2.1.7 → codegraph_engine-2.2.0}/src/codegraph/__init__.py

@@ -1,6 +1,6 @@
 """CodeGraph MCP: local, evidence-backed codebase intelligence."""
 
-__version__ = "2.1.7"
+__version__ = "2.2.0"
 from codegraph.errors import (
     CodeGraphError,
     ErrorCode,