rigortype 0.4.3 → 0.4.5

data/lib/rigor/lens/members.rb

@@ -14,10 +14,13 @@ module Rigor
       # @param contracts — `{[owner, scope, name] => ContractReader::Contract or nil}`
       # @param elsewhere — callable `(owner, scope, name) -> [{path, line}]`: other project files defining it
       # @param site_paths — `{site key => absolute path of its file}`, to match an inline contract's buffer
-      def initialize(sites:, omissions:, contracts:, elsewhere:, site_paths:)
+      # @param defaulted_blocks — `{[owner, scope, name] => {required, type}}`: the block a member's otherwise
+      #   defaulted inline declaration declares (ContractReader#read_defaulted_block)
+      def initialize(sites:, omissions:, contracts:, elsewhere:, site_paths:, defaulted_blocks: {})
         @sites = sites
         @omissions = omissions
         @contracts = contracts
+        @defaulted_blocks = defaulted_blocks
         @elsewhere = elsewhere
         @site_paths = site_paths
       end
@@ -25,25 +28,36 @@ module Rigor
       def build
         groups = Hash.new { |hash, key| hash[key] = [] }
         @sites.each do |site|
-          site.data["members"].each { |name| groups[[site.data["owner"], site.data["scope"], name]] << site }
+          Members.scopes_of(site.data).each do |scope|
+            site.data["members"].each { |name| groups[[site.data["owner"], scope, name]] << site }
+          end
         end
+        @groups = groups
         result = groups.sort_by { |key, _| key }.map { |key, sites| member(key, sites) }
         mark_inline_sites
         result
       end
 
+      # The scopes a site's members live in: a module function (`module_function`) defines a private instance method
+      # and a public singleton copy from one `def`.
+      def self.scopes_of(data)
+        data["module_function"] ? %w[instance singleton] : [data["scope"]]
+      end
+
       private
 
       def member(key, sites)
         owner, scope, name = key
         contract = @contracts[key]
         also = @elsewhere.call(owner, scope, name)
-        omitted = @omissions.count { |omission| [omission["owner"], omission["scope"], omission["name"]] == key }
+        omitted = @omissions.count do |omission|
+          [omission["owner"], omission["scope"]] == [owner, scope] && [name, nil].include?(omission["name"])
+        end
         single = sites.size == 1 && omitted.zero? && also.empty? ? sites.first : nil
         { "owner" => owner, "scope" => scope, "name" => name, "kind" => member_kind(sites),
-          "visibility" => common_visibility(sites), "sites" => sites.map { |site| site.data["key"] },
+          "visibility" => common_visibility(sites, scope), "sites" => sites.map { |site| site.data["key"] },
           "also_defined_at" => also, "basis" => basis(contract, single),
-          "overloads" => overloads(contract, sites.first, name, single) }
+          "overloads" => overloads(contract, sites.first, name, single, scope) }
       end
 
       # A member a `def` defines anywhere in the requested files is a method, whatever `attr_*` also names it.
@@ -58,28 +72,32 @@ module Rigor
         "contested"
       end
 
-      def common_visibility(sites)
-        values = sites.map { |site| site.data["visibility"] }.uniq
+      # A module function's singleton copy is public; its instance method carries the site's (private) visibility.
+      def common_visibility(sites, scope)
+        values = sites.map do |site|
+          copy = site.data["module_function"] && scope == "singleton"
+          copy ? site.data["singleton_visibility"] : site.data["visibility"]
+        end.uniq
         values.size == 1 ? values.first : nil
       end
 
       # A contested member without a contract has no overloads: its definitions may differ in arity, and each
       # method site carries its own parameter list.
-      def overloads(contract, site, name, single)
+      def overloads(contract, site, name, single, scope)
         return [] if contract.nil? && single.nil?
 
