The best way to control Claude Code, Codex and more from any computer or phone
fix(server): t3 pair --tailscale no longer replaces another app's Serve route (#35547)
Julius Marminge committed
Nov 12, 2026 at 11:18 UTC
77f40aff37b8478d39f8f342bdf7417d07459065
4 files changed
+121
-20
apps/server/src/cli/pair.test.ts
+87
-2
@@ -35,7 +35,11 @@ import {
35
type PersistedServerRuntimeState,
36
} from "../serverRuntimeState.ts";
37
import { resolveHostCliCommand } from "./invocation.ts";
38
-import { DevServerNotProxiableError, resolveTailscaleLocalTarget } from "./pair.ts";
38
+import {
39
+ DevServerNotProxiableError,
40
+ resolveTailscaleLocalTarget,
41
+ ServePortOccupiedError,
42
+} from "./pair.ts";
43
44
import packageJson from "../../package.json" with { type: "json" };
45
import { buildPairingAppLink } from "@t3tools/shared/remote";
@@ -136,7 +140,7 @@ describe("t3 pair", () => {
140
Effect.gen(function* () {
141
if (!ChildProcess.isStandardCommand(command))
142
return yield* Effect.die("Unexpected pipeline");
139
- if (command.args[0] === "serve") {
143
+ if (command.args[0] === "serve" && command.args[1] === "--bg") {
144
const target = String(command.args.at(-1));
145
const descriptor = yield* Effect.promise(async () =>
146
(await fetch(new URL("/.well-known/t3/environment", target))).json(),
@@ -194,6 +198,87 @@ describe("t3 pair", () => {
198
).pipe(Effect.provide(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer))),
199
);
200
201
+ // The MagicDNS probe fails whenever the host cannot reach its own *.ts.net name,
202
+ // so it cannot be what decides that the port is free.
203
+ it.effect(
204
+ "leaves another app's Serve route alone when the host cannot reach its MagicDNS URL",
205
+ () =>
206
+ withDescriptorServer((origin) =>
207
+ // Another live app on loopback; a dead port's route may be taken back.
208
+ withDescriptorServer((otherAppOrigin) =>
209
+ Effect.gen(function* () {
210
+ const fetch = yield* FetchHttpClient.Fetch;
211
+ const tailscaleCalls: Array<ReadonlyArray<string>> = [];
212
+ const spawner = ChildProcessSpawner.make((command) => {
213
+ const { args } = command as unknown as { readonly args: ReadonlyArray<string> };
214
+ tailscaleCalls.push(args);
215
+ const stdout =
216
+ args[0] === "status"
217
+ ? '{"BackendState":"Running","Self":{"DNSName":"host-a.tail.ts.net.","TailscaleIPs":["100.64.0.1"],"CapMap":{"https":null}}}'
218
+ : args[0] === "serve" && args[1] === "status"
219
+ ? JSON.stringify({
220
+ TCP: { "443": { HTTPS: true } },
221
+ Web: {
222
+ "host-a.tail.ts.net:443": {
223
+ Handlers: { "/": { Proxy: otherAppOrigin } },
224
+ },
225
+ },
226
+ })
227
+ : "";
228
+ return Effect.succeed(
229
+ ChildProcessSpawner.makeHandle({
230
+ pid: ChildProcessSpawner.ProcessId(1),
231
+ // A recorded takeover fails fast instead of waiting out the HTTPS retries.
232
+ exitCode: Effect.succeed(
233
+ ChildProcessSpawner.ExitCode(
234
+ args[0] === "serve" && args[1] !== "status" ? 1 : 0,
235
+ ),
236
+ ),
237
+ isRunning: Effect.succeed(false),
238
+ kill: () => Effect.void,
239
+ unref: Effect.succeed(Effect.void),
240
+ stdin: Sink.drain,
241
+ stdout: Stream.make(new TextEncoder().encode(stdout)),
242
+ stderr: Stream.empty,
243
+ all: Stream.empty,
244
+ getInputFd: () => Sink.drain,
245
+ getOutputFd: () => Stream.empty,
246
+ }),
247
+ );
248
+ });
249
+
250
+ const baseDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-pair-ts-held-"));
251
+ yield* persistServerRuntimeState({
252
+ path: NodePath.join(baseDir, "userdata", "server-runtime.json"),
253
+ state: yield* makePersistedServerRuntimeState({
254
+ config: { host: "127.0.0.1", devUrl: undefined },
255
+ port: Number(new URL(origin).port),
256
+ }),
257
+ });
258
+
259
+ const exit = yield* runCli(["pair", "--base-dir", baseDir, "--tailscale"]).pipe(
260
+ Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
261
+ Effect.provideService(HostProcess.Platform, "linux"),
262
+ Effect.provideService(FetchHttpClient.Fetch, async (input, init) => {
263
+ if (String(input).startsWith(origin)) return fetch(input, init);
264
+ throw new TypeError("getaddrinfo ENOTFOUND host-a.tail.ts.net");
265
+ }),
266
+ Effect.exit,
267
+ );
268
+
269
+ assert.deepEqual(
270
+ tailscaleCalls.filter((args) => args[0] === "serve" && args[1] !== "status"),
271
+ [],
272
+ );
273
+ assert.isTrue(Exit.isFailure(exit));
274
+ if (Exit.isFailure(exit)) {
275
+ assert.instanceOf(Cause.squash(exit.cause), ServePortOccupiedError);
276
+ }
277
+ }),
278
+ ),
279
+ ).pipe(Effect.provide(layerCliRuntime)),
280
+ );
281
+
282
it.effect("mints a token and prints a QR pairing URL for a live server", () =>
283
withDescriptorServer((origin) =>
284
Effect.gen(function* () {
apps/server/src/cli/pair.ts
+10
@@ -15,6 +15,7 @@ import {
15
buildTailscaleHttpsBaseUrl,
16
DEFAULT_TAILSCALE_SERVE_PORT,
17
ensureTailscaleServe,
18
+ readTailscaleServeRootHolder,
19
readTailscaleStatus,
20
} from "@t3tools/tailscale";
21
import * as Config from "effect/Config";
@@ -405,6 +406,15 @@ const resolveTailscalePairingBase = Effect.fn("pair.resolveTailscalePairingBase"
406
if (isDevServerNotProxiableError(localTarget)) {
407
return yield* localTarget;
408
}
409
+ // The probe above fails whenever this host cannot reach its own MagicDNS name, so the Serve
410
+ // config, not the probe, decides whether the port is free.
411
+ const holder = yield* readTailscaleServeRootHolder(input.servePort, {
412
+ host: (localTarget.localHost ?? "127.0.0.1").replace(/^\[|\]$/gu, ""),
413
+ port: localTarget.localPort,
414
+ }).pipe(Effect.mapError((cause) => new TailscaleUnavailableError({ cause })));
415
+ if (holder === "other") {
416
+ return yield* new ServePortOccupiedError({ servePort: input.servePort });
417
+ }
418
yield* ensureTailscaleServe({
419
localPort: localTarget.localPort,
420
servePort: input.servePort,
apps/server/src/server.ts
+3
-17
@@ -218,7 +218,7 @@ import * as RelayClient from "@t3tools/shared/relayClient";
218
import {
219
disableTailscaleServe,
220
ensureTailscaleServe,
221
- readTailscaleServeRootHolders,
221
+ readTailscaleServeRootHolder,
222
readTailscaleServeRoutesTo,
223
readTailscaleStatus,
224
} from "@t3tools/tailscale";
@@ -906,22 +906,8 @@ const layerMakeServer = Layer.unwrap(
906
);
907
}),
908
);
909
- // Who holds the Serve port's root: nobody, this server, only dead loopback ports (an unclean
910
- // exit leaves one), or another live server or app, whose route is left alone.
911
- const tailscaleServeRootHolder = Effect.fn("server.tailscaleServeRootHolder")(
912
- function* (target: { readonly host: string; readonly port: number }) {
913
- const net = yield* NetService.NetService;
914
- const holders = yield* readTailscaleServeRootHolders(config.tailscaleServePort, target);
915
- if (holders.length === 0) return "none" as const;
916
- if (holders.some((holder) => holder.ours)) return "ours" as const;
917
- const live = yield* Effect.forEach(holders, (holder) =>
918
- holder.ours || holder.loopback === undefined
919
- ? Effect.succeed(true)
920
- : net.hasListenerOnHost(holder.loopback.port, holder.loopback.host),
921
- );
922
- return live.includes(true) ? ("other" as const) : ("dead" as const);
923
- },
924
- );
909
+ const tailscaleServeRootHolder = (target: { readonly host: string; readonly port: number }) =>
910
+ readTailscaleServeRootHolder(config.tailscaleServePort, target);
911
const layerTailscaleServe = config.tailscaleServeEnabled
912
? Layer.effectDiscard(
913
Effect.acquireRelease(
packages/tailscale/src/tailscale.ts
+21
-1
@@ -1,5 +1,6 @@
1
import { ExecutionEnvironmentDescriptor } from "@t3tools/contracts";
2
import * as HostProcess from "@t3tools/shared/HostProcess";
3
+import * as NetService from "@t3tools/shared/Net";
4
import { isLocalLoopbackHost, normalizeHostname } from "@t3tools/shared/hostClassification";
5
import * as Duration from "effect/Duration";
6
import * as Effect from "effect/Effect";
@@ -723,7 +724,7 @@ export const parseTailscaleServeRootHolders = (
724
return [...tcp, ...web];
725
};
726
726
-export const readTailscaleServeRootHolders = (
727
+const readTailscaleServeRootHolders = (
728
servePort: number,
729
target: { readonly host: string; readonly port: number },
730
) =>
@@ -736,6 +737,25 @@ export const readTailscaleServeRootHolders = (
737
}),
738
);
739
740
+/**
741
+ * Who holds the root of `servePort`: nobody, the server at `target`, only dead loopback ports (an
742
+ * unclean exit leaves one), or another live server or app, whose route must be left alone.
743
+ */
744
+export const readTailscaleServeRootHolder = Effect.fn("tailscale.readTailscaleServeRootHolder")(
745
+ function* (servePort: number, target: { readonly host: string; readonly port: number }) {
746
+ const net = yield* NetService.NetService;
747
+ const holders = yield* readTailscaleServeRootHolders(servePort, target);
748
+ if (holders.length === 0) return "none" as const;
749
+ if (holders.some((holder) => holder.ours)) return "ours" as const;
750
+ const live = yield* Effect.forEach(holders, (holder) =>
751
+ holder.ours || holder.loopback === undefined
752
+ ? Effect.succeed(true)
753
+ : net.hasListenerOnHost(holder.loopback.port, holder.loopback.host),
754
+ );
755
+ return live.includes(true) ? ("other" as const) : ("dead" as const);
756
+ },
757
+);
758
+
759
export const probeTailscaleHttpsEndpoint = Effect.fn("tailscale.probeTailscaleHttpsEndpoint")(
760
function* (input: { readonly baseUrl: string; readonly timeout?: Duration.Input }) {
761
const client = yield* HttpClient.HttpClient;