alvin-bot 4.12.0 → 4.12.2

package/CHANGELOG.md

@@ -2,6 +2,130 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [4.12.2] — 2026-04-15
+
+### 🔒 Security patch: file permissions, ALLOWED_USERS hard-fail, exec-guard hardening, CVE updates
+
+This is the first **formal security release** of Alvin Bot, motivated by a comprehensive audit after v4.12.1 production deployment. The audit surfaced real issues that needed fixing before the bot could be safely installed on multi-user dev servers or shared by external users. All fixes are additive and backwards-compatible — existing single-user installs see no behavior change except improved security.
+
+#### CRITICAL CVE — axios 1.14.0 → 1.15.0 (CVSS 10.0)
+
+Transitive dependency via `@slack/bolt`. Two CVEs closed:
+- GHSA-fvcv-3m26-pcqx — Cloud Metadata Exfiltration via Header Injection Chain (CVSS 10.0)
+- GHSA-3p68-rc4w-qgx5 — NO_PROXY Hostname Normalization Bypass → SSRF
+
+Fix: `npm update @slack/bolt` (4.6.0 → 4.7.0) + `package.json overrides: axios ^1.15.0` to force transitive updates in `@slack/web-api` and `@whiskeysockets/baileys`. Post-fix `npm audit` shows **0 critical, 2 high remaining** (`basic-ftp` HIGH — never invoked by Alvin, `electron` HIGH — devDep only, tracked as Phase 18).
+
+Also updated `@anthropic-ai/claude-agent-sdk` 0.2.97 → 0.2.109 (MODERATE: GHSA-5474-4w2j-mq4c Path Validation Sandbox Escape).
+
+#### CRITICAL — File permissions on sensitive files (0o600)
+
+Pre-v4.12.2 `~/.alvin-bot/.env`, `state/sessions.json`, memory logs, cron-jobs.json were written with the default umask — typically 0o644 on Linux/macOS, meaning any other user on the same machine could read BOT_TOKEN + all API keys, full conversation history, cron prompts, and encrypted sudo credentials.
+
+**Fix**: new `src/services/file-permissions.ts` with `writeSecure()`, `ensureSecureMode()`, `auditSensitiveFiles()`. All `.env` writes in setup-api, doctor-api, server, fallback-order, session-persistence now use `writeSecure()`. Startup audit in `index.ts` chmod-repairs the full sensitive-file list idempotently on every boot.
+
+#### CRITICAL — ALLOWED_USERS startup hard-fail
+
+Pre-v4.12.2 Alvin started with BOT_TOKEN set but ALLOWED_USERS empty with only a console.warn — leaving the bot "configured but unguarded".
+
+**Fix**: new pure gate function `src/services/allowed-users-gate.ts`. `src/index.ts` refuses to start with a clear error message. Two explicit escape hatches: `AUTH_MODE=open` or `ALVIN_INSECURE_ACKNOWLEDGED=1`.
+
+#### HIGH — Webhook bearer token timing-safe comparison
+
+`src/web/server.ts` POST /api/webhook previously used naive `authHeader !== "Bearer " + token` leaking comparison position via timing side-channel.
+
+**Fix**: new `src/services/timing-safe-bearer.ts` wraps `crypto.timingSafeEqual` with strict "Bearer <token>" format, empty-expected rejection, length-mismatch dummy comparison.
+
+#### HIGH — Exec-guard shell metacharacter rejection
+
+`checkExecAllowed()` only inspected the first word — `echo safe; rm -rf /` passed as "echo". Trivially bypassable via `&&`, `|`, `` ` ``, `$(...)`, redirects.
+
+**Fix**: allowlist mode rejects any command containing `;`, `&`, `|`, `` ` ``, `$(...)`, `{...}`, `<`, `>`. Operators who need shell pipelines set `EXEC_SECURITY=full` explicitly.
+
+#### HIGH — Cron shell-job execGuard integration
+
+Pre-v4.12.2 cron `type: "shell"` bypassed the exec-guard entirely. **Fix**: cron.ts case "shell" now calls `checkExecAllowed()` before `execSync()` and sends a blocked-notification on deny.
+
+#### MEDIUM — Sub-agent toolset allowlist (readonly, research)
+
+`SubAgentConfig.toolset` widened from `"full"` to `"full" | "readonly" | "research"`:
+- `readonly` → Read, Glob, Grep only (no write, shell, network)
+- `research` → readonly + WebSearch, WebFetch
+- `full` → unchanged default
+
+New `QueryOptions.allowedTools?: string[]` honored by `claude-sdk-provider`. Other providers ignore it.
+
+#### NEW — `docs/security.md` threat model + hardening guide (279 lines)
+
+First formal security documentation covering: TL;DR safety table, capability surface, attacker model, trust boundaries, hardening step-by-step, shell execution policy, file permissions list, sub-agent presets, prompt injection honesty section, Phase 18 pending work, security issue reporting, incident response playbook. Public doc, shipped with the repo.
+
+#### NEW — README Security section rewrite
+
+Replaced thin bullet list with a boxed warning ("Alvin has full shell + filesystem access") and four sub-sections: access control, execution hardening, data hardening, known limitations. Links to docs/security.md.
+
+#### Testing
+
+**396 tests total** (350 baseline from v4.12.1 + 46 new). All green. Build clean.
+
+- 10 `test/file-permissions.test.ts`
+- 7 `test/allowed-users-gate.test.ts`
+- 10 `test/timing-safe-bearer.test.ts`
+- 13 `test/exec-guard-metachars.test.ts`
+- 4 `test/subagent-toolset-allowlist.test.ts`
+- 2 extended `test/subagents-toolset.test.ts` (readonly + research)
+
+#### Phase 18 (deferred, tracked in README Roadmap)
+
+- Electron 35 → 41+ upgrade (Desktop build, 6 CVEs)
+- Prompt injection defense strategy (design debate, not code filter)
+- TypeScript 5 → 6 upgrade
+- MCP plugin sandboxing (architectural v5.0)
+
+---
+
+## [4.12.1] — 2026-04-15
+
+### 🐛 Patch: Sync sub-agent timeout + workspace command menu
+
+Three issues from v4.12.0 production use, fixed:
+
+- **Fix (Bug 1)**: `Task`/`Agent` tool calls without `run_in_background: true` were false-aborted after 10 minutes. The Claude Agent SDK runs synchronous sub-agents entirely inside the tool call — the parent stream emits no intermediate chunks during that time, so the flat 10-minute stuck-timer fired on legitimate long-running work. The new task-aware stuck timer detects sync Task/Agent tool calls (tracked by `toolUseId`) and automatically escalates the idle timeout to 120 minutes (configurable via `ALVIN_SYNC_AGENT_IDLE_TIMEOUT_MINUTES`). Once the matching `tool_result` arrives, the timer reverts to the normal 10-minute idle detection for genuine SDK hangs.
+
+- **Mitigation (Bug 2)**: The `BACKGROUND_SUBAGENT_HINT` in `src/services/personality.ts` was rewritten with `⚠️ CRITICAL` framing, a concrete decision-tree structure, an aggressive ~30 second threshold (down from "2 minutes"), and an explicit warning about the Telegram session-blocking consequence. The goal is to get Claude to reliably set `run_in_background: true` when sub-agents will take more than a few seconds, so the main Telegram session doesn't stay blocked while the sub-agent works. This is defense-in-depth on top of the Bug 1 fix — the timer prevents false aborts regardless of Claude's compliance; the strengthened hint reduces how often main-session blocking happens in the first place. Compliance is monitored empirically via logs.
+
+- **Fix (Bug 3)**: `/workspace` and `/workspaces` were registered as Telegram command handlers in v4.12.0 but not added to the `bot.api.setMyCommands` array, so they didn't appear in Telegram's auto-complete menu (the list that pops up when you type `/`). Added both, plus a new "🧭 Workspaces" block in the `/help` text.
+
+#### Architecture details
+
+**NEW `src/handlers/stuck-timer.ts`**: Pure state machine `createStuckTimer({normalMs, extendedMs, onTimeout})` returning `{reset, enterSync, exitSync, cancel}`. Testable in isolation without grammy/session/provider mocks via `vi.useFakeTimers()`. 8 unit tests cover normal fire, enterSync extends, exitSync returns, multi-pending, unknown-id no-op, cancel, reset-while-extended, idempotent enterSync.
+
+**Protocol change in `src/providers/types.ts` + `claude-sdk-provider.ts`**: `StreamChunk` gains a new additive optional field `runInBackground?: boolean`. The provider extracts it from `block.input.run_in_background` **before** the existing 500-char JSON truncation on `toolInput` — this is load-bearing because for long prompts the serialized input can exceed 500 chars, and naive post-truncation parsing would lose the flag and misclassify sync tasks as async. `toolUseId` is now also yielded on `tool_use` chunks (previously only on `tool_result`) so the consumer can correlate tool_use → tool_result for sync tracking. 4 contract-pin tests mock `@anthropic-ai/claude-agent-sdk` with scripted assistant messages to verify the extraction logic.
+
+**Critical ordering in `message.ts`**: State mutation of the pending-sync-task set (`stuckTimer.enterSync` / `stuckTimer.exitSync`) happens **before** `stuckTimer.reset()` in the for-await loop, so the timer arms with the post-mutation state. Inline comment added documenting this invariant.
+
+#### Known limitation (not fixed in v4.12.1)
+
+A Nanosecond-race where the stuck timer fires the same moment a `tool_result` arrives (fundamentally unfixable without `check-before-fire` semantics in `setTimeout`). With the 120-minute extended window the race requires the tool_result to arrive at exactly 120:00:00.000 — practically irrelevant. A proper fix would require rewriting the timer as a state machine with a pre-fire check, deferred to v4.13.0 if it ever matters.
+
+#### Testing
+
+**350 tests total** (330 baseline from v4.12.0 + 20 new). All green, TSC clean.
+
+- 8 `test/stuck-timer.test.ts` — pure state-machine unit tests
+- 4 `test/claude-sdk-tool-use-id.test.ts` — contract pins for `toolUseId` + `runInBackground` on tool_use chunks
+- 3 new assertions in `test/system-prompt-background-hint.test.ts` (CRITICAL framing, Telegram blocking, 30-second threshold)
+- 5 `test/sync-task-timeout.test.ts` — integration tests over realistic timing scales + regression guard for the pre-fix flat-timeout behavior
+
+Live verification after release: local bot restart, Telegram `/` auto-complete shows `/workspace` + `/workspaces`, `curl https://api.telegram.org/bot$TOKEN/getMyCommands` returns the new entries.
+
+#### Files changed
+
+- **NEW**: `src/handlers/stuck-timer.ts`
+- **NEW tests**: `test/stuck-timer.test.ts`, `test/claude-sdk-tool-use-id.test.ts`, `test/sync-task-timeout.test.ts`
+- **Modified**: `src/providers/types.ts` (`StreamChunk.runInBackground`), `src/providers/claude-sdk-provider.ts` (extract `runInBackground` before truncation, yield `toolUseId` on tool_use), `src/handlers/message.ts` (`createStuckTimer` integration + task-aware flow), `src/services/personality.ts` (`BACKGROUND_SUBAGENT_HINT` rewrite), `src/handlers/commands.ts` (setMyCommands + `/help`), `test/system-prompt-background-hint.test.ts` (3 new assertions)
+
+---
+
 ## [4.12.0] — 2026-04-13
 
 ### 🧭 Multi-Session + Slack Interface — parallel contexts, per-channel workspaces

