switchboard-router 0.6.2 → 0.6.4

package/cli.js

@@ -6,6 +6,30 @@ const fs = require("fs");
 const https = require("https");
 const os = require("os");
 const { openBrowser: openBrowserWithoutShell } = require("./src/shared/openBrowser");
+const pkg = require("./package.json");
+const { DEFAULT_HOST, DEFAULT_PORT, formatHelp, isLoopbackHost, parseCliArgs } = require("./src/cli/cliOptions");
+const processTools = require("./src/cli/processManager");
+const { findListeningPids } = processTools;
+const { probeSwitchboard, probeTcp, waitForSwitchboard } = require("./src/cli/serverStatus");
+
+let cliOptions;
+try {
+  cliOptions = parseCliArgs(process.argv.slice(2));
+} catch (error) {
+  console.error(`Error: ${error.message}\n`);
+  console.error(formatHelp({ version: pkg.version }));
+  process.exit(2);
+}
+
+if (cliOptions.help) {
+  console.log(formatHelp({ version: pkg.version }));
+  process.exit(0);
+}
+if (cliOptions.version) {
+  console.log(pkg.version);
+  process.exit(0);
+}
+const startsServer = ["start", "restart"].includes(cliOptions.command);
 
 // Native spinner - no external dependency
 function createSpinner(text) {
@@ -43,12 +67,9 @@ function createSpinner(text) {
   };
 }
 
-const pkg = require("./package.json");
 const { ensureSqliteRuntime, buildEnvWithRuntime } = require("./hooks/sqliteRuntime");
 const { ensureTrayRuntime } = require("./hooks/trayRuntime");
 const { pinDataDir, getDataDir } = require("./src/shared/dataDir");
-const { disableMitm } = require("./src/shared/disableMitm");
-const args = process.argv.slice(2);
 
 // Resolve the data directory ONCE, before anything can create cache dirs inside
 // a candidate, and export it so the spawned server and the CLI's token client
@@ -58,10 +79,14 @@ pinDataDir();
 // Self-heal SQLite runtime deps (sql.js + better-sqlite3) into ~/.switchboard/runtime
 // so the server can resolve them via NODE_PATH. Best-effort — sql.js is required,
 // better-sqlite3 is optional. Logs to stderr only on failure.
-try { ensureSqliteRuntime({ silent: true }); } catch {}
+if (startsServer) {
+  try { ensureSqliteRuntime({ silent: true }); } catch {}
+}
 
 // Self-heal tray runtime (systray for macOS/Linux only). Windows skipped.
-try { ensureTrayRuntime({ silent: true }); } catch {}
+if (startsServer) {
+  try { ensureTrayRuntime({ silent: true }); } catch {}
+}
 
 // Configuration constants
 // npm package name (switchboard-router) vs CLI bin (switchboard)
@@ -69,12 +94,34 @@ const PKG_NAME = pkg.name || "switchboard-router";
 const APP_NAME =
   (pkg.bin && Object.keys(pkg.bin)[0]) || "switchboard";
 const INSTALL_CMD_LATEST = `npm i -g ${PKG_NAME}@latest --prefer-online`;
+const INSTANCE_ID = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+
+function commandFor(action = "") {
+  const commandName = action ? `${APP_NAME} ${action}` : APP_NAME;
+  return `${commandName}${port === DEFAULT_PORT ? "" : ` --port ${port}`}`;
+}
 
-const DEFAULT_PORT = 20128;
 // C1: bind loopback by default — LAN exposure is an explicit opt-in via --host 0.0.0.0
-const DEFAULT_HOST = "127.0.0.1";
 const ALL_INTERFACES = "0.0.0.0";
 
