scint 0.6.0 → 0.7.1

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"
@@ -22,7 +23,9 @@ require_relative "../downloader/pool"
 require_relative "../gem/package"
 require_relative "../gem/extractor"
 require_relative "../cache/layout"
+require_relative "../cache/manifest"
 require_relative "../cache/metadata_store"
+require_relative "../cache/validity"
 require_relative "../installer/planner"
 require_relative "../installer/linker"
 require_relative "../installer/preparer"
@@ -32,31 +35,51 @@ require_relative "../resolver/provider"
 require_relative "../resolver/resolver"
 require_relative "../credentials"
 require "open3"
+require "set"
+require "pathname"
 
 module Scint
   module CLI
     class Install
       RUNTIME_LOCK = "scint.lock.marshal"
 
-      def initialize(argv = [])
+      def initialize(argv = [], without: nil, with: nil)
         @argv = argv
         @jobs = nil
         @path = nil
         @verbose = false
         @force = false
+        @without_groups = nil
+        @with_groups = nil
+        @download_pool = nil
+        @download_pool_lock = Thread::Mutex.new
+        @gemspec_cache = {}
+        @gemspec_cache_lock = Thread::Mutex.new
         parse_options
+        # Allow programmatic override (for tests)
+        @without_groups = Array(without).map(&:to_sym) if without
+        @with_groups = Array(with).map(&:to_sym) if with
+      end
+
+      def _tmark(label, t0)
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        $stderr.puts "  [timing] #{label}: #{((now - t0) * 1000).round}ms" if ENV["SCINT_TIMING"]
+        now
       end
 
       def run
         start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        _t = start_time
 
         cache = Scint::Cache::Layout.new
+        cache_telemetry = Scint::Cache::Telemetry.new
         bundle_path = @path || ENV["BUNDLER_PATH"] || ".bundle"
         bundle_display = display_bundle_path(bundle_path)
         bundle_path = File.expand_path(bundle_path)
-        worker_count = @jobs || [Platform.cpu_count * 2, 50].min
+        worker_count = [(@jobs || [Platform.cpu_count * 2, 50].min).to_i, 1].max
         compile_slots = compile_slots_for(worker_count)
-        per_type_limits = install_task_limits(worker_count, compile_slots)
+        git_slots = git_slots_for(worker_count)
+        per_type_limits = install_task_limits(worker_count, compile_slots, git_slots)
         $stdout.puts "#{GREEN}💎#{RESET} Scintellating Gemfile into #{BOLD}#{bundle_display}#{RESET} #{DIM}(scint #{VERSION}, ruby #{RUBY_VERSION})#{RESET}"
         $stdout.puts
 
@@ -68,6 +91,7 @@ module Scint
         scheduler.start
 
         begin
+          _t = _tmark("startup", _t)
           # 2. Parse Gemfile
           gemfile = Scint::Gemfile::Parser.parse("Gemfile")
 
@@ -79,6 +103,7 @@ module Scint
           dep_count = gemfile.dependencies.size
           scheduler.scale_workers(dep_count)
 
+          _t = _tmark("parse_gemfile", _t)
           # 3. Enqueue index fetches for all sources immediately
           gemfile.sources.each do |source|
             scheduler.enqueue(:fetch_index, source[:uri] || source.to_s,
@@ -99,25 +124,39 @@ module Scint
                               -> { clone_git_source(source, cache) })
           end
 
+          _t = _tmark("enqueue_fetches", _t)
           # 6. Wait for index fetches, then resolve
           scheduler.wait_for(:fetch_index)
+          _t = _tmark("wait_index", _t)
           scheduler.wait_for(:git_clone)
+          _t = _tmark("wait_git", _t)
 
           resolved = resolve(gemfile, lockfile, cache)
           resolved = dedupe_resolved_specs(adjust_meta_gems(resolved))
+          resolved = filter_excluded_gems(resolved, gemfile)
           force_purge_artifacts(resolved, bundle_path, cache) if @force
 
+          _t = _tmark("resolve", _t)
           # 7. Plan: diff resolved vs installed
