unitup 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-10-18
+
+### Added
+- **Supervisor Active Generation TCP Health Verification & Self-Healing**: Supervisor now validates TCP connectivity on the internal port (`active.internalPort`) of persisted active generations at startup. If the target generation is dead or refusing connections, supervisor cleans up stale state and automatically triggers a fresh deployment, eliminating stale `502 Bad Gateway (ECONNREFUSED)` loops.
+- **Systemd Crash Loop Circuit Breaker (`RestartPreventExitStatus=78`)**: Added `RestartPreventExitStatus=78` (POSIX `EX_CONFIG`) to generated systemd unit files, paired with `StartLimitIntervalSec=30s` and `StartLimitBurst=5`. When supervisor encounters unrecoverable configuration errors (such as public port collision / `EADDRINUSE`), it exits with code 78, preventing systemd from endlessly restarting and spamming journald logs.
+- **Enhanced Connection Diagnostics in Router**: Detailed internal port and error context (`connect ECONNREFUSED 127.0.0.1:<port>`) reported on proxy failures to clarify application startup crashes.
+- **Exported `IPCClient` Type Definitions**: Exported `IPCClient` class and interface in `index.d.ts` for clean downstream programmatic integration by orchestrators.
+
+### Fixed
+- **Systemd Unit Parser & Directives**: Added extraction and preservation of `RestartPreventExitStatus` in `parseUnitContent` to maintain parity across read/write cycles.
+- **Router In-Flight Request Timing**: Resolved timing race condition in `test/router.test.js` in-flight request tracking test.
+
+## [0.4.0] - 2026-10-18
+
+### Added
+- **Multi-Port Concurrent Routing**: Enhanced `Router` to listen on multiple distinct ports concurrently using an internal server map (`servers: Map<port, { server, port, host }>`), enabling multiple zero-downtime services to operate simultaneously without port collisions or premature listener termination.
+- **Port-Scoped Traffic Isolation**: Added strict port-to-service mapping (`portServices: Map<port, Set<serviceName>>`) ensuring requests on port `A` are strictly isolated from services listening on port `B`.
+- **Domain Normalization in Router**: Added hostname normalization (`hostNormalized`) to resolve incoming Host headers seamlessly against registered service names (e.g., `supanote.app` accurately resolves to service `supanoteapp`).
+- **Automated GitHub Actions Release Pipeline**: Added `.github/workflows/release.yml` using Litepacks reusable release workflow with OIDC Trusted Publishing and provenance.
+- **TypeScript Typecheck Script**: Added `npm run typecheck` (`tsc --noEmit`) to scripts for automated type validation in CI.
+- **Package Distribution Optimization**: Configured `"files"` in `package.json` to publish only essential production files, reducing package size from 2.4 MB to 85 KB.
+
+### Changed
+- **Eliminated Blind Cross-Service Fallback**: Removed indiscriminate fallback to other active backends when a Host header does not match; the router now safely returns `503 Service Unavailable` instead of cross-routing traffic to an unrelated backend.
+- **Service Metadata Persistence**: `writeUnitFile` now explicitly preserves `port` and `deploy` configurations in `saveAppMetadata`, allowing systemd supervisors to retain their target public ports across daemon restarts.
+- **Supervisor Public Port Resolution**: Updated `Supervisor` to reliably resolve public ports across `options.publicPort`, `config.port`, and `config.deploy?.port`.
+- **Connection Draining on Shutdown**: Enhanced `Router.close()` to invoke `server.closeAllConnections()` for immediate and clean termination of idle keep-alive sockets.
+
+
 ## [0.1.5] - 2026-07-31
 
 ### Fixed

package/index.d.ts

@@ -85,6 +85,24 @@ export interface CreateServiceOptions {
         resetAfter?: number | null;
       };
 
