alvin-bot 4.10.0 → 4.12.0

package/test/session-persistence.test.ts

@@ -0,0 +1,195 @@
+/**
+ * v4.11.0 — Session persistence across bot restarts.
+ *
+ * Sessions live in an in-memory Map that gets wiped on every bot restart.
+ * This persistence layer flushes the Map to disk (debounced) and rehydrates
+ * it on bot startup so Claude SDK's `resume: sessionId` keeps working,
+ * conversation history survives, and user preferences (language, effort,
+ * voiceReply) don't reset.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import fs from "fs";
+import os from "os";
+import { resolve } from "path";
+
+const TEST_DATA_DIR = resolve(os.tmpdir(), `alvin-session-persist-${process.pid}-${Date.now()}`);
+
+beforeEach(() => {
+  if (fs.existsSync(TEST_DATA_DIR)) fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+  fs.mkdirSync(TEST_DATA_DIR, { recursive: true });
+  process.env.ALVIN_DATA_DIR = TEST_DATA_DIR;
+  vi.resetModules();
+});
+
+afterEach(() => {
+  try { fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true }); } catch { /* ignore */ }
+});
+
+describe("session-persistence (v4.11.0)", () => {
+  it("flushSessions writes a JSON file with all session fields that survive restart", async () => {
+    const sessionMod = await import("../src/services/session.js");
+    const persistMod = await import("../src/services/session-persistence.js");
+
+    const s = sessionMod.getSession("user-1");
+    s.sessionId = "sdk-abc-123";
+    s.language = "de";
+    s.effort = "high";
+    s.voiceReply = true;
+    s.workingDir = "/tmp/test-cwd";
+    s.history = [
+      { role: "user", content: "hi" },
+      { role: "assistant", content: "hello" },
+    ];
+
+    await persistMod.flushSessions();
+
+    const stateFile = resolve(TEST_DATA_DIR, "state", "sessions.json");
+    expect(fs.existsSync(stateFile)).toBe(true);
+
+    // v4.12.0 — Format is now an envelope: { version: 2, sessions: {...}, telegramWorkspaces: {...} }
+    const envelope = JSON.parse(fs.readFileSync(stateFile, "utf-8"));
+    expect(envelope.version).toBe(2);
+    const parsed = envelope.sessions;
+    expect(parsed).toHaveProperty("user-1");
+    expect(parsed["user-1"].sessionId).toBe("sdk-abc-123");
+    expect(parsed["user-1"].language).toBe("de");
+    expect(parsed["user-1"].effort).toBe("high");
+    expect(parsed["user-1"].voiceReply).toBe(true);
+    expect(parsed["user-1"].history).toHaveLength(2);
+  });
+
+  it("loadPersistedSessions rehydrates the sessions Map from disk", async () => {
+    fs.mkdirSync(resolve(TEST_DATA_DIR, "state"), { recursive: true });
+    fs.writeFileSync(
+      resolve(TEST_DATA_DIR, "state", "sessions.json"),
+      JSON.stringify({
+        "user-7": {
+          sessionId: "sdk-restored",
+          language: "en",
+          effort: "medium",
+          voiceReply: false,
+          workingDir: "/home/test",
+          lastActivity: Date.now() - 60_000,
+          lastSdkHistoryIndex: 3,
+          history: [{ role: "user", content: "from past life" }],
+          messageCount: 5,
+          toolUseCount: 2,
+        },
+      }),
+    );
+
+    const persistMod = await import("../src/services/session-persistence.js");
+    const sessionMod = await import("../src/services/session.js");
+
+    const loaded = persistMod.loadPersistedSessions();
+    expect(loaded).toBe(1);
+
+    const s = sessionMod.getSession("user-7");
+    expect(s.sessionId).toBe("sdk-restored");
+    expect(s.language).toBe("en");
+    expect(s.history).toHaveLength(1);
+    expect(s.history[0].content).toBe("from past life");
+    expect(s.messageCount).toBe(5);
+  });
+
+  it("survives a corrupt sessions.json file (does not crash)", async () => {
+    fs.mkdirSync(resolve(TEST_DATA_DIR, "state"), { recursive: true });
+    fs.writeFileSync(
+      resolve(TEST_DATA_DIR, "state", "sessions.json"),
+      "{ this is not valid json",
+    );
+
+    const persistMod = await import("../src/services/session-persistence.js");
+    const loaded = persistMod.loadPersistedSessions();
+    expect(loaded).toBe(0);
+  });
+
+  it("survives missing sessions.json file (returns 0 loaded)", async () => {
+    const persistMod = await import("../src/services/session-persistence.js");
+    const loaded = persistMod.loadPersistedSessions();
+    expect(loaded).toBe(0);
+  });
+
+  it("does NOT persist runtime-only fields (abortController, isProcessing)", async () => {
+    const sessionMod = await import("../src/services/session.js");
+    const persistMod = await import("../src/services/session-persistence.js");
+
+    const s = sessionMod.getSession("user-2");
+    s.isProcessing = true;
+    s.abortController = new AbortController();
+    s.sessionId = "abc";
+
+    await persistMod.flushSessions();
+
+    const stateFile = resolve(TEST_DATA_DIR, "state", "sessions.json");
+    const parsed = JSON.parse(fs.readFileSync(stateFile, "utf-8")).sessions;
+    expect(parsed["user-2"]).not.toHaveProperty("abortController");
+    expect(parsed["user-2"]).not.toHaveProperty("isProcessing");
+    expect(parsed["user-2"].sessionId).toBe("abc");
+  });
+
+  it("caps history at MAX_PERSISTED_HISTORY (50) so the file doesn't grow unbounded", async () => {
+    const sessionMod = await import("../src/services/session.js");
+    const persistMod = await import("../src/services/session-persistence.js");
+
+    const s = sessionMod.getSession("user-3");
+    s.sessionId = "needs-some-state-to-be-persisted";
+    for (let i = 0; i < 200; i++) {
+      s.history.push({ role: i % 2 === 0 ? "user" : "assistant", content: `msg ${i}` });
+    }
+
+    await persistMod.flushSessions();
+
+    const parsed = JSON.parse(fs.readFileSync(resolve(TEST_DATA_DIR, "state", "sessions.json"), "utf-8")).sessions;
+    expect(parsed["user-3"].history.length).toBeLessThanOrEqual(50);
+    // Last message should still be there
+    expect(parsed["user-3"].history.at(-1).content).toContain("199");
+  });
+
+  it("debounce: schedulePersist coalesces multiple rapid mutations into one flush", async () => {
+    const persistMod = await import("../src/services/session-persistence.js");
+    const sessionMod = await import("../src/services/session.js");
+
+    sessionMod.getSession("user-4").sessionId = "v1";
+    persistMod.schedulePersist();
+    sessionMod.getSession("user-4").sessionId = "v2";
+    persistMod.schedulePersist();
+    sessionMod.getSession("user-4").sessionId = "v3";
+    persistMod.schedulePersist();
+
+    // Force the debounced flush
+    await persistMod.flushSessions();
+
+    const parsed = JSON.parse(fs.readFileSync(resolve(TEST_DATA_DIR, "state", "sessions.json"), "utf-8")).sessions;
+    expect(parsed["user-4"].sessionId).toBe("v3");
+  });
+
+  it("atomic write: tmp+rename, never leaves a half-written file on crash", async () => {
+    const persistMod = await import("../src/services/session-persistence.js");
+    const sessionMod = await import("../src/services/session.js");
+
+    sessionMod.getSession("user-5").sessionId = "abc";
+    await persistMod.flushSessions();
+
+    // After successful flush: no .tmp leftover
+    const tmpFile = resolve(TEST_DATA_DIR, "state", "sessions.json.tmp");
+    expect(fs.existsSync(tmpFile)).toBe(false);
+    expect(fs.existsSync(resolve(TEST_DATA_DIR, "state", "sessions.json"))).toBe(true);
+  });
+
+  it("does not persist sessions that have never been activated (only defaults)", async () => {
+    const sessionMod = await import("../src/services/session.js");
+    const persistMod = await import("../src/services/session-persistence.js");
+
+    // Touching getSession creates an empty default session — but we don't want to
+    // persist it if it has no meaningful state (no sessionId, no history)
+    sessionMod.getSession("noop-user");
+    await persistMod.flushSessions();
+
+    const stateFile = resolve(TEST_DATA_DIR, "state", "sessions.json");
+    if (fs.existsSync(stateFile)) {
+      const parsed = JSON.parse(fs.readFileSync(stateFile, "utf-8")).sessions;
+      expect(parsed).not.toHaveProperty("noop-user");
+    }
+  });
+});

