alvin-bot 5.0.0 → 5.1.0

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [5.1.0] — 2026-05-13
+
+### Permissions Wizard — guided one-and-done macOS setup
+
+macOS' TCC framework architecturally **refuses** to let any app grant Full Disk Access / Automation / Accessibility programmatically — only the user can flip those switches in System Settings. There is no API, no AppleScript trick, no sudo bypass for a normal Node CLI.
+
+What we can do — and what 5.1.0 does — is make the toggling experience painless:
+
+1. **Detect** every permission's current state (sudo + FDA + Automation + Accessibility)
+2. For each missing one: **open the exact right Settings pane**
+3. **Poll for the toggle** every 2 s, up to 60 s per permission
+4. **Verify** and move to the next
+5. End with a clear summary of granted / skipped / still-missing
+
+```bash
+alvin-bot permissions status           # quick state-of-the-world
+alvin-bot permissions wizard           # interactive guided setup
+alvin-bot permissions open <id>        # open one Settings pane
+```
+
+The wizard also bundles **sudo-password storage** (Keychain on macOS, encrypted file on Linux) as the first step, so users get a single upfront onboarding flow instead of separate prompts later. Run-once intent: no more piecemeal permission requests at runtime.
+
+### New detections
+
+- **Automation (Apple Events)** — probes via `osascript -e 'tell application "System Events" to ...'`, catches error code 1743 / "Not authorized" to distinguish denied vs granted. Used by Apple Mail, Apple Notes, Calendar skills.
+- **Accessibility** — now distinguishes "cliclick not installed" from "permission denied", so the wizard suggests the actually-correct fix (install via brew vs. toggle in Settings).
+
+### Doctor integration
+
+`alvin-bot doctor` now uses the same wizard service for its macOS-permissions section — shows all 4 permissions instead of just FDA, points to the wizard for any missing ones.
+
+### Telegram `/setup` integration
+
+`/setup` keyboard gets a new **🛡️ Permissions Wizard (Mac)** button — surfaces the current 4-permission status and the CLI / WebUI commands to actually run the wizard. Mobile UX is intentionally read-only: the wizard needs to drive System Settings panes on the host, which only the local CLI/WebUI can do.
+
+### README — comprehensive CLI section refresh
+
+Documented commands added: `tools`, `provider`, `permissions`, `browser`, `status`. Plus the full env-var opt-out table for Self-Preservation Phase 1 + 2 (`ALVIN_DISABLE_*`, `ALVIN_DEADMAN_THRESHOLD_SEC`, etc.). The README CLI section was missing six commands shipped in 4.23 — 5.0; now matches reality.
+
+### Honest about what we CAN'T do
+
+The README and wizard are explicit about this: macOS TCC permissions cannot be granted by an app. The wizard opens panes and verifies after; the user toggles. No tricks, no entitlement bypass attempts.
+
 ## [5.0.0] — 2026-05-13
 
 ### Self-Preservation Phase 2 — the bot now reasons about its own failures

package/README.md

@@ -527,21 +527,105 @@ Drop your own `<name>/SKILL.md` into `~/.alvin-bot/skills/` for hot-reload. List
 
 ## 🛠️ CLI
 
