[FEATURE] Concurrent sessions should not compete for well-known dev server ports

Preflight Checklist

• [x] I have searched existing issues and this has not been requested
• [x] This is a single feature request

---

Problem Statement

When multiple Codex CLI sessions run concurrently on the same machine, each agent independently reaches for the same well-known ports (3000, 8000, 8080) when spinning up a dev server. There is no coordination mechanism between sessions, so conflicts are inevitable. When they occur, agents compete to reclaim the port, killing each other's processes or entering restart loops.

This is increasingly relevant as Codex's own subagent workflows (#11523 touches the related memory pressure problem) make multi-session setups more common, not less. The problem isn't agent behavior in isolation, each agent is doing the reasonable thing. The problem is that there is no cross-session primitive to prevent two reasonable agents from making the same autonomous decision at the same time.

Related concurrent-session coordination issues in this repo: #11523 (memory budgeting), #16195 (worktree change conflicts).

Proposed Solution

A configurable port allocation range in config.toml that agents draw from when selecting a port autonomously:

[port_allocation]
range = "8700-8999"
mode = "autonomous"  # or "ask"

• autonomous - agent selects a free port from the range without prompting
• ask - agent requests confirmation before binding any port

This makes port selection deterministic and conflict-free without requiring user intervention on every server start.

Alternative / Current Workaround

I built portbroker, an agent-agnostic named port registry, as a stopgap. Agents request a named reservation before starting any service; the same name always returns the same port, collisions are impossible, and it works via a single AGENTS.md instruction. It solves the problem but requires a third-party tool to work around behavior the agent itself is causing.

I filed the same feature request in the Claude Code repo: anthropic/claude-code#34385. This is not a Claude Code-specific problem, it's a gap in how CLI coding agents generally handle autonomous server startup. I'm raising it here because Codex is also actively used in concurrent multi-session workflows and would benefit from a native solution.

Use Case

1. Session A starts a web app, agent picks port 3000.
2. Session B starts a different project, agent also tries port 3000.
3. Both agents detect the conflict and compete to reclaim the port.
4. User has to intervene, find a free port manually, and tell both agents what to use, and defeating the purpose of autonomous workflows.

With a configured allocation range, each agent draws a free port, binds it, and moves on.

Priority

Medium — meaningful friction in any multi-session or subagent workflow involving a dev server.