alvin-bot 4.9.2 → 4.9.4

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.2",
+  "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/cron-progress-ticker.test.ts

@@ -0,0 +1,76 @@
+/**
+ * Fix #15 (B) — /cron run must give visible feedback during long runs.
+ *
+ * Regression from production: a 13-minute Daily Job Alert run showed
+ * the user ZERO feedback between trigger time and completion. The
+ * sub-agent was actually working (and eventually succeeded), but the
+ * Telegram chat was silent for the whole duration.
+ *
+ * This test doesn't exercise grammy directly — it tests the pure
+ * helper that drives the live progress message so we can verify the
+ * formatting, cadence math, and safety edges in isolation.
+ */
+import { describe, it, expect } from "vitest";
+import { formatElapsed, buildTickerText, buildDoneText } from "../src/handlers/cron-progress.js";
+
+describe("formatElapsed (Fix #15B)", () => {
+  it("formats seconds under a minute", () => {
+    expect(formatElapsed(0)).toBe("0s");
+    expect(formatElapsed(45)).toBe("45s");
+    expect(formatElapsed(59)).toBe("59s");
+  });
+
+  it("formats minutes+seconds above a minute", () => {
+    expect(formatElapsed(60)).toBe("1m 0s");
+    expect(formatElapsed(61)).toBe("1m 1s");
+    expect(formatElapsed(125)).toBe("2m 5s");
+    expect(formatElapsed(797)).toBe("13m 17s"); // real prod duration
+  });
+
+  it("formats hours+minutes above 60m", () => {
+    expect(formatElapsed(3600)).toBe("1h 0m");
+    expect(formatElapsed(3660)).toBe("1h 1m");
+  });
+});
+
+describe("buildTickerText (Fix #15B)", () => {
+  it("shows job name and elapsed time in the running state", () => {
+    const text = buildTickerText("Daily Job Alert", 125);
+    expect(text).toContain("Daily Job Alert");
+    expect(text).toContain("2m 5s");
+    expect(text).toMatch(/🔄|running/i);
+  });
+
+  it("escapes markdown-breaking characters in the job name", () => {
+    // Underscores and asterisks in job names would otherwise break
+    // the Markdown edit and trigger "can't parse entities".
+    const text = buildTickerText("weird_job*name", 10);
+    expect(text).not.toContain("_job*"); // no raw unescaped asterisk
+    // We expect some form of escaping — back-slashes are fine
+    expect(text).toMatch(/weird/);
+  });
+});
+
+describe("buildDoneText (Fix #15B)", () => {
+  it("shows green check for a clean completion", () => {
+    const text = buildDoneText("Daily Job Alert", 797, { ok: true });
+    expect(text).toContain("✅");
+    expect(text).toContain("Daily Job Alert");
+    expect(text).toContain("13m 17s");
+  });
+
+  it("shows red cross and error excerpt for a failure", () => {
+    const text = buildDoneText("Daily Job Alert", 10, {
+      ok: false,
+      error: "Sub-agent cancelled: timeout",
+    });
+    expect(text).toContain("❌");
+    expect(text).toContain("timeout");
+  });
+
+  it("shows warning for an already-running skip", () => {
+    const text = buildDoneText("Daily Job Alert", 0, { ok: true, skipped: true });
+    expect(text).toContain("⏳");
+    expect(text).toMatch(/already running|in progress/i);
+  });
+});

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/subagent-delivery-markdown-fallback.test.ts