-        overloads = contract ? contract_overloads(contract, single) : [body_overload(site, name, single)]
+        overloads = contract ? contract_overloads(contract, single, scope) : [body_overload(site, name, single, scope)]
         overloads.map { |overload| overload.merge("rbs" => rbs_unless_unavailable(overload)) }
       end
 
       # A contract's overloads. A defaulted return (`inferred-return`) is inferred as for a member without a
       # contract, and its `untyped` parameters are unknown: Rigor cannot tell an authored `untyped` from a
       # defaulted one.
-      def contract_overloads(contract, single)
+      def contract_overloads(contract, single, scope)
         contract.overloads.map do |overload|
           next overload.except("return_rbs") unless contract.return_inferred
 
-          slot = inferred_return(single)
+          slot = inferred_return(single, scope)
           params = overload["params"]&.map do |param|
             param["type"]["type"] == "untyped" ? param.merge("type" => Slot.unavailable("not_computed")) : param
           end
@@ -92,16 +110,58 @@ module Rigor
 
       # A member with no contract: its parameters as written, each `untyped` with ADR-75's undeclared-parameter
       # cause, and the return from its one body.
-      def body_overload(site, name, single)
+      def body_overload(site, name, single, scope)
         return attribute_overload(name, single) if site.data["kind"] == "attribute"
 
-        params, block, head = Parameters.read(site.node.parameters, yields: Parameters.yields?(site.node.body))
-        slot = inferred_return(single)
-        block_rbs = block ? " ?{ (?) -> untyped }" : ""
+        node = site.data["alias_of"] ? resolved_alias(site) : site.node
+        return unknown_overload if node.nil?
+
+        params, block, head = Parameters.read(node.parameters, yields: Parameters.yields?(node.body))
+        slot = inferred_return(single, scope)
+        declared = !site.data["alias_of"] && @defaulted_blocks[[site.data["owner"], scope, name]]
+        block = declared || block
+        block_rbs = block_spelling(block, declared)
         { "rbs" => "#{head}#{block_rbs} -> #{return_spelling(slot)}", "params" => params, "block" => block,
           "return" => slot }
       end
 
+      # A block an otherwise defaulted declaration declares reads as declared (`{ (Integer) -> void }`); one the
+      # definition merely takes reads as `?{ (?) -> untyped }`.
+      def block_spelling(block, declared)
+        return "" if block.nil?
+        return " ?{ (?) -> untyped }" unless declared
+
+        " #{'?' unless declared['required']}{ #{declared['type']['type']} }"
+      end
+
+      # An alias whose original Rigor cannot pin to one `def`: nothing about its signature is known.
+      def unknown_overload
+        { "rbs" => nil, "params" => nil, "block" => nil, "return" => Slot.unavailable("not_computed") }
+      end
+
+      # The `def` an alias site copied, when its original has no other project definition (one site in the
+      # requested files, no omission naming it, none elsewhere) and no contract. Otherwise which `def` Ruby copied
+      # depends on load order, and `check` reads the last one it saw.
+      def resolved_alias(site)
+        node = site.data["aliased_node"]
+        return nil if node.nil?
+
+        owner = site.data["owner"]
+        old_name = site.data["alias_of"]
+        omitted = @omissions.any? do |omission|
+          [omission["owner"], omission["scope"]] == [owner, "instance"] && [old_name, nil].include?(omission["name"])
+        end
+        olds = @groups.fetch([owner, "instance", old_name], [])
+        return nil if omitted || olds.size != 1 || !@elsewhere.call(owner, "instance", old_name).empty?
+        # The original's contract is not the alias's: whether a declaration carries it over (`alias` in RBS) or
+        # not (`alias_method` under rbs-inline), the alias's undeclared parameters would contradict it.
+        return nil if @contracts[[owner, "instance", old_name]]
+        # An alias of an alias holds only if the alias it copied does.
+        return nil if olds.first.data["alias_of"] && resolved_alias(olds.first).nil?
+
+        node
+      end
+
       # An attribute without a contract: Rigor does not report the ivar's type in revision 1.
       def attribute_overload(name, _single)
         unknown = Slot.unavailable("not_computed")