-          plan = Installer::Planner.plan(resolved, bundle_path, cache)
+          plan = Installer::Planner.plan(resolved, bundle_path, cache, telemetry: cache_telemetry)
           total_gems = resolved.size
           updated_gems = plan.count { |e| e.action != :skip }
           cached_gems = total_gems - updated_gems
           to_install = plan.reject { |e| e.action == :skip }
+          _t = _tmark("plan", _t)
 
           # 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)
+          _t = _tmark("prelink", _t)
+
           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 +187,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 +209,22 @@ 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
+            cache_telemetry.warn_if_needed(cache_root: cache.root)
+          ensure
+            begin
+              scheduler.shutdown
+            ensure
+              close_download_pool
+            end
+          end
         end
       end
 
@@ -207,18 +256,103 @@ 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
       end
 
+      # Determine which gem names should be excluded based on group settings.
+      # A gem is excluded if ALL of its group memberships are in excluded groups.
+      # Gems appearing in any non-excluded group are kept.
+      def excluded_gem_names(gemfile, resolved: nil)
+        excluded_groups = compute_excluded_groups(gemfile)
+        return Set.new if excluded_groups.empty?
+
+        # Build map: gem_name => set of all groups it appears in (across all declarations)
+        gem_groups = Hash.new { |h, k| h[k] = Set.new }
+        gemfile.dependencies.each do |dep|
+          dep.groups.each { |g| gem_groups[dep.name] << g }
+        end
+
+        # A gem is directly excluded if ALL its groups are excluded
+        directly_excluded = Set.new
+        gem_groups.each do |name, groups|
+          directly_excluded << name if groups.subset?(excluded_groups)
+        end
+
+        # If we have resolved specs, also exclude transitive-only deps
+        if resolved && directly_excluded.any?
+          exclude_transitive_deps(directly_excluded, resolved, gem_groups)
+        else
+          directly_excluded
+        end
+      end
+
+      # Filter resolved specs, removing gems that belong only to excluded groups.
+      def filter_excluded_gems(resolved, gemfile)
+        excluded = excluded_gem_names(gemfile, resolved: resolved)
+        return resolved if excluded.empty?
+
+        resolved.reject { |spec| excluded.include?(spec.name) }
+      end
+
+      private
+
+      def compute_excluded_groups(gemfile)
+        optional = Set.new(Array(gemfile.optional_groups))
+        without = Set.new(Array(@without_groups))
+        with = Set.new(Array(@with_groups))
+
+        # Optional groups are excluded by default unless explicitly included via --with
+        excluded = optional - with
+        # --without adds more groups to exclude
+        excluded.merge(without)
+        excluded
+      end
+
+      # Walk the dependency graph to find transitive deps that are ONLY
+      # reachable through excluded gems. Shared deps are kept.
+      def exclude_transitive_deps(directly_excluded, resolved, gem_groups)
+        # Build dependency graph: name => [dep_names]
+        dep_graph = {}
+        resolved.each do |spec|
+          dep_names = Array(spec.dependencies).filter_map do |dep|
+            if dep.is_a?(Hash)
+              dep[:name] || dep["name"]
+            elsif dep.respond_to?(:name)
+              dep.name
+            end
+          end
+          dep_graph[spec.name] = dep_names
+        end
+
+        all_names = Set.new(resolved.map(&:name))
+
+        # Start from Gemfile deps that are NOT excluded, then walk transitive deps
+        included_roots = gem_groups.keys.reject { |n| directly_excluded.include?(n) }
+
+        # BFS from included roots to find all reachable gems
+        reachable = Set.new
+        queue = included_roots.dup
+        while (name = queue.shift)
+          next if reachable.include?(name)
+          reachable << name
+          (dep_graph[name] || []).each { |dep| queue << dep }
+        end
+
+        # Everything not reachable from included roots is excluded
+        all_names - reachable
+      end
+
+      public
+
       # Install scint into the bundle by copying our own lib tree.
       # 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 +404,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 +442,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 +452,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,32 +529,158 @@ 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)
           begin
-            spec = Gem::Specification.load(gs)
+            spec = SpecUtils.load_gemspec(gs, isolate: true)
             return spec if spec
-          rescue StandardError
+          rescue SystemExit, StandardError
             nil
           end
         end
         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 +716,106 @@ 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)
