Fix residual-reference keep reported as drift (#1184)

[Mikola Lysenko (mikolalysenko)]

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

Fixes #1184

Summary

Since #997, a vendored PyPI revert keeps the wheel and ledger entry while another root project file still installs from it (vendor_revert_residual_reference). The everyday shape is a pipenv requirements > requirements.txt export made after vendoring. The keep itself is correct, but remove / rollback / vendor --revert reported it as drift:

• vendor_artifact_kept said "undo the drift".
• remove printed Kept vendored state …: lockfile wiring drifted.
• The top-level vendor_revert_kept error told the user to "re-run scan --mode vendored to normalize, then remove".
• rollback gave vendoredKept[].reason: "lockfile wiring drifted…".

Following that remedy loops. The re-vendor re-wires Pipfile.lock, and the next remove keeps the entry again. The hosted takeover lane had the same mislabel ("part of its vendored wiring was edited since vendoring"), and its vendor --revert remedy left the project unpatched.

Root cause

revert_pypi_opts (core vendor/pypi.rs) handled the residual-reference keep through the generic RevertOutcome::keep_artifact, which emits drift wording. The CLI's VendorRevertStep::Kept carried no cause, so every caller printed the drift text and the normalize remedy.

Fix

• Core: RevertOutcome::keep_artifact_for_reference emits vendor_artifact_kept with the real cause and remedy. kept_for_residual_reference() reports a keep whose only signal is RESIDUAL_REFERENCE_CODE. The residual warning's remedy now names every unwind (vendor --revert, remove, rollback).

• CLI: VendorRevertStep::Kept(KeepCause::{Drift, Reference}). For Reference, the following all say that a project file still installs from the vendored artifact and give the remedy "point the file named by vendor_revert_residual_reference back at the registry release (or re-export it from the restored lock), then again":

  • remove's warning, skip reason, top-level message and human error line
  • rollback's vendoredKept reason
  • vendor --revert and the manifest-reconcile skips

  The JSON error code stays vendor_revert_kept, so the contract code is unchanged. Drift keeps keep their exact existing wording.

• Takeover: a refusal whose only cause is a residual reference now names the file. Its remedy is to point that file back at the registry release and re-run scan --mode hosted.

• CLI_CONTRACT.md vendor_revert_kept row updated.

Tests (per issue)

• remove and rollback call a vendored PyPI residual-reference keep "lockfile wiring drifted", and their "re-run scan --mode vendored to normalize, then remove" remedy loops (Pipenv pipenv requirements export) #1184: mode_migration_pypi::pipenv_residual_export_keep_is_not_reported_as_drift vendors a Pipenv project and then writes a pipenv requirements-shaped export naming the vendored wheel. It runs remove (JSON and human), rollback and vendor --revert. Nothing says "drift" or "normalize", the remedy says "re-export", and Pipfile.lock is restored while the wheel is kept. After the prescribed re-export, the same command finishes and reclaims the wheel.
• remove and rollback call a vendored PyPI residual-reference keep "lockfile wiring drifted", and their "re-run scan --mode vendored to normalize, then remove" remedy loops (Pipenv pipenv requirements export) #1184 takeover lane: pipenv_residual_export_takeover_refusal_names_the_export. The redirect_vendored_revert_failed detail names requirements.txt and "re-export", not "edited since vendoring" or vendor --revert, and the package stays vendored.

Red→green: before the fix the first test failed on "reason":"lockfile wiring drifted; vendored state and manifest entry kept" and the normalize error. Both pass now.

Commands run

• cargo test -p socket-patch-core --lib vendor::: 2498 passed
• cargo test -p socket-patch-cli --all-features --test cli_remove_silent --test remove --test rollback --test covgap_commands_rollback --test covgap_commands_vendor --test in_process_rollback_vendored --test mode_migration_pypi --test scan_vendor_e2e --test in_process_vendor_pypi_takeover --test e2e_vendor_pypi_build --test vendor --test in_process_vendor --test coverage_fix_scan_hosted_dryrun_vendored: all pass
• cargo clippy --workspace --all-features -- -D warnings and cargo fmt --all -- --check: clean

Coordination: #1188 rewrites Pipfile.lock writing, and this PR doesn't touch the Pipfile.lock writers. mode_migration_pypi.rs also gets a test from the #477 PR, which appends at the end of the file, so the two may need a trivial rebase.

🤖 Generated with Claude Code

[Mikola Lysenko (mikolalysenko)]

BugBot review

[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 060e1c2. Configure here.}