Let a project action reserve a port so its Preview URL works in every worktree #21212

Problem

A project action's Preview URL is a fixed string. That works for one checkout, but not when several worktrees of the same project run their dev servers at once: each server needs its own port, and the Preview URL can only name one. Agents in each thread have the same gap, since nothing tells them which port their worktree's server is on.

My current annoying workaround is a small landing page on a fixed port that every worktree registers its dev server with, plus a Preview URL pointing at that page. It works, but it's hideous.

Proposal

Add a "Reserve a port" option to actions. Like "Open preview automatically", it's available once the action has a Preview URL.

• When an action with the option runs, the server assigns it a port for that worktree. It starts at a port hashed from the worktree path and action ID, between 20000 and 29999, and steps past ports that are in use or already assigned. The assignment holds while the server runs, and because it starts from the hash, the same action in the same worktree usually gets the same port after a restart.
• The action runs in its own terminal with the port in T3CODE_PREVIEW_PORT, alongside the existing T3CODE_PROJECT_ROOT and T3CODE_WORKTREE_PATH. It needs its own terminal because a shell's environment is fixed when the shell starts. Running the action again reuses that terminal.
• The Preview URL can contain ${T3CODE_PREVIEW_PORT}, which T3 replaces before opening the preview. Nothing else in the URL is expanded.
• Agents can read each action's port for their thread's worktree through T3's MCP tools, so an agent knows where the preview is, or which port to use if it starts the server itself.

command:     vite --port $T3CODE_PREVIEW_PORT --strictPort
Preview URL: http://localhost:${T3CODE_PREVIEW_PORT}

Actions without the option behave exactly as they do today. The preview still opens only after the command reaches the terminal, and a launch that fails never opens it.

Related

#20055 proposes opening whatever server an action's terminal starts, which suits servers you can't configure. A reserved port covers what detection can't. The port is known before the server starts, so agents and config can use it. It usually stays the same between runs, so the preview keeps its cookies and logins. And an action that starts both a frontend and an API doesn't leave T3 guessing which one to open. The two fit together.

I'm building this now and plan to open a PR that links back here. If this isn't a direction you'd accept, or you'd want a different scope, I'd rather hear it before the PR than after.