fix(widgets/mcp-install): make uvx + pipx + pip cooldown snippets resolvable for fresh releases

[tony]

Summary

• Add --exclude-newer-package libtmux-mcp=2099-01-01 to every uvx + days panel (CLI, JSON, TOML body shapes) so a security-conscious cooldown stays applied to transitive deps without filtering libtmux-mcp itself out of the resolver.
• Fall (pipx, *) and (pip, *) panels back to the bare install command and surface the limitation in a redirect note. Removes broken pipx run --pip-args=--uploaded-prior-to=<DATE> libtmux-mcp and pip install … --uploaded-prior-to … libtmux-mcp snippets that emit ERROR: Could not find a version that satisfies the requirement libtmux-mcp whenever the cutoff filters fresh releases.

Why

The previous snippets were copy-paste foot-guns: any time a libtmux-mcp release was newer than the cooldown window, the snippet's cutoff would filter the target package itself out of the resolver. Direct source verification:

• pip 26.1.1 (_internal/cli/cmdoptions.py:463): --uploaded-prior-to parses both P7D and absolute dates, but it's a single global cutoff — no per-package override flag exists. pip issue #13674 added the duration parser; no per-package issue is open.
• pipx 1.8.0 bundles pip 26.0.1 (which rejects P7D with "Invalid isoformat") and commands/run_uv.py::_UV_TRANSLATABLE_VALUE_FLAGS whitelists only --index-url, --pre, --no-deps, --no-cache-dir, --upgrade — neither --exclude-newer nor --uploaded-prior-to is forwarded to the uv backend.
• uv (crates/uv-distribution-types/src/exclude_newer.rs:209): supports P7D natively and has --exclude-newer-package <pkg>=<date> for per-package overrides. uv issues #18386 and #17999 cover related per-package work.

So uv is the only path where a per-package cooldown override exists today. The widget now reflects that.

What changed

docs/_ext/widgets/mcp_install.py

• _tool_command(): uvx + days emits uvx --exclude-newer <DURATION> --exclude-newer-package libtmux-mcp=2099-01-01 libtmux-mcp. pipx + days / off / bypass all emit bare pipx run libtmux-mcp. pip is unchanged at this layer (return "libtmux-mcp").
• _pip_prereq_for(): always returns pip install --user --upgrade libtmux libtmux-mcp regardless of cooldown mode (was emitting --uploaded-prior-to for days, which was broken).
• _json_body() and _toml_body(): uvx + days carries the same exempt flag; pipx + days / off / bypass all emit the same bare args / args_inner.
• _cooldown_note(): single redirect note for any (pipx | pip, days | bypass) cell — "pip has no per-package cooldown override, so this snippet runs without cooldown enforcement. Switch to the uvx tab — it applies the cooldown to transitive deps via `--exclude-newer` while exempting libtmux-mcp itself via `--exclude-newer-package`."
• Drop unused _DATE_SENTINEL and PIP_PREREQ_DAYS constants.

tests/docs/test_widgets.py

• test_body_for_uvx_days_inserts_duration_sentinel now also asserts the --exclude-newer-package libtmux-mcp=2099-01-01 exempt appears.
• New test_body_for_pipx_days_falls_back_to_bare_run asserts pipx + days emits the same bare command as off, with no --pip-args / --uploaded-prior-to / <COOLDOWN_DATE>, and the note redirects to uvx.
• New test_body_for_pip_days_falls_back_to_bare_install mirrors the pipx test for pip.
• test_body_for_pipx_bypass_returns_caveat_note and test_body_for_pip_bypass_returns_caveat_note updated to assert the new redirect-to-uvx prose.
• test_pip_panel_has_cooldown_aware_pip_prereq renamed to test_pip_panel_has_bare_pip_prereq_across_modes; asserts all three pip cooldown modes emit the same bare prereq.
• test_cooldown_days_slot_filter_registered_on_widget_render updated to drop the date-slot assertion — no widget emits <COOLDOWN_DATE> anymore.

CHANGES

• New ### Fixes entry under the unreleased block describing the mcp-install widget fix and citing the pip / pipx / uv source evidence.

Test plan

• uv run ruff check . --fix --show-fixes clean
• uv run ruff format . clean
• uv run mypy clean (51 source files, no issues)
• uv run py.test --reruns 0 — 483 passed
• just build-docs succeeds
• Live verified: pipx run libtmux-mcp starts the MCP server (exit 0) — confirms the new bare snippet works where the old --pip-args=--uploaded-prior-to=... form failed
• Live verified: the cli-install fix shape in agentgrep on tony/agentgrep#feat/cli-section using the same per-package exempt pattern resolves and runs

Companion change

The same fix shipped to agentgrep's mcp-install + cli-install widgets on tony/agentgrep's feat/cli-section branch. Both repos share the same git-pull workspace widget design; both needed the same fix.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.94%. Comparing base (3cb9aa4) to head (85ad5b8).

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #58      +/-   ##
==========================================
- Coverage   86.02%   85.94%   -0.09%     
==========================================
  Files          40       40              
  Lines        2454     2440      -14     
  Branches      325      319       -6     
==========================================
- Hits         2111     2097      -14     
  Misses        260      260              
  Partials       83       83              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.