scint 0.6.0 → 0.7.0

data/lib/scint/cli/install.rb

@@ -3,6 +3,7 @@
 require_relative "../errors"
 require_relative "../fs"
 require_relative "../platform"
+require_relative "../spec_utils"
 require_relative "../progress"
 require_relative "../worker_pool"
 require_relative "../scheduler"
@@ -32,6 +33,8 @@ require_relative "../resolver/provider"
 require_relative "../resolver/resolver"
 require_relative "../credentials"
 require "open3"
+require "set"
+require "pathname"
 
 module Scint
   module CLI
@@ -44,6 +47,10 @@ module Scint
         @path = nil
         @verbose = false
         @force = false
+        @download_pool = nil
+        @download_pool_lock = Thread::Mutex.new
+        @gemspec_cache = {}
+        @gemspec_cache_lock = Thread::Mutex.new
         parse_options
       end
 
@@ -117,7 +124,14 @@ module Scint
           # Scale up for download/install phase based on actual work count
           scheduler.scale_workers(to_install.size)
 
+          # Warm-cache accelerator: pre-materialize cache-backed gem trees in
+          # batches so install workers avoid one cp process per gem.
+          bulk_prelink_gem_files(to_install, cache, bundle_path)
+
           if to_install.empty?
+            # Keep lock artifacts aligned even when everything is already installed.
+            write_lockfile(resolved, gemfile, lockfile)
+            write_runtime_config(resolved, bundle_path)
             elapsed_ms = elapsed_ms_since(start_time)
             worker_count = scheduler.stats[:workers]
             warn_missing_bundle_gitignore_entry
@@ -148,7 +162,9 @@ module Scint
           if errors.any?
             $stderr.puts "#{RED}Some gems failed to install:#{RESET}"
             errors.each do |err|
-              $stderr.puts "  #{BOLD}#{err[:name]}#{RESET}: #{err[:error].message}"
+              error = err[:error]
+              $stderr.puts "  #{BOLD}#{err[:name]}#{RESET}: #{error.message}"
+              emit_network_error_details(error)
             end
           elsif stats[:failed] > 0
             $stderr.puts "#{YELLOW}Warning: #{stats[:failed]} jobs failed but no error details captured#{RESET}"
@@ -168,14 +184,18 @@ module Scint
             1
           else
             # 10. Write lockfile + runtime config only for successful installs
-            write_lockfile(resolved, gemfile)
+            write_lockfile(resolved, gemfile, lockfile)
             write_runtime_config(resolved, bundle_path)
             warn_missing_bundle_gitignore_entry
             $stdout.puts "\n#{GREEN}#{total_gems}#{RESET} gems installed total#{install_breakdown(cached: cached_gems, updated: updated_gems, compiled: compiled_gems)}. #{DIM}(#{format_run_footer(elapsed_ms, worker_count)})#{RESET}"
             0
           end
         ensure
-          scheduler.shutdown
+          begin
+            scheduler.shutdown
+          ensure
+            close_download_pool
+          end
         end
       end
 
@@ -207,7 +227,7 @@ module Scint
       def dedupe_resolved_specs(resolved)
         seen = {}
         resolved.each do |spec|
-          key = "#{spec.name}-#{spec.version}-#{spec.platform}"
+          key = SpecUtils.full_key(spec)
           seen[key] ||= spec
         end
         seen.values
@@ -217,8 +237,8 @@ module Scint
       # No download needed — we know exactly where we are.
       def install_builtin_gem(entry, bundle_path)
         spec = entry.spec
-        ruby_dir = File.join(bundle_path, "ruby", RUBY_VERSION.split(".")[0, 2].join(".") + ".0")
-        full_name = spec_full_name(spec)
+        ruby_dir = Platform.ruby_install_dir(bundle_path)
+        full_name = SpecUtils.full_name(spec)
         scint_root = File.expand_path("../../..", __FILE__)
 
         # Copy gem files into gems/scint-x.y.z/lib/
@@ -270,7 +290,10 @@ module Scint
 
       def resolve(gemfile, lockfile, cache)
         # If lockfile is up-to-date, use its specs directly
-        if lockfile && lockfile_current?(gemfile, lockfile)
+        if lockfile &&
+           lockfile_current?(gemfile, lockfile) &&
+           lockfile_dependency_graph_valid?(lockfile) &&
+           lockfile_git_source_mapping_valid?(lockfile, cache)
           return lockfile_to_resolved(lockfile)
         end
 
@@ -305,6 +328,7 @@ module Scint
         # Build path_gems: gem_name => { version:, dependencies:, source: }
         # for gems with path: or git: sources (skip compact index for these)
         path_gems = {}
+        git_source_metadata_cache = {}
         gemfile.dependencies.each do |dep|
           opts = dep.source_options
           next unless opts[:path] || opts[:git]
@@ -314,19 +338,57 @@ module Scint
 
           # Try to read version and deps from gemspec if it's a path gem
           if opts[:path]
-            gemspec = find_gemspec(opts[:path], dep.name)
+            gemspec = find_gemspec(opts[:path], dep.name, glob: opts[:glob])
             if gemspec
               version = gemspec.version.to_s
               deps = gemspec.dependencies
                 .select { |d| d.type == :runtime }
-                .map { |d| [d.name, d.requirement.to_s] }
+                .map do |d|
+                  requirement_parts = d.requirement.requirements.map { |op, req_version| "#{op} #{req_version}" }
+                  [d.name, requirement_parts]
+                end
             end
           end
 
-          # For git gems, try lockfile for version
-          if opts[:git] && lockfile
-            locked_spec = lockfile.specs.find { |s| s[:name] == dep.name }
-            version = locked_spec[:version] if locked_spec
+          # For git gems, read version and dependencies from the available revision when possible.
+          if opts[:git]
+            git_source = find_matching_git_source(Array(lockfile&.sources), opts) || find_matching_git_source(gemfile.sources, opts)
+            revision_hint = git_source&.revision || git_source&.ref || opts[:ref] || opts[:branch] || opts[:tag] || "HEAD"
+            bare_repo = cache&.git_path(opts[:git])
+            if bare_repo && !Dir.exist?(bare_repo)
+              clone_git_repo(opts[:git], bare_repo)
+            elsif bare_repo && Dir.exist?(bare_repo)
+              fetch_git_repo(bare_repo)
+            end
+            if bare_repo && Dir.exist?(bare_repo)
+              begin
+                resolved_revision = resolve_git_revision(bare_repo, revision_hint)
+                cache_key = "#{opts[:git]}@#{resolved_revision}"
+                git_metadata = git_source_metadata_cache[cache_key]
+                unless git_metadata
+                  git_metadata = build_git_path_gems_for_revision(
+                    bare_repo,
+                    resolved_revision,
+                    glob: opts[:glob],
+                    source_desc: opts[:git],
+                  )
+                  git_source_metadata_cache[cache_key] = git_metadata
+                end
+                path_gems.merge!(git_metadata)
+                current = git_metadata[dep.name]
+                if current
+                  version = current[:version]
+                  deps = current[:dependencies]
+                end
+              rescue StandardError
+                # Fall back to lockfile version below.
+              end
+            end
+
+            if lockfile && version == "0"
+              locked_spec = lockfile.specs.find { |s| s[:name] == dep.name }
+              version = locked_spec[:version] if locked_spec
+            end
           end
 
           source_desc = opts[:path] || opts[:git] || "local"