+function isNetworkExposed() {
+  return !isLoopbackHost(host);
+}
+
+function getProbeHost() {
+  if (host === ALL_INTERFACES) return "127.0.0.1";
+  if (host === "::") return "::1";
+  return host;
+}
+
+function needsOwnedTcpProbe() {
+  return isNetworkExposed() && host !== ALL_INTERFACES && host !== "::";
+}
+
+function hasOwnedServerListener() {
+  return findListeningPids(port).some((pid) => processTools.processMatchesRecordedPath(pid, serverPath));
+}
+
 // First non-internal IPv4 — the address remote peers actually reach when bound to 0.0.0.0.
 function getLanIp() {
   for (const ifaces of Object.values(os.networkInterfaces())) {
@@ -87,58 +134,24 @@ function getLanIp() {
 
 // Local URL stays "localhost" for loopback binds.
 function getDisplayHost() {
-  if (host === DEFAULT_HOST || host === "localhost" || host === "::1") return "localhost";
+  if ([DEFAULT_HOST, "localhost", "::1", ALL_INTERFACES, "::"].includes(host)) return "localhost";
   return host;
 }
-const MAX_PORT_ATTEMPTS = 10;
-// Parse arguments
-let port = DEFAULT_PORT;
-let host = DEFAULT_HOST;
-let noBrowser = false;
-let skipUpdate = false;
-let showLog = false;
-let trayMode = false;
-
-for (let i = 0; i < args.length; i++) {
-  if (args[i] === "--port" || args[i] === "-p") {
-    port = parseInt(args[i + 1], 10) || DEFAULT_PORT;
-    i++;
-  } else if (args[i] === "--host" || args[i] === "-H") {
-    host = args[i + 1] || DEFAULT_HOST;
-    i++;
-  } else if (args[i] === "--no-browser" || args[i] === "-n") {
-    noBrowser = true;
-  } else if (args[i] === "--log" || args[i] === "-l") {
-    showLog = true;
-  } else if (args[i] === "--skip-update") {
-    skipUpdate = true;
-  } else if (args[i] === "--tray" || args[i] === "-t") {
-    trayMode = true;
-    process.env.TRAY_MODE = "1";
-  } else if (args[i] === "--help" || args[i] === "-h") {
-    console.log(`
-Usage: ${APP_NAME} [options]
-
-Options:
-  -p, --port <port>   Port to run the server (default: ${DEFAULT_PORT})
-  -H, --host <host>   Host to bind (default: ${DEFAULT_HOST})
-  -n, --no-browser    Don't open browser automatically
-  -l, --log           Show server logs (default: hidden)
-  -t, --tray          Run in system tray mode (background)
-  --skip-update       Skip auto-update check
-  -h, --help          Show this help message
-  -v, --version       Show version
-`);
-    process.exit(0);
-  } else if (args[i] === "--version" || args[i] === "-v") {
-    console.log(pkg.version);
-    process.exit(0);
-  }
+const command = cliOptions.command;
+let port = cliOptions.port;
+let host = cliOptions.host;
+const noBrowser = cliOptions.noBrowser;
+const skipUpdate = cliOptions.skipUpdate;
+const showLog = cliOptions.showLog;
+let trayMode = cliOptions.trayMode;
+
+if (noBrowser) {
+  console.warn("Note: --no-browser is retained for compatibility; Switchboard only opens a browser when you explicitly select Web UI.");
 }
 
 // A detached or piped CLI cannot answer the interactive menu. Keep it in the
 // long-lived tray lifecycle even when it was launched without lifecycle flags.
-if ((!process.stdin.isTTY || !process.stdout.isTTY) && !trayMode) {
+if (startsServer && (!process.stdin.isTTY || !process.stdout.isTTY) && !trayMode) {
   trayMode = true;
   process.env.TRAY_MODE = "1";
 }
@@ -174,36 +187,40 @@ function readOwnedProcessState() {
 function writeOwnedProcessState(serverPid) {
   try {
     const file = getProcessStateFile();
+    const tmp = `${file}.tmp-${process.pid}`;
     fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, JSON.stringify({
+    const state = JSON.stringify({
       cliPid: process.pid,
       cliPath: __filename,
       serverPid,
       serverPath,
+      port,
+      host,
+      instanceId: INSTANCE_ID,
       writtenAt: Date.now(),
-    }), { mode: 0o600 });
+    });
+    fs.writeFileSync(tmp, state, { mode: 0o600 });
+    fs.renameSync(tmp, file);
   } catch { /* best effort */ }
 }
 
 function clearOwnedProcessState() {
   try {
     const state = readOwnedProcessState();
-    if (Number(state.cliPid) === process.pid) fs.unlinkSync(getProcessStateFile());
+    if (Number(state.cliPid) === process.pid && state.instanceId === INSTANCE_ID) fs.unlinkSync(getProcessStateFile());
   } catch { /* best effort */ }
 }
 
-function processMatchesRecordedPath(pid, expectedPath) {
-  if (!expectedPath) return false;
+function clearRecordedProcessState(state) {
   try {
-    const command = process.platform === "win32"
-      ? execSync(`powershell -NonInteractive -NoProfile -Command "(Get-CimInstance Win32_Process -Filter 'ProcessId = ${Number(pid)}').CommandLine"`, { encoding: "utf8", windowsHide: true, timeout: 3000 })
-      : execSync(`ps -p ${Number(pid)} -o command=`, { encoding: "utf8", timeout: 3000 });
-    return command.includes(expectedPath);
-  } catch {
-    // If identity cannot be verified, fail closed rather than risking a PID
-    // reuse killing an unrelated process.
-    return false;
-  }
+    const current = readOwnedProcessState();
+    const sameGeneration = current.instanceId
+      ? current.instanceId === state.instanceId
+      : Number(current.cliPid) === Number(state.cliPid)
+        && Number(current.serverPid) === Number(state.serverPid)
+        && Number(current.writtenAt) === Number(state.writtenAt);
+    if (sameGeneration) fs.unlinkSync(getProcessStateFile());
+  } catch { /* best effort */ }
 }
 
 function readOwnedAppPids() {
@@ -214,16 +231,21 @@ function readOwnedAppPids() {
   ]
     .filter(([, expectedPath]) => typeof expectedPath === "string" && expectedPath.length > 0)
     .map(([pid, expectedPath]) => [Number(pid), expectedPath])
-    .filter(([pid, expectedPath]) => Number.isInteger(pid) && pid > 1 && pid !== process.pid && processMatchesRecordedPath(pid, expectedPath))
+    .filter(([pid, expectedPath]) => Number.isInteger(pid) && pid > 1 && pid !== process.pid && processTools.processMatchesRecordedPath(pid, expectedPath))
     .map(([pid]) => pid);
 }
 
 // Kill PID from file (best-effort, removes file after)
-function killByPidFile(pidFile) {
+function killByPidFile(pidFile, expectedProcessNames = []) {
   try {
     if (!fs.existsSync(pidFile)) return;
     const pid = parseInt(fs.readFileSync(pidFile, "utf8").trim(), 10);
     if (!pid) return;
+    const commandLine = processTools.getProcessCommand(pid).toLowerCase();
+    if (!commandLine || !expectedProcessNames.some((name) => commandLine.includes(name.toLowerCase()))) {
+      console.warn(`[switchboard] refusing to signal unverifiable PID ${pid} from ${pidFile}`);
+      return;
+    }
     try {
       if (process.platform === "win32") {
         execSync(`taskkill /F /T /PID ${pid}`, { stdio: "ignore", windowsHide: true, timeout: 3000 });
@@ -231,65 +253,35 @@ function killByPidFile(pidFile) {
         process.kill(pid, "SIGKILL");
       }
     } catch { }
-    try { fs.unlinkSync(pidFile); } catch { }
+    if (!processTools.isPidAlive(pid)) {
+      try { fs.unlinkSync(pidFile); } catch { }
+    }
   } catch { }
 }
 
 // Kill tunnel processes (cloudflared/tailscale) by their PID files
 function killTunnelByPidFile() {
   const tunnelDir = path.join(getAppDataDir(), "tunnel");
-  killByPidFile(path.join(tunnelDir, "cloudflared.pid"));
-  killByPidFile(path.join(tunnelDir, "tailscale.pid"));
+  killByPidFile(path.join(tunnelDir, "cloudflared.pid"), ["cloudflared"]);
+  killByPidFile(path.join(tunnelDir, "tailscale.pid"), ["tailscale"]);
 }
 
 // Kill only processes previously recorded by this launcher.
-function killAllAppProcesses(appPort) {
-  return new Promise((resolve) => {
-    try {
-      // Kill MIT first (privileged process, needs special handling)
-      killProxyByPidFile();
-      // Kill cloudflared/tailscale by PID file (precise, only this app's tunnel)
-      killTunnelByPidFile();
-
-      const platform = process.platform;
-      const pids = readOwnedAppPids();
-
-      // Gracefully stop owned processes, then force only survivors.
-      if (pids.length > 0) {
-        const uniquePids = [...new Set(pids.map(Number))];
-        uniquePids.forEach(pid => {
-          try {
-            if (platform === "win32") {
-              execSync(`taskkill /T /PID ${pid} 2>nul`, { stdio: 'ignore', shell: true, windowsHide: true, timeout: 3000 });
-            } else {
-              process.kill(pid, "SIGTERM");
-            }
-          } catch (err) {
-            // Process already dead or can't kill - continue
-          }
-        });
-        setTimeout(() => {
-          uniquePids.forEach((pid) => {
-            try {
-              process.kill(pid, 0);
-              if (platform === "win32") {
-                execSync(`taskkill /F /T /PID ${pid} 2>nul`, { stdio: "ignore", shell: true, windowsHide: true, timeout: 3000 });
-              } else {
-                process.kill(pid, "SIGKILL");
-              }
-            } catch { /* already stopped */ }
-          });
-          try { fs.unlinkSync(getProcessStateFile()); } catch { }
-          resolve();
-        }, 2000);
-      } else {
-        resolve();
-      }
-    } catch (err) {
-      // Silent fail - continue anyway
-      resolve();
-    }
-  });
+async function killAllAppProcesses(appPort) {
+  killProxyByPidFile();
+  killTunnelByPidFile();
+  const state = readOwnedProcessState();
+  const recoverableServerPids = findListeningPids(appPort)
+    .filter((pid) => processTools.processMatchesRecordedPath(pid, serverPath));
+  const uniquePids = [...new Set([...readOwnedAppPids(), ...recoverableServerPids].map(Number))];
+  const serverPids = new Set([Number(state.serverPid), ...recoverableServerPids]);
+  const results = await Promise.allSettled(uniquePids.map((pid) => processTools.terminatePid(pid, {
+    timeoutMs: 2500,
+    processGroup: serverPids.has(pid),
+  })));
+  const allStopped = results.every((result) => result.status === "fulfilled" && result.value === true);
+  if (allStopped) clearRecordedProcessState(state);
+  return allStopped;
 }
 
 // Sleep helper using SharedArrayBuffer wait (sync, no busy-loop)
@@ -315,6 +307,11 @@ function killProxyByPidFile() {
     if (!fs.existsSync(pidFile)) return;
     const pid = parseInt(fs.readFileSync(pidFile, "utf8").trim(), 10);
     if (!pid) return;
+    const commandLine = processTools.getProcessCommand(pid).toLowerCase();
+    if (!commandLine || !commandLine.includes("mitm") || !commandLine.includes("server")) {
+      console.warn(`[switchboard] refusing to signal unverifiable MITM PID ${pid}`);
+      return;
+    }
 
     if (process.platform === "win32") {
       // Graceful first (lets server cleanup hosts), then force
@@ -335,74 +332,23 @@ function killProxyByPidFile() {
         catch { try { process.kill(pid, "SIGKILL"); } catch { } }
       }
     }
-    try { fs.unlinkSync(pidFile); } catch { }
-  } catch { }
-}
-
-function findListeningPids(port) {
-  const numericPort = Number(port);
-  if (!Number.isInteger(numericPort) || numericPort <= 0) return [];
-
-  try {
-    if (process.platform === "win32") {
-      const output = execSync(`netstat -ano | findstr :${numericPort}`, {
-        encoding: "utf8",
-        shell: true,
-        windowsHide: true,
-        timeout: 5000,
-      });
-      return output.split("\n")
-        .filter((line) => line.includes("LISTENING"))
-        .filter((line) => line.trim().split(/\s+/).some((field) => field.endsWith(`:${numericPort}`)))
-        .map((line) => Number(line.trim().split(/\s+/).pop()))
-        .filter((pid) => Number.isInteger(pid) && pid > 1);
+    if (!processTools.isPidAlive(pid)) {
+      try { fs.unlinkSync(pidFile); } catch { }
     }
-
-    const output = execSync(`lsof -tiTCP:${numericPort} -sTCP:LISTEN`, {
-      encoding: "utf8",
-      stdio: ["pipe", "pipe", "ignore"],
-    });
-    return output.split(/\s+/)
-      .map(Number)
-      .filter((pid) => Number.isInteger(pid) && pid > 1);
-  } catch {
-    return [];
-  }
+  } catch { }
 }
 
 // Never kill an arbitrary listener that happens to share the app port. The
 // launcher may only signal PIDs recorded in its ownership state file.
-function killProcessOnPort(port) {
-  const ownedPids = new Set(readOwnedAppPids());
-  const pids = findListeningPids(port).filter((pid) => ownedPids.has(pid));
-  if (pids.length === 0) return Promise.resolve();
-
-  return new Promise((resolve) => {
-    const platform = process.platform;
-    pids.forEach((pid) => {
-      try {
-        if (platform === "win32") {
-          execSync(`taskkill /T /PID ${pid}`, { stdio: "ignore", shell: true, windowsHide: true, timeout: 3000 });
-        } else {
-          process.kill(pid, "SIGTERM");
-        }
-      } catch { /* already dead or inaccessible */ }
-    });
-
-    setTimeout(() => {
-      pids.forEach((pid) => {
-        try {
-          process.kill(pid, 0);
-          if (platform === "win32") {
-            execSync(`taskkill /F /T /PID ${pid}`, { stdio: "ignore", shell: true, windowsHide: true, timeout: 3000 });
-          } else {
-            process.kill(pid, "SIGKILL");
-          }
-        } catch { /* already stopped */ }
-      });
-      resolve();
-    }, 500);
-  });
+async function killProcessOnPort(port) {
+  const listeningPids = findListeningPids(port);
+  const ownedPids = new Set([
+    ...readOwnedAppPids(),
+    ...listeningPids.filter((pid) => processTools.processMatchesRecordedPath(pid, serverPath)),
+  ]);
+  const pids = listeningPids.filter((pid) => ownedPids.has(pid));
+  const results = await Promise.allSettled(pids.map((pid) => processTools.terminatePid(pid, { timeoutMs: 1000 })));
+  return results.every((result) => result.status === "fulfilled" && result.value === true);
 }
 
 
@@ -501,20 +447,141 @@ const serverPath = fs.existsSync(customServerPath)
   ? customServerPath
   : path.join(standaloneDir, "server.js");
 
-if (!fs.existsSync(serverPath)) {
+if (startsServer && !fs.existsSync(serverPath)) {
   console.error("Error: Standalone build not found.");
   console.error("Please run 'npm run build:cli' first.");
   process.exit(1);
 }
 
-// Check for updates FIRST, then start server
-checkForUpdate().then((latestVersion) => {
-  killAllAppProcesses(port).then(() => {
-    return killProcessOnPort(port);
-  }).then(() => {
+async function probeRunningSwitchboard() {
+  const serverInfo = await probeSwitchboard(port, 1000, getProbeHost());
+  if (serverInfo) return serverInfo;
+  if (needsOwnedTcpProbe() && hasOwnedServerListener() && await probeTcp(port, 1000, getProbeHost())) {
+    return { name: "switchboard-app", version: null, startedAt: null, tcpOnly: true };
+  }
+  return null;
+}
+
+async function showStatus() {
+  const listeners = findListeningPids(port);
+  const serverInfo = await probeSwitchboard(port, 1000, getProbeHost());
+  const state = readOwnedProcessState();
+  const stateApplies = Number(state.port) === port;
+  const recordedPids = stateApplies ? new Set(readOwnedAppPids()) : new Set();
+  const owned = listeners.filter((pid) =>
+    recordedPids.has(pid) || processTools.processMatchesRecordedPath(pid, serverPath)
+  );
+  const tcpVerified = !serverInfo && needsOwnedTcpProbe() && owned.length > 0
+    ? await probeTcp(port, 1000, getProbeHost())
+    : false;
+  const verifiedServer = (!!serverInfo && (!serverInfo.legacyHealth || owned.length > 0)) || tcpVerified;
+  const result = {
+    running: verifiedServer,
+    port,
+    url: `http://localhost:${port}`,
+    listenerPids: listeners,
+    ownedPids: owned,
+    cliPid: stateApplies && recordedPids.has(Number(state.cliPid)) ? Number(state.cliPid) : null,
+    serverPid: verifiedServer ? (owned[0] || listeners[0] || null) : null,
+    serverVersion: serverInfo?.version || null,
+    cliVersion: pkg.version,
+    startedAt: serverInfo?.startedAt || null,
+    conflict: listeners.length > 0 && !verifiedServer,
+  };
+
+  if (cliOptions.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (result.running) {
+    console.log(`Switchboard is running at ${result.url}`);
+    console.log(`Server: v${result.serverVersion || "unknown"} (PID: ${result.serverPid || "unknown"})`);
+    console.log(`CLI:    v${result.cliVersion}`);
+    console.log(`Managed: ${owned.length ? "yes" : "no (this CLI will not signal an unverified process)"}`);
+    if (result.startedAt) console.log(`Started: ${result.startedAt}`);
+    if (owned.length) {
+      console.log(`Stop:   ${commandFor("stop")}`);
+      console.log(`Restart:${commandFor("restart")}`);
+    }
+  } else if (result.conflict) {
+    console.error(`Switchboard is stopped, but port ${port} is used by another process (PID: ${listeners.join(", ")}).`);
+  } else {
+    console.log(`Switchboard is not running on port ${port}.`);
+    console.log(`Start: ${commandFor()}`);
+  }
+  return result;
+}
+
+async function stopExistingInstance({ quiet = false } = {}) {
+  const before = quiet ? null : await probeRunningSwitchboard();
+  if (!quiet) console.log(before ? `Stopping Switchboard on port ${port}...` : `Checking for an owned Switchboard instance on port ${port}...`);
+  await killAllAppProcesses(port);
+  await killProcessOnPort(port);
+  await new Promise((resolve) => setTimeout(resolve, 250));
+  const after = await probeRunningSwitchboard();
+  const survivors = readOwnedAppPids();
+  if (after || survivors.length > 0) {
+    const listeners = findListeningPids(port);
+    console.error(`Could not safely stop Switchboard on port ${port}${listeners.length ? ` (PID: ${listeners.join(", ")})` : ""}.`);
+    console.error(`Run "${commandFor("status")}" for details.`);
+    return false;
+  }
+  clearRecordedProcessState(readOwnedProcessState());
+  if (!quiet) console.log(before ? "Switchboard stopped gracefully." : "No running owned instance found.");
+  return true;
+}
+
+async function run() {
+  if (["status", "stop", "restart"].includes(command)) {
+    const recorded = readOwnedProcessState();
+    if (!cliOptions.portProvided && Number.isInteger(Number(recorded.port)) && Number(recorded.port) > 0 && Number(recorded.port) <= 65535) {
+      port = Number(recorded.port);
+    }
+    if (!cliOptions.hostProvided && typeof recorded.host === "string" && recorded.host) host = recorded.host;
+  }
+  if (command === "status") {
+    const status = await showStatus();
+    return status.running ? 0 : status.conflict ? 1 : 3;
+  }
+  const releaseLock = await processTools.acquireLifecycleLock(getAppDataDir(), { instanceId: INSTANCE_ID });
+  try {
+    if (command === "stop") {
+      const stopped = await stopExistingInstance();
+      return stopped ? 0 : 1;
+    }
+
+    if (command === "restart") console.log(`Restarting Switchboard on port ${port}...`);
+    const stopped = await stopExistingInstance({ quiet: command === "start" });
+    if (!stopped) return 1;
+
+    const remaining = findListeningPids(port);
+    if (remaining.length > 0) {
+      const existing = await probeSwitchboard(port, 1000, getProbeHost());
+      const recoverable = remaining.some((pid) => processTools.processMatchesRecordedPath(pid, serverPath));
+      if (existing && (!existing.legacyHealth || recoverable)) {
+        console.log(`Switchboard is already running at http://localhost:${port} (v${existing.version || "unknown"}).`);
+        console.log(`Use "${commandFor("restart")}" to replace it.`);
+        return 0;
+      }
+      console.error(`Port ${port} is already in use by another process (PID: ${remaining.join(", ")}).`);
+      console.error(`Choose another port with --port or stop that process first.`);
+      return 1;
+    }
+
+    const latestVersion = await checkForUpdate();
     startServer(latestVersion);
+    return null;
+  } finally {
+    releaseLock();
+  }
+}
+
+run()
+  .then((exitCode) => {
+    if (Number.isInteger(exitCode)) process.exit(exitCode);
+  })
+  .catch((error) => {
+    console.error(`Failed to start Switchboard: ${error.message}`);
+    process.exit(1);
   });
-});
 
 // Show interface selection menu
 async function showInterfaceMenu(latestVersion) {
@@ -567,10 +634,10 @@ const RESTART_RESET_MS = 30000; // Reset counter if alive > 30s
 function startServer(latestVersion) {
   const displayHost = getDisplayHost();
   const url = `http://${displayHost}:${port}/dashboard`;
-  // Surface real network exposure when bound to all interfaces (explicit opt-in).
-  if (host === ALL_INTERFACES || host === "::") {
-    const lanIp = getLanIp();
-    if (lanIp) console.log(`\x1b[33m⚠ Network-exposed: reachable at http://${lanIp}:${port} (bound ${host}). Use --host 127.0.0.1 for local-only. Non-loopback /v1 requires an API key by default.\x1b[0m`);
+  // Surface real network exposure for wildcard and specific non-loopback binds.
+  if (isNetworkExposed()) {
+    const reachableHost = host === ALL_INTERFACES || host === "::" ? getLanIp() : host;
+    if (reachableHost) console.log(`\x1b[33m⚠ Network-exposed: reachable at http://${reachableHost}:${port} (bound ${host}). Use --host 127.0.0.1 for local-only. Non-loopback /v1 requires an API key by default.\x1b[0m`);
   }
 
   let restartCount = 0;
@@ -584,7 +651,7 @@ function startServer(latestVersion) {
     crashLog = [];
     const child = spawn(RUNTIME, ["--max-old-space-size=6144", serverPath], {
       cwd: standaloneDir,
-      stdio: showLog ? "inherit" : ["ignore", "ignore", "pipe"],
+      stdio: ["ignore", "pipe", "pipe"],
       detached: true,
       windowsHide: true,
       env: {
@@ -594,90 +661,89 @@ function startServer(latestVersion) {
       }
     });
     if (child.pid) writeOwnedProcessState(child.pid);
-    if (!showLog && child.stderr) {
-      child.stderr.on("data", (data) => {
+    const captureOutput = (stream, destination) => {
+      if (!stream) return;
+      stream.on("data", (data) => {
         const lines = data.toString().split("\n").filter(Boolean);
         crashLog.push(...lines);
         if (crashLog.length > CRASH_LOG_LINES) crashLog = crashLog.slice(-CRASH_LOG_LINES);
+        if (showLog && destination?.writable) destination.write(data);
       });
-    }
+    };
+    captureOutput(child.stdout, process.stdout);
+    captureOutput(child.stderr, process.stderr);
     return child;
   }
 
   let server = spawnServer();
 
-  // Cleanup function - graceful SIGTERM → wait → SIGKILL
+  // One bounded, idempotent shutdown path owns every exit trigger.
   let isCleaningUp = false;
-  function cleanup() {
+  let isShuttingDown = false;
+  let shutdownPromise = null;
+  let restartTimer = null;
+
+  async function cleanup() {
     if (isCleaningUp) return;
     isCleaningUp = true;
     try {
-      // Kill tray if running
+      let trayCleanup = Promise.resolve();
       try {
         const { killTray } = require("./src/cli/tray/tray");
-        killTray();
+        trayCleanup = killTray();
       } catch (e) { }
-      // Kill MIT server (privileged process) via PID file
       killProxyByPidFile();
-      // Kill cloudflared/tailscale via PID file (only this app's tunnel)
       killTunnelByPidFile();
-      // Graceful shutdown: SIGTERM first so server can flush DB, then SIGKILL
-      if (server.pid) {
-        try { process.kill(server.pid, "SIGTERM"); } catch { }
-        if (!waitForExit(server.pid, 2000)) {
-          try { process.kill(server.pid, "SIGKILL"); } catch { }
-        }
-        // Also try to kill process group
-        try { process.kill(-server.pid, "SIGKILL"); } catch { }
-      }
-      clearOwnedProcessState();
+      const serverCleanup = server?.pid
+        ? processTools.terminatePid(server.pid, { timeoutMs: 2500, processGroup: true })
+        : Promise.resolve(true);
+      const [, serverResult] = await Promise.allSettled([trayCleanup, serverCleanup]);
+      if (serverResult.status === "fulfilled" && serverResult.value === true) clearOwnedProcessState();
     } catch (e) { }
   }
 
-  // Suppress all errors during shutdown (systray lib throws JSON parse errors)
-  let isShuttingDown = false;
+  function shutdown(exitCode = 0, message = "") {
+    if (shutdownPromise) return shutdownPromise;
+    isShuttingDown = true;
+    if (restartTimer) clearTimeout(restartTimer);
+    if (message) console.log(message);
+    shutdownPromise = cleanup().finally(() => process.exit(exitCode));
+    return shutdownPromise;
+  }
+
   process.on("uncaughtException", (err) => {
     if (isShuttingDown) return;
     console.error("Error:", err.message);
+    void shutdown(1);
   });
 
-  // Handle all exit scenarios
-  process.on("SIGINT", () => {
-    if (isShuttingDown) return;
-    isShuttingDown = true;
-    console.log("\nExiting...");
-    cleanup();
-    setTimeout(() => process.exit(0), 100);
-  });
-  process.on("SIGTERM", () => {
-    if (isShuttingDown) return;
-    isShuttingDown = true;
-    cleanup();
-    setTimeout(() => process.exit(0), 100);
-  });
-  process.on("SIGHUP", () => {
-    if (isShuttingDown) return;
-    isShuttingDown = true;
-    cleanup();
-    setTimeout(() => process.exit(0), 100);
-  });
+  process.on("SIGINT", () => { void shutdown(0, "\nStopping Switchboard gracefully..."); });
+  process.on("SIGTERM", () => { void shutdown(0); });
+  process.on("SIGHUP", () => { void shutdown(0); });
 
-  // Initialize tray icon (runs alongside TUI)
-  const initTrayIcon = () => {
+  const initTrayIcon = async () => {
     try {
       const { initTray } = require("./src/cli/tray/tray");
-      initTray({
+      const tray = initTray({
         port,
-        onQuit: () => {
-          isShuttingDown = true;
+        host,
+        onQuit: async () => {
           console.log("\n👋 Shutting down from tray...");
-          cleanup();
-          setTimeout(() => process.exit(0), 100);
+          await shutdown(0);
         },
         onOpenDashboard: () => openBrowser(url)
       });
+      if (!tray) return false;
+      if (typeof tray.ready === "function") {
+        await Promise.race([
+          tray.ready(),
+          new Promise((_, reject) => setTimeout(() => reject(new Error("tray startup timed out")), 5000)),
+        ]);
+      }
+      return true;
     } catch (err) {
-      // Tray not available - continue without it
+      console.error(`[switchboard] tray unavailable: ${err.message}`);
+      return false;
     }
   };
 
@@ -688,37 +754,64 @@ function startServer(latestVersion) {
     process.on("SIGHUP", () => {});
 
     console.log(`\n🚀 ${pkg.name} v${pkg.version}`);
-    console.log(`Server: http://${displayHost}:${port}`);
+    console.log(`Starting server at http://${displayHost}:${port}...`);
 
-    setTimeout(() => {
-      initTrayIcon();
-      console.log("\n💡 Router is now running in system tray. Close this terminal if you want.");
-      console.log("   Right-click tray icon to open dashboard or quit.\n");
-    }, 2000);
+    void (async () => {
+      const ready = await waitForSwitchboard(port, {
+        hostname: getProbeHost(),
+        acceptTcpFallback: needsOwnedTcpProbe() ? hasOwnedServerListener : null,
+      });
+      if (!ready || isShuttingDown) {
+        if (!isShuttingDown) {
+          console.error(`Server did not become ready on port ${port}.`);
+          await shutdown(1);
+        }
+        return;
+      }
+      const trayReady = await initTrayIcon();
+      if (trayReady) {
+        console.log("\nSwitchboard is ready in the system tray.");
+        console.log("Right-click the tray icon to open the dashboard or quit.");
+      } else {
+        console.warn("\nSwitchboard is running without a tray icon.");
+        console.warn(`Stop it gracefully with: ${commandFor("stop")}`);
+      }
+      console.log(`Server: http://${displayHost}:${port}`);
+      console.log(`Status: ${commandFor("status")}\n`);
+    })();
 
     return;
   }
 
-  // Wait for server to be ready, then show interface menu loop + tray
-  setTimeout(async () => {
-    // Start tray icon alongside TUI
-    initTrayIcon();
+  // Wait for the actual management endpoint before exposing controls.
+  void (async () => {
+    const ready = await waitForSwitchboard(port, {
+      hostname: getProbeHost(),
+      acceptTcpFallback: needsOwnedTcpProbe() ? hasOwnedServerListener : null,
+    });
+    if (!ready || isShuttingDown) {
+      if (!isShuttingDown) {
+        console.error(`Server did not become ready on port ${port}.`);
+        await shutdown(1);
+      }
+      return;
+    }
+    const trayReady = await initTrayIcon();
+    if (!trayReady) {
+      console.warn(`Tray icon unavailable. You can stop safely with Ctrl+C or "${APP_NAME} stop".`);
+    }
 
     try {
       while (true) {
         const choice = await showInterfaceMenu(latestVersion);
 
         if (choice === "update") {
-          isShuttingDown = true;
           const { clearScreen } = require("./src/cli/utils/display");
           clearScreen();
           console.log(`\n⬆  Update v${pkg.version} → v${latestVersion}\n`);
           console.log(`Run this after exit:\n`);
           console.log(`   \x1b[33m${INSTALL_CMD_LATEST}\x1b[0m\n`);
-          cleanup();
-          await killAllAppProcesses(port);
-          await killProcessOnPort(port);
-          setTimeout(() => process.exit(0), 200);
+          await shutdown(0);
           return;
         } else if (choice === "web") {
           openBrowser(url);
@@ -728,18 +821,12 @@ function startServer(latestVersion) {
         } else if (choice === "terminal") {
           // Start Terminal UI - it will return when user selects Back
           const { startTerminalUI } = require("./src/cli/terminalUI");
-          await startTerminalUI(port);
+          await startTerminalUI(port, { networkExposed: isNetworkExposed() });
           // Loop continues, show menu again
         } else if (choice === "hide") {
           const { clearScreen } = require("./src/cli/utils/display");
           clearScreen();
 
-          // Enable auto startup on OS boot
-          try {
-            const { enableAutoStart } = require("./src/cli/tray/autostart");
-            enableAutoStart(__filename);
-          } catch (e) { }
-
           if (process.platform === "darwin") {
             // macOS: keep current process alive — spawning a detached child puts
             // it outside the login session so NSStatusItem silently fails.
@@ -750,6 +837,7 @@ function startServer(latestVersion) {
             console.log(`🔔 Switchboard is running in tray (PID: ${process.pid})`);
             console.log(`   Server: http://${displayHost}:${port}`);
             console.log(`\n💡 You can close this terminal. Right-click tray icon to quit.\n`);
+            console.log(`   If the icon is unavailable: ${commandFor("stop")}\n`);
 
             // Tray already init'd at startup — just keep event loop alive.
             return;
@@ -758,7 +846,10 @@ function startServer(latestVersion) {
           // Windows/Linux: spawn detached bgProcess (systray works fine in child)
           console.log(`\n⏳ Starting background process... (tray icon will appear in ~3s)`);
 
-          const bgProcess = spawn(process.execPath, [__filename, "--tray", "--skip-update", "-p", port.toString()], {
+          await cleanup();
+          const { getLaunchArgs } = require("./src/cli/tray/autostart");
+          const bgArgs = [__filename, "start", ...getLaunchArgs({ port, host })];
+          const bgProcess = spawn(process.execPath, bgArgs, {
             detached: true,
             stdio: "ignore",
             windowsHide: true,
@@ -770,61 +861,61 @@ function startServer(latestVersion) {
           console.log(`   Server: http://${displayHost}:${port}`);
           console.log(`\n💡 You can close this terminal. Right-click tray icon to quit.\n`);
 
-          // cleanup() kills server so bgProcess can claim the port fresh
-          cleanup();
           process.exit(0);
         } else if (choice === "exit") {
-          isShuttingDown = true;
-          console.log("\nExiting...");
-          cleanup();
-          setTimeout(() => process.exit(0), 100);
+          await shutdown(0, "\nStopping Switchboard gracefully...");
         }
       }
     } catch (err) {
       console.error("Error:", err.message);
-      cleanup();
-      process.exit(1);
+      await shutdown(1);
     }
-  }, 3000);
+  })();
 
   function attachServerEvents() {
-    server.on("error", (err) => {
-      console.error("Failed to start server:", err.message);
-      if (err?.code === "EADDRINUSE") stopForPortConflict();
-      else if (!isShuttingDown) tryRestart();
-      else { cleanup(); process.exit(1); }
-    });
-
-    server.on("close", (code) => {
-      if (isShuttingDown || code === 0) {
-        process.exit(code || 0);
+    const observedServer = server;
+    let terminalEventHandled = false;
+    const handleTerminalEvent = (code, signal, error) => {
+      if (terminalEventHandled) return;
+      terminalEventHandled = true;
+      if (isShuttingDown) return;
+      if (error) console.error("Failed to start server:", error.message);
+      if (error?.code === "EADDRINUSE" || isPortConflict()) {
+        void stopForPortConflict();
         return;
       }
-      if (isPortConflict()) {
-        stopForPortConflict();
+      if (code === 0 && !signal) {
+        console.log("\nServer stopped cleanly; shutting down the launcher.");
+        void shutdown(0);
         return;
       }
-      tryRestart(code);
+      tryRestart(code, signal);
+    };
+
+    observedServer.on("error", (err) => {
+      handleTerminalEvent(null, null, err);
     });
-  }
 
-  let mitmResetDone = false;
+    observedServer.on("close", (code, signal) => {
+      handleTerminalEvent(code, signal, null);
+    });
+  }
 
   function isPortConflict() {
     return crashLog.some((line) => /EADDRINUSE|address already in use|listen .*already in use/i.test(line));
   }
 
-  function stopForPortConflict() {
+  async function stopForPortConflict() {
     if (isShuttingDown) return;
-    isShuttingDown = true;
-    console.error(`\n❌ Port ${port} is already in use. Stop the other listener or choose a different port.`);
-    cleanup();
-    process.exit(1);
+    const listeners = findListeningPids(port).filter((pid) => pid !== server?.pid);
+    console.error(`\nPort ${port} is already in use${listeners.length ? ` (PID: ${listeners.join(", ")})` : ""}.`);
+    console.error(`Run "${commandFor("status")}" or choose a different port.`);
+    await shutdown(1);
   }
 
-  function tryRestart(code) {
+  function tryRestart(code, signal) {
     if (isPortConflict()) {
-      stopForPortConflict();
+      void stopForPortConflict();
       return;
     }
     const aliveMs = Date.now() - serverStartTime;
@@ -832,41 +923,31 @@ function startServer(latestVersion) {
     if (aliveMs >= RESTART_RESET_MS) restartCount = 0;
 
     if (restartCount >= MAX_RESTARTS) {
-      // Already tried MITM reset and still crashing — exit non-zero
-      if (mitmResetDone) {
-        console.error(`\n❌ Server still crashing after MITM reset. Giving up.`);
-        console.error(`   Data directory: ${getAppDataDir()}`);
-        if (crashLog.length) {
-          console.error("\n--- Server crash log ---");
-          crashLog.forEach(l => console.error(l));
-          console.error("--- End crash log ---\n");
-        }
-        cleanup();
-        process.exit(1);
-      }
-      console.error(`\n⚠️  Server crashed ${MAX_RESTARTS} times. Disabling MIT and restarting...`);
-      if (!disableMitm()) {
-        console.error("❌ Could not disable MIT in the database — refusing to restart into the same crash.");
-        console.error(`   Data directory: ${getAppDataDir()}`);
-        process.exit(1);
+      console.error(`\nServer crashed ${MAX_RESTARTS} times. Giving up without changing your settings.`);
+      console.error(`Data directory: ${getAppDataDir()}`);
+      console.error(`Retry with server logs: ${commandFor()} --log`);
+      if (crashLog.length) {
+        console.error("\n--- Server crash log ---");
+        crashLog.forEach(l => console.error(l));
+        console.error("--- End crash log ---\n");
       }
-      mitmResetDone = true;
-      restartCount = 0;
-      server = spawnServer();
-      attachServerEvents();
+      void shutdown(1);
       return;
     }
 
     restartCount++;
     const delay = Math.min(1000 * restartCount, 10000);
-    console.error(`\n⚠️  Server exited (code=${code ?? "unknown"}). Restarting in ${delay / 1000}s... (${restartCount}/${MAX_RESTARTS})`);
+    const reason = signal ? `signal=${signal}` : `code=${code ?? "unknown"}`;
+    console.error(`\nServer exited (${reason}). Restarting in ${delay / 1000}s... (${restartCount}/${MAX_RESTARTS})`);
     if (crashLog.length) {
       console.error("\n--- Server crash log ---");
       crashLog.forEach(l => console.error(l));
       console.error("--- End crash log ---\n");
     }
 
-    setTimeout(() => {
+    restartTimer = setTimeout(() => {
+      restartTimer = null;
+      if (isShuttingDown) return;
       server = spawnServer();
       attachServerEvents();
     }, delay);