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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codegraph-engine
-Version: 2.1.7
+Version: 2.1.8
 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 Engine (v2.1.8)</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.1.8/"><img src="https://img.shields.io/badge/pypi-codegraph--engine%20v2.1.8-blue.svg" alt="PyPI: codegraph-engine v2.1.8" /></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-853%20passed-brightgreen.svg" alt="Tests: 853 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(79%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.1.8/"><strong>PyPI (v2.1.8)</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> •
@@ -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
@@ -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.1.8}/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 Engine (v2.1.8)</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.1.8/"><img src="https://img.shields.io/badge/pypi-codegraph--engine%20v2.1.8-blue.svg" alt="PyPI: codegraph-engine v2.1.8" /></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-853%20passed-brightgreen.svg" alt="Tests: 853 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(79%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.1.8/"><strong>PyPI (v2.1.8)</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> •
@@ -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
@@ -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.1.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codegraph-engine"
-version = "2.1.7"
+version = "2.1.8"
 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.1.8}/src/codegraph/__init__.py

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

{codegraph_engine-2.1.7 → codegraph_engine-2.1.8}/src/codegraph/cli.py

@@ -9,6 +9,7 @@ import typer
 
 from codegraph import __version__
 from codegraph.architecture import get_architecture
+from codegraph.cli_output import cli_echo
 from codegraph.config import Settings
 from codegraph.context import get_context
 from codegraph.errors import ErrorCode, SecurityError
