alvin-bot 4.25.0 → 4.25.1

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [4.25.1] — 2026-05-13
+
+### Fixed: `alvin-bot launchd install` now persists the PM2 cleanup
+
+The launchd installer correctly called `pm2 delete alvin-bot` when migrating a previously-PM2-managed bot to launchd — but `pm2 delete` only mutates the live process list, **not** the persisted `~/.pm2/dump.pm2`. On the next login, PM2's startup script would call `pm2 resurrect`, see alvin-bot in the stale dump, and re-spawn it. The resurrected pm2-managed instance and the new launchd-managed instance then both polled Telegram with the same `BOT_TOKEN`, racking up `409 Conflict: terminated by other getUpdates request` errors until one of them crashed.
+
+The fix adds `pm2 save --force` immediately after `pm2 delete`, so the dump file reflects reality. `--force` is needed because plain `pm2 save` refuses to persist an empty list with a warning. Other PM2-managed processes (e.g. unrelated projects in the user's PM2) are preserved correctly — the save only mutates entries for alvin-bot.
+
+### How it surfaced
+
+A maintainer's local Mac that had been running alvin-bot under PM2 *before* the v4.x migration to launchd hit `409 Conflict` errors out of nowhere — turns out PM2 had been silently resurrecting alvin-bot on every reboot for months (106,000+ restart counter), invocations without args printed help and exited, PM2 restarted it instantly, the cycle continued. Today the cycle accidentally aligned with a Telegram getUpdates call, causing the conflict. Cleanup steps:
+
+```bash
+pm2 delete polyseus                      # any other PM2 entries
+pm2 save --force                         # empty dump
+launchctl unload ~/Library/LaunchAgents/pm2.alvin_de.plist 2>/dev/null
+rm -f ~/Library/LaunchAgents/pm2.alvin_de.plist
+pm2 kill
+npm uninstall -g pm2
+rm -rf ~/.pm2
+```
+
+After this patch, future users migrating from PM2 to launchd via `alvin-bot launchd install` won't accumulate the stale-dump time bomb — the cleanup is persistent immediately.
+
+### End-to-end verified on a real Apple Silicon Mac (.75)
+
+1. Reproduced the broken pre-condition: install PM2, add alvin-bot to its dump via `pm2 start … && pm2 save`. `grep -c alvin-bot ~/.pm2/dump.pm2` → 7 hits.
+2. Ran `alvin-bot launchd install` with the fix applied.
+3. Verified `grep -c alvin-bot ~/.pm2/dump.pm2` → **0 hits**. PM2 live list is also empty.
+
+The installer's output now ends with `🧹 Removed alvin-bot from pm2 and persisted (other pm2 projects left intact).` and includes a `💡 pm2 now has zero managed processes. You can remove it entirely:` hint when no other pm2 projects remain.
+
 ## [4.25.0] — 2026-05-13
 
 ### Auto-bootstrap media tools (yt-dlp + ffmpeg) on every setup and update

package/bin/cli.js

@@ -2743,7 +2743,19 @@ async function launchdInstall() {
     if (pm2HadAlvinBot) {
       try {
         execSync("pm2 delete alvin-bot", { stdio: "pipe" });
-        console.log("🧹 Removed alvin-bot from pm2 (other pm2 projects left intact).");
+        // CRITICAL: `pm2 delete` only mutates the live process list; the
+        // persisted dump (~/.pm2/dump.pm2) keeps a stale copy. Without
+        // `pm2 save --force` here, the next time PM2 resurrects on
+        // login it will re-spawn alvin-bot from the dump — fighting with
+        // the new launchd-managed bot for the same BOT_TOKEN and racking
+        // up Telegram getUpdates 409 conflicts (six-figure restart counts
+        // in extreme cases). `--force` ensures the save runs even when
+        // the resulting list is empty (default `pm2 save` warns and
+        // skips the write on an empty list).
+        try {
+          execSync("pm2 save --force", { stdio: "pipe" });
+        } catch { /* save failed — non-fatal, user has clean live list either way */ }
+        console.log("🧹 Removed alvin-bot from pm2 and persisted (other pm2 projects left intact).");
       } catch { /* already gone */ }
     }
   } catch { /* pm2 not installed — nothing to clean up */ }

package/package.json

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