rails-ai-context 5.20.2 → 5.20.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 81eedfa398603e64a27f7555b4288e39a11e41093c3a06450354c2f5cb1d17c5
-  data.tar.gz: 34972bf4259e8e12695f008744111bff94ed7caa93155bd3f8352010e3134c15
+  metadata.gz: 812fc2b5160e39c746e9d399bf6cea5752339f53c57a80f3ce0d01a5e819b7d0
+  data.tar.gz: 22254f62db474a0f0b7f364f156b3098819b52285e88df2835b32ea25c86972b
 SHA512:
-  metadata.gz: c88339dc6c73a5fdb38209d69e61437a6494382c069ae943478e51a265e57b2b847d4cb89f22ef0449c024bdb43185feef7e58a5e92f199c0a0389f4822898ca
-  data.tar.gz: 2f0a283b5691f00d4f49aeed839da56af13e248f566c9a526e3926cbc0c71185cf2e99a9b809d5e316d7e1144826456bb65ea36148493b4102f44b3bf0857584
+  metadata.gz: 4eddc9f145293be65bc99e9b0dd5334de7570ef217df4dca4f554c191ae314bd6544ed16f49be013a2db93c3394e49f02204c1d76c1c256d7394881ea273eb81
+  data.tar.gz: 53e469b48920a4baefe955ff90624199f60200a6759d180a02d040d4c1368322d0b9648637fe4a13d20cf1ecc9153d3b7a1b041e1d41ae835c7a8e523cfd4bdf

data/CHANGELOG.md

