ruby-mcp-client 2.1.0 → 3.0.0

data/lib/mcp_client/server_sse.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'request_meta_scope'
 require 'uri'
 require 'json'
 require 'monitor'
@@ -7,26 +8,41 @@ require 'logger'
 require 'faraday'
 require 'faraday/retry'
 require 'faraday/follow_redirects'
+require_relative 'deprecations'
 
 module MCPClient
   # Implementation of MCP server that communicates via Server-Sent Events (SSE)
   # Useful for communicating with remote MCP servers over HTTP
   #
+  # @deprecated The HTTP+SSE transport has been deprecated since MCP
+  #   2025-03-26 and is listed in the 2026-07-28 deprecated features
+  #   registry (SEP-2596); earliest removal is three months after SEP-2596
+  #   reaches Final. Use {MCPClient::ServerStreamableHTTP}.
+  #
   # @note Elicitation Support (MCP 2025-06-18)
   #   This transport FULLY supports server-initiated elicitation requests via bidirectional
   #   JSON-RPC. The server sends elicitation/create requests via the SSE stream, and the
   #   client responds via HTTP POST to the RPC endpoint. This provides full elicitation
   #   capability for remote servers.
   class ServerSSE < ServerBase
+    require_relative 'request_authorization'
     require_relative 'server_sse/sse_parser'
     require_relative 'server_sse/json_rpc_transport'
 
     include SseParser
     include JsonRpcTransport
+    # The credentials of the request this thread last sent, kept in the same
+    # slot, with the same empty-slot semantics, as on the other transports:
+    # {#cleanup} drops it with the rest of what this transport left behind.
+    include MCPClient::RequestAuthorization
 
     require_relative 'server_sse/reconnect_monitor'
 
     include ReconnectMonitor
+    # Every operation that may weigh a cache decision runs inside a scope
+    # that reserves the host request_meta evaluation for the request it
+    # leads to, and drops it when the operation ends.
+    prepend MCPClient::RequestMetaScope
 
     # Ratio of close_after timeout to ping interval
     CLOSE_AFTER_PING_RATIO = 2.5
@@ -144,21 +160,23 @@ module MCPClient
     # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
     # @raise [MCPClient::Errors::PromptGetError] for other errors during prompt listing
     def list_prompts
-      @mutex.synchronize do
-        return @prompts if @prompts
-      end
+      # MCP 2026-07-28 caching: a list is served only while its hint is
+      # fresh, and only from the entry that carries the hint.
+      cached = fresh_list_value(:prompts) { @mutex.synchronize { @prompts } }
+      return cached if cached
+
+      @mutex.synchronize { @prompts_data = nil }
 
       begin
         ensure_initialized
 
-        prompts_data = request_prompts_list
+        prompts = request_prompts_list.map { |prompt_data| MCPClient::Prompt.from_json(prompt_data, server: self) }
         @mutex.synchronize do
-          @prompts = prompts_data.map do |prompt_data|
-            MCPClient::Prompt.from_json(prompt_data, server: self)
-          end
+          @prompts = attach_list_value(:prompts, prompts) ? prompts : nil
         end
 
-        @mutex.synchronize { @prompts }
+        # This request's own list, never a re-read of @prompts.
+        prompts
       rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
         # Re-raise these errors directly
         raise
@@ -180,6 +198,12 @@ module MCPClient
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
       # Re-raise connection/transport errors directly to match test expectations
       raise
+    rescue MCPClient::Errors::ServerError => e
+      # 2026-07-28 protocol errors (typed -3202x, invalid result) carry
+      # actionable data such as requiredCapabilities; keep them intact.
+      raise if e.protocol_error?
+
+      raise MCPClient::Errors::PromptGetError, "Error get prompt '#{prompt_name}': #{e.message}"
     rescue StandardError => e
       # For all other errors, wrap in PromptGetError
       raise MCPClient::Errors::PromptGetError, "Error get prompt '#{prompt_name}': #{e.message}"