@@ -605,8 +606,10 @@ def serve(
     """Run the stdio MCP server (requires the optional mcp extra)."""
     repo = _resolve_repo(path, repository)
     from codegraph.mcp import create_server
+    from codegraph.process_lifecycle import run_mcp_stdio_server
 
-    create_server(repo, profile=profile).run()
+    server = create_server(repo, profile=profile)
+    run_mcp_stdio_server(server, repo, profile=profile)
 
 
 mcp_app = typer.Typer(help="MCP server commands.")
@@ -622,8 +625,70 @@ def mcp_serve(
     """Run the stdio MCP server (requires the optional mcp extra)."""
     repo = _resolve_repo(path, repository)
     from codegraph.mcp import create_server
+    from codegraph.process_lifecycle import run_mcp_stdio_server
 
-    create_server(repo, profile=profile).run()
+    server = create_server(repo, profile=profile)
+    run_mcp_stdio_server(server, repo, profile=profile)
+
+
+def _execute_stop(
+    path: Path | None,
+    repository: Path | None,
+    all_processes: bool,
+    timeout: float,
+    json_output: bool,
+) -> None:
+    from codegraph.process_lifecycle import stop_codegraph_processes
+
+    target_repo: Path | None = None
+    if not all_processes:
+        target_repo = _resolve_repo(path, repository)
+
+    res = stop_codegraph_processes(
+        repository=target_repo,
+        stop_all=all_processes,
+        timeout_sec=timeout,
+    )
+    if json_output:
+        cli_echo(json.dumps(res.as_dict(), indent=2), json_mode=True)
+    else:
+        cli_echo(res.format_human())
+
+
+@app.command("stop")
+def stop_cmd(
+    path: Annotated[Path | None, typer.Argument(help="Repository path (default: current directory)")] = None,
+    repository: Annotated[Path | None, typer.Option("--repository", "-r", "--repo", help="Repository path")] = None,
+    all_processes: Annotated[bool, typer.Option("--all", "-a", help="Stop all CodeGraph-owned MCP processes across all repositories")] = False,
+    timeout: Annotated[float, typer.Option("--timeout", help="Graceful shutdown timeout in seconds before force-kill")] = 3.0,
+    json_output: Annotated[bool, typer.Option("--json", help="Output deterministic machine-readable JSON")] = False,
+) -> None:
+    """Safely stop running CodeGraph MCP background processes and release file locks."""
+    _execute_stop(path, repository, all_processes, timeout, json_output)
+
+
+@mcp_app.command("stop")
+def mcp_stop_cmd(
+    path: Annotated[Path | None, typer.Argument(help="Repository path (default: current directory)")] = None,
+    repository: Annotated[Path | None, typer.Option("--repository", "-r", "--repo", help="Repository path")] = None,
+    all_processes: Annotated[bool, typer.Option("--all", "-a", help="Stop all CodeGraph-owned MCP processes across all repositories")] = False,
+    timeout: Annotated[float, typer.Option("--timeout", help="Graceful shutdown timeout in seconds before force-kill")] = 3.0,
+    json_output: Annotated[bool, typer.Option("--json", help="Output deterministic machine-readable JSON")] = False,
+) -> None:
+    """Safely stop running CodeGraph MCP background processes and release file locks."""
+    _execute_stop(path, repository, all_processes, timeout, json_output)
+
+
+@mcp_app.command("kill")
+def mcp_kill_cmd(
+    path: Annotated[Path | None, typer.Argument(help="Repository path (default: current directory)")] = None,
+    repository: Annotated[Path | None, typer.Option("--repository", "-r", "--repo", help="Repository path")] = None,
+    all_processes: Annotated[bool, typer.Option("--all", "-a", help="Stop all CodeGraph-owned MCP processes across all repositories")] = False,
+    timeout: Annotated[float, typer.Option("--timeout", help="Graceful shutdown timeout in seconds before force-kill")] = 1.0,
+    json_output: Annotated[bool, typer.Option("--json", help="Output deterministic machine-readable JSON")] = False,
+) -> None:
+    """Alias for `codegraph stop` to terminate CodeGraph MCP processes and release locks."""
+    _execute_stop(path, repository, all_processes, timeout, json_output)
 
 
 @mcp_app.command("doctor")
@@ -636,9 +701,9 @@ def mcp_doctor(
 
     report = run_mcp_doctor(profile=profile)
     if json_output:
-        typer.echo(json.dumps(report.as_dict(), indent=2))
+        cli_echo(json.dumps(report.as_dict(), indent=2), json_mode=True)
     else:
-        typer.echo(report.format_human())
+        cli_echo(report.format_human())
     if not report.healthy:
         raise typer.Exit(code=1)
 
@@ -656,9 +721,9 @@ def mcp_config_check(
     ws = (path or Path.cwd()).resolve()
     rep = check_mcp_configuration(workspace_dir=ws, config_file=config_file, include_example=include_example)
     if json_output:
-        typer.echo(json.dumps(rep.as_dict(), indent=2))
+        cli_echo(json.dumps(rep.as_dict(), indent=2), json_mode=True)
     else:
-        typer.echo(f"{rep.status.value}: {rep.message}")
+        cli_echo(f"{rep.status.value}: {rep.message}")
 
 
 @mcp_app.command("capabilities")
@@ -666,7 +731,7 @@ def mcp_capabilities() -> None:
     """Output the deterministic machine-readable CodeGraph capability manifest."""
     from codegraph.agent_capabilities import get_capability_manifest
 
-    typer.echo(json.dumps(get_capability_manifest(), indent=2))
+    cli_echo(json.dumps(get_capability_manifest(), indent=2), json_mode=True)
 
 
 @mcp_app.command("rules")
@@ -676,7 +741,7 @@ def mcp_rules(
     """Render deterministic CodeGraph agent rules for the specified agent."""
     from codegraph.agent_rules import render_agent_rules
 
-    typer.echo(render_agent_rules(agent=agent), nl=False)
+    cli_echo(render_agent_rules(agent=agent), nl=False)
 
 
 @app.command()
@@ -685,9 +750,20 @@ def doctor(
     repository: Annotated[Path | None, typer.Option("--repository", "-r", "--repo", help="Repository path")] = None,
     resources: Annotated[bool, typer.Option("--resources")] = False,
     database: Annotated[bool, typer.Option("--database", help="Run comprehensive database integrity and schema checks")] = False,
+    processes: Annotated[bool, typer.Option("--processes", help="Inspect active CodeGraph processes, parent state, and stale PID files")] = False,
     json_output: Annotated[bool, typer.Option("--json")] = False,
 ) -> None:
-    """Check repository and index readiness, database integrity, and freshness."""
+    """Check repository and index readiness, database integrity, process lifecycle, and freshness."""
+    if processes:
+        from codegraph.process_lifecycle import discover_codegraph_processes
+
+        discovery = discover_codegraph_processes(clean_stale=True)
+        if json_output:
+            cli_echo(json.dumps(discovery.as_dict(), indent=2), json_mode=True)
+        else:
+            cli_echo(discovery.format_human())
+        return
+
     repo = _resolve_repo(path, repository)
     indexer_inst = _indexer(repo)
     db = repo / ".codegraph.sqlite3"
@@ -1007,7 +1083,7 @@ def install(
 
             rules_txt = render_agent_rules(canon)
             if json_output:
-                typer.echo(
+                cli_echo(
                     json.dumps(
                         {
                             "status": "ok",
@@ -1016,21 +1092,22 @@ def install(
                             "instructions_block": format_marker_block(rules_txt),
                         },
                         indent=2,
-                    )
+                    ),
+                    json_mode=True,
                 )
             else:
-                typer.echo(f"# MCP Configuration ({canon})\n")
-                typer.echo(json.dumps(snippet, indent=2))
-                typer.echo(f"\n# Instructions Block ({canon})\n")
-                typer.echo(format_marker_block(rules_txt), nl=False)
+                cli_echo(f"# MCP Configuration ({canon})\n")
+                cli_echo(json.dumps(snippet, indent=2), json_mode=True)
+                cli_echo(f"\n# Instructions Block ({canon})\n")
+                cli_echo(format_marker_block(rules_txt), nl=False)
             return
         except CodeGraphError as exc:
             if json_output:
-                typer.echo(json.dumps(exc.to_response(), indent=2))
+                cli_echo(json.dumps(exc.to_response(), indent=2), json_mode=True)
             else:
-                typer.echo(f"Error [{exc.code}]: {exc.message}")
+                cli_echo(f"Error [{exc.code}]: {exc.message}")
                 if exc.next_action and exc.next_action.get("command"):
-                    typer.echo(f"\nTry:\n  {exc.next_action['command']}")
+                    cli_echo(f"\nTry:\n  {exc.next_action['command']}")
             raise typer.Exit(code=1) from exc
 
     ws = _resolve_repo(path, repository)
@@ -1040,15 +1117,15 @@ def install(
 
         assert isinstance(preview_rep, InstallerReport)
         if not json_output:
-            typer.echo(preview_rep.format_preview_human())
-            typer.echo("")
-            typer.echo("Continue? [y/N] ", nl=False)
+            cli_echo(preview_rep.format_preview_human())
+            cli_echo("")
+            cli_echo("Continue? [y/N] ", nl=False)
         try:
             ans = input().strip().lower()
         except EOFError:
             ans = ""
         if not json_output:
-            typer.echo("")
+            cli_echo("")
         return ans in ("y", "yes")
 
     try:
@@ -1062,22 +1139,22 @@ def install(
         )
     except CodeGraphError as exc:
         if json_output:
-            typer.echo(json.dumps(exc.to_response(), indent=2))
+            cli_echo(json.dumps(exc.to_response(), indent=2), json_mode=True)
         else:
-            typer.echo(f"Error [{exc.code}]: {exc.message}")
+            cli_echo(f"Error [{exc.code}]: {exc.message}")
             if exc.next_action and exc.next_action.get("reason"):
-                typer.echo(f"\nExpected:\n  {exc.next_action['reason']}")
+                cli_echo(f"\nExpected:\n  {exc.next_action['reason']}")
             if exc.next_action and exc.next_action.get("command"):
-                typer.echo(f"\nTry:\n  {exc.next_action['command']}")
+                cli_echo(f"\nTry:\n  {exc.next_action['command']}")
         raise typer.Exit(code=1) from exc
 
     if json_output:
-        typer.echo(json.dumps(report.as_dict(), indent=2))
+        cli_echo(json.dumps(report.as_dict(), indent=2), json_mode=True)
     else:
         if yes and not dry_run:
-            typer.echo(report.format_preview_human())
-            typer.echo("")
-        typer.echo(report.format_human())
+            cli_echo(report.format_preview_human())
+            cli_echo("")
+        cli_echo(report.format_human())
 
     if report.status == "error":
         raise typer.Exit(code=1)
@@ -1107,17 +1184,17 @@ def uninstall(
 
     def _confirm_uninstall(preview_rep: InstallerReport) -> bool:
         if not json_output:
-            typer.echo("CodeGraph Uninstaller\n")
+            cli_echo("CodeGraph Uninstaller\n")
             for c in preview_rep.changes:
                 if c.action in ("remove", "modify"):
-                    typer.echo(f"  - {c.display_path} ({c.action})")
-            typer.echo("\nContinue? [y/N] ", nl=False)
+                    cli_echo(f"  - {c.display_path} ({c.action})")
+            cli_echo("\nContinue? [y/N] ", nl=False)
         try:
             ans = input().strip().lower()
         except EOFError:
             ans = ""
         if not json_output:
-            typer.echo("")
+            cli_echo("")
         return ans in ("y", "yes")
 
     try:
@@ -1130,17 +1207,17 @@ def uninstall(
         )
     except CodeGraphError as exc:
         if json_output:
-            typer.echo(json.dumps(exc.to_response(), indent=2))
+            cli_echo(json.dumps(exc.to_response(), indent=2), json_mode=True)
         else:
-            typer.echo(f"Error [{exc.code}]: {exc.message}")
+            cli_echo(f"Error [{exc.code}]: {exc.message}")
             if exc.next_action and exc.next_action.get("command"):
-                typer.echo(f"\nTry:\n  {exc.next_action['command']}")
+                cli_echo(f"\nTry:\n  {exc.next_action['command']}")
         raise typer.Exit(code=1) from exc
 
     if json_output:
-        typer.echo(json.dumps(report.as_dict(), indent=2))
+        cli_echo(json.dumps(report.as_dict(), indent=2), json_mode=True)
     else:
-        typer.echo(report.format_human())
+        cli_echo(report.format_human())
 
 
 @app.command()
@@ -1159,16 +1236,16 @@ def uninit(
 
     def _confirm_uninit(preview_rep: InstallerReport) -> bool:
         if not json_output:
-            typer.echo("Remove CodeGraph project index files?\n")
+            cli_echo("Remove CodeGraph project index files?\n")
             for c in preview_rep.changes:
-                typer.echo(f"  - {c.display_path}")
-            typer.echo("\nContinue? [y/N] ", nl=False)
+                cli_echo(f"  - {c.display_path}")
+            cli_echo("\nContinue? [y/N] ", nl=False)
         try:
             ans = input().strip().lower()
         except EOFError:
             ans = ""
         if not json_output:
-            typer.echo("")
+            cli_echo("")
         return ans in ("y", "yes")
 
     try:
@@ -1179,15 +1256,15 @@ def uninit(
         )
     except CodeGraphError as exc:
         if json_output:
-            typer.echo(json.dumps(exc.to_response(), indent=2))
+            cli_echo(json.dumps(exc.to_response(), indent=2), json_mode=True)
         else:
-            typer.echo(f"Error [{exc.code}]: {exc.message}")
+            cli_echo(f"Error [{exc.code}]: {exc.message}")
         raise typer.Exit(code=1) from exc
 
     if json_output:
-        typer.echo(json.dumps(report.as_dict(), indent=2))
+        cli_echo(json.dumps(report.as_dict(), indent=2), json_mode=True)
     else:
-        typer.echo(report.format_human())
+        cli_echo(report.format_human())
 
 
 if __name__ == "__main__":