@@ -0,0 +1,147 @@
+/**
+ * Fix #15 (A) — subagent-delivery must retry without parse_mode when
+ * Telegram rejects the Markdown entities.
+ *
+ * Real regression: Daily Job Alert banners have been silently failing
+ * with "Bad Request: can't parse entities: Can't find end of the entity"
+ * every single day since the subagent-delivery module shipped. The
+ * result text contains mixed `|`, `**`, `\|`, emoji, and asterisks that
+ * Telegram's Markdown parser chokes on. The code currently logs the
+ * error and drops the delivery, so the user never sees the banner.
+ *
+ * Contract: when `sendMessage(..., parse_mode: Markdown)` throws with
+ * the "can't parse entities" pattern, retry the SAME text WITHOUT
+ * `parse_mode`. Any other error still logs + bails.
+ *
+ * This file uses a minimal bot-api stub so we can drive both the happy
+ * path and the parse-error path deterministically.
+ */
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { deliverSubAgentResult, __setBotApiForTest } from "../src/services/subagent-delivery.js";
+import type { SubAgentInfo, SubAgentResult } from "../src/services/subagents.js";
+
+interface Sent {
+  chatId: number;
+  text: string;
+  parseMode?: string;
+}
+
+function makeInfo(overrides: Partial<SubAgentInfo> = {}): SubAgentInfo {
+  return {
+    id: "id-1",
+    name: "Daily Job Alert",
+    status: "completed",
+    startedAt: 0,
+    depth: 0,
+    source: "cron",
+    parentChatId: 42,
+    ...overrides,
+  };
+}
+
+function makeResult(output: string): SubAgentResult {
+  return {
+    id: "id-1",
+    name: "Daily Job Alert",
+    status: "completed",
+    output,
+    tokensUsed: { input: 1000, output: 200 },
+    duration: 60_000,
+  };
+}
+
+beforeEach(() => {
+  __setBotApiForTest(null);
+});
+
+describe("deliverSubAgentResult Markdown fallback (Fix #15)", () => {
+  it("retries without parse_mode when Telegram rejects entity parsing", async () => {
+    const sent: Sent[] = [];
+    let callCount = 0;
+
+    __setBotApiForTest({
+      sendMessage: async (chatId: number, text: string, opts?: Record<string, unknown>) => {
+        callCount++;
+        const parseMode = opts?.parse_mode as string | undefined;
+        // First call (Markdown) throws the real production error
+        if (callCount === 1 && parseMode === "Markdown") {
+          const err = Object.assign(
+            new Error("Call to 'sendMessage' failed! (400: Bad Request: can't parse entities: Can't find end of the entity starting at byte offset 2636)"),
+            {
+              description: "Bad Request: can't parse entities: Can't find end of the entity starting at byte offset 2636",
+              error_code: 400,
+            },
+          );
+          throw err;
+        }
+        sent.push({ chatId, text, parseMode });
+        return { message_id: 1 };
+      },
+      sendDocument: async () => ({}),
+    });
+
+    const info = makeInfo();
+    const result = makeResult("This **has** | broken markdown \\| entities that fail Markdown parsing");
+
+    await deliverSubAgentResult(info, result);
+
+    // Must have retried at least once WITHOUT parse_mode
+    const plainAttempt = sent.find((s) => s.parseMode === undefined);
+    expect(plainAttempt).toBeDefined();
+    expect(plainAttempt?.text).toContain("Daily Job Alert");
+    expect(plainAttempt?.text).toContain("broken markdown");
+  });
+
+  it("does NOT retry for non-parse errors (e.g. chat not found)", async () => {
+    let callCount = 0;
+    __setBotApiForTest({
+      sendMessage: async () => {
+        callCount++;
+        const err = Object.assign(new Error("Forbidden: bot was blocked by the user"), {
+          description: "Forbidden: bot was blocked by the user",
+          error_code: 403,
+        });
+        throw err;
+      },
+      sendDocument: async () => ({}),
+    });
+
+    await deliverSubAgentResult(makeInfo(), makeResult("some text"));
+
+    // Should have tried once and given up — no retry
+    expect(callCount).toBe(1);
+  });
+
+  it("chunked delivery also retries without parse_mode on parse errors", async () => {
+    const sent: Sent[] = [];
+    let callCount = 0;
+
+    __setBotApiForTest({
+      sendMessage: async (chatId: number, text: string, opts?: Record<string, unknown>) => {
+        callCount++;
+        const parseMode = opts?.parse_mode as string | undefined;
+        // First banner attempt fails — should retry without parse_mode
+        if (callCount === 1 && parseMode === "Markdown") {
+          const err = Object.assign(
+            new Error("400: Bad Request: can't parse entities"),
+            { description: "can't parse entities", error_code: 400 },
+          );
+          throw err;
+        }
+        sent.push({ chatId, text, parseMode });
+        return { message_id: callCount };
+      },
+      sendDocument: async () => ({}),
+    });
+
+    const info = makeInfo();
+    // Large body forces the chunked path
+    const result = makeResult("x".repeat(5000));
+
+    await deliverSubAgentResult(info, result);
+
+    // At least one plain-text delivery must have landed
+    expect(sent.length).toBeGreaterThan(0);
+    expect(sent.some((s) => s.parseMode === undefined)).toBe(true);
+  });
+});