alvin-bot 4.11.0 → 4.12.1

package/CHANGELOG.md

@@ -2,6 +2,154 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [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
+
+A colleague's feature request the same day v4.11.0 shipped: *"Multiple Session und Interface über Slack — wie bei OpenClaw. Du hast mehrere parallele Sessions, die den jeweiligen Kontext voneinander nicht kennen aber in sich einen bestimmten Kontext und Zweck haben. Sie hatten dabei Zugriff auf das gesamte Knowledge (Skills + Memory). Und konnten bei Bedarf eigene agents starten."*
+
+The ultra-analysis revealed Alvin was already ~80% built for this: the Slack adapter existed (355 LOC with `@slack/bolt@4.6.0`), the platform abstraction was clean, `buildSessionKey()` already supported `per-channel` mode, `session.workingDir` was already per-session, sub-agents were already async and session-isolated (v4.10.0), and memory/skills were already globally shared. **The single blocker: one line in `platform-message.ts` that bypassed `buildSessionKey` with a naive `hashUserId(userId)`, collapsing every non-Telegram channel from the same user into one session.**
+
+This release adds a thin workspace layer on top plus Slack polish. **No breaking changes** — if no workspaces are configured, pre-v4.12 behavior is preserved exactly.
+
+#### P0 #1 — Session-Key Fix (`src/handlers/platform-message.ts`)
+
+`handlePlatformMessage` now routes through `buildSessionKey(msg.platform, msg.chatId, msg.userId)` instead of `hashUserId(msg.userId)`. On Slack with `SESSION_MODE=per-channel`, each channel gets its own session. Cross-channel isolation is automatic.
+
+`buildSessionKey` signature widened from `userId: number` to `userId: string | number` so Slack user IDs (`U01ABC...`) pass through unchanged.
+
+**6 unit tests** covering per-channel / per-channel-peer / per-user modes, cross-channel isolation, cross-platform isolation, and backwards compat with numeric Telegram user IDs.
+
+#### P0 #2 — Workspace Registry (`src/services/workspaces.ts`, NEW)
+
+Loads `~/.alvin-bot/workspaces/*.md` markdown files with YAML frontmatter. Each workspace has: `name`, `purpose`, `cwd`, optional `color`/`emoji`, explicit `channels: []` array for ID-based mapping, and a markdown body that becomes the system prompt override.
+
+Hot-reload via `fs.watch()` with 500 ms debounce — same pattern as `src/services/skills.ts`. Changes to workspace files are picked up without a bot restart.
+
+Public API: `loadWorkspaces`, `reloadWorkspaces`, `listWorkspaces`, `getWorkspace`, `getDefaultWorkspace`, `matchWorkspaceForChannel`, `resolveWorkspaceOrDefault`, `initWorkspaces`, `startWorkspaceWatcher`, `stopWorkspaceWatcher`.
+
+**13 unit tests** covering default fallback, single/multi-workspace load, `~` expansion in cwd, channel-ID match, channel-name match, hot-reload, non-`.md` file skipping, malformed frontmatter resilience, missing directory graceful handling.
+
+#### P0 #3 — Workspace Resolver Integration (`src/handlers/platform-message.ts`, `src/handlers/message.ts`)
+
+Both the platform handler (Slack/Discord/WhatsApp) and the Telegram main handler now resolve the incoming message to a workspace before building the system prompt. If the session's `workspaceName` changed vs. the previous turn, `workingDir` is updated and persisted via `session-persistence` (v4.11.0).
+
+`buildSystemPrompt` and `buildSmartSystemPrompt` gained a new optional `workspacePersona` parameter that injects a `## Workspace Persona` section into the system prompt. Empty string = no-op (default workspace).
+
+`UserSession` gained a new `workspaceName: string | null` field. Persisted across restarts via the new v2 envelope format in `sessions.json` (backwards compatible with v4.11 flat format — the loader auto-detects).
+
+#### P0 #4 — Slack Setup Documentation (`docs/install/slack-setup.md`, `docs/install/slack-manifest.json`)
+
+Step-by-step guide: create Slack App from manifest → Socket Mode → App-Level Token → Bot Token → `~/.alvin-bot/.env` → restart → invite bot → create workspace files. Covers troubleshooting for common issues. The `slack-manifest.json` is copy-paste-ready: pre-configured bot user, all required scopes, event subscriptions, Socket Mode enabled. Both files are gitignored (Ali's docs/install/ convention) and ship via GitHub Release assets.
+
+#### P1 #1 — Slack Progress Ticker (`src/platforms/slack.ts`)
+
+`SlackAdapter.sendText()` now returns the message `ts` so callers can hold on to it. New `SlackAdapter.editMessage(chatId, messageId, newText)` wraps `chat.update`. Fail-silent: if Slack API errors, the ticker degrades gracefully and the full message still arrives at query end.
+
+`PlatformAdapter` interface: `sendText` return type widened from `void` to `string | void`, optional `editMessage` method added. Existing adapters (Telegram, WhatsApp, Discord, Signal) that don't implement `editMessage` are unaffected.
+
+**3 unit tests** with mocked `@slack/bolt` covering `chat.update` call, `sendText` ts return, and graceful failure handling.
+
+#### P1 #2 — Slack Typing Status + Channel Name Resolution (`src/platforms/slack.ts`)
+
+`SlackAdapter.setTyping()` now calls `assistant.threads.setStatus` so Slack shows "Alvin is thinking…" under the message during long queries. Silently no-ops in channels where the assistant scope isn't granted.
+
+New `SlackAdapter.getChannelName(channelId)` resolves + caches channel names via `conversations.info`. `platform-message.ts` detects this helper via duck-typing on the adapter and passes the resolved name to `resolveWorkspaceOrDefault` — enabling channel-name matching (`#alev-b` → `workspaces/alev-b.md`) without hardcoding the Slack type in the platform handler.
+
+#### P1 #3 — Telegram `/workspace` + `/workspaces` Commands
+
+Feature parity for Telegram. `/workspaces` lists all configured workspaces with emojis, purposes, and the active one marked ✅. `/workspace <name>` switches the active workspace for the Telegram user; next message uses the new persona and cwd. `/workspace default` resets.
+
+New `session.ts` exports: `getTelegramWorkspace(userId)` / `setTelegramWorkspace(userId, name)` + a module-level `telegramWorkspaces` map persisted via a new v2 envelope format in `sessions.json` (backwards compatible with v4.11 flat format).
+
+**5 new unit tests** covering getter/setter/null-clear, persistence roundtrip, and v4.11 flat-format backwards compat.
+
+#### P1 #4 — Per-Workspace Cost Aggregation (`src/services/session.ts`)
+
+New `getCostByWorkspace()` helper aggregates `session.totalCost` by `session.workspaceName` across all active sessions in memory. Returns per-workspace totals for cost, session count, message count, and tool use count. Used by the Web UI workspace cards.
+
+Sessions with `workspaceName === null` aggregate under `"default"` in the breakdown.
+
+#### P1 #5 — Web UI Workspace Cards (`src/web/server.ts`, `web/public/index.html`, `web/public/js/app.js`)
+
+New `GET /api/workspaces` endpoint returns the workspace registry merged with `getCostByWorkspace()`. Dashboard SPA gains a "🧭 Workspaces" page in the Data section of the sidebar (between Sessions and Files). Cards show emoji, name, purpose, cwd, channel mappings, session count, message count, and cumulative cost — color-coded via workspace frontmatter `color` field.
+
+Default workspace is always included even when no user configs exist, so the UI always shows at least one card.
+
+#### Architecture Decisions
+
+- **Workspace is channel-scoped, not thread-scoped.** Slack channel = workspace. Threads within a channel are continuations of the same session.
+- **Memory stays global.** All workspaces share `MEMORY.md`, the Hub memory, and the embeddings index.
+- **Provider stays global.** Per-workspace provider override deferred to v4.13.
+- **`@slack/bolt@^4.6.0`** is a regular dep, already in `package.json` from a previous branch.
+- **Backwards compat is absolute.** If no workspaces exist, `resolveWorkspaceOrDefault` returns the default workspace with empty persona + global cwd. v4.11 flat-format `sessions.json` files still load without migration.
+- **v2 envelope format**: `sessions.json` is now `{ version: 2, sessions: {...}, telegramWorkspaces: {...} }`. Loader auto-detects and handles both legacy flat format and new envelope.
+
+#### Testing
+
+**330 tests total** (292 baseline from v4.11 + 38 new). All green. TSC clean.
+
+- 6 platform-session-key unit tests
+- 14 workspaces unit + integration tests
+- 3 slack-progress-ticker tests (mocked @slack/bolt)
+- 5 telegram-workspace-command tests
+- 10 multi-session end-to-end stress tests
+
+**Live verified** via `tmp/live-multi-session.mjs` probe against the real `dist/`: 5 parallel workspaces, 5 simulated Slack channels, full persistence roundtrip with v2 envelope, cost aggregation, hot-reload picking up new workspace files, channel-name fallback, telegramWorkspaces map persistence. **All 7 phases passed.**
+
+#### Files changed
+
+- **NEW code:** `src/services/workspaces.ts`
+- **NEW tests:** `test/platform-session-key.test.ts`, `test/workspaces.test.ts`, `test/slack-progress-ticker.test.ts`, `test/telegram-workspace-command.test.ts`, `test/multi-session-stress.test.ts`
+- **NEW docs (gitignored, in Release assets):** `docs/install/slack-setup.md`, `docs/install/slack-manifest.json`
+- **Modified:** `src/handlers/platform-message.ts`, `src/handlers/message.ts`, `src/handlers/commands.ts`, `src/platforms/slack.ts`, `src/platforms/types.ts`, `src/services/session.ts`, `src/services/session-persistence.ts`, `src/services/personality.ts`, `src/paths.ts`, `src/index.ts`, `src/web/server.ts`, `web/public/index.html`, `web/public/js/app.js`
+- **Plan:** `docs/superpowers/plans/2026-04-13-multi-session-slack.md`
+
+---
+
 ## [4.11.0] — 2026-04-13
 
 ### 🧠 Memory Persistence + Smart Loading — sessions survive restart, memory is layered

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,6 +632,33 @@ 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
 
 ---
 

package/dist/handlers/commands.js

@@ -2,7 +2,8 @@ import { InlineKeyboard, InputFile } from "grammy";
 import fs from "fs";
 import path, { resolve } from "path";
 import os from "os";
-import { getSession, resetSession, markSessionDirty } from "../services/session.js";
+import { getSession, resetSession, markSessionDirty, getTelegramWorkspace, setTelegramWorkspace } from "../services/session.js";
+import { listWorkspaces, getWorkspace } from "../services/workspaces.js";
 import { getRegistry } from "../engine.js";
 import { reloadSoul } from "../services/personality.js";
 import { parseDuration, createReminder, listReminders, cancelReminder } from "../services/reminders.js";
@@ -109,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` +
@@ -148,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)" },
@@ -425,6 +432,50 @@ export function registerCommands(bot) {
         markSessionDirty(userId);
         await ctx.reply(`✅ Effort: ${EFFORT_LABELS[session.effort]}`);
     });
+    // v4.12.0 P1 #3 — Multi-workspace support on Telegram
+    bot.command("workspaces", async (ctx) => {
+        const userId = ctx.from.id;
+        const active = getTelegramWorkspace(userId) ?? "default";
+        const all = listWorkspaces();
+        if (all.length === 0) {
+            await ctx.reply("🧭 No workspaces configured.\n\n" +
+                "Create one by adding a file at `~/.alvin-bot/workspaces/<name>.md` " +
+                "with YAML frontmatter. See docs/install/slack-setup.md for the format.", { parse_mode: "Markdown" });
+            return;
+        }
+        const lines = [`🧭 *Workspaces* (active: \`${active}\`)`, ""];
+        for (const ws of all) {
+            const marker = ws.name === active ? "✅" : (ws.emoji ?? "▪️");
+            const purpose = ws.purpose || "(no purpose)";
+            lines.push(`${marker} \`${ws.name}\` — ${purpose}`);
+        }
+        lines.push("");
+        lines.push("Switch with: `/workspace <name>` · Reset: `/workspace default`");
+        await ctx.reply(lines.join("\n"), { parse_mode: "Markdown" });
+    });
+    bot.command("workspace", async (ctx) => {
+        const userId = ctx.from.id;
+        const arg = ctx.match?.trim();
+        if (!arg) {
+            const active = getTelegramWorkspace(userId) ?? "default";
+            const ws = active === "default" ? null : getWorkspace(active);
+            const purpose = ws?.purpose || "global default — no persona, global cwd";
+            await ctx.reply(`🧭 Active workspace: *${active}*\n_${purpose}_\n\nUse \`/workspaces\` to see all available.`, { parse_mode: "Markdown" });
+            return;
+        }
+        if (arg === "default" || arg === "reset") {
+            setTelegramWorkspace(userId, null);
+            await ctx.reply("✅ Switched to the default workspace.");
+            return;
+        }
+        const ws = getWorkspace(arg);
+        if (!ws) {
+            await ctx.reply(`❌ Workspace \`${arg}\` not found.\nUse \`/workspaces\` to list available ones.`, { parse_mode: "Markdown" });
+            return;
+        }
+        setTelegramWorkspace(userId, arg);
+        await ctx.reply(`✅ Switched to workspace *${ws.emoji ?? "🧭"} ${ws.name}*\n_${ws.purpose || "(no purpose set)"}_\n\nNext message will use this workspace's persona and cwd (\`${ws.cwd}\`).`, { parse_mode: "Markdown" });
+    });
     // Inline keyboard callback for effort switching
     bot.callbackQuery(/^effort:(.+)$/, async (ctx) => {
         const level = ctx.match[1];

package/dist/handlers/message.js

@@ -1,6 +1,7 @@
 import { InputFile } from "grammy";
 import fs from "fs";
-import { getSession, addToHistory, trackProviderUsage, buildSessionKey } from "../services/session.js";
+import { getSession, addToHistory, trackProviderUsage, buildSessionKey, getTelegramWorkspace } from "../services/session.js";
+import { resolveWorkspaceOrDefault, getWorkspace } from "../services/workspaces.js";
 import { TelegramStreamer } from "../services/telegram.js";
 import { getRegistry } from "../engine.js";
 import { textToSpeech } from "../services/voice.js";
@@ -16,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.
  *
@@ -36,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
@@ -164,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, "🤔");
@@ -226,10 +250,22 @@ export async function handleMessage(ctx) {
         // and rehydrated sessions where the persisted snapshot lacked a sessionId.
         // After the first SDK turn, Claude resumes via SDK session_id and already
         // carries the recalled context — no need for another search per turn.
+        //
+        // v4.12.0 — Resolve the user's active Telegram workspace (if any) and
+        // forward the persona to buildSmartSystemPrompt. If the workspace
+        // changed since last turn, update session's workingDir + workspaceName.
+        const activeWsName = getTelegramWorkspace(userId);
+        const workspace = activeWsName
+            ? (getWorkspace(activeWsName) ?? resolveWorkspaceOrDefault("telegram", String(userId), undefined))
+            : resolveWorkspaceOrDefault("telegram", String(userId), undefined);
+        if (session.workspaceName !== workspace.name) {
+            session.workspaceName = workspace.name;
+            session.workingDir = workspace.cwd;
+        }
         const chatIdStr = String(ctx.chat.id);
         const skillContext = buildSkillContext(text);
         const isFirstSDKTurn = isSDK && session.sessionId === null;
-        const systemPrompt = (await buildSmartSystemPrompt(isSDK, session.language, text, chatIdStr, isFirstSDKTurn)) + skillContext;
+        const systemPrompt = (await buildSmartSystemPrompt(isSDK, session.language, text, chatIdStr, isFirstSDKTurn, workspace.systemPromptOverride)) + skillContext;
         // Track the user turn in history regardless of provider type. This keeps
         // the fallback path (Ollama etc.) aware of what was said on SDK turns.
         addToHistory(userId, { role: "user", content: text });
@@ -291,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 || "";
@@ -460,8 +513,7 @@ export async function handleMessage(ctx) {
         }
     }
     finally {
-        if (stuckTimer)
-            clearTimeout(stuckTimer);
+        stuckTimer.cancel();
         clearInterval(typingInterval);
         session.isProcessing = false;
         session.abortController = null;