[colbymchenry]

Summary

The first successful tool response for a project whose index predates the running extraction engine now opens with a one-time warning, once per project per MCP session. codegraph_status always reports the build version, the running version and whether a rebuild is recommended. Detection is local, and nothing rebuilds by itself.

Root cause

Only the codegraph status CLI reported an index built by an older engine. An agent working over MCP had no sign that its answers could miss what a newer engine extracts.

What came from the contributor, and what changed

The design is theirs: state on the session because one daemon serves many clients, a warning that an error response doesn't use up, independent tracking for each projectPath project, and the proxy noting a warning the daemon delivered so an in-process failover doesn't repeat it.

Our changes:

• Dropped the plan document under docs/superpowers/.
• Rebased over about 450 commits. The only conflict was the proxy's call into the tool handler.
• The warning and the status line now leave indexing to the user ("Indexing is the user's decision: they can run codegraph index"), the wording the not-indexed guidance uses. AGENTS.md: indexing is the user's call, never the agent's.
• One-time claims key on the canonical project root, so the proxy and the handler agree on a project however its path is spelled. Added a case for that, and a case for the wording.
• CHANGELOG moved under [Unreleased], in house format.

No automatic rebuild: that stays #1798.

Validation

• Tests: 7 unit cases in mcp-index-version-warning.test.ts and 2 real proxy and daemon cases in mcp-daemon.test.ts.
• Mutations: turning the notice off fails 5 of 7, delivering it every time fails 5 of 7, and dropping the proxy's record fails the failover case.
• Real MCP sessions, main against this branch, both arms on one index:

Repo	Files	tools/list	Current index: 2 explores	Stale: first explore	Stale: second explore
express	149	same	byte-identical	main's + 338 chars	byte-identical
flask	91	same	byte-identical	main's + 338 chars	byte-identical
gin	110	same	byte-identical	main's + 338 chars	byte-identical
excalidraw	738	same	byte-identical	main's + 338 chars	byte-identical

• Explore's budgets aren't touched, and explore output sizes match main (14K to 25K chars here).
• isIndexStale() costs 30 to 48 µs per tool call on those indexes.
• Suite: one full Vitest 4 run with 4 workers on a stack of fix(cli): reject sync for stale extraction indexes #1842, this PR, fix(cli): require full rebuild for stale extraction indexes #1256 and feat(cli): expose test-file classification #1960: top c8652154 on main d494e43, 845 files, 10307 tests, 10219 passed, 1 failed, 87 skipped. The one failure was owning-package.test.ts, pinned to feat(cli): expose test-file classification #1960 and fixed in its commit.
• On the stack after a clean rebase (top fc42f83b on 446d08c): 8 affected test files, this PR's two included, 174 passed, 1 skipped, kernel expected. This commit has the same lines as the stack's.

Fixes #1852

Lands #1853 by @cbeaulieu-gt

🤖 Generated with Claude Code