switchboard-router 0.9.9 → 0.9.11

package/cli.js

@@ -602,7 +602,7 @@ async function showInterfaceMenu(latestVersion, { trayAvailable = true } = {}) {
   const { selectMenu } = require("./src/cli/utils/input");
   const { clearScreen } = require("./src/cli/utils/display");
   const { getEndpoint } = require("./src/cli/utils/endpoint");
-  const { buildInterfaceMenuItems } = require("./src/cli/interfaceMenu");
+  const { buildInterfaceMenuItems, mapInterfaceSelection } = require("./src/cli/interfaceMenu");
 
   clearScreen();
 
@@ -626,11 +626,11 @@ async function showInterfaceMenu(latestVersion, { trayAvailable = true } = {}) {
   });
 
   const selected = await selectMenu(`Choose Interface (v${pkg.version})`, menuItems, 0, subtitle);
-  return menuItems[selected]?.action || "exit";
+  return mapInterfaceSelection(menuItems, selected);
 }
 
-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"],
@@ -687,8 +692,16 @@ function startServer(latestVersion) {
   const stopHealthWatchdog = startHealthWatchdog({
     port,
     hostname: getProbeHost(),
+    onHealthy: () => {
+      everHealthy = true;
+      if (!isShuttingDown && server?.pid) writeOwnedProcessState(server.pid);
+    },
     onUnhealthy: async () => {
-      if (isShuttingDown || watchdogRestarting || !server?.pid) return;
+      // 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);
@@ -697,8 +710,15 @@ function startServer(latestVersion) {
       try {
         const terminated = await processTools.terminatePid(unhealthyServer.pid, { timeoutMs: 2500, processGroup: true });
         if (!terminated || isShuttingDown || server !== unhealthyServer) return;
-        server = spawnServer();
-        attachServerEvents();
+        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;
       }
@@ -716,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) { }
@@ -779,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}...`);
@@ -795,6 +821,7 @@ function startServer(latestVersion) {
         }
         return;
       }
+      everHealthy = true;
       const trayReady = await initTrayIcon();
       if (trayReady) {
         console.log("\nSwitchboard is ready in the system tray.");
@@ -823,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".`);
@@ -832,7 +860,9 @@ function startServer(latestVersion) {
       while (true) {
         const choice = await showInterfaceMenu(latestVersion, { trayAvailable: trayReady });
 
-        if (choice === "update") {
+        if (choice === "back") {
+          continue;
+        } else if (choice === "update") {
           const { clearScreen } = require("./src/cli/utils/display");
           clearScreen();
           console.log(`\n⬆  Update v${pkg.version} → v${latestVersion}\n`);
@@ -848,7 +878,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");
@@ -872,6 +902,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})`);
@@ -948,11 +981,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) {
@@ -963,15 +1001,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(() => {
@@ -982,5 +1024,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.9",
+  "version": "0.9.11",
   "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/commands/xaiVideo.js

@@ -18,6 +18,7 @@ const DEFAULT_HOST = "127.0.0.1";
 const DEFAULT_MODEL = "xai/grok-imagine-video";
 const DEFAULT_TIMEOUT_SEC = 600;
 const DEFAULT_POLL_INTERVAL_MS = 5000;
+const DEFAULT_REQUEST_TIMEOUT_SEC = 30;
 
 const TERMINAL_STATUSES = new Set(["done", "failed", "completed", "error", "expired", "cancelled"]);
 const FAILED_STATUSES = new Set(["failed", "error", "expired", "cancelled"]);
@@ -37,6 +38,8 @@ Options:
   --resolution <res>      480p | 720p | 1080p
   --image <path-or-url>   Image input for image-to-video
   --timeout <seconds>     Max wait for the job (default: ${DEFAULT_TIMEOUT_SEC})
+  --request-timeout <seconds> Per-request gateway timeout (default: ${DEFAULT_REQUEST_TIMEOUT_SEC})
+  --force               Overwrite the output file if it exists
   --port <port>           Gateway port (default: ${DEFAULT_PORT})
   --host <host>           Gateway host (default: ${DEFAULT_HOST})
   --api-key <key>         Switchboard API key (or env SWITCHBOARD_API_KEY)
@@ -47,19 +50,29 @@ function sanitizeText(text) {
   return String(text ?? "").replace(/Bearer\s+[A-Za-z0-9._~+/=-]{8,}/gi, "Bearer [redacted]");
 }
 
+function requireValue(argv, i, flag) {
+  const value = argv[i + 1];
+  if (value === undefined || value.startsWith("-")) {
+    throw new Error(`${flag} requires a value`);
+  }
+  return value;
+}
+
 function parseArgs(argv) {
   const opts = {
     model: DEFAULT_MODEL,
     output: "video.mp4",
     timeoutSec: DEFAULT_TIMEOUT_SEC,
+    requestTimeoutMs: DEFAULT_REQUEST_TIMEOUT_SEC * 1000,
     port: DEFAULT_PORT,
     host: DEFAULT_HOST,
     apiKey: process.env.SWITCHBOARD_API_KEY || null,
     pollIntervalMs: DEFAULT_POLL_INTERVAL_MS,
+    force: false,
   };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    const next = () => argv[++i];
+    const next = (flag = a) => { const v = requireValue(argv, i, flag); i++; return v; };
     if (a === "--prompt") opts.prompt = next();
     else if (a === "--output" || a === "-o") opts.output = next();
     else if (a === "--model") opts.model = next();
@@ -68,6 +81,8 @@ function parseArgs(argv) {
     else if (a === "--resolution") opts.resolution = next();
     else if (a === "--image") opts.image = next();
     else if (a === "--timeout") opts.timeoutSec = parseInt(next(), 10) || DEFAULT_TIMEOUT_SEC;
+    else if (a === "--request-timeout") opts.requestTimeoutMs = (parseInt(next(), 10) || DEFAULT_REQUEST_TIMEOUT_SEC) * 1000;
+    else if (a === "--force") opts.force = true;
     else if (a === "--port" || a === "-p") opts.port = parseInt(next(), 10) || DEFAULT_PORT;
     else if (a === "--host" || a === "-H") opts.host = next() || DEFAULT_HOST;
     else if (a === "--api-key") opts.apiKey = next();
@@ -90,7 +105,7 @@ function imageInputToUrl(input) {
 }
 
 /** Minimal JSON request against the local gateway. Returns { status, headers, body }. */
-function gatewayRequest({ host, port, apiKey, method, reqPath, body, signal }) {
+function gatewayRequest({ host, port, apiKey, method, reqPath, body, signal, timeoutMs = DEFAULT_REQUEST_TIMEOUT_SEC * 1000 }) {
   return new Promise((resolve, reject) => {
     const payload = body ? JSON.stringify(body) : null;
     const headers = { Accept: "application/json" };
@@ -100,7 +115,7 @@ function gatewayRequest({ host, port, apiKey, method, reqPath, body, signal }) {
     }
     if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
 
-    const req = http.request({ hostname: host, port, path: reqPath, method, headers, signal }, (res) => {
+    const req = http.request({ hostname: host, port, path: reqPath, method, headers, signal, timeout: timeoutMs }, (res) => {
       let data = "";
       res.on("data", (c) => (data += c));
       res.on("end", () => {
@@ -109,6 +124,7 @@ function gatewayRequest({ host, port, apiKey, method, reqPath, body, signal }) {
         resolve({ status: res.statusCode, headers: res.headers, body: parsed, raw: data });
       });
     });
+    req.on("timeout", () => req.destroy(new Error("gateway request timed out")));
     req.on("error", reject);
     if (payload) req.write(payload);
     req.end();
@@ -125,7 +141,7 @@ const sleep = (ms, signal) =>
  * Poll GET /v1/videos/{id} until a terminal status or deadline.
  * @returns {Promise<object>} final poll body (status done) — throws on failed/timeout.
  */
-async function pollUntilDone({ host, port, apiKey, requestId, connectionId, timeoutSec, pollIntervalMs, signal, onProgress }) {
+async function pollUntilDone({ host, port, apiKey, requestId, connectionId, timeoutSec, pollIntervalMs, signal, onProgress, timeoutMs }) {
   const deadline = Date.now() + timeoutSec * 1000;
   while (true) {
     if (signal?.aborted) throw new Error("aborted");
@@ -133,7 +149,7 @@ async function pollUntilDone({ host, port, apiKey, requestId, connectionId, time
       throw new Error(`Timed out after ${timeoutSec}s waiting for video job ${requestId}`);
     }
 
-    const res = await gatewayRequestWithConnection({ host, port, apiKey, requestId, connectionId, signal });
+    const res = await gatewayRequestWithConnection({ host, port, apiKey, requestId, connectionId, signal, timeoutMs });
     if (res.status === 200 && res.body) {
       const status = String(res.body.status || "").toLowerCase();
       onProgress?.(status || "pending", res.body.progress);
@@ -149,13 +165,13 @@ async function pollUntilDone({ host, port, apiKey, requestId, connectionId, time
   }
 }
 
-function gatewayRequestWithConnection({ host, port, apiKey, requestId, connectionId, signal }) {
+function gatewayRequestWithConnection({ host, port, apiKey, requestId, connectionId, signal, timeoutMs = DEFAULT_REQUEST_TIMEOUT_SEC * 1000 }) {
   return new Promise((resolve, reject) => {
     const headers = { Accept: "application/json" };
     if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
     if (connectionId) headers["x-connection-id"] = connectionId;
     const req = http.request(
-      { hostname: host, port, path: `/v1/videos/${encodeURIComponent(requestId)}`, method: "GET", headers, signal },
+      { hostname: host, port, path: `/v1/videos/${encodeURIComponent(requestId)}`, method: "GET", headers, signal, timeout: timeoutMs },
       (res) => {
         let data = "";
         res.on("data", (c) => (data += c));
@@ -166,6 +182,7 @@ function gatewayRequestWithConnection({ host, port, apiKey, requestId, connectio
         });
       }
     );
+    req.on("timeout", () => req.destroy(new Error("gateway request timed out")));
     req.on("error", reject);
     req.end();
   });
@@ -224,6 +241,10 @@ async function run(argv) {
     console.log(HELP);
     return 1;
   }
+  if (!opts.force && fs.existsSync(opts.output)) {
+    console.error(`❌ Output file already exists: ${opts.output} (use --force to overwrite)`);
+    return 1;
+  }
 
   const controller = new AbortController();
   const partPath = `${opts.output}.part`;
@@ -246,6 +267,7 @@ async function run(argv) {
     const create = await gatewayRequest({
       host: opts.host, port: opts.port, apiKey: opts.apiKey,
       method: "POST", reqPath: "/v1/videos/generations", body, signal: controller.signal,
+      timeoutMs: opts.requestTimeoutMs,
     });
 
     if (create.status !== 200 || !create.body?.request_id) {
@@ -266,6 +288,7 @@ async function run(argv) {
       host: opts.host, port: opts.port, apiKey: opts.apiKey,
       requestId, connectionId,
       timeoutSec: opts.timeoutSec, pollIntervalMs: opts.pollIntervalMs,
+      timeoutMs: opts.requestTimeoutMs,
       signal: controller.signal,
       onProgress: (status, progress) => {
         const line = `⏳ ${status}${Number.isFinite(progress) ? ` ${progress}%` : ""}`;
@@ -297,4 +320,4 @@ async function run(argv) {
   }
 }
 
-module.exports = { run, parseArgs, pollUntilDone, downloadToFile, imageInputToUrl, sanitizeText };
+module.exports = { run, parseArgs, pollUntilDone, downloadToFile, imageInputToUrl, sanitizeText, gatewayRequest, gatewayRequestWithConnection, DEFAULT_REQUEST_TIMEOUT_SEC };

package/src/cli/interfaceMenu.js

@@ -29,4 +29,15 @@ async function ensureTrayReady(trayReady, initTrayIcon) {
   return Boolean(await initTrayIcon());
 }
 
-module.exports = { buildInterfaceMenuItems, ensureTrayReady };
+/**
+ * Map a selectMenu() index to a menu action. ESC / non-TTY resolves -1 and
+ * out-of-range indexes are treated as "back" (re-show the menu) — never as
+ * "exit", so dismissing the menu cannot shut down a healthy gateway.
+ */
+function mapInterfaceSelection(menuItems, selected) {
+  if (!Array.isArray(menuItems)) return "back";
+  if (!Number.isInteger(selected) || selected < 0 || selected >= menuItems.length) return "back";
+  return menuItems[selected]?.action || "back";
+}
+
+module.exports = { buildInterfaceMenuItems, ensureTrayReady, mapInterfaceSelection };

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) {
@@ -176,6 +177,16 @@ async function terminatePid(pid, { timeoutMs = 2000, processGroup = false } = {}
   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) => {
@@ -187,14 +198,49 @@ function observeChildExit(child, onTerminal) {
   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,
 };