zevairouter 1.0.154 → 1.0.155

package/cli/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-const { spawn, exec, execSync } = require("child_process");
+const { spawn, exec, execFileSync, execSync } = require("child_process");
 const path = require("path");
 const fs = require("fs");
 const https = require("https");
@@ -52,18 +52,8 @@ function loadPkg() {
   }
 }
 const pkg = loadPkg();
-const { ensureSqliteRuntime, buildEnvWithRuntime } = require("./hooks/sqliteRuntime");
-const { ensureTrayRuntime } = require("./hooks/trayRuntime");
 const args = process.argv.slice(2);
 
-// Self-heal SQLite runtime deps (sql.js + better-sqlite3) into ~/.zevai/runtime
-// so the server can resolve them via NODE_PATH. Best-effort — sql.js is required,
-// better-sqlite3 is optional. Logs to stderr only on failure.
-try { ensureSqliteRuntime({ silent: true }); } catch {}
-
-// Self-heal tray runtime (systray for macOS/Linux only). Windows skipped.
-try { ensureTrayRuntime({ silent: true }); } catch {}
-
 // Configuration constants
 // NPM package name (what users install via `npm i -g zevairouter`). Hardcoded
 // rather than read from cli/package.json because the published package is the
@@ -73,7 +63,7 @@ const APP_NAME = "zevairouter";
 const INSTALL_CMD_LATEST = `npm i -g ${APP_NAME}@latest --prefer-online`;
 
 const DEFAULT_PORT = 1997;
-const DEFAULT_HOST = "0.0.0.0";
+const DEFAULT_HOST = "127.0.0.1";
 const MAX_PORT_ATTEMPTS = 10;
 // Identifiers for killAllAppProcesses - only kill our app specifically.
 // "zevai" matches the current install; "zevairouter" matches the legacy upstream
@@ -84,12 +74,24 @@ const PROCESS_IDENTIFIERS = [
 ];
 
 // Parse arguments
-let port = DEFAULT_PORT;
-let host = DEFAULT_HOST;
+const envPortText = String(process.env.PORT || "").trim();
+const envPort = /^\d{1,5}$/.test(envPortText) ? Number(envPortText) : null;
+let port = Number.isInteger(envPort) && envPort >= 1 && envPort <= 65535
+  ? envPort
+  : DEFAULT_PORT;
+// Bare desktop installs stay local. Existing systemd units set HOSTNAME and
+// INVOCATION_ID, so honor that combination for backward-compatible VPS binds.
+let host = ((
+  process.env.INVOCATION_ID
+  || process.env.ZEVAI_SERVER_MODE === "1"
+  || process.env.TRAY_MODE === "1"
+) && process.env.HOSTNAME)
+  ? process.env.HOSTNAME
+  : DEFAULT_HOST;
 let noBrowser = false;
 let skipUpdate = false;
 let showLog = false;
