feat: add Tailscale binary detection, IP binding modes, and health probe password fix

This PR includes three main improvements:

1. Tailscale Binary Detection with Fallback Strategies
   - Added findTailscaleBinary() with multi-strategy detection:
     * PATH lookup via 'which' command
     * Known macOS app path (/Applications/Tailscale.app/Contents/MacOS/Tailscale)
     * find /Applications for Tailscale.app
     * locate database lookup
   - Added getTailscaleBinary() with caching
   - Updated all Tailscale operations to use detected binary
   - Added TUI warning when Tailscale binary not found for serve/funnel modes

2. Custom Gateway IP Binding with Fallback
   - New bind mode "custom" allowing user-specified IP with fallback to 0.0.0.0
   - Removed "tailnet" mode (folded into "auto")
   - All modes now support graceful fallback: custom (if fail → 0.0.0.0), loopback (127.0.0.1 → 0.0.0.0), auto (tailnet → 0.0.0.0), lan (0.0.0.0)
   - Added customBindHost config option for custom bind mode
   - Added canBindTo() helper to test IP availability before binding
   - Updated configure and onboarding wizards with new bind mode options

3. Health Probe Password Auth Fix
   - Gateway probe now tries both new and old passwords
   - Fixes issue where password change fails health check if gateway hasn't restarted yet
   - Uses nextConfig password first, falls back to baseConfig password if needed

