alvin-bot 5.0.0 → 5.1.1

package/CHANGELOG.md

@@ -2,6 +2,79 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [5.1.1] — 2026-05-13
+
+### Audit baseline cleanup — 16 → 6 vulnerabilities via safe fixes
+
+Ran `npm audit fix` (no `--force`) on the lockfile. Cleared 10 of 16 findings: the protobufjs top-level (axios pollution, basic-ftp CRLF, fast-uri path traversal, xmldom DoS, hono jsx/cache, ip-address XSS, postcss XSS, follow-redirects header leak, and the protobufjs vuln at the package root — but **not** the nested copy inside `libsignal-node`). No source-code changes; build + privacy clean; vitest passes 542/543 (one pre-existing flaky port-binding test, unrelated to this change).
+
+### Remaining 6 — documented as known/deferred baseline
+
+These are tracked, not blocking, with an honest paper trail in `.github/workflows/security-audit.yml`:
+
+| Sev | Package | Why deferred |
+|---|---|---|
+| critical | `protobufjs@6.8.8` (nested) | Pinned by `@whiskeysockets/libsignal-node` (custom git fork). Forcing an `npm override` to newer protobufjs would touch Signal-Protocol parsing → high breakage risk. Awaits whiskeysockets upstream. **Only reachable with `WHATSAPP_ENABLED=true`** — dead code for the typical user. |
+| high | `electron <=39.8.4` | devDependency only — affects the DMG-build path, not the npm-CLI runtime users. Major bump 35→42 = breaking, scheduled separately when DMG release is next prepared. |
+| moderate × 4 | derived | `@anthropic-ai/sdk` + `claude-agent-sdk` await Anthropic minor; `baileys` + `libsignal-node` carry the protobufjs upstream lag. |
+
+### CI audit workflow — documents the baseline
+
+`.github/workflows/security-audit.yml` keeps `continue-on-error: true` on the audit step (PRs not blocked on the documented baseline), but the workflow header now spells out exactly what's tracked, why each is deferred, and what would unblock removal of the soft-fail flag.
+
+### Stale Dependabot PRs closed
+
+The 8 open Dependabot PRs (#10–#17) were opened against the pre-audit-fix lockfile state. Closed all with a redirect comment; Dependabot will reconsider against the cleaned-up baseline at its next scheduled Monday run. Closing them avoids tedious merge-conflict resolution on each.
+
+### What didn't change
+
+- No source code edits — pure dependency-tree pruning
+- No npm audit fix `--force` — every applied bump is within existing semver ranges
+- Bot runtime behavior identical to 5.1.0; verified on .75 (Pre-Flight green, all permissions detection works, bot online via launchd)
+
+## [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.1",
   "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 .",