Fix orphaned hosted uv override wiring (#1445)

[Mikola Lysenko (mikolalysenko)]

LLM Description written by Claude Code

Fixes #1445

Summary

After hosted mode pins a transitive uv package, removing or upgrading
its parent (uv remove isodate, uv lock --upgrade-package isodate) used
to lock the project out of socket-patch: rollback, remove and list
failed with hosted_wiring_contested every time, and the suggested re-scan
changed nothing. Now that leftover wiring counts as Socket's own leftover
pin, as yarn berry's leftover resolutions selectors already do (#1203).
list lists around it with a hosted_resolution_orphaned warning, and
rollback / remove retire it, leaving a lock uv lock --locked
accepts.

Root cause

Hosted uv wires a transitive package with an override-dependencies entry
under the rewrite's # socket-patch hosted comment, plus a
[tool.uv.sources] URL. uv.lock records the pair under
[manifest] overrides. When the parent stops depending on the package, uv
drops its [[package]] but never edits the override or the source. In
discovery the hosted URL was then recognized but had no lock entry to
attribute it to, so HostedInventory::of filed it under contested. The
orphan path (HostedInventory::stale) was fed only by yarn berry
discovery.

Changes

• utils::python_script::hosted_override_pins: one shared reading of
  "the marked <name>==<version> overrides the hosted run added for a
  package not declared directly". The uv restore's pushed_override now
  uses it, and so does discovery.
• vex::discover::pypi_locks: for a uv / script lock, each such override
  whose package the lock no longer holds, and whose single unconditional
  source is a hosted URL naming that release's artifact, is recorded as a
  StaleSelector with the lock as its file.
• HostedInventory::of: a stale uv pin's URL is excused in the lock and in
  its paired metadata.
• upstream::uv::retire_orphaned_overrides: removes the override, the
  source and the lock's [manifest] record (dropping emptied tables), with
  a hosted_resolution_orphaned warning. Nothing is fetched. It refuses
  with the reason when the source or a manifest record names another patch,
  or when the metadata can't be read.
• list: the warning names the metadata file and says
  override-dependencies pin, not resolutions entry.
• CLI_CONTRACT.md: documents the uv case.

These stay contested, with tests: a user's own (unmarked) override, and a
package the lock still holds (a half-reverted pair).

Tests: per-issue checklist

• Hosted uv: after uv remove <parent> or uv lock --upgrade-package <parent> drops a hosted-pinned transitive package, its leftover override makes rollback, remove and list fail forever with hosted_wiring_contested #1445
  • core (crates/socket-patch-core/tests/hosted_inventory.rs):
    uv_override_left_by_relock_is_stale_not_contested,
    uv_override_left_beside_a_live_hosted_pin_is_stale,
    restore_retires_a_leftover_uv_override (byte-exact pyproject and lock;
    the expected lock is what real uv writes, and it passes uv lock --locked). Guards: users_own_uv_override_left_by_relock_stays_contested,
    uv_override_still_in_the_lock_is_not_stale,
    leftover_uv_override_is_not_retired_against_another_patchs_record.
    Red on main: the first 3 failed; green with the fix.
  • CLI (in_process_rollback_hosted.rs):
    uv_override_left_by_relock_is_listed_around,
    rollback_retires_a_uv_override_left_by_relock (unscoped and by purl),
    remove_retires_a_uv_override_left_by_relock (by uuid and by purl).
    Red on main: 3/3 failed (run with main's src/); green: 41/41.
  • real uv (e2e_redirect_uv_build, transitive hosted lane, new
    orphan-unwind step): drop the parent, uv lock, then list exit 0
    with the warning, rollback exit 0, and a following uv lock keeps the
    lock byte for byte. uv 0.11.32 locally: red on main (list must list around the leftover pin), green with the fix. CI runs the lane on
    its uv legs.

Local gate on f6af097: cargo fmt --check and cargo clippy --workspace --all-features -D warnings clean. In cargo test --workspace --all-features,
13 tests failed; the same tests fail on main in this sandbox. 12 of them
check write or remove failures that root bypasses (the sandbox runs as uid 0).
The 13th, e2e_bun_lockb, can't reach patches-api.socket.dev. None of them
touch this diff. The real-uv orphan-unwind step passes on f6af097.

Review notes

I ran /code-review high on the diff and fixed: retiring when the source
or [manifest] record names another patch (now refused, with a test);
swallowed metadata errors (now in the refusal); three spellings of the
paired-metadata path (now one paired_metadata_path helper); the
duplicated unconditional-source lookup (now unconditional_source); and
building the package-name set for pylocks.

Not changed:

• Sharing the direct-dependency check with the hosted rewriter
  (rewrite_project_metadata). hosted_override_pins keeps the exact
  check the restore already used (declares_directly), so nothing that
  decides ownership changes here. Merging it with the rewriter's check is
  a separate refactor.
• Folding the retire pass into restore_lock to skip a second parse. The
  extra parse happens only when an unhandled pin remains for that lock, and
  a separate pass keeps restore_lock's refusal ordering as it was.
• A kind field on StaleSelector. The filename-based split now goes
  through paired_metadata_path in every consumer. A typed kind would
  change a public struct in core for one extra consumer.

🤖 Generated with Claude Code

https://claude.ai/code/session_019BeSCbNmwztgigM9uxRTHd

---

Note

Medium Risk
Changes hosted-mode discovery and rollback/remove behavior for uv lockfiles and pyproject metadata; incorrect classification could retire user overrides or leave contested state, but guards and tests cover unmarked overrides and in-lock packages.

Overview
Fixes #1445: leftover hosted uv wiring after a parent dependency is removed or upgraded no longer traps projects in hosted_wiring_contested.

When hosted mode pins a transitive package via a marked [tool.uv] override-dependencies entry and [tool.uv.sources] URL (with uv.lock [manifest] overrides), uv remove / uv lock --upgrade-package can drop the package from the lock while leaving those lines. The PR classifies that as Socket’s own orphan pin (same idea as yarn berry #1203 resolutions leftovers): discovery records it as a StaleSelector, inventory treats it as stale not contested, list warns with hosted_resolution_orphaned (uv-specific wording), and rollback / remove retire the override, source, and manifest record offline—refusing when metadata is unreadable or manifest/source point at another patch.

Shared helpers hosted_override_pins and paired_metadata_path centralize detection; CLI_CONTRACT.md documents the uv case. User unmarked overrides and packages still in the lock stay contested.

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

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

Ready for review (burn-down agent)

• Head: f6af0979cb96677e6a13a63eebbd0dc919239b00
• CI: 36/36 green (50 skipped), no main-wide failures.
• Bugbot: reviewed f6af097, no findings. No open review threads.
• Reviewers: look at how rollback / remove retire the orphaned uv override, source and [manifest] overrides record offline, and at the refusal when metadata is unreadable or points at another patch. Unmarked user overrides and packages still in uv.lock stay contested.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

Final review brief

What it does: After hosted mode pins a transitive uv package, removing or upgrading the parent (uv remove, uv lock --upgrade-package) leaves the marked override-dependencies entry and its [tool.uv.sources] URL behind, and every later list/rollback/remove failed with hosted_wiring_contested. This PR treats that leftover as Socket's own stale pin, as is already done for yarn berry's leftover resolutions (#1203). list now warns and works around it, and rollback/remove retire the override, the source and the lock's [manifest] record together.

Risk: low to medium. A retire happens only when all of these hold: the override carries the hosted marker, the package isn't declared directly, the package is gone from the lock, the source is a single unconditional hosted URL naming that exact release, and the source and manifest URLs carry the pin's uuid. A user's own overrides, and wiring that belongs to another patch, stay contested, and tests cover both. pushed_override is now built on the shared helper and is used by ordinary uv rollback too.

Look here:

• upstream/uv.rs:190-293:`` retire_orphaned_overrides
• upstream/uv.rs:121:``` orphan_wiring_names, the guard that stops it removing another patch's wiring
• pypi_locks.rs:464-522:```` the stale-vs-contested decision
• python_script.rs:298: hosted_override_pins, the shared ownership check
• upstream/mod.rs:258-276:````` the inventory excusal, which now also covers the paired metadata file

Verified:

• I read the full diff. CHANGELOG.md is untouched.
• Tests run locally: hosted_inventory 21/21 and in_process_rollback_hosted 41/41.
• Clippy lib/bins with -D warnings is clean. Local --all-targets clippy on a newer toolchain flags only lints in files this PR doesn't touch. CI clippy is green.
• No unwraps or panics on untrusted TOML, and CRLF is preserved.
• Names are canonicalized on both sides. Overrides with markers or extras, and sources with markers, arrays or groups, stay contested.
• CI is 36/36 green (50 path-skipped), and Bugbot is clean on f6af097.

Changes I made: none.

Open questions (non-blocking):

• uv.rs:200 skips a uuid that is already in result.handled.
  • Suppose the same leftover pin sits in two python locks, for example uv.lock and a tool.py.lock. The first lock is retired, but the second keeps its override until a second rollback, and the first run still reports Restored.
  • The second run clears it, so nothing is lost. Tracking (uuid, file) pairs would close the gap.
• retire_orphaned_overrides doesn't repeat restore_lock's lock version == 1 guard. This is defensive only.
• Tests don't cover a PEP 723 script lock, an inline-table tool.uv, or several orphans in one lock.

Auto-merge (squash) is armed, so approving sends this straight to the merge queue.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

Thanks for the brief. On the three open questions:

• Same leftover pin in two locks (uv.rs:200): confirmed. The filter checks handled across all locks, so the second lock's override survives until a second rollback, and the first run still reports the pin as restored. Nothing is lost, and the next list warns about the leftover again. Fixing it means tracking (uuid, lock) pairs; the ordinary restore path already uses the same global handled set, so that change belongs in a follow-up, not on this green, ready-to-merge head.
• No version == 1 guard: the retire step only removes lines whose hosted URL names this pin's uuid. An unknown lock version means uv rejects the lock before that matters. Leaving it as is.
• Script locks, inline-table tool.uv, several orphans in one lock: fair gaps. They can go with the (uuid, lock) follow-up.

No changes pushed; head stays f6af097.

---

Generated by Claude Code