@@ -113,10 +173,14 @@ module Rigor
         end
       end
 
-      def inferred_return(single)
+      # A module function's singleton copy has its own return reading (`singleton_body_return`).
+      def inferred_return(single, scope)
         return Slot.unavailable("contested") unless single
 
-        body = single.data["body_return"]
+        return Slot.unavailable("not_computed") if single.data["alias_of"] && resolved_alias(single).nil?
+
+        copy = single.data["module_function"] && scope == "singleton"
+        body = copy ? single.data["singleton_body_return"] : single.data["body_return"]
         return Slot.unavailable("not_computed") if body.nil?
         return body if Slot.unavailable?(body)
 

data/lib/rigor/lens/run.rb

@@ -18,7 +18,7 @@ module Rigor
     # The check-equivalent computation behind `rigor lens` (docs/internal-spec/lens.md § Computation). The session
     # is the `--incremental` one rooted at the configuration's `paths:`, so it shares the snapshot with
     # `rigor check --incremental`; the targets are forced into the run and read inside it, on the seeded index.
-    class Run
+    class Run # rubocop:disable Metrics/ClassLength
       # One target's answer: `status` is `ok` or a failure reason; the rest is set only for `ok`.
       Target = Data.define(:argument, :path, :absolute, :status, :reason, :reader, :diagnostics, :inputs)
       Outcome = Data.define(:targets, :member_rows, :plugins, :warm)
@@ -78,6 +78,7 @@ module Rigor
       def reset_captures
         @captured = {}
         @contracts = {}
+        @defaulted_blocks = {}
         @site_paths = {}
       end
 
@@ -127,16 +128,84 @@ module Rigor
                                 spell: speller(scope.environment)).read
         reader.sites.each do |site|
           @site_paths[site.data["key"]] = absolute
-          site.data["members"].each { |name| read_contract(site.data["owner"], site.data["scope"], name, scope) }
+          read_constant_value(site, scope) if site.data["kind"] == "constant"
+          Members.scopes_of(site.data).product(site.data["members"]).each do |member_scope, name|
+            read_contract(site.data["owner"], member_scope, name, scope)
+          end
         end
         @captured[absolute] = reader
       end
 
+      # The constant's type as `check` reads it ({Reflection.constant_type_for}): the value the project's source
+      # publishes for the name (every write joined, a mutated one widened) over any declaration, else its RBS
+      # declaration, else unknown.
+      def read_constant_value(site, scope)
+        name = site.data["name"]
+        published = scope.in_source_constants[name]
+        site.data["value"] =
+          if published
+            published_slot(published, scope.environment)
+          else
+            declared_slot(site, contract_reader(scope.environment).read_constant(name, scope.environment), scope)
+          end
+      end
+
+      # The rbs-inline plugin declares every constant of a file it reads, typing an unannotated one from its
+      # literal (`[]` as `Array[untyped]`), and reads only a `#:` trailing the assignment as its type: an inline
+      # declaration is the constant's own only when that is the site's one contract comment. Otherwise it is the
+      # plugin's default, which `check` reads all the same: that type, `inferred`. A `Class.new` / `Module.new`
+      # value is the exception, which `check` types through its own write reading, not the default `untyped`.
+      # An inline declaration from another file says nothing about this site: when the name is written in two
+      # files, the one the environment kept decides, and this site's own comment may say otherwise.
+      def declared_slot(site, declared, scope)
+        return Slot.unavailable("not_computed") if declared.nil?
+        return declared unless declared["provenance"] == "inline"
+        return Slot.unavailable("not_computed") unless own_inline_declaration?(site, scope)
+        return declared if trailing_type?(site)
+        return Slot.unavailable("not_computed") if anonymous_namespace?(site.node.value)
+
+        published_slot(scope.environment.constant_for_name(site.data["name"]), scope.environment)
+      end
+
+      def own_inline_declaration?(site, scope)
+        buffer = scope.environment.rbs_loader&.constant_declaration(site.data["name"])&.last
+        path = @site_paths.fetch(site.data["key"])
+        buffer&.end_with?(":#{path}") || false
+      end
+
+      def anonymous_namespace?(node)
+        return false unless node.is_a?(Prism::Node)
+        return true if node.is_a?(Prism::CallNode) && node.name == :new && node.receiver &&
+                       %w[Class Module].include?(node.receiver.slice.delete_prefix("::"))
+
+        node.compact_child_nodes.any? { |child| anonymous_namespace?(child) }
+      end
+
+      def trailing_type?(site)
+        comments = site.contract_comments
+        comments.size == 1 && comments.first.location.start_line == site.node.location.end_line &&
+          comments.first.location.slice.start_with?("#:")
+      end
+
+      def published_slot(type, environment)
+        return Slot.unavailable("not_computed") if type.nil?
+        return Slot.dynamic("inferred", nil) if type.is_a?(Type::Dynamic)
+
+        spelled = speller(environment).call(type, nil)
+        spelled == "untyped" ? Slot.dynamic("inferred", nil) : Slot.typed(spelled, "inferred")
+      rescue StandardError
+        Slot.unavailable("not_computed")
+      end
+
       def read_contract(owner, member_scope, name, scope)
         key = [owner, member_scope, name]
         return if @contracts.key?(key)
 
