Reduce ask_knowledge_base lexical-rescue code-term scan I/O cost

Context

Follow-up from the PR #12710 review (Approve+Follow-Up) of the #12703 ask_knowledge_base Brain-graph retrieval repair. #12710's addCodeTermRescues lexical-rescue layer correctly surfaces exact-named Brain/graph anchors (shipped + tested, 7/7), but at a per-query I/O cost worth hardening now that the correctness fix has merged.

Live latest-open sweep: checked recent open issues at 2026-06-08T00:4xZ; no equivalent KB lexical-rescue-perf ticket (the targeted sweep returned none).

The Problem

In ai/services/knowledge-base/QueryService.mjs, addCodeTermRescues fires whenever a query contains any snake_case/kebab code term >5 chars — which is common in agent KB queries (mutate_frontier, query_recent_turns, golden_path, etc.). When it fires, it walks ai/services + ai/mcp/server + ai/graph (collectFiles limit:500/root ⇒ up to ~1,500 files), reads each file's full content, and normalizes it — per query. limit:500 bounds it, but reading + normalizing ~1,500 files adds real latency to a frequent query class, and a cloud / network filesystem (multi-tenant deployment) would amplify it.

This is a scaling / perf harden, not a correctness fix — the rescue is correct and tenant-safe (verified in the #12710 review).

The Architectural Reality

addCodeTermRescues currently does a per-query filesystem walk + full-content read of the three code roots, cost ≈ O(files × content-size) per code-term query. The other rescue paths (path-hint, filename-hint, guide-title) are bounded to named anchors and are not the concern; the code-term path is the scan.

The Fix (options for the implementer)

• An inverted index / cached term → file map, built once at KB-server init (or refreshed on content change), so a code-term query is a map lookup instead of a ~1,500-file scan.
• OR narrow the candidate set (e.g. only files already matched by path/filename anchors, not all root files).
• OR a per-query file-read budget / short-circuit after enough candidates.

Acceptance Criteria

• A code-term query no longer reads up to ~1,500 files' full content per call (bounded by an index/cache or a tighter candidate set).
• The #12703 rescue behavior is preserved: the QueryService.queryDocuments.spec.mjs #12703 test still passes and the surfaced anchors are unchanged.
• A negative test added: a no-anchor semantic query does NOT trigger the code-term scan (locks in the vector-primary contract + the I/O bound).
• No tenant-isolation regression (rescued sources stay neo-shared stamped).

Out of Scope

• Lexical-rescue correctness (shipped + tested in #12710).
• The path/filename/guide-title rescue paths, unless they share the same scan cost.

Related

• Follow-up to PR #12710 (introduced addCodeTermRescues) / #12703 (the regression) / #12696 (v13 epic).
• Source: the #12710 review (Approve+Follow-Up), review PRR_kwDODSospM8AAAABCQIcAg.

Origin Session ID: 728442d6-a2a0-4481-a631-a3112ce6d703 Retrieval Hint: "ask_knowledge_base lexical rescue addCodeTermRescues per-query file scan I/O cost"