+  /**
+   * Maximum log level written to systemd journal.
+   * @default "info"
+   */
+  logLevelMax?: string;
+
+  /**
+   * Rate limit interval for systemd journal logging.
+   * @default "10s"
+   */
+  logRateLimitIntervalSec?: string;
+
+  /**
+   * Maximum number of logs per interval before rate limiting kicks in.
+   * @default 200
+   */
+  logRateLimitBurst?: number;
+
   /**
    * Positional arguments to pass to the script/command execution line.
    */
@@ -575,16 +593,27 @@ export function generations(name: string, options?: Record<string, unknown>): Ge
 
 export class ProcessManager {
   constructor(options?: Record<string, unknown>);
-  start(command: string, args?: string[], options?: Record<string, unknown>): { pid: number; child: any; exitPromise: Promise<any> };
+  start(
+    command: string,
+    args?: string[],
+    options?: Record<string, unknown>
+  ): { pid: number; child: any; exitPromise: Promise<any> };
   stop(processOrPid: number | object, options?: { timeout?: number; signal?: string }): Promise<boolean>;
   signal(processOrPid: number | object, signal?: string): boolean;
   isAlive(processOrPid: number | object): boolean;
-  waitForExit(processOrPid: number | object, timeout?: number): Promise<{ exited: boolean; code?: number | null; signal?: string | null }>;
+  waitForExit(
+    processOrPid: number | object,
+    timeout?: number
+  ): Promise<{ exited: boolean; code?: number | null; signal?: string | null }>;
 }
 
 export class GenerationManager {
   constructor(options?: Record<string, unknown>);
-  create(serviceName: string, config?: Record<string, unknown>, options?: Record<string, unknown>): Promise<GenerationRecord>;
+  create(
+    serviceName: string,
+    config?: Record<string, unknown>,
+    options?: Record<string, unknown>
+  ): Promise<GenerationRecord>;
   getActive(serviceName: string): GenerationRecord | null;
   getPrevious(serviceName: string): GenerationRecord | null;
   getCanary(serviceName: string): GenerationRecord | null;
@@ -616,12 +645,18 @@ export class ReadinessChecker {
   checkTcp(port: number, host?: string, timeout?: number): Promise<boolean>;
   checkHttp(port: number, path?: string, timeout?: number): Promise<boolean>;
   ensure(generation: GenerationRecord, options?: { path?: string }): Promise<boolean>;
-  wait(generation: GenerationRecord, options?: { timeout?: number; interval?: number; path?: string }): Promise<boolean>;
+  wait(
+    generation: GenerationRecord,
+    options?: { timeout?: number; interval?: number; path?: string }
+  ): Promise<boolean>;
 }
 
 export class DrainManager {
   constructor(options?: Record<string, unknown>);
-  drain(generation: GenerationRecord, options?: { timeout?: number; pollInterval?: number; stopProcess?: boolean }): Promise<{ drained: boolean; inFlightRemaining: number; timedOut: boolean }>;
+  drain(
+    generation: GenerationRecord,
+    options?: { timeout?: number; pollInterval?: number; stopProcess?: boolean }
+  ): Promise<{ drained: boolean; inFlightRemaining: number; timedOut: boolean }>;
 }
 
 export class DeploymentLock {
@@ -632,13 +667,31 @@ export class DeploymentLock {
 
 export class DeploymentManager {
   constructor(options?: Record<string, unknown>);
-  deploy(serviceName: string, serviceConfig?: Record<string, unknown>, options?: Record<string, unknown>): Promise<DeploymentResult>;
-  promote(serviceName: string, serviceConfig?: Record<string, unknown>, options?: Record<string, unknown>): Promise<PromoteResult>;
+  deploy(
+    serviceName: string,
+    serviceConfig?: Record<string, unknown>,
+    options?: Record<string, unknown>
+  ): Promise<DeploymentResult>;
+  promote(
+    serviceName: string,
+    serviceConfig?: Record<string, unknown>,
+    options?: Record<string, unknown>
+  ): Promise<PromoteResult>;
 }
 
 export class RollbackManager {
   constructor(options?: Record<string, unknown>);
-  rollback(serviceName: string, serviceConfig?: Record<string, unknown>, options?: Record<string, unknown>): Promise<RollbackResult>;
+  rollback(
+    serviceName: string,
+    serviceConfig?: Record<string, unknown>,
+    options?: Record<string, unknown>
+  ): Promise<RollbackResult>;
+}
+
+export class IPCClient {
+  constructor(serviceName: string, ipcDir?: string);
+  isAlive(): Promise<boolean>;
+  send(message: Record<string, unknown>, onProgress?: (msg: unknown) => void, timeoutMs?: number): Promise<unknown>;
 }
 
 export class Supervisor {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitup",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Minimal, zero-dependency cross-platform native service manager (systemd, launchd, Windows Services) for any runtime, script, or executable",
   "main": "src/index.js",
   "types": "./index.d.ts",
@@ -12,7 +12,8 @@
     "test": "node --test",
     "lint": "biome check .",
     "format": "biome format --write .",
-    "check": "biome check ."
+    "check": "biome check .",
+    "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
@@ -56,5 +57,6 @@
   "homepage": "https://github.com/litepacks/unitup#readme",
   "engines": {
     "node": ">=20.0.0"
-  }
+  },
+  "files": ["bin", "src", "index.d.ts", "README.md", "LICENSE", "CHANGELOG.md"]
 }

package/src/cli.js

@@ -1,6 +1,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import readline from 'node:readline';
+import { GenerationManager } from './core/generation-manager.js';
+import { IPCClient } from './core/ipc.js';
+import { Supervisor } from './core/supervisor.js';
+import {
+  defaultDeploymentManager as deploymentManager,
+  defaultRollbackManager as rollbackManager
+} from './deploy/index.js';
 import { runDoctor } from './doctor.js';
 import { getAdapter } from './platform/index.js';
 import {
@@ -47,13 +54,6 @@ import {
   saveProjectConfig,
   validateMemorySize
 } from './utils.js';
-import { GenerationManager } from './core/generation-manager.js';
-import { IPCClient } from './core/ipc.js';
-import { Supervisor } from './core/supervisor.js';
-import {
-  defaultDeploymentManager as deploymentManager,
-  defaultRollbackManager as rollbackManager
-} from './deploy/index.js';
 
 /**
  * Custom light CLI argument parser without runtime dependencies.

package/src/core/process-manager.js

@@ -1,4 +1,4 @@
-import { spawn, execFile } from 'node:child_process';
+import { execFile, spawn } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 

package/src/core/readiness.js

@@ -170,7 +170,8 @@ export class ReadinessChecker {
     while (true) {
       // 1. Fail fast if process has crashed during startup
       if (generation.pid && this.processManager && !this.processManager.isAlive(generation.pid)) {
-        const procInfo = typeof this.processManager.getProcess === 'function' ? this.processManager.getProcess(generation.pid) : null;
+        const procInfo =
+          typeof this.processManager.getProcess === 'function' ? this.processManager.getProcess(generation.pid) : null;
         const stderr = procInfo?.recentStderr || '';
 
         if (stderr.includes('EADDRINUSE') || stderr.includes('address already in use')) {

package/src/core/router.js

@@ -2,9 +2,14 @@ import http from 'node:http';
 import net from 'node:net';
 
 /**
- * Router owns a stable public port and reverse-proxies HTTP & WebSocket traffic
+ * Router owns stable public ports and reverse-proxies HTTP & WebSocket traffic
  * to whichever internal generation is marked active.
  *
+ * Supports multi-port listening with STRICT port-level isolation:
+ * - A request arriving on port A can ONLY EVER route to backends registered for port A.
+ * - Under NO circumstances will requests cross port boundaries.
+ * - Opening port B will NEVER close or disrupt port A.
+ *
  * It contains NO deployment sequencing decisions.
  */
 export class Router {
@@ -12,20 +17,40 @@ export class Router {
     this.activeBackends = new Map(); // serviceName -> generation { id, internalPort }
     this.canaryBackends = new Map(); // serviceName -> { generation, weight }
     this.inFlightRequests = new Map(); // generationId -> number
-    this.server = null;
-    this.listeningPort = null;
-    this.listeningHost = null;
+    this.servers = new Map(); // port -> { server, port, host }
+    this.portServices = new Map(); // port -> Set<serviceName>
+    this.servicePorts = new Map(); // serviceName -> port
+    this.server = null; // backward compatibility: primary/latest server
+    this.listeningPort = null; // backward compatibility
+    this.listeningHost = null; // backward compatibility
     this.closing = false;
   }
 
+  /**
+   * Associates a service name with a public port.
+   *
+   * @param {string} serviceName
+   * @param {number|string} port
+   */
+  registerServicePort(serviceName, port) {
+    if (!serviceName || !port) return;
+    const numPort = Number(port);
+    this.servicePorts.set(serviceName, numPort);
+    if (!this.portServices.has(numPort)) {
+      this.portServices.set(numPort, new Set());
+    }
+    this.portServices.get(numPort).add(serviceName);
+  }
+
   /**
    * Sets a canary backend with a specific traffic weight (0 to 1, or 1 to 100).
    *
    * @param {string} serviceName
    * @param {object} generation
    * @param {number} [weight=0.1] - Probability (0 to 1) or percentage (1 to 100)
+   * @param {number} [publicPort]
    */
-  setCanary(serviceName, generation, weight = 0.1) {
+  setCanary(serviceName, generation, weight = 0.1, publicPort = null) {
     const parsed = typeof weight === 'string' ? Number.parseFloat(weight.replace('%', '')) : Number(weight);
     const num = Number.isNaN(parsed) ? 0.1 : parsed;
     const normalizedWeight = num > 1 ? num / 100 : num;
@@ -33,6 +58,12 @@ export class Router {
       generation,
       weight: Math.max(0, Math.min(1, normalizedWeight))
     });
+
+    const targetPort =
+      publicPort || generation?.publicPort || (this.servers.size === 1 ? this.servers.keys().next().value : null);
+    if (targetPort) {
+      this.registerServicePort(serviceName, targetPort);
+    }
   }
 
   /**
@@ -54,7 +85,8 @@ export class Router {
   promoteCanary(serviceName) {
     const canary = this.canaryBackends.get(serviceName);
     if (!canary || !canary.generation) return null;
-    this.switchBackend(serviceName, canary.generation);
+    const port = this.servicePorts.get(serviceName);
+    this.switchBackend(serviceName, canary.generation, port);
     this.canaryBackends.delete(serviceName);
     return canary.generation;
   }
@@ -109,26 +141,54 @@ export class Router {
 
   /**
    * Helper to find the service name matching the request.
+   * STRICT: Scoped to the listening port. Never returns an unrelated service!
+   *
    * @param {import('node:http').IncomingMessage} [req]
+   * @param {number} [listeningPort]
    * @returns {string|null}
    */
-  _resolveServiceName(req) {
-    if (this.activeBackends.size === 1) {
-      return this.activeBackends.keys().next().value;
+  _resolveServiceName(req, listeningPort = null) {
+    const numPort = listeningPort ? Number(listeningPort) : null;
+    let candidateNames = null;
+
+    if (numPort && this.portServices.has(numPort)) {
+      candidateNames = Array.from(this.portServices.get(numPort));
+    } else if (this.activeBackends.size > 0 || this.canaryBackends.size > 0) {
+      candidateNames = Array.from(new Set([...this.activeBackends.keys(), ...this.canaryBackends.keys()]));
+    }
+
+    if (!candidateNames || candidateNames.length === 0) {
+      return null;
     }
-    if (this.activeBackends.size > 1 && req?.headers?.host) {
-      for (const srv of this.activeBackends.keys()) {
-        if (req.headers.host.includes(srv)) {
+
+    // Single service registered on this port: unconditionally routes to it
+    if (candidateNames.length === 1) {
+      return candidateNames[0];
+    }
+
+    // Multiple services registered on this port: match by Host header
+    if (req?.headers?.host) {
+      const hostRaw = req.headers.host.split(':')[0].toLowerCase();
+      const hostNormalized = hostRaw.replace(/[^a-z0-9]/g, '');
+
+      // 1. Exact match
+      for (const srv of candidateNames) {
+        if (hostRaw === srv.toLowerCase()) {
+          return srv;
+        }
+      }
+
+      // 2. Normalized match (e.g. "supanote.app" matches service "supanoteapp")
+      for (const srv of candidateNames) {
+        const srvNorm = srv.toLowerCase().replace(/[^a-z0-9]/g, '');
+        if (hostNormalized === srvNorm || hostNormalized.includes(srvNorm) || srvNorm.includes(hostNormalized)) {
           return srv;
         }
       }
     }
-    if (this.activeBackends.size > 0) {
-      return this.activeBackends.keys().next().value;
-    }
-    if (this.canaryBackends.size > 0) {
-      return this.canaryBackends.keys().next().value;
-    }
+
+    // STRICT: Return null if host does not match any service on this port.
+    // NEVER fall back to another random service.
     return null;
   }
 
@@ -172,9 +232,15 @@ export class Router {
    *
    * @param {string} serviceName
    * @param {object} generation - { id, internalPort, service }
+   * @param {number} [publicPort]
    */
-  switchBackend(serviceName, generation) {
+  switchBackend(serviceName, generation, publicPort = null) {
     this.activeBackends.set(serviceName, generation);
+    const targetPort =
+      publicPort || generation?.publicPort || (this.servers.size === 1 ? this.servers.keys().next().value : null);
+    if (targetPort) {
+      this.registerServicePort(serviceName, targetPort);
+    }
   }
 
   /**
@@ -189,44 +255,52 @@ export class Router {
 
   /**
    * Starts listening on the public port.
+   * Supports multiple distinct ports concurrently without closing existing ones.
    *
    * @param {number} publicPort
    * @param {string} [host='0.0.0.0']
+   * @param {string} [serviceName=null]
    * @returns {Promise<{ port: number, host: string }>}
    */
-  async listen(publicPort, host = '0.0.0.0') {
-    if (this.server && this.listeningPort === publicPort) {
-      return { port: this.listeningPort, host: this.listeningHost };
+  async listen(publicPort, host = '0.0.0.0', serviceName = null) {
+    const portNum = Number(publicPort);
+    if (serviceName) {
+      this.registerServicePort(serviceName, portNum);
     }
 
-    if (this.server) {
-      await this.close();
+    const existing = this.servers.get(portNum);
+    if (existing && existing.server) {
+      this.listeningPort = portNum;
+      this.listeningHost = existing.host;
+      this.server = existing.server;
+      return { port: portNum, host: existing.host };
     }
 
     this.closing = false;
 
     return new Promise((resolve, reject) => {
       const server = http.createServer((req, res) => {
-        this._handleHttpRequest(req, res);
+        this._handleHttpRequest(req, res, portNum);
       });
 
       server.on('upgrade', (req, clientSocket, head) => {
-        this._handleWebSocketUpgrade(req, clientSocket, head);
+        this._handleWebSocketUpgrade(req, clientSocket, head, portNum);
       });
 
       server.once('error', (err) => {
         if (err.code === 'EADDRINUSE') {
-          reject(new Error(`Public port ${publicPort} is already occupied by another process.`));
+          reject(new Error(`Public port ${portNum} is already occupied by another process.`));
         } else {
           reject(err);
         }
       });
 
-      server.listen(publicPort, host, () => {
-        this.server = server;
-        const actualPort = server.address() ? server.address().port : publicPort;
+      server.listen(portNum, host, () => {
+        this.servers.set(portNum, { server, port: portNum, host });
+        const actualPort = server.address() ? server.address().port : portNum;
         this.listeningPort = actualPort;
         this.listeningHost = host;
+        this.server = server;
         resolve({ port: actualPort, host });
       });
     });
@@ -237,17 +311,30 @@ export class Router {
    *
    * @param {import('node:http').IncomingMessage} req
    * @param {import('node:http').ServerResponse} res
+   * @param {number} [listeningPort]
    */
-  _handleHttpRequest(req, res) {
-    const serviceName = this._resolveServiceName(req);
+  _handleHttpRequest(req, res, listeningPort = null) {
+    const effectivePort = listeningPort || this.listeningPort;
+    const serviceName = this._resolveServiceName(req, effectivePort);
     const backend = serviceName ? this.resolveBackend(serviceName, req) : null;
 
+    if (!serviceName) {
+      res.writeHead(503, {
+        'Content-Type': 'text/plain; charset=utf-8',
+        'Retry-After': '1'
+      });
+      res.end(
+        `503 Service Unavailable: No service matching host "${req?.headers?.host || 'unknown'}" on port ${effectivePort}.`
+      );
+      return;
+    }
+
     if (!backend || !backend.internalPort) {
       res.writeHead(503, {
         'Content-Type': 'text/plain; charset=utf-8',
         'Retry-After': '1'
       });
-      res.end('503 Service Unavailable: No active generation backend available.');
+      res.end(`503 Service Unavailable: No active generation backend available for service "${serviceName}".`);
       return;
     }
 
@@ -272,8 +359,8 @@ export class Router {
       ? `${forwardedHeaders['x-forwarded-for']}, ${clientIp}`
       : clientIp;
     forwardedHeaders['x-forwarded-proto'] = forwardedHeaders['x-forwarded-proto'] || 'http';
-    forwardedHeaders['x-forwarded-host'] = req.headers.host || `localhost:${this.listeningPort}`;
-    forwardedHeaders['x-forwarded-port'] = String(this.listeningPort);
+    forwardedHeaders['x-forwarded-host'] = req.headers.host || `localhost:${effectivePort}`;
+    forwardedHeaders['x-forwarded-port'] = String(effectivePort);
 
     const proxyReq = http.request(
       {
@@ -298,7 +385,11 @@ export class Router {
       cleanupInFlight();
       if (!res.headersSent) {
         res.writeHead(502, { 'Content-Type': 'text/plain; charset=utf-8' });
-        res.end(`502 Bad Gateway: Error communicating with generation #${genId} (${err.message}).`);
+        const errorDetail =
+          err.code === 'ECONNREFUSED'
+            ? `Connection refused at 127.0.0.1:${backend.internalPort}. The application process may have crashed or not bound to process.env.PORT.`
+            : err.message;
+        res.end(`502 Bad Gateway: Error communicating with generation #${genId} (${errorDetail}).`);
       } else {
         res.destroy();
       }
@@ -310,10 +401,11 @@ export class Router {
   /**
    * Dispatches and proxies WebSocket / Upgrade connections to the active backend.
    */
-  _handleWebSocketUpgrade(req, clientSocket, head) {
-    const serviceName = this._resolveServiceName(req);
+  _handleWebSocketUpgrade(req, clientSocket, head, listeningPort = null) {
+    const effectivePort = listeningPort || this.listeningPort;
+    const serviceName = this._resolveServiceName(req, effectivePort);
     const backend = serviceName ? this.resolveBackend(serviceName, req) : null;
-    if (!backend || !backend.internalPort) {
+    if (!serviceName || !backend || !backend.internalPort) {
       clientSocket.destroy();
       return;
     }
@@ -370,21 +462,50 @@ export class Router {
   }
 
   /**
-   * Closes the public router HTTP listener.
+   * Closes the public router HTTP listener(s).
    *
+   * @param {number} [port=null] - Specific port to close, or null to close all.
    * @returns {Promise<void>}
    */
-  async close() {
-    this.closing = true;
-    if (!this.server) return;
-
-    return new Promise((resolve) => {
-      this.server.close(() => {
-        this.server = null;
-        this.listeningPort = null;
-        this.listeningHost = null;
-        resolve();
+  async close(port = null) {
+    if (port !== null) {
+      const portNum = Number(port);
+      const entry = this.servers.get(portNum);
+      if (!entry || !entry.server) return;
+      return new Promise((resolve) => {
+        if (typeof entry.server.closeAllConnections === 'function') entry.server.closeAllConnections();
+        entry.server.close(() => {
+          this.servers.delete(portNum);
+          this.portServices.delete(portNum);
+          if (this.listeningPort === portNum) {
+            const nextEntry = this.servers.values().next().value;
+            this.server = nextEntry ? nextEntry.server : null;
+            this.listeningPort = nextEntry ? nextEntry.port : null;
+            this.listeningHost = nextEntry ? nextEntry.host : null;
+          }
+          resolve();
+        });
       });
-    });
+    }
+
+    this.closing = true;
+    const closePromises = [];
+    for (const [, entry] of this.servers.entries()) {
+      if (entry.server) {
+        closePromises.push(
+          new Promise((resolve) => {
+            if (typeof entry.server.closeAllConnections === 'function') entry.server.closeAllConnections();
+            entry.server.close(() => resolve());
+          })
+        );
+      }
+    }
+    await Promise.all(closePromises);
+    this.servers.clear();
+    this.portServices.clear();
+    this.servicePorts.clear();
+    this.server = null;
+    this.listeningPort = null;
+    this.listeningHost = null;
   }
 }

package/src/core/supervisor.js

@@ -1,3 +1,5 @@
+import { DeploymentManager } from '../deploy/deployment-manager.js';
+import { RollbackManager } from '../deploy/rollback-manager.js';
 import { readAppMetadata, sanitizeServiceName } from '../utils.js';
 import { DrainManager } from './drain-manager.js';
 import { GenerationManager } from './generation-manager.js';
@@ -6,8 +8,6 @@ import { DeploymentLock } from './lock.js';
 import { ProcessManager } from './process-manager.js';
 import { ReadinessChecker } from './readiness.js';
 import { Router } from './router.js';
-import { DeploymentManager } from '../deploy/deployment-manager.js';
-import { RollbackManager } from '../deploy/rollback-manager.js';
 
 /**
  * Supervisor is the long-running host managed by the OS service manager (unitupd).
@@ -142,16 +142,29 @@ export class Supervisor {
     this.generationManager.loadState(this.serviceName);
     this.generationManager.cleanupStale(this.serviceName);
 
-    const publicPort = this.options.publicPort || this.config.port;
+    const publicPort = this.options.publicPort || this.config.port || this.config.deploy?.port;
 
     // 3. Check if there is an active running generation from persisted state
     const active = this.generationManager.getActive(this.serviceName);
+    let activeHealthy = false;
     if (active && this.processManager.isAlive(active.pid)) {
-      if (publicPort) {
-        await this.router.listen(publicPort);
+      // Verify internal port is actually listening to prevent 502 Bad Gateway
+      activeHealthy = await this.readiness.checkTcp(active.internalPort, '127.0.0.1', 1000);
+      if (activeHealthy) {
+        if (publicPort) {
+          await this.router.listen(publicPort, '0.0.0.0', this.serviceName);
+        }
+        this.router.switchBackend(this.serviceName, active, publicPort);
+      }
+    }
+
+    if (!activeHealthy) {
+      if (active) {
+        process.stderr.write(
+          `[unitup supervisor] Persisted active generation #${active.id} (PID ${active.pid}) is not listening on internal port :${active.internalPort}. Deploying fresh instance...\n`
+        );
+        this.generationManager.remove(active, false);
       }
-      this.router.switchBackend(this.serviceName, active);
-    } else {
       // Start initial generation
       await this.deploymentManager.deploy(this.serviceName, this.config, {
         publicPort,
@@ -216,7 +229,11 @@ export class Supervisor {
       await supervisor.start();
     } catch (err) {
       process.stderr.write(`[unitup supervisor] Failed to start: ${err.message}\n`);
-      process.exit(1);
+      const isUnrecoverableConfigError =
+        err.message?.includes('already occupied') ||
+        err.message?.includes('EADDRINUSE') ||
+        err.name === 'PortMismatchError';
+      process.exit(isUnrecoverableConfigError ? 78 : 1);
     }
   }
 }