-        @contracts[key] = contract_reader(scope.environment).read(owner, member_scope.to_sym, name, scope)
+        reader = contract_reader(scope.environment)
+        @contracts[key] = reader.read(owner, member_scope.to_sym, name, scope)
+        return if @contracts[key]
+
+        @defaulted_blocks[key] = reader.read_defaulted_block(owner, member_scope.to_sym, name, scope)
       end
 
       def target(entry, diagnostics, session)
@@ -187,7 +256,7 @@ module Rigor
         sites = readers.values.flat_map(&:sites)
         omissions = readers.values.flat_map(&:omissions)
         requested = readers.keys.to_set
-        Members.new(sites: sites, omissions: omissions, contracts: @contracts,
+        Members.new(sites: sites, omissions: omissions, contracts: @contracts, defaulted_blocks: @defaulted_blocks,
                     elsewhere: elsewhere(session, requested), site_paths: @site_paths).build
       end
 

data/lib/rigor/lens.rb

@@ -9,7 +9,8 @@ module Rigor
     SCHEMA = "lens/v0"
     # Bumped on every breaking change to the `lens/v0` document (docs/internal-spec/lens.md § Status).
     REVISION = 1
-    CAPABILITIES = %w[class module method attribute body_return diagnostics inputs].freeze
+    CAPABILITIES = %w[class module method attribute constant module_function builder alias body_return
+                      diagnostics inputs].freeze
 
     module_function
 

data/lib/rigor/mcp/server.rb

@@ -63,6 +63,25 @@ module Rigor
             }
           }
         },
+        {
+          name: "rigor_lens",
+          description: "Map the classes, modules, methods and attributes the given Ruby files declare, with the " \
+                       "type `rigor check` gives each one and where that type came from (sig/, an inline " \
+                       "comment, a plugin, a library, or inference). Returns the lens/v0 JSON document " \
+                       "(experimental). Pass every file you need in one call: each call pays one analysis run.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              files: {
+                type: "array",
+                items: { type: "string" },
+                description: "Ruby files to map (required)"
+              },
+              config: { type: "string", description: "Path to .rigor.yml (optional)" }
+            },
+            required: ["files"]
+          }
+        },
         {
           name: "rigor_annotate",
           description: "Return the given Ruby source file with each line's last-expression type " \
@@ -109,8 +128,8 @@ module Rigor
             properties: {
               rule: {
                 type: "string",
-                description: "Rule ID, legacy alias, or family prefix (call, flow, assert, dump, def). " \
-                             "Omit to list every rule."
+                description: "Rule ID, legacy alias, or family prefix (call, flow, def, assert, dump, global, " \
+                             "suppression, static, effect). Omit to list every rule."
               }
             }
           }