package/test/slack-progress-ticker.test.ts

@@ -0,0 +1,123 @@
+/**
+ * v4.12.0 — Slack adapter editMessage support for progress tickers.
+ *
+ * Slack doesn't stream text like the OpenAI API does; the idiom is to
+ * post an initial message, capture its `ts` (timestamp), then edit it
+ * with growing content via chat.update. This mirrors Telegram's
+ * editMessageText approach used in the cron progress ticker.
+ */
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+beforeEach(() => {
+  vi.resetModules();
+});
+
+describe("SlackAdapter.editMessage (v4.12.0)", () => {
+  it("calls chat.update with the correct channel + ts when editMessage is invoked", async () => {
+    const updateSpy = vi.fn().mockResolvedValue({ ok: true, ts: "1234567890.123456" });
+    const postSpy = vi.fn().mockResolvedValue({ ok: true, ts: "1234567890.123456" });
+    const authSpy = vi.fn().mockResolvedValue({ ok: true, user_id: "U_BOT", user: "alvin", team: "Test" });
+
+    vi.doMock("@slack/bolt", () => ({
+      App: class {
+        client = {
+          auth: { test: authSpy },
+          chat: { postMessage: postSpy, update: updateSpy },
+          users: { info: vi.fn() },
+          reactions: { add: vi.fn() },
+          filesUploadV2: vi.fn(),
+          conversations: { info: vi.fn() },
+          apiCall: vi.fn(),
+        };
+        constructor(_opts: unknown) {}
+        message(_h: unknown) {}
+        event(_k: string, _h: unknown) {}
+        async start() {}
+        async stop() {}
+      },
+    }));
+
+    const { SlackAdapter } = await import("../src/platforms/slack.js");
+    const adapter = new SlackAdapter("xoxb-test", "xapp-test");
+    await adapter.start();
+
+    const returnedId = await adapter.editMessage!("C_TEST", "1234567890.123456", "updated text");
+    expect(updateSpy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        channel: "C_TEST",
+        ts: "1234567890.123456",
+        text: "updated text",
+      }),
+    );
+    expect(returnedId).toBe("1234567890.123456");
+
+    await adapter.stop();
+  });
+
+  it("sendText returns the message ts so it can be edited later", async () => {
+    const postSpy = vi.fn().mockResolvedValue({ ok: true, ts: "9876543210.555555" });
+    const authSpy = vi.fn().mockResolvedValue({ ok: true, user_id: "U_BOT", user: "alvin", team: "Test" });
+
+    vi.doMock("@slack/bolt", () => ({
+      App: class {
+        client = {
+          auth: { test: authSpy },
+          chat: { postMessage: postSpy, update: vi.fn() },
+          users: { info: vi.fn() },
+          reactions: { add: vi.fn() },
+          filesUploadV2: vi.fn(),
+          conversations: { info: vi.fn() },
+          apiCall: vi.fn(),
+        };
+        constructor(_opts: unknown) {}
+        message(_h: unknown) {}
+        event(_k: string, _h: unknown) {}
+        async start() {}
+        async stop() {}
+      },
+    }));
+
+    const { SlackAdapter } = await import("../src/platforms/slack.js");
+    const adapter = new SlackAdapter("xoxb-test", "xapp-test");
+    await adapter.start();
+
+    const id = await adapter.sendText("C_TEST", "first message");
+    expect(id).toBe("9876543210.555555");
+
+    await adapter.stop();
+  });
+
+  it("editMessage returns messageId unchanged when chat.update fails", async () => {
+    const updateSpy = vi.fn().mockRejectedValue(new Error("slack down"));
+    const authSpy = vi.fn().mockResolvedValue({ ok: true, user_id: "U_BOT", user: "alvin", team: "Test" });
+
+    vi.doMock("@slack/bolt", () => ({
+      App: class {
+        client = {
+          auth: { test: authSpy },
+          chat: { postMessage: vi.fn().mockResolvedValue({ ok: true, ts: "x" }), update: updateSpy },
+          users: { info: vi.fn() },
+          reactions: { add: vi.fn() },
+          filesUploadV2: vi.fn(),
+          conversations: { info: vi.fn() },
+          apiCall: vi.fn(),
+        };
+        constructor(_opts: unknown) {}
+        message(_h: unknown) {}
+        event(_k: string, _h: unknown) {}
+        async start() {}
+        async stop() {}
+      },
+    }));
+
+    const { SlackAdapter } = await import("../src/platforms/slack.js");
+    const adapter = new SlackAdapter("xoxb-test", "xapp-test");
+    await adapter.start();
+
+    // Should not throw
+    const result = await adapter.editMessage!("C_TEST", "123.456", "new text");
+    expect(result).toBe("123.456");
+
+    await adapter.stop();
+  });
+});

