RFC: /mcp reconnect <name> — live teardown without breaking the cache prefix

[esengine]

Spun out of #105 (Stage C2b). The slow-toast half landed in #109; this captures what's left for follow-up design before any code is written.

Why

/mcp reconnect <name> should let a user recover from a transiently broken MCP server (handshake stuck, server hot-restarted) without restarting the whole Reasonix session. The design doc (docs/design/agent-tui-terminal.html §37) lists ↻ reconnect 2/5 as one of the six lifecycle states.

The constraint that makes this non-trivial

Reasonix's whole architecture rests on a byte-stable prompt prefix:

system + tool_specs + few-shots → identical bytes across turns → DeepSeek prefix-cache hits at 90%+

Reconnecting a server tears down its McpClient, re-handshakes, and re-bridges. If the reconnected server's tools/list came back with anything different — added a tool, dropped one, changed a description, even reordered — the prompt prefix shifts and the next turn cache-misses entirely. On a long session that 80%+ cache hit becomes an unrecoverable loss.

So the design question isn't "how do we tear down and re-bridge"; that part is a few dozen lines. The question is "what do we do when the reconnected tool surface differs?"

Approaches to weigh

1. Strict (refuse-on-drift): before re-bridging, snapshot the new tools/list and compare against the prior. If anything changed, refuse with a card explaining "tool surface changed, restart to apply". Preserves cache. Cost: reconnect is useless when the server has actually been updated upstream.

2. Permissive + announce: always accept the new surface; if it differs from the prior, emit a prominent warn card ("cache reset — next turn will be a full miss; subsequent turns reseed") and continue. Cost: silent expensive turns when users don't read warnings.

3. Identity-only: allow reconnect only when the new tools/list is byte-identical to the prior. Same effect as (1) for the user, but the trigger isn't user-visible. Probably worse than (1).

4. Two-mode flag: /mcp reconnect <name> is strict by default; /mcp reconnect <name> --force is permissive + warns. Best ergonomics, most code.

Other open questions

• Mid-turn vs between-turn: is reconnect allowed while a turn is in flight? Easiest answer: no, queue until next prompt.
• Other servers' callers: if the server being reconnected was mid-tool-call, the in-flight callTool promise needs to reject cleanly. Existing AbortSignal threading should cover this.
• Lifecycle event ordering: the design's ↻ reconnect 2/5 backoff 4s implies retry semantics. Is the "2/5" surface from the underlying transport's reconnect attempts, or from a Reasonix-level retry wrapper around the manual /mcp reconnect? Probably the latter, capped at 5 with exponential backoff, but worth pinning.
• r keybind in /mcp browser: Stage B left this as a stub. Once this RFC lands, the r key triggers the same code path.

Out of scope

• Auto-reconnect on transient failures during dispatch. That's a separate failure-mode question (currently a failed lifecycle line is emitted and the session continues without it). Tracking issue if anyone wants it.
• Hot-reloading the --mcp flag list to add new servers mid-session (different feature; would also need cache-prefix work).

Suggested resolution shape

I'd commit to approach #4 (default strict, --force for permissive) once the open questions above have at-least-loose answers. Spike: prototype the strict path first against the bundled demo MCP server in tests, confirm cache prefix stability, then layer --force.

Closes part of #105 (specifically: removes the r keybind stub from McpBrowser once shipped).

[esengine]

The structural half of this RFC's claim is now pinned by tests/mcp-reconnect-prefix-invariant.test.ts (landed in #112): 6 cases proving the ImmutablePrefix.fingerprint byte-identity behaviour under every drift the reconnect path could trigger — added tool, removed tool, description-only edit, schema edit, reordering, and the no-op identity case.

Practical takeaway for the design choice: only the byte-identical-tool-list case is a free reconnect. Anything else is a guaranteed cache miss, no exceptions, no degraded modes. So the strict / permissive / --force decision is purely a UX policy call, not a "maybe-cheap" gradient.

The empirical-DeepSeek spike (#2 in the original plan) is still open if anyone wants to confirm DeepSeek's prefix cache actually keys off the bytes the way our fingerprint asserts; that's the only remaining unknown.

[esengine]

Update — empirical spike landed in #113 overturns the RFC body's premise.

Live deepseek-chat run with controlled tool-list drifts:

turn	prompt	hit	miss	hit%
1 cold (toolset A)	758	640	118	84.4%
2 same prefix	753	640	113	85.0%
3 drift: ADDED tool	810	768	42	94.8%
4 same prefix again	807	768	39	95.2%
5 drift: EDITED description	761	640	121	84.1%

DeepSeek's cache works at ~128-token chunks. The position of the drift dominates the cost:

• append a tool at the end → effectively free (turn 3 hits 94.8%, higher than the no-drift baseline because the appended chunk also gets cached)
• edit a description mid-stream → bounded loss; only chunks past the edit miss (turn 5: 84.1%, with the system-prompt chunks before the edit still hitting)
• whole-list reorder / removal → would be full miss (not measured but follows from the chunk model — divergence at the start invalidates everything)

So my earlier "any drift = full cache miss" framing was wrong. /mcp reconnect is much cheaper than I thought for the most common drift shape (server adds a tool).

Revised approach recommendation

Drop the strict-default framing entirely. Adopt graduated permissive:

reconnect drift	action	reason
identical tool list	accept silently	best-case cache survival
append-only (tools added at end)	accept silently	observed 94.8% hit — trivial cost
in-place edit (description / schema changed on existing tool)	accept + one-line warn	bounded loss, user should know
removal or reorder	refuse, suggest restart (or --force flag)	divergence near front of tools = catastrophic miss

The earlier --force flag becomes a --strict flag, inverted: explicit opt-in to "don't accept anything that touches cache, even appends" — useful for high-volume scripted runs where every byte matters.

Numbers + spike script committed under benchmarks/spike-mcp-reconnect/ (#113), so future revisits can re-run cheaply.

[esengine]

Implementation status — identity-drift case landed in #115.

/mcp reconnect <name> now works for the most common drift shape: identity. Append / edit / reorder / remove drift surfaces a clear "restart Reasonix to apply" message instead of mutating the registry or prefix mid-session.

Architecture:

• McpClientHost indirection on BridgeOptions — tool closures resolve host.client at call time, so swapping the underlying client doesn't require re-bridging tools.
• New src/mcp/reconnect.ts — opens a fresh transport, classifies drift via feat(mcp): tool-list drift classifier — groundwork for #110 C2b #114's classifier, swaps host.client only on identity, closes the new client cleanly on refusal so the old one stays untouched.
• Slash subcommand /mcp reconnect <name> fires async, reports via lifecycle vocabulary (↻ reconnect… → ✓ connected / ✖ failed).

What's still deferred:

• Append-drift mid-session — needs ImmutablePrefix.addTool to be safely callable from outside the loop (it exists but the pathway from a slash callback isn't wired). Also needs ToolRegistry mutation that doesn't break the prefix invariant.
• Edit-drift mid-session — needs ImmutablePrefix.replaceTool (doesn't exist yet).
• Reorder/remove mid-session — needs ImmutablePrefix.removeTool plus a cache-reset announcement card.
• r keybind in McpBrowser — reuses this slash, trivial to add once landed.
• --strict flag — opt-in to refusing even identity reconnects.

Each is its own PR with its own (smaller) design call. The graduated-permissive policy from #113's empirical spike is the target end state; this PR delivers the first stage.

Closing this RFC's identity-case section. Will open follow-up issues for each deferred case as they get prioritized.