@@ -192,16 +216,21 @@ module MCPClient
     # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
     # @raise [MCPClient::Errors::ResourceReadError] for other errors during resource listing
     def list_resources(cursor: nil)
-      @mutex.synchronize do
-        return @resources_result if @resources_result && !cursor
-      end
+      cached = cursor ? nil : fresh_list_value(:resources) { @mutex.synchronize { @resources_result } }
+      return cached if cached
 
       begin
         ensure_initialized
 
         params = {}
         params['cursor'] = cursor if cursor
-        result = rpc_request('resources/list', params)
+        epoch = cache_epoch(:resources)
+        answer = fetching_list_page(:resources, cursor) { rpc_request('resources/list', params) }
+        result = require_complete_result!(answer, 'resources/list')
+        # MCP 2026-07-28 caching: the first page's hint decides how long the
+        # cached list may be served, counted from receipt (the list is
+        # attached once converted).
+        record_cache_hint(:resources, result, epoch: epoch) unless cursor
 
         resources = (result['resources'] || []).map do |resource_data|
           MCPClient::Resource.from_json(resource_data, server: self)
@@ -210,7 +239,9 @@ module MCPClient
         resources_result = { 'resources' => resources, 'nextCursor' => result['nextCursor'] }
 
         @mutex.synchronize do
-          @resources_result = resources_result unless cursor
+          unless cursor
+            @resources_result = attach_list_value(:resources, resources_result) ? resources_result : nil
+          end
         end
 
         resources_result
@@ -230,9 +261,13 @@ module MCPClient
     # @raise [MCPClient::Errors::ResourceReadError] for other errors during resource reading
     # @raise [MCPClient::Errors::ConnectionError] if server is disconnected
     def read_resource(uri)
-      result = rpc_request('resources/read', { uri: uri })
-      contents = result['contents'] || []
-      contents.map { |content| MCPClient::ResourceContent.from_json(content) }
+      ensure_initialized
+      read_resource_with_cache(uri) { |sent| rpc_request('resources/read', { uri: sent }) }
+    rescue MCPClient::Errors::ServerError => e
+      raise if e.protocol_error?
+      raise resource_not_found_error(uri, e) if resource_not_found_response?(e)
+
+      raise MCPClient::Errors::ResourceReadError, "Error reading resource '#{uri}': #{e.message}"
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
       # Re-raise connection/transport errors directly to match test expectations
       raise
@@ -247,16 +282,35 @@ module MCPClient
     # @raise [MCPClient::Errors::ServerError] if server returns an error
     # @raise [MCPClient::Errors::ResourceReadError] for other errors during resource template listing
     def list_resource_templates(cursor: nil)
+      # Only a list the server itself bounded is served from here: a
+      # positive ttlMs means no second request, while a list with no hint
+      # (a 2025-11-25 server) is asked for again, as it was before this
+      # transport cached anything (MCP 2026-07-28 caching).
+      cached = cursor ? nil : hinted_list_value(:templates)
+      return cached if cached
+
       ensure_initialized
       params = {}
       params['cursor'] = cursor if cursor
-      result = rpc_request('resources/templates/list', params)
+      epoch = cache_epoch(:templates)
+      answer = fetching_list_page(:templates, cursor) { rpc_request('resources/templates/list', params) }
+      result = require_complete_result!(answer, 'resources/templates/list')
+      # MCP 2026-07-28 caching: the first page's hint decides freshness,
+      # counted from receipt (the list is attached once converted).
+      record_cache_hint(:templates, result, epoch: epoch) unless cursor
 
       templates = (result['resourceTemplates'] || []).map do |template_data|
         MCPClient::ResourceTemplate.from_json(template_data, server: self)
       end
+      templates_result = { 'resourceTemplates' => templates, 'nextCursor' => result['nextCursor'] }
 
