fix(mcp): reconnect MCP/CLI session after a transient engine restart

[mathias-heide]

Problem — MCP/CLI "disconnects from the project"

Distinct from the desktop engine-disconnect. The Summer MCP server (npx summer-engine mcp) is a long-lived stdio process — it lives as long as Claude Code / Cursor / Codex keep it. It caches one EngineApiClient that snapshots the engine's ~/.summer/api-port + api-token at first connect and never refreshes them.

But the engine invalidates those credentials on every launch:

Engine behavior	Source	Effect on the cached client
Mints a new random api-token each launch	local_api_server.cpp::_generate_api_token	Old Bearer token → 401 → reads as "disconnected"
Binds 6550 but increments to 6565 if the old socket lingers	tool_net_thread.cpp::start()	Pinned to a dead/old port
New random instanceId per process	engine_identity.cpp	identity drift

So any engine restart / reopen / crash-relaunch / update left the cached client hitting the old port with the old token → 401. The only recovery was withEngine's catch → resetClient(), which heals on the next call — so every restart cost at least one hard, user-visible disconnect, and soft not_connected / identity_mismatch terminal states (which bypass the catch) never reset the client at all.

Fix (scope kept to MCP/CLI)

• EngineApiClient.credentialsChanged() — cheap drift probe: re-reads api-port + api-token and reports whether they no longer match this client's snapshot. Empty/unreadable creds (engine mid-write or just-closed) count as no drift so a transient read never thrashes the cache.
• getClient() — checks credentialsChanged() before reusing the cache, so a silent engine restart reconnects transparently with zero surfaced error.
• withEngine() — drops the cached client and retries once on connection-class failures only: thrown 401/403/ECONNREFUSED/closed-port, and the soft not_connected / identity_mismatch terminal states (both "nothing applied" by contract). Deliberately does NOT retry timed_out / content_mismatch / denied / canceled — ambiguous or intentional, and retrying could double-apply a mutation.

Two layers compose as defense-in-depth: proactive drift detection handles the common "restarted between calls" case; reset+retry handles the race where the restart lands during a call.

Repro / tests

• src/mcp/reconnect.integration.test.ts — drives the real getClient → EngineApiClient → withEngine stack over real HTTP against a fake engine that rotates its token (only the credential-file readers are stubbed, so the user's ~/.summer is untouched). The session survives the rotation and a mid-call restart.
• src/mcp/server.reconnect.test.ts — drift cache: reuse while stable, rebuild on token/port rotation, don't thrash on a mid-write empty read.
• src/mcp/tools/with-engine.reconnect.test.ts — retry classifier: heals 401 / fetch failed / not_connected / identity_mismatch; does not retry timed_out / normal op errors / 5xx.

All 6 new repro tests fail on main and pass with this change. Full suite: 312 passed (was 298). tsc strict build clean.

Coordinated with the engine-disconnect work but no engine/web changes here — purely the summer-engine-agent MCP/CLI client.

🤖 Generated with Claude Code