switchboard-router 0.9.8 → 0.9.10

package/cli.js

@@ -9,8 +9,8 @@ const { openBrowser: openBrowserWithoutShell } = require("./src/shared/openBrows
 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");
+const { findListeningPids, observeChildExit } = processTools;
+const { probeSwitchboard, probeTcp, startHealthWatchdog, waitForSwitchboard } = require("./src/cli/serverStatus");
 
 // Subcommands (`switchboard xai video …`) run against an already-running
 // gateway and skip the launcher flow (no arg parsing, no server spawn).
@@ -629,8 +629,8 @@ async function showInterfaceMenu(latestVersion, { trayAvailable = true } = {}) {
   return menuItems[selected]?.action || "exit";
 }
 
-const MAX_RESTARTS = 2;
-const RESTART_RESET_MS = 30000; // Reset counter if alive > 30s
+
+const RESTART_RESET_MS = 30000;
 
 function startServer(latestVersion) {
   const displayHost = getDisplayHost();
@@ -641,15 +641,20 @@ function startServer(latestVersion) {
     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;
+  let consecutiveCrashes = 0;
+  let everHealthy = false;
   let serverStartTime = Date.now();
 
   const CRASH_LOG_LINES = 50;
   let crashLog = [];
+  let lastPrintedCrashLog = "";
 
   function spawnServer() {
     serverStartTime = Date.now();
     crashLog = [];
+    // A restarted child must prove itself healthy again before it earns
+    // unbounded restarts.
+    everHealthy = false;
     const child = spawn(RUNTIME, ["--max-old-space-size=6144", serverPath], {
       cwd: standaloneDir,
       stdio: ["ignore", "pipe", "pipe"],
@@ -683,6 +688,42 @@ function startServer(latestVersion) {
   let isShuttingDown = false;
   let shutdownPromise = null;
   let restartTimer = null;
+  let watchdogRestarting = false;
+  const stopHealthWatchdog = startHealthWatchdog({
+    port,
+    hostname: getProbeHost(),
+    onHealthy: () => {
+      everHealthy = true;
+      if (!isShuttingDown && server?.pid) writeOwnedProcessState(server.pid);
+    },
+    onUnhealthy: async () => {
+      // A child that already exited belongs to the crash-restart path (its
+      // respawn timer is pending); signalling its PID could hit an unrelated
+      // process if the OS reused it, so leave it alone without touching
+      // restartTimer.
+      if (isShuttingDown || watchdogRestarting || !processTools.childIsLive(server)) return;
+      watchdogRestarting = true;
+      const unhealthyServer = server;
+      clearTimeout(restartTimer);
+      restartTimer = null;
+      console.error("\nServer health checks failed repeatedly; restarting the owned server process.");
+      try {
+        const terminated = await processTools.terminatePid(unhealthyServer.pid, { timeoutMs: 2500, processGroup: true });
+        if (!terminated || isShuttingDown || server !== unhealthyServer) return;
+        try {
+          server = spawnServer();
+          attachServerEvents();
+        } catch (error) {
+          // The watchdog swallows callback errors, so a failed respawn must
+          // exit here instead of leaving a launcher with no server.
+          console.error("Failed to restart server:", error.message);
+          void shutdown(1);
+        }
+      } finally {
+        watchdogRestarting = false;
+      }
+    },
+  });
 
   async function cleanup() {
     if (isCleaningUp) return;
@@ -695,9 +736,12 @@ function startServer(latestVersion) {
       } catch (e) { }
       killProxyByPidFile();
       killTunnelByPidFile();
-      const serverCleanup = server?.pid
+      // An exited child is never signalled (its PID may be reused), but its
+      // process group can still hold grandchildren (MCP stdio bridges, MITM
+      // proxy) that must not outlive the launcher.
+      const serverCleanup = processTools.childIsLive(server)
         ? processTools.terminatePid(server.pid, { timeoutMs: 2500, processGroup: true })
-        : Promise.resolve(true);
+        : processTools.terminateOrphanedGroup(server?.pid, { timeoutMs: 2500 });
       const [, serverResult] = await Promise.allSettled([trayCleanup, serverCleanup]);
       if (serverResult.status === "fulfilled" && serverResult.value === true) clearOwnedProcessState();
     } catch (e) { }
@@ -707,6 +751,7 @@ function startServer(latestVersion) {
     if (shutdownPromise) return shutdownPromise;
     isShuttingDown = true;
     if (restartTimer) clearTimeout(restartTimer);
+    stopHealthWatchdog();
     if (message) console.log(message);
     shutdownPromise = cleanup().finally(() => process.exit(exitCode));
     return shutdownPromise;
@@ -757,6 +802,9 @@ function startServer(latestVersion) {
     // Ignore SIGHUP so macOS terminal close doesn't kill the background tray process
     process.removeAllListeners("SIGHUP");
     process.on("SIGHUP", () => {});
+    // The terminal may close while we keep running; a later console write to
+    // the dead pty would wedge the process, so fail those writes safely.
+    require("./src/cli/utils/display").detachTerminalOutput();
 
     console.log(`\n🚀 ${pkg.name} v${pkg.version}`);
     console.log(`Starting server at http://${displayHost}:${port}...`);
@@ -773,6 +821,7 @@ function startServer(latestVersion) {
         }
         return;
       }
+      everHealthy = true;
       const trayReady = await initTrayIcon();
       if (trayReady) {
         console.log("\nSwitchboard is ready in the system tray.");
@@ -801,6 +850,7 @@ function startServer(latestVersion) {
       }
       return;
     }
+    everHealthy = true;
     let trayReady = await initTrayIcon();
     if (!trayReady) {
       console.warn(`Tray icon unavailable. You can stop safely with Ctrl+C or "${APP_NAME} stop".`);
@@ -826,7 +876,7 @@ 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, { networkExposed: isNetworkExposed() });
+          await startTerminalUI(port, { networkExposed: isNetworkExposed(), host: getProbeHost() });
           // Loop continues, show menu again
         } else if (choice === "hide") {
           const { clearScreen } = require("./src/cli/utils/display");
@@ -850,6 +900,9 @@ function startServer(latestVersion) {
             // it outside the login session so NSStatusItem silently fails.
             process.removeAllListeners("SIGHUP");
             process.on("SIGHUP", () => {});
+            // The user may now close this terminal; detach output first so a
+            // later console write to the dead pty cannot wedge the launcher.
+            require("./src/cli/utils/display").detachTerminalOutput();
 
             console.log(`\n⏳ Switching to tray mode... (icon already visible in menu bar)`);
             console.log(`🔔 Switchboard is running in tray (PID: ${process.pid})`);
@@ -892,11 +945,8 @@ function startServer(latestVersion) {
 
   function attachServerEvents() {
     const observedServer = server;
-    let terminalEventHandled = false;
-    const handleTerminalEvent = (code, signal, error) => {
-      if (terminalEventHandled) return;
-      terminalEventHandled = true;
-      if (isShuttingDown) return;
+    observeChildExit(observedServer, (code, signal, error) => {
+      if (isShuttingDown || watchdogRestarting || observedServer !== server) return;
       if (error) console.error("Failed to start server:", error.message);
       if (error?.code === "EADDRINUSE" || isPortConflict()) {
         void stopForPortConflict();
@@ -908,14 +958,6 @@ function startServer(latestVersion) {
         return;
       }
       tryRestart(code, signal);
-    };
-
-    observedServer.on("error", (err) => {
-      handleTerminalEvent(null, null, err);
-    });
-
-    observedServer.on("close", (code, signal) => {
-      handleTerminalEvent(code, signal, null);
     });
   }
 
@@ -937,11 +979,16 @@ function startServer(latestVersion) {
       return;
     }
     const aliveMs = Date.now() - serverStartTime;
-    // Reset counter if last run was stable
-    if (aliveMs >= RESTART_RESET_MS) restartCount = 0;
+    // Stable runs reset backoff. Repeated crashes keep retrying at a bounded
+    // cadence so a transient runtime fault never leaves the gateway dead.
+    if (aliveMs >= RESTART_RESET_MS) {
+      consecutiveCrashes = 0;
+      lastPrintedCrashLog = "";
+    }
 
-    if (restartCount >= MAX_RESTARTS) {
-      console.error(`\nServer crashed ${MAX_RESTARTS} times. Giving up without changing your settings.`);
+    consecutiveCrashes++;
+    if (processTools.shouldAbandonRestarts({ consecutiveCrashes, everHealthy })) {
+      console.error(`\nServer crashed ${consecutiveCrashes} times without ever becoming healthy. Giving up without changing your settings.`);
       console.error(`Data directory: ${getAppDataDir()}`);
       console.error(`Retry with server logs: ${commandFor()} --log`);
       if (crashLog.length) {
@@ -952,15 +999,19 @@ function startServer(latestVersion) {
       void shutdown(1);
       return;
     }
-
-    restartCount++;
-    const delay = Math.min(1000 * restartCount, 10000);
+    const delay = processTools.nextRestartDelay(consecutiveCrashes - 1);
     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");
+    console.error(`\nServer exited (${reason}). Restarting in ${delay / 1000}s... (attempt ${consecutiveCrashes})`);
+    const logText = crashLog.join("\n");
+    if (processTools.shouldPrintCrashLog(consecutiveCrashes, crashLog, lastPrintedCrashLog)) {
+      if (crashLog.length) {
+        console.error("\n--- Server crash log ---");
+        crashLog.forEach(l => console.error(l));
+        console.error("--- End crash log ---\n");
+      }
+      lastPrintedCrashLog = logText;
+    } else if (consecutiveCrashes === 11 && logText) {
+      console.error(`suppressing repeated crash log; run \`${commandFor()} --log\` for full output`);
     }
 
     restartTimer = setTimeout(() => {
@@ -971,5 +1022,6 @@ function startServer(latestVersion) {
     }, delay);
   }
 
+
   attachServerEvents();
 }

package/hooks/trayRuntime.js

@@ -2,14 +2,19 @@
 // Uses platform-specific optionalDependencies (esbuild/swc pattern).
 // Each platform has its own npm package containing only that architecture's binary.
 // Falls back to downloading from GitHub releases if optionalDeps are missing.
+const crypto = require("crypto");
 const fs = require("fs");
 const path = require("path");
 const https = require("https");
 const zlib = require("zlib");
+const { getDataDir } = require("../src/shared/dataDir");
 
 const BINARY_NAME = "switchboard-tray";
 const TRAY_VERSION = "1.0.0";
 const GITHUB_REPO = "Vijay-Duke/switchboard-router";
+// Upper bound for any single registry response body we buffer in memory.
+const TARBALL_MAX_BYTES = 32 * 1024 * 1024;
+const METADATA_MAX_BYTES = 1024 * 1024;
 
 // Platform → package name mapping
 const PLATFORM_PACKAGES = {
@@ -48,13 +53,10 @@ function resolveBinaryFromPackage() {
 }
 
 /**
- * Fallback: check if the binary was downloaded by postinstall into ~/.switchboard/runtime/bin/
+ * Fallback: check if the binary was downloaded by postinstall into <DATA_DIR>/runtime/bin/
  */
 function resolveBinaryFromCache() {
-  const cacheDir = path.join(
-    process.env.SWITCHBOARD_DATA_DIR || path.join(require("os").homedir(), ".switchboard"),
-    "runtime", "bin"
-  );
+  const cacheDir = path.join(getDataDir(), "runtime", "bin");
   const binPath = path.join(cacheDir, BINARY_NAME);
   if (fs.existsSync(binPath)) {
     return binPath;
@@ -63,17 +65,50 @@ function resolveBinaryFromCache() {
 }
 
 /**
- * Download the tray binary from GitHub releases as a last resort.
- * Stores it in ~/.switchboard/runtime/bin/
+ * Fetch the registry-recorded sha512 integrity for the platform tarball.
+ * Returns null when the metadata is missing or unusable (fail closed).
+ */
+async function fetchTarballIntegrity(pkg) {
+  const metaUrl = `https://registry.npmjs.org/${pkg}/${TRAY_VERSION}`;
+  const body = await module.exports.httpGet(metaUrl, { maxBytes: METADATA_MAX_BYTES });
+  let meta;
+  try {
+    meta = JSON.parse(body.toString("utf8"));
+  } catch {
+    return null;
+  }
+  const integrity = meta && meta.dist && meta.dist.integrity;
+  if (typeof integrity !== "string" || !integrity.startsWith("sha512-")) return null;
+  return integrity;
+}
+
+/**
+ * Verify the downloaded tarball against the registry-recorded integrity
+ * (`sha512-<base64>`). Throws on mismatch — the bytes must never be executed.
+ */
+function verifyTarballIntegrity(tarball, integrity) {
+  let expected;
+  try {
+    expected = Buffer.from(integrity.slice("sha512-".length), "base64");
+  } catch {
+    throw new Error("tray tarball has an unparseable integrity value");
+  }
+  const actual = crypto.createHash("sha512").update(tarball).digest();
+  if (expected.length !== actual.length || !crypto.timingSafeEqual(expected, actual)) {
+    throw new Error("tray tarball integrity mismatch; refusing to install");
+  }
+}
+
+/**
+ * Download the tray binary from the npm registry as a last resort.
+ * Stores it in <DATA_DIR>/runtime/bin/. The tarball is verified against the
+ * registry metadata integrity before anything is written or executed.
  */
 async function downloadBinaryFallback({ silent = false } = {}) {
   const pkg = getPlatformPackage();
   if (!pkg) return null;
 
-  const cacheDir = path.join(
-    process.env.SWITCHBOARD_DATA_DIR || path.join(require("os").homedir(), ".switchboard"),
-    "runtime", "bin"
-  );
+  const cacheDir = path.join(getDataDir(), "runtime", "bin");
   fs.mkdirSync(cacheDir, { recursive: true });
   const destPath = path.join(cacheDir, BINARY_NAME);
 
@@ -82,7 +117,13 @@ async function downloadBinaryFallback({ silent = false } = {}) {
   if (!silent) console.log(`⏳ Downloading tray binary from npm (${pkg})...`);
 
   try {
-    const tarball = await httpGet(tarballUrl);
+    const integrity = await fetchTarballIntegrity(pkg);
+    if (!integrity) {
+      if (!silent) console.warn("⚠️  Tray metadata has no usable integrity; refusing download");
+      return null;
+    }
+    const tarball = await module.exports.httpGet(tarballUrl, { maxBytes: TARBALL_MAX_BYTES });
+    verifyTarballIntegrity(tarball, integrity);
     const extracted = extractFileFromTarball(zlib.gunzipSync(tarball), `package/bin/${BINARY_NAME}`);
     if (!extracted) {
       if (!silent) console.warn("⚠️  Failed to extract tray binary from tarball");
@@ -97,18 +138,32 @@ async function downloadBinaryFallback({ silent = false } = {}) {
   }
 }
 
-function httpGet(url) {
+function httpGet(url, { maxBytes = TARBALL_MAX_BYTES } = {}) {
   return new Promise((resolve, reject) => {
     https.get(url, (res) => {
       if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-        return httpGet(res.headers.location).then(resolve, reject);
+        return module.exports.httpGet(res.headers.location, { maxBytes }).then(resolve, reject);
       }
       if (res.statusCode < 200 || res.statusCode >= 300) {
         return reject(new Error(`HTTP ${res.statusCode}`));
       }
       const chunks = [];
-      res.on("data", (c) => chunks.push(c));
-      res.on("end", () => resolve(Buffer.concat(chunks)));
+      let size = 0;
+      let rejected = false;
+      res.on("data", (c) => {
+        if (rejected) return;
+        size += c.length;
+        if (size > maxBytes) {
+          rejected = true;
+          try { res.destroy(); } catch { /* best effort */ }
+          reject(new Error(`response exceeds ${maxBytes} bytes`));
+          return;
+        }
+        chunks.push(c);
+      });
+      res.on("end", () => {
+        if (!rejected) resolve(Buffer.concat(chunks));
+      });
       res.on("error", reject);
     }).on("error", reject);
   });
@@ -179,5 +234,5 @@ function ensureTrayRuntime({ silent = false } = {}) {
   return { systray: false, needsDownload: true };
 }
 
-module.exports = { ensureTrayRuntime, getTrayBinPath, downloadBinaryFallback, getPlatformPackage };
+module.exports = { ensureTrayRuntime, getTrayBinPath, downloadBinaryFallback, getPlatformPackage, httpGet };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchboard-router",
-  "version": "0.9.8",
+  "version": "0.9.10",
   "description": "Switchboard CLI — local AI routing gateway (install: npm i -g switchboard-router; run: switchboard)",
   "bin": {
     "switchboard": "./cli.js",

package/src/cli/api/client.js

@@ -50,10 +50,14 @@ function loadCliSecret() {
 }
 
 function getCliToken() {
-  if (cachedCliToken !== null) return cachedCliToken;
+  if (cachedCliToken) return cachedCliToken;
+  // Never cache an empty token: the long-lived launcher probes before the
+  // server has written machine-id, and machineIdSync can fail (e.g. no
+  // /usr/sbin on PATH under launchd). Retry until the file exists.
   const raw = loadRawMachineId();
+  if (!raw) return "";
   const secret = loadCliSecret();
-  cachedCliToken = raw ? crypto.createHash("sha256").update(raw + CLI_TOKEN_SALT + secret).digest("hex").substring(0, 16) : "";
+  cachedCliToken = crypto.createHash("sha256").update(raw + CLI_TOKEN_SALT + secret).digest("hex").substring(0, 16);
   return cachedCliToken;
 }
 
@@ -481,7 +485,9 @@ async function disableTunnel() {
 
 module.exports = {
   configure,
-  
+  getCliToken,
+  CLI_TOKEN_HEADER,
+
   // Providers
   getProviders,
   getProviderById,

package/src/cli/cliOptions.js

@@ -102,6 +102,7 @@ function formatHelp({ version = "unknown", defaultPort = DEFAULT_PORT, defaultHo
 Usage:
   switchboard [start] [options]   Start Switchboard (default)
   switchboard status [options]   Show server, version, PID, and ownership status
+                                 Exit codes: 0 running, 1 port conflict, 3 not running
   switchboard stop [options]     Stop the owned Switchboard instance gracefully
   switchboard restart [options]  Gracefully stop, then start Switchboard
   switchboard xai video [options]   Generate a Grok Imagine video (MP4)
@@ -129,7 +130,6 @@ Examples:
   switchboard restart --port ${defaultPort}
   switchboard xai video --prompt "a neon city" --output video.mp4
   switchboard stop
-  switchboard xai video --prompt "a neon city" --output video.mp4
 `;
 }
 

package/src/cli/processManager.js

@@ -3,7 +3,8 @@ const path = require("path");
 const { execFileSync, execSync } = require("child_process");
 
 function normalizePath(value) {
-  try { return path.resolve(value); } catch { return ""; }
+  try { return fs.realpathSync(path.resolve(value)); }
+  catch { try { return path.resolve(value); } catch { return ""; } }
 }
 
 function tokenizeCommand(command) {
@@ -171,16 +172,75 @@ async function terminatePid(pid, { timeoutMs = 2000, processGroup = false } = {}
       process.kill(unixTarget, "SIGKILL");
     }
   } catch { /* best effort */ }
+  const killDeadline = Date.now() + Math.min(timeoutMs, 1000);
+  while (targetIsAlive() && Date.now() < killDeadline) await sleep(25);
   return !targetIsAlive();
 }
 
+// After a detached child has exited, its process group may still hold
+// grandchildren. Sweep the group only while the leader PID itself is gone: a
+// live PID means the OS reused it, and that process's group is not ours.
+async function terminateOrphanedGroup(pid, { timeoutMs = 2000 } = {}) {
+  const numericPid = Number(pid);
+  if (process.platform === "win32" || !Number.isInteger(numericPid) || numericPid <= 1) return true;
+  if (isPidAlive(numericPid) || !isPidAlive(-numericPid)) return true;
+  return terminatePid(numericPid, { timeoutMs, processGroup: true });
+}
+
+function observeChildExit(child, onTerminal) {
+  let handled = false;
+  const finish = (code, signal, error) => {
+    if (handled) return;
+    handled = true;
+    onTerminal(code, signal, error);
+  };
+  child.once("error", (error) => finish(null, null, error));
+  child.once("exit", (code, signal) => finish(code, signal, null));
+}
+
+function nextRestartDelay(attempt) {
+  const exponent = Math.min(Math.max(Number(attempt) || 0, 0), 5);
+  return Math.min(1000 * (2 ** exponent), 30000);
+}
+
+// Give up on deterministic boot failures: a child that never served a healthy
+// probe after maxBootFailures consecutive crashes will never recover by
+// retrying. Once a child has been healthy, restarts stay unbounded.
+function shouldAbandonRestarts({ consecutiveCrashes, everHealthy, maxBootFailures = 5 } = {}) {
+  return !everHealthy && Number(consecutiveCrashes) >= Number(maxBootFailures);
+}
+
+// True only for a child that the OS may still deliver signals to. A crashed
+// child keeps its pid property after exit, so signalling it risks hitting an
+// unrelated process if the OS has reused the PID.
+function childIsLive(child) {
+  return !!child?.pid && child.exitCode === null && child.signalCode === null;
+}
+
+// Echo the crash log on the first attempt of a backoff cycle and whenever it
+// changes; after 10 consecutive crashes the launcher keeps restarting at the
+// 30 s cap but stays quiet (the log is still available via --log).
+function shouldPrintCrashLog(attempt, log, lastPrinted) {
+  if (Number(attempt) > 10) return false;
+  const text = Array.isArray(log) ? log.join("\n") : String(log ?? "");
+  if (!text) return false;
+  if (Number(attempt) <= 1) return true;
+  return text !== String(lastPrinted ?? "");
+}
+
 module.exports = {
   acquireLifecycleLock,
+  childIsLive,
   findListeningPids,
   getProcessCommand,
   getProcessCwd,
   isPidAlive,
+  observeChildExit,
+  nextRestartDelay,
+  shouldAbandonRestarts,
+  shouldPrintCrashLog,
   matchesRecordedProcess,
   processMatchesRecordedPath,
+  terminateOrphanedGroup,
   terminatePid,
 };

package/src/cli/serverStatus.js

@@ -3,6 +3,11 @@ const net = require("net");
 const MAX_RESPONSE_BYTES = 64 * 1024;
 
 function requestJson({ hostname = "127.0.0.1", port, path, timeoutMs = 1000 }) {
+  // Lazily required so the data-dir resolution (and its tests) can point
+  // DATA_DIR at a temp dir before this module is first used. The CLI token
+  // lets probes authenticate against local-only routes from any peer, which
+  // keeps health and version probes working on explicit LAN binds.
+  const { CLI_TOKEN_HEADER, getCliToken } = require("./api/client");
   return new Promise((resolve) => {
     let settled = false;
     const finish = (value) => {
@@ -15,7 +20,7 @@ function requestJson({ hostname = "127.0.0.1", port, path, timeoutMs = 1000 }) {
       port,
       path,
       method: "GET",
-      headers: { Accept: "application/json" },
+      headers: { Accept: "application/json", [CLI_TOKEN_HEADER]: getCliToken() },
     }, (res) => {
       let body = "";
       res.setEncoding("utf8");
@@ -61,14 +66,18 @@ function probeTcp(port, timeoutMs = 1000, hostname = "127.0.0.1") {
   });
 }
 
+async function probeHealth(port, timeoutMs = 1000, hostname = "127.0.0.1") {
+  const response = await requestJson({ hostname, port, path: "/api/health", timeoutMs });
+  return response?.statusCode === 200 && response?.body?.ok === true;
+}
+
 async function probeSwitchboard(port, timeoutMs = 1000, hostname = "127.0.0.1") {
   const response = await requestJson({ hostname, port, path: "/api/mgmt/v1/version", timeoutMs });
   const data = response?.body?.data;
   if (response?.statusCode === 200 && data?.name === "switchboard-app") return data;
 
   // Compatibility with older bundles that predate the management version API.
-  const health = await requestJson({ hostname, port, path: "/api/health", timeoutMs });
-  if (health?.statusCode === 200 && health?.body?.ok === true) {
+  if (await probeHealth(port, timeoutMs, hostname)) {
     return { name: "switchboard-app", version: null, startedAt: null, legacyHealth: true };
   }
   return null;
@@ -87,4 +96,57 @@ async function waitForSwitchboard(port, { timeoutMs = 20000, intervalMs = 250, h
   return null;
 }
 
-module.exports = { probeSwitchboard, probeTcp, waitForSwitchboard };
+function startHealthWatchdog({
+  port,
+  hostname = "127.0.0.1",
+  graceMs = 60_000,
+  intervalMs = 10_000,
+  timeoutMs = 2_000,
+  maxFailures = 3,
+  probe = probeHealth,
+  onUnhealthy,
+  onHealthy,
+} = {}) {
+  let stopped = false;
+  let timer = null;
+  let failures = 0;
+
+  const tick = async () => {
+    if (stopped) return;
+    try {
+      const status = await probe(port, timeoutMs, hostname).catch(() => null);
+      if (status) {
+        failures = 0;
+        try {
+          await onHealthy?.();
+        } catch (error) {
+          console.error("[watchdog] onHealthy failed:", error?.message || error);
+        }
+      } else failures++;
+
+      if (failures >= maxFailures) {
+        failures = 0;
+        try {
+          await onUnhealthy?.();
+        } catch (error) {
+          console.error("[watchdog] onUnhealthy failed:", error?.message || error);
+        }
+        if (stopped) return;
+      }
+    } catch (error) {
+      // A probe that throws synchronously must not become an unhandled
+      // rejection (the launcher would treat it as fatal).
+      console.error("[watchdog] probe failed:", error?.message || error);
+    } finally {
+      if (!stopped) timer = setTimeout(tick, intervalMs);
+    }
+  };
+
+  timer = setTimeout(tick, graceMs);
+  return () => {
+    stopped = true;
+    clearTimeout(timer);
+  };
+}
+
+module.exports = { probeHealth, probeSwitchboard, probeTcp, startHealthWatchdog, waitForSwitchboard };

package/src/cli/terminalUI.js

@@ -52,10 +52,13 @@ function getHeader(port, networkExposed) {
 /**
  * Start Terminal UI
  * @param {number} port - Server port number
+ * @param {Object} [options] - UI options
+ * @param {boolean} [options.networkExposed] - Whether the bind is reachable from the LAN
+ * @param {string} [options.host] - Probe/bind host so API requests reach a specific-IP bind
  */
-async function startTerminalUI(port, { networkExposed = false } = {}) {
+async function startTerminalUI(port, { networkExposed = false, host } = {}) {
   // Configure API client
-  api.configure({ port });
+  api.configure(host ? { port, host } : { port });
 
   const basePath = ["Switchboard"];