codecortex 0.15.3__tar.gz → 0.15.5__tar.gz

{codecortex-0.15.3/src/codecortex.egg-info → codecortex-0.15.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.15.3
+Version: 0.15.5
 Summary: Local-first, MCP-native code-intelligence server — graph, LSP, and semantic search behind one safe code.query tool for coding agents.
 Author: Shammai Hamilton
 License-Expression: MIT
@@ -95,23 +95,29 @@ It's one call: `code.query(op, target, engine="auto")`. In `auto` mode (the defa
 | Everything about one symbol | `context` | graph + lsp | both views merged |
 | **Impact of your uncommitted edits** | `changed` | graph | changed files → impacted symbols |
 | Refactor-risk hotspots | `hotspots` | graph | highest complexity / fan-in symbols |
-| Unreferenced (dead) code | `deadcode` | graph | non-test symbols with no callers, **verified against the source** — [treat as candidates, not instructions](#deadcode-is-a-candidate-list-not-a-delete-list) |
+| Unreferenced (dead) code | `deadcode` | graph | **withdrawn** — measured wrong in both directions on real repos; safe-nulls with `reason: "op-withdrawn"` unless you opt in — [why, and what to use instead](#deadcode-is-withdrawn) |
 
 Pin one engine with `--engine graph│lsp│semantic`, or fan out with `--engine both` / `all` to merge results.
 
-#### `deadcode` is a candidate list, not a delete list
+#### `deadcode` is withdrawn
 
-`deadcode` is the one op whose output invites a destructive action, so it gets an explicit caveat.
-Every hit is re-read and verified against the source before it is reported, which removes the
-common false positives — but **no reachability analysis sees every caller.** Dynamic dispatch,
-registries and decorators, `getattr` lookups, entry points declared in packaging metadata, plugin
-discovery, reflection, and calls from languages the graph does not parse are all invisible to it.
-Through `0.14.x` it was systematically wrong on callback-heavy code and confident about it; that
-class of defect is fixed, but the underlying limit is structural and permanent.
+`deadcode` is withdrawn: it returns a safe-null (`reason: "op-withdrawn"`) instead of running. It
+was measured wrong in **both** directions on real repositories — on one it named five candidates of
+which four were live code (a rollup plugin hook; two entries of a `Record<string, fn>` reached by a
+runtime string; a `predicate` passed inline to the call that consumes it), and on another it
+reported "(none found)" for a 4,883-function codebase that had at least three genuinely unreferenced
+private helpers. It is the one op whose output is an instruction to delete code, so it needs the
+highest evidence bar of any op here, and currently has the least. It returns when a labelled corpus
+measures its precision and recall — not before.
 
-**So: review each hit before deleting anything, and never wire `deadcode` into an agent that
-deletes without a human in the loop.** Used as a ranked list of *places worth looking*, it is
-genuinely useful. Used as a work order, it will eventually remove live code.
+**Use `callers` on a specific symbol instead.** "Does anything call this?" is exactly the question
+`deadcode` was trying to answer in bulk, and `callers` answers it accurately, one symbol at a time.
+
+**Escape hatch, if you understand the risk.** Set `CODEINTEL_ENABLE_UNVERIFIED_OPS=1` to run it
+anyway. It still re-reads the source before reporting a hit, which removes the *common* false
+positives — but that verification is exactly what was measured wrong on the repositories above, so
+**review every hit before deleting anything, and never wire it into an agent that deletes without a
+human in the loop.**
 
 **Example — "who uses `safe_null_result`?"**
 
@@ -511,26 +517,33 @@ back to grep rather than crashing.
 
 | Area | Why |
 |---|---|
-| `deadcode` | It suggests deletions and cannot see every caller — [read the caveat](#deadcode-is-a-candidate-list-not-a-delete-list). |
+| `deadcode` | Withdrawn by default (`reason: "op-withdrawn"`) — measured wrong in both directions on real repos. Use `callers` on a specific symbol instead — [details](#deadcode-is-withdrawn). |
 | Non-loopback serving | `serve-http` is stdlib `http.server`. It binds loopback by default for a reason; front it with a reverse proxy and see [docs/deploy.md](docs/deploy.md). |
 | RBAC between **untrusting** tenants | It separates privilege levels among callers you already trust. It is not a wall against an adversary with write access to their own root — see the warning in [docs/deploy.md](docs/deploy.md). |
 | Unattended automation | Anything that acts on a result without a human reading it deserves a pilot first. |
 
 **On the test numbers.** The suite is large and the coverage floor is enforced, but read the figure
-with its caveat: the graph and LSP backends are external binaries that are **not installed in CI**,
-so those two engines are exercised against hand-authored mocks rather than the real wire contract,
-and the release canary — which does assert on real answer text against a built wheel — currently
-covers the semantic engine only. Line coverage measures how much of the intended behavior runs, not
-how much of reality it has met.
+with its caveat. In the **main test job** the graph and LSP backends are absent, so their live tests
+skip and those engines run against hand-authored mocks rather than the real wire contract. Separate
+jobs cover the contract itself: `graph-contract` installs the pinned `codebase-memory-mcp` and runs
+the live graph tests — and **fails if they skipped**, because a silently-skipped contract test is
+how a total backend outage stayed green here once — while the nightly corpus job runs that same
+real backend against pinned third-party repositories. `lsp-contract` runs the live serena tests but
+is **`continue-on-error`**: serena is fetched from an upstream git HEAD this project does not
+control, so a breakage there must be visible without blocking an unrelated release. Read that as
+the LSP wire contract being *watched* rather than *gated*. The release canary — the only check that
+asserts on real answer text from a built wheel — still covers **the semantic engine only**.
+
+Line coverage measures how much of the intended behavior runs, not how much of reality it has met.
 
 **The honest one-paragraph version.** codeintel has been run on very few repositories its author did
 not write, and that is where its bugs have come from — every fix in `0.15.x` came from pointing it
 at an unfamiliar codebase. Its characteristic failure mode is **answering confidently from the
 wrong index rather than failing loudly**, which the never-raise contract makes harder to notice: a
 wrong answer and a right one are the same shape. Run `codeintel doctor` before trusting a repo-wide
-answer, treat `deadcode` as candidates for review, and if something looks off please
-[report it](#reporting-a-problem) — an issue from someone who is not the author is the single most
-useful thing this project can receive right now.
+answer — and `deadcode` in particular is withdrawn rather than merely caveated (see above) — and if
+something looks off please [report it](#reporting-a-problem) — an issue from someone who is not the
+author is the single most useful thing this project can receive right now.
 
 **Engine coverage depends on external binaries.** Semantic search works out of the box. The graph
 engine needs `codebase-memory-mcp` and the LSP engine needs `uvx` on `PATH` — without them those

{codecortex-0.15.3 → codecortex-0.15.5}/README.md

@@ -58,23 +58,29 @@ It's one call: `code.query(op, target, engine="auto")`. In `auto` mode (the defa
 | Everything about one symbol | `context` | graph + lsp | both views merged |
 | **Impact of your uncommitted edits** | `changed` | graph | changed files → impacted symbols |
 | Refactor-risk hotspots | `hotspots` | graph | highest complexity / fan-in symbols |
-| Unreferenced (dead) code | `deadcode` | graph | non-test symbols with no callers, **verified against the source** — [treat as candidates, not instructions](#deadcode-is-a-candidate-list-not-a-delete-list) |
+| Unreferenced (dead) code | `deadcode` | graph | **withdrawn** — measured wrong in both directions on real repos; safe-nulls with `reason: "op-withdrawn"` unless you opt in — [why, and what to use instead](#deadcode-is-withdrawn) |
 
 Pin one engine with `--engine graph│lsp│semantic`, or fan out with `--engine both` / `all` to merge results.
 
-#### `deadcode` is a candidate list, not a delete list
+#### `deadcode` is withdrawn
 
-`deadcode` is the one op whose output invites a destructive action, so it gets an explicit caveat.
-Every hit is re-read and verified against the source before it is reported, which removes the
-common false positives — but **no reachability analysis sees every caller.** Dynamic dispatch,
-registries and decorators, `getattr` lookups, entry points declared in packaging metadata, plugin
-discovery, reflection, and calls from languages the graph does not parse are all invisible to it.
-Through `0.14.x` it was systematically wrong on callback-heavy code and confident about it; that
-class of defect is fixed, but the underlying limit is structural and permanent.
+`deadcode` is withdrawn: it returns a safe-null (`reason: "op-withdrawn"`) instead of running. It
+was measured wrong in **both** directions on real repositories — on one it named five candidates of
+which four were live code (a rollup plugin hook; two entries of a `Record<string, fn>` reached by a
+runtime string; a `predicate` passed inline to the call that consumes it), and on another it
+reported "(none found)" for a 4,883-function codebase that had at least three genuinely unreferenced
+private helpers. It is the one op whose output is an instruction to delete code, so it needs the
+highest evidence bar of any op here, and currently has the least. It returns when a labelled corpus
+measures its precision and recall — not before.
 
-**So: review each hit before deleting anything, and never wire `deadcode` into an agent that
-deletes without a human in the loop.** Used as a ranked list of *places worth looking*, it is
-genuinely useful. Used as a work order, it will eventually remove live code.
+**Use `callers` on a specific symbol instead.** "Does anything call this?" is exactly the question
+`deadcode` was trying to answer in bulk, and `callers` answers it accurately, one symbol at a time.
+
+**Escape hatch, if you understand the risk.** Set `CODEINTEL_ENABLE_UNVERIFIED_OPS=1` to run it
+anyway. It still re-reads the source before reporting a hit, which removes the *common* false
+positives — but that verification is exactly what was measured wrong on the repositories above, so
+**review every hit before deleting anything, and never wire it into an agent that deletes without a
+human in the loop.**
 
 **Example — "who uses `safe_null_result`?"**
 
@@ -474,26 +480,33 @@ back to grep rather than crashing.
 
 | Area | Why |
 |---|---|
-| `deadcode` | It suggests deletions and cannot see every caller — [read the caveat](#deadcode-is-a-candidate-list-not-a-delete-list). |
+| `deadcode` | Withdrawn by default (`reason: "op-withdrawn"`) — measured wrong in both directions on real repos. Use `callers` on a specific symbol instead — [details](#deadcode-is-withdrawn). |
 | Non-loopback serving | `serve-http` is stdlib `http.server`. It binds loopback by default for a reason; front it with a reverse proxy and see [docs/deploy.md](docs/deploy.md). |
 | RBAC between **untrusting** tenants | It separates privilege levels among callers you already trust. It is not a wall against an adversary with write access to their own root — see the warning in [docs/deploy.md](docs/deploy.md). |
 | Unattended automation | Anything that acts on a result without a human reading it deserves a pilot first. |
 
 **On the test numbers.** The suite is large and the coverage floor is enforced, but read the figure
-with its caveat: the graph and LSP backends are external binaries that are **not installed in CI**,
-so those two engines are exercised against hand-authored mocks rather than the real wire contract,
-and the release canary — which does assert on real answer text against a built wheel — currently
-covers the semantic engine only. Line coverage measures how much of the intended behavior runs, not
-how much of reality it has met.
+with its caveat. In the **main test job** the graph and LSP backends are absent, so their live tests
+skip and those engines run against hand-authored mocks rather than the real wire contract. Separate
+jobs cover the contract itself: `graph-contract` installs the pinned `codebase-memory-mcp` and runs
+the live graph tests — and **fails if they skipped**, because a silently-skipped contract test is
+how a total backend outage stayed green here once — while the nightly corpus job runs that same
+real backend against pinned third-party repositories. `lsp-contract` runs the live serena tests but
+is **`continue-on-error`**: serena is fetched from an upstream git HEAD this project does not
+control, so a breakage there must be visible without blocking an unrelated release. Read that as
+the LSP wire contract being *watched* rather than *gated*. The release canary — the only check that
+asserts on real answer text from a built wheel — still covers **the semantic engine only**.
+
+Line coverage measures how much of the intended behavior runs, not how much of reality it has met.
 
 **The honest one-paragraph version.** codeintel has been run on very few repositories its author did
 not write, and that is where its bugs have come from — every fix in `0.15.x` came from pointing it
 at an unfamiliar codebase. Its characteristic failure mode is **answering confidently from the
 wrong index rather than failing loudly**, which the never-raise contract makes harder to notice: a
 wrong answer and a right one are the same shape. Run `codeintel doctor` before trusting a repo-wide
-answer, treat `deadcode` as candidates for review, and if something looks off please
-[report it](#reporting-a-problem) — an issue from someone who is not the author is the single most
-useful thing this project can receive right now.
+answer — and `deadcode` in particular is withdrawn rather than merely caveated (see above) — and if
+something looks off please [report it](#reporting-a-problem) — an issue from someone who is not the
+author is the single most useful thing this project can receive right now.
 
 **Engine coverage depends on external binaries.** Semantic search works out of the box. The graph
 engine needs `codebase-memory-mcp` and the LSP engine needs `uvx` on `PATH` — without them those

{codecortex-0.15.3 → codecortex-0.15.5/src/codecortex.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.15.3
+Version: 0.15.5
 Summary: Local-first, MCP-native code-intelligence server — graph, LSP, and semantic search behind one safe code.query tool for coding agents.
 Author: Shammai Hamilton
 License-Expression: MIT
@@ -95,23 +95,29 @@ It's one call: `code.query(op, target, engine="auto")`. In `auto` mode (the defa
 | Everything about one symbol | `context` | graph + lsp | both views merged |
 | **Impact of your uncommitted edits** | `changed` | graph | changed files → impacted symbols |
 | Refactor-risk hotspots | `hotspots` | graph | highest complexity / fan-in symbols |
-| Unreferenced (dead) code | `deadcode` | graph | non-test symbols with no callers, **verified against the source** — [treat as candidates, not instructions](#deadcode-is-a-candidate-list-not-a-delete-list) |
+| Unreferenced (dead) code | `deadcode` | graph | **withdrawn** — measured wrong in both directions on real repos; safe-nulls with `reason: "op-withdrawn"` unless you opt in — [why, and what to use instead](#deadcode-is-withdrawn) |
 
 Pin one engine with `--engine graph│lsp│semantic`, or fan out with `--engine both` / `all` to merge results.
 
-#### `deadcode` is a candidate list, not a delete list
+#### `deadcode` is withdrawn
 
-`deadcode` is the one op whose output invites a destructive action, so it gets an explicit caveat.
-Every hit is re-read and verified against the source before it is reported, which removes the
-common false positives — but **no reachability analysis sees every caller.** Dynamic dispatch,
-registries and decorators, `getattr` lookups, entry points declared in packaging metadata, plugin
-discovery, reflection, and calls from languages the graph does not parse are all invisible to it.
-Through `0.14.x` it was systematically wrong on callback-heavy code and confident about it; that
-class of defect is fixed, but the underlying limit is structural and permanent.
+`deadcode` is withdrawn: it returns a safe-null (`reason: "op-withdrawn"`) instead of running. It
+was measured wrong in **both** directions on real repositories — on one it named five candidates of
+which four were live code (a rollup plugin hook; two entries of a `Record<string, fn>` reached by a
+runtime string; a `predicate` passed inline to the call that consumes it), and on another it
+reported "(none found)" for a 4,883-function codebase that had at least three genuinely unreferenced
+private helpers. It is the one op whose output is an instruction to delete code, so it needs the
+highest evidence bar of any op here, and currently has the least. It returns when a labelled corpus
+measures its precision and recall — not before.
 
-**So: review each hit before deleting anything, and never wire `deadcode` into an agent that
-deletes without a human in the loop.** Used as a ranked list of *places worth looking*, it is
-genuinely useful. Used as a work order, it will eventually remove live code.
+**Use `callers` on a specific symbol instead.** "Does anything call this?" is exactly the question
+`deadcode` was trying to answer in bulk, and `callers` answers it accurately, one symbol at a time.
+
+**Escape hatch, if you understand the risk.** Set `CODEINTEL_ENABLE_UNVERIFIED_OPS=1` to run it
+anyway. It still re-reads the source before reporting a hit, which removes the *common* false
+positives — but that verification is exactly what was measured wrong on the repositories above, so
+**review every hit before deleting anything, and never wire it into an agent that deletes without a
+human in the loop.**
 
 **Example — "who uses `safe_null_result`?"**
 
@@ -511,26 +517,33 @@ back to grep rather than crashing.
 
 | Area | Why |
 |---|---|
-| `deadcode` | It suggests deletions and cannot see every caller — [read the caveat](#deadcode-is-a-candidate-list-not-a-delete-list). |
+| `deadcode` | Withdrawn by default (`reason: "op-withdrawn"`) — measured wrong in both directions on real repos. Use `callers` on a specific symbol instead — [details](#deadcode-is-withdrawn). |
 | Non-loopback serving | `serve-http` is stdlib `http.server`. It binds loopback by default for a reason; front it with a reverse proxy and see [docs/deploy.md](docs/deploy.md). |
 | RBAC between **untrusting** tenants | It separates privilege levels among callers you already trust. It is not a wall against an adversary with write access to their own root — see the warning in [docs/deploy.md](docs/deploy.md). |
 | Unattended automation | Anything that acts on a result without a human reading it deserves a pilot first. |
 
 **On the test numbers.** The suite is large and the coverage floor is enforced, but read the figure
-with its caveat: the graph and LSP backends are external binaries that are **not installed in CI**,
-so those two engines are exercised against hand-authored mocks rather than the real wire contract,
-and the release canary — which does assert on real answer text against a built wheel — currently
-covers the semantic engine only. Line coverage measures how much of the intended behavior runs, not
-how much of reality it has met.
+with its caveat. In the **main test job** the graph and LSP backends are absent, so their live tests
+skip and those engines run against hand-authored mocks rather than the real wire contract. Separate
+jobs cover the contract itself: `graph-contract` installs the pinned `codebase-memory-mcp` and runs
+the live graph tests — and **fails if they skipped**, because a silently-skipped contract test is
+how a total backend outage stayed green here once — while the nightly corpus job runs that same
+real backend against pinned third-party repositories. `lsp-contract` runs the live serena tests but
+is **`continue-on-error`**: serena is fetched from an upstream git HEAD this project does not
+control, so a breakage there must be visible without blocking an unrelated release. Read that as
+the LSP wire contract being *watched* rather than *gated*. The release canary — the only check that
+asserts on real answer text from a built wheel — still covers **the semantic engine only**.
+
+Line coverage measures how much of the intended behavior runs, not how much of reality it has met.
 
 **The honest one-paragraph version.** codeintel has been run on very few repositories its author did
 not write, and that is where its bugs have come from — every fix in `0.15.x` came from pointing it
 at an unfamiliar codebase. Its characteristic failure mode is **answering confidently from the
 wrong index rather than failing loudly**, which the never-raise contract makes harder to notice: a
 wrong answer and a right one are the same shape. Run `codeintel doctor` before trusting a repo-wide
-answer, treat `deadcode` as candidates for review, and if something looks off please
-[report it](#reporting-a-problem) — an issue from someone who is not the author is the single most
-useful thing this project can receive right now.
+answer — and `deadcode` in particular is withdrawn rather than merely caveated (see above) — and if
+something looks off please [report it](#reporting-a-problem) — an issue from someone who is not the
+author is the single most useful thing this project can receive right now.
 
 **Engine coverage depends on external binaries.** Semantic search works out of the box. The graph
 engine needs `codebase-memory-mcp` and the LSP engine needs `uvx` on `PATH` — without them those

{codecortex-0.15.3 → codecortex-0.15.5}/src/codecortex.egg-info/SOURCES.txt

@@ -20,13 +20,16 @@ src/codeintel/http_server.py
 src/codeintel/indexer.py
 src/codeintel/injector.py
 src/codeintel/installer.py
+src/codeintel/loc.py
 src/codeintel/logconfig.py
 src/codeintel/mapper.py
 src/codeintel/metrics.py
 src/codeintel/onboarding.py
+src/codeintel/outcome.py
 src/codeintel/policy.py
 src/codeintel/provider.py
 src/codeintel/py.typed
+src/codeintel/redact.py
 src/codeintel/reindexer.py
 src/codeintel/reset.py
 src/codeintel/searcher.py
@@ -60,13 +63,17 @@ tests/test_cache.py
 tests/test_chunking.py
 tests/test_cli_commands.py
 tests/test_cli_help.py
+tests/test_cold_process.py
 tests/test_config.py
 tests/test_corpus.py
+tests/test_docs_ci_claims.py
+tests/test_docs_deadcode_withdrawal.py
 tests/test_doctor.py
 tests/test_e2e.py
 tests/test_engine_adoption.py
 tests/test_enterprise.py
 tests/test_gateway.py
+tests/test_graph_failure_population.py
 tests/test_graph_provider.py
 tests/test_graph_real.py
 tests/test_graph_stdin.py
@@ -74,8 +81,10 @@ tests/test_grapher.py
 tests/test_hardening.py
 tests/test_http_auth.py
 tests/test_http_server.py
+tests/test_incompleteness.py
 tests/test_installer.py
 tests/test_integration.py
+tests/test_loc_census.py
 tests/test_lsp_provider.py
 tests/test_lsp_real.py
 tests/test_mapper.py
@@ -93,4 +102,5 @@ tests/test_source_kind.py
 tests/test_term.py
 tests/test_treesitter.py
 tests/test_verify.py
-tests/test_verify_call.py
+tests/test_verify_call.py
+tests/test_version_skew.py

codecortex-0.15.5/src/codeintel/__init__.py

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

{codecortex-0.15.3 → codecortex-0.15.5}/src/codeintel/commands/query.py

@@ -1,6 +1,7 @@
 """`codeintel query` — one question against the gateway: search, callers, callees, impact, chain."""
 
 import json
+import os
 import sys
 import time
 from typing import Any
@@ -12,6 +13,36 @@ from codeintel.provider import Result, safe_null_result
 # and reporting whatever the gateway last said.
 _WARMING_TIMEOUT_S = 45.0
 
+# Per-query time budget, in milliseconds, handed to whichever engine answers.
+#
+# This used to be omitted entirely, so every engine fell back to its own default — 5s for the LSP
+# provider — against a cold first `symbol` query measured at 11.65s on a real 841-file TypeScript
+# repo. The call timed out, the reference lookup came back empty, and the empty list was rendered
+# as "(none)": a confident false answer produced by a missing argument. A CLI invocation is a
+# human or an agent waiting on one question; it can afford to wait properly.
+_CLI_BUDGET_MS = 30_000
+
+
+def _budget_ms() -> int:
+    """The per-query budget, overridable via ``CODEINTEL_BUDGET_MS``.
+
+    Two reasons this is an env var rather than a constant. Operators on slow machines or huge
+    repositories need to raise it. And tests need to LOWER it: the cold-process tier exists to catch
+    the defect where a timed-out backend call is rendered as a confident "(none)", but on a fast
+    machine the cold call simply succeeds, so the tier passed with that exact regression planted
+    back in. A budget it can drive to near-zero lets it reproduce the starvation condition
+    deterministically instead of waiting for a slow day.
+    """
+    raw = os.environ.get("CODEINTEL_BUDGET_MS", "").strip()
+    if raw:
+        try:
+            n = int(raw)
+            if n > 0:
+                return n
+        except ValueError:
+            pass
+    return _CLI_BUDGET_MS
+
 
 def run(args: Any) -> int:
     """`--json` promises parseable stdout, so its failures must be JSON too.
@@ -55,7 +86,9 @@ def _query(args: Any) -> Result:
 
     project_root = resolve_root(args)
     engine = args.engine if args.engine != "auto" else None
-    gw = server._build_gateway()
+    # oneshot: this process exits when the query returns, so it must not start a background
+    # reindex it cannot finish (and must not then report that reindex as staleness).
+    gw = server._build_gateway(oneshot=True)
 
     def _run_query() -> Result:
         return gw.query(
@@ -63,6 +96,7 @@ def _query(args: Any) -> Result:
             target=args.target,
             engine=engine,
             role="",
+            budget=_budget_ms(),
             project_root=project_root,
         )
 

{codecortex-0.15.3 → codecortex-0.15.5}/src/codeintel/commands/status.py

@@ -32,6 +32,16 @@ def run(args: Any) -> int:
     if status.get("healthy") is False:
         print("\n  run `codeintel doctor` for the fix for each gap")
 
+    # Printed before anything else the user might act on. A skew means every line above describes
+    # the code this process loaded, not the code installed — so a fix the user can read in the
+    # CHANGELOG can be absent from every answer while the engines all report green.
+    skew = status.get("version_skew")
+    if isinstance(skew, dict) and skew.get("running") and skew.get("installed"):
+        print(
+            f"\n  ! serving {skew['running']}, but {skew['installed']} is installed"
+            "\n    restart the codeintel server (or the agent hosting it) to pick it up"
+        )
+
     from codeintel.config import load_config
     from codeintel.semantic_db import default_db_path
 

{codecortex-0.15.3 → codecortex-0.15.5}/src/codeintel/doctor.py

@@ -8,6 +8,7 @@ effects). The same report drives the CLI `doctor` command, the `code.doctor` MCP
 from __future__ import annotations
 
 import os
+import pathlib
 import shutil
 from collections.abc import Callable
 from typing import Any
@@ -106,6 +107,51 @@ def _dist_version(name: str) -> str | None:
         return None
 
 
+def running_version_skew() -> tuple[str, str] | None:
+    """``(running, on_disk)`` when this process is serving code older than what is installed.
+
+    A long-lived server holds the module it imported at startup. Upgrading the package underneath
+    it — `uv tool install`, `pip install -U` — replaces the files on disk and changes nothing about
+    the running process, which keeps answering with the old code until something restarts it. That
+    gap is silent and it is not hypothetical: a fix can be committed, released, installed, read in
+    the CHANGELOG, and still absent from every answer the user is getting, with `status` reporting
+    the stale version as if it were the truth.
+
+    Detected by re-reading `__version__` out of the very file this module was loaded FROM, at call
+    time. `importlib.metadata` would be the obvious route and is the wrong one here: it answers
+    "what does the installed distribution claim", which is the same number for a fresh process and
+    a stale one, and its path caches make the negative case unreliable. Parsed with `ast` rather
+    than imported or regexed — re-importing would either return the cached stale module or execute
+    freshly-installed code inside a process running the old version, and neither is something a
+    health check should do.
+
+    Never raises, and stays silent whenever it cannot be sure: a missing file, an unparseable
+    source, or an absent `__version__` all mean "no claim", because a false upgrade prompt costs
+    more trust than a missed one.
+    """
+    try:
+        import ast as _ast
+
+        import codeintel
+        running = getattr(codeintel, "__version__", None)
+        path = getattr(codeintel, "__file__", None)
+        if not isinstance(running, str) or not path:
+            return None
+        src = pathlib.Path(path).read_text(encoding="utf-8", errors="replace")
+        for node in _ast.parse(src).body:
+            if not isinstance(node, _ast.Assign):
+                continue
+            for target in node.targets:
+                if isinstance(target, _ast.Name) and target.id == "__version__":
+                    on_disk = _ast.literal_eval(node.value)
+                    if isinstance(on_disk, str) and on_disk != running:
+                        return (running, on_disk)
+                    return None
+    except Exception:
+        return None
+    return None
+
+
 def collect_versions(engines: dict) -> dict:
     """Versions of the external backends each engine depends on.
 
@@ -270,12 +316,27 @@ def run_doctor(
     healthy = all(
         e.get("status") != "fail" for n, e in engines.items() if n not in _OPTIONAL_ENGINES
     )
+    # A skew is reported even when every engine is green, because it makes all the other numbers
+    # untrustworthy: they describe the code this process loaded, not the code that is installed.
+    skew = running_version_skew()
     return {
         "ok": True,
         "project_root": root,
         "deep": bool(deep),
         "treesitter": treesitter,
         "versions": versions,
+        "version_skew": (
+            {
+                "running": skew[0],
+                "installed": skew[1],
+                "remediation": (
+                    f"this process is serving {skew[0]} while {skew[1]} is installed — "
+                    "restart the codeintel server (or the agent hosting it) to pick it up"
+                ),
+            }
+            if skew
+            else None
+        ),
         "summary": {"ready": ready, "total": len(engines), "healthy": healthy},
         "engines": engines,
         "registrations": collect_registrations(),
@@ -326,6 +387,16 @@ def render_doctor_text(report: dict) -> str:
         if rem:
             out.append("     " + c.bold(c.cyan("fix:")) + " " + rem)
 
+    # Rendered with the engine notes rather than in the version block: it is a gap with a fix,
+    # which is what this section is for, and it outranks the engine rows — those describe the
+    # loaded code, and a skew means the loaded code is not the installed code.
+    skew = report.get("version_skew")
+    if isinstance(skew, dict) and skew.get("running") and skew.get("installed"):
+        out.append("  " + c.dim("└─") + " " + c.cyan("codeintel")
+                   + f": serving {skew['running']}, installed is {skew['installed']}")
+        out.append("     " + c.bold(c.cyan("fix:")) + " restart the codeintel server "
+                   "(or the agent hosting it) to pick up the installed version")
+
     summ = report.get("summary", {})
     ready, total, healthy = summ.get("ready", "?"), summ.get("total", "?"), summ.get("healthy")
     count = c.bold(f"{ready} / {total}")