+
+        SpecUtils.load_gemspec(absolute_gemspec, isolate: true)
+      rescue SystemExit, 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 +853,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 +880,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 +898,7 @@ module Scint
         spec = entry.spec
         source = spec.source
         if git_source?(source)
-          prepare_git_source(entry, cache)
+          ensure_git_repo_for_spec(spec, cache, fetch: true)
           return
         end
         source_uri = source.to_s
@@ -504,7 +906,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 +915,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,20 +936,37 @@ 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)
+          assemble_git_spec(entry, cache, fetch: false)
+          return
+        end
         return if source_uri.start_with?("/") || !source_uri.start_with?("http")
 
-        extracted = cache.extracted_path(spec)
-        return if Dir.exist?(extracted)
+        return if Cache::Validity.cached_valid?(spec, cache)
 
         dest_path = cache.inbound_path(spec)
         raise InstallError, "Missing cached gem file for #{spec.name}: #{dest_path}" unless File.exist?(dest_path)
 
-        FS.mkdir_p(extracted)
-        pkg = GemPkg::Package.new
-        result = pkg.extract(dest_path, extracted)
-        cache_gemspec(spec, result[:gemspec], cache)
+        assembling = cache.assembling_path(spec)
+        tmp = "#{assembling}.#{Process.pid}.#{Thread.current.object_id}.tmp"
+        begin
+          FileUtils.rm_rf(assembling)
+          FileUtils.rm_rf(tmp)
+          FS.mkdir_p(File.dirname(assembling))
+
+          pkg = GemPkg::Package.new
+          result = pkg.extract(dest_path, tmp)
+          FS.atomic_move(tmp, assembling)
+          cache_gemspec(spec, result[:gemspec], cache)
+
+          unless Installer::ExtensionBuilder.needs_build?(spec, assembling)
+            promote_assembled_gem(spec, cache, assembling, result[:gemspec], extensions: false)
+          end
+        ensure
+          FileUtils.rm_rf(tmp) if tmp && File.exist?(tmp)
+        end
       end
 
       def git_source?(source)
@@ -546,50 +976,135 @@ 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.
+        assemble_git_spec(entry, cache, fetch: true)
+      end
+
+      def ensure_git_repo_for_spec(spec, cache, fetch:)
+        source = spec.source
+        uri, _revision = git_source_ref(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
+          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
+        end
+
+        bare_repo
+      end
+
+      def assemble_git_spec(entry, cache, fetch: true)
         spec = entry.spec
+        return if Cache::Validity.cached_valid?(spec, cache)
+
         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)
+          tmp_checkout = nil
+          tmp_assembled = nil
 
-          resolved_revision = resolve_git_revision(bare_repo, revision)
+          begin
+            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
 
-          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
+            resolved_revision = resolve_git_revision(bare_repo, revision)
+            assembling = cache.assembling_path(spec)
+            tmp_checkout = "#{assembling}.checkout.#{Process.pid}.#{Thread.current.object_id}.tmp"
+            tmp_assembled = "#{assembling}.#{Process.pid}.#{Thread.current.object_id}.tmp"
+            promoter = cache_promoter(cache)
+
+            FileUtils.rm_rf(assembling)
+            FileUtils.rm_rf(tmp_checkout)
+            FileUtils.rm_rf(tmp_assembled)
+            FS.mkdir_p(File.dirname(assembling))
+
+            promoter.validate_within_root!(cache.root, assembling, label: "assembling")
+            promoter.validate_within_root!(cache.root, tmp_checkout, label: "git-checkout")
+            promoter.validate_within_root!(cache.root, tmp_assembled, label: "git-assembled")
+
+            if submodules
+              checkout_git_tree_with_submodules(
+                bare_repo,
+                tmp_checkout,
+                resolved_revision,
+                spec,
+                uri,
+              )
+            else
+              checkout_git_tree(
+                bare_repo,
+                tmp_checkout,
+                resolved_revision,
+                spec,
+                uri,
+              )
+            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",
-              resolved_revision,
-              "--",
-              ".",
-            )
-            unless status.success?
-              raise InstallError, "Git checkout failed for #{spec.name} (#{uri}@#{resolved_revision}): #{err.to_s.strip}"
+            # Remove .git artifacts from checkout so assembled output is
+            # deterministic and contains no git internals.
+            Dir.glob(File.join(tmp_checkout, "**", ".git"), File::FNM_DOTMATCH).each do |path|
+              FileUtils.rm_rf(path)
+            end
+
+            gem_root = resolve_git_gem_subdir(tmp_checkout, spec)
+            gem_rel = git_relative_root(tmp_checkout, gem_root)
+            dest_root = tmp_assembled
+            dest_path = gem_rel.empty? ? dest_root : File.join(dest_root, gem_rel)
+
+            promoter.validate_within_root!(cache.root, dest_path, label: "git-dest")
+
+            FS.clone_tree(gem_root, dest_path)
+            copy_gemspec_root_files(tmp_checkout, gem_root, dest_root, spec)
+            FS.atomic_move(tmp_assembled, assembling)
+
+            gem_subdir = begin
+              resolve_git_gem_subdir(assembling, spec)
+            rescue InstallError
+              assembling
             end