@@ -180,13 +199,12 @@ module Rigor
         out_io = StringIO.new
         err_io = StringIO.new
         require_relative "../cli"
-        exit_code = CLI.new(argv, out: out_io, err: err_io).run
-
-        is_error = exit_code == CLI::EXIT_USAGE
-        text = out_io.string
-        text = err_io.string if text.empty? && is_error
+        exit_code = with_captured_streams(out_io, err_io) { CLI.new(argv, out: out_io, err: err_io).run }
 
-        success(id, { content: [{ type: "text", text: text }], isError: is_error })
+        success(id, tool_result(out_io.string, err_io.string, exit_code))
+      rescue SystemExit => e
+        # Defence against any command that exits: it must not take the server down with it.
+        success(id, { content: [{ type: "text", text: "Command exited (status #{e.status})" }], isError: true })
       rescue StandardError => e
         @err.puts("rigor mcp: #{e.class}: #{e.message}")
         @err.puts(e.backtrace.first(5).join("\n")) if e.backtrace
@@ -196,6 +214,26 @@ module Rigor
                 })
       end
 
+      # A non-zero exit with nothing on stdout printed only an error; exit 1 with a document (check, lens) is a
+      # result, not an error.
+      def tool_result(out, err, exit_code)
+        is_error = [CLI::EXIT_USAGE, CLI::EXIT_INTERNAL_ERROR].include?(exit_code) || (out.empty? && !exit_code.zero?)
+        { content: [{ type: "text", text: out.empty? ? err : out }], isError: is_error }
+      end
+
+      # The JSON-RPC channel is the process's stdout, so nothing a command writes past its `out:` (an option
+      # parser's `--help`, a stray `puts`) may reach it while the command runs.
+      def with_captured_streams(out_io, err_io)
+        stdout = $stdout
+        stderr = $stderr
+        $stdout = out_io
+        $stderr = err_io
+        yield
+      ensure
+        $stdout = stdout
+        $stderr = stderr
+      end
+
       def build_argv(name, args) # rubocop:disable Metrics/MethodLength,Metrics/CyclomaticComplexity,Metrics/AbcSize,Metrics/PerceivedComplexity
         effective_config = args["config"] || @config_path
 
@@ -203,49 +241,52 @@ module Rigor
         when "rigor_check"
           argv = ["check", "--format=json", "--no-stats"]
           argv << "--config=#{effective_config}" if effective_config
-          argv += Array(args["paths"])
-          argv
+          argv + ["--", *Array(args["paths"])]
 
         when "rigor_type_of"
           return nil unless args["file"] && args["line"] && args["col"]
 
           argv = ["type-of", "--format=json"]
           argv << "--config=#{effective_config}" if effective_config
-          argv << "#{args['file']}:#{args['line']}:#{args['col']}"
-          argv
+          # `--` ends the options, so a file named like a flag is a file.
+          argv + ["--", "#{args['file']}:#{args['line']}:#{args['col']}"]
 
         when "rigor_triage"
           argv = ["triage", "--format=json"]
           argv << "--config=#{effective_config}" if effective_config
           argv << "--top=#{args['top']}" if args["top"]
-          argv += Array(args["paths"])
-          argv
+          argv + ["--", *Array(args["paths"])]
+
+        when "rigor_lens"
+          files = args["files"]
+          return nil unless files.is_a?(Array) && !files.empty? && files.all?(String)
+
+          argv = ["lens", "--format=json"]
+          argv << "--config=#{effective_config}" if effective_config
+          # `--` ends the options, so a file named like a flag (`--version`) is a file.
+          argv + ["--", *files]
 
         when "rigor_annotate"
           return nil unless args["file"]
 
           argv = ["annotate", "--no-color"]
           argv << "--config=#{effective_config}" if effective_config
-          argv << args["file"]
-          argv
+          argv + ["--", args["file"]]
 
         when "rigor_sig_gen"
           argv = ["sig-gen", "--print", "--format=json"]
           argv << "--config=#{effective_config}" if effective_config
           argv << "--params=#{args['params']}" if args["params"]
