[Mikola Lysenko (mikolalysenko)]

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

Fixes #1851

Summary

This covers a project whose requirements.txt pins a package only through a -r include outside the project root (-r ../shared/base.txt holding six==1.16.0), next to a pip lock pylock.toml or another tool lock. Before this PR, vendored mode wired only the lock and exited 0. vendor --check passed, and vex attested not_affected, while pip install -r requirements.txt installed the upstream release.

Now:

• vendor / scan --mode vendored / the hosted → vendored eject refuse the package with pypi_requirements_outside_root, which is the code the requirements-only path already uses for the same pin. They write nothing for it. This applies beside a pylock and beside a governing tool lock (uv, Poetry, PDM, Pipenv). Before, the tool-lock case didn't even name requirements.txt as a loser, because it only checked the root file.
• vendor --check and vex see a lock already wired beside such a pin (vendored before this fix, or a pin added later) as contested. vendor --check exits 1 and vex omits the package, the same as for an in-root pin (CLI_CONTRACT.md "Contested locks").

Root cause

Two code paths both skip a pin in an out-of-root include:

• Planner: detect_pypi_flavor (vendor/pypi.rs) gets sibling_pin_wirable == false for the read-only include, so it names requirements.txt a pypi_multiple_lockfiles loser ("retain their existing sources") and wires the lock.
• Discovery: extract_requirements (vex/discover/pypi_other.rs) reads only requirements_include_names_in, which drops out-of-root includes. Nothing contests the lock's wiring.

Change

• pypi_requirements::pin_outside_root finds an out-of-root include through which pip installs the release from a non-vendored source:

  • an == / === pin (extras and per-requirement options allowed)
  • a direct reference, or an editable checkout
  • a bare URL / VCS / path line whose filename or #egg= names the package

  It decodes the file the way pip does, so a UTF-16 pip freeze export counts too. The planner and discovery read these lines through the same helpers: utils::requirements::{editable_location, egg_name} and pypi_other::foreign_release. detect_pypi_flavor refuses through refuse_pin_outside_root in both lock branches. The refusal message is shared with plan_requirements (outside_root_refusal).