-      { 'resourceTemplates' => templates, 'nextCursor' => result['nextCursor'] }
+      @mutex.synchronize do
+        unless cursor
+          @templates_result = attach_list_value(:templates, templates_result) ? templates_result : nil
+        end
+      end
+
+      templates_result
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
       raise
     rescue StandardError => e
@@ -303,21 +357,23 @@ module MCPClient
     # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
     # @raise [MCPClient::Errors::ToolCallError] for other errors during tool listing
     def list_tools
-      @mutex.synchronize do
-        return @tools if @tools
-      end
+      # MCP 2026-07-28 caching: a list is served only while its hint is
+      # fresh, and only from the entry that carries the hint.
+      cached = fresh_list_value(:tools) { @mutex.synchronize { @tools } }
+      return cached if cached
+
+      @mutex.synchronize { @tools_data = nil }
 
       begin
         ensure_initialized
 
-        tools_data = request_tools_list
+        tools = request_tools_list.map { |tool_data| MCPClient::Tool.from_json(tool_data, server: self) }
         @mutex.synchronize do
-          @tools = tools_data.map do |tool_data|
-            MCPClient::Tool.from_json(tool_data, server: self)
-          end
+          @tools = attach_list_value(:tools, tools) ? tools : nil
         end
 
-        @mutex.synchronize { @tools }
+        # This request's own list, never a re-read of @tools.
+        tools
       rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
         # Re-raise these errors directly
         raise
@@ -339,6 +395,12 @@ module MCPClient
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
       # Re-raise connection/transport errors directly to match test expectations
       raise
+    rescue MCPClient::Errors::ServerError => e
+      # 2026-07-28 protocol errors (typed -3202x, invalid result) carry
+      # actionable data such as requiredCapabilities; keep them intact.
+      raise if e.protocol_error?
+
+      raise MCPClient::Errors::ToolCallError, "Error calling tool '#{tool_name}': #{e.message}"
     rescue StandardError => e
       # For all other errors, wrap in ToolCallError
       raise MCPClient::Errors::ToolCallError, "Error calling tool '#{tool_name}': #{e.message}"
@@ -355,11 +417,17 @@ module MCPClient
       require_capability!('completions', method: 'completion/complete')
       params = { ref: ref, argument: argument }
       params[:context] = context if context
-      result = rpc_request('completion/complete', params)
+      result = require_complete_result!(rpc_request('completion/complete', params), 'completion/complete')
       result['completion'] || { 'values' => [] }
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError,
            MCPClient::Errors::CapabilityError
       raise
+    rescue MCPClient::Errors::ServerError => e
+      # 2026-07-28 protocol errors (typed -3202x, invalid result) carry
+      # actionable data such as requiredCapabilities; keep them intact.
+      raise if e.protocol_error?
+
+      raise MCPClient::Errors::ServerError, "Error requesting completion: #{e.message}"
     rescue StandardError => e
       raise MCPClient::Errors::ServerError, "Error requesting completion: #{e.message}"
     end
@@ -369,13 +437,24 @@ module MCPClient
     #   'critical', 'alert', 'emergency')
     # @return [Hash] empty result on success
     # @raise [MCPClient::Errors::ServerError] if server returns an error
+    # @deprecated Logging is deprecated since MCP 2026-07-28 (SEP-2577);
+    #   earliest removal is the first revision released on or after
+    #   2027-07-28. Have the server log to stderr (stdio) or use
+    #   OpenTelemetry instead.
     def log_level=(level)
+      MCPClient::Deprecations.warn(:logging, @logger)
       ensure_initialized
       require_capability!('logging', method: 'logging/setLevel')
       rpc_request('logging/setLevel', { level: level })
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError,
            MCPClient::Errors::CapabilityError
       raise