+            gemspec = read_gemspec_from_extracted(gem_subdir, spec)
+            cache_gemspec(spec, gemspec, cache) if gemspec
 
-            FileUtils.rm_rf(extracted)
-            FS.atomic_move(tmp, extracted)
-            FS.atomic_write(marker, "#{resolved_revision}\n")
+            unless Installer::ExtensionBuilder.needs_build?(spec, assembling)
+              promote_assembled_gem(spec, cache, assembling, gemspec, extensions: false)
+            end
           ensure
-            FileUtils.rm_rf(tmp) if tmp && File.exist?(tmp)
+            FileUtils.rm_rf(tmp_checkout) if tmp_checkout && File.exist?(tmp_checkout)
+            FileUtils.rm_rf(tmp_assembled) if tmp_assembled && File.exist?(tmp_assembled)
           end
         end
       end
@@ -603,6 +1118,117 @@ module Scint
         [source.to_s, "HEAD"]
       end
 
+      def git_source_submodules?(source)
+        source.respond_to?(:submodules) && !!source.submodules
+      end
+
+      def copy_gemspec_root_files(repo_root, gem_root, dest_root, spec)
+        repo_root = File.expand_path(repo_root.to_s)
+        gem_root = File.expand_path(gem_root.to_s)
+        return if repo_root == gem_root
+
+        gemspec_path = git_gemspec_path_for_root(gem_root, spec)
+        return unless gemspec_path && File.exist?(gemspec_path)
+
+        content = File.read(gemspec_path) rescue nil
+        return unless content
+
+        root_files = git_root_files_from_gemspec(content)
+        root_files.each do |file|
+          source = File.join(repo_root, file)
+          next unless File.file?(source)
+
+          dest = File.join(dest_root, file)
+          next if File.exist?(dest)
+
+          FS.clonefile(source, dest)
+        end
+      end
+
+      def git_gemspec_path_for_root(gem_root, spec)
+        if spec && spec.respond_to?(:name)
+          candidate = File.join(gem_root, "#{spec.name}.gemspec")
+          return candidate if File.exist?(candidate)
+        end
+
+        Dir.glob(File.join(gem_root, "*.gemspec")).first
+      end
+
+      def git_root_files_from_gemspec(content)
+        files = ["RAILS_VERSION", "VERSION"]
+        files.select { |file| content.include?(file) }
+      end
+
+      def git_relative_root(repo_root, gem_root)
+        repo_root = File.expand_path(repo_root.to_s)
+        gem_root = File.expand_path(gem_root.to_s)
+        return "" if repo_root == gem_root
+
+        if gem_root.start_with?("#{repo_root}/")
+          return gem_root.delete_prefix("#{repo_root}/")
+        end
+
+        File.basename(gem_root)
+      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
@@ -645,30 +1271,59 @@ module Scint
         Open3.capture3("git", "-c", "core.fsmonitor=false", *args)
       end
 
