@noego/app 0.0.16 → 0.0.18

package/cjs/client.cjs

@@ -0,0 +1,35 @@
+'use strict';
+
+// CJS wrapper for ESM client module
+
+let modulePromise = null;
+
+function getModule() {
+  if (!modulePromise) {
+    modulePromise = import('../src/client.js');
+  }
+  return modulePromise;
+}
+
+// Export functions that return promises
+module.exports = {
+  setContext: async (...args) => {
+    const mod = await getModule();
+    return mod.setContext(...args);
+  },
+  boot: async (...args) => {
+    const mod = await getModule();
+    return mod.boot(...args);
+  },
+  clientBoot: async (...args) => {
+    const mod = await getModule();
+    return mod.clientBoot(...args);
+  },
+  clientInit: async (...args) => {
+    const mod = await getModule();
+    return mod.clientInit(...args);
+  },
+  get client() {
+    return getModule().then(mod => mod.client);
+  }
+};

package/cjs/config.cjs

@@ -0,0 +1,24 @@
+'use strict';
+
+// CJS wrapper for ESM config module
+
+let modulePromise = null;
+
+function getModule() {
+  if (!modulePromise) {
+    modulePromise = import('../src/runtime/config.js');
+  }
+  return modulePromise;
+}
+
+// Export functions that return promises
+module.exports = {
+  buildConfig: async (...args) => {
+    const mod = await getModule();
+    return mod.buildConfig(...args);
+  },
+  getConfig: async (...args) => {
+    const mod = await getModule();
+    return mod.getConfig(...args);
+  }
+};

package/cjs/index.cjs