-          argv += Array(args["paths"])
-          argv
+          argv + ["--", *Array(args["paths"])]
 
         when "rigor_explain"
           argv = ["explain", "--format=json"]
-          argv << args["rule"] if args["rule"]
-          argv
+          args["rule"] ? argv + ["--", args["rule"]] : argv
 
         when "rigor_coverage"
           argv = ["coverage", "--format=json"]
           argv << "--config=#{effective_config}" if effective_config
-          argv += Array(args["paths"])
-          argv
+          argv + ["--", *Array(args["paths"])]
         end
       end
 

data/lib/rigor/plugin/base.rb

@@ -13,6 +13,7 @@ require_relative "../cache/engine_source"
 # plugin class body can be evaluated before anything else pulled the cache layer in.
 require_relative "../cache/store"
 require_relative "../source/node_walker"
+require_relative "../rooted_glob"
 
 module Rigor
   module Plugin
@@ -1003,7 +1004,7 @@ module Rigor
       # plugin code calls `watch:`.
       #
       # @param roots — search roots (relative to the project root, or absolute paths)
-      # @param patterns — glob suffixes joined under each root via `File.join(root, pattern)`.
+      # @param patterns — glob suffixes matched under each root, the root read literally (#1956).
       #   Multiple patterns union into one descriptor (`"**/*.erb", "**/*.html"` etc.).
       def glob_descriptor(roots, *patterns)
         files = collect_glob_files(Array(roots), patterns)
@@ -1163,7 +1164,7 @@ module Rigor
           absolute = File.absolute_path(root.to_s)
           next [] unless File.directory?(absolute)
 
-          patterns.flat_map { |pattern| Dir.glob(File.join(absolute, pattern.to_s)) }
+          patterns.flat_map { |pattern| RootedGlob.glob(absolute, pattern) }
         end
         matched.uniq.sort.select { |path| File.file?(path) }
       end

data/lib/rigor/plugin/box_probe.rb

@@ -15,7 +15,8 @@ module Rigor
     # under `RUBY_BOX=1` and must print the right answer. That admits a 4.1.0dev build with the fix and a
     # future 4.0.x that backports it, and refuses a development build cut before the fix — none of which a
     # `RUBY_VERSION` bound gets right. The probe costs one short-lived `ruby --disable-gems` process, paid
-    # only when a run opts into `ruby_box`.
+    # only when a run opts into `ruby_box` or starts with `RUBY_BOX` already set, and only once per Ruby
+    # build: {cached_unsupported_reason} remembers the verdict.
     #
     # Loaded by `exe/rigor` before anything else, so this file requires nothing from Rigor.
     module BoxProbe
@@ -36,20 +37,166 @@ module Rigor
       # counted as a failure, so a wedged probe cannot hang the launcher (or `rigor lsp` behind it).
       DEADLINE_SECONDS = 10
 
+      # Set on the environment of every re-exec this module asks for, so the re-exec'ed launcher neither
+      # probes again nor re-execs again. The launcher deletes it before Rigor loads, so nothing Rigor spawns
+      # inherits it.
+      REEXEC_MARKER = "RIGOR_BOX_PROBED"
+
+      # The signals the bug's NULL-box dereference ends a child with. A child killed by any other signal
+      # (an OOM killer's `SIGKILL`, an operator's `SIGTERM`) is still refused, but that verdict is not cached.
+      CRASH_SIGNALS = %w[SEGV BUS ABRT ILL].freeze
+
+      CACHE_FORMAT = "rigor-box-probe-v1"
+
       module_function
 
