CONTRIBUTING's `pip install -e "agent-mesh[dev]"` cannot resolve: agent_hypervisor>=5.0.0 is not on PyPI

Package

agent-mesh (agentmesh-platform), plus CONTRIBUTING.md

Description

CONTRIBUTING.md line 56 tells a new contributor to run:

pip install -e "agent-mesh[dev]"

That command cannot succeed outside CI. The dev extra pins agent_hypervisor>=5.0.0,<6.0, and PyPI tops out at the pre-consolidation 3.7.0:

ERROR: Could not find a version that satisfies the requirement
agent-hypervisor<6.0,>=5.0.0; extra == "dev" (from agentmesh-platform[dev])
(from versions: 2.0.0, ..., 3.6.0, 3.7.0)
ERROR: No matching distribution found for agent-hypervisor<6.0,>=5.0.0

CI already knows this and works around it. .github/workflows/ci.yml pre-installs the local stub before the dev extra runs, with a comment that explains the whole thing:

agent-mesh's dev extra pins agent_hypervisor>=5.0.0 (its ring tests exercise the hypervisor). PyPI tops out at the pre-consolidation 3.7.0 wheel, which ships real code that would collide with the hypervisor top-level package force-included by -core. Satisfy the pin from the local dep-only stub so pip never falls back to PyPI

pip install --no-cache-dir --no-deps -e agent-governance-python/agent-hypervisor

So the knowledge exists. It lives in a comment inside a workflow file, which is not where somebody following CONTRIBUTING.md will look, and the documented command fails before they get that far.

The reason this is worth an issue rather than a note is the second-order failure. A contributor who hits the resolver error and reaches for the obvious fix makes things worse rather than better:

• relaxing the pin, or installing agent-hypervisor==3.7.0 from PyPI, installs real code into the top-level hypervisor package that -core force-includes;
• per the CI comment that is a collision, so the environment does not fail loudly at install time, it fails later and confusingly at import or test time;
• nothing in the error message points at any of this.

An install error that teaches you the wrong fix costs more than one that just stops.

Only agent-mesh is affected. I checked every pyproject.toml under agent-governance-python/ and it is the only package declaring a monorepo sibling at a version PyPI cannot satisfy. The neighbouring agentrust-trace>=0.5.1,<0.6.0 pin resolves fine.

Possible resolutions

Roughly in order of effort, and any one of them closes it:

1. Document the ordering in CONTRIBUTING.md. One line before the agent-mesh[dev] instruction, saying the local agent-hypervisor stub has to be installed first and why. Cheapest, and it puts the CI comment where contributors read.
2. A bootstrap target (make dev-agent-mesh, or a scripts/ entry) that performs the two steps in order, so the documented path is a command rather than a procedure.
3. Move the sibling pin out of the published dev extra, since it is a monorepo-internal build requirement rather than something a wheel consumer can resolve. Largest change and I have not thought through what it breaks for the ring tests, so I mention it only for completeness.

Happy to send the PR for (1), which is the option I would pick if it is not already on somebody's list.

How does this impact your work?

I maintain an open-source recorder that ingests AGT FileAuditSink output, and I was setting up a local environment to generate the test vectors in #3732. Losing the time is not the point. The point is that the wrong fix is more discoverable than the right one, so this is a trap for exactly the drive-by contributor the repo presumably wants.

Steps to Reproduce

1. Clone the repository.
2. cd agent-governance-python/agent-mesh
3. python -m venv .venv && .venv/bin/pip install -e ".[dev]"
4. Resolution fails on agent_hypervisor>=5.0.0,<6.0.
5. Works if pip install --no-deps -e ../agent-hypervisor is run first, which is what CI does.

Reproduced on Python 3.14 / Windows, though nothing about it looks platform specific.

Start with the agent-mesh setup command around line 56 of CONTRIBUTING.md and compare it with the local stub installation and explanatory comment in .github/workflows/ci.yml. Confirm the contributor instructions avoid the unsatisfiable PyPI resolution and that a fresh environment can complete the documented setup without installing the conflicting PyPI package.