feat: global port conflict detection for concurrent headroom wrap sessions

[hareeshkar]

Description

When one headroom proxy is already running (e.g. headroom wrap claude on
port 8787), starting another agent (headroom wrap codex, headroom wrap aider) fails because port 8787 is occupied. This PR adds global port
conflict detection so any agent started second automatically uses the
next available port — no manual --port flags needed.

Integrated into all three proxy startup paths used by every agent.

Type of Change

• New feature (non-breaking change that adds functionality)

Changes Made

• _find_available_port(start_port, max_attempts=10) helper in wrap.py
• Integrated into _launch_tool, _run_proxy_only_watcher, and claude()
• All paths guarded by not no_proxy so --no-proxy bypasses detection
• 13 new tests: 9 unit + 4 integration

Testing

• Unit tests pass
• New tests added

Test Output

tests/test_cli/test_port_conflict.py   13 passed
CI precheck: 110 passed, 4 skipped
Total: 123 passing

Real Behavior Proof

• Environment: macOS arm64, Python 3.10, headroom v0.27.0
• Exact command / steps: headroom wrap claude in terminal 1 (port 8787), then headroom wrap codex in terminal 2
• Observed result: Codex prints "port 8787 in use — using 8788", starts on port 8788. Zero user intervention.
• Not tested: Windows, Linux. More than 10 concurrent agents.

Review Readiness

• I have performed a self-review
• This PR is ready for human review

Additional Notes

• Cherry-picked into PR feat(opencode): native OpenCode support — provider discovery, wrap/unwrap, MCP, install #1089 (opencode support)
• No breaking changes — existing single-agent workflows unaffected

[github-actions]

PR governance

This PR follows the template and is marked ready for human review.

[JerrettDavis]

The port-conflict change needs cleanup before merge. The PR adds local Serena project files (.serena/.gitignore, .serena/project.yml) and unrelated uv.lock churn for package version/litellm markers. Those are outside the feature behavior and should be removed from this PR so the review and merge only cover the port-selection change. After that, the remaining wrap.py/test changes can be reviewed on their own merits.

[JerrettDavis]

The port selection implementation is close, but this PR still has unrelated uv.lock churn in the current diff. The lockfile changes bump the local package version and alter LiteLLM dependency markers; that is not part of global port conflict detection and should not ride along with this feature.

Please remove the uv.lock changes from this PR so the diff is limited to headroom/cli/wrap.py and the focused port-conflict tests. Once the scope is clean, the wrap-path behavior and CI can be reviewed/merged without accidentally changing dependency metadata.