package/test/telegram-workspace-command.test.ts

@@ -0,0 +1,78 @@
+/**
+ * v4.12.0 — Telegram /workspace command + workspace-aware session key.
+ */
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import fs from "fs";
+import os from "os";
+import { resolve } from "path";
+
+const TEST_DATA_DIR = resolve(os.tmpdir(), `alvin-tgws-${process.pid}-${Date.now()}`);
+
+beforeEach(() => {
+  if (fs.existsSync(TEST_DATA_DIR)) fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+  fs.mkdirSync(resolve(TEST_DATA_DIR, "workspaces"), { recursive: true });
+  process.env.ALVIN_DATA_DIR = TEST_DATA_DIR;
+  vi.resetModules();
+});
+
+describe("Telegram workspace state (v4.12.0)", () => {
+  it("getTelegramWorkspace returns null by default", async () => {
+    const { getTelegramWorkspace } = await import("../src/services/session.js");
+    expect(getTelegramWorkspace("42")).toBeNull();
+  });
+
+  it("setTelegramWorkspace stores the name", async () => {
+    const { getTelegramWorkspace, setTelegramWorkspace } = await import("../src/services/session.js");
+    setTelegramWorkspace("42", "alev-b");
+    expect(getTelegramWorkspace("42")).toBe("alev-b");
+  });
+
+  it("setTelegramWorkspace(userId, null) clears the mapping", async () => {
+    const { getTelegramWorkspace, setTelegramWorkspace } = await import("../src/services/session.js");
+    setTelegramWorkspace("42", "alev-b");
+    setTelegramWorkspace("42", null);
+    expect(getTelegramWorkspace("42")).toBeNull();
+  });
+
+  it("persistence: setTelegramWorkspace + flush + reload roundtrips", async () => {
+    const { setTelegramWorkspace, attachPersistHook } = await import("../src/services/session.js");
+    const { flushSessions, schedulePersist } = await import("../src/services/session-persistence.js");
+    attachPersistHook(schedulePersist);
+
+    setTelegramWorkspace("42", "alev-b");
+    setTelegramWorkspace("99", "homes");
+    await flushSessions();
+
+    vi.resetModules();
+    const s2 = await import("../src/services/session.js");
+    const p2 = await import("../src/services/session-persistence.js");
+    p2.loadPersistedSessions();
+
+    expect(s2.getTelegramWorkspace("42")).toBe("alev-b");
+    expect(s2.getTelegramWorkspace("99")).toBe("homes");
+  });
+
+  it("legacy flat session file still loads (backwards compat)", async () => {
+    fs.mkdirSync(resolve(TEST_DATA_DIR, "state"), { recursive: true });
+    fs.writeFileSync(
+      resolve(TEST_DATA_DIR, "state", "sessions.json"),
+      JSON.stringify({
+        "legacy-user": {
+          sessionId: "abc",
+          history: [{ role: "user", content: "from v4.11 era" }],
+          language: "en",
+          effort: "medium",
+          voiceReply: false,
+          workingDir: "/tmp",
+        },
+      }),
+    );
+
+    const { loadPersistedSessions } = await import("../src/services/session-persistence.js");
+    const { getSession } = await import("../src/services/session.js");
+    const loaded = loadPersistedSessions();
+    expect(loaded).toBe(1);
+    expect(getSession("legacy-user").sessionId).toBe("abc");
+    expect(getSession("legacy-user").history[0].content).toBe("from v4.11 era");
+  });
+});