package/README.md

@@ -62,20 +62,23 @@ Alvin Bot is an open-source, self-hosted AI agent that lives where you chat. Bui
 - **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
+- **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)
+- **Background Sub-Agents** — Claude autonomously uses `run_in_background: true` for long audits/research; main session stays responsive, results deliver as separate messages (v4.10.0)
 - **Smart Tool Discovery** — Scans your system at startup, knows exactly what CLI tools, plugins, and APIs are available
-- **Skill System** — 6 built-in SKILL.md files (code, data analysis, email, docs, research, sysadmin) auto-activate based on message context
+- **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) and adapts; learns preference over time
+- **Automatic Language Detection** — Detects user language (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
+- **Web UI** — Full dashboard with chat, settings, file manager, terminal, workspace overview
 
 ### 🔧 Capabilities
 - **52+ Built-in Tools** — Shell, files, email, screenshots, PDF, media, git, system control
@@ -244,6 +247,8 @@ If your AI provider isn't working, run `doctor` — it tests the actual API conn
 | `/remember <text>` | Save to memory |
 | `/export` | Export conversation |
 | `/dir <path>` | Change working directory |
+| `/workspaces` | List all configured workspaces (v4.12.0) |
+| `/workspace [name]` | Show or switch the active workspace — `/workspace default` resets (v4.12.0) |
 | `/status` | Current session & cost info |
 | `/setup` | Configure API keys & platforms |
 | `/system <prompt>` | Set custom system prompt |
@@ -258,15 +263,19 @@ If your AI provider isn't working, run `doctor` — it tests the actual API conn
 ## 🏗️ Architecture
 
 ```
-                    ┌──────────────┐
-                    │   Web UI     │ (Dashboard, Chat, Settings)
-                    └──────┬───────┘
-                           │ HTTP/WS
-┌──────────┐  ┌──────────┐ │ ┌──────────┐  ┌──────────┐
-│ Telegram │  │ WhatsApp │ │ │ Discord  │  │  Signal  │
-└────┬─────┘  └────┬─────┘ │ └────┬─────┘  └────┬─────┘
-     │             │       │      │              │
-     └─────────────┴───────┴──────┴──────────────┘
+                            ┌──────────────┐
+                            │   Web UI     │ (Dashboard, Workspaces, Chat, Settings)
+                            └──────┬───────┘
+                                   │ HTTP/WS
+┌──────────┐  ┌───────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
+│ Telegram │  │ Slack │  │ WhatsApp │  │ Discord  │  │  Signal  │
+└────┬─────┘  └───┬───┘  └────┬─────┘  └────┬─────┘  └────┬─────┘
+     │            │           │             │              │
+     └────────────┴───────────┴─────────────┴──────────────┘
+                           │
+                 ┌─────────┴──────────┐
+                 │ Workspace Resolver │ (per-channel context: cwd + persona)
+                 └─────────┬──────────┘
                            │
                     ┌──────┴───────┐
                     │   Engine     │ (Query routing, fallback)
@@ -302,14 +311,15 @@ alvin-bot/
 │   ├── config.ts                # Configuration
 │   ├── handlers/                # Message & command handlers
 │   ├── middleware/              # Auth & access control
-│   ├── platforms/               # Telegram, WhatsApp, Discord, Signal adapters
+│   ├── platforms/               # Telegram, Slack, WhatsApp, Discord, Signal adapters
 │   ├── providers/               # AI provider implementations
-│   ├── services/                # Memory, voice, cron, plugins, tool discovery
+│   ├── 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
@@ -319,6 +329,89 @@ alvin-bot/
 
 ---
 
+## 🧭 Multi-Session Workspaces (v4.12.0)
+
+**Run multiple parallel Alvin sessions on the same bot — one per project, context-isolated, memory shared.** Think Claude Coworker, but on your own machine with your own tools. Each workspace has its own working directory, purpose, and optional persona. Sub-agents spawned in one workspace stay in that workspace. Memory, skills, and the knowledge base are globally shared across all of them.
+
+### Why you'd want this
+
+Without workspaces, Alvin has one big blob of context. If you ask about Alev-B deployment right after debugging a trading bot, Claude pollutes one context with the other. Workspaces solve this: **Slack channel = session**, or on Telegram, **`/workspace alev-b` = session**. Each one has its own Claude SDK `resume` token, history, and current project CLAUDE.md loaded via its working directory.
+
+### How it works
+
+1. **Drop a markdown file** into `~/.alvin-bot/workspaces/<name>.md` with YAML frontmatter.
+2. **Alvin hot-reloads** the workspace registry (no restart needed — same pattern as skills).
+3. On **Slack**, workspaces resolve by explicit channel ID first, then by channel name match (`#alev-b` → `workspaces/alev-b.md`, case-insensitive).
+4. On **Telegram**, run `/workspace <name>` to switch — next message uses the new persona and cwd.
+5. Nothing configured? Alvin falls back to the "default" workspace exactly like pre-v4.12 — **no breaking changes**.
+
+### Example workspace file
+
+Create `~/.alvin-bot/workspaces/alev-b.md`:
+
+```markdown
+---
+purpose: Alev-B consulting website dev
+cwd: ~/Projects/alev-b-website
+emoji: "🏢"
+color: "#6366f1"
+channels: ["C01ABCDEF"]
+---
+You are focused on the Alev-B consulting website. Stack: React + Express +
+Drizzle + MySQL. Production VPS 72.62.34.230, deploy via rsync. Prefer
+concise, directly actionable answers about features, deployment, and
+Stripe integration.
+```
+
+The `cwd` auto-loads the project-specific `CLAUDE.md` via Claude SDK's `settingSources: ["user", "project"]`, so each workspace inherits its project's conventions automatically. `channels` is optional — omit it to match by filename.
+
+### 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-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-`)
+4. Install the app to your workspace, copy the **Bot User OAuth Token** (starts with `xoxb-`)
+5. Add both to `~/.alvin-bot/.env`:
+   ```bash
+   SLACK_APP_TOKEN=xapp-1-...
+   SLACK_BOT_TOKEN=xoxb-...
+   SLACK_ALLOWED_USERS=U01ABCDEF      # optional, comma-separated
+   ```
+6. Restart Alvin. You should see `💬 Slack connected (Alvin @ YourWorkspace)` in the log.
+7. Invite Alvin to channels with `/invite @Alvin`. DMs work without an invite.
+
+### Telegram `/workspace` commands
+
+| Command | Effect |
+|---|---|
+| `/workspaces` | List all configured workspaces with emojis and purposes (active one marked ✅) |
+| `/workspace` | Show the currently active workspace |
+| `/workspace <name>` | Switch to `<name>` — next message uses its persona and cwd |
+| `/workspace default` | Reset to the default workspace (global cwd, no persona) |
+
+Workspace selection is per Telegram user, persisted across bot restarts via `~/.alvin-bot/state/sessions.json` (v2 envelope format, backwards compatible with v4.11).
+
+### Web UI
+
+The dashboard has a dedicated **🧭 Workspaces** tab (Data section in the sidebar). Each workspace shows as a color-coded card with emoji, purpose, cwd, mapped channels, session count, message count, and cumulative cost. Useful for spotting which project is burning the most tokens.
+
+Or query directly:
+
+```bash
+curl -s http://localhost:3100/api/workspaces | jq
+```
+
+### Architecture guarantees
+
+- **Memory is global.** Facts Alvin learns in `#alev-b` are visible in `#homes` via the shared `MEMORY.md` and embeddings index. Per-workspace memory layer is on the v4.13 roadmap.
+- **Sub-agents are per-session.** Each workspace can spawn its own `run_in_background` agents — results come back to the same channel automatically (v4.10.0).
+- **Session state survives restart.** Claude SDK `resume` tokens, conversation history, language, effort, and `workspaceName` all persist via `session-persistence.ts` (v4.11.0).
+- **Backwards compatible.** If you don't create any workspace files, everything behaves exactly like v4.11. Upgrade is a no-op.
+
+---
+
 ## ⚙️ Configuration
 
 ### Environment Variables
@@ -345,13 +438,21 @@ WHATSAPP_ENABLED=true           # Enable WhatsApp (needs Chrome)
 DISCORD_TOKEN=<token>           # Enable Discord
 SIGNAL_API_URL=<url>            # Signal REST API URL
 SIGNAL_NUMBER=<number>          # Signal phone number
+SLACK_BOT_TOKEN=xoxb-...        # Slack Bot User OAuth Token (Socket Mode)
+SLACK_APP_TOKEN=xapp-1-...      # Slack App-Level Token (connections:write scope)
+SLACK_ALLOWED_USERS=U01...      # Optional: comma-separated Slack user IDs allowlist
+
+# Multi-Session (v4.12.0)
+SESSION_MODE=per-channel        # per-user (default) | per-channel | per-channel-peer
+                                # per-channel gives each Slack channel / group its own isolated session
 
 # Optional
-WORKING_DIR=~                   # Default working directory
+WORKING_DIR=~                   # Default working directory (used when no workspace is resolved)
 MAX_BUDGET_USD=5.0              # Cost limit per session
 WEB_PORT=3100                   # Web UI port
 WEB_PASSWORD=<password>         # Web UI auth (optional)
 CHROME_PATH=/path/to/chrome     # Custom Chrome path (for WhatsApp)
+MEMORY_EXTRACTION_DISABLED=1    # Opt out of v4.11.0 auto-fact-extraction in compaction
 ```
 
 ### Custom Models
@@ -531,17 +632,81 @@ alvin-bot version   # Show version
   - [ ] 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)
+- [ ] **Phase 17** — Memory + Workspace polish (v4.13.0+)
+  - [ ] SQLite migration of the embeddings index (currently 128 MB JSON)
+  - [ ] Per-workspace memory layer (additive over global) — facts learned in `#alev-b` stay in `alev-b` unless explicitly promoted to global
+  - [ ] Per-workspace provider override (`provider:` in frontmatter) — e.g. Alev-B uses Claude Opus, JobSnack uses cheap Gemini
+  - [ ] 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 alev-b as homes-dev` spins up a new workspace from an existing one
+  - [ ] Slack slash commands (`/alvin workspace`, `/alvin status`, `/alvin new`) — native Slack command integration via Bolt
+  - [ ] 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.
 
 ---
 
 ## 🔒 Security
 
-- **User whitelist** — Only `ALLOWED_USERS` can interact with the bot
+> ### ⚠️ Important: Alvin has full shell + filesystem access
+>
+> Alvin Bot is an **autonomous AI agent** built on the Claude Agent SDK with shell, filesystem, and network access to the machine it runs on. This is by design — it's the point of the project. But it means:
+>
+> - **Treat the bot like `sudo` access** — only install it on machines where you'd trust Claude Code to run without supervision.
+> - **Never expose the Web UI (port 3100) to the internet** without HTTPS, rate limiting, and a strong `WEB_PASSWORD`. It binds to `localhost` by default.
+> - **On multi-user systems**, verify `~/.alvin-bot/.env` is chmod `600` (v4.12.2+ enforces this automatically on startup).
+> - **`ALLOWED_USERS` is your first line of defense** — v4.12.2+ refuses to start if it's empty and Telegram is enabled.
+>
+> **Read the full threat model and hardening guide:** [`docs/security.md`](docs/security.md)
+
+### Access control
+
+- **User whitelist** — Only `ALLOWED_USERS` can interact with the bot (hard-enforced at startup since v4.12.2)
 - **WhatsApp group approval** — Per-group participant whitelist + owner approval gate via Telegram (with WhatsApp DM / Discord / Signal fallback). Group members never see the approval process.
-- **Self-hosted** — Your data stays on your machine
-- **No telemetry** — Zero tracking, zero analytics, zero phone-home
-- **Web UI auth** — Optional password protection for the dashboard
-- **Owner protection** — Owner account cannot be deleted via UI
+- **Slack allowlist** — `SLACK_ALLOWED_USERS` restricts who can DM or @mention the bot in Slack
+- **DM pairing** — Optional 6-digit code flow for new users via owner approval (`AUTH_MODE=pairing`)
+
+### Execution hardening
+
+- **`EXEC_SECURITY=allowlist`** (default) — Shell commands must match a whitelist of safe binaries and **cannot contain shell metacharacters** (`;`, `|`, `&`, `` ` ``, `$(...)`, redirects). Rejected by v4.12.2's exec-guard metachar filter.
+- **Cron shell jobs** go through the same exec-guard (v4.12.2+) — cron is no longer a bypass vector.
+- **Sub-agent toolset presets** — spawn sub-agents with `toolset: "readonly"` or `"research"` to restrict what they can do, regardless of the parent's privileges.
+- **Timing-safe webhook auth** — `POST /api/webhook` uses `crypto.timingSafeEqual` (v4.12.2+) to prevent timing side-channel token extraction.
+
+### Data hardening
+
+- **Self-hosted** — Your data stays on your machine. No cloud sync, no external logging of prompts or responses.
+- **No telemetry** — Zero tracking, zero analytics, zero phone-home.
+- **File permissions** — `.env`, `sessions.json`, memory logs, cron jobs, and all sensitive state files are chmod `0o600` on every write and repaired at startup (v4.12.2+).
+- **Owner protection** — Owner account cannot be deleted via UI.
+- **Encrypted sudo credentials** — If you enable sudo exec, passwords are stored encrypted with an XOR key in a separate file, both chmod `0o600`.
+
+### Known limitations (documented honestly)
+
+- **Prompt injection** cannot be reliably filtered — we document this as a capability tradeoff rather than pretending to solve it. See `docs/security.md` for the full discussion.
+- **Not yet hardened for public-internet deployment** — current scope is "on your own machine". VPS deployment works but requires additional reverse-proxy + TLS + rate-limit setup that we don't automate.
+- **Electron Desktop build** has known CVEs (Phase 18 roadmap). The primary distribution is npm global install, not Desktop — if you don't use the Desktop wrapper, you're not affected.
 
 ---
 

