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.

Three Layers

The MCP server has three layers, each with its own lifecycle:

MCP Client (Claude, etc.)
    |
    v
[runt-mcp-proxy] Process supervision layer
    |  - Tracks last_notebook_id from tool results
    |  - Restarts child on crash / daemon upgrade
    |  - Seeds NTERACT_MCP_REJOIN_NOTEBOOK env var
    v
[runt-mcp] Session state layer
    |  - Arc<RwLock<Option<NotebookSession>>>
    |  - daemon_watch loop (background rejoin)
    |  - Tool dispatch (user-initiated session changes)
    v
[runtimed] Room lifecycle layer
    - NotebookRoom per notebook UUID
    - Peer counting, delayed eviction (30s)
    - Automerge sync, RuntimeStateDoc

Proxy Layer (runt-mcp-proxy)

The proxy is the outermost shell. It:

• Spawns the actual runt mcp child process
• Monitors stdout for MCP JSON-RPC and extracts notebook_id from connect_notebook / create_notebook results
• On child exit: if exit code is EX_TEMPFAIL (75), the daemon upgraded and we restart with the new binary; otherwise just restart
• Seeds NTERACT_MCP_REJOIN_NOTEBOOK env var so the child can rejoin the notebook the previous child was attached to
• Detects binary version changes (compares SHA of new binary path)

Session State Layer (runt-mcp)

This is where most complexity lives. Key types:

// The shared session state
session: Arc<RwLock<Option<NotebookSession>>>

// What's in a session
struct NotebookSession {
    handle: DocHandle,        // Automerge sync handle
    broadcast_rx: Receiver,   // Daemon broadcast channel
    notebook_id: String,      // UUID
    notebook_path: Option<String>, // File path (None for untitled)
}

Two code paths compete for the session write lock:

1. Tool calls (connect_notebook, create_notebook): User-initiated, always win. Take write lock, install new session.
2. daemon_watch loop (rejoin): Background auto-rejoin. Must check that no tool call has changed the session during the async window.

Daemon Room Layer (runtimed)

• Rooms are keyed by UUID, never change identity
• File paths are a secondary index (PathIndex)
• Peer counting: each connection is a peer. When all peers disconnect, a delayed eviction timer starts (default 30s, configurable via keep_alive_secs)
• If no peer reconnects within the eviction window: kernel shuts down, file watcher stops, room removed

The Watch Loop State Machine

daemon_watch.rs runs a classify → act loop on DaemonEvents:

classify(event, initial_target, has_session, was_disconnected, disconnect_target)
    -> WatchDecision { Exit | RejoinInitial | RejoinContinuation | MarkDisconnected | NoOp }

State Tracking

Event → Decision Matrix

The Heartbeat Problem (#2088)

DaemonConnection emits Connected every ~10s as a heartbeat. Without was_disconnected gating, every heartbeat would trigger a rejoin, creating a brief 2-peer spike that resets the room's eviction timer. The fix: only rejoin after a real Disconnected event.

The Session-Write Guard

The critical race: rejoin is async (socket connect + initial sync load, potentially 120s). During that window, a tool call might establish a completely different session. Without a guard, rejoin would overwrite it.

The guard in rejoin():

// After connect + initial load succeed...
{
    let guard = session.read().await;
    if let Some(existing) = guard.as_ref() {
        if existing.notebook_id != new_notebook_id {
            info!("Rejoin superseded by active session; dropping");
            return true;
        }
    }
}
// Only now install the rejoined session
*session.write().await = Some(new_session);

Invariant: User-initiated session changes always win over background rejoin. The guard ensures this by checking the session state after the async work completes.

Session Access Pattern

All tool handlers use the require_handle! macro:

// Read lock → clone DocHandle → drop lock → work
let handle = {
    let guard = session.read().await;
    match guard.as_ref() {
        Some(s) => s.handle.clone(),
        None => return no_session_error(...),
    }
};
// handle is now owned; lock is dropped
handle.with_doc(|doc| { ... });

This prevents lock contention: the read lock is held only for the clone, not for the entire tool execution. DocHandle is cheaply cloneable (Arc<Mutex<SharedDocState>>).

Rejoin: File-Backed vs Ephemeral

Ephemeral notebooks call connect(uuid) directly and trust the daemon's resident/recoverable-room handling. The daemon is authoritative about whether a notebook still exists — a refusal comes back as NotebookUnavailable and is handled as evicted with no retry. No pre-check list_rooms call.

File-backed notebooks use connect_open(path) which lets the daemon reload from disk. The .automerge persist files for file-backed rooms are deleted, so UUID-only connect would yield an empty document.

Session Drop Tracking

When a session ends, last_session_drop records why:

enum SessionDropReason {
    Evicted,       // Room evicted (all peers left, timer expired)
    Switched,      // User connected to a different notebook
    Disconnected,  // Daemon connection lost
}

struct SessionDropInfo {
    reason: SessionDropReason,
    notebook_id: String,
    notebook_path: Option<String>,
}

The no_session_error() function uses this to give the MCP client actionable guidance: "notebook X was evicted, call connect_notebook" vs "daemon disconnected, retry in a moment."

Common Mistakes

1. Taking write lock during tool execution

Tool handlers should clone the DocHandle under a read lock, then drop the lock before doing work. Holding a write lock during async work blocks all other tool calls and the rejoin loop.

2. Not checking session after async work in rejoin

Any async gap in rejoin (socket connect, initial load) is a window where a tool call can change the session. Always re-check before installing.

3. Treating Connected events as reconnection signals

Connected fires on every heartbeat (~10s). Only rejoin after a real Disconnected event (was_disconnected flag).

4. UUID-only connect for file-backed notebooks

File-backed rooms don't have persistent .automerge files after the room is closed. Use connect_open(path) to let the daemon reload from disk.

5. Creating phantom rooms on rejoin

If an ephemeral room was evicted, connect(uuid) creates a new empty room with no cells and no kernel. Check list_rooms first.

North Star: Concurrent MCP Clients

The current architecture assumes a single MCP client per daemon session. The north star is supporting multiple concurrent MCP clients against the same daemon. Key tension points:

• Session state is per-process: Each runt mcp process has one Arc<RwLock<Option<NotebookSession>>>. Multiple clients would need either multiple processes or per-client session tracking.
• Peer identity: Currently one peer label per MCP process. Multiple clients would need distinct peer identities for presence and conflict resolution.
• Tool dispatch: require_handle! assumes one active session. With multiple notebooks open, tools would need notebook_id routing.
• Proxy supervision: The proxy tracks one last_notebook_id. Multiple concurrent notebooks would need a session registry.