v5 Bundler plugin cleanup leaves .bundle/plugin registered in every other checkout, so bundle install crashes with LoadError on Bundler 2.3–2.5 #1295

[agent] Found by the scheduled Bundler (RubyGems) bug-hunt routine (ledger #316).

Summary

v5 removed setup, including setup --remove, which since #210 also cleared Bundler's machine-local plugin registration (.bundle/plugin/index). The v5 cleanup instructions don't fully replace it:

• docs/migrating-to-v5.md:93 tells the person migrating to remove the Gemfile plugin "socket-patch" block, run bundle plugin uninstall socket-patch, and delete .socket/bundler-plugin/.
• CLI_CONTRACT.md ("Agent mode in CI (v5.0: setup removed)") and the socket-patch setup error in lib.rs:334 only say to remove the block and .socket/bundler-plugin/ by hand. Neither mentions bundle plugin uninstall.

.bundle/ isn't committed, so bundle plugin uninstall only clears the checkout it runs in. Any other checkout that ran bundle install while the v4 plugin was wired still has the registration: other developers' machines, persistent CI runners, and the migrator's own checkout if they followed CLI_CONTRACT.md. Once those checkouts pull the cleanup commit, .bundle/plugin/index points at a plugins.rb that no longer exists:

• Bundler 2.3, 2.4 and 2.5: every bundle install aborts with LoadError: cannot load such file -- …/.socket/bundler-plugin/plugins.rb (exit 1). Bundler 2.5 is the default on Ruby 3.3.
• Bundler 2.6 and 4.0: the install prints "The following plugin paths don't exist … Continuing without installing plugin socket-patch" on every run. That's the residue fix(gem): setup --remove clears bundler's machine-local .bundle/plugin registration #210 fixed for v4.

bundle exec and bundle check still work. Running bundle plugin uninstall socket-patch (or deleting .bundle/plugin) in the affected checkout recovers it, but nothing tells those users to do that.

Impact

After a team migrates to v5 as documented, every teammate and persistent runner on Bundler ≤ 2.5 gets a crashing bundle install. The error doesn't mention socket-patch, and there's no v5 command that cleans it up.

Repro (Linux, Ruby 3.3.6)

npm pack @socketsecurity/socket-patch-linux-x64-gnu@4.0.0 && tar xzf socketsecurity-*.tgz   # v4 binary
export BUNDLER_VERSION=2.5.22
mkdir app && cd app
printf 'source "https://rubygems.org"\ngem "colorize", "0.8.1"\n' > Gemfile
bundle config set --local path vendor/bundle
../package/socket-patch setup --yes        # v4: managed plugin block + .socket/bundler-plugin/
bundle install                             # registers the plugin in .bundle/plugin/index
# The migration commit as it arrives in a teammate's checkout (block and dir removed):
printf 'source "https://rubygems.org"\ngem "colorize", "0.8.1"\n' > Gemfile
rm -r .socket/bundler-plugin
bundle install; echo "exit $?"
# LoadError: cannot load such file -- …/app/.socket/bundler-plugin/plugins.rb
#   …/bundler/plugin.rb:347:in `load_plugin' … in `block in hook'
# exit 1
bundle plugin uninstall socket-patch && bundle install   # recovers

Expected vs actual

• Expected: following the v5 cleanup leaves every checkout able to bundle install, as setup --remove did after fix(gem): setup --remove clears bundler's machine-local .bundle/plugin registration #210 ("clears bundler's machine-local .bundle/plugin registration"). CLI_CONTRACT.md says old hooks "keep working until you delete them; remove them by hand", which implies that removing them by hand is enough.
• Actual: removing the block and the plugin dir (the CLI_CONTRACT.md recipe, or the migration-guide recipe as it reaches any other checkout) breaks bundle install on Bundler 2.3–2.5, and leaves a warning on every run with 2.6 and 4.0.

Matrix (each Bundler cell reproduced twice in a fresh project)

The failure is in Bundler's own plugin loader, so it doesn't depend on the OS.

First bad release

v5.0.0: setup and its --remove were dropped (#279). On v4.0.0, setup --remove cleared the registration (#210).

Suspect locations

• docs/migrating-to-v5.md:93: the Bundler row lists bundle plugin uninstall as a one-time step. It doesn't say that every existing checkout needs it, or rm -rf .bundle/plugin.
• crates/socket-patch-cli/CLI_CONTRACT.md:448-456 and crates/socket-patch-cli/src/lib.rs:334: the removal recipe and the setup error omit the registration step entirely.

Possible directions: document the per-checkout step in all three places. Alternatively, have v5 (for example apply / scan on a gem project) detect a .bundle/plugin/index that registers socket-patch at a missing .socket/bundler-plugin path and warn with the one-line fix.