-      def git_checkout_marker_path(dir)
-        "#{dir}.scint_git_revision"
+      def compile_slots_for(worker_count)
+        # Scale compile concurrency with available CPUs.
+        # Most native extensions have 1-3 source files and don't benefit from
+        # high make -j; running more concurrent builds is more effective.
+        # Each slot gets cpu_count/slots make jobs (see adaptive_make_jobs).
+        workers = [worker_count.to_i, 1].max
+        override = positive_integer_env("SCINT_COMPILE_CONCURRENCY")
+        return [override, workers].min if override
+
+        cpus = Platform.cpu_count
+        # Aim for 8 make-jobs per slot → slots = cpus / 8, clamped.
+        slots = cpus / 8
+        slots = [[slots, 2].max, workers].min
+        slots
       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
+      def git_slots_for(worker_count)
+        workers = [worker_count.to_i, 1].max
+        override = positive_integer_env("SCINT_GIT_CONCURRENCY")
+        slots = override || workers
+        [[slots, workers].min, 1].max
       end
 
-      def install_task_limits(worker_count, compile_slots)
+      def install_task_limits(worker_count, compile_slots, git_slots = worker_count)
         # 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
+        workers = [worker_count.to_i, 1].max
+        io_cpu_limit = [workers - 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
+        git_limit = [[git_slots.to_i, 1].max, workers].min
         {
-          download: io_cpu_limit,
+          download: download_limit,
           extract: io_cpu_limit,
           link: io_cpu_limit,
+          git_clone: git_limit,
           build_ext: compile_slots,
           binstub: 1,
         }
       end
 
+      def positive_integer_env(key)
+        raw = ENV[key]
+        return nil if raw.nil? || raw.empty?
+
+        value = Integer(raw, exception: false)
+        return nil unless value
+        return nil if value <= 0
+
+        value
+      end
+
       def display_bundle_path(path)
         return path if path.start_with?("/", "./", "../")
 
@@ -770,7 +1425,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 +1460,36 @@ 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)
+          cached_dir = cache.cached_path(entry.spec)
+          assembling = cache.assembling_path(entry.spec)
+          base = if entry.cached_path
+            entry.cached_path
+          elsif Cache::Validity.cached_valid?(entry.spec, cache)
+            cached_dir
+          elsif Dir.exist?(assembling)
+            assembling
+          else
+            nil
+          end
+
+          if git_source?(entry.spec.source) && base && Dir.exist?(base)
             resolve_git_gem_subdir(base, entry.spec)
+          elsif path_source?(entry.spec.source) && base && Dir.exist?(base)
+            begin
+              resolve_path_gem_subdir(base, entry.spec)
+            rescue InstallError
+              base
+            end
           else
             base
           end
@@ -826,8 +1506,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
+
+        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
 
-        repo_root
+        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)
@@ -843,19 +1555,18 @@ module Scint
           from_cache: true,
         )
         Installer::Linker.link_files(prepared, bundle_path)
-        # If this gem has a cached native build, materialize it during link.
-        # This lets reinstalling into a fresh .bundle skip build_ext entirely.
-        Installer::ExtensionBuilder.link_cached_build(prepared, bundle_path, cache)
       end
 
       def build_extensions(entry, cache, bundle_path, progress = nil, compile_slots: 1)
+        spec = entry.spec
         extracted = extracted_path_for_entry(entry, cache)
-        gemspec = load_gemspec(extracted, entry.spec, cache)
+        gemspec = load_gemspec(extracted, spec, cache)
+        promote_after_build = assembling_path?(extracted, cache)
 
-        sync_build_env_dependencies(entry.spec, bundle_path, cache)
+        sync_build_env_dependencies(spec, bundle_path, cache)
 
         prepared = PreparedGem.new(
-          spec: entry.spec,
+          spec: spec,
           extracted_path: extracted,
           gemspec: gemspec,
           from_cache: true,
@@ -866,8 +1577,24 @@ module Scint
           bundle_path,
           cache,
           compile_slots: compile_slots,
-          output_tail: ->(lines) { progress&.on_build_tail(entry.spec.name, lines) },
+          output_tail: ->(lines) { progress&.on_build_tail(spec.name, lines) },
         )
