rails-ai-context 5.32.2 → 5.34.0

data/lib/rails_ai_context/mcp_edge.rb

@@ -6,10 +6,11 @@ require "json"
 module RailsAiContext
   # What the three HTTP entry points - the standalone rack app, the Rack
   # middleware and the engine controller - have in common: how a transport is
-  # built, and what a transport failure looks like on the wire. Their genuine
-  # differences (streaming, header handling, memoization lifetime) stay with
-  # them.
+  # built, which conversation a request belongs to, and what a transport
+  # failure looks like on the wire. Their genuine differences (streaming,
+  # header handling, memoization lifetime) stay with them.
   module McpEdge
+    INVALID_REQUEST = -32600
     INTERNAL_ERROR = -32603
 
     class << self
@@ -17,11 +18,15 @@ module RailsAiContext
       # into a JSON-RPC reply, so each has to answer in JSON-RPC shape itself
       # or leave the client's request loop hanging on a non-JSON body.
       def internal_error_frame(error)
-        {
-          jsonrpc: "2.0",
-          error: { code: INTERNAL_ERROR, message: "Internal error: #{error.message}" },
-          id: nil
-        }.to_json
+        error_frame(INTERNAL_ERROR, "Internal error: #{error.message}")
+      end
+
+      # JSON.generate rather than to_json: ActiveSupport replaces to_json,
+      # and in an app whose encoder raises (Rails 8.0 under json 3: "unknown
+      # keyword: quirks_mode") the frame that should name the failure failed
+      # with it, so the client got the web server's plain-text 500.
+      def error_frame(code, message)
+        JSON.generate({ jsonrpc: "2.0", error: { code: code, message: message }, id: nil })
       end
 
       # The Rack-shaped answer, for the two entry points that return triples.
@@ -31,35 +36,180 @@ module RailsAiContext
         [ 500, { "Content-Type" => "application/json" }, [ internal_error_frame(error) ] ]
       end
 
-      # The whole Rack-shaped request: the path match (trailing slash
-      # included), session scoping, dispatch and error containment. The
-      # middleware and the standalone server used to state these ten lines
-      # separately, and only the non-match branch differs, so the caller
-      # supplies it as the block. The block runs outside the rescue: an
-      # exception from the app behind the middleware is the app's to handle,
-      # not an MCP error frame.
-      def rack_call(env, transport:)
+      # Whether a request is for the MCP endpoint, trailing slash included.
+      def mcp_request?(env)
         path = RailsAiContext.configuration.http_path
-        return yield unless env["PATH_INFO"] == path || env["PATH_INFO"] == "#{path}/"
-
-        begin
-          request = Rack::Request.new(env)
-          Tools::BaseTool.with_session_for(env) do
-            transport.handle_request(request)
-          end
-        rescue => e
-          internal_error_response(e)
-        end
+        env["PATH_INFO"] == path || env["PATH_INFO"] == "#{path}/"
+      end
+
+      # One MCP request, Rack-shaped: session scoping, dispatch and error
+      # containment. Only a transport failure becomes an MCP error frame; the
+      # middleware calls the app behind it outside this, so the app's own
+      # exceptions stay the app's to handle.
+      def serve(env, transport)
+        request = Rack::Request.new(env)
+        session = Tools::BaseTool.session_from(env)
+        status, headers, body = Tools::BaseTool.with_session(session) { transport.handle_request(request) }
+        [ status, headers, session_scoped(body, session) ]
+      rescue => e
+        internal_error_response(e)
+      end
+
+      # The SDK answers a request inside a session with a streaming body, and
+      # the tool runs when the web server calls that body - after `serve` has
+      # returned and the scope around handle_request is gone. Every client's
+      # calls then landed in the one default record, so the scope travels
+      # with the body.
+      def session_scoped(body, session)
+        return body unless body.respond_to?(:call) && !body.respond_to?(:each)
+
+        ->(stream) { Tools::BaseTool.with_session(session) { body.call(stream) } }
+      end
+
+      # The middleware and the engine ride the app's own web server, which in
+      # a deployed environment is the one the network reaches, and every tool
+      # answers whoever asks. Serving there is the app's decision, so without
+      # it the answer is a refusal that says how to make it. Deployed is any
+      # environment but development and test: a staging app is reached the
+      # way production is.
+      def production_refusal
+        config = RailsAiContext.configuration
+        env = RailsAiContext.environment_name
+        return nil if config.allow_http_in_production || LOCAL_ENVIRONMENTS.include?(env)
+
+        log_production_refusal(env)
+        [ 403, { "Content-Type" => "application/json" }, [ error_frame(INVALID_REQUEST, production_refusal_message(env)) ] ]
+      end
+
+      def production_refusal_message(env)
+        "rails-ai-context does not serve MCP over HTTP in the #{env} environment, where every tool " \
+          "would answer whoever can reach this app. To serve it here, put the endpoint behind your app's " \
+          "authentication and set config.allow_http_in_production = true."
+      end
+
+      # The engine's transport, one per process, so every session it opens is
+      # found again on the next request, whatever the app reloads in between.
+      def engine_transport
+        ENGINE_TRANSPORT_LOCK.synchronize { @engine_transport ||= build_transport(answered_whole: true) }
       end
 
