fix(gem): production-safe bundler plugin — tolerant bootstrap, honest digest, project-scoped stamp

[Mikola Lysenko (mikolalysenko)]

STACKED on PR #175 (fix/gem-bundler-audit) — merge that first; this branch's base is its tip (10c0079).

Makes the bundler setup plugin production-safe. Every trigger claim was re-derived empirically against real bundler 4.0.15 (host) and 2.7.2 (the gem docker image); every behavior change is pinned by a test that fails without it (red-run evidence below).

P0 — bootstrap deadlock (fixed)

Bundler evaluates the generated plugins.rb at plugin registration, before any project gem is installed. The load-time SocketPatch.apply! got apply's exit 1 ("No packages found") and raised Bundler::BundlerError, so on a fresh clone of a setup-wired project the FIRST bundle install died (exit 29 under 4.0.15, exit 1 under 2.7) and every retry failed identically — registration never completed. Reproduced in a scratch project before fixing.

Now: patch failures never break bundle install — they warn once per process, naming what failed and the remediation (socket-patch apply --ecosystems gem), plus a "resolved" note if a later trigger succeeds. SOCKET_PATCH_STRICT=1 restores raise-on-failure. The load-time and per-gem triggers are additionally stamp-gated, so a bootstrap install is silent and defers to the forced after-install-all pass (the actual patch point).

P1 — trigger reality + honest digest (fixed)

The old header claimed plugins.rb runs "on EVERY bundle invocation" during the Gemfile pass — false. Measured surface (identical on 2.7 and 4.0):

• every bundle install — fresh and fully cached — fires before/after-install(-all) and (re-)evaluates plugins.rb;
• bundle pristine fires only the per-gem after-install events;
• bundle exec / bundle check / plain ruby / gem pristine fire nothing.

Changes: the plugin now also subscribes after-install (digest+stamp-gated), which catches bundle pristine's patch reversion in the same run (validated on both bundler versions with a mutating fake apply); the digest folds in the on-disk content of every gem-patch target file (resolved from the manifest purls under Bundler.bundle_path/gems, absence-marked, recomputed after apply) so out-of-band reversion flips the digest even when every committed input is byte-identical. The header now documents exactly which flows re-apply and which cannot (gem pristine/bundle exec heal at the next bundle install), including the stale .bundle/plugin/index caveat: hook subscriptions are recorded at registration, so checkouts registered by an older plugin keep their old subscription set until re-registration (fresh clones/CI always re-register).

P2 — stamp location (fixed)

The digest stamp was a fixed-name file under Bundler.bundle_path — with no bundle path configured, the interpreter's machine-global gem dir, shared and clobbered across every socket-patch project on the host. It now lives at .socket/gem-plugin-stamp (project-local, safe to gitignore/delete, excluded from its own digest inputs). Migration: the legacy global stamp is deleted best-effort and never read.

P2 + nits — launcher.rb

