[ViperJuice]

Closes #182. Narrows #180 further, and recommends it stay open — see #180 status.

The defect

detect_package_type skipped flags but not the values those flags carry, so the first non-flag token was often a flag's argument. Two different servers then resolved to one identity — and v2.4.0's gate compares exactly this name to decide whether a cached description still describes the configured package, so it read that as a positive confirmation and served the wrong package's tool descriptions.

All seven reproduced on main; all seven now resolve distinctly:

uvx   --python 3.12 a/b        ('pypi','3.12')      -> ('pypi','a') / ('pypi','b')
uvx   --with requests a/b      ('pypi','requests')  -> ('pypi','a') / ('pypi','b')
pip   --index-url URL a/b      ('pypi','https://x') -> ('pypi','a') / ('pypi','b')
cargo --features full a/b      ('cargo','full')     -> ('cargo','a') / ('cargo','b')
docker --env-file .env a/b     ('docker','.env')    -> ('docker','a') / ('docker','b')
docker --mount spec a/b        ('docker','type=…')  -> ('docker','a') / ('docker','b')
npm   exec --package=old/new   ('npm','bin')        -> ('npm','old') / ('npm','new')

Design: three-way classification, fail-closed default

Per ecosystem: known-value flags consume the next token, known-boolean flags skip, known-positive flags yield the package, and any unlisted bare flag → ("unknown", None).

This is not the denylist #183 rejected. Docker's table failed open because unlisted meant "take the next token as the image" — an omission silently produced a wrong identity. Inverting the default means an omission costs auto-update for one odd config (safe, loud, fixable) instead of a silent collision (unsafe, invisible).

Two designs the board rejected before this one

A first draft — "any bare flag before the candidate yields unknown" — would have broken the canonical configs, all correct today:

docker run -i --rm mcp/server:latest      docker run -it --rm img
uvx --quiet my-package --arg              docker run -e KEY=val --rm ghcr.io/org/mcp

docker run -it --rm is the shape this repo's own README uses (:1528). Essentially every real docker server would have become permanently unverifiable. A second draft added a whole-argv --from scan, which turns uvx mypkg --from other from mypkg into other — a fail-open misidentification introduced by the fix. All five forms are now pinned as regression tests.

Two live defects repaired along the way

The README's own pin form was mis-identified. README.md:1133 documents uvx --python 3.12 --from index-it-mcp==1.2.0 index-it-mcp, which resolved to ('pypi','3.12') — the Python version as the package name.

A pinned server could have been moved to latest. --from=pkg==1.2.0 reported no pin while the spaced form reported 1.2.0. Both now report 1.2.0.

And browser-use's version checks were silently failing. manifest.yaml:352 ships --from browser-use[cli]; PyPI returns None for that name and 0.13.8 for browser-use. PEP 508 base-name normalization repairs it. Confirmed live, not assumed.

The flag tables were verified mechanically, and ten entries were dropped

The claim "verified entry by entry against --help" was not true when first written — several entries were added from memory, the practice the plan forbids and the direction that fails open. All 296 entries were then checked against live help output:

