alvin-bot 4.12.0 → 4.12.1

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 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

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

@@ -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;
+        },
+    };
+}

package/dist/providers/claude-sdk-provider.js

@@ -161,6 +161,24 @@ export class ClaudeSDKProvider {
                             }
                             if ("name" in block) {
                                 localToolUseCount++;
+                                // v4.12.1 — Extract run_in_background from the raw input
+                                // object BEFORE the 500-char JSON truncation below. This is
+                                // load-bearing: 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 (→ false
+                                // 10-min abort on legitimate long-running sub-agents).
+                                // See src/handlers/stuck-timer.ts and message.ts for the
+                                // consumer side.
+                                let runInBackground;
+                                if ("input" in block &&
+                                    block.input &&
+                                    typeof block.input === "object") {
+                                    const input = block.input;
+                                    if (input.run_in_background === true)
+                                        runInBackground = true;
+                                    else if (input.run_in_background === false)
+                                        runInBackground = false;
+                                }
                                 // Serialise the tool input (parameters) so the message
                                 // handler can surface detail for specific tools — most
                                 // importantly the "Task" tool where `input.description`
@@ -176,10 +194,17 @@ export class ClaudeSDKProvider {
                                         // unserializable — skip
                                     }
                                 }
+                                // Tool-use blocks in the Anthropic API always have an `id`
+                                // at runtime, but the SDK's .d.ts shape doesn't guarantee it
+                                // — defensive cast. Used by the task-aware stuck timer to
+                                // correlate tool_use → tool_result for sync tracking.
+                                const toolUseId = block.id;
                                 yield {
                                     type: "tool_use",
                                     toolName: block.name,
                                     toolInput: toolInputStr,
+                                    toolUseId,
+                                    runInBackground,
                                     sessionId: capturedSessionId,
                                 };
                             }

package/dist/services/personality.js

@@ -61,43 +61,68 @@ const SDK_ADDON = `When you run commands or edit files, briefly explain what you
  * See test/system-prompt-background-hint.test.ts and
  * docs/superpowers/plans/2026-04-13-async-subagents.md
  */
-const BACKGROUND_SUBAGENT_HINT = `## Background Sub-Agents (IMPORTANT)
+const BACKGROUND_SUBAGENT_HINT = `## ⚠️ CRITICAL: Background Sub-Agents (Telegram blocking rule)
 
-For long-running work, ALWAYS set \`run_in_background: true\` on your Agent
-tool call. This makes the tool return IMMEDIATELY with an \`agentId\` and
-\`outputFile\` path instead of blocking for the full duration. Your main
-turn ends quickly, the user's session unlocks, and they can keep chatting
-with me while the sub-agent works in parallel.
+**The rule**: For any Agent/Task tool call that will take more than
+~30 seconds, you MUST set \`run_in_background: true\`. Otherwise the
+Telegram user is COMPLETELY BLOCKED from messaging me until the task
+finishes — terrible UX for anything that ends up taking minutes or
+hours. This is the single most important rule for using the Agent tool.
 
-After launching a background agent, you MUST:
-1. Tell the user in one short sentence what you kicked off ("Starting SEO
-   audit for gethomes.io in the background — I'll send the report when
-   it's done").
-2. End your turn promptly. Do NOT wait around. Do NOT keep working on
-   that task. Wrap up within 1-2 short messages.
-3. When the agent finishes, its final report will arrive as a SEPARATE
-   message in this chat — the bot handles that delivery automatically.
-   You don't need to poll the outputFile proactively.
+**Why it matters**: During a synchronous Agent tool call the parent
+session has no way to know the sub-agent is still working. It appears
+hung. After a long silence the session can be aborted, destroying the
+work. Using \`run_in_background: true\` solves this: the tool returns
+an \`agentId\` + \`outputFile\` path IMMEDIATELY, your turn ends in
+seconds, the user can keep chatting with me, and the bot automatically
+delivers the sub-agent's final result as a separate message when ready.
 
-If the user asks "is it done yet?" before the bot delivers the result,
-you MAY read the agent's \`outputFile\` (from the tool result) using the
-Read tool to check progress.
+**Decision tree** (apply every time you consider the Agent/Task tool):
+
+  Does the task involve ANY of the following?
+    • Visiting more than 2 URLs
+    • Reading/analyzing more than 5 files
+    • A full-repo scan, audit, or refactor proposal
+    • A multi-section report or structured document
+    • Tasks you'd describe as "thorough", "comprehensive", or "deep"
+    • Shell commands that may take >30s (builds, installs, tests)
+    • Crawling, scraping, or fetching multiple resources
+    • Research across multiple sources or domains
+
+  YES → \`run_in_background: true\` (no exceptions)
+  NO  → foreground is fine (single quick sub-query under 30s)
 
-**DO use \`run_in_background: true\` for:**
-- Audits (SEO, security, code quality, performance)
-- Research tasks that visit more than 3 web pages
-- Multi-file codebase analyses, full-repo scans
+**Examples where you MUST use \`run_in_background: true\`:**
+- ANY audit (SEO, security, code quality, performance, accessibility, GEO)
+- Research visiting more than 1-2 web pages
+- Code reviews on more than a single file
+- Full-repo analyses, dependency scans, architecture proposals
 - Report generation with multiple sub-steps
-- Anything you estimate will take longer than 2 minutes
+- Build / install / test runs
+- Long data-processing jobs
+- Anything involving the word "analyze", "audit", "review", "scan", "research"
 
-**DON'T use run_in_background for:**
-- Simple questions the user is actively waiting on a quick answer
-- Single file reads
-- Quick web fetches for a specific fact
-- Short tool chains under ~30 seconds
+**Examples where foreground is fine:**
+- "Read this file and summarize it" (single file, <10s)
+- "What's 2+2?" (no sub-agent needed — answer yourself)
+- "Check if package.json has foo" (one quick tool call)
+
+**After launching a background agent, you MUST:**
+1. Tell the user in ONE short sentence what you kicked off.
+   Example: "Starting SEO audit for gethomes.io in the background —
+   I'll send the report when it's done."
+2. End your turn IMMEDIATELY. Do not continue working. Do not wait.
+3. The bot will deliver the result as a separate message when ready.
+   You don't need to poll the outputFile proactively.
+
+If the user asks "is it done yet?" before the bot delivers the result,
+you MAY read the agent's \`outputFile\` (from the original tool result)
+using the Read tool to peek at progress — but don't block on it.
 
-When in doubt: prefer background for audits/research, foreground for
-conversational answers.`;
+**Never** call the Agent/Task tool without \`run_in_background: true\`
+for anything you're not 100% sure completes in under 30 seconds. The
+cost of unnecessary background mode is zero. The cost of blocking the
+Telegram user for 20 minutes on a synchronous call is very high.`;
 /**
  * Self-Awareness Core — Dynamic introspection block.
  *

package/package.json

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