@@ -0,0 +1,54 @@
+'use strict';
+
+// CJS wrapper for ESM module
+// Uses dynamic import to load ESM and caches the result
+
+let modulePromise = null;
+
+function getModule() {
+  if (!modulePromise) {
+    modulePromise = import('../src/index.js');
+  }
+  return modulePromise;
+}
+
+module.exports = new Proxy({}, {
+  get(_, prop) {
+    if (prop === 'then' || prop === 'catch' || prop === 'finally') {
+      return undefined; // Prevent treating as thenable
+    }
+    return async (...args) => {
+      const mod = await getModule();
+      const fn = mod[prop];
+      if (typeof fn === 'function') {
+        return fn(...args);
+      }
+      return fn;
+    };
+  }
+});
+
+// Also export named exports as promises for destructuring
+Object.defineProperties(module.exports, {
+  runCombinedServices: {
+    get() {
+      return async (...args) => {
+        const mod = await getModule();
+        return mod.runCombinedServices(...args);
+      };
+    }
+  },
+  boot: {
+    get() {
+      return async (...args) => {
+        const mod = await getModule();
+        return mod.boot(...args);
+      };
+    }
+  },
+  client: {
+    get() {
+      return getModule().then(mod => mod.client);
+    }
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noego/app",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "description": "Production build tool for Dinner/Forge apps.",
   "type": "module",
   "bin": {
@@ -9,14 +9,17 @@
   },
   "exports": {
     ".": {
-      "import": "./src/index.js"
+      "import": "./src/index.js",
+      "require": "./cjs/index.cjs"
     },
     "./client": {
       "import": "./src/client.js",
+      "require": "./cjs/client.cjs",
       "types": "./types/client.d.ts"
     },
     "./config": {
       "import": "./src/runtime/config.js",
+      "require": "./cjs/config.cjs",
       "types": "./types/config.d.ts"
     }
   },

package/src/commands/dev.js

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { spawn } from 'node:child_process';
+import { spawn, execSync } from 'node:child_process';
 import { createBuildContext } from '../build/context.js';
 import { findConfigFile } from '../runtime/index.js';
 import { loadConfig } from '../runtime/config-loader.js';
@@ -28,6 +28,90 @@ function killProcessTree(pid, signal = 'SIGKILL') {
   }
 }
 
+/**
+ * Recovery utility for EADDRINUSE errors
+ * Uses lsof to detect what process is using a port, kills it, and waits for the port to be free
+ *
+ * @param {number} port - The port to recover
+ * @param {object} logger - Logger instance for output
+ * @returns {boolean} - True if recovery was successful, false otherwise
+ */
+function recoverFromPortInUse(port, logger) {
+  try {
+    logger.warn(`[PORT RECOVERY] Attempting to recover port ${port}...`);
+
+    // Run lsof to find what's using the port
+    let lsofOutput;
+    try {
+      lsofOutput = execSync(`lsof -i :${port}`, { encoding: 'utf-8' });
+    } catch (err) {
+      // lsof returns exit code 1 if no processes found
+      if (err.status === 1) {
+        logger.info(`[PORT RECOVERY] Port ${port} appears to be free (no process found)`);
+        return true;
+      }
+      throw err;
+    }
+
+    // Parse lsof output to extract PIDs
+    // Output format: COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME
+    // Skip header line, extract second column (PID)
+    const lines = lsofOutput.trim().split('\n');
+    const pidsToKill = new Set();
+
+    for (let i = 1; i < lines.length; i++) { // Skip header
+      const columns = lines[i].split(/\s+/);
+      if (columns.length >= 2) {
+        const pid = parseInt(columns[1], 10);
+        if (!isNaN(pid) && pid !== process.pid) { // Don't kill ourselves
+          pidsToKill.add(pid);
+        }
+      }
+    }
+
+    if (pidsToKill.size === 0) {
+      logger.info(`[PORT RECOVERY] No killable processes found on port ${port}`);
+      return true;
+    }
+
+    // Kill each process holding the port
+    for (const pid of pidsToKill) {
+      try {
+        logger.warn(`[PORT RECOVERY] Killing stale process PID ${pid} holding port ${port}`);
+        execSync(`kill -9 ${pid}`, { encoding: 'utf-8' });
+      } catch (killErr) {
+        // Process might already be dead
+        logger.debug(`[PORT RECOVERY] Could not kill PID ${pid}: ${killErr.message}`);
+      }
+    }
+
+    // Brief wait for OS to release the port
+    // execSync is synchronous so we use a simple busy-wait
+    const waitStart = Date.now();
+    const maxWait = 2000; // 2 seconds max
+    while (Date.now() - waitStart < maxWait) {
+      try {
+        // Check if port is now free by running lsof again
+        execSync(`lsof -i :${port}`, { encoding: 'utf-8' });
+        // If lsof succeeds, port is still in use - keep waiting
+        // Small synchronous delay
+        const spinStart = Date.now();
+        while (Date.now() - spinStart < 100) { /* busy wait 100ms */ }
+      } catch {
+        // lsof failed = port is free
+        logger.info(`[PORT RECOVERY] Port ${port} is now free`);
+        return true;
+      }
+    }
+
+    logger.warn(`[PORT RECOVERY] Port ${port} may still be in use after recovery attempt`);
+    return false;
+  } catch (error) {
+    logger.error(`[PORT RECOVERY] Failed to recover port ${port}: ${error.message}`);
+    return false;
+  }
+}
+
 export async function runDev(config) {
   const context = createBuildContext(config);
   const { logger } = context;
@@ -441,6 +525,7 @@ async function runSplitServeWithWatch(context, tsxExecutable, tsxArgs, baseEnv,
 
   // Crash restart tracking
   const MAX_CRASH_RESTARTS = 3;
+  const PORT_RECOVERY_TIMEOUT = 30000; // 30 seconds to wait for port to become free
   const CRASH_RESTART_DELAY = 2000; // 2 seconds between crash restarts
   const STABILITY_THRESHOLD = 30000; // Reset crash counter if running 30+ seconds
   let backendCrashRestarts = 0;
@@ -448,7 +533,27 @@ async function runSplitServeWithWatch(context, tsxExecutable, tsxArgs, baseEnv,
   let backendStartTime = 0;
   let frontendStartTime = 0;
 
-  const startBackend = () => {
+  // Port recovery retry tracking
+  const MAX_PORT_RECOVERY_RETRIES = 3;
+  let backendPortRetries = 0;
+  let frontendPortRetries = 0;
+
+  const startBackend = (retryAfterRecovery = false) => {
+    if (retryAfterRecovery) {
+      backendPortRetries++;
+      if (backendPortRetries > MAX_PORT_RECOVERY_RETRIES) {
+        logger.error(`[BACKEND] Exceeded max port recovery retries (${MAX_PORT_RECOVERY_RETRIES}).`);
+        logger.info(`[BACKEND] Service is down. Waiting for file change to retry...`);
+        backendProc = null;
+        // Don't shutdown - keep file watcher running so a file change can trigger a fresh restart
+        return;
+      }
+      logger.warn(`[BACKEND] Port recovery retry ${backendPortRetries}/${MAX_PORT_RECOVERY_RETRIES}...`);
+    } else {
+      // Reset retry counter on normal start
+      backendPortRetries = 0;
+    }
+
     backendRestartCount++;
     backendStartTime = Date.now();
     logger.info(`🚀 [RESTART #${backendRestartCount}] Starting backend on port ${backendPort}...`);
@@ -458,13 +563,23 @@ async function runSplitServeWithWatch(context, tsxExecutable, tsxArgs, baseEnv,
       NOEGO_PORT: String(backendPort)
     };
 
+    // Capture stderr to differentiate between port errors and boot errors
+    let stderrBuffer = '';
+
     backendProc = spawn(tsxExecutable, tsxArgs, {
       cwd: context.config.rootDir,
       env: backendEnv,
-      stdio: 'inherit',
+      stdio: ['inherit', 'inherit', 'pipe'], // Pipe stderr to capture errors
       detached: false
     });
 
+    // Capture stderr while also logging it to console
+    backendProc.stderr.on('data', (data) => {
+      const text = data.toString();
+      stderrBuffer += text;
+      process.stderr.write(text); // Still show errors to user
+    });
+
     backendProc.on('exit', (code, signal) => {
       if (isShuttingDown) return;
 
@@ -472,19 +587,40 @@ async function runSplitServeWithWatch(context, tsxExecutable, tsxArgs, baseEnv,
       const runDuration = Date.now() - backendStartTime;
       if (runDuration > STABILITY_THRESHOLD) {
         backendCrashRestarts = 0;
+        backendPortRetries = 0; // Also reset port retries on stability
       }
 
+      // Quick exit (< 5 seconds) might be port conflict OR boot error
+      const isQuickExit = runDuration < 5000;
+
+      // Check stderr for EADDRINUSE to determine error type
+      const isPortError = stderrBuffer.includes('EADDRINUSE') ||
+                          stderrBuffer.includes('address already in use') ||
+                          stderrBuffer.includes('listen EADDRINUSE');
+
       if (code !== null && code !== 0) {
-        logger.error(`[BACKEND] Exited with code ${code}, signal ${signal}`);
+        logger.error(`[BACKEND] Exited with code ${code}, signal ${signal}, ran for ${runDuration}ms`);
 
-        // Auto-restart on crash if under limit
+        // Differentiate between port errors and other boot errors
+        if (isQuickExit && !isPortError && stderrBuffer.length > 0) {
+          // Boot error (syntax error, missing module, etc.) - don't retry
+          logger.error(`[BACKEND] Boot error detected (not a port conflict). Not retrying.`);
+          logger.error(`[BACKEND] Fix the error and save a file to trigger a new restart attempt.`);
+          backendProc = null;
+          // Reset crash counter so next file change gets a fresh attempt
+          backendCrashRestarts = 0;
+          backendPortRetries = 0;
+          return;
+        }
+
+        // Auto-restart on crash if under limit (for port errors or runtime crashes)
         if (backendCrashRestarts < MAX_CRASH_RESTARTS) {
           backendCrashRestarts++;
           logger.warn(`[BACKEND] Crash detected. Auto-restart ${backendCrashRestarts}/${MAX_CRASH_RESTARTS}...`);
 
           // Wait for port to be free before restarting (fixes race condition)
           backendProc = null;
-          waitForPortFree(backendPort, 10000, 100).subscribe({
+          waitForPortFree(backendPort, PORT_RECOVERY_TIMEOUT, 100).subscribe({
             next: () => {
               if (!isShuttingDown) {
                 logger.info(`[BACKEND] Port ${backendPort} is free, restarting...`);
@@ -492,25 +628,72 @@ async function runSplitServeWithWatch(context, tsxExecutable, tsxArgs, baseEnv,
               }
             },
             error: (err) => {
-              logger.warn(`[BACKEND] Port wait warning: ${err.message}. Attempting restart anyway...`);
+              logger.warn(`[BACKEND] Port wait timed out: ${err.message}`);
+
+              // Quick exit + port not free + port error = likely EADDRINUSE from stale process
+              if (isQuickExit && isPortError) {
+                logger.warn(`[BACKEND] Port conflict detected - attempting port recovery...`);
+                const recovered = recoverFromPortInUse(backendPort, logger);
+                if (recovered && !isShuttingDown) {
+                  // Wait for OS to fully release the port before retrying
+                  setTimeout(() => {
+                    if (!isShuttingDown) {
+                      startBackend(true); // Mark as recovery retry
+                    }
+                  }, CRASH_RESTART_DELAY);
+                  return;
+                }
+              }
+
+              // Fallback: try restart anyway
               if (!isShuttingDown) {
                 startBackend();
               }
             }
           });
         } else {
-          logger.error(`[BACKEND] Exceeded max crash restarts (${MAX_CRASH_RESTARTS}). Shutting down...`);
-          shutdown('backend-exceeded-restarts', 1, 'backend-crash');
+          logger.error(`[BACKEND] Exceeded max crash restarts (${MAX_CRASH_RESTARTS}).`);
+          logger.info(`[BACKEND] Service is down. Waiting for file change to retry...`);
+          backendProc = null;
+          // Don't shutdown - keep file watcher running so a file change can trigger a fresh restart
         }
       }
     });
 
     backendProc.on('error', (err) => {
       logger.error(`[BACKEND] Spawn error: ${err.message}`);
+
+      // Check if this is an EADDRINUSE-like error at spawn level
+      if (err.code === 'EADDRINUSE' || err.message.includes('EADDRINUSE')) {
+        logger.warn(`[BACKEND] EADDRINUSE detected at spawn - attempting port recovery...`);
+        const recovered = recoverFromPortInUse(backendPort, logger);
+        if (recovered && backendPortRetries < MAX_PORT_RECOVERY_RETRIES && !isShuttingDown) {
+          setTimeout(() => {
+            if (!isShuttingDown) {
+              startBackend(true);
+            }
+          }, CRASH_RESTART_DELAY);
+        }
+      }
     });
   };
 
-  const startFrontend = () => {
+  const startFrontend = (retryAfterRecovery = false) => {
+    if (retryAfterRecovery) {
+      frontendPortRetries++;
+      if (frontendPortRetries > MAX_PORT_RECOVERY_RETRIES) {
+        logger.error(`[FRONTEND] Exceeded max port recovery retries (${MAX_PORT_RECOVERY_RETRIES}).`);
+        logger.info(`[FRONTEND] Service is down. Waiting for file change to retry...`);
+        frontendProc = null;
+        // Don't shutdown - keep file watcher running so a file change can trigger a fresh restart
+        return;
+      }
+      logger.warn(`[FRONTEND] Port recovery retry ${frontendPortRetries}/${MAX_PORT_RECOVERY_RETRIES}...`);
+    } else {
+      // Reset retry counter on normal start
+      frontendPortRetries = 0;
+    }
+
     frontendRestartCount++;
     frontendStartTime = Date.now();
     logger.info(`🚀 [RESTART #${frontendRestartCount}] Starting frontend on port ${frontendPort}...`);
@@ -520,13 +703,23 @@ async function runSplitServeWithWatch(context, tsxExecutable, tsxArgs, baseEnv,
       NOEGO_PORT: String(frontendPort)
     };
 
+    // Capture stderr to differentiate between port errors and boot errors
+    let stderrBuffer = '';
+
     frontendProc = spawn(tsxExecutable, tsxArgs, {
       cwd: context.config.rootDir,
       env: frontendEnv,
-      stdio: 'inherit',
+      stdio: ['inherit', 'inherit', 'pipe'], // Pipe stderr to capture errors
       detached: false
     });
 
+    // Capture stderr while also logging it to console
+    frontendProc.stderr.on('data', (data) => {
+      const text = data.toString();
+      stderrBuffer += text;
+      process.stderr.write(text); // Still show errors to user
+    });
+
     frontendProc.on('exit', (code, signal) => {
       if (isShuttingDown) return;
 
@@ -534,19 +727,40 @@ async function runSplitServeWithWatch(context, tsxExecutable, tsxArgs, baseEnv,
       const runDuration = Date.now() - frontendStartTime;
       if (runDuration > STABILITY_THRESHOLD) {
         frontendCrashRestarts = 0;
+        frontendPortRetries = 0; // Also reset port retries on stability
       }
 
+      // Quick exit (< 5 seconds) might be port conflict OR boot error
+      const isQuickExit = runDuration < 5000;
+
+      // Check stderr for EADDRINUSE to determine error type
+      const isPortError = stderrBuffer.includes('EADDRINUSE') ||
+                          stderrBuffer.includes('address already in use') ||
+                          stderrBuffer.includes('listen EADDRINUSE');
+
       if (code !== null && code !== 0) {
-        logger.error(`[FRONTEND] Exited with code ${code}, signal ${signal}`);
+        logger.error(`[FRONTEND] Exited with code ${code}, signal ${signal}, ran for ${runDuration}ms`);
+
+        // Differentiate between port errors and other boot errors
+        if (isQuickExit && !isPortError && stderrBuffer.length > 0) {
+          // Boot error (syntax error, missing module, etc.) - don't retry
+          logger.error(`[FRONTEND] Boot error detected (not a port conflict). Not retrying.`);
+          logger.error(`[FRONTEND] Fix the error and save a file to trigger a new restart attempt.`);
+          frontendProc = null;
+          // Reset crash counter so next file change gets a fresh attempt
+          frontendCrashRestarts = 0;
+          frontendPortRetries = 0;
+          return;
+        }
 
-        // Auto-restart on crash if under limit
+        // Auto-restart on crash if under limit (for port errors or runtime crashes)
         if (frontendCrashRestarts < MAX_CRASH_RESTARTS) {
           frontendCrashRestarts++;
           logger.warn(`[FRONTEND] Crash detected. Auto-restart ${frontendCrashRestarts}/${MAX_CRASH_RESTARTS}...`);
 
           // Wait for port to be free before restarting (fixes race condition)
           frontendProc = null;
-          waitForPortFree(frontendPort, 10000, 100).subscribe({
+          waitForPortFree(frontendPort, PORT_RECOVERY_TIMEOUT, 100).subscribe({
             next: () => {
               if (!isShuttingDown) {
                 logger.info(`[FRONTEND] Port ${frontendPort} is free, restarting...`);
@@ -554,21 +768,53 @@ async function runSplitServeWithWatch(context, tsxExecutable, tsxArgs, baseEnv,
               }
             },
             error: (err) => {
-              logger.warn(`[FRONTEND] Port wait warning: ${err.message}. Attempting restart anyway...`);
+              logger.warn(`[FRONTEND] Port wait timed out: ${err.message}`);
+
+              // Quick exit + port not free + port error = likely EADDRINUSE from stale process
+              if (isQuickExit && isPortError) {
+                logger.warn(`[FRONTEND] Port conflict detected - attempting port recovery...`);
+                const recovered = recoverFromPortInUse(frontendPort, logger);
+                if (recovered && !isShuttingDown) {
+                  // Wait for OS to fully release the port before retrying
+                  setTimeout(() => {
+                    if (!isShuttingDown) {
+                      startFrontend(true); // Mark as recovery retry
+                    }
+                  }, CRASH_RESTART_DELAY);
+                  return;
+                }
+              }
+
+              // Fallback: try restart anyway
               if (!isShuttingDown) {
                 startFrontend();
               }
             }
           });
         } else {
-          logger.error(`[FRONTEND] Exceeded max crash restarts (${MAX_CRASH_RESTARTS}). Shutting down...`);
-          shutdown('frontend-exceeded-restarts', 1, 'frontend-crash');
+          logger.error(`[FRONTEND] Exceeded max crash restarts (${MAX_CRASH_RESTARTS}).`);
+          logger.info(`[FRONTEND] Service is down. Waiting for file change to retry...`);
+          frontendProc = null;
+          // Don't shutdown - keep file watcher running so a file change can trigger a fresh restart
         }
       }
     });
 
     frontendProc.on('error', (err) => {
       logger.error(`[FRONTEND] Spawn error: ${err.message}`);
+
+      // Check if this is an EADDRINUSE-like error at spawn level
+      if (err.code === 'EADDRINUSE' || err.message.includes('EADDRINUSE')) {
+        logger.warn(`[FRONTEND] EADDRINUSE detected at spawn - attempting port recovery...`);
+        const recovered = recoverFromPortInUse(frontendPort, logger);
+        if (recovered && frontendPortRetries < MAX_PORT_RECOVERY_RETRIES && !isShuttingDown) {
+          setTimeout(() => {
+            if (!isShuttingDown) {
+              startFrontend(true);
+            }
+          }, CRASH_RESTART_DELAY);
+        }
+      }
     });
   };
 
@@ -782,6 +1028,9 @@ async function runSplitServeWithWatch(context, tsxExecutable, tsxArgs, baseEnv,
           // Then start the new backend
           of(undefined).pipe(
             tap(() => {
+              // Reset crash counters - file change gives a fresh start
+              backendCrashRestarts = 0;
+              backendPortRetries = 0;
               startBackend();
               logger.info(`✅ Backend restart complete\n`);
             })
@@ -818,6 +1067,9 @@ async function runSplitServeWithWatch(context, tsxExecutable, tsxArgs, baseEnv,
           // Then start the new frontend
           of(undefined).pipe(
             tap(() => {
+              // Reset crash counters - file change gives a fresh start
+              frontendCrashRestarts = 0;
+              frontendPortRetries = 0;
               startFrontend();
               logger.info(`✅ Frontend restart complete\n`);
             })
@@ -893,6 +1145,12 @@ async function runSplitServeWithWatch(context, tsxExecutable, tsxArgs, baseEnv,
     })
     .on('error', handleWatcherError);
   
+  // Proactive port recovery before initial startup
+  // This handles the case where stale processes from a previous dev session are holding the ports
+  logger.info(`[STARTUP] Checking ports ${backendPort} and ${frontendPort} for stale processes...`);
+  recoverFromPortInUse(backendPort, logger);
+  recoverFromPortInUse(frontendPort, logger);
+
   // Start initial processes
   startBackend();
   startFrontend();

package/src/runtime/runtime.js

@@ -390,10 +390,23 @@ async function runBackendService(config) {
   console.log('[backend] config.dev.backendPort:', config.dev.backendPort);
   console.log('[backend] Using port:', backendPort);
 
-  backendApp.listen(backendPort, '0.0.0.0', () => {
+  const httpServer = http.createServer(backendApp);
+
+  httpServer.on('error', (err) => {
+    if (err.code === 'EADDRINUSE') {
+      console.error(`[ERROR] Port ${backendPort} is already in use (EADDRINUSE)`);
+      console.error(`[ERROR] This likely means a stale process is still running.`);
+      console.error(`[ERROR] The dev server will attempt to recover...`);
+    } else {
+      console.error(`[ERROR] Server error on port ${backendPort}:`, err.message);
+    }
+    process.exit(1);
+  });
+
+  httpServer.listen(backendPort, '0.0.0.0', () => {
     console.log(`Backend server running on http://localhost:${backendPort}`);
   });
-  
+
   return backendApp;
 }
 
@@ -441,6 +454,17 @@ async function runFrontendService(config) {
   console.log('[frontend] config.dev.port:', config.dev.port);
   console.log('[frontend] Using port:', frontendPort);
 
+  httpServer.on('error', (err) => {
+    if (err.code === 'EADDRINUSE') {
+      console.error(`[ERROR] Port ${frontendPort} is already in use (EADDRINUSE)`);
+      console.error(`[ERROR] This likely means a stale process is still running.`);
+      console.error(`[ERROR] The dev server will attempt to recover...`);
+    } else {
+      console.error(`[ERROR] Server error on port ${frontendPort}:`, err.message);
+    }
+    process.exit(1);
+  });
+
   httpServer.listen(frontendPort, '0.0.0.0', () => {
     console.log(`Frontend server running on http://localhost:${frontendPort}`);
   });
@@ -669,6 +693,17 @@ async function runRouterService(config) {
     try { socket?.destroy?.(); } catch {}
   });
 
+  httpServer.on('error', (err) => {
+    if (err.code === 'EADDRINUSE') {
+      console.error(`[ERROR] Port ${routerPort} is already in use (EADDRINUSE)`);
+      console.error(`[ERROR] This likely means a stale process is still running.`);
+      console.error(`[ERROR] The dev server will attempt to recover...`);
+    } else {
+      console.error(`[ERROR] Server error on port ${routerPort}:`, err.message);
+    }
+    process.exit(1);
+  });
+
   httpServer.listen(routerPort, '0.0.0.0', () => {
     console.log(`Router server running on http://localhost:${routerPort}`);
     console.log(`  Proxying to frontend on port ${frontendPort}`);
@@ -724,6 +759,18 @@ export async function runCombinedServices(config, options = {}) {
 
   // Allow PORT env var to override config
   const port = process.env.PORT ? parseInt(process.env.PORT, 10) : (config.dev?.port || 3000);
+
+  httpServer.on('error', (err) => {
+    if (err.code === 'EADDRINUSE') {
+      console.error(`[ERROR] Port ${port} is already in use (EADDRINUSE)`);
+      console.error(`[ERROR] This likely means a stale process is still running.`);
+      console.error(`[ERROR] The dev server will attempt to recover...`);
+    } else {
+      console.error(`[ERROR] Server error on port ${port}:`, err.message);
+    }
+    process.exit(1);
+  });
+
   httpServer.listen(port, '0.0.0.0', () => {
     const services = [];
     if (hasBackend && config.server?.main_abs) services.push('Backend');