fix(gem): setup --remove clears bundler's machine-local .bundle/plugin registration

[Mikola Lysenko (mikolalysenko)]

Defect

socket-patch setup --remove un-wired the Gemfile and deleted the generated plugin files, but left bundler's machine-local plugin registration (.bundle/plugin/index) dangling. Every later bundle install then prints bundler's block forever:

The following plugin paths don't exist: .../.socket/bundler-plugin
... Continuing without installing plugin socket-patch

with a misleading reinstall suggestion — on a project the user just cleanly ejected from.

Root cause

remove_plugin_directive (crates/socket-patch-core/src/setup/gem/update.rs:255) had only two steps: Gemfile un-wire + remove_plugin_files. Nothing ever touched the index bundler writes on first install (hook subscriptions in hooks:, plus plugin_paths:/load_paths: entries). Matches campaign REPORT.md root cause D3/C3 (dangling .bundle/plugin registration after setup --remove).

Campaign repro evidence

• Original repro agent-b4/eject-setup-remove (bundler 4.0.18) re-run against a gem-b4 image rebuilt from this branch's binary under unique tags (socket-patch-test-{base,gem-b4}:f3-setup-remove; no :latest touched): ===EJECT-SETUP-REMOVE PASS===, out/i3.log now contains zero plugin mentions (only Bundle complete!), and stale .bundle/plugin dir present: no (was yes + the 5-line bundler block).
• Verification artifacts: session scratchpad f3-verify/ (Dockerfile.gem-b4-f3 + b4 scenario copy with post-fix out/); images left in place for reviewer re-runs.
• agent-b2 (bundler 2.7.2) shows the same residue pre-fix; the 2.7/4.0 index dialect is identical (bundler YAMLSerializer), covered by unit tests + the real host-bundler 4.0.15 runtime test.

Fix

remove_plugin_directive gains a third step, remove_plugin_registration (crates/socket-patch-core/src/setup/gem/mod.rs), which:

• resolves the index exactly like Bundler.app_config_path ($BUNDLE_APP_CONFIG, relative resolved against the project root, else <root>/.bundle);
• parses only bundler's YAMLSerializer dialect (verified against the campaign's real 4.0.18 index) and strips socket-patch from plugin_paths/load_paths/hooks/commands/sources, dropping hook events it empties, keeping every other plugin's lines byte-verbatim;
• deletes a bundler-installed plugin dir only when inside the plugin root; deletes the index when no plugin remains (bundler regenerates on demand) and prunes emptied dirs; rewrites atomically when other plugins remain; dry-run writes nothing;
• never rewrites an unrecognized index shape — that surfaces as a new remove-only gem_plugin_registration files[] error naming the remedy bundler plugin uninstall socket-patch (documented in CLI_CONTRACT.md; README --remove row updated).

Scoped away from the sibling lane: no edits to update.rs's PLUGIN_BLOCK/add path or version-gate regions.

Tests (red → green)

Red commit e91f98f (tests only) fails on main's production code exactly as designed; fix commit f8ee008 turns it green:

• setup_matrix_gem::host_guard::gem_setup_roundtrip_host — seeds the campaign's verbatim index; pre-fix panic "remove must clear bundler's machine-local plugin registration".
• host_guard::gem_setup_remove_strips_registration_surgically_under_bundle_app_config — multi-plugin index under BUNDLE_APP_CONFIG: other plugin kept byte-verbatim, emptied hook event dropped.
• plugin_runtime::setup_remove_clears_bundler_plugin_registration — real host bundler 4.0.15: bundle install registers → setup --remove → next install must print no plugin warning.
• 14 new -core unit tests (surgical strip, index deletion + dir prune, dry-run, unparseable-index residue-without-corruption, containment gate, Bundler.app_config_path resolution incl. the ruby-image /usr/local/bundle case) + update.rs envelope-entry test.

Review sign-off + follow-ups addressed

Independent reviewer verdict: approve, red/green independently verified via per-file baseline checkout (all 3 new tests fail on da58dee's production code, 16/16 + 69/69 green at HEAD). The review's non-blocking findings are addressed in follow-up commits on this branch, red-first where a red exists:

1. P2 traversal (0a0295e red, 11d007c fix): Path::starts_with is lexical, so a crafted committed index recording <plugin_root>/../../victim passed the containment gate into remove_dir_all. Red test proves the victim dir was deleted; fix rejects any recorded dir containing a .. component.
2. P2 hermeticity (75084db): remove_plugin_directive read ambient BUNDLE_APP_CONFIG, so -core unit tests failed spuriously on machines exporting it (verified red with BUNDLE_APP_CONFIG=/usr/local/bundle) and could have touched a real machine-local index. Env now threaded through an explicit remove_plugin_directive_at; tests inject None.
3. nit fmt (499e498): the branch's 5 rustfmt divergences fixed; workspace --check back to main's pre-existing count.

Final gate (post-follow-ups)

• cargo test -p socket-patch-core --lib setup::gem — 69 passed, 0 failed (also green with BUNDLE_APP_CONFIG=/usr/local/bundle exported)
• cargo test -p socket-patch-cli --features setup-e2e --test setup_matrix_gem — 16 passed (incl. the real-bundler leg)
• setup_invariants 29 / cli_setup_silent 6 / cli_parse_setup 19 — all ok
• cargo clippy --workspace --all-features -- -D warnings — clean

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes gem setup --remove file I/O and index rewriting on a committed attacker-influenced path; traversal rejection and dialect refusal limit blast radius, and coverage includes real bundler e2e tests.

Overview
Fixes incomplete gem eject: setup --remove used to restore the Gemfile and delete .socket/bundler-plugin but left bundler's machine-local plugin registration in .bundle/plugin/index, so every later bundle install warned about missing plugin paths.

Third remove step: After Gemfile un-wire and plugin file deletion, removal now clears that registration via remove_plugin_registration — resolving the index like Bundler.app_config_path ($BUNDLE_APP_CONFIG, relative paths against the project root), parsing only bundler's YAMLSerializer index dialect, stripping socket-patch from hooks/paths/commands while keeping other plugins byte-verbatim, atomically rewriting or deleting the index, and pruning empty dirs. Unparseable indexes are not guessed; cleanup failure surfaces a gem_plugin_registration files[] error with the bundler plugin uninstall socket-patch fallback.

Safety & docs: Recorded install-dir deletion is containment-gated and rejects .. traversal in index paths. README and CLI_CONTRACT.md document the new behavior and JSON kind.

^{Reviewed by Cursor Bugbot for commit 499e498. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{Bugbot Autofix is ON. A cloud agent has been kicked off to fix the reported issue.}

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

^{Reviewed by Cursor Bugbot for commit 499e498. Configure here.}