fix(gateway): ride out port release race on restart; add machine assignment to API key clients

- restart_gateway: wait for the released port to actually free before
  rebinding, mirroring autostart's port-wait race handling
- useGatewayControl.restart: skip the pre-probe (we still hold the port
  at probe time) and go straight to restartGateway, falling back to the
  bind-failure dialog on genuine conflict
- RegisterApiKeyClientModal: optional machine assignment (existing or
  new) when registering an API key client
- migration 040: rename gateway.public_url setting key to
  gateway.public_base_url

Unrelated pre-existing WIP on this branch, committed separately before starting the workspace-binding-popup-loop-fix plan.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>

Author: crimsonsunset

apps/desktop/src-tauri/src/commands/gateway.rs

@@ -5,7 +5,9 @@
 use crate::commands::server_manager::ServerManagerState;
 use crate::services::ui_events::OAUTH_CONSENT_REQUEST_CHANNEL;
 use crate::AppState;
-use mcpmux_core::service::{allocate_dynamic_port, is_port_available};
+use mcpmux_core::service::{
+    allocate_dynamic_port, is_port_available, wait_for_port_available, AUTOSTART_PORT_WAIT,
+};
 use mcpmux_core::DomainEvent;
 use mcpmux_gateway::admin::ui_events::AdminUiEventBus;
 use mcpmux_gateway::{
@@ -1623,6 +1625,21 @@ pub async fn restart_gateway(
         shutdown_gateway_handle(h).await;
     }
 
+    // The shutdown above is graceful (or force-aborted after a 2s timeout),
+    // but the OS may hold the socket a moment longer than the in-process
+    // handle takes to resolve. Ride out that brief window the same way
+    // auto-start rides out the self-update restart race, so start_gateway's
+    // single is_port_available() check below doesn't spuriously report the
+    // port we just released as taken.
+    let (preferred_port, _source) = resolve_preferred_port(&app_state, port).await;
+    if !wait_for_port_available(preferred_port, AUTOSTART_PORT_WAIT).await {
+        warn!(
+            "[Gateway] Restart: port {} still unavailable after waiting — \
+             deferring to start_gateway's normal conflict handling",
+            preferred_port
+        );
+    }
+
     // Start with new config
     start_gateway(
         port,

apps/desktop/src/features/clients/RegisterApiKeyClientModal.tsx

@@ -10,12 +10,27 @@
  * never display it again — if lost, revoke it and issue a new one.
  */
 
-import { useState } from 'react';
+import { useEffect, useState } from 'react';
 import { AlertTriangle, Check, Copy, KeyRound, Loader2, ShieldCheck, X } from 'lucide-react';
 import { Button, Card, CardContent, CardDescription, CardHeader, CardTitle } from '@mcpmux/ui';
 import { registerApiKeyClient, type RegisteredApiKeyClient } from '@/lib/api/gateway';
+import {
+  createMachine,
+  getHostname,
+  listMachines,
+  setClientMachineId,
+  type Machine,
+} from '@/lib/api/machines';
+import {
+  getMissingMachineProfileField,
+  toMachineProfilePayload,
+} from '@/lib/machine-profile.helpers';
+import { EmojiPickerButton } from '@/components/emoji-picker-button.component';
 import { useSpaces } from '@/stores';
 
+/** Sentinel `<select>` value that reveals the "create new machine" sub-form. */
+const NEW_MACHINE_OPTION = '__new__';
+
 interface RegisterApiKeyClientModalProps {
   onClose: () => void;
   /** Called once the client + key are created, so the page can refresh. */
@@ -37,19 +52,62 @@ export function RegisterApiKeyClientModal({
   const [result, setResult] = useState<RegisteredApiKeyClient | null>(null);
   const [copied, setCopied] = useState(false);
 
+  const [machines, setMachines] = useState<Machine[]>([]);
+  const [selectedMachineId, setSelectedMachineId] = useState('');
+  const [machineName, setMachineName] = useState('');
+  const [machineIcon, setMachineIcon] = useState('');
+  const [machineHostname, setMachineHostname] = useState('');
+  const isCreatingMachine = selectedMachineId === NEW_MACHINE_OPTION;
+
+  useEffect(() => {
+    void listMachines()
+      .then(setMachines)
+      .catch(() => undefined);
+  }, []);
+
   const handleGenerate = async () => {
     const trimmed = name.trim();
     if (!trimmed) {
       setError('Give the client a name so you can recognise it later.');
       return;
     }
+    if (isCreatingMachine) {
+      const missingField = getMissingMachineProfileField({
+        name: machineName,
+        icon: machineIcon,
+        hostname: machineHostname,
+      });
+      if (missingField) {
+        setError(`New machine ${missingField} is required, or switch back to "No machine".`);
+        return;
+      }
+    }
+
     setIsSubmitting(true);
     setError(null);
     try {
       const client = await registerApiKeyClient(
         trimmed,
         lockedSpaceId.trim() ? lockedSpaceId.trim() : null
       );
+
+      let machineId: string | null = null;
+      if (isCreatingMachine) {
+        const created = await createMachine(
+          toMachineProfilePayload({
+            name: machineName,
+            icon: machineIcon,
+            hostname: machineHostname,
+          })
+        );
+        machineId = created.id;
+      } else if (selectedMachineId) {
+        machineId = selectedMachineId;
+      }
+      if (machineId) {
+        await setClientMachineId(client.clientId, machineId);
+      }
+
       setResult(client);
     } catch (e) {
       setError(e instanceof Error ? e.message : String(e));
@@ -169,10 +227,7 @@ export function RegisterApiKeyClientModal({
               </div>
 
               <div>
-                <label
-                  htmlFor="api-key-locked-space"
-                  className="mb-1.5 block text-sm font-medium"
-                >
+                <label htmlFor="api-key-locked-space" className="mb-1.5 block text-sm font-medium">
                   Lock to a Space
                 </label>
                 <select
@@ -196,6 +251,61 @@ export function RegisterApiKeyClientModal({
                 </p>
               </div>
 
+              <div>
+                <label htmlFor="api-key-machine" className="mb-1.5 block text-sm font-medium">
+                  Machine
+                </label>
+                <select
+                  id="api-key-machine"
+                  data-testid="register-api-key-machine"
+                  value={selectedMachineId}
+                  onChange={(e) => setSelectedMachineId(e.target.value)}
+                  className="w-full rounded-xl border border-[rgb(var(--border))] bg-[rgb(var(--surface))] px-3.5 py-2.5 text-sm transition-all focus:border-[rgb(var(--accent))] focus:outline-none focus:ring-2 focus:ring-[rgb(var(--accent))]/40"
+                >
+                  <option value="">No machine — assign later if needed</option>
+                  {machines.map((machine) => (
+                    <option key={machine.id} value={machine.id}>
+                      {machine.icon ? `${machine.icon} ` : ''}
+                      {machine.name}
+                    </option>
+                  ))}
+                  <option value={NEW_MACHINE_OPTION}>+ New machine…</option>
+                </select>
+                {isCreatingMachine && (
+                  <div className="mt-3 space-y-3 rounded-xl border border-[rgb(var(--border))] p-4">
+                    <div className="flex items-center gap-2">
+                      <EmojiPickerButton value={machineIcon} onChange={setMachineIcon} />
+                      <input
+                        type="text"
+                        value={machineName}
+                        onChange={(e) => setMachineName(e.target.value)}
+                        placeholder="e.g. Cursor Web"
+                        className="h-10 min-w-0 flex-1 rounded-lg border border-[rgb(var(--border))] bg-[rgb(var(--background))] px-3 text-sm"
+                      />
+                    </div>
+                    <input
+                      type="text"
+                      value={machineHostname}
+                      onChange={(e) => setMachineHostname(e.target.value)}
+                      onFocus={() => {
+                        if (!machineHostname) {
+                          void getHostname()
+                            .then(setMachineHostname)
+                            .catch(() => undefined);
+                        }
+                      }}
+                      placeholder="Hostname"
+                      className="w-full rounded-lg border border-[rgb(var(--border))] bg-[rgb(var(--background))] px-3 py-2 font-mono text-sm"
+                    />
+                  </div>
+                )}
+                <p className="mt-1.5 text-xs text-[rgb(var(--muted))]">
+                  Optional. Tags the client so tunneled routing (the{' '}
+                  <code>X-Mcpmux-Machine-Id</code> header) and the Connections list can identify
+                  which device it's connecting from.
+                </p>
+              </div>
+
               <div className="flex items-start gap-3 rounded-xl border border-[rgb(var(--border-subtle))] bg-[rgb(var(--surface))] p-3.5">
                 <ShieldCheck className="mt-0.5 h-5 w-5 flex-shrink-0 text-[rgb(var(--accent))]" />
                 <p className="text-xs text-[rgb(var(--muted))]">

apps/desktop/src/features/gateway/useGatewayControl.tsx

@@ -90,8 +90,7 @@ export function useGatewayControl() {
   const start = async (opts?: { port?: number }): Promise<GatewayStartOutcome> => {
     try {
       return await runStart(
-        (allowFallback) =>
-          startGateway({ port: opts?.port, allowDynamicFallback: allowFallback }),
+        (allowFallback) => startGateway({ port: opts?.port, allowDynamicFallback: allowFallback }),
         opts?.port
       );
     } catch (err) {
@@ -104,12 +103,18 @@ export function useGatewayControl() {
   };
 
   const restart = async (opts?: { port?: number }): Promise<GatewayStartOutcome> => {
+    // Unlike start(), restart never pre-probes the port: the gateway we're
+    // about to replace is still holding it at probe time, so
+    // probeGatewayStart() would see our own listener and spuriously report
+    // the port as taken. Restart owns the port by definition — go straight
+    // to restartGateway() and only surface the confirm dialog on a genuine
+    // bind failure (handleBindFailure), same as a real conflict from start().
+    console.log('[Gateway] restart → skipping pre-probe, going straight to restartGateway');
     try {
-      return await runStart(
-        (allowFallback) =>
-          restartGateway({ port: opts?.port, allowDynamicFallback: allowFallback }),
-        opts?.port
-      );
+      const url = await restartGateway({ port: opts?.port, allowDynamicFallback: false });
+      const port = parsePortFromUrl(url) ?? opts?.port ?? 0;
+      console.log('[Gateway] restart ok →', url);
+      return { status: 'started', url, port, fellBackToDynamic: false };
     } catch (err) {
       return await handleBindFailure(err, opts?.port, (allowFallback) =>
         restartGateway({ port: opts?.port, allowDynamicFallback: allowFallback })

crates/mcpmux-core/src/domain/workspace_binding.rs

@@ -925,7 +925,10 @@ mod tests {
     #[test]
     fn normalize_expands_home_tilde() {
         let home = dirs::home_dir().expect("test environment has a home dir");
-        let home_str = home.to_string_lossy().trim_end_matches(['/', '\\']).to_string();
+        let home_str = home
+            .to_string_lossy()
+            .trim_end_matches(['/', '\\'])
+            .to_string();
 
         assert_eq!(
             normalize_workspace_root("~/Desktop/proj"),

crates/mcpmux-storage/src/database.rs

@@ -228,6 +228,11 @@ const MIGRATIONS: &[Migration] = &[
         name: "inbound_client_icon",
         sql: include_str!("migrations/039_inbound_client_icon.sql"),
     },
+    Migration {
+        version: 40,
+        name: "public_url_rename",
+        sql: include_str!("migrations/040_public_url_rename.sql"),
+    },
 ];
 
 /// SQLite database wrapper.
@@ -768,7 +773,7 @@ mod tests {
                 |row| row.get(0),
             )
             .unwrap();
-        assert_eq!(version, 38);
+        assert_eq!(version, 40);
 
         let v16_name: String = db
             .conn
@@ -863,4 +868,113 @@ mod tests {
 
         assert_eq!(name, "Test");
     }
+
+    /// Migration 40 must carry an old `gateway.public_url` row over to
+    /// `gateway.public_base_url` (the key current code actually reads) and
+    /// remove the superseded key, without clobbering an already-current row.
+    #[test]
+    fn migration_40_renames_public_url_setting_key() {
+        use rusqlite::{params, Connection};
+
+        let conn = Connection::open_in_memory().unwrap();
+        conn.pragma_update(None, "foreign_keys", "ON").unwrap();
+        let db = Database { conn };
+        db.ensure_migrations_table().unwrap();
+
+        // Apply migrations up to v39, recording each as applied.
+        const PRE_RENAME: i64 = 39;
+        for m in MIGRATIONS.iter().filter(|m| m.version <= PRE_RENAME) {
+            db.conn.execute_batch(m.sql).unwrap();
+            db.conn
+                .execute(
+                    "INSERT OR REPLACE INTO schema_migrations (version, name, applied_at) \
+                     VALUES (?1, ?2, datetime('now'))",
+                    params![m.version, m.name],
+                )
+                .unwrap();
+        }
+
+        // Seed the OLD key, simulating an install that predates the rename.
+        db.conn
+            .execute(
+                "INSERT INTO app_settings (key, value, updated_at) \
+                 VALUES ('gateway.public_url', 'https://mcp.example.com', datetime('now'))",
+                [],
+            )
+            .unwrap();
+
+        db.run_migrations().unwrap();
+
+        let new_value: String = db
+            .conn
+            .query_row(
+                "SELECT value FROM app_settings WHERE key = 'gateway.public_base_url'",
+                [],
+                |row| row.get(0),
+            )
+            .unwrap();
+        assert_eq!(new_value, "https://mcp.example.com");
+
+        let old_key_count: i64 = db
+            .conn
+            .query_row(
+                "SELECT COUNT(*) FROM app_settings WHERE key = 'gateway.public_url'",
+                [],
+                |row| row.get(0),
+            )
+            .unwrap();
+        assert_eq!(old_key_count, 0, "old key must be removed");
+    }
+
+    /// If the new key is already present (e.g. the user re-saved the setting
+    /// as a workaround), migration 40 must not overwrite it with the old
+    /// value — `INSERT OR IGNORE` should be a no-op for that row.
+    #[test]
+    fn migration_40_does_not_overwrite_existing_new_key() {
+        use rusqlite::{params, Connection};
+
+        let conn = Connection::open_in_memory().unwrap();
+        conn.pragma_update(None, "foreign_keys", "ON").unwrap();
+        let db = Database { conn };
+        db.ensure_migrations_table().unwrap();
+
+        const PRE_RENAME: i64 = 39;
+        for m in MIGRATIONS.iter().filter(|m| m.version <= PRE_RENAME) {
+            db.conn.execute_batch(m.sql).unwrap();
+            db.conn
+                .execute(
+                    "INSERT OR REPLACE INTO schema_migrations (version, name, applied_at) \
+                     VALUES (?1, ?2, datetime('now'))",
+                    params![m.version, m.name],
+                )
+                .unwrap();
+        }
+
+        db.conn
+            .execute(
+                "INSERT INTO app_settings (key, value, updated_at) \
+                 VALUES ('gateway.public_url', 'https://stale.example.com', datetime('now'))",
+                [],
+            )
+            .unwrap();
+        db.conn
+            .execute(
+                "INSERT INTO app_settings (key, value, updated_at) \
+                 VALUES ('gateway.public_base_url', 'https://current.example.com', datetime('now'))",
+                [],
+            )
+            .unwrap();
+
+        db.run_migrations().unwrap();
+
+        let new_value: String = db
+            .conn
+            .query_row(
+                "SELECT value FROM app_settings WHERE key = 'gateway.public_base_url'",
+                [],
+                |row| row.get(0),
+            )
+            .unwrap();
+        assert_eq!(new_value, "https://current.example.com");
+    }
 }

crates/mcpmux-storage/src/migrations/040_public_url_rename.sql

@@ -0,0 +1,13 @@
+-- Migration 040: gateway.public_url -> gateway.public_base_url key rename.
+--
+-- Two branches independently introduced this setting under different key
+-- names on 2026-05-27; current code only reads gateway.public_base_url, so
+-- installs that still carry the old key silently lose their public URL
+-- (allowed_hosts drops the tunnel hostname -> remote requests 403).
+
+INSERT OR IGNORE INTO app_settings (key, value, updated_at)
+SELECT 'gateway.public_base_url', value, datetime('now')
+  FROM app_settings
+ WHERE key = 'gateway.public_url';
+
+DELETE FROM app_settings WHERE key = 'gateway.public_url';