alvin-bot 4.15.1 → 4.16.0

package/CHANGELOG.md

@@ -2,6 +2,69 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [4.16.0] — 2026-04-20
+
+### 🚀 Feature: bot-owned CDP Chromium — no more hub dependency
+
+**Problem for new users:** The bot's CDP strategy and the `browse` / `social-fetch` skills referenced `~/.claude/hub/SCRIPTS/browser.sh` — a private tooling setup that only the maintainer has. New npm installs silently lacked a working CDP path; the skill-documented commands errored with "file not found". A second failure mode: when a user followed any online guide to start Chrome with `--remote-debugging-port` while their daily Chrome was already running, macOS LaunchServices silently routed the call to the existing instance without applying the flag (log: "Wird in einer aktuellen Browsersitzung geöffnet"), and no CDP endpoint came up.
+
+**Fix — three additions:**
+
+1. **`src/services/cdp-bootstrap.ts` (new):** Spawns Playwright's bundled *Google Chrome for Testing* binary with a distinct bundle ID — zero conflict with the user's daily Chrome. Dynamic binary resolution walks the latest `chromium-NNNN/` cache directory; cross-platform (macOS arm64/x64, Linux, Windows). Idempotent `ensureRunning()` — safe to call from multiple concurrent code paths, serialized via a single-flight lock. Cleans stale PID files, verifies liveness via both process signal and CDP `/json/version` probe, captures Chromium stderr to `~/.alvin-bot/browser/chrome-cdp.log` for diagnosis.
+
+2. **`alvin-bot browser` CLI subcommand (new):** Stable shell interface that works on every install — `start`, `stop`, `status`, `goto`, `shot`, `eval`, `tabs`, `doctor`. Wraps the bootstrap so agents in skills have a single, documented command. Screenshots default to `~/.alvin-bot/browser/screenshots/`.
+
+3. **`browser-manager` rewired:** The `cdp` strategy now calls `cdp-bootstrap.ensureRunning()` first (works for every install), and only falls back to the hub script if present (maintainer-only dev convenience). The whole cascade still works with no hub at all.
+
+**Skills updated:**
+- `skills/browse/SKILL.md` — rewritten to use `alvin-bot browser ...` commands; hub-script references removed (kept as "if present" note for dev environments).
+- `skills/social-fetch/SKILL.md` — CDP fallback line uses `alvin-bot browser goto/shot`.
+
+**Docs:**
+- `CLAUDE.md` — browser automation section switched to `alvin-bot browser` everywhere. Tier 0 (curl/WebFetch) now explicit as the cheapest path. Tier 1 example uses inline `node -e` + Playwright (no hub dependency).
+- `src/paths.ts` — `HUB_BROWSER_SH` annotated as dev-only optional. New paths: `CDP_PROFILE_DIR`, `CDP_SCREENSHOTS_DIR`, `CDP_PID_FILE`, `CDP_LOG_FILE` under `~/.alvin-bot/browser/`.
+
+**First-run setup (one-time):**
+```bash
+npx playwright install chromium
+```
+
+**Verified on 2026-04-20 with user's daily Chrome running:**
+- `alvin-bot browser start` → PID + endpoint, no LaunchServices hijack
+- `alvin-bot browser stop` + immediate `alvin-bot browser shot <url>` → CDP auto-starts, screenshot written (15 KB PNG in `~/.alvin-bot/browser/screenshots/`)
+- `alvin-bot browser doctor` → all 4 checks green (binary, endpoint, PID, profile lock)
+- `npm test` → 504/504 tests passing
+
+## [4.15.2] — 2026-04-17
+
+### 🐛 Fix: sleep-aware heartbeat prevents false failover after macOS wake
+
+**Problem:** When the Mac goes to sleep, Node.js' `setInterval` pauses completely. After waking up, the first heartbeat probe runs against a CLI + network stack that's still warming up (OAuth token refresh, DNS cache cold, TCP connections stale). The 5s `isAvailable()` timeout is too tight for post-wake latency → probe fails → 2 consecutive failures (the heartbeat fires its backlog) → auto-failover to Ollama → the bot silently answers via Gemma4 instead of Claude, sometimes for hours.
+
+**Evidence:** Logs showed a 7-hour gap (02:02–09:14 UTC) with zero heartbeat activity — the Mac was asleep. Immediately after wake, `claude-sdk: failure 1/2` → `unhealthy` → Ollama boot. The auto-recovery logic was correct but had no chance to fire before a manual restart.
+
+**Fix — three mechanisms in `heartbeat.ts`:**
+
+1. **Sleep detection via wall-clock drift:** If `now - lastHeartbeatRanAt > 2× interval`, the machine was suspended. On detection:
+   - 60s grace period where probe failures don't count toward the fail threshold
+   - All stale failure counters reset to zero (pre-sleep failures are meaningless)
+   - `isAvailable()` caches invalidated (a 7-hour-old "available: false" cache must not survive wake)
+
+2. **Quick recovery probe:** After every failover, schedule an extra heartbeat after 60s (not 5 min). If the primary is already back, recovery happens in ≤60s instead of up to 5 minutes.
+
+3. **Cache invalidation API:** `ClaudeSDKProvider.invalidateAvailabilityCache()` exposed so the heartbeat can clear stale results after sleep.
+
+**Typical post-sleep flow with fix:**
+```
+[wake]   → 💓 😴 Sleep detected (~420min gap). Grace period 60s
+         → reset claude-sdk to healthy, invalidate caches
+[+0s]    → 💓 😴 claude-sdk: probe failed during grace period — not counting
+[+60s]   → grace expired → normal probe → claude-sdk healthy ✅
+```
+Without the fix, the same scenario triggered failover at +0s.
+
+---
+
 ## [4.15.1] — 2026-04-16
 
 ### 🐛 Patch: suppress `fallbackModel` when primary is Haiku
