codecortex 0.23.1__tar.gz → 0.23.3__tar.gz

{codecortex-0.23.1/src/codecortex.egg-info → codecortex-0.23.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.23.1
+Version: 0.23.3
 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

{codecortex-0.23.1 → codecortex-0.23.3/src/codecortex.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.23.1
+Version: 0.23.3
 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

codecortex-0.23.3/src/codeintel/__init__.py

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

{codecortex-0.23.1 → codecortex-0.23.3}/src/codeintel/gateway.py

@@ -174,7 +174,7 @@ class Gateway:
         self, result: Result, op: str, target: str, budget: Any,
         project_root: Any, was_auto: bool,
     ) -> Result:
-        """Ask the LSP when the graph's whole answer was resolved by name rather than by import.
+        """Ask the LSP when the graph's caller answer carries a known binding failure.
 
         This closes the routing gap that let the worst failure through. `_AUTO_ENGINE` is a static
         op→engine map, not a cascade: `callers` goes to the graph and, uniquely among the ops, has
@@ -185,48 +185,71 @@ class Gateway:
         being confidently wrong is a bug; no second engine ever being consulted is the design that
         let it reach the caller.
 
-        Deliberately narrow. It fires only when the graph itself raised `all-rows-name-resolved` —
-        every row a name guess, across enough rows for the pattern to mean something — which is the
-        collision signature and not the ordinary case of one unverified row among several. It
-        APPENDS rather than replaces: the LSP answers a related but different question (references,
-        not call edges), so presenting its list as the graph's would substitute one over-claim for
-        another. And it never fires for an explicitly pinned `--engine graph`, where the caller has
-        said which engine they want."""
+        Deliberately narrow. It fires when every graph row was name-resolved, or when a caller used
+        a file hint and the graph found same-named symbols but no edge for that exact definition.
+        The latter catches property calls that the TypeScript graph resolver failed to bind, while
+        avoiding an LSP call for ordinary healthy answers. It APPENDS rather than replaces: the LSP
+        answers a related but different question (references, not call edges), so presenting its
+        list as the graph's would substitute one over-claim for another. And it never fires for an
+        explicitly pinned `--engine graph`, where the caller has said which engine they want."""
         try:
             if not was_auto or op not in self._CROSS_CHECKED_OPS:
                 return result
             if result.get("result") is None or self.lsp is None:
                 return result
             gaps = result.get("gaps") or []
-            if not any(g.get("kind") == "all-rows-name-resolved"
-                       for g in gaps if isinstance(g, dict)):
+            kinds = {
+                str(g.get("kind") or "") for g in gaps if isinstance(g, dict)
+            }
+            all_name_resolved = "all-rows-name-resolved" in kinds
+            exact_target_unbound = "target-hint-unmatched" in kinds
+            if not (all_name_resolved or exact_target_unbound):
                 return result
+            graph_problem = (
+                "every graph row was resolved by name"
+                if all_name_resolved
+                else "the graph found no caller edge for the file-qualified symbol"
+            )
             probe = self._dispatch_single(
                 self.lsp, "symbol", target, budget, project_root, "lsp")
             body = probe.get("result")
-            if not body:
+            probe_gaps = probe.get("gaps") or []
+            reference_gap = next((
+                gap for gap in probe_gaps
+                if isinstance(gap, dict) and gap.get("section") == "references"
+            ), None)
+            if not body or reference_gap is not None:
                 # Silence from the LSP is not agreement. Say which check did not happen — and
                 # separate "not yet booted" from "had nothing", because only the first is fixed by
                 # asking again. A one-shot CLI process meets a cold serena on every invocation; the
                 # long-lived MCP server keeps the session warm and takes this branch once at most.
                 # Waiting here is deliberately NOT done: it would hold back a graph answer that is
                 # already complete, to append a section that is only advisory.
-                warming = probe.get("reason") == "warming"
-                why = ("the language server had not finished booting"
-                       if warming else "the LSP engine reported nothing for this symbol")
+                unavailable_reason = (
+                    str(reference_gap.get("kind") or "not-asked")
+                    if reference_gap is not None else str(probe.get("reason") or "no-result")
+                )
+                warming = unavailable_reason in {"warming", "timeout"}
+                why = (
+                    "the language server had not finished booting"
+                    if unavailable_reason == "warming"
+                    else str(reference_gap.get("detail") or "the reference lookup did not answer")
+                    if reference_gap is not None
+                    else "the LSP engine reported nothing for this symbol"
+                )
                 nxt = (" Ask again once it is warm and this section will be filled in."
                        if warming else
                        " Check it yourself with `--engine lsp --op symbol`.")
                 return {**result, "gaps": [*gaps, {
                     "section": op, "kind": "cross-check-unavailable",
                     "engine": "lsp",
-                    "reason": probe.get("reason") or "no-result",
-                    "detail": f"every graph row was name-resolved and the LSP could not confirm "
-                              f"them ({why}), so they remain unverified"
+                    "reason": unavailable_reason,
+                    "detail": f"{graph_problem} and the LSP could not provide an independent "
+                              f"reference check ({why}), so the graph answer remains unverified"
                               + (" — retry" if warming else ""),
                     **({"retry_after_s": 2} if warming else {}),
                 }], "result": str(result["result"]) + (
-                    f"\n\n> Cross-check unavailable: every row above was resolved by name, and "
+                    f"\n\n> Cross-check unavailable: {graph_problem}, and "
                     f"{why}, so nothing here has been confirmed against a second engine.{nxt}"
                 )}
             refs = self._reference_lines(str(body))
@@ -236,15 +259,15 @@ class Gateway:
             merged = (
                 f"{result['result']}\n\n## Cross-check — LSP references to `{target}` "
                 f"({len(refs)})\n"
-                f"_The rows above were all resolved by NAME by the graph engine. These come from the "
-                f"language server, which resolves through the file's imports. A caller listed above "
-                f"but absent here is very likely a name collision; a location here but missing above "
-                f"is a call the graph could not bind._\n" + listing + more
+                f"_The graph answer has a known binding gap: {graph_problem}. These locations come "
+                f"from the language server, which resolves the exact definition. A caller listed "
+                f"above but absent here is likely a name collision; a location here but missing "
+                f"above is a reference the graph could not bind._\n" + listing + more
             )
             return {**result, "result": merged, "gaps": [*gaps, {
                 "section": op, "kind": "cross-checked-with-lsp",
                 "engine": "lsp",
-                "detail": f"every graph row was name-resolved, so the LSP was consulted "
+                "detail": f"{graph_problem}, so the LSP was consulted "
                           f"independently and reported {len(refs)} reference location(s); the two "
                           f"lists answer related but different questions and are shown separately",
             }]}
@@ -292,17 +315,22 @@ class Gateway:
             # codebase throws away the could-not-ask / asked-and-found-nothing distinction it is
             # otherwise careful to preserve per-provider.
             reasons = {eng: str(r.get("reason") or "no-result") for eng, r in results.items()}
-            unreachable = {"engine-unavailable", "boot-failed", "warming", "project-not-indexed",
-                           "project-not-indexed-standalone", "error", "timeout",
-                           # An index pass that RAN and FAILED is a could-not-ask, not a
-                           # found-nothing. `no-index` deliberately stays out: it means the pass
-                           # completed and there was nothing to embed, which is an answer.
-                           "index-failed",
-                           # A query the embedder could not encode. No search ran, so the empty
-                           # result says nothing about the repository — the same reasoning as
-                           # `index-failed`, one step later in the pipeline.
-                           "query-failed"}
-            all_unreachable = bool(reasons) and all(v in unreachable for v in reasons.values())
+            # Providers have already classified their reason into the public outcome taxonomy.
+            # Repeating a private reason allow-list here guaranteed drift: the first new reason,
+            # ``source-unreadable``, was correctly marked unavailable by LSP and then collapsed
+            # back to ``not_found`` by this merge.  Failed and unavailable both mean no engine was
+            # able to answer; an actual miss is the explicit ``not_found`` outcome.
+            # Older/custom providers may not have adopted ``outcome`` yet. Route their reason
+            # through the SAME central classifier rather than reintroducing a local allow-list.
+            classified = [
+                r.get("outcome") or safe_null_result(
+                    op_str, target_str, engine=eng, reason=reasons[eng]
+                ).get("outcome")
+                for eng, r in results.items()
+            ]
+            all_unreachable = bool(classified) and all(
+                outcome in ("unavailable", "failed") for outcome in classified
+            )
             summary = "engines-unavailable" if all_unreachable else "no-result"
             detail = ", ".join(f"{eng}: {why}" for eng, why in sorted(reasons.items()))
             return safe_null_result(

{codecortex-0.23.1 → codecortex-0.23.3}/src/codeintel/indexer.py

@@ -390,7 +390,19 @@ class Indexer:
             root_real = real_root(str(root))
         except Exception:
             root_real = str(root)
-        for dirpath, dirnames, filenames in os.walk(root):
+        def fail_on_unreadable_tree(error: OSError) -> None:
+            """Do not turn an unreadable subtree into a successful empty index.
+
+            ``os.walk`` silently ignores directory-enumeration failures unless an ``onerror``
+            callback is supplied.  On macOS this is particularly dangerous for folders protected
+            by Files & Folders / Full Disk Access: the root can pass ``isdir`` while every source
+            directory raises ``EPERM``, leaving the CLI to report "Nothing new to index" at exit
+            zero.  Propagating the original error preserves its path and lets ``index()`` expose a
+            truthful, actionable failure.
+            """
+            raise error
+
+        for dirpath, dirnames, filenames in os.walk(root, onerror=fail_on_unreadable_tree):
             at_root = os.path.realpath(dirpath) == os.path.realpath(real_root_str)
             dirnames[:] = [
                 d for d in dirnames

{codecortex-0.23.1 → codecortex-0.23.3}/src/codeintel/provider.py

@@ -75,20 +75,31 @@ def safe_null_result(
     hint: str | None = None,
 ) -> Result:
     failed_reasons = {
-        "backend-error", "backend-incompatible", "boot-failed", "error", "index-failed",
-        "provider-error", "timeout", "unparsable",
+        "backend-error", "backend-incompatible", "boot-failed", "error", "gateway-error",
+        "handler-error", "index-failed", "provider-error", "query-failed", "timeout",
+        "unparsable",
     }
     unavailable_reasons = {
-        "engine-unavailable", "engines-unavailable", "indexing-in-progress", "no-engine",
-        "no-index", "no-project-root", "op-not-supported", "project-not-indexed",
-        "project-not-indexed-standalone", "unsupported-op", "warming",
+        "backend-unreachable", "engine-unavailable", "engines-unavailable", "indexing-in-progress",
+        "index-stale", "no-engine", "no-project-root", "op-not-allowed-for-role",
+        "op-not-supported", "op-withdrawn", "project-not-indexed",
+        "project-not-indexed-standalone", "root-not-allowed-for-role", "source-unreadable",
+        "unknown-engine", "unsupported-op", "warming",
+    }
+    not_found_reasons = {
+        "below-floor", "no-edges", "no-index", "no-result", "not-found", "not-in-graph",
     }
     if reason in failed_reasons:
         outcome = "failed"
     elif reason in unavailable_reasons:
         outcome = "unavailable"
-    else:
+    elif reason in not_found_reasons:
         outcome = "not_found"
+    else:
+        # New failure reasons must fail closed.  Defaulting every unknown string to ``not_found``
+        # turned a newly introduced ``source-unreadable`` reason into an assertion that the symbol
+        # was absent — exactly the ambiguity the explicit outcome field was added to remove.
+        outcome = "failed"
     r: Result = {
         "ok": True,
         "op": str(op or ""),

{codecortex-0.23.1 → codecortex-0.23.3}/src/codeintel/providers/lsp.py

@@ -67,6 +67,30 @@ _BACKEND_ERROR_MARKERS = (
 )
 
 
+def _split_target_file_hint(target: str) -> tuple[str, str]:
+    """Return Serena's symbol pattern and an optional repo-relative file hint.
+
+    Graph operations accept ``name@path`` to disambiguate duplicate symbols. The gateway may pass
+    that exact target to the LSP for an independent reference cross-check, but Serena understands
+    only the name-path portion. Keep the syntax aligned here without coupling the LSP provider to
+    graph.py's private target parser.
+    """
+    raw = str(target or "").strip()
+    if "@" not in raw:
+        return raw, ""
+    head, _, tail = raw.rpartition("@")
+    if not head.strip() or not tail.strip():
+        return raw, ""
+    return head.strip(), tail.strip()
+
+
+def _file_hint_matches(file_path: Any, hint: str) -> bool:
+    """Match a file hint on path-segment boundaries, consistently with the graph provider."""
+    have = str(file_path or "").replace("\\", "/").strip().strip("/").lower()
+    want = str(hint or "").replace("\\", "/").strip().strip("/").lower()
+    return bool(have and want and (have == want or have.endswith("/" + want)))
+
+
 def _looks_like_backend_error(text: str) -> bool:
     """Whether *text* is a backend failure message rather than a result.
 
@@ -127,6 +151,29 @@ def _serena_launch_args(cmd: str, project_root: str) -> list[str]:
     return [cmd, *common]
 
 
+def _project_access_failure(project_root: str) -> tuple[str, str] | None:
+    """Return a safe diagnosis when the host cannot enumerate the project root.
+
+    Serena's stdio transport wraps an early subprocess exit in an ``ExceptionGroup``.  When the
+    real cause is a macOS Files & Folders denial, reporting that wrapper as a network/bootstrap
+    failure sends the user in exactly the wrong direction.  A one-entry scan is cheap, local, and
+    establishes the prerequisite Serena itself needs without forwarding any backend-controlled
+    prose to the calling agent.
+    """
+    try:
+        with os.scandir(project_root) as entries:
+            next(entries, None)
+    except OSError as exc:
+        location = str(getattr(exc, "filename", None) or project_root)
+        detail = f"repository root is not readable by codeintel ({type(exc).__name__}: {location})"
+        remediation = (
+            "grant the codeintel host read access to the repository, then retry; on macOS check "
+            "System Settings > Privacy & Security > Files and Folders (or Full Disk Access)"
+        )
+        return detail, remediation
+    return None
+
+
 class _State(enum.Enum):
     WARMING = "WARMING"
     READY = "READY"
@@ -433,6 +480,12 @@ class LspProvider:
                     "detail": "serena session is warming for this repo", "remediation": None}
 
         # deep: boot (or reuse) a session and poll to a hard deadline — never hangs.
+        access_failure = _project_access_failure(project_root)
+        if access_failure is not None:
+            detail, remediation = access_failure
+            return {"installed": True, "runnable": False, "repo_indexed": None,
+                    "detail": detail, "remediation": remediation}
+
         session = self._get_or_create_session(project_root)
         deadline = time.monotonic() + timeout_s
         while time.monotonic() < deadline:
@@ -502,6 +555,21 @@ class LspProvider:
             if not self.available:
                 return safe_null_result(op_str, target_str, engine="lsp", reason="engine-unavailable")
 
+            # A protected macOS folder can still satisfy ``isdir`` while denying enumeration.
+            # Detect that locally before spawning Serena: otherwise its early exit is wrapped by
+            # the MCP transport as a generic boot failure and the first-query hint talks about a
+            # cold uvx cache instead of the permission the user actually needs to grant.  Keep the
+            # ``isdir`` guard so synthetic/nonexistent roots used by embedders retain the existing
+            # never-raise backend behaviour.
+            if os.path.isdir(root_str):
+                access_failure = _project_access_failure(root_str)
+                if access_failure is not None:
+                    detail, remediation = access_failure
+                    return safe_null_result(
+                        op_str, target_str, engine="lsp", reason="source-unreadable",
+                        hint=f"{detail}; {remediation}",
+                    )
+
             try:
                 budget_ms = int(budget) if budget else 0
             except Exception:
@@ -729,10 +797,18 @@ class LspProvider:
         self, session: _LspSession, target: str, root: str, timeout_s: float
     ) -> str | None:
         try:
+            symbol_target, file_hint = _split_target_file_hint(target)
             def_out = self._call_tool(
                 session,
                 "find_symbol",
-                {"name_path_pattern": target, "include_body": True, "max_matches": 5},
+                {
+                    "name_path_pattern": symbol_target,
+                    "include_body": True,
+                    # A file hint exists specifically because the name is ambiguous. Retrieve
+                    # enough definitions to find the requested file instead of silently selecting
+                    # whichever five Serena happens to return first.
+                    "max_matches": 50 if file_hint else 5,
+                },
                 timeout_s,
             )
             if isinstance(def_out, Missing):
@@ -745,6 +821,21 @@ class LspProvider:
             def_raw = def_out.value
             def_text = self._extract_text(def_raw)
             matches = self._loads(def_text)
+            if isinstance(matches, list) and file_hint:
+                matches = [
+                    match for match in matches
+                    if isinstance(match, dict)
+                    and _file_hint_matches(match.get("relative_path"), file_hint)
+                ]
+                if not matches:
+                    # Do not fall through and render the original JSON containing definitions
+                    # from other files. More importantly, the reference lookup below must remain
+                    # "not asked", rather than turning an unresolved exact definition into a
+                    # confident zero-reference answer.
+                    def_text = (
+                        f"> The language server found no definition for `{symbol_target}` in "
+                        f"`{file_hint}`."
+                    )
 
             first: dict | None = None
             if isinstance(matches, list) and matches:

{codecortex-0.23.1 → codecortex-0.23.3}/tests/test_doctor.py

@@ -316,6 +316,27 @@ def test_lsp_probe_deep_boot_failure_is_bounded(monkeypatch):
     assert r["runnable"] in (False, None)  # failed to boot (or timed out) — never True
 
 
+def test_lsp_probe_reports_repository_access_before_blaming_network(monkeypatch):
+    monkeypatch.setattr("codeintel.providers.lsp.shutil.which", lambda x: "/fake/uvx")
+    monkeypatch.setattr(
+        "codeintel.providers.lsp.os.scandir",
+        lambda root: (_ for _ in ()).throw(PermissionError(1, "denied", str(root))),
+    )
+    p = LspProvider()
+    monkeypatch.setattr(
+        p, "_get_or_create_session",
+        lambda root: pytest.fail("an unreadable repository must not launch serena"),
+    )
+
+    r = p.probe("/protected/repo", deep=True)
+
+    assert r["runnable"] is False
+    assert "PermissionError" in r["detail"]
+    assert "/protected/repo" in r["detail"]
+    assert "Privacy & Security" in r["remediation"]
+    assert "network" not in r["remediation"].lower()
+
+
 # --------------------------------------------------------------------------- #
 # handler + hint plumbing
 # --------------------------------------------------------------------------- #

{codecortex-0.23.1 → codecortex-0.23.3}/tests/test_gateway.py

@@ -548,6 +548,7 @@ def test_a_fanout_where_engines_ran_and_found_nothing_still_reports_no_result():
                  lsp=_NullProvider("lsp", "not-found"))
     r = gw.query(op="context", target="nope", engine="both")
     assert r["reason"] == "no-result"
+    assert r["outcome"] == "not_found"
     assert "NOT evidence" not in (r.get("hint") or "")
 
 

{codecortex-0.23.1 → codecortex-0.23.3}/tests/test_incompleteness.py

@@ -371,8 +371,13 @@ def test_null_result_outcome_is_machine_readable():
     from codeintel.provider import safe_null_result
 
     assert safe_null_result("x", "y", reason="not-in-graph")["outcome"] == "not_found"
+    assert safe_null_result("x", "y", reason="not-found")["outcome"] == "not_found"
+    assert safe_null_result("x", "y", reason="no-index")["outcome"] == "not_found"
     assert safe_null_result("x", "y", reason="engine-unavailable")["outcome"] == "unavailable"
     assert safe_null_result("x", "y", reason="backend-error")["outcome"] == "failed"
+    assert safe_null_result("x", "y", reason="source-unreadable")["outcome"] == "unavailable"
+    assert safe_null_result("x", "y", reason="backend-unreachable")["outcome"] == "unavailable"
+    assert safe_null_result("x", "y", reason="new-unclassified-reason")["outcome"] == "failed"
 
 
 def test_a_fanned_out_answer_reports_the_engine_that_could_not_be_asked():
@@ -398,6 +403,31 @@ def test_a_fanned_out_answer_reports_the_engine_that_could_not_be_asked():
     assert "engine-unavailable" in kinds, kinds
 
 
+def test_fan_out_preserves_source_unreadable_as_unavailable():
+    """The merge must consume the public outcome, not maintain another reason allow-list.  If all
+    engines could not answer, a newly introduced reason must never collapse back to ``not_found``.
+    """
+    from codeintel.gateway import Gateway
+    from codeintel.provider import safe_null_result
+
+    merged = Gateway()._merge(
+        {
+            "lsp": safe_null_result(
+                "context", "createSession", engine="lsp", reason="source-unreadable"
+            ),
+            "graph": safe_null_result(
+                "context", "createSession", engine="graph", reason="project-not-indexed"
+            ),
+        },
+        "context", "createSession",
+    )
+
+    assert merged["result"] is None
+    assert merged["reason"] == "engines-unavailable"
+    assert merged["outcome"] == "unavailable"
+    assert "NOT evidence" in merged["hint"]
+
+
 def test_a_constituent_gap_survives_the_merge():
     from codeintel.gateway import Gateway
 

{codecortex-0.23.1 → codecortex-0.23.3}/tests/test_index_failure_reason.py

@@ -326,6 +326,31 @@ def test_other_failures_keep_their_type_prefix(monkeypatch, tmp_path):
     assert indexer.last_error == "PermissionError: read-only file system"
 
 
+def test_an_unreadable_subtree_is_not_a_successful_empty_walk(monkeypatch, tmp_path):
+    """``os.walk`` ignores enumeration errors by default.  A macOS-protected repository could
+    therefore scan as zero files and make the CLI print "Nothing new to index" at exit zero even
+    though no source was readable.  The original permission error, including its path, must escape
+    the walk so ``Indexer.index`` can report it as an unrecoverable failure.
+    """
+    import codeintel.indexer as indexer_module
+    from codeintel.indexer import Indexer
+
+    protected = tmp_path / "protected-repo"
+
+    def denied_walk(root, *, onerror=None):
+        assert onerror is not None
+        onerror(PermissionError(1, "Operation not permitted", str(protected)))
+        return []
+
+    monkeypatch.setattr(indexer_module.os, "walk", denied_walk)
+    monkeypatch.setattr(indexer_module, "load_gitattributes_globs", lambda root: [])
+    indexer = Indexer.__new__(Indexer)
+    monkeypatch.setattr(indexer, "_load_gitignore", lambda root: set())
+
+    with pytest.raises(PermissionError, match="protected-repo"):
+        list(indexer._walk_files(tmp_path))
+
+
 def test_the_searcher_reports_it_too(monkeypatch):
     """A query is the other way a cold cache is discovered — stage-qualified, message verbatim."""
     from codeintel.searcher import Searcher

{codecortex-0.23.1 → codecortex-0.23.3}/tests/test_lsp_provider.py

@@ -6,6 +6,8 @@ import time
 from typing import Any
 from unittest.mock import MagicMock
 
+import pytest
+
 from codeintel.outcome import Missing, Ok
 from codeintel.providers.lsp import LspProvider, _State
 from codeintel.server import code_status_handler
@@ -161,6 +163,64 @@ def test_lsp_provider_ready_symbol(monkeypatch):
     assert "parse_result" in r["result"]
 
 
+def test_file_qualified_symbol_selects_the_matching_definition(monkeypatch):
+    """A graph file hint must survive the LSP cross-check instead of selecting a same-name method."""
+    monkeypatch.setattr("codeintel.providers.lsp.shutil.which", lambda x: "/fake/uvx")
+    p = LspProvider()
+    p._sessions["/my/repo"] = _make_fake_session(_State.READY)
+    calls: list[tuple[str, dict]] = []
+
+    def _fake_call_tool(session, tool, args, timeout_s):
+        calls.append((tool, args))
+        if tool == "find_symbol":
+            return Ok('[{"name_path":"Other/createSession","kind":"Method",'
+                      '"relative_path":"src/other.ts","body_location":{"start_line":1,'
+                      '"end_line":2},"body":"wrong"},{"name_path":"WsSessionHandler/createSession",'
+                      '"kind":"Method","relative_path":"backend/src/session.handler.ts",'
+                      '"body_location":{"start_line":138,"end_line":177},"body":"right"}]')
+        if tool == "find_referencing_symbols":
+            assert args["name_path"] == "WsSessionHandler/createSession"
+            assert args["relative_path"] == "backend/src/session.handler.ts"
+            return Ok('{"backend/src/gateway.ts":{"Method":[{"name_path":"Gateway/routeMessage",'
+                      '"content_around_reference":"> 612: await handler.createSession()"}]}}')
+        return Missing("backend-error", "unstubbed tool")
+
+    monkeypatch.setattr(p, "_call_tool", _fake_call_tool)
+    r = p.build_result(
+        "symbol", "createSession@backend/src/session.handler.ts", [], 30000, "/my/repo"
+    )
+
+    assert r["confidence"] == "complete"
+    assert "right" in r["result"] and "wrong" not in r["result"]
+    assert "backend/src/gateway.ts:613" in r["result"]
+    assert calls[0][1]["name_path_pattern"] == "createSession"
+    assert calls[0][1]["max_matches"] == 50
+
+
+def test_file_qualified_symbol_does_not_use_a_definition_from_another_file(monkeypatch):
+    monkeypatch.setattr("codeintel.providers.lsp.shutil.which", lambda x: "/fake/uvx")
+    p = LspProvider()
+    p._sessions["/my/repo"] = _make_fake_session(_State.READY)
+    calls: list[str] = []
+
+    def _fake_call_tool(session, tool, args, timeout_s):
+        calls.append(tool)
+        return Ok('[{"name_path":"Other/createSession","kind":"Method",'
+                  '"relative_path":"src/other.ts","body_location":{"start_line":1,'
+                  '"end_line":2},"body":"wrong"}]')
+
+    monkeypatch.setattr(p, "_call_tool", _fake_call_tool)
+    r = p.build_result(
+        "symbol", "createSession@backend/src/session.handler.ts", [], 30000, "/my/repo"
+    )
+
+    assert r["confidence"] == "partial"
+    assert "found no definition" in r["result"] and "wrong" not in r["result"]
+    assert "References — not retrieved" in r["result"]
+    assert calls == ["find_symbol"]
+    assert any(g["section"] == "references" and g["kind"] == "not-asked" for g in r["gaps"])
+
+
 # ---------------------------------------------------------------------------
 # Group 8 — Unsupported op when READY
 # ---------------------------------------------------------------------------
@@ -462,6 +522,32 @@ def test_boot_failed_on_a_cold_uvx_first_attempt_reads_as_retry(monkeypatch):
     assert "download" in hint
 
 
+def test_an_unreadable_repository_never_launches_serena(monkeypatch):
+    monkeypatch.setattr("codeintel.providers.lsp.shutil.which",
+                        lambda x: "/fake/uvx" if x == "uvx" else None)
+    monkeypatch.setattr("codeintel.providers.lsp.os.path.isdir", lambda root: True)
+    monkeypatch.setattr(
+        "codeintel.providers.lsp._project_access_failure",
+        lambda root: (
+            f"repository root is not readable by codeintel (PermissionError: {root})",
+            "grant repository access",
+        ),
+    )
+    p = LspProvider()
+    monkeypatch.setattr(
+        p, "_get_or_create_session",
+        lambda root: pytest.fail("an unreadable repository must not launch serena"),
+    )
+
+    r = p.build_result("symbol", "createSession", [], 1000, "/protected/repo")
+
+    assert r["result"] is None
+    assert r["reason"] == "source-unreadable"
+    assert r["outcome"] == "unavailable"
+    assert "PermissionError" in r["hint"]
+    assert "grant repository access" in r["hint"]
+
+
 def test_boot_failed_on_a_respawn_does_not_blame_a_cold_cache(monkeypatch):
     """`uvx` populated its cache on the first attempt, so "still downloading" is only true once."""
     monkeypatch.setattr("codeintel.providers.lsp.shutil.which",