alvin-bot 4.9.3 → 4.9.4

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [4.9.4] — 2026-04-13
+
+### 🔌 Web UI fully decoupled from main bot — port conflicts no longer crash anything
+
+Colleague feedback (WhatsApp voice note, 2026-04-13):
+> *"The gateway binds to port 3100 like OpenClaw. When the bot restarts,
+> the port is often still held → catastrophic crash. I ended up
+> decoupling the gateway process completely, because the actual bot
+> runs independently of the gateway — it can still answer Telegram
+> even if the web endpoint isn't reachable yet. It's weird that the
+> main routine crashes when the port is busy. It should just run in
+> the background, watch for the port to become free, and connect
+> then. Zero impact on the main routine."*
+
+He was right. My v4.9.0 `stopWebServer()` fix was *prevention* — it stopped the bot itself from holding 3100 across restarts. But it didn't cover the *resilience* side: a foreign process holding 3100 (another dev server, an OpenClaw-style orphan, a TIME_WAIT race after SIGKILL) still crashed the boot, because `startWebServer()` was synchronous and the `uncaught exception` from `server.listen()` escaped to the main event loop.
+
+**Complete rewrite of the bind loop:**
+
+- **`src/web/bind-strategy.ts` (new) — pure decision helper.** `decideNextBindAction(err, attempt, opts)` returns either `{type: "retry-port", port, attempt}` (climb the ladder) or `{type: "retry-background", delayMs, port}` (back off, retry the original port in 30 s). EADDRINUSE with attempts remaining → ladder. EADDRINUSE exhausted → background. Any other error → background. 8 unit tests covering every branch + purity.
+
+- **`src/web/server.ts` startWebServer — non-blocking, fresh-server-per-attempt.** Returns `void` synchronously, NEVER throws, NEVER blocks on bind. Each attempt creates a new `http.Server` (no state-recycling bugs) and attaches its own error handler. On failure, cleans up and calls `decideNextBindAction` to decide the next move. If the ladder is exhausted, schedules a 30 s background retry at the original port — the Telegram bot keeps running the whole time, the web UI just isn't reachable yet.
+
+- **`src/web/server.ts` WebSocketServer attached POST-bind.** The `ws` library's `WebSocketServer` constructor installs its own event plumbing on the underlying `http.Server` and — crucially — causes EADDRINUSE errors to escape as uncaught exceptions when attached pre-listen. Debugging this chewed an hour on 2026-04-13. Fix: only `new WebSocketServer({ server })` AFTER `listen()` has fired its callback. The unit-test `test/web-server-integration.test.ts "when the primary port is taken"` pins this behaviour.
+
+- **`src/web/server.ts` error handler: `on` not `once`.** Previous version used `.once("error", handler)` and a node edge case where a single bind failure emits TWO error events left the second one uncaught. Handler is now `on` with a `handled` guard — idempotent, and a post-bind quiet logger replaces it on success.
+
+- **`src/web/server.ts` defensive try/catch around `server.listen()`.** In the wild Node sometimes throws synchronously for edge-case binds (already-listening, invalid backlog, kernel race). The catch funnels sync throws through the same `handleBindFailure` path as async error events.
+
+- **`src/web/server.ts` `closeHttpServerGracefully(server)` + `stopWebServer()`.** The old `stopWebServer(server)` took an explicit server arg; it's been split into a low-level helper (`closeHttpServerGracefully(server)`, exported for tests) and a stateful top-level (`stopWebServer()`, no args, cleans up `currentServer` + `wsServerRef` + `bindRetryTimer`). Safe to call before start, safe to call twice, cancels pending background retries.
+
+- **`src/index.ts` call sites adjusted.** `const webServer = startWebServer()` → `startWebServer()`. `stopWebServer(webServer)` → `stopWebServer()`. The comment above the call explains the decoupling so nobody accidentally re-couples it in a future "clean up" refactor.
+
+**Testing: 186 → 201 (+15 new).**
+
+- `test/web-server-resilience.test.ts` — 8 unit tests for `decideNextBindAction`
+- `test/web-server-integration.test.ts` — 7 real-server integration tests: startWebServer returns void, binds, stops, is idempotent, survives primary-port conflict by climbing the ladder, closes servers with hanging sockets.
+- **Live-verified on the maintainer's machine**: `launchctl unload` + dual-stack Node hog on port 3100 + `launchctl load` → bot booted cleanly → out.log contained `[web] port 3100 busy (EADDRINUSE) — trying 3101` → `🌐 Web UI: http://localhost:3101   (Port 3100 was busy, using 3101 instead)` → Telegram responsive throughout. Exactly what the colleague described.
+
+**Non-goals / intentionally unchanged:**
+- Timeouts stay unlimited (v4.8.8 behaviour preserved).
+- The primary port is still `WEB_PORT || 3100` — no config schema change.
+- When the bot binds on a non-primary port (e.g. 3101), the README permalink still points at 3100. Users hitting a ladder-climbed bot should check the startup log; this is rare and temporary.
+
 ## [4.9.3] — 2026-04-11
 
 ### 🛠 Two UX bugs found in production after v4.9.2 — now closed