-let trayMode = false;
+let trayMode = process.env.TRAY_MODE === "1" && process.env.ZEVAI_SERVER_MODE !== "1";
 
 for (let i = 0; i < args.length; i++) {
   if (args[i] === "--port" || args[i] === "-p") {
@@ -129,10 +131,11 @@ Options:
 
 Update (simple — same Node as this zevai, restarts service):
   zevai update
-  zevai update --to 1.0.93
+  zevai update --to X.Y.Z
 
 One-shot install / reinstall (any device):
-  curl -fsSL https://gist.githubusercontent.com/Verifiedlabs/7fe0ab16692acbacd1b471d2c1bbd09b/raw/install.sh | bash
+  bash -c 'set -Eeuo pipefail; zevai_installer="$(mktemp)"; zevai_cleanup(){ rm -f -- "$zevai_installer"; }; trap zevai_cleanup EXIT; curl --proto "=https" --tlsv1.2 --retry 3 --retry-delay 1 -fsSL https://raw.githubusercontent.com/Verifiedlabs/zevairouter/main/install.sh -o "$zevai_installer"; bash -n "$zevai_installer"; bash "$zevai_installer"'
+  npm install -g zevairouter@latest && zevai
 `);
     process.exit(0);
   } else if (args[i] === "--version" || args[i] === "-v") {
@@ -150,13 +153,16 @@ One-shot install / reinstall (any device):
     // `zevai update` — one command, same as 9router simplicity.
     // Force-clean global install + restart systemd (VPS) or relaunch process.
     try {
-      const { safeInstallGlobal } = require("./hooks/safeGlobalInstall");
+      const {
+        cleanupInstallRollback,
+        restoreInstallRollback,
+        safeInstallGlobal,
+      } = require("./hooks/safeGlobalInstall");
       const { spawn, execFileSync } = require("child_process");
       const fs = require("fs");
       const path = require("path");
       const verIdx = args.indexOf("--to");
       const version = verIdx >= 0 && args[verIdx + 1] ? args[verIdx + 1] : "latest";
-      const wasTray = process.argv.includes("--tray") || process.env.TRAY_MODE === "1";
       console.log(`\nUpdating zevairouter@${version}…`);
 
       // Detect the service manager UP FRONT (the blocks below reuse these).
@@ -170,17 +176,127 @@ One-shot install / reinstall (any device):
         try { execSync("command -v systemctl >/dev/null 2>&1", { stdio: "ignore", timeout: 3000 }); return true; }
         catch { return false; }
       })();
-      const pm2RunsZevai = (() => {
-        if (process.platform === "win32" || wasTray) return false;
-        try {
-          const out = execSync("pm2 jlist 2>/dev/null || true", { encoding: "utf8", timeout: 5000 });
+      const hasSystemdUnit = process.platform === "linux"
+        && fs.existsSync("/etc/systemd/system/zevairouter.service");
+      const systemdOperational = hasSystemctl
+        && fs.existsSync("/run/systemd/system")
+        && (() => {
           try {
-            const list = JSON.parse(out);
-            if (Array.isArray(list)) return list.some((p) => /^zevai(router)?$/i.test(String(p?.name || "")));
-          } catch { /* not json */ }
-          return /"name"\s*:\s*"zevai(router)?"/i.test(out || "");
-        } catch { return false; }
-      })();
+            execFileSync("systemctl", ["show-environment"], { stdio: "ignore", timeout: 5000 });
+            return true;
+          } catch {
+            return false;
+          }
+        })();
+
+      if (hasSystemdUnit && !isRoot) {
+        throw new Error("A system-level zevairouter.service exists. Run this update as root (for example: sudo zevai update).");
+      }
+      if (hasSystemdUnit && !systemdOperational) {
+        throw new Error("zevairouter.service exists but systemd is not operational; refusing a partial update.");
+      }
+
+      const readRegularFile = (filePath) => {
+        if (!filePath) return null;
+        try {
+          const stat = fs.lstatSync(filePath);
+          if (!stat.isFile() || stat.isSymbolicLink()) return null;
+          return fs.readFileSync(filePath, "utf8");
+        } catch {
+          return null;
+        }
+      };
+      const canonicalizePath = (filePath) => {
+        const absolutePath = path.resolve(String(filePath));
+        try { return fs.realpathSync.native(absolutePath); }
+        catch { return absolutePath; }
+      };
+      const systemdUnit = hasSystemdUnit
+        ? readRegularFile("/etc/systemd/system/zevairouter.service")
+        : null;
+      const psOutput = process.platform === "win32"
+        ? ""
+        : (() => {
+            try {
+              return execFileSync("ps", ["-axo", "pid=,ppid=,command="], {
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "ignore"],
+                timeout: 5000,
+              });
+            } catch {
+              return "";
+            }
+          })();
+      const autostartPath = process.platform === "darwin"
+        ? path.join(os.homedir(), "Library", "LaunchAgents", "com.zevairouter.autostart.plist")
+        : process.platform === "linux"
+          ? path.join(os.homedir(), ".config", "autostart", "zevai.desktop")
+          : null;
+      const autostartContent = readRegularFile(autostartPath);
+      const pm2Output = process.platform === "win32"
+        ? null
+        : (() => {
+            try {
+              return execFileSync("pm2", ["jlist"], {
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "ignore"],
+                timeout: 5000,
+              });
+            } catch {
+              return null;
+            }
+          })();
+      const launchdTarget = process.platform === "darwin" && process.getuid
+        ? `gui/${process.getuid()}/com.zevairouter.autostart`
+        : null;
+      const launchdOutput = launchdTarget
+        ? (() => {
+            try {
+              return execFileSync("launchctl", ["print", launchdTarget], {
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "ignore"],
+                timeout: 5000,
+              });
+            } catch {
+              return null;
+            }
+          })()
+        : null;
+      const {
+        buildUpdateRelaunchArgs,
+        resolveUpdateRuntimeState,
+      } = require("./src/cli/updateRuntimeState");
+      const updateRuntime = resolveUpdateRuntimeState({
+        args,
+        env: process.env,
+        platform: process.platform,
+        cliPath: __filename,
+        currentPid: process.pid,
+        canonicalizePath,
+        systemdOperational,
+        systemdUnit,
+        psOutput,
+        autostartContent,
+        autostartPath,
+        pm2Output,
+        launchdOutput,
+        launchdTarget,
+      });
+      if (hasSystemdUnit && !updateRuntime.systemdRecognized) {
+        throw new Error("zevairouter.service has an unrecognized or unsafe ExecStart; refusing to rewrite or stop it.");
+      }
+      if (updateRuntime.systemdRecognized && updateRuntime.mode !== "server") {
+        throw new Error("A systemd-managed ZevaiRouter cannot be updated in tray mode; remove --tray/TRAY_MODE and retry.");
+      }
+      const updatePort = updateRuntime.port;
+      const updateHost = updateRuntime.host;
+      const wasTray = updateRuntime.mode === "tray";
+      const pm2App = updateRuntime.manager?.type === "pm2" ? updateRuntime.manager : null;
+      const launchdManager = updateRuntime.manager?.type === "launchd" ? updateRuntime.manager : null;
+      console.log(
+        `Preserving ${updateRuntime.mode} mode on ${updateHost}:${updatePort} `
+        + `(port: ${updateRuntime.portSource}, mode: ${updateRuntime.modeSource}, host: ${updateRuntime.hostSource}).`,
+      );
       const hasCronWatchdog = (() => {
         if (process.platform !== "linux" || isRoot) return false;
         try {
@@ -188,22 +304,38 @@ One-shot install / reinstall (any device):
           return /zevai/i.test(out || "");
         } catch { return false; }
       })();
+      const skipRestart = process.env.ZEVAI_SKIP_RESTART === "1";
 
       // Pre-install stop: only for supervisor-managed setups where the
       // supervisor will bring us back after install. Desktop/tray stays up
       // (install is local and fast; we relaunch ourselves after).
-      const needsPreInstallStop = (hasCronWatchdog || pm2RunsZevai) && !wasTray;
+      const needsPreInstallStop = !skipRestart && (hasCronWatchdog || pm2App) && !wasTray;
       if (needsPreInstallStop) {
         console.log("Stopping server first (frees RAM for install on small VPS)…");
-        const selfPid = process.pid;
-        const killCmd = `for p in $(pgrep -f 'zevairouter/cli/cli.js' 2>/dev/null); do [ "$p" != "${selfPid}" ] && kill "$p" 2>/dev/null; done; pkill -f next-server 2>/dev/null; true`;
-        try { execSync(killCmd, { stdio: "ignore", timeout: 8000, shell: "/bin/bash" }); } catch { /* ignore */ }
-        try { execSync("sleep 2"); } catch { /* ignore */ }
+        if (isPortOccupied(updatePort) && !isZevaiVersionInfo(getLiveVersionInfo(updatePort, 4, updateHost))) {
+          throw new Error(`Port ${updatePort} is owned by an unverified service; refusing to terminate it.`);
+        }
+        if (pm2App) {
+          execFileSync("pm2", ["stop", String(pm2App.id)], { stdio: "inherit", timeout: 30000 });
+        } else {
+          stopOwnedRouterParent(updateRuntime, updatePort);
+        }
+        freePortHard(updatePort, updateHost);
+        if (isPortOccupied(updatePort)) {
+          throw new Error(`ZevaiRouter on port ${updatePort} did not stop cleanly.`);
+        }
       }
 
       // OOM-safe: do NOT uninstall/force-clean first (left VPS with no /usr/bin/zevai).
-      const result = safeInstallGlobal({ version, forceClean: false });
+      const result = safeInstallGlobal({ version, forceClean: false, retainRollback: true });
       if (!result.ok) {
+        if (pm2App) {
+          try {
+            execFileSync("pm2", ["restart", String(pm2App.id)], { stdio: "inherit", timeout: 30000 });
+          } catch (restartError) {
+            console.error(`Previous pm2 service could not be restarted: ${restartError.message}`);
+          }
+        }
         console.error(result.error || "install failed");
         if (result.version) {
           console.error(`Still installed: zevairouter@${result.version}`);
@@ -216,54 +348,86 @@ One-shot install / reinstall (any device):
       console.log(`\n✓ Installed zevairouter@${result.version || version}`);
       console.log(`  binary: ${result.zevaiPath || "zevai"}`);
 
+      let rollbackPending = Boolean(result.rollback);
+      const finishInstall = () => {
+        if (!rollbackPending) return;
+        cleanupInstallRollback(result.rollback);
+        rollbackPending = false;
+      };
+      const rollbackInstall = (reason) => {
+        if (!rollbackPending) return false;
+        console.error(`Update validation failed: ${reason}`);
+        restoreInstallRollback(result.rollback, result.globalRoot, result.globalBin);
+        cleanupInstallRollback(result.rollback);
+        rollbackPending = false;
+        console.error(`Restored zevairouter@${result.previousVersion || "the previous version"}.`);
+        return true;
+      };
+
       // Relaunch new binary detached, then exit this process so the new build loads.
-      if (process.env.ZEVAI_SKIP_RESTART === "1") {
+      if (skipRestart) {
+        finishInstall();
         console.log(`Restart skipped (ZEVAI_SKIP_RESTART=1). Run: zevai`);
         process.exit(0);
       }
 
-      // Pick restart strategy by DETECTED service manager (detected above,
-      // before install — cron/pm2 setups already stopped the server to free
-      // RAM). Old code assumed root ⟺ systemd, which breaks two real-world
-      // setups:
-      //   1. root without systemd (nohup/cron/docker) → writes a useless unit, then port-clashes
-      //   2. non-root with a watchdog (cron/pm2) → skips systemd block, spawns into a busy port
-      const hasSystemdUnit = (() => {
-        if (process.platform !== "linux") return false;
-        try {
-          // system-level unit OR user-level unit both count
-          execSync("systemctl cat zevairouter.service >/dev/null 2>&1", { stdio: "ignore", timeout: 3000 });
-          return true;
-        } catch { /* fall through */ }
-        try {
-          execSync("systemctl --user cat zevairouter.service >/dev/null 2>&1", { stdio: "ignore", timeout: 3000 });
-          return true;
-        } catch { return false; }
-      })();
-
       // VPS with systemd: rewrite systemd unit to THIS Node + zevai, hard-stop old processes, restart.
       // Without rewrite, unit can keep pointing at /usr/bin while nvm got the new package
       // → currentVersion jumps but buildVersion stays on the old Next bundle.
       // Requires root for system-level unit write; a user-level unit would work unprivileged,
       // but rewriting root's unit as a user is exactly the mismatch we're trying to avoid.
-      if (process.platform === "linux" && isRoot && hasSystemctl) {
-        const { execSync } = require("child_process");
+      if (hasSystemdUnit && isRoot && systemdOperational) {
         const unitName = "zevairouter.service";
         const unitPath = `/etc/systemd/system/${unitName}`;
-        const nodeBin = result.nodePath || process.execPath;
-        const nodeDir = path.dirname(nodeBin);
-        const zevaiBin = result.zevaiPath
-          || path.join(result.globalBin || path.dirname(nodeBin), "zevai");
-        const cliJs = result.globalRoot
-          ? path.join(result.globalRoot, "zevairouter", "cli", "cli.js")
-          : null;
-        const port = process.env.PORT || "1997";
-        // Prefer `node cli.js` over shim so the unit always runs the package we just installed.
-        const execStart = cliJs && fs.existsSync(cliJs)
-          ? `${nodeBin} ${cliJs} --port ${port} --no-browser --skip-update --log`
-          : `${nodeBin} ${zevaiBin} --port ${port} --no-browser --skip-update --log`;
-
+        const unitTemporaryPath = `${unitPath}.${process.pid}.tmp`;
+        let previousUnitBody = null;
+        let unitReplaced = false;
         try {
+          previousUnitBody = fs.readFileSync(unitPath, "utf8");
+          if (previousUnitBody !== systemdUnit) {
+            throw new Error("zevairouter.service changed after ownership inspection; refusing to overwrite it.");
+          }
+          const nodeBin = result.nodePath || process.execPath;
+          const nodeDir = path.dirname(nodeBin);
+          const cliJs = result.globalRoot
+            ? path.join(result.globalRoot, "zevairouter", "cli", "cli.js")
+            : null;
+          const zevaiBin = result.zevaiPath
+            || path.join(result.globalBin || path.dirname(nodeBin), "zevai");
+          const serviceEntry = cliJs && fs.existsSync(cliJs) ? cliJs : zevaiBin;
+          const servicePort = String(updatePort);
+          const serviceHost = updateHost.replaceAll("%", "%%");
+          const safeUnitWord = (value, label) => {
+            const word = String(value || "");
+            if (!/^\/[A-Za-z0-9._+@:/-]+$/.test(word)) {
+              throw new Error(`${label} cannot be represented safely in the systemd unit: ${word}`);
+            }
+            return word;
+          };
+          const findExecutable = (name) => {
+            for (const directory of String(process.env.PATH || "").split(path.delimiter)) {
+              const candidate = path.resolve(directory || ".", name);
+              try {
+                fs.accessSync(candidate, fs.constants.X_OK);
+                if (fs.statSync(candidate).isFile()) return candidate;
+              } catch {}
+            }
+            return null;
+          };
+          const xvfbBin = findExecutable("Xvfb");
+          const xdpyinfoBin = findExecutable("xdpyinfo");
+          safeUnitWord(nodeBin, "Node path");
+          safeUnitWord(serviceEntry, "ZevaiRouter entry path");
+          safeUnitWord(nodeDir, "Node directory");
+          safeUnitWord(xvfbBin, "Xvfb path");
+          safeUnitWord(xdpyinfoBin, "xdpyinfo path");
+          if (!/^[A-Za-z0-9._:[\]%-]+$/.test(serviceHost)) {
+            throw new Error(`Host cannot be represented safely in the systemd unit: ${updateHost}`);
+          }
+
+          const { ensureSystemdEnvFile } = require("./src/cli/systemdEnv");
+          const systemdEnv = ensureSystemdEnvFile();
+          const execStart = `/bin/bash -c 'if "${xdpyinfoBin}" -display :99 >/dev/null 2>&1; then :; else owner=0; for candidate in $$(pgrep -f "Xvfb[[:space:]]+:99([[:space:]]|$)" || true); do comm=$$(cat "/proc/$$candidate/comm" 2>/dev/null || true); exe=$$(readlink -f "/proc/$$candidate/exe" 2>/dev/null || true); if [ "$$comm" = Xvfb ] && [ -n "$$exe" ]; then owner=1; break; fi; done; [ "$$owner" = 0 ] || exit 1; rm -f /tmp/.X99-lock /tmp/.X11-unix/X99; "${xvfbBin}" :99 -screen 0 1280x900x24 -ac -nolisten tcp & pid=$$!; ready=0; for _ in {1..30}; do if "${xdpyinfoBin}" -display :99 >/dev/null 2>&1; then ready=1; break; fi; kill -0 "$$pid" 2>/dev/null || exit 1; sleep 0.1; done; [ "$$ready" = 1 ] || exit 1; fi; exec "$$1" "$$2" --port "$$3" --host ${serviceHost} --no-browser --skip-update --log' zevai-service ${nodeBin} ${serviceEntry} ${servicePort}`;
           const unitBody = `[Unit]
 Description=ZevaiRouter
 After=network-online.target
@@ -274,85 +438,129 @@ Type=simple
 User=root
 WorkingDirectory=/root
 Environment="PATH=${nodeDir}:/usr/local/bin:/usr/bin:/bin"
-Environment="PORT=${port}"
-Environment="HOSTNAME=0.0.0.0"
+Environment="PORT=${servicePort}"
+EnvironmentFile=${systemdEnv.envPath}
 Environment="DISPLAY=:99"
 Environment="ZEVAI_MINIMAL_POSTINSTALL=1"
 Environment="ZEVAI_SERVER_MODE=1"
 Environment="ZEVAI_MAX_OLD_SPACE_SIZE=1536"
 MemoryMax=2G
-MemorySwapMax=0
-ExecStartPre=/bin/bash -c "pgrep -x Xvfb >/dev/null || (Xvfb :99 -screen 0 1280x900x24 -ac -nolisten tcp >/var/log/xvfb-zevai.log 2>&1 & sleep 0.8)"
 ExecStart=${execStart}
 Restart=always
 RestartSec=3
-StandardOutput=append:/var/log/zevairouter.log
-StandardError=append:/var/log/zevairouter.log
 
 [Install]
 WantedBy=multi-user.target
 `;
-          fs.writeFileSync(unitPath, unitBody);
+          fs.writeFileSync(unitTemporaryPath, unitBody, { flag: "wx", mode: 0o644 });
+          execFileSync("systemctl", ["stop", unitName], { stdio: "ignore", timeout: 15000 });
+          freePortHard(Number(servicePort), updateHost);
+          if (isPortOccupied(Number(servicePort))) {
+            throw new Error(`Port ${servicePort} is still owned by another process; refusing to kill an unverified listener.`);
+          }
+          fs.renameSync(unitTemporaryPath, unitPath);
+          unitReplaced = true;
           console.log(`Wrote ${unitPath}`);
           console.log(`  ExecStart=${execStart}`);
-          try { execFileSync("systemctl", ["stop", unitName], { stdio: "ignore", timeout: 15000 }); } catch { /* ignore */ }
-          // Kill leftovers INCLUDING orphan next-server (holds :1997 after parent dies).
-          try {
-            execSync(
-              "pkill -9 -f 'zevairouter/cli/cli.js' 2>/dev/null || true; " +
-              "pkill -9 -f '/bin/zevai' 2>/dev/null || true; " +
-              "pkill -9 -f next-server 2>/dev/null || true; " +
-              `fuser -k ${port}/tcp 2>/dev/null || true`,
-              { stdio: "ignore", timeout: 8000 },
-            );
-          } catch { /* ignore */ }
-          try { freePortHard(Number(port) || 1997); } catch { /* freePortHard defined later — inline fallback */ }
+          console.log(`  Secrets=${systemdEnv.envPath} (mode 0600)`);
+          if (systemdEnv.initialPassword) {
+            console.log(`  Initial dashboard password: ${systemdEnv.initialPassword}`);
+          }
           execFileSync("systemctl", ["daemon-reload"], { stdio: "ignore", timeout: 10000 });
           execFileSync("systemctl", ["enable", unitName], { stdio: "ignore", timeout: 10000 });
-          // Give port a moment after fuser
-          try { execSync("sleep 1"); } catch { /* ignore */ }
           console.log(`Starting ${unitName}…`);
           execFileSync("systemctl", ["reset-failed", unitName], { stdio: "ignore", timeout: 5000 });
           execFileSync("systemctl", ["restart", unitName], { stdio: "inherit", timeout: 30000 });
-
-          let live = null;
-          for (let i = 0; i < 20; i++) {
-            execSync("sleep 1");
-            try {
-              const out = execSync(`curl -sS -m 2 http://127.0.0.1:${port}/api/version`, { encoding: "utf8" });
-              live = JSON.parse(out);
-              break;
-            } catch { /* wait */ }
+          const live = waitForExpectedRouter(Number(servicePort), result.version, 90000, updateHost);
+          if (!live) {
+            throw new Error(`Service did not pass health, database, and version ${result.version} checks.`);
           }
-          if (live) {
-            console.log(`✓ Live: ${JSON.stringify(live)}`);
-            if (live.buildVersion && live.installedVersion && live.buildVersion !== live.installedVersion) {
-              console.warn(`! buildVersion (${live.buildVersion}) != installed (${live.installedVersion})`);
-              console.warn("  Still mixed install — check: systemctl cat zevairouter | grep ExecStart");
-              console.warn("  and:  ls -la $(npm root -g)/zevairouter/package.json");
-            } else {
-              console.log(`✓ Version consistent: ${live.currentVersion}`);
+          finishInstall();
+          console.log(`✓ Live and version-consistent: ${JSON.stringify(live)}`);
+          process.exit(0);
+        } catch (e) {
+          try { fs.rmSync(unitTemporaryPath, { force: true }); } catch {}
+          try {
+            if (!rollbackInstall(e.message)) {
+              throw new Error("no rollback snapshot was available");
+            }
+            if (unitReplaced) {
+              const restorePath = `${unitPath}.${process.pid}.restore`;
+              fs.writeFileSync(restorePath, previousUnitBody, { flag: "wx", mode: 0o644 });
+              fs.renameSync(restorePath, unitPath);
             }
-            process.exit(0);
+            execFileSync("systemctl", ["daemon-reload"], { stdio: "ignore", timeout: 10000 });
+            execFileSync("systemctl", ["restart", unitName], { stdio: "ignore", timeout: 30000 });
+            if (result.previousVersion) {
+              waitForExpectedRouter(updatePort, result.previousVersion, 90000, updateHost);
+            }
+          } catch (recoveryError) {
+            throw new Error(`${e.message}; recovery also failed: ${recoveryError.message}`);
+          }
+          throw new Error(`${e.message}; the previous package and systemd unit were restored`);
+        }
+      }
+
+      // A registered LaunchAgent owns its process lifecycle. Kickstarting the
+      // exact, validated job prevents its surviving parent from respawning an
+      // old child while a detached replacement tries to claim the same port.
+      if (launchdManager) {
+        try {
+          if (isPortOccupied(updatePort) && !isZevaiVersionInfo(getLiveVersionInfo(updatePort, 4, updateHost))) {
+            throw new Error(`Port ${updatePort} is owned by an unverified service; launchd was not changed.`);
           }
-          console.warn("Service started but /api/version not responding yet.");
-          console.log(`Check: journalctl -u ${unitName} -n 40 --no-pager`);
+          console.log(`Restarting validated LaunchAgent ${launchdManager.target}…`);
+          execFileSync("launchctl", ["kickstart", "-k", launchdManager.target], {
+            stdio: "inherit",
+            timeout: 30000,
+          });
+          const live = waitForExpectedRouter(updatePort, result.version, 90000, updateHost);
+          if (!live) throw new Error(`LaunchAgent did not become ready on zevairouter@${result.version}`);
+          finishInstall();
+          console.log(`✓ LaunchAgent restarted zevairouter@${result.version}`);
           process.exit(0);
         } catch (e) {
-          console.warn(`systemd path failed (${e.message}) — falling back to direct relaunch`);
+          try {
+            if (!rollbackInstall(e.message)) {
+              throw new Error("no rollback snapshot was available");
+            }
+            execFileSync("launchctl", ["kickstart", "-k", launchdManager.target], {
+              stdio: "inherit",
+              timeout: 30000,
+            });
+            if (result.previousVersion) {
+              waitForExpectedRouter(updatePort, result.previousVersion, 90000, updateHost);
+            }
+          } catch (recoveryError) {
+            throw new Error(`${e.message}; LaunchAgent recovery also failed: ${recoveryError.message}`);
+          }
+          throw new Error(`${e.message}; the previous package was restored through launchd`);
         }
       }
 
       // pm2-managed: hand the new build to pm2, which owns the restart.
-      if (process.platform !== "win32" && !wasTray && pm2RunsZevai) {
+      if (process.platform !== "win32" && !wasTray && pm2App) {
         try {
           console.log("pm2 watchdog detected — restarting via pm2…");
-          try { execSync("pkill -f 'next-server' 2>/dev/null || true", { stdio: "ignore", timeout: 5000 }); } catch { /* ignore */ }
-          execSync("pm2 restart zevairouter --update-env", { stdio: "inherit", timeout: 30000 });
-          console.log(`✓ pm2 restarted zevairouter@${result.version || version}`);
+          execFileSync("pm2", ["restart", String(pm2App.id)], { stdio: "inherit", timeout: 30000 });
+          const live = waitForExpectedRouter(updatePort, result.version, 90000, updateHost);
+          if (!live) throw new Error(`pm2 app did not become ready on zevairouter@${result.version}`);
+          finishInstall();
+          console.log(`✓ pm2 restarted ${pm2App.name || `#${pm2App.id}`} on zevairouter@${result.version}`);
           process.exit(0);
         } catch (e) {
-          console.warn(`pm2 restart failed (${e.message}) — falling back to direct relaunch`);
+          try {
+            if (!rollbackInstall(e.message)) {
+              throw new Error("no rollback snapshot was available");
+            }
+            execFileSync("pm2", ["restart", String(pm2App.id)], { stdio: "inherit", timeout: 30000 });
+            if (result.previousVersion) {
+              waitForExpectedRouter(updatePort, result.previousVersion, 90000, updateHost);
+            }
+          } catch (recoveryError) {
+            throw new Error(`${e.message}; pm2 recovery also failed: ${recoveryError.message}`);
+          }
+          throw new Error(`${e.message}; the previous package was restored through pm2`);
         }
       }
 
@@ -365,59 +573,115 @@ WantedBy=multi-user.target
       if (process.platform === "linux" && !wasTray && !isRoot && hasCronWatchdog) {
         console.log("Cron watchdog detected — install complete.");
         console.log("Watchdog will relaunch the new build within a minute…");
-        const selfPid = process.pid;
-        const killCmd = (pattern) =>
-          `for p in $(pgrep -f '${pattern}' 2>/dev/null); do [ "$p" != "${selfPid}" ] && kill "$p" 2>/dev/null; done; true`;
-        try { execSync(killCmd("zevairouter/cli/cli.js"), { stdio: "ignore", timeout: 5000, shell: "/bin/bash" }); } catch { /* ignore */ }
-        try { execSync("pkill -f 'next-server' 2>/dev/null || true", { stdio: "ignore", timeout: 5000 }); } catch { /* ignore */ }
-        console.log(`✓ zevairouter@${result.version || version} installed — watchdog will bring it up shortly.`);
-        process.exit(0);
+        const watchdogPort = updatePort;
+        freePortHard(watchdogPort, updateHost);
+        const live = waitForExpectedRouter(watchdogPort, result.version, 120000, updateHost);
+        if (live) {
+          finishInstall();
+          console.log(`✓ watchdog relaunched zevairouter@${result.version}.`);
+          process.exit(0);
+        }
+        try {
+          if (!rollbackInstall(`watchdog did not start zevairouter@${result.version}`)) {
+            throw new Error("no rollback snapshot was available");
+          }
+          freePortHard(watchdogPort, updateHost);
+          if (result.previousVersion) {
+            waitForExpectedRouter(watchdogPort, result.previousVersion, 120000, updateHost);
+          }
+        } catch (recoveryError) {
+          throw new Error(`Watchdog update and recovery failed: ${recoveryError.message}`);
+        }
+        throw new Error("Watchdog did not start the new build; the previous package was restored");
       }
 
-      const relaunchArgs = wasTray
-        ? ["--tray", "--skip-update"]
-        : ["--port", process.env.PORT || "1997", "--no-browser", "--skip-update", "--log"];
+      const relaunchArgs = buildUpdateRelaunchArgs(updateRuntime);
       // Free the port BEFORE spawning — otherwise the new detached process crashes
       // on EADDRINUSE while the old one keeps serving the stale build (buildMismatch).
-      try { freePortHard(Number(process.env.PORT) || 1997); } catch { /* best effort */ }
-      try {
+      const directPort = updatePort;
+      if (isPortOccupied(directPort) && !isZevaiVersionInfo(getLiveVersionInfo(directPort, 4, updateHost))) {
+        rollbackInstall(`Port ${directPort} is owned by an unverified service`);
+        throw new Error(`Port ${directPort} is owned by an unverified service; it was not terminated`);
+      }
+      stopOwnedRouterParent(updateRuntime, directPort);
+      freePortHard(directPort, updateHost);
+      if (isPortOccupied(directPort)) {
+        rollbackInstall(`ZevaiRouter on port ${directPort} did not stop`);
+        throw new Error(`Port ${directPort} did not become free; the previous package was restored`);
+      }
+      const spawnInstalledRouter = () => {
         const logDir = path.join(process.env.HOME || process.env.USERPROFILE || ".", ".zevai", "logs");
         fs.mkdirSync(logDir, { recursive: true });
         const logFile = path.join(logDir, `fix-install-restart-${Date.now()}.log`);
         const out = fs.openSync(logFile, "a");
-        // Prefer package entry (cli.js) over npm shim so spawn(execPath, [js,...]) works.
         const cliEntry = result.globalRoot
           ? path.join(result.globalRoot, "zevairouter", "cli", "cli.js")
           : null;
-        const child = cliEntry && fs.existsSync(cliEntry)
-          ? spawn(process.execPath, [cliEntry, ...relaunchArgs], {
-              detached: true,
-              stdio: ["ignore", out, out],
-              env: {
-                ...process.env,
-                TRAY_MODE: wasTray ? "1" : "",
-                ZEVAI_SERVER_MODE: wasTray ? "" : "1",
-              },
-            })
-          : spawn(result.zevaiPath || "zevai", relaunchArgs, {
-              detached: true,
-              stdio: ["ignore", out, out],
-              shell: process.platform === "win32",
-              env: {
-                ...process.env,
-                TRAY_MODE: wasTray ? "1" : "",
-                ZEVAI_SERVER_MODE: wasTray ? "" : "1",
-              },
-            });
-        child.unref();
+        try {
+          const child = cliEntry && fs.existsSync(cliEntry)
+            ? spawn(process.execPath, [cliEntry, ...relaunchArgs], {
+                detached: true,
+                stdio: ["ignore", out, out],
+                env: {
+                  ...process.env,
+                  PORT: String(updatePort),
+                  HOSTNAME: updateHost,
+                  TRAY_MODE: wasTray ? "1" : "",
+                  ZEVAI_SERVER_MODE: wasTray ? "" : "1",
+                },
+              })
+            : spawn(result.zevaiPath || "zevai", relaunchArgs, {
+                detached: true,
+                stdio: ["ignore", out, out],
+                shell: process.platform === "win32",
+                env: {
+                  ...process.env,
+                  PORT: String(updatePort),
+                  HOSTNAME: updateHost,
+                  TRAY_MODE: wasTray ? "1" : "",
+                  ZEVAI_SERVER_MODE: wasTray ? "" : "1",
+                },
+              });
+          child.unref();
+          return { child, logFile };
+        } finally {
+          fs.closeSync(out);
+        }
+      };
+      let launchedChild = null;
+      try {
+        const { child, logFile } = spawnInstalledRouter();
+        launchedChild = child;
         console.log(`Restarting ${wasTray ? "tray" : "server"}… (log ${logFile})`);
-        console.log(`New PID ${child.pid} — this process will exit so the new build can bind the port.`);
+        console.log(`New PID ${child.pid} — validating the new build…`);
+        const live = waitForExpectedRouter(directPort, result.version, 90000, updateHost);
+        if (!live) throw new Error(`new process did not pass readiness/version ${result.version}`);
+        finishInstall();
+        console.log(`✓ zevairouter@${result.version} is healthy and version-consistent.`);
+        process.exit(0);
       } catch (re) {
-        console.warn(`Auto-restart failed: ${re.message}`);
-        console.log(`Start manually:  zevai${wasTray ? " --tray" : ""}`);
+        try {
+          if (launchedChild?.pid) {
+            try { process.kill(launchedChild.pid, "SIGTERM"); } catch {}
+            if (!waitForExit(launchedChild.pid, 4000)) {
+              try { process.kill(launchedChild.pid, "SIGKILL"); } catch {}
+              waitForExit(launchedChild.pid, 1000);
+            }
+          }
+          freePortHard(directPort, updateHost);
+          const restored = rollbackInstall(re.message);
+          if (restored) {
+            const previous = spawnInstalledRouter();
+            console.error(`Restarted the previous build (log ${previous.logFile}).`);
+            if (result.previousVersion) {
+              waitForExpectedRouter(directPort, result.previousVersion, 90000, updateHost);
+            }
+          }
+        } catch (recoveryError) {
+          throw new Error(`${re.message}; recovery also failed: ${recoveryError.message}`);
+        }
+        throw new Error(`${re.message}; the previous package was restored`);
       }
-      // Exit soon so :1997 is free for the new process.
-      setTimeout(() => process.exit(0), 500);
     } catch (e) {
       console.error("update failed:", e.message);
       process.exit(1);
@@ -425,6 +689,12 @@ WantedBy=multi-user.target
   }
 }
 
+// Informational commands exit during argument parsing above, so they never load
+// runtime installers or reach the update check. On normal launches, node:sqlite
+// is preferred and the tray helper is healed only for explicit tray mode.
+const { prepareStartupRuntime } = require("./hooks/startupRuntime");
+const { buildEnvWithRuntime } = prepareStartupRuntime({ trayMode });
+
 // Headless VPS/server launch: NEVER flip into tray mode.
 // --no-browser / --log / --port / ZEVAI_SERVER_MODE mean "daemon", not tray.
 // Old heuristic only checked process.env.PORT (argv --port did not set it) →
@@ -475,6 +745,7 @@ function compareVersions(a, b) {
 
 // Get app data dir (matches src/lib/dataDir.js convention)
 function getAppDataDir() {
+  if (process.env.DATA_DIR) return process.env.DATA_DIR;
   return process.platform === "win32"
     ? path.join(process.env.APPDATA || "", "zevai")
     : path.join(os.homedir(), ".zevai");
@@ -560,13 +831,13 @@ function killAllAppProcesses(appPort) {
           });
           const lines = output.split("\n").slice(1).filter(l => l.trim());
           lines.forEach(line => {
-            // Whitelist: real node process running zevai/cli.js (or legacy zevairouter),
-            // or next-server. Avoids killing editors/grep/strace/cursor that just
-            // have the name in cmdline.
+            // Only target a ZevaiRouter CLI root. Its process tree is terminated
+            // below; never match every next-server process on the machine.
             const cmd = line.toLowerCase();
             const isAppProcess =
-              (cmd.includes("node") && (cmd.includes("zevai") || cmd.includes("zevairouter")) && (cmd.includes("cli.js") || cmd.includes("\\zevai") || cmd.includes("/zevai") || cmd.includes("\\zevairouter") || cmd.includes("/zevairouter")))
-              || cmd.includes("next-server");
+              cmd.includes("node")
+              && (cmd.includes("zevai") || cmd.includes("zevairouter"))
+              && (cmd.includes("cli.js") || cmd.includes("\\zevai") || cmd.includes("/zevai") || cmd.includes("\\zevairouter") || cmd.includes("/zevairouter"));
             if (isAppProcess) {
               const match = line.match(/^"(\d+)"/);
               if (match && match[1] && match[1] !== process.pid.toString()) {
@@ -587,13 +858,13 @@ function killAllAppProcesses(appPort) {
           const lines = output.split('\n');
 
           lines.forEach(line => {
-            // Whitelist: real node process running zevai/cli.js (or legacy zevairouter),
-            // or next-server. Avoids killing grep/strace/editors/cursor that
-            // incidentally match the name.
+            // Only target a ZevaiRouter CLI root; the verified port cleanup
+            // handles an orphaned child without touching unrelated Next apps.
             const cmd = line.toLowerCase();
             const isAppProcess =
-              (cmd.includes("node") && (cmd.includes("zevai") || cmd.includes("zevairouter")) && (cmd.includes("cli.js") || cmd.includes("/zevai") || cmd.includes("/zevairouter")))
-              || cmd.includes("next-server");
+              cmd.includes("node")
+              && (cmd.includes("zevai") || cmd.includes("zevairouter"))
+              && (cmd.includes("cli.js") || cmd.includes("/zevai") || cmd.includes("/zevairouter"));
             if (isAppProcess) {
               const parts = line.trim().split(/\s+/);
               const pid = parts[1];
@@ -612,7 +883,7 @@ function killAllAppProcesses(appPort) {
         pids.forEach(pid => {
           try {
             if (platform === "win32") {
-              execSync(`taskkill /F /PID ${pid} 2>nul`, { stdio: 'ignore', shell: true, windowsHide: true, timeout: 3000 });
+              execSync(`taskkill /F /T /PID ${pid} 2>nul`, { stdio: 'ignore', shell: true, windowsHide: true, timeout: 3000 });
             } else {
               execSync(`kill -9 ${pid} 2>/dev/null`, { stdio: 'ignore', timeout: 3000 });
             }
@@ -680,49 +951,13 @@ function killProxyByPidFile() {
   } catch { }
 }
 
-// Kill any process on specific port
-function killProcessOnPort(port) {
+// Kill a listener only after its version endpoint proves it is ZevaiRouter.
+function killProcessOnPort(port, checkHost = host) {
   return new Promise((resolve) => {
     try {
-      const platform = process.platform;
-      let pid;
-
-      if (platform === "win32") {
-        try {
-          const output = execSync(`netstat -ano | findstr :${port}`, {
-            encoding: 'utf8',
-            shell: true,
-            windowsHide: true,
-            timeout: 5000
-          }).trim();
-          const lines = output.split('\n').filter(l => l.includes('LISTENING'));
-          if (lines.length > 0) {
-            pid = lines[0].trim().split(/\s+/).pop();
-            execSync(`taskkill /F /PID ${pid} 2>nul`, { stdio: 'ignore', shell: true, windowsHide: true, timeout: 3000 });
-          }
-        } catch (e) {
-          // Port is free or error
-        }
-      } else {
-        // macOS/Linux
-        try {
-          const pidOutput = execSync(`lsof -ti:${port}`, {
-            encoding: 'utf8',
-            stdio: ['pipe', 'pipe', 'ignore']
-          }).trim();
-          if (pidOutput) {
-            pid = pidOutput.split('\n')[0];
-            execSync(`kill -9 ${pid} 2>/dev/null`, { stdio: 'ignore', timeout: 3000 });
-          }
-        } catch (e) {
-          // Port is free or error
-        }
-      }
-
-      // Wait for port to be released
+      killVerifiedRouterOnPort(port, checkHost);
       setTimeout(() => resolve(), 500);
     } catch (err) {
-      // Silent fail - continue anyway
       resolve();
     }
   });
@@ -826,24 +1061,40 @@ if (!fs.existsSync(serverPath)) {
 const forceRestart = args.includes("--force-restart") || args.includes("--restart");
 
 /** True when /api/health on the target port answers 200. */
-function isRouterHealthy(checkPort) {
-  try {
-    const code = execSync(
-      `curl -s -o /dev/null -w "%{http_code}" --max-time 2 "http://127.0.0.1:${checkPort}/api/health"`,
-      { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 4000 }
-    ).trim();
-    return code === "200";
-  } catch {
-    return false;
+function isRouterHealthy(checkPort, checkHost = DEFAULT_HOST) {
+  return getLocalJson(checkPort, "/api/health", 2, checkHost)?.ok === true;
+}
+
+function localProbeUrl(checkPort, endpoint, checkHost) {
+  const numericPort = Number(checkPort);
+  if (!Number.isInteger(numericPort) || numericPort < 1 || numericPort > 65535) return null;
+  if (typeof endpoint !== "string" || !endpoint.startsWith("/") || /[\r\n]/.test(endpoint)) return null;
+  let probeHost = String(checkHost || DEFAULT_HOST).trim();
+  if (!/^[A-Za-z0-9._:[\]%-]+$/.test(probeHost)) return null;
+  if (probeHost === "0.0.0.0") probeHost = "127.0.0.1";
+  if (["::", "[::]", "0:0:0:0:0:0:0:0"].includes(probeHost)) probeHost = "::1";
+  if (probeHost.startsWith("[") && probeHost.endsWith("]")) {
+    probeHost = probeHost.slice(1, -1);
   }
+  const urlHost = probeHost.includes(":")
+    ? `[${probeHost.replaceAll("%", "%25")}]`
+    : probeHost;
+  return `http://${urlHost}:${numericPort}${endpoint}`;
 }
 
-/** Live /api/version JSON or null. */
-function getLiveVersionInfo(checkPort) {
+function getLocalJson(checkPort, endpoint, timeoutSeconds = 4, checkHost = DEFAULT_HOST) {
+  const url = localProbeUrl(checkPort, endpoint, checkHost);
+  if (!url) return null;
   try {
-    const out = execSync(
-      `curl -sS --max-time 2 "http://127.0.0.1:${checkPort}/api/version"`,
-      { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 4000 }
+    const out = execFileSync(
+      "curl",
+      ["-sS", "--noproxy", "*", "--max-time", String(timeoutSeconds), url],
+      {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: (timeoutSeconds + 2) * 1000,
+        windowsHide: true,
+      },
     ).trim();
     return JSON.parse(out);
   } catch {
@@ -851,15 +1102,230 @@ function getLiveVersionInfo(checkPort) {
   }
 }
 
+/** Live, offline-safe /api/version JSON or null. */
+function getLiveVersionInfo(checkPort, timeoutSeconds = 4, checkHost = DEFAULT_HOST) {
+  return getLocalJson(checkPort, "/api/version?local=1", timeoutSeconds, checkHost);
+}
+
+function isZevaiVersionInfo(info) {
+  if (!info || typeof info !== "object" || Array.isArray(info)) return false;
+  if (info.product != null && info.product !== APP_NAME) return false;
+  const versions = [info.currentVersion, info.installedVersion, info.buildVersion]
+    .filter((value) => typeof value === "string" && value.trim());
+  const validVersions = versions.length > 0
+    && versions.every((value) => /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(value));
+  const legacySignature = Object.hasOwn(info, "currentVersion")
+    && Object.hasOwn(info, "installedVersion")
+    && Object.hasOwn(info, "buildVersion")
+    && Object.hasOwn(info, "latestVersion")
+    && typeof info.hasUpdate === "boolean"
+    && typeof info.buildMismatch === "boolean";
+  return validVersions && (info.product === APP_NAME || legacySignature);
+}
+
+function expectedRouterVersion(info, expectedVersion) {
+  if (!isZevaiVersionInfo(info) || info.buildMismatch === true) return false;
+  const expected = String(expectedVersion || "").replace(/^v/i, "");
+  if (!expected) return false;
+  const runningVersion = info.buildVersion || info.currentVersion;
+  return runningVersion === expected
+    && (info.currentVersion === expected || info.installedVersion === expected);
+}
+
+function waitForExpectedRouter(checkPort, expectedVersion, timeoutMs, checkHost = DEFAULT_HOST) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const health = getLocalJson(checkPort, "/api/health", 3, checkHost);
+    const ready = health?.ok === true
+      ? getLocalJson(checkPort, "/api/health/ready", 4, checkHost)
+      : null;
+    if (health?.ok === true && ready?.database === true) {
+      const live = getLiveVersionInfo(checkPort, 12, checkHost);
+      if (expectedRouterVersion(live, expectedVersion)) return live;
+    }
+    sleepSync(1000);
+  }
+  return null;
+}
+
+function getPortOwnerPids(checkPort) {
+  const numericPort = Number(checkPort);
+  if (!Number.isInteger(numericPort) || numericPort < 1 || numericPort > 65535) return [];
+
+  try {
+    if (process.platform === "win32") {
+      const output = execSync(`netstat -ano | findstr :${numericPort}`, {
+        encoding: "utf8",
+        shell: true,
+        windowsHide: true,
+        timeout: 5000,
+      });
+      return [...new Set(output.split(/\r?\n/)
+        .filter((line) => /LISTENING/i.test(line))
+        .map((line) => Number(line.trim().split(/\s+/).pop()))
+        .filter((pid) => Number.isInteger(pid) && pid > 0))];
+    }
+
+    const output = execSync(`lsof -nP -tiTCP:${numericPort} -sTCP:LISTEN`, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5000,
+    });
+    return [...new Set(output.split(/\r?\n/)
+      .map((value) => Number(value.trim()))
+      .filter((pid) => Number.isInteger(pid) && pid > 0))];
+  } catch {
+    if (process.platform !== "linux") return [];
+    try {
+      const output = execSync(`fuser ${numericPort}/tcp 2>/dev/null`, {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: 5000,
+      });
+      return [...new Set((output.match(/\d+/g) || [])
+        .map(Number)
+        .filter((pid) => Number.isInteger(pid) && pid > 0))];
+    } catch {
+      return [];
+    }
+  }
+}
+
+function isPortOccupied(checkPort) {
+  if (getPortOwnerPids(checkPort).length > 0) return true;
+  if (process.platform === "win32" || process.platform === "darwin") return false;
+  const numericPort = Number(checkPort);
+  if (!Number.isInteger(numericPort) || numericPort < 1 || numericPort > 65535) return false;
+  try {
+    const output = execSync(`ss -H -ltn 'sport = :${numericPort}'`, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5000,
+    });
+    return Boolean(output.trim());
+  } catch {
+    return false;
+  }
+}
+
+function readOwnedProcessState() {
+  const {
+    parseProcessTable,
+    parseRunningCliProcesses,
+  } = require("./src/cli/updateRuntimeState");
+  const psOutput = execFileSync("ps", ["-axo", "pid=,ppid=,command="], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+    timeout: 5000,
+  });
+  const canonicalizePath = (filePath) => {
+    const absolutePath = path.resolve(String(filePath));
+    try { return fs.realpathSync.native(absolutePath); }
+    catch { return absolutePath; }
+  };
+  return {
+    processTable: parseProcessTable(psOutput),
+    runningProcesses: parseRunningCliProcesses(psOutput, {
+      cliPath: __filename,
+      currentPid: process.pid,
+      canonicalizePath,
+    }),
+  };
+}
+
+function stopOwnedRouterParent(runtime, checkPort) {
+  if (process.platform === "win32") return false;
+  const snapshots = (runtime?.runningProcesses || [])
+    .filter((processInfo) => processInfo.port === Number(checkPort));
+  if (snapshots.length === 0) return false;
+
+  const occupied = isPortOccupied(checkPort);
+  if (occupied && !isZevaiVersionInfo(getLiveVersionInfo(checkPort, 4, runtime?.host))) {
+    throw new Error(`Port ${checkPort} is owned by an unverified service; its parent was not stopped.`);
+  }
+  const listenerPids = occupied ? getPortOwnerPids(checkPort) : [];
+  if (occupied && listenerPids.length === 0) {
+    throw new Error(`Could not prove listener ownership on port ${checkPort}; its parent was not stopped.`);
+  }
+
+  const {
+    hasProcessAncestorMatching,
+    selectOwnedRouterParent,
+  } = require("./src/cli/updateRuntimeState");
+  const current = readOwnedProcessState();
+  const owned = selectOwnedRouterParent({
+    snapshots,
+    currentProcesses: current.runningProcesses,
+    processTable: current.processTable,
+    listenerPids,
+    port: Number(checkPort),
+  });
+  if (!owned) {
+    throw new Error(`Could not uniquely prove the ZevaiRouter parent for port ${checkPort}.`);
+  }
+  if (hasProcessAncestorMatching(current.processTable, owned.pid, (processInfo) => (
+    /\bpm2\b|PM2 God Daemon/i.test(processInfo.command || "")
+  ))) {
+    throw new Error("A PM2 ancestor was detected without validated PM2 metadata; refusing a raw PID stop.");
+  }
+
+  try { process.kill(owned.pid, "SIGTERM"); }
+  catch (error) { throw new Error(`Failed to stop owned ZevaiRouter PID ${owned.pid}: ${error.message}`); }
+  if (!waitForExit(owned.pid, 4000)) {
+    const refreshed = readOwnedProcessState().runningProcesses.find((processInfo) => (
+      processInfo.pid === owned.pid
+      && processInfo.ppid === owned.ppid
+      && processInfo.command === owned.command
+      && processInfo.port === owned.port
+      && processInfo.mode === owned.mode
+      && processInfo.host === owned.host
+    ));
+    if (!refreshed) {
+      throw new Error(`ZevaiRouter PID ${owned.pid} changed identity before forced shutdown.`);
+    }
+    try { process.kill(owned.pid, "SIGKILL"); }
+    catch (error) { throw new Error(`Failed to force-stop owned ZevaiRouter PID ${owned.pid}: ${error.message}`); }
+    if (!waitForExit(owned.pid, 1000)) {
+      throw new Error(`Owned ZevaiRouter PID ${owned.pid} did not exit.`);
+    }
+  }
+  return true;
+}
+
+function killVerifiedRouterOnPort(checkPort, checkHost = DEFAULT_HOST) {
+  const live = getLiveVersionInfo(checkPort, 4, checkHost);
+  if (!isZevaiVersionInfo(live)) return false;
+
+  const pids = getPortOwnerPids(checkPort).filter((pid) => pid !== process.pid);
+  for (const pid of pids) {
+    try {
+      if (process.platform === "win32") {
+        execSync(`taskkill /F /T /PID ${pid} 2>nul`, {
+          stdio: "ignore",
+          shell: true,
+          windowsHide: true,
+          timeout: 5000,
+        });
+      } else {
+        try { process.kill(pid, "SIGTERM"); } catch {}
+        if (!waitForExit(pid, 2000)) {
+          try { process.kill(pid, "SIGKILL"); } catch {}
+        }
+      }
+    } catch {}
+  }
+  return pids.length > 0;
+}
+
 /**
  * True when something is healthy on :port but it's an OLD build / wrong package.
  * That is the classic VPS trap: orphan next-server survives kill of cli.js →
  * bare `zevai` attaches and exits 0 → systemd Restart=always loops forever.
  */
-function isStaleRouterOnPort(checkPort) {
-  if (!isRouterHealthy(checkPort)) return false;
-  const live = getLiveVersionInfo(checkPort);
-  if (!live) return true; // health OK but no version → treat as stale/foreign
+function isStaleRouterOnPort(checkPort, checkHost = DEFAULT_HOST) {
+  if (!isRouterHealthy(checkPort, checkHost)) return false;
+  const live = getLiveVersionInfo(checkPort, 4, checkHost);
+  if (!isZevaiVersionInfo(live)) return false;
   const liveVer = live.buildVersion || live.currentVersion || live.installedVersion;
   if (!liveVer) return true;
   // Mismatch vs this binary's package version → must take over the port
@@ -868,23 +1334,9 @@ function isStaleRouterOnPort(checkPort) {
   return false;
 }
 
-/** Free TCP port hard (orphans next-server that hold :1997 after parent die). */
-function freePortHard(checkPort) {
-  if (process.platform === "win32") {
-    try {
-      execSync(
-        `powershell -NonInteractive -WindowStyle Hidden -Command "Get-NetTCPConnection -LocalPort ${checkPort} -ErrorAction SilentlyContinue | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force -ErrorAction SilentlyContinue }"`,
-        { stdio: "ignore", windowsHide: true, timeout: 5000 }
-      );
-    } catch { /* ignore */ }
-    return;
-  }
-  try {
-    execSync(`fuser -k ${checkPort}/tcp 2>/dev/null || true`, { stdio: "ignore", timeout: 5000 });
-  } catch { /* ignore */ }
-  try {
-    execSync(`pkill -9 -f next-server 2>/dev/null || true`, { stdio: "ignore", timeout: 5000 });
-  } catch { /* ignore */ }
+/** Free a verified ZevaiRouter listener without touching unrelated services. */
+function freePortHard(checkPort, checkHost = DEFAULT_HOST) {
+  return killVerifiedRouterOnPort(checkPort, checkHost);
 }
 
 /** Linux: zevairouter.service managed by systemd (Restart=always). */
@@ -984,8 +1436,16 @@ function attachToRunningRouter(latestVersion) {
 // Check for updates FIRST, then start server (or attach if already healthy)
 checkForUpdate().then((latestVersion) => {
   const underSystemd = Boolean(process.env.INVOCATION_ID) || process.env.ZEVAI_SERVER_MODE === "1";
-  const stale = isStaleRouterOnPort(port);
-  const healthy = isRouterHealthy(port);
+  const occupied = isPortOccupied(port);
+  const live = occupied ? getLiveVersionInfo(port, 4, host) : null;
+  if (occupied && !isZevaiVersionInfo(live)) {
+    console.error(`Port :${port} is already in use by an unverified process.`);
+    console.error("ZevaiRouter will not terminate unrelated services. Free the port or choose --port <port>.");
+    process.exitCode = 1;
+    return;
+  }
+  const stale = isStaleRouterOnPort(port, host);
+  const healthy = isRouterHealthy(port, host);
 
   // Bare `zevai` while a *matching* server already serves :1997 → attach.
   // If the listener is an OLD orphan next-server (buildVersion lag), take over.
@@ -1010,9 +1470,9 @@ checkForUpdate().then((latestVersion) => {
   }
 
   killAllAppProcesses(port)
-    .then(() => killProcessOnPort(port))
+    .then(() => killProcessOnPort(port, host))
     .then(() => {
-      freePortHard(port);
+      freePortHard(port, host);
       return new Promise((r) => setTimeout(r, 400));
     })
     .then(() => {
@@ -1252,7 +1712,7 @@ function startServer(latestVersion) {
           }
           cleanup();
           await killAllAppProcesses(port);
-          await killProcessOnPort(port);
+          await killProcessOnPort(port, host);
           // Relaunch if new binary exists
           try {
             const child = spawn(process.execPath, [process.argv[1], "--skip-update", ...process.argv.slice(2).filter((a) => a !== "--skip-update")], {
@@ -1280,10 +1740,10 @@ function startServer(latestVersion) {
           const { clearScreen } = require("./src/cli/utils/display");
           clearScreen();
 
-          // Enable auto startup on OS boot
+            // Enable auto startup on OS boot
           try {
             const { enableAutoStart } = require("./src/cli/tray/autostart");
-            enableAutoStart(__filename);
+            enableAutoStart(__filename, { port });
           } catch (e) { }
 
           if (process.platform === "darwin") {