fix(auth): redirect to /login on logout and unauthenticated workspace visits

Two gaps previously left users stuck on blank workspace pages:

1. app-sidebar logout() cleared all state but never moved the URL. The
   current path is /{workspaceSlug}/... which has no meaning without
   auth; the workspace layout would then see user=null, render null
   (via the hasBeenSeen short-circuit), and the user saw a blank page
   thinking logout didn't work.

2. The workspace layouts (web + desktop) had no !user handling at all.
   Any path that leaves user=null — token expiration, cross-tab logout,
   or fresh visit to a workspace URL without a session — resulted in
   the same blank screen.

Fix:
- app-sidebar.logout() explicitly push(paths.login()) after authLogout()
  to cover the primary (user-initiated) logout path.
- Both workspace layouts get a defensive useEffect that redirects to
  /login whenever auth has settled and user is null. Covers token
  expiration, realtime logout, and any other silent session loss.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

CLI_AND_DAEMON.md

@@ -143,6 +143,9 @@ The daemon auto-detects these AI CLIs on your PATH:
 | OpenCode | `opencode` | Open-source coding agent |
 | OpenClaw | `openclaw` | Open-source coding agent |
 | Hermes | `hermes` | Nous Research coding agent |
+| Gemini | `gemini` | Google's coding agent |
+| [Pi](https://pi.dev/) | `pi` | Pi coding agent |
+| [Cursor Agent](https://cursor.com/) | `cursor-agent` | Cursor's headless coding agent |
 
 You need at least one installed. The daemon registers each detected CLI as an available runtime.
 
@@ -183,6 +186,12 @@ Agent-specific overrides:
 | `MULTICA_OPENCLAW_MODEL` | Override the OpenClaw model used |
 | `MULTICA_HERMES_PATH` | Custom path to the `hermes` binary |
 | `MULTICA_HERMES_MODEL` | Override the Hermes model used |
+| `MULTICA_GEMINI_PATH` | Custom path to the `gemini` binary |
+| `MULTICA_GEMINI_MODEL` | Override the Gemini model used |
+| `MULTICA_PI_PATH` | Custom path to the `pi` binary |
+| `MULTICA_PI_MODEL` | Override the Pi model used |
+| `MULTICA_CURSOR_PATH` | Custom path to the `cursor-agent` binary |
+| `MULTICA_CURSOR_MODEL` | Override the Cursor Agent model used |
 
 ### Self-Hosted Server
 

CLI_INSTALL.md

@@ -165,12 +165,12 @@ Wait 3 seconds, then verify:
 multica daemon status
 ```
 
-Expected output should show `running` status with detected agents (e.g. `claude`, `codex`, `opencode`, `openclaw`, `hermes`).
+Expected output should show `running` status with detected agents (e.g. `claude`, `codex`, `opencode`, `openclaw`, `hermes`, `gemini`, `pi`, `cursor-agent`).
 
 **If daemon fails to start:**
 - Check logs: `multica daemon logs`
 - If a port conflict occurs, the daemon may already be running under a different profile.
-- If no agents are detected, ensure at least one AI CLI (`claude`, `codex`, `opencode`, `openclaw`, or `hermes`) is installed and on the `$PATH`.
+- If no agents are detected, ensure at least one AI CLI (`claude`, `codex`, `opencode`, `openclaw`, `hermes`, `gemini`, `pi`, or `cursor-agent`) is installed and on the `$PATH`.
 
 ---
 
@@ -184,12 +184,12 @@ multica daemon status
 
 Confirm:
 1. Status is `running`
-2. At least one agent is listed (e.g. `claude`, `codex`, `opencode`, `openclaw`, or `hermes`)
+2. At least one agent is listed (e.g. `claude`, `codex`, `opencode`, `openclaw`, `hermes`, `gemini`, `pi`, or `cursor-agent`)
 3. At least one workspace is being watched
 
 If the agents list is empty, tell the user:
 
-> "The Multica daemon is running but no AI agent CLIs were detected. Please install at least one supported CLI (`claude`, `codex`, `opencode`, `openclaw`, or `hermes`), then restart the daemon with `multica daemon stop && multica daemon start`."
+> "The Multica daemon is running but no AI agent CLIs were detected. Please install at least one supported CLI (`claude`, `codex`, `opencode`, `openclaw`, `hermes`, `gemini`, `pi`, or `cursor-agent`), then restart the daemon with `multica daemon stop && multica daemon start`."
 
 ---
 

HANDOFF_ARCHITECTURE_AUDIT.md

@@ -0,0 +1,383 @@
+# Architecture Audit — Workspace & Realtime Cache
+
+> 基于代码审计整理的 4 个任务。优先级：P0 一个、P1 一个、P2 两个。每个任务都包含问题、根因、受影响的 issue、复现步骤、修复方案、改动范围。
+
+---
+
+## 任务 1 — [P0] 空闲后列表数据陈旧
+
+**关联 issue**：[#951](https://github.com/multica-ai/multica/issues/951)
+
+### 问题
+
+用户登录后静置一段时间，Issue 列表里缺失一部分数据（其他成员期间新建/变更的 issue 不出现）。登出再登入可以恢复。`ec5af33b` 声称 "Closes #951"，但 issue 仍为 OPEN 状态 —— 因为它只修了 401 一种场景，没修 WS 半开这一种。
+
+### 根因
+
+系统把 cache 新鲜度的全部责任压给了 WebSocket 推送：
+
+- `packages/core/query-client.ts:7` — `staleTime: Infinity`，cache 永不主动过期
+- `packages/core/query-client.ts:9` — `refetchOnWindowFocus: false`，tab 重新获得焦点也不 refetch
+- 依赖 WS 推送 `issue:created` / `issue:updated` 事件 invalidate cache
+
+但 WS 层存在一个**不对称**：
+
+- **服务端**：`server/internal/realtime/hub.go:83-96, 420-475` 有 54s ping / 60s pongWait，会清理死连接
+- **客户端**：`packages/core/api/ws-client.ts`（142 行全貌）**完全没有心跳检测**，只靠 `onclose` 事件触发重连
+
+浏览器原生 `WebSocket` API 不把 ping/pong 帧暴露给 JS，所以 JS 层无法主动探测 "半开" 连接。当 NAT / 负载均衡器 / 笔记本睡眠导致 TCP 连接被静默切断时：
+
+1. 浏览器 `readyState` 仍是 `OPEN`
+2. `onclose` 不触发
+3. `ws-client.ts:70-73` 的 3 秒重连逻辑不跑
+4. `packages/core/realtime/use-realtime-sync.ts:462-487` 的 `onReconnect` 全量 invalidate 不跑
+5. 期间的 WS 事件进黑洞
+6. cache 保持旧快照
+
+### 复现
+
+**浏览器 DevTools 里的 "Block request URL" 不行** —— 那会触发 `onclose`，走正常重连 → 不复现。真正的半开需要在网络层静默丢包。
+
+**方法 A（推荐，最接近真实场景）**：macOS 用 pfctl 丢包
+
+```bash
+# 假设后端在 8080
+sudo pfctl -E
+echo "block drop out quick proto tcp to any port 8080" | sudo pfctl -f -
+
+# 观察:
+# - Console 里没有 "disconnected, reconnecting in 3s" 日志
+# - Network 里 WS 连接仍显示 Pending / 101
+# 用另一个账号/CLI 创建一个 issue
+# 回到原客户端: 列表不更新
+# 登出再登入: 列表恢复完整
+
+sudo pfctl -d  # 解除
+```
+
+**方法 B（不动网络）**：临时修改代码，在 `packages/core/api/ws-client.ts:52` 的 `onmessage` 处理器里加一行 `return;` 在前面，吞掉所有入站消息。效果等价于半开。
+
+### 修复方案（三个选项，推荐 C）
+
+#### 选项 A — 浏览器端心跳探活（治本，改动大）
+
+在 `ws-client.ts` 加客户端侧的心跳检测：记录 `lastMessageTime`，定时器检查若超过 N 秒没收到任何消息就主动 `ws.close()`，触发现有重连逻辑。
+
+- 优点：从根本上解决半开问题
+- 缺点：浏览器原生 API 没有 ping 能力，需要服务端配合发"应用层 heartbeat"消息供客户端更新 `lastMessageTime`；服务端改 + 客户端改
+
+#### 选项 B — Page Visibility API 触发 invalidate（治标，改动小）
+
+在 `packages/core/platform/core-provider.tsx` 加 `visibilitychange` 监听，tab 重新可见时强制 `queryClient.invalidateQueries({ queryKey: issueKeys.all(wsId) })`（及其他关键 key）。
+
+- 优点：~10 行代码，能兜住 80% 场景（睡眠、切后台 tab）
+- 缺点：treats symptom, 不是真正的半开检测；对"一直保持 tab 可见但网络层断了"的场景无效
+
+#### 选项 C — **A + B 组合**（推荐）
+
+- 短期上 B，立刻止血
+- 中期上 A，把 cache 新鲜度从"只信 WS"改成"WS 是优化，Visibility 是兜底"
+- 可选加 `refetchOnWindowFocus: true` 或把 `staleTime` 改成一个有限值（比如 5 min），作为第三层保险
+
+### 改动范围
+
+| 方案 | 文件 | 改动规模 |
+|---|---|---|
+| B | `packages/core/platform/core-provider.tsx` | ~10 行 |
+| A 客户端 | `packages/core/api/ws-client.ts` | ~30 行 |
+| A 服务端 | `server/internal/realtime/hub.go` | 加 app-level heartbeat message |
+
+### 验证
+
+修完之后：
+
+1. 跑方法 A 复现流程，确认数据不再丢失
+2. 加 e2e 测试：模拟 `document.dispatchEvent(new Event('visibilitychange'))` + 验证 issue list 被 refetch
+
+---
+
+## 任务 2 — [P1] Workspace 不在 URL 路径中
+
+**关联 issue**：MUL-723（slug 不在 URL）、MUL-43（切换 workspace 报错）、MUL-509（手机端无法切换）
+
+> **注意**：审计中提到的 MUL-43 / MUL-476 issue 编号需要当面核对一次 —— agent 查询 GitHub 后返回的标题对不上（看起来是别的 PR）。交接时请让执行人以具体症状为准。
+
+### 问题
+
+当前 workspace 身份完全靠 `X-Workspace-ID` HTTP header + Zustand store + localStorage 承载，URL 里没有 workspace 信息。所有路径都是 `/issues`、`/issues/:id` 这种 workspace-agnostic 的。
+
+### 根因
+
+**数据库和 API 已经支持 slug**：
+
+- `server/migrations/001_init.up.sql:15-23` — workspace 表有 `slug TEXT UNIQUE NOT NULL`
+- `server/pkg/db/queries/workspace.sql:11-13` — 有 `GetWorkspaceBySlug` 查询
+- `packages/core/types/workspace.ts:8-19` — Workspace 类型里有 slug 字段
+
+**但前端路由和导航层没用它**：
+
+- Web 路由：`apps/web/app/(dashboard)/` 下 25 个 route file 都是 workspace-implicit
+- Desktop 路由：`apps/desktop/src/renderer/src/routes.tsx:71-143` 同样
+- Navigation 适配器 `apps/web/platform/navigation.tsx` 直接透传 `router.push`，没有任何 workspace 前缀逻辑
+
+**workspace 切换只靠 sidebar UI**（`packages/views/layout/app-sidebar.tsx:284-286`）：
+
+```tsx
+if (ws.id !== workspace?.id) {
+  push("/issues");              // 硬跳 /issues（workspace-implicit！）
+  switchWorkspace(ws);           // 然后改 store
+}
+```
+
+这种设计使得：
+
+- 手机端因为没 sidebar UI，也没 URL 层切换入口，**完全切不了 workspace**（MUL-509）
+- 把 `/issues/xxx` 链接发给处于不同 workspace 的同事，会打开错误 workspace 下的 issue，或找不到报错（MUL-43 系列）
+- 分享链接没有 workspace 上下文，接收方必须先手动切对 workspace
+
+### 复现
+
+1. **MUL-723**：登录 → 观察地址栏，没有任何 workspace 标识
+2. **MUL-43**：
+   - 加入两个 workspace A 和 B
+   - 在 A 中打开某个 issue `/issues/abc123`
+   - 切到 B，URL 不变 → 访问失败 / 显示错数据
+3. **MUL-509**：手机浏览器打开，尝试切 workspace → 无法切换（UI 不显示 sidebar 触发器或触发器无法切）
+
+### 修复方案（三个选项，推荐 A）
+
+#### 选项 A — `/ws/:slug/...` URL 前缀（根本方案，推荐）
+
+所有路径加上 workspace slug 前缀。例如 `/issues/abc123` → `/ws/my-team/issues/abc123`。
+
+**要改的地方**：
+
+1. **Web 路由目录结构**：`apps/web/app/(dashboard)/` 下全部搬到 `apps/web/app/(dashboard)/ws/[slug]/...`（~25 个文件）
+2. **Desktop 路由**：`apps/desktop/src/renderer/src/routes.tsx:71-143` 给所有路径加 `/ws/:slug` 前缀
+3. **Navigation 适配器**：
+   - `apps/web/platform/navigation.tsx` — `push(path)` 内部前置 `/ws/${workspace.slug}`，`pathname` 读取时去掉前缀
+   - `apps/desktop/src/renderer/src/platform/navigation.tsx` — 同上
+4. **Sidebar 切换逻辑**：`packages/views/layout/app-sidebar.tsx:284-286` 改成 `push('/ws/${ws.slug}/issues')`（或依赖适配器自动加前缀就不用改）
+5. **服务端中间件**：`server/internal/middleware/workspace.go:41-46` 增加 "从 URL path 解析 slug → 查 ID → 校验 membership" 的逻辑，header 继续作为 fallback（迁移期兼容）
+
+**预计改动**：~50-100 个文件（大部分是 route 搬迁，不是逻辑改动）、~5-7 人天
+
+**不改也能工作的部分**：
+- `packages/core/api/client.ts` — 仍旧走 header，不用改
+- 所有 `packages/views/` 下的组件 —— 它们用 `useNavigation().push()` 抽象，适配器层处理前缀就行
+
+**风险**：
+- 旧的 bookmark URL 失效（如果产品还没正式 ship，问题不大）
+- E2E 测试需要更新所有 URL 断言
+
+#### 选项 B — `?ws=slug` query param（折中）
+
+URL 形如 `/issues?ws=my-team`。改动更小（~30 个文件），URL 丑但向后兼容。推荐度低于 A。
+
+#### 选项 C — 只修症状不动架构
+
+在 `switchWorkspace` 和各个 query 之间加 debounce、error boundary 等 workaround。不解决根因，技术债越攒越多。**不推荐**。
+
+### 改动范围（选项 A）
+
+| 模块 | 文件数 | 备注 |
+|---|---|---|
+| Web routes | ~25 | 目录搬迁 |
+| Desktop routes | 1 | 路径前缀 |
+| Navigation adapters | 2 | 前缀逻辑 |
+| Server middleware | 1-2 | slug → ID 解析 |
+| 组件（不用改） | 30-40 | 用 `useNavigation` 的不受影响 |
+| E2E tests | 20-30 | URL 断言更新 |
+
+---
+
+## 任务 3 — [P1] Workspace 切换时 navigation 状态未隔离
+
+**关联 issue**：MUL-43（切换报错）、MUL-476（本地缓存未按 workspace 隔离）
+
+> 同上，这两个编号建议交接时核对症状。
+
+### 问题
+
+绝大多数 workspace-scoped 的 Zustand store 都正确使用了 `createWorkspaceAwareStorage`（key 后缀加 wsId 自动隔离），但 **`useNavigationStore` 是个例外**：它持久化了 `lastPath`，但用的是 global storage，切换 workspace 后里面仍是上个 workspace 的路径。
+
+### 根因
+
+**`packages/core/navigation/store.ts:15-31`**：
+
+```typescript
+export const useNavigationStore = create<NavigationState>()(
+  persist(
+    (set) => ({
+      lastPath: "/issues",
+      onPathChange: (path) => { /* ... */ set({ lastPath: path }); },
+    }),
+    {
+      name: "multica_navigation",
+      storage: createJSONStorage(() => createPersistStorage(defaultStorage)), // ← 这里用的是 global，不是 workspace-aware
+      partialize: (state) => ({ lastPath: state.lastPath }),
+    }
+  )
+);
+// ← 没有调 registerForWorkspaceRehydration
+```
+
+**对比：其他 store 都是正确的**：
+
+| Store | 是否 workspace-aware | 是否注册 rehydration |
+|---|---|---|
+| useNavigationStore | ❌ | ❌ |
+| useIssuesScopeStore | ✅ | ✅ |
+| useIssueDraftStore | ✅ | ✅ |
+| useRecentIssuesStore | ✅ | ✅ |
+| useIssueViewStore | ✅ | ✅ |
+| myIssuesViewStore | ✅ | ✅ |
+| useChatStore | ✅（手动用 wsKey）| ✅ |
+
+另外 `packages/core/platform/storage-cleanup.ts:10-19` 的 `WORKSPACE_SCOPED_KEYS` 列表里也漏了 `multica_navigation`。
+
+**现有的 workaround**：`packages/views/layout/app-sidebar.tsx:285` 切 workspace 时硬跳到 `/issues`，正是为了绕开这个 bug。修好 navigation store 之后这行 hack 可以删掉。
+
+### 复现
+
+1. 在 workspace A 中打开一个具体 issue `/issues/abc123`
+2. 切到 workspace B
+3. 观察：如果没有 sidebar 的硬跳 workaround，会尝试恢复到 `/issues/abc123`，但那个 issue 不属于 B，导致 404 或错误
+
+目前因为有硬跳 workaround，症状表现为"切 workspace 后总是回到 issue 首页"—— 这本身也是 bug（用户期望记住上次位置）。
+
+### 修复方案（推荐 Option C：组合）
+
+**三处改动**：
+
+1. `packages/core/navigation/store.ts:28` —— 把 `createPersistStorage(defaultStorage)` 改成 `createWorkspaceAwareStorage(defaultStorage)`
+2. 同文件在末尾加：`registerForWorkspaceRehydration(() => useNavigationStore.persist.rehydrate());`
+3. `packages/core/platform/storage-cleanup.ts:10-19` 的 `WORKSPACE_SCOPED_KEYS` 数组里加 `"multica_navigation"`
+
+**可选**：清理 `packages/views/layout/app-sidebar.tsx:285` 的 `push("/issues")` workaround（改完之后不再需要）。
+
+### 改动范围
+
+| 文件 | 改动 |
+|---|---|
+| `packages/core/navigation/store.ts` | 改 storage 类型、加 rehydration 注册（~3 行） |
+| `packages/core/platform/storage-cleanup.ts` | 数组加一行 |
+| `packages/core/platform/workspace-storage.test.ts` | 加 rehydration 的单测 |
+| `packages/views/layout/app-sidebar.tsx`（可选） | 移除硬跳 workaround |
+
+**风险**：极低。只是把 navigation store 对齐到其他 store 已经在用的模式。
+
+---
+
+## 任务 4 — [P2] Workspace 生命周期副作用散落
+
+**关联 issue**：MUL-727（创建后闪页）、MUL-728（删除确认）、MUL-820（接受邀请不自动切）
+
+### 问题
+
+创建 / 删除 / 切换 / 加入 workspace 的副作用分散在 mutation 的 `onSuccess` 和各处 UI 回调里，没有统一抽象。几个具体 bug：
+
+### 4.1 MUL-727 — 创建 workspace 后闪一下 `/issues` 再跳 `/onboarding`
+
+**根因**：两个 `onSuccess` 回调同时跑，顺序不确定。
+
+- `packages/core/workspace/mutations.ts:7-21` 的 `useCreateWorkspace.onSuccess` 里调了 `switchWorkspace(newWs)` —— 同步改 Zustand，`/issues` 路由开始用新 workspace 渲染
+- `packages/views/modals/create-workspace.tsx:68-70` 的 UI `onSuccess` 里调了 `router.push("/onboarding")` —— 异步 schedule 导航
+
+于是：`/issues` 先渲染（闪一下）→ 导航到 `/onboarding`。
+
+**修复**：把 `switchWorkspace` 从 mutation 里拿出来，让 UI 层主导。在 `create-workspace.tsx` 的 `onSuccess` 里先 `switchWorkspace` 再 `push`，保证同一个微任务里完成。
+
+**文件**：`packages/core/workspace/mutations.ts`、`packages/views/modals/create-workspace.tsx`、可能 `packages/views/onboarding/step-workspace.tsx`
+
+### 4.2 MUL-728 — 删除 workspace 的"缺少确认"
+
+**核查结果**：`packages/views/settings/components/workspace-tab.tsx:102-119, 236-255` **已经有 AlertDialog 确认**了。
+
+**真实问题**：删除成功后**没有导航**，用户停在 `/settings`，而当前 workspace 已经是删除后系统挑的另一个。
+
+**修复**：在 `handleDeleteWorkspace` 的 `onConfirm` 成功分支里加 `push("/issues")`。
+
+**文件**：`packages/views/settings/components/workspace-tab.tsx`（加一行）
+
+### 4.3 MUL-820 — 接受邀请不自动切换 workspace
+
+**核查结果**：有两条路径：
+
+- ✅ `/invite/:id` 独立页（`packages/views/invite/invite-page.tsx:32-52`）是**正确的**：accept → switchWorkspace → push("/issues")
+- ❌ **Sidebar 下拉里的 "Join" 按钮**（`packages/views/layout/app-sidebar.tsx:203-209, 321-324`）**是错的**：只 invalidate cache，不切也不跳
+
+**修复（推荐 Option 2）**：Sidebar 的 "Join" 改成跳转到 `/invite/:id` 页面，不再就地接受。单一入口、单一行为。
+
+```tsx
+<DropdownMenuItem onClick={() => push(`/invite/${inv.id}`)}>
+  {inv.workspace_name}
+</DropdownMenuItem>
+```
+
+**文件**：`packages/views/layout/app-sidebar.tsx`（~10 行）
+
+### 复现
+
+| Issue | 步骤 |
+|---|---|
+| MUL-727 | 创建新 workspace → 仔细看是否闪了一下 `/issues` 再跳 `/onboarding` |
+| MUL-728 | 删除当前 workspace → 观察删完后是否留在 `/settings` 页面（BUG: 没有自动跳走） |
+| MUL-820 | 被邀请用户登录 → sidebar 下拉 → 点 "Join" → 观察当前 workspace 是否切过去（BUG: 不切）|
+
+### 长期架构建议（可选）
+
+抽一个 `useWorkspaceLifecycle` hook 统一管这些副作用。Agent 报告里有完整设计，文件：`packages/core/workspace/hooks.ts`（新建）。但建议先修 MUL-727/728/820 三个具体 bug，hook 抽象作为后续迭代。
+
+### 改动范围
+
+| Issue | 文件 | 改动规模 |
+|---|---|---|
+| MUL-727 | mutations.ts + create-workspace.tsx | ~10 行 |
+| MUL-728 | workspace-tab.tsx | ~1 行 |
+| MUL-820 | app-sidebar.tsx | ~10 行 |
+
+---
+
+## 总览
+
+| 任务 | Issue | 优先级 | 预估规模 | 风险 |
+|---|---|---|---|---|
+| 1. WS 半开 + 陈旧 cache | #951 | **P0** | Option B ~10 行；Option C ~1-2 天 | 低 |
+| 2. Workspace URL 化 | MUL-723/43/509 | P1 | 5-7 人天（大部分是搬迁）| 中（影响面大、e2e 要改）|
+| 3. Navigation store 隔离 | MUL-43/476 | P1 | ~0.5 天 | 低 |
+| 4. Workspace 生命周期 bug | MUL-727/728/820 | P2 | ~1 天 | 低 |
+
+### 建议推进顺序
+
+1. **立刻做**：任务 1 的 Option B（visibilitychange 触发 invalidate）—— 代码最少、收益最明显，能当天止血
+2. **同步开始**：任务 3（navigation store 隔离）—— 影响小、风险低、顺便清掉一个 workaround
+3. **规划立项**：任务 2（URL 化）—— 大改造，需要单独开一个 iteration
+4. **次要修补**：任务 4 的三个小 bug —— 可以拆成独立 PR，各自 review
+
+### 重要澄清
+
+- **Issue 编号核对**：MUL-43 / MUL-476 的编号需要核对一次，agent 查询 GitHub 返回的标题看起来对不上（可能是内部 issue tracker 编号 vs GitHub 编号混用）。以症状为准。
+- **MUL-728 实际状态**：确认对话框已经存在，真实缺的是"删除后跳走"。
+- **MUL-820 实际状态**：`/invite/:id` 页面路径工作正常，只是 sidebar 下拉按钮坏了。
+
+### 所有关键代码位置索引
+
+```
+packages/core/query-client.ts:7-10          # staleTime: Infinity
+packages/core/api/ws-client.ts:1-142        # 客户端 WS，无心跳
+packages/core/realtime/use-realtime-sync.ts:462-487  # onReconnect 全量 invalidate
+packages/core/platform/core-provider.tsx    # 加 visibilitychange 的位置
+packages/core/navigation/store.ts:15-31     # lastPath 未隔离
+packages/core/platform/storage-cleanup.ts:10-19  # WORKSPACE_SCOPED_KEYS
+packages/core/workspace/store.ts:43-77      # hydrateWorkspace / switchWorkspace
+packages/core/workspace/mutations.ts:7-57   # create/leave/delete 三个 mutation
+packages/views/layout/app-sidebar.tsx:203-324  # 侧边栏切 workspace、接受邀请入口
+packages/views/modals/create-workspace.tsx:63-82  # 创建 workspace 入口
+packages/views/settings/components/workspace-tab.tsx:102-119  # 删除 workspace 入口
+packages/views/invite/invite-page.tsx:32-52 # 接受邀请正确实现参考
+
+server/internal/realtime/hub.go:83-96       # 服务端 WS 心跳
+server/internal/middleware/workspace.go:41-46  # wsId resolution
+server/migrations/001_init.up.sql:15-23     # workspace.slug 已存在
+```

Makefile

@@ -182,7 +182,7 @@ server:
 	cd server && go run ./cmd/server
 
 daemon:
-	@$(MAKE) multica MULTICA_ARGS="daemon"
+	@$(MAKE) multica MULTICA_ARGS="daemon restart --profile local"
 
 cli:
 	@$(MAKE) multica MULTICA_ARGS="$(MULTICA_ARGS)"

README.md

@@ -30,7 +30,7 @@ Turn coding agents into real teammates — assign tasks, track progress, compoun
 
 Multica turns coding agents into real teammates. Assign issues to an agent like you'd assign to a colleague — they'll pick up the work, write code, report blockers, and update statuses autonomously.
 
-No more copy-pasting prompts. No more babysitting runs. Your agents show up on the board, participate in conversations, and compound reusable skills over time. Think of it as open-source infrastructure for managed agents — vendor-neutral, self-hosted, and designed for human + AI teams. Works with **Claude Code**, **Codex**, **OpenClaw**, and **OpenCode**.
+No more copy-pasting prompts. No more babysitting runs. Your agents show up on the board, participate in conversations, and compound reusable skills over time. Think of it as open-source infrastructure for managed agents — vendor-neutral, self-hosted, and designed for human + AI teams. Works with **Claude Code**, **Codex**, **OpenClaw**, **OpenCode**, **Hermes**, **Gemini**, **Pi**, and **Cursor Agent**.
 
 <p align="center">
   <img src="docs/assets/hero-screenshot.png" alt="Multica board view" width="800">
@@ -97,7 +97,7 @@ multica setup          # Connect to Multica Cloud, log in, start daemon
 multica setup           # Configure, authenticate, and start the daemon
 ```
 
-The daemon runs in the background and auto-detects agent CLIs (`claude`, `codex`, `openclaw`, `opencode`) on your PATH.
+The daemon runs in the background and auto-detects agent CLIs (`claude`, `codex`, `openclaw`, `opencode`, `hermes`, `gemini`, `pi`, `cursor-agent`) on your PATH.
 
 ### 2. Verify your runtime
 
@@ -107,7 +107,7 @@ Open your workspace in the Multica web app. Navigate to **Settings → Runtimes*
 
 ### 3. Create an agent
 
-Go to **Settings → Agents** and click **New Agent**. Pick the runtime you just connected and choose a provider (Claude Code, Codex, OpenClaw, or OpenCode). Give your agent a name — this is how it will appear on the board, in comments, and in assignments.
+Go to **Settings → Agents** and click **New Agent**. Pick the runtime you just connected and choose a provider (Claude Code, Codex, OpenClaw, OpenCode, Hermes, Gemini, Pi, or Cursor Agent). Give your agent a name — this is how it will appear on the board, in comments, and in assignments.
 
 ### 4. Assign your first task
 
@@ -158,10 +158,10 @@ See the [CLI and Daemon Guide](CLI_AND_DAEMON.md) for the full command reference
 └──────────────┘     └──────┬───────┘     └──────────────────┘
                             │
                      ┌──────┴───────┐
-                     │ Agent Daemon │  (runs on your machine)
-                     │Claude/Codex/ │
-                     │OpenClaw/Code │
-                     └──────────────┘
+                     │ Agent Daemon │  runs on your machine
+                     └──────────────┘  (Claude Code, Codex, OpenCode,
+                                        OpenClaw, Hermes, Gemini,
+                                        Pi, Cursor Agent)
 ```
 
 | Layer | Stack |
@@ -169,7 +169,7 @@ See the [CLI and Daemon Guide](CLI_AND_DAEMON.md) for the full command reference
 | Frontend | Next.js 16 (App Router) |
 | Backend | Go (Chi router, sqlc, gorilla/websocket) |
 | Database | PostgreSQL 17 with pgvector |
-| Agent Runtime | Local daemon executing Claude Code, Codex, OpenClaw, or OpenCode |
+| Agent Runtime | Local daemon executing Claude Code, Codex, OpenClaw, OpenCode, Hermes, Gemini, Pi, or Cursor Agent |
 
 ## Development
 

README.zh-CN.md

@@ -30,7 +30,7 @@
 
 Multica 将编码 Agent 变成真正的队友。像分配给同事一样分配给 Agent——它们会自主接手工作、编写代码、报告阻塞问题、更新状态。
 
-不再需要复制粘贴 prompt，不再需要盯着运行过程。你的 Agent 出现在看板上、参与对话、随着时间积累可复用的技能。可以理解为开源的 Managed Agents 基础设施——厂商中立、可自部署、专为人类 + AI 团队设计。支持 **Claude Code**、**Codex**、**OpenClaw** 和 **OpenCode**。
+不再需要复制粘贴 prompt，不再需要盯着运行过程。你的 Agent 出现在看板上、参与对话、随着时间积累可复用的技能。可以理解为开源的 Managed Agents 基础设施——厂商中立、可自部署、专为人类 + AI 团队设计。支持 **Claude Code**、**Codex**、**OpenClaw**、**OpenCode**、**Hermes**、**Gemini**、**Pi** 和 **Cursor Agent**。
 
 <p align="center">
   <img src="docs/assets/hero-screenshot.png" alt="Multica 看板视图" width="800">
@@ -99,7 +99,7 @@ multica setup          # 连接 Multica Cloud，登录，启动 daemon
 multica setup           # 配置、认证、启动 daemon（一条命令搞定）
 ```
 
-daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动检测 PATH 中可用的 Agent CLI（`claude`、`codex`、`openclaw`、`opencode`）。
+daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动检测 PATH 中可用的 Agent CLI（`claude`、`codex`、`openclaw`、`opencode`、`hermes`、`gemini`、`pi`、`cursor-agent`）。
 
 ### 2. 确认运行时已连接
 
@@ -109,7 +109,7 @@ daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动
 
 ### 3. 创建 Agent
 
-进入 **设置 → Agents**，点击 **新建 Agent**。选择你刚连接的 Runtime，选择 Provider（Claude Code、Codex、OpenClaw 或 OpenCode），并为 Agent 起个名字——它将以这个名字出现在看板、评论和任务分配中。
+进入 **设置 → Agents**，点击 **新建 Agent**。选择你刚连接的 Runtime，选择 Provider（Claude Code、Codex、OpenClaw、OpenCode、Hermes、Gemini、Pi 或 Cursor Agent），并为 Agent 起个名字——它将以这个名字出现在看板、评论和任务分配中。
 
 ### 4. 分配你的第一个任务
 
@@ -141,10 +141,10 @@ daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动
 └──────────────┘     └──────┬───────┘     └──────────────────┘
                             │
                      ┌──────┴───────┐
-                     │ Agent Daemon │  （运行在你的机器上）
-                     │Claude/Codex/ │
-                     │OpenClaw/Code │
-                     └──────────────┘
+                     │ Agent Daemon │  运行在你的机器上
+                     └──────────────┘  （Claude Code、Codex、OpenCode、
+                                        OpenClaw、Hermes、Gemini、
+                                        Pi、Cursor Agent）
 ```
 
 | 层级 | 技术栈 |
@@ -152,7 +152,7 @@ daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动
 | 前端 | Next.js 16 (App Router) |
 | 后端 | Go (Chi router, sqlc, gorilla/websocket) |
 | 数据库 | PostgreSQL 17 with pgvector |
-| Agent 运行时 | 本地 daemon 执行 Claude Code、Codex、OpenClaw 或 OpenCode |
+| Agent 运行时 | 本地 daemon 执行 Claude Code、Codex、OpenClaw、OpenCode、Hermes、Gemini、Pi 或 Cursor Agent |
 
 ## 开发
 

SELF_HOSTING.md

@@ -85,6 +85,9 @@ You also need at least one AI agent CLI installed:
 - [OpenClaw](https://github.com/openclaw/openclaw) (`openclaw` on PATH)
 - [OpenCode](https://github.com/anomalyco/opencode) (`opencode` on PATH)
 - [Hermes](https://github.com/NousResearch/hermes) (`hermes` on PATH)
+- Gemini (`gemini` on PATH)
+- [Pi](https://pi.dev/) (`pi` on PATH)
+- [Cursor Agent](https://cursor.com/) (`cursor-agent` on PATH)
 
 ### b) One-command setup
 

SELF_HOSTING_ADVANCED.md

@@ -80,6 +80,12 @@ Agent-specific overrides:
 | `MULTICA_OPENCLAW_MODEL` | Override the OpenClaw model used |
 | `MULTICA_HERMES_PATH` | Custom path to the `hermes` binary |
 | `MULTICA_HERMES_MODEL` | Override the Hermes model used |
+| `MULTICA_GEMINI_PATH` | Custom path to the `gemini` binary |
+| `MULTICA_GEMINI_MODEL` | Override the Gemini model used |
+| `MULTICA_PI_PATH` | Custom path to the `pi` binary |
+| `MULTICA_PI_MODEL` | Override the Pi model used |
+| `MULTICA_CURSOR_PATH` | Custom path to the `cursor-agent` binary |
+| `MULTICA_CURSOR_MODEL` | Override the Cursor Agent model used |
 
 ## Database Setup
 

apps/desktop/src/main/index.ts

@@ -94,6 +94,18 @@ function createWindow(): void {
   }
 }
 
+// --- Dev / production isolation -------------------------------------------
+// Give dev mode a separate app name and userData path so it gets its own
+// single-instance lock file and doesn't conflict with the packaged production
+// app. Must run BEFORE requestSingleInstanceLock() because the lock location
+// is derived from the userData path. (Same approach VS Code uses for
+// Stable / Insiders coexistence.)
+
+if (is.dev) {
+  app.setName("Multica Dev");
+  app.setPath("userData", join(app.getPath("appData"), "Multica Dev"));
+}
+
 // --- Protocol registration -----------------------------------------------
 
 if (process.defaultApp) {
@@ -125,7 +137,9 @@ if (!gotTheLock) {
   });
 
   app.whenReady().then(() => {
-    electronApp.setAppUserModelId("ai.multica.desktop");
+    electronApp.setAppUserModelId(
+      is.dev ? "ai.multica.desktop.dev" : "ai.multica.desktop",
+    );
 
     app.on("browser-window-created", (_, window) => {
       optimizer.watchWindowShortcuts(window);
@@ -137,7 +151,7 @@ if (!gotTheLock) {
     });
 
     // IPC: toggle immersive mode — hides the macOS traffic lights so full-screen
-    // modals (create-workspace, onboarding) can place UI in the top-left corner
+    // modals (e.g. create-workspace) can place UI in the top-left corner
     // without fighting the native window controls' hit-test.
     ipcMain.handle("window:setImmersive", (_event, immersive: boolean) => {
       if (process.platform !== "darwin") return;

apps/desktop/src/renderer/src/App.tsx

@@ -1,7 +1,8 @@
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
 import { CoreProvider } from "@multica/core/platform";
 import { useAuthStore } from "@multica/core/auth";
-import { useWorkspaceStore } from "@multica/core/workspace";
+import { workspaceKeys, workspaceListOptions } from "@multica/core/workspace/queries";
 import { api } from "@multica/core/api";
 import { ThemeProvider } from "@multica/ui/components/common/theme-provider";
 import { MulticaIcon } from "@multica/ui/components/common/multica-icon";
@@ -13,13 +14,14 @@ import { UpdateNotification } from "./components/update-notification";
 function AppContent() {
   const user = useAuthStore((s) => s.user);
   const isLoading = useAuthStore((s) => s.isLoading);
+  const qc = useQueryClient();
   // Deep-link login runs loginWithToken → syncToken → listWorkspaces →
-  // hydrateWorkspace sequentially. loginWithToken sets user+isLoading=false
+  // setQueryData sequentially. loginWithToken sets user+isLoading=false
   // as soon as getMe resolves, which would cause DesktopShell to mount
   // before the workspace list is hydrated and briefly see `!workspace`.
   // This local flag keeps the loading screen up until the whole chain
-  // finishes, so the shell's "needs onboarding?" check gets a definitive
-  // workspace state on first render.
+  // finishes, so IndexRedirect gets a definitive workspace state on
+  // first render.
   const [bootstrapping, setBootstrapping] = useState(false);
 
   // Tell the main process which backend URL we talk to, so daemon-manager
@@ -36,16 +38,20 @@ function AppContent() {
       setBootstrapping(true);
       try {
         await useAuthStore.getState().loginWithToken(token);
+        // Seed React Query cache with the workspace list so the index-route
+        // redirect (routes.tsx `IndexRedirect`) can resolve the initial
+        // destination without a second fetch. Workspace side-effects
+        // (setCurrentWorkspace, persist namespace) are synced later by
+        // WorkspaceRouteLayout when the URL resolves.
         const wsList = await api.listWorkspaces();
-        const lastWsId = localStorage.getItem("multica_workspace_id");
-        useWorkspaceStore.getState().hydrateWorkspace(wsList, lastWsId);
+        qc.setQueryData(workspaceKeys.list(), wsList);
       } catch {
         // Token invalid or expired — user stays on login page
       } finally {
         setBootstrapping(false);
       }
     });
-  }, []);
+  }, [qc]);
 
   // Sync token and start the daemon whenever the user logs in.
   useEffect(() => {
@@ -63,6 +69,38 @@ function AppContent() {
     })();
   }, [user]);
 
+  // When a user who started the session with zero workspaces creates their
+  // first one, restart the daemon so it picks up the new workspace
+  // immediately (otherwise workspaceSyncLoop's next 30s tick would be the
+  // earliest pickup point). Specifically scoped to "started empty" because
+  // account switches (user A logout → user B login) should not trigger a
+  // daemon restart here — daemon-manager already restarts on user change
+  // via syncToken.
+  const { data: workspaces, isFetched: workspaceListFetched } = useQuery({
+    ...workspaceListOptions(),
+    enabled: !!user,
+  });
+  const wsCount = workspaces?.length ?? 0;
+  // null = undecided (pre-login or list hasn't settled yet)
+  // true  = session started with zero workspaces; next transition to >=1 triggers restart
+  // false = session started with >=1 workspace, OR we've already restarted; skip
+  const sessionStartedEmptyRef = useRef<boolean | null>(null);
+  useEffect(() => {
+    if (!user) {
+      sessionStartedEmptyRef.current = null;
+      return;
+    }
+    if (!workspaceListFetched) return;
+    if (sessionStartedEmptyRef.current === null) {
+      sessionStartedEmptyRef.current = wsCount === 0;
+      return;
+    }
+    if (sessionStartedEmptyRef.current && wsCount >= 1) {
+      void window.daemonAPI.restart();
+      sessionStartedEmptyRef.current = false;
+    }
+  }, [user, workspaceListFetched, wsCount]);
+
   if (isLoading || bootstrapping) {
     return (
       <div className="flex h-screen items-center justify-center">

apps/desktop/src/renderer/src/components/desktop-layout.tsx

@@ -1,4 +1,4 @@
-import { useEffect } from "react";
+import { useEffect, useSyncExternalStore } from "react";
 import { ChevronLeft, ChevronRight } from "lucide-react";
 import { cn } from "@multica/ui/lib/utils";
 import { useTabHistory } from "@/hooks/use-tab-history";
@@ -6,17 +6,16 @@ import { useActiveTitleSync } from "@/hooks/use-tab-sync";
 import { useTabStore, resolveRouteIcon } from "@/stores/tab-store";
 import {
   SidebarProvider,
+  SidebarTrigger,
   useSidebar,
 } from "@multica/ui/components/ui/sidebar";
 import { ModalRegistry } from "@multica/views/modals/registry";
-import { AppSidebar, DashboardGuard } from "@multica/views/layout";
+import { AppSidebar } from "@multica/views/layout";
 import { SearchCommand, SearchTrigger } from "@multica/views/search";
 import { ChatFab, ChatWindow } from "@multica/views/chat";
-import { StepWorkspace } from "@multica/views/onboarding";
-import { useWorkspaceStore } from "@multica/core/workspace";
+import { WorkspaceSlugProvider } from "@multica/core/paths";
+import { getCurrentSlug, subscribeToCurrentSlug } from "@multica/core/platform";
 import { DesktopNavigationProvider } from "@/platform/navigation";
-import { MulticaIcon } from "@multica/ui/components/common/multica-icon";
-import { OnboardingGate } from "./onboarding-gate";
 import { TabBar } from "./tab-bar";
 import { TabContent } from "./tab-content";
 
@@ -54,17 +53,28 @@ function SidebarTopBar() {
 }
 
 // The main area's top bar doubles as a window drag region. When the sidebar
-// is collapsed, we pad the left side so tabs don't land under the macOS
-// traffic lights (which live at roughly x=16..68 and always hit-test above HTML).
+// is not occupying main-flow width — either user-collapsed (offcanvas) or
+// auto-hidden in mobile mode (<768px, becomes a sheet drawer) — we pad the
+// left side so tabs don't land under the macOS traffic lights (which live at
+// roughly x=16..68 and always hit-test above HTML), and surface a trigger so
+// the sidebar can be brought back without keyboard shortcut.
 function MainTopBar() {
-  const { state } = useSidebar();
-  const sidebarCollapsed = state === "collapsed";
+  const { state, isMobile } = useSidebar();
+  const sidebarHidden = state === "collapsed" || isMobile;
 
   return (
     <header
-      className={cn("h-12 shrink-0", sidebarCollapsed && "pl-20")}
+      className={cn(
+        "h-12 shrink-0 flex items-center gap-2",
+        sidebarHidden && "pl-20",
+      )}
       style={{ WebkitAppRegion: "drag" } as React.CSSProperties}
     >
+      {sidebarHidden && (
+        <SidebarTrigger
+          style={{ WebkitAppRegion: "no-drag" } as React.CSSProperties}
+        />
+      )}
       <TabBar />
     </header>
   );
@@ -89,45 +99,40 @@ export function DesktopShell() {
   useInternalLinkHandler();
   useActiveTitleSync();
 
-  const workspace = useWorkspaceStore((s) => s.workspace);
+  // Reactive read of current workspace slug from the platform singleton.
+  // On first mount, slug is null until WorkspaceRouteLayout (inside the tab
+  // router) sets it. Once set, the sidebar and other shell-level components
+  // can resolve workspace-scoped paths via useWorkspacePaths().
+  const slug = useSyncExternalStore(subscribeToCurrentSlug, getCurrentSlug, () => null);
 
   return (
     <DesktopNavigationProvider>
-      <OnboardingGate
-        hasWorkspace={!!workspace}
-        onboarding={(onComplete) => (
-          <div className="flex min-h-screen items-center justify-center overflow-auto bg-background px-6 py-12">
-            <StepWorkspace onNext={onComplete} />
-          </div>
-        )}
-      >
-        <DashboardGuard
-          loginPath="/login"
-          loadingFallback={
-            <div className="flex h-screen items-center justify-center">
-              <MulticaIcon className="size-6 animate-pulse" />
-            </div>
-          }
-        >
-          <div className="flex h-screen">
-            <SidebarProvider className="flex-1">
-              <AppSidebar topSlot={<SidebarTopBar />} searchSlot={<SearchTrigger />} />
-              {/* Right side: header + content container */}
-              <div className="flex flex-1 min-w-0 flex-col">
-                <MainTopBar />
-                {/* Content area with inset styling — relative so ChatWindow/ChatFab are constrained here */}
-                <div className="relative flex flex-1 min-h-0 flex-col overflow-hidden mr-2 mb-2 ml-0.5 rounded-xl shadow-sm bg-background">
-                  <TabContent />
-                  <ChatWindow />
-                  <ChatFab />
-                </div>
+      {/* WorkspaceSlugProvider accepts null — components that need slug
+          use useWorkspaceSlug() (nullable) or useRequiredWorkspaceSlug()
+          (throws). TabContent MUST always render so the tab router can
+          mount WorkspaceRouteLayout, which calls setCurrentWorkspace()
+          to populate the slug. The sidebar gates on slug being present
+          to avoid the useRequiredWorkspaceSlug throw. Zero-workspace
+          users are routed to /new-workspace by IndexRedirect. */}
+      <WorkspaceSlugProvider slug={slug}>
+        <div className="flex h-screen">
+          <SidebarProvider className="flex-1">
+            {slug && <AppSidebar topSlot={<SidebarTopBar />} searchSlot={<SearchTrigger />} />}
+            {/* Right side: header + content container */}
+            <div className="flex flex-1 min-w-0 flex-col">
+              <MainTopBar />
+              {/* Content area with inset styling — relative so ChatWindow/ChatFab are constrained here */}
+              <div className="relative flex flex-1 min-h-0 flex-col overflow-hidden mr-2 mb-2 ml-0.5 rounded-xl shadow-sm bg-background">
+                <TabContent />
+                {slug && <ChatWindow />}
+                {slug && <ChatFab />}
               </div>
-            </SidebarProvider>
-          </div>
-          <ModalRegistry />
-          <SearchCommand />
-        </DashboardGuard>
-      </OnboardingGate>
+            </div>
+          </SidebarProvider>
+        </div>
+        {slug && <ModalRegistry />}
+        {slug && <SearchCommand />}
+      </WorkspaceSlugProvider>
     </DesktopNavigationProvider>
   );
 }

apps/desktop/src/renderer/src/components/onboarding-gate.test.tsx

@@ -1,81 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { render, screen, act } from "@testing-library/react";
-import { useState } from "react";
-import { OnboardingGate } from "./onboarding-gate";
-
-describe("OnboardingGate", () => {
-  it("renders children when a workspace exists at mount", () => {
-    render(
-      <OnboardingGate
-        hasWorkspace={true}
-        onboarding={() => <div data-testid="wizard">wizard</div>}
-      >
-        <div data-testid="main">main shell</div>
-      </OnboardingGate>,
-    );
-
-    expect(screen.getByTestId("main")).toBeInTheDocument();
-    expect(screen.queryByTestId("wizard")).not.toBeInTheDocument();
-  });
-
-  it("keeps the wizard mounted even after hasWorkspace flips to true mid-flow", () => {
-    // Controls the hasWorkspace prop from outside so we can simulate
-    // step 0 of the wizard creating a workspace while steps 1-3 still need
-    // to render. The gate should ignore the prop change and hold the wizard.
-    function Harness() {
-      const [hasWorkspace, setHasWorkspace] = useState(false);
-      return (
-        <>
-          <button
-            type="button"
-            data-testid="grant-workspace"
-            onClick={() => setHasWorkspace(true)}
-          >
-            grant
-          </button>
-          <OnboardingGate
-            hasWorkspace={hasWorkspace}
-            onboarding={() => <div data-testid="wizard">wizard</div>}
-          >
-            <div data-testid="main">main shell</div>
-          </OnboardingGate>
-        </>
-      );
-    }
-
-    render(<Harness />);
-    expect(screen.getByTestId("wizard")).toBeInTheDocument();
-
-    act(() => {
-      screen.getByTestId("grant-workspace").click();
-    });
-
-    // Prop change alone does not dismiss the wizard — only onComplete does.
-    expect(screen.getByTestId("wizard")).toBeInTheDocument();
-    expect(screen.queryByTestId("main")).not.toBeInTheDocument();
-  });
-
-  it("transitions to children after the wizard calls onComplete", () => {
-    render(
-      <OnboardingGate
-        hasWorkspace={false}
-        onboarding={(onComplete) => (
-          <button type="button" data-testid="finish" onClick={onComplete}>
-            finish
-          </button>
-        )}
-      >
-        <div data-testid="main">main shell</div>
-      </OnboardingGate>,
-    );
-
-    expect(screen.getByTestId("finish")).toBeInTheDocument();
-
-    act(() => {
-      screen.getByTestId("finish").click();
-    });
-
-    expect(screen.getByTestId("main")).toBeInTheDocument();
-    expect(screen.queryByTestId("finish")).not.toBeInTheDocument();
-  });
-});

apps/desktop/src/renderer/src/components/onboarding-gate.tsx

@@ -1,33 +0,0 @@
-import { useState, type ReactNode } from "react";
-
-/**
- * Renders `onboarding` as a full-screen takeover when the user logs in
- * without a workspace, otherwise renders `children`.
- *
- * The "needs onboarding" decision is frozen at first mount via the lazy
- * useState initializer so the onboarding view controls its own exit: the
- * onboarding component calls the `onComplete` callback when it's ready to
- * hand off to `children`, instead of getting unmounted the moment the
- * workspace store updates.
- *
- * Assumes `hasWorkspace` is definitive at first render: desktop only mounts
- * DesktopShell after AppContent's bootstrapping flag resolves, so the first
- * render of this component reflects the actual server state.
- */
-export function OnboardingGate({
-  hasWorkspace,
-  onboarding,
-  children,
-}: {
-  hasWorkspace: boolean;
-  onboarding: (onComplete: () => void) => ReactNode;
-  children: ReactNode;
-}) {
-  const [initialNeedsOnboarding] = useState(() => !hasWorkspace);
-  const [onboardingDone, setOnboardingDone] = useState(false);
-
-  if (initialNeedsOnboarding && !onboardingDone) {
-    return <>{onboarding(() => setOnboardingDone(true))}</>;
-  }
-  return <>{children}</>;
-}

apps/desktop/src/renderer/src/components/workspace-route-layout.tsx

@@ -0,0 +1,79 @@
+import { useEffect } from "react";
+import { Outlet, useNavigate, useParams } from "react-router-dom";
+import { useQuery } from "@tanstack/react-query";
+import { WorkspaceSlugProvider, paths } from "@multica/core/paths";
+import { workspaceBySlugOptions } from "@multica/core/workspace";
+import { setCurrentWorkspace } from "@multica/core/platform";
+import { useAuthStore } from "@multica/core/auth";
+import { NoAccessPage } from "@multica/views/workspace/no-access-page";
+import { useWorkspaceSeen } from "@multica/views/workspace/use-workspace-seen";
+
+/**
+ * Desktop equivalent of apps/web/app/[workspaceSlug]/layout.tsx.
+ *
+ * Resolves the URL slug → workspace UUID via the React Query list cache
+ * (seeded by AuthInitializer). Children do not render until the workspace
+ * is fully resolved — useWorkspaceId() inside child pages is therefore
+ * guaranteed non-null when called. Two industry-standard identities are
+ * kept distinct: slug (URL / browser) and UUID (API / cache keys).
+ *
+ * If the slug doesn't resolve to any workspace the user has access to,
+ * we render NoAccessPage instead of silently redirecting — users get
+ * explicit feedback for stale bookmarks or revoked access.
+ */
+export function WorkspaceRouteLayout() {
+  const { workspaceSlug } = useParams<{ workspaceSlug: string }>();
+  const navigate = useNavigate();
+  const user = useAuthStore((s) => s.user);
+  const isAuthLoading = useAuthStore((s) => s.isLoading);
+
+  // Workspace routes require auth. If user is unauthenticated (token
+  // expired, logged out from another tab, etc.), bounce to /login.
+  // Without this, the layout renders null and the user sees a blank page
+  // stuck on /{slug}/...
+  useEffect(() => {
+    if (!isAuthLoading && !user) navigate(paths.login(), { replace: true });
+  }, [isAuthLoading, user, navigate]);
+
+  const { data: workspace, isFetched: listFetched } = useQuery({
+    ...workspaceBySlugOptions(workspaceSlug ?? ""),
+    enabled: !!user && !!workspaceSlug,
+  });
+
+  // Feed the URL slug into the platform singleton so the API client's
+  // X-Workspace-Slug header and persist namespace follow the active tab.
+  // setCurrentWorkspace self-dedupes on slug equality — safe to call on
+  // every render (matters on desktop, where N tabs each mount their own
+  // layout). Rehydrate is the singleton's internal side effect.
+  if (workspace && workspaceSlug) {
+    setCurrentWorkspace(workspaceSlug, workspace.id);
+  }
+
+  // Remember whether this slug has resolved before (see hook docs). Gates
+  // the NoAccessPage render below so active workspace removal doesn't
+  // flash "Workspace not available" before the navigate lands.
+  const hasBeenSeen = useWorkspaceSeen(workspaceSlug, !!workspace);
+
+  if (isAuthLoading) return null;
+  if (!workspaceSlug) return null;
+  // Don't render children until workspace is resolved. useWorkspaceId()
+  // throws when the workspace list hasn't populated or the slug is
+  // unknown — gating here is the single point where that invariant is
+  // enforced, so every descendant can call useWorkspaceId() safely.
+  if (!listFetched) return null;
+  if (!workspace) {
+    // Active workspace just removed (delete/leave/realtime eviction) —
+    // navigate is in flight; hold null briefly instead of flashing
+    // NoAccessPage.
+    if (hasBeenSeen) return null;
+    // Genuinely inaccessible slug (stale bookmark, revoked access, or a
+    // link from a former teammate's workspace) → explicit feedback.
+    return <NoAccessPage />;
+  }
+
+  return (
+    <WorkspaceSlugProvider slug={workspaceSlug}>
+      <Outlet />
+    </WorkspaceSlugProvider>
+  );
+}

apps/desktop/src/renderer/src/pages/login.tsx

@@ -4,8 +4,6 @@ import { MulticaIcon } from "@multica/ui/components/common/multica-icon";
 const WEB_URL = import.meta.env.VITE_APP_URL || "http://localhost:3000";
 
 export function DesktopLoginPage() {
-  const lastWorkspaceId = localStorage.getItem("multica_workspace_id");
-
   const handleGoogleLogin = () => {
     // Open web login page in the default browser with platform=desktop flag.
     // The web callback will redirect back via multica:// deep link with the token.
@@ -23,9 +21,9 @@ export function DesktopLoginPage() {
       />
       <LoginPage
         logo={<MulticaIcon bordered size="lg" />}
-        lastWorkspaceId={lastWorkspaceId}
         onSuccess={() => {
-          // Auth store update triggers AppContent re-render → shows DesktopShell
+          // Auth store update triggers AppContent re-render → shows DesktopShell.
+          // Initial workspace navigation happens in routes.tsx via IndexRedirect.
         }}
         onGoogleLogin={handleGoogleLogin}
       />

apps/desktop/src/renderer/src/routes.tsx

@@ -6,6 +6,7 @@ import {
   useMatches,
 } from "react-router-dom";
 import type { RouteObject } from "react-router-dom";
+import { useQuery } from "@tanstack/react-query";
 import { IssueDetailPage } from "./pages/issue-detail-page";
 import { ProjectDetailPage } from "./pages/project-detail-page";
 import { AutopilotDetailPage } from "./pages/autopilot-detail-page";
@@ -19,11 +20,14 @@ import { DaemonRuntimeCard } from "./components/daemon-runtime-card";
 import { AgentsPage } from "@multica/views/agents";
 import { InboxPage } from "@multica/views/inbox";
 import { SettingsPage } from "@multica/views/settings";
-import { OnboardingWizard } from "@multica/views/onboarding";
+import { NewWorkspacePage } from "@multica/views/workspace/new-workspace-page";
 import { InvitePage } from "@multica/views/invite";
 import { useNavigation } from "@multica/views/navigation";
+import { paths } from "@multica/core/paths";
+import { workspaceListOptions } from "@multica/core/workspace/queries";
 import { Server } from "lucide-react";
 import { DaemonSettingsTab } from "./components/daemon-settings-tab";
+import { WorkspaceRouteLayout } from "./components/workspace-route-layout";
 
 /**
  * Sets document.title from the deepest matched route's handle.title.
@@ -55,9 +59,40 @@ function PageShell() {
   );
 }
 
-function OnboardingRoute() {
+function NewWorkspaceRoute() {
   const nav = useNavigation();
-  return <OnboardingWizard onComplete={() => nav.push("/issues")} />;
+  return (
+    <NewWorkspacePage
+      onSuccess={(ws) => nav.push(paths.workspace(ws.slug).issues())}
+    />
+  );
+}
+
+/**
+ * Root index route: resolves the URL-less `/` path to a concrete destination.
+ *
+ * Runs both on first login (App.tsx seeded the cache) and on app reopen
+ * (AuthInitializer seeded the cache). Reading from React Query avoids
+ * duplicate fetches across tabs — each tab's memory router hits this
+ * component independently but the query is deduped.
+ *
+ * Sends first-time users without any workspace to /new-workspace,
+ * everyone else to their first workspace's issues page. Persisted tab
+ * paths that already carry a workspace slug bypass this component
+ * entirely.
+ */
+function IndexRedirect() {
+  const { data: wsList, isFetched } = useQuery(workspaceListOptions());
+
+  // Wait for the query to settle so we don't redirect to /new-workspace
+  // on the initial render before the seeded/fetched data arrives.
+  if (!isFetched) return null;
+
+  const firstWorkspace = wsList?.[0];
+  if (firstWorkspace) {
+    return <Navigate to={paths.workspace(firstWorkspace.slug).issues()} replace />;
+  }
+  return <Navigate to={paths.newWorkspace()} replace />;
 }
 
 function InviteRoute() {
@@ -67,55 +102,28 @@ function InviteRoute() {
   return <InvitePage invitationId={id} />;
 }
 
-/** Route definitions shared by all tabs (no layout wrapper). */
+/**
+ * Route definitions shared by all tabs.
+ *
+ * Structure mirrors the web app's [workspaceSlug]/... layout: all dashboard
+ * pages live under /:workspaceSlug, with WorkspaceRouteLayout resolving the
+ * slug to a workspace and syncing side-effects (api client, persist namespace,
+ * Zustand mirror). Global (pre-workspace) routes — new-workspace and invite —
+ * sit at the top level alongside the workspace wrapper.
+ */
 export const appRoutes: RouteObject[] = [
   {
     element: <PageShell />,
     children: [
-      { index: true, element: <Navigate to="/issues" replace /> },
-      { path: "issues", element: <IssuesPage />, handle: { title: "Issues" } },
+      // Top-level index: no slug yet. `IndexRedirect` reads the workspace
+      // list from React Query cache (seeded by AuthInitializer on reopen
+      // or App.tsx on deep-link login) and bounces to the first
+      // workspace's issues page — or /new-workspace if the user has none.
+      { index: true, element: <IndexRedirect /> },
       {
-        path: "issues/:id",
-        element: <IssueDetailPage />,
-        handle: { title: "Issue" },
-      },
-      {
-        path: "projects",
-        element: <ProjectsPage />,
-        handle: { title: "Projects" },
-      },
-      {
-        path: "projects/:id",
-        element: <ProjectDetailPage />,
-        handle: { title: "Project" },
-      },
-      {
-        path: "autopilots",
-        element: <AutopilotsPage />,
-        handle: { title: "Autopilot" },
-      },
-      {
-        path: "autopilots/:id",
-        element: <AutopilotDetailPage />,
-        handle: { title: "Autopilot" },
-      },
-      {
-        path: "my-issues",
-        element: <MyIssuesPage />,
-        handle: { title: "My Issues" },
-      },
-      {
-        path: "runtimes",
-        element: <RuntimesPage topSlot={<DaemonRuntimeCard />} />,
-        handle: { title: "Runtimes" },
-      },
-      { path: "skills", element: <SkillsPage />, handle: { title: "Skills" } },
-      { path: "agents", element: <AgentsPage />, handle: { title: "Agents" } },
-      { path: "inbox", element: <InboxPage />, handle: { title: "Inbox" } },
-      {
-        path: "onboarding",
-        element: <OnboardingRoute />,
-        handle: { title: "Get Started" },
+        path: "new-workspace",
+        element: <NewWorkspaceRoute />,
+        handle: { title: "Create Workspace" },
       },
       {
         path: "invite/:id",
@@ -123,20 +131,66 @@ export const appRoutes: RouteObject[] = [
         handle: { title: "Accept Invite" },
       },
       {
-        path: "settings",
-        element: (
-          <SettingsPage
-            extraAccountTabs={[
-              {
-                value: "daemon",
-                label: "Daemon",
-                icon: Server,
-                content: <DaemonSettingsTab />,
-              },
-            ]}
-          />
-        ),
-        handle: { title: "Settings" },
+        path: ":workspaceSlug",
+        element: <WorkspaceRouteLayout />,
+        children: [
+          { index: true, element: <Navigate to="issues" replace /> },
+          { path: "issues", element: <IssuesPage />, handle: { title: "Issues" } },
+          {
+            path: "issues/:id",
+            element: <IssueDetailPage />,
+            handle: { title: "Issue" },
+          },
+          {
+            path: "projects",
+            element: <ProjectsPage />,
+            handle: { title: "Projects" },
+          },
+          {
+            path: "projects/:id",
+            element: <ProjectDetailPage />,
+            handle: { title: "Project" },
+          },
+          {
+            path: "autopilots",
+            element: <AutopilotsPage />,
+            handle: { title: "Autopilot" },
+          },
+          {
+            path: "autopilots/:id",
+            element: <AutopilotDetailPage />,
+            handle: { title: "Autopilot" },
+          },
+          {
+            path: "my-issues",
+            element: <MyIssuesPage />,
+            handle: { title: "My Issues" },
+          },
+          {
+            path: "runtimes",
+            element: <RuntimesPage topSlot={<DaemonRuntimeCard />} />,
+            handle: { title: "Runtimes" },
+          },
+          { path: "skills", element: <SkillsPage />, handle: { title: "Skills" } },
+          { path: "agents", element: <AgentsPage />, handle: { title: "Agents" } },
+          { path: "inbox", element: <InboxPage />, handle: { title: "Inbox" } },
+          {
+            path: "settings",
+            element: (
+              <SettingsPage
+                extraAccountTabs={[
+                  {
+                    value: "daemon",
+                    label: "Daemon",
+                    icon: Server,
+                    content: <DaemonSettingsTab />,
+                  },
+                ]}
+              />
+            ),
+            handle: { title: "Settings" },
+          },
+        ],
       },
     ],
   },

apps/desktop/src/renderer/src/stores/tab-store.ts

@@ -3,6 +3,7 @@ import { createJSONStorage, persist } from "zustand/middleware";
 import { arrayMove } from "@dnd-kit/sortable";
 import { createPersistStorage, defaultStorage } from "@multica/core/platform";
 import { createSafeId } from "@multica/core/utils";
+import { isGlobalPath } from "@multica/core/paths";
 import type { DataRouter } from "react-router-dom";
 import { createTabRouter } from "../routes";
 
@@ -45,29 +46,50 @@ interface TabStore {
 // ---------------------------------------------------------------------------
 
 const ROUTE_ICONS: Record<string, string> = {
-  "/inbox": "Inbox",
-  "/my-issues": "CircleUser",
-  "/issues": "ListTodo",
-  "/projects": "FolderKanban",
-  "/agents": "Bot",
-  "/runtimes": "Monitor",
-  "/skills": "BookOpenText",
-  "/settings": "Settings",
+  inbox: "Inbox",
+  "my-issues": "CircleUser",
+  issues: "ListTodo",
+  projects: "FolderKanban",
+  autopilots: "ListTodo",
+  agents: "Bot",
+  runtimes: "Monitor",
+  skills: "BookOpenText",
+  settings: "Settings",
 };
 
-/** Resolve a route icon. Title is NOT determined here — it comes from document.title. */
+/**
+ * Resolve a route icon from a pathname. Title is NOT determined here — it
+ * comes from document.title.
+ *
+ * Path shape after the workspace URL refactor:
+ *  - workspace-scoped: `/{workspaceSlug}/{route}/...` → use segment index 1
+ *  - global (new-workspace/invite/auth/login): `/{route}/...` → use segment index 0
+ *
+ * `isGlobalPath` is the single source of truth for which prefixes are global.
+ */
 export function resolveRouteIcon(pathname: string): string {
-  return ROUTE_ICONS[pathname]
-    ?? (pathname.startsWith("/issues/") ? "ListTodo" : undefined)
-    ?? (pathname.startsWith("/projects/") ? "FolderKanban" : undefined)
-    ?? "ListTodo";
+  const segments = pathname.split("/").filter(Boolean);
+  const routeSegment = isGlobalPath(pathname)
+    ? (segments[0] ?? "")
+    : (segments[1] ?? "");
+  return ROUTE_ICONS[routeSegment] ?? "ListTodo";
 }
 
 // ---------------------------------------------------------------------------
 // Store
 // ---------------------------------------------------------------------------
 
-const DEFAULT_PATH = "/issues";
+/**
+ * Sentinel path for new tabs with no explicit destination. The tab store is
+ * workspace-implicit — it doesn't know which workspace is active, so it can't
+ * build a `/:slug/issues` path itself. Instead we hand off to the router: `/`
+ * matches the top-level index route, which redirects to the workspace default
+ * (slug-aware redirect lives in routes.tsx / App.tsx).
+ *
+ * `title` and `icon` on the placeholder tab get overwritten by
+ * useTabRouterSync + useActiveTitleSync once the redirect resolves.
+ */
+const DEFAULT_PATH = "/";
 
 function createId(): string {
   return createSafeId();
@@ -177,12 +199,28 @@ export const useTabStore = create<TabStore>()(
           | undefined;
         if (!persisted?.tabs?.length) return currentState;
 
-        const tabs: Tab[] = persisted.tabs.map((tab) => ({
-          ...tab,
-          router: createTabRouter(tab.path),
-          historyIndex: 0,
-          historyLength: 1,
-        }));
+        const tabs: Tab[] = persisted.tabs.map((tab) => {
+          // Migration: pre-refactor tab paths like "/issues/abc" lack a
+          // workspace slug prefix. These would 404 in the new router.
+          // Reset to "/" so IndexRedirect picks the right workspace.
+          let path = tab.path;
+          if (path !== "/" && !isGlobalPath(path)) {
+            const segments = path.split("/").filter(Boolean);
+            const firstSegment = segments[0] ?? "";
+            // If the first segment IS a known route name (e.g. "issues",
+            // "projects"), it's an old-format path missing the slug prefix.
+            if (ROUTE_ICONS[firstSegment]) {
+              path = "/";
+            }
+          }
+          return {
+            ...tab,
+            path,
+            router: createTabRouter(path),
+            historyIndex: 0,
+            historyLength: 1,
+          };
+        });
 
         // Validate activeTabId — fall back to first tab if stale
         const activeTabId = tabs.some((t) => t.id === persisted.activeTabId)

apps/docs/content/docs/cli/installation.mdx

@@ -78,7 +78,7 @@ multica daemon status
 
 Confirm:
 1. Status is `running`
-2. At least one agent is listed (e.g. `claude`, `codex`, `gemini`, `opencode`, `openclaw`, or `hermes`)
+2. At least one agent is listed (e.g. `claude`, `codex`, `gemini`, `opencode`, `openclaw`, `hermes`, or `pi`)
 3. At least one workspace is being watched
 
 If the agents list is empty, install at least one supported AI agent CLI:

apps/docs/content/docs/getting-started/cloud-quickstart.mdx

@@ -45,7 +45,7 @@ Then configure, authenticate, and start the daemon:
 multica setup
 ```
 
-The daemon auto-detects available agent CLIs (`claude`, `codex`, `gemini`, `openclaw`, `opencode`, `hermes`) on your PATH. When an agent is assigned a task, the daemon creates an isolated environment, runs the agent, and reports results back.
+The daemon auto-detects available agent CLIs (`claude`, `codex`, `gemini`, `openclaw`, `opencode`, `hermes`, `pi`) on your PATH. When an agent is assigned a task, the daemon creates an isolated environment, runs the agent, and reports results back.
 
 ## 3. Verify your runtime
 

apps/docs/content/docs/guides/quickstart.mdx

@@ -11,7 +11,7 @@ Once you have the CLI installed (or signed up for [Multica Cloud](https://multic
 multica setup           # Configure, authenticate, and start the daemon
 ```
 
-This configures the CLI, opens your browser for login, discovers your workspaces, and starts the agent daemon in the background. It auto-detects agent CLIs (`claude`, `codex`, `gemini`, `openclaw`, `opencode`, `hermes`) available on your PATH.
+This configures the CLI, opens your browser for login, discovers your workspaces, and starts the agent daemon in the background. It auto-detects agent CLIs (`claude`, `codex`, `gemini`, `openclaw`, `opencode`, `hermes`, `pi`) available on your PATH.
 
 ## 2. Verify your runtime
 

apps/web/app/(auth)/invite/[id]/page.tsx

@@ -3,6 +3,7 @@
 import { useEffect } from "react";
 import { useRouter, useParams } from "next/navigation";
 import { useAuthStore } from "@multica/core/auth";
+import { paths } from "@multica/core/paths";
 import { InvitePage } from "@multica/views/invite";
 
 export default function InviteAcceptPage() {
@@ -14,7 +15,9 @@ export default function InviteAcceptPage() {
   // Redirect to login if not authenticated, with a redirect back to this page.
   useEffect(() => {
     if (!isLoading && !user) {
-      router.replace(`/login?next=/invite/${params.id}`);
+      router.replace(
+        `${paths.login()}?next=${encodeURIComponent(paths.invite(params.id))}`,
+      );
     }
   }, [isLoading, user, router, params.id]);
 

apps/web/app/(auth)/login/page.test.tsx

@@ -11,13 +11,10 @@ function createWrapper() {
   );
 }
 
-const { mockSendCode, mockVerifyCode, mockHydrateWorkspace } = vi.hoisted(
-  () => ({
-    mockSendCode: vi.fn(),
-    mockVerifyCode: vi.fn(),
-    mockHydrateWorkspace: vi.fn(),
-  }),
-);
+const { mockSendCode, mockVerifyCode } = vi.hoisted(() => ({
+  mockSendCode: vi.fn(),
+  mockVerifyCode: vi.fn(),
+}));
 
 // Mock next/navigation
 vi.mock("next/navigation", () => ({
@@ -47,16 +44,6 @@ vi.mock("@/features/auth/auth-cookie", () => ({
   setLoggedInCookie: vi.fn(),
 }));
 
-// Mock workspace store — shared LoginPage uses getState().hydrateWorkspace
-vi.mock("@multica/core/workspace", () => {
-  const wsState = { hydrateWorkspace: mockHydrateWorkspace };
-  const useWorkspaceStore = Object.assign(
-    (selector: (s: typeof wsState) => unknown) => selector(wsState),
-    { getState: () => wsState },
-  );
-  return { useWorkspaceStore };
-});
-
 // Mock api
 vi.mock("@multica/core/api", () => ({
   api: {

apps/web/app/(auth)/login/page.tsx

@@ -2,8 +2,11 @@
 
 import { Suspense, useEffect } from "react";
 import { useSearchParams, useRouter } from "next/navigation";
+import { useQueryClient } from "@tanstack/react-query";
 import { useAuthStore } from "@multica/core/auth";
-import { useWorkspaceStore } from "@multica/core/workspace";
+import { workspaceKeys } from "@multica/core/workspace/queries";
+import { paths } from "@multica/core/paths";
+import type { Workspace } from "@multica/core/types";
 import { setLoggedInCookie } from "@/features/auth/auth-cookie";
 import { LoginPage, validateCliCallback } from "@multica/views/auth";
 
@@ -11,6 +14,7 @@ const googleClientId = process.env.NEXT_PUBLIC_GOOGLE_CLIENT_ID;
 
 function LoginPageContent() {
   const router = useRouter();
+  const qc = useQueryClient();
   const user = useAuthStore((s) => s.user);
   const isLoading = useAuthStore((s) => s.isLoading);
   const searchParams = useSearchParams();
@@ -18,30 +22,47 @@ function LoginPageContent() {
   const cliCallbackRaw = searchParams.get("cli_callback");
   const cliState = searchParams.get("cli_state") || "";
   const platform = searchParams.get("platform");
-  const nextUrl = searchParams.get("next") || "/issues";
+  // `next` carries a protected URL the user was originally headed to
+  // (e.g. /invite/{id}). With URL-driven workspaces there is no legacy
+  // "/issues" default — if `next` is absent we decide after login based on
+  // the user's workspace list.
+  const nextUrl = searchParams.get("next");
 
-  // Already authenticated — redirect to dashboard (skip if CLI callback)
+  // Already authenticated — honor ?next= or fall back to first workspace
+  // (or /new-workspace if the user has none). Skip this entire path when
+  // the user arrived to authorize the CLI.
   useEffect(() => {
-    if (!isLoading && user && !cliCallbackRaw) {
+    if (isLoading || !user || cliCallbackRaw) return;
+    if (nextUrl) {
       router.replace(nextUrl);
+      return;
     }
-  }, [isLoading, user, router, nextUrl, cliCallbackRaw]);
-
-  const lastWorkspaceId =
-    typeof window !== "undefined"
-      ? localStorage.getItem("multica_workspace_id")
-      : null;
+    const list = qc.getQueryData<Workspace[]>(workspaceKeys.list()) ?? [];
+    const [first] = list;
+    router.replace(
+      first ? paths.workspace(first.slug).issues() : paths.newWorkspace(),
+    );
+  }, [isLoading, user, router, nextUrl, cliCallbackRaw, qc]);
 
   const handleSuccess = () => {
-    const ws = useWorkspaceStore.getState().workspace;
-    router.push(ws ? nextUrl : "/onboarding");
+    if (nextUrl) {
+      router.push(nextUrl);
+      return;
+    }
+    // The LoginPage view populates the workspace list cache before calling
+    // onSuccess, so it's safe to read here.
+    const list = qc.getQueryData<Workspace[]>(workspaceKeys.list()) ?? [];
+    const [first] = list;
+    router.push(
+      first ? paths.workspace(first.slug).issues() : paths.newWorkspace(),
+    );
   };
 
   // Build Google OAuth state: encode platform + next URL so the callback
   // can redirect to the right place after login.
   const googleState = [
     platform === "desktop" ? "platform:desktop" : "",
-    nextUrl !== "/issues" ? `next:${nextUrl}` : "",
+    nextUrl ? `next:${nextUrl}` : "",
   ]
     .filter(Boolean)
     .join(",") || undefined;
@@ -63,7 +84,6 @@ function LoginPageContent() {
           ? { url: cliCallbackRaw, state: cliState }
           : undefined
       }
-      lastWorkspaceId={lastWorkspaceId}
       onTokenObtained={setLoggedInCookie}
     />
   );

apps/web/app/(auth)/new-workspace/page.tsx

@@ -1,23 +1,25 @@
 "use client";
 
-import { useEffect } from "react";
 import { useRouter } from "next/navigation";
+import { useEffect } from "react";
 import { useAuthStore } from "@multica/core/auth";
-import { OnboardingWizard } from "@multica/views/onboarding";
+import { paths } from "@multica/core/paths";
+import { NewWorkspacePage } from "@multica/views/workspace/new-workspace-page";
 
-export default function OnboardingPage() {
+export default function Page() {
   const router = useRouter();
   const user = useAuthStore((s) => s.user);
   const isLoading = useAuthStore((s) => s.isLoading);
 
-  // Redirect to login if not authenticated
   useEffect(() => {
-    if (!isLoading && !user) router.replace("/login");
+    if (!isLoading && !user) router.replace(paths.login());
   }, [isLoading, user, router]);
 
   if (isLoading || !user) return null;
 
   return (
-    <OnboardingWizard onComplete={() => router.push("/issues")} />
+    <NewWorkspacePage
+      onSuccess={(ws) => router.push(paths.workspace(ws.slug).issues())}
+    />
   );
 }

apps/web/app/(landing)/page.tsx

@@ -1,5 +1,6 @@
 import type { Metadata } from "next";
 import { MulticaLanding } from "@/features/landing/components/multica-landing";
+import { RedirectIfAuthenticated } from "@/features/landing/components/redirect-if-authenticated";
 
 export const metadata: Metadata = {
   title: {
@@ -19,5 +20,10 @@ export const metadata: Metadata = {
 };
 
 export default function LandingPage() {
-  return <MulticaLanding />;
+  return (
+    <>
+      <RedirectIfAuthenticated />
+      <MulticaLanding />
+    </>
+  );
 }

apps/web/app/[workspaceSlug]/(dashboard)/layout.tsx

@@ -11,8 +11,6 @@ export default function Layout({ children }: { children: React.ReactNode }) {
       loadingIndicator={<MulticaIcon className="size-6" />}
       searchSlot={<SearchTrigger />}
       extra={<><SearchCommand /><ChatWindow /><ChatFab /></>}
-      onboardingPath="/onboarding"
-      loginPath="/login"
     >
       {children}
     </DashboardLayout>

apps/web/app/[workspaceSlug]/layout.tsx

@@ -0,0 +1,84 @@
+"use client";
+
+import { use, useEffect } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { useRouter } from "next/navigation";
+import { WorkspaceSlugProvider, paths } from "@multica/core/paths";
+import { workspaceBySlugOptions } from "@multica/core/workspace";
+import { setCurrentWorkspace } from "@multica/core/platform";
+import { useAuthStore } from "@multica/core/auth";
+import { NoAccessPage } from "@multica/views/workspace/no-access-page";
+import { useWorkspaceSeen } from "@multica/views/workspace/use-workspace-seen";
+
+export default function WorkspaceLayout({
+  children,
+  params,
+}: {
+  children: React.ReactNode;
+  params: Promise<{ workspaceSlug: string }>;
+}) {
+  const { workspaceSlug } = use(params);
+  const user = useAuthStore((s) => s.user);
+  const isAuthLoading = useAuthStore((s) => s.isLoading);
+  const router = useRouter();
+
+  // Workspace routes require auth. If user is unauthenticated (initial visit
+  // without a session, token expired, another tab logged out, etc.), bounce
+  // to /login. Without this, the layout renders null and the user sees a
+  // blank page stuck on /{slug}/...
+  useEffect(() => {
+    if (!isAuthLoading && !user) router.replace(paths.login());
+  }, [isAuthLoading, user, router]);
+
+  // Resolve workspace by slug from the React Query list cache.
+  // Enabled only when user is authenticated — otherwise the list query isn't seeded.
+  const { data: workspace, isFetched: listFetched } = useQuery({
+    ...workspaceBySlugOptions(workspaceSlug),
+    enabled: !!user,
+  });
+
+  // Render-phase sync: feed the URL slug into the platform singleton so
+  // the first child query's X-Workspace-Slug header is already correct.
+  // setCurrentWorkspace self-dedupes + runs rehydrate as a side effect;
+  // safe to call on every render.
+  if (workspace) {
+    setCurrentWorkspace(workspaceSlug, workspace.id);
+  }
+
+  // Cookie write (last_workspace_slug) — proxy reads it on next page load
+  // to redirect unauthenticated-URL hits to the user's last workspace.
+  useEffect(() => {
+    if (!workspace || typeof document === "undefined") return;
+    const oneYear = 60 * 60 * 24 * 365;
+    const secure = location.protocol === "https:" ? "; Secure" : "";
+    document.cookie = `last_workspace_slug=${encodeURIComponent(workspaceSlug)}; path=/; max-age=${oneYear}; SameSite=Lax${secure}`;
+  }, [workspace, workspaceSlug]);
+
+  // Remember whether this slug has resolved before. Used below to avoid
+  // flashing NoAccessPage during active workspace removal (delete, leave,
+  // or realtime eviction) — in those cases the caller is navigating away
+  // and we just need to hold null briefly.
+  const hasBeenSeen = useWorkspaceSeen(workspaceSlug, !!workspace);
+
+  if (isAuthLoading) return null;
+  // Don't render children until workspace is resolved. useWorkspaceId()
+  // throws when the list hasn't populated or the slug is unknown — gating
+  // here makes that invariant hold for every descendant.
+  if (!listFetched) return null;
+  if (!workspace) {
+    // If we've resolved this slug before in this session, it was just
+    // removed from our list (deleted/left/evicted). A navigate is almost
+    // certainly in flight — render null to avoid a NoAccessPage flash.
+    if (hasBeenSeen) return null;
+    // Otherwise: the URL points at a workspace the user never had access
+    // to. Show explicit feedback instead of silently redirecting. Doesn't
+    // distinguish 404 vs 403 to avoid letting attackers enumerate slugs.
+    return <NoAccessPage />;
+  }
+
+  return (
+    <WorkspaceSlugProvider slug={workspaceSlug}>
+      {children}
+    </WorkspaceSlugProvider>
+  );
+}

apps/web/app/auth/callback/page.tsx

@@ -4,8 +4,8 @@ import { Suspense, useEffect, useState } from "react";
 import { useSearchParams, useRouter } from "next/navigation";
 import { useQueryClient } from "@tanstack/react-query";
 import { useAuthStore } from "@multica/core/auth";
-import { useWorkspaceStore } from "@multica/core/workspace";
 import { workspaceKeys } from "@multica/core/workspace/queries";
+import { paths } from "@multica/core/paths";
 import { api } from "@multica/core/api";
 import {
   Card,
@@ -22,7 +22,6 @@ function CallbackContent() {
   const searchParams = useSearchParams();
   const qc = useQueryClient();
   const loginWithGoogle = useAuthStore((s) => s.loginWithGoogle);
-  const hydrateWorkspace = useWorkspaceStore((s) => s.hydrateWorkspace);
   const [error, setError] = useState("");
   const [desktopToken, setDesktopToken] = useState<string | null>(null);
 
@@ -64,17 +63,21 @@ function CallbackContent() {
         .then(async () => {
           const wsList = await api.listWorkspaces();
           qc.setQueryData(workspaceKeys.list(), wsList);
-          const lastWsId = localStorage.getItem("multica_workspace_id");
-          const ws = await hydrateWorkspace(wsList, lastWsId);
-          // Honor the ?next= redirect if present (e.g. /invite/{id})
-          const defaultDest = ws ? "/issues" : "/onboarding";
+          // URL is now the source of truth for the current workspace — the
+          // [workspaceSlug]/layout syncs stores + cookie once we navigate.
+          // Honor ?next= first (e.g. came from /invite/{id}), otherwise land
+          // in the first workspace's issues, or /new-workspace for zero-workspace users.
+          const [first] = wsList;
+          const defaultDest = first
+            ? paths.workspace(first.slug).issues()
+            : paths.newWorkspace();
           router.push(nextUrl || defaultDest);
         })
         .catch((err) => {
           setError(err instanceof Error ? err.message : "Login failed");
         });
     }
-  }, [searchParams, loginWithGoogle, hydrateWorkspace, router, qc]);
+  }, [searchParams, loginWithGoogle, router, qc]);
 
   if (desktopToken) {
     return (
@@ -111,7 +114,7 @@ function CallbackContent() {
             <CardDescription>{error}</CardDescription>
           </CardHeader>
           <CardContent className="flex justify-center">
-            <a href="/login" className="text-primary underline-offset-4 hover:underline">
+            <a href={paths.login()} className="text-primary underline-offset-4 hover:underline">
               Back to login
             </a>
           </CardContent>

apps/web/features/landing/components/how-it-works-section.tsx

@@ -41,7 +41,7 @@ export function HowItWorksSection() {
         </div>
 
         <div className="mt-14 flex flex-wrap items-center gap-4">
-          <Link href={user ? "/issues" : "/login"} className={heroButtonClassName("solid")}>
+          <Link href={user ? "/" : "/login"} className={heroButtonClassName("solid")}>
             {user ? t.header.dashboard : t.howItWorks.cta}
           </Link>
           <Link

apps/web/features/landing/components/landing-footer.tsx

@@ -48,7 +48,7 @@ export function LandingFooter() {
             </div>
             <div className="mt-6">
               <Link
-                href={user ? "/issues" : "/login"}
+                href={user ? "/" : "/login"}
                 className="inline-flex items-center justify-center rounded-[11px] bg-white px-5 py-2.5 text-[13px] font-semibold text-[#0a0d12] transition-colors hover:bg-white/88"
               >
                 {user ? t.header.dashboard : t.footer.cta}

apps/web/features/landing/components/landing-header.tsx

@@ -54,7 +54,7 @@ export function LandingHeader({
             {t.header.github}
           </Link>
           <Link
-            href={user ? "/issues" : "/login"}
+            href={user ? "/" : "/login"}
             className={headerButtonClassName("solid", variant)}
           >
             {user ? t.header.dashboard : t.header.login}

apps/web/features/landing/components/landing-hero.tsx

@@ -41,9 +41,31 @@ export function LandingHero() {
             </p>
 
             <div className="mt-8 flex flex-wrap items-center justify-center gap-3">
-              <Link href={user ? "/issues" : "/login"} className={heroButtonClassName("solid")}>
+              <Link href={user ? "/" : "/login"} className={heroButtonClassName("solid")}>
                 {user ? t.header.dashboard : t.hero.cta}
               </Link>
+              <Link
+                href="https://github.com/multica-ai/multica/releases/latest"
+                target="_blank"
+                rel="noreferrer"
+                className={heroButtonClassName("ghost")}
+              >
+                <svg
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  stroke="currentColor"
+                  strokeWidth="2"
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  className="size-4"
+                  aria-hidden="true"
+                >
+                  <rect x="2" y="3" width="20" height="14" rx="2" ry="2" />
+                  <line x1="8" y1="21" x2="16" y2="21" />
+                  <line x1="12" y1="17" x2="12" y2="21" />
+                </svg>
+                {t.hero.downloadDesktop}
+              </Link>
               <Link
                 href={githubUrl}
                 target="_blank"

apps/web/features/landing/components/redirect-if-authenticated.tsx

@@ -0,0 +1,45 @@
+"use client";
+
+import { useEffect } from "react";
+import { useRouter } from "next/navigation";
+import { useQuery } from "@tanstack/react-query";
+import { useAuthStore } from "@multica/core/auth";
+import { workspaceListOptions } from "@multica/core/workspace";
+import { paths } from "@multica/core/paths";
+
+/**
+ * Client-side fallback redirect for authenticated visitors on the landing page.
+ *
+ * The primary path for logged-in users hitting `/` is a server-side redirect
+ * in the Next.js proxy/middleware, driven by the `last_workspace_slug` cookie.
+ * That cookie is set by the workspace layout on every visit. But on *first
+ * login* — before the user has ever visited a workspace — the cookie is
+ * absent, so the proxy falls through to the landing page. This component
+ * covers that gap: once auth is resolved and the workspace list has loaded,
+ * push the user into their workspace (or /new-workspace if they have none).
+ *
+ * Renders nothing. Uses `router.replace` so the landing page never enters
+ * browser history for authenticated users.
+ */
+export function RedirectIfAuthenticated() {
+  const router = useRouter();
+  const user = useAuthStore((s) => s.user);
+  const isLoading = useAuthStore((s) => s.isLoading);
+
+  const { data: list } = useQuery({
+    ...workspaceListOptions(),
+    enabled: !!user,
+  });
+
+  useEffect(() => {
+    if (isLoading || !user || !list) return;
+    const [first] = list;
+    if (!first) {
+      router.replace(paths.newWorkspace());
+      return;
+    }
+    router.replace(paths.workspace(first.slug).issues());
+  }, [isLoading, user, list, router]);
+
+  return null;
+}

apps/web/features/landing/i18n/en.ts

@@ -14,6 +14,7 @@ export const en: LandingDict = {
     subheading:
       "Multica is an open-source platform that turns coding agents into real teammates. Assign tasks, track progress, compound skills \u2014 manage your human + agent workforce in one place.",
     cta: "Start free trial",
+    downloadDesktop: "Download Desktop",
     worksWith: "Works with",
     imageAlt: "Multica board view \u2014 issues managed by humans and agents",
   },
@@ -223,6 +224,7 @@ export const en: LandingDict = {
           { label: "Features", href: "#features" },
           { label: "How it Works", href: "#how-it-works" },
           { label: "Changelog", href: "/changelog" },
+          { label: "Desktop", href: "https://github.com/multica-ai/multica/releases/latest" },
         ],
       },
       resources: {

apps/web/features/landing/i18n/types.ts

@@ -26,6 +26,7 @@ export type LandingDict = {
     headlineLine2: string;
     subheading: string;
     cta: string;
+    downloadDesktop: string;
     worksWith: string;
     imageAlt: string;
   };

apps/web/features/landing/i18n/zh.ts

@@ -13,8 +13,9 @@ export const zh: LandingDict = {
     headlineLine2: "\u4e0d\u662f\u4eba\u7c7b\u3002",
     subheading:
       "Multica \u662f\u4e00\u4e2a\u5f00\u6e90\u5e73\u53f0\uff0c\u5c06\u7f16\u7801 Agent \u53d8\u6210\u771f\u6b63\u7684\u961f\u53cb\u3002\u5206\u914d\u4efb\u52a1\u3001\u8ddf\u8e2a\u8fdb\u5ea6\u3001\u79ef\u7d2f\u6280\u80fd\u2014\u2014\u5728\u4e00\u4e2a\u5730\u65b9\u7ba1\u7406\u4f60\u7684\u4eba\u7c7b + Agent \u56e2\u961f\u3002",
-    cta: "\u514d\u8d39\u5f00\u59cb",
-    worksWith: "\u652f\u6301",
+    cta: "免费开始",
+    downloadDesktop: "下载桌面端",
+    worksWith: "支持",
     imageAlt: "Multica \u770b\u677f\u89c6\u56fe\u2014\u2014\u4eba\u7c7b\u548c Agent \u534f\u540c\u7ba1\u7406\u4efb\u52a1",
   },
 
@@ -222,7 +223,8 @@ export const zh: LandingDict = {
         links: [
           { label: "\u529f\u80fd\u7279\u6027", href: "#features" },
           { label: "\u5982\u4f55\u5de5\u4f5c", href: "#how-it-works" },
-          { label: "\u66f4\u65b0\u65e5\u5fd7", href: "/changelog" },
+          { label: "更新日志", href: "/changelog" },
+          { label: "桌面端", href: "https://github.com/multica-ai/multica/releases/latest" },
         ],
       },
       resources: {

apps/web/proxy.ts

@@ -1,10 +1,81 @@
-import { NextResponse } from "next/server";
-import type { NextRequest } from "next/server";
+import { NextResponse, type NextRequest } from "next/server";
+
+// Old workspace-scoped route segments that existed before the URL refactor
+// (pre-#1131). Any URL with these as the FIRST segment is a legacy URL that
+// needs to be rewritten to /{slug}/{route}/... so old bookmarks, deep links,
+// and post-revert-and-reapply users don't hit 404.
+const LEGACY_ROUTE_SEGMENTS = new Set([
+  "issues",
+  "projects",
+  "agents",
+  "inbox",
+  "my-issues",
+  "autopilots",
+  "runtimes",
+  "skills",
+  "settings",
+]);
+
+// Next.js 16 renamed `middleware` → `proxy`. The runtime API is identical.
+export function proxy(req: NextRequest) {
+  const { pathname } = req.nextUrl;
+  const hasSession = req.cookies.has("multica_logged_in");
+  const lastSlug = req.cookies.get("last_workspace_slug")?.value;
+
+  // --- Legacy URL redirect: /issues/... → /{slug}/issues/... ---
+  // Old bookmarks and clients that hit us before the slug migration would
+  // otherwise 404 since the route moved under [workspaceSlug].
+  const firstSegment = pathname.split("/")[1] ?? "";
+  if (LEGACY_ROUTE_SEGMENTS.has(firstSegment)) {
+    const url = req.nextUrl.clone();
+
+    if (!hasSession) {
+      url.pathname = "/login";
+      return NextResponse.redirect(url);
+    }
+
+    if (lastSlug) {
+      // Preserve deep-link path + query: /issues/abc → /{lastSlug}/issues/abc
+      url.pathname = `/${lastSlug}${pathname}`;
+      return NextResponse.redirect(url);
+    }
+
+    // Logged-in but no cookie yet (first login since slug migration, or
+    // cookie cleared). Bounce to root; the root-path logic below picks a
+    // workspace and writes the cookie, then future hits short-circuit here.
+    url.pathname = "/";
+    return NextResponse.redirect(url);
+  }
+
+  // --- Root path: redirect logged-in users to their last workspace ---
+  if (pathname === "/") {
+    if (!hasSession) return NextResponse.next();
+
+    if (lastSlug) {
+      const url = req.nextUrl.clone();
+      url.pathname = `/${lastSlug}/issues`;
+      return NextResponse.redirect(url);
+    }
+
+    // No last_workspace_slug cookie → let landing page pick the first workspace
+    // client-side (features/landing/components/redirect-if-authenticated.tsx).
+    return NextResponse.next();
+  }
 
-export function proxy(_request: NextRequest) {
   return NextResponse.next();
 }
 
 export const config = {
-  matcher: ["/"],
+  matcher: [
+    "/",
+    "/issues/:path*",
+    "/projects/:path*",
+    "/agents/:path*",
+    "/inbox/:path*",
+    "/my-issues/:path*",
+    "/autopilots/:path*",
+    "/runtimes/:path*",
+    "/skills/:path*",
+    "/settings/:path*",
+  ],
 };

apps/web/test/helpers.tsx

@@ -78,7 +78,6 @@ export const mockAuthValue: Record<string, any> = {
   isLoading: false,
   login: vi.fn(),
   logout: vi.fn(),
-  switchWorkspace: vi.fn(),
   updateWorkspace: vi.fn(),
   updateCurrentUser: vi.fn(),
   getMemberName: (userId: string) => {

docs/plans/2026-04-16-unify-workspace-identity-resolver.md

@@ -0,0 +1,357 @@
+# Unify Workspace Identity Resolver Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Fix broken file uploads caused by the workspace slug refactor (v2, PR #1138/#1141), and eliminate the structural bug source that allowed it. File uploads from within a workspace on the desktop and web apps currently land in S3 without a corresponding DB attachment record — the file is orphaned and the UI never sees it.
+
+**Architecture:** The server currently has **two independent implementations** of the same logic — extract the workspace UUID from an HTTP request. One lives in the workspace middleware (post-v2, accepts slug header → DB lookup → UUID). The other lives inside the handler package (pre-v2, only accepts UUID header/query). The v2 refactor updated the middleware one and forgot the handler one; routes that sit *outside* the workspace middleware group (notably `/api/upload-file`) still run through the stale resolver and can't translate the frontend's new `X-Workspace-Slug` header.
+
+The root cause is duplication. The fix is to collapse both resolvers into a single shared function that middleware and handlers both delegate to, so any future change to "how do we read workspace identity" is impossible to forget. The existing middleware's resolver already has the full logic; we extract it into a package-level function and have the handler helper call it.
+
+**Tech Stack:** Go (Chi router, sqlc, pgx).
+
+**Non-goals:**
+- No frontend changes. The frontend has been sending `X-Workspace-Slug` since v2; this plan makes the server finish accepting it everywhere.
+- No route reshuffling. `/api/upload-file` stays outside `RequireWorkspaceMember` because it serves two distinct use cases (avatar upload + workspace attachment); the avatar path needs to work without a workspace context.
+- No change to CLI / daemon clients. They still send `X-Workspace-ID` (UUID); the resolver keeps UUID as a fallback.
+
+---
+
+## Overview
+
+| # | Change | Type | Files |
+|---|--------|------|-------|
+| 1 | Extract shared resolver into middleware package | Refactor | `server/internal/middleware/workspace.go` |
+| 2 | Promote handler `resolveWorkspaceID` to `(h *Handler).resolveWorkspaceID` + delegate to shared | Refactor | `server/internal/handler/handler.go` |
+| 3 | Rename 47 call sites from `resolveWorkspaceID(r)` → `h.resolveWorkspaceID(r)` | Mechanical | handler/*.go (see exhaustive list in task 3) |
+| 4 | Add test for upload-file with slug header | Test | `server/internal/handler/file_test.go` |
+| 5 | Add test for shared resolver | Test | `server/internal/middleware/workspace_test.go` |
+| 6 | `make check` and commit | Verify | — |
+
+---
+
+## Background: what's broken and why
+
+**Frontend (current, post-v2):** `ApiClient.authHeaders()` in `packages/core/api/client.ts:121` sends:
+```
+X-Workspace-Slug: <slug>
+```
+
+**Server middleware resolver** (`server/internal/middleware/workspace.go:53-86`, `resolveWorkspaceUUID`): accepts the slug header, looks up the slug via `queries.GetWorkspaceBySlug`, and writes the resolved UUID into the request context. Every handler behind `RequireWorkspaceMember` / `RequireWorkspaceRole` / `RequireWorkspaceMemberFromURL` sees the UUID in context and works correctly.
+
+**Handler resolver** (`server/internal/handler/handler.go:155-165`, `resolveWorkspaceID`): a parallel implementation used by handlers that are NOT behind the workspace middleware. It only checks:
+1. `middleware.WorkspaceIDFromContext(r.Context())`
+2. `?workspace_id` query param
+3. `X-Workspace-ID` header
+
+Never touches slug, because it has no `*db.Queries` access (it's a package-level function, not a method).
+
+**Impact:** `/api/upload-file` (registered at `server/cmd/server/router.go:166`, in the user-scoped group, outside workspace middleware) calls `resolveWorkspaceID(r)`, gets `""` because the frontend only sends slug, thinks "no workspace context", and silently skips the DB attachment record creation (`server/internal/handler/file.go:235-245`). The file reaches S3; the UI never sees it.
+
+**Why `/api/upload-file` is outside workspace middleware:** it serves both "avatar upload (no workspace)" and "attachment upload (with workspace)", branching on the resolved workspace ID inside the handler. Moving it under `RequireWorkspaceMember` would break avatar uploads.
+
+**Structural root cause:** two resolvers, same job, divergent capabilities. The duplication is what let v2 ship "mostly working" — most handlers live behind middleware, so the broken handler resolver had a low blast radius that wasn't caught in review.
+
+---
+
+### Task 1: Extract shared resolver into middleware package
+
+**Problem:** The middleware's `resolveWorkspaceUUID` closure captures `*db.Queries` and can look up slugs. The handler's `resolveWorkspaceID` is a bare package-level function without queries access. We need a single implementation both sides can reuse. Putting it in the `middleware` package is fine — the `handler` package already imports `middleware`.
+
+**Files:**
+- Modify: `server/internal/middleware/workspace.go`
+
+**Step 1: Add `ResolveWorkspaceIDFromRequest` export**
+
+After `errWorkspaceNotFound` (around line 45), add a package-level exported function that takes `(r *http.Request, queries *db.Queries)` and returns the workspace UUID as a string (empty if none found or slug doesn't resolve).
+
+Priority order (mirrors `resolveWorkspaceUUID`, plus a context lookup first so handlers behind middleware still get the fast path):
+
+```go
+// ResolveWorkspaceIDFromRequest returns the workspace UUID for an HTTP
+// request, using the same priority order as the workspace middleware.
+// Handlers behind workspace middleware get it from context (cheap); handlers
+// outside middleware (e.g. /api/upload-file) still resolve slug → UUID via
+// a DB lookup instead of silently falling through to "no workspace".
+//
+// Priority:
+//  1. middleware-injected context (if the route is behind workspace middleware)
+//  2. X-Workspace-Slug header → GetWorkspaceBySlug → UUID (post-refactor frontend)
+//  3. ?workspace_slug query → GetWorkspaceBySlug → UUID
+//  4. X-Workspace-ID header (CLI/daemon compat)
+//  5. ?workspace_id query (CLI/daemon compat)
+//
+// Returns "" when no identifier was provided OR a slug was provided but doesn't
+// resolve to any workspace. Callers that need the "slug provided but invalid"
+// distinction should use the resolver inside the middleware directly.
+func ResolveWorkspaceIDFromRequest(r *http.Request, queries *db.Queries) string {
+    if id := WorkspaceIDFromContext(r.Context()); id != "" {
+        return id
+    }
+    if slug := r.Header.Get("X-Workspace-Slug"); slug != "" {
+        if ws, err := queries.GetWorkspaceBySlug(r.Context(), slug); err == nil {
+            return util.UUIDToString(ws.ID)
+        }
+    }
+    if slug := r.URL.Query().Get("workspace_slug"); slug != "" {
+        if ws, err := queries.GetWorkspaceBySlug(r.Context(), slug); err == nil {
+            return util.UUIDToString(ws.ID)
+        }
+    }
+    if id := r.Header.Get("X-Workspace-ID"); id != "" {
+        return id
+    }
+    return r.URL.Query().Get("workspace_id")
+}
+```
+
+**Step 2: Refactor `resolveWorkspaceUUID` to delegate**
+
+The existing middleware closure has slightly different semantics (returns `errWorkspaceNotFound` when a slug was provided but doesn't resolve, so middleware can 404 instead of 400). Keep that, but share the resolution logic:
+
+Leave `resolveWorkspaceUUID` as-is for now — it distinguishes "no identifier" (400) from "invalid slug" (404). `ResolveWorkspaceIDFromRequest` returns "" in both cases because handler-level callers don't need that distinction (they just check for empty).
+
+Document in a comment near `resolveWorkspaceUUID` that it's an internal variant that preserves the error distinction for middleware gating, and point to `ResolveWorkspaceIDFromRequest` as the handler-facing API.
+
+**Step 3: Build and verify**
+
+```bash
+cd server && go build ./...
+```
+Expected: clean build.
+
+**Step 4: Commit**
+
+```
+refactor(server): extract ResolveWorkspaceIDFromRequest from middleware
+
+Introduces a shared helper that consolidates the workspace-identity
+resolution logic used by both the workspace middleware and the handler
+package. No behavior change yet — callers still use the old functions.
+Sets up the next commit to fix the /api/upload-file slug bug by routing
+the handler-side resolver through this shared function.
+```
+
+---
+
+### Task 2: Promote handler resolver to a method + delegate
+
+**Problem:** The package-level `resolveWorkspaceID(r *http.Request)` in `handler.go` can't call `GetWorkspaceBySlug` because it has no queries access. Promoting it to a method on `*Handler` gives it access to `h.Queries` at no syntactic cost elsewhere.
+
+**Files:**
+- Modify: `server/internal/handler/handler.go:155-165`
+
+**Step 1: Replace `resolveWorkspaceID` with a Handler method**
+
+```go
+// resolveWorkspaceID resolves the workspace UUID for this request.
+// Delegates to middleware.ResolveWorkspaceIDFromRequest so routes inside
+// and outside workspace middleware see identical resolution behavior.
+//
+// Returns "" when no workspace identifier was provided or a slug was
+// provided but doesn't match any workspace.
+func (h *Handler) resolveWorkspaceID(r *http.Request) string {
+    return middleware.ResolveWorkspaceIDFromRequest(r, h.Queries)
+}
+```
+
+Delete the old package-level `resolveWorkspaceID` function.
+
+**Step 2: Build — expect errors at 47 call sites**
+
+```bash
+cd server && go build ./... 2>&1 | head -60
+```
+
+Expected: `resolveWorkspaceID is not a value` or `undefined: resolveWorkspaceID` errors at each existing call site. That's the signal to run Task 3.
+
+**Do not commit yet.** Task 2 and 3 are a single logical change; they commit together after Task 3 fixes the compile.
+
+---
+
+### Task 3: Rename 47 call sites to `h.resolveWorkspaceID(r)`
+
+**Problem:** Every `resolveWorkspaceID(r)` call in the handler package now fails to compile because the function became a method. All 47 call sites are inside methods on `*Handler` (or similar receiver types that have access to `h`), so the rename is mechanical.
+
+**Files affected** (verified via `grep -rn "resolveWorkspaceID" server/internal/handler/`):
+
+- `server/internal/handler/handler.go:275, 365, 388` (3 sites)
+- `server/internal/handler/issue.go:447, 559, 731, 783, 1294, 1476` (6 sites)
+- `server/internal/handler/activity.go:133` (1 site)
+- `server/internal/handler/autopilot.go:178, 203, 255, 306, 386, 414, 490, 578, 615, 662` (10 sites)
+- `server/internal/handler/project.go:80, 127, 150, 192, 273, 430` (6 sites)
+- `server/internal/handler/comment.go:443, 510` (2 sites)
+- `server/internal/handler/runtime.go:207, 247, 296` (3 sites)
+- `server/internal/handler/pin.go:59, 105, 175, 202` (4 sites)
+- `server/internal/handler/reaction.go:43, 110` (2 sites)
+- `server/internal/handler/skill.go:126, 146, 187, 384, 815` (5 sites)
+- `server/internal/handler/agent.go:158, 254` (2 sites)
+- `server/internal/handler/file.go:83, 115, 282, 306` (4 sites)
+
+Total: 48 (the resolver declaration itself + 47 callers).
+
+**Step 1: Mechanical rename**
+
+For each file above, change every `resolveWorkspaceID(r)` to `h.resolveWorkspaceID(r)`. In the one case in `file.go:83` inside `groupAttachments`, the receiver is already `*Handler`, so the method is accessible.
+
+**Semantic check:** all 47 call sites are on methods with an `h *Handler` receiver (verifiable by scrolling up a few lines from each grep match). If any call site is inside a non-method function, that site needs to either take `*Handler` as a parameter or be skipped from this rename. Spot-check three sites before doing the rename.
+
+**Step 2: Build**
+
+```bash
+cd server && go build ./...
+```
+Expected: clean build.
+
+**Step 3: Run Go tests**
+
+```bash
+cd server && go test ./...
+```
+Expected: all pass. The 46 call sites behind workspace middleware hit the context branch (identical behavior to before). Only `UploadFile` gains new capability (slug resolution); it wasn't tested before, will be covered in Task 4.
+
+**Step 4: Commit**
+
+```
+fix(server): resolve X-Workspace-Slug in /api/upload-file and other middleware-less handlers
+
+The v2 workspace URL refactor updated the workspace middleware to accept
+X-Workspace-Slug but left the handler-package resolveWorkspaceID helper
+(used by handlers outside the middleware group) stuck on X-Workspace-ID.
+The frontend switched to the slug header, so /api/upload-file was
+receiving a slug it couldn't translate to a UUID, silently falling
+through to the avatar-upload branch and skipping DB attachment record
+creation — files were landing in S3 with no database reference.
+
+Promote resolveWorkspaceID to a Handler method and delegate to the new
+middleware.ResolveWorkspaceIDFromRequest so middleware-behind and
+middleware-outside handlers share the same resolution logic. The 46
+call sites that live inside the workspace middleware group are
+unaffected (context lookup still wins). /api/upload-file now correctly
+recognizes slug requests and creates the attachment record.
+
+Fixes: missing DB attachment rows for files uploaded since v2 (#1141)
+```
+
+---
+
+### Task 4: Add handler test for upload-file with slug header
+
+**Problem:** The bug manifested exactly because there was no test covering the "upload-file with only a slug header" code path. Prevent regression.
+
+**Files:**
+- Modify: `server/internal/handler/file_test.go` (or create if absent)
+
+**Step 1: Locate existing upload-file test infrastructure**
+
+```bash
+grep -rn "UploadFile\|upload-file" server/internal/handler/*_test.go
+```
+
+If there's an existing upload-file test, add a new test case alongside it. If not, scaffold one using the same `handler_test.go` fixture pattern (`testWorkspaceID`, `testUserID`, seeded workspace).
+
+**Step 2: Write the test**
+
+Test name: `TestUploadFile_ResolvesWorkspaceViaSlugHeader`.
+
+Flow:
+1. Seed a workspace with a known slug and the default test user as a member.
+2. POST a multipart form to `/api/upload-file` with an `issue_id` field referencing a seeded issue, with only `X-Workspace-Slug: <slug>` in headers (no `X-Workspace-ID`).
+3. Assert response is 200.
+4. Assert a DB row exists in `attachments` with the expected `workspace_id`, `uploader_id`, `issue_id`, and `filename`.
+
+Anti-regression: also add `TestUploadFile_ResolvesWorkspaceViaIDHeaderStill` to confirm legacy `X-Workspace-ID` header still works (CLI / daemon compat).
+
+**Step 3: Run the new test**
+
+```bash
+cd server && go test ./internal/handler/ -run UploadFile
+```
+Expected: both pass.
+
+**Step 4: Commit**
+
+```
+test(server): cover upload-file slug and UUID header resolution
+
+Regression test for the v2 refactor bug: uploads from the frontend
+(which sends X-Workspace-Slug) now reach the workspace-aware branch
+and create attachment records.
+```
+
+---
+
+### Task 5: Add unit test for the shared resolver
+
+**Problem:** The shared function will be the single point through which all workspace identity resolution flows. It deserves table-driven test coverage for each priority level.
+
+**Files:**
+- Create or modify: `server/internal/middleware/workspace_test.go`
+
+**Step 1: Table test**
+
+Cases to cover:
+- Context UUID present → returns context UUID, ignores headers/query
+- Only `X-Workspace-Slug` → DB lookup succeeds → returns UUID
+- Only `X-Workspace-Slug` → DB lookup fails → returns ""
+- Only `?workspace_slug` → DB lookup succeeds → returns UUID
+- Only `X-Workspace-ID` → returns UUID
+- Only `?workspace_id` → returns UUID
+- Slug header + UUID header both present → slug wins (frontend priority)
+- Nothing → returns ""
+
+**Step 2: Run**
+
+```bash
+cd server && go test ./internal/middleware/ -run ResolveWorkspaceIDFromRequest
+```
+Expected: all cases pass.
+
+**Step 3: Commit**
+
+```
+test(server): table-driven coverage for ResolveWorkspaceIDFromRequest
+
+Pins down the priority order (context > slug header > slug query >
+UUID header > UUID query) so future changes can't silently diverge.
+```
+
+---
+
+### Task 6: Full verification
+
+**Step 1: `make check`**
+
+```bash
+make check
+```
+Expected: typecheck, TS tests, Go tests, E2E (if backend+frontend up) all green.
+
+**Step 2: Manual smoke test**
+
+1. Start desktop dev environment.
+2. Open an issue, attach a file via drag-and-drop or the file picker.
+3. Refresh the issue. The attachment should appear in the attachments list.
+
+Before this fix: attachment silently disappears on refresh (file is in S3, DB has no row).
+
+**Step 3: Open PR**
+
+Branch name: `fix/unify-workspace-identity-resolver`.
+
+Title: `fix(server): resolve X-Workspace-Slug in middleware-less handlers`
+
+Body should:
+- Link to the symptom PR (v2 refactor #1141) and reference that it's a latent follow-up.
+- Describe the structural change (two resolvers → one).
+- Note that 46 of 47 call sites see zero behavior change (context branch wins); only `/api/upload-file` gains capability.
+
+---
+
+## Risk / blast radius
+
+**Low risk.** The 46 middleware-protected callers hit the context branch in `ResolveWorkspaceIDFromRequest` identically to how they hit `WorkspaceIDFromContext` before — zero semantic change. The only new code path exercised in production is the slug-header branch for `/api/upload-file`, which is already exercised by every other slug-header-carrying request (just via the middleware's version of the same logic). Task 4 and 5 lock the behavior down with tests.
+
+## Rollback plan
+
+If a regression surfaces after deploy, revert the single commit from Task 3. `ResolveWorkspaceIDFromRequest` and the Handler method remain but are unused — harmless dead code until the next attempt.

docs/workspace-url-refactor-proposal.md

@@ -0,0 +1,109 @@
+# Workspace URL 化重构 — 项目汇报
+
+**日期**：2026-04-15
+**作者**：Naiyuan
+**状态**：调研完成，待评审
+
+---
+
+## 一、为什么要做
+
+当前 workspace 上下文完全靠 `X-Workspace-ID` HTTP header + Zustand store + localStorage 承载，URL 里**不含任何 workspace 信息**。所有路径都是 `/issues`、`/issues/:id` 这种 workspace-agnostic 的。
+
+这个设计已经在产品里直接表现为 3 个已知问题：
+
+1. **分享链接不可靠**（MUL-43）：`/issues/abc` 发给另一个成员，会用他自己 localStorage 里的 workspace 去解析，导致 404 或看到错误 workspace 的数据
+2. **手机端无法切 workspace**（MUL-509）：切换只靠 sidebar UI，手机端不展开 sidebar 就没有切换入口
+3. **多 tab 互相覆盖**：`multica_workspace_id` 是全局 localStorage key，两个 tab 打开不同 workspace 会互相污染
+
+除了这 3 个显性 bug，架构上的"多份 workspace 状态拷贝互相同步"也带来一些隐性问题（创建 workspace 闪页、切换 workspace 时 cache 竞态等），积累时间越长后续改动越难。
+
+行业惯例（Linear / Notion / Vercel / GitHub）都是 `/{workspace-slug}/...` 的 URL 形态，把 URL 当作 workspace 的唯一来源。这是我们应该对齐的最佳实践。
+
+## 二、调研结论
+
+### 好消息：基础设施已经就位
+
+- 数据库 `workspace.slug` 字段已经存在（`TEXT UNIQUE NOT NULL`），用户创建时手动指定且不可修改
+- 后端已有 `GetWorkspaceBySlug` 查询
+- 前端 `Workspace` 类型已包含 `slug` 字段
+- Web 端认证已经切换为 HttpOnly cookie 模式，Next.js middleware 可读到登录态
+
+也就是说这次改造**不需要大量后端改动**，主要是前端路由和状态管理的重新组织。
+
+### 坏消息：范围比最初估计大
+
+初看以为只是"URL 前缀加个 slug"，调研后发现必须一起做的事情有：
+
+1. **URL 路由重组**：web 端所有 dashboard 路由迁到 `app/[workspaceSlug]/(dashboard)/*`；desktop 端所有 react-router 路由加 `/:workspaceSlug` 前缀
+2. **状态管理清理**：删除 `useWorkspaceStore.workspace` 作为独立状态，改为从 URL 派生；删除 `hydrateWorkspace` / `switchWorkspace` actions（切 workspace 变成纯导航）；删除 `localStorage["multica_workspace_id"]`
+3. **所有路径引用替换**：`push("/issues")` 改为 path builder（`paths.issues()`），影响 ~25 个组件文件
+4. **Mutation 副作用重构**：`useCreateWorkspace` / `useLeaveWorkspace` / `useDeleteWorkspace` 里的 `switchWorkspace` 调用全部移除（这些调用正是 MUL-727 闪页、MUL-728 删除后不跳转、MUL-820 接受邀请不切 workspace 等一系列 bug 的根因）
+5. **桌面端 tab 系统适配**：tab 路径天然包含 workspace，切 workspace = 开新 tab 或导航，不再有全局切换动作
+6. **Shareable URL 修复**：桌面端 `getShareableUrl` 当前生成 `https://www.multica.ai/issues/abc`（缺 slug），需要更新
+7. **后端保留词校验**：slug 不能和前端顶级路由冲突（`login`、`onboarding`、`invite`、`api`、`settings` 等），后端创建时校验
+8. **内部 markdown 链接兼容**：issue 评论里写的 `[foo](/issues/abc)` 触发的 `multica:navigate` 事件需要自动补当前 workspace slug
+
+### 不需要改的（边界已确认）
+
+- 邮件邀请链接 `/invite/{id}` — 接受邀请是 pre-workspace 流程，不需要 slug
+- `mention://type/id` 协议 — 只存 UUID，workspace-agnostic
+- CLI 登录 URL — `/login` 也是 pre-workspace，不需要 slug
+- 后端 API 路径 — 保持 `/api/workspaces/{id}`，slug 仅用于前端 URL
+- 桌面端 `multica://auth/callback` — 认证回调，不涉及 workspace
+
+## 三、方案要点
+
+**核心原则**：URL 是 workspace 上下文的唯一 source of truth，其他状态都是派生态。
+
+**URL 形状**：`/{workspace-slug}/issues/{id}` （和 Linear / Notion 一致）
+
+**切换 workspace = 导航**：sidebar 下拉改为 `<Link href="/{new-slug}/issues">`，不再有命令式的 `switchWorkspace` 函数。这样一次性消除前面列出的一大批 mutation 副作用 bug。
+
+**预估影响面**：~30-35 个文件，其中约 20 个是机械替换（hardcoded 路径 → path builder），真正需要思考的核心逻辑改动集中在 5-6 个文件。
+
+**一个 PR 合并**：中间状态不可运行（URL 结构是原子变化），不拆 PR。worktree 里充分开发和自测，一次 review 合并。
+
+## 四、执行与测试计划
+
+### 执行阶段
+
+1. **本周内**：完成方案详细实施文档（精确到文件 / 行号 / 代码片段）
+2. **下一步**：在独立 worktree 上开发，AI 辅助写代码，过程中人工 review
+3. **开发完成后**：本地跑全套验证（`make check` — TypeScript + 单测 + Go 测试 + E2E）
+
+### 测试阶段
+
+1. **本地自测**：
+   - 已知功能路径（创建 / 浏览 / 搜索 issue，切换 workspace，接受邀请，分享链接）
+   - 已知 bug 场景（MUL-43 / MUL-509 / MUL-727 / MUL-820）逐一验证已修复
+   - 多 tab 场景（两个 tab 打开不同 workspace 互不影响）
+2. **测试环境部署**：本地通过后发测试环境，全员试用几天，观察：
+   - 是否有回归（特别是导航流、创建/删除 workspace、邀请流程）
+   - URL 使用感受（分享、收藏、刷新）
+3. **灰度 / 生产**：测试环境稳定后推生产
+
+### 风险提示
+
+- **唯一的硬中断点**：现有的 `/issues` 等 URL 在重构后会 404（产品还没正式 ship、用户量可忽略，所以不做兼容性重定向）
+- **E2E 测试断言**：约 20-30 处 URL 断言需要更新
+- **后端保留词清单**：如果现有 workspace 里有名字撞到保留词的（例如正好叫 `settings`），需要提前 migrate（可能性极低，因 slug 限制较严）
+
+## 五、附注
+
+这次重构会**顺带修掉**以下已登记 issue，不需要单独开 PR：
+
+| Issue | 修复方式 |
+|---|---|
+| MUL-43（切换 workspace 报错 / 分享链接失效） | URL 带 slug，根本解决 |
+| MUL-509（手机端无法切 workspace） | 切换变导航，手机能点链接就能切 |
+| MUL-723（workspace 不在 URL） | 核心目标 |
+| MUL-727（创建 workspace 闪 /issues） | 删除 mutation 里的 switchWorkspace 副作用 |
+| MUL-728（删除 workspace 后留在 /settings） | 删除成功后 navigate 到下一个 workspace |
+| MUL-820（sidebar Join 不切 workspace） | Join 改成跳转到 `/invite/{id}` 走统一路径 |
+
+不在本次范围内的：Issue #951（WebSocket 半开导致 cache 陈旧）—— 这是 realtime 层独立问题，单独 PR 处理。
+
+---
+
+**当前状态**：准备进入详细实施方案撰写，预计完成后再同步一次。

e2e/auth.spec.ts

@@ -24,10 +24,12 @@ test.describe("Authentication", () => {
     await page.goto("/login");
     await page.evaluate(() => {
       localStorage.removeItem("multica_token");
-      localStorage.removeItem("multica_workspace_id");
     });
 
-    await page.goto("/issues");
+    // Visit a workspace-scoped route; DashboardGuard should redirect to /login.
+    // The slug here need not exist — the guard runs before workspace resolution
+    // for unauthenticated users.
+    await page.goto("/e2e-workspace/issues");
     await page.waitForURL("**/login", { timeout: 10000 });
   });
 

e2e/comments.spec.ts

@@ -16,8 +16,9 @@ test.describe("Comments", () => {
   });
 
   test("can add a comment on an issue", async ({ page }) => {
-    // Wait for issues to load and click first one
-    const issueLink = page.locator('a[href^="/issues/"]').first();
+    // Wait for issues to load and click first one. `*=` matches both legacy
+    // `/issues/{id}` and URL-refactored `/{slug}/issues/{id}` hrefs.
+    const issueLink = page.locator('a[href*="/issues/"]').first();
     await expect(issueLink).toBeVisible({ timeout: 5000 });
     await issueLink.click();
     await page.waitForURL(/\/issues\/[\w-]+/);
@@ -42,7 +43,7 @@ test.describe("Comments", () => {
   });
 
   test("comment submit button is disabled when empty", async ({ page }) => {
-    const issueLink = page.locator('a[href^="/issues/"]').first();
+    const issueLink = page.locator('a[href*="/issues/"]').first();
     await expect(issueLink).toBeVisible({ timeout: 5000 });
     await issueLink.click();
     await page.waitForURL(/\/issues\/[\w-]+/);

e2e/fixtures.ts

@@ -7,7 +7,10 @@
 import "./env";
 import pg from "pg";
 
-const API_BASE = process.env.NEXT_PUBLIC_API_URL ?? `http://localhost:${process.env.PORT ?? "8080"}`;
+// `||` (not `??`) so an empty `NEXT_PUBLIC_API_URL=` in .env still falls
+// back to localhost. dotenv sets unset-vs-empty both as "" — treating them
+// the same matches user intent.
+const API_BASE = process.env.NEXT_PUBLIC_API_URL || `http://localhost:${process.env.PORT || "8080"}`;
 const DATABASE_URL = process.env.DATABASE_URL ?? "postgres://multica:multica@localhost:5432/multica?sslmode=disable";
 
 interface TestWorkspace {
@@ -18,6 +21,7 @@ interface TestWorkspace {
 
 export class TestApiClient {
   private token: string | null = null;
+  private workspaceSlug: string | null = null;
   private workspaceId: string | null = null;
   private createdIssueIds: string[] = [];
 
@@ -86,11 +90,16 @@ export class TestApiClient {
     this.workspaceId = id;
   }
 
+  setWorkspaceSlug(slug: string) {
+    this.workspaceSlug = slug;
+  }
+
   async ensureWorkspace(name = "E2E Workspace", slug = "e2e-workspace") {
     const workspaces = await this.getWorkspaces();
     const workspace = workspaces.find((item) => item.slug === slug) ?? workspaces[0];
     if (workspace) {
       this.workspaceId = workspace.id;
+      this.workspaceSlug = workspace.slug;
       return workspace;
     }
 
@@ -150,7 +159,8 @@ export class TestApiClient {
       ...((init?.headers as Record<string, string>) ?? {}),
     };
     if (this.token) headers["Authorization"] = `Bearer ${this.token}`;
-    if (this.workspaceId) headers["X-Workspace-ID"] = this.workspaceId;
+    if (this.workspaceSlug) headers["X-Workspace-Slug"] = this.workspaceSlug;
+    else if (this.workspaceId) headers["X-Workspace-ID"] = this.workspaceId;
     return fetch(`${API_BASE}${path}`, { ...init, headers });
   }
 }

e2e/helpers.ts

@@ -9,19 +9,25 @@ const DEFAULT_E2E_WORKSPACE = "e2e-workspace";
  * Log in as the default E2E user and ensure the workspace exists first.
  * Authenticates via API (send-code → DB read → verify-code), then injects
  * the token into localStorage so the browser session is authenticated.
+ *
+ * Returns the E2E workspace slug so callers can build workspace-scoped URLs.
  */
-export async function loginAsDefault(page: Page) {
+export async function loginAsDefault(page: Page): Promise<string> {
   const api = new TestApiClient();
   await api.login(DEFAULT_E2E_EMAIL, DEFAULT_E2E_NAME);
-  await api.ensureWorkspace("E2E Workspace", DEFAULT_E2E_WORKSPACE);
+  const workspace = await api.ensureWorkspace(
+    "E2E Workspace",
+    DEFAULT_E2E_WORKSPACE,
+  );
 
   const token = api.getToken();
   await page.goto("/login");
   await page.evaluate((t) => {
     localStorage.setItem("multica_token", t);
   }, token);
-  await page.goto("/issues");
+  await page.goto(`/${workspace.slug}/issues`);
   await page.waitForURL("**/issues", { timeout: 10000 });
+  return workspace.slug;
 }
 
 /**

e2e/issues.spec.ts

@@ -65,8 +65,10 @@ test.describe("Issues", () => {
     // Reload to see the new issue
     await page.reload();
 
-    // Navigate to the issue detail
-    const issueLink = page.locator(`a[href="/issues/${issue.id}"]`);
+    // Navigate to the issue detail. Use a suffix match so the selector works
+    // whether the href is legacy `/issues/{id}` or URL-refactored
+    // `/{slug}/issues/{id}`.
+    const issueLink = page.locator(`a[href$="/issues/${issue.id}"]`);
     await expect(issueLink).toBeVisible({ timeout: 5000 });
     await issueLink.click();
 

packages/core/api/client.ts

@@ -66,6 +66,7 @@ import type {
 } from "../types";
 import { type Logger, noopLogger } from "../logger";
 import { createRequestId } from "../utils";
+import { getCurrentSlug } from "../platform/workspace-storage";
 
 export interface ApiClientOptions {
   logger?: Logger;
@@ -92,7 +93,6 @@ export class ApiError extends Error {
 export class ApiClient {
   private baseUrl: string;
   private token: string | null = null;
-  private workspaceId: string | null = null;
   private logger: Logger;
   private options: ApiClientOptions;
 
@@ -110,10 +110,6 @@ export class ApiClient {
     this.token = token;
   }
 
-  setWorkspaceId(id: string | null) {
-    this.workspaceId = id;
-  }
-
   private readCsrfToken(): string | null {
     if (typeof document === "undefined") return null;
     const match = document.cookie
@@ -125,7 +121,8 @@ export class ApiClient {
   private authHeaders(): Record<string, string> {
     const headers: Record<string, string> = {};
     if (this.token) headers["Authorization"] = `Bearer ${this.token}`;
-    if (this.workspaceId) headers["X-Workspace-ID"] = this.workspaceId;
+    const slug = getCurrentSlug();
+    if (slug) headers["X-Workspace-Slug"] = slug;
     const csrf = this.readCsrfToken();
     if (csrf) headers["X-CSRF-Token"] = csrf;
     return headers;
@@ -133,7 +130,10 @@ export class ApiClient {
 
   private handleUnauthorized() {
     this.token = null;
-    this.workspaceId = null;
+    // Workspace id is owned by the URL-driven workspace-storage singleton
+    // (set by [workspaceSlug]/layout.tsx). On 401, the auth flow navigates
+    // to /login which leaves the workspace route, and the next workspace
+    // entry will overwrite the id. No clear needed here.
     this.options.onUnauthorized?.();
   }
 
@@ -231,8 +231,7 @@ export class ApiClient {
     const search = new URLSearchParams();
     if (params?.limit) search.set("limit", String(params.limit));
     if (params?.offset) search.set("offset", String(params.offset));
-    const wsId = params?.workspace_id ?? this.workspaceId;
-    if (wsId) search.set("workspace_id", wsId);
+    if (params?.workspace_id) search.set("workspace_id", params.workspace_id);
     if (params?.status) search.set("status", params.status);
     if (params?.priority) search.set("priority", params.priority);
     if (params?.assignee_id) search.set("assignee_id", params.assignee_id);
@@ -263,9 +262,7 @@ export class ApiClient {
   }
 
   async createIssue(data: CreateIssueRequest): Promise<Issue> {
-    const search = new URLSearchParams();
-    if (this.workspaceId) search.set("workspace_id", this.workspaceId);
-    return this.fetch(`/api/issues?${search}`, {
+    return this.fetch("/api/issues", {
       method: "POST",
       body: JSON.stringify(data),
     });
@@ -396,8 +393,7 @@ export class ApiClient {
   // Agents
   async listAgents(params?: { workspace_id?: string; include_archived?: boolean }): Promise<Agent[]> {
     const search = new URLSearchParams();
-    const wsId = params?.workspace_id ?? this.workspaceId;
-    if (wsId) search.set("workspace_id", wsId);
+    if (params?.workspace_id) search.set("workspace_id", params.workspace_id);
     if (params?.include_archived) search.set("include_archived", "true");
     return this.fetch(`/api/agents?${search}`);
   }
@@ -430,8 +426,7 @@ export class ApiClient {
 
   async listRuntimes(params?: { workspace_id?: string; owner?: "me" }): Promise<AgentRuntime[]> {
     const search = new URLSearchParams();
-    const wsId = params?.workspace_id ?? this.workspaceId;
-    if (wsId) search.set("workspace_id", wsId);
+    if (params?.workspace_id) search.set("workspace_id", params.workspace_id);
     if (params?.owner) search.set("owner", params.owner);
     return this.fetch(`/api/runtimes?${search}`);
   }
@@ -788,9 +783,7 @@ export class ApiClient {
   }
 
   async createProject(data: CreateProjectRequest): Promise<Project> {
-    const search = new URLSearchParams();
-    if (this.workspaceId) search.set("workspace_id", this.workspaceId);
-    return this.fetch(`/api/projects?${search}`, {
+    return this.fetch("/api/projects", {
       method: "POST",
       body: JSON.stringify(data),
     });

packages/core/api/ws-client.ts

@@ -7,7 +7,7 @@ export class WSClient {
   private ws: WebSocket | null = null;
   private baseUrl: string;
   private token: string | null = null;
-  private workspaceId: string | null = null;
+  private workspaceSlug: string | null = null;
   private cookieAuth = false;
   private handlers = new Map<WSEventType, Set<EventHandler>>();
   private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
@@ -22,9 +22,9 @@ export class WSClient {
     this.cookieAuth = options?.cookieAuth ?? false;
   }
 
-  setAuth(token: string | null, workspaceId: string) {
+  setAuth(token: string | null, workspaceSlug: string) {
     this.token = token;
-    this.workspaceId = workspaceId;
+    this.workspaceSlug = workspaceSlug;
   }
 
   connect() {
@@ -33,8 +33,8 @@ export class WSClient {
     // proxies, CDNs, and browser history.  In cookie mode the HttpOnly cookie
     // is sent automatically with the upgrade request.  In token mode the token
     // is delivered as the first WebSocket message after the connection opens.
-    if (this.workspaceId)
-      url.searchParams.set("workspace_id", this.workspaceId);
+    if (this.workspaceSlug)
+      url.searchParams.set("workspace_slug", this.workspaceSlug);
 
     this.ws = new WebSocket(url.toString());
 

packages/core/auth/store.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it, vi } from "vitest";
+import type { ApiClient } from "../api/client";
+import { ApiError } from "../api/client";
+import type { StorageAdapter, User } from "../types";
+import { createAuthStore } from "./store";
+
+const fakeUser: User = {
+  id: "u1",
+  name: "Alice",
+  email: "alice@example.com",
+  avatar_url: null,
+} as User;
+
+function makeStorage(initial: Record<string, string> = {}): StorageAdapter & {
+  snapshot: () => Record<string, string>;
+} {
+  const data = { ...initial };
+  return {
+    getItem: (k) => data[k] ?? null,
+    setItem: (k, v) => {
+      data[k] = v;
+    },
+    removeItem: (k) => {
+      delete data[k];
+    },
+    snapshot: () => ({ ...data }),
+  };
+}
+
+function makeApi(getMe: () => Promise<User>): ApiClient {
+  return {
+    setToken: vi.fn(),
+    getMe,
+    // Only the methods touched by store.initialize are needed. Cast to
+    // ApiClient for type compatibility — the store treats it opaquely.
+  } as unknown as ApiClient;
+}
+
+describe("authStore.initialize — token mode", () => {
+  it("keeps the stored token when getMe fails with a non-401 ApiError (e.g. 500)", async () => {
+    const storage = makeStorage({ multica_token: "t" });
+    const api = makeApi(() =>
+      Promise.reject(new ApiError("server error", 500, "Internal Server Error")),
+    );
+    const store = createAuthStore({ api, storage });
+
+    await store.getState().initialize();
+
+    expect(store.getState().user).toBeNull();
+    expect(store.getState().isLoading).toBe(false);
+    expect(storage.snapshot().multica_token).toBe("t");
+  });
+
+  it("keeps the stored token on a network failure (non-ApiError throw)", async () => {
+    const storage = makeStorage({ multica_token: "t" });
+    const api = makeApi(() => Promise.reject(new TypeError("fetch failed")));
+    const store = createAuthStore({ api, storage });
+
+    await store.getState().initialize();
+
+    expect(store.getState().user).toBeNull();
+    expect(storage.snapshot().multica_token).toBe("t");
+  });
+
+  it("on 401, leaves storage cleanup to ApiClient.onUnauthorized and resets state", async () => {
+    // Simulate the real path: ApiClient fires onUnauthorized on 401, which
+    // removes the token from storage. The store's catch block must not
+    // duplicate or short-circuit this — it should only reset in-memory
+    // auth state.
+    const storage = makeStorage({ multica_token: "t" });
+    const api = makeApi(() => {
+      storage.removeItem("multica_token"); // stand-in for onUnauthorized
+      return Promise.reject(new ApiError("unauthorized", 401, "Unauthorized"));
+    });
+    const store = createAuthStore({ api, storage });
+
+    await store.getState().initialize();
+
+    expect(store.getState().user).toBeNull();
+    expect(storage.snapshot().multica_token).toBeUndefined();
+  });
+
+  it("populates user when getMe succeeds", async () => {
+    const storage = makeStorage({ multica_token: "t" });
+    const api = makeApi(() => Promise.resolve(fakeUser));
+    const store = createAuthStore({ api, storage });
+
+    await store.getState().initialize();
+
+    expect(store.getState().user).toEqual(fakeUser);
+    expect(storage.snapshot().multica_token).toBe("t");
+  });
+});

packages/core/auth/store.ts

@@ -1,6 +1,7 @@
 import { create } from "zustand";
 import type { User, StorageAdapter } from "../types";
-import type { ApiClient } from "../api/client";
+import { ApiError, type ApiClient } from "../api/client";
+import { setCurrentWorkspace } from "../platform/workspace-storage";
 
 export interface AuthStoreOptions {
   api: ApiClient;
@@ -56,10 +57,17 @@ export function createAuthStore(options: AuthStoreOptions) {
       try {
         const user = await api.getMe();
         set({ user, isLoading: false });
-      } catch {
-        api.setToken(null);
-        api.setWorkspaceId(null);
-        storage.removeItem("multica_token");
+      } catch (err) {
+        // Only clear the stored token on a genuine auth failure (401). For
+        // transient errors — network blips, backend rolling restarts, 5xx,
+        // aborted fetches — keep the token so the next initialize() (next
+        // page load or focus-refresh) can retry. The 401 path's token
+        // cleanup is handled upstream by ApiClient.handleUnauthorized via
+        // the onUnauthorized callback; we only need to reset the in-memory
+        // user + workspace state here.
+        if (err instanceof ApiError && err.status === 401) {
+          setCurrentWorkspace(null, null);
+        }
         set({ user: null, isLoading: false });
       }
     },
@@ -107,7 +115,7 @@ export function createAuthStore(options: AuthStoreOptions) {
       }
       storage.removeItem("multica_token");
       api.setToken(null);
-      api.setWorkspaceId(null);
+      setCurrentWorkspace(null, null);
       onLogout?.();
       set({ user: null });
     },

packages/core/chat/queries.ts

@@ -3,10 +3,10 @@ import { api } from "../api";
 
 // NOTE on workspace scoping:
 // `wsId` is used only as part of queryKey for cache isolation per workspace.
-// The actual workspace context comes from ApiClient's X-Workspace-ID header,
-// which is set by useWorkspaceStore.switchWorkspace(). Callers must ensure the
-// header is in sync with the wsId they pass here — otherwise cache writes will
-// be misattributed during a workspace switch race window.
+// The actual workspace context comes from ApiClient's X-Workspace-Slug header,
+// which is set by the URL-driven [workspaceSlug] layout. Callers must ensure
+// the header is in sync with the wsId they pass here — otherwise cache writes
+// will be misattributed during a workspace switch race window.
 
 export const chatKeys = {
   all: (wsId: string) => ["chat", wsId] as const,

packages/core/chat/store.ts

@@ -1,6 +1,6 @@
 import { create } from "zustand";
 import type { StorageAdapter } from "../types";
-import { getCurrentWorkspaceId, registerForWorkspaceRehydration } from "../platform/workspace-storage";
+import { getCurrentSlug, registerForWorkspaceRehydration } from "../platform/workspace-storage";
 import { createLogger } from "../logger";
 
 const logger = createLogger("chat.store");
@@ -90,8 +90,8 @@ export function createChatStore(options: ChatStoreOptions) {
   const { storage } = options;
 
   const wsKey = (base: string) => {
-    const wsId = getCurrentWorkspaceId();
-    return wsId ? `${base}:${wsId}` : base;
+    const slug = getCurrentSlug();
+    return slug ? `${base}:${slug}` : base;
   };
 
   const store = create<ChatState>((set, get) => ({

packages/core/hooks.tsx

@@ -1,25 +1,17 @@
 "use client";
 
-import { createContext, useContext } from "react";
-
-const WorkspaceIdContext = createContext<string | null>(null);
-
-export function WorkspaceIdProvider({
-  wsId,
-  children,
-}: {
-  wsId: string;
-  children: React.ReactNode;
-}) {
-  return (
-    <WorkspaceIdContext.Provider value={wsId}>
-      {children}
-    </WorkspaceIdContext.Provider>
-  );
-}
+import { useCurrentWorkspace } from "./paths/hooks";
 
+/**
+ * Returns the current workspace UUID. Throws if called outside a workspace route.
+ *
+ * Implementation: derives from useCurrentWorkspace() (URL slug + React Query list).
+ * No longer backed by a React Context — the WorkspaceIdProvider has been removed
+ * as part of the slug-first refactor. The throw semantics are preserved so existing
+ * callers that depend on non-null don't need guard code.
+ */
 export function useWorkspaceId(): string {
-  const wsId = useContext(WorkspaceIdContext);
-  if (!wsId) throw new Error("useWorkspaceId: no workspace selected — wrap in WorkspaceIdProvider");
-  return wsId;
+  const ws = useCurrentWorkspace();
+  if (!ws) throw new Error("useWorkspaceId: no workspace selected — ensure component renders inside a workspace route");
+  return ws.id;
 }

packages/core/index.ts

@@ -1,3 +1,3 @@
-export { useWorkspaceId, WorkspaceIdProvider } from "./hooks";
+export { useWorkspaceId } from "./hooks";
 export { createQueryClient } from "./query-client";
 export { QueryProvider } from "./provider";

packages/core/issues/stores/index.ts

@@ -17,8 +17,7 @@ export {
   createIssueViewStore,
   viewStoreSlice,
   viewStorePersistOptions,
-  registerViewStoreForWorkspaceSync,
-  initFilterWorkspaceSync,
+  useClearFiltersOnWorkspaceChange,
   SORT_OPTIONS,
   CARD_PROPERTY_OPTIONS,
   type ViewMode,

packages/core/issues/stores/view-store.ts

@@ -1,5 +1,6 @@
 "use client";
 
+import { useEffect, useRef } from "react";
 import { create } from "zustand";
 import { createStore, type StoreApi } from "zustand/vanilla";
 import { createJSONStorage, persist } from "zustand/middleware";
@@ -215,43 +216,23 @@ export const useIssueViewStore = create<IssueViewState>()(
 
 registerForWorkspaceRehydration(() => useIssueViewStore.persist.rehydrate());
 
-// Clear filters on all registered view stores when workspace switches.
-const _syncedStores = new Set<StoreApi<IssueViewState>>();
-let _workspaceSyncInitialized = false;
-
 /**
- * Register a view store to clear filters on workspace switch.
+ * Clears the given view store's filters whenever the workspace id changes.
  *
- * @param store - The view store to register.
- * @param subscribeToWorkspace - Optional: a function that subscribes to workspace
- *   changes and calls the callback with the new workspace ID. The app layer should
- *   provide this to avoid a circular dependency on the workspace store.
- *   Example: `(cb) => useWorkspaceStore.subscribe(s => cb(s.workspace?.id))`
+ * URL-driven: wsId arrives from `useWorkspaceId()` (Context fed by the
+ * `[workspaceSlug]` route). We track the previous id via ref so the first
+ * render doesn't wipe persisted filters — clearing only fires on transitions
+ * from one defined workspace to another.
  */
-export function registerViewStoreForWorkspaceSync(
-  store: StoreApi<IssueViewState>,
-  subscribeToWorkspace?: (callback: (workspaceId: string | undefined) => void) => void,
+export function useClearFiltersOnWorkspaceChange(
+  store: StoreApi<IssueViewState> | { getState: () => IssueViewState },
+  wsId: string | undefined,
 ) {
-  _syncedStores.add(store);
-  if (_workspaceSyncInitialized) return;
-  _workspaceSyncInitialized = true;
-
-  if (subscribeToWorkspace) {
-    let prevId: string | undefined;
-    subscribeToWorkspace((id) => {
-      if (prevId && id !== prevId) {
-        for (const s of _syncedStores) s.getState().clearFilters();
-      }
-      prevId = id;
-    });
-  }
-  // TODO: If no subscribeToWorkspace is provided, the workspace sync is a no-op.
-  // The app layer (apps/web) should call this with the workspace store subscription
-  // to wire up filter clearing on workspace switch.
+  const prevIdRef = useRef<string | undefined>(undefined);
+  useEffect(() => {
+    if (prevIdRef.current && wsId && wsId !== prevIdRef.current) {
+      store.getState().clearFilters();
+    }
+    prevIdRef.current = wsId;
+  }, [wsId, store]);
 }
-
-/** Backward-compatible alias — registers the global singleton for workspace sync. */
-export const initFilterWorkspaceSync = (
-  subscribeToWorkspace?: (callback: (workspaceId: string | undefined) => void) => void,
-) =>
-  registerViewStoreForWorkspaceSync(useIssueViewStore, subscribeToWorkspace);

packages/core/navigation/store.test.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect } from "vitest";
+
+// EXCLUDED_PREFIXES is private to store.ts but checked here via behavior.
+// We assert that every global path prefix is also excluded from lastPath
+// persistence — otherwise lastPath could contain /login etc, and on next
+// app load we'd "restore" a user to the login page.
+describe("useNavigationStore.lastPath excludes global paths", () => {
+  it("does not persist /login, /new-workspace, /invite/, /auth/, /logout, /signup", async () => {
+    const { useNavigationStore } = await import("./store");
+    const globalPrefixes = [
+      "/login",
+      "/logout",
+      "/signup",
+      "/new-workspace",
+      "/invite/abc",
+      "/auth/callback",
+    ];
+
+    for (const path of globalPrefixes) {
+      // Reset to a known sentinel so we can detect any write.
+      useNavigationStore.setState({ lastPath: "/sentinel" });
+      useNavigationStore.getState().onPathChange(path);
+      expect(
+        useNavigationStore.getState().lastPath,
+        `${path} should not be persisted as lastPath (would restore user to a global route)`,
+      ).toBe("/sentinel");
+    }
+  });
+
+  it("does persist workspace-scoped paths", async () => {
+    const { useNavigationStore } = await import("./store");
+    useNavigationStore.setState({ lastPath: null });
+    useNavigationStore.getState().onPathChange("/acme/issues");
+    expect(useNavigationStore.getState().lastPath).toBe("/acme/issues");
+  });
+});

packages/core/navigation/store.ts

@@ -2,21 +2,35 @@
 
 import { create } from "zustand";
 import { createJSONStorage, persist } from "zustand/middleware";
-import { createPersistStorage } from "../platform/persist-storage";
+import {
+  createWorkspaceAwareStorage,
+  registerForWorkspaceRehydration,
+} from "../platform/workspace-storage";
 import { defaultStorage } from "../platform/storage";
 
-const EXCLUDED_PREFIXES = ["/login", "/pair/", "/invite/"];
+// Paths that should not be persisted as "last visited":
+//  - Auth flows (/login, /signup, /logout)
+//  - Pre-workspace routes (/new-workspace, /auth/, /invite/)
+//  - Pair flow (/pair/)
+const EXCLUDED_PREFIXES = [
+  "/login",
+  "/signup",
+  "/logout",
+  "/new-workspace",
+  "/auth/",
+  "/invite/",
+  "/pair/",
+];
 
 interface NavigationState {
-  lastPath: string;
+  lastPath: string | null;
   onPathChange: (path: string) => void;
 }
 
 export const useNavigationStore = create<NavigationState>()(
   persist(
     (set) => ({
-      lastPath: "/issues",
-
+      lastPath: null,
       onPathChange: (path: string) => {
         if (!EXCLUDED_PREFIXES.some((prefix) => path.startsWith(prefix))) {
           set({ lastPath: path });
@@ -25,8 +39,11 @@ export const useNavigationStore = create<NavigationState>()(
     }),
     {
       name: "multica_navigation",
-      storage: createJSONStorage(() => createPersistStorage(defaultStorage)),
+      storage: createJSONStorage(() => createWorkspaceAwareStorage(defaultStorage)),
       partialize: (state) => ({ lastPath: state.lastPath }),
-    }
-  )
+    },
+  ),
 );
+
+// Workspace-aware: re-read lastPath when current workspace changes.
+registerForWorkspaceRehydration(() => useNavigationStore.persist.rehydrate());

packages/core/package.json

@@ -55,6 +55,7 @@
     "./realtime": "./realtime/index.ts",
     "./navigation": "./navigation/index.ts",
     "./modals": "./modals/index.ts",
+    "./paths": "./paths/index.ts",
     "./hooks": "./hooks.tsx",
     "./hooks/*": "./hooks/*.ts",
     "./query-client": "./query-client.ts",

packages/core/paths/consistency.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect } from "vitest";
+import { paths, isGlobalPath } from "./paths";
+import { RESERVED_SLUGS } from "./reserved-slugs";
+
+// C4 — link-handler's WORKSPACE_ROUTE_SEGMENTS must match paths.workspace's
+// parameterless method names. We can't import WORKSPACE_ROUTE_SEGMENTS here
+// because link-handler is in packages/views (no inverse import allowed), so
+// we hardcode the expected list and assert paths.workspace produces the same
+// keys. If you change either, BOTH need to be updated — the test catches drift.
+describe("paths.workspace() shape", () => {
+  it("exposes the expected parameterless workspace route methods", () => {
+    const ws = paths.workspace("__probe__");
+    const parameterlessRoutes = Object.entries(ws)
+      .filter(([, fn]) => typeof fn === "function" && fn.length === 0)
+      .map(([key]) => key);
+
+    expect(new Set(parameterlessRoutes)).toEqual(
+      new Set([
+        "root",
+        "issues",
+        "projects",
+        "autopilots",
+        "agents",
+        "inbox",
+        "myIssues",
+        "runtimes",
+        "skills",
+        "settings",
+      ]),
+    );
+  });
+
+  it("each parameterless route emits /{slug}/{segment}", () => {
+    const ws = paths.workspace("acme");
+    // Check that none of the parameterless paths embed a leaked literal
+    // and that their second URL segment matches the method name's kebab-case.
+    const expectedSegments: Array<[string, string]> = [
+      ["issues", "issues"],
+      ["projects", "projects"],
+      ["autopilots", "autopilots"],
+      ["agents", "agents"],
+      ["inbox", "inbox"],
+      ["myIssues", "my-issues"],
+      ["runtimes", "runtimes"],
+      ["skills", "skills"],
+      ["settings", "settings"],
+    ];
+    const wsAsAny = ws as unknown as Record<string, () => string>;
+    for (const [method, segment] of expectedSegments) {
+      const fn = wsAsAny[method];
+      expect(typeof fn).toBe("function");
+      expect(fn!()).toBe(`/acme/${segment}`);
+    }
+  });
+});
+
+// C5 — invariants between the global/reserved lists.
+describe("global path / reserved slug consistency", () => {
+  // If a path is "global" (never workspace-scoped), the slug name underlying it
+  // must be reserved — otherwise a user could create a workspace with that slug
+  // and shadow the global route's URL space.
+  //
+  // GLOBAL_PREFIXES from paths.ts is private — we re-derive the list from
+  // probing isGlobalPath. Order matters: keep this list in sync with paths.ts.
+  const globalPrefixes = [
+    "/login",
+    "/logout",
+    "/signup",
+    "/new-workspace",
+    "/invite/",
+    "/auth/",
+  ];
+
+  it("isGlobalPath agrees with the canonical global prefix list", () => {
+    for (const prefix of globalPrefixes) {
+      expect(isGlobalPath(prefix)).toBe(true);
+    }
+    expect(isGlobalPath("/acme/issues")).toBe(false);
+    expect(isGlobalPath("/")).toBe(false);
+  });
+
+  it("every global prefix's first path segment is a reserved slug", () => {
+    for (const prefix of globalPrefixes) {
+      const firstSegment = prefix.split("/").filter(Boolean)[0];
+      if (!firstSegment) continue;
+      expect(
+        RESERVED_SLUGS.has(firstSegment),
+        `'${firstSegment}' is a global path prefix but not a reserved slug — ` +
+          `a workspace could be created with this slug and shadow the global route`,
+      ).toBe(true);
+    }
+  });
+});

packages/core/paths/hooks.tsx

@@ -0,0 +1,70 @@
+"use client";
+
+import { createContext, useContext, type ReactNode } from "react";
+import { useQuery } from "@tanstack/react-query";
+import type { Workspace } from "../types";
+import { workspaceListOptions } from "../workspace/queries";
+import { paths, type WorkspacePaths } from "./paths";
+
+/**
+ * Context for the current workspace slug (read from URL by the platform layer).
+ *
+ * apps/web populates this from Next.js `params.workspaceSlug` in
+ * [workspaceSlug]/layout.tsx. apps/desktop populates it from react-router's
+ * `useParams()` in the workspace route layout.
+ *
+ * packages/core/ cannot import next/navigation or react-router-dom directly,
+ * so the slug arrives via this Context — mirroring how WorkspaceIdProvider
+ * already works for workspace IDs.
+ */
+const WorkspaceSlugContext = createContext<string | null>(null);
+
+export function WorkspaceSlugProvider({
+  slug,
+  children,
+}: {
+  slug: string | null;
+  children: ReactNode;
+}) {
+  return (
+    <WorkspaceSlugContext.Provider value={slug}>
+      {children}
+    </WorkspaceSlugContext.Provider>
+  );
+}
+
+/** Current workspace slug from URL, or null outside workspace-scoped routes. */
+export function useWorkspaceSlug(): string | null {
+  return useContext(WorkspaceSlugContext);
+}
+
+/** Same as useWorkspaceSlug, but throws if called outside a workspace route. */
+export function useRequiredWorkspaceSlug(): string {
+  const slug = useWorkspaceSlug();
+  if (!slug) {
+    throw new Error(
+      "useRequiredWorkspaceSlug called outside a workspace-scoped route",
+    );
+  }
+  return slug;
+}
+
+/**
+ * The currently-selected workspace, derived from URL slug + React Query list.
+ * Returns null if slug is missing or doesn't match any workspace in the list.
+ */
+export function useCurrentWorkspace(): Workspace | null {
+  const slug = useWorkspaceSlug();
+  const { data: list = [] } = useQuery(workspaceListOptions());
+  if (!slug) return null;
+  return list.find((w) => w.slug === slug) ?? null;
+}
+
+/**
+ * Path builder bound to the current workspace. Throws if called outside a
+ * workspace route — for cross-workspace links use paths.workspace(slug) directly.
+ */
+export function useWorkspacePaths(): WorkspacePaths {
+  const slug = useRequiredWorkspaceSlug();
+  return paths.workspace(slug);
+}

packages/core/paths/index.ts

@@ -0,0 +1,10 @@
+export { paths, isGlobalPath } from "./paths";
+export type { WorkspacePaths } from "./paths";
+export { RESERVED_SLUGS, isReservedSlug } from "./reserved-slugs";
+export {
+  WorkspaceSlugProvider,
+  useWorkspaceSlug,
+  useRequiredWorkspaceSlug,
+  useCurrentWorkspace,
+  useWorkspacePaths,
+} from "./hooks";

packages/core/paths/paths.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from "vitest";
+import { paths, isGlobalPath } from "./paths";
+
+describe("paths.workspace(slug)", () => {
+  const ws = paths.workspace("acme");
+
+  it("builds dashboard paths with slug prefix", () => {
+    expect(ws.issues()).toBe("/acme/issues");
+    expect(ws.issueDetail("abc-123")).toBe("/acme/issues/abc-123");
+    expect(ws.projects()).toBe("/acme/projects");
+    expect(ws.projectDetail("p1")).toBe("/acme/projects/p1");
+    expect(ws.autopilots()).toBe("/acme/autopilots");
+    expect(ws.autopilotDetail("a1")).toBe("/acme/autopilots/a1");
+    expect(ws.agents()).toBe("/acme/agents");
+    expect(ws.inbox()).toBe("/acme/inbox");
+    expect(ws.myIssues()).toBe("/acme/my-issues");
+    expect(ws.runtimes()).toBe("/acme/runtimes");
+    expect(ws.skills()).toBe("/acme/skills");
+    expect(ws.settings()).toBe("/acme/settings");
+  });
+
+  it("URL-encodes special characters in ids", () => {
+    expect(ws.issueDetail("id with space")).toBe("/acme/issues/id%20with%20space");
+  });
+});
+
+describe("paths (global)", () => {
+  it("builds global paths without slug", () => {
+    expect(paths.login()).toBe("/login");
+    expect(paths.newWorkspace()).toBe("/new-workspace");
+    expect(paths.invite("inv-1")).toBe("/invite/inv-1");
+    expect(paths.authCallback()).toBe("/auth/callback");
+  });
+});
+
+describe("isGlobalPath", () => {
+  it("returns true for pre-workspace routes", () => {
+    expect(isGlobalPath("/login")).toBe(true);
+    expect(isGlobalPath("/new-workspace")).toBe(true);
+    expect(isGlobalPath("/invite/abc")).toBe(true);
+    expect(isGlobalPath("/auth/callback")).toBe(true);
+  });
+
+  it("returns false for workspace-scoped paths", () => {
+    expect(isGlobalPath("/acme/issues")).toBe(false);
+    expect(isGlobalPath("/")).toBe(false);
+  });
+});

packages/core/paths/paths.ts

@@ -0,0 +1,55 @@
+/**
+ * Centralized URL path builder. All navigation in shared packages (packages/views)
+ * MUST go through this module — no hardcoded string paths.
+ *
+ * Two kinds of paths:
+ *  - workspace-scoped: paths.workspace(slug).xxx() — carry workspace in URL
+ *  - global: paths.login(), paths.newWorkspace(), paths.invite(id) — pre-workspace routes
+ *
+ * Why pure functions + builder pattern:
+ *  - Changing a route shape (e.g. adding workspace slug prefix) becomes a single-file edit
+ *  - IDs are always URL-encoded here so callers can't forget
+ *  - Zero runtime deps means this module is safe in Node (tests) and browsers
+ */
+
+const encode = (id: string) => encodeURIComponent(id);
+
+function workspaceScoped(slug: string) {
+  const ws = `/${encode(slug)}`;
+  return {
+    root: () => `${ws}/issues`,
+    issues: () => `${ws}/issues`,
+    issueDetail: (id: string) => `${ws}/issues/${encode(id)}`,
+    projects: () => `${ws}/projects`,
+    projectDetail: (id: string) => `${ws}/projects/${encode(id)}`,
+    autopilots: () => `${ws}/autopilots`,
+    autopilotDetail: (id: string) => `${ws}/autopilots/${encode(id)}`,
+    agents: () => `${ws}/agents`,
+    inbox: () => `${ws}/inbox`,
+    myIssues: () => `${ws}/my-issues`,
+    runtimes: () => `${ws}/runtimes`,
+    skills: () => `${ws}/skills`,
+    settings: () => `${ws}/settings`,
+  };
+}
+
+export const paths = {
+  workspace: workspaceScoped,
+
+  // Global (pre-workspace) routes
+  login: () => "/login",
+  newWorkspace: () => "/new-workspace",
+  invite: (id: string) => `/invite/${encode(id)}`,
+  authCallback: () => "/auth/callback",
+  root: () => "/",
+};
+
+export type WorkspacePaths = ReturnType<typeof workspaceScoped>;
+
+// Prefixes — not slug names — because we match against full URL paths.
+// A path is global if it equals or begins with any of these.
+const GLOBAL_PREFIXES = ["/login", "/new-workspace", "/invite/", "/auth/", "/logout", "/signup"];
+
+export function isGlobalPath(path: string): boolean {
+  return GLOBAL_PREFIXES.some((p) => path === p || path.startsWith(p));
+}

packages/core/paths/reserved-slugs.ts

@@ -0,0 +1,50 @@
+/**
+ * Slugs reserved because they collide with frontend top-level routes.
+ * Keep in sync with server/internal/handler/workspace_reserved_slugs.go.
+ */
+export const RESERVED_SLUGS = new Set([
+  // Auth + onboarding
+  "login",
+  "logout",
+  "signup",
+  "onboarding",
+  "new-workspace",
+  "invite",
+  "auth",
+
+  // Reserved for future platform routes
+  "api",
+  "admin",
+  "help",
+  "about",
+  "pricing",
+  "changelog",
+
+  // Dashboard route segments. Even though Next.js's route specificity
+  // would technically resolve /{slug}/{view} correctly, having a workspace
+  // slug equal to a route name (e.g. slug="issues") makes URLs visually
+  // ambiguous — /issues/abc reads as either "issue abc in workspace
+  // 'issues'" or "issue abc in some workspace". Reserve to avoid the
+  // ambiguity entirely.
+  "issues",
+  "projects",
+  "autopilots",
+  "agents",
+  "inbox",
+  "my-issues",
+  "runtimes",
+  "skills",
+  "settings",
+
+  // Next.js / hosting internals
+  "_next",
+  "favicon.ico",
+  "robots.txt",
+  "sitemap.xml",
+  "manifest.json",
+  ".well-known",
+]);
+
+export function isReservedSlug(slug: string): boolean {
+  return RESERVED_SLUGS.has(slug);
+}

packages/core/platform/auth-initializer.tsx

@@ -4,11 +4,11 @@ import { useEffect, type ReactNode } from "react";
 import { useQueryClient } from "@tanstack/react-query";
 import { getApi } from "../api";
 import { useAuthStore } from "../auth";
-import { useWorkspaceStore } from "../workspace";
 import { configStore } from "../config";
 import { workspaceKeys } from "../workspace/queries";
 import { createLogger } from "../logger";
 import { defaultStorage } from "./storage";
+import { setCurrentWorkspace } from "./workspace-storage";
 import type { StorageAdapter } from "../types/storage";
 
 const logger = createLogger("auth");
@@ -30,7 +30,6 @@ export function AuthInitializer({
 
   useEffect(() => {
     const api = getApi();
-    const wsId = storage.getItem("multica_workspace_id");
 
     // Fetch app config (CDN domain, etc.) in the background — non-blocking.
     api.getConfig().then((cfg) => {
@@ -40,12 +39,16 @@ export function AuthInitializer({
     if (cookieAuth) {
       // Cookie mode: the HttpOnly cookie is sent automatically by the browser.
       // Call the API to check if the session is still valid.
+      //
+      // Seed the workspace list into React Query so the URL-driven layout can
+      // resolve the slug without a second fetch. The active workspace itself
+      // is derived from the URL by [workspaceSlug]/layout.tsx — no imperative
+      // selection here.
       Promise.all([api.getMe(), api.listWorkspaces()])
         .then(([user, wsList]) => {
           onLogin?.();
           useAuthStore.setState({ user, isLoading: false });
           qc.setQueryData(workspaceKeys.list(), wsList);
-          useWorkspaceStore.getState().hydrateWorkspace(wsList, wsId);
         })
         .catch((err) => {
           logger.error("cookie auth init failed", err);
@@ -69,16 +72,15 @@ export function AuthInitializer({
       .then(([user, wsList]) => {
         onLogin?.();
         useAuthStore.setState({ user, isLoading: false });
-        // Seed React Query cache so components don't need a second fetch
+        // Seed React Query cache so the URL-driven layout can resolve the
+        // slug without a second fetch.
         qc.setQueryData(workspaceKeys.list(), wsList);
-        useWorkspaceStore.getState().hydrateWorkspace(wsList, wsId);
       })
       .catch((err) => {
         logger.error("auth init failed", err);
         api.setToken(null);
-        api.setWorkspaceId(null);
+        setCurrentWorkspace(null, null);
         storage.removeItem("multica_token");
-        storage.removeItem("multica_workspace_id");
         onLogout?.();
         useAuthStore.setState({ user: null, isLoading: false });
       });

packages/core/platform/core-provider.tsx

@@ -4,7 +4,6 @@ import { useMemo } from "react";
 import { ApiClient } from "../api/client";
 import { setApiInstance } from "../api";
 import { createAuthStore, registerAuthStore } from "../auth";
-import { createWorkspaceStore, registerWorkspaceStore } from "../workspace";
 import { createChatStore, registerChatStore } from "../chat";
 import { WSProvider } from "../realtime";
 import { QueryProvider } from "../provider";
@@ -18,7 +17,6 @@ import type { StorageAdapter } from "../types/storage";
 // Vite HMR preserves module-level state, so these survive hot reloads.
 let initialized = false;
 let authStore: ReturnType<typeof createAuthStore>;
-let workspaceStore: ReturnType<typeof createWorkspaceStore>;
 let chatStore: ReturnType<typeof createChatStore>;
 function initCore(
   apiBaseUrl: string,
@@ -33,7 +31,6 @@ function initCore(
     logger: createLogger("api"),
     onUnauthorized: () => {
       storage.removeItem("multica_token");
-      storage.removeItem("multica_workspace_id");
     },
   });
   setApiInstance(api);
@@ -43,15 +40,14 @@ function initCore(
     const token = storage.getItem("multica_token");
     if (token) api.setToken(token);
   }
-  const wsId = storage.getItem("multica_workspace_id");
-  if (wsId) api.setWorkspaceId(wsId);
+  // Workspace identity is URL-driven: the [workspaceSlug] layout resolves
+  // the slug and calls setCurrentWorkspace(slug, wsId) on mount. The api
+  // client reads the slug from that singleton for the X-Workspace-Slug
+  // header. No boot-time hydration from storage is required.
 
   authStore = createAuthStore({ api, storage, onLogin, onLogout, cookieAuth });
   registerAuthStore(authStore);
 
-  workspaceStore = createWorkspaceStore(api, { storage });
-  registerWorkspaceStore(workspaceStore);
-
   chatStore = createChatStore({ storage });
   registerChatStore(chatStore);
 
@@ -78,7 +74,6 @@ export function CoreProvider({
         <WSProvider
           wsUrl={wsUrl}
           authStore={authStore}
-          workspaceStore={workspaceStore}
           storage={storage}
           cookieAuth={cookieAuth}
         >

packages/core/platform/index.ts

@@ -3,5 +3,5 @@ export type { CoreProviderProps } from "./types";
 export { AuthInitializer } from "./auth-initializer";
 export { defaultStorage } from "./storage";
 export { createPersistStorage } from "./persist-storage";
-export { createWorkspaceAwareStorage, setCurrentWorkspaceId, getCurrentWorkspaceId, registerForWorkspaceRehydration, rehydrateAllWorkspaceStores } from "./workspace-storage";
+export { createWorkspaceAwareStorage, setCurrentWorkspace, getCurrentSlug, getCurrentWsId, subscribeToCurrentSlug, registerForWorkspaceRehydration } from "./workspace-storage";
 export { clearWorkspaceStorage } from "./storage-cleanup";

packages/core/platform/storage-cleanup.test.ts

@@ -19,6 +19,7 @@ describe("clearWorkspaceStorage", () => {
     expect(adapter.removeItem).toHaveBeenCalledWith("multica:chat:activeSessionId:ws_123");
     expect(adapter.removeItem).toHaveBeenCalledWith("multica:chat:drafts:ws_123");
     expect(adapter.removeItem).toHaveBeenCalledWith("multica:chat:expanded:ws_123");
-    expect(adapter.removeItem).toHaveBeenCalledTimes(8);
+    expect(adapter.removeItem).toHaveBeenCalledWith("multica_navigation:ws_123");
+    expect(adapter.removeItem).toHaveBeenCalledTimes(9);
   });
 });

packages/core/platform/storage-cleanup.ts

@@ -1,7 +1,7 @@
 import type { StorageAdapter } from "../types/storage";
 
 /**
- * Keys that are namespaced per workspace (stored as `${key}:${wsId}`).
+ * Keys that are namespaced per workspace (stored as `${key}:${slug}`).
  *
  * IMPORTANT: When adding a new workspace-scoped persist store or storage key,
  * add its key here so that workspace deletion and logout properly clean it up.
@@ -16,14 +16,15 @@ const WORKSPACE_SCOPED_KEYS = [
   "multica:chat:activeSessionId",
   "multica:chat:drafts",
   "multica:chat:expanded",
+  "multica_navigation",
 ];
 
-/** Remove all workspace-scoped storage entries for the given workspace. */
+/** Remove all workspace-scoped storage entries for the given workspace slug. */
 export function clearWorkspaceStorage(
   adapter: StorageAdapter,
-  wsId: string,
+  slug: string,
 ) {
   for (const key of WORKSPACE_SCOPED_KEYS) {
-    adapter.removeItem(`${key}:${wsId}`);
+    adapter.removeItem(`${key}:${slug}`);
   }
 }

packages/core/platform/workspace-storage.test.ts

@@ -1,5 +1,9 @@
 import { describe, it, expect, vi, afterEach } from "vitest";
-import { createWorkspaceAwareStorage, setCurrentWorkspaceId } from "./workspace-storage";
+import {
+  createWorkspaceAwareStorage,
+  setCurrentWorkspace,
+  registerForWorkspaceRehydration,
+} from "./workspace-storage";
 import type { StorageAdapter } from "../types/storage";
 
 function mockAdapter(): StorageAdapter {
@@ -12,50 +16,104 @@ function mockAdapter(): StorageAdapter {
 }
 
 afterEach(() => {
-  setCurrentWorkspaceId(null);
+  setCurrentWorkspace(null, null);
 });
 
 describe("workspace-aware storage", () => {
   it("uses plain key when no workspace is set", () => {
     const adapter = mockAdapter();
-    setCurrentWorkspaceId(null);
+    setCurrentWorkspace(null, null);
     const storage = createWorkspaceAwareStorage(adapter);
 
     storage.setItem("draft", "data");
     expect(adapter.setItem).toHaveBeenCalledWith("draft", "data");
   });
 
-  it("namespaces key when workspace is set", () => {
+  it("namespaces key with slug when workspace is set", () => {
     const adapter = mockAdapter();
-    setCurrentWorkspaceId("ws_abc");
+    setCurrentWorkspace("acme", "ws_abc");
     const storage = createWorkspaceAwareStorage(adapter);
 
     storage.setItem("draft", "data");
-    expect(adapter.setItem).toHaveBeenCalledWith("draft:ws_abc", "data");
+    expect(adapter.setItem).toHaveBeenCalledWith("draft:acme", "data");
 
     storage.getItem("draft");
-    expect(adapter.getItem).toHaveBeenCalledWith("draft:ws_abc");
+    expect(adapter.getItem).toHaveBeenCalledWith("draft:acme");
   });
 
   it("follows workspace changes dynamically", () => {
     const adapter = mockAdapter();
     const storage = createWorkspaceAwareStorage(adapter);
 
-    setCurrentWorkspaceId("ws_1");
+    setCurrentWorkspace("team-a", "ws_1");
     storage.setItem("draft", "v1");
-    expect(adapter.setItem).toHaveBeenCalledWith("draft:ws_1", "v1");
+    expect(adapter.setItem).toHaveBeenCalledWith("draft:team-a", "v1");
 
-    setCurrentWorkspaceId("ws_2");
+    setCurrentWorkspace("team-b", "ws_2");
     storage.setItem("draft", "v2");
-    expect(adapter.setItem).toHaveBeenCalledWith("draft:ws_2", "v2");
+    expect(adapter.setItem).toHaveBeenCalledWith("draft:team-b", "v2");
   });
 
-  it("removeItem uses current workspace", () => {
+  it("removeItem uses current workspace slug", () => {
     const adapter = mockAdapter();
-    setCurrentWorkspaceId("ws_x");
+    setCurrentWorkspace("dev", "ws_x");
     const storage = createWorkspaceAwareStorage(adapter);
 
     storage.removeItem("draft");
-    expect(adapter.removeItem).toHaveBeenCalledWith("draft:ws_x");
+    expect(adapter.removeItem).toHaveBeenCalledWith("draft:dev");
+  });
+});
+
+describe("setCurrentWorkspace — rehydrate side effect", () => {
+  const flush = () => new Promise((resolve) => queueMicrotask(() => resolve(null)));
+
+  it("runs registered fns once when slug changes", async () => {
+    const fn = vi.fn();
+    registerForWorkspaceRehydration(fn);
+
+    setCurrentWorkspace("team-a", "ws_a");
+    await flush();
+
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("is a no-op when slug is unchanged — repeat calls with same slug skip the side effect", async () => {
+    const fn = vi.fn();
+    registerForWorkspaceRehydration(fn);
+
+    setCurrentWorkspace("team-a", "ws_a");
+    await flush();
+    setCurrentWorkspace("team-a", "ws_a");
+    setCurrentWorkspace("team-a", "ws_a");
+    setCurrentWorkspace("team-a", "ws_a");
+    await flush();
+
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("runs again on real workspace switch", async () => {
+    const fn = vi.fn();
+    registerForWorkspaceRehydration(fn);
+
+    setCurrentWorkspace("team-a", "ws_a");
+    await flush();
+    setCurrentWorkspace("team-b", "ws_b");
+    await flush();
+
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it("runs again after logout → re-entry into same workspace", async () => {
+    const fn = vi.fn();
+    registerForWorkspaceRehydration(fn);
+
+    setCurrentWorkspace("team-a", "ws_a");
+    await flush();
+    setCurrentWorkspace(null, null);
+    await flush();
+    setCurrentWorkspace("team-a", "ws_a");
+    await flush();
+
+    expect(fn).toHaveBeenCalledTimes(3);
   });
 });

packages/core/platform/workspace-storage.ts

@@ -1,11 +1,89 @@
 import type { StateStorage } from "zustand/middleware";
 import type { StorageAdapter } from "../types/storage";
 
+// Paired module vars — always set/cleared together by the workspace layout.
+// _currentSlug is the primary identifier (matches the URL segment).
+// _currentWsId is derived (from the React Query workspace list) and used for
+// query keys and path-embedded API calls where UUID is required.
+let _currentSlug: string | null = null;
 let _currentWsId: string | null = null;
-const _rehydrateFns: Array<() => void> = [];
 
-export function setCurrentWorkspaceId(wsId: string | null) {
+const _rehydrateFns: Array<() => void> = [];
+const _slugSubscribers = new Set<(slug: string | null) => void>();
+let _pendingNotify = false;
+let _pendingRehydrate = false;
+
+/**
+ * Update the current workspace identity. This is the single source of truth
+ * for "which workspace is active"; everything downstream (WS connection,
+ * persist namespace, cache-key derivation) follows from here.
+ *
+ * If the slug actually changed, two side effects fire:
+ *   1. Subscribers are notified (e.g. WSProvider reconnects).
+ *   2. All registered persist stores rehydrate from the new slug's namespace.
+ *
+ * Both side effects are idempotent on slug-equality: repeat calls with the
+ * same slug are a pure no-op. This matters on desktop, where N tabs each
+ * mount their own WorkspaceRouteLayout and each one naively tries to sync;
+ * only the first call for a given slug does real work.
+ *
+ * Both side effects are deferred to a microtask because zustand persist
+ * rehydrate + subscriber notifications both end up calling setState(), and
+ * React 19 forbids "cross-component updates during render".
+ */
+export function setCurrentWorkspace(slug: string | null, wsId: string | null) {
+  if (_currentSlug === slug) {
+    // Slug unchanged: nothing to rehydrate, nothing to notify. Accept a
+    // (possibly) updated wsId for consumers that read the UUID mirror.
+    _currentWsId = wsId;
+    return;
+  }
+  _currentSlug = slug;
   _currentWsId = wsId;
+
+  if (!_pendingNotify) {
+    _pendingNotify = true;
+    queueMicrotask(() => {
+      _pendingNotify = false;
+      const current = _currentSlug;
+      for (const fn of _slugSubscribers) {
+        fn(current);
+      }
+    });
+  }
+
+  if (!_pendingRehydrate) {
+    _pendingRehydrate = true;
+    queueMicrotask(() => {
+      _pendingRehydrate = false;
+      for (const fn of _rehydrateFns) {
+        fn();
+      }
+    });
+  }
+}
+
+/** Current workspace slug (from URL). */
+export function getCurrentSlug(): string | null {
+  return _currentSlug;
+}
+
+/** Current workspace UUID (derived from slug + workspace list cache). */
+export function getCurrentWsId(): string | null {
+  return _currentWsId;
+}
+
+/**
+ * Subscribe to changes of the current workspace slug. Returns an unsubscribe
+ * function. Designed for React's `useSyncExternalStore` (WSProvider reconnect).
+ */
+export function subscribeToCurrentSlug(
+  fn: (slug: string | null) => void,
+): () => void {
+  _slugSubscribers.add(fn);
+  return () => {
+    _slugSubscribers.delete(fn);
+  };
 }
 
 /** Register a persist store's rehydrate function to be called on workspace switch. */
@@ -13,24 +91,13 @@ export function registerForWorkspaceRehydration(fn: () => void) {
   _rehydrateFns.push(fn);
 }
 
-/** Rehydrate all registered workspace-scoped persist stores from the new namespace. */
-export function rehydrateAllWorkspaceStores() {
-  for (const fn of _rehydrateFns) {
-    fn();
-  }
-}
-
-export function getCurrentWorkspaceId(): string | null {
-  return _currentWsId;
-}
-
 /**
- * Storage that automatically namespaces keys with the current workspace ID.
- * Reads _currentWsId at call time, so it follows workspace switches dynamically.
+ * Storage that automatically namespaces keys with the current workspace slug.
+ * Reads _currentSlug at call time, so it follows workspace switches dynamically.
  */
 export function createWorkspaceAwareStorage(adapter: StorageAdapter): StateStorage {
   const resolve = (key: string) =>
-    _currentWsId ? `${key}:${_currentWsId}` : key;
+    _currentSlug ? `${key}:${_currentSlug}` : key;
 
   return {
     getItem: (key) => adapter.getItem(resolve(key)),

packages/core/realtime/provider.tsx

@@ -6,13 +6,17 @@ import {
   useEffect,
   useState,
   useCallback,
+  useSyncExternalStore,
   type ReactNode,
 } from "react";
 import { WSClient } from "../api/ws-client";
 import type { WSEventType, StorageAdapter } from "../types";
 import type { StoreApi, UseBoundStore } from "zustand";
 import type { AuthState } from "../auth/store";
-import type { WorkspaceStore } from "../workspace/store";
+import {
+  getCurrentSlug,
+  subscribeToCurrentSlug,
+} from "../platform/workspace-storage";
 import { createLogger } from "../logger";
 import { useRealtimeSync, type RealtimeSyncStores } from "./use-realtime-sync";
 
@@ -31,8 +35,6 @@ export interface WSProviderProps {
   wsUrl: string;
   /** Platform-created auth store instance */
   authStore: UseBoundStore<StoreApi<AuthState>>;
-  /** Platform-created workspace store instance */
-  workspaceStore: UseBoundStore<StoreApi<WorkspaceStore>>;
   /** Platform-specific storage adapter for reading auth tokens */
   storage: StorageAdapter;
   /** When true, use HttpOnly cookies instead of token query param for WS auth. */
@@ -45,17 +47,25 @@ export function WSProvider({
   children,
   wsUrl,
   authStore,
-  workspaceStore,
   storage,
   cookieAuth,
   onToast,
 }: WSProviderProps) {
   const user = authStore((s) => s.user);
-  const workspace = workspaceStore((s) => s.workspace);
+  // Reactive read of the current workspace slug (URL-driven singleton in
+  // packages/core/platform/workspace-storage.ts). When the workspace switches,
+  // the useEffect below tears down the old WS connection and opens a new one
+  // bound to the new workspace slug. SSR snapshot is `null` because this
+  // provider only renders client-side under CoreProvider.
+  const wsSlug = useSyncExternalStore(
+    subscribeToCurrentSlug,
+    getCurrentSlug,
+    () => null,
+  );
   const [wsClient, setWsClient] = useState<WSClient | null>(null);
 
   useEffect(() => {
-    if (!user || !workspace) return;
+    if (!user || !wsSlug) return;
 
     // In token mode we need a token from storage; in cookie mode the HttpOnly
     // cookie is sent automatically with the WS upgrade request.
@@ -66,7 +76,7 @@ export function WSProvider({
       logger: createLogger("ws"),
       cookieAuth,
     });
-    ws.setAuth(token, workspace.id);
+    ws.setAuth(token, wsSlug);
     setWsClient(ws);
     ws.connect();
 
@@ -74,9 +84,9 @@ export function WSProvider({
       ws.disconnect();
       setWsClient(null);
     };
-  }, [user, workspace, wsUrl, storage, cookieAuth]);
+  }, [user, wsSlug, wsUrl, storage, cookieAuth]);
 
-  const stores: RealtimeSyncStores = { authStore, workspaceStore };
+  const stores: RealtimeSyncStores = { authStore };
 
   // Centralized WS -> store sync (uses state so it re-subscribes when WS changes)
   useRealtimeSync(wsClient, stores, onToast);

packages/core/realtime/use-realtime-sync.ts

@@ -5,10 +5,10 @@ import { useQueryClient } from "@tanstack/react-query";
 import type { WSClient } from "../api/ws-client";
 import type { StoreApi, UseBoundStore } from "zustand";
 import type { AuthState } from "../auth/store";
-import type { WorkspaceStore } from "../workspace/store";
 import { createLogger } from "../logger";
 import { clearWorkspaceStorage } from "../platform/storage-cleanup";
 import { defaultStorage } from "../platform/storage";
+import { getCurrentWsId, getCurrentSlug } from "../platform/workspace-storage";
 import { issueKeys } from "../issues/queries";
 import { projectKeys } from "../projects/queries";
 import { pinKeys } from "../pins/queries";
@@ -23,6 +23,7 @@ import { onInboxNew, onInboxInvalidate, onInboxIssueStatusChanged } from "../inb
 import { inboxKeys } from "../inbox/queries";
 import { workspaceKeys, workspaceListOptions } from "../workspace/queries";
 import { chatKeys } from "../chat/queries";
+import { paths } from "../paths";
 import type {
   MemberAddedPayload,
   WorkspaceDeletedPayload,
@@ -54,7 +55,6 @@ const logger = createLogger("realtime-sync");
 
 export interface RealtimeSyncStores {
   authStore: UseBoundStore<StoreApi<AuthState>>;
-  workspaceStore: UseBoundStore<StoreApi<WorkspaceStore>>;
 }
 
 /**
@@ -79,7 +79,7 @@ export function useRealtimeSync(
   stores: RealtimeSyncStores,
   onToast?: (message: string, type?: "info" | "error") => void,
 ) {
-  const { authStore, workspaceStore } = stores;
+  const { authStore } = stores;
   const qc = useQueryClient();
   // Main sync: onAny -> refreshMap with debounce
   useEffect(() => {
@@ -87,39 +87,39 @@ export function useRealtimeSync(
 
     const refreshMap: Record<string, () => void> = {
       inbox: () => {
-        const wsId = workspaceStore.getState().workspace?.id;
+        const wsId = getCurrentWsId();
         if (wsId) onInboxInvalidate(qc, wsId);
       },
       agent: () => {
-        const wsId = workspaceStore.getState().workspace?.id;
+        const wsId = getCurrentWsId();
         if (wsId) qc.invalidateQueries({ queryKey: workspaceKeys.agents(wsId) });
       },
       member: () => {
-        const wsId = workspaceStore.getState().workspace?.id;
+        const wsId = getCurrentWsId();
         if (wsId) qc.invalidateQueries({ queryKey: workspaceKeys.members(wsId) });
       },
       workspace: () => {
         qc.invalidateQueries({ queryKey: workspaceKeys.list() });
       },
       skill: () => {
-        const wsId = workspaceStore.getState().workspace?.id;
+        const wsId = getCurrentWsId();
         if (wsId) qc.invalidateQueries({ queryKey: workspaceKeys.skills(wsId) });
       },
       project: () => {
-        const wsId = workspaceStore.getState().workspace?.id;
+        const wsId = getCurrentWsId();
         if (wsId) qc.invalidateQueries({ queryKey: projectKeys.all(wsId) });
       },
       pin: () => {
-        const wsId = workspaceStore.getState().workspace?.id;
+        const wsId = getCurrentWsId();
         const userId = authStore.getState().user?.id;
         if (wsId && userId) qc.invalidateQueries({ queryKey: pinKeys.all(wsId, userId) });
       },
       daemon: () => {
-        const wsId = workspaceStore.getState().workspace?.id;
+        const wsId = getCurrentWsId();
         if (wsId) qc.invalidateQueries({ queryKey: runtimeKeys.all(wsId) });
       },
       autopilot: () => {
-        const wsId = workspaceStore.getState().workspace?.id;
+        const wsId = getCurrentWsId();
         if (wsId) qc.invalidateQueries({ queryKey: autopilotKeys.all(wsId) });
       },
     };
@@ -166,7 +166,7 @@ export function useRealtimeSync(
     const unsubIssueUpdated = ws.on("issue:updated", (p) => {
       const { issue } = p as IssueUpdatedPayload;
       if (!issue?.id) return;
-      const wsId = workspaceStore.getState().workspace?.id;
+      const wsId = getCurrentWsId();
       if (wsId) {
         onIssueUpdated(qc, wsId, issue);
         if (issue.status) {
@@ -178,21 +178,21 @@ export function useRealtimeSync(
     const unsubIssueCreated = ws.on("issue:created", (p) => {
       const { issue } = p as IssueCreatedPayload;
       if (!issue) return;
-      const wsId = workspaceStore.getState().workspace?.id;
+      const wsId = getCurrentWsId();
       if (wsId) onIssueCreated(qc, wsId, issue);
     });
 
     const unsubIssueDeleted = ws.on("issue:deleted", (p) => {
       const { issue_id } = p as IssueDeletedPayload;
       if (!issue_id) return;
-      const wsId = workspaceStore.getState().workspace?.id;
+      const wsId = getCurrentWsId();
       if (wsId) onIssueDeleted(qc, wsId, issue_id);
     });
 
     const unsubInboxNew = ws.on("inbox:new", (p) => {
       const { item } = p as InboxNewPayload;
       if (!item) return;
-      const wsId = workspaceStore.getState().workspace?.id;
+      const wsId = getCurrentWsId();
       if (wsId) onInboxNew(qc, wsId, item);
     });
 
@@ -260,16 +260,35 @@ export function useRealtimeSync(
 
     // --- Side-effect handlers (toast, navigation) ---
 
+    // After the current workspace disappears (deleted or we were kicked out),
+    // navigate to another workspace the user still has access to, or to the
+    // create-workspace page. We use a full-page navigation: this reliably
+    // tears down any in-flight queries / subscriptions tied to the dead
+    // workspace without relying on framework-specific routers from here in
+    // core.
+    const relocateAfterWorkspaceLoss = async (lostWsId: string) => {
+      const wsList = await qc.fetchQuery({
+        ...workspaceListOptions(),
+        staleTime: 0,
+      });
+      const next = wsList.find((w) => w.id !== lostWsId);
+      const target = next ? paths.workspace(next.slug).issues() : paths.newWorkspace();
+      if (typeof window !== "undefined") {
+        window.location.assign(target);
+      }
+    };
+
     const unsubWsDeleted = ws.on("workspace:deleted", (p) => {
       const { workspace_id } = p as WorkspaceDeletedPayload;
-      clearWorkspaceStorage(defaultStorage, workspace_id);
-      const currentWs = workspaceStore.getState().workspace;
-      if (currentWs?.id === workspace_id) {
+      // Event payload has UUID; look up slug from cached workspace list
+      // since clearWorkspaceStorage keys are namespaced by slug.
+      const wsList = qc.getQueryData<{ id: string; slug: string }[]>(workspaceKeys.list()) ?? [];
+      const deletedSlug = wsList.find((w) => w.id === workspace_id)?.slug;
+      if (deletedSlug) clearWorkspaceStorage(defaultStorage, deletedSlug);
+      if (getCurrentWsId() === workspace_id) {
         logger.warn("current workspace deleted, switching");
         onToast?.("This workspace was deleted", "info");
-        qc.fetchQuery({ ...workspaceListOptions(), staleTime: 0 }).then((wsList) => {
-          workspaceStore.getState().hydrateWorkspace(wsList);
-        });
+        relocateAfterWorkspaceLoss(workspace_id);
       }
     });
 
@@ -277,13 +296,14 @@ export function useRealtimeSync(
       const { user_id } = p as MemberRemovedPayload;
       const myUserId = authStore.getState().user?.id;
       if (user_id === myUserId) {
-        const wsId = workspaceStore.getState().workspace?.id;
-        if (wsId) clearWorkspaceStorage(defaultStorage, wsId);
-        logger.warn("removed from workspace, switching");
-        onToast?.("You were removed from this workspace", "info");
-        qc.fetchQuery({ ...workspaceListOptions(), staleTime: 0 }).then((wsList) => {
-          workspaceStore.getState().hydrateWorkspace(wsList);
-        });
+        const slug = getCurrentSlug();
+        const wsId = getCurrentWsId();
+        if (slug && wsId) {
+          clearWorkspaceStorage(defaultStorage, slug);
+          logger.warn("removed from workspace, switching");
+          onToast?.("You were removed from this workspace", "info");
+          relocateAfterWorkspaceLoss(wsId);
+        }
       }
     });
 
@@ -312,14 +332,14 @@ export function useRealtimeSync(
 
     // invitation:accepted / declined / revoked — refresh invitation lists
     const unsubInvitationAccepted = ws.on("invitation:accepted", () => {
-      const currentWsId = workspaceStore.getState().workspace?.id;
+      const currentWsId = getCurrentWsId();
       if (currentWsId) {
         qc.invalidateQueries({ queryKey: workspaceKeys.invitations(currentWsId) });
         qc.invalidateQueries({ queryKey: workspaceKeys.members(currentWsId) });
       }
     });
     const unsubInvitationDeclined = ws.on("invitation:declined", () => {
-      const currentWsId = workspaceStore.getState().workspace?.id;
+      const currentWsId = getCurrentWsId();
       if (currentWsId) {
         qc.invalidateQueries({ queryKey: workspaceKeys.invitations(currentWsId) });
       }
@@ -357,11 +377,11 @@ export function useRealtimeSync(
 
     // Helpers reused by chat lifecycle handlers.
     const invalidatePendingAggregate = () => {
-      const id = workspaceStore.getState().workspace?.id;
+      const id = getCurrentWsId();
       if (id) qc.invalidateQueries({ queryKey: chatKeys.pendingTasks(id) });
     };
     const invalidateSessionLists = () => {
-      const id = workspaceStore.getState().workspace?.id;
+      const id = getCurrentWsId();
       if (id) {
         qc.invalidateQueries({ queryKey: chatKeys.sessions(id) });
         qc.invalidateQueries({ queryKey: chatKeys.allSessions(id) });
@@ -457,7 +477,7 @@ export function useRealtimeSync(
       timers.forEach(clearTimeout);
       timers.clear();
     };
-  }, [ws, qc, authStore, workspaceStore, onToast]);
+  }, [ws, qc, authStore, onToast]);
 
   // Reconnect -> refetch all data to recover missed events
   useEffect(() => {
@@ -466,7 +486,7 @@ export function useRealtimeSync(
     const unsub = ws.onReconnect(async () => {
       logger.info("reconnected, refetching all data");
       try {
-        const wsId = workspaceStore.getState().workspace?.id;
+        const wsId = getCurrentWsId();
         if (wsId) {
           qc.invalidateQueries({ queryKey: issueKeys.all(wsId) });
           qc.invalidateQueries({ queryKey: inboxKeys.all(wsId) });
@@ -484,5 +504,5 @@ export function useRealtimeSync(
     });
 
     return unsub;
-  }, [ws, qc, workspaceStore]);
+  }, [ws, qc]);
 }

packages/core/workspace/index.ts

@@ -1,41 +1,3 @@
-export * from "./store";
 export * from "./queries";
 export * from "./mutations";
 export * from "./hooks";
-
-import type { createWorkspaceStore as CreateWorkspaceStoreFn } from "./store";
-
-type WorkspaceStoreInstance = ReturnType<typeof CreateWorkspaceStoreFn>;
-
-/** Module-level singleton — set once at app boot via `registerWorkspaceStore()`. */
-let _store: WorkspaceStoreInstance | null = null;
-
-/**
- * Register the workspace store instance created by the app.
- * Must be called at boot before any component renders.
- */
-export function registerWorkspaceStore(store: WorkspaceStoreInstance) {
-  _store = store;
-}
-
-/**
- * Singleton accessor — a Zustand hook backed by the registered instance.
- * Supports `useWorkspaceStore(selector)` and `useWorkspaceStore.getState()`.
- */
-export const useWorkspaceStore: WorkspaceStoreInstance = new Proxy(
-  (() => {}) as unknown as WorkspaceStoreInstance,
-  {
-    apply(_target, _thisArg, args) {
-      if (!_store)
-        throw new Error(
-          "Workspace store not initialised — call registerWorkspaceStore() first",
-        );
-      return (_store as unknown as (...a: unknown[]) => unknown)(...args);
-    },
-    get(_target, prop) {
-      // Allow property inspection (HMR/React Refresh) before registration
-      if (!_store) return undefined;
-      return Reflect.get(_store, prop);
-    },
-  },
-);

packages/core/workspace/mutations.ts

@@ -1,18 +1,23 @@
 import { useMutation, useQueryClient } from "@tanstack/react-query";
 import type { Workspace } from "../types";
 import { api } from "../api";
-import { workspaceKeys, workspaceListOptions } from "./queries";
-import { useWorkspaceStore } from "./index";
+import { workspaceKeys } from "./queries";
 
 export function useCreateWorkspace() {
   const qc = useQueryClient();
   return useMutation({
     mutationFn: (data: { name: string; slug: string; description?: string }) =>
       api.createWorkspace(data),
+    // Seed the workspace list cache BEFORE callers navigate to /{newWs.slug}/issues.
+    // The destination [workspaceSlug]/layout queries by slug from this cache;
+    // without seeding, it would briefly show "loading" before the background
+    // invalidation completes. TanStack Query guarantees this onSuccess runs
+    // before mutateAsync's resolver / before any callback-style onSuccess
+    // passed to mutate(), so any caller that navigates after the mutation
+    // resolves will see the seeded data synchronously. Switching workspaces
+    // is pure navigation now — no imperative store writes needed.
     onSuccess: (newWs) => {
-      // Add to cache before switching so sidebar list is consistent on first render
       qc.setQueryData(workspaceKeys.list(), (old: Workspace[] = []) => [...old, newWs]);
-      useWorkspaceStore.getState().switchWorkspace(newWs);
     },
     onSettled: () => {
       qc.invalidateQueries({ queryKey: workspaceKeys.list() });
@@ -24,14 +29,6 @@ export function useLeaveWorkspace() {
   const qc = useQueryClient();
   return useMutation({
     mutationFn: (workspaceId: string) => api.leaveWorkspace(workspaceId),
-    onSuccess: async (_, workspaceId) => {
-      const currentWsId = useWorkspaceStore.getState().workspace?.id;
-      if (currentWsId === workspaceId) {
-        // staleTime: 0 forces a real network fetch — cache still has the left workspace
-        const wsList = await qc.fetchQuery({ ...workspaceListOptions(), staleTime: 0 });
-        useWorkspaceStore.getState().hydrateWorkspace(wsList);
-      }
-    },
     onSettled: () => {
       qc.invalidateQueries({ queryKey: workspaceKeys.list() });
     },
@@ -42,14 +39,6 @@ export function useDeleteWorkspace() {
   const qc = useQueryClient();
   return useMutation({
     mutationFn: (workspaceId: string) => api.deleteWorkspace(workspaceId),
-    onSuccess: async (_, workspaceId) => {
-      const currentWsId = useWorkspaceStore.getState().workspace?.id;
-      if (currentWsId === workspaceId) {
-        // staleTime: 0 forces a real network fetch — cache still has the deleted workspace
-        const wsList = await qc.fetchQuery({ ...workspaceListOptions(), staleTime: 0 });
-        useWorkspaceStore.getState().hydrateWorkspace(wsList);
-      }
-    },
     onSettled: () => {
       qc.invalidateQueries({ queryKey: workspaceKeys.list() });
     },

packages/core/workspace/queries.ts

@@ -1,5 +1,6 @@
 import { queryOptions } from "@tanstack/react-query";
 import { api } from "../api";
+import type { Workspace } from "../types";
 
 export const workspaceKeys = {
   all: (wsId: string) => ["workspaces", wsId] as const,
@@ -19,6 +20,14 @@ export function workspaceListOptions() {
   });
 }
 
+/** Resolves the workspace whose slug matches, from the cached workspace list. */
+export function workspaceBySlugOptions(slug: string) {
+  return queryOptions({
+    ...workspaceListOptions(),
+    select: (list: Workspace[]) => list.find((w) => w.slug === slug) ?? null,
+  });
+}
+
 export function memberListOptions(wsId: string) {
   return queryOptions({
     queryKey: workspaceKeys.members(wsId),

packages/core/workspace/store.ts

@@ -1,92 +0,0 @@
-import { create } from "zustand";
-import type { Workspace, StorageAdapter } from "../types";
-import type { ApiClient } from "../api/client";
-import { createLogger } from "../logger";
-import { setCurrentWorkspaceId, rehydrateAllWorkspaceStores } from "../platform/workspace-storage";
-
-const logger = createLogger("workspace-store");
-
-interface WorkspaceStoreOptions {
-  storage?: StorageAdapter;
-}
-
-interface WorkspaceState {
-  workspace: Workspace | null;
-}
-
-interface WorkspaceActions {
-  /**
-   * Pick a workspace from a list and set it as current.
-   * The list itself is NOT stored here — it lives in React Query.
-   */
-  hydrateWorkspace: (
-    wsList: Workspace[],
-    preferredWorkspaceId?: string | null,
-  ) => Workspace | null;
-  /** Switch to a workspace. Caller provides the full object (from React Query). */
-  switchWorkspace: (ws: Workspace) => void;
-  /** Update current workspace data in place (e.g. after rename). */
-  updateWorkspace: (ws: Workspace) => void;
-  clearWorkspace: () => void;
-}
-
-export type WorkspaceStore = WorkspaceState & WorkspaceActions;
-
-export function createWorkspaceStore(api: ApiClient, options?: WorkspaceStoreOptions) {
-  const storage = options?.storage;
-
-  return create<WorkspaceStore>((set) => ({
-    // Only the currently selected workspace (UI state).
-    // The workspace list is server state and lives in React Query.
-    workspace: null,
-
-    hydrateWorkspace: (wsList, preferredWorkspaceId) => {
-      const nextWorkspace =
-        (preferredWorkspaceId
-          ? wsList.find((item) => item.id === preferredWorkspaceId)
-          : null) ??
-        wsList[0] ??
-        null;
-
-      if (!nextWorkspace) {
-        api.setWorkspaceId(null);
-        setCurrentWorkspaceId(null);
-        rehydrateAllWorkspaceStores();
-        storage?.removeItem("multica_workspace_id");
-        set({ workspace: null });
-        return null;
-      }
-
-      api.setWorkspaceId(nextWorkspace.id);
-      setCurrentWorkspaceId(nextWorkspace.id);
-      rehydrateAllWorkspaceStores();
-      storage?.setItem("multica_workspace_id", nextWorkspace.id);
-      set({ workspace: nextWorkspace });
-      logger.debug("hydrate workspace", nextWorkspace.name, nextWorkspace.id);
-
-      return nextWorkspace;
-    },
-
-    switchWorkspace: (ws) => {
-      logger.info("switching to", ws.id);
-      api.setWorkspaceId(ws.id);
-      setCurrentWorkspaceId(ws.id);
-      rehydrateAllWorkspaceStores();
-      storage?.setItem("multica_workspace_id", ws.id);
-      set({ workspace: ws });
-    },
-
-    updateWorkspace: (ws) => {
-      set((state) => ({
-        workspace: state.workspace?.id === ws.id ? ws : state.workspace,
-      }));
-    },
-
-    clearWorkspace: () => {
-      api.setWorkspaceId(null);
-      setCurrentWorkspaceId(null);
-      rehydrateAllWorkspaceStores();
-      set({ workspace: null });
-    },
-  }));
-}

packages/ui/components/ui/sidebar.tsx

@@ -353,7 +353,7 @@ function SidebarInset({ className, ...props }: React.ComponentProps<"main">) {
     <main
       data-slot="sidebar-inset"
       className={cn(
-        "relative flex w-full flex-1 flex-col bg-background md:peer-data-[variant=inset]:m-2 md:peer-data-[variant=inset]:ml-0 md:peer-data-[variant=inset]:rounded-xl md:peer-data-[variant=inset]:shadow-sm md:peer-data-[variant=inset]:peer-data-[state=collapsed]:ml-2",
+        "relative flex w-full flex-1 flex-col bg-background md:peer-data-[variant=inset]:m-2 md:peer-data-[variant=inset]:ml-0 md:peer-data-[variant=inset]:rounded-xl md:peer-data-[variant=inset]:peer-data-[state=collapsed]:ml-2",
         className
       )}
       {...props}

packages/ui/components/ui/tooltip.tsx

@@ -5,7 +5,7 @@ import { Tooltip as TooltipPrimitive } from "@base-ui/react/tooltip"
 import { cn } from "@multica/ui/lib/utils"
 
 function TooltipProvider({
-  delay = 0,
+  delay = 200,
   ...props
 }: TooltipPrimitive.Provider.Props) {
   return (
@@ -50,13 +50,12 @@ function TooltipContent({
         <TooltipPrimitive.Popup
           data-slot="tooltip-content"
           className={cn(
-            "z-50 inline-flex w-fit max-w-xs origin-(--transform-origin) items-center gap-1.5 rounded-md bg-foreground px-3 py-1.5 text-xs text-background has-data-[slot=kbd]:pr-1.5 data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 **:data-[slot=kbd]:relative **:data-[slot=kbd]:isolate **:data-[slot=kbd]:z-50 **:data-[slot=kbd]:rounded-sm data-[state=delayed-open]:animate-in data-[state=delayed-open]:fade-in-0 data-[state=delayed-open]:zoom-in-95 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
+            "z-50 inline-flex w-fit max-w-xs origin-(--transform-origin) items-center gap-1.5 rounded-lg border border-border bg-popover px-2.5 py-1 text-xs text-popover-foreground has-data-[slot=kbd]:pr-1.5 data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 **:data-[slot=kbd]:relative **:data-[slot=kbd]:isolate **:data-[slot=kbd]:z-50 **:data-[slot=kbd]:rounded-sm data-[state=delayed-open]:animate-in data-[state=delayed-open]:fade-in-0 data-[state=delayed-open]:zoom-in-95 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
             className
           )}
           {...props}
         >
           {children}
-          <TooltipPrimitive.Arrow className="z-50 size-2.5 translate-y-[calc(-50%-2px)] rotate-45 rounded-[2px] bg-foreground fill-foreground data-[side=bottom]:top-1 data-[side=inline-end]:top-1/2! data-[side=inline-end]:-left-1 data-[side=inline-end]:-translate-y-1/2 data-[side=inline-start]:top-1/2! data-[side=inline-start]:-right-1 data-[side=inline-start]:-translate-y-1/2 data-[side=left]:top-1/2! data-[side=left]:-right-1 data-[side=left]:-translate-y-1/2 data-[side=right]:top-1/2! data-[side=right]:-left-1 data-[side=right]:-translate-y-1/2 data-[side=top]:-bottom-2.5" />
         </TooltipPrimitive.Popup>
       </TooltipPrimitive.Positioner>
     </TooltipPrimitive.Portal>

packages/ui/styles/tokens.css

@@ -27,7 +27,6 @@
     --color-brand: var(--brand);
     --color-brand-foreground: var(--brand-foreground);
     --color-priority: var(--priority);
-    --color-canvas: var(--canvas);
     --color-accent-foreground: var(--accent-foreground);
     --color-accent: var(--accent);
     --color-muted-foreground: var(--muted-foreground);
@@ -86,7 +85,6 @@
     --sidebar-ring: oklch(0.705 0.015 286.067);
     --brand: oklch(0.55 0.16 255);
     --brand-foreground: oklch(0.985 0 0);
-    --canvas: oklch(0.95 0.002 286);
     --success: oklch(0.55 0.16 145);
     --warning: oklch(0.75 0.16 85);
     --info: oklch(0.55 0.18 250);
@@ -130,7 +128,6 @@
     --sidebar-ring: oklch(0.552 0.016 285.938);
     --brand: oklch(0.65 0.16 255);
     --brand-foreground: oklch(0.985 0 0);
-    --canvas: oklch(0.2 0.005 286);
     --success: oklch(0.65 0.15 145);
     --warning: oklch(0.70 0.16 85);
     --info: oklch(0.65 0.18 250);

packages/views/agents/components/agents-page.tsx

@@ -18,6 +18,7 @@ import { runtimeListOptions } from "@multica/core/runtimes/queries";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
 import { useWorkspaceId } from "@multica/core/hooks";
 import { agentListOptions, memberListOptions, workspaceKeys } from "@multica/core/workspace/queries";
+import { PageHeader } from "../../layout/page-header";
 import { CreateAgentDialog } from "./create-agent-dialog";
 import { AgentListItem } from "./agent-list-item";
 import { AgentDetail } from "./agent-detail";
@@ -140,28 +141,28 @@ export function AgentsPage() {
       <ResizablePanel id="list" defaultSize={280} minSize={240} maxSize={400} groupResizeBehavior="preserve-pixel-size">
         {/* Left column — agent list */}
         <div className="overflow-y-auto h-full border-r">
-          <div className="flex h-12 items-center justify-between border-b px-4">
+          <PageHeader className="justify-between">
             <h1 className="text-sm font-semibold">Agents</h1>
             <div className="flex items-center gap-1">
               {archivedCount > 0 && (
                 <Button
                   variant={showArchived ? "secondary" : "ghost"}
-                  size="icon-xs"
+                  size="icon-sm"
                   onClick={() => setShowArchived(!showArchived)}
                   title={showArchived ? "Show active agents" : "Show archived agents"}
                 >
-                  <Archive className="h-4 w-4 text-muted-foreground" />
+                  <Archive className="text-muted-foreground" />
                 </Button>
               )}
               <Button
                 variant="ghost"
-                size="icon-xs"
+                size="icon-sm"
                 onClick={() => setShowCreate(true)}
               >
-                <Plus className="h-4 w-4 text-muted-foreground" />
+                <Plus className="text-muted-foreground" />
               </Button>
             </div>
-          </div>
+          </PageHeader>
           {filteredAgents.length === 0 ? (
             <div className="flex flex-col items-center justify-center px-4 py-12">
               <Bot className="h-8 w-8 text-muted-foreground/40" />

packages/views/agents/components/tabs/skills-tab.tsx

@@ -125,7 +125,7 @@ export function SkillsTab({
               </div>
               <Button
                 variant="ghost"
-                size="icon-xs"
+                size="icon-sm"
                 onClick={() => handleRemove(skill.id)}
                 disabled={saving}
                 className="text-muted-foreground hover:text-destructive"

packages/views/auth/login-page.test.tsx

@@ -8,7 +8,6 @@ import userEvent from "@testing-library/user-event";
 
 const mockSendCode = vi.hoisted(() => vi.fn());
 const mockVerifyCode = vi.hoisted(() => vi.fn());
-const mockHydrateWorkspace = vi.hoisted(() => vi.fn());
 const mockApiListWorkspaces = vi.hoisted(() => vi.fn());
 const mockApiVerifyCode = vi.hoisted(() => vi.fn());
 const mockApiSetToken = vi.hoisted(() => vi.fn());
@@ -39,20 +38,6 @@ vi.mock("@multica/core/auth", () => ({
   ),
 }));
 
-vi.mock("@multica/core/workspace", () => ({
-  useWorkspaceStore: Object.assign(
-    (selector?: (s: unknown) => unknown) => {
-      const state = { hydrateWorkspace: mockHydrateWorkspace };
-      return selector ? selector(state) : state;
-    },
-    {
-      getState: () => ({
-        hydrateWorkspace: mockHydrateWorkspace,
-      }),
-    },
-  ),
-}));
-
 vi.mock("@multica/core/api", () => ({
   api: {
     listWorkspaces: mockApiListWorkspaces,
@@ -224,11 +209,10 @@ describe("LoginPage", () => {
   // Code verification
   // -------------------------------------------------------------------------
 
-  it("calls verifyCode, listWorkspaces, hydrateWorkspace, then onSuccess", async () => {
+  it("calls verifyCode, seeds workspace list cache, then onSuccess", async () => {
     mockSendCode.mockResolvedValueOnce(undefined);
     mockVerifyCode.mockResolvedValueOnce(undefined);
     mockApiListWorkspaces.mockResolvedValueOnce([{ id: "ws-1" }]);
-    mockHydrateWorkspace.mockReturnValueOnce({ id: "ws-1" });
 
     render(<LoginPage onSuccess={onSuccess} />);
 
@@ -253,9 +237,11 @@ describe("LoginPage", () => {
         "123456",
       );
       expect(mockApiListWorkspaces).toHaveBeenCalled();
-      expect(mockHydrateWorkspace).toHaveBeenCalledWith(
+      // The workspace list is seeded into React Query so onSuccess can read
+      // it synchronously to compute a destination URL.
+      expect(mockSetQueryData).toHaveBeenCalledWith(
+        expect.arrayContaining(["workspaces", "list"]),
         [{ id: "ws-1" }],
-        undefined,
       );
       expect(onSuccess).toHaveBeenCalled();
     });
@@ -620,7 +606,6 @@ describe("LoginPage", () => {
     mockSendCode.mockResolvedValueOnce(undefined);
     mockVerifyCode.mockResolvedValueOnce(undefined);
     mockApiListWorkspaces.mockResolvedValueOnce([{ id: "ws-1" }]);
-    mockHydrateWorkspace.mockReturnValueOnce({ id: "ws-1" });
     const onTokenObtained = vi.fn();
 
     render(
@@ -674,43 +659,6 @@ describe("LoginPage", () => {
     ).toBeInTheDocument();
   });
 
-  // -------------------------------------------------------------------------
-  // lastWorkspaceId
-  // -------------------------------------------------------------------------
-
-  it("passes lastWorkspaceId to hydrateWorkspace", async () => {
-    mockSendCode.mockResolvedValueOnce(undefined);
-    mockVerifyCode.mockResolvedValueOnce(undefined);
-    mockApiListWorkspaces.mockResolvedValueOnce([
-      { id: "ws-1" },
-      { id: "ws-2" },
-    ]);
-    mockHydrateWorkspace.mockReturnValueOnce({ id: "ws-2" });
-
-    render(
-      <LoginPage onSuccess={onSuccess} lastWorkspaceId="ws-2" />,
-    );
-
-    const user = userEvent.setup();
-    await user.type(screen.getByLabelText(/email/i), "test@example.com");
-    await user.click(screen.getByRole("button", { name: /continue/i }));
-
-    await waitFor(() => {
-      expect(
-        screen.getByText(/check your email/i),
-      ).toBeInTheDocument();
-    });
-
-    const otpInput = getOTPInput();
-    await user.type(otpInput, "123456");
-
-    await waitFor(() => {
-      expect(mockHydrateWorkspace).toHaveBeenCalledWith(
-        [{ id: "ws-1" }, { id: "ws-2" }],
-        "ws-2",
-      );
-    });
-  });
 });
 
 // ---------------------------------------------------------------------------