Stop calling a residual-reference keep drift

When a vendored PyPI revert restored its recorded wiring but kept the
wheel because another project file (a `pipenv requirements` export)
still installs from it, `remove` and `rollback` reported the keep as
"lockfile wiring drifted" and told the user to re-run `scan --mode
vendored` to normalize, then remove. That remedy loops: the re-vendor
re-wires Pipfile.lock and the next remove keeps the entry again.

The keep now carries its cause. `vendor_artifact_kept`, the remove
warning, skip reason and top-level error, rollback's vendoredKept
reason and `vendor --revert` / reconcile skips say a project file
still installs from the artifact, and the remedy is to point that file
back at the registry release (or re-export it from the restored lock)
and run the unwind again. A hosted takeover refused for the same
reason names the file instead of a wiring edit. Drift keeps keep their
existing wording.

Fixes #1184

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: mikolalysenko

crates/socket-patch-cli/CLI_CONTRACT.md

@@ -1266,7 +1266,7 @@ Every `--json` invocation emits a single JSON object that follows the **unified
 | `vendor_state_retained`   | `skipped`        | remove `--skip-rollback`: vendor wiring + artifact deliberately left in place (the next `vendor` run reconciles the dropped entry). Also the top-level error code when `--skip-rollback` targets a vendored patch with no manifest record (every `scan`/`get --mode vendored` entry — and, v5.0, the ledger-only leftover of an earlier `remove --skip-rollback` of a manifest-tracked vendored patch). |
 | `hosted_state_retained`   | (top-level error) | remove `--skip-rollback` targeting a hosted-only patch (no manifest entry): restoring the pin's upstream registry entry is the only possible removal, so the combination is refused (exit 1), mirroring the manifest-less vendored refusal above. |
 | `vendor_state_preserved`  | `skipped`        | remove `--preserve-state` (v5.0): lockfile unwired; artifact, ledger entry, and manifest entry all kept for a later re-apply. Rollback's counterpart is the `vendoredPreserved: []` envelope array. |
