fix(preview): resolve dev-server ports against the environment

[patroza]

The bug

Opening a dev server from a remote client shows ERR_CONNECTION_REFUSED.

apps/web/src/browser/browserTargetResolver.ts rewrote localhost:PORT to the environment's hostname, kept the port and scheme, and navigated. That address only works if the port is independently published there — which it usually is not, because dev servers bind loopback. Vite binds localhost by default (apps/web/vite.config.ts), so nothing listens on the tailnet interface at that port.

The failure surfaced as a browser error page, indistinguishable from a broken app. Agents driving preview_navigate reported it as an app failure rather than an unreachable port.

This is upstream, not fork-local. browserTargetResolver.ts, scripts/lib/dev-share.ts, and packages/tailscale/src/tailscale.ts are byte-identical to upstream/main. Both halves came from merged upstream PRs — #4011 added the rewrite, #4556 added tailnet sharing — and the seam between them was never covered. No upstream issue reports it. Promote after merge.

The fix

Reachability is resolved by the environment, the only side that knows what is listening locally and what the tailnet routes. A new preview.resolvePort RPC answers with a URL it has verified, in order:

1. Same-machine client → plain localhost:PORT, nothing published.
2. An existing tailscale serve route for the port → reused, at whatever port and scheme it was published under.
3. Port already answering on the environment's own address (WSL, LAN, a tunnel) → that address, nothing published.
4. Otherwise → a tailnet-only HTTPS route (tailscale serve, never Funnel), probed until it answers, withdrawn when the dev server exits or the server shuts down.

When none apply it fails with PreviewPortUnreachableError carrying a reason and a next action, instead of a URL that cannot load.

Navigation, the discovered-port list, chat links, and agent preview_navigate/preview_open all route through it. The old synchronous rewrite is kept for labels only and documented as such.

Two loopback-family bugs found while verifying

Vite's default --host localhost binds ::1 only, so tailscale serve mappings pinned to 127.0.0.1 proxy to nothing and answer 502. vp run dev --share produced a URL that never worked — reproduced on this branch before the fix. Both the new resolver and scripts/lib/dev-share.ts now target localhost and let tailscale pick the family.

Verification

Focused tests (357 passing across the touched scope), local typecheck for every touched package, and vp check clean.

Verified against real tailscale on a live dev stack, not just mocks:

case	result
127.0.0.1-only backend port, remote client	published, verified, returned https://…:15665, withdrawn on shutdown
--share-published web port (::1-bound)	reused existing mapping, createdExposure: false, HTTP 200
port with nothing listening	not-listening + remedy, no mapping created
same-machine client	http://localhost:15665, tailscale never invoked
after all runs	zero leaked serve mappings

vp run dev --share re-verified end to end: 502 before the fix, 200 after, and the shared origin loads in a controlled browser.

Notes for review

• Publishing is automatic and treated as consented by opening the port; routes are tailnet-only and never Funnel. docs/user/remote-access.md documents the behavior, the requirements (tailscale set --operator), and how to opt out by binding a routable address or publishing ports by hand.
• The direct-reachability probe is skipped when a serve mapping occupies the same port number for a different local port — otherwise the probe would find that other app answering and hand back a URL to the wrong thing.
• .agents/skills/test-t3-app/SKILL.md now tells agents to hand the preview localhost:<port> and never hand-write the environment hostname with a dev port appended.

🤖 Generated with Claude Code