MCP Session Lifecycle

Use this skill when debugging notebook routing, attachment ownership, reconnection, observation, or proxy behavior. Read the owning source and tests; a protocol version or a successful connect is not proof of notebook readiness.

The current routing decision is explicit notebook attachments. The earlier lifecycle record preserves daemon and recovery decisions; its active-selection routing is superseded by the attachment contract.

Three Layers

• Process supervision: installed nteract mcp/nteract-mcp and development mcp-supervisor use the runt-mcp-proxy library to supervise a worker. The library is not a standalone MCP entrypoint.
• Notebook attachments: the runt mcp worker retains a registry of logical notebook owners, each addressed by an opaque notebook_handle. Its active slot, parked map and activation helpers also support internal recovery; they do not supply a missing notebook target for public tool requests.
• Daemon rooms: runtimed owns notebook content, source recovery, runtime documents, kernels, saves and peer accounting.

Separate children can share one daemon. One stdio process can also receive interleaved requests from unrelated chats. Neither the connection, process, request ID nor client label identifies a chat's notebook. Attribution is not an authorization boundary for same-user local clients.

Explicit Targets on Every Protocol

Ordinary notebook calls require exactly one of notebook_id (plus configured domain for hosted notebooks) or notebook_handle. Omitted domain is the fixed local daemon. Disconnect and the hidden compatibility wait require an exact handle. Missing/ambiguous targets fail before effects on every MCP protocol.

ID resolution uses already connected authorized replicas; it never opens a peer or launches a kernel. The first ID call retains a separate shared address owner, counted under the 128-owner limit, with no TTL/eviction. Local selection checks daemon incarnation/operator; hosted selection checks pinned actual credentials, operator and authenticated principal. Conflicting principal evidence fails closed. Release of an explicit handle does not release the address owner. The ID result's target.notebook_handle releases that shared retention, not a chat-private lease.

Each ID request captures its exact replica through completion, preserving known cell/execution outcomes after retention release. Exact-handle calls retain their membership fences. A cell_id is always resolved inside the supplied notebook. Cold IDs require an explicit connect; expired handles never rebind as ID requests.

targets::dispatch, notebook_target::acquire, session_access and NotebookSession::access separate selection from operation readiness. Preserve source/runtime authority and causal execution gates. The proxy checks the exact live child's target contract before forwarding; cache/schema rewriting cannot prove support. Handle-only workers reject ID requests before dispatch.

Catalog migration and attachment recovery are separate. Prefer standard tools/list_changed notification and native catalog subscription relisting inside the existing chat. A server can invalidate its own cache and notify a host; it cannot replace schemas already in the host's model context. If a host keeps old definitions, reconnect its MCP connection and relist rather than guess a target or restore implicit selection. An already-running old proxy may need that reconnect to load new code. After child replacement, acquire the intended notebook again, read a baseline and resubscribe; inspect ambiguous mutations before retry. Configuration reload alone does not prove a catalog refresh. Catalog publication requires successful discovery from the current connected child; fallback or rewritten schemas never prove child capability.

Tool additions, removals, renames and schema changes publish catalog invalidation without forcing a stdio exit. Relist to discover the current names; removed names receive unknown-tool protocol errors. Fatal failures and crash-budget exhaustion retain their own recovery policies.

Relevant source: crates/runt-mcp/src/targets.rs, attachments.rs, lib.rs, session.rs, and crates/mcp-transport/src/lib.rs.

Ownership and Retention

The registry retains at most 128 logical attachments plus pending acquisitions. Reservations count toward that limit and return on cancellation or failure. There is no TTL or arbitrary ownership eviction. Release removes only the named handle, signals its expiry immediately, and returns its capacity slot. Acquisition descriptions state retention; repeated connect creates a new owner and must not advertise idempotence.

Logical ownership is separate from a physical peer. Compatible healthy local acquisitions may share backing by canonical target, fixed endpoint, live daemon incarnation and operator. Sharing never reuses an unhealthy or unready replica or a stale saved-path alias. A failed optional room listing skips reuse and attempts guarded fresh admission. Hosted peers are not pooled without a stable authenticated principal/source key. Dropping the last owner releases the backing.

An address owner also retains the MCP peer after explicit handles are released. This can postpone the local daemon's last-client idle teardown. Release that shared retention with disconnect_notebook(notebook_handle=target.notebook_handle) from the ID result, or find its handle through resources/list. Switching request targets does not release another notebook's owners or runtime peer.

The bounded parked cache is not the ownership registry. Dropping a cache entry must not release an independently retained attachment. Legacy notebook-ID resource URIs still identify a notebook explicitly; ambiguous identities require an exact handle. They never justify an implicit tool target.

Readiness and Execution Gates

