feat: attach graph freshness provenance to MCP tool responses

[SHudici]

Problem

Tool responses carry no freshness signal. An agent asking query_graph(callers_of, X) gets an answer that may describe a graph built hours ago, on a different branch, at a different commit — and has no way to tell. The build metadata already exists (last_updated, git_branch, git_head_sha in the metadata table); it's just never surfaced where decisions are made.

Fix

Every graph-backed tool response now carries a compact _graph provenance envelope:

"_graph": {
    "updated_at": "2026-07-03T18:22:41",
    "age_seconds": 5121,
    "built_on_branch": "main",
    "built_at_sha": "b72413c9d0aa1e..."
}

• graph_provenance() (tools/_common.py) reads the three metadata keys via a read-only SQLite connection. The db path is escaped with Path.as_uri() so URI-significant characters (#, %) in repo paths cannot derail SQLite's URI parser. Best-effort by design: any failure — no graph, unreadable DB, missing metadata — returns None and never fails the tool call. age_seconds is clamped to ≥ 0 and omitted if the timestamp doesn't parse; branch/sha are included only when present (full SHA, not truncated — agents comparing against git rev-parse HEAD shouldn't need prefix semantics).
• with_provenance() attaches the envelope to dict responses only, skips results that already carry _graph, and passes everything else through untouched.
• All 27 graph-backed MCP tools in main.py wrap their returns at the return site (not via a decorator — the Build & Embed operations hang silently on Windows 11 with uvx #46/embed_graph_tool hangs indefinitely on Windows with both sentence-transformers and Gemini provider #136 regression guards introspect tool source with inspect.getsource, and a decorator would defeat them). For the five async tools the wrap runs inside the asyncio.to_thread worker: the envelope read opens the graph DB, and the event loop must never touch disk (Build & Embed operations hang silently on Windows 11 with uvx #46, embed_graph_tool hangs indefinitely on Windows with both sentence-transformers and Gemini provider #136). Excluded: get_docs_section_tool, list_repos_tool, cross_repo_search_tool (not backed by a single repo graph).

Cost: one read-only SQLite open + a 3-row SELECT per tool call (off-loop for async tools), ~4 lines of JSON per response.

Testing

13 new tests: metadata read (all fields), URI-hostile repo paths (% and #), future-timestamp clamping, unparseable-timestamp omits age_seconds, optional branch/sha, None for missing last_updated / missing graph DB / invalid repo root, envelope attach, no-provenance pass-through, non-dict pass-through, existing-_graph preservation, and one end-to-end registered-tool response. The #46/#136 async/to_thread guards still pass. Full suite passes.

🤖 Generated with Claude Code