+      # Decides what `exe/rigor` does before Rigor loads, editing `env` (the real `ENV` in the launcher) in
+      # place. Returns true when the launcher must re-exec itself with `env` as now edited.
+      #
+      # - `RUBY_BOX` already set (by hand or by a wrapper), and `Ruby::Box` active in this process: the
+      #   process booted inside the box before any Rigor code ran, so on a Ruby without the Bug #22260 fix
+      #   the first Ractor-shareable lambda Rigor calls segfaults. Probe (through the cache); when the Ruby
+      #   is refused, print a notice, drop `RUBY_BOX` and the `ruby_box` request, and re-exec. When it
+      #   passes, keep `RUBY_BOX` as the user set it.
+      # - `ruby_box` requested and `RUBY_BOX` unset: probe; re-exec under `RUBY_BOX=1` when it passes,
+      #   otherwise warn and drop the request.
+      # - Otherwise nothing.
+      def needs_reexec?(env, stderr: $stderr, box_active: box_active?, cache_dir: default_cache_dir(env))
+        return false if env.delete(REEXEC_MARKER)
+
+        if env["RUBY_BOX"].to_s.empty?
+          reexec_for_box_request?(env, stderr, cache_dir)
+        else
+          reexec_without_preset_box?(env, stderr, box_active, cache_dir)
+        end
+      end
+
+      def reexec_for_box_request?(env, stderr, cache_dir)
+        isolation = env["RIGOR_PLUGIN_ISOLATION"].to_s
+        return false unless isolation == "ruby_box" || !env["RIGOR_BOX"].to_s.empty?
+
+        if (reason = cached_unsupported_reason(cache_dir: cache_dir))
+          # `puts` on stderr, not `warn`: `-W0` silences `warn`, and this fallback must never be silent.
+          stderr.puts "rigor: ruby_box plugin isolation is unavailable: #{reason}. " \
+                      "Falling back to the configured plugins_isolation strategy (default: process)."
+          drop_box_request(env)
+          false
+        else
+          env["RUBY_BOX"] = "1"
+          env["RIGOR_PLUGIN_ISOLATION"] = "ruby_box" if isolation.empty?
+          env[REEXEC_MARKER] = "1"
+          true
+        end
+      end
+
+      def reexec_without_preset_box?(env, stderr, box_active, cache_dir)
+        return false unless box_active
+
+        reason = cached_unsupported_reason(cache_dir: cache_dir)
+        return false unless reason
+
+        stderr.puts "rigor: RUBY_BOX is set, but #{reason}. " \
+                    "Re-running without RUBY_BOX; plugins will not run inside Ruby::Box."
+        env.delete("RUBY_BOX")
+        drop_box_request(env)
+        env[REEXEC_MARKER] = "1"
+        true
+      end
+
+      def drop_box_request(env)
+        env.delete("RIGOR_PLUGIN_ISOLATION") if env["RIGOR_PLUGIN_ISOLATION"].to_s == "ruby_box"
+        env.delete("RIGOR_BOX")
+      end
+
+      # Whether this process booted inside `Ruby::Box`. False on a Ruby without the feature, which ignores
+      # `RUBY_BOX`, so a preset variable there costs nothing.
+      def box_active?
+        return false unless defined?(::Ruby::Box) && ::Ruby::Box.respond_to?(:enabled?)
+
+        ::Ruby::Box.enabled? == true
+      end
+
+      # `$XDG_CACHE_HOME/rigor` when that is an absolute path, else `$HOME/.cache/rigor` when `HOME` is an
+      # absolute path (the passwd entry when `HOME` is unset); nil otherwise, which turns the cache off
+      # rather than writing under the working directory.
+      def default_cache_dir(env)
+        xdg = env["XDG_CACHE_HOME"].to_s
+        return File.join(xdg, "rigor") if xdg.start_with?("/")
+
+        home = env.key?("HOME") ? env["HOME"].to_s : Dir.home
+        File.absolute_path?(home) ? File.join(home, ".cache", "rigor") : nil
+      rescue ArgumentError
+        nil
+      end
+
+      # {unsupported_reason}, remembered per Ruby build so a launcher that probes on every run pays for the
+      # child process once. A pass is stored only when the child printed the right answer, and a refusal
+      # only when it is a property of the Ruby (no `Ruby::Box`, or a crash signal); a probe that could not
+      # run, timed out, or failed some other way is answered but not stored. An unreadable or corrupt
+      # cache file reads as a miss; a write that fails is ignored.
+      def cached_unsupported_reason(ruby = RbConfig.ruby, cache_dir:)
+        path = cache_dir && cache_path(cache_dir, ruby)
+        cached = path && read_cache(path)
+        return cached[:reason] if cached
+
+        reason, cacheable = verdict(ruby)
+        write_cache(path, reason) if path && cacheable
+        reason
+      end
+
+      # The cache file for `ruby`: keyed on the Ruby build that runs the launcher (its version, patch level,
+      # revision and description) together with the executable path and the probe script itself.
+      def cache_path(cache_dir, ruby)
+        require "digest/sha2"
+        key = [RUBY_VERSION, RUBY_PATCHLEVEL, RUBY_REVISION, RUBY_DESCRIPTION, File.expand_path(ruby), SCRIPT]
+        File.join(cache_dir, "ruby-box-probe", Digest::SHA256.hexdigest(key.join("\0")))
+      end
+
+      def read_cache(path)
+        format, verdict, reason = File.read(path).split("\n", 3)
+        return nil unless format == CACHE_FORMAT
+
+        case verdict
+        when "pass" then reason.nil? ? { reason: nil } : nil
+        when "fail" then reason.to_s.chomp.empty? ? nil : { reason: reason.chomp }
+        end
+      rescue SystemCallError, IOError, ArgumentError
+        nil
+      end
+
+      def write_cache(path, reason)
+        require "fileutils"
+        FileUtils.mkdir_p(File.dirname(path))
+        body = reason ? "#{CACHE_FORMAT}\nfail\n#{reason}\n" : "#{CACHE_FORMAT}\npass"
+        temp = "#{path}.#{::Process.pid}.tmp"
+        File.write(temp, body)
+        File.rename(temp, path)
+      rescue SystemCallError, IOError
+        nil
+      end
+
       # nil when `ruby` can run Rigor under `RUBY_BOX=1`; otherwise a short reason for the launcher's
       # warning. Only a child killed by a signal is blamed on the bug; any other failure to answer is
       # reported as the probe failing, never as a pass.
       def unsupported_reason(ruby = RbConfig.ruby)