• pypi_requirements::requirements_outside_root_names_in lists the out-of-root includes the root reaches, through in-root files and through each other. Discovery reads them in the same install tree as the root file (so, as with Lockfile discovery treats a requirements.txt -r include as a competing lock, so after a hosted rewrite vex attests nothing (exit 2) and rollback refuses (exit 1), although pip install -r requirements.txt installs the patched wheel #1086, they never contest a wiring inside that tree). It reads them as evidence only: registry pins via registry_pin, editable checkouts, and non-Socket direct references and bare lines via foreign_reference. An include that can't be read or decoded is reported as lockfile_unreadable instead of being dropped silently. Nothing in them is read as wiring, because neither writer edits them. They share the MAX_REQUIREMENTS_FILES budget.

No wrapper changes: npm/, pypi/ and gem/ only dispatch to the binary. No new error code.

Tests (red → green)

Issue facet	Test	Without fix	With fix
#1851 planner: exact pin in ../base.txt beside pylock / uv.lock / Pipfile.lock / poetry.lock refuses; another release or an in-root-only package doesn't	core vendor::pypi::tests::exact_pin_in_an_out_of_root_include_refuses_beside_a_lock	FAIL (unwrap_err on Ok, pypi.rs:4179)	pass
#1851 discovery: out-of-root pin (direct and via a nested out-of-root include) contests a vendored pylock; another release / other package doesn't	core vex::discover::pypi_locks::tests::out_of_root_include_pin_contests_a_vendored_pylock (also extras/===, direct reference, editable, bare VCS and path lines, and an undecodable include diagnosed)	FAIL (refs still holds the pylock wiring)	pass
#1851 planner, every shape (review follow-up): extras, ===, --config-settings, direct reference, -e/--editable= egg, bare git+…#egg= / URL / path wheels, UTF-16 export; other-release and other-package bare wheels don't refuse	core vendor::pypi::tests::every_installing_shape_in_an_out_of_root_include_refuses	FAIL (first cut matched only == in UTF-8; before 713eec9, Ok(PythonLocks) for git+…#egg=six)	pass
#1851 CLI: vendor refuses and leaves every file byte-identical; with another release in the include, the pylock vendors and vendor --check passes; once the include pins the vendored release, vendor --check fails as contested	cli mode_migration_pypi::pip_lock_beside_an_out_of_root_include_pin_refuses	FAIL (vendor exit 0)	pass

Commands run locally:

• cargo fmt --all -- --check: clean
• cargo clippy --workspace --all-features -- -D warnings: clean
• cargo test -p socket-patch-core --all-features --lib: all pass except 4 known permission-denial tests that can't fail a write as root in this sandbox (copy_tree::relax_loop_must_not_traverse_symlinked_root, vlt_heal::an_unremovable_hidden_lock_keeps_every_store_entry, pypi_poetry::wire_write_failure_…, pypi_requirements::wire_failure_rolls_back_…). The other agent PRs see the same 4, and none of them touches this change.
• cargo test -p socket-patch-cli --all-features for mode_migration_pypi (75), e2e_vex (45), e2e_vex_vendor (53), e2e_vex_redirect (53), in_process_vendor_pypi_takeover, scan_requirements_lock_only, scan_vendor_requirements_unwired, hosted_superseding_pypi, vendor_ledger_schema_e2e and e2e_pypi: all pass.
• CI on 713eec9 is green (ci-ok), including the real-pip e2e_vex_build legs. Its first attempt lost 3 jobs to Depot runners (no logs, 10-minute cutoff, Depot runners lost mid-job evicted 2 merge-queue entries in 27h #1660), and one re-run of those jobs passed.

Per-issue checklist

• Vendored pip: a pin in a -r include outside the project root is ignored when a pylock.toml exists, so vendor --check passes and vex attests not_affected while pip install -r requirements.txt installs the unpatched release #1851 scan --mode vendored / vendor / eject no longer wire only the pylock and exit 0: exact_pin_in_an_out_of_root_include_refuses_beside_a_lock, every_installing_shape_in_an_out_of_root_include_refuses, pip_lock_beside_an_out_of_root_include_pin_refuses
• Vendored pip: a pin in a -r include outside the project root is ignored when a pylock.toml exists, so vendor --check passes and vex attests not_affected while pip install -r requirements.txt installs the unpatched release #1851 vendor --check doesn't pass a pylock wiring that an out-of-root pin contests: pip_lock_beside_an_out_of_root_include_pin_refuses
• Vendored pip: a pin in a -r include outside the project root is ignored when a pylock.toml exists, so vendor --check passes and vex attests not_affected while pip install -r requirements.txt installs the unpatched release #1851 vex doesn't attest not_affected (same discovery contest that omits in-root contested pins): out_of_root_include_pin_contests_a_vendored_pylock

/code-review high

Fixed in the review follow-up commit:

• Extras / === / per-requirement-option pins, direct references, editables and UTF-16 files in an out-of-root include were missed by the planner, and direct references were also missed by discovery.
• An unreadable out-of-root include was dropped silently. It's now diagnosed.
• The dead wired_with_lock parameter is removed.

Bugbot (fixed in 713eec9): bare URL / VCS / path lines in an out-of-root include didn't refuse in the planner, though discovery contested them. Both sides now read them through one helper, pypi_other::foreign_release. Bugbot's re-review of 713eec9 found no new issues.

Not changed:

• An in-root include beside poetry.lock / pdm.lock isn't named a loser. requirements_pins_target reads only the root file. That predates this PR and isn't Vendored pip: a pin in a -r include outside the project root is ignored when a pylock.toml exists, so vendor --check passes and vex attests not_affected while pip install -r requirements.txt installs the unpatched release #1851. Discovery already contests it, since in-root includes are in the tree, so vendor --check and vex stay honest. A single tree-wide "pins target" predicate is a reasonable follow-up.
• Extra tree walks. The planner walks the requirements tree again in detect_pypi_flavor, and discovery walks it once more to find out-of-root includes. These are small text files read once per routed package or discovery run, so I kept the separate, readable helpers rather than reshape sibling_pin_wirable's and requirements_include_names_in's return types.

Notes for review

• In-sync re-runs aren't special-cased, unlike Fix extras pin un-hosted beside a pylock (#1794) #1796. A project vendored before this fix, with such a pin, really is unpatched under pip install -r, so vendor refusing it on the next run is the honest answer. vendor --check also fails it now.
• This touches the same detect_pypi_flavor branch as Fix extras pin un-hosted beside a pylock (#1794) #1796 (extras pins). The two changes are independent: whichever lands second needs a trivial merge.

https://claude.ai/code/session_011f9aeR3uZQzo93CSAMyih2

---

Note

Medium Risk
Changes PyPI vendoring routing and VEX discovery around requirements includes; incorrect matching could block legitimate vendoring or miss contested installs, but behavior is fail-closed and heavily regression-tested.

Overview
Fixes #1851: when requirements.txt pulls an exact package pin from a -r include outside the project root (e.g. -r ../shared/base.txt) next to a pylock or other governing lock, vendored mode no longer wires only the lock and reports success while pip install -r still installs the upstream release.

Planner (vendor / vendored scan / eject): detect_pypi_flavor now calls refuse_pin_outside_root, which uses pin_outside_root to walk the requirements tree and refuse with pypi_requirements_outside_root (same code as the requirements-only path) when pip would install the target from that unreadable include—covering == / === pins, direct references, editables, bare URL/VCS/path lines, UTF-16 exports, and fail-closed behavior when an include exists but cannot be decoded.

Discovery (vex / vendor --check): requirements_outside_root_names_in plus outside_root_line treat those includes as evidence only (not wiring), so an already-wired lock beside a matching out-of-root pin is contested like an in-root pin. Shared parsing helpers (editable_location, egg_name, bare_line_release / foreign_release) keep planner refusal and discovery contest aligned.

Adds CLI and core tests for refusal, --check contest, and multiple requirement line shapes.

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

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

BugBot review

---

Generated by Claude Code

[cursor]

Stale Bugbot comment from a previous run.

[Mikola Lysenko (mikolalysenko)]

BugBot review

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

[agent] CI on eb7935d didn't produce test results: 14 jobs failed together at 21:23:31 UTC. They span cargo, node-addon, yarn, pnpm, vlt, gradle, maven, gem, composer and pip-vex, most of which this diff doesn't touch. All ran on Depot runners, and none has a log (HTTP 404) or check output. That is the lost-runner pattern from #1660, not a test failure. The push of 713eec9 (Bugbot fix) re-runs the full suite, so that serves as the re-run. I'll treat any failure there as real.

---

Generated by Claude Code

[cursor]

Stale Bugbot comment from a previous run.

[Mikola Lysenko (mikolalysenko)]

[agent] On 713eec9, three jobs failed the same way as on eb7935d: coverage (1), coverage (2) and e2e-build (ubuntu-latest). Each ran on Depot runners and ended exactly 10 minutes after it started (21:29:58 → 21:39:58). None has a log (HTTP 404) or check output, so no test body reported a failure. This matches the lost-runner pattern in #1660, not this diff. I'll re-run the failed jobs once when the run finishes (GitHub refuses a re-run while it's still running). If they fail again with a real log, I'll treat that as this PR's failure.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

Burn-down agent: labeled Ready for review at 713eec90deb121456ebadce913de8da40520c50c.

• CI: 31/31 run checks green (19 skipped). The earlier failures on eb7935d and 713eec9 were Depot runner loss; the re-run passed.
• Bugbot: reviewed 713eec9, no findings; no open threads.
• Reviewer note: pylock wiring now honors a -r include that points outside the project root (Vendored pip: a pin in a -r include outside the project root is ignored when a pylock.toml exists, so vendor --check passes and vex attests not_affected while pip install -r requirements.txt installs the unpatched release #1851); the shared logic is in utils/requirements.rs, and vendor/pypi*.rs and the VEX pypi discovery both use it.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

Final review brief

What it does: Fixes #1851. Before, when a pylock.toml or a tool lock (uv, Poetry, PDM or Pipenv) sat beside a requirements.txt whose -r include outside the project root pinned the target release, vendoring wired the lock, called requirements.txt a loser and exited 0, while pip would still install the registry pin. The planner now refuses with the existing pypi_requirements_outside_root code. VEX discovery also reads out-of-root includes, as evidence only, so an already-wired lock shows as contested: vendor --check exits 1 and vex leaves the package out.

Risk: medium. It fails closed: there is no new write path and no new error code. The risk is the user-visible change. Projects that wired a lock beside such a pin used to pass and are now refused or flagged as contested. That is the intended fix, but users will notice it.

Look here:

• pypi.rs:418 and pypi.rs:473: the refusal in the pylock and tool-lock branches
• pypi_requirements.rs:463-512:`` pin_outside_root and `installs_outside_vendor`
• pypi_requirements.rs:1324:``` requirements_outside_root_names_in
• vex/discover/pypi_other.rs:275-322:```` discovery reads the includes as evidence

Verified: I read the full diff against #1851.

• Path safety: ../ and absolute includes were already read before this PR. Reads go through the FIFO-safe read_regular_to_bytes, and nothing is written outside the root.
• Tests: they exercise the change and would fail without it. The planner test would get Ok, and the CLI test checks every file is byte-identical and that vendor --check fails as contested.
• Moving editable_location and egg_name into utils/requirements.rs is a clean extraction.
• CHANGELOG.md is untouched.
• CI is green on 713eec9 (31 passed, 19 skipped, ci-ok and clippy both green). Bugbot found no new issues on the head, and its one earlier thread is resolved.

Changes I made: none.

Open questions (non-blocking; edge cases, none a regression from main):

• If an out-of-root include can't be read or decoded, the planner skips it and wires the lock, while discovery reports lockfile_unreadable for the same file (pypi_requirements.rs:472).````` Should the planner fail closed here too?
• The planner refuses a name @ url or editable line at any version, while discovery contests only a matching artifact version. The stricter side is the planner, so this is not a safety gap.
• The planner's vendor-dir check uses contains(".socket/vendor/"), so Windows .socket\vendor\ paths refuse (fail closed). Discovery normalizes backslashes.
• The description says "exact pin", but direct references and editables also trigger the refusal. The doc comments say so; the description doesn't.

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

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

[agent] On the final review brief's open questions:

• Unreadable / undecodable out-of-root include: fixed in 70b2147. The planner now refuses with pypi_requirements_outside_root and names the file, matching discovery's lockfile_unreadable. Before, it skipped the file and wired the lock. Test: every_installing_shape_in_an_out_of_root_include_refuses (undecodable case). It fails without the change and passes with it.
• Windows .socket\vendor\ paths: the planner's vendor-dir check now normalizes backslashes, as discovery already did (70b2147).
• Planner stricter than discovery for name @ url / editable at any version: left as is. The planner is the side that fails closed, so the mismatch can only refuse, never attest.
• Description wording: the "Change" section lists every shape that refuses, including direct references and editables. "Exact pin" appears only in the first test row, which covers that test's case.

BugBot review

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

BugBot review

---

Generated by Claude Code

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

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

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

[Mikola Lysenko (mikolalysenko)]

Final review brief (updated for 70b2147)

What it does: Fixes #1851. When a pylock.toml or tool lock sits beside a requirements.txt whose -r include outside the project root pins the target release, vendor now refuses with pypi_requirements_outside_root instead of wiring the lock while pip still installs the registry pin. VEX discovery reads the same includes, so an already-wired lock shows as contested. Since the last brief, 70b2147 also refuses when such an include exists but can't be read or decoded, and normalizes Windows backslashes in the vendor-dir check.

Risk: medium. It fails closed, with no new write path and no new error code. The change is user-visible: projects that wired a lock beside such a pin, or beside an unreadable out-of-root include, are now refused.

Look here:

• pypi_requirements.rs:465-504:`` pin_outside_root, including the new unreadable-include refusal (any non-`NotFound` read or decode error on an out-of-root file)
• pypi_requirements.rs:527:``` backslash normalization in installs_outside_vendor
• pypi.rs:261: refuse_pin_outside_root now returns the refusal as built
• pypi.rs:4245-4261: the new undecodable-include test

Verified:

• I read the 713eec9..70b2147 diff (2 files, +50/-12). It answers two of the earlier open questions; the other two were answered on the thread and need no code.
• An unreadable include refuses only when it is outside the root and exists. A missing include and in-root read errors behave as before.
• Ran cargo test -p socket-patch-core --lib vendor::pypi locally: 514 passed. The 2 failures (wire_failure_rolls_back_already_written_files, wire_write_failure_maps_error_and_leaves_lock_untouched) are permission-based tests that also fail on main when run as root. They are not caused by this PR.
• CI is green on 70b2147 (ci-ok and clippy both green). Bugbot found no new issues on 70b2147. No unresolved threads. CHANGELOG.md is untouched.

Changes I made: none.

Open questions: none blocking. Note that an unreadable out-of-root include now refuses every PyPI package in that project, not just the one it might pin. That fails closed, but users will see it.

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

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

Burn-down agent: re-verified Ready for review on the new head 70b2147 (label was applied at 713eec9). CI 50/50 green; mergeable, no conflicts. Bugbot reviewed 70b2147: no findings; no open review threads. Slack re-announcement not sent this run (Slack posting unavailable).

---

Generated by Claude Code