@@ -353,14 +415,16 @@ module Scint
         resolver.resolve
       end
 
-      def find_gemspec(path, gem_name)
+      def find_gemspec(path, gem_name, glob: nil)
         return nil unless Dir.exist?(path)
 
+        glob_pattern = glob || Source::Path::DEFAULT_GLOB
         # Look for exact match first, then any gemspec
         candidates = [
           File.join(path, "#{gem_name}.gemspec"),
+          *Dir.glob(File.join(path, glob_pattern)),
           *Dir.glob(File.join(path, "*.gemspec")),
-        ]
+        ].uniq
 
         candidates.each do |gs|
           next unless File.exist?(gs)
@@ -374,11 +438,135 @@ module Scint
         nil
       end
 
+      def find_git_gemspec(bare_repo, revision, gem_name, glob: nil)
+        gemspec_paths = gemspec_paths_in_git_revision(bare_repo, revision)
+        return nil if gemspec_paths.empty?
+
+        path = gemspec_paths[gem_name.to_s]
+        if path.nil? && glob
+          glob_regex = git_glob_to_regex(glob)
+          path = gemspec_paths.values.find { |candidate| candidate.match?(glob_regex) }
+        end
+        path ||= gemspec_paths.values.first
+        return nil if path.nil?
+
+        load_git_gemspec(bare_repo, revision, path)
+      rescue StandardError
+        nil
+      end
+
+      def build_git_path_gems_for_revision(bare_repo, revision, glob: nil, source_desc: nil)
+        gemspec_paths = gemspec_paths_in_git_revision(bare_repo, revision)
+        return {} if gemspec_paths.empty?
+
+        glob_regex = glob ? git_glob_to_regex(glob) : nil
+        data = {}
+
+        with_git_worktree(bare_repo, revision) do |worktree|
+          gemspec_paths.each_value do |path|
+            next if glob_regex && !path.match?(glob_regex)
+
+            gemspec = load_gemspec_from_worktree(worktree, path)
+            next unless gemspec
+
+            deps = gemspec.dependencies
+              .select { |d| d.type == :runtime }
+              .map do |d|
+                requirement_parts = d.requirement.requirements.map { |op, req_version| "#{op} #{req_version}" }
+                [d.name, requirement_parts]
+              end
+
+            data[gemspec.name] = {
+              version: gemspec.version.to_s,
+              dependencies: deps,
+              source: source_desc || "local",
+            }
+          end
+        end
+
+        data
+      rescue StandardError
+        {}
+      end
+
+      def git_glob_to_regex(glob)
+        pattern = glob.to_s
+        escaped = Regexp.escape(pattern)
+        escaped = escaped.gsub("\\*\\*", ".*")
+        escaped = escaped.gsub("\\*", "[^/]*")
+        escaped = escaped.gsub("\\?", ".")
+        /\A#{escaped}\z/
+      end
+
       def lockfile_current?(gemfile, lockfile)
         return false unless lockfile
 
         locked_names = Set.new(lockfile.specs.map { |s| s[:name] })
-        gemfile.dependencies.all? { |d| locked_names.include?(d.name) }
+        gemfile.dependencies.all? do |dep|
+          next true unless dependency_relevant_for_local_platform?(dep)
+
+          locked_names.include?(dep.name)
+        end
+      end
+
+      def lockfile_dependency_graph_valid?(lockfile)
+        return false unless lockfile
+
+        specs = Array(lockfile.specs)
+        return false if specs.empty?
+
+        by_name = Hash.new { |h, k| h[k] = [] }
+        specs.each { |spec| by_name[spec[:name].to_s] << spec }
+
+        specs.all? do |spec|
+          Array(spec[:dependencies]).all? do |dep|
+            dep_name = dep[:name].to_s
+            # Lockfiles generally do not include a concrete "bundler" spec
+            # entry even though many gemspecs declare a runtime dependency
+            # on bundler. Treat it as externally satisfied.
+            next true if dep_name == "bundler"
+
+            dep_reqs = Array(dep[:version_reqs])
+            req = Gem::Requirement.new(dep_reqs.empty? ? [">= 0"] : dep_reqs)
+            by_name[dep_name].any? { |candidate| req.satisfied_by?(Gem::Version.new(candidate[:version].to_s)) }
+          end
+        end
+      rescue StandardError
+        false
+      end
+
+      def dependency_relevant_for_local_platform?(dependency)
+        platforms = Array(dependency.platforms).map(&:to_sym)
+        return true if platforms.empty?
+
+        platforms.any? { |platform| gemfile_platform_matches_local?(platform) }
+      end
+
+      def gemfile_platform_matches_local?(platform)
+        case platform
+        when :ruby
+          true
+        when :mri
+          RUBY_ENGINE == "ruby"
+        when :jruby
+          RUBY_ENGINE == "jruby"
+        when :truffleruby
+          RUBY_ENGINE == "truffleruby"
+        when :rbx
+          RUBY_ENGINE == "rbx"
+        when :windows, :mswin, :mswin64, :mingw, :x64_mingw, :x86_mingw, :x64_mingw_ucrt
+          Platform.windows?
+        when :linux
+          Platform.linux?
+        when :darwin, :macos
+          Platform.macos?
+        else
+          platform_name = platform.to_s.tr("_", "-")
+          spec_platform = Gem::Platform.new(platform_name)
+          spec_platform === Platform.local_platform
+        end
+      rescue StandardError
+        false
       end
 
       def lockfile_to_resolved(lockfile)
@@ -414,6 +602,108 @@ module Scint
         apply_locked_platform_preferences(resolved)
       end
 
