perf(mcp): slim SERVER_INSTRUCTIONS ~35%; pin marker literals + size budget with a test

[zyrill]

Why

The initialize instructions land in the agent's system prompt on every session of every MCP client — the header of server-instructions.ts itself says "Keep it tight. The agent reads this every session — long instructions burn tokens." Measured on v1.5.0, SERVER_INSTRUCTIONS is 5,890 chars (~1.5k tokens), and much of that is repetition: the explore-over-Read directive appears ~6 times and the return-shape description ("verbatim line-numbered source + call path + blast radius") ~4 times.

For context on how this compounds: we run codegraph in a multi-agent repo where every session, subagent, and cache rewrite re-pays the block — it was the single largest non-configurable item left after dieting everything else in our always-on context.

What

Rewrote the block to 3,814 chars (−35%), removing only repetition — every operative rule survives:

• explore-first / while-editing guidance, flow-by-endpoints querying (incl. the mutateElement renderScene example), treat-returned-source-as-Read, overloaded-name behavior
• all three staleness banners with their exact literal wording (agents pattern-match on these), the mis-slice/omit semantics and shifted-line-numbers caveat, and the "Already sent earlier in this conversation" dedup-pointer semantics
• the not-indexed → stop-for-session rule, codegraph init etiquette (mention, don't run), best-effort cross-file resolution, no-correctness-validation
• the merged "How to query" content folded into the tool section; "Anti-patterns" and a new compact "Staleness signals" section keep the rest

SERVER_INSTRUCTIONS_NO_ROOT_INDEX is untouched (already tight).

Guarding against re-inflation

New __tests__/server-instructions.test.ts (matches the existing root-__tests__/ vitest layout):

• pins the four literal marker strings agents match on, so a future rewording can't silently break them
• asserts no hidden tool name (anything beyond codegraph_explore) leaks into the text, per the header's own rule
• enforces a 4,000-char size budget on SERVER_INSTRUCTIONS (1,500 for the no-root variant) — the same ratchet pattern that keeps our own agent contract from regrowing

Testing

• npx vitest run __tests__/server-instructions.test.ts — 3/3 (the size case fails on v1.5.0's text, passes after the rewrite)
• npm run build — clean

🤖 Generated with Claude Code