fix(server): stop a second instance hijacking the Tailscale Serve mapping#10364

Fixes #10363.

What Changed

The Tailscale Serve mapping is now claimed only when it is free, already ours, or stale — never when it still reaches a live server.

• apps/server/src/tailscaleServe.ts (new). acquireTailscaleServe reads the current mapping before writing:

  • already points at this server's loopback port → adopt it, log, don't rewrite;
  • points somewhere else and that target still answers /.well-known/t3/environment → log a warning naming the environment it found and return null, i.e. not owned;
  • points somewhere else and that target is unreachable → log the reclaim and write the mapping;
  • no mapping, or the read fails → treat as unclaimed and write.

  releaseTailscaleServe re-reads the mapping and calls disableTailscaleServe only while it still points here.

• apps/server/src/server.ts. The acquireRelease layer now calls those two instead of ensureTailscaleServe / disableTailscaleServe directly. Net −42 lines; the acquire body is down to "wait for activation, read the bound port, delegate". HttpClient is already provided to this layer via FetchHttpClient.layer.

• apps/server/src/environmentProbe.ts (new). probeEnvironmentDescriptor lifted verbatim out of cli/pair.ts so the server path reuses the exact liveness check t3 pair already had (descriptor / unreachable / not-a-t3-server; 502/503/504 and transport errors count as unreachable). pair.ts imports it now and loses its private copy (−47 lines).

• packages/tailscale/src/tailscale.ts. Adds readTailscaleServeTarget / parseTailscaleServeTarget over tailscale serve status --json, reading only the Web["<host>:<port>"].Handlers["/"].Proxy leaf as unknown rather than modelling a shape that moves between tailscale releases. The status and serve status readers now share one captureTailscaleCommand runner so the scoped spawn, the timeout and the redacted error shape stay identical (including the existing catchDefect ENOTDIR handling). No existing export changed signature.

Why

The mapping is tailnet-wide state keyed only by HTTPS port, but the server wrote it unconditionally on startup and removed it unconditionally on shutdown, so every server started with tailscaleServeEnabled competes for the same slot. On macOS a second desktop instance is easy to get (no single-instance lock on darwin), it lands on the next free backend port, and it repoints the tailnet URL away from the healthy first one. If it then exits without its finalizer running, the mapping is left pointing at a dead port and the tailnet URL 502s with nothing in the codebase to reconcile it. Full timeline in #10363.

The approach follows the guard resolveTailscalePairingBase in cli/pair.ts already applies for the same question, rather than inventing a second policy — hence sharing the probe rather than copying it. Ownership itself is decided from tailscale serve status --json (target port + loopback host) rather than from the probed environment id, because that is also what makes the two safety properties exact:

• Never hijacks a live primary. Any non-unreachable probe result — same environment, another environment, or something that isn't T3 at all — leaves the mapping untouched and marks this server as not owning it.
• Never removes a mapping it doesn't own. Release is a no-op unless the mapping still points at this server's port, so a secondary that lost the race can't tear down the primary's mapping on its way out.

The stale-mapping case also self-heals now, which is the part that actually bites users: a server that starts while the mapping points at a port nothing answers on takes the slot back instead of leaving the tailnet URL broken.

UI Changes

None — server-side only.

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes (n/a)
• I included a video for animation/interaction changes (n/a)

Testing

New apps/server/src/tailscaleServe.test.ts (6 cases) drives the logic through a recording ChildProcessSpawner mock and an HttpClient mock: writes when the port is free; keeps a mapping that already fronts a live server on another port (the 3773-primary / 3774-secondary case — asserts no serve --bg was spawned and the probe hit http://127.0.0.1:3773/.well-known/t3/environment); reclaims a mapping whose target no longer answers; adopts a mapping that already points here; removes the mapping on shutdown while it still points here; leaves a mapping another server has taken over.

packages/tailscale/src/tailscale.test.ts gains two cases for the new reader (parses the Web entry for a given serve port, defaults the serve port to 443).

Ran, on main @ 223ff44:

Per AGENTS.md I did not run repo-wide checks. Not verified: no live end-to-end run against a real tailnet — the tailscale CLI is mocked at the spawner boundary in the tests, so the serve status --json shape is exercised against a captured fixture rather than a live daemon.

Deliberately out of scope, noted as a follow-up on the issue: a secondary instance also overwrites ~/.t3/userdata/server-runtime.json while the recorded pid is still alive, which is what breaks t3 pair's discovery afterwards.

Written by Claude Opus 4.6 in Claude Code.

https://claude.ai/code/session_01DXuSCeZKfJRHgukS6BZCZT