Fix Poetry venv selection ignoring envs.toml (#476, #526)

[Mikola Lysenko (mikolalysenko)]

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

Fixes #476
Fixes #526

Summary

Agent mode, hosted mode's stale-install check, and VEX now use the Poetry virtualenv that Poetry itself uses. Before this change, two common Poetry setups led socket-patch to patch (or inspect) the wrong environment. The env behind poetry run stayed unpatched while the run reported success, and vex attested not_affected.

Root cause

Poetry venv discovery in crates/socket-patch-core/src/crawlers/python_crawler.rs approximated Poetry's EnvManager.get() instead of following it:

• With several Poetry envs for one project (poetry env use on two Python minors), agent mode patches the alphabetically first env instead of the one Poetry activated, and VEX attests not_affected #526: it never read <virtualenvs.path>/envs.toml, where poetry env use records the activated env. With several <name>-<hash>-py* envs it returned all of them in lexicographic order, so the first one (often a dead older minor) got patched. It also let an unrelated activated VIRTUAL_ENV win, but Poetry ignores VIRTUAL_ENV once envs.toml names the project (second trigger in the issue thread).
• Poetry with virtualenvs.in-project = true but no ./.venv keeps using its out-of-tree env, which socket-patch never probes: agent patches the global interpreter and hosted VEX falsely attests #476: it read virtualenvs.in-project = true as "only ./.venv" and poetry_virtualenvs_root returned None for it. Poetry only uses ./.venv when the directory exists (in_project_venv_exists). Otherwise it keeps installing into the existing out-of-tree env.

Fix

Follow EnvManager.get() for Poetry projects:

• load_poetry_project reads envs.toml under virtualenvs.path ([<name>-<hash>] minor = "X.Y"). When the project has an entry, only <name>-<hash>-pyX.Y is probed.
• The VIRTUAL_ENV shortcut is gated the way Poetry gates it: it's skipped when envs.toml has an entry, CONDA_PREFIX is honoured like VIRTUAL_ENV, and conda's base env doesn't count as an activated venv. This mirrors the existing Pipenv gate (pipenv_uses_virtual_env).
• ./.venv is the env only when it exists and in-project isn't an explicit false. virtualenvs.path is resolved whatever in-project says, and create = false still opts out.
• load_poetry_project now takes the injected environment instead of reading the process env. This also removes a race between the new tests and the existing serial env-mutating test.
• docs/testing/poetry-compatibility.md "Mode notes" are updated to match.

Hosted mode's redirect_pypi_stale_install check and vex both go through find_local_venv_site_packages, so they pick up the fix with no further changes. There are no wrapper changes: npm/, pypi/ and gem/ only dispatch to the binary.

Per-issue checklist

Issue	Regression test	main	this PR
#526 activated env (3.12/3.9/3.11 among 3.9–3.12; 3.10 vs 3.9 lexicographic trap)	crawlers::python_crawler::tests::poetry_envs_toml_activated_env_is_the_only_one_probed	❌ all 4 envs returned	✅
#526 envs.toml beats VIRTUAL_ENV; conda prefix / base	crawlers::python_crawler::tests::poetry_envs_toml_entry_overrides_virtual_env	❌ VIRTUAL_ENV returned	✅
#476 in-project = true (poetry.toml and POETRY_VIRTUALENVS_IN_PROJECT) with no ./.venv	crawlers::python_crawler::tests::poetry_in_project_true_without_dot_venv_keeps_the_out_of_tree_env	❌ []	✅

Two existing assertions encoded the #476 behaviour (in-project = true ⇒ nothing probed, and a None virtualenvs root). They now assert Poetry's behaviour instead.

Test evidence (Linux)

• New tests on main's code: 3 failed (output above). With the fix: cargo test -p socket-patch-core --lib -- crawlers::python_crawler gives 57/57 passed.
• Real Poetry 2.1.1 (not committed; a throwaway probe of find_local_venv_site_packages):
  • With several Poetry envs for one project (poetry env use on two Python minors), agent mode patches the alphabetically first env instead of the one Poetry activated, and VEX attests not_affected #526 layout: poetry env use python3.11, install, then poetry env use python3.12, install. The probe returns only envmulti-…-py3.12, which is what poetry env info -p prints. It still returns that env with an unrelated VIRTUAL_ENV=/tmp/other, and so does Poetry.
  • Poetry with virtualenvs.in-project = true but no ./.venv keeps using its out-of-tree env, which socket-patch never probes: agent patches the global interpreter and hosted VEX falsely attests #476 layout: a default install, then poetry config --local virtualenvs.in-project true and install again, leaving no ./.venv. The probe returns ipapp-…-py3.11, matching poetry env info -p.
• cargo clippy --workspace --all-features -- -D warnings: clean.
• cargo test --workspace --all-features --no-fail-fast: all pass except 12 permission-based write-failure tests. They fail only because this sandbox runs as uid 0 (root ignores read-only bits), they fail the same way on main, and all 12 pass when re-run as uid 65534.
• rustfmt --check on the changed file: clean. main isn't cargo fmt-clean workspace-wide, so unrelated reflows were left out.

Follow-ups (not in scope)

• With several envs and no envs.toml entry, Poetry picks the env matching the interpreter it would use (python on PATH or its own, depending on virtualenvs.use-poetry-python). Resolving that would mean running an interpreter, so in that case every env is still returned, as before.
• vex collapsing to the first copy (collapse_to_first) is tracked for npm in Agent-mode npm vex hashes only the first installed copy of a package, so it attests not_affected while another nested copy of the same name@version is unpatched #516 / Fix agent vex checking only one installed copy (#516) #517.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Rh6wkfBxavb2aj1JWKbSxM

---

Note

Medium Risk
Changes which site-packages paths agent mode patches—a wrong choice previously left the real Poetry env unpatched; the new logic is more complex but targets documented Poetry behavior with regression tests.

Overview
Agent-mode Python crawling now picks the same virtualenv Poetry uses, instead of approximating it.

envs.toml (#526): The crawler reads <virtualenvs.path>/envs.toml for the env poetry env use recorded and probes only that <name>-<hash>-py<minor> tree. When that entry exists, an unrelated VIRTUAL_ENV is ignored; otherwise VIRTUAL_ENV or a non-base CONDA_PREFIX can still win, matching Poetry’s EnvManager.get().

In-project setting (#476): virtualenvs.in-project = true no longer blocks out-of-tree discovery when ./.venv is missing—only an existing ./.venv (and not an explicit in-project = false) counts as the in-project env. virtualenvs.path / envs.toml resolution is unchanged by in-project.

load_poetry_project takes an injected env lookup for tests; regression tests and docs/testing/poetry-compatibility.md agent-mode notes are updated. Anything that already uses find_local_venv_site_packages (hosted stale-install checks, VEX, etc.) inherits the fix.

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

---

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 0b4a2df. Configure here.}

[Mikola Lysenko (mikolalysenko)]

[agent] Ready for review at 0b4a2df.

• CI: 333/333 non-skipped check runs green, including the real-Poetry e2e_vex_build legs and the Pipenv workflow.
• Bugbot: no findings on the current head.
• Mergeable, 0 commits behind main.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

[burn-down agent] Labeled Ready for review at 0b4a2dffb2.

• CI: 340/340 check runs finished on the head, none failed (success, skipped, or neutral).
• Bugbot: reviewed 0b4a2dffb2, no new issues. No unresolved review threads.
• Mergeable against main. Still needs a human approval.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

Reviewed 0b4a2dffb2654381f11426e23469d84a21cd7772. Recommendation: ready to merge as-is from code review.

No actionable correctness/security regressions found. Checked envs.toml selection, activated virtualenv/conda precedence, in-project fallback, and the shared stale-install/VEX discovery path against Poetry's environment manager.

Validation: cargo test -p socket-patch-core --lib crawlers::python_crawler — 57 passed on macOS. Full workspace/platform matrix not rerun.