package/test/workspaces.test.ts

@@ -0,0 +1,196 @@
+/**
+ * v4.12.0 — Workspace registry tests.
+ *
+ * A workspace is a markdown file under ~/.alvin-bot/workspaces/<name>.md
+ * with YAML frontmatter defining name, purpose, cwd, color, emoji, and
+ * an optional "channels" array for explicit channel-ID mapping. The
+ * markdown body (below the frontmatter) is the persona instruction
+ * that gets injected into the system prompt for that workspace.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import fs from "fs";
+import os from "os";
+import { resolve } from "path";
+
+const TEST_DATA_DIR = resolve(os.tmpdir(), `alvin-workspaces-${process.pid}-${Date.now()}`);
+
+beforeEach(() => {
+  if (fs.existsSync(TEST_DATA_DIR)) fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+  fs.mkdirSync(TEST_DATA_DIR, { recursive: true });
+  fs.mkdirSync(resolve(TEST_DATA_DIR, "workspaces"), { recursive: true });
+  process.env.ALVIN_DATA_DIR = TEST_DATA_DIR;
+  vi.resetModules();
+});
+
+afterEach(() => {
+  try { fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true }); } catch { /* ignore */ }
+});
+
+function writeWorkspace(name: string, frontmatter: Record<string, unknown>, body: string): void {
+  const fm = Object.entries(frontmatter)
+    .map(([k, v]) => `${k}: ${Array.isArray(v) ? JSON.stringify(v) : JSON.stringify(v)}`)
+    .join("\n");
+  const content = `---\n${fm}\n---\n${body}`;
+  fs.writeFileSync(resolve(TEST_DATA_DIR, "workspaces", `${name}.md`), content, "utf-8");
+}
+
+describe("workspace registry (v4.12.0)", () => {
+  it("returns a default workspace when nothing is configured", async () => {
+    const { loadWorkspaces, getDefaultWorkspace } = await import("../src/services/workspaces.js");
+    loadWorkspaces();
+    const def = getDefaultWorkspace();
+    expect(def.name).toBe("default");
+    expect(def.purpose).toBe("");
+    expect(def.systemPromptOverride).toBe("");
+  });
+
+  it("loads a workspace from a markdown file with frontmatter", async () => {
+    writeWorkspace(
+      "alev-b",
+      { purpose: "Alev-B consulting website dev", cwd: "~/Projects/alev-b-website", emoji: "🏢", color: "#6366f1" },
+      "You are the Alev-B dev assistant. Stack: React + Express + Drizzle.",
+    );
+    const { loadWorkspaces, getWorkspace } = await import("../src/services/workspaces.js");
+    loadWorkspaces();
+    const ws = getWorkspace("alev-b");
+    expect(ws).not.toBeNull();
+    expect(ws!.name).toBe("alev-b");
+    expect(ws!.purpose).toBe("Alev-B consulting website dev");
+    expect(ws!.cwd).toContain("alev-b-website");
+    expect(ws!.emoji).toBe("🏢");
+    expect(ws!.color).toBe("#6366f1");
+    expect(ws!.systemPromptOverride).toContain("Alev-B dev assistant");
+  });
+
+  it("loads multiple workspaces and listWorkspaces returns all of them", async () => {
+    writeWorkspace("alev-b", { purpose: "p1" }, "body1");
+    writeWorkspace("homes", { purpose: "p2" }, "body2");
+    writeWorkspace("jobsnack", { purpose: "p3" }, "body3");
+    const { loadWorkspaces, listWorkspaces } = await import("../src/services/workspaces.js");
+    loadWorkspaces();
+    const names = listWorkspaces().map(w => w.name).sort();
+    expect(names).toEqual(["alev-b", "homes", "jobsnack"]);
+  });
+
+  it("expands ~ in cwd to the user's home directory", async () => {
+    writeWorkspace("tilde", { purpose: "p", cwd: "~/some/path" }, "");
+    const { loadWorkspaces, getWorkspace } = await import("../src/services/workspaces.js");
+    loadWorkspaces();
+    const ws = getWorkspace("tilde");
+    expect(ws!.cwd).toBe(resolve(os.homedir(), "some/path"));
+    expect(ws!.cwd).not.toContain("~");
+  });
+
+  it("matchWorkspaceForChannel matches by explicit channel ID in frontmatter", async () => {
+    writeWorkspace(
+      "alev-b",
+      { purpose: "p", channels: ["C01ALEVABC", "C01ALEVXYZ"] },
+      "",
+    );
+    const { loadWorkspaces, matchWorkspaceForChannel } = await import("../src/services/workspaces.js");
+    loadWorkspaces();
+    const ws = matchWorkspaceForChannel("slack", "C01ALEVABC", undefined);
+    expect(ws?.name).toBe("alev-b");
+  });
+
+  it("matchWorkspaceForChannel falls back to channel name match (case-insensitive, # stripped)", async () => {
+    writeWorkspace("alev-b", { purpose: "p" }, "");
+    const { loadWorkspaces, matchWorkspaceForChannel } = await import("../src/services/workspaces.js");
+    loadWorkspaces();
+    const byHash = matchWorkspaceForChannel("slack", "C_UNKNOWN", "#alev-b");
+    const noHash = matchWorkspaceForChannel("slack", "C_UNKNOWN", "ALEV-B");
+    expect(byHash?.name).toBe("alev-b");
+    expect(noHash?.name).toBe("alev-b");
+  });
+
+  it("matchWorkspaceForChannel returns null for unknown channel with no name match", async () => {
+    writeWorkspace("alev-b", { purpose: "p" }, "");
+    const { loadWorkspaces, matchWorkspaceForChannel } = await import("../src/services/workspaces.js");
+    loadWorkspaces();
+    const ws = matchWorkspaceForChannel("slack", "C_MYSTERY", "#unmapped");
+    expect(ws).toBeNull();
+  });
+
+  it("resolveWorkspaceOrDefault returns the matched workspace when one is found", async () => {
+    writeWorkspace("alev-b", { purpose: "p" }, "persona body");
+    const { loadWorkspaces, resolveWorkspaceOrDefault } = await import("../src/services/workspaces.js");
+    loadWorkspaces();
+    const ws = resolveWorkspaceOrDefault("slack", "C_UNKNOWN", "#alev-b");
+    expect(ws.name).toBe("alev-b");
+    expect(ws.systemPromptOverride).toContain("persona body");
+  });
+
+  it("resolveWorkspaceOrDefault returns the default workspace when no match", async () => {
+    const { loadWorkspaces, resolveWorkspaceOrDefault } = await import("../src/services/workspaces.js");
+    loadWorkspaces();
+    const ws = resolveWorkspaceOrDefault("slack", "C_UNKNOWN", "#whatever");
+    expect(ws.name).toBe("default");
+  });
+
+  it("reloadWorkspaces picks up a newly created file", async () => {
+    const { loadWorkspaces, reloadWorkspaces, listWorkspaces } = await import("../src/services/workspaces.js");
+    loadWorkspaces();
+    expect(listWorkspaces()).toHaveLength(0);
+    writeWorkspace("new-one", { purpose: "p" }, "body");
+    reloadWorkspaces();
+    expect(listWorkspaces()).toHaveLength(1);
+    expect(listWorkspaces()[0].name).toBe("new-one");
+  });
+
+  it("skips files that aren't .md", async () => {
+    fs.writeFileSync(resolve(TEST_DATA_DIR, "workspaces", "notes.txt"), "ignored");
+    writeWorkspace("real", { purpose: "p" }, "body");
+    const { loadWorkspaces, listWorkspaces } = await import("../src/services/workspaces.js");
+    loadWorkspaces();
+    expect(listWorkspaces()).toHaveLength(1);
+    expect(listWorkspaces()[0].name).toBe("real");
+  });
+
+  it("malformed frontmatter: workspace is skipped or loaded with defaults, other workspaces still load", async () => {
+    fs.writeFileSync(
+      resolve(TEST_DATA_DIR, "workspaces", "broken.md"),
+      "---\nthis is: not: valid: yaml:\n---\nbody",
+    );
+    writeWorkspace("good", { purpose: "p" }, "body");
+    const { loadWorkspaces, listWorkspaces } = await import("../src/services/workspaces.js");
+    loadWorkspaces();
+    const names = listWorkspaces().map(w => w.name);
+    expect(names).toContain("good");
+  });
+
+  it("missing workspaces directory is handled gracefully", async () => {
+    fs.rmSync(resolve(TEST_DATA_DIR, "workspaces"), { recursive: true, force: true });
+    const { loadWorkspaces, listWorkspaces } = await import("../src/services/workspaces.js");
+    const count = loadWorkspaces();
+    expect(count).toBe(0);
+    expect(listWorkspaces()).toEqual([]);
+  });
+});
+
+describe("workspace resolver integration with session (v4.12.0)", () => {
+  it("two channels resolve to two different workspaces", async () => {
+    fs.writeFileSync(
+      resolve(TEST_DATA_DIR, "workspaces", "alev-b.md"),
+      `---\npurpose: Alev-B\ncwd: ~/tmp/alev-b\nchannels: ["C_ALEV"]\n---\nAlev-B persona`,
+    );
+    fs.writeFileSync(
+      resolve(TEST_DATA_DIR, "workspaces", "homes.md"),
+      `---\npurpose: HOMES\ncwd: ~/tmp/homes\nchannels: ["C_HOMES"]\n---\nHOMES persona`,
+    );
+
+    vi.resetModules();
+    const { initWorkspaces, resolveWorkspaceOrDefault } = await import("../src/services/workspaces.js");
+    initWorkspaces();
+
+    const alev = resolveWorkspaceOrDefault("slack", "C_ALEV", undefined);
+    const homes = resolveWorkspaceOrDefault("slack", "C_HOMES", undefined);
+    const unknown = resolveWorkspaceOrDefault("slack", "C_MYSTERY", undefined);
+
+    expect(alev.name).toBe("alev-b");
+    expect(alev.systemPromptOverride).toBe("Alev-B persona");
+    expect(homes.name).toBe("homes");
+    expect(homes.systemPromptOverride).toBe("HOMES persona");
+    expect(unknown.name).toBe("default");
+    expect(unknown.systemPromptOverride).toBe("");
+  });
+});