+      def lockfile_git_source_mapping_valid?(lockfile, cache)
+        return true unless lockfile && cache
+
+        git_specs = Array(lockfile.specs).select { |s| s[:source].is_a?(Source::Git) }
+        return true if git_specs.empty?
+
+        by_source = git_specs.group_by { |s| s[:source] }
+        by_source.each do |source, specs|
+          uri, revision = git_source_ref(source)
+          bare_repo = cache.git_path(uri)
+          # Do not invalidate an otherwise-usable lockfile just because this
+          # git source has not been cached yet in the current machine/session.
+          next unless Dir.exist?(bare_repo)
+
+          resolved_revision = begin
+            resolve_git_revision(bare_repo, revision)
+          rescue InstallError
+            nil
+          end
+          return false unless resolved_revision
+
+          gemspec_paths = gemspec_paths_in_git_revision(bare_repo, resolved_revision)
+          gemspec_names = gemspec_paths.keys.to_set
+          return false if gemspec_names.empty?
+
+          specs.each do |spec|
+            return false unless gemspec_names.include?(spec[:name].to_s)
+          end
+        end
+
+        true
+      end
+
+      def gemspec_paths_in_git_revision(bare_repo, revision)
+        out, _err, status = git_capture3(
+          "--git-dir", bare_repo,
+          "ls-tree",
+          "-r",
+          "--name-only",
+          revision,
+        )
+        return {} unless status.success?
+
+        paths = {}
+        out.each_line do |line|
+          path = line.strip
+          next unless path.end_with?(".gemspec")
+          name = File.basename(path, ".gemspec")
+          paths[name] ||= path
+        end
+        paths
+      rescue StandardError
+        {}
+      end
+
+      def runtime_dependencies_for_git_gemspec(bare_repo, revision, gemspec_path)
+        spec = load_git_gemspec(bare_repo, revision, gemspec_path)
+        return nil unless spec
+
+        spec.dependencies.select { |dep| dep.type == :runtime }
+      rescue StandardError
+        nil
+      end
+
+      def load_git_gemspec(bare_repo, revision, gemspec_path)
+        return nil if gemspec_path.to_s.empty?
+
+        with_git_worktree(bare_repo, revision) do |worktree|
+          load_gemspec_from_worktree(worktree, gemspec_path)
+        end
+      rescue StandardError
+        nil
+      end
+
+      def with_git_worktree(bare_repo, revision)
+        worktree = Dir.mktmpdir("scint-gemspec")
+        _out, _err, status = git_capture3(
+          "--git-dir", bare_repo,
+          "--work-tree", worktree,
+          "checkout",
+          "--force",
+          revision,
+        )
+        return nil unless status.success?
+
+        File.write(File.join(worktree, ".git"), "gitdir: #{bare_repo}\n")
+        yield worktree if block_given?
+      ensure
+        FileUtils.rm_rf(worktree) if worktree && !worktree.empty?
+      end
+
+      def load_gemspec_from_worktree(worktree, gemspec_path)
+        absolute_gemspec = File.join(worktree, gemspec_path)
+        return nil unless File.exist?(absolute_gemspec)
+
+        Dir.chdir(File.dirname(absolute_gemspec)) do
+          Gem::Specification.load(absolute_gemspec)
+        end
+      rescue StandardError
+        nil
+      end
+
       # Preference: exact platform match > compatible match > ruby > first.
       def pick_best_platform_spec(specs, local_plat)
         return specs.first if specs.size == 1
@@ -451,7 +741,7 @@ module Scint
         return resolved_specs if preferred.empty?
 
         resolved_specs.each do |spec|
-          key = "#{spec.name}-#{spec.version}"
+          key = SpecUtils.full_name_for(spec.name, spec.version)
           platform = preferred[key]
           next if platform.nil? || platform.empty?
 
@@ -478,7 +768,7 @@ module Scint
               preferred = preferred.to_s
               next if preferred.empty? || preferred == spec.platform.to_s
 
-              out["#{spec.name}-#{spec.version}"] = preferred
+              out[SpecUtils.full_name_for(spec.name, spec.version)] = preferred
             end
           rescue StandardError
             next
@@ -496,7 +786,7 @@ module Scint
         spec = entry.spec
         source = spec.source
         if git_source?(source)
-          prepare_git_source(entry, cache)
+          prepare_git_checkout(spec, cache, fetch: false)
           return
         end
         source_uri = source.to_s
@@ -504,7 +794,7 @@ module Scint
         # Path gems are not downloaded from a remote
         return if source_uri.start_with?("/") || !source_uri.start_with?("http")
 
-        full_name = spec_full_name(spec)
+        full_name = SpecUtils.full_name(spec)
         gem_filename = "#{full_name}.gem"
         source_uri = source_uri.chomp("/")
         download_uri = "#{source_uri}/gems/#{gem_filename}"
@@ -513,9 +803,20 @@ module Scint
         FS.mkdir_p(File.dirname(dest_path))
 
         unless File.exist?(dest_path)
-          pool = Downloader::Pool.new(size: 1, credentials: @credentials)
-          pool.download(download_uri, dest_path)
-          pool.close
+          downloader_pool.download(download_uri, dest_path)
+        end
+      end
+
+      def downloader_pool
+        @download_pool_lock.synchronize do
+          @download_pool ||= Downloader::Pool.new(credentials: @credentials)
+        end
+      end
+
+      def close_download_pool
+        @download_pool_lock.synchronize do
+          @download_pool&.close
+          @download_pool = nil
         end
       end
 
@@ -523,8 +824,12 @@ module Scint
         spec = entry.spec
         source_uri = spec.source.to_s
 
-        # Git/path gems are already materialized by checkout or local path.
-        return if git_source?(spec.source)
+        # Git gems are extracted from the cached checkout; path gems are
+        # linked directly from local source.
+        if git_source?(spec.source)
+          materialize_git_spec(entry, cache)
+          return
+        end
         return if source_uri.start_with?("/") || !source_uri.start_with?("http")
 
         extracted = cache.extracted_path(spec)
@@ -546,51 +851,132 @@ module Scint
         source_str.end_with?(".git") || source_str.include?(".git/")
       end
 
+      def path_source?(source)
+        return true if source.is_a?(Source::Path)
+
+        source_str =
+          if source.respond_to?(:path)
+            source.path.to_s
+          else
+            source.to_s
+          end
+        return false if source_str.empty?
+        return false if source_str.start_with?("http://", "https://")
+        return false if git_source?(source)
+
+        source_str.start_with?("/", ".", "~")
+      end
+
       def prepare_git_source(entry, cache)
+        # Legacy helper used by tests/callers that expect git download+extract
+        # in a single step.
         spec = entry.spec
+        checkout_dir, resolved_revision, _uri = prepare_git_checkout(spec, cache, fetch: true)
+        materialize_git_spec(entry, cache, checkout_dir: checkout_dir, resolved_revision: resolved_revision)
+      end
+
+      def prepare_git_checkout(spec, cache, fetch: false)
         source = spec.source
         uri, revision = git_source_ref(source)
+        submodules = git_source_submodules?(source)
 
         bare_repo = cache.git_path(uri)
 
         # Serialize all git operations per bare repo — git uses index.lock
         # and can't handle concurrent checkouts from the same repo.
         git_mutex_for(bare_repo).synchronize do