@@ -94,7 +157,7 @@ Four hardcoded Claude model IDs replaced with current strings: `claude-sonnet-4-
 
 ### 🐛 Patch: watcher zombie-entry fix (missing outputFile > 10 min = failed)
 
-**Edge case Ali caught today:** a pending async-agent entry stuck in `/subagents list` for 3+ hours showing "running" — but the underlying `alvin_dispatch_agent` subprocess had already died (its output file was gone). The entry would have continued haunting the list until the 12-hour `giveUpAt` ceiling fired.
+**Edge case the maintainer caught today:** a pending async-agent entry stuck in `/subagents list` for 3+ hours showing "running" — but the underlying `alvin_dispatch_agent` subprocess had already died (its output file was gone). The entry would have continued haunting the list until the 12-hour `giveUpAt` ceiling fired.
 
 **Root cause:** `async-agent-watcher`'s `pollOnce` handled four states from `parseOutputFileStatus` — `completed` / `failed` / `running` / `missing`. For `missing` (file doesn't exist or is empty), the watcher just kept polling forever, on the assumption that a slow subprocess might eventually write. If the subprocess crashed before writing ANY output, the file never appeared, and we polled for 12 hours before timing out.
 
@@ -137,7 +200,7 @@ Four hardcoded Claude model IDs replaced with current strings: `claude-sonnet-4-
 
 ### 🐛 Patch: `/subagents list` now shows v4.13+ dispatch agents too
 
-**Bug Ali caught:** typing `/subagents list` in Telegram while a `alvin_dispatch_agent` sub-agent was actively running returned "no agents running" — even though the user could see the agent finish and deliver a result shortly after. Cross-platform effect too: `/alvin` slash command on Slack had the same display gap.
+**Bug the maintainer caught:** typing `/subagents list` in Telegram while a `alvin_dispatch_agent` sub-agent was actively running returned "no agents running" — even though the user could see the agent finish and deliver a result shortly after. Cross-platform effect too: `/alvin` slash command on Slack had the same display gap.
 
 **Root cause:** two separate registries for sub-agents:
 - `src/services/subagents.ts` `activeAgents` Map — used since v4.0.0 for bot-level sub-agents (cron spawns, implicit Task tool children, `/sub-agents spawn` CLI)
@@ -392,7 +455,7 @@ This matches the OpenClaw experience the user was asking about — except it's b
 
 ### 🐛 Patch: recover partial output from interrupted background sub-agents
 
-**The bug Ali saw:** Two Telegram messages appeared hours apart: `⏱️ Background agent a5bf8c74 timeout · 720m 3s · 0 in / 0 out` and `... ab9372d4 timeout · 720m 1s · 0 in / 0 out`, both with `(empty output)`. Three more agents were still pending, all interrupted mid-execution with hundreds of KB of real work sitting on disk.
+**The bug the maintainer saw:** Two Telegram messages appeared hours apart: `⏱️ Background agent a5bf8c74 timeout · 720m 3s · 0 in / 0 out` and `... ab9372d4 timeout · 720m 1s · 0 in / 0 out`, both with `(empty output)`. Three more agents were still pending, all interrupted mid-execution with hundreds of KB of real work sitting on disk.
 
 **Root cause:** v4.12.3's bypass-abort calls `session.abortController.abort()`, which propagates through `claude-sdk-provider.ts`'s `internalAbortController` into the SDK's CLI subprocess, which in turn propagates into any in-flight `Agent(run_in_background: true)` tool executions. Evidence from the disk:
 
@@ -441,7 +504,7 @@ Result: on the next `pollOnce()` after v4.12.4 ships, the three stuck agents get
 
 ### 🐛 Patch: Background sub-agent no longer blocks the main Telegram session
 