• Windows arm propagates the child's real exit code (was: every non-zero collapsed to 1).
• Binary-cache install is atomic: temp file in the destination dir → chmod → File.rename (Windows rename race tolerated when a concurrent run already published).
• Non-LauncherError first-run failures (DNS/TLS/...) exit with a clean one-line message instead of a raw backtrace.
• PowerShell Expand-Archive fallback quotes paths containing single quotes (powershell_quote, ''-doubling).
• Bonus bug found by the new guard: version's documented from-a-checkout fallback never engaged — Gem::MissingSpecError is a Gem::LoadError (ScriptError family), not a StandardError; the rescue now names it.
• socket-patch-bundler.gemspec: stale git: comment → path: (true since Structure-review batch: sweep fixes, module taxonomy, npm-family dedup, coverage gaps, CI honesty #150).

setup-matrix: gem with-setup cases are GREEN

run-case.sh now serves the real git-blob beforeHash for gem fixtures, probed from the published .gem (gem fetch + gem unpack, mirroring docker_e2e_gem's probe; verified against an independent oracle hash). Combined with the deadlock fix, the formerly-gapped gem docker cases (baseline_with_setup, alt_content_patchset) — and the formerly-red wrong_target_patchset — now pass with no dependency on any sibling apply-side change: the full 6-case gem matrix is green in host mode (bundler 4.0.15, real rubygems.org installs) and docker mode (image rebuilt from this branch, bundler 2.7). npm-family separability: the fixtures the old and new driver produce for npm are byte-identical across all patchsets (diff-verified); non-gem ecosystems keep the zero placeholder. Note for local runs: a gem image built before this branch bakes the old binary (old raising template) and will still red-flag the with-setup cases — rebuild the image or use SOCKET_PATCH_TEST_HOST=1 (the stale-image hint is in the harness failure message).

Tests (each red without its fix)

Pin	Test	Red on base
P0 deadlock	setup_matrix_gem::plugin_runtime::first_bundle_install_survives_failing_apply (real bundle install, fake apply exit 1, generated by the real binary)	exit 29, "Failed to install plugin"
strict hatch	plugin_runtime::strict_mode_fails_bundle_install_on_apply_failure	green on base (base always raised); pins the hatch against the tolerant default
P2 stamp + digest gate	plugin_runtime::successful_apply_stamps_project_scoped (stamp path, 64-hex content, no legacy file, exactly +1 forced apply per cached install)	stamp under vendor/bundle
P1 content digest + migration	plugin_runtime::digest_tracks_gem_file_content_and_legacy_stamp_is_removed (plain-ruby drive; reversion must re-trigger; legacy stamp deleted)	manifest-only digest misses reversion; legacy stamp kept
template invariants	core test_plugin_template_failure_policy_and_stamp_location (new) + test_templates_are_well_formed (extended; also pins published-twin parity)	2 failures
launcher exit code	launcher_guard::windows_branch_propagates_child_exit_code (win_platform stub, child exits 7)	got 1
launcher error wrap	launcher_guard::unexpected_download_errors_exit_cleanly (stubbed Net::HTTP.start raising SocketError)	raw backtrace
ps-quote / atomic install	launcher_guard::powershell_quote_doubles_single_quotes, install_executable_is_atomic_into_place	helpers absent

Red-run evidence: with only the base-branch plugins.rb.tmpl + launcher.rb restored, 7 of 8 runtime/launcher guards fail and both core template tests fail; all green with this branch.

Verification

• core 2461/0, cli lib 350/0, clippy + fmt clean on both crates
• setup_matrix_gem 11/11 — including the docker-mode 6-case gem matrix on an image rebuilt from this branch and a host-mode (4.0.15) matrix run
• docker_e2e_gem 2/2, docker_e2e_vendor_gem 1/1, e2e_gem 11/11 (incl. live lifecycle)

Out-of-scope notes (not in my owned files)

• CLI_CONTRACT.md §gem hook table and README §705 still describe the old "load-time digest gate + after-install-all" wording and don't mention SOCKET_PATCH_STRICT; follow-up doc touch-up needed.
• Existing wired checkouts keep a stale .bundle/plugin/index (after-install-all only) until re-registration; setup does not force re-registration (deleting .bundle/plugin could break users' other plugins offline). Documented in the template header instead.
• The plugin's warn-per-process on a manifest that matches nothing (e.g. wrong_target) repeats on every install by design — the honest signal until the stale record is removed; strict mode makes it fatal.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes default bundle install behavior for all setup-wired Ruby projects (warn vs fail) and re-apply logic; misconfiguration could leave gems unpatched until strict mode or manual apply, but scope is gem/Bundler integration rather than core auth or data paths.

Overview
Makes the generated Bundler plugin safe for fresh clones and honest about on-disk gem state, with matching updates to the published socket-patch-bundler twin and the RubyGems launcher.

Bootstrap / failure policy: Apply failures no longer raise Bundler::BundlerError by default (fixes first bundle install deadlock when plugins.rb runs before gems exist). Failures warn with remediation; SOCKET_PATCH_STRICT=1 restores fatal behavior. Load-time and per-gem after-install triggers use require_stamp so bootstrap installs defer to forced after-install-all.

Triggers & digest: Adds digest-gated after-install (covers bundle pristine in the same run). Digest folds in actual patch-target file bytes under the bundle path, excludes the stamp from its own inputs, and recomputes after apply. APPLY_LOCK mutex avoids concurrent apply children.

Stamp: Digest stamp moves to .socket/gem-plugin-stamp; legacy .socket-patch-gem-stamp under Bundler.bundle_path is deleted best-effort.

Tests & matrix: New plugin_runtime tests (real bundle install with fake apply) and launcher_guard tests; setup-matrix gem fixtures use real beforeHash from published gems via resolve_before_hash in run-case.sh.

Launcher: Windows propagates child exit codes; atomic cache install; clean non-LauncherError failures; PowerShell path quoting; Gem::LoadError fallback for version.

^{Reviewed by Cursor Bugbot for commit c11248c. 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 c11248c. Configure here.}

[cursor]

Platform gem digest misses on Windows

Medium Severity

patch_target_files builds the platform-gem pattern with File.join and passes it to Dir.glob. On Windows File.join yields backslashes, and Dir.glob treats \ as an escape, so the * never matches. Platform installs (e.g. nokogiri-…-x64-mingw-ucrt) are omitted from the digest, so a bundle pristine reversion can leave the stamp matching and skip re-apply.

Additional Locations (1)

• gem/socket-patch-bundler/plugins.rb#L130-L132

 

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

[Mikola Lysenko (mikolalysenko)]

Polish pass for the adversarial review findings (commit e356b1b), all empirically validated against real bundler 4.0.15:

Major 1 — stamp-existence bootstrap gate (committed-dir stamp): Reproduced the resurrection first: a stale .socket/gem-plugin-stamp committed by git add .socket + SOCKET_PATCH_STRICT=1 on a fresh clone gave exit 29, Failed to install plugin, no plugin index, identical retries. Fix is the reviewer's gate rework: apply!'s bootstrap gate (renamed from require_stamp) now bails while none of the manifest's gem-patch targets exist on disk — it reads the live gem tree, never the stamp, which is now a pure digest cache. Registration stays quiet whatever the stamp says; strict enforcement waits for the post-install hooks (where the failure is remediable and registration is already recorded, so retries converge). setup also wires /gem-plugin-stamp into .socket/.gitignore (append-only, user lines spared; --check demands it, keeping check/setup agreement), killing both the git-status churn and the committed-stamp vector. Twin mirrored. Pinned by plugin_runtime::committed_stale_stamp_does_not_deadlock_strict_fresh_clone (registration index present, no Failed to install plugin, hook-only failure, retry with working apply exits 0) — fails on the previous tip.

Major 2 — matrix.json gem row: flipped to hook_family: "bundler-plugin", baseline_supported: true, so a future with-setup regression classifies as blocking regression rather than known_gap. The gem Docker matrix leg ran green with the flip in place.

Minor (strict message lies): report_failure now appends a mode-branched trailer — the strict raise says the install is failing because SOCKET_PATCH_STRICT is set (unset to warn-and-continue); tolerant keeps the old wording. Pinned by new asserts in strict_mode_fails_bundle_install_on_apply_failure.

Minor (header claim about deleting the stamp): with the gate rework the original claim is now true — verified with a real bundle pristine after deleting the stamp: old template never shells apply (patches stay reverted), new one heals in the same run. Header reworded to match; pinned by plugin_runtime::bootstrap_gate_keys_on_target_presence_not_stamp (both gate directions).

Minor (remove leaves stamp orphaned): gem --remove best-effort deletes the stamp and strips our .gitignore line (file deleted when nothing else is left). Pinned in the host_guard remove round-trip + core gem tests.

Minor (launcher_guard env scrub): run_ruby (and the atomic-install test's direct command) now scrub RUBYOPT/BUNDLE_*/GEM_*/SOCKET_* like plugin_runtime::scrub.

Tests: core 2463 pass; setup_matrix_gem 13/13 (incl. the real Docker matrix leg, 76s) ; setup_invariants 29 pass; deno/maven/monorepo/nuget/env_guard matrix suites green. Pre-existing, unrelated to this diff: setup_matrix_npm (stale 3-week image; the documented wrong_target/empty_patchset install_exit=1 bug), setup_matrix_pypi and setup_matrix_composer docker legs fail the same aspirational expectations on this machine — no data-flow from the gem-only diff into those cases.

🤖 Generated with Claude Code

[Mikola Lysenko (mikolalysenko)]

Bugbot finding (Medium, plugins.rb patch_target_files platform-gem glob): CONFIRMED and fixed in ee9383c.

Verification before fixing (host ruby 3.4.10):

• Dir.glob treats \ as an escape on every platform: a pattern base of vendor\bundle escape-eats the separator and matches only a (nonexistent) vendorbundle, so the <name>-<version>-* platform wildcard returns nothing.
• Bundler.bundle_path carries backslashes through verbatim: BUNDLE_PATH='vendor\bundle' → <root>/vendor\bundle/ruby/3.4.0. So on Windows the platform installs (e.g. nokogiri-1.15.0-x64-mingw-ucrt) drop out of the digest and a bundle pristine reversion of them leaves the stamp matching — re-apply skipped, exactly as flagged.

Fix: glob a slash-normalized base (glob_gems_dir = gems_dir.tr("\\", "/")) — forward slashes are valid separators on Windows; the direct non-glob join stays byte-faithful. Applied to BOTH the setup template (crates/socket-patch-core/src/setup/gem/templates/plugins.rb.tmpl) and the published twin (gem/socket-patch-bundler/plugins.rb), with new needles in the core parity test pinning the normalization in each.

Regression test (plugin_runtime::backslash_bundle_path_still_digests_platform_gem_files in setup_matrix_gem.rs): drives the generated plugins.rb with plain ruby under BUNDLE_PATH='vendor\bundle' while the real gem tree lives at the forward-slash spelling — the two-spellings-one-directory situation Windows creates (glob escape semantics are identical everywhere). Asserts the platform install is enumerated as a patch target and that reverting its content flips the digest and re-runs apply. Verified red without the fix (re-apply skipped: 1 call instead of 2, at exactly the flagged failure mode) and green with it.

Runs: cargo test -p socket-patch-core setup::gem (54 passed), SOCKET_PATCH_TEST_HOST=1 cargo test -p socket-patch-cli --features docker-e2e,setup-e2e --test setup_matrix_gem (14 passed), clippy clean on both crates, ruby -c OK on both plugin files.

🤖 Generated with Claude Code

[Mikola Lysenko (mikolalysenko)]

Rebased fix/gem-plugin-bootstrap onto the freshly-rebased base branch fix/gem-bundler-audit (new base tip: 99f9cd0, which now carries main's 11 new commits — --vendor-source in vendor_flow, hosted JSON envelope changes, maven/nuget GA, #157/#164/#169).

Transplanted exactly this PR's 3 commits via git rebase --onto origin/fix/gem-bundler-audit d063cb1:

• c11248c → 4f68bc4 (production-safe bundler plugin)
• e356b1b → 9b0fd73 (bootstrap gate keys on target presence)
• ee9383c → c954115 (platform-gem glob base forward slashes)

Conflicts: none — all three commits replayed identically (range-diff shows = for each); no behavior-changing judgment calls were needed.

Verification (all green):

• cargo test -p socket-patch-core setup::gem — 54 passed
• SOCKET_PATCH_TEST_HOST=1 cargo test -p socket-patch-cli --features docker-e2e,setup-e2e --test setup_matrix_gem — 14/14 passed
• cargo test -p socket-patch-cli --features docker-e2e,setup-e2e --test docker_e2e_gem — 2 passed
• cargo fmt --check + clippy: this PR's files are clean. Note: origin/main itself has 23 pre-existing rustfmt-1.8.0 (toolchain 1.93.1) drift hunks and 3 clippy doc warnings (in files from fix(vendor): resolve installed packages via the qualified-purl-aware lookup #157/fix(scan): warn when a mode takeover leaves the other ledger stale #164/test(vendored): real-production e2e for scan --mode vendored across every package manager #169 etc.); this branch carries a strict subset of those (21 hunks) and adds none — left untouched to avoid unrelated noise.

New tip: c954115

🤖 Generated with Claude Code