• Ten entries absent from their tool's help were REMOVED, not kept — removal is fail-closed. Measured cost: zero for shipped configs (all 98 manifest servers still resolve, 0 unknown).
• Drafting from memory had got docker --pull wrong (it takes a value — the plan's own named hazard), plus uv's --quiet/--verbose and pip's --platform.
• Three exceptions are stated rather than silent (-it/-ti combined shorts; npm's bare --package).

Mutation proof: 20/20 killed, each by its own single node

The harness carries an import-provenance guard — without it every mutant would have falsely survived while the unmutated worktree served the imports. Three tests claimed more than they pinned and were fixed or relabelled:

• _takes_a_value_ambiguously's "=" not in arg clause was dead code — the rule had two homes and only one was live.
• Repeated --package had no test; returning the first of several different packages is the exact guess this change exists to stop. Now fails closed.
• One mutation never applied (anchor didn't match ruff-formatted source) and had been reported as unproven rather than passing.

Two tests are non-discriminating and now say so in their docstrings instead of implying a proof.

#180 status — recommend it stays OPEN

All three forms from its narrowing comment are closed, and its two original forms stay fixed. But by #180's own closing sentence — "until the identity gate actually holds for ordinary commands" — the npm branch still fails open on unlisted flags:

npm exec --loglevel silly a/b      -> both ('npm','silly')
npm exec --registry https://r a/b  -> both ('npm','https://r')

Converting npm needs an enumeration of its boolean globals so the pinned ordering (npm --silent exec pkg → pkg) keeps passing — a new design surface deserving its own board round. The middle ground, a fail-open npm value table, is precisely the shape this plan rejected, so it was not introduced into a fifth ecosystem.

Verification

2764 passed, 3 skipped (baseline 2737, +27); ruff and mypy clean; all seven collisions closed; all five non-negotiable forms unchanged; 98/98 manifest servers resolve.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XbREMUsxgJ8TDBLpJ56PWb

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

[ViperJuice]

Implementation board — 1 AGREE, 1 DISAGREE, 1 PARTIALLY AGREE; two real defects, both mine

Seat	Verdict
grok-4.6 (adversarial)	AGREE
gemini-3.7-flash (alternative-approach)	AGREE
gpt-5.6-sol (red-team)	DISAGREE
claude-fable-5 (correctness)	PARTIALLY AGREE

Both dissents were right. Fixed in 688d5a5 and 3b9e41f.

1. A collision this fix introduced (red-team)

_pep508_base_name listed @ among the name terminators, so a PEP 508 direct reference truncated to its bare name:

pkg @ git+https://x/y  ->  ('pypi', 'pkg')
pkg @ git+https://x/z  ->  ('pypi', 'pkg')     COLLIDES

Two different repositories, one identity — the exact defect class #182 exists to close, newly created by the fix for it. It also violated this PR's own acceptance criterion that distinct URLs keep distinct identities. The existing test covered only the bare URL form and missed the standard named one, which is why nothing caught it.

@ is no longer a terminator. Verified after: the repos resolve distinctly, and normalization is unaffected — browser-use[cli] → browser-use, index-it-mcp==1.2.0 → index-it-mcp, pkg>=1.0 → pkg. Pinned by TestDirectReferencesStayDistinct, whose second test exists specifically to catch a carve-out that disables the rest of the rule.

2. The 21st mutant — and my fix for it had a hollow spot (correctness)

Deleting the following.startswith("-") guard arm left all 364 tests green while uvx --from --offline a and ... b both resolved to ('pypi','--offline'). Verified end-to-end: _same_package('--offline','pypi','--offline','pypi') returns True, so the mutant's collision passes the identity gate.

Then, mutation-proving my own patch rather than trusting it: a third mutant (dropping the following is None arm) passed all four new tests. My end-of-argv case used ["--from"], which returns before reaching the guard. I probed five inputs for one that distinguishes the arm — none does. It is genuinely unreachable: a trailing positive flag ends the loop and falls through to unknown anyway. The test now says that rather than implying a proof it can't give.

Kills verified per node, on a copy, provenance-checked:

drop startswith arm  -> 2 tests fail
drop `or None`       -> 1 test fails
drop is-None arm     -> 0 fail (unreachable; documented as such)

3. Two findings were false — and how they failed is the interesting part

• "Missing body in test_readme_documented_pin_form_resolves_to_the_package" — it has a full assertion body; the docstring was read as the whole test.
• "Unreachable fallthrough in _scan_for_package_token" — the -- branch is already labelled in-code as measured-redundant-but-kept, with the reasoning inline.

Both landed exactly where the implementer had already written "this does not pin what it looks like it pins." The disclosure didn't prevent the flag, but it made each checkable in seconds instead of requiring a fresh investigation — a concrete argument for writing non-discrimination into the code rather than into a report.

Verification at 3b9e41f

2770 passed, 3 skipped, 0 failed
ruff + mypy clean
7 collisions closed: True
direct refs distinct: True
browser-use -> browser-use
docker run -it --rm img -> img