+
+        ruby_dir = Platform.ruby_install_dir(bundle_path)
+        bundle_gem_dir = File.join(ruby_dir, "gems", SpecUtils.full_name(spec))
+        if Dir.exist?(bundle_gem_dir)
+          Installer::ExtensionBuilder.sync_extensions_into_gem(extracted, bundle_gem_dir)
+          File.write(File.join(bundle_gem_dir, Installer::ExtensionBuilder::BUILD_MARKER), "")
+        end
+
+        return unless promote_after_build
+
+        promote_assembled_gem(spec, cache, extracted, gemspec, extensions: true)
+      rescue StandardError
+        if promote_after_build && extracted && Dir.exist?(extracted)
+          FileUtils.rm_rf(extracted)
+        end
+        raise
       end
 
       def sync_build_env_dependencies(spec, bundle_path, cache)
@@ -882,7 +1609,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 +1649,21 @@ 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
+
+        direct = read_gemspec_from_extracted(extracted_path, spec)
+        if direct
+          @gemspec_cache_lock.synchronize { @gemspec_cache[cache_key] = direct }
+          return direct
+        end
 
         inbound = cache.inbound_path(spec)
         return nil unless File.exist?(inbound)
@@ -931,30 +1671,97 @@ 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 read_gemspec_from_extracted(extracted_dir, spec)
+        return nil unless extracted_dir && Dir.exist?(extracted_dir)
+
+        pattern = File.join(extracted_dir, "*.gemspec")
+        candidates = Dir.glob(pattern)
+        return nil if candidates.empty?
+
+        load_gemspec_file(candidates.first, spec)
+      end
+
+      # Load a .gemspec file, temporarily injecting VERSION env var for gems
+      # like kgio/unicorn that use `ENV["VERSION"] or abort` in their gemspec.
+      def load_gemspec_file(path, spec = nil)
+        version = spec.respond_to?(:version) ? spec.version.to_s : nil
+        old_version = ENV["VERSION"]
+        begin
+          ENV["VERSION"] = version if version && !ENV["VERSION"]
+          SpecUtils.load_gemspec(path, isolate: true)
+        rescue SystemExit, StandardError
+          nil
+        ensure
+          ENV["VERSION"] = old_version
+        end
+      end
+
+      def bulk_prelink_gem_files(entries, cache, bundle_path)
+        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")
+        cache_abi_dir = cache.cached_abi_dir
+
+        gem_names = []
+        entries.each do |entry|
+          next unless entry.action == :link || entry.action == :build_ext
+
+          source_dir = entry.cached_path
+          next unless source_dir
+
+          full_name = cache.full_name(entry.spec)
+          next unless File.basename(source_dir) == full_name
+          next unless Dir.exist?(source_dir)
+          next if Dir.exist?(File.join(gems_dir, full_name))
+
+          gem_names << full_name
+        end
+
+        return if gem_names.empty?
+
+        if ENV["SCINT_TIMING"]
+          $stderr.puts "  [timing] prelink: #{gem_names.size} gems via linker"
+        end
+
+        FS.bulk_link_gems(cache_abi_dir, gems_dir, gem_names)
+      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)
+        paths = [cache.cached_spec_path(spec)]
 
-        data = File.binread(path)
-        gemspec = if data.start_with?("---")
-          Gem::Specification.from_yaml(data)
-        else
-          begin
-            Marshal.load(data)
-          rescue StandardError
+        paths.each do |path|
+          next unless File.exist?(path)
+
+          data = File.binread(path)
+          gemspec = if data.start_with?("# -*- encoding")
+            # Ruby format (to_ruby output) — most reliable, preserves require_paths
+            Gem::Specification.load(path)
+          elsif data.start_with?("---")
+            data.force_encoding("UTF-8") if data.encoding != Encoding::UTF_8
             Gem::Specification.from_yaml(data)
+          else
+            begin
+              Marshal.load(data)
+            rescue StandardError
+              data.force_encoding("UTF-8") if data.encoding != Encoding::UTF_8
+              Gem::Specification.from_yaml(data)
+            end
           end
+          return gemspec if cached_gemspec_valid?(gemspec, extracted_path)
         end
-        return gemspec if cached_gemspec_valid?(gemspec, extracted_path)
 
         nil
-      rescue StandardError
+      rescue SystemExit, StandardError
         nil
       end
 