+### Core lifecycle
+
+```bash
+alvin-bot setup           # Interactive setup wizard (Telegram + AI provider + tools)
+alvin-bot start           # Start the bot in background (launchd on macOS, pm2 elsewhere)
+alvin-bot start -f        # Start in foreground (for debugging)
+alvin-bot stop            # Stop the running bot
+alvin-bot status          # Show version + LaunchAgent / pm2 state (offline)
+alvin-bot doctor          # Health check — config, provider, memory, permissions
+alvin-bot update          # Pull latest from npm (or git if running from source)
+alvin-bot version         # Show version
+```
+
+### Interactive chat
+
+```bash
+alvin-bot tui             # Terminal chat UI with streaming + ANSI colors ✨
+alvin-bot chat            # Alias for tui
+alvin-bot tui --lang de   # Force German UI
+```
+
+### AI provider management (since 4.24.0)
+
+Switch between Claude SDK / Codex CLI / Groq / Gemini / OpenAI / OpenRouter / NVIDIA NIM / offline Gemma 4 without re-running the full setup wizard. The switch command runs the same install + auth flow the wizard uses (CLI install + OAuth login for `claude-sdk` / `codex-cli`, API-key prompt + live validation for the rest), then does a byte-preserving merge of `~/.alvin-bot/.env` — the previous provider's API key is **parked, not deleted**, so rollback is one un-comment away.
+
+```bash
+alvin-bot provider list                # Show all providers + per-provider install/key status
+alvin-bot provider show                # Detailed info on the currently configured provider
+alvin-bot provider switch <key>        # Switch (interactive setup + .env merge + bot restart)
+alvin-bot provider doctor              # Validate current provider's auth against its API
+```
+
+`<key>` accepts canonical slugs **or** short aliases: `claude`, `codex`, `gemini`, `nvidia`, `gpt`, `gemma`.
+
+### Optional tools — install / update (since 4.23.0)
+
+A curated set of universally useful CLIs that unlock specific skills. Bootstrap tools (`yt-dlp`, `ffmpeg`, and `wacli` if WhatsApp is enabled) are auto-installed/updated by `setup` and `update`; the rest you opt into through the menu.
+
+```bash
+alvin-bot tools list                   # Show installed / missing optional tools
+alvin-bot tools install                # Interactive menu — pick which to install
+```
+
+### macOS permissions wizard (since 5.1.0)
+
+macOS' TCC framework refuses to let any app grant Full Disk Access / Automation / Accessibility programmatically — only the user can flip those switches. The wizard makes the toggling experience painless: it detects every permission's current state, opens the **exact right Settings pane** for each missing one, waits for you to toggle (polling every 2 s for up to 60 s per permission), verifies, and moves on. Bundles sudo-password storage in the same upfront flow.
+
+```bash
+alvin-bot permissions status           # Quick status: all 4 permissions + current state
+alvin-bot permissions wizard           # Interactive guided setup, one-and-done
+alvin-bot permissions open <id>        # Open one Settings pane (full-disk-access / automation / accessibility)
+alvin-bot perms                        # alias for permissions
+```
+
+### LaunchAgent (macOS only)
+
+```bash
+alvin-bot launchd install              # Write ~/Library/LaunchAgents/com.alvinbot.app.plist + load
+                                       # (Also installs the dead-man-switch companion plist since 4.26.0)
+alvin-bot launchd status               # Show PID + recent stdout/stderr from the LaunchAgent
+alvin-bot launchd uninstall            # Unload + remove both plists
+```
+
+### Browser automation (bot-managed Chromium)
+
+```bash
+alvin-bot browser start                # Launch Chromium with CDP, persistent profile
+alvin-bot browser start headful        # Same, visible (for login flows)
+alvin-bot browser goto <url>           # Open URL, return JSON metadata
+alvin-bot browser shot <url> [file]    # Screenshot → ~/.alvin-bot/browser/screenshots/
+alvin-bot browser eval <url> "<js>"    # Run JS in page context
+alvin-bot browser tabs                 # List open tabs
+alvin-bot browser status               # PID + CDP endpoint
+alvin-bot browser stop                 # Quit Chromium
+alvin-bot browser doctor               # Diagnose Chromium / Playwright setup
+```
+
+### Maintenance & introspection
+
+```bash
+alvin-bot audit                        # Security health check — permissions, secrets, config
+alvin-bot search "<query>"             # Search assets, memories, and skills index
+```
+
+### Environment-variable opt-outs (Self-Preservation features since 4.26.0 / 5.0.0)
+
+Granular opt-out for the resilience subsystems — everything is enabled by default:
+
 ```bash
-alvin-bot setup     # Interactive setup wizard
-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 (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
+ALVIN_DISABLE_SELF_PRESERVATION=true   # Kill ALL Phase-1 + Phase-2 features below
+ALVIN_DISABLE_PREFLIGHT=true           # Skip startup sanity check (Telegram, provider, SQLite, disk)
+ALVIN_DISABLE_CRITICAL_NOTIFY=true     # Skip cross-channel alerts (Telegram + macOS notif + file flag)
+ALVIN_DISABLE_DEAD_MAN=true            # Skip the zombie-detection heartbeat writer
+ALVIN_DISABLE_AUTO_DIAGNOSTIC=true     # Skip forensic-bundle writing on crash
+ALVIN_DISABLE_SELF_DIAGNOSIS=true      # Skip AI analysis of forensic bundles at startup
+ALVIN_DISABLE_TRENDS=true              # Skip daily trend snapshots + AI anomaly detection
+ALVIN_DEADMAN_THRESHOLD_SEC=600        # Dead-man's-switch staleness threshold (default 10 min)
+ALVIN_TRENDS_INTERVAL_HOURS=24         # Trend-snapshot cadence (default 24 h)
+ALVIN_TRENDS_AI_AFTER_DAYS=7           # Days of history before AI anomaly detection kicks in
 ```
 
 ---

