[FEATURE] A port-allocation coordination primitive for concurrent sessions (re-file of #34385)

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Re-filing #34385, which was auto-closed as inactive rather than declined — its closing message invites a new issue if still relevant. It is: #21496, #24990, #25464 and #15320 all describe versions of the same thing.

When several Claude Code sessions run at once (commonly one per git worktree), each agent independently reaches for a well-known port — 3000, 5173, 8080 — with no awareness of what the others hold. The failure mode isn't just the collision. An agent that hits EADDRINUSE frequently cannot distinguish a port conflict from a bug in the code, so it "fixes" the application instead: rewriting a working server binding, or killing another session's process to claim the port back.

That makes it worse than an ordinary conflict, because the damage lands in the repo rather than the terminal, and the user is left debugging a problem no human created.

Proposed Solution

A coordination primitive Claude Code consults before binding, rather than reactive conflict handling after the fact. Roughly what #34385 proposed:

{
  "portAllocation": {
    "range": "8700-8999",
    "mode": "autonomous"
  }
}

The important properties, in priority order:

1. Race-free under genuine concurrency. Check-then-bind is not enough; two sessions can pass the check in the same instant.
2. Stable across restarts. A given worktree or service should keep the same port, so URLs, bookmarks and .env files don't rot between runs.
3. Reservation, not just discovery. Knowing a port is free right now is different from holding it.

Alternative Solutions

PreToolUse hooks that rewrite well-known ports were suggested on #34385. Useful as a stopgap, but the original reporter's objection stands: check-before-bind plus random free-port selection is still racy under truly concurrent sessions, and session-hashed ranges aren't equivalent to stable reservations that survive a restart.

External brokers. At least two exist now, built independently by people who hit this — tweakyourpc/portbroker, and an alloc command in a tool of my own. Disclosure: I maintain the latter, and I'm not raising this to advertise it. The relevant point is that when several people independently build the same coordination layer outside the tool, it's a gap in the platform rather than a niche preference. Mine assigns a stable port per (git root, service) and records reservations, which covers 2 and 3 above — happy to share what did and didn't work if useful.

Priority

Medium

Feature Category

Other