Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

perf(mcp): serve a digest of the index scope, not the whole thing, on every call (#2284)

Raghav Chamadiyacc0f9ae15a56
diff --git a/docs/reference/CLI_REFERENCE.md b/docs/reference/CLI_REFERENCE.md
index 002308e5d..f6a6e5eee 100644
--- a/docs/reference/CLI_REFERENCE.md
+++ b/docs/reference/CLI_REFERENCE.md
@@ -270,6 +270,8 @@ See [WORKTREES.md](../scale/WORKTREES.md).
`state.json:index_scope` is the canonical machine-readable description used by `status --format json`, `/api/repos`, generated agent guidance, and MCP `_meta.index_scope`. It separately records run mode, content provenance (`none`, `template`, or `model`), Git tier, configured commit cap, achieved Git-history coverage, configured/effective file-page caps, eligible/generated/omitted file-page counts, unavailable/skipped analysis, search availability, provider choices, and upgrade state. Older indexes project missing facts as `unknown`/`null`; a configured cap is never reported as achieved coverage and a missing analysis result is never reported as a clean result.
+Over MCP, an ordinary tool response carries a **compact projection** of this object rather than all of it: the run mode, content provenance, Git tier, a `status` of `complete`, `partial`, `degraded`, `upgrading` or `unknown`, the names of any degraded analyses, and a `fingerprint` identifying the canonical object. `get_overview` carries the canonical object in full, with the same `fingerprint` beside it, so a held copy can be checked against a later digest without either side resending it. `status` reaches `complete` only when the evidence exists and is clean; an index whose coverage was never recorded reports `unknown`. Set `REPOWISE_MCP_INDEX_SCOPE=full` to put the canonical object on every MCP response, as builds before `_meta.contract_version` 2 did.
+
**Examples:**
```bash
diff --git a/packages/core/src/repowise/core/index_scope.py b/packages/core/src/repowise/core/index_scope.py
index a68796503..5ce09fa14 100644
--- a/packages/core/src/repowise/core/index_scope.py
+++ b/packages/core/src/repowise/core/index_scope.py
@@ -8,6 +8,7 @@ complete from a configured limit or from the absence of a finding.
from __future__ import annotations
+import hashlib
import json
from collections.abc import Mapping
from copy import deepcopy
@@ -177,6 +178,140 @@ def resolve_index_scope(
}
+#: What a routine response says instead of the whole canonical scope. The full
+#: object is roughly 900 characters, which on a small ``get_symbol`` response
+#: was about a third of everything the agent received — paid for on every call
+#: to answer a question almost none of them asked.
+COMPACT_INDEX_SCOPE_PROJECTION = "compact"
+CANONICAL_INDEX_SCOPE_PROJECTION = "full"
+
+#: Set to ``full`` to serve the canonical scope everywhere, as builds before
+#: the compact projection did. The compatibility window for a reader that
+#: parses the whole object and cannot yet ask for it by name.
+INDEX_SCOPE_ENV = "REPOWISE_MCP_INDEX_SCOPE"
+
+
+#: Upgrade states that mean the index is still being built. Reported ahead of
+#: everything else: they explain the rest and they resolve on their own.
+_UPGRADE_IN_FLIGHT = frozenset({"pending", "running", "resumable"})
+
+#: Search legs. A leg that is "pending" is not usable yet, which is a smaller
+#: problem than one that failed but is not nothing.
+_SEARCH_LEGS = ("full_text", "semantic")
+
+
+def _section(scope: Mapping[str, Any], name: str) -> Mapping[str, Any]:
+ """One sub-block of a scope, or an empty one when it is missing or junk."""
+ section = scope.get(name)
+ return section if isinstance(section, Mapping) else {}
+
+
+def _is_degraded(upgrade: Mapping[str, Any], scope: Mapping[str, Any]) -> bool:
+ """Whether some part of the index was meant to exist and does not."""
+ search = _section(scope, "search")
+ return (
+ upgrade.get("status") == "failed"
+ or bool(_section(scope, "analysis").get("unavailable"))
+ or any(search.get(leg) == "unavailable" for leg in _SEARCH_LEGS)
+ )
+
+
+def _is_partial(scope: Mapping[str, Any]) -> bool:
+ """Whether the index is sound but does not yet cover everything."""
+ search = _section(scope, "search")
+ return (
+ bool(_number(_section(scope, "file_pages").get("omitted")))
+ or bool(_section(scope, "analysis").get("skipped"))
+ or any(search.get(leg) == "pending" for leg in _SEARCH_LEGS)
+ )
+
+
+def _is_unexamined(scope: Mapping[str, Any]) -> bool:
+ """Whether the evidence that would tell complete from partial is missing.
+
+ A legacy index, or any state with no ``index_scope`` key, projects every
+ one of these as ``unknown``/``None``. Reading that as "nothing is wrong"
+ would turn absence of evidence into a claim of completeness, which is the
+ one thing this module promises never to do.
+ """
+ search = _section(scope, "search")
+ return _number(_section(scope, "file_pages").get("omitted")) is None or any(
+ search.get(leg) == "unknown" for leg in _SEARCH_LEGS
+ )
+
+
+def _scope_status(scope: Mapping[str, Any]) -> str:
+ """One word for how much of the intended index actually exists.
+
+ Ordered worst-first on purpose: an index that is both mid-upgrade and
+ missing pages reports the upgrade, because that is the condition that
+ explains the rest and the one that will change on its own. ``complete``
+ is last and is reached only when the evidence exists and is clean, so it
+ never stands in for evidence that was merely never recorded — that is
+ ``unknown``, which is a different answer and says so.
+ """
+ upgrade = _section(scope, "upgrade")
+ if upgrade.get("status") in _UPGRADE_IN_FLIGHT:
+ return "upgrading"
+ if _is_degraded(upgrade, scope):
+ return "degraded"
+ if _is_partial(scope):
+ return "partial"
+ if _is_unexamined(scope):
+ return "unknown"
+ return "complete"
+
+
+def index_scope_fingerprint(scope: Mapping[str, Any]) -> str:
+ """A short stable digest of one canonical scope.
+
+ Two responses carrying the same fingerprint were built against the same
+ scope, so a caller holding the full object from an earlier call knows its
+ copy still describes this one — without either side resending it.
+
+ sha256 over the canonical JSON, first 12 hex characters. No ``default``
+ serializer: every field here is JSON-derived or passed through
+ :func:`_number`/:func:`_string`/:func:`_choice`, and a fallback would let a
+ future plain object stringify to its address and churn the digest every
+ process while still looking valid. Raising is the better failure.
+ """
+ canonical = json.dumps(scope, sort_keys=True, separators=(",", ":"))
+ return hashlib.sha256(canonical.encode("utf-8")).hexdigest()[:12]
+
+
+def compact_index_scope(
+ scope: Mapping[str, Any] | None, *, full_hint: str = "get_overview()"
+) -> dict[str, Any] | None:
+ """The routine-response projection of a canonical scope.
+
+ Keeps what changes how an answer should be read — the run mode, where the
+ prose came from, how much git there is, and whether the index is whole —
+ plus a fingerprint identifying the full object and the call that returns
+ it. Everything else is a diagnostic, and a diagnostic that rides on every
+ response is a tax, not a disclosure.
+
+ The one exception is ``degraded_analyses``, carried only when non-empty:
+ which analysis is missing changes what an answer means, and "health failed"
+ and "the graph failed" are not the same warning.
+ """
+ if not isinstance(scope, Mapping):
+ return None
+ compact: dict[str, Any] = {
+ "version": scope.get("version", INDEX_SCOPE_VERSION),
+ "projection": COMPACT_INDEX_SCOPE_PROJECTION,
+ "run_mode": scope.get("run_mode", "unknown"),
+ "content_provenance": scope.get("content_provenance", "unknown"),
+ "git_tier": scope.get("git_tier", "unknown"),
+ "status": _scope_status(scope),
+ "fingerprint": index_scope_fingerprint(scope),
+ "full": full_hint,
+ }
+ unavailable = _section(scope, "analysis").get("unavailable")
+ if unavailable:
+ compact["degraded_analyses"] = list(unavailable)
+ return compact
+
+
def stamp_index_scope(
state: dict[str, Any],
config: Mapping[str, Any] | None = None,
diff --git a/packages/server/src/repowise/server/mcp_server/_meta.py b/packages/server/src/repowise/server/mcp_server/_meta.py
index b8198ecaa..71e75fa5f 100644
--- a/packages/server/src/repowise/server/mcp_server/_meta.py
+++ b/packages/server/src/repowise/server/mcp_server/_meta.py
@@ -18,13 +18,24 @@ Rules of thumb baked into the hint generators:
from __future__ import annotations
+import os
from datetime import UTC, datetime
from pathlib import Path
from typing import Any
-from repowise.core.index_scope import load_index_scope
+from repowise.core.index_scope import (
+ CANONICAL_INDEX_SCOPE_PROJECTION,
+ INDEX_SCOPE_ENV,
+ compact_index_scope,
+ index_scope_fingerprint,
+ load_index_scope,
+)
-MCP_CONTRACT_VERSION = 1
+# 2: index_scope carries the compact projection on routine responses. The key
+# and its version field are unchanged, so a consumer reading the old shape has
+# no way to notice from index_scope itself — the envelope version is where a
+# wire-shape change is announced. REPOWISE_MCP_INDEX_SCOPE=full restores it.
+MCP_CONTRACT_VERSION = 2
# Only warn about age when we have no other signal AND the index is genuinely
# old. A short threshold here would nag on every call and train the agent to
@@ -110,6 +121,43 @@ def read_index_scope(local_path: str | None) -> dict[str, Any] | None:
return load_index_scope(local_path)
+def _canonical_scope_requested() -> bool:
+ """Whether the environment asks for the whole scope on every response.
+
+ The compatibility window, for a reader that parses the full object and has
+ no way yet to ask for it by name. Read per call, so turning it on does not
+ need a restart of a server a client spawned.
+ """
+ return (
+ os.environ.get(INDEX_SCOPE_ENV, "").strip().lower()
+ == CANONICAL_INDEX_SCOPE_PROJECTION
+ )
+
+
+def _full_scope_hint() -> str:
+ """The call that returns the whole scope, as this server is running.
+
+ In workspace mode ``get_overview()`` returns the repo listing and carries
+ no scope at all, so a digest pointing there would send an agent somewhere
+ the rest of the answer is not. The argument is named rather than filled in
+ because the alias belongs to the caller's own request, not to the
+ repository row this envelope was built from.
+ """
+ from repowise.server.mcp_server import _state
+
+ if getattr(_state, "_registry", None) is not None:
+ return "get_overview(repo=...)"
+ return "get_overview()"
+
+
+def index_scope_for_response(local_path: str | None) -> dict[str, Any] | None:
+ """The scope an ordinary response carries: the digest, unless asked."""
+ scope = read_index_scope(local_path)
+ if scope is None or _canonical_scope_requested():
+ return scope
+ return compact_index_scope(scope, full_hint=_full_scope_hint())
+
+
def resolve_indexed_commit(head_commit: str | None, local_path: str | None) -> str | None:
"""Best available "commit the index reflects" for a repo.
@@ -336,6 +384,12 @@ def build_meta(
serves) to scope ``stale_warning`` to actually-affected content — see
:func:`freshness_from_repo`.
+ ``index_scope`` rides on every response, so it carries the compact
+ projection: the run mode, the provenance, the git tier, one word for
+ whether the index is whole, and a fingerprint identifying the canonical
+ object. See :func:`build_meta_with_full_scope` for the calls that are
+ worth the whole thing.
+
Stable shape:
{
"timing_ms": float, # tool wall-time (omitted if None)
@@ -356,7 +410,7 @@ def build_meta(
out["cached"] = True
if repository is not None:
out.update(freshness_from_repo(repository, targets=targets))
- scope = read_index_scope(getattr(repository, "local_path", None))
+ scope = index_scope_for_response(getattr(repository, "local_path", None))
if scope is not None:
out["index_scope"] = scope
out.update(_embedder_meta())
@@ -366,6 +420,28 @@ def build_meta(
return out
+def build_meta_with_full_scope(**kwargs: Any) -> dict[str, Any]:
+ """:func:`build_meta` for an orientation call: the whole ``index_scope``.
+
+ A separate function rather than a parameter on ``build_meta``, which has
+ 68 call sites that all want the digest and one that wants this. A knob
+ every caller must read past to learn it does not apply to them belongs
+ beside the one caller it does.
+ """
+ meta = build_meta(**kwargs)
+ repository = kwargs.get("repository")
+ if repository is not None:
+ scope = read_index_scope(getattr(repository, "local_path", None))
+ if scope is not None:
+ # The fingerprint is what makes a held copy checkable against a
+ # later digest, so the copy being held has to carry it too.
+ meta["index_scope"] = {
+ **scope,
+ "fingerprint": index_scope_fingerprint(scope),
+ }
+ return meta
+
+
def persisted_analysis_meta(
timestamp: str | None,
commits: dict[str, str] | None = None,
diff --git a/packages/server/src/repowise/server/mcp_server/tool_overview.py b/packages/server/src/repowise/server/mcp_server/tool_overview.py
index 36cbf89f3..3a425950d 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_overview.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_overview.py
@@ -62,6 +62,9 @@ from repowise.server.mcp_server._helpers import (
is_excluded,
)
from repowise.server.mcp_server._meta import build_meta as _build_meta
+from repowise.server.mcp_server._meta import (
+ build_meta_with_full_scope as _build_meta_with_full_scope,
+)
from repowise.server.mcp_server._tool_selection import registry_tool_rows, selected_tool_names
# Orientation, not a directory listing — the top few modules are enough to
@@ -1109,7 +1112,10 @@ async def get_overview(repo: str | None = None, include: list[str] | None = None
result["tool_surface"] = _tool_surface_guide(is_workspace=_state._registry is not None)
- result["_meta"] = _build_meta(repository=repository)
+ # The orientation call, and the one place the whole scope is worth its
+ # bytes: it is made once per session and it is what the compact
+ # projection on every other response points at.
+ result["_meta"] = _build_meta_with_full_scope(repository=repository)
collector.attach(result)
return result
diff --git a/tests/unit/server/mcp/test_index_scope_projection.py b/tests/unit/server/mcp/test_index_scope_projection.py
new file mode 100644
index 000000000..7057ccd17
--- /dev/null
+++ b/tests/unit/server/mcp/test_index_scope_projection.py
@@ -0,0 +1,320 @@
+"""What an ordinary response says about the index's scope, and what it costs.
+
+The canonical scope answers a question almost no call asks, and it was riding
+on every response: about 900 characters, roughly a third of a small
+``get_symbol`` reply. The digest keeps the part that changes how an answer
+should be read and names where the rest lives.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from repowise.core.index_scope import (
+ INDEX_SCOPE_ENV,
+ compact_index_scope,
+ index_scope_fingerprint,
+ resolve_index_scope,
+)
+from repowise.server.mcp_server import _meta
+
+
+class _Repo:
+ def __init__(self, path: Path) -> None:
+ self.local_path = str(path)
+ self.head_commit = "abc123def456"
+ self.indexed_at = "2026-09-16T00:00:00+00:00"
+
+
+def _write_state(path: Path, state: dict[str, Any]) -> _Repo:
+ repowise_dir = path / ".repowise"
+ repowise_dir.mkdir(exist_ok=True)
+ (repowise_dir / "state.json").write_text(json.dumps(state), encoding="utf-8")
+ return _Repo(path)
+
+
+_FULL_STATE: dict[str, Any] = {
+ "run_mode": "standard",
+ "git_tier": "full",
+ "docs_mode": "llm",
+ "index_scope": {
+ "git_commit_cap": 500,
+ "file_pages": {"eligible": 2499, "generated": 2247, "omitted": 252},
+ "provider": {"name": "openai", "model": "a-model", "embedder": "openai"},
+ "search": {"full_text": "available", "semantic": "available"},
+ },
+ "git_history_coverage": {"eligible_files": 4024, "retained_commits": 15360},
+ "full_upgrade": {"status": "complete", "completed_stages": ["generation"]},
+}
+
+
[email protected](autouse=True)
+def _no_env(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.delenv(INDEX_SCOPE_ENV, raising=False)
+ monkeypatch.setattr(_meta, "read_live_head", lambda _p: None)
+
+
+def _chars(value: Any) -> int:
+ return len(json.dumps(value, separators=(",", ":"), default=str))
+
+
+_WHOLE_PAGES = {"eligible": 10, "generated": 10, "omitted": 0}
+
+
+def _scope_with(**overrides: Any) -> dict[str, Any]:
+ """A canonical scope from the full fixture, with sub-blocks replaced."""
+ return resolve_index_scope(
+ {**_FULL_STATE, "index_scope": {**_FULL_STATE["index_scope"], **overrides}}
+ )
+
+
+def _status_of(**overrides: Any) -> str:
+ return compact_index_scope(_scope_with(**overrides))["status"]
+
+
+# --- the projection itself -------------------------------------------------
+
+
+def test_the_digest_keeps_what_changes_how_an_answer_reads() -> None:
+ scope = resolve_index_scope(_FULL_STATE)
+ compact = compact_index_scope(scope)
+
+ assert compact is not None
+ assert compact["run_mode"] == "standard"
+ assert compact["content_provenance"] == "model"
+ assert compact["git_tier"] == "full"
+ assert compact["projection"] == "compact"
+ # Says outright that it is not the whole thing, and where the rest is.
+ assert compact["full"] == "get_overview()"
+
+
+def test_the_digest_is_a_fraction_of_the_scope_it_stands_for() -> None:
+ scope = resolve_index_scope(_FULL_STATE)
+
+ assert _chars(compact_index_scope(scope)) < _chars(scope) * 0.5
+
+
+def test_nothing_to_project_stays_nothing() -> None:
+ assert compact_index_scope(None) is None
+
+
+ ("state", "expected"),
+ [
+ ({**_FULL_STATE, "full_upgrade": {"status": "running"}}, "upgrading"),
+ ({**_FULL_STATE, "full_upgrade": {"status": "resumable"}}, "upgrading"),
+ ({**_FULL_STATE, "full_upgrade": {"status": "failed"}}, "degraded"),
+ ({**_FULL_STATE, "degraded": ["health"]}, "degraded"),
+ (_FULL_STATE, "partial"),
+ ],
+)
+def test_status_names_the_condition_that_explains_the_rest(
+ state: dict[str, Any], expected: str
+) -> None:
+ assert compact_index_scope(resolve_index_scope(state))["status"] == expected
+
+
+def test_omitted_pages_are_never_reported_as_complete() -> None:
+ """A partial index must not read as a whole one to save a word."""
+ scope = resolve_index_scope(_FULL_STATE)
+ assert scope["file_pages"]["omitted"] == 252
+
+ assert compact_index_scope(scope)["status"] != "complete"
+
+
+def test_a_whole_index_says_so() -> None:
+ assert _status_of(file_pages=_WHOLE_PAGES) == "complete"
+
+
+# --- the fingerprint -------------------------------------------------------
+
+
+def test_the_same_scope_fingerprints_the_same() -> None:
+ scope = resolve_index_scope(_FULL_STATE)
+
+ assert index_scope_fingerprint(scope) == index_scope_fingerprint(
+ resolve_index_scope(_FULL_STATE)
+ )
+
+
+def test_a_changed_scope_fingerprints_differently() -> None:
+ """The point of carrying it: a held copy can be checked without resending."""
+ other = resolve_index_scope({**_FULL_STATE, "run_mode": "fast"})
+
+ assert index_scope_fingerprint(resolve_index_scope(_FULL_STATE)) != (
+ index_scope_fingerprint(other)
+ )
+
+
+# --- what a response carries -----------------------------------------------
+
+
+def test_a_routine_response_carries_the_digest(tmp_path: Path) -> None:
+ out = _meta.build_meta(repository=_write_state(tmp_path, _FULL_STATE))
+
+ assert out["index_scope"]["projection"] == "compact"
+ assert "git_history_coverage" not in out["index_scope"]
+
+
+def test_an_orientation_call_carries_the_whole_scope(tmp_path: Path) -> None:
+ out = _meta.build_meta_with_full_scope(
+ repository=_write_state(tmp_path, _FULL_STATE)
+ )
+
+ assert out["index_scope"]["git_history_coverage"]["eligible_files"] == 4024
+ assert "projection" not in out["index_scope"]
+
+
+def test_the_environment_restores_the_old_shape_everywhere(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """The compatibility window for a reader that parses the whole object."""
+ monkeypatch.setenv(INDEX_SCOPE_ENV, "full")
+
+ out = _meta.build_meta(repository=_write_state(tmp_path, _FULL_STATE))
+
+ assert out["index_scope"]["file_pages"]["eligible"] == 2499
+ assert "projection" not in out["index_scope"]
+
+
+def test_the_digest_stays_under_a_fixed_ceiling(tmp_path: Path) -> None:
+ """The measured regression was ~900 characters on every response.
+
+ A fixed ceiling rather than a ratio against the canonical object: tying
+ the digest's budget to the size of the thing it replaced would tighten
+ this bar every time a diagnostic is added to that object, and fail a test
+ about the digest for a reason that has nothing to do with it.
+ """
+ compact = _meta.build_meta(repository=_write_state(tmp_path, _FULL_STATE))
+
+ assert _chars(compact["index_scope"]) <= 300
+
+
+def test_a_repo_with_no_state_still_carries_no_scope(tmp_path: Path) -> None:
+ out = _meta.build_meta(repository=_Repo(tmp_path))
+
+ assert "index_scope" not in out
+
+
+# --- absence of evidence is not completeness -------------------------------
+
+
+def test_an_index_that_never_recorded_its_coverage_says_unknown() -> None:
+ """The invariant: a missing result is never reported as a clean result.
+
+ Every field the fold reads projects as ``unknown``/``None`` for a legacy
+ index, and reading that as "nothing is wrong" would launder silence into
+ a claim of completeness.
+ """
+ assert compact_index_scope(resolve_index_scope({}))["status"] == "unknown"
+
+
+def test_an_index_with_no_scope_key_says_unknown() -> None:
+ state = {"run_mode": "standard", "git_tier": "full", "docs_mode": "llm"}
+
+ assert compact_index_scope(resolve_index_scope(state))["status"] == "unknown"
+
+
+def _legs(**override: str) -> dict[str, str]:
+ return {"full_text": "available", "semantic": "available", **override}
+
+
[email protected]("leg", ["full_text", "semantic"])
+def test_an_unavailable_search_leg_is_degraded(leg: str) -> None:
+ assert _status_of(search=_legs(**{leg: "unavailable"})) == "degraded"
+
+
[email protected]("leg", ["full_text", "semantic"])
+def test_a_pending_search_leg_is_partial(leg: str) -> None:
+ """Pending means not usable yet — smaller than failed, larger than fine."""
+ status = _status_of(file_pages=_WHOLE_PAGES, search=_legs(**{leg: "pending"}))
+
+ assert status == "partial"
+
+
+def test_skipped_analysis_is_partial() -> None:
+ status = _status_of(
+ file_pages=_WHOLE_PAGES, analysis={"skipped": ["performance"]}
+ )
+
+ assert status == "partial"
+
+
+def test_a_degraded_index_names_what_degraded() -> None:
+ """"health failed" and "the graph failed" are not the same warning."""
+ state = {**_FULL_STATE, "degraded": ["health"]}
+
+ compact = compact_index_scope(resolve_index_scope(state))
+
+ assert compact["status"] == "degraded"
+ assert compact["degraded_analyses"] == ["health"]
+
+
+def test_a_sound_index_carries_no_degraded_names() -> None:
+ assert "degraded_analyses" not in compact_index_scope(
+ resolve_index_scope(_FULL_STATE)
+ )
+
+
+# --- the fingerprint has to be on both shapes ------------------------------
+
+
+def test_the_held_copy_carries_the_fingerprint_too(tmp_path: Path) -> None:
+ """Checking a held copy needs the fingerprint on the copy, not only the
+ digest that would be compared against it."""
+ repository = _write_state(tmp_path, _FULL_STATE)
+
+ compact = _meta.build_meta(repository=repository)["index_scope"]
+ full = _meta.build_meta_with_full_scope(repository=repository)["index_scope"]
+
+ assert full["fingerprint"] == compact["fingerprint"]
+
+
+def test_the_fingerprint_refuses_what_it_cannot_canonicalise() -> None:
+ """A silent str() fallback would churn the digest every process."""
+ with pytest.raises(TypeError):
+ index_scope_fingerprint({"version": 1, "odd": object()})
+
+
+# --- where the rest actually lives -----------------------------------------
+
+
+def test_the_pointer_names_the_repo_argument_in_workspace_mode(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """get_overview() with no repo returns the listing, which carries no scope."""
+ from repowise.server.mcp_server import _state
+
+ monkeypatch.setattr(_state, "_registry", object(), raising=False)
+
+ out = _meta.build_meta(repository=_write_state(tmp_path, _FULL_STATE))
+
+ assert out["index_scope"]["full"] == "get_overview(repo=...)"
+
+
+def test_the_pointer_is_a_plain_call_for_a_single_repo(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ from repowise.server.mcp_server import _state
+
+ monkeypatch.setattr(_state, "_registry", None, raising=False)
+
+ out = _meta.build_meta(repository=_write_state(tmp_path, _FULL_STATE))
+
+ assert out["index_scope"]["full"] == "get_overview()"
+
+
+def test_the_window_opens_without_a_restart(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """A client spawns this server; it cannot be told to start again."""
+ repository = _write_state(tmp_path, _FULL_STATE)
+ assert _meta.build_meta(repository=repository)["index_scope"]["projection"]
+
+ monkeypatch.setenv(INDEX_SCOPE_ENV, "full")
+
+ assert "projection" not in _meta.build_meta(repository=repository)["index_scope"]
diff --git a/tests/unit/server/mcp/test_meta_freshness.py b/tests/unit/server/mcp/test_meta_freshness.py
index be23f7c8a..10b46333d 100644
--- a/tests/unit/server/mcp/test_meta_freshness.py
+++ b/tests/unit/server/mcp/test_meta_freshness.py
@@ -73,10 +73,16 @@ def test_build_meta_exposes_the_persisted_index_scope(tmp_path, monkeypatch):
monkeypatch.setattr(_meta, "read_live_head", lambda p: None)
out = _meta.build_meta(repository=_repo(tmp_path))
+ whole = _meta.build_meta_with_full_scope(repository=_repo(tmp_path))
+ # An ordinary response carries the digest; what it says about the run is
+ # the same, and the diagnostics it leaves out are one get_overview away.
assert out["index_scope"]["run_mode"] == "fast"
assert out["index_scope"]["content_provenance"] == "none"
- assert out["index_scope"]["git_history_coverage"] is None
+ assert out["index_scope"]["projection"] == "compact"
+ assert whole["index_scope"]["run_mode"] == "fast"
+ assert whole["index_scope"]["content_provenance"] == "none"
+ assert whole["index_scope"]["git_history_coverage"] is None
def test_served_target_changed_warns(tmp_path, monkeypatch):