+    rescue MCPClient::Errors::ServerError => e
+      # 2026-07-28 protocol errors (typed -3202x, invalid result) carry
+      # actionable data such as requiredCapabilities; keep them intact.
+      raise if e.protocol_error?
+
+      raise MCPClient::Errors::ServerError, "Error setting log level: #{e.message}"
     rescue StandardError => e
       raise MCPClient::Errors::ServerError, "Error setting log level: #{e.message}"
     end
@@ -384,7 +463,15 @@ module MCPClient
     # @return [Boolean] true if connection was successful
     # @raise [MCPClient::Errors::ConnectionError] if connection fails
     def connect
-      return true if @mutex.synchronize { @connection_established }
+      # An already-established connection is another use of the transport,
+      # and another chance at the notice: the first connect may have found
+      # notices disabled, a logger above WARN or a logger that raised, all of
+      # which leave the slot unspent. A long-lived connection would otherwise
+      # never retry it.
+      if @mutex.synchronize { @connection_established }
+        MCPClient::Deprecations.warn(:http_sse_transport, @logger)
+        return true
+      end
 
       # Check for pre-existing auth error (needed for tests)
       pre_existing_auth_error = @mutex.synchronize { @auth_error }
@@ -399,6 +486,10 @@ module MCPClient
         effective_timeout = [@read_timeout || 30, 30].min
         wait_for_connection(timeout: effective_timeout)
         start_activity_monitor
+        # The notice is about using the transport: MCPClient.connect builds
+        # (and tries) an SSE server while probing a URL that may end up on
+        # another transport, so only an established connection counts.
+        MCPClient::Deprecations.warn(:http_sse_transport, @logger)
         true
       rescue MCPClient::Errors::ConnectionError => e
         cleanup
@@ -423,6 +514,12 @@ module MCPClient
     #   multiple connection attempts. This is essential for proper reconnection
     #   logic and exponential backoff.
     def cleanup
+      # Everything this transport left on this thread — the notes of the
+      # entries it served and recorded, the credentials, parameters and
+      # metadata of its requests — describes a slice that will never be
+      # tagged and a request that will never be made.
+      forget_transport_thread_state
+      bump_session_epoch
       @mutex.synchronize do
         # Set flags first before killing threads to prevent race conditions
         # where threads might check flags after they're set but before they're killed
@@ -493,9 +590,48 @@ module MCPClient
         @sse_conn = nil
 
         @tools = nil
+        @tools_data = nil
+        @prompts = nil
+        @prompts_data = nil
+        @resources_result = nil
+        @templates_result = nil
         # Don't clear auth error as we need it for reporting the correct error
         # Don't reset @consecutive_ping_failures or @reconnect_attempts as they're tracked across reconnections
       end
+      # Cached results and their hints belong to the connection that was just
+      # torn down (MCP 2026-07-28 caching); outside @mutex, as the cache has
+      # its own lock.
+      clear_result_cache
+    end
+
+    # The authorization context of this transport (MCP 2026-07-28 caching,
+    # cacheScope "private"): HTTP+SSE sends the static Authorization header
+    # it was configured with, so that header is both what the next request
+    # would carry and what the last one carried.
+    # @param _kind [Symbol, String, nil] the cache kind (every request carries the same header)
+    # @return [String, nil]
+    def current_authorization_context(_kind = nil)
+      # Through Faraday's case-insensitive table, so several spellings of
+      # the header in the configured hash resolve to the one value a
+      # request would actually carry.
+      authorization_fingerprint(authorization_header_value(faraday_headers(@headers)))
+    end
+
+    # Remember the Authorization a request actually carried once it was sent,
+    # for a request that recorded none of its own. What binds the result is
+    # what the request was built with: `response.env` is mutable and the
+    # response phase may rewrite it (a redaction, a redirect that strips the
+    # header), which would file an authenticated result under the anonymous
+    # context.
+    # @param response [Faraday::Response, nil]
+    # @return [void]
+    def note_sent_authorization(response)
+      return if request_authorization_recorded?
+
+      env = response.respond_to?(:env) ? response.env : nil
+      return unless env.respond_to?(:request_headers) && env.request_headers
+
+      note_request_authorization(authorization_header_value(env.request_headers))
     end
 
     # Register a callback for elicitation requests (MCP 2025-06-18)
