alvin-bot 4.5.0 → 4.6.0

package/CHANGELOG.md

@@ -2,6 +2,156 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [4.6.0] — 2026-04-11
+
+### ✨ Sub-Agents Stufe 1 — context-aware delivery, name-first addressing, shutdown notifications
+
+**The big one.** Stufe 1 of the SubAgents refinement spec (9 design axes, two-stage rollout) is complete. Everything here is live-validated on a remote test MacBook via `@Alvin_testbot_bot` over Telegram with Claude Agent SDK + Max OAuth.
+
+#### A4 + I3 — Source-aware delivery router
+
+New module `src/services/subagent-delivery.ts`. Every completed sub-agent routes through a single entry point that picks its delivery path based on `SubAgentInfo.source`:
+
+- `implicit` (Main-Claude calling the SDK `Task` tool) → **no-op**, the parent stream already shows the result.
+- `user` (explicit user spawn) → **banner + final** to `parentChatId` in the originating chat.
+- `cron` (scheduled job) → **banner + final** to the `chatId` from the cron job's target.
+
+The banner format is fixed: `{icon} *{name}* {status} · {duration} · {input_tokens} in / {output_tokens} out` followed by the agent output. Status icons: ✅ completed, ⚠️ cancelled, ⏱️ timeout, ❌ error. Duration is human-formatted (`42s`, `3m 12s`). Token counts collapse at 1000 (`4.2k`).
+
+Output chunking:
+- ≤3800 chars → single message `banner + body`
+- 3800–20000 chars → banner alone, then body chunks of 3800 chars each
+- \>20000 chars → banner + the body as a `.md` file upload (via `grammy`'s `InputFile`)
+
+The bot API is attached lazily at startup via `attachBotApi()` so `subagent-delivery.ts` stays free of a circular import on `index.ts`. Test hook `__setBotApiForTest()` lets Vitest inject a fake.
+
+#### New command: `/subagents visibility <auto|banner|silent>`
+
+Per-install persistent visibility setting, written to `~/.alvin-bot/sub-agents.json`. `silent` suppresses the delivery entirely — the result is still stored in the `activeAgents` map and pullable via `/subagents result <name>`. `auto` is the default and falls through to the source-based routing described above.
+
+#### B2 — Name-first addressing with automatic `#N` collision suffixes
+
+`/subagents cancel <name|id>` and `/subagents result <name|id>` now accept names, not just UUIDs. When a new spawn collides with an existing name, the resolver appends `#2`, `#3`, … using the smallest free index. Example: three parallel `review` spawns appear as `review`, `review#2`, `review#3` in `/subagents list`.
+
+Resolution order:
+1. Explicit `#N` suffix (e.g. `review#2`) → exact match wins, never falls through to ambiguity
+2. Base name with a single sibling → that sibling
+3. Base name with multiple siblings **and** `ambiguousAsList: true` opt-in → disambiguation reply listing all candidates
+4. Base name with multiple siblings, no opt-in → first sibling
+5. No name match → UUID prefix (back-compat)
+
+#### C3 — Parent inheritance
+
+Sub-agents now inherit `workingDir` (with `inheritCwd: false` opt-out), `CLAUDE.md` (via `settingSources: ["project"]`), and the registry's provider/model. Conversation history is **not** inherited — the sub-agent reads only its own prompt, which forces clean, self-describing spawn requests and keeps parallel agents from colliding on shared context.
+
+#### D4 — Priority-aware reject messages
+
+Pool is still strictly capped (no preemption), but the error message when it's full now depends on who holds the slots:
+- User spawn + background (cron/implicit) hold slots → message points at `/subagents list` so the user knows the pool isn't stuck on another interactive task
+- User spawn + other user spawns → suggests cancel-or-wait with command hints
+- Cron/implicit rejects → generic "limit reached" (those callers handle retry themselves)
+
+#### E2 — Shutdown notifications
+
+`cancelAllSubAgents(notify: true)` is now async and fires a delivery to each still-running agent before the process exits. Each notification is a synth `cancelled` result with the body `⚠️ Agent wurde durch Bot-Restart unterbrochen. Bitte neu triggern.` and routes through the normal I3 delivery path. Total delivery phase is capped at 5s so a hanging Telegram send can't block shutdown.
+
+The shutdown hook in `src/index.ts` now `await`s `cancelAllSubAgents(true)` before stopping the grammy bot and tearing down plugins.
+
+#### F2 — Depth cap (hard limit = 2)
+
+`SubAgentConfig.depth` is a new optional field (defaults to 0 = root). `spawnSubAgent` rejects any depth > 2 with a clear error. The depth shows in `/subagents list` as `d0` / `d1` / `d2` with 2-space indentation per level, so nested scatter-gather runs are visually nested.
+
+#### G1 — Toolset preset infrastructure
+
+New `SubAgentConfig.toolset` field with a single valid value `"full"`. Runtime validation rejects any other string. This is purely infrastructure for future `"readonly"` / `"research"` presets — no behavior change today, but adding a preset later is a one-line diff.
+
+#### H2 — Per-run token accounting in the banner
+
+Every completed sub-agent's banner carries the input/output token counts it actually consumed. No aggregation (H3) — that comes later with the SQLite migration. For now, you can see "this agent cost me 4.2k/2.1k" right next to the result.
+
+#### Tests
+
+67 passing Vitest tests across 12 files. New test files added for this release:
+- `test/claude-sdk-provider.test.ts` — auth probe + `isAuthErrorOutput` helper
+- `test/subagents-depth.test.ts` — depth cap (F2)
+- `test/subagents-inheritance.test.ts` — cwd inheritance (C3)
+- `test/subagents-toolset.test.ts` — toolset literal (G1)
+- `test/subagents-name-resolver.test.ts` — `findSubAgentByName` including regression for exact-match vs ambiguity
+- `test/subagents-commands.test.ts` — `cancelSubAgentByName`/`getSubAgentResultByName` helpers
+- `test/subagent-delivery.test.ts` — I3 delivery router (all 5 source/visibility paths)
+- `test/subagents-shutdown.test.ts` — E2 notify=true / notify=false + regression for shutdown double-delivery
+- `test/subagents-priority-reject.test.ts` — D4 priority-aware reject messages
+- `test/subagents-config.test.ts` — expanded with visibility config round-trip
+
+### 🖥 New CLI: `alvin-bot launchd install|uninstall|status` (macOS only)
+
+**Why this matters.** Claude Code 2.x stores the Max-subscription OAuth token in the macOS Keychain, service `"Claude Code-credentials"`. Accessing the token requires:
+1. A Keychain ACL that permits the `claude` binary (granted via the "Always Allow" dialog on first GUI invocation)
+2. An *unlocked* Keychain in the calling process's security context
+
+Processes started via SSH, pm2, or `nohup` run in a detached launchd session that does **not** inherit the GUI user's unlocked-Keychain state. Even a manual `security unlock-keychain -p '...'` only unlocks the current SSH session — the pm2 daemon running in its own context stays locked out. Result: the Bot saw `Not logged in · Please run /login` on every sub-agent query, and the fix in 4.6.0's Phase 0 exposes that as a clean error instead of leaking it as chat text.
+
+**The fix**: run the bot as a **launchd user agent**. LaunchAgents run inside the GUI login session and inherit the unlocked Keychain automatically. No SSH dance, no pm2 drama, no manual unlocks on every restart.
+
+```
+alvin-bot launchd install    — Write ~/Library/LaunchAgents/com.alvinbot.app.plist,
+                                unload any existing instance, launchctl load -w.
+alvin-bot launchd uninstall  — Unload and rm the plist.
+alvin-bot launchd status     — Plist existence, PID from `launchctl list`,
+                                tail of ~/.alvin-bot/logs/alvin-bot.{out,err}.log.
+```
+
+Plist details:
+- `KeepAlive` → auto-restart on crash, not on successful exit
+- `RunAtLoad` → starts on login
+- `ThrottleInterval 10` → prevents rapid restart loops
+- `PATH` covers `~/.local/bin`, `/opt/homebrew/bin` (Apple Silicon), `/usr/local/bin` (Intel Homebrew)
+- stdout → `~/.alvin-bot/logs/alvin-bot.out.log`
+- stderr → `~/.alvin-bot/logs/alvin-bot.err.log`
+
+macOS users should migrate from `alvin-bot start` (pm2) to `alvin-bot launchd install`. Pm2 still works and remains the Linux/Windows default.
+
+### 🐛 Bug fixes
+
+- **`ClaudeSDKProvider.isAvailable()` now actually probes authentication.** The old check only ran `claude --version`, which succeeds whether or not the CLI has a valid OAuth token. A locked-out CLI would be reported as available, and the `Not logged in` response would leak into the chat as a normal assistant message. New behavior: `claude --version` for the binary check, then `claude -p "ping"` to verify auth. If the output matches the "Not logged in" pattern, the provider reports `false` and the registry falls through to the next provider.
+
+- **`ClaudeSDKProvider.query()` surfaces `Not logged in` as an error chunk.** Even in code paths where `isAvailable()` returned stale cache, a runtime failure during the stream would emit `Not logged in · Please run /login` as text. The query loop now detects the auth pattern on the first text chunk and yields a typed `error` chunk with a clear "Run `claude login`" message, instead of pretending it's a normal response.
+
+- **`/subagents cancel|result <name#N>` now hits the exact entry.** Regression caught during the remote test: asking for `test-ping#2` returned the "Mehrdeutig — welchen meinst du?" ambiguity reply instead of the specific `#2` entry, because `findSubAgentByName` checked base-name siblings before the exact-name match when `ambiguousAsList: true` was set. Explicit `#N` queries now always win.
+
+- **Shutdown double-delivery race fixed.** If the bot received SIGTERM while a sub-agent was mid-stream, Telegram saw two messages: a "completed · (empty output)" banner from `runSubAgent.finally()` (because the test generator exited gracefully after the abort), followed by the "cancelled · Bot-Restart" banner from `cancelAllSubAgents`. Fixed with a `delivered: boolean` flag on each `activeAgents` entry — whoever posts first sets it, the other skips.
+
+- **`providerKeyMap` alignment in `src/index.ts`.** The pre-flight provider-key warning used `gemini-2.5-flash` as the map key, but the registry registers Google Gemini under `google`. Users who set `PRIMARY_PROVIDER=google` never saw the "GOOGLE_API_KEY missing" warning. Fixed by canonical `google → GOOGLE_API_KEY`; legacy custom-model aliases stay for rollback safety.
+
+- **`cron.ts` ai-query triple-notification cleanup.** A single failed ai-query cron job was sending three legacy error messages (`slow-fox: cancelled — cancelled`, `AI-Query Error (slow-fox)`, `Cron Error (slow-fox)`) because the failure path fired `notifyCallback` in the inner `if`, the inner `catch`, and the outer `catch`. The I3 delivery router already posts the cancellation banner for ai-query jobs, so all three legacy notify calls are now skipped and ai-query errors propagate via the outer catch for bookkeeping only. Other job types (reminder, shell, http, message) keep the legacy notify path.
+
+- **`/subagents` now shows up in Telegram's command autocomplete.** The grammy handler was registered from v4.0.0 but `setMyCommands` never listed it, so users had to know the exact spelling. Added.
+
+### 📚 Documentation
+
+- New English-language handbook at `docs/HANDBOOK.md` — covers installation, architecture, all providers, the sub-agents system, cron jobs, platform adapters, security audit, and the web UI. Written to be readable standalone without cross-referencing the README.
+- README.md updated with a pointer to the handbook and the new `launchd` command.
+
+## [4.5.1] — 2026-04-09
+
+### 🐛 TUI Header Rendering Hotfix
+
+**The header was appearing inline in the middle of the conversation after scrolling** — a follow-up bug to the 4.5.0 TUI fix. Reported from a live 4.5.0 Test MacBook session where the header popped up right after a long bot response.
+
+**Root cause**: `redrawHeader()` in 4.5.0 used `\x1b[H` (move to top-left) + `\x1b[s`/`\x1b[u` (save/restore cursor) to update the header in place when cost/model/target changed. But `\x1b[H` resolves to the **current viewport top**, not the document top — and once the terminal has scrolled past the original header, the "viewport top" is somewhere in the middle of the conversation. So the header got re-rendered inline in the middle of the bot's output.
+
+**Fix**: removed all `redrawHeader()` calls from mid-session code paths:
+- `ws.on("open")` (connect): no redraw, header was already drawn at startup
+- `ws.on("close")` (disconnect): no redraw, just the error message
+- `case "done"` (after each bot response): no redraw (this was the primary bug site — it fired after every message)
+- `case "model"` (model switch): no redraw, just a success info line
+- `case "target tui|telegram"` (target switch): no redraw, just an info line
+- `process.stdout.on("resize")`: no redraw, just re-renders the prompt line
+
+The only remaining `redrawHeader()` call is inside `/clear`, which calls `console.clear()` first to wipe the whole buffer — the only context where an in-place redraw is safe.
+
+The trade-off: the header no longer reflects live cost/model/target updates mid-session. You'll see the up-to-date values after the next `/clear` or on the next TUI start. In exchange, the conversation flow stays clean. A future release could add a proper status-line region using terminal scrolling regions if this becomes annoying.
+
 ## [4.5.0] — 2026-04-09
 
 ### 🐛 TUI Bug Fixes (critical — the old TUI was effectively unusable)

package/README.md

@@ -109,13 +109,29 @@ alvin-bot start
 
 That's it. The setup wizard validates everything:
 - ✅ Tests your AI provider key
-- ✅ Verifies your Telegram bot token  
+- ✅ Verifies your Telegram bot token
 - ✅ Confirms the setup works before you start
 
 **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.
 
+### macOS: use `launchd` instead of pm2 (recommended)
+
+If you're on macOS and using Claude Code (Max subscription) as your provider, run the bot as a **LaunchAgent** — it inherits the GUI login session so the macOS Keychain stays unlocked and the Claude OAuth token just works without any manual `security unlock-keychain` dance:
+
+```bash
+alvin-bot launchd install    # writes ~/Library/LaunchAgents/com.alvinbot.app.plist and starts the agent
+alvin-bot launchd status     # show PID + recent stdout/stderr logs
+alvin-bot launchd uninstall  # unload + remove the plist
+```
+
+Pm2 still works and remains the default on Linux/Windows — but on macOS with Claude Code, `launchd` is the only path that reliably keeps Keychain access over restarts.
+
+### 📖 Handbook
+
+For a full walkthrough of everything Alvin Bot can do — providers, sub-agents, cron jobs, plugins, MCP, security audit, web UI — read **[`docs/HANDBOOK.md`](docs/HANDBOOK.md)**.
+
 ### AI Providers
 
 | Provider | Cost | Best for |
@@ -436,7 +452,14 @@ alvin-bot tui       # Terminal chat UI ✨
 alvin-bot chat      # Alias for tui
 alvin-bot doctor    # Health check
 alvin-bot update    # Pull latest & rebuild
-alvin-bot start     # Start the bot
+alvin-bot start     # Start the bot (background via pm2)
+alvin-bot start -f  # Start in foreground
+alvin-bot stop      # Stop the bot
+alvin-bot launchd install    # macOS only: install as LaunchAgent
+alvin-bot launchd status     # macOS only: show LaunchAgent state
+alvin-bot launchd uninstall  # macOS only: remove LaunchAgent
+alvin-bot audit     # Security health check
+alvin-bot search    # Search assets/memories/skills
 alvin-bot version   # Show version
 ```
 

package/bin/cli.js

@@ -1153,6 +1153,232 @@ async function version() {
   }
 }
 
+// ── LaunchAgent helpers (macOS only) ────────────────────────────────────────
+
+/**
+ * Render the launchd plist that runs `node dist/index.js` as a per-user
+ * agent. Inherits the GUI login session so the macOS Keychain is
+ * automatically unlocked — which means Claude Code OAuth tokens (Max
+ * subscription) work without a manual `security unlock-keychain`.
+ */
+function renderLaunchdPlist({ label, nodePath, entryPoint, cwd, home, logDir }) {
+  // PATH covers both Apple Silicon and Intel Homebrew plus the legacy
+  // user-local claude binary path.
+  const pathValue = `${home}/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin`;
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${label}</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>${nodePath}</string>
+        <string>${entryPoint}</string>
+    </array>
+
+    <key>WorkingDirectory</key>
+    <string>${cwd}</string>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>KeepAlive</key>
+    <dict>
+        <key>SuccessfulExit</key>
+        <false/>
+        <key>Crashed</key>
+        <true/>
+    </dict>
+
+    <key>ThrottleInterval</key>
+    <integer>10</integer>
+
+    <key>StandardOutPath</key>
+    <string>${logDir}/alvin-bot.out.log</string>
+
+    <key>StandardErrorPath</key>
+    <string>${logDir}/alvin-bot.err.log</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>${pathValue}</string>
+        <key>HOME</key>
+        <string>${home}</string>
+        <key>NODE_ENV</key>
+        <string>production</string>
+    </dict>
+</dict>
+</plist>
+`;
+}
+
+/**
+ * Common paths + label used by all three launchd subcommands.
+ */
+function launchdPaths() {
+  const home = homedir();
+  const label = "com.alvinbot.app";
+  const plistPath = join(home, "Library", "LaunchAgents", `${label}.plist`);
+  const logDir = join(home, ".alvin-bot", "logs");
+  // dist/index.js lives two levels up from bin/cli.js, then dist/
+  const entryPoint = resolve(join(import.meta.dirname, "..", "dist", "index.js"));
+  const cwd = resolve(join(import.meta.dirname, ".."));
+  const nodePath = process.execPath;
+  return { home, label, plistPath, logDir, entryPoint, cwd, nodePath };
+}
+
+async function launchdInstall() {
+  if (process.platform !== "darwin") {
+    console.log("❌ alvin-bot launchd is macOS-only.");
+    console.log("   Linux users: create a systemd user unit for dist/index.js.");
+    console.log("   Windows users: use Task Scheduler or NSSM.");
+    process.exit(1);
+  }
+
+  const { home, label, plistPath, logDir, entryPoint, cwd, nodePath } = launchdPaths();
+
+  // Sanity-check that dist/ is built
+  if (!existsSync(entryPoint)) {
+    console.log(`❌ Build not found at ${entryPoint}`);
+    console.log("   Run 'npm run build' first.");
+    process.exit(1);
+  }
+
+  // Ensure the LaunchAgents dir and log dir exist
+  mkdirSync(join(home, "Library", "LaunchAgents"), { recursive: true });
+  mkdirSync(logDir, { recursive: true });
+
+  // Render and write the plist
+  const plist = renderLaunchdPlist({ label, nodePath, entryPoint, cwd, home, logDir });
+  writeFileSync(plistPath, plist, { mode: 0o644 });
+  console.log(`📝 Wrote ${plistPath}`);
+
+  // Unload any previous instance (best-effort)
+  try {
+    execSync(`launchctl unload -w "${plistPath}"`, { stdio: "pipe" });
+  } catch { /* not loaded yet — fine */ }
+
+  // Stop any nohup'd bot that might still be running
+  try {
+    execSync(`pkill -TERM -f 'node.*dist/index.js' || true`, { stdio: "pipe" });
+  } catch { /* nothing to kill */ }
+
+  // Load fresh
+  try {
+    execSync(`launchctl load -w "${plistPath}"`, { stdio: "inherit" });
+  } catch (err) {
+    console.log(`❌ launchctl load failed: ${err.message}`);
+    console.log("   Try manually: launchctl load -w " + plistPath);
+    process.exit(1);
+  }
+
+  console.log("");
+  console.log("✅ alvin-bot is now a launchd user agent.");
+  console.log(`   Label:   ${label}`);
+  console.log(`   Logs:    ${logDir}/alvin-bot.out.log`);
+  console.log(`   Errors:  ${logDir}/alvin-bot.err.log`);
+  console.log("");
+  console.log("   Status:    alvin-bot launchd status");
+  console.log("   Stop:      alvin-bot launchd uninstall");
+  console.log("   Restart:   launchctl kickstart -k gui/$UID/" + label);
+  console.log("");
+  console.log("   Because launchd runs the bot inside your GUI login session,");
+  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.");
+  process.exit(0);
+}
+
+async function launchdUninstall() {
+  if (process.platform !== "darwin") {
+    console.log("❌ alvin-bot launchd is macOS-only.");
+    process.exit(1);
+  }
+  const { plistPath, label } = launchdPaths();
+  if (!existsSync(plistPath)) {
+    console.log(`⚠️  No LaunchAgent plist at ${plistPath}`);
+    console.log("   Nothing to uninstall.");
+    process.exit(0);
+  }
+
+  try {
+    execSync(`launchctl unload -w "${plistPath}"`, { stdio: "inherit" });
+    console.log(`✅ Unloaded ${label}`);
+  } catch (err) {
+    console.log(`⚠️  Unload reported an error (may not have been running): ${err.message}`);
+  }
+
+  try {
+    execSync(`rm -f "${plistPath}"`);
+    console.log(`🗑  Removed ${plistPath}`);
+  } catch (err) {
+    console.log(`⚠️  Could not remove plist: ${err.message}`);
+  }
+
+  console.log("");
+  console.log("✅ alvin-bot is no longer a launchd user agent.");
+  process.exit(0);
+}
+
+async function launchdStatus() {
+  if (process.platform !== "darwin") {
+    console.log("❌ alvin-bot launchd is macOS-only.");
+    process.exit(1);
+  }
+  const { plistPath, label, logDir } = launchdPaths();
+
+  console.log(`📋 alvin-bot launchd status`);
+  console.log("");
+  console.log(`Label:    ${label}`);
+  console.log(`Plist:    ${plistPath}`);
+  console.log(`Plist exists: ${existsSync(plistPath) ? "yes" : "no"}`);
+  console.log("");
+
+  try {
+    const out = execSync(`launchctl list | grep ${label} || true`, { encoding: "utf-8" });
+    if (out.trim()) {
+      // Format: <PID>\t<ExitCode>\t<Label>
+      const parts = out.trim().split(/\s+/);
+      const pid = parts[0];
+      const exitCode = parts[1];
+      const isRunning = pid !== "-" && pid !== "0";
+      console.log(`Running:  ${isRunning ? "✅ yes (PID " + pid + ")" : "❌ no (last exit " + exitCode + ")"}`);
+    } else {
+      console.log(`Running:  ❌ not loaded`);
+    }
+  } catch {
+    console.log(`Running:  ❌ unknown (launchctl list failed)`);
+  }
+
+  console.log("");
+  console.log(`Log dir:  ${logDir}`);
+  const outLog = join(logDir, "alvin-bot.out.log");
+  const errLog = join(logDir, "alvin-bot.err.log");
+  if (existsSync(outLog)) {
+    try {
+      const tail = execSync(`tail -n 5 "${outLog}"`, { encoding: "utf-8" });
+      console.log("");
+      console.log("── Last 5 lines of stdout ──");
+      console.log(tail.trimEnd());
+    } catch { /* ignore */ }
+  }
+  if (existsSync(errLog)) {
+    try {
+      const tail = execSync(`tail -n 5 "${errLog}"`, { encoding: "utf-8" });
+      const trimmed = tail.trimEnd();
+      if (trimmed) {
+        console.log("");
+        console.log("── Last 5 lines of stderr ──");
+        console.log(trimmed);
+      }
+    } catch { /* ignore */ }
+  }
+  process.exit(0);
+}
+
 // ── CLI Router ──────────────────────────────────────────────────────────────
 
 const cmd = process.argv[2];
@@ -1211,6 +1437,25 @@ switch (cmd) {
     }
     process.exit(0);
   }
+  case "launchd": {
+    const sub = process.argv[3];
+    if (sub === "install") {
+      await launchdInstall();
+    } else if (sub === "uninstall") {
+      await launchdUninstall();
+    } else if (sub === "status") {
+      await launchdStatus();
+    } else {
+      console.log("Usage: alvin-bot launchd <install|uninstall|status>");
+      console.log("");
+      console.log("  install    — Install as a macOS launchd user agent.");
+      console.log("               Runs on login, keychain auto-unlocked.");
+      console.log("  uninstall  — Unload and remove the LaunchAgent plist.");
+      console.log("  status     — Show current launchd state + recent logs.");
+      process.exit(1);
+    }
+    break;
+  }
   case "tui":
   case "chat":
     import("../dist/tui/index.js").then(m => m.startTUI()).catch(console.error);
@@ -1254,6 +1499,7 @@ ${t("cli.commands")}
   start     ${t("cli.startDesc")} (background via PM2)
   start -f  Start in foreground (for debugging)
   stop      Stop the bot
+  launchd   macOS only: install/uninstall/status as launchd user agent
   version   ${t("cli.versionDesc")}
 
 ${t("cli.example")}