alvin-bot 4.6.0 → 4.8.0

package/CHANGELOG.md

@@ -2,6 +2,197 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [4.8.0] — 2026-04-11
+
+### ✨ Offline mode — Gemma 4 E4B via Ollama in the setup wizard
+
+Fresh installs on a machine without any AI-provider key can now pick **Offline mode** as the first option in the setup wizard. It runs **Google Gemma 4 E4B** locally via Ollama — no API key, zero running cost, works 100% offline once downloaded.
+
+New in `bin/cli.js`:
+
+- `PROVIDERS[0]` is now `offline-gemma4`, labeled prominently with the `~10 GB one-time download` so users can't miss the size.
+- `setupOfflineGemma4()` helper walks the user through:
+  1. **Warning** about download size (15–70 min depending on connection) and on-disk footprint (~10 GB in `~/.ollama/models`)
+  2. **Confirmation prompt** — if the user declines, the wizard loops back to the normal provider picker (no dead ends)
+  3. **Ollama install** via the official `curl -fsSL https://ollama.com/install.sh | sh` if the `ollama` binary is missing
+  4. **Daemon check** — ensures Ollama is listening, spawns it in the background if not
+  5. **Cache check** — if `gemma4:e4b` is already pulled, skips the download
+  6. **Model pull** with a second confirmation before the 10 GB actually starts, streaming progress output so the user sees every layer land
+- `.env` gets `PRIMARY_PROVIDER=ollama`. The registry's Ollama preset in `src/providers/types.ts` already defaults to `gemma4:e4b`, so no extra environment variable is needed.
+
+macOS + Linux only. Windows users get pointed at https://ollama.com/download.
+
+### ✨ `/version` command + version display in `/status`
+
+- New `/version` command in both **Telegram** and **TUI**. Shows `Alvin Bot vX.Y.Z · Node vN · platform/arch`. Registered in `setMyCommands` so Telegram shows it in the autocomplete menu.
+- `/status` header on Telegram now reads `🤖 Alvin Bot vX.Y.Z` instead of just `Alvin Bot Status`.
+- TUI `/status` header also carries the version.
+- **Bug fix**: `/api/status` used to hard-code `version: "3.0.0"` (a leftover from v3). It now reads `BOT_VERSION` dynamically, so the TUI and Web UI see the actual running version.
+
+Implementation: new `src/version.ts` module reads `package.json` once at module load, exports `BOT_VERSION` as a const. Path resolution uses `import.meta.url` so the cwd can't break it.
+
+### 🐛 `alvin-bot launchd install` preserves other pm2 projects
+
+The initial 4.7.0 release called `pm2 kill` during `launchd install` to stop the pm2 daemon. That's wrong for users who have **other** pm2-managed projects (e.g. `polyseus`) alongside `alvin-bot` — their other work would go down with the switch.
+
+New behavior in `bin/cli.js`:
+
+- Parse `pm2 jlist` JSON to detect (a) whether `alvin-bot` is pm2-managed and (b) whether any other pm2 projects exist.
+- Only run `pm2 delete alvin-bot` — never `pm2 kill`. The daemon keeps running for the other projects.
+- Post-install hint is smarter:
+  - **pm2 now empty** → *"pm2 now has zero managed processes. Remove it with: `npm uninstall -g pm2`"*
+  - **pm2 still has other projects** → *"pm2 still has other projects running — leaving it installed."*
+
+Caught immediately after 4.7.0 shipped when Ali pointed out his Mac mini has `polyseus` in pm2 alongside `alvin-bot` and didn't want it touched.
+
+## [4.7.0] — 2026-04-11
+
+### ✨ Sub-Agents Stufe 2 — live-stream, bounded queue, 24h stats
+
+Stufe 2 of the sub-agents refinement spec lands alongside the same-day 4.6.0 release. Everything here builds on the Stufe 1 foundation and is fully unit-tested (85 passing tests).
+
+#### A4 Live-Stream for user-spawns
+
+`/subagents visibility live` enables a new delivery mode where user-spawned sub-agents stream their text incrementally into a single Telegram message, then post a completion banner as a separate message.
+
+Implementation in `src/services/subagent-delivery.ts`:
+
+- `LiveStream` class with `start()` / `update()` / `finalize()`
+- `start()` posts an initial `⏳ <name> thinking…` placeholder and records its `message_id`
+- `update()` is called on every text chunk from the agent's generator; it coalesces rapid updates via a throttle window of **800 ms** so we never exceed Telegram's edit rate limit. Multiple `update()` calls within the window collapse into a single edit with the latest accumulated text.
+- `finalize()` flushes any pending text, replaces the `thinking…` header with the final body, then sends a new banner message so the user gets a completion notification (edits don't trigger push notifications).
+- The live-stream message uses **plain text** (no `parse_mode`) so half-formed markdown during streaming can never cause an edit to be rejected. The final banner does use markdown.
+
+Wiring in `runSubAgent`:
+
+- Detects `effectiveVisibility === "live"` AND `source === "user"` AND `parentChatId`. Cron and implicit spawns are never live-streamed — cron because there's no interactive watcher, implicit because the parent Claude stream already shows everything inline.
+- Creates the `LiveStream` via `createLiveStream()` before the for-await loop.
+- Calls `liveStream.update(chunk.text)` on every text chunk.
+- Calls `liveStream.finalize(info, result)` after the loop and marks `entry.delivered = true` so `spawnSubAgent.finally()` skips the regular `deliverSubAgentResult` path. If finalize fails, the `delivered` flag stays false and the normal banner delivery fires as a fallback.
+- Falls back to `"banner"` mode transparently if the bot API doesn't support `editMessageText` (e.g. during tests or if `attachBotApi` was never called).
+
+Tests added in `test/subagent-delivery.test.ts`:
+
+- `start` posts an initial placeholder and stores the message_id
+- `update` coalesces rapid calls into a single throttled edit within the 800 ms window
+- `finalize` posts a banner as a new message
+- `createLiveStream` returns `null` when `editMessageText` is missing
+
+#### D3 Bounded priority queue
+
+Previously, hitting `maxParallel` returned a hard reject. Now spawn requests that don't fit run into a **bounded priority queue**:
+
+- Default cap: **20** slots (configurable via `/subagents queue <n>`, clamped to 0–200)
+- Setting cap to 0 disables the queue entirely and restores the old reject-on-full behavior
+- Priority order on drain: **user > cron > implicit**
+- FIFO within each priority class
+- Drains automatically when a running agent finishes — the `runSubAgent.finally()` now calls `drainQueue()` after cleanup
+
+New fields:
+
+- `SubAgentsConfig.queueCap: number` — persisted in `~/.alvin-bot/sub-agents.json`
+- `SubAgentInfo.status: "queued"` — new valid state
+- `SubAgentInfo.queuePosition?: number` — 1-based position in the queue, shown in `/subagents list` as `#N`
+
+Functions in `subagents.ts`:
+
+- `getQueueCap()` / `setQueueCap(n)` — public config accessors
+- `drainQueue()` — called from `runSubAgent.finally()`, pops in priority order and transitions entries from `queued` to `running`
+- `popHighestPriorityQueued()` — internal FIFO-per-priority scan
+- `reindexQueue()` — keeps `SubAgentInfo.queuePosition` in sync after pop/cancel
+- `cancelSubAgent()` now handles queued entries by removing them from the queue without starting `runSubAgent` at all
+- `cancelAllSubAgents()` clears the pending queue before cancelling running agents, so shutdown doesn't spawn anything new
+- `spawnSubAgent()` is split: queue decision first (run immediately vs queue vs reject), then `startRun()` helper starts the background loop
+
+Reject messages stay priority-aware (D4) but now mention queue saturation:
+
+- `user` spawn + pool full + cron/implicit in pool + queue full → *"Alle Slots belegt (N/M), davon X cron/implicit im Hintergrund. Queue voll (Q/C). /subagents list für Details …"*
+- `user` spawn + pool full + user in pool + queue full → *"Alle Slots belegt (N/M) mit eigenen user-Spawns. Queue voll (Q/C). /subagents cancel <name> oder warten."*
+- Non-user spawns + pool + queue full → *"Sub-agent limit reached (N running, Q/C queued). Wait for a running agent to finish or cancel one."*
+
+Tests added in `test/subagents-queue.test.ts`:
+
+- Default cap is 20
+- Clamping (negative → 0, above 200 → 200, fractional floors)
+- Round-trip through disk
+- Third spawn at full pool lands as `status: "queued"` with `queuePosition: 1`
+- Queue drains automatically when a running agent finishes
+- Priority order: user spawns drain before cron at the same moment
+- `cancelSubAgent` removes a queued entry
+
+The existing priority-reject tests now explicitly set `queueCap = 0` to test the old reject path, and a new "queue enabled" test fills both pool and queue before asserting the reject message.
+
+#### H3 24-hour run stats
+
+New module `src/services/subagent-stats.ts` — a simple append-only JSON ring buffer persisted to `~/.alvin-bot/subagent-stats.json`. Each completed sub-agent run appends one entry:
+
+```ts
+{
+  completedAt: number;
+  name: string;
+  source: "user" | "cron" | "implicit";
+  status: "completed" | "timeout" | "error" | "cancelled";
+  durationMs: number;
+  inputTokens: number;
+  outputTokens: number;
+}
+```
+
+On every load or append, entries older than 24 hours are pruned. A hard cap of 5000 entries protects against unbounded growth on high-frequency bots.
+
+Accessors:
+
+- `recordSubAgentRun(info, result)` — called from `runSubAgent.finally()` as a non-blocking side effect. Errors are logged but don't affect delivery.
+- `getSubAgentStats()` — returns a `StatsSummary` with totals, per-source breakdown, and per-status counts.
+
+New Telegram command **`/subagents stats`** renders the summary:
+
+```
+📊 Sub-Agent Stats — last 24h
+
+Total: 44 runs · 165k in / 89k out · 12m
+
+By source:
+  👤 user:     12 runs · 45k in / 22k out
+  ⏰ cron:      8 runs · 31k in / 15k out
+  🔗 implicit: 24 runs · 89k in / 52k out
+
+By status:
+  ✅ completed: 42
+  ⚠️ cancelled: 1
+  ⏱️ timeout:   0
+  ❌ error:     1
+```
+
+The JSON backing file is a deliberate short-term choice. When the SQLite migration lands (already scoped in a separate memory entry as `project_alvinbot_sqlite_migration.md`), we swap the backend without touching `getSubAgentStats()` or `recordSubAgentRun()` — both are designed as a narrow interface.
+
+Tests added in `test/subagent-stats.test.ts`:
+
+- Fresh install returns zeros
+- Recording 3 runs updates totals + per-source breakdown
+- Persistence + reload round-trip
+- Entries older than 24h are pruned on load
+- `byStatus` tracks cancelled/error/timeout separately
+
+### 🖥 CLI: `alvin-bot start` / `stop` now auto-detect LaunchAgent
+
+The `start` and `stop` commands previously always went through pm2. That created a conflict after `alvin-bot launchd install`: the LaunchAgent ran the bot, but `alvin-bot start` would happily spawn a second instance via pm2, and `alvin-bot stop` would try to stop a pm2 process that didn't exist.
+
+Now both commands check for `~/Library/LaunchAgents/com.alvinbot.app.plist` on macOS and switch transparently:
+
+- **`alvin-bot start`** with a LaunchAgent present → `launchctl kickstart -k gui/$UID/com.alvinbot.app` (or `launchctl load -w` if not loaded yet). No pm2 involvement.
+- **`alvin-bot stop`** with a LaunchAgent present → `launchctl unload -w` (doesn't remove the plist, just stops the daemon).
+- **`alvin-bot start`** on macOS without a LaunchAgent → pm2 path + a helpful tip: *"💡 Tip: on macOS with Claude Code, switch to launchd for automatic Keychain access: alvin-bot launchd install"*.
+
+Linux and Windows users are unaffected — they always get the pm2 path.
+
+### 🐛 Other
+
+- `/subagents queue` is registered in the usage string for en/de/es/fr.
+- `/subagents stats` is registered in the usage string for en/de/es/fr.
+- `/subagents visibility` usage now lists `live` as a valid mode.
+- Removed the leftover `alvin-bot-4.5.1.tgz` from the repo root.
+
 ## [4.6.0] — 2026-04-11
 
 ### ✨ Sub-Agents Stufe 1 — context-aware delivery, name-first addressing, shutdown notifications

package/bin/cli.js

@@ -54,6 +54,17 @@ const LOGO = `
 // ── Provider Definitions ────────────────────────────────────────────────────
 
 const PROVIDERS = [
+  {
+    key: "offline-gemma4",
+    name: "🔒 Offline — Gemma 4 E4B (no API key, ~10 GB one-time download)",
+    desc: () => "Works without internet. Runs Google Gemma 4 E4B locally via Ollama. Big first-time download, zero running cost, works forever offline.",
+    free: true,
+    envKey: null,
+    signup: null,
+    model: "gemma4:e4b",
+    needsCLI: false,
+    offline: true,
+  },
   {
     key: "groq",
     name: "Groq (Llama 3.3 70B)",
@@ -117,6 +128,165 @@ const PROVIDERS = [
   },
 ];
 
+// ── Offline mode: Ollama + Gemma 4 E4B ─────────────────────────────────────
+
+/**
+ * Check whether the `ollama` binary is present on PATH.
+ */
+function hasOllama() {
+  try {
+    execSync("ollama --version", { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Install Ollama via the official installer. Prints progress to stdout.
+ * Returns true on success, false on failure.
+ */
+function installOllama() {
+  console.log("\n📥 Installing Ollama (official installer)...");
+  try {
+    if (process.platform === "darwin" || process.platform === "linux") {
+      execSync("curl -fsSL https://ollama.com/install.sh | sh", {
+        stdio: "inherit",
+        timeout: 300_000, // 5 minutes
+      });
+      return hasOllama();
+    } else {
+      console.log("  ❌ Offline mode only supported on macOS and Linux.");
+      console.log("     Windows users: download from https://ollama.com/download");
+      return false;
+    }
+  } catch (err) {
+    console.log(`\n  ❌ Ollama install failed: ${err.message || err}`);
+    console.log("     Try manually: curl -fsSL https://ollama.com/install.sh | sh");
+    return false;
+  }
+}
+
+/**
+ * Ensure the Ollama daemon is running. Spawns it in the background if not.
+ */
+function ensureOllamaServe() {
+  try {
+    // 'ollama list' needs the daemon running
+    execSync("ollama list", { stdio: "pipe", timeout: 5000 });
+    return true;
+  } catch {
+    // Daemon not running — spawn it
+    try {
+      execSync("nohup ollama serve > /tmp/ollama-setup.log 2>&1 &", {
+        stdio: "pipe",
+        shell: "/bin/sh",
+      });
+      // Give it a moment
+      execSync("sleep 2", { stdio: "pipe" });
+      execSync("ollama list", { stdio: "pipe", timeout: 5000 });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+/**
+ * Check whether gemma4:e4b is already pulled into Ollama's model cache.
+ */
+function hasGemma4E4b() {
+  try {
+    const out = execSync("ollama list", { encoding: "utf-8", timeout: 5000 });
+    return /gemma4[:\s].*e4b/i.test(out);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Pull gemma4:e4b from the Ollama registry. Streams progress to stdout.
+ * Returns true on success, false on failure.
+ */
+function pullGemma4E4b() {
+  console.log("\n📥 Downloading gemma4:e4b (~10 GB — this can take 10-30 min)...\n");
+  try {
+    execSync("ollama pull gemma4:e4b", {
+      stdio: "inherit",
+      timeout: 45 * 60_000, // 45 minutes
+    });
+    return hasGemma4E4b();
+  } catch (err) {
+    console.log(`\n  ❌ Pull failed: ${err.message || err}`);
+    return false;
+  }
+}
+
+/**
+ * Full offline-mode setup flow: warn about download size, confirm, install
+ * Ollama if missing, pull the model, verify. Returns true on success,
+ * false if the user bailed or something broke (caller falls back to
+ * interactive provider selection).
+ */
+async function setupOfflineGemma4() {
+  console.log("\n  ⚠️  Offline mode uses Google Gemma 4 E4B via Ollama.");
+  console.log("     • One-time download: ~10 GB");
+  console.log("     • On a 100 Mbps connection: ~15 minutes");
+  console.log("     • On a 20 Mbps connection: ~70 minutes");
+  console.log("     • Disk usage: ~10 GB in ~/.ollama/models");
+  console.log("     • Runs on CPU + GPU via Metal (macOS) / CUDA (Linux)");
+  console.log("     • Works 100% offline once downloaded\n");
+
+  const yesChars = getLocale() === "de" ? ["j", "ja", "y", "yes"] : ["y", "yes"];
+  const proceed = (await ask("  Continue with offline mode? (y/N): ")).trim().toLowerCase();
+  if (!yesChars.includes(proceed)) {
+    console.log("\n  ℹ️  Offline mode declined — returning to provider selection.\n");
+    return false;
+  }
+
+  // Step 1: Ollama binary
+  if (!hasOllama()) {
+    console.log("\n  ℹ️  Ollama not installed.");
+    const installProceed = (await ask("  Install Ollama now? (y/N): ")).trim().toLowerCase();
+    if (!yesChars.includes(installProceed)) {
+      console.log("\n  ℹ️  Offline mode cancelled — Ollama is required.\n");
+      return false;
+    }
+    if (!installOllama()) return false;
+    console.log("  ✅ Ollama installed");
+  } else {
+    console.log("\n  ✅ Ollama already installed");
+  }
+
+  // Step 2: Ensure daemon is running
+  if (!ensureOllamaServe()) {
+    console.log("\n  ⚠️  Could not start Ollama daemon. Try manually:");
+    console.log("     ollama serve");
+    console.log("     (in a separate terminal, then re-run alvin-bot setup)\n");
+    return false;
+  }
+  console.log("  ✅ Ollama daemon responding");
+
+  // Step 3: Model already present?
+  if (hasGemma4E4b()) {
+    console.log("  ✅ gemma4:e4b already downloaded — skipping pull");
+    return true;
+  }
+
+  // Step 4: Pull the model (big download)
+  console.log("\n  📦 gemma4:e4b not in cache yet.");
+  const pullProceed = (await ask("  Start 10 GB download now? (y/N): ")).trim().toLowerCase();
+  if (!yesChars.includes(pullProceed)) {
+    console.log("\n  ℹ️  Pull cancelled. You can run this later:");
+    console.log("     ollama pull gemma4:e4b\n");
+    return false;
+  }
+
+  if (!pullGemma4E4b()) return false;
+  console.log("\n  ✅ gemma4:e4b downloaded and ready\n");
+  return true;
+}
+
 // ── Provider Validation ────────────────────────────────────────────────────
 
 /**
@@ -594,6 +764,32 @@ async function setup() {
 
   console.log(`\n✅ ${t("setup.providerSelected")} ${provider.name}`);
 
+  // ── Offline mode: Gemma 4 E4B via Ollama ────────────────────────
+  // Handled specially because it needs a 10 GB model download, not an
+  // API key. If the user bails out anywhere in the flow, we loop back
+  // to the normal provider picker so setup isn't a dead-end.
+  if (provider.offline) {
+    const ok = await setupOfflineGemma4();
+    if (!ok) {
+      // User declined or something failed — pick a different provider
+      console.log(`\n  Choose a different provider:\n`);
+      for (let i = 0; i < PROVIDERS.length; i++) {
+        if (PROVIDERS[i].offline) continue;
+        const p = PROVIDERS[i];
+        const badge = p.free ? "🆓" : "💰";
+        const premium = p.needsCLI ? " ⭐" : "";
+        console.log(`  ${i + 1}. ${badge} ${p.name}${premium}`);
+      }
+      console.log("");
+      const fallbackChoice = parseInt((await ask(t("setup.yourChoice"))).trim()) || 2;
+      provider = PROVIDERS[Math.max(1, Math.min(fallbackChoice - 1, PROVIDERS.length - 1))];
+      console.log(`\n✅ ${t("setup.providerSelected")} ${provider.name}`);
+    }
+    // Note: if setupOfflineGemma4 succeeded, we skip further API-key
+    // validation below — offline mode doesn't need a key. The .env
+    // write step reads provider.offline and sets PRIMARY_PROVIDER=ollama.
+  }
+
   // ── Validate Provider ────────────────────────────────────────────
 
   // Claude SDK: show requirements upfront
@@ -803,13 +999,17 @@ async function setup() {
   // ── Write .env
   console.log(`\n${t("setup.writingConfig")}`);
 
+  // Offline mode translates to PRIMARY_PROVIDER=ollama — the registry's
+  // ollama preset already points at gemma4:e4b, so no extra env needed.
+  const primaryKey = provider.offline ? "ollama" : provider.key;
+
   const envLines = [
     "# === Telegram ===",
     `BOT_TOKEN=${botToken || ""}`,
     `ALLOWED_USERS=${userId || ""}`,
     "",
     "# === AI Provider ===",
-    `PRIMARY_PROVIDER=${provider.key}`,
+    `PRIMARY_PROVIDER=${primaryKey}`,
   ];
 
   if (provider.envKey && providerApiKey) {
@@ -1261,6 +1461,32 @@ async function launchdInstall() {
     execSync(`launchctl unload -w "${plistPath}"`, { stdio: "pipe" });
   } catch { /* not loaded yet — fine */ }
 
+  // If pm2 is managing an alvin-bot process, tear that one process down.
+  // We deliberately do NOT `pm2 kill` the whole daemon — the user may
+  // have other pm2-managed projects (polyseus, etc.) and we must not
+  // nuke those. Only the alvin-bot entry is removed.
+  let pm2HadAlvinBot = false;
+  let pm2StillHasOtherProcesses = false;
+  try {
+    execSync("pm2 --version", { stdio: "pipe" });
+    // Check whether alvin-bot is currently pm2-managed
+    try {
+      const lsOut = execSync("pm2 jlist", { stdio: ["pipe", "pipe", "pipe"], encoding: "utf-8" });
+      const procs = JSON.parse(lsOut);
+      if (Array.isArray(procs)) {
+        pm2HadAlvinBot = procs.some((p) => p && p.name === "alvin-bot");
+        pm2StillHasOtherProcesses = procs.some((p) => p && p.name !== "alvin-bot");
+      }
+    } catch { /* pm2 jlist can fail on empty list or missing daemon — ignore */ }
+
+    if (pm2HadAlvinBot) {
+      try {
+        execSync("pm2 delete alvin-bot", { stdio: "pipe" });
+        console.log("🧹 Removed alvin-bot from pm2 (other pm2 projects left intact).");
+      } catch { /* already gone */ }
+    }
+  } catch { /* pm2 not installed — nothing to clean up */ }
+
   // Stop any nohup'd bot that might still be running
   try {
     execSync(`pkill -TERM -f 'node.*dist/index.js' || true`, { stdio: "pipe" });
@@ -1289,6 +1515,14 @@ async function launchdInstall() {
   console.log("   the macOS Keychain is automatically unlocked — Claude Code");
   console.log("   OAuth tokens (Max subscription) just work, no SSH keychain");
   console.log("   dance needed anymore.");
+  if (pm2HadAlvinBot && !pm2StillHasOtherProcesses) {
+    console.log("");
+    console.log("💡 pm2 now has zero managed processes. You can remove it entirely:");
+    console.log("      npm uninstall -g pm2");
+  } else if (pm2HadAlvinBot && pm2StillHasOtherProcesses) {
+    console.log("");
+    console.log("💡 pm2 still has other projects running — leaving it installed.");
+  }
   process.exit(0);
 }
 
@@ -1396,40 +1630,93 @@ switch (cmd) {
     const fg = process.argv.includes("--foreground") || process.argv.includes("-f");
     if (fg) {
       import("../dist/index.js");
-    } else {
-      // Start via PM2 (background, survives terminal close, auto-restart on crash)
-      try {
-        execSync("pm2 --version", { stdio: "pipe" });
-      } catch {
-        // PM2 not installed — install it
-        console.log("Installing PM2 for background operation...");
+      break;
+    }
+
+    // On macOS, if a LaunchAgent plist already exists, we're in "launchd
+    // mode" — don't start pm2 in parallel. Reload the LaunchAgent instead
+    // so a plain `alvin-bot start` still works as "bring the bot up".
+    if (process.platform === "darwin") {
+      const { plistPath, label } = launchdPaths();
+      if (existsSync(plistPath)) {
+        console.log(`🚀 Detected existing LaunchAgent (${label})`);
+        console.log(`   Reloading via 'launchctl kickstart -k'...`);
         try {
-          execSync("npm install -g pm2", { stdio: "inherit", timeout: 60000 });
+          execSync(`launchctl kickstart -k gui/$(id -u)/${label}`, {
+            stdio: "inherit",
+            shell: "/bin/zsh",
+          });
         } catch {
-          console.log("Could not install PM2. Starting in foreground instead.");
-          console.log("Tip: Install PM2 manually (npm install -g pm2) to run in background.\n");
-          await import("../dist/index.js");
-          break;
+          // Maybe unloaded — load it fresh
+          try {
+            execSync(`launchctl load -w "${plistPath}"`, { stdio: "inherit" });
+          } catch (err) {
+            console.log(`❌ launchctl load failed: ${err.message}`);
+            process.exit(1);
+          }
         }
+        console.log("\n✅ Bot is running via launchd.");
+        console.log("   Status: alvin-bot launchd status");
+        console.log("   Stop:   alvin-bot stop");
+        console.log("   Logs:   ~/.alvin-bot/logs/alvin-bot.out.log");
+        process.exit(0);
       }
-      const cliPath = resolve(join(import.meta.dirname, "cli.js"));
+    }
+
+    // Fall-through: pm2 path (Linux, Windows, or macOS without LaunchAgent)
+    try {
+      execSync("pm2 --version", { stdio: "pipe" });
+    } catch {
+      console.log("Installing PM2 for background operation...");
       try {
-        // Stop existing instance if running
-        execSync("pm2 delete alvin-bot", { stdio: "pipe" });
-      } catch { /* not running — fine */ }
-      execSync(`pm2 start "${cliPath}" --name alvin-bot -- start --foreground`, {
-        stdio: "inherit",
-        timeout: 15000,
-      });
-      console.log("\n✅ Bot is running in the background.");
-      console.log("   Logs:    pm2 logs alvin-bot");
-      console.log("   Stop:    alvin-bot stop");
-      console.log("   Restart: alvin-bot start\n");
-      process.exit(0);
+        execSync("npm install -g pm2", { stdio: "inherit", timeout: 60000 });
+      } catch {
+        console.log("Could not install PM2. Starting in foreground instead.");
+        console.log("Tip: Install PM2 manually (npm install -g pm2) to run in background.\n");
+        await import("../dist/index.js");
+        break;
+      }
     }
-    break;
+    const cliPath = resolve(join(import.meta.dirname, "cli.js"));
+    try {
+      execSync("pm2 delete alvin-bot", { stdio: "pipe" });
+    } catch { /* not running — fine */ }
+    execSync(`pm2 start "${cliPath}" --name alvin-bot -- start --foreground`, {
+      stdio: "inherit",
+      timeout: 15000,
+    });
+    console.log("\n✅ Bot is running in the background via PM2.");
+    console.log("   Logs:    pm2 logs alvin-bot");
+    console.log("   Stop:    alvin-bot stop");
+    console.log("   Restart: alvin-bot start");
+    if (process.platform === "darwin") {
+      console.log("");
+      console.log("   💡 Tip: on macOS with Claude Code, switch to launchd for");
+      console.log("      automatic Keychain access:  alvin-bot launchd install");
+    }
+    console.log("");
+    process.exit(0);
   }
   case "stop": {
+    // On macOS with a LaunchAgent, stopping means unloading the LaunchAgent,
+    // not asking pm2 to stop a process it never managed.
+    if (process.platform === "darwin") {
+      const { plistPath, label } = launchdPaths();
+      if (existsSync(plistPath)) {
+        console.log(`⏹  Stopping LaunchAgent (${label})...`);
+        try {
+          execSync(`launchctl unload -w "${plistPath}"`, { stdio: "inherit" });
+          console.log("✅ LaunchAgent stopped.");
+          console.log("   (The plist is still installed. To remove it: alvin-bot launchd uninstall)");
+        } catch (err) {
+          console.log(`❌ launchctl unload failed: ${err.message}`);
+          process.exit(1);
+        }
+        process.exit(0);
+      }
+    }
+
+    // Fall-through: pm2 path
     try {
       execSync("pm2 stop alvin-bot", { stdio: "inherit", timeout: 10000 });
     } catch {