+        verdict(ruby).first
+      end
+
+      # `[reason, cacheable]` — {unsupported_reason}'s answer, and whether it is a property of the Ruby
+      # build rather than of this one attempt.
+      def verdict(ruby)
         output, status = run(ruby)
-        return "the Ruby::Box probe could not run #{ruby}" if status.nil?
-        return nil if status.success? && output == EXPECTED_OUTPUT
-        return "Ruby::Box is not available in Ruby #{RUBY_VERSION}" if status.exitstatus == 2
-        return "the Ruby::Box probe failed (#{status})" unless status.signaled?
+        return ["the Ruby::Box probe could not run #{ruby}", false] if status.nil?
+        return [nil, true] if status.success? && output == EXPECTED_OUTPUT
+        return ["Ruby::Box is not available in Ruby #{RUBY_VERSION}", true] if status.exitstatus == 2
+        return ["the Ruby::Box probe failed (#{status})", false] unless status.signaled?
+
+        ["Ruby #{RUBY_VERSION} crashes running Ractor-shareable procs inside Ruby::Box " \
+         "(Ruby Bug #22260; a Ruby carrying its fix is needed)", crash_signal?(status.termsig)]
+      end
 
-        "Ruby #{RUBY_VERSION} crashes running Ractor-shareable procs inside Ruby::Box " \
-          "(Ruby Bug #22260; a Ruby carrying its fix is needed)"
+      def crash_signal?(signo)
+        CRASH_SIGNALS.any? { |name| Signal.list[name] == signo }
       end
 
       # `RUBYOPT` is cleared so a `-r` of the caller's (bootsnap, a debugger, a coverage hook) cannot fail