@@ -5,6 +5,79 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.20.3] - 2026-08-11
+
+### Fixed
+
+- **`serve --transport http` no longer answers "Session not found" to about half
+  of all requests.** Rackup hands Puma the host app's `config/puma.rb`, and a
+  real app sets `workers` there, so the transport ran as a cluster - but MCP
+  sessions live in one process's memory, and a forked worker cannot answer a
+  request whose `initialize` a sibling handled. Puma is now pinned to single
+  mode. Both options are load-bearing: refusing the config file still leaves
+  `WEB_CONCURRENCY` able to start a cluster on its own, and pinning the worker
+  count still lets the file's `pidfile` and `preload_app!` through - the pidfile
+  being one this server would otherwise write over the app's own. (#123)
+
+- **A gem's background job is no longer counted as the app's.** `extract_jobs`
+  filtered `ActiveJob::Base.descendants` with a list of framework name
+  prefixes, which no list can keep up with: on an app with 118 Sidekiq workers
+  and no ActiveJob of its own, the generated `CLAUDE.md` read `Async: 1 job`
+  and that job was an indexing worker belonging to a gem. Ownership is now
+  decided by where the class is defined. A class with no source location is
+  kept, because understating what the app runs is the worse mistake. (#120)
+
+- **`get_job_pattern` now names the queues `config/sidekiq.yml` declares.**
+  `extract_sidekiq_config` already read them; holding the result back left the
+  answer describing `app/jobs/` and nothing else, on an app whose sidekiq.yml
+  is the one piece of evidence in reach that async work happens elsewhere. It
+  reaches the job listing as well as the empty-directory message - a count of
+  what `app/jobs/` holds is still a claim about the app's async work, and on an
+  app running most of it through Sidekiq that count is the small half. (#120)
+
+- **The context no longer carries `static_parse` as a database name.**
+  `SchemaIntrospector` writes that placeholder when it reads a dump instead of
+  the connection, and laundering it at each rendering surface left the ones
+  nobody thought of - `.ai-context.json` and `rails://schema` - naming a
+  database that does not exist beside a `multi_database` section in the same
+  file naming the real one. It is now resolved once, where the context is
+  assembled, so nothing downstream has to remember. The raw observation stays
+  under `adapter_source`. (#128)
+
+- **The static tier follows `draw` into `config/routes/*.rb`.** An app that
+  splits its routing table that way kept most of it in files the parser never
+  opened: `--no-boot` answered 94 routes on a 723-route app. Rails resolves
+  `draw(:admin)` by literal path, so following it is a plain file read; the
+  resolved path is confirmed inside `config/routes/` with `realpath` first, so
+  a symlink there cannot reach the rest of the disk. (#127)
+
+- **Every surface that prints a route count says how much of the table it
+  could not expand.** `RouteIntrospector` recorded `dynamic_routes` for
+  constructs it refused to fabricate (`devise_for`, a `draw` whose target is
+  computed or too large to parse) and nothing read it, so `rails_get_routes`,
+  `rails_onboard`, `CLAUDE.md`, the Cursor and Copilot rule files, the markdown
+  context and the rake summary all quoted a partial count as the whole routing
+  table. `RouteCoverage` is the one answer they now share, shaped as a suffix
+  so no call site needs a conditional of its own - nine each having to remember
+  is what produced this. A `draw` whose routes are in the list does not count,
+  whether this pass read the file or an earlier branch did; one stopped by the
+  depth cap, or naming a file too large to parse, does. A drawn file that
+  cannot be parsed costs its own routes rather than the whole section. (#127)
+
+- **The static tier counts an update route once.** Rails registers PATCH and
+  PUT separately for one action and every surface that lists routes merges
+  them, but the static total did not - so the generated files said "8 total"
+  where `rails_get_routes`, which merges for itself, said 7 on the same
+  `resources :posts`. (#127)
+
+### Changed
+
+- `actionmailer` and `puma` are development dependencies now. Without
+  ActionMailer loaded, `ActionMailer::Base` is undefined and every assertion
+  about mailer actions passed over an empty array; the Puma single-mode pin is
+  only testable against Puma's own option semantics. Neither affects the
+  gem's runtime dependencies. (#123, #126)
+
 ## [5.20.2] - 2026-08-11
 
 ### Fixed

data/gemfiles/prism_floor.gemfile

@@ -15,6 +15,8 @@ rails_version = ENV.fetch("RAILS_VERSION", "8.0")
 group :development, :test do
   gem "railties", "~> #{rails_version}.0"
   gem "activerecord", "~> #{rails_version}.0"
+  gem "actionmailer", "~> #{rails_version}.0"
+  gem "puma"
   gem "sqlite3"
   gem "logger"
 end

data/gemfiles/prism_head.gemfile

@@ -14,6 +14,8 @@ rails_version = ENV.fetch("RAILS_VERSION", "8.0")
 group :development, :test do
   gem "railties", "~> #{rails_version}.0"
   gem "activerecord", "~> #{rails_version}.0"
+  gem "actionmailer", "~> #{rails_version}.0"
+  gem "puma"
   gem "sqlite3"
   gem "logger"
 end

data/lib/rails_ai_context/introspector.rb

@@ -48,6 +48,8 @@ module RailsAiContext
       end
       context[:_warnings] = warnings if warnings.any?
 
+      resolve_schema_adapter(context)
+
       context
     end
 
@@ -99,6 +101,41 @@ module RailsAiContext
 
     private
 
+    # `SchemaIntrospector` writes `static_parse` when it read a dump instead of
+    # the connection, and every surface that rendered the section raw named a
+    # database that does not exist. Fixing that one surface at a time meant
+    # `.ai-context.json` and `rails://schema` still disagreed with the
+    # multi_database section of the same file. Resolving it here means the
+    # context never carries the placeholder, so nothing downstream has to
+    # remember. The raw observation stays under `adapter_source` for a reader
+    # that needs to know the schema was parsed rather than observed.
+    #
+    # Runs after the loop: the answer comes from the database config and gem
+    # list, which are sections of this same context.
+    #
+    # Rescued for the same reason the loop above is: this reads two other
+    # sections, and a malformed one raising here would cost the whole context
+    # rather than one entry. The placeholder surviving is the honest failure.
+    def resolve_schema_adapter(context)
+      schema = context[:schema]
+      return unless schema.is_a?(Hash) && !schema[:error]
+      # Only correct a claim that was made. A missing or nil adapter said
+      # nothing about the database, and answering for it would be the
+      # fabrication this method exists to remove.
+      return if schema[:adapter].nil?
+      return unless SchemaAdapter.placeholder?(schema[:adapter])
+
+      # "unknown" is a placeholder too. Swapping one for another buys nothing
+      # and would bury the parse mode that at least says how the schema was read.
+      resolved = SchemaAdapter.label(context)
+      return if SchemaAdapter.placeholder?(resolved)
+
+      schema[:adapter_source] = schema[:adapter]
+      schema[:adapter] = resolved
+    rescue StandardError => e
+      RailsAiContext.log_warn "[rails-ai-context] schema adapter resolution failed: #{e.message}"
+    end
+
     def app_name
       return File.basename(app.root.to_s) if app.is_a?(RailsAiContext::StaticApp)
 

data/lib/rails_ai_context/introspectors/job_introspector.rb

@@ -2,8 +2,10 @@
 
 module RailsAiContext
   module Introspectors
-    # Discovers background jobs (ActiveJob/Sidekiq), mailers,
-    # and Action Cable channels.
+    # Discovers ActiveJob jobs, mailers, and Action Cable channels. Sidekiq
+    # reaches this only as config/sidekiq.yml: a class that includes
+    # Sidekiq::Worker without subclassing ActiveJob::Base is not a descendant
+    # and does not live in app/jobs/, so neither pass here finds it.
     class JobIntrospector
       extend StaticTier
       static_tier :alternate_source
@@ -52,6 +54,7 @@ module RailsAiContext
         ActiveJob::Base.descendants.filter_map do |job|
           next if job.name.nil? || job.name == "ApplicationJob" ||
                   job.name.start_with?("ActionMailer", "ActiveStorage::", "ActionMailbox::", "Turbo::", "Sentry::")
+          next unless app_defined?(job)
 
           queue = job.queue_name
           queue = "dynamic" if queue.is_a?(Proc)
@@ -67,6 +70,26 @@ module RailsAiContext
         []
       end
 
+      # `descendants` is every ActiveJob subclass in the process, and the name
+      # prefixes above only cover the framework's own - a job from any other gem
+      # was counted as the app's. Where the class is defined answers it for gems
+      # the list has never heard of. A class with no source location stays:
+      # dropping one would understate what the app runs.
+      def app_defined?(job)
+        location = Object.const_source_location(job.name)&.first
+        return true unless location
+
+        File.realpath(location).start_with?("#{app_root_real}/")
+      rescue NameError, ArgumentError, TypeError, SystemCallError
+        true
+      end
+
+      def app_root_real
+        @app_root_real ||= File.realpath(app.root.to_s)
+      rescue SystemCallError
+        @app_root_real = app.root.to_s
+      end
+
       def extract_jobs_from_source
         jobs_dir = File.join(app.root, "app", "jobs")
         return [] unless Dir.exist?(jobs_dir)
@@ -255,10 +278,11 @@ module RailsAiContext
         []
       end
 
-      # A mailer's actions are its public instance methods. The booted side asks
-      # `action_methods`, which also subtracts inherited and internal ones - the
-      # AST cannot see that, so a public helper on a concrete mailer is still
-      # listed here and not there.
+      # A mailer's actions are its public instance methods, and the AST sees
+      # one file at a time. `action_methods` counts the public methods a mailer
+      # inherits too, so a public helper on a base class is an action the
+      # booted tier reports and this one cannot - the entries are tagged STATIC
+      # for that reason.
       def extract_mailers_from_source
         source_classes(File.join(app.root, "app", "mailers")).filter_map do |name, methods|
           next if name == "ApplicationMailer"

data/lib/rails_ai_context/introspectors/listeners/routes_dsl_listener.rb

@@ -272,7 +272,17 @@ module RailsAiContext
         def emit_dynamic(node)
           return if suppressed?
 
-          @results << { type: :dynamic, macro: node.name, location: node.location.start_line }
+          record = { type: :dynamic, macro: node.name, location: node.location.start_line }
+          # `draw(:admin)` names a file, and Rails resolves it by literal path.
+          # Recording the name is what lets the introspector follow it instead
+          # of writing off everything the file defines.
+          record[:target] = draw_target(node) if node.name == :draw
+          @results << record
+        end
+
+        def draw_target(node)
+          target = extract_first_symbol(node)
+          target unless target == RailsAiContext::Confidence::INFERRED
         end
 
         # Keyword options including hash-rocket string keys, so

data/lib/rails_ai_context/introspectors/route_introspector.rb

@@ -8,6 +8,10 @@ module RailsAiContext
       extend StaticTier
       static_tier :alternate_source
 
+      # A drawn file can draw again. Rails allows it; this stops a cycle of
+      # symlinked or mutually-drawing files from walking forever.
+      MAX_DRAW_DEPTH = 5
+
       attr_reader :app
 
       def initialize(app)
@@ -38,7 +42,8 @@ module RailsAiContext
         { error: e.message }
       end
 
-      # Static tier: answer route questions from config/routes.rb alone.
+      # Static tier: answer route questions from config/routes.rb and the
+      # files it draws.
       # Output mirrors the runtime shape exactly so tools, resources, and
       # serializers need no static-awareness of their own. Routes behind
       # dynamic constructs (devise_for, draw, concerns) are counted in
@@ -47,21 +52,23 @@ module RailsAiContext
         routes_path = File.join(app.root.to_s, "config", "routes.rb")
         return { error: "config/routes.rb not found in #{app.root}" } unless File.exist?(routes_path)
 
-        ast = SourceIntrospector.walk(routes_path, {
-          routes: -> { Listeners::RoutesDslListener.new },
-          mounts: -> { Listeners::MountListener.new }
-        })
-        records = ast[:routes] || []
+        records, mounts, files = walk_routes_file(routes_path)
         entries = records.select { |r| r[:type] == :route }
-        dynamic = records.count { |r| r[:type] == :dynamic }
+        # A followed `draw` is no longer unexpanded - its routes are in the
+        # list above. Counting it would overstate what is missing by exactly
+        # the number of files this pass just read.
+        dynamic = records.count { |r| r[:type] == :dynamic && !r[:followed] }
 
         result = {
-          total_routes: entries.size,
+          # Merged, for the reason `call` gives above: a raw total here made the
+          # generated files say "8 total" where rails_get_routes, which merges
+          # for itself, said 7 on the same `resources :posts`.
+          total_routes: Tools::BaseTool.dedupe_put_patch_routes(entries).size,
           by_controller: group_by_controller(entries),
           api_namespaces: static_api_namespaces(entries),
-          mounted_engines: (ast[:mounts] || []).map { |m| { engine: m[:engine], path: m[:path] } },
+          mounted_engines: mounts.map { |m| { engine: m[:engine], path: m[:path] } },
           root_route: static_root_route(entries),
-          note: "Parsed statically from config/routes.rb (app not booted)",
+          note: "Parsed statically from #{static_sources_phrase(files)} (app not booted)",
           confidence: Confidence::STATIC
         }
         result[:dynamic_routes] = dynamic if dynamic.positive?
@@ -72,6 +79,95 @@ module RailsAiContext
 
       private
 
+      # An app that splits its routing table with `draw` keeps most of it in
+      # config/routes/*.rb, and reading config/routes.rb alone answered 94 on a
+      # 723-route app with nothing saying the count was partial. Rails resolves
+      # `draw(:admin)` to config/routes/admin.rb by literal path, so following
+      # it is a plain file read.
+      #
+      # Returns the merged records, mounts, and the files actually read.
+      def walk_routes_file(path, already_read = [], depth = 0)
+        return [ [], [], [] ] if depth > MAX_DRAW_DEPTH
+
+        already_read << path
+        ast = SourceIntrospector.walk(path, {
+          routes: -> { Listeners::RoutesDslListener.new },
+          mounts: -> { Listeners::MountListener.new }
+        })
+        records = ast[:routes] || []
+        mounts = ast[:mounts] || []
+        files = [ path ]
+
+        records.select { |r| r[:type] == :dynamic && r[:macro] == :draw }.each do |record|
+          target = draw_target_path(record[:target])
+          next unless target
+
+          # Two files can draw the same third one, and a cycle brings the walk
+          # back to a file it started at. Both mean the routes are already in
+          # the list, so the draw is expanded even though this branch will not
+          # read it again - and this is also what stops the recursion.
+          if already_read.include?(target)
+            record[:followed] = true
+            next
+          end
+
+          sub_records, sub_mounts, sub_files = walk_draw_target(target, already_read, depth)
+          # Only the depth cap and an unreadable file get here, and both mean
+          # routes are missing. Marking the draw followed would drop the caveat
+          # precisely where it is needed.
+          next if sub_files.empty?
+
+          record[:followed] = true
+          records.concat(sub_records)
+          mounts.concat(sub_mounts)
+          files.concat(sub_files)
+        end
+
+        [ records, mounts, files ]
+      end
+
+      # A drawn file that cannot be parsed - over AstCache's size ceiling, or
+      # syntax-broken - must cost its own routes, not the routing table. Before
+      # this walk existed only config/routes.rb could fail the whole section;
+      # letting the raise through would hand that power to every file it draws.
+      # The draw stays unmarked, so the count already says routes are missing.
+      def walk_draw_target(target, already_read, depth)
+        walk_routes_file(target, already_read, depth + 1)
+      rescue StandardError, ScriptError => e
+        $stderr.puts "[rails-ai-context] draw target #{target} skipped: #{e.message}" if ENV["DEBUG"]
+        [ [], [], [] ]
+      end
+
+      # `draw(:"admin/users")` is legal and resolves under config/routes/, but
+      # the name reaches here from source text, so the resolved path has to be
+      # confirmed inside that directory before it is read.
+      #
+      # Resolved with realpath, like safe_glob_realpath: expand_path folds
+      # `..` without following links, so a symlink under config/routes/ was
+      # enough to read a file anywhere on disk.
+      def draw_target_path(target)
+        return nil if target.nil? || target.to_s.empty?
+
+        dir = File.realpath(File.join(app.root.to_s, "config", "routes"))
+        candidate = File.realpath(File.join(dir, "#{target}.rb"))
+        return nil unless candidate.start_with?("#{dir}#{File::SEPARATOR}")
+        return nil unless File.file?(candidate)
+
+        candidate
+      rescue SystemCallError
+        # No config/routes/ at all, a dangling symlink, or a name that resolves
+        # to nothing. None of them is a route this pass can read.
+        nil
+      end
+
+      def static_sources_phrase(files)
+        root = "#{app.root}#{File::SEPARATOR}"
+        names = files.map { |f| f.delete_prefix(root) }
+        return names.first if names.size == 1
+
+        "#{names.first} and #{CountPhrase.call(names.size - 1, "file")} it draws"
+      end
+
       def extract_routes
         # Force Rails to reload routes if routes.rb has changed
         app.routes_reloader&.execute_if_updated rescue nil

data/lib/rails_ai_context/route_coverage.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  # One answer to "how much of the routing table is this number", for every
+  # surface that prints a route count.
+  #
+  # `RouteIntrospector` records the constructs it refused to fabricate -
+  # `devise_for`, a `draw` whose target is computed or too large to parse - in
+  # `:dynamic_routes`, and nothing read it. So `rails_get_routes`, `CLAUDE.md`,
+  # the Cursor and Copilot rule files, `rails_onboard` and the rake summary all
+  # quoted 94 routes on a 723-route app with nothing saying the count was
+  # partial. Nine call sites each having to remember is what produced that;
+  # this is the seam they share.
+  module RouteCoverage
+    module_function
+
+    # A suffix rather than a predicate, so no call site needs a conditional of
+    # its own - that shape is what let nine of them forget.
+    #
+    # @param routes [Hash] the :routes section of an introspection context
+    # @return [String] a leading-comma clause naming what the count leaves out,
+    #   or "" when the count is the whole table
+    def suffix(routes)
+      return "" unless routes.is_a?(Hash) && !routes[:error]
+
+      unexpanded = routes[:dynamic_routes].to_i
+      return "" unless unexpanded.positive?
+
+      ", #{CountPhrase.call(unexpanded, "dynamic construct")} not expanded"
+    end
+  end
+end

data/lib/rails_ai_context/serializers/claude_rules_serializer.rb

@@ -50,7 +50,7 @@ module RailsAiContext
         lines << "- Models: #{models.size}" if models.is_a?(Hash) && !models[:error]
 
         routes = context[:routes]
-        lines << "- Routes: #{routes[:total_routes]}" if routes.is_a?(Hash) && !routes[:error]
+        lines << "- Routes: #{routes[:total_routes]}#{RouteCoverage.suffix(routes)}" if routes.is_a?(Hash) && !routes[:error]
 
         lines.concat(full_preset_stack_lines)
 

data/lib/rails_ai_context/serializers/compact_serializer_helper.rb

@@ -46,7 +46,7 @@ module RailsAiContext
           app_routes = app_ctrls.sum { |k| Tools::BaseTool.dedupe_put_patch_routes(Array(by_controller[k])).size }
           lines << "- Routes: #{count_phrase(app_routes, "app route")} across " \
                    "#{count_phrase(app_ctrls.size, "controller")} " \
-                   "(#{routes[:total_routes]} total incl. framework)"
+                   "(#{routes[:total_routes]} total incl. framework#{RouteCoverage.suffix(routes)})"
         end
 
         jobs = context[:jobs]

data/lib/rails_ai_context/serializers/copilot_instructions_serializer.rb

@@ -52,7 +52,7 @@ module RailsAiContext
         lines << "- Models: #{models.size}" if models.is_a?(Hash) && !models[:error]
 
         routes = context[:routes]
-        lines << "- Routes: #{routes[:total_routes]}" if routes.is_a?(Hash) && !routes[:error]
+        lines << "- Routes: #{routes[:total_routes]}#{RouteCoverage.suffix(routes)}" if routes.is_a?(Hash) && !routes[:error]
 
         gems = context[:gems]
         if gems.is_a?(Hash) && !gems[:error]

data/lib/rails_ai_context/serializers/copilot_serializer.rb

@@ -47,7 +47,7 @@ module RailsAiContext
           app_routes = app_ctrls.sum { |k| Tools::BaseTool.dedupe_put_patch_routes(Array(by_controller[k])).size }
           lines << "- Routes: #{count_phrase(app_routes, "app route")} across " \
                    "#{count_phrase(app_ctrls.size, "controller")} " \
-                   "(#{routes[:total_routes]} total incl. framework)"
+                   "(#{routes[:total_routes]} total incl. framework#{RouteCoverage.suffix(routes)})"
         end
 
         lines.concat(full_preset_stack_lines)

data/lib/rails_ai_context/serializers/cursor_rules_serializer.rb

@@ -82,7 +82,7 @@ module RailsAiContext
 
         routes = context[:routes]
         if routes && !routes[:error]
-          lines << "- Routes: #{routes[:total_routes]}"
+          lines << "- Routes: #{routes[:total_routes]}#{RouteCoverage.suffix(routes)}"
         end
 
         gems = context[:gems]

data/lib/rails_ai_context/serializers/markdown_serializer.rb

@@ -117,7 +117,7 @@ module RailsAiContext
         routes = context[:routes]
         return if routes[:error]
 
-        lines = [ "## Routes (#{routes[:total_routes]} total)" ]
+        lines = [ "## Routes (#{routes[:total_routes]} total#{RouteCoverage.suffix(routes)})" ]
         routes[:by_controller]&.sort&.each do |ctrl, actions|
           lines << "### #{escape_markdown(ctrl)}"
           actions.each do |r|

data/lib/rails_ai_context/server.rb

@@ -214,14 +214,41 @@ module RailsAiContext
       $stderr.puts tool_banner(server)
       maybe_start_live_reload(server)
 
-      begin
-        require "rackup"
-        Rackup::Handler.default.run(rack_app, Host: config.http_bind, Port: config.http_port)
-      rescue LoadError
-        # Fallback for older rack without rackup gem
-        require "rack/handler"
-        Rack::Handler.default.run(rack_app, Host: config.http_bind, Port: config.http_port)
-      end
+      handler = default_rack_handler
+      handler.run(rack_app, **rack_handler_options(handler, config))
+    end
+
+    def default_rack_handler
+      require "rackup"
+      Rackup::Handler.default
+    rescue LoadError
+      # Fallback for older rack without rackup gem
+      require "rack/handler"
+      Rack::Handler.default
+    end
+
+    # MCP sessions live in this process's memory, so a forked worker cannot
+    # answer a request whose `initialize` another worker handled - about half
+    # of them come back "Session not found". Puma's handler otherwise reads the
+    # host app's config/puma.rb, which on a real app sets `workers` (and a
+    # pidfile this server would then write over). Both options are load-bearing:
+    # refusing the file still leaves WEB_CONCURRENCY able to start a cluster on
+    # its own, and pinning the worker count still lets the file's pidfile and
+    # preload_app! through.
+    def rack_handler_options(handler, config)
+      options = { Host: config.http_bind, Port: config.http_port }
+      return options unless puma_handler?(handler)
+
+      $stderr.puts "[rails-ai-context] Puma pinned to single mode - MCP sessions are per-process, " \
+                   "so config/puma.rb and WEB_CONCURRENCY are not read."
+      options.merge(workers: 0, config_files: [ "-" ])
+    end
+
+    # The handler is whatever Rackup picked, and only Puma understands these
+    # keys. Puma::RackHandler is the module both Rackup::Handler::Puma and the
+    # older Rack::Handler::Puma extend, so this recognizes either.
+    def puma_handler?(handler)
+      defined?(::Puma::RackHandler) && handler.singleton_class.include?(::Puma::RackHandler)
     end
 
     # Conditionally start live reload based on configuration.

data/lib/rails_ai_context/tasks/rails_ai_context.rake

@@ -448,7 +448,7 @@ namespace :ai do
     end
 
     if context[:routes] && !context[:routes][:error]
-      puts "🛤️  Routes: #{context[:routes][:total_routes]}"
+      puts "🛤️  Routes: #{context[:routes][:total_routes]}#{RailsAiContext::RouteCoverage.suffix(context[:routes])}"
     end
 
     if context[:jobs]

data/lib/rails_ai_context/tools/get_job_pattern.rb

@@ -55,9 +55,11 @@ module RailsAiContext
         channels = channels.reject { |c| c.is_a?(Hash) && c[:error] }
         channels_note = unavailable_note(jobs_data)
 
+        sidekiq_line = sidekiq_queues_line(jobs_data)
+
         # Single-job query: requires jobs to be present.
         if job
-          return text_response(no_job_files_message(jobs_dir_exists)) if job_files.empty?
+          return text_response(no_job_files_message(jobs_dir_exists, sidekiq_line)) if job_files.empty?
           return format_single_job(job, job_files, real_jobs_dir, real_root)
         end
 
@@ -67,7 +69,7 @@ module RailsAiContext
         # actually ran - if it's unavailable (static tier), say so instead of
         # claiming "no channels detected".
         if job_files.empty? && channels.empty?
-          return text_response(no_jobs_or_channels_message(jobs_dir_exists, channels_note))
+          return text_response(no_jobs_or_channels_message(jobs_dir_exists, channels_note, sidekiq_line))
         end
 
         # Compose: jobs section (if any) + channels section (if any).
@@ -77,6 +79,13 @@ module RailsAiContext
           lines << "" if lines.any?
           lines.concat(format_channels_section(channels))
         end
+        # A count of what app/jobs/ holds is still a claim about the app's async
+        # work, and on an app that runs most of it through Sidekiq workers that
+        # count is the small half. The queues are already in hand either way.
+        if sidekiq_line
+          lines << "" if lines.any?
+          lines << "_#{sidekiq_line} Workers outside app/jobs/ are not covered by this tool._"
+        end
         text_response(lines.join("\n"))
       end
 
@@ -84,12 +93,13 @@ module RailsAiContext
       # but has no job classes besides ApplicationJob" - both used to be
       # reported as "No app/jobs/ directory found," which is false when the
       # directory is there (e.g. freshly generated by `rails new`).
-      private_class_method def self.no_job_files_message(jobs_dir_exists)
-        if jobs_dir_exists
+      private_class_method def self.no_job_files_message(jobs_dir_exists, sidekiq_line = nil)
+        message = if jobs_dir_exists
           "No job classes in app/jobs/ beyond ApplicationJob. Workers outside that directory (Sidekiq::Worker in app/workers/, for example) are not covered by this tool."
         else
           "No app/jobs/ directory. Workers outside it (Sidekiq::Worker in app/workers/, for example) are not covered by this tool."
         end
+        [ message, sidekiq_line ].compact.join(" ")
       end
 
       # Same distinction for the "nothing async at all" bail-out message,
@@ -98,13 +108,29 @@ module RailsAiContext
       # section never ran (static tier) - in that case, asserting "no Action
       # Cable channels detected" would be a fabricated negative rather than
       # an observed one, so the note replaces that claim instead of joining it.
-      private_class_method def self.no_jobs_or_channels_message(jobs_dir_exists, channels_note)
+      private_class_method def self.no_jobs_or_channels_message(jobs_dir_exists, channels_note, sidekiq_line = nil)
         channels_clause = channels_note || "no Action Cable channels detected"
-        if jobs_dir_exists
+        message = if jobs_dir_exists
           "No job classes in app/jobs/ beyond ApplicationJob, and #{channels_clause}. Workers outside that directory are not covered by this tool."
         else
           "No app/jobs/ directory and #{channels_clause}. Workers outside it are not covered by this tool."
         end
+        [ message, sidekiq_line ].compact.join(" ")
+      end
+
+      # JobIntrospector#extract_sidekiq_config already read this file, and on an
+      # app that runs everything through Sidekiq workers it is the only evidence
+      # in reach that async work happens at all.
+      private_class_method def self.sidekiq_queues_line(jobs_data)
+        config = jobs_data.is_a?(Hash) ? jobs_data[:sidekiq_config] : nil
+        return nil unless config.is_a?(Hash)
+
+        queues = Array(config[:queues])
+        return nil if queues.empty?
+
+        line = "config/sidekiq.yml declares #{count_phrase(queues.size, "queue")}: #{queues.join(', ')}"
+        line += " (concurrency: #{config[:concurrency]})" if config[:concurrency]
+        "#{line}."
       end
 
       private_class_method def self.format_single_job(job, job_files, jobs_dir, root)

data/lib/rails_ai_context/tools/get_routes.rb

@@ -89,6 +89,12 @@ module RailsAiContext
           if unattributed_count > 0 && controller.nil?
             count_label += " and #{count_phrase(unattributed_count, "engine mount")}"
           end
+          # Dropping the count of what the static tier could not expand let a
+          # partial list read as the whole routing table, which is the one
+          # thing an unbooted answer must not do. All three detail levels share
+          # this label. Gated on `controller` because the caveat is about the
+          # whole table, and a filtered answer is not that.
+          count_label += RailsAiContext::RouteCoverage.suffix(routes) if controller.nil?
 
           case detail
           when "summary"

data/lib/rails_ai_context/tools/onboard.rb

@@ -285,7 +285,9 @@ module RailsAiContext
             .select { |k, _| prefixes.any? { |p| k.downcase.start_with?(p) } }
             .values.sum { |route_list| dedupe_put_patch_routes(route_list).size }
           framework_note = framework_count > 0 ? " (plus #{count_phrase(framework_count, 'framework route')})" : ""
-          lines << "Total: #{count_phrase(app_route_count, 'app route')} across #{count_phrase(app_ctrls.size, 'controller')}#{framework_note}."
+          lines << "Total: #{count_phrase(app_route_count, 'app route')} across " \
+                   "#{count_phrase(app_ctrls.size, 'controller')}#{framework_note}" \
+                   "#{RailsAiContext::RouteCoverage.suffix(routes)}."
           lines << ""
           lines
         end

data/lib/rails_ai_context/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsAiContext
-  VERSION = "5.20.2"
+  VERSION = "5.20.3"
 end

data/server.json

@@ -7,7 +7,7 @@
     "url": "https://github.com/crisnahine/rails-ai-context",
     "source": "github"
   },
-  "version": "5.20.1",
+  "version": "5.20.3",
   "packages": [
     {
       "registryType": "mcpb",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-ai-context
 version: !ruby/object:Gem::Version
-  version: 5.20.2
+  version: 5.20.3
 platform: ruby
 authors:
 - crisnahine
@@ -385,6 +385,7 @@ files:
 - lib/rails_ai_context/presets.rb
 - lib/rails_ai_context/redaction.rb
 - lib/rails_ai_context/resources.rb
+- lib/rails_ai_context/route_coverage.rb
 - lib/rails_ai_context/safe_file.rb
 - lib/rails_ai_context/schema_adapter.rb
 - lib/rails_ai_context/schema_hint.rb