Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
perf(mcp): stop returning payload the caller already has (#1426)
Raghav Chamadiyae9ec97b07010
diff --git a/docs/reference/CLI_REFERENCE.md b/docs/reference/CLI_REFERENCE.mdindex 5124ea512..571040157 100644--- a/docs/reference/CLI_REFERENCE.md+++ b/docs/reference/CLI_REFERENCE.md@@ -497,11 +497,14 @@ call.```bashrepowise context src/api/routes.py src/api/auth.pyrepowise context src/api/routes.py::login --include callers --include metrics-repowise context src/api/routes.py --full # includes the skeleton source+repowise context src/api/routes.py --include skeleton # + the file's source```-The skeleton's *text* is the bulk of the underlying payload, so the default-reports its size and coverage and `--full` carries the source.+**No source bytes by default.** A card is relationships and risk signals:+title, summary, signatures with line numbers, hotspot, fix history. Pass+`--include skeleton` for the whole file body-elided and line-verified in one+call, or just read the file. `--full` returns the raw tool dict, which carries+a skeleton only when one was asked for.---diff --git a/packages/cli/src/repowise/cli/commands/context_cmd.py b/packages/cli/src/repowise/cli/commands/context_cmd.pyindex 4fda37ee0..e5ca151b6 100644--- a/packages/cli/src/repowise/cli/commands/context_cmd.py+++ b/packages/cli/src/repowise/cli/commands/context_cmd.py@@ -41,7 +41,7 @@ _REPLACED_KEYS = frozenset(# Folded into flatter keys."architectural_layer","freshness",- # Replaced by its shape, without its ~10K-char text.+ # Placed by hand below, whole: opt-in, so it was asked for."skeleton",# A breadcrumb to the wiki page the card came from, not a signal."parent_page",@@ -103,18 +103,13 @@ def _project_one(card: dict) -> dict:out[key] = valueskeleton = card.get("skeleton") or {}if skeleton:- # The skeleton *text* is the bulk of get_context's payload — 10K chars- # for one file — and it is source a caller can also get from `symbol`- # or a plain Read. The card keeps its shape and size so a caller can- # decide whether to pay for it; --full carries the text.- out["skeleton"] = {- "mode": skeleton.get("mode", ""),- "tokens": skeleton.get("tokens"),- "full_tokens": skeleton.get("full_tokens"),- "pct_of_full": skeleton.get("pct_of_full"),- "verified": skeleton.get("verified"),- "bodies_kept": skeleton.get("bodies_kept") or [],- }+ # The skeleton is opt-in on the tool now (``--include skeleton``), so a+ # card that carries one carries it because this caller asked by name.+ # Trimming its ``text`` away here would make the flag inert — the+ # failure mode the ``--include`` passthrough above exists to avoid — so+ # the block passes through whole. It is still summarised rather than+ # printed on the table path.+ out["skeleton"] = skeletonreturn out@@ -127,16 +122,13 @@ def project(payload: dict, targets: tuple[str, ...]) -> dict:kept target, type, docs.title -> title,docs.summary -> summary,architectural_layer.name -> layer,- freshness.is_stale -> stale, the skeleton's- shape without its ``text``, and **every other+ freshness.is_stale -> stale, and **every otherkey the card carries** — hotspot, fix_history,- episodes, and each ``--include`` block under- its own name- dropped skeleton.text (~10K chars per file, the bulk- of the payload), skeleton.opt_out_hint /- auto, parent_page,- freshness.confidence_score, ``_meta`` minus- its freshness keys+ episodes, the skeleton when ``--include+ skeleton`` asked for one, and each other+ ``--include`` block under its own name+ dropped parent_page, freshness.confidence_score,+ ``_meta`` minus its freshness keys================== ===========================================A target the tool could not resolve gets a card carrying only ``error``,@@ -199,8 +191,8 @@ def context_command(TARGETS are file paths, module paths, or "path/to/file.py::Symbol" ids.Batch them in one call. Relationships and risk signals, not source bytes:- pass --full for the verified skeleton, or use 'repowise symbol' for one- body.+ pass --include skeleton for the whole file body-elided and line-verified,+ or just read the file."""fmt = _ta.resolve_format_for(fmt, full)repo_path = _ta.resolve_indexed_repo(@@ -286,11 +278,14 @@ def _render(projected: dict) -> None:table.add_row("Signals", ", ".join(signals))skeleton = card.get("skeleton") or {}if skeleton:+ # Summarised, never printed: the text is the reason the caller+ # passed --include skeleton, and a terminal table is not where a+ # few thousand lines of source belong. --format json carries it.table.add_row("Skeleton",f"{skeleton.get('mode', '?')}, {skeleton.get('tokens', '?')} of "f"{skeleton.get('full_tokens', '?')} tokens "- f"({skeleton.get('pct_of_full', '?')}% of full) — pass --full for the text",+ f"({skeleton.get('pct_of_full', '?')}% of full) — --format json for the text",)if card.get("decision_records"):table.add_row(diff --git a/packages/core/src/repowise/core/generation/editor_files/tool_table.py b/packages/core/src/repowise/core/generation/editor_files/tool_table.pyindex 3f57b3a59..49c6242bf 100644--- a/packages/core/src/repowise/core/generation/editor_files/tool_table.py+++ b/packages/core/src/repowise/core/generation/editor_files/tool_table.py@@ -40,9 +40,9 @@ TOOL_TABLE_ROWS: dict[str, tuple[str, str]] = {),"get_context": ("get_context(targets=[...])",- "Triage card for files/modules/symbols, serving a `verified` skeleton for "- 'file targets. Batch targets; `include=["callers"|"callees"|"decisions"|'- '"metrics"]` for depth.',+ "Triage card for files/modules/symbols: docs, signatures, hotspot, fix "+ 'history. No source bytes — `include=["skeleton"]` for the whole file '+ 'verified, `["callers"|"decisions"]` for depth. Batch targets.',),"get_symbol": ("get_symbol(id)",diff --git a/packages/server/src/repowise/server/mcp_server/_budget/budgeter.py b/packages/server/src/repowise/server/mcp_server/_budget/budgeter.pyindex a4325c579..6f6e0438b 100644--- a/packages/server/src/repowise/server/mcp_server/_budget/budgeter.py+++ b/packages/server/src/repowise/server/mcp_server/_budget/budgeter.py@@ -215,6 +215,15 @@ def truncate_to_budget("dropped_symbol_counts": {k: len(v) for k, v in result["dropped_symbols"].items()},},)+ else:+ # Nothing was dropped, so say nothing. ``truncated: false`` ++ # ``dropped_targets: []`` + ``dropped_symbols: {}`` is 60 characters of+ # "nothing happened" on every untruncated response — and every response+ # is untruncated in the common case. Absent reads the same as empty to+ # a ``.get()``, which is how both projections already test them.+ for key in ("truncated", "dropped_targets", "dropped_symbols"):+ if not result.get(key):+ result.pop(key, None)return resultdiff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/answer.py b/packages/server/src/repowise/server/mcp_server/tool_answer/answer.pyindex 1bd2e96c1..efffe9ab9 100644--- a/packages/server/src/repowise/server/mcp_server/tool_answer/answer.py+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/answer.py@@ -145,6 +145,7 @@ from repowise.server.mcp_server.tool_answer.episodes import (attach_episode as _attach_episode,)from repowise.server.mcp_server.tool_answer.retrieval import (+ _CANDIDATE_LIMIT,_apply_domain_penalty,_attach_page_excerpts,_candidate_justification,@@ -401,7 +402,10 @@ def _build_best_guesses(hits: list[dict]) -> list[dict]:"file": h.get("target_path"),"why_relevant": _candidate_justification(h),"score": round(h.get("score", 0.0), 3),- "domain_penalty": h.get("_domain_penalty"),+ # Absent rather than null. It was `null` in all six wire samples+ # measured 2026-08-11 — a penalty applies to a minority of hits, so+ # the common row paid 22 characters to say nothing happened.+ **({"domain_penalty": h["_domain_penalty"]} if h.get("_domain_penalty") else {}),**({"excerpt": h["excerpt"]} if h.get("excerpt") else {}),}for h in hits[:_GATED_RETURN_HITS]@@ -409,6 +413,67 @@ def _build_best_guesses(hits: list[dict]) -> list[dict]:]+def _trim_served_payload(payload: dict) -> dict:+ """Every size cut that runs on the way OUT, on both the fresh and cache paths.++ Serve-time rather than build-time, and that is the whole point. A cut+ applied where the payload is assembled reaches only fresh answers: a cache+ row written by an older build keeps the old shape until+ ``_ANSWER_SCHEMA_VERSION`` moves, and bumping that invalidates every user's+ answer cache — re-synthesis, i.e. real provider spend — to change the size+ of a block. Measured: after capping ``candidates`` at build time only, a+ re-measured ``get_answer`` came back byte-identical, because the tree's+ cache answered. Trimming on the way out fixes old and new rows alike and+ costs nobody a re-synthesis.++ Anything that only REMOVES redundancy belongs here. Anything that changes+ what an answer says does not, and still owes a schema bump.+ """+ _cap_candidates(payload)+ _drop_duplicated_guess_excerpts(payload)+ return payload+++def _cap_candidates(payload: dict) -> dict:+ """Hold ``candidates`` to :data:`_CANDIDATE_LIMIT` rows on the way out."""+ candidates = payload.get("candidates")+ if isinstance(candidates, list) and len(candidates) > _CANDIDATE_LIMIT:+ payload["candidates"] = candidates[:_CANDIDATE_LIMIT]+ return payload+++def _drop_duplicated_guess_excerpts(payload: dict) -> dict:+ """Drop ``best_guesses[].excerpt`` where ``retrieval[]`` already carries it.++ Both blocks slice the same 1,500-character page excerpt for the same file,+ and when both are present the guess copy is byte-for-byte redundant —+ measured at 4,714 characters, 21.3% of one low-confidence payload, 3 of 3+ guesses duplicated.++ **Conditional, and the condition matters.** ``retrieval`` is+ confidence-gated and shrinks to nothing as the prose gets more+ trustworthy; the legacy abstain path ships ``retrieval: []`` outright. On+ those responses the guess excerpt is the only content in the payload, not a+ duplicate of anything, and a sample measured here carried 4,667 characters+ of it. So the drop is keyed on the duplicate actually being present, which+ makes it lossless rather than merely cheap — and keeps every ``excerpt``+ mentioned by ``note`` / ``next_action_hint`` on the paths that mention it.+ """+ guesses = payload.get("best_guesses")+ if not guesses:+ return payload+ # Substring, not equality: the two blocks cut their slabs independently and+ # the retrieval one is the longer of the two where they differ.+ carried = [r["excerpt"] for r in (payload.get("retrieval") or []) if r.get("excerpt")]+ if not carried:+ return payload+ for guess in guesses:+ excerpt = guess.get("excerpt")+ if excerpt and any(excerpt in c for c in carried):+ del guess["excerpt"]+ return payload++def _json_default(obj):"""Serialize the non-JSON types retrieval hits carry (``_sources`` sets).@@ -890,6 +955,7 @@ async def get_answer(targets=[p for p in cached_paths if isinstance(p, str) and p],)_apply_lean_high(payload, question)+ _trim_served_payload(payload)# Serve-time, on this path as well as the fresh one: the# episode is read on every call and never cached into an# answer, so a disagreement cannot be frozen into a row and@@ -1895,6 +1961,10 @@ async def get_answer(if degraded := _degraded_legs(_retrieval_legs()):payload["_meta"]["retrieval_degraded"] = degraded_apply_lean_high(payload, question)+ # After the cache write above and after lean-high (which can remove+ # ``best_guesses`` outright), so the cut sees the finished payload and the+ # cached row keeps the shape its schema version promises.+ _trim_served_payload(payload)# After the cache write above, deliberately. ``cache_payload`` is a shallow# copy taken before this point, so the episode reaches the caller and never# the cache row — which is why adding it needs no _ANSWER_SCHEMA_VERSIONdiff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/retrieval.py b/packages/server/src/repowise/server/mcp_server/tool_answer/retrieval.pyindex a8115aaf8..396f445a4 100644--- a/packages/server/src/repowise/server/mcp_server/tool_answer/retrieval.py+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/retrieval.py@@ -34,10 +34,22 @@ from repowise.server.mcp_server.tool_answer.config import (_log = logging.getLogger("repowise.mcp.answer")-# How many files ``candidates`` names. Twenty path lines cost roughly 800-# characters against the ~10k a get_answer response already spends, so the-# block makes the tool *more* token-efficient per candidate offered, not less.-_CANDIDATE_LIMIT = 20+# How many files ``candidates`` names.+#+# Was 20, on the estimate that "twenty path lines cost roughly 800 characters+# against the ~10k a get_answer response already spends". Measured on the wire+# 2026-08-11 the block is **3,107-3,279 characters, up to 39.9% of a+# get_answer payload** — four times the estimate, because ``defines`` and the+# paths themselves are both longer than a bare path line. That estimate was+# also made before ``defines`` existed.+#+# Five, not zero. Rows 6-20 appear in no other block, but nor are rows 1-5+# redundant: on the repowise samples ``candidates`` is the only block naming+# files outside the top-two ``citations``, and dropping it whole (which the+# CLI projection does) pushes the agent into a Grep that costs more than the+# rows saved. The head keeps the ``defines`` budget, so the navigational value+# per character goes up.+_CANDIDATE_LIMIT = 5def serialize_candidates(hits: list[dict], *, limit: int = _CANDIDATE_LIMIT) -> list[dict]:diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/context.py b/packages/server/src/repowise/server/mcp_server/tool_context/context.pyindex b8bed5d39..b17e30e04 100644--- a/packages/server/src/repowise/server/mcp_server/tool_context/context.py+++ b/packages/server/src/repowise/server/mcp_server/tool_context/context.py@@ -2,10 +2,12 @@Workhorse for "what is this and what touches it" questions. Returns a triagecard by default (title, summary, signatures, hotspot bit, top callers, pointers-to risk / why / symbol). NOT a source-body tool — for raw bytes call-``get_symbol("path::Name")`` instead. The split keeps the cached prompt prefix-small on multi-turn agent sessions: ``get_context`` stays under ~2k tokens for-common targets, while ``get_symbol`` returns bounded bytes for one symbol.+to risk / why / symbol). **NOT a source-body tool.** For source, ask for it in+one call — ``include=["skeleton"]`` returns the whole file body-elided and+line-verified — or just Read the file. Reaching for ``get_symbol`` once per+signature in the card is the expensive path and the card does not recommend it.+The split keeps the cached prompt prefix small on multi-turn agent sessions:+``get_context`` stays under ~2k tokens for common targets.Optional ``include`` parameter widens the response:- include=["full_doc"] → full wiki markdown content@@ -55,18 +57,16 @@ async def get_context() -> dict:"""Triage card for files / modules / symbols — relationships, not source bytes.- Returns title, summary, signatures, hotspot bit, decision_record titles,- and symbol_ids to pipe into get_symbol (cheaper than Read for bodies).- fix_history appears only on files with counted bug fixes (count, age,- bug_magnet); hotspot is churn. Either one is a cue to call get_risk.- episodes counts the dated records bound to a target — what happened here- and why — and appears only when there is at least one; get_why serves the- bodies. A symbol target is counted as its file, and a module aggregates- everything beneath it.- Batch targets in one call. File targets above ~80 lines default to a- skeleton (every signature + top-PageRank bodies, with a verified flag —- a fraction of Read cost); ``mostly_full`` marks files where a direct- Read costs little more.+ Returns title, summary, signatures with line numbers, hotspot bit, and+ decision_record titles. fix_history appears only on files with counted bug+ fixes (count, age, bug_magnet); hotspot is churn. Either one is a cue to+ call get_risk. episodes counts the dated records bound to a target — what+ happened here and why — and appears only when there is at least one;+ get_why serves the bodies. A symbol target is counted as its file, and a+ module aggregates everything beneath it.+ Batch targets in one call. No source bytes by default: pass+ include=["skeleton"] for the whole file body-elided and line-verified in+ ONE call, or Read it. Do not call get_symbol per signature.Args:targets: file paths, module paths, or "path::Symbol" ids.diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/targets.py b/packages/server/src/repowise/server/mcp_server/tool_context/targets.pyindex 3bbaeb254..83db341db 100644--- a/packages/server/src/repowise/server/mcp_server/tool_context/targets.py+++ b/packages/server/src/repowise/server/mcp_server/tool_context/targets.py@@ -50,13 +50,27 @@ from repowise.server.mcp_server.tool_context.kg import ()from repowise.server.mcp_server.tool_risk.assessment import fix_annotation-# Skeleton-by-default threshold for file targets. Measured on this repo: a-# 1,400-line file's default card costs ~2.5k tokens for 16 bare signatures,-# while the smart skeleton costs ~1.7k and carries every signature plus-# docstrings and the highest-PageRank bodies — strictly better per token.-# Small files skeletonize poorly (pct_of_full approaches a plain Read), so-# the card remains the default below this line count.-_SKELETON_AUTO_MIN_LINES = 80+# Skeleton-by-default is GONE; ``include=["skeleton"]`` still serves it in full.+#+# It was introduced on the claim that "a 1,400-line file's default card costs+# ~2.5k tokens for 16 bare signatures, while the smart skeleton costs ~1.7k" —+# strictly better per token. Re-measured 2026-08-11 on pinned Textualize/rich,+# whole serialised cards in characters, auto-upgrade suppressed for the+# comparison:+#+# target auto card symbol-list card skeleton text alone+# rich/ansi.py 6,585 2,171 5,295+# rich/text.py 13,365 8,562 12,247+# rich/color.py 8,591 4,818 7,405+#+# The symbol list is 1,321 chars on ansi.py where the skeleton text is 5,295.+# The original claim is inverted on this corpus, and the auto card was 73-91%+# source text on every sample — text the agent can Read for ~1/5 the marginal+# cost of a mid-session tool result, which is what the block's own+# ``mostly_full`` note ("a direct Read costs little more") was already saying+# at the agent's expense. So the default card is the symbol list again and the+# skeleton is opt-in. If you restore an auto-upgrade, re-run the measurement+# first: the numbers above are the bar.def _synthesize_structural_summary(file_path: str, classes: list[str], functions: list[str]) -> str:@@ -364,7 +378,6 @@ async def _resolve_one_target(}want_skeleton = bool(include and "skeleton" in include)- auto_skeleton = False# --- Docs ---# "full_doc" implies "docs" — entering the docs block whenever either is requested.@@ -389,24 +402,11 @@ async def _resolve_one_target(symbols = res.scalars().all()classes = [s.name for s in symbols if s.kind == "class"]functions = [s.name for s in symbols if s.kind in ("function", "method")]- # Skeleton-by-default: for file targets of meaningful size the- # smart skeleton dominates the bare signature list per token, so- # the default card upgrades itself. compact=False (the rich- # symbol card) and full_doc both opt out.- if not want_skeleton and compact and not want_full_doc:- total_loc = max((s.end_line or 0 for s in symbols), default=0)- if total_loc > _SKELETON_AUTO_MIN_LINES:- want_skeleton = auto_skeleton = True- # Explicitly requested skeleton suppresses the symbol list up- # front; the auto default still builds the card and only swaps- # it out once the skeleton actually resolved (see bottom), so a- # moved/unreadable source file degrades to the card, not to an- # error-only response.- if want_skeleton and not auto_skeleton:- # The skeleton block already renders every signature with- # line bounds — repeating the symbol list in docs would- # roughly double the response for zero information. Keep- # the cheap title/summary card only.+ if want_skeleton:+ # A requested skeleton suppresses the symbol list: it already+ # renders every signature with line bounds, so repeating the+ # list in docs would roughly double the response for zero+ # information. Keep the cheap title/summary card only.if not docs.get("summary"):docs["summary"] = _synthesize_structural_summary(target, classes, functions)elif compact:@@ -881,31 +881,10 @@ async def _resolve_one_target(if include and "health" in include:await _resolve_health(session, repository, target, target_type, result_data)- # --- Skeleton (distill) — explicit include or the file-target default ---+ # --- Skeleton (distill) — opt-in only, see the module note ---if want_skeleton:await _resolve_skeleton(session, repository, target, target_type, result_data, repo_root=repo_root)- skeleton = result_data.get("skeleton")- if auto_skeleton and isinstance(skeleton, dict):- if "error" in skeleton:- # Auto-upgrade failed (source moved/unreadable) — keep the- # symbol card the docs block already built and drop the- # failed block so the default response stays usable.- result_data.pop("skeleton", None)- else:- skeleton["auto"] = True- skeleton["opt_out_hint"] = (- "Skeleton is the default for file targets above "- f"{_SKELETON_AUTO_MIN_LINES} lines. Pass compact=False "- "for the symbol-list card instead."- )- docs_block = result_data.get("docs")- if isinstance(docs_block, dict):- # The skeleton renders every signature with line bounds —- # the symbol list would double the response for zero- # information.- docs_block.pop("symbols", None)- docs_block.pop("symbols_truncated", None)return result_datadiff --git a/packages/server/src/repowise/server/mcp_server/tool_overview.py b/packages/server/src/repowise/server/mcp_server/tool_overview.pyindex 0271e02a4..d575df859 100644--- a/packages/server/src/repowise/server/mcp_server/tool_overview.py+++ b/packages/server/src/repowise/server/mcp_server/tool_overview.py@@ -1027,9 +1027,14 @@ async def get_overview(repo: str | None = None, include: list[str] | None = Noneresult["tool_guide"] = {"first_call": "get_answer for any how/where/why question; trust ""confidence=high directly (it is content-grounded).",- "reading_code": "get_context skeleton (≈37% of a full Read) → "- "get_symbol for bodies (verified: true = no re-read needed). "- "Raw Read only for files marked mostly_full or unservable.",+ # NOT "get_context skeleton -> get_symbol for bodies". That routed+ # the agent into a per-signature walk, which is where three+ # quarters of every measured session's retrieval calls went, on the+ # one tool whose payload cannot be trimmed. get_context serves no+ # source by default now, so this names the two whole-file routes.+ "reading_code": 'get_context(include=["skeleton"]) for a whole file '+ "verified, or just Read it. get_symbol only for an id a response "+ "already gave you — never file-by-signature.","recipes": ["get_answer low confidence → Read best_guesses[0].file","get_context hotspot: true → get_risk before editing",diff --git a/packages/server/src/repowise/server/mcp_server/tool_risk/assessment.py b/packages/server/src/repowise/server/mcp_server/tool_risk/assessment.pyindex f58849526..4ff8a0e1e 100644--- a/packages/server/src/repowise/server/mcp_server/tool_risk/assessment.py+++ b/packages/server/src/repowise/server/mcp_server/tool_risk/assessment.py@@ -166,7 +166,13 @@ def _compute_impact_surface("is_entry_point": meta.is_entry_point if meta else False,})- ranked.sort(key=lambda x: -x["pagerank"])+ # Path breaks the tie, or the answer is not the same twice. ``visited`` is+ # a set, so ``ranked`` starts in hash order, and a stable sort keeps that+ # order wherever pagerank ties — which it does constantly, since most+ # dependents sit at 0.0. Two identical get_risk calls were returning+ # different "top 3 most critical modules" (measured: tests/test_progress.py+ # vs examples/fullscreen.py in the same slot, same tree, minutes apart).+ ranked.sort(key=lambda x: (-x["pagerank"], x["file_path"]))ranked = filter_dicts_by_key(ranked, "file_path", exclude_spec)return ranked[:3]diff --git a/packages/server/src/repowise/server/mcp_server/tool_search.py b/packages/server/src/repowise/server/mcp_server/tool_search.pyindex 44abe5aaa..973f320dd 100644--- a/packages/server/src/repowise/server/mcp_server/tool_search.py+++ b/packages/server/src/repowise/server/mcp_server/tool_search.py@@ -486,6 +486,33 @@ def _attach_paths(output: list[dict], page_info: dict) -> None:item["file"] = item["target_path"].split("::", 1)[0]+def _drop_derivable_page_ids(results: list[dict]) -> list[dict]:+ """Strip ``page_id`` from every result that can rebuild it, in place.++ A page id is ``compute_page_id(page_type, target_path)`` — literally+ ``f"{page_type}:{target_path}"`` (``core/generation/models.py``) — and both+ halves ship in the same row. So the field is 229-369 characters per+ response, 7.8-10.3% of the payload, restating two of its own siblings. It+ is ranking plumbing: every internal use above keys the fused dict on it,+ and none of that needs to reach the wire.++ Conditional rather than unconditional, and the condition is the derivation+ itself. ``_attach_paths`` writes ``target_path: ""`` for a hit whose Page+ row did not load, and a row like that cannot be rebuilt — so it keeps its+ id instead of losing one. The rule is "drop it only where it is provably+ redundant", which is also the check: if this ever stops firing, the+ invariant it rests on has changed.++ Consumers rebuild with the same expression; ``ui/src/chat/source-citations``+ does exactly that, and used to skip any row whose ``page_id`` was missing.+ """+ for item in results:+ derived = f"{item.get('page_type', '')}:{item.get('target_path', '')}"+ if item.get("page_id") == derived:+ item.pop("page_id", None)+ return results++async def _load_page_info(session, output: list[dict], *, with_git: bool = False) -> tuple[dict, set, dict]:@@ -712,6 +739,8 @@ async def _federated_search(# name files.if candidates := file_candidates(all_results, limit=limit):response["candidates"] = candidates+ # Last, so nothing above has to know the field is on its way out.+ _drop_derivable_page_ids(output)return response@@ -917,6 +946,8 @@ async def _structured_search()if grep_hint and not results:response["grep_hint"] = grep_hint+ # Last, so nothing above has to know the field is on its way out.+ _drop_derivable_page_ids(results)return response@@ -1044,4 +1075,6 @@ async def search_codebase(response["candidates"] = candidatesif grep_hint and not output:response["grep_hint"] = grep_hint+ # Last, so nothing above has to know the field is on its way out.+ _drop_derivable_page_ids(output)return responsediff --git a/packages/ui/src/chat/source-citations.tsx b/packages/ui/src/chat/source-citations.tsxindex d714472ba..7907c4e28 100644--- a/packages/ui/src/chat/source-citations.tsx+++ b/packages/ui/src/chat/source-citations.tsx@@ -35,7 +35,15 @@ export function extractSources(if (tc.name === "search_codebase") {const results = (result.results as Array<Record<string, unknown>>) ?? [];for (const r of results) {- const pageId = r.page_id as string;+ // `page_id` is `${page_type}:${target_path}`, and the tool now omits it+ // wherever those two rebuild it. Derive rather than skip: the previous+ // `const pageId = r.page_id` dropped the whole row — and its citation —+ // for any result without one. Same fallback the get_context branch uses.+ const pageType = r.page_type as string | undefined;+ const targetPath = r.target_path as string | undefined;+ const pageId =+ (r.page_id as string | undefined) ??+ (pageType && targetPath ? `${pageType}:${targetPath}` : "");if (!pageId || seen.has(pageId)) continue;seen.add(pageId);sources.push({diff --git a/tests/unit/cli/test_tool_adapter_commands.py b/tests/unit/cli/test_tool_adapter_commands.pyindex 5b375e6a8..c2d7e4f8f 100644--- a/tests/unit/cli/test_tool_adapter_commands.py+++ b/tests/unit/cli/test_tool_adapter_commands.py@@ -325,7 +325,16 @@ def test_ask_projection_is_a_fraction_of_the_payload():assert trimmed * 3 < full, f"trim saved too little: {trimmed} of {full}"-def test_context_projection_keeps_the_skeleton_shape_without_its_text():+def test_context_projection_passes_a_requested_skeleton_through_whole():+ """A skeleton in the card was asked for by name, so it survives the trim.++ This used to strip ``skeleton.text``, and that was right while the tool+ auto-upgraded every file target above 80 lines: the text was 73-91% of the+ payload and nobody had requested it. The tool no longer auto-upgrades, so+ the only way a skeleton reaches this function is ``--include skeleton``,+ and trimming its text back out would make that flag inert — the same+ failure the include passthrough two tests below exists to prevent.+ """out = project_context(CONTEXT_PAYLOAD, ("a.py",))card = out["targets"]["a.py"]assert card["title"] == "File: a.py"@@ -338,11 +347,8 @@ def test_context_projection_keeps_the_skeleton_shape_without_its_text():unknown = {"target": "a.py", "freshness": {"is_stale": None}}assert "stale" not in project_context({"targets": {"a.py": unknown}}, ("a.py",))["targets"]["a.py"]assert card["episodes"] == 4- assert card["skeleton"] == {- "mode": "smart", "tokens": 100, "full_tokens": 400,- "pct_of_full": 25.0, "verified": True, "bodies_kept": ["f"],- }- assert "z" * 100 not in json.dumps(out), "skeleton text survived the trim"+ assert card["skeleton"] == CONTEXT_PAYLOAD["targets"]["a.py"]["skeleton"]+ assert "z" * 100 in card["skeleton"]["text"], "the requested source went missing"assert "parent_page" not in carddiff --git a/tests/unit/server/mcp/test_answer_calibration.py b/tests/unit/server/mcp/test_answer_calibration.pyindex 1849b4437..ae24fdc3b 100644--- a/tests/unit/server/mcp/test_answer_calibration.py+++ b/tests/unit/server/mcp/test_answer_calibration.py@@ -1044,8 +1044,15 @@ async def test_non_dominant_best_guesses_carry_candidate_excerpts(setup_mcp, monA pointers-only reply makes the agent re-acquire all content natively(observed as an 8-15 call Grep/Read spree in agent transcripts), so the- best_guesses folded into a non-dominant reply carry the top candidates'- actual page content beside the synthesized prose.+ non-dominant reply ships the top candidates' actual page content beside+ the synthesized prose.++ **Once, not twice.** ``best_guesses`` and ``retrieval`` used to slice the+ same 1,500-character page excerpt for the same file — 21.3% of one measured+ payload, duplicated byte for byte — so the guess copy is dropped wherever+ ``retrieval`` already carries it. The content requirement above is+ unchanged and is what the second half of this test pins: the excerpt is+ still in the response, in exactly one place."""import repowise.server.mcp_server as mcp_modimport repowise.server.mcp_server.tool_answer.answer as answer_mod@@ -1083,7 +1090,13 @@ async def test_non_dominant_best_guesses_carry_candidate_excerpts(setup_mcp, monassert result["confidence"] == "medium" # non-dominant ceilingassert result["answer"]top = result["best_guesses"][0]- assert top["excerpt"].startswith("Page content for pkg/alpha/one.py")+ assert top["file"] == "pkg/alpha/one.py"+ assert top["why_relevant"]+ # The content is in the response exactly once: dropped from the guess+ # because retrieval carries the identical slab for the same file.+ assert "excerpt" not in top+ carried = [r.get("excerpt", "") for r in result["retrieval"]]+ assert any(e.startswith("Page content for pkg/alpha/one.py") for e in carried)# The reply names the ambiguity and points at best_guesses to verify.assert "best_guesses" in result["note"]assert "ambiguous" in result["note"]diff --git a/tests/unit/server/mcp/test_context.py b/tests/unit/server/mcp/test_context.pyindex 77bdd32f9..296124398 100644--- a/tests/unit/server/mcp/test_context.py+++ b/tests/unit/server/mcp/test_context.py@@ -330,9 +330,14 @@ def test_truncate_noop_when_under_budget():"_meta": {},}out = _truncate_to_budget(small)- assert out["truncated"] is False- assert out["dropped_targets"] == []- assert out["dropped_symbols"] == {}+ # Absent, not false. ``truncated: false`` plus two empty containers is 60+ # characters of "nothing happened" on every response that fits — which is+ # nearly all of them. Both projections read these with ``.get()``, so empty+ # and absent are the same answer to a consumer.+ assert not out.get("truncated")+ assert not out.get("dropped_targets")+ assert not out.get("dropped_symbols")+ assert "truncated" not in outassert "content_md" not in out["targets"]["a.py"]["docs"] # wasn't there anywaydiff --git a/tests/unit/server/mcp/test_context_skeleton.py b/tests/unit/server/mcp/test_context_skeleton.pyindex d92aea2d3..8fdf9cbaa 100644--- a/tests/unit/server/mcp/test_context_skeleton.py+++ b/tests/unit/server/mcp/test_context_skeleton.py@@ -151,28 +151,59 @@ async def test_skeleton_missing_source_file(setup_mcp, tmp_path, monkeypatch):@pytest.mark.asyncio-async def test_skeleton_is_default_for_large_file_targets(setup_mcp, tmp_path, monkeypatch):- # service.py spans 100 lines (> the 80-line threshold): the default card- # auto-upgrades to the skeleton and drops the redundant symbol list.+async def test_no_skeleton_without_an_explicit_include(setup_mcp, tmp_path, monkeypatch):+ """A file target serves the symbol card, never source bytes, unless asked.++ service.py spans 100 lines and used to auto-upgrade to a skeleton above an+ 80-line threshold, on the claim that the skeleton beat the bare signature+ list per token. Re-measured on pinned Textualize/rich the claim is+ inverted — rich/ansi.py's card is 2,171 characters against 6,585 with the+ auto skeleton, of which the skeleton text alone is 5,295 — so source is+ opt-in. See the note on the retired constant in ``tool_context/targets``.+ """from repowise.server.mcp_server import _state, get_context_write_source(tmp_path)monkeypatch.setattr(_state, "_repo_path", str(tmp_path))result = await get_context(["src/auth/service.py"])card = result["targets"]["src/auth/service.py"]- sk = card["skeleton"]- assert sk["auto"] is True- assert "compact=False" in sk["opt_out_hint"]- assert "class AuthService:" in sk["text"]- assert "symbols" not in card["docs"]- # Summary and freshness still ride along.+ assert "skeleton" not in card+ # The navigation the skeleton used to displace survives: names,+ # signatures, line numbers, and the cheap card around them.+ assert card["docs"]["symbols"]assert card["docs"].get("summary") is not Noneassert "freshness" in card+async def test_include_skeleton_still_serves_the_full_text(setup_mcp, tmp_path, monkeypatch):+ """The other direction: the opt-in path is untouched and carries the text."""+ from repowise.server.mcp_server import _state, get_context++ _write_source(tmp_path)+ monkeypatch.setattr(_state, "_repo_path", str(tmp_path))+ result = await get_context(["src/auth/service.py"], include=["skeleton"])+ card = result["targets"]["src/auth/service.py"]+ assert "class AuthService:" in card["skeleton"]["text"]+ assert card["skeleton"]["verified"] is True+++async def test_untruncated_response_omits_the_empty_truncation_keys(+ setup_mcp, tmp_path, monkeypatch+):+ """60 characters of "nothing happened", on every response that fits."""+ from repowise.server.mcp_server import _state, get_context++ monkeypatch.setattr(_state, "_repo_path", str(tmp_path))+ result = await get_context(["src/db/models.py"])+ assert not result.get("truncated")+ for key in ("truncated", "dropped_targets", "dropped_symbols"):+ assert key not in result, f"{key} shipped on an untruncated response"++@pytest.mark.asyncioasync def test_small_file_keeps_symbol_card(setup_mcp, tmp_path, monkeypatch):- # models.py's symbols end at line 30 — below the threshold, no skeleton.from repowise.server.mcp_server import _state, get_contextmonkeypatch.setattr(_state, "_repo_path", str(tmp_path))@@ -183,7 +214,7 @@ async def test_small_file_keeps_symbol_card(setup_mcp, tmp_path, monkeypatch):@pytest.mark.asyncio-async def test_compact_false_opts_out_of_auto_skeleton(setup_mcp, tmp_path, monkeypatch):+async def test_compact_false_still_serves_no_skeleton(setup_mcp, tmp_path, monkeypatch):from repowise.server.mcp_server import _state, get_context_write_source(tmp_path)@@ -195,11 +226,9 @@ async def test_compact_false_opts_out_of_auto_skeleton(setup_mcp, tmp_path, monk@pytest.mark.asyncio-async def test_auto_skeleton_falls_back_to_card_when_source_missing(- setup_mcp, tmp_path, monkeypatch-):- # Nothing on disk: the auto-upgrade must degrade to the symbol card, not- # to an error-only response (explicit include=["skeleton"] still errors).+async def test_default_card_survives_a_missing_source_file(setup_mcp, tmp_path, monkeypatch):+ # Nothing on disk. The default card never touches the source, so it is+ # unaffected; explicit include=["skeleton"] still errors (test above).from repowise.server.mcp_server import _state, get_contextmonkeypatch.setattr(_state, "_repo_path", str(tmp_path))diff --git a/tests/unit/server/mcp/test_payload_cuts.py b/tests/unit/server/mcp/test_payload_cuts.pynew file mode 100644index 000000000..5812714b3--- /dev/null+++ b/tests/unit/server/mcp/test_payload_cuts.py@@ -0,0 +1,205 @@+"""Payload cuts: each one is lossless, and each proof is the loss test.++A tool result is new text entering a long, already-cached conversation, so it+is billed at the cache-*write* rate — far above the rate at which the rest of+the prompt is re-read, and paid again for every result. A field the agent does+not act on is therefore not free; it is some of the most expensive text in the+session, and it costs more the later in a session it arrives.++Every test here pins the same shape: **the cut fires where the information is+redundant, and does NOT fire where it is the only copy.** A one-directional+test passes just as happily on a cut that silently ate the payload, which is+the failure mode each of these changes was designed around.+"""++from __future__ import annotations++from repowise.server.mcp_server._budget.budgeter import truncate_to_budget+from repowise.server.mcp_server.tool_answer.answer import (+ _build_best_guesses,+ _drop_duplicated_guess_excerpts,+ _trim_served_payload,+)+from repowise.server.mcp_server.tool_answer.retrieval import _CANDIDATE_LIMIT+from repowise.server.mcp_server.tool_search import _drop_derivable_page_ids++# ---------------------------------------------------------------------------+# search_codebase.results[].page_id — derivable from two of its own siblings+# ---------------------------------------------------------------------------+++def test_page_id_dropped_when_page_type_and_target_path_rebuild_it():+ results = [+ {+ "page_id": "file_page:rich/ansi.py",+ "page_type": "file_page",+ "target_path": "rich/ansi.py",+ "title": "ansi",+ }+ ]+ _drop_derivable_page_ids(results)+ assert "page_id" not in results[0]+ # Lossless: the consumer rebuilds it from what is still there.+ assert f"{results[0]['page_type']}:{results[0]['target_path']}" == "file_page:rich/ansi.py"+++def test_page_id_kept_when_it_cannot_be_rebuilt():+ """The other direction, and it is a real case, not a hypothetical.++ ``_attach_paths`` writes ``target_path: ""`` for a hit whose Page row did+ not load. Dropping the id there would lose the only handle the row has.+ """+ orphan = {"page_id": "file_page:rich/gone.py", "page_type": "file_page", "target_path": ""}+ renamed = {"page_id": "module_page:rich", "page_type": "file_page", "target_path": "rich"}+ _drop_derivable_page_ids([orphan, renamed])+ assert orphan["page_id"] == "file_page:rich/gone.py"+ assert renamed["page_id"] == "module_page:rich"+++def test_symbol_qualified_page_ids_still_rebuild():+ """A symbol_spotlight's target_path is ``file.py::Symbol`` — still derivable."""+ results = [+ {+ "page_id": "symbol_spotlight:rich/ansi.py::AnsiDecoder",+ "page_type": "symbol_spotlight",+ "target_path": "rich/ansi.py::AnsiDecoder",+ }+ ]+ _drop_derivable_page_ids(results)+ assert "page_id" not in results[0]+++# ---------------------------------------------------------------------------+# get_answer.best_guesses[].excerpt — the same slab retrieval[] already carries+# ---------------------------------------------------------------------------+++def test_guess_excerpt_dropped_when_retrieval_carries_it():+ payload = {+ "retrieval": [{"path": "a.py", "excerpt": "line one\nline two\nline three"}],+ "best_guesses": [{"file": "a.py", "score": 1.0, "excerpt": "line two\nline three"}],+ }+ _drop_duplicated_guess_excerpts(payload)+ assert "excerpt" not in payload["best_guesses"][0]+ # Still in the response, exactly once.+ assert "line two" in payload["retrieval"][0]["excerpt"]+++def test_guess_excerpt_kept_when_retrieval_is_empty():+ """The abstain path ships ``retrieval: []``, so the guess IS the content.++ A measured payload carried 4,667 characters of guess excerpt with an empty+ retrieval block. An unconditional drop would have deleted the answer.+ """+ payload = {+ "retrieval": [],+ "best_guesses": [{"file": "a.py", "score": 1.0, "excerpt": "the only copy"}],+ }+ _drop_duplicated_guess_excerpts(payload)+ assert payload["best_guesses"][0]["excerpt"] == "the only copy"+++def test_guess_excerpt_kept_when_retrieval_carries_a_different_file():+ payload = {+ "retrieval": [{"path": "b.py", "excerpt": "unrelated content"}],+ "best_guesses": [{"file": "a.py", "score": 1.0, "excerpt": "a.py content"}],+ }+ _drop_duplicated_guess_excerpts(payload)+ assert payload["best_guesses"][0]["excerpt"] == "a.py content"+++def test_drop_is_a_noop_without_best_guesses():+ payload = {"answer": "prose", "retrieval": [{"path": "a.py", "excerpt": "x"}]}+ assert _drop_duplicated_guess_excerpts(payload) == payload+++def test_null_domain_penalty_is_absent_not_null():+ plain = _build_best_guesses([{"target_path": "a.py", "score": 0.5}])+ assert "domain_penalty" not in plain[0]+ penalised = _build_best_guesses(+ [{"target_path": "a.py", "score": 0.5, "_domain_penalty": "ui question; cross-domain"}]+ )+ assert penalised[0]["domain_penalty"] == "ui question; cross-domain"+++# ---------------------------------------------------------------------------+# get_answer.candidates — 20 rows measured at up to 39.9% of the payload+# ---------------------------------------------------------------------------+++def test_candidate_limit_is_capped():+ # Not an equality assert on 5: the number is a judgement call and may move+ # again. What must not come back is the 20 that made this block 3,107-3,279+ # characters, up to 39.9% of a measured get_answer payload.+ assert _CANDIDATE_LIMIT <= 8+++def test_cached_payload_is_capped_on_the_way_out():+ """A cache row written at 20 rows must not serve 20 rows.++ Capping only where the block is built left the cap unreachable for every+ already-cached answer, and the tree used to re-measure this change came+ back byte-identical because of exactly that.+ """+ payload = {"candidates": [{"path": f"f{i}.py"} for i in range(20)]}+ _trim_served_payload(payload)+ assert len(payload["candidates"]) == _CANDIDATE_LIMIT+ # Head kept, so the best-ranked file is still the one described.+ assert payload["candidates"][0]["path"] == "f0.py"+++def test_trim_leaves_a_short_candidate_list_alone():+ payload = {"candidates": [{"path": "a.py"}, {"path": "b.py"}]}+ _trim_served_payload(payload)+ assert len(payload["candidates"]) == 2+++# ---------------------------------------------------------------------------+# The empty truncation keys+# ---------------------------------------------------------------------------+++def test_truncation_keys_absent_when_nothing_was_dropped():+ out = truncate_to_budget({"targets": {"a.py": {"target": "a.py"}}, "_meta": {}})+ for key in ("truncated", "dropped_targets", "dropped_symbols"):+ assert key not in out+++# ---------------------------------------------------------------------------+# get_risk.impact_surface — the same call must give the same answer+# ---------------------------------------------------------------------------+++def test_impact_surface_is_stable_across_equal_pagerank():+ """Ties broke on set-iteration order, so the "top 3" changed between calls.++ Found by a payload-parity run: two identical `get_risk` calls minutes apart+ on the same tree named `tests/test_progress.py` and `examples/fullscreen.py`+ in the same slot. `visited` is a set and the sort is stable, so wherever+ pagerank ties — which is most of the graph, at 0.0 — the order was whatever+ hashing produced that process.+ """+ from repowise.server.mcp_server.tool_risk.assessment import _compute_impact_surface++ deps = {"t.py": {"b.py", "a.py", "c.py", "d.py"}}+ first = _compute_impact_surface("t.py", deps, {})+ # Same inputs, a set built in a different insertion order.+ deps2 = {"t.py": {"d.py", "c.py", "a.py", "b.py"}}+ second = _compute_impact_surface("t.py", deps2, {})++ assert [r["file_path"] for r in first] == ["a.py", "b.py", "c.py"]+ assert first == second+++def test_truncation_keys_present_when_something_was_dropped():+ """The other direction. A silent drop is the one failure this must not have."""+ targets = {+ f"file_{i}.py": {+ "target": f"file_{i}.py",+ "docs": {"symbols": [{"name": f"sym_{n}", "doc": "x" * 400} for n in range(40)]},+ }+ for i in range(30)+ }+ out = truncate_to_budget({"targets": targets, "_meta": {}}, char_budget=2_000)+ assert out["truncated"] is True+ assert out["dropped_targets"] or out["dropped_symbols"]diff --git a/tests/unit/server/mcp/test_tombstones.py b/tests/unit/server/mcp/test_tombstones.pyindex 0deccc26b..be75c1d6e 100644--- a/tests/unit/server/mcp/test_tombstones.py+++ b/tests/unit/server/mcp/test_tombstones.py@@ -106,7 +106,11 @@ async def test_search_drops_tombstoned_pages(setup_mcp, session, monkeypatch):mcp_mod._vector_store.search = fake_searchresult = await search_codebase("auth service")- ids = [r["page_id"] for r in result["results"]]+ # ``page_id`` is omitted from any result that can rebuild it from+ # ``page_type`` + ``target_path``, which is every result whose Page row+ # loaded. Reconstruct rather than read — the tombstone filter itself is+ # unchanged and still keys on the id internally.+ ids = [f"{r['page_type']}:{r['target_path']}" for r in result["results"]]assert "file_page:src/auth/service.py" not in idsassert "file_page:src/db/models.py" in ids