@@ -988,87 +1795,490 @@ module Scint
       end
 
       def cache_gemspec(spec, gemspec, cache)
-        path = cache.spec_cache_path(spec)
-        FS.atomic_write(path, gemspec.to_yaml)
+        path = cache.cached_spec_path(spec)
+        content = if gemspec.respond_to?(:to_ruby)
+          gemspec.to_ruby
+        else
+          gemspec.to_yaml
+        end
+        FS.atomic_write(path, content)
       rescue StandardError
         # Non-fatal: we'll read metadata from .gem next time.
       end
 
-      # --- Lockfile + runtime config ---
+      def cache_promoter(cache)
+        @cache_promoter ||= Installer::Promoter.new(root: cache.root)
+      end
 
-      def write_lockfile(resolved, gemfile)
-        sources = []
+      def assembling_path?(path, cache)
+        return false if path.nil? || path.empty?
 
-        # 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],
+        root = File.expand_path(cache.assembling_dir)
+        candidate = File.expand_path(path)
+        candidate == root || candidate.start_with?("#{root}/")
+      end
+
+      def promote_assembled_gem(spec, cache, assembling_path, gemspec, extensions:)
+        return unless assembling_path && Dir.exist?(assembling_path)
+
+        cached_dir = cache.cached_path(spec)
+        promoter = cache_promoter(cache)
+        lock_key = "#{Platform.abi_key}-#{cache.full_name(spec)}"
+
+        promoter.validate_within_root!(cache.root, assembling_path, label: "assembling")
+        promoter.validate_within_root!(cache.root, cached_dir, label: "cached")
+
+        begin
+          result = nil
+          promoter.with_staging_dir(prefix: "cached") do |staging|
+            FS.clone_tree(assembling_path, staging)
+            manifest = build_cached_manifest(spec, cache, staging, extensions: extensions)
+            Cache::Manifest.write_dotfiles(staging, manifest)
+            spec_payload = gemspec ? gemspec.to_ruby : nil
+            result = promoter.promote_tree(
+              staging_path: staging,
+              target_path: cached_dir,
+              lock_key: lock_key,
             )
+            if result == :promoted
+              write_cached_metadata(spec, cache, spec_payload, manifest)
+            end
+            FileUtils.rm_rf(assembling_path) if Dir.exist?(assembling_path)
           end
+          result
+        rescue StandardError
+          FileUtils.rm_rf(cached_dir) if Dir.exist?(cached_dir)
+          raise
         end
+      end
 
-        # Build rubygems sources -- collect all unique URIs
-        rubygems_uris = gemfile.sources
-          .select { |s| s[:type] == :rubygems }
-          .map { |s| s[:uri] }
-          .uniq
+      def write_cached_metadata(spec, cache, spec_payload, manifest)
+        spec_path = cache.cached_spec_path(spec)
+        manifest_path = cache.cached_manifest_path(spec)
+        FS.mkdir_p(File.dirname(spec_path))
 
-        # 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
-        end
+        FS.atomic_write(spec_path, spec_payload) if spec_payload
+        Cache::Manifest.write(manifest_path, manifest)
+      end
+
+      def build_cached_manifest(spec, cache, gem_dir, extensions:)
+        Cache::Manifest.build(
+          spec: spec,
+          gem_dir: gem_dir,
+          abi_key: Platform.abi_key,
+          source: manifest_source_for(spec),
+          extensions: extensions,
+        )
+      end
 
-        # Each scoped URI gets its own source object
-        scoped_uris.each do |uri|
-          sources << Source::Rubygems.new(remotes: [uri])
+      def manifest_source_for(spec)
+        source = spec.source
+        if source.is_a?(Source::Git)
+          {
+            "type" => "git",
+            "uri" => source.uri.to_s,
+            "revision" => source.revision || source.ref || source.branch || source.tag,
+          }.compact
+        elsif source.is_a?(Source::Path)
+          {
+            "type" => "path",
+            "path" => File.expand_path(source.path.to_s),
+            "uri" => source.path.to_s,
+          }
+        else
+          source_str = source.to_s
+          if source_str.start_with?("http://", "https://")
+            { "type" => "rubygems", "uri" => source_str }
+          elsif path_source?(source)
+            { "type" => "path", "path" => File.expand_path(source_str), "uri" => source_str }
+          else
+            { "type" => "rubygems", "uri" => source_str }
+          end
         end