@@ -506,6 +642,13 @@ module MCPClient
     end
 
     # Register a callback for roots/list requests (MCP 2025-06-18)
+    #
+    # @deprecated Roots is deprecated since MCP 2026-07-28 (SEP-2577); earliest
+    #   removal is the first revision released on or after 2027-07-28. Registering
+    #   a handler is not itself use of Roots — a handler that answers with no root
+    #   exposes nothing deprecated — but a handler that answers with a root adopts
+    #   the deprecated feature and raises the notice. Pass directories or files
+    #   through tool parameters, resource URIs or server configuration instead.
     # @param block [Proc] callback that receives (request_id, params) and returns response hash
     # @return [void]
     def on_roots_list_request(&block)
@@ -513,6 +656,11 @@ module MCPClient
     end
 
     # Register a callback for sampling requests (MCP 2025-11-25)
+    #
+    # @deprecated Sampling is deprecated since MCP 2026-07-28 (SEP-2577); earliest
+    #   removal is the first revision released on or after 2027-07-28. Integrate
+    #   directly with the LLM provider API instead of serving
+    #   sampling/createMessage.
     # @param block [Proc] callback that receives (request_id, params) and returns response hash
     # @return [void]
     def on_sampling_request(&block)
@@ -599,6 +747,10 @@ module MCPClient
 
       # Call the registered callback
       result = @roots_list_request_callback.call(request_id, params)
+      # Serving a roots/list answer that carries a root means this host
+      # declared, and is using, the deprecated Roots capability (SEP-2577) —
+      # with or without a Client. An empty answer is not use of it.
+      warn_roots_deprecated(result)
 
       # Send the response back to the server (echoing related-task _meta)
       send_roots_list_response(request_id, merge_related_task_meta(result, params))
@@ -631,10 +783,18 @@ module MCPClient
       # If no callback is registered, return error
       unless @sampling_request_callback
         @logger.warn('Received sampling request but no callback registered, returning error')
-        send_error_response(request_id, -1, 'Sampling not supported')
+        # sampling.mdx § Error Handling reserves -1 for "User rejected sampling
+        # request"; a capability this client never declared is an unsupported
+        # method (-32601, Method not found), as Client#handle_sampling_request answers.
+        send_error_response(request_id, -32_601, 'Sampling not supported')
         return
       end
 
+      # Sampling, and the includeContext values it may carry, are deprecated
+      # (SEP-2577, SEP-2596) — with or without a Client.
+      warn_sampling_deprecated(params)
+      return if refused_undeclared_sampling_tools?(request_id, params)
+
       # Call the registered callback
       result = @sampling_request_callback.call(request_id, params)
 
@@ -741,6 +901,7 @@ module MCPClient
         # header on all HTTP requests after the initialize handshake.
         req.headers['Mcp-Protocol-Version'] = @protocol_version if @protocol_version
         @headers.each { |k, v| req.headers[k] = v }
+        note_request_authorization(authorization_header_value(req.headers))
         req.body = json_body
       end
 
@@ -804,6 +965,7 @@ module MCPClient
     def establish_sse_connection(conn, sse_path)
       conn.get(sse_path) do |req|
         @headers.each { |k, v| req.headers[k] = v }
+        note_request_authorization(authorization_header_value(req.headers))
 
         req.options.on_data = proc do |chunk, _bytes|
           process_sse_chunk(chunk.dup) if chunk && !chunk.empty?
@@ -866,6 +1028,11 @@ module MCPClient
     # Process an SSE chunk from the server
     # @param chunk [String] the chunk to process
     def process_sse_chunk(chunk)