package/web/public/index.html

@@ -82,6 +82,15 @@
     <div id="sessions-list"></div>
   </div>
 
+  <!-- Workspaces (v4.12.0) -->
+  <div class="page content" id="page-workspaces">
+    <div class="card" style="max-width:900px">
+      <h2 style="margin-top:0">🧭 Workspaces</h2>
+      <p class="hint" style="color:var(--fg2);font-size:0.9em">Active sessions grouped by workspace. Each workspace can have its own purpose, working directory, and persona.</p>
+      <div id="workspaces-list" style="display:flex;flex-direction:column;gap:0.5rem;margin-top:1rem"></div>
+    </div>
+  </div>
+
   <!-- Files -->
   <div class="page content" id="page-files">
     <div class="editor-toolbar">

package/web/public/js/app.js

@@ -30,6 +30,7 @@ function initUI() {
     { section: 'nav.data', items: [
       { page: 'memory', icon: 'brain', label: 'nav.memory' },
       { page: 'sessions', icon: 'clipboard', label: 'nav.sessions' },
+      { page: 'workspaces', icon: 'compass', label: 'nav.workspaces' },
       { page: 'files', icon: 'folder', label: 'nav.files' },
     ]},
     { section: 'nav.system', items: [
@@ -228,7 +229,8 @@ function bindNavEvents() {
       const loaders = { dashboard: loadDashboard, memory: loadMemory, models: loadModels,
         sessions: loadSessions, plugins: loadPlugins, tools: loadTools, cron: loadCron,
         files: () => navigateFiles('.'), users: loadUsers, settings: loadSettings,
-        platforms: loadPlatforms, personality: loadPersonality, maintenance: loadMaintenance };
+        platforms: loadPlatforms, personality: loadPersonality, maintenance: loadMaintenance,
+        workspaces: loadWorkspaces };
       if (loaders[page]) loaders[page]();
     });
   });