package/bin/cli.js

@@ -2538,17 +2538,32 @@ async function doctor() {
   }
 
   // ── macOS permissions (TCC) ────────────────────────────────────────────
+  // 5.1.0 — superseded by the permissions-wizard service, which checks
+  // all four (sudo + FDA + Automation + Accessibility) and gives the
+  // user a single command to fix anything missing. The legacy FDA-only
+  // block stays as a fast-path summary for users who haven't yet run
+  // the wizard.
   if (process.platform === "darwin") {
     console.log("\n  macOS permissions:");
-    const fda = checkMacosFullDiskAccess(process.execPath);
-    if (fda.hasFDA) {
-      console.log(`  ✅ Full Disk Access — granted to ${fda.realNodePath}`);
-    } else {
-      console.log(`  ⚠️  Full Disk Access NOT granted to node (${fda.realNodePath})`);
-      console.log(`     Spawned tools (codex CLI, file-reading skills) may silently fail`);
-      console.log(`     to read protected directories under launchd. To fix:`);
-      console.log(`       open "${fda.paneUrl}"`);
-      console.log(`     and add the path above with the "+" button.`);
+    try {
+      const { readPermissionsSnapshot, formatPermissionsSnapshot } = await import("../dist/services/permissions-wizard.js");
+      const snaps = await readPermissionsSnapshot();
+      console.log(formatPermissionsSnapshot(snaps));
+      const missing = snaps.filter(s => s.state === "missing" || s.state === "tool-missing").length;
+      if (missing > 0) {
+        console.log(`\n  ${missing} permission${missing === 1 ? "" : "s"} need attention. Run:`);
+        console.log("       alvin-bot permissions wizard");
+      }
+    } catch (err) {
+      // Fall back to the legacy FDA-only check if the wizard module
+      // is unavailable for any reason.
+      const fda = checkMacosFullDiskAccess(process.execPath);
+      if (fda.hasFDA) {
+        console.log(`  ✅ Full Disk Access — granted to ${fda.realNodePath}`);
+      } else {
+        console.log(`  ⚠️  Full Disk Access NOT granted to node (${fda.realNodePath})`);
+        console.log(`     To fix:  open "${fda.paneUrl}"  →  add ${fda.realNodePath}`);
+      }
     }
   }
 
@@ -3102,6 +3117,76 @@ switch (cmd) {
     }
     break;
   }
