feat(telemetry): a read surface over retrieval_logs — the tuning loop had no read half (#2975)

`retrieval_logs` was write-only. `record_retrieval` inserted rows and nothing
in the tree ever selected from them: the only `select()` over RetrievalLog
lived in a test. So #1038's gate — "build the reranker once telemetry shows
precision is the bottleneck" — was unsatisfiable by construction, and the one
real tuning decision on record (the 0.68 write-path threshold, #2223) had to
be reached by hand-probing the live instance with eight payloads. This adds
the half that was missing.

`retrieval_summary(user_id, days=30)` returns two aggregates side by side,
each read from the table built for it — NOT a join. NoteUsageEvent's docstring
is explicit that the two are complements ("RetrievalLog tunes the threshold,
this tunes the corpus") and that RetrievalLog's JSONB `result_ids` cannot be
indexed at the per-note grain, so correlating through it would be both slower
and less honest than reading each source directly. That corrects the approach
sketched on the task.

  - `sources`, per surface: calls, zero_result_calls, cleared_threshold (how
    often the best hit beat the threshold in force for THAT call), the
    top_score spread as p10/p50/p90/min/max, avg_result_count, p90 duration.
    Zero-result calls are counted apart from low-scoring ones — they are a
    different failure and averaging them together would hide both.
  - `usage`, from note_usage_events: ranked surfacings, ambient surfacings,
    and pulls split into `pulled_by_agent` / `pulled_by_human`.

That split is not decoration. NoteUsageEvent's own comment says the mcp_/rest_
prefix is load-bearing and names #1038 while saying so: "is this dead weight?"
is answered by any pull, "was that injected line useful?" only by an agent
pull. `pull_through` exists to answer the second, so it counts agent pulls
over ranked surfacings; both halves ship so the first stays answerable.

Two things the code made me get right rather than guess:

  - Distinct-note counts get their own queries. `count(distinct note_id)` per
    (event, source) group cannot be summed across groups — a note surfaced by
    two sources is one distinct note and would be counted twice. A wrong
    number labelled "distinct" is worse than no number.
  - No CASE in the GROUP BY. #2663 is the bug where a second case() rendered
    its own expanding bind names, Postgres rejected the query, a broad except
    swallowed it, and every counter read zero in production while mocked tests
    passed. Grouping on raw `source` and classifying in Python cannot fail
    that way. For the same reason the readout distinguishes `read_failed` from
    an empty window, and its tests are integration against real Postgres —
    percentile_cont ... WITHIN GROUP only proves it parses against a database.

Exposed as the `retrieval_telemetry` MCP tool, added to `_READ_ONLY_TOOLS`:
it mutates nothing, but its name carries no read prefix, so the completeness
test cannot derive it and it would otherwise have failed closed for read-only
keys in silence — the same reason `enter_project` is spelled out there. Docs
updated to name both exceptions rather than leave the rule looking derivable.

Scoped to the caller's own telemetry: a retrieval log records what one user's
agent asked for, query text included, and is not a shared record kind — the
owner filter is the whole access rule, not a shortcut past access.py.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/scribe/mcp/tools/search.py

@@ -12,7 +12,7 @@ import time
 from scribe.mcp._context import current_user_id
 from scribe.services.access import owner_names_for
 from scribe.services.embeddings import DEFAULT_SIMILARITY_THRESHOLD, semantic_search_notes
-from scribe.services.retrieval_telemetry import record_retrieval
+from scribe.services.retrieval_telemetry import record_retrieval, retrieval_summary
 
 
 async def search(
@@ -95,5 +95,52 @@ async def search(
     }
 
 
+async def retrieval_telemetry(days: int = 30) -> dict:
+    """What the retrieval telemetry says about YOUR surfaces, over a window.
+
+    The read half of the loop the ranker's thresholds are meant to be tuned
+    from (#2975). Reach for it before changing a similarity threshold, a top-k,
+    or deciding whether a reranker is worth building — the alternative is
+    hand-probing the live instance, which is how the last such decision had to
+    be made.
+
+    Two readouts, from the two tables built for them:
+
+    `sources` — per retrieval surface (`auto_inject`, `write_path`,
+    `mcp_search`, …), from `retrieval_logs`: `calls`, `zero_result_calls`,
+    `cleared_threshold` (how often the best hit beat the threshold in force for
+    that call), the `top_score` spread (p10/p50/p90/min/max), `avg_result_count`
+    and `p90_duration_ms`. THE number to read first is `cleared_threshold`
+    against `calls`, with the spread beside it: a surface that clears its bar
+    on nearly every call is either well-tuned or too loose, and p10 says which.
+
+    `usage` — from `note_usage_events`, at the per-note grain
+    `retrieval_logs` cannot be indexed at: `surfaced` (ranked surfacings — a
+    scored surface CHOSE the record), `ambient` (the rest), `pulled` split into
+    `pulled_by_agent` / `pulled_by_human`, the distinct-note counts, and
+    `pull_through`. That ratio is the corpus-side precision signal: records
+    surfaced often and opened never are dead weight competing for the injection
+    budget every turn.
+
+    `pull_through` is AGENT pulls over RANKED surfacings, and both halves of
+    that matter. "Is this record dead weight?" is answered by any pull; "was
+    that injected line useful?" — the question a threshold or a reranker is
+    tuned against — only by a pull the agent made. Aggregating across the
+    mcp_/rest_ prefix would silently answer the wrong one.
+
+    Scoped to your own telemetry — a retrieval log records what your agent
+    asked for, query text included, and is not a shared record kind.
+
+    `read_failed: true` means the query itself failed — deliberately distinct
+    from an empty window, because those two looked identical for weeks once
+    (#2663) and every counter silently read zero.
+
+    Args:
+        days: window size, default 30. Clamped to at least 1.
+    """
+    return await retrieval_summary(current_user_id(), days=days)
+
+
 def register(mcp) -> None:
     mcp.tool(name="search")(search)
+    mcp.tool(name="retrieval_telemetry")(retrieval_telemetry)