Files changed:
- src/infra/tailscale.ts: Binary detection + caching
- src/gateway/net.ts: IP binding with fallback logic
- src/config/types.ts: BridgeBindMode type + customBindHost field
- src/commands/configure.ts: Health probe dual-password try + Tailscale detection warning + bind mode UI
- src/wizard/onboarding.ts: Tailscale detection warning + bind mode UI
- src/gateway/server.ts: Use new resolveGatewayBindHost
- src/gateway/call.ts: Updated preferTailnet logic (removed "tailnet" mode)
- src/commands/onboard-types.ts: Updated GatewayBind type
- src/commands/onboard-helpers.ts: resolveControlUiLinks updated
- src/cli/*.ts: Updated bind mode casts
- src/gateway/call.test.ts: Removed "tailnet" mode test

src/gateway/call.test.ts

@@ -74,8 +74,8 @@ describe("callGateway url resolution", () => {
     closeReason = "";
   });
 
-  it("uses tailnet IP when local bind is tailnet", async () => {
-    loadConfig.mockReturnValue({ gateway: { mode: "local", bind: "tailnet" } });
+  it("uses tailnet IP when local bind is auto and tailnet is present", async () => {
+    loadConfig.mockReturnValue({ gateway: { mode: "local", bind: "auto" } });
     resolveGatewayPort.mockReturnValue(18800);
     pickPrimaryTailnetIPv4.mockReturnValue("100.64.0.1");
 
@@ -84,16 +84,6 @@ describe("callGateway url resolution", () => {
     expect(lastClientOptions?.url).toBe("ws://100.64.0.1:18800");
   });
 
-  it("uses tailnet IP when local bind is auto and tailnet is present", async () => {
-    loadConfig.mockReturnValue({ gateway: { mode: "local", bind: "auto" } });
-    resolveGatewayPort.mockReturnValue(18800);
-    pickPrimaryTailnetIPv4.mockReturnValue("100.64.0.2");
-
-    await callGateway({ method: "health" });
-
-    expect(lastClientOptions?.url).toBe("ws://100.64.0.2:18800");
-  });
-
   it("falls back to loopback when local bind is auto without tailnet IP", async () => {
     loadConfig.mockReturnValue({ gateway: { mode: "local", bind: "auto" } });
     resolveGatewayPort.mockReturnValue(18800);

src/gateway/call.ts

@@ -59,8 +59,7 @@ export function buildGatewayConnectionDetails(
   const localPort = resolveGatewayPort(config);
   const tailnetIPv4 = pickPrimaryTailnetIPv4();
   const bindMode = config.gateway?.bind ?? "loopback";
-  const preferTailnet =
-    bindMode === "tailnet" || (bindMode === "auto" && !!tailnetIPv4);
+  const preferTailnet = bindMode === "auto" && !!tailnetIPv4;
   const localUrl =
     preferTailnet && tailnetIPv4
       ? `ws://${tailnetIPv4}:${localPort}`

src/gateway/net.ts

@@ -1,3 +1,5 @@
+import net from "node:net";
+
 import { pickPrimaryTailnetIPv4 } from "../infra/tailnet.js";
 
 export function isLoopbackAddress(ip: string | undefined): boolean {
@@ -9,15 +11,86 @@ export function isLoopbackAddress(ip: string | undefined): boolean {
   return false;
 }
 
-export function resolveGatewayBindHost(
+/**
+ * Resolves gateway bind host with fallback strategy.
+ *
+ * Modes:
+ * - loopback: 127.0.0.1 (rarely fails, but handled gracefully)
+ * - lan: always 0.0.0.0 (no fallback)
+ * - auto: Tailnet IPv4 if available, else 0.0.0.0
+ * - custom: User-specified IP, fallback to 0.0.0.0 if unavailable
+ *
+ * @returns The bind address to use (never null)
+ */
+export async function resolveGatewayBindHost(
   bind: import("../config/config.js").BridgeBindMode | undefined,
-): string | null {
+  customHost?: string,
+): Promise<string> {
   const mode = bind ?? "loopback";
-  if (mode === "loopback") return "127.0.0.1";
-  if (mode === "lan") return "0.0.0.0";
-  if (mode === "tailnet") return pickPrimaryTailnetIPv4() ?? null;
-  if (mode === "auto") return pickPrimaryTailnetIPv4() ?? "0.0.0.0";
-  return "127.0.0.1";
+
+  if (mode === "loopback") {
+    // 127.0.0.1 rarely fails, but handle gracefully
+    if (await canBindTo("127.0.0.1")) return "127.0.0.1";
+    return "0.0.0.0"; // extreme fallback
+  }
+
+  if (mode === "lan") {
+    return "0.0.0.0";
+  }
+
+  if (mode === "custom") {
+    const host = customHost?.trim();
+    if (!host) return "0.0.0.0"; // invalid config → fall back to all
+
+    if (isValidIPv4(host) && (await canBindTo(host))) return host;
+    // Custom IP failed → fall back to LAN
+    return "0.0.0.0";
+  }
+
+  if (mode === "auto") {
+    const tailnetIP = pickPrimaryTailnetIPv4();
+    if (tailnetIP && (await canBindTo(tailnetIP))) return tailnetIP;
+    return "0.0.0.0";
+  }
+
+  return "0.0.0.0";
+}
+
+/**
+ * Test if we can bind to a specific host address.
+ * Creates a temporary server, attempts to bind, then closes it.
+ *
+ * @param host - The host address to test
+ * @returns True if we can successfully bind to this address
+ */
+async function canBindTo(host: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    const testServer = net.createServer();
+    testServer.once("error", () => {
+      resolve(false);
+    });
+    testServer.once("listening", () => {
+      testServer.close();
+      resolve(true);
+    });
+    // Use port 0 to let OS pick an available port for testing
+    testServer.listen(0, host);
+  });
+}
+
+/**
+ * Validate if a string is a valid IPv4 address.
+ *
+ * @param host - The string to validate
+ * @returns True if valid IPv4 format
+ */
+function isValidIPv4(host: string): boolean {
+  const parts = host.split(".");
+  if (parts.length !== 4) return false;
+  return parts.every((part) => {
+    const n = parseInt(part, 10);
+    return !Number.isNaN(n) && n >= 0 && n <= 255 && part === String(n);
+  });
 }
 
 export function isLoopbackHost(host: string): boolean {

src/gateway/server.ts

@@ -490,12 +490,9 @@ export async function startGatewayServer(
   }
   let pluginServices: PluginServicesHandle | null = null;
   const bindMode = opts.bind ?? cfgAtStart.gateway?.bind ?? "loopback";
-  const bindHost = opts.host ?? resolveGatewayBindHost(bindMode);
-  if (!bindHost) {
-    throw new Error(
-      "gateway bind is tailnet, but no tailnet interface was found; refusing to start gateway",
-    );
-  }
+  const customBindHost = cfgAtStart.gateway?.customBindHost;
+  const bindHost =
+    opts.host ?? (await resolveGatewayBindHost(bindMode, customBindHost));
   const controlUiEnabled =
     opts.controlUiEnabled ?? cfgAtStart.gateway?.controlUi?.enabled ?? true;
   const openAiChatCompletionsEnabled =
@@ -960,18 +957,20 @@ export async function startGatewayServer(
     }
 
     const bind =
-      cfgAtStart.bridge?.bind ?? (wideAreaDiscoveryEnabled ? "tailnet" : "lan");
+      cfgAtStart.bridge?.bind ?? (wideAreaDiscoveryEnabled ? "auto" : "lan");
     if (bind === "loopback") return "127.0.0.1";
     if (bind === "lan") return "0.0.0.0";
 
     const tailnetIPv4 = pickPrimaryTailnetIPv4();
     const tailnetIPv6 = pickPrimaryTailnetIPv6();
-    if (bind === "tailnet") {
-      return tailnetIPv4 ?? tailnetIPv6 ?? null;
-    }
     if (bind === "auto") {
       return tailnetIPv4 ?? tailnetIPv6 ?? "0.0.0.0";
     }
+    if (bind === "custom") {
+      // For bridge, customBindHost is not currently supported on GatewayConfig.
+      // This will fall back to "0.0.0.0" until we add customBindHost to BridgeConfig.
+      return "0.0.0.0";
+    }
     return "0.0.0.0";
   })();