+  case "permissions":
+  case "perms": {
+    const sub = (process.argv[3] || "status").toLowerCase();
+    (async () => {
+      const { readPermissionsSnapshot, formatPermissionsSnapshot, runPermissionsWizard, PERMISSIONS } = await import("../dist/services/permissions-wizard.js");
+      if (sub === "status" || sub === "ls" || sub === "list") {
+        const snaps = await readPermissionsSnapshot();
+        console.log("\n🛡️  Permissions status\n");
+        console.log(formatPermissionsSnapshot(snaps));
+        const missing = snaps.filter(s => s.state === "missing" || s.state === "tool-missing").length;
+        console.log("");
+        if (missing > 0) {
+          console.log(`  ${missing} missing — run:  alvin-bot permissions wizard`);
+        } else {
+          console.log("  All applicable permissions granted.");
+        }
+        console.log("");
+      } else if (sub === "wizard" || sub === "grant" || sub === "setup") {
+        const yes = ["y","yes","j","ja"];
+        await runPermissionsWizard({
+          print: (t) => console.log(t),
+          confirm: async (q) => {
+            const a = (await ask(`${q} (y/n): `)).trim().toLowerCase();
+            return yes.includes(a) || a === "";
+          },
+          promptPassword: async (q) => {
+            // Best-effort: hide password if process.stdin is TTY (we can
+            // toggle echo). Otherwise plain read — acceptable fallback.
+            try {
+              if (process.stdin.isTTY) {
+                process.stdin.setRawMode?.(true);
+              }
+            } catch {}
+            const a = await ask(q);
+            try {
+              process.stdin.setRawMode?.(false);
+            } catch {}
+            return a.trim();
+          },
+        });
+      } else if (sub === "open") {
+        const id = process.argv[4];
+        const perm = PERMISSIONS.find(p => p.id === id);
+        if (!perm || !perm.openPane) {
+          console.log(`Unknown or non-openable permission: ${id}`);
+          console.log("Available: " + PERMISSIONS.filter(p => p.openPane).map(p => p.id).join(", "));
+        } else {
+          const ok = perm.openPane();
+          console.log(ok ? `Opened System Settings → ${perm.name}` : "Could not open Settings.");
+        }
+      } else {
+        console.log("Usage: alvin-bot permissions <status|wizard|open <id>>");
+        console.log("");
+        console.log("  status (default)  — List all permissions + current state");
+        console.log("  wizard            — Interactive guided setup: walks through each missing");
+        console.log("                       permission, opens the right Settings pane, waits for");
+        console.log("                       you to toggle, verifies. macOS-only TCC bits + sudo.");
+        console.log("  open <id>         — Open one specific Settings pane");
+        console.log("                       <id>: full-disk-access | automation | accessibility");
+        console.log("");
+        console.log("Note: macOS does NOT allow apps to grant TCC permissions programmatically.");
+        console.log("The wizard opens the right Settings panes; YOU flip the switches; the wizard");
+        console.log("verifies each one is actually granted before moving on.");
+      }
+    })().then(() => closeRL()).catch((err) => {
+      console.error(err);
+      closeRL();
+    });
+    break;
+  }
   case "provider": {
     const sub = (process.argv[3] || "list").toLowerCase();
     const arg = process.argv[4];
@@ -3494,6 +3579,7 @@ ${t("cli.commands")}
   search    Search your assets, memories, and skills
   tools     List / install optional capability tools (ffmpeg, pandoc, …)
   provider  List / switch AI provider (claude, codex, groq, gemini, …)
+  permissions  Status / wizard for macOS TCC + sudo permissions (alias: perms)
   browser   Manage bot-owned Chromium (start/stop/goto/shot/doctor)
   update    ${t("cli.updateDesc")}
   start     ${t("cli.startDesc")} (background via PM2)

package/dist/handlers/commands.js

@@ -1698,6 +1698,7 @@ export function registerCommands(bot) {
                 .text("🔑 Manage API Keys", "setup:keys").row()
                 .text("📱 Platforms", "setup:platforms").row()
                 .text("🔐 Sudo / Admin Access", "setup:sudo").row()
+                .text("🛡️ Permissions Wizard (Mac)", "setup:permissions").row()
                 .text("🔧 Open Web Dashboard", "setup:web").row();
             await ctx.reply(`⚙️ *Alvin Bot Setup*\n\n` +
                 `*Active Model:* ${activeInfo.name}\n` +
@@ -1854,6 +1855,31 @@ export function registerCommands(bot) {
                     `_The password is securely stored in ${status.storageMethod}._`, { parse_mode: "Markdown" });
                 break;
             }
+            case "permissions": {
+                // 5.1.0 — Permissions Wizard summary. Mobile UX is intentionally
+                // read-only: the wizard itself needs to open System Settings panes
+                // on the host machine, which only the CLI/WebUI can drive. Here
+                // we surface status + tell the user how to run the actual wizard.
+                try {
+                    const { readPermissionsSnapshot } = await import("../services/permissions-wizard.js");
+                    const snaps = await readPermissionsSnapshot();
+                    const icons = { granted: "✅", missing: "❌", "tool-missing": "⚠️", "n/a": "·" };
+                    const lines = snaps.map(s => `${icons[s.state]} *${s.permission.name}* — ${s.state}${s.detail ? "  _(" + s.detail + ")_" : ""}`);
+                    const missing = snaps.filter(s => s.state === "missing" || s.state === "tool-missing").length;
+                    const summary = missing === 0
+                        ? "*All applicable permissions granted.*"
+                        : `*${missing} permission${missing === 1 ? "" : "s"} need attention.*`;
+                    await ctx.editMessageText(`🛡️ *Permissions Status*\n\n${lines.join("\n")}\n\n${summary}\n\n` +
+                        `_macOS doesn't let any app grant TCC permissions on its own — you toggle the switch, the wizard verifies._\n\n` +
+                        `*To run the guided wizard:*\n` +
+                        `• CLI:  \`alvin-bot permissions wizard\` (opens each Settings pane, waits, verifies)\n` +
+                        `• WebUI:  http://localhost:${process.env.WEB_PORT || 3100} → Settings`, { parse_mode: "Markdown" });
+                }
+                catch (err) {
+                    await ctx.editMessageText("🛡️ *Permissions Status*\n\n_Could not load wizard module — try `alvin-bot permissions status` in a terminal._", { parse_mode: "Markdown" });
+                }
+                break;
+            }
             case "web": {
                 await ctx.editMessageText(`🌐 *Web Dashboard*\n\n` +
                     `URL: \`http://localhost:${process.env.WEB_PORT || 3100}\`\n\n` +

package/dist/services/permissions-wizard.js

@@ -0,0 +1,291 @@
+/**
+ * Permissions Wizard (5.1.0).
+ *
+ * Reality check up front: on macOS, TCC (Transparency, Consent, Control)
+ * permissions are architecturally NOT grantable by an app — no API, no
+ * AppleScript, no sudo trick, no signed-entitlement bypass for a normal
+ * Node CLI. The user has to toggle the switches in System Settings.
+ *
+ * What this wizard DOES do — make the toggling experience painless:
+ *
+ *   1. Detect every permission's current state
+ *   2. For each missing one: open the EXACT right Settings pane
+ *   3. Wait for the user to toggle (poll detect every 2 s)
+ *   4. Verify and move to the next
+ *   5. End with a clear summary of granted / skipped / still-missing
+ *
+ * Covered permissions (macOS):
+ *   - sudo password (not TCC; stored in Keychain so brew/apt commands
+ *     don't re-prompt — separate from TCC but bundled here for
+ *     "one upfront onboarding" UX)
+ *   - Full Disk Access (TCC — for protected dirs like ~/Library/Mail,
+ *     ~/Documents when needed by skills/codex)
+ *   - Automation (TCC — for osascript driving Apple Mail/Notes/Calendar)
+ *   - Accessibility (TCC — for cliclick mouse/keyboard automation)
+ *
+ * On Linux: only sudo applies. The wizard reports a no-op for TCC steps.
+ *
+ * Opt-out: set ALVIN_DISABLE_SELF_PRESERVATION=true to silence everything,
+ * but this wizard never runs unless explicitly invoked — no startup hook.
+ */
+import { execSync } from "child_process";
+import os from "os";
+import { getSudoStatus, openSystemSettings, storePassword, verifyPassword, } from "./sudo.js";
+const PLATFORM = os.platform();
+export const PERMISSIONS = [
+    {
+        id: "sudo",
+        name: "Sudo / Admin Access",
+        why: "Lets Alvin run admin commands (brew install, apt-get, etc.) without re-prompting every time.",
+        platforms: ["darwin", "linux"],
+        detect: async (status) => {
+            const s = status ?? (await getSudoStatus());
+            if (!s.configured)
+                return { state: "missing", detail: "password not stored" };
+            if (!s.verified)
+                return { state: "missing", detail: "stored but doesn't authenticate" };
+            return { state: "granted" };
+        },
+    },
+    {
+        id: "full-disk-access",
+        name: "Full Disk Access",
+        why: "Lets `node` (and anything it spawns — codex, file-skills, document tools) read protected directories like ~/Library/Mail, ~/Documents when skills need them.",
+        platforms: ["darwin"],
+        detect: async (status) => {
+            const s = status ?? (await getSudoStatus());
+            if (PLATFORM !== "darwin")
+                return { state: "n/a" };
+            return { state: s.permissions.fullDiskAccess ? "granted" : "missing" };
+        },
+        openPane: () => openSystemSettings("full-disk-access"),
+    },
+    {
+        id: "automation",
+        name: "Automation (Apple Events)",
+        why: "Lets osascript drive Apple Mail, Apple Notes, Calendar, Finder — used by the email-send, apple-notes, and several productivity skills.",
+        platforms: ["darwin"],
+        detect: async (status) => {
+            const s = status ?? (await getSudoStatus());
+            if (PLATFORM !== "darwin")
+                return { state: "n/a" };
+            const a = s.permissions.automation;
+            if (a === null || a === undefined)
+                return { state: "n/a" };
+            return { state: a ? "granted" : "missing" };
+        },
+        openPane: () => openSystemSettings("automation"),
+    },
+    {
+        id: "accessibility",
+        name: "Accessibility",
+        why: "Lets cliclick simulate mouse + keyboard input — used by some browser-automation and UI-testing skills.",
+        platforms: ["darwin"],
+        detect: async (status) => {
+            const s = status ?? (await getSudoStatus());
+            if (PLATFORM !== "darwin")
+                return { state: "n/a" };
+            if (s.accessibilityDetail === "cliclick-missing") {
+                return { state: "tool-missing", detail: "cliclick not installed (brew install cliclick)" };
+            }
+            return { state: s.permissions.accessibility ? "granted" : "missing" };
+        },
+        openPane: () => openSystemSettings("accessibility"),
+        prereq: "brew install cliclick",
+    },
+];
+/**
+ * Read-only — return the current state of every applicable permission.
+ * Used by `permissions status` and by the doctor command.
+ */
+export async function readPermissionsSnapshot() {
+    const status = await getSudoStatus();
+    const out = [];
+    for (const perm of PERMISSIONS) {
+        if (!perm.platforms.includes(PLATFORM)) {
+            out.push({ permission: perm, state: "n/a", detail: `not applicable on ${PLATFORM}` });
+            continue;
+        }
+        const r = await perm.detect(status);
+        out.push({ permission: perm, ...r });
+    }
+    return out;
+}
+/**
+ * Wait up to `timeoutMs` for a permission to flip from missing→granted.
+ * Polls detect() every 2 seconds. Used after openPane() to give the
+ * user time to toggle the switch.
+ */
+async function waitForGrant(perm, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const r = await perm.detect();
+        if (r.state === "granted")
+            return true;
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+    }
+    return false;
+}
+/**
+ * Run the full guided permissions wizard. Sequential per permission.
+ *
+ * Behaviour per permission:
+ *   - already granted → skip silently (one-liner)
+ *   - tool-missing → tell user the prereq, offer to skip
+ *   - missing (TCC) → open Settings pane, wait up to 60 s, verify
+ *   - missing (sudo) → prompt for password, store in Keychain, verify
+ *
+ * The user can decline any step. Nothing is required for the bot to keep
+ * working — degraded skills just won't work until the relevant permission
+ * is granted.
+ */
+export async function runPermissionsWizard(cb) {
+    const result = { granted: [], skipped: [], stillMissing: [], toolMissing: [] };
+    cb.print("\n🛡️  Mac Permissions Wizard");
+    cb.print("─────────────────────────────────────────────────────────");
+    cb.print("macOS doesn't let any app grant TCC permissions on its own —");
+    cb.print("we'll walk you through each toggle. Decline any step you want.");
+    cb.print("");
+    // First read snapshot once so we don't re-probe constantly
+    const initial = await readPermissionsSnapshot();
+    cb.print("Current state:");
+    for (const snap of initial) {
+        const icon = snap.state === "granted" ? "✓" : snap.state === "n/a" ? "·" : "✗";
+        cb.print(`  ${icon} ${snap.permission.name.padEnd(28)}  ${snap.state}${snap.detail ? "  (" + snap.detail + ")" : ""}`);
+    }
+    cb.print("");
+    // ── Sudo step (always first; not TCC, just Keychain) ────────────────
+    const sudoSnap = initial.find((s) => s.permission.id === "sudo");
+    if (sudoSnap && sudoSnap.state !== "granted" && sudoSnap.permission.platforms.includes(PLATFORM)) {
+        cb.print(`\n[1/4] ${sudoSnap.permission.name}`);
+        cb.print(`      ${sudoSnap.permission.why}`);
+        cb.print(`      Status: ${sudoSnap.state}${sudoSnap.detail ? " (" + sudoSnap.detail + ")" : ""}`);
+        const proceed = await cb.confirm("      Set up now?");
+        if (!proceed) {
+            result.skipped.push("sudo");
+        }
+        else {
+            const pw = await cb.promptPassword("      Your macOS account password (stored in Keychain): ");
+            if (!pw) {
+                result.skipped.push("sudo");
+            }
+            else {
+                const stored = storePassword(pw);
+                if (!stored.ok) {
+                    cb.print(`      ❌ Could not store: ${stored.error}`);
+                    result.stillMissing.push("sudo");
+                }
+                else {
+                    const verify = await verifyPassword();
+                    if (verify.ok) {
+                        cb.print(`      ✓ Stored in ${stored.method} and verified.`);
+                        result.granted.push("sudo");
+                    }
+                    else {
+                        cb.print(`      ❌ Wrong password — Keychain entry removed.`);
+                        // storePassword stored it; verifyPassword found it wrong.
+                        // We should revoke to avoid leaving a bogus pw lying around.
+                        try {
+                            const { revokePassword } = await import("./sudo.js");
+                            revokePassword();
+                        }
+                        catch { }
+                        result.stillMissing.push("sudo");
+                    }
+                }
+            }
+        }
+    }
+    else if (sudoSnap?.state === "granted") {
+        cb.print(`[1/4] ${sudoSnap.permission.name}  ✓ already configured`);
+        result.granted.push("sudo");
+    }
+    // ── TCC permissions (Mac only) ──────────────────────────────────────
+    if (PLATFORM !== "darwin") {
+        cb.print("\nNon-macOS platform — TCC permissions are macOS-only. Skipping.");
+        return result;
+    }
+    let i = 2;
+    for (const id of ["full-disk-access", "automation", "accessibility"]) {
+        const perm = PERMISSIONS.find((p) => p.id === id);
+        const snap = initial.find((s) => s.permission.id === id);
+        cb.print(`\n[${i}/4] ${perm.name}`);
+        cb.print(`      ${perm.why}`);
+        cb.print(`      Status: ${snap.state}${snap.detail ? " (" + snap.detail + ")" : ""}`);
+        i++;
+        if (snap.state === "granted") {
+            cb.print(`      ✓ Already granted.`);
+            result.granted.push(id);
+            continue;
+        }
+        if (snap.state === "tool-missing") {
+            cb.print(`      ⚠ Prerequisite missing: ${perm.prereq || "(no install hint)"}`);
+            const install = await cb.confirm("      Install the prerequisite now?");
+            if (install && perm.prereq) {
+                try {
+                    execSync(perm.prereq, { stdio: "inherit", timeout: 120_000 });
+                    cb.print(`      ✓ Installed.`);
+                }
+                catch {
+                    cb.print(`      ❌ Install failed.`);
+                    result.toolMissing.push(id);
+                    continue;
+                }
+            }
+            else {
+                result.toolMissing.push(id);
+                continue;
+            }
+        }
+        // Open the Settings pane and wait for toggle
+        if (!perm.openPane) {
+            cb.print(`      (no automatic pane-open for this permission)`);
+            result.stillMissing.push(id);
+            continue;
+        }
+        const proceed = await cb.confirm("      Open System Settings and grant now?");
+        if (!proceed) {
+            result.skipped.push(id);
+            continue;
+        }
+        cb.print(`      → Opening System Settings…`);
+        perm.openPane();
+        cb.print(`      → Waiting up to 60 s for you to toggle the switch (polls every 2 s)…`);
+        cb.print(`      → For Full Disk Access: add the actual node binary —`);
+        cb.print(`         ${getNodeBinaryHint()}`);
+        const granted = await waitForGrant(perm, 60_000);
+        if (granted) {
+            cb.print(`      ✓ Granted.`);
+            result.granted.push(id);
+        }
+        else {
+            cb.print(`      ⏱  Timeout — you can run the wizard again any time.`);
+            result.stillMissing.push(id);
+        }
+    }
+    return result;
+}
+function getNodeBinaryHint() {
+    try {
+        const path = execSync(`readlink -f "$(command -v node)"`, { encoding: "utf-8", timeout: 1000 }).trim();
+        return path || "(could not resolve node binary)";
+    }
+    catch {
+        return "(run: readlink -f \"$(command -v node)\")";
+    }
+}
+/**
+ * Format a snapshot list as a compact human-readable block.
+ * Used by both `permissions status` and the doctor command.
+ */
+export function formatPermissionsSnapshot(snaps) {
+    const lines = [];
+    for (const snap of snaps) {
+        const icon = snap.state === "granted" ? "✓" :
+            snap.state === "tool-missing" ? "⚠" :
+                snap.state === "n/a" ? "·" : "✗";
+        lines.push(`  ${icon} ${snap.permission.name.padEnd(28)}  ${snap.state}` +
+            (snap.detail ? `  — ${snap.detail}` : ""));
+    }
+    return lines.join("\n");
+}

package/dist/services/sudo.js

@@ -218,7 +218,47 @@ export function openSystemSettings(pane) {
     }
 }
 /**
- * Get comprehensive sudo status.
+ * Detect Automation permission on macOS (TCC).
+ *
+ * Method: try to send a benign AppleEvent to System Events. If TCC has
+ * NOT granted the calling binary (typically `node` under launchd)
+ * permission to control System Events, osascript fails with one of:
+ *
+ *   - error 1743 ("Not authorized to send Apple events to ...")
+ *   - "(-1743)" in stderr
+ *   - "errAEEventNotPermitted"
+ *
+ * If TCC grants it, osascript returns a small integer (process count).
+ * Either way, we don't actually care about the count — only that the
+ * call succeeded.
+ *
+ * Returns:
+ *   true  — Automation granted
+ *   false — Automation denied (or never asked, which appears identical)
+ *   null  — non-macOS (no TCC)
+ */
+function detectAutomation() {
+    if (PLATFORM !== "darwin")
+        return null;
+    try {
+        execSync(`osascript -e 'tell application "System Events" to count of processes' 2>&1`, { stdio: "pipe", timeout: 3000 });
+        return true;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        // Either way, treat as "not granted". The error path is fast; we
+        // don't want to wedge startup on this probe.
+        if (msg.includes("1743") || /[Nn]ot authoriz/i.test(msg) || /errAEEventNotPermitted/.test(msg)) {
+            return false;
+        }
+        // Other error (e.g. osascript itself missing — very unlikely on macOS)
+        // — treat as unknown but bias false to surface the issue.
+        return false;
+    }
+}
+/**
+ * Get comprehensive sudo + permissions status. Used by both the
+ * `/sudo` command and the new permissions wizard.
  */
 export async function getSudoStatus() {
     const configured = retrievePassword() !== null;
@@ -230,15 +270,33 @@ export async function getSudoStatus() {
     }
     // Check macOS permissions
     let accessibility = null;
+    let accessibilityDetail = "n/a";
     let fullDiskAccess = null;
+    let automation = null;
     if (PLATFORM === "darwin") {
+        // Accessibility — distinguish "denied" from "tool not installed".
+        // cliclick is the standard probe; if it's missing the test is
+        // inconclusive but we can tell the wizard exactly what to do.
+        let cliclickPresent = false;
         try {
-            // Check Accessibility (approximate — try to use cliclick)
-            execSync("cliclick p:.", { stdio: "pipe", timeout: 3000 });
-            accessibility = true;
+            execSync("command -v cliclick", { stdio: "pipe", timeout: 1000 });
+            cliclickPresent = true;
         }
-        catch {
+        catch { }
+        if (!cliclickPresent) {
             accessibility = false;
+            accessibilityDetail = "cliclick-missing";
+        }
+        else {
+            try {
+                execSync("cliclick p:.", { stdio: "pipe", timeout: 3000 });
+                accessibility = true;
+                accessibilityDetail = "granted";
+            }
+            catch {
+                accessibility = false;
+                accessibilityDetail = "denied";
+            }
         }
         try {
             // Check Full Disk Access (try to read a protected file)
@@ -248,6 +306,7 @@ export async function getSudoStatus() {
         catch {
             fullDiskAccess = false;
         }
+        automation = detectAutomation();
     }
     return {
         configured,
@@ -255,7 +314,8 @@ export async function getSudoStatus() {
         verified,
         platform: PLATFORM,
         user,
-        permissions: { accessibility, fullDiskAccess },
+        permissions: { accessibility, fullDiskAccess, automation },
+        accessibilityDetail,
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alvin-bot",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "description": "Alvin Bot — Your personal AI agent on Telegram, WhatsApp, Discord, Signal, and Web.",
   "type": "module",
   "main": "dist/index.js",
@@ -16,6 +16,8 @@
     "test:watch": "vitest",
     "test:ui": "vitest --ui",
     "privacy-check": "bash scripts/privacy-check.sh",
+    "audit": "npm audit --audit-level=high",
+    "audit:full": "npm audit",
     "prepublishOnly": "bash scripts/privacy-check.sh",
     "electron:compile": "tsc -p electron/tsconfig.json",
     "electron:dev": "npm run electron:compile && electron .",