+      end
+
+      # --- Lockfile + runtime config ---
 
-        # 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 write_lockfile(resolved, gemfile, lockfile = nil)
+        specs, sources, preserved_layout = build_lockfile_specs_and_sources(resolved, gemfile, lockfile)
 
         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,
+          specs: specs,
+          dependencies: build_lockfile_dependencies(gemfile, lockfile),
+          platforms: preserved_layout && lockfile ? Array(lockfile.platforms) : build_lockfile_platforms(specs, lockfile),
           sources: sources,
-          bundler_version: Scint::VERSION,
-          ruby_version: nil,
-          checksums: nil,
+          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 = {}
+
+        gemfile.dependencies.each do |dep|
+          opts = dep.source_options
+
+          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
+
+      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
+
+      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
+
+      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
+
+      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
+
+        return nil if checksums.empty?
+
+        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 +2286,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,
@@ -1089,33 +2305,47 @@ module Scint
       def read_require_paths(spec_file)
         return ["lib"] unless File.exist?(spec_file)
 
-        gemspec = Gem::Specification.load(spec_file)
+        gemspec = SpecUtils.load_gemspec(spec_file)
         paths = Array(gemspec&.require_paths).reject(&:empty?)
         paths.empty? ? ["lib"] : paths
-      rescue StandardError
+      rescue SystemExit, StandardError
         ["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 +2354,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|
@@ -1132,8 +2362,12 @@ module Scint
 
           # Global cache artifacts.
           FileUtils.rm_f(cache.inbound_path(spec))
-          FileUtils.rm_rf(cache.extracted_path(spec))
+          FileUtils.rm_rf(cache.assembling_path(spec))
+          FileUtils.rm_rf(cache.cached_path(spec))
+          FileUtils.rm_f(cache.cached_spec_path(spec))
+          FileUtils.rm_f(cache.cached_manifest_path(spec))
           FileUtils.rm_f(cache.spec_cache_path(spec))
+          FileUtils.rm_rf(cache.extracted_path(spec))
           FileUtils.rm_rf(cache.ext_path(spec))
 
           # Local bundle artifacts.
@@ -1160,6 +2394,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)
@@ -1201,6 +2457,12 @@ module Scint
           when "--path"
             @path = @argv[i + 1]
             i += 2
+          when "--without"
+            @without_groups = @argv[i + 1]&.split(/[\s:,]+/)&.map(&:to_sym) || []
+            i += 2
+          when "--with"
+            @with_groups = @argv[i + 1]&.split(/[\s:,]+/)&.map(&:to_sym) || []
+            i += 2
           when "--verbose"
             @verbose = true
             i += 1
@@ -1211,6 +2473,32 @@ module Scint
             i += 1
           end
         end
+
+        # Also read BUNDLE_WITHOUT / BUNDLE_WITH env vars (Bundler compat)
+        if !@without_groups && ENV["BUNDLE_WITHOUT"]
+          @without_groups = ENV["BUNDLE_WITHOUT"].split(/[\s:,]+/).map(&:to_sym)
+        end
+        if !@with_groups && ENV["BUNDLE_WITH"]
+          @with_groups = ENV["BUNDLE_WITH"].split(/[\s:,]+/).map(&:to_sym)
+        end
+
+        # Read from .bundle/config if present
+        load_bundle_config_groups if !@without_groups && !@with_groups
+      end
+
+      def load_bundle_config_groups
+        config_path = File.join(".bundle", "config")
+        return unless File.exist?(config_path)
+
+        config = YAML.safe_load(File.read(config_path)) rescue nil
+        return unless config.is_a?(Hash)
+
+        if config["BUNDLE_WITHOUT"] && !@without_groups
+          @without_groups = config["BUNDLE_WITHOUT"].to_s.split(/[\s:]+/).map(&:to_sym)
+        end
+        if config["BUNDLE_WITH"] && !@with_groups
+          @with_groups = config["BUNDLE_WITH"].to_s.split(/[\s:]+/).map(&:to_sym)
+        end
       end
     end
   end