codecortex 0.15.4__tar.gz → 0.15.5__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.15.4
+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.4 → 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.4 → codecortex-0.15.5/src/codecortex.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.15.4
+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.4 → codecortex-0.15.5}/src/codecortex.egg-info/SOURCES.txt

@@ -66,6 +66,8 @@ 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
@@ -100,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.4 → 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.4 → 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}")

{codecortex-0.15.4 → codecortex-0.15.5}/src/codeintel/providers/graph.py

@@ -1070,6 +1070,15 @@ class GraphProvider:
         does filter them: a callee in a different language family than the caller, or in a file that
         is not code at all, is not a callee — it is a name collision, and dropping it costs nothing
         real. What survives is marked so the caller knows the resolution is name-based.
+
+        The family check is resolved PER ROW against that row's own `a.file_path`, not against the
+        set of families across every row. `target` can itself be a bare name shared by callers in
+        more than one language, and comparing a row's callee to the UNION of every caller's family
+        let a genuine collision hide behind an unrelated caller: three rows for a Python `target`
+        and a TypeScript `target` made `caller_families = {python, ts-js}`, so a `.ts` name-collision
+        callee reached from the *Python* caller passed the check — it shares a family with the
+        wrong caller. Each row already carries the one caller file it actually came from, so that is
+        what it is checked against.
         """
         cypher = (
             f'MATCH (a)-[c:CALLS|USAGE]->(b) WHERE a.name="{_cypher_literal(target)}" '
@@ -1079,10 +1088,6 @@ class GraphProvider:
         if not rows:
             return None
 
-        caller_families = {
-            _lang_family(str(r.get("a.file_path") or "")) for r in rows
-        } - {""}
-
         kept: list[dict] = []
         dropped = 0
         for r in rows:
@@ -1090,9 +1095,10 @@ class GraphProvider:
             if _is_non_code(path):
                 dropped += 1          # a data/doc file cannot be a callee
                 continue
-            fam = _lang_family(path)
-            if fam and caller_families and fam not in caller_families:
-                dropped += 1          # cross-language name collision
+            callee_fam = _lang_family(path)
+            caller_fam = _lang_family(str(r.get("a.file_path") or ""))
+            if callee_fam and caller_fam and callee_fam != caller_fam:
+                dropped += 1          # cross-language name collision, resolved against THIS row's own caller
                 continue
             kept.append(r)
 

{codecortex-0.15.4 → codecortex-0.15.5}/src/codeintel/server.py

@@ -132,6 +132,7 @@ _STATUS_FALLBACK: dict = {
     "model": None,
     "healthy": False,
     "readiness": {},
+    "version_skew": None,
 }
 
 
@@ -228,6 +229,11 @@ def _code_status_handler_inner(args: dict) -> dict:
             "healthy": bool(summary.get("healthy")),
             "readiness": readiness,
             "versions": report.get("versions", {}) if isinstance(report, dict) else {},
+            # Null on the normal path. Non-null means every other field above describes the code
+            # this process loaded at startup rather than the code that is installed — so it is
+            # surfaced on `status`, not just in `doctor`, because `status` is what a caller checks
+            # when an expected fix appears to be missing.
+            "version_skew": report.get("version_skew") if isinstance(report, dict) else None,
         }
     except Exception:
         return dict(_STATUS_FALLBACK)

codecortex-0.15.5/tests/test_docs_ci_claims.py

@@ -0,0 +1,99 @@
+"""The README's claims about CI must match the workflow that actually runs.
+
+This guards a drift that has now happened in BOTH directions. The `deadcode` case was the
+optimistic one: the docs advertised a capability the product had withdrawn. This is the pessimistic
+one — the README told readers the graph and LSP backends were "not installed in CI, so those two
+engines are exercised against hand-authored mocks", long after dedicated contract jobs had been
+added that install the real backends and run against them. Understating assurance is a smaller sin
+than overstating it, but it is the same defect: a hand-written claim about a machine-readable fact,
+with nothing checking the two still agree.
+
+Facts are derived from `.github/workflows/ci.yml`, never typed here — a hand-typed expectation is
+the thing being guarded against. Parsed as text rather than with PyYAML, which is present in the
+dev environment but is not a declared dependency, so importing it would make this test the reason a
+clean install fails.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parent.parent
+CI = ROOT / ".github" / "workflows" / "ci.yml"
+README = ROOT / "README.md"
+
+
+def _job_blocks(text: str) -> dict[str, str]:
+    """``{job_name: body}`` for each top-level job — a 2-space key under `jobs:`."""
+    lines = text.splitlines()
+    starts: list[tuple[int, str]] = [
+        (i, m.group(1))
+        for i, line in enumerate(lines)
+        if (m := re.match(r"^  ([a-z0-9][a-z0-9_-]*):\s*$", line))
+    ]
+    blocks: dict[str, str] = {}
+    for idx, (line_no, name) in enumerate(starts):
+        end = starts[idx + 1][0] if idx + 1 < len(starts) else len(lines)
+        blocks[name] = "\n".join(lines[line_no:end])
+    return blocks
+
+
+@pytest.fixture(scope="module")
+def ci_text() -> str:
+    if not CI.exists():
+        pytest.skip("ci.yml not present")
+    return CI.read_text(encoding="utf-8")
+
+
+@pytest.fixture(scope="module")
+def readme_text() -> str:
+    return README.read_text(encoding="utf-8")
+
+
+def test_the_workflow_actually_has_contract_jobs(ci_text):
+    # Non-vacuity. Every assertion below is of the form "for each contract job ..." and would pass
+    # trivially against a workflow that has none — which is exactly the state this file exists to
+    # notice, so it is asserted rather than assumed.
+    contract = [n for n in _job_blocks(ci_text) if "contract" in n]
+    assert contract, "no *-contract jobs found in ci.yml — the parser or the workflow changed"
+
+
+def test_readme_names_every_contract_job(ci_text, readme_text):
+    missing = [
+        name for name in _job_blocks(ci_text)
+        if "contract" in name and name not in readme_text
+    ]
+    assert not missing, (
+        f"ci.yml runs contract job(s) {missing} that the README never mentions — the docs "
+        "understate what is actually verified"
+    )
+
+
+def test_readme_does_not_claim_backends_are_absent_from_ci(ci_text, readme_text):
+    # The precise stale sentence, tied to the fact that falsifies it.
+    installs_graph_backend = "codebase-memory-mcp==" in ci_text
+    if installs_graph_backend:
+        assert "not installed in CI" not in readme_text, (
+            "ci.yml installs the pinned graph backend, but the README still says the backends are "
+            "'not installed in CI' — the claim was true before the contract jobs existed"
+        )
+
+
+def test_readme_reflects_which_contract_jobs_actually_gate(ci_text, readme_text):
+    """A non-gating job must not read as a gating one.
+
+    `continue-on-error` is the difference between "a serena regression turns CI red" and "a serena
+    regression is a note someone may notice". A reader deciding how much to trust the LSP path
+    needs that distinction, so if any contract job carries the flag, the README has to say so.
+    """
+    soft = [
+        name for name, body in _job_blocks(ci_text).items()
+        if "contract" in name and re.search(r"^\s*continue-on-error:\s*true\s*$", body, re.M)
+    ]
+    if soft:
+        assert "continue-on-error" in readme_text, (
+            f"contract job(s) {soft} are continue-on-error, so they do not gate a release — the "
+            "README describes the contract coverage without saying which parts are non-gating"
+        )