-**The bug Ali reported:** After launching an async sub-agent (`run_in_background: true`), sending any follow-up message to the bot silently stalled for 2+ minutes before being processed. v4.12.1/v4.12.2 attempted a prompt-hint mitigation but did NOT address the architectural root cause.
+**The bug the maintainer reported:** After launching an async sub-agent (`run_in_background: true`), sending any follow-up message to the bot silently stalled for 2+ minutes before being processed. v4.12.1/v4.12.2 attempted a prompt-hint mitigation but did NOT address the architectural root cause.
 
 **Root cause (re-diagnosed with live SDK event logs):** The Claude Agent SDK's CLI subprocess stays alive for the full duration of a background task so it can inject the `<task-notification>` inline into the NEXT assistant turn. While that subprocess idles, Alvin's query iterator is still being drained, `session.isProcessing` stays `true`, and every new user message gets pushed into the 3-slot queue — which doesn't auto-drain. From the user's perspective: send "A" → nothing happens for 2 minutes.
 
@@ -663,7 +726,7 @@ Both the platform handler (Slack/Discord/WhatsApp) and the Telegram main handler
 
 #### 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.
+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 (the maintainer's docs/install/ convention) and ship via GitHub Release assets.
 
 #### P1 #1 — Slack Progress Ticker (`src/platforms/slack.ts`)
 
@@ -677,7 +740,7 @@ Step-by-step guide: create Slack App from manifest → Socket Mode → App-Level
 
 `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.
+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 (`#my-project` → `workspaces/my-project.md`) without hardcoding the Slack type in the platform handler.
 
 #### P1 #3 — Telegram `/workspace` + `/workspaces` Commands
 
@@ -793,7 +856,7 @@ Inspired by Mem0's auto-extraction. When `compactSession()` archives old message
 
 - **mempalace as MCP server: rejected.** Considered installing mempalace as a Python MCP service. Rejected because (1) Alvin is all-TypeScript and adding a 2nd Python service to launchd is operational complexity, (2) Alvin already has an embeddings vector index — mempalace would be a parallel duplicate, (3) mempalace's MCP tools are only consumed by the SDK; cron jobs, sub-agents, and non-SDK providers wouldn't see them. Conclusion: **adopt the patterns natively** (L0–L3 layering, AAAK-style structured extraction) rather than running a second service.
 - **SQLite migration deferred.** The 128 MB JSON embeddings index is a known performance issue and is already noted in `~/.claude/projects/-Users-alvin-de/memory/project_alvinbot_sqlite_migration.md` for v4.12+. Orthogonal to the "frickelig nach Restart" UX problem this release targets.
-- **Multi-user isolation deferred.** Memories are still global per data dir. Single-user use case, not a privacy concern for Ali's setup.
+- **Multi-user isolation deferred.** Memories are still global per data dir. Single-user use case, not a privacy concern for the maintainer's setup.
 - **Decay/aging deferred.** Daily logs grow monotonically. Will be addressed alongside SQLite migration.
 
 #### Testing
@@ -868,11 +931,11 @@ Live-verified via isolated SDK probe (`node sdk-probe.mjs` inside the repo) whic
 
 #### What you'll see as a user
 
-Send: *"Make a SEO audit of gethomes.io and alev-b.com in parallel"*
+Send: *"Make a SEO audit of example.com and example.com in parallel"*
 
 - **0 s** — Claude responds: *"Starting both audits in the background — I'll send the reports when done."* Main session **unlocks**.
 - **1–10 min later** — You can chat about anything else. The bot answers immediately.
-- **~13 min** (when each agent finishes) — Two separate banner messages arrive: *"✅ SEO audit gethomes.io completed · 13m 17s · 2.6M in / 28k out"* + the full report body, delivered via the v4.9.3 Markdown→plain-text fallback path.
+- **~13 min** (when each agent finishes) — Two separate banner messages arrive: *"✅ SEO audit example.com completed · 13m 17s · 2.6M in / 28k out"* + the full report body, delivered via the v4.9.3 Markdown→plain-text fallback path.
 
 #### Non-goals
 
@@ -931,7 +994,7 @@ He was right. My v4.9.0 `stopWebServer()` fix was *prevention* — it stopped th
 
 ### 🛠 Two UX bugs found in production after v4.9.2 — now closed
 
-Ali triggered `/cron run Daily Job Alert` after the v4.9.2 deploy and saw 13 minutes of chat silence followed by nothing. Forensics on the live bot revealed two distinct problems on top of an already-successful run:
+the maintainer triggered `/cron run Daily Job Alert` after the v4.9.2 deploy and saw 13 minutes of chat silence followed by nothing. Forensics on the live bot revealed two distinct problems on top of an already-successful run:
 
 **1. `subagent-delivery` has been silently dropping every banner for days.** Err.log: `GrammyError: Call to 'sendMessage' failed! (400: Bad Request: can't parse entities: Can't find end of the entity starting at byte offset 2636)`. The daily-job-alert sub-agent produces markdown-dense output (`|` tables, `**bold**`, `\|` escapes, mixed asterisks). Telegram's Markdown parser refuses it, `api.sendMessage(..., parse_mode: "Markdown")` throws, and the bare try/catch in `deliverSubAgentResult` logs + bails. **Result: the user has never seen a sub-agent-delivery banner, even when the underlying run succeeded perfectly and emailed the HTML report correctly.**
 
@@ -1060,12 +1123,12 @@ The `browse` skill used to instruct the agent to start `node scripts/browse-serv
   - **Tier 1** — `browser.sh stealth <url>` (Playwright + stealth plugin, headless, Cloudflare-masking)
   - **Tier 2** — `browser.sh cdp {start|goto|shot|tabs|stop}` (real Chrome with persistent profile at `~/.claude/hub/BROWSER/profile/`, login cookies survive restarts)
   - **Tier 3** — Claude-in-Chrome extension via MCP tools (interactive CLI only)
-  - Explicit escalation ladder (WebFetch → stealth → CDP → ask Ali to log in) and a `NIEMALS browse-server.cjs nutzen` anti-rule.
+  - Explicit escalation ladder (WebFetch → stealth → CDP → ask the maintainer to log in) and a `NIEMALS browse-server.cjs nutzen` anti-rule.
   - Concrete working targets (StepStone ✅, Michael Page ✅, LinkedIn ✅ with login, Indeed ❌) so the agent knows what to try where.
 
 - **`src/services/browser-manager.ts` — hardened fallback chain.** The multi-strategy manager already had the right *shape* (`gateway → cdp → hub-stealth → cli`) but several ops silently broke or hung:
   - **`gatewayRequest` now has a 15 s timeout** (`req.destroy` on elapse). Previously a hung gateway would wedge the caller forever.
-  - **CDP fallback for interactive ops.** `click`, `fill`, `type`, `press`, `scroll`, `evaluate`, `info`, and `getTree` used to hard-throw `"requires gateway"` when `browse-server.cjs` wasn't running. They now try the gateway first, then a short-lived `chromium.connectOverCDP()` via a new `withCdpPage()` helper that reuses Ali's live Chrome on port 9222. Refs are interpreted as CSS selectors when gateway is absent.
+  - **CDP fallback for interactive ops.** `click`, `fill`, `type`, `press`, `scroll`, `evaluate`, `info`, and `getTree` used to hard-throw `"requires gateway"` when `browse-server.cjs` wasn't running. They now try the gateway first, then a short-lived `chromium.connectOverCDP()` via a new `withCdpPage()` helper that reuses the maintainer's live Chrome on port 9222. Refs are interpreted as CSS selectors when gateway is absent.
   - **Explicit PNG extension** on auto-generated screenshot filenames (`shot_<ts>.png`) so Playwright's format inference is unambiguous.
   - **Better error messages** — every "needs interactive" throw now includes the exact command to start CDP Chrome (`~/.claude/hub/SCRIPTS/browser.sh cdp start headless`).
 
@@ -1094,7 +1157,7 @@ Sub-agents and `ai-query` cron jobs used to hard-cap at 5 minutes (`SUBAGENT_TIM
 
 ### 🐛 Silenced harmless `message is not modified` Telegram errors
 
-Occasionally Ali would see a red banner at the bottom of an Alvin message:
+Occasionally the maintainer would see a red banner at the bottom of an Alvin message:
 
 > Error: Call to 'editMessageText' failed! (400: Bad Request: message is not modified: specified new message content and reply markup are exactly the same as a current content and reply markup of the message)
 
@@ -1129,7 +1192,7 @@ After 4.8.7, running `/update` after a manual rebuild will correctly say *"Disk
 
 ### ✨ Internal watchdog with crash-loop brake (`src/services/watchdog.ts`)
 
-Ali asked for "derbe persistent" — already 95% there with `KeepAlive: true` from 4.8.6, but the missing piece was a brake to stop the bot from infinite-restart-looping if a deterministic crash happens (corrupt state file, missing dependency, broken upgrade).
+the maintainer asked for "derbe persistent" — already 95% there with `KeepAlive: true` from 4.8.6, but the missing piece was a brake to stop the bot from infinite-restart-looping if a deterministic crash happens (corrupt state file, missing dependency, broken upgrade).
 
 **New module**: `src/services/watchdog.ts`. Two responsibilities:
 
@@ -1244,7 +1307,7 @@ After 4.8.5, `/update` on the test MacBook will correctly detect the npm install
 
 ### 🐛 WhatsApp self-chat detection for the new `@lid` identity format
 
-Ali reported that the WhatsApp bot wasn't responding to "Hi" in his self-chat even after enabling both `Self-chat only` and `Reply to private messages` in the Web UI. Debug logging showed the bot receiving the message correctly and detecting `fromMe=true`, but then hitting the "skip: own message in group/DM" branch because `isSelfChat()` was returning `false`.
+the maintainer reported that the WhatsApp bot wasn't responding to "Hi" in his self-chat even after enabling both `Self-chat only` and `Reply to private messages` in the Web UI. Debug logging showed the bot receiving the message correctly and detecting `fromMe=true`, but then hitting the "skip: own message in group/DM" branch because `isSelfChat()` was returning `false`.
 
 **Root cause**: WhatsApp has rolled out a new privacy feature that replaces phone-number JIDs in self-chats (and some groups) with a **LID — Linked Identity**. Instead of `4917661236656@s.whatsapp.net`, messages in a self-chat now arrive with `jid = "162805718225143@lid"` — a completely opaque identifier that looks nothing like the phone number.
 
@@ -1316,7 +1379,7 @@ Offline-friendly status command — no running bot required. Prints:
   - On Linux/Windows: `pm2 jlist` check for the `alvin-bot` process
 - **Live info** (when the bot is running with the web UI on :3100): Uptime, active model
 
-Answers Ali's request: *"alvin-bot status im Terminal soll auch die Version anzeigen"*. The command prominently features the version at the top so it's the first thing you see.
+Answers the maintainer's request: *"alvin-bot status im Terminal soll auch die Version anzeigen"*. The command prominently features the version at the top so it's the first thing you see.
 
 Example:
 
@@ -1419,7 +1482,7 @@ New behavior in `bin/cli.js`:
   - **pm2 now empty** → *"pm2 now has zero managed processes. Remove it with: `npm uninstall -g pm2`"*
   - **pm2 still has other projects** → *"pm2 still has other projects running — leaving it installed."*
 
-Caught immediately after 4.7.0 shipped when Ali pointed out his Mac mini has `polyseus` in pm2 alongside `alvin-bot` and didn't want it touched.
+Caught immediately after 4.7.0 shipped when the maintainer pointed out his Mac mini has `polyseus` in pm2 alongside `alvin-bot` and didn't want it touched.
 
 ## [4.7.0] — 2026-04-11
 
@@ -1799,7 +1862,7 @@ Remaining unaddressed (by design, require breaking upgrades or overrides):
 
 ### ✨ Stability Improvements
 
-**Session memory hygiene (`src/services/session.ts`)** — The in-memory `sessions` Map grew unbounded: every user that ever messaged the bot kept a full session object (including conversation history, cost breakdown, abort controller) forever. On a single-user bot like Ali's this is a non-issue; on any multi-user deployment it's a steady leak.
+**Session memory hygiene (`src/services/session.ts`)** — The in-memory `sessions` Map grew unbounded: every user that ever messaged the bot kept a full session object (including conversation history, cost breakdown, abort controller) forever. On a single-user bot like the maintainer's this is a non-issue; on any multi-user deployment it's a steady leak.
 
 New behavior:
 - **Conservative 7-day TTL**: a session is only eligible for cleanup after 7 full days of complete inactivity. Configurable via `ALVIN_SESSION_TTL_DAYS` env var.

package/README.md

@@ -335,32 +335,32 @@ alvin-bot/
 
 ### 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.
+Without workspaces, Alvin has one big blob of context. If you ask about one project's deployment right after debugging a completely unrelated service, Claude pollutes one context with the other. Workspaces solve this: **Slack channel = session**, or on Telegram, **`/workspace my-project` = 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).
+3. On **Slack**, workspaces resolve by explicit channel ID first, then by channel name match (`#my-project` → `workspaces/my-project.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`:
+Create `~/.alvin-bot/workspaces/my-project.md`:
 
 ```markdown
 ---
-purpose: Alev-B consulting website dev
-cwd: ~/Projects/alev-b-website
+purpose: my-project website dev
+cwd: ~/Projects/my-project
 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.
+You are focused on the my-project website. Stack: React + Express +
+Drizzle + MySQL. Production VPS at your-vps.example.com, 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.
@@ -405,7 +405,7 @@ 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.
+- **Memory is global.** Facts Alvin learns in one workspace are visible in every other workspace 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 dispatch its own detached sub-agents via `alvin_dispatch_agent` — results come back to the originating channel on any platform (Telegram, Slack, Discord, WhatsApp), visible in `/subagents list` (v4.13.0+ dispatch, v4.14.0 cross-platform, v4.14.1 unified list view).
 - **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.
@@ -658,11 +658,11 @@ alvin-bot version   # Show version
   - [x] Watcher zombie guard — missing outputFile > 10 min delivers as failed instead of 12h timeout (v4.14.2)
   - [x] Staleness-based partial output recovery for interrupted sub-agents (v4.12.4)
   - [ ] SQLite migration of the embeddings index (currently 128 MB JSON)
-  - [ ] Per-workspace memory layer (additive over global) — facts learned in `#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 memory layer (additive over global) — facts learned in one workspace stay there unless explicitly promoted to global
+  - [ ] Per-workspace provider override (`provider:` in frontmatter) — e.g. one workspace uses Claude Opus, another uses a cheaper model
   - [ ] Per-workspace skill allowlist — scope Apple Notes to personal workspace, sysadmin only to devops workspace, etc.
   - [ ] Multi-User Slack (real `per-channel-peer` mode) — different users in the same Slack channel get their own sub-sessions
-  - [ ] Workspace cloning / templates — `/workspace clone alev-b as homes-dev` spins up a new workspace from an existing one
+  - [ ] Workspace cloning / templates — `/workspace clone my-project as my-fork` spins up a new workspace from an existing one
   - [ ] Daily log decay / archive — older daily logs move to cold storage after N days
 - [ ] **Phase 18** — Security + Platform hardening (from v4.12.1 audit, prioritized)
   - [ ] **P1 — Electron major upgrade** (35 → 41+) — fixes 1 HIGH + 5 MODERATE Electron CVEs in the Desktop-Build path. Major version jump, requires full rebuild + test of `.dmg` flow. Separate release (likely bundled with Windows `.exe` work).

package/bin/cli.js

@@ -1928,6 +1928,129 @@ switch (cmd) {
     console.log("");
     process.exit(0);
   }
+  case "browser": {
+    // Browser subcommands: wraps cdp-bootstrap so Skills + humans have a
+    // stable shell interface that works everywhere the bot is installed.
+    const sub = process.argv[3];
+    const { dist } = await import("../dist/services/cdp-bootstrap.js").then(
+      (m) => ({ dist: m }),
+      async () => {
+        console.error("❌ dist/services/cdp-bootstrap.js not found. Run: npm run build");
+        process.exit(1);
+      }
+    );
+    try {
+      switch (sub) {
+        case "start": {
+          const mode = process.argv[4] === "headful" ? "headful" : "headless";
+          const st = await dist.ensureRunning({ mode });
+          console.log(`✅ CDP running — PID ${st.pid} — ${st.endpoint}`);
+          if (st.binary) console.log(`   Binary: ${st.binary}`);
+          break;
+        }
+        case "stop": {
+          await dist.stop();
+          console.log("✅ CDP stopped");
+          break;
+        }
+        case "status": {
+          const st = await dist.status();
+          if (st.running) {
+            console.log(`✅ CDP running — PID ${st.pid}`);
+          } else {
+            console.log(`❌ CDP not running: ${st.reason || "unknown"}`);
+          }
+          if (st.binary) console.log(`   Binary: ${st.binary}`);
+          console.log(`   Endpoint: ${st.endpoint}`);
+          break;
+        }
+        case "doctor": {
+          const rep = await dist.doctor();
+          console.log("=== Browser Doctor ===\n");
+          for (const c of rep.checks) {
+            console.log(`${c.ok ? "✅" : "❌"} ${c.name}: ${c.detail}`);
+          }
+          console.log(rep.ok ? "\nAll checks passed." : "\nSome checks failed — see above.");
+          process.exit(rep.ok ? 0 : 1);
+        }
+        case "goto":
+        case "shot":
+        case "screenshot":
+        case "tabs":
+        case "eval": {
+          await dist.ensureRunning({ mode: "headless" });
+          const { chromium } = await import("playwright").catch(() => ({ chromium: null }));
+          if (!chromium) {
+            console.error("❌ playwright not available. Run: npm install");
+            process.exit(1);
+          }
+          const browser = await chromium.connectOverCDP("http://127.0.0.1:9222");
+          try {
+            if (sub === "tabs") {
+              const tabs = [];
+              for (const ctx of browser.contexts()) {
+                for (const page of ctx.pages()) {
+                  tabs.push({ title: await page.title(), url: page.url() });
+                }
+              }
+              console.log(JSON.stringify(tabs, null, 2));
+              break;
+            }
+            const url = process.argv[4];
+            if (!url) {
+              console.error(`Usage: alvin-bot browser ${sub} <url> [args]`);
+              process.exit(1);
+            }
+            const ctx = browser.contexts()[0] || (await browser.newContext());
+            const page = await ctx.newPage();
+            try {
+              await page.goto(url, { waitUntil: "domcontentloaded", timeout: 30000 });
+              if (sub === "goto") {
+                console.log(JSON.stringify({ url: page.url(), title: await page.title() }, null, 2));
+              } else if (sub === "shot" || sub === "screenshot") {
+                const name = process.argv[5] || `shot_${Date.now()}.png`;
+                const { CDP_SCREENSHOTS_DIR } = await import("../dist/paths.js");
+                const out = name.startsWith("/") ? name : `${CDP_SCREENSHOTS_DIR}/${name}`;
+                await page.screenshot({ path: out, fullPage: true });
+                console.log(JSON.stringify({ url: page.url(), title: await page.title(), screenshot: out }, null, 2));
+              } else if (sub === "eval") {
+                const js = process.argv[5] || "document.title";
+                const result = await page.evaluate(new Function(`return (${js})`));
+                console.log(JSON.stringify({ url: page.url(), result }, null, 2));
+              }
+            } finally {
+              await page.close();
+            }
+          } finally {
+            await browser.close();
+          }
+          break;
+        }
+        default:
+          console.log(`alvin-bot browser — bot-managed Chromium (CDP on port 9222)
+
+  start [headful|headless]   Start Chromium with CDP (default: headless)
+  stop                        Stop the bot-managed Chromium
+  status                      Show PID + binary + endpoint
+  doctor                      Diagnose common issues
+  goto <url>                  Navigate and print page info as JSON
+  shot <url> [filename]       Screenshot to ~/.alvin-bot/browser/screenshots/
+  eval <url> <js>             Evaluate JS expression in page context
+  tabs                        List all open tabs
+
+Notes:
+  • Uses Playwright's bundled Chromium — no conflict with your normal Chrome.
+  • Profile persists at ~/.alvin-bot/browser/profile/ (cookies survive restarts).
+  • First run needs: npx playwright install chromium
+`);
+          process.exit(sub ? 1 : 0);
+      }
+    } catch (err) {
+      console.error(`❌ ${err.message || err}`);
+      process.exit(1);
+    }
+    break;
+  }
   default:
     console.log(`
 ${t("cli.title")}
@@ -1939,6 +2062,7 @@ ${t("cli.commands")}
   doctor    ${t("cli.doctorDesc")}
   audit     Security health check (permissions, secrets, config)
   search    Search your assets, memories, and skills
+  browser   Manage bot-owned Chromium (start/stop/goto/shot/doctor)
   update    ${t("cli.updateDesc")}
   start     ${t("cli.startDesc")} (background via PM2)
   start -f  Start in foreground (for debugging)

package/dist/handlers/platform-message.js

@@ -100,8 +100,8 @@ export async function handlePlatformMessage(msg, adapter) {
     touchProfile(profileKey, msg.userName, msg.userHandle, msg.platform, text);
     // v4.12.0 — Workspace resolution: channel → workspace → persona + cwd.
     // P1 #2 — If the platform has a getChannelName helper (Slack does), use
-    // it to enable channel-name-based workspace matching (e.g. #alev-b →
-    // workspaces/alev-b.md). Cached in the adapter, so no extra API call
+    // it to enable channel-name-based workspace matching (e.g. #my-project →
+    // workspaces/my-project.md). Cached in the adapter, so no extra API call
     // after the first hit per channel.
     let channelName;
     const getChannelName = adapter.getChannelName;

package/dist/paths.js

@@ -108,11 +108,21 @@ export const AGENTS_FILE = resolve(DATA_DIR, "AGENTS.md");
 export const HOOKS_DIR = resolve(DATA_DIR, "hooks");
 /** scripts/browse-server.cjs — HTTP gateway for persistent browser sessions */
 export const BROWSE_SERVER_SCRIPT = resolve(BOT_ROOT, "scripts", "browse-server.cjs");
-/** ~/.claude/hub/SCRIPTS/browser.sh — Hub 3-tier browser router (stealth, CDP, ext) */
+/** ~/.claude/hub/SCRIPTS/browser.sh — Optional dev-only 3-tier browser router.
+ *  Used ONLY if present (maintainer dev environment). Not required for normal operation —
+ *  the bot has its own CDP bootstrap (see src/services/cdp-bootstrap.ts). */
 export const HUB_BROWSER_SH = resolve(os.homedir(), ".claude", "hub", "SCRIPTS", "browser.sh");
+/** browser/profile/ — Persistent Chromium profile for CDP (cookies, login state) */
+export const CDP_PROFILE_DIR = resolve(DATA_DIR, "browser", "profile");
+/** browser/screenshots/ — CDP screenshot output directory */
+export const CDP_SCREENSHOTS_DIR = resolve(DATA_DIR, "browser", "screenshots");
+/** browser/chrome-cdp.pid — PID of Chromium started by cdp-bootstrap */
+export const CDP_PID_FILE = resolve(DATA_DIR, "browser", "chrome-cdp.pid");
+/** browser/chrome-cdp.log — Chromium stderr/stdout when started by cdp-bootstrap */
+export const CDP_LOG_FILE = resolve(DATA_DIR, "browser", "chrome-cdp.log");
 /** data/exec-allowlist.json — User-defined exec allowlist */
 export const EXEC_ALLOWLIST_FILE = resolve(DATA_DIR, "exec-allowlist.json");
-/** assets/ — User asset files (CVs, cover letters, legal docs, photos) */
+/** assets/ — User-supplied files organized in category subdirectories */
 export const ASSETS_DIR = resolve(DATA_DIR, "assets");
 /** assets/INDEX.json — Machine-readable asset registry */
 export const ASSETS_INDEX_JSON = resolve(DATA_DIR, "assets", "INDEX.json");

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

@@ -393,6 +393,12 @@ export class ClaudeSDKProvider {
             return cache(false);
         }
     }
+    /** v4.15.2 — Clear the cached isAvailable() result. Called by the
+     *  heartbeat service after detecting macOS sleep/wake so the first
+     *  post-wake probe doesn't serve a stale "unavailable" from hours ago. */
+    invalidateAvailabilityCache() {
+        this.availabilityCache = null;
+    }
     getInfo() {
         const model = this.config.model === "inherit"
             ? "CLI default (latest)"

package/dist/services/alvin-mcp-tools.js

@@ -61,7 +61,7 @@ export function buildAlvinMcpServer(ctx) {
                     .describe("The full prompt for the sub-agent. Be specific and self-contained — the sub-agent has no access to this conversation's context and will see only this prompt."),
                 description: z
                     .string()
-                    .describe("Short human-readable title (e.g. 'SEO audit alev-b.com', 'Research Higgsfield Seedance 2.0'). Shown to the user when the result arrives."),
+                    .describe("Short human-readable title (e.g. 'SEO audit example.com', 'Research topic X'). Shown to the user when the result arrives."),
             }, async (args) => {
                 try {
                     const result = dispatchDetachedAgent({

package/dist/services/asset-index.js

@@ -50,22 +50,16 @@ function walkDir(dir) {
 }
 /**
  * Generate a human-readable description from a filename.
- * "acme-cover-letter.html" → "Cover Letter: Acme"
  * "profile-photo.jpeg" → "Profile Photo"
+ * "my-document.html"   → "My Document"
  */
 function descriptionFromFilename(filename, category) {
     const name = filename.replace(/\.[^.]+$/, ""); // strip extension
     const words = name.replace(/[-_]/g, " ").trim();
-    // Special handling for known patterns
-    if (category === "cover-letters") {
-        const company = words.replace(/cover letter/i, "").replace(/^Cover_Letter_[A-Za-z_]+_/i, "").trim();
-        return `Cover Letter: ${company || words}`;
-    }
-    if (category === "cv-templates") {
-        return `CV Template: ${words}`;
-    }
-    // Default: capitalize words
-    return words.replace(/\b\w/g, c => c.toUpperCase());
+    // Prefix with capitalized category for disambiguation when the filename alone is terse
+    const prefix = category ? category.replace(/[-_]/g, " ").replace(/\b\w/g, c => c.toUpperCase()) + ": " : "";
+    const title = words.replace(/\b\w/g, c => c.toUpperCase());
+    return prefix ? `${prefix}${title}` : title;
 }
 /**
  * Determine category for a file.

package/dist/services/browser-manager.js

@@ -17,6 +17,7 @@ import { config } from "../config.js";
 import { BROWSE_SERVER_SCRIPT, HUB_BROWSER_SH } from "../paths.js";
 import { screenshotUrl, extractText, generatePdf } from "./browser.js";
 import { webfetchNavigate, WebfetchFailed } from "./browser-webfetch.js";
+import * as cdpBootstrap from "./cdp-bootstrap.js";
 const CDP_PORT = 9222;
 const EXEC_TIMEOUT = 60_000; // 60s for page loads via shell
 // ── Logging ──────────────────────────────────────────────────────────
@@ -125,23 +126,35 @@ export async function resolveStrategy(preferred) {
             case "cdp":
                 if (await isCDPAvailable())
                     return "cdp";
-                // Try starting CDP via hub script
+                // Bot-owned bootstrap is the primary path — works for every install,
+                // no Hub dependency, no conflict with user's own Chrome.
+                try {
+                    log("CDP not running — starting bot-managed Chromium via cdp-bootstrap...");
+                    await cdpBootstrap.ensureRunning({ mode: "headless" });
+                    if (await isCDPAvailable()) {
+                        log("CDP bootstrap started successfully.");
+                        return "cdp";
+                    }
+                }
+                catch (err) {
+                    log(`CDP bootstrap failed: ${err.message}`);
+                }
+                // Dev-only fallback: maintainer Hub script, if present
                 if (isHubBrowserAvailable()) {
                     try {
-                        log("CDP Chrome not running — attempting to start via hub browser.sh...");
+                        log("Trying Hub script as fallback...");
                         execSync(`"${HUB_BROWSER_SH}" cdp start headless`, {
                             stdio: "pipe",
                             timeout: 15_000,
                         });
-                        // Give it a moment to spin up
                         await new Promise((r) => setTimeout(r, 3000));
                         if (await isCDPAvailable()) {
-                            log("CDP Chrome started successfully.");
+                            log("CDP via Hub script.");
                             return "cdp";
                         }
                     }
                     catch (err) {
-                        log(`Failed to start CDP Chrome: ${err.message}`);
+                        log(`Hub script fallback failed: ${err.message}`);
                     }
                 }
                 log("CDP unavailable. Falling back.");
@@ -385,7 +398,7 @@ async function withCdpPage(fn) {
         await browser.close(); // Closes CDP connection, not Chrome itself
     }
 }
-const NEEDS_INTERACTIVE_HINT = "Start CDP Chrome: ~/.claude/hub/SCRIPTS/browser.sh cdp start headless";
+const NEEDS_INTERACTIVE_HINT = "Start CDP: alvin-bot browser start (headless by default)";
 /**
  * Get accessibility tree (gateway preferred, CDP fallback returns outerHTML).
  * The @eN ref model only exists in the gateway; under CDP we return a