+      # Every event in this chunk arrived together, before any of them was
+      # decoded or dispatched: a response is dated from that moment, so a
+      # slow callback on an earlier event in the same chunk cannot make it
+      # look younger than the ttlMs its server sent (MCP 2026-07-28 caching).
+      arrived = monotonic_now if respond_to?(:monotonic_now, true)
       # Size only: the chunk is raw wire data carrying sampling prompts,
       # elicitation content and tool results.
       @logger.debug("Processing SSE chunk (#{describe_body_size(chunk)})")
@@ -879,7 +1046,7 @@ module MCPClient
       event_buffers = extract_complete_events(chunk)
 
       # Process extracted events outside the mutex to avoid deadlocks
-      event_buffers&.each { |event_data| parse_and_handle_sse_event(event_data) }
+      event_buffers&.each { |event_data| parse_and_handle_sse_event(event_data, arrived) }
     end
 
     # Check if the error represents an authorization error
@@ -1015,16 +1182,32 @@ module MCPClient
     # @return [Array<Hash>] the prompts data
     # @raise [MCPClient::Errors::PromptGetError] if prompts list retrieval fails
     # @private
-    def request_prompts_list
+    # Drop a cached list so the next access re-fetches it (change
+    # notification, MCP 2026-07-28 caching).
+    # @param kind [Symbol] :tools, :prompts or :resources
+    # @return [void]
+    def invalidate_list_cache(kind)
       @mutex.synchronize do
-        return @prompts_data.dup if @prompts_data
+        case kind
+        when :tools
+          @tools = nil
+          @tools_data = nil
+        when :prompts
+          @prompts = nil
+          @prompts_data = nil
+        when :resources
+          @resources_result = nil
+        when :templates
+          # resources/list_changed covers resources/templates/list too.
+          @templates_result = nil
+        end
       end
+    end
 
-      # Follow nextCursor across pages so the full prompt list is returned.
-      prompts = request_paginated_list('prompts/list', 'prompts')
-
-      @mutex.synchronize { @prompts_data = prompts }
-      @mutex.synchronize { @prompts_data.dup }
+    def request_prompts_list
+      # Follow nextCursor across pages so the full prompt list is returned;
+      # the raw pages are this fetch's own (see request_tools_list).
+      request_paginated_list('prompts/list', 'prompts')
     end
 
     # Request the resources list using JSON-RPC
@@ -1032,23 +1215,11 @@ module MCPClient
     # @raise [MCPClient::Errors::ResourceReadError] if resources list retrieval fails
     # @private
     def request_resources_list
-      @mutex.synchronize do
-        return @resources_data if @resources_data
-      end
-
+      # The raw list is this fetch's own (see request_tools_list).
       result = rpc_request('resources/list')
 
-      if result && result['resources']
-        @mutex.synchronize do
-          @resources_data = result['resources']
-        end
-        return @mutex.synchronize { @resources_data.dup }
-      elsif result
-        @mutex.synchronize do
-          @resources_data = result
-        end
-        return @mutex.synchronize { @resources_data.dup }
-      end
+      return result['resources'].dup if result && result['resources']
+      return result.dup if result
 
       raise MCPClient::Errors::ResourceReadError, 'Failed to get resources list from JSON-RPC request'
     end
@@ -1058,17 +1229,11 @@ module MCPClient
     # @raise [MCPClient::Errors::ToolCallError] if tools list retrieval fails
     # @private
     def request_tools_list
-      @mutex.synchronize do
-        return @tools_data.dup if @tools_data
-      end
-
       # Follow nextCursor across pages so the full tool list is returned. The
-      # SSE parser no longer writes @tools_data per page, so this method is the
-      # sole writer and only ever caches the COMPLETE list.
-      tools = request_paginated_list('tools/list', 'tools')
-
-      @mutex.synchronize { @tools_data = tools }
-      @mutex.synchronize { @tools_data.dup }
+      # raw pages are this fetch's own: a shared copy could answer a
+      # concurrent caller under other credentials with a privately scoped
+      # list (MCP 2026-07-28 caching).
+      request_paginated_list('tools/list', 'tools')
     end
   end
 end