-| `vendor_revert_kept`      | `skipped` + top-level error | remove (v5.0): the vendored revert drift-kept (`kept_artifact`), so the ledger entry AND the manifest entry were both kept. ANY drift-keep makes the run a `partialFailure` (exit 1) — part of the requested removal did not happen; when EVERY matching entry drift-kept, the top-level error carries this code (`summary.removed` stays 0; the identifier DID match, so never `not_found`). Remedy: re-run `scan --mode vendored` to normalize, then remove. Rollback's counterpart is the `vendoredKept: []` envelope array (also exit 1). |
+| `vendor_revert_kept`      | `skipped` + top-level error | remove (v5.0): the vendored revert drift-kept (`kept_artifact`), so the ledger entry AND the manifest entry were both kept. ANY drift-keep makes the run a `partialFailure` (exit 1) — part of the requested removal did not happen; when EVERY matching entry drift-kept, the top-level error carries this code (`summary.removed` stays 0; the identifier DID match, so never `not_found`). Remedy: re-run `scan --mode vendored` to normalize, then remove. A PyPI revert that restored its recorded wiring but kept the wheel because another project file still installs from it (`vendor_revert_residual_reference`, e.g. a `pipenv requirements` / `uv export` / `poetry export` requirements file) is a keep too, but not a drift (#1184): its skip reason, the per-entry warning, the top-level message and rollback's `vendoredKept[].reason` say that a project file still installs from the vendored artifact, and the remedy is to point the file named by `vendor_revert_residual_reference` back at the registry release (or re-export it from the restored lock), then remove (or roll back) again. Its `vendor_artifact_kept` advisory says the same, and a hosted takeover refused for it (`redirect_vendored_revert_failed`) names the file instead of a wiring edit. Rollback's counterpart is the `vendoredKept: []` envelope array (also exit 1). |
 | `hosted_reverted`         | `removed`        | remove (v5.0): a hosted lockfile pin was restored to its upstream registry entry as part of removing the patch (`verified` on dry-run). Beside a manifest entry it bypasses `summary.removed` like `vendor_reverted`. |
 | `hosted_revert_failed`    | top-level error  | remove (v5.0): a matched hosted pin could not be restored to its upstream registry entry (`--offline`, a registry that does not answer, `bun.lockb`, a lock shape the restore refuses — see "Hosted unwind coverage"), or writing the restored files failed; the message names the `git checkout -- <files>` remedy. The manifest was not modified, exit 1. Rollback's counterpart is a `hosted.failed[]` entry (also `partial_failure` exit 1). v4's `hosted_revert_unsupported` is no longer emitted (every ecosystem has a restore). |
 | `reinstall_required`      | rollback `warnings[]` | rollback (v5.0): vendored/hosted wiring was unwound, but installed trees keep their patched bytes until the next package-manager install — the stale-install advisory. When the run also emits a Bun advisory (`vendor_bun_reinstall_required` / `redirect_bun_reinstall_required`) the detail and the human note add " (Bun: a plain `bun install` keeps them; run `bun install --force`)". |

crates/socket-patch-cli/src/commands/remove.rs

@@ -18,7 +18,9 @@ use super::rollback::{rollback_patches_inner, InnerSelection};
 use crate::args::{apply_env_toggles, GlobalArgs};
 use crate::commands::hosted_unwind::{run_hosted_leg, HostedLegOutcome};
 use crate::commands::lock_cli::acquire_or_emit;
-use crate::commands::vendored_backend::{RevertedEntry, VendorRevertStep, VendoredBackend};
+use crate::commands::vendored_backend::{
+    KeepCause, RevertedEntry, VendorRevertStep, VendoredBackend,
+};
 use crate::json_envelope::{Command, Envelope, EnvelopeError, PatchAction, PatchEvent, Status};
 use crate::ui::short_uuid;
 use crate::ui::{plural, sweep_failure};
@@ -863,11 +865,7 @@ pub async fn run(args: RemoveArgs) -> i32 {
         // this is the only way the removal can be empty): the remove did
         // not happen. NOT not_found; partialFailure keeps `summary.removed`
         // honest at 0.
-        let msg = format!(
-            "{}: every matching entry's vendored state drift-kept; nothing was \
-             removed (re-run `scan --mode vendored` to normalize, then remove)",
-            args.identifier
-        );
+        let msg = all_kept_message(&args.identifier, &vendor_leg.kept_causes);
         track_patch_remove_failed(&msg, &telemetry).await;
         if args.common.json {
             let mut env = Envelope::new(Command::Remove);
@@ -1125,21 +1123,62 @@ pub async fn run(args: RemoveArgs) -> i32 {
         // above are gated, so name the outcome once here.
         if !args.common.json {
             eprintln!(
-                "Error: {} matching entr{} drift-kept (vendored state and manifest \
-                 record retained); re-run `scan --mode vendored` to normalize, then \
-                 remove again",
-                vendor_leg.kept.len(),
-                if vendor_leg.kept.len() == 1 {
-                    "y was"
-                } else {
-                    "ies were"
-                }
+                "Error: {}",
+                kept_error_line(&vendor_leg.kept_causes, "manifest record")
             );
         }
         1
     }
 }
 
+/// The top-level error when every matching vendored entry was kept: the
+/// drift wording and its normalize remedy only for drift-keeps (#1184).
+fn all_kept_message(identifier: &str, causes: &[KeepCause]) -> String {
+    if causes.iter().all(|c| *c == KeepCause::Drift) {
+        return format!(
+            "{identifier}: every matching entry's vendored state drift-kept; nothing was \
+             removed (re-run `scan --mode vendored` to normalize, then remove)"
+        );
+    }
+    format!(
+        "{identifier}: every matching entry's vendored state was kept; nothing was removed \
+         ({})",
+        kept_remedies(causes)
+    )
+}
+
+/// The human error line for kept entries (`retained` names the record kept
+/// beside the vendored state).
+fn kept_error_line(causes: &[KeepCause], retained: &str) -> String {
+    let n = causes.len();
+    let entries = if n == 1 { "y was" } else { "ies were" };
+    if causes.iter().all(|c| *c == KeepCause::Drift) {
+        return format!(
+            "{n} matching entr{entries} drift-kept (vendored state and {retained} \
+             retained); re-run `scan --mode vendored` to normalize, then remove again"
+        );
+    }
+    format!(
+        "{n} matching entr{entries} kept (vendored state and {retained} retained); {}",
+        kept_remedies(causes)
+    )
+}
+
+/// One remedy per distinct keep cause.
+fn kept_remedies(causes: &[KeepCause]) -> String {
+    let mut out: Vec<String> = Vec::new();
+    for cause in [KeepCause::Reference, KeepCause::Drift] {
+        if causes.contains(&cause) {
+            let remedy = cause.remedy("remove again");
+            out.push(match cause {
+                KeepCause::Reference => remedy,
+                KeepCause::Drift => format!("for a drift-kept entry, {remedy}"),
+            });
+        }
+    }
+    out.join("; ")
+}
+
 /// The vendored leg's envelope material, collected by
 /// [`revert_vendored_matches`].
 #[derive(Default)]
@@ -1150,9 +1189,11 @@ struct RemoveVendorLeg {
     /// Backend warnings, drift-keeps and preserved entries — `Skipped`
     /// events.
     skipped: Vec<PatchEvent>,
-    /// Ledger keys whose revert drift-kept: entry, artifact and any
+    /// Ledger keys whose revert kept the artifact: entry, artifact and any
     /// manifest record stay.
     kept: Vec<String>,
+    /// Why each [`Self::kept`] entry was kept (same order).
+    kept_causes: Vec<KeepCause>,
     /// Entries actually reverted and dropped from the ledger (wet runs).
     reverted_count: usize,
     /// Entries unwired with their artifact and ledger entry kept
@@ -1223,29 +1264,29 @@ async fn revert_vendored_matches(
                 );
                 return Err(1);
             }
-            VendorRevertStep::Kept => {
-                // Drift-keep: the lock changed under us and the backend
-                // left both the wiring and the artifact alone. Per the
-                // RevertOutcome contract the ledger entry stays — and so
-                // must any manifest entry, or `vendor`'s reconcile would
-                // re-revert an entry whose backing record is gone.
+            VendorRevertStep::Kept(cause) => {
+                // The backend kept the artifact (a drift-keep, or a file
+                // that still installs from it). Per the RevertOutcome
+                // contract the ledger entry stays — and so must any
+                // manifest entry, or `vendor`'s reconcile would re-revert
+                // an entry whose backing record is gone.
+                let reason = cause.reason();
                 let (note, detail) = if manifest_backed {
                     (
                         "; its manifest entry was kept too",
-                        "lockfile wiring drifted; vendored state and manifest entry kept",
+                        format!("{reason}; vendored state and manifest entry kept"),
                     )
                 } else {
                     (
                         "",
-                        "lockfile wiring drifted; vendored state and ledger entry kept",
+                        format!("{reason}; vendored state and ledger entry kept"),
                     )
                 };
                 if loud {
-                    eprintln!(
-                        "Warning: Kept vendored state for {key}: lockfile wiring drifted{note}"
-                    );
+                    eprintln!("Warning: Kept vendored state for {key}: {reason}{note}");
                 }
                 leg.kept.push(key.clone());
+                leg.kept_causes.push(cause);
                 leg.skipped.push(
                     PatchEvent::new(PatchAction::Skipped, key.clone())
                         .with_reason("vendor_revert_kept", detail),
@@ -1571,11 +1612,7 @@ async fn remove_ledger_only(
         // top-level error names the outcome — nothing was removed.
         env.mark_partial_failure();
         if leg.kept.len() == keys.len() {
-            let msg = format!(
-                "{}: every matching entry's vendored state drift-kept; nothing was \
-                 removed (re-run `scan --mode vendored` to normalize, then remove)",
-                args.identifier
-            );
+            let msg = all_kept_message(&args.identifier, &leg.kept_causes);
             track_patch_remove_failed(&msg, telemetry).await;
             env.error = Some(EnvelopeError::new("vendor_revert_kept", msg));
         }
@@ -1593,14 +1630,8 @@ async fn remove_ledger_only(
         // are gated, so name the outcome once here.
         if !args.common.json {
             eprintln!(
-                "Error: {} matching entr{} drift-kept (vendored state and ledger record \
-                 retained); re-run `scan --mode vendored` to normalize, then remove again",
-                leg.kept.len(),
-                if leg.kept.len() == 1 {
-                    "y was"
-                } else {
-                    "ies were"
-                }
+                "Error: {}",
+                kept_error_line(&leg.kept_causes, "ledger record")
             );
         }
         1

crates/socket-patch-cli/src/commands/rollback.rs

@@ -27,7 +27,9 @@ use std::time::Duration;
 use crate::args::{apply_env_toggles, is_local_go, parse_bool_flag, GlobalArgs};
 use crate::commands::hosted_unwind::run_hosted_leg;
 use crate::commands::lock_cli::acquire_or_emit;
-use crate::commands::vendored_backend::{RevertedEntry, VendorRevertStep, VendoredBackend};
+use crate::commands::vendored_backend::{
+    KeepCause, RevertedEntry, VendorRevertStep, VendoredBackend,
+};
 use crate::ecosystem_dispatch::{
     distinct_npm_copies, find_all_packages_for_rollback, partition_purls, JvmScope,
 };
@@ -794,10 +796,18 @@ async fn run_vendored_leg(
                 }
                 out.failed.push((key, why));
             }
-            VendorRevertStep::Kept => out.kept.push((
+            VendorRevertStep::Kept(KeepCause::Drift) => out.kept.push((
                 key,
                 "lockfile wiring drifted; vendored state left untouched".to_string(),
             )),
+            VendorRevertStep::Kept(cause @ KeepCause::Reference) => out.kept.push((
+                key,
+                format!(
+                    "{}; vendored state kept — {}",
+                    cause.reason(),
+                    cause.remedy("roll back again")
+                ),
+            )),
             VendorRevertStep::WouldRevert if preserve => {
                 if loud {
                     println!("Would unwire vendoring for {key} (artifact preserved)");

crates/socket-patch-cli/src/commands/scan/hosted/takeover.rs

@@ -253,6 +253,11 @@ impl Takeover {
                         outcome.error.as_deref().unwrap_or("unknown error")
                     ),
                 }))
+            } else if let Some(residual) = residual_only_keep(&outcome) {
+                // Nothing drifted: another project file (an exported
+                // requirements file) still installs from the vendored
+                // wheel (#1184). Name it, not a drift.
+                Some(residual_takeover_warning(&purl, &residual))
             } else if revert_keeps_wiring(&outcome) {
                 // A wiring record drifted and was left in place, so the
                 // project may still resolve through the vendored artifact
@@ -552,6 +557,45 @@ fn revert_keeps_wiring(outcome: &RevertOutcome) -> bool {
             .any(|w| w.code == "vendor_revert_residual_reference")
 }
 
+/// The `vendor_revert_residual_reference` detail of a revert whose ONLY
+/// keep signal is a file that still references the artifact.
+fn residual_only_keep(outcome: &RevertOutcome) -> Option<String> {
+    if outcome.drift_skipped() {
+        return None;
+    }
+    outcome
+        .warnings
+        .iter()
+        .find(|w| w.code == socket_patch_core::vendor::RESIDUAL_REFERENCE_CODE)
+        .map(|w| {
+            // `kept <dir>: <file> still resolves through it, and deleting …`:
+            // only the clause naming the file; the revert's own remedy is
+            // not this command's.
+            let detail = w.detail.as_str();
+            detail
+                .split_once(": ")
+                .map_or(detail, |(_, rest)| rest)
+                .split(", and deleting")
+                .next()
+                .unwrap_or(detail)
+                .to_string()
+        })
+}
+
+/// The refusal for a takeover whose vendored wheel another project file
+/// still installs from.
+fn residual_takeover_warning(purl: &str, residual: &str) -> serde_json::Value {
+    serde_json::json!({
+        "code": "redirect_vendored_revert_failed",
+        "detail": format!(
+            "{purl} is vendored and another project file still installs from its \
+             vendored wheel ({residual}), so it is left in place; NOT switched to hosted — \
+             point that file back at the registry release (re-export it once the hosted \
+             scan has rewired the lock), then re-run `scan --mode hosted`"
+        ),
+    })
+}
+
 /// The refusal for a takeover whose vendored wiring drifted since vendoring.
 fn drifted_takeover_warning(purl: &str) -> serde_json::Value {
     serde_json::json!({

crates/socket-patch-cli/src/commands/vendor.rs

@@ -51,7 +51,7 @@ use crate::commands::apply::{representative_file, result_to_event, variant_match
 use crate::commands::bun_preflight::bun_vendor_preflight_pairs;
 use crate::commands::lock_cli::acquire_or_emit;
 use crate::commands::vendored_backend::{
-    ApplyRequest, RevertedEntry, VendorRevertStep, VendoredBackend,
+    ApplyRequest, KeepCause, RevertedEntry, VendorRevertStep, VendoredBackend,
 };
 use crate::commands::vex::{
     generate_vex_from_manifest_path, generate_vex_without_manifest, ManifestlessVex, VexEmbedArgs,
@@ -4105,13 +4105,24 @@ pub(crate) async fn reconcile_dropped(
             // Drift-skip keep: the backend left the drifted lock alone and
             // kept the artifacts, so the ledger entry must survive too — and
             // the genuine outcome is a COUNTED skip, not a removal.
-            VendorRevertStep::Kept => env.record(
+            VendorRevertStep::Kept(KeepCause::Drift) => env.record(
                 PatchEvent::new(PatchAction::Skipped, purl.clone()).with_reason(
                     "vendor_revert_kept",
                     "patch no longer in manifest, but its lock entries drifted since \
                      vendoring; artifacts and ledger entry kept",
                 ),
             ),
+            VendorRevertStep::Kept(cause @ KeepCause::Reference) => env.record(
+                PatchEvent::new(PatchAction::Skipped, purl.clone()).with_reason(
+                    "vendor_revert_kept",
+                    format!(
+                        "patch no longer in manifest, but {}; artifacts and ledger entry \
+                         kept — {}",
+                        cause.reason(),
+                        cause.remedy("re-run `vendor`")
+                    ),
+                ),
+            ),
             VendorRevertStep::WouldRevert | VendorRevertStep::Reverted => {
                 if !common.json && !common.silent {
                     println!("{}", format_reconciled(&purl, common.dry_run));
@@ -4208,13 +4219,23 @@ async fn run_revert(args: &VendorArgs, env: &mut Envelope) -> i32 {
             // the genuine outcome is a COUNTED skip, not a removal.
             // (`record_warning` above already surfaced the per-record
             // details as uncounted advisory events.)
-            VendorRevertStep::Kept => env.record(
+            VendorRevertStep::Kept(KeepCause::Drift) => env.record(
                 PatchEvent::new(PatchAction::Skipped, purl.clone()).with_reason(
                     "vendor_revert_kept",
                     "lock entries drifted since vendoring; artifacts and ledger entry kept \
                      — undo the drift and re-run `vendor --revert` to finish",
                 ),
             ),
+            VendorRevertStep::Kept(cause @ KeepCause::Reference) => env.record(
+                PatchEvent::new(PatchAction::Skipped, purl.clone()).with_reason(
+                    "vendor_revert_kept",
+                    format!(
+                        "{}; artifacts and ledger entry kept — {}",
+                        cause.reason(),
+                        cause.remedy("re-run `vendor --revert` to finish")
+                    ),
+                ),
+            ),
             VendorRevertStep::WouldRevert | VendorRevertStep::Reverted => {
                 env.record(PatchEvent::new(PatchAction::Removed, purl.clone()));
                 reverted_flavors.extend(flavor);