@@ -1002,6 +1004,47 @@ async function loadSessions() {
   }).join('');
 }
 
+// ── Workspaces (v4.12.0) ────────────────────────────────
+async function loadWorkspaces() {
+  try {
+    const res = await fetch(API + '/api/workspaces');
+    const data = await res.json();
+    const list = document.getElementById('workspaces-list');
+    if (!list) return;
+    if (!data.workspaces || data.workspaces.length === 0) {
+      list.innerHTML = `<div class="hint" style="color:var(--fg2)">No workspaces yet. Create one at <code>~/.alvin-bot/workspaces/&lt;name&gt;.md</code> with YAML frontmatter (purpose, cwd, emoji, color, channels). See <code>docs/install/slack-setup.md</code>.</div>`;
+      return;
+    }
+    list.innerHTML = data.workspaces.map(ws => {
+      const emoji = ws.emoji || '🧭';
+      const color = ws.color || '#6366f1';
+      const purpose = ws.purpose || '<em style="opacity:0.6">(no purpose set)</em>';
+      const cost = (ws.stats.totalCost || 0).toFixed(4);
+      const sessionCount = ws.stats.sessionCount || 0;
+      const messageCount = ws.stats.messageCount || 0;
+      const channelsList = (ws.channels && ws.channels.length > 0)
+        ? `<div class="sub" style="font-size:0.75em;opacity:0.6;margin-top:4px">channels: ${ws.channels.join(', ')}</div>`
+        : '';
+      return `
+        <div class="list-item" style="border-left:4px solid ${color};padding-left:12px">
+          <div class="info" style="flex:1">
+            <div class="name" style="font-weight:600">${emoji} ${ws.name}</div>
+            <div class="desc">${purpose}</div>
+            <div class="sub" style="font-size:0.78em;opacity:0.7;margin-top:2px">cwd: <code>${ws.cwd}</code></div>
+            ${channelsList}
+          </div>
+          <div style="text-align:right;font-family:monospace;font-size:0.85em;opacity:0.8;line-height:1.5">
+            <div>${sessionCount} session${sessionCount === 1 ? '' : 's'}</div>
+            <div>${messageCount} msg</div>
+            <div>$${cost}</div>
+          </div>
+        </div>`;
+    }).join('');
+  } catch (err) {
+    console.error('loadWorkspaces failed:', err);
+  }
+}
+
 // ── Plugins ─────────────────────────────────────────────
 async function loadPlugins() {
   const [pluginsRes, mcpRes, skillsRes] = await Promise.all([