-          clone_git_repo(uri, bare_repo) unless Dir.exist?(bare_repo)
-          fetch_git_repo(bare_repo)
+          if Dir.exist?(bare_repo)
+            fetch_git_repo(bare_repo) if fetch
+          else
+            clone_git_repo(uri, bare_repo)
+            fetch_git_repo(bare_repo)
+          end
 
           resolved_revision = resolve_git_revision(bare_repo, revision)
+          incoming_checkout = cache.git_checkout_path(uri, resolved_revision)
+          materialize_git_checkout(
+            bare_repo,
+            incoming_checkout,
+            resolved_revision,
+            spec,
+            uri,
+            submodules: submodules,
+          )
+          [incoming_checkout, resolved_revision, uri]
+        end
+      end
 
-          extracted = cache.extracted_path(spec)
-          marker = git_checkout_marker_path(extracted)
-          if Dir.exist?(extracted) && File.exist?(marker)
-            return if File.read(marker).strip == resolved_revision
-          end
+      def materialize_git_spec(entry, cache, checkout_dir: nil, resolved_revision: nil)
+        spec = entry.spec
+        checkout_dir, resolved_revision, _uri = prepare_git_checkout(spec, cache, fetch: false) unless checkout_dir && resolved_revision
+        gem_root = resolve_git_gem_subdir(checkout_dir, spec)
+        extracted = cache.extracted_path(spec)
+        marker = git_checkout_marker_path(extracted)
+        if Dir.exist?(extracted) &&
+           File.exist?(marker) &&
+           File.read(marker).strip == resolved_revision &&
+           git_spec_layout_current?(extracted, spec)
+          return
+        end
 
