alvin-bot 4.10.0 → 4.12.0

package/CHANGELOG.md

@@ -2,6 +2,200 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [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
+
+A colleague asked the same day v4.10.0 shipped: *"Memory after session restart is also a bit fiddly. I installed mempalace as a workaround — maybe build something like that natively."* He was right. Alvin had a hand-curated `MEMORY.md`, a 128 MB embeddings vector index, and an AI-powered compaction service — but **the in-memory `sessions Map` was wiped on every bot restart**. Claude SDK then started a fresh conversation on the next user message, behaving like a goldfish despite all that memory infrastructure on disk.
+
+This release fixes that with **five complementary tasks**, all bundled into v4.11.0. Three core fixes (P0) plus two structural improvements (P1) inspired by mempalace's L0–L3 stack and Mem0's auto-extraction pattern.
+
+#### P0 #1 — Session Persistence (`src/services/session-persistence.ts`, NEW)
+
+The core fix. The `sessions Map` in `src/services/session.ts` was in-memory only; every `launchctl kickstart` wiped every user's `sessionId`, history, language, effort, voiceReply, and tracking counters.
+
+- **Debounced flush** (1.5 s coalesce window) writes a sanitized snapshot of `getAllSessions()` to `~/.alvin-bot/state/sessions.json` via atomic tmp+rename.
+- **`loadPersistedSessions()`** rehydrates the Map at bot startup; `flushSessions()` flushes synchronously on graceful shutdown (SIGINT/SIGTERM).
+- **`attachPersistHook()` / `markSessionDirty()`** in `session.ts` give handlers a callback to trigger persist after direct mutations (`/lang`, `/effort`, `/voice`). `addToHistory()` and `trackProviderUsage()` trigger it automatically.
+- History is capped at `MAX_PERSISTED_HISTORY = 50` per session so the file stays small.
+- Runtime-only fields (`abortController`, `isProcessing`, `messageQueue`) are stripped before persisting.
+- Schema drift is handled: missing fields fall back to defaults; corrupt JSON loads zero sessions; null root rejected gracefully.
+- **9 unit tests** + **18 stress tests** covering 100-session burst, 1000-mutate debounce coalescing, unicode (RTL/ZWJ/astral plane), atomic write recovery from stale `.tmp`, schema drift, hostile JSON, read-only filesystem, simulated bot restart.
+
+#### P0 #2 — MEMORY.md Auto-Inject for SDK (`src/services/personality.ts`)
+
+Before v4.11.0, only non-SDK providers (Groq, Gemini, NVIDIA) got `buildMemoryContext()` injected into their system prompt. The Claude SDK was *expected* to read memory files via tools, but in practice rarely did unless the user's first message specifically prompted it.
+
+- Drops the `!isSDK` guard around `buildMemoryContext()` and asset-index injection.
+- SDK now gets the same compact memory context (MEMORY.md + today + yesterday daily logs) at every turn — the same context non-SDK providers had since 4.0.
+- **3 unit tests** verifying SDK includes the memory section, non-SDK regression, and graceful behavior when MEMORY.md is missing.
+
+#### P0 #3 — Semantic Recall on SDK First Turn (`src/services/personality.ts`, `src/handlers/message.ts`, `src/handlers/platform-message.ts`)
+
+`buildSmartSystemPrompt()` now accepts an `isFirstTurn` flag. For SDK providers it runs the embeddings-based `searchMemory()` only on the first turn (`session.sessionId === null` — meaning Claude hasn't given us a resume token yet for this session). After the first turn Claude carries the recalled context inside the SDK session via resume, so spamming the embeddings API on every subsequent turn is wasted work. Non-SDK providers still run the search on every turn (no resume mechanism).
+
+- `handlers/message.ts` and `handlers/platform-message.ts` updated to compute `isFirstSDKTurn = isSDK && session.sessionId === null` and pass it through.
+- The bare `buildSystemPrompt` calls on the SDK paths are gone — `buildSmartSystemPrompt` is the single entry point.
+- **5 mocked-search tests** covering call-count semantics for SDK first/later turns, non-SDK every turn, missing `userMessage` skip, and graceful failure when `searchMemory` throws.
+
+#### P1 #4 — Layered Memory Loader (`src/services/memory-layers.ts`, NEW)
+
+Inspired by mempalace's L0–L3 stack. Replaces the monolithic `MEMORY.md → System Prompt` injection with a structured, token-budgeted layered loader:
+
+- **L0** `~/.alvin-bot/memory/identity.md` — always loaded, ~200 tokens (core user facts: name, location, family, contact)
+- **L1** `~/.alvin-bot/memory/preferences.md` — always loaded (communication style, do's and don'ts)
+- **L1** `~/.alvin-bot/memory/MEMORY.md` — backwards-compat: existing curated knowledge (full content if no split files exist; truncated to 1500 chars when split files coexist)
+- **L2** `~/.alvin-bot/memory/projects/*.md` — loaded only when the user's incoming query mentions the project topic (substring or first-200-char keyword overlap)
+- **L3** daily logs — still handled by `embeddings.ts` vector search (unchanged)
+
+The split is **opt-in**: if `identity.md` and `preferences.md` don't exist, the loader falls back to monolithic MEMORY.md exactly like before. No migration required for existing users. Users who want the cleaner layout can split MEMORY.md manually and the loader picks it up automatically. Token budget: L0+L1 capped at 5000 chars (~1300 tokens), L2 capped at 3000 chars total (~750 tokens, max 1500 per matched project file). New `query` parameter on `buildSystemPrompt()` and `buildMemoryContext()` propagates the user message all the way through. **9 unit tests** + 2 layered-context stress tests.
+
+#### P1 #5 — Auto-Fact-Extraction in Compaction (`src/services/memory-extractor.ts`, NEW)
+
+Inspired by Mem0's auto-extraction. When `compactSession()` archives old messages, it now runs an additional extraction pass that pulls structured facts (`user_facts`, `preferences`, `decisions`) out of the archived chunk via the active AI provider and appends them to MEMORY.md.
+
+- **`parseExtractedFacts(text)`** — tolerates JSON wrapped in markdown code fences, surrounding prose, null/undefined fields, non-string entries.
+- **`appendFactsToMemoryFile(facts)`** — exact-string dedup against existing MEMORY.md content, structured under `## Auto-extracted (YYYY-MM-DD)` header with `### User Facts` / `### Preferences` / `### Decisions` sub-sections.
+- **`extractAndStoreFacts(chunk)`** — safe wrapper, never throws. Opt-out via `MEMORY_EXTRACTION_DISABLED=1` env var. Uses effort=low for cost minimization. Skips short input (<50 chars). Provider failures are swallowed; compaction always continues.
+- Wired into `compactSession()` after the daily-log flush, before the AI summary generation.
+- Marked **experimental** in v4.11.0. Semantic dedup (vs current exact-string match) deferred to v4.12+.
+- **11 unit tests** covering JSON parsing edge cases, dedup, opt-out, short-input skip, garbage input, non-string filtering, graceful provider-failure handling.
+
+#### Architecture decisions
+
+- **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.
+- **Decay/aging deferred.** Daily logs grow monotonically. Will be addressed alongside SQLite migration.
+
+#### Testing
+
+**292 tests total** (237 baseline + 55 new). All green. TSC clean.
+
+- 9 session-persistence unit tests
+- 8 SDK memory-injection tests (3 base + 5 smart-prompt mocked-search)
+- 9 memory-layers tests (loader + topic match + token budget)
+- 11 memory-extractor tests (parse + append + extract pipeline)
+- 18 stress tests (100 sessions, schema drift, unicode, atomic recovery, hostile JSON, simulated restart)
+
+**Live verification:**
+- `tmp/live-stress-memory.mjs` — 50 fake sessions against the built `dist/`, real ~/.alvin-bot/memory/MEMORY.md as the L1 source, simulated restart via Map clear + reload. Result: 215 KB state file, 1 ms flush, 1 ms reload, 50/50 perfect round-trip.
+- `tmp/live-edge-cases.mjs` — 7 hostile scenarios: all-null fields, 1000-burst debounce (2 ms), 20 concurrent flushes, extreme unicode (RTL + ZWJ + astral plane), 4-layer memory with project topic match, atomic write recovery from stale .tmp, empty project file skipping. All passed.
+
+#### Files changed
+
+- **NEW:** `src/services/session-persistence.ts`, `src/services/memory-layers.ts`, `src/services/memory-extractor.ts`
+- **NEW tests:** `test/session-persistence.test.ts`, `test/memory-sdk-injection.test.ts`, `test/memory-layers.test.ts`, `test/memory-extractor.test.ts`, `test/memory-stress-restart.test.ts`
+- **Modified:** `src/services/session.ts` (persist hook), `src/services/personality.ts` (SDK injection + isFirstTurn), `src/services/memory.ts` (use layered loader), `src/services/compaction.ts` (extractor hook), `src/handlers/message.ts` + `src/handlers/platform-message.ts` (smart prompt wiring), `src/handlers/commands.ts` (`markSessionDirty` calls), `src/index.ts` (load + flush wiring), `src/paths.ts` (4 new constants)
+- **Plan:** `docs/superpowers/plans/2026-04-13-memory-persistence.md`
+
+---
+
 ## [4.10.0] — 2026-04-13
 
 ### 🚀 Async sub-agents — main session no longer blocks during long tasks

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 } 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";
@@ -399,6 +400,7 @@ export function registerCommands(bot) {
         const userId = ctx.from.id;
         const session = getSession(userId);
         session.voiceReply = !session.voiceReply;
+        markSessionDirty(userId);
         await ctx.reply(session.voiceReply
             ? "Voice replies enabled. Responses will also be sent as voice messages."
             : "Voice replies disabled. Text-only responses.");
@@ -421,8 +423,53 @@ export function registerCommands(bot) {
             return;
         }
         session.effort = level;
+        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];
@@ -433,6 +480,7 @@ export function registerCommands(bot) {
         const userId = ctx.from.id;
         const session = getSession(userId);
         session.effort = level;
+        markSessionDirty(userId);
         const keyboard = new InlineKeyboard();
         for (const [key, label] of Object.entries(EFFORT_LABELS)) {
             const marker = key === session.effort ? "✅ " : "";
@@ -827,6 +875,7 @@ export function registerCommands(bot) {
         }
         else if (arg === "en" || arg === "de" || arg === "es" || arg === "fr") {
             session.language = arg;
+            markSessionDirty(userId);
             const { setExplicitLanguage } = await import("../services/language-detect.js");
             setExplicitLanguage(userId, arg);
             await ctx.reply(t("bot.lang.setFixed", arg, { name: LOCALE_NAMES[arg] }));
@@ -851,6 +900,7 @@ export function registerCommands(bot) {
         }
         const newLang = choice;
         session.language = newLang;
+        markSessionDirty(userId);
         const { setExplicitLanguage } = await import("../services/language-detect.js");
         setExplicitLanguage(userId, newLang);
         const currentName = `${LOCALE_FLAGS[newLang]} ${LOCALE_NAMES[newLang]}`;

package/dist/handlers/message.js

@@ -1,10 +1,11 @@
 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";
-import { buildSystemPrompt, buildSmartSystemPrompt } from "../services/personality.js";
+import { buildSmartSystemPrompt } from "../services/personality.js";
 import { buildSkillContext } from "../services/skills.js";
 import { isForwardingAllowed } from "../services/access.js";
 import { touchProfile } from "../services/users.js";
@@ -219,12 +220,29 @@ export async function handleMessage(ctx) {
         if (adaptedLang !== session.language) {
             session.language = adaptedLang;
         }
-        // Build query options (with semantic memory search for non-SDK + skill injection)
+        // Build query options (with semantic memory search for non-SDK + skill injection).
+        // v4.11.0 P0 #3: SDK now also gets semantic recall on first-turn. The signal
+        // is `session.sessionId === null` — meaning Claude SDK hasn't given us a
+        // resume token yet for this session. True for: brand-new users, post-/new,
+        // 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 systemPrompt = (isSDK
-            ? buildSystemPrompt(isSDK, session.language, chatIdStr)
-            : await buildSmartSystemPrompt(isSDK, session.language, text, chatIdStr)) + skillContext;
+        const isFirstSDKTurn = isSDK && session.sessionId === null;
+        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 });

package/dist/handlers/platform-message.js

@@ -7,9 +7,10 @@
  * This is the platform-agnostic equivalent of message.ts (which is Telegram-specific).
  */
 import fs from "fs";
-import { getSession, addToHistory, trackProviderUsage } from "../services/session.js";
+import { getSession, addToHistory, trackProviderUsage, buildSessionKey } from "../services/session.js";
+import { resolveWorkspaceOrDefault } from "../services/workspaces.js";
 import { getRegistry } from "../engine.js";
-import { buildSystemPrompt, buildSmartSystemPrompt } from "../services/personality.js";
+import { buildSmartSystemPrompt } from "../services/personality.js";
 import { buildSkillContext } from "../services/skills.js";
 import { touchProfile } from "../services/users.js";
 import { trackAndAdapt } from "../services/language-detect.js";
@@ -87,9 +88,38 @@ export async function handlePlatformMessage(msg, adapter) {
     const cmdHandled = await handlePlatformCommand(text, msg, adapter);
     if (cmdHandled)
         return;
-    const userId = hashUserId(msg.userId);
-    const session = getSession(userId);
-    touchProfile(userId, msg.userName, msg.userHandle, msg.platform, text);
+    // v4.12.0 — Use buildSessionKey so each channel on Slack/Discord/WhatsApp
+    // gets its own session. Before v4.12.0 we hashed just userId, which
+    // collapsed every channel from the same user into one session and broke
+    // multi-session completely on non-Telegram platforms.
+    const sessionKey = buildSessionKey(msg.platform, msg.chatId, msg.userId);
+    const session = getSession(sessionKey);
+    // touchProfile still uses a stable userId-based numeric hash for the
+    // user profile store — profiles are about *people*, not sessions.
+    const profileKey = hashUserId(msg.userId);
+    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
+    // after the first hit per channel.
+    let channelName;
+    const getChannelName = adapter.getChannelName;
+    if (typeof getChannelName === "function") {
+        try {
+            channelName = await getChannelName.call(adapter, msg.chatId);
+        }
+        catch {
+            channelName = undefined;
+        }
+    }
+    const workspace = resolveWorkspaceOrDefault(msg.platform, msg.chatId, channelName);
+    // If the workspace changed since last turn, update the session's cwd +
+    // workspaceName. This is debounced via session-persistence (v4.11.0).
+    if (session.workspaceName !== workspace.name) {
+        session.workspaceName = workspace.name;
+        session.workingDir = workspace.cwd;
+    }
     // Skip if already processing (queue up to 3)
     if (session.isProcessing) {
         if (session.messageQueue.length < 3) {
@@ -129,9 +159,11 @@ export async function handlePlatformMessage(msg, adapter) {
         const activeProvider = registry.getActive();
         const isSDK = activeProvider.config.type === "claude-sdk";
         const skillContext = buildSkillContext(fullText);
-        const systemPrompt = (isSDK
-            ? buildSystemPrompt(isSDK, session.language, msg.chatId)
-            : await buildSmartSystemPrompt(isSDK, session.language, fullText, msg.chatId)) + skillContext;
+        // v4.11.0 P0 #3 — SDK gets semantic recall on first turn (when no resume token yet).
+        // v4.12.0 P0 #3 — Workspace persona is forwarded so per-channel personas land
+        // in the system prompt for this query.
+        const isFirstSDKTurn = isSDK && session.sessionId === null;
+        const systemPrompt = (await buildSmartSystemPrompt(isSDK, session.language, fullText, msg.chatId, isFirstSDKTurn, workspace.systemPromptOverride)) + skillContext;
         const queryOpts = {
             prompt: fullText,
             systemPrompt,
@@ -141,7 +173,7 @@ export async function handlePlatformMessage(msg, adapter) {
             history: !isSDK ? session.history : undefined,
         };
         if (!isSDK) {
-            addToHistory(userId, { role: "user", content: fullText });
+            addToHistory(sessionKey, { role: "user", content: fullText });
         }
         for await (const chunk of registry.queryWithFallback(queryOpts)) {
             switch (chunk.type) {
@@ -153,7 +185,7 @@ export async function handlePlatformMessage(msg, adapter) {
                         session.sessionId = chunk.sessionId;
                     if (chunk.costUsd)
                         session.totalCost += chunk.costUsd;
-                    trackProviderUsage(userId, registry.getActiveKey(), chunk.costUsd || 0, chunk.inputTokens, chunk.outputTokens);
+                    trackProviderUsage(sessionKey, registry.getActiveKey(), chunk.costUsd || 0, chunk.inputTokens, chunk.outputTokens);
                     session.lastActivity = Date.now();
                     break;
                 case "error":
@@ -174,7 +206,7 @@ export async function handlePlatformMessage(msg, adapter) {
                 await adapter.sendText(msg.chatId, finalText);
             }
             if (!isSDK && finalText) {
-                addToHistory(userId, { role: "assistant", content: finalText });
+                addToHistory(sessionKey, { role: "assistant", content: finalText });
             }
         }
     }
@@ -198,12 +230,14 @@ async function handlePlatformCommand(text, msg, adapter) {
         return false;
     const parts = text.split(/\s+/);
     const cmd = parts[0].toLowerCase();
-    const userId = hashUserId(msg.userId);
-    const session = getSession(userId);
+    // v4.12.0 — Same buildSessionKey routing as the main handler so /new and
+    // /status etc operate on the per-channel session, not the per-user one.
+    const sessionKey = buildSessionKey(msg.platform, msg.chatId, msg.userId);
+    const session = getSession(sessionKey);
     switch (cmd) {
         case "/new": {
             const { resetSession } = await import("../services/session.js");
-            resetSession(userId);
+            resetSession(sessionKey);
             await adapter.sendText(msg.chatId, "🔄 New chat started.");
             return true;
         }

package/dist/index.js

@@ -79,7 +79,8 @@ import { initMCP, disconnectMCP, hasMCPConfig } from "./services/mcp.js";
 import { startWebServer, stopWebServer } from "./web/server.js";
 import { startScheduler, stopScheduler, setNotifyCallback } from "./services/cron.js";
 import { startWatcher as startAsyncAgentWatcher, stopWatcher as stopAsyncAgentWatcher } from "./services/async-agent-watcher.js";
-import { startSessionCleanup, stopSessionCleanup } from "./services/session.js";
+import { startSessionCleanup, stopSessionCleanup, attachPersistHook } from "./services/session.js";
+import { loadPersistedSessions, flushSessions, schedulePersist, } from "./services/session-persistence.js";
 import { processQueue, cleanupQueue, setSenders, enqueue } from "./services/delivery-queue.js";
 import { discoverTools } from "./services/tool-discovery.js";
 import { startHeartbeat } from "./services/heartbeat.js";
@@ -100,6 +101,10 @@ if (assetScanResult.assets.length > 0) {
 discoverTools();
 // Load skill files
 loadSkills();
+// v4.12.0 — Workspace registry: load per-channel configs and start the
+// hot-reload watcher. Safe no-op if no workspaces are configured.
+import { initWorkspaces, stopWorkspaceWatcher } from "./services/workspaces.js";
+initWorkspaces();
 // Load user-defined lifecycle hooks from ~/.alvin-bot/hooks/
 const hookCount = loadHooks();
 if (hookCount > 0)
@@ -257,6 +262,11 @@ const shutdown = async () => {
     stopScheduler();
     stopAsyncAgentWatcher();
     stopSessionCleanup();
+    stopWorkspaceWatcher();
+    // v4.11.0 — Final immediate flush of in-memory sessions to disk before exit.
+    // The debounced timer might be pending; flushSessions() cancels it and writes
+    // synchronously so the next boot can rehydrate the latest state.
+    await flushSessions().catch((err) => console.warn("[shutdown] flushSessions failed:", err));
     if (queueInterval)
         clearInterval(queueInterval);
     if (queueCleanupInterval)
@@ -430,6 +440,13 @@ startAsyncAgentWatcher();
 // Session memory hygiene: purge sessions idle > 7 days (configurable via
 // ALVIN_SESSION_TTL_DAYS). Never touches active sessions — see session.ts.
 startSessionCleanup();
+// Session persistence (v4.11.0): wire the debounced persist hook BEFORE we
+// load the snapshot, then rehydrate the in-memory Map from disk so users'
+// Claude SDK session_id, conversation history, language and effort all
+// survive bot restarts. Without this, every launchctl restart turns the
+// bot into a goldfish for every active conversation.
+attachPersistHook(schedulePersist);
+loadPersistedSessions();
 // Wire delivery queue senders
 setSenders({
     telegram: async (chatId, content) => {

package/dist/paths.js

@@ -41,8 +41,20 @@ export const TOOLS_EXAMPLE_JSON = resolve(BOT_ROOT, "docs", "tools.example.json"
 export const ENV_FILE = resolve(DATA_DIR, ".env");
 /** memory/ — Daily logs and embeddings */
 export const MEMORY_DIR = resolve(DATA_DIR, "memory");
-/** memory/MEMORY.md — Long-term curated memory */
+/** memory/MEMORY.md — Long-term curated memory (legacy monolithic, still loaded) */
 export const MEMORY_FILE = resolve(DATA_DIR, "memory", "MEMORY.md");
+/** memory/identity.md — L0 layer (v4.11.0): core user facts, always loaded.
+ *  Optional. If missing, MEMORY.md acts as the L0+L1 fallback. */
+export const IDENTITY_FILE = resolve(DATA_DIR, "memory", "identity.md");
+/** memory/preferences.md — L1 layer (v4.11.0): communication style + don'ts. */
+export const PREFERENCES_FILE = resolve(DATA_DIR, "memory", "preferences.md");
+/** memory/projects/ — L2 layer (v4.11.0): per-project context loaded on topic match. */
+export const PROJECTS_MEMORY_DIR = resolve(DATA_DIR, "memory", "projects");
+/** workspaces/ — Per-workspace configuration (v4.12.0).
+ *  Each file is a markdown doc with YAML frontmatter defining the workspace's
+ *  name, purpose, cwd, color, emoji, and an optional system prompt body.
+ *  See src/services/workspaces.ts for the loader and matcher. */
+export const WORKSPACES_DIR = resolve(DATA_DIR, "workspaces");
 /** memory/.embeddings.json — Vector index */
 export const EMBEDDINGS_IDX = resolve(DATA_DIR, "memory", ".embeddings.json");
 /** users/ — User profiles and per-user memory */
@@ -66,6 +78,12 @@ export const BACKUP_DIR = resolve(DATA_DIR, "backups");
  *  See src/services/async-agent-watcher.ts for the watcher that polls and
  *  delivers these. Survives bot restarts. */
 export const ASYNC_AGENTS_STATE_FILE = resolve(DATA_DIR, "state", "async-agents.json");
+/** state/sessions.json — Persisted user sessions across bot restarts (v4.11.0).
+ *  Includes: sessionId (Claude SDK resume token), language, effort, voiceReply,
+ *  workingDir, lastActivity, lastSdkHistoryIndex, history (capped). Atomic write
+ *  via tmp+rename. Loaded on startup, debounce-flushed on mutations.
+ *  See src/services/session-persistence.ts for the loader/flusher. */
+export const SESSIONS_STATE_FILE = resolve(DATA_DIR, "state", "sessions.json");
 /** soul.md — Bot personality */
 export const SOUL_FILE = resolve(DATA_DIR, "soul.md");
 /** tools.md — Custom tool definitions (Markdown) */