package/README.md

@@ -114,7 +114,18 @@ That's it. The setup wizard validates everything:
 
 **Requires:** Node.js 18+ ([nodejs.org](https://nodejs.org)) · Telegram bot token ([@BotFather](https://t.me/BotFather)) · Your Telegram user ID ([@userinfobot](https://t.me/userinfobot))
 
-Free AI providers available — no credit card needed.
+Free AI providers available — no credit card needed. **Privacy-first?** Pick the 🔒 **Offline — Gemma 4 E4B** option in setup for a fully local LLM via Ollama (macOS/Linux: automated install; Windows: manual).
+
+### 📘 First-time setup walkthroughs
+
+Step-by-step guides with screenshots and screen-for-screen instructions:
+
+| Platform | PDF (printable) |
+|---|---|
+| 🍎 **macOS** (with `launchd` background service) | [Download PDF](https://github.com/alvbln/Alvin-Bot/releases/latest/download/Alvin-Bot-macOS-Setup-Guide.pdf) |
+| 🪟 **Windows** (with Task Scheduler / Startup folder) | [Download PDF](https://github.com/alvbln/Alvin-Bot/releases/latest/download/Alvin-Bot-Windows-Setup-Guide.pdf) |
+
+Both guides cover: Node.js install · Telegram bot creation · first-time `setup` · foreground test · background service · offline Gemma 4 mode · troubleshooting. ~15 min end-to-end for a first-time user.
 
 ### macOS: use `launchd` instead of pm2 (recommended)
 

package/dist/index.js

@@ -267,7 +267,7 @@ const shutdown = async () => {
     }
     // Release :3100 so the next launchd boot doesn't hit EADDRINUSE.
     // Must happen before exit — see src/web/server.ts stopWebServer() comment.
-    await stopWebServer(webServer).catch((err) => console.warn("[shutdown] stopWebServer failed:", err));
+    await stopWebServer().catch((err) => console.warn("[shutdown] stopWebServer failed:", err));
     await unloadPlugins().catch(() => { });
     await disconnectMCP().catch(() => { });
     // Tear down any bot-managed local runners (Ollama, LM Studio, …) so VRAM
@@ -404,8 +404,13 @@ async function startOptionalPlatforms() {
     }
 }
 startOptionalPlatforms().catch(err => console.error("Platform startup error:", err));
-// Start Web UI (ALWAYS — regardless of Telegram/AI config)
-const webServer = startWebServer();
+// Start Web UI (ALWAYS — regardless of Telegram/AI config).
+// startWebServer is now non-blocking and will never throw: if port 3100
+// is busy (foreign process, TIME_WAIT, another bot instance), it climbs
+// the port ladder up to 3119 and then enters a background retry loop
+// at 3100 every 30s. The Telegram bot runs independently — Web UI is a
+// feature, not core. See src/web/bind-strategy.ts for the retry rules.
+startWebServer();
 // Start Cron Scheduler — route notifications through delivery queue for reliability
 setNotifyCallback(async (target, text) => {
     if (target.platform === "web") {

package/dist/web/bind-strategy.js

@@ -0,0 +1,42 @@
+/**
+ * Pure decision helper for the web-server bind loop.
+ *
+ * Decouples the "what should happen next" logic from the side-effect
+ * spaghetti of real http.Server binding so it can be unit-tested in
+ * isolation. See test/web-server-resilience.test.ts for the contract.
+ *
+ * Why this exists: the v4.8.x and earlier implementations crashed the
+ * entire bot when port 3100 was held by a foreign process. A colleague
+ * running an OpenClaw fork hit the same bug years ago and ended up
+ * decoupling the web server completely — the main bot should never be
+ * gated on a web-UI bind. This helper encodes the decision logic so
+ * the new startWebServer() can just act on the returned action.
+ */
+/**
+ * Decide what the bind loop should do next after a failed listen().
+ *
+ * Rule of thumb:
+ *   - EADDRINUSE AND attempts remaining  → climb the port ladder.
+ *   - EADDRINUSE AND ladder exhausted    → background retry at original port.
+ *   - any other error (EACCES, listen-called-twice, etc.) → background retry.
+ *
+ * PURE: no timers, no I/O, no mutation of inputs. Safe to call from tests.
+ */
+export function decideNextBindAction(err, attempt, opts) {
+    const code = err?.code;
+    if (code === "EADDRINUSE" && attempt < opts.maxPortTries - 1) {
+        return {
+            type: "retry-port",
+            port: opts.originalPort + attempt + 1,
+            attempt: attempt + 1,
+        };
+    }
+    // EADDRINUSE with no attempts left, OR any non-EADDRINUSE error:
+    // don't walk the port ladder further, just back off and retry the
+    // original port in the background.
+    return {
+        type: "retry-background",
+        delayMs: opts.backgroundRetryMs,
+        port: opts.originalPort,
+    };
+}

package/dist/web/server.js

@@ -30,10 +30,24 @@ import { addCanvasClient } from "./canvas.js";
 import { BOT_ROOT, ENV_FILE, PUBLIC_DIR, MEMORY_DIR, MEMORY_FILE, SOUL_FILE, DATA_DIR, MCP_CONFIG, SKILLS_DIR } from "../paths.js";
 import { broadcast } from "../services/broadcast.js";
 import { BOT_VERSION } from "../version.js";
+import { decideNextBindAction } from "./bind-strategy.js";
 const WEB_PORT = parseInt(process.env.WEB_PORT || "3100");
-/** Module-scope reference to the WebSocket server so stopWebServer() can
- *  tear it down together with the HTTP server. Set inside startWebServer(). */
+/** Tuning for the bind loop. Walk the port ladder `MAX_PORT_TRIES` times
+ *  then fall back to a `BACKGROUND_RETRY_MS` idle loop — the bot keeps
+ *  running on Telegram either way; see bind-strategy.ts for the pure
+ *  decision logic. */
+const MAX_PORT_TRIES = 20;
+const BACKGROUND_RETRY_MS = 30_000;
+/** Current live http.Server, if one has successfully bound. */
+let currentServer = null;
+/** Current live WebSocketServer attached to currentServer. */
 let wsServerRef = null;
+/** Background-retry timer handle — set when the bind loop is in its
+ *  idle wait between cycles, cleared when stopWebServer() cancels. */
+let bindRetryTimer = null;
+/** Flag flipped by stopWebServer(). Every bind-loop callback checks
+ *  this and exits silently if set, so stop is truly terminal. */
+let stopRequested = false;
 const WEB_PASSWORD = process.env.WEB_PASSWORD || "";
 /** The actual port the Web UI is running on (may differ from WEB_PORT if busy). */
 let actualWebPort = WEB_PORT;
@@ -1371,126 +1385,207 @@ function handleWebSocket(wss) {
     });
 }
 // ── Start Server ────────────────────────────────────────
-export function startWebServer() {
-    const server = http.createServer((req, res) => {
-        let body = "";
-        req.on("data", (chunk) => { body += chunk; });
-        req.on("end", () => {
-            const urlPath = (req.url || "/").split("?")[0];
-            // OpenAI-compatible API (/v1/chat/completions, /v1/models)
-            if (urlPath.startsWith("/v1/")) {
-                handleOpenAICompat(req, res, urlPath, body);
-                return;
-            }
-            // API routes
-            if (urlPath.startsWith("/api/")) {
-                handleAPI(req, res, urlPath, body);
-                return;
-            }
-            // Auth page (if password set and not authenticated)
-            if (WEB_PASSWORD && !checkAuth(req) && urlPath !== "/login.html") {
-                res.writeHead(302, { Location: "/login.html" });
-                res.end();
-                return;
-            }
-            // Canvas UI
-            if (urlPath === "/canvas") {
-                const canvasFile = resolve(PUBLIC_DIR, "canvas.html");
-                try {
-                    const content = fs.readFileSync(canvasFile);
-                    res.setHeader("Content-Type", "text/html");
-                    res.end(content);
-                }
-                catch {
-                    res.statusCode = 404;
-                    res.end("Not found");
-                }
-                return;
-            }
-            // Static files
-            let filePath = urlPath === "/" ? "/index.html" : urlPath;
-            filePath = resolve(PUBLIC_DIR, filePath.slice(1));
-            // Security: prevent path traversal
-            if (!filePath.startsWith(PUBLIC_DIR)) {
-                res.statusCode = 403;
-                res.end("Forbidden");
-                return;
-            }
+/**
+ * HTTP request handler for the web UI. Hoisted to a top-level function
+ * so every bind attempt can create a fresh http.Server without
+ * rebuilding the handler closure.
+ */
+function handleWebRequest(req, res) {
+    let body = "";
+    req.on("data", (chunk) => { body += chunk; });
+    req.on("end", () => {
+        const urlPath = (req.url || "/").split("?")[0];
+        // OpenAI-compatible API (/v1/chat/completions, /v1/models)
+        if (urlPath.startsWith("/v1/")) {
+            handleOpenAICompat(req, res, urlPath, body);
+            return;
+        }
+        // API routes
+        if (urlPath.startsWith("/api/")) {
+            handleAPI(req, res, urlPath, body);
+            return;
+        }
+        // Auth page (if password set and not authenticated)
+        if (WEB_PASSWORD && !checkAuth(req) && urlPath !== "/login.html") {
+            res.writeHead(302, { Location: "/login.html" });
+            res.end();
+            return;
+        }
+        // Canvas UI
+        if (urlPath === "/canvas") {
+            const canvasFile = resolve(PUBLIC_DIR, "canvas.html");
             try {
-                const content = fs.readFileSync(filePath);
-                const ext = path.extname(filePath);
-                res.setHeader("Content-Type", MIME[ext] || "application/octet-stream");
+                const content = fs.readFileSync(canvasFile);
+                res.setHeader("Content-Type", "text/html");
                 res.end(content);
             }
             catch {
                 res.statusCode = 404;
                 res.end("Not found");
             }
-        });
+            return;
+        }
+        // Static files
+        let filePath = urlPath === "/" ? "/index.html" : urlPath;
+        filePath = resolve(PUBLIC_DIR, filePath.slice(1));
+        // Security: prevent path traversal
+        if (!filePath.startsWith(PUBLIC_DIR)) {
+            res.statusCode = 403;
+            res.end("Forbidden");
+            return;
+        }
+        try {
+            const content = fs.readFileSync(filePath);
+            const ext = path.extname(filePath);
+            res.setHeader("Content-Type", MIME[ext] || "application/octet-stream");
+            res.end(content);
+        }
+        catch {
+            res.statusCode = 404;
+            res.end("Not found");
+        }
     });
-    const wss = new WebSocketServer({ server });
-    wsServerRef = wss;
-    handleWebSocket(wss);
-    // Smart port: try WEB_PORT, increment if busy (up to +20)
-    const MAX_TRIES = 20;
-    function tryListen(port, attempt = 0) {
-        server.once("error", (err) => {
-            if (err.code === "EADDRINUSE" && attempt < MAX_TRIES) {
-                tryListen(port + 1, attempt + 1);
-            }
-            else {
-                console.error(`❌ Web UI failed to start: ${err.message}`);
-            }
+}
+/**
+ * Kick off the web-UI bind loop. NEVER throws, NEVER blocks.
+ *
+ * History: earlier versions returned an http.Server synchronously and
+ * let listen() errors bubble up as uncaught exceptions — a colleague
+ * flagged this on 2026-04-13 after spending months fighting the exact
+ * same bug on a parallel OpenClaw fork. Their resolution: "the gateway
+ * is a feature, not core. Decouple it."
+ *
+ * New contract:
+ *   - Returns `void` immediately. The actual bind happens asynchronously.
+ *   - If port 3100 is busy, tries 3101…3119 in sequence (same as before).
+ *   - If ALL 20 ports are busy, schedules a background retry at 3100
+ *     in `BACKGROUND_RETRY_MS` — keeps trying forever until success
+ *     or stopWebServer() is called.
+ *   - Any non-EADDRINUSE error also falls through to background retry.
+ *   - Each attempt uses a FRESH http.Server to avoid node's fragile
+ *     "listen-called-twice" state-recycling behaviour.
+ *   - The main Telegram bot is completely independent of this — if the
+ *     web UI never binds, the bot still answers messages.
+ */
+export function startWebServer() {
+    stopRequested = false;
+    scheduleBindAttempt(WEB_PORT, 0);
+}
+function scheduleBindAttempt(port, attempt) {
+    if (stopRequested)
+        return;
+    // Read WEB_PORT live every time rather than closing over the
+    // module-load value, so tests that change process.env.WEB_PORT
+    // between runs see the new port.
+    const originalPort = parseInt(process.env.WEB_PORT || "3100");
+    // Fresh server for each attempt. Recycling a server that has already
+    // emitted an EADDRINUSE error has produced "Listen method has been
+    // called more than once" crashes in the wild.
+    //
+    // IMPORTANT: do NOT attach the WebSocketServer yet. The `ws` library
+    // installs its own event plumbing on the http.Server in its
+    // constructor, which causes bind errors to escape as uncaught
+    // exceptions. We only attach it AFTER listen() has succeeded.
+    const server = http.createServer(handleWebRequest);
+    // Double-invocation guard: on some Node versions `server.listen`
+    // both throws synchronously AND emits an `error` event for the same
+    // bind failure. Without the guard we'd climb the ladder twice in
+    // parallel and end up with two retry cascades racing each other.
+    let handled = false;
+    const cleanupDeadAttempt = () => {
+        try {
+            server.removeAllListeners("error");
+        }
+        catch { /* ignore */ }
+        try {
+            server.close(() => { });
+        }
+        catch { /* ignore */ }
+    };
+    const handleBindFailure = (err) => {
+        if (handled)
+            return;
+        handled = true;
+        cleanupDeadAttempt();
+        if (stopRequested)
+            return;
+        const action = decideNextBindAction(err, attempt, {
+            originalPort,
+            maxPortTries: MAX_PORT_TRIES,
+            backgroundRetryMs: BACKGROUND_RETRY_MS,
         });
+        if (action.type === "retry-port") {
+            console.warn(`[web] port ${port} busy (${err.code || err.message}) — trying ${action.port}`);
+            scheduleBindAttempt(action.port, action.attempt);
+            return;
+        }
+        // action.type === "retry-background"
+        console.warn(`[web] bind failed (${err.code || err.message}) — ` +
+            `backing off ${action.delayMs / 1000}s then retrying port ${action.port}. ` +
+            `Bot is unaffected; Telegram remains live.`);
+        bindRetryTimer = setTimeout(() => {
+            bindRetryTimer = null;
+            scheduleBindAttempt(action.port, 0);
+        }, action.delayMs);
+    };
+    // Use `on` (not `once`) so a pathological server that emits two
+    // error events for a single failure doesn't leave the second one
+    // uncaught. The `handled` guard makes the handler idempotent.
+    server.on("error", handleBindFailure);
+    // Defensive try/catch — `server.listen()` usually emits async errors,
+    // but certain Node versions + edge cases (already-listening server,
+    // invalid backlog, kernel hiccup) can throw synchronously. Catch here
+    // so the main routine never crashes during web-UI bind.
+    try {
         server.listen(port, () => {
+            if (handled)
+                return; // Should be impossible; paranoia.
+            handled = true;
+            // Now — and only now — attach the WebSocketServer. Before the
+            // bind succeeded, the ws library's constructor would hijack the
+            // http.Server's error event chain and let EADDRINUSE escape as
+            // uncaught. Post-bind is safe.
+            const wss = new WebSocketServer({ server });
+            handleWebSocket(wss);
+            currentServer = server;
+            wsServerRef = wss;
             actualWebPort = port;
+            // Remove the bind error handler — post-listen errors (socket
+            // errors, close events) should not kick off a spurious retry
+            // cycle. Install a quiet logger for any stray error events so
+            // they can't escape as uncaught.
+            server.removeListener("error", handleBindFailure);
+            server.on("error", (err) => {
+                console.warn(`[web] post-bind server error (ignored): ${err.message}`);
+            });
             console.log(`🌐 Web UI: http://localhost:${actualWebPort}`);
-            if (actualWebPort !== WEB_PORT) {
-                console.log(`   (Port ${WEB_PORT} was busy, using ${actualWebPort} instead)`);
+            if (actualWebPort !== originalPort) {
+                console.log(`   (Port ${originalPort} was busy, using ${actualWebPort} instead)`);
             }
         });
     }
-    tryListen(WEB_PORT);
-    return server;
+    catch (err) {
+        handleBindFailure(err);
+    }
 }
 /**
- * Gracefully stop the web server so the port is released.
- *
- * Why this exists: `shutdown()` in src/index.ts used to stop grammy and the
- * scheduler but leave the HTTP server listening. macOS then held the
- * listening socket in the socket table, so launchd's next boot of the bot
- * hit `EADDRINUSE :::3100`, threw an Uncaught exception and crash-looped.
+ * Gracefully close a specific http.Server — the low-level building
+ * block. Exported for tests and for any future callers that manage
+ * their own servers. Production bot code uses `stopWebServer()` below
+ * which operates on the module-global current server instead.
  *
  * What this does:
- *   1. Force-close idle keep-alive sockets (otherwise close() hangs on them).
- *   2. Force-close active open requests (long-poll clients, WebSocket
- *      upgrades that never completed).
- *   3. Tear down the WebSocket server so its own sockets don't linger.
- *   4. Await `server.close()` so the listening socket is truly released
- *      before the caller's shutdown continues.
+ *   1. Force-close idle keep-alive sockets (Node 18.2+).
+ *   2. Force-close active open requests (long-poll clients).
+ *   3. Await `server.close()` so the listening socket is truly freed.
  *
- * Safe to call multiple times; no-op when the server is already closed or
- * never listened. Never throws.
+ * Safe to call on already-closed, never-listened, or mid-listen servers.
+ * Never throws.
  */
-export async function stopWebServer(server) {
-    try {
-        if (wsServerRef) {
-            for (const client of wsServerRef.clients) {
-                try {
-                    client.terminate();
-                }
-                catch { /* ignore */ }
-            }
-            await new Promise((resolve) => wsServerRef.close(() => resolve()));
-            wsServerRef = null;
-        }
-    }
-    catch { /* ignore */ }
+export async function closeHttpServerGracefully(server) {
     if (!server.listening)
         return;
     try {
-        // Node 18.2+ APIs — break any keep-alive / long-poll stalls so
-        // server.close() can actually resolve.
         const s = server;
         if (typeof s.closeIdleConnections === "function")
             s.closeIdleConnections();
@@ -1499,12 +1594,47 @@ export async function stopWebServer(server) {
     }
     catch { /* ignore */ }
     await new Promise((resolve) => {
-        // close() callback fires with an Error arg when the server wasn't
-        // listening — we just resolve in either case. The caller only cares
-        // that the port is free when this awaits.
         server.close(() => resolve());
     });
 }
+/**
+ * Stop the web server: cancel any pending background-retry, close
+ * WebSocket clients, then gracefully close the HTTP server.
+ *
+ * Idempotent — safe to call multiple times, and safe to call before
+ * startWebServer() ever successfully bound. Never throws.
+ */
+export async function stopWebServer() {
+    stopRequested = true;
+    // Cancel any pending background-retry timer so a late retry doesn't
+    // grab the port AFTER we thought we'd shut everything down.
+    if (bindRetryTimer) {
+        clearTimeout(bindRetryTimer);
+        bindRetryTimer = null;
+    }
+    // Tear down the WebSocket server first so its sockets can't keep
+    // the underlying http.Server alive.
+    if (wsServerRef) {
+        try {
+            for (const client of wsServerRef.clients) {
+                try {
+                    client.terminate();
+                }
+                catch { /* ignore */ }
+            }
+            await new Promise((resolve) => wsServerRef.close(() => resolve()));
+        }
+        catch { /* ignore */ }
+        wsServerRef = null;
+    }
+    if (currentServer) {
+        try {
+            await closeHttpServerGracefully(currentServer);
+        }
+        catch { /* ignore */ }
+        currentServer = null;
+    }
+}
 /** Get the actual port the Web UI is running on. */
 export function getWebPort() {
     return actualWebPort;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alvin-bot",
-  "version": "4.9.3",
+  "version": "4.9.4",
   "description": "Alvin Bot — Your personal AI agent on Telegram, WhatsApp, Discord, Signal, and Web.",
   "type": "module",
   "main": "dist/index.js",

package/test/stress-scenarios.test.ts

@@ -19,7 +19,7 @@
  */
 import { describe, it, expect, beforeEach, vi } from "vitest";
 import http from "http";
-import { stopWebServer } from "../src/web/server.js";
+import { closeHttpServerGracefully as stopWebServer } from "../src/web/server.js";
 import {
   handleStartupCatchup,
   prepareForExecution,

package/test/web-server-integration.test.ts

@@ -0,0 +1,189 @@
+/**
+ * Fix #16 (integration) — end-to-end tests for the decoupled
+ * startWebServer + stopWebServer pair.
+ *
+ * These tests exercise the ACTUAL http.Server binding, not the pure
+ * decision helper. They rely on:
+ *   - process.env.WEB_PORT to keep the test off the running bot's 3100
+ *   - process.env.ALVIN_DATA_DIR to keep touch-points away from
+ *     the maintainer's real ~/.alvin-bot/.env
+ *
+ * What's covered here:
+ *   1. startWebServer() returns synchronously (void) without throwing
+ *   2. stopWebServer() releases the port so another server can bind
+ *   3. Start → stop → start cycle doesn't leak sockets or timers
+ *   4. If the configured port is already busy, startWebServer still
+ *      returns cleanly (no throw); the bot keeps running.
+ *   5. stopWebServer() is idempotent — safe to call twice in a row
+ *      and safe to call before startWebServer ever succeeded.
+ *
+ * The deliberate EADDRINUSE scenario is tested HERE against a real
+ * running hog — no mocking.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import http from "http";
+import fs from "fs";
+import os from "os";
+import { resolve } from "path";
+
+const TEST_DATA_DIR = resolve(os.tmpdir(), `alvin-bot-web-int-${process.pid}-${Date.now()}`);
+
+function getFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const s = http.createServer();
+    s.listen(0, () => {
+      const addr = s.address();
+      if (typeof addr === "object" && addr) {
+        const p = addr.port;
+        s.close(() => resolve(p));
+      } else {
+        reject(new Error("no address"));
+      }
+    });
+  });
+}
+
+async function waitForPortBound(port: number, timeoutMs = 3000): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const code = await new Promise<number>((resolveCode, reject) => {
+        const req = http.get(`http://127.0.0.1:${port}/`, (res) => {
+          res.resume();
+          resolveCode(res.statusCode ?? 0);
+        });
+        req.on("error", (err) => reject(err));
+        req.setTimeout(500, () => {
+          req.destroy(new Error("timeout"));
+        });
+      });
+      if (code > 0) return true;
+    } catch {
+      /* not yet */
+    }
+    await new Promise((r) => setTimeout(r, 100));
+  }
+  return false;
+}
+
+beforeEach(async () => {
+  if (fs.existsSync(TEST_DATA_DIR)) fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+  fs.mkdirSync(TEST_DATA_DIR, { recursive: true });
+  process.env.ALVIN_DATA_DIR = TEST_DATA_DIR;
+  // Write a minimal .env so config.ts loads cleanly
+  fs.writeFileSync(`${TEST_DATA_DIR}/.env`, "WEB_PASSWORD=\n", "utf-8");
+  process.env.WEB_PORT = String(await getFreePort());
+  // Reset module cache so each test imports server.js fresh and
+  // picks up the new WEB_PORT env var at module-load time.
+  vi.resetModules();
+});
+
+afterEach(async () => {
+  // Best-effort: stop whatever is running in the current module instance
+  try {
+    const { stopWebServer } = await import("../src/web/server.js");
+    await stopWebServer();
+  } catch {
+    /* ignore */
+  }
+  // Give the OS a moment to release ports before the next test
+  await new Promise((r) => setTimeout(r, 50));
+});
+
+describe("startWebServer / stopWebServer integration (Fix #16)", () => {
+  it("startWebServer returns void synchronously without throwing", async () => {
+    const { startWebServer } = await import("../src/web/server.js");
+    const result = startWebServer();
+    // Must return void (undefined). If it returned a Server instance
+    // the old API is still in place.
+    expect(result).toBeUndefined();
+  });
+
+  it("actually binds the web server and serves HTTP", async () => {
+    const port = Number(process.env.WEB_PORT);
+    const { startWebServer } = await import("../src/web/server.js");
+    startWebServer();
+    const up = await waitForPortBound(port, 3000);
+    expect(up).toBe(true);
+  });
+
+  it("stopWebServer releases the port", async () => {
+    const port = Number(process.env.WEB_PORT);
+    const { startWebServer, stopWebServer } = await import("../src/web/server.js");
+    startWebServer();
+    expect(await waitForPortBound(port, 3000)).toBe(true);
+    await stopWebServer();
+
+    // Port should now be free — a fresh bind must succeed
+    const reuse = http.createServer();
+    await new Promise<void>((resolve, reject) => {
+      reuse.once("error", reject);
+      reuse.listen(port, () => resolve());
+    });
+    await new Promise<void>((r) => reuse.close(() => r()));
+  });
+
+  it("stopWebServer is idempotent — safe to call multiple times", async () => {
+    const { startWebServer, stopWebServer } = await import("../src/web/server.js");
+    startWebServer();
+    await new Promise((r) => setTimeout(r, 200));
+    await stopWebServer();
+    // Second call must not throw
+    await expect(stopWebServer()).resolves.toBeUndefined();
+    // Third call must also not throw
+    await expect(stopWebServer()).resolves.toBeUndefined();
+  });
+
+  it("stopWebServer is safe to call before startWebServer ever bound", async () => {
+    const { stopWebServer } = await import("../src/web/server.js");
+    // Module just imported — nothing started yet
+    await expect(stopWebServer()).resolves.toBeUndefined();
+  });
+
+  it("when the primary port is taken, startWebServer still returns cleanly (climbs the ladder)", async () => {
+    const originalPort = Number(process.env.WEB_PORT);
+    // Plant a hog on the primary port BEFORE startWebServer
+    const hog = http.createServer();
+    await new Promise<void>((r) => hog.listen(originalPort, () => r()));
+
+    try {
+      const { startWebServer } = await import("../src/web/server.js");
+      // Must NOT throw even though the port is occupied
+      expect(() => startWebServer()).not.toThrow();
+
+      // The bot should have climbed the ladder — one port higher should
+      // now be serving HTTP.
+      const climbed = await waitForPortBound(originalPort + 1, 3000);
+      expect(climbed).toBe(true);
+    } finally {
+      await new Promise<void>((r) => hog.close(() => r()));
+    }
+  });
+
+  it("closeHttpServerGracefully closes a server that's holding an open socket", async () => {
+    const { closeHttpServerGracefully } = await import("../src/web/server.js");
+    const port = await getFreePort();
+    const server = http.createServer((_req, res) => {
+      res.writeHead(200, { "Content-Type": "text/plain" });
+      res.write("chunk");
+      // never res.end — client hangs forever
+    });
+    await new Promise<void>((r) => server.listen(port, () => r()));
+
+    const req = http.get(`http://127.0.0.1:${port}/hang`);
+    req.on("error", () => { /* expected */ });
+    await new Promise((r) => setTimeout(r, 100));
+
+    const t0 = Date.now();
+    await closeHttpServerGracefully(server);
+    expect(Date.now() - t0).toBeLessThan(2000);
+
+    // Port is reusable
+    const reuse = http.createServer();
+    await new Promise<void>((resolve, reject) => {
+      reuse.once("error", reject);
+      reuse.listen(port, () => resolve());
+    });
+    await new Promise<void>((r) => reuse.close(() => r()));
+  });
+});

package/test/web-server-resilience.test.ts

@@ -0,0 +1,118 @@
+/**
+ * Fix #16 — Web server must never crash the bot.
+ *
+ * Colleague feedback (WhatsApp voice note, 2026-04-13):
+ *   > The gateway binds to port 3100 like OpenClaw. When the bot
+ *   > restarts, the port is often still held → catastrophic crash.
+ *   > I ended up decoupling the gateway process completely, because
+ *   > the actual bot runs independently of the gateway — it can still
+ *   > answer Telegram even if the web endpoint isn't reachable yet.
+ *   > It's weird that the main routine crashes when the port is busy.
+ *   > It should just run in the background, watch for the port to
+ *   > become free, and connect then. Zero impact on the main routine.
+ *
+ * This file tests the pure decision helper that the new startWebServer
+ * uses to choose between "try the next port immediately" and "retry
+ * the default port in the background after a delay".
+ *
+ * Contract:
+ *   decideNextBindAction(err, attempt, opts)
+ *
+ *   err.code = "EADDRINUSE", attempt < maxPortTries
+ *     → { type: "retry-port", port: opts.originalPort + attempt + 1, attempt: attempt + 1 }
+ *
+ *   err.code = "EADDRINUSE", attempt >= maxPortTries
+ *     → { type: "retry-background", delayMs: opts.backgroundRetryMs, port: opts.originalPort }
+ *
+ *   err.code = anything else (EACCES, ECONNRESET, "Listen method called twice"…)
+ *     → { type: "retry-background", delayMs: opts.backgroundRetryMs, port: opts.originalPort }
+ *
+ *   Pure function, no side effects, no timers, no I/O.
+ */
+import { describe, it, expect } from "vitest";
+import { decideNextBindAction } from "../src/web/bind-strategy.js";
+
+const defaultOpts = {
+  originalPort: 3100,
+  maxPortTries: 20,
+  backgroundRetryMs: 30_000,
+};
+
+describe("decideNextBindAction (Fix #16)", () => {
+  it("retries on the next port when EADDRINUSE and attempts remain", () => {
+    const err = Object.assign(new Error("EADDRINUSE"), { code: "EADDRINUSE" });
+    const result = decideNextBindAction(err, 0, defaultOpts);
+    expect(result).toEqual({ type: "retry-port", port: 3101, attempt: 1 });
+  });
+
+  it("walks the port ladder across multiple attempts", () => {
+    const err = Object.assign(new Error("EADDRINUSE"), { code: "EADDRINUSE" });
+    expect(decideNextBindAction(err, 5, defaultOpts)).toEqual({
+      type: "retry-port",
+      port: 3106,
+      attempt: 6,
+    });
+    expect(decideNextBindAction(err, 18, defaultOpts)).toEqual({
+      type: "retry-port",
+      port: 3119,
+      attempt: 19,
+    });
+  });
+
+  it("switches to background retry when all port attempts are exhausted", () => {
+    const err = Object.assign(new Error("EADDRINUSE"), { code: "EADDRINUSE" });
+    const result = decideNextBindAction(err, 19, defaultOpts); // 20th failure
+    expect(result).toEqual({
+      type: "retry-background",
+      delayMs: 30_000,
+      port: 3100,
+    });
+  });
+
+  it("goes straight to background retry on non-EADDRINUSE errors", () => {
+    const err = Object.assign(new Error("EACCES"), { code: "EACCES" });
+    const result = decideNextBindAction(err, 0, defaultOpts);
+    expect(result).toEqual({
+      type: "retry-background",
+      delayMs: 30_000,
+      port: 3100,
+    });
+  });
+
+  it("handles errors without a .code field by doing background retry", () => {
+    const err = new Error("Listen method has been called more than once");
+    const result = decideNextBindAction(err, 3, defaultOpts);
+    expect(result.type).toBe("retry-background");
+    if (result.type === "retry-background") {
+      expect(result.port).toBe(3100);
+    }
+  });
+
+  it("respects custom maxPortTries", () => {
+    const err = Object.assign(new Error("EADDRINUSE"), { code: "EADDRINUSE" });
+    const opts = { ...defaultOpts, maxPortTries: 3 };
+    // attempts 0, 1 still retry; attempt 2 is the LAST retry; attempt 3 -> background
+    expect(decideNextBindAction(err, 0, opts).type).toBe("retry-port");
+    expect(decideNextBindAction(err, 1, opts).type).toBe("retry-port");
+    expect(decideNextBindAction(err, 2, opts).type).toBe("retry-background");
+  });
+
+  it("respects custom backgroundRetryMs", () => {
+    const err = Object.assign(new Error("EACCES"), { code: "EACCES" });
+    const opts = { ...defaultOpts, backgroundRetryMs: 5_000 };
+    const result = decideNextBindAction(err, 0, opts);
+    expect(result).toEqual({
+      type: "retry-background",
+      delayMs: 5_000,
+      port: 3100,
+    });
+  });
+
+  it("is pure — same input, same output, no mutation", () => {
+    const err = Object.assign(new Error("EADDRINUSE"), { code: "EADDRINUSE" });
+    const snapshot = JSON.stringify({ ...defaultOpts });
+    decideNextBindAction(err, 5, defaultOpts);
+    decideNextBindAction(err, 5, defaultOpts);
+    expect(JSON.stringify({ ...defaultOpts })).toBe(snapshot);
+  });
+});

package/test/web-server-shutdown.test.ts

@@ -17,7 +17,13 @@
 import { describe, it, expect } from "vitest";
 import http from "http";
 import { once } from "events";
-import { startWebServer, stopWebServer } from "../src/web/server.js";
+// Fix #1 shipped as stopWebServer(server) — Fix #16 (v4.9.4) promoted
+// that to `closeHttpServerGracefully(server)` and reserved the name
+// `stopWebServer()` for the module-state-aware shutdown. The underlying
+// contract (close an http.Server even when clients hold open sockets,
+// release the port, idempotent, never throw) is unchanged — these
+// tests now exercise the renamed helper.
+import { closeHttpServerGracefully as stopWebServer } from "../src/web/server.js";
 
 function getFreePort(): Promise<number> {
   return new Promise((resolve, reject) => {