MCP Session Lifecycle

MCP Session Lifecycle

Use this skill when debugging session state, changing reconnection logic, working on the proxy, or reasoning about races between background rejoin and user-initiated tool calls.

Source checkpoint: 2026-09-04 at 6bff3e7b. The decision record is docs/adr/mcp-session-lifecycle.md. Read the source functions below rather than copying an abbreviated session struct or reconnect algorithm.

Three Layers

• Process supervision: installed nteract-mcp and development mcp-supervisor use the runt-mcp-proxy library to supervise a runt mcp child. The library is not an executable entrypoint.
• MCP session state: the child owns one active NotebookSession, a bounded map of parked sessions, explicit activation generations, and the daemon watch loop.
• Daemon room state: runtimed owns notebook rooms, runtime state, kernels, recovery, and peer accounting. Kernel teardown and room reaping are separate.

The shipped MCP entrypoints use stdio. Multiple MCP clients can run separate children against the same daemon, including the same notebook room. Concurrent requests on one stdio connection share that child's active slot; they are not independent MCP clients. The daemon's multiplexed notebook frames are a separate protocol, not an HTTP MCP endpoint.

Entry points: crates/runt/src/lib.rs, crates/nteract-mcp/src/lib.rs, and crates/mcp-supervisor/src/main.rs.

Proxy Layer

McpProxy::track_session and session::extract_session_id track one preferred restart target, despite the field name last_notebook_id:

• Successful connect/create calls prefer the child's canonical file path for local file-backed notebooks, falling back to a UUID. Hosted targets retain their URL identity.
• Successful save_notebook promotes a local UUID target to the saved path.
• Disconnecting the active notebook clears the handoff. Disconnecting another parked notebook preserves it. Failed calls do not replace the target.
• Restart re-resolves the child executable and seeds NTERACT_MCP_REJOIN_NOTEBOOK. It does not reconstruct the parked map.
• Exit 75 is an intentional daemon-upgrade handoff, separate from the normal crash budget. Other restarts are subject to the proxy's restart controls.
• Daemon-version banners compare the old and new child's reported ServerInfo.server_info.title, not binary SHA. A banner says rejoin was requested; it does not prove that notebook readiness has completed.
• The reconnect tool restarts the child, not the daemon.

See crates/runt-mcp-proxy/src/session.rs:17, crates/runt-mcp-proxy/src/proxy.rs:310, :962, and :1268. A closed-child forwarding failure is retried once; this is not an exactly-once mutation guarantee (proxy.rs:658).

Active and Parked Sessions

NteractMcp holds the active slot and parked map in crates/runt-mcp/src/lib.rs:119. NotebookSession in crates/runt-mcp/src/session.rs carries the handle, target, activation identity, readiness evidence, and local daemon incarnation when applicable.

Switching targets parks the previous peer instead of immediately disconnecting it. MAX_PARKED_SESSIONS is eight; overflow removes an entry by arbitrary HashMap iteration order. Parked peers keep their rooms from reaching zero peers, so they can keep kernels alive. Local switch-back establishes a fresh activation and removes the old parked peer after successful publication; parked-handle reuse is not a universal reconnect contract.

Most notebook tools operate on the active target. Exceptions include explicit parked-session disconnect and notebook-ID resource reads against connected or parked local sessions. A parked map does not provide independent active tool contexts for multiple MCP clients.

See park_session, install_activated_session, and disconnect_notebook in crates/runt-mcp/src/tools/session.rs:74, :742, and :949, and handle_for_notebook in crates/runt-mcp/src/resources.rs:285.

The Watch Loop State Machine

crates/runt-mcp/src/daemon_watch.rs:238 reconciles session ownership against a live daemon incarnation (pid + started_at), not a disconnect latch:

1. A daemon event wakes the watcher. Lagged delivery also requires a fresh observation. The watcher directly calls query_daemon_info(socket_path); it does not decide from DaemonConnection's cached heartbeat info.
2. A failed identity query alone is not proof of daemon loss. Without an explicit Disconnected event, defer reconciliation and retain the handles.
3. Compare a live version with the startup baseline. A mismatch exits with 75; if startup had no daemon, the first live version establishes the baseline.
4. Remove active and parked local handles bound to a different incarnation, or to no live incarnation after confirmed absence. Hosted sessions are excluded from this local ownership reconciliation.
5. Preserve the removed active session's best recovery target, preferring a saved path. Local recovery requires a live daemon and empty slot; try the proxy handoff target first, then that preserved target.

Hosted proxy handoffs are attempted immediately at watcher entry, without a local daemon event or incarnation. Failed hosted recovery has a bounded retry timer independent of the local event stream. Both paths retain the explicit session intent epoch and publication slot guards; local recovery still checks daemon incarnation before and after connection/readiness.

A same-incarnation heartbeat leaves healthy bindings alone. A same-version restart changes incarnation and invalidates old local handles even if a Disconnected event was missed. Removing parked local handles does not enqueue recovery for every parked notebook.

See RecoveryState, reconcile_sessions, and watch. Focused tests in the same file cover same-incarnation heartbeats, lagged delivery, failed identity queries, stale parked handles, and tool-installed replacements.

The Session-Write Guard

Background rejoin connects outside the session lock. Local rejoin samples the expected daemon incarnation before and after connection/readiness. Then publish_rejoined_session checks the captured session_intent_epoch and slot emptiness under the same write lock that installs the session. Any already installed session wins, including one for the same notebook. Explicit disconnect advances the epoch under that lock so a completed background connection cannot resurrect the disconnected session.

Explicit connect/create activation has a separate generation owner: SessionActivation. Same-target in-flight connects share a result. Selecting a different canonical target supersedes the older attempt; A→B→A must not join stale A work. ActivationLease::install_in_slot_recovering rechecks ownership under the slot lock and restores the previous occupant if the installation commit is refused. A failed replacement does not invalidate the healthy installed session.

Use these production helpers, not a read-lock check followed by a separate write. See crates/runt-mcp/src/daemon_watch.rs:365, :493, :567, crates/runt-mcp/src/session_activation.rs:76, :225, and crates/runt-mcp/src/tools/session.rs:977.