Fix gem crawler missing Bundler .bundle root (#967)

[Mikola Lysenko (mikolalysenko)]

LLM Description written by Claude Code:claude-opus-5-5

Fixes #967

Stacked on #916 (base branch agent/fix-gem-path-system-default-root). Both issues come from the same gap: the gem crawler's install-root discovery doesn't model Bundler's Settings#path → Path#use_system_gems? / base_path resolution. #916 handles the system_path half (#915). This PR handles the base_path = ".bundle" half and generalizes #916's bundler_path_system into a bundler_path_tier resolver both halves share. Once #916 merges, GitHub retargets this PR to main.

Root cause

When no settings tier sets path, path.system or disable_shared_gems, Bundler's use_system_gems? is !default_install_uses_path? on 2.x and !bundler_5_mode? on 4.x (checked in the 2.5.22 and 4.0.18 sources). So simulate_version 5 turns it off, and Bundler 5 will make that the default. When it's false, base_path is <root>/.bundle, and gems install to <root>/.bundle/<engine>/<abi>/gems. discover_bundle_stores_impl never probed that root. So agent apply patched only the system copy, vex attested not_affected over the unpatched loaded copy, and the hosted stale-install guard missed a stale .bundle copy.

Fix

• bundler_path_tier returns the deciding tier's explicit_path and system (or None). Fix gem crawl ignoring Bundler path.system (#915) #916's path.system handling is unchanged on top of it.
• <cwd>/.bundle is probed (both layouts) when that tier names no path and no truthy path.system. The version-dependent flags aren't read: the scoped store only exists once Bundler installed there, which is the same "probe if present" rule the default vendor/bundle uses. Like the other explicit roots, it keeps the gem env fallback on, because default gems stay in the system homes.
• The .bundle root only counts for a Ruby project (Bundler manifest present), like the other explicit roots.
• CLI_CONTRACT.md "Gem install roots" now lists the root.

Tests (red → green)

Test	Without fix	With fix
ruby_crawler::tests::dot_bundle_base_path_is_crawled (no config, local simulate_version 5, local default_install_uses_path, falsy path.system)	FAIL	pass
ruby_crawler::tests::dot_bundle_base_path_with_global_flag_is_crawled	FAIL	pass
ruby_crawler::tests::dot_bundle_base_path_is_skipped_when_bundler_does_not_use_it (controls: local/env/global path, empty path, path.system in each tier, non-Ruby dir)	pass	pass
crawler_ruby_e2e::dot_bundle_base_path_crawls_the_loaded_copy (ambient discovery finds the .bundle copy before the gem env home; local and env flags)	FAIL	pass
e2e_redirect_gem_stale_install::gem_hosted_stale_dot_bundle_install_warns_and_is_not_attested (hosted guard names the stale .bundle copy, same-run --vex doesn't attest)	FAIL	pass

Per-issue checklist:

• Gem crawler ignores Bundler's .bundle default install path (default_install_uses_path on 2.x, simulate_version 5 on 4.x), so agent apply patches the system copy and vex attests not_affected while Bundler loads the unpatched .bundle/ruby/<abi> copy #967: agent apply / vex (crawler unit + e2e tests above) and the hosted stale guard (CLI e2e above).

Real Bundler check (Ruby 3.3.6, Bundler 4.0.18, bundle config set --local simulate_version 5, bundle install → ./.bundle/ruby/3.3.0/gems/colorize-0.8.1, hand-written manifest):

• socket-patch apply --offline --json → applied, and bundle exec now loads the patched file (include?("SOCKET-PATCHED") → true).
• socket-patch vex → not_affected. After reverting the .bundle copy by hand, vex omits the purl (not_applied).

Local runs:

• cargo clippy --workspace --all-features -- -D warnings: clean.
• rustfmt --check on the changed files: clean. CI has no fmt job, and main isn't fmt-clean repo-wide.
• cargo test --workspace --all-features: 10829 passed, 12 failed. All 12 are chmod/unwritable-file tests (e.g. vendor_state_write_failure_reports_failed_event, copy_tree::relax_loop_must_not_traverse_symlinked_root). They can't fail a write when run as root, which this container is. None of them touch gem code, and CI runs them as non-root.

Notes

• Bundler resolves .bundle against Bundler.root. Like the other roots here, this uses --cwd. A BUNDLE_GEMFILE that moves the root is Gem agent crawl ignores that BUNDLE_GEMFILE=gemfiles/x.gemfile moves Bundler.root, so a relative bundle path resolves to the wrong dir, apply patches the system copy and vex attests not_affected while Bundler loads the unpatched gemfiles/vendor/bundle copy #952's separate cause.

🤖 Generated with Claude Code

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

BugBot review

---

Generated by Claude Code

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 25e3ca6. Configure here.}

[Mikola Lysenko (mikolalysenko)]

[agent] Ready for review at 25e3ca6.

• CI: all check runs on 25e3ca6 green (93 success, 3 skipped, 1 neutral; 0 failing). Mergeable, clean.
• Bugbot: reviewed 25e3ca6, no findings. No open review threads.
• For reviewers: this PR is stacked on Fix gem crawl ignoring Bundler path.system (#915) #916 (base agent/fix-gem-path-system-default-root). Merge Fix gem crawl ignoring Bundler path.system (#915) #916 first, then retarget this to main.

---

Generated by Claude Code