package/dist/handlers/commands.js

@@ -110,6 +110,10 @@ export function registerCommands(bot) {
             `/effort — Set reasoning depth\n` +
             `/voice — Voice replies on/off\n` +
             `/dir <path> — Working directory\n\n` +
+            `🧭 *Workspaces*\n` +
+            `/workspaces — List all workspaces\n` +
+            `/workspace <name> — Switch active workspace\n` +
+            `/workspace default — Reset to default\n\n` +
             `🎨 *Extras*\n` +
             `/imagine <prompt> — Generate image\n` +
             `/remind <time> <text> — Set reminder\n` +
@@ -149,6 +153,8 @@ export function registerCommands(bot) {
         { command: "version", description: "Show Alvin Bot version" },
         { command: "new", description: "Start new session" },
         { command: "dir", description: "Change working directory" },
+        { command: "workspaces", description: "List all workspaces" },
+        { command: "workspace", description: "Switch active workspace" },
         { command: "web", description: "Quick web search" },
         { command: "imagine", description: "Generate image (e.g. /imagine A fox)" },
         { command: "remind", description: "Set reminder (e.g. /remind 30m Text)" },

package/dist/handlers/message.js

@@ -17,6 +17,7 @@ import { emitUserMessage as broadcastUserMessage, emitResponseStart as broadcast
 import { t } from "../i18n.js";
 import { isHarmlessTelegramError } from "../util/telegram-error-filter.js";
 import { handleToolResultChunk } from "./async-agent-chunk-handler.js";
+import { createStuckTimer } from "./stuck-timer.js";
 /**
  * Stuck-only timeout — NO absolute cap.
  *
@@ -37,6 +38,26 @@ import { handleToolResultChunk } from "./async-agent-chunk-handler.js";
  */
 const STUCK_TIMEOUT_MINUTES = Number(process.env.ALVIN_STUCK_TIMEOUT_MINUTES) || 10;
 const STUCK_TIMEOUT_MS = STUCK_TIMEOUT_MINUTES * 60 * 1000;
+/**
+ * v4.12.1 — Task-aware stuck timeout for sync Task/Agent tool calls.
+ *
+ * When Claude calls the Task/Agent tool WITHOUT run_in_background: true,
+ * the Claude Agent SDK runs the sub-agent synchronously inside the tool
+ * call. The parent stream emits NO intermediate chunks during that time
+ * — it's silent until the sub-agent finishes and the final tool_result
+ * arrives. With the normal STUCK_TIMEOUT_MS (10 min), this triggered a
+ * false abort on legitimate long-running sub-agents.
+ *
+ * The new approach: track pending sync Task/Agent tool calls by their
+ * toolUseId, and while any are active, escalate the idle timeout to
+ * SYNC_AGENT_IDLE_TIMEOUT_MS (default 120 min, env-configurable). After
+ * the matching tool_result arrives, revert to the normal timeout.
+ *
+ * The normal 10-min timeout still applies for genuine SDK hangs (no
+ * sync tool call active, no chunks arriving).
+ */
+const SYNC_AGENT_IDLE_TIMEOUT_MINUTES = Number(process.env.ALVIN_SYNC_AGENT_IDLE_TIMEOUT_MINUTES) || 120;
+const SYNC_AGENT_IDLE_TIMEOUT_MS = SYNC_AGENT_IDLE_TIMEOUT_MINUTES * 60 * 1000;
 /** Checkpoint reminder thresholds — kept in sync with
  *  src/providers/claude-sdk-provider.ts (where the actual hint injection
  *  happens). We mirror the check here so the session telemetry knows
@@ -165,21 +186,23 @@ export async function handleMessage(ctx) {
     const typingInterval = setInterval(() => {
         ctx.api.sendChatAction(ctx.chat.id, "typing").catch(() => { });
     }, 4000);
-    // Stuck-only timer: fires if NO chunks arrive for STUCK_TIMEOUT_MS.
-    // Reset on every chunk so any actively-progressing task runs indefinitely.
-    // No absolute cap — Alvin is allowed to work as long as needed.
-    let stuckTimer = null;
-    const resetStuckTimer = () => {
-        if (stuckTimer)
-            clearTimeout(stuckTimer);
-        stuckTimer = setTimeout(() => {
+    // v4.12.1 — Task-aware stuck timer. Normal mode (STUCK_TIMEOUT_MS)
+    // fires after 10 min of silence. When a sync Task/Agent tool call is
+    // active (tracked by toolUseId in the for-await loop below), the
+    // timeout escalates to SYNC_AGENT_IDLE_TIMEOUT_MS (120 min) so
+    // legitimate long-running sub-agents that emit no intermediate chunks
+    // don't get falsely aborted. See src/handlers/stuck-timer.ts.
+    const stuckTimer = createStuckTimer({
+        normalMs: STUCK_TIMEOUT_MS,
+        extendedMs: SYNC_AGENT_IDLE_TIMEOUT_MS,
+        onTimeout: () => {
             if (session.abortController && !session.abortController.signal.aborted) {
                 timedOut = true;
                 session.abortController.abort();
             }
-        }, STUCK_TIMEOUT_MS);
-    };
-    resetStuckTimer();
+        },
+    });
+    stuckTimer.reset();
     try {
         // React with 🤔 to show we're thinking
         await react(ctx, "🤔");
@@ -304,8 +327,25 @@ export async function handleMessage(ctx) {
         // not in the tool_result text). See Fix #17 Stage 2.
         let lastAgentToolUseInput;
         for await (const chunk of registry.queryWithFallback(queryOpts)) {
-            // Any chunk is progress — reset the stuck timer.
-            resetStuckTimer();
+            // v4.12.1 — Update pending-sync-task state FIRST so the timer's
+            // next reset picks up the new state. This ordering is load-bearing:
+            // reversing it means the timer rearms with stale state. A sync
+            // Task/Agent tool call switches the stuck timer to extended mode
+            // (120 min) to tolerate the silent gap until tool_result arrives.
+            if (chunk.type === "tool_use" &&
+                (chunk.toolName === "Task" || chunk.toolName === "Agent") &&
+                chunk.toolUseId &&
+                chunk.runInBackground !== true) {
+                stuckTimer.enterSync(chunk.toolUseId);
+            }
+            else if (chunk.type === "tool_result" && chunk.toolUseId) {
+                // Any tool_result may match a pending sync entry. Set.delete is
+                // a no-op if the id isn't in the set — safe for async results.
+                stuckTimer.exitSync(chunk.toolUseId);
+            }
+            // Any chunk is progress — reset the stuck timer (now with
+            // updated pending-sync state so the correct timeout is armed).
+            stuckTimer.reset();
             switch (chunk.type) {
                 case "text":
                     finalText = chunk.text || "";
@@ -473,8 +513,7 @@ export async function handleMessage(ctx) {
         }
     }
     finally {
-        if (stuckTimer)
-            clearTimeout(stuckTimer);
+        stuckTimer.cancel();
         clearInterval(typingInterval);
         session.isProcessing = false;
         session.abortController = null;

package/dist/handlers/stuck-timer.js

@@ -0,0 +1,54 @@
+/**
+ * Task-aware stuck timer for the Telegram message handler (v4.12.1).
+ *
+ * The main handler must detect genuine SDK hangs (no chunks for N minutes)
+ * while NOT aborting legitimate long-running work — specifically sync Agent
+ * tool calls that emit no intermediate chunks for their entire duration.
+ *
+ * State machine:
+ *   - Normal mode: idle timeout = NORMAL_MS (default 10 min, env-configurable
+ *     in message.ts via ALVIN_STUCK_TIMEOUT_MINUTES)
+ *   - When any Agent/Task tool call is known to be running sync (tracked by
+ *     its toolUseId), the next reset() arms the timer with EXTENDED_MS
+ *     instead (default 120 min, env-configurable via
+ *     ALVIN_SYNC_AGENT_IDLE_TIMEOUT_MINUTES)
+ *   - Back to NORMAL_MS once all tracked sync tool calls have emitted their
+ *     tool_result and been released via exitSync()
+ *
+ * This module is pure — no grammy, no session, no provider. Takes its ms
+ * values and onTimeout callback as constructor args. Testable in isolation
+ * with vi.useFakeTimers(). The handler owns the state; the handler decides
+ * which chunks flip the mode based on chunk.toolName and chunk.runInBackground.
+ *
+ * See docs/superpowers/plans/... and test/stuck-timer.test.ts.
+ */
+export function createStuckTimer(cfg) {
+    const pending = new Set();
+    let handle = null;
+    const currentTimeout = () => pending.size > 0 ? cfg.extendedMs : cfg.normalMs;
+    const rearm = () => {
+        if (handle)
+            clearTimeout(handle);
+        handle = setTimeout(cfg.onTimeout, currentTimeout());
+    };
+    return {
+        reset: rearm,
+        enterSync(id) {
+            pending.add(id);
+            rearm();
+        },
+        exitSync(id) {
+            pending.delete(id);
+            rearm();
+        },
+        cancel() {
+            if (handle) {
+                clearTimeout(handle);
+                handle = null;
+            }
+        },
+        _pendingCount() {
+            return pending.size;
+        },
+    };
+}