data/lib/mcp_client/server_stdio/child_session.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module MCPClient
+  class ServerStdio
+    # The record of one server child process: when the open subscriptions were
+    # handed to it, and when its handles were torn down. One record per
+    # process, written only by that process's own lifecycle, so nothing
+    # another thread does to another process can change what this one says.
+    #
+    # It exists for the crash-loop bound. That bound used to live in flags and
+    # a timestamp on the transport, which two restarts (or a restart and a host
+    # request that re-established the process first) raced over: whichever
+    # finished last decided what the *other* process's uptime had been, and a
+    # server that exited on sight could be respawned for ever. The question a
+    # restart actually has to answer is about one particular process — "did the
+    # last process we gave these subscriptions to die straight after we gave
+    # them to it?" — and both facts it needs are recorded here, on that
+    # process, at the two moments they happen.
+    class ChildSession
+      # @return [Float, nil] monotonic time the open subscriptions were re-sent
+      #   to this process, nil if it was never asked to carry any
+      attr_reader :carried_at
+      # @return [Float, nil] monotonic time this process's handles were torn
+      #   down, nil while it is still the live session
+      attr_reader :ended_at
+
+      def initialize
+        @carried_at = nil
+        @ended_at = nil
+        @exited_unexpectedly = false
+      end
+
+      # @return [Boolean] whether this process went on its own rather than
+      #   being torn down by the client
+      def exited_unexpectedly?
+        @exited_unexpectedly
+      end
+
+      # @return [Float] monotonic seconds
+      def self.now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      # This process has been handed the subscriptions a previous process left
+      # open. Stamped before they go out, not after: the process can exit while
+      # they are still being written, and an exit under the re-send is the
+      # clearest crash loop there is.
+      # @return [void]
+      def carrying_subscriptions
+        @carried_at = ChildSession.now
+      end
+
+      # This process is gone (its stdio handles have been torn down). First
+      # stamp wins: a host `cleanup` racing the reader's own teardown must not
+      # move the moment the process ended.
+      # @return [void]
+      def ended
+        return if @ended_at
+
+        @ended_at = ChildSession.now
+      end
+
+      # This process exited on its own — the reader saw EOF on a stdin the
+      # client had not closed (see
+      # {MCPClient::ServerStdio#handle_server_exit}). Recorded separately from
+      # {#ended}, which every teardown stamps, because only an exit is a crash.
+      # @return [void]
+      def exited_unexpectedly
+        @exited_unexpectedly = true
+      end
+
+      # Whether this process died too soon after being given the subscriptions
+      # to be given them again — the crash loop the restart bound exists to
+      # stop. A process that was never given any is not part of that loop, and
+      # one that is still alive has not ended anything.
+      #
+      # Neither is a process the client itself shut down. A host that closes
+      # the transport and reconnects — as a `cleanup`/request cycle does, and
+      # as re-authenticating or re-configuring a server does — tears the
+      # process down whenever it likes, and reading that as the server crashing
+      # closed the very subscriptions the reconnect exists to carry across.
+      # Only an exit the reader actually watched happen counts.
+      #
+      # The interval is measured from the moment it received them, so a server
+      # that is slow to start is credited with none of its own handshake, and a
+      # process that was already gone when they were sent to it (its exit
+      # stamped before the re-send) counts as having survived no time at all.
+      # @param min_uptime [Numeric] seconds it had to last (see
+      #   {MCPClient::ServerStdio::SUBSCRIPTION_RESTART_MIN_INTERVAL})
+      # @return [Boolean]
+      def died_carrying_subscriptions?(min_uptime)
+        return false unless @exited_unexpectedly && @carried_at && @ended_at
+
+        (@ended_at - @carried_at) < min_uptime
+      end
+    end
+  end
+end