-      # Memoization is the caller's: the middleware holds one per instance
-      # and the controller one per class. The standalone server builds its
-      # own transport because start_http also needs the underlying server
-      # for the banner and live reload.
-      def build_transport(app = nil)
+      # Drops the engine's transport and closes it, which ends its sessions
+      # and stops its reaper; the next request builds a fresh one.
+      def reset_engine_transport!
+        transport = ENGINE_TRANSPORT_LOCK.synchronize { @engine_transport.tap { @engine_transport = nil } }
+        transport.close if transport.respond_to?(:close)
+      end
+
+      # Memoization is the caller's: the middleware holds one per instance,
+      # and the engine one per process (engine_transport). The standalone
+      # server builds its own transport because start_http also needs the
+      # underlying server for the banner and live reload.
+      #
+      # The middleware and the engine never start live reload; their tool
+      # calls check the app's files themselves, as every server's do.
+      def build_transport(app = nil, answered_whole: false)
         app ||= Rails.application
-        MCP::Server::Transports::StreamableHTTPTransport.new(Server.new(app, transport: :http).build)
+        options = host_check_options
+        options = options.merge(answered_whole_options) if answered_whole
+        transport = MCP::Server::Transports::StreamableHTTPTransport.new(Server.new(app, transport: :http).build, **options)
+        transport.extend(AnsweredWhole) if answered_whole
+        CodeReloader.track_loaded_code!
+        Tools::BaseTool.check_files_per_call!(app)
+        transport
+      end
+
+      # The SDK answers only the Host 127.0.0.1, ::1 or localhost, and its
+      # allowed_hosts takes exact names only: none of config.hosts' domain,
+      # pattern and address forms. These transports ride the app's own server,
+      # so its config.hosts decides instead (host_refusal), and the SDK's
+      # check is turned off where the SDK lets it be.
+      def host_check_options
+        return {} unless defined?(ActionDispatch::HostAuthorization)
+
+        transport_option?(:dns_rebinding_protection) ? { dns_rebinding_protection: false } : {}
+      end
+
+      # The engine answers each request whole (McpController), so it cannot
+      # keep open the stream `subscriptions/listen` delivers notifications
+      # on: the answer would be the acknowledgement alone, and the client,
+      # told it was subscribed, would hear nothing more. Told not to serve
+      # it, the SDK answers the method as one it does not have; an SDK older
+      # than the method has nothing to turn off.
+      def answered_whole_options
+        transport_option?(:serve_subscriptions_listen) ? { serve_subscriptions_listen: false } : {}
+      end
+
+      # The Host and Origin checks the SDK made, made by the app's rules: the
+      # Host as Rails' HostAuthorization judges it against config.hosts, its
+      # exclusions included, so the endpoint answers every name the app does
+      # (`myapp.localhost` in development, the app's own domain in
+      # production) and refuses the rest, a rebinding attacker's domain
+      # among them. A browser's request from another origin is refused, as
+      # the SDK refuses it.
+      def host_refusal(env, app = Rails.application)
+        message = if !host_allowed?(env, app) then "Forbidden: Invalid Host header"
+        elsif env["HTTP_ORIGIN"] && !same_origin?(env["HTTP_ORIGIN"], env["HTTP_HOST"]) then "Forbidden: Invalid Origin header"
+        end
+        message && [ 403, { "Content-Type" => "application/json" }, [ error_frame(INVALID_REQUEST, message) ] ]
+      end
+
+      private
+
+      def host_allowed?(env, app)
+        config = app.config
+        exclude = config.respond_to?(:host_authorization) && config.host_authorization.is_a?(Hash) ? config.host_authorization[:exclude] : nil
+        judge = ActionDispatch::HostAuthorization.new(->(_env) { :allowed }, config.hosts, exclude: exclude, response_app: ->(_env) { :blocked })
+        judge.call(env.dup) == :allowed
+      rescue StandardError
+        # Rails' own rules unreadable: the SDK's, a loopback name only.
+        LOOPBACK_HOSTS.include?(env["HTTP_HOST"].to_s.downcase.sub(/:\d+\z/, "").delete_prefix("[").delete_suffix("]"))
+      end
+
+      # The SDK's test: the Origin's host and port are the request's own, a
+      # scheme's default port dropped from both.
+      def same_origin?(origin, host)
+        return false if host.nil?
+
+        origin = origin.downcase
+        default_port = origin.start_with?("https://") ? ":443" : ":80"
+        origin.sub(%r{\Ahttps?://}, "").delete_suffix(default_port) == host.downcase.delete_suffix(default_port)
+      end
+
+      # Once per process: a client that keeps retrying would otherwise fill
+      # the production log with the same line.
+      def log_production_refusal(env)
+        return if @production_refusal_logged
+
+        @production_refusal_logged = true
+        RailsAiContext.log_warn "[rails-ai-context] Refused an MCP request. #{production_refusal_message(env)}"
+      end
+
+      # Whether the installed SDK's transport takes this keyword: the gemspec
+      # allows SDKs from before it took several of them.
+      def transport_option?(name)
+        MCP::Server::Transports::StreamableHTTPTransport.instance_method(:initialize).parameters.any? { |_, param| param == name }
       end
     end
+
+    # The engine's transport, which answers each request whole: what a tool
+    # sends during a call reaches the client with the answer. A request a
+    # tool makes of the client mid-call (sampling, elicitation, roots, ping)
+    # would get there only once nothing waited for its reply, so the tool
+    # would wait out the SDK's timeout - 600 seconds on mcp 1.7, without end
+    # on 0.13 - holding a server thread, and in development every code reload
+    # and every request after an edit behind it. It fails at once instead,
+    # saying why.
+    module AnsweredWhole
+      def send_request(method, *_params, **_routing)
+        raise "#{method} needs the client to answer during the call, and the mounted engine answers each request " \
+              "whole: nothing it sends reaches the client before the call is over. Serve a tool that asks the " \
+              "client over stdio or the standalone HTTP server (rails-ai-context serve --transport http)."
+      end
+    end
+
+    # The environments the endpoint answers in without allow_http_in_production.
+    LOCAL_ENVIRONMENTS = %w[development test].freeze
+    LOOPBACK_HOSTS = %w[127.0.0.1 ::1 localhost].freeze
+    ENGINE_TRANSPORT_LOCK = Mutex.new
   end
 end

data/lib/rails_ai_context/middleware.rb

@@ -14,8 +14,12 @@ module RailsAiContext
       @mutex = Mutex.new
     end
 
+    # The transport is built on the first MCP request, not the first request
+    # of any kind: building it builds the whole MCP server.
     def call(env)
-      McpEdge.rack_call(env, transport: transport) { @app.call(env) }
+      return @app.call(env) unless McpEdge.mcp_request?(env)
+
+      McpEdge.production_refusal || McpEdge.host_refusal(env) || McpEdge.serve(env, transport)
     end
 
     private

data/lib/rails_ai_context/migration_status.rb

@@ -1,14 +1,19 @@
 # frozen_string_literal: true
 
 module RailsAiContext
-  # Resolves pending-migration status the same way Rails itself does for the
-  # "Migrations are pending" dev error page (ActiveRecord::Migration.check_pending!
-  # walks pool.migration_context.open.pending_migrations). MigrationContext moved
-  # from the connection object to the connection pool between Rails 7.0 and 7.1,
-  # and ActiveRecord::Migrator.new's signature changed to require a schema_migration
-  # + internal_metadata pair it can no longer build on its own - so a single
-  # hardcoded construction path breaks on part of the range this gem supports.
-  # The respond_to? cascade below picks whichever construction the loaded
+  # Resolves pending-migration status the way Rails' own
+  # MigrationContext#needs_migration? reads it, and without writing: the
+  # migration files Rails loads, minus the versions schema_migrations holds
+  # (none when the table is not there). MigrationContext#open, which the
+  # "Migrations are pending" page walks, builds a Migrator, and building one
+  # creates schema_migrations and ar_internal_metadata in a database that
+  # lacks them.
+  #
+  # The MigrationContext itself moved from the connection object to the
+  # connection pool between Rails 7.0 and 7.1, and from 7.1 on it takes a
+  # schema_migration + internal_metadata pair - so a single hardcoded
+  # construction path breaks on part of the range this gem supports. The
+  # respond_to? cascade below picks whichever construction the loaded
   # ActiveRecord version actually exposes instead of guessing from a version
   # number.
   module MigrationStatus
@@ -19,23 +24,76 @@ module RailsAiContext
     def self.pending(migrate_dir)
       dirs = Array(migrate_dir).select { |dir| Dir.exist?(dir) }
       return nil if dirs.empty? || !defined?(ActiveRecord::Base)
+      # A database that is not there yet, said without creating its file.
+      return nil if DatabaseFile.missing(ActiveRecord::Base.connection_db_config)
 
-      context = migration_context(dirs)
-      begin
-        context.open.pending_migrations.map { |m| { version: m.version.to_s, name: m.name } }
-      rescue ActiveRecord::MigrationError
-        # A future or duplicate version stops Rails loading the directory; the applied set still answers.
-        PendingMigrations.for(migrate_dir: dirs, applied: context.get_all_versions)
-      end
+      pending_in(migration_context(dirs), dirs)
     rescue => e
       RailsAiContext.debug_fail(e, nil, label: "MigrationStatus.pending")
     end
 
-    # @return [ActiveRecord::MigrationContext]
-    def self.migration_context(migrate_dir)
-      pool = ActiveRecord::Base.connection_pool
+    # One database's pending migrations, as `db:migrate:status:<name>` reads
+    # them: from that database's own schema_migrations, through a pool of its
+    # own that is removed after, so the app's connections are left as they
+    # are. The primary is asked through the app's own pool. The connection is
+    # made first, so a database that does not exist, or a server that does
+    # not answer, says so rather than reading as nothing pending; a SQLite
+    # file that is not there is said to be missing without connecting, which
+    # would create it.
+    #
+    # @param db_config [ActiveRecord::DatabaseConfigurations::DatabaseConfig]
+    # @return [Hash] { pending: [{ version:, name: }, ...] }, or { error: exception }
+    def self.of_database(db_config, migrate_dir, primary: false)
+      missing = DatabaseFile.missing(db_config)
+      return { error: missing } if missing
+
+      dirs = Array(migrate_dir).select { |dir| Dir.exist?(dir) }
+      with_pool(db_config, primary: primary) do |pool|
+        pool.with_connection(&:verify!)
+        { pending: dirs.empty? ? [] : pending_in(migration_context(dirs, pool), dirs) }
+      end
+    rescue StandardError => e
+      { error: e }
+    end
+
+    def self.pending_in(context, dirs)
+      applied = context.get_all_versions
+      context.migrations.reject { |m| applied.include?(m.version) }.map { |m| { version: m.version.to_s, name: m.name } }
+    rescue ActiveRecord::MigrationError
+      # A version Rails will not load (one past tomorrow, a name it cannot
+      # read) stops it reading the directory; the applied set still answers.
+      PendingMigrations.for(migrate_dir: dirs, applied: context.get_all_versions)
+    end
+
+    # What a pool established for another database belongs to: Rails names a
+    # pool by its owner, and an owner that is no primary class leaves the
+    # app's own pools alone (ActiveRecord::PendingMigrationConnection, which
+    # Rails 7.0 lacks and 7.1 shapes differently).
+    class TemporaryOwner
+      def self.primary_class?
+        false
+      end
 
-      # Rails 7.1+: MigrationContext takes a schema_migration + internal_metadata
+      def self.current_preventing_writes
+        false
+      end
+    end
+
+    def self.with_pool(db_config, primary:)
+      return yield(ActiveRecord::Base.connection_pool) if primary
+
+      handler = ActiveRecord::Base.connection_handler
+      begin
+        yield handler.establish_connection(db_config, owner_name: TemporaryOwner)
+      ensure
+        handler.remove_connection_pool(TemporaryOwner.name)
+      end
+    end
+    private_class_method :with_pool
+
+    # @return [ActiveRecord::MigrationContext]
+    def self.migration_context(migrate_dir, pool = ActiveRecord::Base.connection_pool)
+      # Rails 7.2+: MigrationContext takes a schema_migration + internal_metadata
       # pair (per-connection bookkeeping objects) that only the pool knows how
       # to build - construct explicitly with OUR migrate_dir rather than
       # calling pool.migration_context directly, since that resolves its own
@@ -46,12 +104,17 @@ module RailsAiContext
         return ActiveRecord::MigrationContext.new(migrate_dir, pool.schema_migration, pool.internal_metadata)
       end
 
-      # Rails 7.0: MigrationContext.new(migrations_paths, schema_migration =
-      # SchemaMigration) - construct with OUR migrate_dir for the same reason
-      # as above. The connection's own migration_context resolves the app's
-      # configured migrations_paths and ignores the directory being asked
-      # about, silently reporting zero pending migrations.
-      ActiveRecord::MigrationContext.new(migrate_dir)
+      # Rails 7.1 keeps the pair on the connection, and Rails 7.0 the
+      # schema_migration alone - construct with OUR migrate_dir for the same
+      # reason as above. The connection's own migration_context resolves the
+      # app's configured migrations_paths and ignores the directory being
+      # asked about, silently reporting zero pending migrations.
+      connection = pool.connection
+      if connection.respond_to?(:internal_metadata)
+        return ActiveRecord::MigrationContext.new(migrate_dir, connection.schema_migration, connection.internal_metadata)
+      end
+
+      ActiveRecord::MigrationContext.new(migrate_dir, connection.schema_migration)
     end
   end
 end

data/lib/rails_ai_context/output_guard.rb

@@ -37,14 +37,19 @@ module RailsAiContext
         # Bundler re-execs exactly here: `require "bundler/setup"` runs
         # inside this block, and auto_switch re-execs when the lockfile
         # names a different Bundler than the one running.
-        saved_stdout.close_on_exec = false
-        ENV[STDOUT_FD_ENV] = saved_stdout.fileno.to_s
+        if Gem.win_platform?
+          arm_exec(saved_stdout)
+        else
+          saved_stdout.close_on_exec = false
+          ENV[STDOUT_FD_ENV] = saved_stdout.fileno.to_s
+        end
       end
       STDOUT.reopen($stderr) if saved_stdout
       $stdout = $stderr
       yield(saved_stdout || original)
     ensure
       if saved_stdout
+        @exec_stdout = nil
         STDOUT.reopen(saved_stdout)
         # Closed for real, and the pointer goes with it: the descriptor
         # exists to survive one exec, and leaving it open with close-on-exec
@@ -56,6 +61,47 @@ module RailsAiContext
       $stdout = original
     end
 
+    # Windows has no exec: Ruby starts the new image as a child that takes
+    # the standard handles as they stand and no other descriptor, so a
+    # descriptor named in the environment means nothing there. An exec
+    # inside the quarantine puts fd 1 back on the real stdout first, for the
+    # new image to start with.
+    module ExecWithRealStdout
+      def exec(...)
+        OutputGuard.restore_for_exec
+        super(...)
+      end
+    end
+
+    # The same for a bare `exec`, which is Kernel's private instance method;
+    # Kernel.exec and Process.exec are public.
+    module PrivateExecWithRealStdout
+      private
+
+      def exec(...)
+        OutputGuard.restore_for_exec
+        super(...)
+      end
+    end
+
+    def self.arm_exec(saved_stdout)
+      @exec_stdout = saved_stdout
+      return if @exec_patched
+
+      Kernel.prepend(PrivateExecWithRealStdout)
+      Kernel.singleton_class.prepend(ExecWithRealStdout)
+      Process.singleton_class.prepend(ExecWithRealStdout)
+      @exec_patched = true
+    end
+    private_class_method :arm_exec
+
+    def self.restore_for_exec
+      io = @exec_stdout
+      STDOUT.reopen(io) if io && !io.closed?
+    rescue IOError, SystemCallError
+      nil
+    end
+
     # The descriptor an earlier image of this process saved, when there is
     # one and it is still open; a fresh dup of fd 1 otherwise.
     def self.saved_stdout_io

data/lib/rails_ai_context/package_json.rb

@@ -101,7 +101,7 @@ module RailsAiContext
     # it is missing, sensitive or a symlink out of that directory. A lockfile
     # past max_file_size still exists.
     def outside_file(dir, name)
-      found = SafePath.locate(name, under: dir)
+      found = SafePath.locate(name, under: dir, links: false)
       found.realpath if found.ok? || found.refusal == :too_large
     end
 

data/lib/rails_ai_context/path_resolver.rb

@@ -39,24 +39,20 @@ module RailsAiContext
     # unshifts wins over app/views even when it is nested inside it.
     def view_dirs(root)
       prepended, appended = declared(root)[:views].partition { |direction, _dir| direction == :prepend }
-      spelled = ->(list) { list.map { |_direction, dir| File.join(root.to_s, dir) } }
+      spelled = ->(list) { list.map { |_direction, dir| File.join(root.to_s, dir) }.reject { |dir| linked_out?(dir, root) } }
       engines = RunCache.fetch([ :engine_view_dirs, root.to_s ]) do
         enclosing_engine_roots(root).map { |engine| File.join(engine, "app/views") }.select { |dir| Dir.exist?(dir) }
       end
       (spelled.(prepended) + dirs_for(root, "app/views") + spelled.(appended) + engines).uniq.freeze
     end
 
-    # Every initializer Rails loads: railties globs config/initializers with **/*.rb, in path order.
-    # A symlink that resolves outside the app root, or nowhere, is left out.
+    # Every initializer Rails loads: railties globs config/initializers with **/*.rb, in path order,
+    # a glob that enters no linked directory below it. A symlink out of the app (linked_out?), or
+    # to nothing, is left out.
     def initializer_paths(root)
-      real_root = File.realpath(root.to_s)
       Dir.glob(File.join(root.to_s, "config", "initializers", "**", "*.rb")).sort.select do |path|
-        SafePath.contained?(File.realpath(path), real_root)
-      rescue SystemCallError
-        false
+        File.file?(path) && !linked_out?(path, root)
       end
-    rescue SystemCallError
-      []
     end
 
     # The initializers an app spells for `name`, however it spells them: a
@@ -251,7 +247,7 @@ module RailsAiContext
         relative = RunCache.fetch([ :dirs_for, root_key(root), kind, extra ]) do
           resolve_dirs(root, kind).map { |dir| dir.start_with?("#{root}/") ? dir.delete_prefix("#{root}/") : dir }
         end
-        relative.map { |dir| dir.start_with?(File::SEPARATOR) ? dir : File.join(root, dir) }.freeze
+        relative.map { |dir| SafePath.absolute?(dir) ? dir : File.join(root, dir) }.freeze
       end
     end
 
@@ -304,12 +300,49 @@ module RailsAiContext
     # Inside the app root, or inside the engine its test/dummy runs in.
     def project_file?(path, root)
       real = File.realpath(path)
-      dirs = RunCache.fetch([ :project_dirs, root.to_s ]) { [ root.to_s, *enclosing_engine_roots(root) ].map { |dir| root_key(dir) } }
-      dirs.any? { |dir| SafePath.contained?(real, dir) }
+      project_dirs(root).any? { |dir| SafePath.contained?(real, dir) }
+    rescue SystemCallError
+      false
+    end
+
+    # A path the app spells inside the project that a symlink carries out of
+    # it: to a place neither the app root, the engine its test/dummy runs in,
+    # nor a directory linked in from the app's repository holds
+    # (SafePath.linked_in). A pack linked into packs/ from elsewhere in the
+    # repository keeps its files, as Zeitwerk follows it; a link to anywhere
+    # outside the repository, or a file linked out of the app and of the
+    # linked-in directory it sits in, does not. A path spelled outside the
+    # project, such as a gem's, is not one, nor is one that resolves nowhere:
+    # nothing can be read through it.
+    def linked_out?(path, root)
+      # Resolved as given: a spelled `..` after a link climbs from where the link leads.
+      real = SafePath.real_file(path.to_s)
+      return false if project_dirs(root).any? { |dir| SafePath.contained?(real, dir) }
+
+      spelled = File.expand_path(path.to_s)
+      base = [ root.to_s, *enclosing_engine_roots(root) ].map { |dir| File.expand_path(dir) }
+        .find { |dir| spelled.start_with?(SafePath.dir_prefix(dir)) }
+      return false unless base
+
+      SafePath.linked_in(path, real, base, root).nil?
     rescue SystemCallError
       false
     end
 
+    # Whether a directory link that leads to `real` is one a walk enters: one
+    # inside the app's repository or the project, never one back up over
+    # `start`, the directory being walked, which would only walk it again.
+    def enter_link?(real, start, root)
+      return false if SafePath.contained?(start, real)
+
+      SafePath.contained?(real, SafePath.link_bound(root)) || project_dirs(root).any? { |dir| SafePath.contained?(real, dir) }
+    end
+
+    def project_dirs(root)
+      RunCache.fetch([ :project_dirs, root.to_s ]) { [ root.to_s, *enclosing_engine_roots(root) ].map { |dir| root_key(dir) } }
+    end
+    private_class_method :project_dirs
+
     def root_key(root)
       File.realpath(root)
     rescue SystemCallError
@@ -323,7 +356,7 @@ module RailsAiContext
 
     def resolve_dirs(root, kind)
       places(root, kind).flat_map { |_shown, path, glob| glob ? Dir.glob(path).sort : [ path ] }
-        .uniq.select { |dir| Dir.exist?(dir) }.freeze
+        .uniq.select { |dir| Dir.exist?(dir) && !linked_out?(dir, root) }.freeze
     end
     private_class_method :resolve_dirs