alvin-bot 4.22.0 → 4.22.1

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [4.22.1] — 2026-05-09
+
+### Fixed
+
+- **Cron scheduler:** prevent duplicate catch-up runs for already-attempted slots. When a daily/scheduled job fired but crashed before completion, the boot-time catch-up would re-fire it hours later (e.g. an `0 8 * * *` job retried at 11:00 after a 10:51 reboot). The catch-up now skips jobs whose current schedule slot has already been attempted: for cron expressions, `lastAttemptAt >= mostRecentPastTrigger` short-circuits the rewind; for interval schedules, `now - lastAttemptAt < intervalMs` does the same. Crashed runs from *previous* slots within the 6h grace window still catch up as before. New `prevCronRun()` helper in `cron-scheduling.ts`. ([#cron-catchup-bug](src/services/cron-scheduling.ts))
+
 ## [4.22.0] — 2026-05-05
 
 ### 🧠 Memory architecture overhaul: pluggable providers + smart inject

package/README.md

@@ -1,104 +1,49 @@
 # 🤖 Alvin Bot — Autonomous AI Agent
 
-> Your personal AI assistant — on Telegram, WhatsApp, Discord, Signal, Terminal, and Web.
+> Your personal AI agent — on Telegram, WhatsApp, Discord, Slack, Signal, Terminal, and Web.
 
-Alvin Bot is an open-source, self-hosted AI agent that lives where you chat. Built on a multi-model engine with full system access, memory, plugins, and a rich web dashboard. Not just a chatbot — an autonomous agent that remembers, acts, and learns.
+Open-source, self-hosted, multi-model. Lives where you chat, has full shell + filesystem access, remembers across sessions, and dispatches detached sub-agents for long-running work. Built on the Claude Agent SDK with a provider-agnostic engine that also drives OpenAI, Groq, Gemini, NVIDIA NIM, OpenRouter, and Ollama.
 
+> **What's new — v4.22 (May 2026):** Pluggable memory backends — Gemini · OpenAI · Ollama · **FTS5 keyword fallback (zero-config)**. Users without an embedding API key now get a working indexed memory store out of the box. Smart inject mode trims ~25 k tokens per turn off long system prompts. [Full changelog →](CHANGELOG.md)
 
 ---
 
-## 📸 Preview
-
-<table>
-<tr>
-<td align="center"><b>💬 Chat (Dark Mode)</b><br><img src="docs/screenshots/01-Chat-Dark-Conversation.png" width="400"></td>
-<td align="center"><b>📊 Dashboard</b><br><img src="docs/screenshots/03-Dashboard-Overview.png" width="400"></td>
-</tr>
-<tr>
-<td align="center"><b>🤖 AI Models & Providers</b><br><img src="docs/screenshots/04-AI-Models-and-Providers.png" width="400"></td>
-<td align="center"><b>🎭 Personality Editor</b><br><img src="docs/screenshots/05-Personality-Editor.png" width="400"></td>
-</tr>
-<tr>
-<td align="center"><b>💬 Telegram</b><br><img src="docs/screenshots/TG.png" width="400"></td>
-<td align="center"><b>📱 Messaging Platforms</b><br><img src="docs/screenshots/12-Messaging-Platforms.png" width="400"></td>
-</tr>
-<tr>
-<td align="center"><b>🔧 Custom Tools</b><br><img src="docs/screenshots/10-Custom-Tools.png" width="400"></td>
-<td align="center"><b>🩺 Health & Maintenance</b><br><img src="docs/screenshots/15-Maintenance-and-Health.png" width="400"></td>
-</tr>
-</table>
-
-<details>
-<summary><b>🖼️ More Screenshots</b> (click to expand)</summary>
-<br>
-
-| Feature | Screenshot |
-|---------|-----------|
-| Login | <img src="docs/screenshots/00-Login.png" width="500"> |
-| Chat (Light) | <img src="docs/screenshots/02-Chat.png" width="500"> |
-| Memory Manager | <img src="docs/screenshots/06-Memory-Manager.png" width="500"> |
-| Active Sessions | <img src="docs/screenshots/07-Active-Sessions.png" width="500"> |
-| File Browser | <img src="docs/screenshots/08-File-Browser.png" width="500"> |
-| Scheduled Jobs | <img src="docs/screenshots/09-Scheduled-Jobs.png" width="500"> |
-| Plugins & MCP | <img src="docs/screenshots/11-Plugins-and-MCP.png" width="500"> |
-| WhatsApp Groups | <img src="docs/screenshots/12.1-Messaging-Platforms-WhatsApp-Groups-List.png" width="500"> |
-| WA Group Details | <img src="docs/screenshots/12.2-Messaging-Platforms-WA-Group-Details.png" width="500"> |
-| User Management | <img src="docs/screenshots/13-User-Management.png" width="500"> |
-| Web Terminal | <img src="docs/screenshots/14-Web-Terminal.png" width="500"> |
-| Settings & Env | <img src="docs/screenshots/16-Settings-and-Env.png" width="500"> |
-| Telegram Commands | <img src="docs/screenshots/TG-commands.png" width="500"> |
-| macOS Installer | <img src="docs/screenshots/_Mac-Installer.png" width="500"> |
-
-</details>
-
----
-
-
 ## ✨ Features
 
 ### 🧠 Intelligence
-- **Multi-Model Engine** — Claude (Agent SDK with full tool use), OpenAI, Groq, NVIDIA NIM, Google Gemini, OpenRouter, or any OpenAI-compatible API
-- **Automatic Fallback** — If one provider fails, seamlessly tries the next
-- **Heartbeat Monitor** — Pings providers every 5 minutes, auto-failover after 2 failures, auto-recovery
-- **User-Configurable Fallback Order** — Rearrange provider priority via Telegram (`/fallback`), Web UI, or API
-- **Adjustable Thinking** — From quick answers (`/effort low`) to deep analysis (`/effort max`)
-- **Persistent Memory** — Remembers across sessions via vector-indexed knowledge base; session state (Claude SDK resume tokens, conversation history, language, effort) survives bot restarts (v4.11.0)
-- **Multi-Session Workspaces** — Run multiple parallel, context-isolated sessions on the same bot — one per Slack channel or per Telegram `/workspace` — each with its own working directory, purpose, and persona. Memory, skills, and sub-agents stay globally shared (v4.12.0). [How-to ↓](#-multi-session-workspaces-v4120)
-- **Truly Detached Sub-Agents** — Claude dispatches long-running research/audit tasks via the `alvin_dispatch_agent` MCP tool, which spawns independent `claude -p` subprocesses with their own PID + process group. Main session stays fully responsive, user can interrupt freely without killing sub-agents. Results deliver as separate messages. Works identically on Telegram, Slack, Discord, and WhatsApp (v4.13.0+ dispatch, v4.14.0 multi-platform)
-- **Smart Tool Discovery** — Scans your system at startup, knows exactly what CLI tools, plugins, and APIs are available
-- **Skill System** — 12 built-in SKILL.md files (code, data analysis, email, docs, research, sysadmin, browse, etc.) auto-activate based on message context
-- **Self-Awareness** — Knows it IS the AI model — won't call external APIs for tasks it can do itself
-- **Automatic Language Detection** — Detects user language (EN/DE/ES/FR) and adapts; learns preference over time
+- **Multi-model engine** — Claude Agent SDK · OpenAI · Groq · NVIDIA NIM · Gemini · OpenRouter · Ollama · Codex CLI · any OpenAI-compatible API
+- **Automatic fallback + heartbeat monitor** — pings providers every 5 min, auto-failover after 2 failures, auto-recovery; reorder priority via Telegram `/fallback`, Web UI, or API
+- **Adjustable thinking depth** — `/effort low` to `/effort max`
+- **Pluggable memory backends (v4.22)** — Gemini · OpenAI · Ollama · FTS5 keyword fallback. Auto-detection picks the best available. Indexed search across `MEMORY.md`, daily logs, project files, hub memory, asset index. Override via `EMBEDDINGS_PROVIDER`.
+- **Smart system-prompt injection (v4.22)** — once SQLite is populated, stops bulk-injecting `MEMORY.md` and surfaces only the chunks relevant to the user's current message. Cuts ~25 k tokens per turn for typical setups. `MEMORY_INJECT_MODE=auto|legacy|sqlite` to override.
+- **Layered memory (L0–L3)** — `identity.md` + `preferences.md` always plain-text · project memories on topic match · daily logs / curated knowledge via semantic or keyword search
+- **Persistent sessions** — Claude SDK resume tokens, conversation history, language, effort survive bot restarts
+- **Multi-session workspaces** — parallel context-isolated sessions per Slack channel or `/workspace` switch, each with its own cwd, purpose, persona. Memory + skills stay globally shared. [How-to ↓](#-multi-session-workspaces-v4120)
+- **Detached sub-agents** — `alvin_dispatch_agent` MCP tool spawns independent `claude -p` subprocesses that survive parent aborts. Results deliver as separate messages. Works identically on Telegram / Slack / Discord / WhatsApp.
+- **Smart tool discovery** — scans your system at startup; typical install surfaces 30–70 tools depending on what's locally available
+- **Skill system** — 14 SKILL.md files (see [Skills ↓](#-skills)) auto-activate based on message context
+- **Self-awareness + auto-language** — knows it IS the AI · detects EN/DE/ES/FR and adapts; learns preference over time
 
 ### 💬 Multi-Platform
-- **Telegram** — Full-featured with streaming, inline keyboards, voice, photos, documents
-- **Slack** — Socket Mode bot via `@slack/bolt`, DMs + @mentions, file attachments, reactions, `assistant.threads.setStatus` typing indicator. **One channel = one isolated workspace.** See [Multi-Session Workspaces](#-multi-session-workspaces-v4120) below.
-- **WhatsApp** — Via WhatsApp Web: self-chat as AI notepad, group whitelist with per-contact access control, full media support (photos, docs, audio, video)
-- **WhatsApp Group Approval** — Owner gets approval requests via Telegram (or WhatsApp DM fallback) before the bot responds to group messages. Silent — group members see nothing.
-- **Discord** — Server bot with mention/reply detection, slash commands
-- **Signal** — Via signal-cli REST API with voice transcription
-- **Terminal** — Rich TUI with ANSI colors and streaming (`alvin-bot tui`)
-- **Web UI** — Full dashboard with chat, settings, file manager, terminal, workspace overview
+- **Telegram** — streaming, inline keyboards, voice, photos, documents
+- **Slack** — Socket Mode via `@slack/bolt`, DMs + @mentions, file attachments, `assistant.threads.setStatus` typing. **One channel = one isolated workspace.**
+- **WhatsApp** — via WhatsApp Web; self-chat as AI notepad, group whitelist with per-contact access, full media. Owner approval gate routes to Telegram (DM / Discord / Signal fallback) before the bot replies.
+- **Discord** — server bot with mention/reply detection and slash commands
+- **Signal** — via signal-cli REST API, voice transcription
+- **Terminal** — rich TUI with ANSI colors + streaming (`alvin-bot tui`)
+- **Web UI** — full dashboard, chat, settings, file manager, terminal, workspace overview
 
 ### 🔧 Capabilities
-- **52+ Built-in Tools** — Shell, files, email, screenshots, PDF, media, git, system control
-- **Plugin System** — 6 built-in plugins (weather, finance, notes, calendar, email, smarthome)
-- **MCP Client** — Connect any Model Context Protocol server
-- **Cron Jobs** — Scheduled tasks with AI-driven creation ("check my email every morning")
-- **Voice** — Speech-to-text (Groq Whisper) + text-to-speech (Edge TTS)
-- **Vision** — Photo analysis, document scanning, screenshot understanding
-- **Image Generation** — Via Google Gemini / DALL·E (with API key)
-- **Web Browsing** — Fetch and summarize web pages
+- **Tool layer** — Shell · files · Python · git · email · PDF · media · vision · screenshots · system control. Universal tool use across any provider that supports function calling; text-only fallback for those that don't.
+- **6 built-in plugins** — weather · finance · notes · calendar · email · smarthome
+- **MCP client** — connect any Model Context Protocol server
+- **Cron** — AI-driven scheduled tasks (`"check my email every morning"`)
+- **Voice** — STT via Groq Whisper, TTS via Edge TTS or ElevenLabs
+- **Vision + image generation** — photo / document analysis · Gemini / DALL·E generation with API key
+- **Browser** — 4-tier strategy: WebFetch · stealth Playwright · CDP with persistent profile · agent-browser CLI (Tier-1.5, opt-in)
 
 ### 🖥️ Web Dashboard
-- **Live Chat** — WebSocket streaming, same experience as Telegram
-- **Model Switcher** — Change AI models on the fly
-- **Platform Setup** — Configure all messengers and providers via UI, WhatsApp group management inline
-- **File Manager** — Browse, edit, create files in the working directory
-- **Memory Editor** — View and edit the agent's knowledge base
-- **Session Browser** — Inspect conversation history
-- **Terminal** — Run commands directly from the browser
-- **Maintenance** — Health checks, backups, bot controls
+- WebSocket streaming chat · model switcher · platform & provider setup · file manager · memory editor · session browser · in-browser terminal · maintenance + health · workspace cards with cost aggregation
 
 ---
 
@@ -121,7 +66,7 @@ Free AI providers available — no credit card needed. **Privacy-first?** Pick t
 
 ### 📘 First-time setup walkthroughs
 
-Step-by-step guides with screenshots and screen-for-screen instructions:
+Step-by-step printable PDF guides:
 
 | Platform | PDF (printable) |
 |---|---|
@@ -262,69 +207,72 @@ If your AI provider isn't working, run `doctor` — it tests the actual API conn
 
 ## 🏗️ Architecture
 
-```
-                            ┌──────────────┐
-                            │   Web UI     │ (Dashboard, Workspaces, Chat, Settings)
-                            └──────┬───────┘
-                                   │ HTTP/WS
-┌──────────┐  ┌───────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
-│ Telegram │  │ Slack │  │ WhatsApp │  │ Discord  │  │  Signal  │
-└────┬─────┘  └───┬───┘  └────┬─────┘  └────┬─────┘  └────┬─────┘
-     │            │           │             │              │
-     └────────────┴───────────┴─────────────┴──────────────┘
-                           │
-                 ┌─────────┴──────────┐
-                 │ Workspace Resolver │ (per-channel context: cwd + persona)
-                 └─────────┬──────────┘
-                           │
-                    ┌──────┴───────┐
-                    │   Engine     │ (Query routing, fallback)
-                    └──────┬───────┘
-                           │
-          ┌────────────────┼────────────────┐
-          │                │                │
-   ┌──────┴──────┐  ┌─────┴──────┐  ┌──────┴──────┐
-   │ Claude SDK  │  │  OpenAI    │  │  Custom     │
-   │ (full agent)│  │ Compatible │  │  Models     │
-   └─────────────┘  └────────────┘  └─────────────┘
+```mermaid
+flowchart TB
+    classDef ent fill:#1e293b,color:#e2e8f0,stroke:#475569
+    classDef core fill:#0f172a,color:#f1f5f9,stroke:#3b82f6,stroke-width:2px
+    classDef prov fill:#1e293b,color:#cbd5e1,stroke:#64748b
+    classDef mem fill:#1e293b,color:#cbd5e1,stroke:#10b981
+
+    TG[Telegram]:::ent
+    SL[Slack]:::ent
+    WA[WhatsApp]:::ent
+    DC[Discord]:::ent
+    SG[Signal]:::ent
+    WEB[Web UI · TUI · CLI]:::ent
+
+    TG & SL & WA & DC & SG & WEB --> WR
+
+    WR[Workspace Resolver<br/>per-channel cwd + persona]:::core
+    WR --> ENG[Engine<br/>routing · fallback · heartbeat]:::core
+
+    ENG --> CL[Claude SDK]:::prov
+    ENG --> OAI[OpenAI · Groq · Gemini ·<br/>NVIDIA · OpenRouter]:::prov
+    ENG --> OL[Ollama · Codex CLI ·<br/>OpenAI-compatible]:::prov
+
+    ENG -.reads.-> MEM
+    MEM[Memory Layer]:::mem
+    MEM --> L0[L0 / L1<br/>identity.md · preferences.md<br/>always plain-text]:::mem
+    MEM --> SQL[SQLite store · provider auto-detect<br/>Gemini · OpenAI · Ollama · FTS5]:::mem
+
+    ENG -.dispatches.-> SUB[Detached sub-agents<br/>independent claude -p]:::prov
 ```
 
-### Provider Types
+### Provider matrix
 
-| Provider | Tool Use | Streaming | Vision | Auth |
-|----------|----------|-----------|--------|------|
-| Claude SDK | ✅ Full (native Bash, Read, Write, Web) | ✅ | ✅ | Claude CLI (OAuth) |
-| OpenAI, Groq, Gemini | ✅ Full (Shell, Files, Python, Web) | ✅ | Varies | API Key |
-| NVIDIA NIM | ✅ Full (Shell, Files, Python, Web) | ✅ | Varies | API Key (free) |
-| OpenRouter | ✅ Full (Shell, Files, Python, Web) | ✅ | ✅ | API Key |
-| Other OpenAI-compatible | ⚡ Auto-detect | ✅ | Varies | API Key |
+| Provider | Tool use | Streaming | Vision | Auth |
+|---|---|---|---|---|
+| Claude SDK (Agent) | ✅ native (Bash, Read, Write, Web, MCP) | ✅ | ✅ | Claude CLI OAuth |
+| OpenAI · Groq · Gemini · NVIDIA NIM · OpenRouter | ✅ universal tool use | ✅ | varies | API key |
+| Ollama (local) | ✅ via tool-bridge | ✅ | varies | none |
+| Codex CLI | ✅ subprocess | ✅ | — | Codex CLI auth |
+| Any OpenAI-compatible | ⚡ auto-detect | ✅ | varies | API key |
 
-> **Universal Tool Use:** Alvin Bot gives full agent capabilities to *any* provider that supports function calling — not just Claude. Shell commands, file operations, Python execution, web search, and more work across all major providers. If a provider doesn't support tool calls, Alvin Bot automatically falls back to text-only chat mode.
+> **Universal tool use** — Alvin gives full agent powers to any provider that supports function calling. Shell · files · Python · web work everywhere; providers without tool calls degrade cleanly to text-only chat.
 
-### Project Structure
+### Project layout
 
 ```
-alvin-bot/
-├── src/
-│   ├── index.ts                 # Entry point
-│   ├── engine.ts                # Multi-model query engine
-│   ├── config.ts                # Configuration
-│   ├── handlers/                # Message & command handlers
-│   ├── middleware/              # Auth & access control
-│   ├── platforms/               # Telegram, Slack, WhatsApp, Discord, Signal adapters
-│   ├── providers/               # AI provider implementations
-│   ├── services/                # Memory, voice, cron, plugins, workspaces, tool discovery
-│   ├── tui/                     # Terminal UI
-│   └── web/                     # Web server, APIs, setup wizard
-├── web/public/                  # Web UI (HTML/CSS/JS, zero build step)
-├── plugins/                     # Plugin directory (6 built-in)
-├── docs/
-│   ├── install/                 # Setup guides (macOS, Windows, Slack)
-│   └── custom-models.json       # Custom model configurations
-├── TOOLS.md                     # Custom tool definitions (Markdown)
-├── SOUL.md                      # Agent personality
-├── bin/cli.js                   # CLI entry point
-└── ecosystem.config.cjs         # PM2 configuration
+src/
+├── index.ts                 entry point
+├── engine.ts                multi-model query engine
+├── handlers/                message + command handlers
+├── platforms/               Telegram · Slack · WhatsApp · Discord · Signal
+├── providers/               Claude SDK · OpenAI-compat · Ollama · Codex CLI
+├── services/
+│   ├── embeddings/          v4.22 pluggable provider facade (Gemini/OpenAI/Ollama/FTS5)
+│   ├── memory*.ts           layered memory (L0-L3) + inject-mode resolver
+│   ├── workspaces.ts        per-channel cwd + persona registry
+│   ├── alvin-dispatch.ts    detached sub-agent orchestration
+│   ├── browser-manager.ts   4-tier browser strategy
+│   └── …                    cron · voice · skills · MCP · hooks · …
+├── tui/                     terminal chat UI
+└── web/                     dashboard server + APIs
+web/public/                  zero-build HTML/CSS/JS UI
+plugins/                     6 built-in plugins (hot-reload)
+skills/                      14 SKILL.md files (hot-reload)
+bin/cli.js                   CLI entry point
+electron/                    Electron wrapper for the .dmg build
 ```
 
 ---
@@ -368,7 +316,7 @@ The `cwd` auto-loads the project-specific `CLAUDE.md` via Claude SDK's `settingS
 ### Slack setup (5 minutes)
 
 1. Download the setup guide + manifest from the [latest release](https://github.com/alvbln/Alvin-Bot/releases/latest):
-   - `slack-setup.md` — step-by-step instructions with screenshots
+   - `slack-setup.md` — step-by-step instructions
    - `slack-manifest.json` — copy-paste ready Slack App manifest
 2. Create a Slack App from the manifest at https://api.slack.com/apps → **Create New App** → **From an app manifest**
 3. Enable Socket Mode, generate an **App-Level Token** (starts with `xapp-`)
@@ -548,18 +496,26 @@ Plugins are auto-loaded at startup. Create your own by adding a directory with a
 
 ## 🎯 Skills
 
-Built-in skills in `skills/`:
+Skills are markdown files in `skills/` that auto-activate when the user's message matches their trigger keywords. The skill body gets injected into the system prompt, giving the agent specialized expertise on demand. 14 ship built-in:
 
-| Skill | Triggers | Description |
-|-------|----------|-------------|
-| code-project | code, build, implement, debug, refactor | Software development workflows, architecture patterns |
-| data-analysis | analyze, chart, csv, excel, statistics | Data processing, visualization, statistical analysis |
-| document-creation | document, report, letter, pdf, write | Professional document creation and formatting |
-| email-summary | email, inbox, unread, newsletter | Email triage, summarization, priority sorting |
-| system-admin | server, deploy, docker, nginx, ssl | DevOps, deployment, system administration |
-| web-research | research, compare, find, review | Deep web research with source verification |
-
-Skills activate automatically when your message matches their trigger keywords. The skill's SKILL.md content is injected into the system prompt, giving the agent specialized expertise for that task.
+| Skill | Description |
+|---|---|
+| **agent-browser** | Token-efficient web automation via the agent-browser CLI (accessibility-tree snapshots) — Tier 1.5 of the browser stack |
+| **apple-notes** | Read, create, search Apple Notes via AppleScript (macOS) |
+| **browse** | 3-tier browser control: WebFetch · stealth Playwright · CDP with persistent profile |
+| **code-project** | Software development workflows: build, debug, refactor, architecture patterns |
+| **data-analysis** | CSV / JSON / Excel processing, charts, statistics via Python |
+| **document-creation** | Professional PDFs, reports, letters with formatting |
+| **email-summary** | Inbox triage, newsletter digests, priority sorting |
+| **github** | Issues, PRs, releases, workflows via the `gh` CLI |
+| **social-fetch** | Analyse Instagram / TikTok / YouTube / X URLs the user shares |
+| **summarize** | Condense URLs, PDFs, long documents |
+| **system-admin** | Server management, deploys, Docker, nginx, SSL |
+| **weather** | Forecasts and conditions |
+| **web-research** | Deep multi-source research with citation aggregation |
+| **webcheck** | Security / SEO audit of a website |
+
+Drop your own `<name>/SKILL.md` into `~/.alvin-bot/skills/` for hot-reload. List active skills via `/skills` or `alvin-bot skills`.
 
 ---
 
@@ -586,96 +542,40 @@ alvin-bot version   # Show version
 
 ## 🗺️ Roadmap
 
-- [x] **Phase 1** — Multi-Model Engine (provider abstraction, fallback chains)
-- [x] **Phase 2** — Memory System (vector search, user profiles, smart context)
-- [x] **Phase 3** — Rich Interactions (video messages, browser automation, email)
-- [x] **Phase 4** — Plugins & Tools (plugin ecosystem, MCP client, custom tools)
-- [x] **Phase 5** — CLI Installer (setup wizard, Docker, health check)
-- [x] **Phase 6** — Web Dashboard (chat, settings, file manager, terminal)
-- [x] **Phase 7** — Multi-Platform (Telegram, Discord, WhatsApp, Signal adapters)
-- [x] **Phase 8** — Universal Tool Use *(NEW)* — All providers get agent powers:
-  - ✅ Shell execution, file read/write/edit, directory listing
-  - ✅ Python execution (Excel, PDF, charts, data processing)
-  - ✅ Web fetch & search
-  - ✅ Auto-detect function calling support per provider
-  - ✅ Graceful fallback to text-only for providers without tool support
-- [x] **Phase 9** — Skill System + Self-Awareness + Language Adaptation:
-  - ✅ SKILL.md files for specialized domain knowledge (email, data analysis, code, docs, research, sysadmin)
-  - ✅ Auto-matching: skill triggers activate contextual expertise on demand
-  - ✅ Self-Awareness Core: agent knows it IS the AI (no external LLM calls for text tasks)
-  - ✅ Automatic language detection and adaptation (EN default, learns user preference)
-  - ✅ Human-readable cron schedules + visual schedule builder in WebUI
-  - ✅ Platform Manager refactor: all adapters via unified registration system
-  - ✅ Cron notifications for all platforms (Telegram, WhatsApp, Discord, Signal)
-  - ✅ PM2 auto-refresh on Maintenance page
-  - ✅ WhatsApp group whitelist with per-contact access control
-  - ✅ Owner approval gate (Telegram → WhatsApp DM → Discord → Signal fallback)
-  - ✅ Full media processing: photos, documents, audio/voice, video across all platforms
-  - ✅ File Browser: create, edit, delete files with safety guards
-  - ✅ Git history sanitized (personal data removed via git-filter-repo)
-- [x] **Phase 10** — Anthropic API Provider + WebUI Provider Management
-  - [x] Anthropic API key test case in WebUI (validation endpoint)
-  - [x] "Add Provider" flow in WebUI — add new providers post-setup without editing `.env`
-  - [x] Claude SDK guided setup from WebUI (install check, login status, step-by-step)
-  - [x] `.env.example` update with `ANTHROPIC_API_KEY`
-- [x] **Phase 11** — WebUI Professional Redesign
-  - [x] Replace emoji icons with Lucide SVG icons (60+ icons, sidebar, pages, buttons)
-  - [x] i18n framework (`i18n.js`) — bilingual DE/EN with browser-locale detection (~400 keys)
-  - [x] Language toggle in sidebar footer (DE | EN)
-  - [x] Typography upgrade (Inter webfont via Google Fonts)
-  - [x] Gradient accents + subtle glassmorphism on cards
-  - [x] Smooth page transitions (fade animation on page switch)
-  - [x] Skeleton loading states + status pulse animations
-  - [x] Command Palette (Cmd+K / Ctrl+K) with fuzzy search
-- [x] **Phase 12** — Native Installers (Non-Techie Friendly)
-  - [x] Electron wrapper (embedded Node.js + WebUI + tray icon)
-  - [x] macOS `.dmg` build via electron-builder (arm64)
-  - [ ] Windows `.exe` (NSIS) via electron-builder
-  - [ ] Linux `.AppImage` + `.deb` via electron-builder
-  - [x] Auto-update mechanism (electron-updater)
-  - [x] GUI Setup Wizard (provider selection, Telegram token, first-run experience)
-  - [ ] Homebrew formula (`brew install alvin-bot`)
-  - [ ] Scoop manifest for Windows
-  - [ ] One-line install script
-  - [x] Docker Compose polish (production-ready `docker-compose.yml`)
-- [x] **Phase 13** — npm publish (security audit)
-- [x] **Phase 14** — Async Sub-Agents (v4.10.0)
-  - [x] `run_in_background: true` system prompt hint for Claude SDK
-  - [x] Async-agent watcher polling `outputFile` JSONL, delivering results as separate messages
-  - [x] Session-bound sub-agents (each session spawns its own background workers)
-- [x] **Phase 15** — Memory Persistence + Smart Loading (v4.11.0)
-  - [x] Session persistence across bot restarts (debounced atomic flush, v2 envelope)
-  - [x] SDK memory injection (MEMORY.md in every system prompt, not just tool-call dependent)
-  - [x] Semantic recall on SDK first-turn via embeddings
-  - [x] Layered memory stack (L0 identity / L1 preferences / L2 projects / L3 vector search)
-  - [x] Auto-fact extraction during compaction (Mem0-style)
-- [x] **Phase 16** — Multi-Session + Slack Interface (v4.12.0)
-  - [x] Session-key fix: platform-message.ts routes through `buildSessionKey()`
-  - [x] Workspace registry with hot-reload (`~/.alvin-bot/workspaces/*.md`)
-  - [x] Workspace resolver in platform handlers (per-channel persona + cwd)
-  - [x] Slack adapter polish: progress ticker (`chat.update`), typing status (`assistant.threads.setStatus`), channel name cache
-  - [x] Telegram `/workspace` + `/workspaces` commands (feature parity)
-  - [x] Per-workspace cost aggregation + Web UI workspace cards
-  - [x] Slack setup guide + copy-paste app manifest (in GitHub Release assets)
-- [x] **Phase 17** — Truly detached sub-agents + multi-platform dispatch (v4.13.0 – v4.14.2, 2026-04-16)
-  - [x] `alvin_dispatch_agent` MCP tool — spawns independent `claude -p` subprocesses that survive parent aborts (v4.13.0)
-  - [x] Slack `/alvin` slash command (namespaced parent with subcommands: status / new / effort / help + LLM fallthrough) (v4.13.2)
-  - [x] Sub-agent dispatch on Slack, Discord, WhatsApp via platform-aware delivery registry (v4.14.0)
-  - [x] `/subagents list` merged view — v4.0.0 bot-level agents + v4.13+ detached dispatches in one list (v4.14.1)
-  - [x] Watcher zombie guard — missing outputFile > 10 min delivers as failed instead of 12h timeout (v4.14.2)
-  - [x] Staleness-based partial output recovery for interrupted sub-agents (v4.12.4)
-  - [ ] SQLite migration of the embeddings index (currently 128 MB JSON)
-  - [ ] Per-workspace memory layer (additive over global) — facts learned in one workspace stay there unless explicitly promoted to global
-  - [ ] Per-workspace provider override (`provider:` in frontmatter) — e.g. one workspace uses Claude Opus, another uses a cheaper model
-  - [ ] Per-workspace skill allowlist — scope Apple Notes to personal workspace, sysadmin only to devops workspace, etc.
-  - [ ] Multi-User Slack (real `per-channel-peer` mode) — different users in the same Slack channel get their own sub-sessions
-  - [ ] Workspace cloning / templates — `/workspace clone my-project as my-fork` spins up a new workspace from an existing one
-  - [ ] Daily log decay / archive — older daily logs move to cold storage after N days
-- [ ] **Phase 18** — Security + Platform hardening (from v4.12.1 audit, prioritized)
-  - [ ] **P1 — Electron major upgrade** (35 → 41+) — fixes 1 HIGH + 5 MODERATE Electron CVEs in the Desktop-Build path. Major version jump, requires full rebuild + test of `.dmg` flow. Separate release (likely bundled with Windows `.exe` work).
-  - [ ] **P1 — Prompt injection defense strategy** — not a single fix but a design debate: heuristic filters vs allow-list vs no-sandbox-accept-the-risk. Currently handled as a documented design-constraint (README security section), not as a code filter. When we decide the policy, implement it across all message entry points.
-  - [ ] **P2 — TypeScript 5 → 6 upgrade** — major release, likely breaking changes in strict mode. Needs a dedicated release + test sweep. Low priority since 5.x is still supported.
-  - [ ] **P0 for v5.0 — MCP plugin sandboxing** — currently MCP servers run with full Node privileges. Plan: run each MCP in a child process with restricted FS + network policy (similar to deno-permission model). Architectural change, v5.0 territory.
+> Per-version details: see [`CHANGELOG.md`](CHANGELOG.md). The roadmap is a forward-looking summary, not a changelog.
+
+### ✅ Recently shipped
+
+| Version | Theme | Highlights |
+|---|---|---|
+| **v4.22** *(May 2026)* | Memory architecture overhaul | Pluggable embedding providers — **Gemini · OpenAI · Ollama · FTS5 (zero-config keyword fallback)**. Auto-detection picks the best available, so users with no API key still get a working indexed memory store. Smart inject mode stops bulk-injecting `MEMORY.md` once SQLite is populated. |
+| **v4.21** | Agent Browser skill | Tier-1.5 token-efficient web automation via the [agent-browser](https://github.com/vercel-labs/agent-browser) CLI — opt-in by install. ~90 % token reduction vs Playwright on cooperative pages. |
+| **v4.20** | SQLite-backed vector memory | Replaces the legacy 128 MB JSON index. Automatic migration on first start, per-chunk INSERT/UPDATE, lazy native binary load with graceful fallback. |
+| **v4.18 – v4.19** | Reliability + per-workspace overrides | SDK auto-recovery on token rotation / quota exhaustion / empty streams. Per-workspace `effort` / `provider` / `voice` / `temperature` / `toolset`. |
+| **v4.17** | Hardening audit | Disk cleanup service, hardening fixes from internal audit. |
+| **v4.13 – v4.14** | Detached sub-agents | `alvin_dispatch_agent` MCP tool spawns independent `claude -p` subprocesses that survive parent aborts. Multi-platform dispatch (Slack / Discord / WhatsApp). Watcher zombie guard. |
+| **v4.10 – v4.12** | Multi-session + Slack | Workspace registry with hot-reload, per-channel personas + cwd, Slack adapter with progress ticker + typing status, owner approval gate, async sub-agents. |
+
+### 🏛️ Foundations (built before v4.10)
+
+Multi-model provider abstraction with fallback chains · plugin & skill ecosystems with hot-reload · multi-platform adapters (Telegram, WhatsApp, Discord, Signal, Slack) · Web UI with i18n + command palette · native macOS `.dmg` via Electron · Docker Compose · npm distribution · MCP client + custom tools · universal tool use across providers · full media pipeline (audio · video · photo · voice).
+
+### 🎯 On the radar
+
+| Priority | Item | Why |
+|---|---|---|
+| **P0 → v5.0** | MCP plugin sandboxing | MCP servers currently run with full Node privileges. Plan: child process with restricted FS + network policy (deno-permission style). Architectural change. |
+| **P1** | Electron major upgrade (35 → 41+) + Windows `.exe` | Closes desktop-build CVEs, unblocks the only platform still missing a native installer. |
+| **P1** | Prompt injection defense policy | Needs a design decision (heuristic filter / allow-list / accept-the-risk with clearer warnings) and consistent enforcement at every message entry point. |
+| **P2** | Per-workspace memory layer | Facts learned in one workspace stay scoped unless explicitly promoted. Builds on the v4.22 SQLite store. |
+| **P2** | Per-workspace skill allowlist | Scope Apple Notes to personal workspace, sysadmin tools to devops only, etc. |
+| **P2** | Multi-user Slack (`per-channel-peer`) | Different users in the same Slack channel get their own sub-sessions. |
+| **P3** | Linux `.AppImage` / `.deb`, Homebrew formula, Scoop manifest, one-line install script | Platform reach for non-npm users. |
+| **P3** | Daily-log decay / archive | Older daily logs move to cold storage after N days. |
+| **P3** | Workspace cloning / templates | `/workspace clone my-project as my-fork` spins up a new workspace from an existing one. |
+| **P3** | TypeScript 5 → 6 | 5.x still supported; strict-mode break-fix work, not urgent. |
+
+Pull requests welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md).
 
 ---
 

package/dist/services/cron-scheduling.js

@@ -29,32 +29,40 @@ function parseInterval(input) {
     };
     return value * (mult[unit] || 60_000);
 }
-function nextCronRun(expression, after) {
+function parseField(expr, min, max) {
+    if (expr === "*")
+        return Array.from({ length: max - min + 1 }, (_, i) => i + min);
+    if (expr.includes("/")) {
+        const [, step] = expr.split("/");
+        const s = parseInt(step);
+        return Array.from({ length: max - min + 1 }, (_, i) => i + min).filter((v) => v % s === 0);
+    }
+    if (expr.includes(","))
+        return expr.split(",").map(Number);
+    if (expr.includes("-")) {
+        const [a, b] = expr.split("-").map(Number);
+        return Array.from({ length: b - a + 1 }, (_, i) => i + a);
+    }
+    return [parseInt(expr)];
+}
+function parseCronFields(expression) {
     const parts = expression.trim().split(/\s+/);
     if (parts.length !== 5)
         return null;
     const [minExpr, hourExpr, dayExpr, monthExpr, weekdayExpr] = parts;
-    function parseField(expr, min, max) {
-        if (expr === "*")
-            return Array.from({ length: max - min + 1 }, (_, i) => i + min);
-        if (expr.includes("/")) {
-            const [, step] = expr.split("/");
-            const s = parseInt(step);
-            return Array.from({ length: max - min + 1 }, (_, i) => i + min).filter((v) => v % s === 0);
-        }
-        if (expr.includes(","))
-            return expr.split(",").map(Number);
-        if (expr.includes("-")) {
-            const [a, b] = expr.split("-").map(Number);
-            return Array.from({ length: b - a + 1 }, (_, i) => i + a);
-        }
-        return [parseInt(expr)];
-    }
-    const minutes = parseField(minExpr, 0, 59);
-    const hours = parseField(hourExpr, 0, 23);
-    const days = parseField(dayExpr, 1, 31);
-    const months = parseField(monthExpr, 1, 12);
-    const weekdays = parseField(weekdayExpr, 0, 6);
+    return {
+        minutes: parseField(minExpr, 0, 59),
+        hours: parseField(hourExpr, 0, 23),
+        days: parseField(dayExpr, 1, 31),
+        months: parseField(monthExpr, 1, 12),
+        weekdays: parseField(weekdayExpr, 0, 6),
+    };
+}
+function nextCronRun(expression, after) {
+    const fields = parseCronFields(expression);
+    if (!fields)
+        return null;
+    const { minutes, hours, days, months, weekdays } = fields;
     const candidate = new Date(after);
     candidate.setSeconds(0, 0);
     candidate.setMinutes(candidate.getMinutes() + 1);
@@ -75,6 +83,39 @@ function nextCronRun(expression, after) {
     }
     return null;
 }
+/**
+ * Find the most recent scheduled trigger at or before `before`. Returns
+ * null for non-cron schedules (interval strings) and for jobs whose
+ * cron expression has never matched in the search window.
+ *
+ * Used by the slot-aware catch-up rule: if a job's lastAttemptAt is
+ * at or after this trigger, the slot is "already attempted" and
+ * handleStartupCatchup leaves it alone.
+ */
+export function prevCronRun(expression, before) {
+    const fields = parseCronFields(expression);
+    if (!fields)
+        return null;
+    const { minutes, hours, days, months, weekdays } = fields;
+    const candidate = new Date(before);
+    candidate.setSeconds(0, 0);
+    for (let i = 0; i < 366 * 24 * 60; i++) {
+        const m = candidate.getMinutes();
+        const h = candidate.getHours();
+        const d = candidate.getDate();
+        const mo = candidate.getMonth() + 1;
+        const wd = candidate.getDay();
+        if (minutes.includes(m) &&
+            hours.includes(h) &&
+            days.includes(d) &&
+            months.includes(mo) &&
+            weekdays.includes(wd)) {
+            return candidate;
+        }
+        candidate.setMinutes(candidate.getMinutes() - 1);
+    }
+    return null;
+}
 /** Compute the next run relative to an explicit base timestamp.
  *  Used by prepareForExecution to make the interval calculation stable
  *  even when `lastRunAt` is stale or null. */
@@ -108,16 +149,49 @@ export function prepareForExecution(job, now) {
 // ── Startup catch-up ───────────────────────────────────────
 /** Default grace window for catching up an interrupted attempt on boot. */
 export const DEFAULT_CATCHUP_GRACE_MS = 6 * 60 * 60 * 1000; // 6 h
+/**
+ * Returns true when the job's *current* schedule slot has already been
+ * attempted — i.e. the bot fired the job for this slot before the
+ * crash. Even if the attempt didn't complete, we treat the slot as
+ * spent and don't auto-retry on boot. Users can still manually rerun
+ * via `/cron run`.
+ *
+ * - Cron expression: the slot is the most recent past trigger time
+ *   (e.g. for `0 8 * * *` at 11:00, the slot starts at today 08:00).
+ *   `lastAttemptAt >= prevTrigger` → already attempted.
+ * - Interval (5m, 1h, …): the slot is one interval wide.
+ *   `now - lastAttemptAt < intervalMs` → still inside the slot the
+ *   crashed attempt belonged to.
+ */
+function slotAlreadyAttempted(job, now) {
+    if (!job.lastAttemptAt)
+        return false;
+    const intervalMs = parseInterval(job.schedule);
+    if (intervalMs !== null) {
+        return now - job.lastAttemptAt < intervalMs;
+    }
+    const lastTrigger = prevCronRun(job.schedule, new Date(now));
+    if (!lastTrigger)
+        return false;
+    return job.lastAttemptAt >= lastTrigger.getTime();
+}
 /**
  * Rewind `nextRunAt` to `now` for every enabled job whose most recent
- * attempt never completed AND is still inside the grace window. This
- * makes the very next scheduler tick pick the job up again, without
- * double-firing jobs that actually finished.
+ * attempt never completed AND is still inside the grace window AND
+ * whose current schedule slot hasn't already been attempted.
+ *
+ * The slot check (slotAlreadyAttempted) is the bug fix for the
+ * "duplicate daily run after reboot" report: if the daily 08:00 job
+ * fired at 08:00, crashed before completion, and the bot reboots at
+ * 11:00, the old logic would re-fire the job at 11:00. The new logic
+ * sees lastAttemptAt = 08:00 ≥ today's 08:00 trigger and leaves the
+ * job's nextRunAt pointing at tomorrow 08:00, accepting the loss.
  *
  * Jobs whose crashed attempt is older than the grace window are NOT
- * caught up — the assumption is that such a run is too stale to be
- * meaningful (a "daily" run from yesterday isn't what the user wants
- * at 2pm today). Those jobs keep their scheduled future nextRunAt.
+ * caught up either — the assumption is that such a run is too stale
+ * to be meaningful (a "daily" run from yesterday isn't what the user
+ * wants at 2pm today). Those jobs keep their scheduled future
+ * nextRunAt.
  *
  * PURE: returns a fresh array, never mutates the input.
  */
@@ -136,7 +210,13 @@ export function handleStartupCatchup(jobs, now, graceMs = DEFAULT_CATCHUP_GRACE_
             return job; // clock weirdness — skip
         if (ageMs > graceMs)
             return job; // outside grace — give up
-        // Within grace, never completed → catch up on next tick.
+        // The current schedule slot has already been attempted (even if it
+        // crashed). Skip catch-up so the user doesn't get a surprise rerun
+        // hours after the originally scheduled time.
+        if (slotAlreadyAttempted(job, now))
+            return job;
+        // Within grace, never completed, and current slot hasn't been
+        // attempted yet → catch up on next tick.
         return { ...job, nextRunAt: now };
     });
 }

package/package.json

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