feat(mcp): surface when a newer CodeGraph release exists (non-blocking update check)

[colbymchenry]

Closes #1243.

Problem

The recommended MCP config launches the local codegraph binary, so the server (and the prompt hook beside it) silently stays on whatever version was last manually upgraded. Users discover the drift only when something breaks. The reporter's preferred fix (their option 1): check on serve start, surface a notice, change nothing.

What this does

On MCP server start (proxy, daemon, and direct modes share the hook), refresh a machine-shared update-check cache in the background and — when a newer release exists — surface one sentence on three surfaces:

• stderr at startup (lands in the MCP host's server log; never stdout, the protocol channel)
• the initialize instructions, with explicit "mention it to the user when convenient; do not run the upgrade yourself" guidance — the primary user-visible channel, since codegraph_status is unlisted by default
• codegraph_status

Nothing auto-updates.

Design notes

• Version resolution reuses resolveLatestVersion() (the GitHub release-redirect trick, linux install? how? #325-safe), so what the check reports and what codegraph upgrade installs can't drift.
• Cache: ~/.codegraph/update-check.json, shared by every server process — 24h TTL on success, 1h backoff on failure; an outage never hides an already-known update; a stale cache re-kicks a background refresh so long-lived daemons keep noticing.
• The initialize path is a memoized synchronous cache read (the MCP server fails to connect with Claude Code: Content-Length framing vs newline-delimited JSON transport mismatch #172 respond-fast contract holds), and both handshake answerers — session and proxy — share one initializeInstructions() helper so they can't diverge.
• Hardening: the latest tag arrives from a network redirect via an on-disk cache and ends up inside agent-visible instructions — only a canonical vX.Y.Z rebuilt from parsed semver fields is ever interpolated. A tag with trailing text (parseSemver isn't end-anchored) renders without it; a non-version tag renders nothing and counts as a failed attempt.
• Off is off: CODEGRAPH_NO_UPDATE_CHECK=1 (dedicated) or DO_NOT_TRACK=1 (broad convention) suppresses the network call and the notice entirely. Documented in TELEMETRY.md with the honest note that only a version number is fetched.

Validation

• 20 unit tests: TTL/backoff discipline, opt-outs, torn-cache resilience, dev-sentinel guard, injection canonicalization, the instructions suffix.
• End-to-end smoke against the spawned dist server: fake-HOME cache claiming v9.9.9 → notice in initialize instructions + stderr; current-version control run → byte-identical clean instructions, silent log.
• Full suite green (2344+ tests).

🤖 Generated with Claude Code