-          tmp = "#{extracted}.#{Process.pid}.#{Thread.current.object_id}.tmp"
-          begin
-            FileUtils.rm_rf(tmp)
-            FileUtils.mkdir_p(tmp)
-
-            _out, err, status = git_capture3(
-              "--git-dir", bare_repo,
-              "--work-tree", tmp,
-              "checkout",
-              "-f",
+        tmp = "#{extracted}.#{Process.pid}.#{Thread.current.object_id}.tmp"
+        begin
+          FileUtils.rm_rf(tmp)
+          FS.clone_tree(gem_root, tmp)
+
+          FileUtils.rm_rf(extracted)
+          FS.atomic_move(tmp, extracted)
+          FS.atomic_write(marker, "#{resolved_revision}\n")
+        ensure
+          FileUtils.rm_rf(tmp) if tmp && File.exist?(tmp)
+        end
+      end
+
+      def git_spec_layout_current?(extracted_path, spec)
+        File.exist?(File.join(extracted_path, "#{spec.name}.gemspec"))
+      rescue StandardError
+        false
+      end
+
+      def materialize_git_checkout(bare_repo, checkout_dir, resolved_revision, spec, uri, submodules: false)
+        marker = git_checkout_marker_path(checkout_dir)
+        if Dir.exist?(checkout_dir) && File.exist?(marker)
+          checkout_marker = parse_git_checkout_marker(marker)
+          marker_revision = checkout_marker[:revision]
+          marker_submodules = checkout_marker[:submodules]
+
+          # Legacy markers only recorded revision. If this source now requires
+          # submodules, force a refresh so previously incomplete checkouts are
+          # not reused.
+          return if marker_revision == resolved_revision && (!submodules || marker_submodules == true)
+        end
+
+        tmp = "#{checkout_dir}.#{Process.pid}.#{Thread.current.object_id}.tmp"
+        begin
+          FileUtils.rm_rf(tmp)
+          if submodules
+            checkout_git_tree_with_submodules(
+              bare_repo,
+              tmp,
               resolved_revision,
-              "--",
-              ".",
+              spec,
+              uri,
+            )
+          else
+            checkout_git_tree(
+              bare_repo,
+              tmp,
+              resolved_revision,
+              spec,
+              uri,
             )
-            unless status.success?
-              raise InstallError, "Git checkout failed for #{spec.name} (#{uri}@#{resolved_revision}): #{err.to_s.strip}"
-            end
-
-            FileUtils.rm_rf(extracted)
-            FS.atomic_move(tmp, extracted)
-            FS.atomic_write(marker, "#{resolved_revision}\n")
-          ensure
-            FileUtils.rm_rf(tmp) if tmp && File.exist?(tmp)
           end
+
+          FileUtils.rm_rf(checkout_dir)
+          FS.atomic_move(tmp, checkout_dir)
+          FS.atomic_write(marker, format_git_checkout_marker(resolved_revision, submodules: submodules))
+        ensure
+          FileUtils.rm_rf(tmp) if tmp && File.exist?(tmp)
         end
       end
 
@@ -603,6 +989,68 @@ module Scint
         [source.to_s, "HEAD"]
       end
 
+      def git_source_submodules?(source)
+        source.respond_to?(:submodules) && !!source.submodules
+      end
+
+      def checkout_git_tree(bare_repo, destination, resolved_revision, spec, uri)
+        FileUtils.mkdir_p(destination)
+        _out, err, status = git_capture3(
+          "--git-dir", bare_repo,
+          "--work-tree", destination,
+          "checkout",
+          "-f",
+          resolved_revision,
+          "--",
+          ".",
+        )
+        unless status.success?
+          raise InstallError, "Git checkout failed for #{spec.name} (#{uri}@#{resolved_revision}): #{err.to_s.strip}"
+        end
+      end
+
+      def checkout_git_tree_with_submodules(bare_repo, destination, resolved_revision, spec, uri)
+        worktree = "#{destination}.worktree"
+        FileUtils.rm_rf(worktree)
+
+        _out, err, status = git_capture3(
+          "--git-dir", bare_repo,
+          "worktree",
+          "add",
+          "--detach",
+          "--force",
+          worktree,
+          resolved_revision,
+        )
+        unless status.success?
+          raise InstallError, "Git worktree checkout failed for #{spec.name} (#{uri}@#{resolved_revision}): #{err.to_s.strip}"
+        end
+
+        begin
+          _sub_out, sub_err, sub_status = git_capture3(
+            "-C", worktree,
+            "-c", "protocol.file.allow=always",
+            "submodule",
+            "update",
+            "--init",
+            "--recursive",
+          )
+          unless sub_status.success?
+            raise InstallError, "Git submodule update failed for #{spec.name} (#{uri}@#{resolved_revision}): #{sub_err.to_s.strip}"
+          end
+
+          FS.clone_tree(worktree, destination)
+
+          # Keep cache/extracted trees deterministic and detached from git internals.
+          Dir.glob(File.join(destination, "**", ".git"), File::FNM_DOTMATCH).each do |path|
+            FileUtils.rm_rf(path)
+          end
+        ensure
+          git_capture3("--git-dir", bare_repo, "worktree", "remove", "--force", worktree)
+          FileUtils.rm_rf(worktree)
+        end
+      end
+
       def git_mutex_for(repo_path)
         @git_mutexes_lock ||= Thread::Mutex.new
         @git_mutexes_lock.synchronize do
@@ -649,19 +1097,53 @@ module Scint
         "#{dir}.scint_git_revision"
       end
 
+      def parse_git_checkout_marker(path)
+        content = File.read(path)
+        revision = nil
+        submodules = nil
+
+        content.each_line do |line|
+          key, value = line.strip.split("=", 2)
+          case key
+          when "revision"
+            revision = value
+          when "submodules"
+            submodules = (value == "1" || value == "true")
+          end
+        end
+
+        if revision.nil?
+          # Legacy format: raw revision only.
+          revision = content.strip
+        end
+
+        { revision: revision, submodules: submodules }
+      rescue StandardError
+        { revision: nil, submodules: nil }
+      end
+
+      def format_git_checkout_marker(revision, submodules:)
+        "revision=#{revision}\nsubmodules=#{submodules ? 1 : 0}\n"
+      end
+
       def compile_slots_for(worker_count)
-        # Keep native builds serialized to avoid build-env races and reduce
-        # memory/CPU spikes from concurrent extension compiles.
-        _ = worker_count
-        1
+        # Keep compile parallelism conservative: at most 2 native builds.
+        # Small pools stay single-lane; larger pools can run two builds.
+        workers = worker_count.to_i
+        return 1 if workers <= 6
+
+        2
       end
 
       def install_task_limits(worker_count, compile_slots)
         # Leave headroom for compile and binstub lanes so link/download
         # throughput cannot fully starve them.
         io_cpu_limit = [worker_count - compile_slots - 1, 1].max
+        # Keep download in-flight set bounded so fail-fast exits quickly on
+        # auth/source errors instead of queueing a large burst.
+        download_limit = [io_cpu_limit, 8].min
         {
-          download: io_cpu_limit,
+          download: download_limit,
           extract: io_cpu_limit,
           link: io_cpu_limit,
           build_ext: compile_slots,
@@ -770,7 +1252,7 @@ module Scint
       end
 
       def spec_key(spec)
-        "#{spec.name}-#{spec.version}-#{spec.platform}"
+        SpecUtils.full_key(spec)
       end
 
       def dependency_link_job_ids(spec, link_job_by_name)
@@ -805,11 +1287,25 @@ module Scint
       def extracted_path_for_entry(entry, cache)
         source_str = entry.spec.source.to_s
         if source_str.start_with?("/") && Dir.exist?(source_str)
-          source_str
+          begin
+            if path_source?(entry.spec.source)
+              resolve_path_gem_subdir(source_str, entry.spec)
+            else
+              resolve_git_gem_subdir(source_str, entry.spec)
+            end
+          rescue InstallError
+            source_str
+          end
         else
           base = entry.cached_path || cache.extracted_path(entry.spec)
           if git_source?(entry.spec.source) && Dir.exist?(base)
             resolve_git_gem_subdir(base, entry.spec)
+          elsif path_source?(entry.spec.source) && Dir.exist?(base)
+            begin
+              resolve_path_gem_subdir(base, entry.spec)
+            rescue InstallError
+              base
+            end
           else
             base
           end
@@ -826,8 +1322,40 @@ module Scint
         Dir.glob(File.join(repo_root, glob)).each do |path|
           return File.dirname(path) if File.basename(path, ".gemspec") == name
         end
+        # Compatibility fallback for monorepos whose gem layout does not match
+        # the lockfile glob exactly.
+        Dir.glob(File.join(repo_root, "**", "*.gemspec")).each do |path|
+          return File.dirname(path) if File.basename(path, ".gemspec") == name
+        end
 
-        repo_root
+        source_uri = source.respond_to?(:uri) ? source.uri : source.to_s
+        raise InstallError,
+              "Git source #{source_uri} does not contain #{name}.gemspec (glob: #{glob.inspect}); lockfile source mapping may be stale"
+      end
+
+      # For path monorepo sources, map gem name to its gemspec subdirectory.
+      def resolve_path_gem_subdir(repo_root, spec)
+        name = spec.name
+        return repo_root if File.exist?(File.join(repo_root, "#{name}.gemspec"))
+
+        source = spec.source
+        glob = source.respond_to?(:glob) ? source.glob : Source::Path::DEFAULT_GLOB
+        Dir.glob(File.join(repo_root, glob)).each do |path|
+          return File.dirname(path) if File.basename(path, ".gemspec") == name
+        end
+        Dir.glob(File.join(repo_root, "**", "*.gemspec")).each do |path|
+          return File.dirname(path) if File.basename(path, ".gemspec") == name
+        end
+
+        source_uri =
+          if source.respond_to?(:path)
+            source.path
+          elsif source.respond_to?(:uri)
+            source.uri
+          else
+            source.to_s
+          end
+        raise InstallError, "Path source #{source_uri} does not contain #{name}.gemspec (glob: #{glob.inspect})"
       end
 
       def link_gem_files(entry, cache, bundle_path)
@@ -882,7 +1410,7 @@ module Scint
         dep_names.uniq!
         return if dep_names.empty?
 
-        source_ruby_dir = File.join(bundle_path, "ruby", RUBY_VERSION.split(".")[0, 2].join(".") + ".0")
+        source_ruby_dir = Platform.ruby_install_dir(bundle_path)
         target_ruby_dir = cache.install_ruby_dir
 
         dep_names.each do |name|
@@ -922,8 +1450,15 @@ module Scint
       end
 
       def load_gemspec(extracted_path, spec, cache)
+        cache_key = "#{cache.full_name(spec)}@#{extracted_path}"
+        cached_value = @gemspec_cache_lock.synchronize { @gemspec_cache[cache_key] }
+        return cached_value if cached_value
+
         cached = load_cached_gemspec(spec, cache, extracted_path)
-        return cached if cached
+        if cached
+          @gemspec_cache_lock.synchronize { @gemspec_cache[cache_key] = cached }
+          return cached
+        end
 
         inbound = cache.inbound_path(spec)
         return nil unless File.exist?(inbound)
@@ -931,12 +1466,38 @@ module Scint
         begin
           metadata = GemPkg::Package.new.read_metadata(inbound)
           cache_gemspec(spec, metadata, cache)
+          @gemspec_cache_lock.synchronize { @gemspec_cache[cache_key] = metadata }
           metadata
         rescue StandardError
           nil
         end
       end
 
+      def bulk_prelink_gem_files(entries, cache, bundle_path)
+        # Keep small installs simple; batching is for large warm-path runs.
+        return if entries.length < 32
+
+        ruby_dir = File.join(bundle_path, "ruby", RUBY_VERSION.split(".")[0, 2].join(".") + ".0")
+        gems_dir = File.join(ruby_dir, "gems")
+
+        sources = entries.filter_map do |entry|
+          next unless entry.action == :link || entry.action == :build_ext
+
+          extracted = cache.extracted_path(entry.spec)
+          full_name = cache.full_name(entry.spec)
+          next unless File.basename(extracted) == full_name
+          next unless Dir.exist?(extracted)
+          next if Dir.exist?(File.join(gems_dir, full_name))
+
+          extracted
+        end
+        return if sources.empty?
+
+        FS.clone_many_trees(sources, gems_dir)
+      rescue StandardError => e
+        $stderr.puts("bulk prelink warning: #{e.message}") if ENV["SCINT_DEBUG"]
+      end
+
       def load_cached_gemspec(spec, cache, extracted_path)
         path = cache.spec_cache_path(spec)
         return nil unless File.exist?(path)
@@ -996,79 +1557,386 @@ module Scint
 
       # --- Lockfile + runtime config ---
 
-      def write_lockfile(resolved, gemfile)
-        sources = []
+      def write_lockfile(resolved, gemfile, lockfile = nil)
+        specs, sources, preserved_layout = build_lockfile_specs_and_sources(resolved, gemfile, lockfile)
+
+        lockfile_data = Lockfile::LockfileData.new(
+          specs: specs,
+          dependencies: build_lockfile_dependencies(gemfile, lockfile),
+          platforms: preserved_layout && lockfile ? Array(lockfile.platforms) : build_lockfile_platforms(specs, lockfile),
+          sources: sources,
+          bundler_version: lockfile&.bundler_version || Scint::VERSION,
+          ruby_version: lockfile&.ruby_version || gemfile.ruby_version,
+          checksums: preserved_layout && lockfile ? lockfile.checksums : build_lockfile_checksums(specs, lockfile),
+        )
+
+        content = Lockfile::Writer.write(lockfile_data)
+        FS.atomic_write("Gemfile.lock", content)
+      end
+
+      def build_lockfile_specs_and_sources(resolved, gemfile, lockfile)
+        resolved_for_lockfile = filter_lockfile_specs(resolved)
+
+        if preserve_existing_lockfile_specs?(resolved_for_lockfile, lockfile)
+          specs = Array(lockfile.specs).map { |spec| normalize_lockfile_spec(spec) }
+          sources = uniq_sources(Array(lockfile.sources))
+          return [specs, sources, true]
+        end
+
+        dependency_sources = dependency_sources_from_gemfile(gemfile, lockfile)
+        existing_sources = Array(lockfile&.sources)
+        candidate_sources = uniq_sources(existing_sources + dependency_sources.values)
+
+        rubygems_uris = collect_lockfile_rubygems_uris(gemfile)
+        if rubygems_uris.empty? && candidate_sources.none? { |src| src.is_a?(Source::Rubygems) }
+          rubygems_uris << "https://rubygems.org"
+        end
+        rubygems_uris.each do |uri|
+          source = find_matching_rubygems_source(candidate_sources, uri)
+          candidate_sources << Source::Rubygems.new(remotes: [uri]) unless source
+        end
+        candidate_sources = uniq_sources(candidate_sources)
+
+        lock_source_by_full, lock_source_by_name_version = lockfile_sources_by_spec_key(lockfile)
+        default_rubygems_source = candidate_sources.find { |src| src.is_a?(Source::Rubygems) }
+
+        specs = resolved_for_lockfile.map do |spec|
+          normalized = normalize_resolved_spec(spec)
+          source = source_for_spec(
+            normalized,
+            dependency_sources: dependency_sources,
+            candidate_sources: candidate_sources,
+            lock_source_by_full: lock_source_by_full,
+            lock_source_by_name_version: lock_source_by_name_version,
+            fallback: default_rubygems_source,
+          )
+          normalized.merge(source: source)
+        end
+
+        sources = uniq_sources(specs.map { |spec| spec[:source] }.compact)
+        if sources.empty?
+          fallback = default_rubygems_source || Source::Rubygems.new(remotes: ["https://rubygems.org"])
+          sources = [fallback]
+          specs.each { |spec| spec[:source] = fallback }
+        end
+
+        [specs, sources, false]
+      end
+
+      def filter_lockfile_specs(specs)
+        specs.reject do |spec|
+          name = spec.is_a?(Hash) ? spec[:name].to_s : spec.name.to_s
+          name == "scint"
+        end
+      end
+
+      def preserve_existing_lockfile_specs?(resolved, lockfile)
+        return false unless lockfile && lockfile.respond_to?(:specs)
+
+        wanted = resolved.map { |spec| [spec.name.to_s, spec.version.to_s] }.uniq
+        return false if wanted.empty?
+
+        available = Set.new
+        Array(lockfile.specs).each do |spec|
+          available << [spec[:name].to_s, spec[:version].to_s]
+        end
+
+        wanted.all? { |tuple| available.include?(tuple) }
+      end
+
+      def normalize_lockfile_spec(spec)
+        if spec.is_a?(Hash)
+          {
+            name: spec[:name],
+            version: spec[:version],
+            platform: spec[:platform] || "ruby",
+            dependencies: spec[:dependencies] || [],
+            source: spec[:source],
+            checksum: spec[:checksum],
+          }
+        else
+          {
+            name: spec.name,
+            version: spec.version,
+            platform: spec.platform || "ruby",
+            dependencies: spec.dependencies || [],
+            source: spec.source,
+            checksum: spec.respond_to?(:checksum) ? spec.checksum : nil,
+          }
+        end
+      end
+
+      def normalize_resolved_spec(spec)
+        if spec.is_a?(Hash)
+          {
+            name: spec[:name],
+            version: spec[:version],
+            platform: spec[:platform] || "ruby",
+            dependencies: spec[:dependencies] || [],
+            source: spec[:source],
+            checksum: spec[:checksum],
+          }
+        else
+          {
+            name: spec.name,
+            version: spec.version,
+            platform: spec.platform || "ruby",
+            dependencies: spec.dependencies || [],
+            source: spec.source,
+            checksum: spec.respond_to?(:checksum) ? spec.checksum : nil,
+          }
+        end
+      end
+
+      def collect_lockfile_rubygems_uris(gemfile)
+        uris = gemfile.sources
+          .select { |src| src[:type] == :rubygems && src[:uri] }
+          .map { |src| src[:uri].to_s }
+
+        gemfile.dependencies.each do |dep|
+          inline = dep.source_options[:source]
+          uris << inline.to_s if inline
+        end
+
+        uris.uniq
+      end
+
+      def dependency_sources_from_gemfile(gemfile, lockfile)
+        existing_sources = Array(lockfile&.sources)
+        out = {}
 
-        # Build source objects for path and git gems
         gemfile.dependencies.each do |dep|
           opts = dep.source_options
-          if opts[:path]
-            sources << Source::Path.new(path: opts[:path], name: dep.name)
-          elsif opts[:git]
-            sources << Source::Git.new(
-              uri: opts[:git],
-              branch: opts[:branch],
-              tag: opts[:tag],
-              ref: opts[:ref],
-            )
+
+          source =
+            if opts[:path]
+              find_matching_path_source(existing_sources, opts[:path]) ||
+                Source::Path.new(path: opts[:path], name: dep.name)
+            elsif opts[:git]
+              matched = find_matching_git_source(existing_sources, opts)
+              Source::Git.new(
+                uri: opts[:git],
+                revision: matched&.revision,
+                ref: opts[:ref] || matched&.ref,
+                branch: opts[:branch] || matched&.branch,
+                tag: opts[:tag] || matched&.tag,
+                submodules: opts.fetch(:submodules, matched&.submodules),
+                glob: matched&.glob,
+                name: dep.name,
+              )
+            elsif opts[:source]
+              find_matching_rubygems_source(existing_sources, opts[:source]) ||
+                Source::Rubygems.new(remotes: [opts[:source]])
+            end
+
+          out[dep.name] = source if source
+        end
+
+        out
+      end
+
+      def lockfile_sources_by_spec_key(lockfile)
+        by_full = {}
+        by_name_version = {}
+
+        Array(lockfile&.specs).each do |spec|
+          source = spec[:source]
+          next unless source
+
+          name = spec[:name].to_s
+          version = spec[:version].to_s
+          platform = (spec[:platform] || "ruby").to_s
+
+          by_full[[name, version, platform]] = source
+          by_name_version[[name, version]] ||= source
+        end
+
+        [by_full, by_name_version]
+      end
+
+      def source_for_spec(spec, dependency_sources:, candidate_sources:, lock_source_by_full:, lock_source_by_name_version:, fallback:)
+        key_full = [spec[:name].to_s, spec[:version].to_s, spec[:platform].to_s]
+        locked_source = lock_source_by_full[key_full] || lock_source_by_name_version[key_full[0, 2]]
+        return locked_source if locked_source
+
+        dep_source = dependency_sources[spec[:name].to_s]
+        return dep_source if dep_source
+
+        spec_source = spec[:source]
+        source = find_matching_source(candidate_sources, spec_source)
+        return source if source
+
+        spec_source = spec_source.to_s
+        if git_source?(spec_source)
+          source = Source::Git.new(uri: spec_source, name: spec[:name])
+          candidate_sources << source
+          return source
+        elsif spec_source.start_with?("/") || spec_source.start_with?(".")
+          source = Source::Path.new(path: spec_source, name: spec[:name])
+          candidate_sources << source
+          return source
+        end
+
+        if rubygems_source_uri?(spec_source.to_s)
+          source = Source::Rubygems.new(remotes: [spec_source.to_s])
+          candidate_sources << source
+          return source
+        end
+
+        fallback
+      end
+
+      def find_matching_source(sources, source_ref)
+        return nil if source_ref.nil?
+
+        sources.find do |source|
+          source_matches?(source, source_ref)
+        end
+      end
+
+      def source_matches?(source, source_ref)
+        return true if source.equal?(source_ref)
+        return true if source == source_ref
+
+        source_key = normalize_source_key(source_ref)
+        return false unless source_key
+
+        if source.is_a?(Source::Rubygems)
+          source.remotes.any? { |remote| normalize_source_key(remote) == source_key }
+        elsif source.respond_to?(:uri)
+          normalize_source_key(source.uri) == source_key
+        else
+          normalize_source_key(source) == source_key
+        end
+      end
+
+      def normalize_source_key(source_ref)
+        return nil if source_ref.nil?
+
+        raw =
+          if source_ref.respond_to?(:uri)
+            source_ref.uri.to_s
+          elsif source_ref.respond_to?(:path)
+            source_ref.path.to_s
+          else
+            source_ref.to_s
           end
+        return nil if raw.empty?
+
+        if raw.match?(%r{\Ahttps?://}i)
+          raw = raw.sub(%r{\Ahttps?://}i, "")
+          raw = raw.sub(%r{\.git/?\z}i, "")
+          raw.chomp("/").downcase
+        elsif raw.start_with?("/") || raw.start_with?(".")
+          File.expand_path(raw)
+        else
+          raw.sub(%r{\.git/?\z}i, "").chomp("/").downcase
         end
+      end
 
-        # Build rubygems sources -- collect all unique URIs
-        rubygems_uris = gemfile.sources
-          .select { |s| s[:type] == :rubygems }
-          .map { |s| s[:uri] }
-          .uniq
+      def find_matching_rubygems_source(sources, uri)
+        sources.find do |source|
+          source.is_a?(Source::Rubygems) && source.remotes.any? { |remote| source_matches?(remote, uri) }
+        end
+      end
 
-        # Group URIs that share specs into one Source::Rubygems each.
-        # The default source gets all remotes that aren't a separate scoped source.
-        scoped_uris = Set.new
-        gemfile.dependencies.each do |dep|
-          src = dep.source_options[:source]
-          scoped_uris << src if src
+      def find_matching_path_source(sources, path)
+        sources.find { |source| source.is_a?(Source::Path) && source_matches?(source, path) }
+      end
+
+      def find_matching_git_source(sources, opts)
+        candidates = sources.select { |source| source.is_a?(Source::Git) && source_matches?(source, opts[:git]) }
+        return nil if candidates.empty?
+
+        candidates.find { |source| git_source_options_match?(source, opts) } || candidates.first
+      end
+
+      def git_source_options_match?(source, opts)
+        return false if opts[:branch] && source.branch.to_s != opts[:branch].to_s
+        return false if opts[:tag] && source.tag.to_s != opts[:tag].to_s
+        return false if opts[:ref] && source.ref.to_s != opts[:ref].to_s
+
+        true
+      end
+
+      def uniq_sources(sources)
+        out = []
+        sources.each do |source|
+          next unless source
+          out << source unless out.any? { |existing| existing.eql?(source) }
         end
+        out
+      end
+
+      def build_lockfile_dependencies(gemfile, lockfile)
+        locked = lockfile&.dependencies || {}
+        gemfile.dependencies
+          .select { |dep| lockfile_dependency_direct?(dep) }
+          .map do |dep|
+            locked_dep = locked[dep.name]
+            {
+              name: dep.name,
+              version_reqs: dep.version_reqs,
+              pinned: !!(locked_dep && locked_dep[:pinned]),
+            }
+          end
+      end
+
+      def lockfile_dependency_direct?(dep)
+        opts = dep.source_options || {}
+        return true unless opts[:gemspec_generated]
+
+        opts[:gemspec_primary] != false
+      end
 
-        # Each scoped URI gets its own source object
-        scoped_uris.each do |uri|
-          sources << Source::Rubygems.new(remotes: [uri])
+      def build_lockfile_platforms(specs, lockfile)
+        platforms = Set.new(Array(lockfile&.platforms))
+        specs.each do |spec|
+          platform = spec[:platform] || "ruby"
+          platforms << platform
         end
+        platforms << "ruby"
+        platforms.to_a
+      end
 
-        # Default rubygems source with remaining remotes
-        default_remotes = rubygems_uris.reject { |u| scoped_uris.include?(u) }
-        default_remotes = ["https://rubygems.org"] if default_remotes.empty?
-        sources << Source::Rubygems.new(remotes: default_remotes)
+      def build_lockfile_checksums(specs, lockfile)
+        existing = lockfile&.checksums
+        checksums = {}
+
+        specs.each do |spec|
+          key = lockfile_spec_checksum_key(spec)
+          checksum = spec[:checksum]
+          if checksum && !Array(checksum).empty?
+            checksums[key] = Array(checksum)
+          elsif existing&.key?(key)
+            checksums[key] = Array(existing[key])
+          end
+        end
 
-        lockfile_data = Lockfile::LockfileData.new(
-          specs: resolved,
-          dependencies: gemfile.dependencies.map { |d| { name: d.name, version_reqs: d.version_reqs } },
-          platforms: [Platform.local_platform.to_s, "ruby"].uniq,
-          sources: sources,
-          bundler_version: Scint::VERSION,
-          ruby_version: nil,
-          checksums: nil,
-        )
+        return nil if checksums.empty?
 
-        content = Lockfile::Writer.write(lockfile_data)
-        FS.atomic_write("Gemfile.lock", content)
+        checksums
+      end
+
+      def lockfile_spec_checksum_key(spec)
+        SpecUtils.full_name_for(spec[:name], spec[:version], spec[:platform] || "ruby")
       end
 
       def write_runtime_config(resolved, bundle_path)
-        ruby_dir = File.join(bundle_path, "ruby",
-                             RUBY_VERSION.split(".")[0, 2].join(".") + ".0")
+        ruby_dir = Platform.ruby_install_dir(bundle_path)
 
         data = {}
         resolved.each do |spec|
-          full = spec_full_name(spec)
+          full = SpecUtils.full_name(spec)
           gem_dir = File.join(ruby_dir, "gems", full)
           spec_file = File.join(ruby_dir, "specifications", "#{full}.gemspec")
           require_paths = read_require_paths(spec_file)
           load_paths = require_paths
-            .map { |rp| File.join(gem_dir, rp) }
+            .map { |rp| expand_require_path(gem_dir, rp) }
             .select { |path| Dir.exist?(path) }
 
           default_lib = File.join(gem_dir, "lib")
           load_paths << default_lib if load_paths.empty? && Dir.exist?(default_lib)
-          load_paths.concat(detect_nested_lib_paths(gem_dir))
           load_paths.uniq!
 
           # Add ext load path if extensions exist
@@ -1076,6 +1944,12 @@ module Scint
                               Platform.gem_arch, Platform.extension_api_version, full)
           load_paths << ext_dir if Dir.exist?(ext_dir)
 
+          if load_paths.empty?
+            source_paths = runtime_source_load_paths(spec)
+            load_paths.concat(source_paths)
+            load_paths.uniq!
+          end
+
           data[spec.name] = {
             version: spec.version.to_s,
             load_paths: load_paths,
@@ -1096,26 +1970,40 @@ module Scint
         ["lib"]
       end
 
-      def detect_nested_lib_paths(gem_dir)
-        lib_dir = File.join(gem_dir, "lib")
-        return [] unless Dir.exist?(lib_dir)
+      def expand_require_path(gem_dir, require_path)
+        value = require_path.to_s
+        return value if Pathname.new(value).absolute?
 
-        children = Dir.children(lib_dir)
-        top_level_rb = children.any? do |entry|
-          path = File.join(lib_dir, entry)
-          File.file?(path) && entry.end_with?(".rb")
+        File.join(gem_dir, value)
+      rescue StandardError
+        File.join(gem_dir, require_path.to_s)
+      end
+
+      def runtime_source_load_paths(spec)
+        source_root = spec.source.to_s
+        return [] unless source_root.start_with?("/") && Dir.exist?(source_root)
+
+        source_dir = begin
+          resolve_git_gem_subdir(source_root, spec)
+        rescue InstallError
+          source_root
         end
-        return [] if top_level_rb
 
-        children
-          .map { |entry| File.join(lib_dir, entry) }
-          .select { |path| File.directory?(path) }
+        gemspec_file = File.join(source_dir, "#{spec.name}.gemspec")
+        require_paths = read_require_paths(gemspec_file)
+        paths = require_paths
+          .map { |rp| expand_require_path(source_dir, rp) }
+          .select { |path| Dir.exist?(path) }
+
+        default_lib = File.join(source_dir, "lib")
+        paths << default_lib if paths.empty? && Dir.exist?(default_lib)
+        paths.uniq
+      rescue StandardError
+        []
       end
 
       def spec_full_name(spec)
-        base = "#{spec.name}-#{spec.version}"
-        plat = spec.respond_to?(:platform) ? spec.platform : nil
-        (plat.nil? || plat.to_s == "ruby" || plat.to_s.empty?) ? base : "#{base}-#{plat}"
+        SpecUtils.full_name(spec)
       end
 
       def elapsed_ms_since(start_time)
@@ -1124,7 +2012,7 @@ module Scint
       end
 
       def force_purge_artifacts(resolved, bundle_path, cache)
-        ruby_dir = File.join(bundle_path, "ruby", RUBY_VERSION.split(".")[0, 2].join(".") + ".0")
+        ruby_dir = Platform.ruby_install_dir(bundle_path)
         ext_root = File.join(ruby_dir, "extensions", Platform.gem_arch, Platform.extension_api_version)
 
         resolved.each do |spec|
@@ -1160,6 +2048,28 @@ module Scint
         "#{format_elapsed(elapsed_ms)}, #{workers} #{noun} used"
       end
 
+      def emit_network_error_details(error)
+        return unless error.is_a?(NetworkError)
+
+        headers = error.response_headers
+        body = error.response_body.to_s
+        return if (headers.nil? || headers.empty?) && body.empty?
+
+        if headers && !headers.empty?
+          $stderr.puts "    headers:"
+          headers.sort.each do |key, value|
+            $stderr.puts "      #{key}: #{value}"
+          end
+        end
+
+        return if body.empty?
+
+        $stderr.puts "    body:"
+        body.each_line do |line|
+          $stderr.puts "      #{line.rstrip}"
+        end
+      end
+
       def warn_missing_bundle_gitignore_entry
         path = ".gitignore"
         return unless File.file?(path)