Retained projection reads do not authorize mutation or execution. Local connect may return before interactivity with a heads-qualified control-plane projection. Create and internal rejoin await their readiness paths. Hosted readiness uses its connected-replica contract. Execute synced notebook cells by cell_id; never send a separate code string that can diverge from the document.

Scoped Observations

Handle-qualified resources use nteract://sessions/{notebook_handle}/cells, /cells/{cell_id}, and /comments. Observers capture identity before waiting and subscribe before baseline capture. Cursors belong to an exact observation journal; stale/foreign cursors require a fresh baseline.

Legacy resources/subscribe and native subscriptions/listen watch their captured attachment. The proxy reference-counts child URI leases: canceling or releasing one listener cannot unsubscribe another. Cached acquisition rechecks child admission before acknowledging a new listener. Native notifications preserve the upstream subscription ID. Child replacement ends old streams; clients obtain new handles and baselines rather than rebinding old ones.

Membership expiry and terminal observation loss are distinct:

• Release/incarnation expiry produces attachment_expired and the metadata key io.nteract/attachmentExpired.
• A terminal disconnected backing produces attachment_unavailable and io.nteract/attachmentUnavailable. Its watch ends, but registry ownership and capacity remain until deliberate release or membership expiry. Read/admission errors preserve their original code/message/readiness and add typed data.

Already-signaled expiry wins. Pending readiness, missing cells and untyped transient failures do not end a live URI lease. A mixed listener survives until its last URI ends. Observation receivers do not independently keep notebook peers or kernels alive.

Resources/subscriptions remain the ongoing observation API. inspect_notebook returns bounded cells/source/readiness and a matching cursor; after plus timeout_secs waits for notebook-wide changes. get_results waits for an exact execution without submitting another run, preserves executed source after edits, and checks durable result context against the target notebook. Both default to zero and cap at 50 seconds, sharing eight wait permits with the hidden legacy wait_for_notebook_change (whose 25-second default and handle contract remain). Cancellation ends observation, not computation. Retained projections have no live cursor; pagination reads live state and callers must compare cursors.

Relevant source: resources.rs, subscriptions.rs, tools/observation.rs, proxy native_subscriptions.rs, observation_bridge.rs, and child.rs.

Recovery and Daemon Incarnation

Local handles carry daemon identity pid + started_at. The watcher queries live identity directly; cached heartbeat events only wake reconciliation. Failed identity lookup alone does not prove loss. Confirmed absence or a replacement incarnation expires affected local registry handles; hosted attachments survive local-daemon reconciliation. Healthy same-incarnation heartbeats do not expire ownership.

Preserve original source recovery. Prefer a canonical saved path; UUID admission remains daemon-authoritative and may recover from resident rooms, persisted untitled content or UUID/path bindings. A missing source is not permission to invent an empty notebook or load a stale mirror. Do not use list_rooms as an existence precheck. NotebookUnavailable is definitive; transient failures retain internal recovery context.

Internal rejoin captures the intent epoch and daemon incarnation, connects outside locks, rechecks incarnation, then publishes under the slot write lock only if intent and slot ownership still permit it. Explicit disconnect must not be undone by late background work. These helpers preserve internal recovery; they never make an old public handle name a new peer.

Proxy restart re-resolves the child executable. Exit 75 is an intentional upgrade handoff, separate from crash budget. reconnect replaces the worker, not the daemon. A recovery banner is not proof of notebook readiness. All old worker handles expire. No ambiguous mutation is automatically replayed; outcome_unknown requires state inspection before any caller retry.

Relevant source: daemon_watch.rs, session_activation.rs, proxy proxy.rs, session.rs, version.rs, and circuit_breaker.rs.

Daemon Room Lifetime and Protocol Limits

The local daemon schedules idle kernel teardown when the last counted client peer leaves. The runtime agent that owns a Python kernel is a separate sync peer, outside that ordinary client-peer count. After keepalive, the daemon rechecks connections, generation and persistence before requesting shutdown through the runtime peer. Releasing an MCP handle does not unconditionally stop the kernel: other owners, admitted requests or client peers may retain a connection, and hosted lifetime follows the room host's policy. Room reaping is a separate decision; kernel teardown does not prove source unavailability. See runtimed/src/notebook_sync_server/peer_connection.rs, peer_runtime_agent.rs, peer_eviction.rs, and runtimed/src/daemon.rs.

The transport supports initialize-based MCP revisions through 2025-11-25 and native per-request 2026-07-28 metadata. The private worker handshake uses 2025-11-25; it still requires explicit notebook arguments. Invalid native metadata must not start recovery/setup or dispatch an application operation. Request cancellation and transport teardown have separate owned scopes.

Source and isolated Unix wire tests do not qualify Codex rendering, Windows, live hosted authentication, installed package delivery or real kernel execution. Many distinct physical peers also retain a separate presence-frame protocol limit; logical peer sharing is not a protocol-cap increase.