fix(ui): replace smiley with check mark in quick emoji list (#1446)

Swap the 4th quick reply emoji 😄 for ✅ so approval-style
acknowledgements are one tap away.

.env.example

@@ -4,8 +4,23 @@ POSTGRES_USER=multica
 POSTGRES_PASSWORD=multica
 POSTGRES_PORT=5432
 DATABASE_URL=postgres://multica:multica@localhost:5432/multica?sslmode=disable
+# Optional pgxpool tuning. Defaults are 25 / 5 per pod and are usually fine.
+# You can also set pool_max_conns / pool_min_conns as query params on
+# DATABASE_URL; env vars below take precedence over URL params.
+# DATABASE_MAX_CONNS=25
+# DATABASE_MIN_CONNS=5
 
 # Server
+# APP_ENV gates dev-only auth shortcuts (primarily the 888888 master code).
+#   - Docker self-host: docker-compose.selfhost.yml already pins APP_ENV to
+#     "production" by default, so 888888 is DISABLED — a public instance can't
+#     be logged into with any email + 888888.
+#   - Local dev (make dev): leave APP_ENV unset so 888888 works out of the box.
+#   - Docker self-host on a private network you fully control, or evaluation
+#     without Resend: set APP_ENV=development to re-enable 888888. Do NOT
+#     enable on a publicly reachable instance.
+# See SELF_HOSTING.md for the full login setup.
+APP_ENV=
 PORT=8080
 JWT_SECRET=change-me-in-production
 MULTICA_SERVER_URL=ws://localhost:8080/ws
@@ -22,7 +37,8 @@ MULTICA_CODEX_WORKDIR=
 MULTICA_CODEX_TIMEOUT=20m
 
 # Email (Resend)
-# For local/dev use, leave RESEND_API_KEY empty — codes print to stdout, and master code 888888 works.
+# For local/dev use, leave RESEND_API_KEY empty — codes print to stdout, and
+# master code 888888 works (only when APP_ENV != "production"; see above).
 # For production, set your Resend API key and change RESEND_FROM_EMAIL to a domain verified in your Resend account.
 RESEND_API_KEY=
 RESEND_FROM_EMAIL=noreply@multica.ai
@@ -40,6 +56,13 @@ CLOUDFRONT_KEY_PAIR_ID=
 CLOUDFRONT_PRIVATE_KEY_SECRET=multica/cloudfront-signing-key
 CLOUDFRONT_PRIVATE_KEY=
 CLOUDFRONT_DOMAIN=
+# COOKIE_DOMAIN — optional Domain attribute on session + CloudFront cookies.
+# Leave empty for single-host deployments (localhost, LAN IP, or a single
+# hostname) — session cookies become host-only, which is what the browser
+# wants. Only set it when the frontend and backend sit on different
+# subdomains of one registered domain (e.g. ".example.com"). Do NOT set it
+# to an IP address: RFC 6265 forbids IP literals in the cookie Domain
+# attribute and browsers silently drop such cookies.
 COOKIE_DOMAIN=
 
 # Local file storage (fallback when S3_BUCKET is not set)
@@ -63,3 +86,27 @@ NEXT_PUBLIC_WS_URL=
 # Remote API (optional) — set to proxy local frontend to a remote backend
 # Leave empty to use local backend (localhost:8080)
 # REMOTE_API_URL=https://multica-api.copilothub.ai
+
+# ==================== Self-hosting: Control Signups (fixes #930) ====================
+# Set to "false" to completely disable new user signups (recommended for private instances)
+ALLOW_SIGNUP=true
+# Must match ALLOW_SIGNUP for the UI to reflect the same signup setting.
+# Note: in typical Next.js builds, NEXT_PUBLIC_* values are baked into the client bundle,
+# so changing this usually requires rebuilding/redeploying the frontend (not just restarting the backend).
+NEXT_PUBLIC_ALLOW_SIGNUP=true
+
+# Optional: Only allow emails from these domains (comma-separated)
+ALLOWED_EMAIL_DOMAINS=
+
+# Optional: Only allow these exact email addresses (comma-separated)
+ALLOWED_EMAILS=
+
+# ==================== Analytics (PostHog) ====================
+# Product analytics events feed the acquisition → activation → expansion funnel.
+# Leave POSTHOG_API_KEY empty for local dev / self-hosted instances; the server
+# will run a no-op analytics client and ship nothing. See docs/analytics.md.
+POSTHOG_API_KEY=
+POSTHOG_HOST=https://us.i.posthog.com
+# Force the no-op client even when POSTHOG_API_KEY is set (CI / opt-out).
+ANALYTICS_DISABLED=
+

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -3,6 +3,17 @@ description: Report a bug — something that's broken, crashes, or behaves incor
 title: "[Bug]: "
 labels: ["bug"]
 body:
+  - type: dropdown
+    id: deployment
+    attributes:
+      label: Deployment type
+      description: Are you using the hosted version or a self-hosted instance?
+      options:
+        - multica.ai (hosted)
+        - Self-hosted
+    validations:
+      required: true
+
   - type: textarea
     id: description
     attributes:

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -3,6 +3,17 @@ description: Suggest a new feature or improvement.
 title: "[Feature]: "
 labels: ["enhancement"]
 body:
+  - type: dropdown
+    id: deployment
+    attributes:
+      label: Deployment type
+      description: Are you using the hosted version or a self-hosted instance?
+      options:
+        - multica.ai (hosted)
+        - Self-hosted
+    validations:
+      required: true
+
   - type: textarea
     id: description
     attributes:

.github/workflows/ci.yml

@@ -30,7 +30,7 @@ jobs:
         run: pnpm install
 
       - name: Build, type check, and test
-        run: pnpm build && pnpm typecheck && pnpm test
+        run: pnpm exec turbo build typecheck test --filter='!@multica/docs'
 
   backend:
     runs-on: ubuntu-latest

.github/workflows/desktop-smoke.yml

@@ -0,0 +1,59 @@
+name: Desktop Smoke Build
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  desktop:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: linux
+          - os: windows-latest
+            target: win
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install rpmbuild (Linux)
+        if: matrix.target == 'linux'
+        run: sudo apt-get update && sudo apt-get install -y rpm
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: server/go.mod
+          cache-dependency-path: server/go.sum
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Package Desktop installers (${{ matrix.target }})
+        working-directory: apps/desktop
+        env:
+          CSC_IDENTITY_AUTO_DISCOVERY: "false"
+        run: node scripts/package.mjs --${{ matrix.target }} --x64 --arm64 --publish never
+
+      - name: Upload Desktop artifacts (${{ matrix.target }})
+        uses: actions/upload-artifact@v4
+        with:
+          name: desktop-${{ matrix.target }}
+          path: apps/desktop/dist
+          if-no-files-found: error

.github/workflows/release.yml

@@ -3,7 +3,10 @@ name: Release
 on:
   push:
     tags:
-      - "v*"
+      # GitHub Actions uses glob patterns here, not regex. Match versioned
+      # tags broadly at the trigger layer, then enforce strict semver below.
+      - "v*.*.*"
+      - "!v*-dirty*"
 
 permissions:
   contents: write
@@ -17,6 +20,19 @@ jobs:
         with:
           fetch-depth: 0
 
+      - name: Validate tag name
+        run: |
+          tag="${GITHUB_REF_NAME}"
+          echo "Triggered by tag: $tag"
+          if [[ ! "$tag" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
+            echo "::error::Release tags must look like vX.Y.Z or vX.Y.Z-suffix; got '$tag'."
+            exit 1
+          fi
+          if [[ "$tag" == *-dirty* ]]; then
+            echo "::error::Refusing to release from dirty tag '$tag'."
+            exit 1
+          fi
+
       - name: Setup Go
         uses: actions/setup-go@v5
         with:
@@ -34,3 +50,60 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           HOMEBREW_TAP_GITHUB_TOKEN: ${{ secrets.HOMEBREW_TAP_GITHUB_TOKEN }}
+
+  # Build the Desktop installers for Linux and Windows and upload them to
+  # the GitHub Release that the `release` job above just published. macOS
+  # Desktop continues to ship via the manual `release-desktop` skill so it
+  # can be signed + notarized with Apple Developer credentials that are
+  # not (yet) wired into CI.
+  desktop:
+    needs: release
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: linux
+          - os: windows-latest
+            target: win
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install rpmbuild (Linux)
+        if: matrix.target == 'linux'
+        run: sudo apt-get update && sudo apt-get install -y rpm
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: server/go.mod
+          cache-dependency-path: server/go.sum
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Package Desktop installers (${{ matrix.target }})
+        working-directory: apps/desktop
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # electron-builder's GitHub publisher reads this:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # Disable code signing on Linux/Windows for now — the public
+          # release is unsigned for these platforms, the CLI carries the
+          # trust boundary. Set CSC_LINK in repo secrets to enable
+          # Windows signing later.
+          CSC_IDENTITY_AUTO_DISCOVERY: "false"
+        run: node scripts/package.mjs --${{ matrix.target }} --x64 --arm64 --publish always

.goreleaser.yml

@@ -21,12 +21,12 @@ builds:
     goarch:
       - amd64
       - arm64
-    ignore:
-      - goos: windows
-        goarch: arm64
 
 archives:
-  - id: default
+  # Legacy archive name kept so already-released CLIs (whose `multica update`
+  # looks for `multica_{os}_{arch}.{ext}`) can keep self-updating. Remove
+  # once those versions are no longer in use.
+  - id: legacy
     formats:
       - tar.gz
     format_overrides:
@@ -34,6 +34,16 @@ archives:
         formats:
           - zip
     name_template: "{{ .ProjectName }}_{{ .Os }}_{{ .Arch }}"
+  # Versioned archive name used by current CLI / install scripts /
+  # desktop bootstrap going forward.
+  - id: versioned
+    formats:
+      - tar.gz
+    format_overrides:
+      - goos: windows
+        formats:
+          - zip
+    name_template: "{{ .ProjectName }}-cli-{{ .Version }}-{{ .Os }}-{{ .Arch }}"
 
 checksum:
   name_template: "checksums.txt"
@@ -48,6 +58,8 @@ changelog:
 
 brews:
   - name: multica
+    ids:
+      - versioned
     repository:
       owner: multica-ai
       name: homebrew-tap

CLAUDE.md

@@ -133,6 +133,7 @@ make start-worktree     # Start using .env.worktree
 - Unless the user explicitly asks for backwards compatibility, do **not** add compatibility layers, fallback paths, dual-write logic, legacy adapters, or temporary shims.
 - If a flow or API is being replaced and the product is not yet live, prefer removing the old path instead of preserving both old and new behavior.
 - Avoid broad refactors unless required by the task.
+- New global (pre-workspace) routes MUST use a single word (`/login`, `/inbox`) or a `/{noun}/{verb}` pair (`/workspaces/new`). NEVER add hyphenated word-group root routes (`/new-workspace`, `/create-team`) — they collide with common user workspace names and force endless reserved-slug audits. Reserving the noun (`workspaces`) automatically protects the entire `/workspaces/*` subtree.
 
 ### Package Boundary Rules
 
@@ -161,7 +162,7 @@ When the two apps need different behavior for the same concept (e.g., different
 When adding a new page or feature:
 
 1. **New page component** → add to `packages/views/<domain>/`. Never import from `next/*` or `react-router-dom`.
-2. **Wire it in both apps** → add a route in `apps/web/app/` (Next.js page file) AND in the desktop router.
+2. **Wire it in both apps** → add a route in `apps/web/app/` (Next.js page file) AND in the desktop router. **Exception**: pre-workspace transition flows (create workspace, accept invite) are NOT routes on desktop — they're `WindowOverlay` state. See *Desktop-specific Rules → Route categories*.
 3. **Navigation** → use `useNavigation().push()` or `<AppLink>`. Never use framework-specific link/router APIs in shared code.
 4. **Shared guards/providers** → use `DashboardGuard` from `packages/views/layout/`. Don't create separate guard logic per app.
 5. **Platform-specific UI** → if a feature is web-only or desktop-only, keep it in the respective app. Use props slots (`extra`, `topSlot`) on shared layout components to inject platform-specific UI.
@@ -175,6 +176,70 @@ Both apps share the same CSS foundation from `packages/ui/styles/`.
 - **Shared styles** → `packages/ui/styles/`. Never duplicate scrollbar styling, keyframes, or base layer rules in app CSS.
 - **`@source` directives** → both apps scan shared packages so Tailwind sees all class names.
 
+## Desktop-specific Rules
+
+These rules apply to `apps/desktop/` only. Web has different constraints (URL bar, SSR, no tabs) and doesn't share these concerns. Every rule in this section was added after a concrete bug — treat them as enforced, not suggestions.
+
+### Route categories
+
+Every path in the desktop app falls into exactly one category. Choosing the wrong one reproduces bugs we've already fixed.
+
+- **Session routes** — workspace-scoped pages (`/:slug/issues`, `/:slug/settings`). Rendered by the per-tab memory router under `WorkspaceRouteLayout`. These are legitimate tab destinations.
+- **Transition flows** — pre-workspace / one-shot actions (create workspace, accept invite). **NOT routes.** They live as `WindowOverlay` state, dispatched when the navigation adapter sees `push('/workspaces/new')` or `push('/invite/<id>')`. The shared view (`NewWorkspacePage`, `InvitePage`) is the content; the overlay wrapper supplies platform chrome.
+- **Error / stale states** — "workspace not available", tabs pointing at a revoked workspace. **NOT pages.** `WorkspaceRouteLayout` auto-heals by dropping the stale tab group from the store; the user never lands on an explicit error screen. Web keeps `NoAccessPage` (shareable URL makes the error state meaningful); desktop has no URL bar so stale = heal silently.
+
+**Adding a new pre-workspace flow on desktop**: register a new `WindowOverlay` type in `stores/window-overlay-store.ts`. Do NOT add it to `routes.tsx`. If a shared view needs the flow on both platforms, add the route on web (`apps/web/app/(auth)/...`) AND the overlay type on desktop — the shared view component is identical.
+
+### Workspace identity singleton
+
+`setCurrentWorkspace(slug, uuid)` in `@multica/core/platform` is the single source of truth for "which workspace is active right now". Three consumers depend on it:
+
+1. API client's `X-Workspace-Slug` header.
+2. Zustand per-workspace storage namespace.
+3. Chrome gating (`{slug && <AppSidebar />}` on desktop, similar on web).
+
+Normally set by `WorkspaceRouteLayout` when its route mounts. Critically: **unmount does NOT clear it.** Any code that leaves workspace context (leave workspace, delete workspace, force navigation to overlay) must call `setCurrentWorkspace(null, null)` explicitly — otherwise the realtime `workspace:deleted` handler races the mutation, chrome gating stays truthy while the workspace is gone from cache, and `useWorkspaceId` throws.
+
+### Workspace destructive operations
+
+Leave / Delete workspace flows must follow this order:
+
+1. Read destination from cached workspace list (no extra fetch).
+2. `setCurrentWorkspace(null, null)`.
+3. `navigation.push(destination)` — switch to next workspace or open new-workspace overlay.
+4. THEN `await mutation.mutateAsync(workspaceId)`.
+
+Reversing step 4 with steps 1–3 (mutate first, navigate after) causes a three-way race between the mutation's `onSettled` invalidate, the explicit `navigateAway`, and the realtime handler's `relocateAfterWorkspaceLoss` — all refetching the same `workspaces` query concurrently. One gets cancelled, bubbles as `CancelledError`, and triggers `window.location.assign` → full renderer reload / white screen.
+
+### Tab isolation
+
+Tabs are grouped per workspace in `stores/tab-store.ts`. The TabBar shows only the active workspace's tabs; cross-workspace tab leakage is impossible by construction (no flat global tabs array).
+
+Cross-workspace `push(path)` is detected by the navigation adapter (`platform/navigation.tsx`) and translated into `switchWorkspace(slug, targetPath)` — NOT a navigation within the current tab's router. Don't bypass the adapter; always go through `useNavigation()` from shared code.
+
+### Drag region (macOS window-move)
+
+Every full-window desktop view (login, overlay, any page that covers the native title bar) needs a top drag strip so users can move the window. On macOS the traffic lights are hidden via `useImmersiveMode` in overlay-style contexts, so the drag strip also gives back that corner for pointer-drag.
+
+**Pattern**: flex child at top, not absolute overlay.
+
+```tsx
+<div className="fixed inset-0 z-50 flex flex-col bg-background">
+  <div className="h-12 shrink-0" style={{ WebkitAppRegion: "drag" }} />
+  <div className="flex-1 overflow-auto" style={{ WebkitAppRegion: "no-drag" }}>
+    {/* page content — interactive elements need their own "no-drag" */}
+  </div>
+</div>
+```
+
+Why flex, not absolute: the absolute-strip + `z-index` approach relies on stacking-context hit-testing, which isn't reliable for `-webkit-app-region`. A real flex row with no siblings at that pixel is unambiguous. Height matches `MainTopBar` (48px / `h-12`) for consistency.
+
+Canonical examples: `components/window-overlay.tsx`, `pages/login.tsx`.
+
+### UX vs platform chrome
+
+UX affordances (Back button, Log out button, welcome copy, invite card) belong in `packages/views/` so web and desktop render identical content. Platform chrome (drag strip, `useImmersiveMode`, tab system interaction, traffic-light accommodation) lives in desktop-only code. Violating this split always produces platform divergence — if a button exists on desktop but not on web for the same flow, it's a signal the UX escaped into platform code.
+
 ## UI/UX Rules
 
 - Prefer shadcn components over custom implementations. Install via `pnpm ui:add <component>` from project root — adds to `packages/ui/components/ui/`. All components use Base UI primitives (`@base-ui/react`), not Radix.

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
 
@@ -269,7 +278,7 @@ multica issue list --priority urgent --assignee "Agent Name"
 multica issue list --limit 20 --output json
 ```
 
-Available filters: `--status`, `--priority`, `--assignee`, `--limit`.
+Available filters: `--status`, `--priority`, `--assignee`, `--project`, `--limit`.
 
 ### Get Issue
 
@@ -284,7 +293,7 @@ multica issue get <id> --output json
 multica issue create --title "Fix login bug" --description "..." --priority high --assignee "Lambda"
 ```
 
-Flags: `--title` (required), `--description`, `--status`, `--priority`, `--assignee`, `--parent`, `--due-date`.
+Flags: `--title` (required), `--description`, `--status`, `--priority`, `--assignee`, `--parent`, `--project`, `--due-date`.
 
 ### Update Issue
 
@@ -323,6 +332,27 @@ multica issue comment add <issue-id> --parent <comment-id> --content "Thanks!"
 multica issue comment delete <comment-id>
 ```
 
+### Subscribers
+
+```bash
+# List subscribers of an issue
+multica issue subscriber list <issue-id>
+
+# Subscribe yourself to an issue
+multica issue subscriber add <issue-id>
+
+# Subscribe another member or agent by name
+multica issue subscriber add <issue-id> --user "Lambda"
+
+# Unsubscribe yourself
+multica issue subscriber remove <issue-id>
+
+# Unsubscribe another member or agent
+multica issue subscriber remove <issue-id> --user "Lambda"
+```
+
+Subscribers receive notifications about issue activity (new comments, status changes, etc.). Without `--user`, the command acts on the caller.
+
 ### Execution History
 
 ```bash
@@ -340,6 +370,70 @@ multica issue run-messages <task-id> --since 42 --output json
 
 The `runs` command shows all past and current executions for an issue, including running tasks. The `run-messages` command shows the detailed message log (tool calls, thinking, text, errors) for a single run. Use `--since` for efficient polling of in-progress runs.
 
+## Projects
+
+Projects group related issues (e.g. a sprint, an epic, a workstream). Every project
+belongs to a workspace and can optionally have a lead (member or agent).
+
+### List Projects
+
+```bash
+multica project list
+multica project list --status in_progress
+multica project list --output json
+```
+
+Available filters: `--status`.
+
+### Get Project
+
+```bash
+multica project get <id>
+multica project get <id> --output json
+```
+
+### Create Project
+
+```bash
+multica project create --title "2026 Week 16 Sprint" --icon "🏃" --lead "Lambda"
+```
+
+Flags: `--title` (required), `--description`, `--status`, `--icon`, `--lead`.
+
+### Update Project
+
+```bash
+multica project update <id> --title "New title" --status in_progress
+multica project update <id> --lead "Lambda"
+```
+
+Flags: `--title`, `--description`, `--status`, `--icon`, `--lead`.
+
+### Change Status
+
+```bash
+multica project status <id> in_progress
+```
+
+Valid statuses: `planned`, `in_progress`, `paused`, `completed`, `cancelled`.
+
+### Delete Project
+
+```bash
+multica project delete <id>
+```
+
+### Associating Issues with Projects
+
+Use the `--project` flag on `issue create` / `issue update` to attach an issue to a
+project, or on `issue list` to filter issues by project:
+
+```bash
+multica issue create --title "Login bug" --project <project-id>
+multica issue update <issue-id> --project <project-id>
+multica issue list --project <project-id>
+```
+
 ## Setup
 
 ```bash
@@ -376,6 +470,63 @@ multica config set app_url https://app.example.com
 multica config set workspace_id <workspace-id>
 ```
 
+## Autopilot Commands
+
+Autopilots are scheduled/triggered automations that dispatch agent tasks (either by creating an issue or by running an agent directly).
+
+### List Autopilots
+
+```bash
+multica autopilot list
+multica autopilot list --status active --output json
+```
+
+### Get Autopilot Details
+
+```bash
+multica autopilot get <id>
+multica autopilot get <id> --output json   # includes triggers
+```
+
+### Create / Update / Delete
+
+```bash
+multica autopilot create \
+  --title "Nightly bug triage" \
+  --description "Scan todo issues and prioritize." \
+  --agent "Lambda" \
+  --mode create_issue
+
+multica autopilot update <id> --status paused
+multica autopilot update <id> --description "New prompt"
+multica autopilot delete <id>
+```
+
+`--mode` currently only accepts `create_issue` (creates a new issue on each run and assigns it to the agent). The server data model also defines `run_only`, but the daemon task path doesn't yet resolve a workspace for runs without an issue, so it's not exposed by the CLI. `--agent` accepts either a name or UUID.
+
+### Manual Trigger
+
+```bash
+multica autopilot trigger <id>            # Fires the autopilot once, returns the run
+```
+
+### Run History
+
+```bash
+multica autopilot runs <id>
+multica autopilot runs <id> --limit 50 --output json
+```
+
+### Schedule Triggers
+
+```bash
+multica autopilot trigger-add <autopilot-id> --cron "0 9 * * 1-5" --timezone "America/New_York"
+multica autopilot trigger-update <autopilot-id> <trigger-id> --enabled=false
+multica autopilot trigger-delete <autopilot-id> <trigger-id>
+```
+
+Only cron-based `schedule` triggers are currently exposed via the CLI. The data model also defines `webhook` and `api` kinds, but there is no server endpoint that fires them yet, so they're not surfaced here.
+
 ## Other Commands
 
 ```bash

CLI_INSTALL.md

@@ -76,7 +76,8 @@ fi
 LATEST=$(curl -sI https://github.com/multica-ai/multica/releases/latest | grep -i '^location:' | sed 's/.*tag\///' | tr -d '\r\n')
 
 # Download and extract
-curl -sL "https://github.com/multica-ai/multica/releases/download/${LATEST}/multica_${OS}_${ARCH}.tar.gz" -o /tmp/multica.tar.gz
+VERSION="${LATEST#v}"
+curl -sL "https://github.com/multica-ai/multica/releases/download/${LATEST}/multica-cli-${VERSION}-${OS}-${ARCH}.tar.gz" -o /tmp/multica.tar.gz
 tar -xzf /tmp/multica.tar.gz -C /tmp multica
 sudo mv /tmp/multica /usr/local/bin/multica
 rm /tmp/multica.tar.gz
@@ -165,12 +166,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 +185,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`."
 
 ---
 

CONTRIBUTING.md

@@ -9,6 +9,7 @@ It covers:
 - isolated worktree development
 - the shared PostgreSQL model
 - testing and verification
+- full-stack isolated testing (backend + frontend + daemon from source)
 - troubleshooting and destructive reset options
 
 ## Development Model
@@ -308,6 +309,199 @@ make daemon
 The daemon authenticates using the CLI's stored token (`multica login`).
 It registers runtimes for all watched workspaces from the CLI config.
 
+## Full-Stack Isolated Testing
+
+This section covers running the complete stack (backend, frontend, daemon) from
+source in a fully isolated environment. Useful for testing end-to-end changes
+that span multiple components, or for automated CI/AI workflows that need zero
+human intervention.
+
+### Why Not Just `make daemon`?
+
+`make daemon` uses the system-installed CLI's stored token and connects to
+whatever server is configured in `~/.multica/config.json`. That's fine for
+day-to-day development against a shared server, but for fully isolated testing
+you need:
+
+- a local backend and frontend (from source)
+- a local daemon (from source) with its own profile
+- automated authentication (no browser login)
+- no interference with your production CLI config
+
+### Dynamic Profile Naming
+
+Each worktree must use a unique daemon profile to avoid collisions when
+multiple features run in parallel.
+
+The profile name is derived from the worktree directory using the same
+slug + hash pattern as `scripts/init-worktree-env.sh`:
+
+```bash
+WORKTREE_DIR="$(basename "$PWD")"
+SLUG="$(printf '%s' "$WORKTREE_DIR" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/_/g; s/__*/_/g; s/^_//; s/_$//')"
+HASH="$(printf '%s' "$PWD" | cksum | awk '{print $1}')"
+OFFSET=$((HASH % 1000))
+PROFILE="dev-${SLUG}-${OFFSET}"
+```
+
+Example: worktree at `../multica-feat-auth` produces profile
+`dev-multica_feat_auth-347`, matching that worktree's port and database
+allocation.
+
+### Start the Isolated Environment
+
+Run all steps from the worktree root (where the Makefile is).
+
+#### 1. Start backend, frontend, and database
+
+```bash
+make dev
+```
+
+Wait for the backend to be healthy:
+
+```bash
+PORT=$(grep '^PORT=' .env.worktree 2>/dev/null || grep '^PORT=' .env | head -1 | cut -d= -f2)
+PORT=${PORT:-8080}
+SERVER="http://localhost:${PORT}"
+
+for i in $(seq 1 30); do
+  curl -sf "$SERVER/health" > /dev/null 2>&1 && break
+  sleep 2
+done
+```
+
+#### 2. Create a test user and token (automated auth)
+
+In non-production environments the verification code is fixed at `888888`:
+
+```bash
+curl -s -X POST "$SERVER/auth/send-code" \
+  -H "Content-Type: application/json" \
+  -d '{"email": "dev@localhost"}'
+
+JWT=$(curl -s -X POST "$SERVER/auth/verify-code" \
+  -H "Content-Type: application/json" \
+  -d '{"email": "dev@localhost", "code": "888888"}' | jq -r '.token')
+
+PAT=$(curl -s -X POST "$SERVER/api/tokens" \
+  -H "Authorization: Bearer $JWT" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "auto-dev", "expires_in_days": 365}' | jq -r '.token')
+```
+
+#### 3. Create a workspace
+
+```bash
+WS=$(curl -s -X POST "$SERVER/api/workspaces" \
+  -H "Authorization: Bearer $PAT" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Dev", "slug": "dev"}' | jq -r '.id')
+```
+
+#### 4. Compute profile name and write CLI config
+
+```bash
+# Compute profile (see Dynamic Profile Naming above)
+WORKTREE_DIR="$(basename "$PWD")"
+SLUG="$(printf '%s' "$WORKTREE_DIR" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/_/g; s/__*/_/g; s/^_//; s/_$//')"
+HASH="$(printf '%s' "$PWD" | cksum | awk '{print $1}')"
+OFFSET=$((HASH % 1000))
+PROFILE="dev-${SLUG}-${OFFSET}"
+
+FRONTEND_PORT=$(grep '^FRONTEND_PORT=' .env.worktree 2>/dev/null || grep '^FRONTEND_PORT=' .env | head -1 | cut -d= -f2)
+FRONTEND_PORT=${FRONTEND_PORT:-3000}
+
+CONFIG_DIR="$HOME/.multica/profiles/$PROFILE"
+mkdir -p "$CONFIG_DIR"
+
+cat > "$CONFIG_DIR/config.json" << EOF
+{
+  "server_url": "$SERVER",
+  "app_url": "http://localhost:${FRONTEND_PORT}",
+  "token": "$PAT",
+  "workspace_id": "$WS",
+  "watched_workspaces": [{"id": "$WS", "name": "Dev"}]
+}
+EOF
+```
+
+#### 5. Start the daemon from source
+
+```bash
+make cli ARGS="daemon start --profile $PROFILE"
+```
+
+The daemon runs from the current worktree's Go source, connecting to the
+local backend. Agent-executed `multica` commands automatically use the same
+binary (the daemon prepends its own directory to `PATH`).
+
+### Stop the Isolated Environment
+
+```bash
+# Compute profile (same formula)
+PROFILE="dev-$(printf '%s' "$(basename "$PWD")" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/_/g; s/__*/_/g; s/^_//; s/_$//')-$(( $(printf '%s' "$PWD" | cksum | awk '{print $1}') % 1000 ))"
+
+# 1. Stop daemon
+make cli ARGS="daemon stop --profile $PROFILE"
+
+# 2. Stop backend + frontend
+make stop            # main checkout
+make stop-worktree   # worktree checkout
+
+# 3. (Optional) Stop shared PostgreSQL
+make db-down
+
+# 4. (Optional) Clean build artifacts
+make clean
+
+# 5. (Optional) Remove profile config
+rm -rf "$HOME/.multica/profiles/$PROFILE"
+```
+
+### Desktop App Local Testing
+
+To test the Electron desktop app against a local backend:
+
+```bash
+# After backend is running (make dev)
+pnpm dev:desktop
+```
+
+This automatically:
+
+1. Compiles the `multica` CLI from `server/cmd/multica` into
+   `apps/desktop/resources/bin/multica`
+2. Creates an isolated profile named `desktop-localhost-<PORT>`
+3. Starts and manages its own daemon instance
+4. Connects to the local backend
+
+Login in the Desktop UI with `dev@localhost` and code `888888`.
+
+If the backend runs on a non-default port (worktree), create
+`apps/desktop/.env.development.local`:
+
+```bash
+VITE_API_URL=http://localhost:<backend-port>
+VITE_WS_URL=ws://localhost:<backend-port>/ws
+```
+
+### Isolation Guarantee
+
+Nothing in this flow touches the system-installed `multica` or the default
+`~/.multica/config.json`:
+
+| Resource | System / Production | Local Dev (per-worktree) |
+|---|---|---|
+| Config | `~/.multica/config.json` | `~/.multica/profiles/dev-<slug>-<hash>/config.json` |
+| Daemon PID | `~/.multica/daemon.pid` | `~/.multica/profiles/dev-<slug>-<hash>/daemon.pid` |
+| Health port | `19514` | `19514 + 1 + (name_hash % 1000)` |
+| Workspaces dir | `~/multica_workspaces/` | `~/multica_workspaces_dev-<slug>-<hash>/` |
+| Database | remote / production | local Docker: `multica_<slug>_<hash>` |
+| Desktop profile | `desktop-api.multica.ai` | `desktop-localhost-<port>` |
+
+Multiple worktrees can run simultaneously without conflict.
+
 ## Troubleshooting
 
 ### Missing Env File

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

@@ -66,7 +66,8 @@ selfhost:
 		echo "  Frontend: http://localhost:$${FRONTEND_PORT:-3000}"; \
 		echo "  Backend:  http://localhost:$${PORT:-8080}"; \
 		echo ""; \
-		echo "Log in with any email + verification code: 888888"; \
+		echo "Log in: configure RESEND_API_KEY in .env for email codes,"; \
+		echo "        or set APP_ENV=development in .env (private networks only) to enable code 888888."; \
 		echo ""; \
 		echo "Next — install the CLI and connect your machine:"; \
 		echo "  brew install multica-ai/tap/multica"; \
@@ -104,6 +105,8 @@ start:
 	@echo "Backend: http://localhost:$(PORT)"
 	@echo "Frontend: http://localhost:$(FRONTEND_PORT)"
 	@bash scripts/ensure-postgres.sh "$(ENV_FILE)"
+	@echo "Running migrations..."
+	cd server && go run ./cmd/migrate up
 	@echo "Starting backend and frontend..."
 	@trap 'kill 0' EXIT; \
 		(cd server && go run ./cmd/server) & \
@@ -180,7 +183,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

@@ -26,7 +26,7 @@ multica setup self-host
 
 This clones the repository, starts all services via Docker Compose, installs the `multica` CLI, then configures it for localhost.
 
-Open http://localhost:3000, log in with any email + verification code **`888888`**.
+Open http://localhost:3000. To log in, configure `RESEND_API_KEY` in `.env` for email-based codes (recommended), or set `APP_ENV=development` in `.env` to enable the dev master code **`888888`**. See [Step 2 — Log In](#step-2--log-in) for details.
 
 > **Prerequisites:** Docker and Docker Compose must be installed. The script checks for this and provides install links if missing.
 >
@@ -63,9 +63,13 @@ Once ready:
 
 ### Step 2 — Log In
 
-Open http://localhost:3000 in your browser. Enter any email address and use verification code **`888888`** to log in.
+Open http://localhost:3000 in your browser. The Docker self-host stack defaults to `APP_ENV=production` (set in `docker-compose.selfhost.yml`), so the dev master code is **disabled by default** for safety on public deployments. Pick one of the following to log in:
 
-> This master code works in all non-production environments (i.e. when `APP_ENV` is not set to `production`). For production, configure an email provider — see [Advanced Configuration](SELF_HOSTING_ADVANCED.md#email-required-for-authentication).
+- **Recommended (production):** configure `RESEND_API_KEY` in `.env`, then restart the backend. Real verification codes will be sent to the email address you enter. See [Advanced Configuration → Email](SELF_HOSTING_ADVANCED.md#email-required-for-authentication).
+- **Evaluation / private network:** set `APP_ENV=development` in `.env` and restart the backend. Verification code **`888888`** will then work for any email address.
+- **Without configuring either:** the verification code is generated server-side and printed to the backend container logs (look for `[DEV] Verification code for ...:`). Useful for one-off testing on a single machine.
+
+> **Warning:** do **not** set `APP_ENV=development` on a publicly reachable instance — anyone who knows an email address can then log in with `888888`.
 
 ### Step 3 — Install CLI & Start Daemon
 
@@ -85,6 +89,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

@@ -14,6 +14,15 @@ All configuration is done via environment variables. Copy `.env.example` as a st
 | `JWT_SECRET` | **Must change from default.** Secret key for signing JWT tokens. Use a long random string. | `openssl rand -hex 32` |
 | `FRONTEND_ORIGIN` | URL where the frontend is served (used for CORS) | `https://app.example.com` |
 
+### Database Pool Tuning (Optional)
+
+These have sensible defaults and only need to be set when tuning a large or constrained deployment. Precedence (highest first): env var → `pool_*` query params on `DATABASE_URL` → built-in default.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `DATABASE_MAX_CONNS` | pgxpool max connections per pod. `pod_count × DATABASE_MAX_CONNS` should stay well below the Postgres `max_connections` ceiling. With a connection pooler (PgBouncer / RDS Proxy / Supavisor) in front, this can be raised significantly. | `25` |
+| `DATABASE_MIN_CONNS` | pgxpool warm baseline connections per pod. Auto-clamped to `DATABASE_MAX_CONNS`. | `5` |
+
 ### Email (Required for Authentication)
 
 Multica uses email-based magic link authentication via [Resend](https://resend.com).
@@ -23,7 +32,7 @@ Multica uses email-based magic link authentication via [Resend](https://resend.c
 | `RESEND_API_KEY` | Your Resend API key |
 | `RESEND_FROM_EMAIL` | Sender email address (default: `noreply@multica.ai`) |
 
-> **Note:** For local/development deployments without email configured, you can use the master verification code `888888` to log in.
+> **Note:** The dev master verification code `888888` is gated by `APP_ENV != "production"`. The Docker self-host stack defaults to `APP_ENV=production` (so `888888` is disabled), which protects publicly reachable instances. For local development without email configured, set `APP_ENV=development` in your `.env` to enable `888888` — never do this on a public instance.
 
 ### Google OAuth (Optional)
 
@@ -44,7 +53,14 @@ For file uploads and attachments, configure S3 and CloudFront:
 | `CLOUDFRONT_DOMAIN` | CloudFront distribution domain |
 | `CLOUDFRONT_KEY_PAIR_ID` | CloudFront key pair ID for signed URLs |
 | `CLOUDFRONT_PRIVATE_KEY` | CloudFront private key (PEM format) |
-| `COOKIE_DOMAIN` | Domain for CloudFront auth cookies |
+
+### Cookies
+
+| Variable | Description |
+|----------|-------------|
+| `COOKIE_DOMAIN` | Optional `Domain` attribute for session + CloudFront cookies. **Leave empty** for single-host deployments (localhost, LAN IP, or a single hostname). Only set it when the frontend and backend sit on different subdomains of one registered domain (e.g. `.example.com`). **Do not use an IP literal** — RFC 6265 forbids IP addresses in the cookie `Domain` attribute and browsers will drop such `Set-Cookie` headers. |
+
+The `Secure` flag on session cookies is derived automatically from the scheme of `FRONTEND_ORIGIN`: HTTPS origins get `Secure` cookies; plain-HTTP origins (LAN / private-network self-host) get non-secure cookies so the browser can actually store them.
 
 ### Server
 
@@ -80,6 +96,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/electron-builder.yml

@@ -21,25 +21,34 @@ mac:
     - zip
   # Hardcoded name avoids the `@multica/desktop-*` subdirectory that
   # `${name}` produces for scoped package names.
-  artifactName: multica-desktop-${version}-${arch}.${ext}
+  # Naming scheme: multica-desktop-<version>-<platform>-<arch>.<ext>
+  # so the filename alone surfaces kind, version, platform, and CPU arch.
+  artifactName: multica-desktop-${version}-mac-${arch}.${ext}
   # Notarize via notarytool. Requires APPLE_ID + APPLE_APP_SPECIFIC_PASSWORD
   # + APPLE_TEAM_ID env vars at package time. Non-mac contributors are
   # unaffected because `pnpm package` already requires the Developer ID
   # signing cert — notarization is a strict superset.
   notarize: true
 dmg:
-  artifactName: multica-desktop-${version}-${arch}.${ext}
+  artifactName: multica-desktop-${version}-mac-${arch}.${ext}
 linux:
   target:
     - AppImage
     - deb
-  artifactName: ${name}-${version}-${arch}.${ext}
+    - rpm
+  artifactName: multica-desktop-${version}-linux-${arch}.${ext}
 win:
   target:
     - nsis
-  artifactName: ${name}-${version}-setup.${ext}
+  artifactName: multica-desktop-${version}-windows-${arch}.${ext}
 publish:
   provider: github
   owner: multica-ai
   repo: multica
+  # Align with our CLI release flow which pre-creates a *published* GitHub
+  # Release via `gh release create`. The electron-builder default of
+  # `releaseType: draft` conflicts with `existingType=release` and causes
+  # uploads of the DMG/ZIP/blockmaps/latest-mac.yml to be silently skipped,
+  # which breaks electron-updater auto-update on installed clients.
+  releaseType: release
 npmRebuild: false

apps/desktop/electron.vite.config.ts

@@ -12,7 +12,10 @@ export default defineConfig({
   },
   renderer: {
     server: {
-      port: 5173,
+      // Allow parallel worktrees to run `pnpm dev:desktop` side-by-side
+      // (e.g. Multica Canary alongside a primary checkout) by overriding
+      // the renderer port via env. Falls back to 5173 for the common case.
+      port: Number(process.env.DESKTOP_RENDERER_PORT) || 5173,
       strictPort: true,
     },
     plugins: [react(), tailwindcss()],

apps/desktop/eslint.config.mjs

@@ -10,4 +10,28 @@ export default [
       globals: { ...globals.node },
     },
   },
+  // Security: every renderer-controlled URL that reaches the OS shell must
+  // flow through openExternalSafely in src/main/external-url.ts (scheme
+  // allowlist). Enforce it statically so a direct shell.openExternal call
+  // cannot silently regress the protection.
+  {
+    files: ["src/main/**/*.ts"],
+    rules: {
+      "no-restricted-syntax": [
+        "error",
+        {
+          selector:
+            "CallExpression[callee.object.name='shell'][callee.property.name='openExternal']",
+          message:
+            "Do not call shell.openExternal directly. Use openExternalSafely from './external-url' so the http/https allowlist stays enforced.",
+        },
+      ],
+    },
+  },
+  {
+    files: ["src/main/external-url.ts"],
+    rules: {
+      "no-restricted-syntax": "off",
+    },
+  },
 ];

apps/desktop/package.json

@@ -2,16 +2,30 @@
   "name": "@multica/desktop",
   "version": "0.1.0",
   "private": true,
+  "description": "Multica Desktop — native desktop client for the Multica platform.",
+  "homepage": "https://multica.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/multica-ai/multica.git",
+    "directory": "apps/desktop"
+  },
+  "author": {
+    "name": "Multica",
+    "email": "support@multica.ai"
+  },
+  "license": "UNLICENSED",
   "main": "./out/main/index.js",
   "scripts": {
     "bundle-cli": "node scripts/bundle-cli.mjs",
-    "dev": "pnpm run bundle-cli && electron-vite dev",
+    "brand-dev-electron": "node scripts/brand-dev-electron.mjs",
+    "dev": "pnpm run bundle-cli && pnpm run brand-dev-electron && electron-vite dev",
     "build": "pnpm run bundle-cli && electron-vite build",
     "typecheck:node": "tsc --noEmit -p tsconfig.node.json --composite false",
     "typecheck:web": "tsc --noEmit -p tsconfig.web.json --composite false",
     "typecheck": "pnpm run typecheck:node && pnpm run typecheck:web",
     "preview": "electron-vite preview",
     "package": "node scripts/package.mjs",
+    "package:all": "node scripts/package.mjs --all-platforms --publish never",
     "lint": "eslint .",
     "test": "vitest run",
     "postinstall": "electron-builder install-app-deps"
@@ -29,6 +43,7 @@
     "@multica/ui": "workspace:*",
     "@multica/views": "workspace:*",
     "electron-updater": "^6.8.3",
+    "fix-path": "^5.0.0",
     "react-router-dom": "^7.6.0",
     "shadcn": "^4.1.0",
     "sonner": "^2.0.7",
@@ -38,6 +53,8 @@
     "@electron-toolkit/tsconfig": "^2.0.0",
     "@multica/tsconfig": "workspace:*",
     "@tailwindcss/vite": "^4",
+    "@testing-library/jest-dom": "catalog:",
+    "@testing-library/react": "catalog:",
     "@types/node": "catalog:",
     "@types/react": "catalog:",
     "@types/react-dom": "catalog:",
@@ -45,6 +62,7 @@
     "electron": "^39.2.6",
     "electron-builder": "^26.0.12",
     "electron-vite": "^5.0.0",
+    "jsdom": "catalog:",
     "react": "catalog:",
     "react-dom": "catalog:",
     "tailwindcss": "^4",

apps/desktop/scripts/brand-dev-electron.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// Rebrand the bundled Electron.app's Info.plist so `pnpm dev:desktop`
+// shows "Multica Canary" in the menu bar, Cmd+Tab switcher, and
+// Activity Monitor. On macOS these titles come from CFBundleName at
+// launch time — `app.setName()` cannot override them at runtime, so
+// patching the plist in node_modules is the only working fix.
+//
+// Idempotent: runs on every dev launch and no-ops once the plist already
+// matches. The patch is isolated to this worktree's node_modules — we
+// unlink the file before rewriting so we never mutate a pnpm-store inode
+// shared with another project.
+
+import { createRequire } from "node:module";
+import { execFileSync } from "node:child_process";
+import { readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+if (process.platform !== "darwin") process.exit(0);
+
+const DESIRED_NAME = "Multica Canary";
+
+const require = createRequire(import.meta.url);
+// `require('electron')` returns the path to the executable
+// (.../Electron.app/Contents/MacOS/Electron). Walk up to Contents/Info.plist.
+const electronBin = require("electron");
+const plistPath = resolve(electronBin, "../../Info.plist");
+
+function plistGet(key) {
+  try {
+    return execFileSync(
+      "/usr/libexec/PlistBuddy",
+      ["-c", `Print :${key}`, plistPath],
+      { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
+    ).trim();
+  } catch {
+    return "";
+  }
+}
+
+function plistSet(key, value) {
+  try {
+    execFileSync("/usr/libexec/PlistBuddy", [
+      "-c",
+      `Set :${key} ${value}`,
+      plistPath,
+    ]);
+  } catch {
+    execFileSync("/usr/libexec/PlistBuddy", [
+      "-c",
+      `Add :${key} string ${value}`,
+      plistPath,
+    ]);
+  }
+}
+
+if (
+  plistGet("CFBundleName") === DESIRED_NAME &&
+  plistGet("CFBundleDisplayName") === DESIRED_NAME
+) {
+  process.exit(0);
+}
+
+// Break any pnpm hardlink to the global store: read, unlink, rewrite.
+// PlistBuddy would otherwise write through the hardlink and mutate the
+// shared store file (and every other project's Electron.app with it).
+const original = readFileSync(plistPath);
+unlinkSync(plistPath);
+writeFileSync(plistPath, original);
+
+plistSet("CFBundleName", DESIRED_NAME);
+plistSet("CFBundleDisplayName", DESIRED_NAME);
+
+console.log(`[brand-dev-electron] ${plistPath} → CFBundleName="${DESIRED_NAME}"`);

apps/desktop/scripts/bundle-cli.mjs

@@ -13,7 +13,7 @@
 // skip the build and fall through to auto-install at runtime. A genuine
 // Go compile error is fatal — you want that to block dev, not hide.
 
-import { access, chmod, copyFile, mkdir } from "node:fs/promises";
+import { access, chmod, copyFile, mkdir, rm } from "node:fs/promises";
 import { constants } from "node:fs";
 import { execFileSync, execSync } from "node:child_process";
 import { dirname, join, resolve } from "node:path";
@@ -23,8 +23,54 @@ const here = dirname(fileURLToPath(import.meta.url));
 const repoRoot = resolve(here, "..", "..", "..");
 const serverDir = join(repoRoot, "server");
 
-const binName = process.platform === "win32" ? "multica.exe" : "multica";
-const srcBinary = join(serverDir, "bin", binName);
+const PLATFORM_TO_GOOS = {
+  darwin: "darwin",
+  linux: "linux",
+  win32: "windows",
+};
+
+const SUPPORTED_ARCHS = new Set(["x64", "arm64"]);
+
+function runtimePlatformFromArgs(argv) {
+  const flagIndex = argv.indexOf("--target-platform");
+  if (flagIndex === -1) return process.platform;
+  return argv[flagIndex + 1] ?? "";
+}
+
+function runtimeArchFromArgs(argv) {
+  const flagIndex = argv.indexOf("--target-arch");
+  if (flagIndex === -1) return process.arch;
+  return argv[flagIndex + 1] ?? "";
+}
+
+function normalizeRuntimePlatform(platform) {
+  if (platform in PLATFORM_TO_GOOS) return platform;
+  throw new Error(
+    `[bundle-cli] unsupported target platform: ${platform}. ` +
+      "Use darwin, linux, or win32.",
+  );
+}
+
+function normalizeRuntimeArch(arch) {
+  if (SUPPORTED_ARCHS.has(arch)) return arch;
+  throw new Error(
+    `[bundle-cli] unsupported target architecture: ${arch}. ` +
+      "Use x64 or arm64.",
+  );
+}
+
+function binaryNameForPlatform(platform) {
+  return platform === "win32" ? "multica.exe" : "multica";
+}
+
+const targetPlatform = normalizeRuntimePlatform(
+  runtimePlatformFromArgs(process.argv.slice(2)),
+);
+const targetArch = normalizeRuntimeArch(runtimeArchFromArgs(process.argv.slice(2)));
+const goos = PLATFORM_TO_GOOS[targetPlatform];
+const goarch = targetArch === "x64" ? "amd64" : targetArch;
+const binName = binaryNameForPlatform(targetPlatform);
+const srcBinary = join(serverDir, "bin", `${goos}-${goarch}`, binName);
 const destDir = join(repoRoot, "apps", "desktop", "resources", "bin");
 const destBinary = join(destDir, binName);
 
@@ -61,8 +107,9 @@ if (hasGo()) {
   const ldflags = `-X main.version=${version} -X main.commit=${commit} -X main.date=${date}`;
 
   console.log(
-    `[bundle-cli] go build → ${srcBinary} (version=${version} commit=${commit})`,
+    `[bundle-cli] go build → ${srcBinary} (${goos}/${goarch}, version=${version} commit=${commit})`,
   );
+  await mkdir(join(serverDir, "bin", `${goos}-${goarch}`), { recursive: true });
   execFileSync(
     "go",
     [
@@ -70,10 +117,19 @@ if (hasGo()) {
       "-ldflags",
       ldflags,
       "-o",
-      join("bin", binName),
+      srcBinary,
       "./cmd/multica",
     ],
-    { cwd: serverDir, stdio: "inherit" },
+    {
+      cwd: serverDir,
+      stdio: "inherit",
+      env: {
+        ...process.env,
+        CGO_ENABLED: "0",
+        GOOS: goos,
+        GOARCH: goarch,
+      },
+    },
   );
 } else {
   console.warn(
@@ -88,9 +144,11 @@ if (!(await exists(srcBinary))) {
     `[bundle-cli] ${srcBinary} not present — Desktop will fall back to ` +
       `auto-installing the latest release at runtime.`,
   );
+  await rm(destDir, { recursive: true, force: true });
   process.exit(0);
 }
 
+await rm(destDir, { recursive: true, force: true });
 await mkdir(destDir, { recursive: true });
 await copyFile(srcBinary, destBinary);
 await chmod(destBinary, 0o755);

apps/desktop/scripts/package.mjs

@@ -5,23 +5,70 @@
 // binary via the `main.version` ldflag — so a single `vX.Y.Z` tag push
 // produces matching CLI and Desktop versions.
 //
-// Runs the existing bundle-cli.mjs first (so the Go binary is compiled
-// and copied into resources/bin/), then invokes electron-builder with
-// `-c.extraMetadata.version=<derived>` so the override applies at build
-// time without mutating the tracked package.json.
+// Builds the Electron bundles once, then for each requested target
+// (platform + arch) compiles the matching Go CLI into resources/bin/ and
+// invokes electron-builder with `-c.extraMetadata.version=<derived>` so
+// the override applies at build time without mutating the tracked
+// package.json.
+//
+// The electron-vite step is important: electron-builder only packages
+// whatever is already in out/, so skipping it (or relying on stale
+// artifacts from a prior partial build) ships an app with missing
+// renderer code and white-screens on launch.
 //
 // Extra CLI args after `pnpm package --` are forwarded to electron-builder
-// unchanged (e.g. `--mac --arm64`).
+// unchanged (e.g. `--mac --arm64`). For an unsigned local smoke-test
+// build, set `CSC_IDENTITY_AUTO_DISCOVERY=false` so electron-builder falls
+// back to an ad-hoc signature instead of requiring a Developer ID cert.
 //
 // The `normalizeGitVersion` helper is exported so tests can cover the
 // version-derivation logic without shelling out.
 
 import { execFileSync, spawnSync, execSync } from "node:child_process";
-import { dirname, resolve } from "node:path";
+import { delimiter, dirname, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const desktopRoot = resolve(here, "..");
+const bundleCliScript = resolve(here, "bundle-cli.mjs");
+
+const PLATFORM_CONFIG = {
+  mac: {
+    aliases: new Set(["--mac", "--macos", "-m"]),
+    builderFlag: "--mac",
+    runtimePlatform: "darwin",
+    label: "macOS",
+  },
+  win: {
+    aliases: new Set(["--win", "--windows", "-w"]),
+    builderFlag: "--win",
+    runtimePlatform: "win32",
+    label: "Windows",
+  },
+  linux: {
+    aliases: new Set(["--linux", "-l"]),
+    builderFlag: "--linux",
+    runtimePlatform: "linux",
+    label: "Linux",
+  },
+};
+
+const ARCH_FLAGS = new Map([
+  ["--x64", "x64"],
+  ["--arm64", "arm64"],
+  ["--ia32", "ia32"],
+  ["--armv7l", "armv7l"],
+  ["--universal", "universal"],
+]);
+
+const SUPPORTED_CLI_ARCHS = new Set(["x64", "arm64"]);
+const MAC_ALL_PLATFORM_TARGETS = [
+  { platform: "mac", arch: "arm64" },
+  { platform: "win", arch: "x64" },
+  { platform: "win", arch: "arm64" },
+  { platform: "linux", arch: "x64" },
+  { platform: "linux", arch: "arm64" },
+];
 
 function sh(cmd) {
   try {
@@ -31,6 +78,18 @@ function sh(cmd) {
   }
 }
 
+/**
+ * Strip the leading `--` that npm/pnpm insert to separate their own
+ * flags from the ones meant for the underlying script.  Without this,
+ * `pnpm package -- --mac --arm64 --publish always` forwards the bare
+ * `--` into electron-builder's argv, which terminates option parsing
+ * and turns `--publish always` into ignored positional arguments.
+ */
+export function stripLeadingSeparator(argv) {
+  if (argv.length > 0 && argv[0] === "--") return argv.slice(1);
+  return argv;
+}
+
 /**
  * Pure transformation from the `git describe --tags --always --dirty`
  * output to the value we feed into electron-builder's extraMetadata.version.
@@ -57,12 +116,242 @@ function deriveVersion() {
   return normalizeGitVersion(sh("git describe --tags --always --dirty"));
 }
 
+function uniqueOrdered(values) {
+  return [...new Set(values)];
+}
+
+export function envWithLocalBins(env = process.env, root = desktopRoot) {
+  const pathKey =
+    Object.keys(env).find((key) => key.toUpperCase() === "PATH") ?? "PATH";
+  const existingPath = env[pathKey] ?? "";
+  const localBins = uniqueOrdered([
+    resolve(root, "node_modules", ".bin"),
+    resolve(root, "..", "..", "node_modules", ".bin"),
+  ]);
+  const mergedPath = uniqueOrdered([
+    ...localBins,
+    ...String(existingPath)
+      .split(delimiter)
+      .filter(Boolean),
+  ]).join(delimiter);
+  return { ...env, [pathKey]: mergedPath };
+}
+
+function hostPlatformKey(platform = process.platform) {
+  if (platform === "darwin") return "mac";
+  if (platform === "win32") return "win";
+  if (platform === "linux") return "linux";
+  throw new Error(`[package] unsupported host platform: ${platform}`);
+}
+
+function hostArchKey(arch = process.arch) {
+  if (SUPPORTED_CLI_ARCHS.has(arch)) return arch;
+  throw new Error(
+    `[package] unsupported host architecture for Desktop CLI bundling: ${arch}`,
+  );
+}
+
+function expandPlatformShorthand(token) {
+  if (!/^-[mwl]{2,}$/.test(token)) return null;
+  const expanded = [];
+  for (const char of token.slice(1)) {
+    if (char === "m") expanded.push("mac");
+    if (char === "w") expanded.push("win");
+    if (char === "l") expanded.push("linux");
+  }
+  return uniqueOrdered(expanded);
+}
+
+function platformKeyForToken(token) {
+  for (const [platform, config] of Object.entries(PLATFORM_CONFIG)) {
+    if (config.aliases.has(token)) return platform;
+  }
+  return null;
+}
+
+function platformTargetsTemplate() {
+  return { mac: [], win: [], linux: [] };
+}
+
+export function parsePackageArgs(argv) {
+  const sharedArgs = [];
+  const platformTargets = platformTargetsTemplate();
+  const requestedPlatforms = [];
+  const requestedArchs = [];
+  let allPlatforms = false;
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === "--all-platforms") {
+      allPlatforms = true;
+      continue;
+    }
+
+    const expandedPlatforms = expandPlatformShorthand(token);
+    if (expandedPlatforms) {
+      requestedPlatforms.push(...expandedPlatforms);
+      continue;
+    }
+
+    const platform = platformKeyForToken(token);
+    if (platform) {
+      requestedPlatforms.push(platform);
+      while (i + 1 < argv.length && !argv[i + 1].startsWith("-")) {
+        platformTargets[platform].push(argv[i + 1]);
+        i += 1;
+      }
+      continue;
+    }
+
+    const arch = ARCH_FLAGS.get(token);
+    if (arch) {
+      requestedArchs.push(arch);
+      continue;
+    }
+
+    sharedArgs.push(token);
+  }
+
+  return {
+    allPlatforms,
+    sharedArgs,
+    platformTargets,
+    requestedPlatforms: uniqueOrdered(requestedPlatforms),
+    requestedArchs: uniqueOrdered(requestedArchs),
+  };
+}
+
+export function resolveBuildMatrix(parsed, platform = process.platform, arch = process.arch) {
+  if (parsed.allPlatforms) {
+    if (parsed.requestedPlatforms.length > 0 || parsed.requestedArchs.length > 0) {
+      throw new Error(
+        "[package] --all-platforms cannot be combined with explicit platform or arch flags",
+      );
+    }
+    if (platform !== "darwin") {
+      throw new Error(
+        `[package] --all-platforms is only supported on macOS hosts (current: ${platform})`,
+      );
+    }
+    return MAC_ALL_PLATFORM_TARGETS.map((target) => ({ ...target }));
+  }
+
+  const platforms =
+    parsed.requestedPlatforms.length > 0
+      ? parsed.requestedPlatforms
+      : [hostPlatformKey(platform)];
+  const archs =
+    parsed.requestedArchs.length > 0
+      ? parsed.requestedArchs
+      : [hostArchKey(arch)];
+
+  const unsupported = archs.filter((value) => !SUPPORTED_CLI_ARCHS.has(value));
+  if (unsupported.length > 0) {
+    throw new Error(
+      `[package] unsupported Desktop CLI architecture(s): ${unsupported.join(", ")}. ` +
+        "Use --x64 or --arm64.",
+    );
+  }
+
+  return platforms.flatMap((targetPlatform) =>
+    archs.map((targetArch) => ({
+      platform: targetPlatform,
+      arch: targetArch,
+    })),
+  );
+}
+
+function formatTarget(target) {
+  return `${PLATFORM_CONFIG[target.platform].label} ${target.arch}`;
+}
+
+export function builderArgsForTarget(
+  target,
+  parsed,
+  version,
+  {
+    disableMacNotarize = false,
+    hostPlatform = process.platform,
+    useScopedOutputDir = false,
+  } = {},
+) {
+  const builderArgs = [];
+  if (version) builderArgs.push(`-c.extraMetadata.version=${version}`);
+  if (disableMacNotarize) builderArgs.push("-c.mac.notarize=false");
+  builderArgs.push(PLATFORM_CONFIG[target.platform].builderFlag);
+  const requestedTargets = parsed.platformTargets[target.platform];
+  if (
+    target.platform === "linux" &&
+    hostPlatform !== "linux" &&
+    requestedTargets.length === 0
+  ) {
+    // electron-builder only guarantees AppImage/Snap when cross-building
+    // Linux from macOS/Windows. Keep `package:all` portable by defaulting
+    // to AppImage unless the caller explicitly requests Linux targets.
+    builderArgs.push("AppImage");
+  } else {
+    builderArgs.push(...requestedTargets);
+  }
+  builderArgs.push(`--${target.arch}`);
+  builderArgs.push(...parsed.sharedArgs);
+  if (useScopedOutputDir) {
+    builderArgs.push(
+      `-c.directories.output=dist/${target.platform}-${target.arch}`,
+    );
+  }
+  // electron-builder's update metadata file is `latest.yml` for Windows
+  // regardless of arch (only Linux gets an arch suffix automatically — see
+  // app-builder-lib's getArchPrefixForUpdateFile). Without an explicit
+  // channel override, building Windows x64 and arm64 in two invocations
+  // makes both publish `latest.yml` to the same GitHub Release, so the
+  // second upload overwrites the first and one of the two architectures
+  // ends up with no auto-update metadata. Route Windows arm64 to its own
+  // channel so x64 keeps `latest.yml` and arm64 ships `latest-arm64.yml`;
+  // the renderer-side updater pins the matching channel per arch.
+  if (target.platform === "win" && target.arch === "arm64") {
+    builderArgs.push("-c.publish.channel=latest-arm64");
+  }
+  return builderArgs;
+}
+
 function main() {
-  // Step 1: build + bundle the Go CLI via the existing script.
-  execFileSync("node", [resolve(here, "bundle-cli.mjs")], {
+  const passthrough = stripLeadingSeparator(process.argv.slice(2));
+  const parsed = parsePackageArgs(passthrough);
+  const buildMatrix = resolveBuildMatrix(parsed);
+  console.log(
+    `[package] build matrix → ${buildMatrix.map(formatTarget).join(", ")}`,
+  );
+
+  // Step 1: build the Electron main/preload/renderer bundles. Without
+  // this step electron-builder silently packages whatever is already in
+  // out/, which on a fresh checkout (or after a partial build) ships an
+  // app that white-screens because the renderer bundle is missing.
+  //
+  // CI invokes this script via `node scripts/package.mjs`, so we cannot
+  // rely on pnpm/npm to inject package-local binaries into PATH.
+  //
+  // `shell: true` is required on Windows: `node_modules/.bin/electron-vite`
+  // ships as a `.cmd` shim there, and Node's `spawnSync` does not honour
+  // PATHEXT when spawning a bare command without a shell — it would fail
+  // with `ENOENT`. On POSIX hosts the shim is a real executable so going
+  // through the shell is harmless. See
+  // https://nodejs.org/api/child_process.html#spawning-bat-and-cmd-files-on-windows
+  const viteResult = spawnSync("electron-vite", ["build"], {
     stdio: "inherit",
     cwd: desktopRoot,
+    env: envWithLocalBins(),
+    shell: true,
   });
+  if (viteResult.error) {
+    console.error(
+      "[package] failed to spawn electron-vite:",
+      viteResult.error.message,
+    );
+    process.exit(1);
+  }
+  if (viteResult.status !== 0) {
+    process.exit(viteResult.status ?? 1);
+  }
 
   // Step 2: derive the version that should be written into the app.
   const version = deriveVersion();
@@ -74,43 +363,62 @@ function main() {
     );
   }
 
-  // Step 3: assemble electron-builder args.
-  const passthrough = process.argv.slice(2);
-  const builderArgs = [];
-  if (version) builderArgs.push(`-c.extraMetadata.version=${version}`);
-
-  // Step 4: gracefully degrade for local dev builds. electron-builder.yml
-  // sets `notarize: true` so real releases notarize in-build (keeping the
-  // stapled .app consistent with latest-mac.yml's SHA512). But a mac dev
-  // who just wants to smoke-test a local package doesn't have Apple
-  // credentials, and would otherwise hit a hard failure at the notarize
-  // step. Detect the missing env and flip notarize off for this run only.
-  if (!process.env.APPLE_TEAM_ID) {
+  const disableMacNotarize = !process.env.APPLE_TEAM_ID;
+  if (disableMacNotarize) {
     console.warn(
       "[package] APPLE_TEAM_ID not set — skipping notarization (local dev build). " +
         "Set APPLE_ID + APPLE_APP_SPECIFIC_PASSWORD + APPLE_TEAM_ID for a release build.",
     );
-    builderArgs.push("-c.mac.notarize=false");
   }
 
-  builderArgs.push(...passthrough);
+  const useScopedOutputDir = buildMatrix.length > 1;
 
-  // Step 5: invoke electron-builder. pnpm puts node_modules/.bin on PATH
-  // for the script run, so spawnSync finds the binary without needing a
-  // shell wrapper (avoids any risk of argv interpolation).
-  const result = spawnSync("electron-builder", builderArgs, {
-    stdio: "inherit",
-    cwd: desktopRoot,
-  });
-
-  if (result.error) {
-    console.error(
-      "[package] failed to spawn electron-builder:",
-      result.error.message,
+  // Step 3: for each requested target, build the matching CLI into
+  // resources/bin/ and package that target in isolation.
+  for (const target of buildMatrix) {
+    console.log(`[package] bundling CLI → ${formatTarget(target)}`);
+    execFileSync(
+      "node",
+      [
+        bundleCliScript,
+        "--target-platform",
+        PLATFORM_CONFIG[target.platform].runtimePlatform,
+        "--target-arch",
+        target.arch,
+      ],
+      {
+        stdio: "inherit",
+        cwd: desktopRoot,
+      },
     );
-    process.exit(1);
+
+    const builderArgs = builderArgsForTarget(target, parsed, version, {
+      disableMacNotarize,
+      hostPlatform: process.platform,
+      useScopedOutputDir,
+    });
+
+    // Step 4: invoke electron-builder for the current target only.
+    // `shell: true` for the same Windows `.cmd` shim reason as the
+    // electron-vite invocation above.
+    const result = spawnSync("electron-builder", builderArgs, {
+      stdio: "inherit",
+      cwd: desktopRoot,
+      env: envWithLocalBins(),
+      shell: true,
+    });
+
+    if (result.error) {
+      console.error(
+        "[package] failed to spawn electron-builder:",
+        result.error.message,
+      );
+      process.exit(1);
+    }
+    if (result.status !== 0) {
+      process.exit(result.status ?? 1);
+    }
   }
-  process.exit(result.status ?? 1);
 }
 
 // Only run when invoked as a CLI, not when imported by a test file.

apps/desktop/scripts/package.test.mjs

@@ -1,5 +1,13 @@
+import { delimiter, resolve } from "node:path";
 import { describe, it, expect } from "vitest";
-import { normalizeGitVersion } from "./package.mjs";
+import {
+  builderArgsForTarget,
+  envWithLocalBins,
+  normalizeGitVersion,
+  parsePackageArgs,
+  resolveBuildMatrix,
+  stripLeadingSeparator,
+} from "./package.mjs";
 
 describe("normalizeGitVersion", () => {
   it("returns null for empty / nullish input", () => {
@@ -37,3 +45,229 @@ describe("normalizeGitVersion", () => {
     expect(normalizeGitVersion("abc1234")).toBe("0.0.0-abc1234");
   });
 });
+
+describe("stripLeadingSeparator", () => {
+  it("removes the leading -- inserted by npm/pnpm", () => {
+    expect(stripLeadingSeparator(["--", "--mac", "--arm64", "--publish", "always"])).toEqual([
+      "--mac", "--arm64", "--publish", "always",
+    ]);
+  });
+
+  it("leaves args untouched when there is no leading --", () => {
+    expect(stripLeadingSeparator(["--mac", "--arm64"])).toEqual(["--mac", "--arm64"]);
+  });
+
+  it("does not strip a -- that appears mid-argv", () => {
+    expect(stripLeadingSeparator(["--mac", "--", "--arm64"])).toEqual([
+      "--mac", "--", "--arm64",
+    ]);
+  });
+
+  it("handles an empty array", () => {
+    expect(stripLeadingSeparator([])).toEqual([]);
+  });
+});
+
+describe("parsePackageArgs", () => {
+  it("collects per-platform targets and shared args", () => {
+    expect(
+      parsePackageArgs([
+        "--win", "nsis",
+        "--mac", "dmg", "zip",
+        "--arm64",
+        "--publish", "never",
+      ]),
+    ).toEqual({
+      allPlatforms: false,
+      sharedArgs: ["--publish", "never"],
+      platformTargets: {
+        mac: ["dmg", "zip"],
+        win: ["nsis"],
+        linux: [],
+      },
+      requestedPlatforms: ["win", "mac"],
+      requestedArchs: ["arm64"],
+    });
+  });
+
+  it("expands combined short flags", () => {
+    expect(parsePackageArgs(["-mw", "--x64"]).requestedPlatforms).toEqual([
+      "mac",
+      "win",
+    ]);
+  });
+
+  it("tracks the all-platforms shortcut", () => {
+    expect(parsePackageArgs(["--all-platforms", "--publish", "never"]).allPlatforms).toBe(true);
+  });
+});
+
+describe("resolveBuildMatrix", () => {
+  it("defaults to the current host platform and arch", () => {
+    expect(
+      resolveBuildMatrix(
+        {
+          allPlatforms: false,
+          sharedArgs: [],
+          platformTargets: { mac: [], win: [], linux: [] },
+          requestedPlatforms: [],
+          requestedArchs: [],
+        },
+        "darwin",
+        "arm64",
+      ),
+    ).toEqual([{ platform: "mac", arch: "arm64" }]);
+  });
+
+  it("expands all-platforms on macOS", () => {
+    expect(
+      resolveBuildMatrix(
+        {
+          allPlatforms: true,
+          sharedArgs: [],
+          platformTargets: { mac: [], win: [], linux: [] },
+          requestedPlatforms: [],
+          requestedArchs: [],
+        },
+        "darwin",
+        "arm64",
+      ),
+    ).toEqual([
+      { platform: "mac", arch: "arm64" },
+      { platform: "win", arch: "x64" },
+      { platform: "win", arch: "arm64" },
+      { platform: "linux", arch: "x64" },
+      { platform: "linux", arch: "arm64" },
+    ]);
+  });
+
+  it("rejects unsupported architectures", () => {
+    expect(() =>
+      resolveBuildMatrix(
+        {
+          allPlatforms: false,
+          sharedArgs: [],
+          platformTargets: { mac: [], win: [], linux: [] },
+          requestedPlatforms: ["win"],
+          requestedArchs: ["universal"],
+        },
+        "darwin",
+        "arm64",
+      ),
+    ).toThrow(/unsupported Desktop CLI architecture/);
+  });
+});
+
+describe("builderArgsForTarget", () => {
+  it("adds scoped output directories for multi-target builds", () => {
+    expect(
+      builderArgsForTarget(
+        { platform: "win", arch: "arm64" },
+        {
+          allPlatforms: false,
+          sharedArgs: ["--publish", "never"],
+          platformTargets: { mac: [], win: ["nsis"], linux: [] },
+          requestedPlatforms: ["win"],
+          requestedArchs: ["arm64"],
+        },
+        "1.2.3",
+        {
+          disableMacNotarize: true,
+          hostPlatform: "darwin",
+          useScopedOutputDir: true,
+        },
+      ),
+    ).toEqual([
+      "-c.extraMetadata.version=1.2.3",
+      "-c.mac.notarize=false",
+      "--win",
+      "nsis",
+      "--arm64",
+      "--publish",
+      "never",
+      "-c.directories.output=dist/win-arm64",
+      "-c.publish.channel=latest-arm64",
+    ]);
+  });
+
+  it("does not override the publish channel for Windows x64 (default latest.yml)", () => {
+    expect(
+      builderArgsForTarget(
+        { platform: "win", arch: "x64" },
+        {
+          allPlatforms: false,
+          sharedArgs: ["--publish", "always"],
+          platformTargets: { mac: [], win: ["nsis"], linux: [] },
+          requestedPlatforms: ["win"],
+          requestedArchs: ["x64"],
+        },
+        "1.2.3",
+        { hostPlatform: "win32", useScopedOutputDir: true },
+      ),
+    ).toEqual([
+      "-c.extraMetadata.version=1.2.3",
+      "--win",
+      "nsis",
+      "--x64",
+      "--publish",
+      "always",
+      "-c.directories.output=dist/win-x64",
+    ]);
+  });
+
+  it("defaults linux cross-builds to AppImage on non-Linux hosts", () => {
+    expect(
+      builderArgsForTarget(
+        { platform: "linux", arch: "x64" },
+        {
+          allPlatforms: false,
+          sharedArgs: ["--publish", "never"],
+          platformTargets: { mac: [], win: [], linux: [] },
+          requestedPlatforms: ["linux"],
+          requestedArchs: ["x64"],
+        },
+        "1.2.3",
+        { hostPlatform: "darwin" },
+      ),
+    ).toEqual([
+      "-c.extraMetadata.version=1.2.3",
+      "--linux",
+      "AppImage",
+      "--x64",
+      "--publish",
+      "never",
+    ]);
+  });
+});
+
+describe("envWithLocalBins", () => {
+  it("prepends desktop-local binary directories to PATH", () => {
+    const desktopRoot = "/repo/apps/desktop";
+    const result = envWithLocalBins(
+      { PATH: ["/usr/local/bin", "/usr/bin"].join(delimiter) },
+      desktopRoot,
+    );
+    expect(result.PATH.split(delimiter)).toEqual([
+      resolve(desktopRoot, "node_modules", ".bin"),
+      resolve(desktopRoot, "..", "..", "node_modules", ".bin"),
+      "/usr/local/bin",
+      "/usr/bin",
+    ]);
+  });
+
+  it("preserves an existing Path key and avoids duplicate entries", () => {
+    const desktopRoot = "/repo/apps/desktop";
+    const desktopBin = resolve(desktopRoot, "node_modules", ".bin");
+    const workspaceBin = resolve(desktopRoot, "..", "..", "node_modules", ".bin");
+    const result = envWithLocalBins(
+      { Path: [desktopBin, "runner-bin", workspaceBin].join(delimiter) },
+      desktopRoot,
+    );
+    expect(result).not.toHaveProperty("PATH");
+    expect(result.Path.split(delimiter)).toEqual([
+      desktopBin,
+      workspaceBin,
+      "runner-bin",
+    ]);
+  });
+});

apps/desktop/src/main/cli-bootstrap.ts

@@ -8,35 +8,15 @@ import { pipeline } from "stream/promises";
 import { tmpdir } from "os";
 import { Readable } from "stream";
 
-// Desktop bootstraps its own copy of the `multica` CLI into userData on first
-// launch, so users never have to brew-install anything. Build-time decoupled:
-// we don't bundle the binary into the .app, we download whatever the upstream
-// release is at first run.
+import { selectPlatformReleaseAssetName } from "./cli-release-asset";
+
+// Desktop prefers the bundled `multica` CLI shipped inside the app for
+// same-repo builds, but it can also repair or bootstrap a managed copy in
+// userData on first launch when the bundled binary is missing or unusable.
 
 const GITHUB_LATEST_BASE =
   "https://github.com/multica-ai/multica/releases/latest/download";
 
-function platformAssetName(): string {
-  const osMap: Record<string, string> = {
-    darwin: "darwin",
-    linux: "linux",
-    win32: "windows",
-  };
-  const archMap: Record<string, string> = {
-    x64: "amd64",
-    arm64: "arm64",
-  };
-  const os = osMap[process.platform];
-  const arch = archMap[process.arch];
-  if (!os || !arch) {
-    throw new Error(
-      `unsupported platform for CLI auto-install: ${process.platform}/${process.arch}`,
-    );
-  }
-  const ext = process.platform === "win32" ? "zip" : "tar.gz";
-  return `multica_${os}_${arch}.${ext}`;
-}
-
 function binaryName(): string {
   return process.platform === "win32" ? "multica.exe" : "multica";
 }
@@ -92,14 +72,8 @@ async function sha256OfFile(path: string): Promise<string> {
 async function verifyChecksum(
   archivePath: string,
   assetName: string,
+  expected: string,
 ): Promise<void> {
-  const checksums = await fetchChecksums();
-  const expected = checksums.get(assetName);
-  if (!expected) {
-    throw new Error(
-      `no checksum for ${assetName} in checksums.txt — refusing to install unverified binary`,
-    );
-  }
   const actual = await sha256OfFile(archivePath);
   if (actual.toLowerCase() !== expected) {
     throw new Error(
@@ -118,7 +92,14 @@ async function extractArchive(archive: string, dest: string): Promise<void> {
 
 async function installFresh(): Promise<string> {
   const target = managedCliPath();
-  const assetName = platformAssetName();
+  const checksums = await fetchChecksums();
+  const assetName = selectPlatformReleaseAssetName(checksums.keys());
+  const expectedChecksum = checksums.get(assetName);
+  if (!expectedChecksum) {
+    throw new Error(
+      `no checksum for ${assetName} in checksums.txt — refusing to install unverified binary`,
+    );
+  }
   const url = `${GITHUB_LATEST_BASE}/${assetName}`;
 
   const workDir = join(tmpdir(), `multica-cli-${Date.now()}`);
@@ -130,7 +111,7 @@ async function installFresh(): Promise<string> {
     await downloadToFile(url, archivePath);
 
     console.log(`[cli-bootstrap] verifying ${assetName} against checksums.txt`);
-    await verifyChecksum(archivePath, assetName);
+    await verifyChecksum(archivePath, assetName, expectedChecksum);
 
     console.log(`[cli-bootstrap] extracting ${assetName}`);
     await extractArchive(archivePath, workDir);
@@ -143,6 +124,7 @@ async function installFresh(): Promise<string> {
     }
 
     await mkdir(dirname(target), { recursive: true });
+    await rm(target, { force: true }).catch(() => {});
     await rename(extractedBin, target);
     await chmod(target, 0o755);
 
@@ -166,8 +148,10 @@ async function installFresh(): Promise<string> {
  * the managed userData location, returns it immediately. Otherwise downloads
  * the latest release asset for the current platform and installs it.
  */
-export async function ensureManagedCli(): Promise<string> {
+export async function ensureManagedCli(
+  options: { forceInstall?: boolean } = {},
+): Promise<string> {
   const target = managedCliPath();
-  if (existsSync(target)) return target;
+  if (existsSync(target) && !options.forceInstall) return target;
   return installFresh();
 }

apps/desktop/src/main/cli-release-asset.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+
+import { selectPlatformReleaseAssetName } from "./cli-release-asset";
+
+describe("selectPlatformReleaseAssetName", () => {
+  it("prefers the versioned archive name when both exist", () => {
+    const assetNames = [
+      "checksums.txt",
+      "multica_darwin_amd64.tar.gz",
+      "multica-cli-1.2.3-darwin-amd64.tar.gz",
+    ];
+
+    expect(selectPlatformReleaseAssetName(assetNames, "darwin", "x64")).toBe(
+      "multica-cli-1.2.3-darwin-amd64.tar.gz",
+    );
+  });
+
+  it("falls back to the legacy archive name when only legacy is present", () => {
+    const assetNames = ["checksums.txt", "multica_darwin_amd64.tar.gz"];
+
+    expect(selectPlatformReleaseAssetName(assetNames, "darwin", "x64")).toBe(
+      "multica_darwin_amd64.tar.gz",
+    );
+  });
+
+  it("matches the renamed darwin archive from release assets", () => {
+    const assetNames = [
+      "checksums.txt",
+      "multica-cli-1.2.3-darwin-amd64.tar.gz",
+      "multica-cli-1.2.3-darwin-arm64.tar.gz",
+      "multica-cli-1.2.3-linux-amd64.tar.gz",
+    ];
+
+    expect(selectPlatformReleaseAssetName(assetNames, "darwin", "x64")).toBe(
+      "multica-cli-1.2.3-darwin-amd64.tar.gz",
+    );
+  });
+
+  it("matches the renamed windows zip archive", () => {
+    const assetNames = [
+      "multica-cli-1.2.3-windows-amd64.zip",
+      "multica-cli-1.2.3-linux-amd64.tar.gz",
+    ];
+
+    expect(selectPlatformReleaseAssetName(assetNames, "win32", "x64")).toBe(
+      "multica-cli-1.2.3-windows-amd64.zip",
+    );
+  });
+
+  it("fails when the current platform asset is missing", () => {
+    expect(() =>
+      selectPlatformReleaseAssetName(
+        ["multica-cli-1.2.3-linux-amd64.tar.gz", "multica_linux_amd64.tar.gz"],
+        "darwin",
+        "arm64",
+      ),
+    ).toThrow(/no release asset found/);
+  });
+});

apps/desktop/src/main/cli-release-asset.ts

@@ -0,0 +1,62 @@
+const RELEASE_ARCHIVE_PREFIX = "multica-cli-";
+
+function platformArchiveDescriptor(
+  platform: NodeJS.Platform = process.platform,
+  arch: string = process.arch,
+): { os: string; arch: string; ext: string } {
+  const osMap: Record<string, string> = {
+    darwin: "darwin",
+    linux: "linux",
+    win32: "windows",
+  };
+  const archMap: Record<string, string> = {
+    x64: "amd64",
+    arm64: "arm64",
+  };
+  const os = osMap[platform];
+  const mappedArch = archMap[arch];
+  if (!os || !mappedArch) {
+    throw new Error(
+      `unsupported platform for CLI auto-install: ${platform}/${arch}`,
+    );
+  }
+  const ext = platform === "win32" ? "zip" : "tar.gz";
+  return { os, arch: mappedArch, ext };
+}
+
+export function selectPlatformReleaseAssetName(
+  assetNames: Iterable<string>,
+  platform: NodeJS.Platform = process.platform,
+  arch: string = process.arch,
+): string {
+  const { os, arch: mappedArch, ext } = platformArchiveDescriptor(
+    platform,
+    arch,
+  );
+  const names = [...assetNames];
+
+  // Prefer the versioned `multica-cli-<v>-<os>-<arch>.<ext>` name; fall
+  // back to the legacy `multica_<os>_<arch>.<ext>` so older releases that
+  // only ship the legacy archive keep working.
+  const suffix = `-${os}-${mappedArch}.${ext}`;
+  const matches = names.filter(
+    (name) =>
+      name.startsWith(RELEASE_ARCHIVE_PREFIX) && name.endsWith(suffix),
+  );
+
+  if (matches.length === 1) {
+    return matches[0];
+  }
+  if (matches.length > 1) {
+    throw new Error(
+      `multiple release assets matched current platform ${suffix}: ${matches.join(", ")}`,
+    );
+  }
+
+  const legacyName = `multica_${os}_${mappedArch}.${ext}`;
+  if (names.includes(legacyName)) {
+    return legacyName;
+  }
+
+  throw new Error(`no release asset found for current platform: ${suffix}`);
+}

apps/desktop/src/main/daemon-manager.ts

@@ -316,6 +316,36 @@ function bundledCliPath(): string {
   );
 }
 
+async function probeCliBinary(
+  bin: string,
+  source: "bundled" | "managed" | "path",
+): Promise<string | null> {
+  try {
+    const stdout = await new Promise<string>((resolve, reject) => {
+      execFile(
+        bin,
+        ["version", "--output", "json"],
+        { timeout: 5_000 },
+        (err, out) => {
+          if (err) reject(err);
+          else resolve(out);
+        },
+      );
+    });
+    const parsed = JSON.parse(stdout) as { version?: string };
+    if (typeof parsed.version === "string" && parsed.version.length > 0) {
+      return parsed.version;
+    }
+    console.warn(
+      `[daemon] ignoring ${source} CLI at ${bin}: version output was missing or invalid`,
+    );
+    return null;
+  } catch (err) {
+    console.warn(`[daemon] ignoring ${source} CLI at ${bin}:`, err);
+    return null;
+  }
+}
+
 /**
  * Returns a usable `multica` binary path. Priority:
  *   1. Cached result from a previous successful resolve.
@@ -339,27 +369,55 @@ async function resolveCliBinary(): Promise<string | null> {
   cliResolvePromise = (async () => {
     const bundled = bundledCliPath();
     if (existsSync(bundled)) {
-      console.log(`[daemon] using bundled CLI at ${bundled}`);
-      cachedCliBinary = bundled;
-      return bundled;
+      const version = await probeCliBinary(bundled, "bundled");
+      if (version) {
+        console.log(`[daemon] using bundled CLI at ${bundled}`);
+        cachedCliBinary = bundled;
+        cachedCliBinaryVersion = version;
+        return bundled;
+      }
     }
 
     const managed = managedCliPath();
     if (existsSync(managed)) {
-      cachedCliBinary = managed;
-      return managed;
+      const version = await probeCliBinary(managed, "managed");
+      if (version) {
+        cachedCliBinary = managed;
+        cachedCliBinaryVersion = version;
+        return managed;
+      }
     }
 
     try {
-      const installed = await ensureManagedCli();
-      cachedCliBinary = installed;
-      return installed;
+      const installed = await ensureManagedCli({
+        forceInstall: existsSync(managed),
+      });
+      const version = await probeCliBinary(installed, "managed");
+      if (version) {
+        cachedCliBinary = installed;
+        cachedCliBinaryVersion = version;
+        return installed;
+      }
+      console.warn(
+        `[daemon] managed CLI at ${installed} failed validation after install`,
+      );
     } catch (err) {
       console.warn("[daemon] CLI auto-install failed, falling back to PATH:", err);
-      const onPath = findCliOnPath();
-      cachedCliBinary = onPath;
-      return onPath;
     }
+
+    const onPath = findCliOnPath();
+    if (onPath) {
+      const version = await probeCliBinary(onPath, "path");
+      if (version) {
+        cachedCliBinary = onPath;
+        cachedCliBinaryVersion = version;
+        return onPath;
+      }
+    }
+
+    cachedCliBinary = null;
+    cachedCliBinaryVersion = null;
+    return null;
   })();
 
   try {
@@ -370,11 +428,10 @@ async function resolveCliBinary(): Promise<string | null> {
 }
 
 /**
- * Reads the version of the currently resolved CLI binary by invoking
- * `multica version --output json`. Cached for the process lifetime — the
- * bundled binary doesn't change after `bundle-cli.mjs` runs at dev/build time.
+ * Reads the version of the currently resolved CLI binary. Cached for the
+ * process lifetime — the bundled binary doesn't change after bundle time.
  * Returns null on any failure (unknown `go` at bundle time, broken binary,
- * etc.) so callers can fail open.
+ * wrong-arch bundled binary, etc.) so callers can fail open.
  */
 async function getCliBinaryVersion(): Promise<string | null> {
   if (cachedCliBinaryVersion !== undefined) return cachedCliBinaryVersion;
@@ -383,24 +440,7 @@ async function getCliBinaryVersion(): Promise<string | null> {
     cachedCliBinaryVersion = null;
     return null;
   }
-  try {
-    const stdout = await new Promise<string>((resolve, reject) => {
-      execFile(
-        bin,
-        ["version", "--output", "json"],
-        { timeout: 5_000 },
-        (err, out) => {
-          if (err) reject(err);
-          else resolve(out);
-        },
-      );
-    });
-    const parsed = JSON.parse(stdout) as { version?: string };
-    cachedCliBinaryVersion = parsed.version ?? null;
-  } catch (err) {
-    console.warn("[daemon] failed to read CLI binary version:", err);
-    cachedCliBinaryVersion = null;
-  }
+  cachedCliBinaryVersion = await probeCliBinary(bin, "path");
   return cachedCliBinaryVersion;
 }
 
@@ -598,11 +638,12 @@ function profileArgs(active: ActiveProfile): string[] {
 
 // Env passed to every CLI child so the daemon process knows it was spawned
 // by the Desktop app. The server uses this to mark runtimes as managed and
-// hide CLI self-update UI.
-const DESKTOP_SPAWN_ENV = {
-  ...process.env,
-  MULTICA_LAUNCHED_BY: "desktop",
-};
+// hide CLI self-update UI. Computed lazily so it picks up the PATH fix
+// applied by fix-path in main/index.ts — as a top-level const it would
+// snapshot process.env at import time, before that block runs.
+function desktopSpawnEnv(): NodeJS.ProcessEnv {
+  return { ...process.env, MULTICA_LAUNCHED_BY: "desktop" };
+}
 
 async function startDaemon(): Promise<{ success: boolean; error?: string }> {
   const bin = await resolveCliBinary();
@@ -624,7 +665,7 @@ async function startDaemon(): Promise<{ success: boolean; error?: string }> {
     execFile(
       bin,
       args,
-      { timeout: 20_000, env: DESKTOP_SPAWN_ENV },
+      { timeout: 20_000, env: desktopSpawnEnv() },
       (err) => {
         if (err) {
           currentState = "stopped";

apps/desktop/src/main/external-url.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+
+vi.mock("electron", () => ({
+  shell: { openExternal: vi.fn().mockResolvedValue(undefined) },
+}));
+
+import { shell } from "electron";
+import { isSafeExternalHttpUrl, openExternalSafely } from "./external-url";
+
+describe("isSafeExternalHttpUrl", () => {
+  it("allows http and https URLs", () => {
+    expect(isSafeExternalHttpUrl("https://multica.ai")).toBe(true);
+    expect(isSafeExternalHttpUrl("http://localhost:3000/auth")).toBe(true);
+  });
+
+  it("allows https URLs with embedded credentials", () => {
+    // WHATWG URL parses these as https; OS-level handling is the shell's concern.
+    expect(isSafeExternalHttpUrl("https://user:pass@example.com")).toBe(true);
+  });
+
+  it("normalizes scheme casing so uppercase variants can't bypass", () => {
+    expect(isSafeExternalHttpUrl("HTTPS://example.com")).toBe(true);
+    expect(isSafeExternalHttpUrl("FILE:///etc/passwd")).toBe(false);
+  });
+
+  it("rejects dangerous pseudo-schemes", () => {
+    expect(isSafeExternalHttpUrl("javascript:alert(1)")).toBe(false);
+    expect(
+      isSafeExternalHttpUrl("data:text/html,<script>alert(1)</script>"),
+    ).toBe(false);
+  });
+
+  it("rejects filesystem and network transport schemes", () => {
+    expect(isSafeExternalHttpUrl("file:///etc/passwd")).toBe(false);
+    expect(isSafeExternalHttpUrl("ftp://example.com/x")).toBe(false);
+    expect(isSafeExternalHttpUrl("smb://share/x")).toBe(false);
+  });
+
+  it("rejects local-handler schemes used in past RCE chains", () => {
+    expect(isSafeExternalHttpUrl("vscode://file/test")).toBe(false);
+    expect(isSafeExternalHttpUrl("ms-msdt:/id%20PCWDiagnostic")).toBe(false);
+  });
+
+  it("rejects mailto and other non-web schemes", () => {
+    expect(isSafeExternalHttpUrl("mailto:test@example.com")).toBe(false);
+    expect(isSafeExternalHttpUrl("tel:+15551234567")).toBe(false);
+  });
+
+  it("rejects empty, whitespace, and malformed input", () => {
+    expect(isSafeExternalHttpUrl("")).toBe(false);
+    expect(isSafeExternalHttpUrl(" ")).toBe(false);
+    expect(isSafeExternalHttpUrl("not a url")).toBe(false);
+    expect(isSafeExternalHttpUrl("http://")).toBe(false);
+  });
+});
+
+describe("openExternalSafely", () => {
+  beforeEach(() => {
+    vi.mocked(shell.openExternal).mockClear();
+  });
+
+  it("forwards http/https URLs to shell.openExternal", () => {
+    openExternalSafely("https://multica.ai");
+    expect(shell.openExternal).toHaveBeenCalledWith("https://multica.ai");
+  });
+
+  it("does not call shell.openExternal for rejected schemes", () => {
+    openExternalSafely("file:///etc/passwd");
+    openExternalSafely("javascript:alert(1)");
+    openExternalSafely("not a url");
+    expect(shell.openExternal).not.toHaveBeenCalled();
+  });
+});

apps/desktop/src/main/external-url.ts

@@ -0,0 +1,38 @@
+import { shell } from "electron";
+
+// True when the URL parses and uses http/https — the only schemes we let
+// reach `shell.openExternal`. Scheme comparison is safe because the WHATWG
+// URL parser lowercases the protocol field.
+export function isSafeExternalHttpUrl(url: string): boolean {
+  return getHttpProtocol(url) !== null;
+}
+
+// Canonical wrapper around shell.openExternal. All renderer-controlled URLs
+// that eventually reach the OS shell MUST flow through here; direct calls
+// to `shell.openExternal` elsewhere in the main process are banned by the
+// no-restricted-syntax rule in apps/desktop/eslint.config.mjs.
+export function openExternalSafely(url: string): Promise<void> | void {
+  if (getHttpProtocol(url) === null) {
+    console.warn(`[security] blocked openExternal: ${describeScheme(url)}`);
+    return;
+  }
+  return shell.openExternal(url);
+}
+
+function getHttpProtocol(url: string): "http:" | "https:" | null {
+  try {
+    const { protocol } = new URL(url);
+    if (protocol === "http:" || protocol === "https:") return protocol;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function describeScheme(url: string): string {
+  try {
+    return `scheme=${new URL(url).protocol}`;
+  } catch {
+    return "invalid URL";
+  }
+}

apps/desktop/src/main/index.ts

@@ -1,8 +1,36 @@
-import { app, shell, BrowserWindow, ipcMain } from "electron";
+import { app, BrowserWindow, ipcMain, nativeImage } from "electron";
+import { homedir } from "os";
 import { join } from "path";
 import { electronApp, optimizer, is } from "@electron-toolkit/utils";
+import fixPath from "fix-path";
 import { setupAutoUpdater } from "./updater";
 import { setupDaemonManager } from "./daemon-manager";
+import { openExternalSafely } from "./external-url";
+
+// Bundled icon used for dev-mode dock/taskbar branding. In production the
+// app bundle icon (from electron-builder) wins; this path is only consumed
+// by the `is.dev` branch below.
+const DEV_ICON_PATH = join(__dirname, "../../resources/icon.png");
+
+// macOS/Linux GUI launches inherit a minimal PATH from launchd that omits
+// the user's shell config (~/.zshrc, Homebrew, nvm, ~/.local/bin, etc.).
+// Run the user's login shell once to recover the real PATH so the bundled
+// multica CLI can find agent binaries like claude/codex/opencode. Must run
+// before any child_process.spawn / execFile call in the main process —
+// ES module imports are hoisted, so this block executes before createWindow
+// or any daemon-manager spawn.
+if (process.platform !== "win32") {
+  fixPath();
+  // Fallback: prepend common install locations in case fix-path came up
+  // short (broken shell rc, non-interactive $SHELL, missing entries). Safe
+  // to duplicate — PATH lookups short-circuit on first match.
+  const fallbackPaths = [
+    "/opt/homebrew/bin",
+    "/usr/local/bin",
+    join(homedir(), ".local/bin"),
+  ];
+  process.env.PATH = `${fallbackPaths.join(":")}:${process.env.PATH ?? ""}`;
+}
 
 const PROTOCOL = "multica";
 
@@ -21,6 +49,19 @@ function handleDeepLink(url: string): void {
       if (token && mainWindow) {
         mainWindow.webContents.send("auth:token", token);
       }
+      return;
+    }
+
+    // multica://invite/<invitationId>
+    // Dispatched from the web invite page when the user chooses "Open in
+    // desktop app". The renderer opens the invite overlay — no tab, no
+    // route persistence, so deep-linking the same invite twice stays safe.
+    if (parsed.hostname === "invite") {
+      const id = parsed.pathname.replace(/^\//, "");
+      if (id && mainWindow) {
+        mainWindow.webContents.send("invite:open", decodeURIComponent(id));
+      }
+      return;
     }
   } catch {
     // Ignore malformed URLs
@@ -39,6 +80,9 @@ function createWindow(): void {
     trafficLightPosition: { x: 16, y: 13 },
     show: false,
     autoHideMenuBar: true,
+    // Windows/Linux pick up the window/taskbar icon from this option in
+    // dev — on macOS it's ignored (dock comes from app.dock.setIcon below).
+    ...(is.dev ? { icon: DEV_ICON_PATH } : {}),
     webPreferences: {
       preload: join(__dirname, "../preload/index.js"),
       sandbox: false,
@@ -61,7 +105,7 @@ function createWindow(): void {
   });
 
   mainWindow.webContents.setWindowOpenHandler((details) => {
-    shell.openExternal(details.url);
+    openExternalSafely(details.url);
     return { action: "deny" };
   });
 
@@ -72,6 +116,27 @@ 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.)
+
+// DESKTOP_APP_SUFFIX lets parallel worktrees run dev Electron side-by-side
+// without fighting for the shared single-instance lock. The suffix is
+// appended to the app name + userData path, so each worktree gets its own
+// lock file. Default (no env var) keeps behavior unchanged — the common
+// single-worktree case still lands at "Multica Canary".
+const DEV_APP_NAME = process.env.DESKTOP_APP_SUFFIX
+  ? `Multica Canary ${process.env.DESKTOP_APP_SUFFIX}`
+  : "Multica Canary";
+
+if (is.dev) {
+  app.setName(DEV_APP_NAME);
+  app.setPath("userData", join(app.getPath("appData"), DEV_APP_NAME));
+}
+
 // --- Protocol registration -----------------------------------------------
 
 if (process.defaultApp) {
@@ -103,19 +168,33 @@ if (!gotTheLock) {
   });
 
   app.whenReady().then(() => {
-    electronApp.setAppUserModelId("ai.multica.desktop");
+    electronApp.setAppUserModelId(
+      is.dev ? "ai.multica.desktop.dev" : "ai.multica.desktop",
+    );
+
+    // macOS: replace the default Electron dock icon with the bundled logo
+    // so the Canary dev build is visually distinct from a stock Electron
+    // run. `app.dock` is macOS-only — guard the call.
+    if (is.dev && process.platform === "darwin" && app.dock) {
+      const icon = nativeImage.createFromPath(DEV_ICON_PATH);
+      if (!icon.isEmpty()) app.dock.setIcon(icon);
+    }
 
     app.on("browser-window-created", (_, window) => {
       optimizer.watchWindowShortcuts(window);
     });
 
-    // IPC: open URL in default browser (used by renderer for Google login)
+    // IPC: open URL in default browser (used by renderer for Google login).
+    // All scheme-allowlist enforcement lives in openExternalSafely — this
+    // is the single audit point for renderer-controlled URLs reaching the
+    // OS shell under the app's intentional webSecurity: false + sandbox:
+    // false configuration.
     ipcMain.handle("shell:openExternal", (_event, url: string) => {
-      return shell.openExternal(url);
+      return openExternalSafely(url);
     });
 
     // 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/main/updater.ts

@@ -1,9 +1,31 @@
 import { autoUpdater } from "electron-updater";
-import { BrowserWindow, ipcMain } from "electron";
+import { app, BrowserWindow, ipcMain } from "electron";
 
 autoUpdater.autoDownload = false;
 autoUpdater.autoInstallOnAppQuit = true;
 
+// Windows arm64 ships its own update metadata channel because
+// electron-builder's `latest.yml` is not arch-suffixed on Windows — both
+// arches would otherwise collide on the same file in the GitHub Release.
+// See scripts/package.mjs (builderArgsForTarget) for the publish-side half
+// of this pact. Pin the channel here so arm64 clients fetch
+// `latest-arm64.yml` instead of the x64 metadata.
+if (process.platform === "win32" && process.arch === "arm64") {
+  autoUpdater.channel = "latest-arm64";
+}
+
+const STARTUP_CHECK_DELAY_MS = 5_000;
+const PERIODIC_CHECK_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
+
+export type ManualUpdateCheckResult =
+  | {
+      ok: true;
+      currentVersion: string;
+      latestVersion: string;
+      available: boolean;
+    }
+  | { ok: false; error: string };
+
 export function setupAutoUpdater(getMainWindow: () => BrowserWindow | null): void {
   autoUpdater.on("update-available", (info) => {
     const win = getMainWindow();
@@ -37,10 +59,42 @@ export function setupAutoUpdater(getMainWindow: () => BrowserWindow | null): voi
     autoUpdater.quitAndInstall(false, true);
   });
 
-  // Check for updates after a short delay to avoid blocking startup
+  ipcMain.handle("updater:check", async (): Promise<ManualUpdateCheckResult> => {
+    try {
+      const result = await autoUpdater.checkForUpdates();
+      const currentVersion = app.getVersion();
+      // Trust electron-updater's own decision rather than re-deriving it from
+      // a version-string compare. The two diverge for pre-release channels,
+      // staged rollouts, downgrades, and minimum-system-version gates — in
+      // those cases updateInfo.version differs from app.getVersion() but no
+      // `update-available` event fires, so showing "available" here would
+      // promise a download prompt that never appears.
+      return {
+        ok: true,
+        currentVersion,
+        latestVersion: result?.updateInfo.version ?? currentVersion,
+        available: result?.isUpdateAvailable ?? false,
+      };
+    } catch (err) {
+      return {
+        ok: false,
+        error: err instanceof Error ? err.message : String(err),
+      };
+    }
+  });
+
+  // Initial check shortly after startup so we don't block boot.
   setTimeout(() => {
     autoUpdater.checkForUpdates().catch((err) => {
       console.error("Failed to check for updates:", err);
     });
-  }, 5000);
+  }, STARTUP_CHECK_DELAY_MS);
+
+  // Background poll so long-running sessions still pick up new releases
+  // without requiring the user to restart the app.
+  setInterval(() => {
+    autoUpdater.checkForUpdates().catch((err) => {
+      console.error("Periodic update check failed:", err);
+    });
+  }, PERIODIC_CHECK_INTERVAL_MS);
 }

apps/desktop/src/preload/index.d.ts

@@ -3,6 +3,8 @@ import { ElectronAPI } from "@electron-toolkit/preload";
 interface DesktopAPI {
   /** Listen for auth token delivered via deep link. Returns an unsubscribe function. */
   onAuthToken: (callback: (token: string) => void) => () => void;
+  /** Listen for invitation IDs delivered via deep link. Returns an unsubscribe function. */
+  onInviteOpen: (callback: (invitationId: string) => void) => () => void;
   /** Open a URL in the default browser. */
   openExternal: (url: string) => Promise<void>;
   /** Hide macOS traffic lights for full-screen modals; restore when false. */
@@ -51,6 +53,10 @@ interface UpdaterAPI {
   onUpdateDownloaded: (callback: () => void) => () => void;
   downloadUpdate: () => Promise<void>;
   installUpdate: () => Promise<void>;
+  checkForUpdates: () => Promise<
+    | { ok: true; currentVersion: string; latestVersion: string; available: boolean }
+    | { ok: false; error: string }
+  >;
 }
 
 declare global {

apps/desktop/src/preload/index.ts

@@ -11,6 +11,15 @@ const desktopAPI = {
       ipcRenderer.removeListener("auth:token", handler);
     };
   },
+  /** Listen for invitation IDs delivered via deep link */
+  onInviteOpen: (callback: (invitationId: string) => void) => {
+    const handler = (_event: Electron.IpcRendererEvent, invitationId: string) =>
+      callback(invitationId);
+    ipcRenderer.on("invite:open", handler);
+    return () => {
+      ipcRenderer.removeListener("invite:open", handler);
+    };
+  },
   /** Open a URL in the default browser */
   openExternal: (url: string) => ipcRenderer.invoke("shell:openExternal", url),
   /** Toggle immersive mode — hide macOS traffic lights for full-screen modals */
@@ -87,6 +96,10 @@ const updaterAPI = {
   },
   downloadUpdate: () => ipcRenderer.invoke("updater:download"),
   installUpdate: () => ipcRenderer.invoke("updater:install"),
+  checkForUpdates: (): Promise<
+    | { ok: true; currentVersion: string; latestVersion: string; available: boolean }
+    | { ok: false; error: string }
+  > => ipcRenderer.invoke("updater:check"),
 };
 
 if (process.contextIsolated) {

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

@@ -1,7 +1,8 @@
-import { useEffect } from "react";
+import { useEffect, useLayoutEffect, 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";
@@ -9,10 +10,22 @@ import { Toaster } from "sonner";
 import { DesktopLoginPage } from "./pages/login";
 import { DesktopShell } from "./components/desktop-layout";
 import { UpdateNotification } from "./components/update-notification";
+import { useTabStore } from "./stores/tab-store";
+import { useWindowOverlayStore } from "./stores/window-overlay-store";
+
 
 function AppContent() {
   const user = useAuthStore((s) => s.user);
   const isLoading = useAuthStore((s) => s.isLoading);
+  const qc = useQueryClient();
+  // Deep-link login runs loginWithToken → syncToken → listWorkspaces →
+  // 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 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
   // can pick the matching CLI profile (server_url from ~/.multica config).
@@ -20,21 +33,40 @@ function AppContent() {
     window.daemonAPI.setTargetApiUrl(DAEMON_TARGET_API_URL);
   }, []);
 
-  // Listen for auth token delivered via deep link (multica://auth/callback?token=...)
+  // Listen for invite IDs delivered via deep link (multica://invite/<id>).
+  // We open the overlay regardless of login state — if the user isn't logged
+  // in, InvitePage's queries will fail and render the "not found" state,
+  // which is acceptable; the expected pre-flight happens in the web app
+  // (login + next=/invite/... dance) before the deep link is ever dispatched.
   useEffect(() => {
-    return window.desktopAPI.onAuthToken(async (token) => {
-      try {
-        const loggedIn = await useAuthStore.getState().loginWithToken(token);
-        await window.daemonAPI.syncToken(token, loggedIn.id);
-        const wsList = await api.listWorkspaces();
-        const lastWsId = localStorage.getItem("multica_workspace_id");
-        useWorkspaceStore.getState().hydrateWorkspace(wsList, lastWsId);
-      } catch {
-        // Token invalid or expired — user stays on login page
-      }
+    return window.desktopAPI.onInviteOpen((invitationId) => {
+      useWindowOverlayStore.getState().open({ type: "invite", invitationId });
     });
   }, []);
 
+  // Listen for auth token delivered via deep link (multica://auth/callback?token=...).
+  // daemonAPI.syncToken is handled separately by the [user] effect below, which
+  // fires whenever a user logs in (deep link, session restore, account switch).
+  useEffect(() => {
+    return window.desktopAPI.onAuthToken(async (token) => {
+      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();
+        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(() => {
     if (!user) return;
@@ -51,7 +83,74 @@ function AppContent() {
     })();
   }, [user]);
 
-  if (isLoading) {
+  // 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;
+
+  // Validate persisted tab state against the current user's workspace list,
+  // and pick an active workspace if none is set. Runs in useLayoutEffect
+  // (synchronously after render, before paint) rather than the render
+  // phase — the original render-phase pattern triggered React's
+  // "Cannot update a component while rendering a different component"
+  // warning because `switchWorkspace` is a Zustand setState that the
+  // TabBar is subscribed to. useLayoutEffect flushes both renders before
+  // the user sees anything, so there's no visible flicker.
+  useLayoutEffect(() => {
+    if (!workspaces) return;
+    const validSlugs = new Set(workspaces.map((w) => w.slug));
+    const tabStore = useTabStore.getState();
+    tabStore.validateWorkspaceSlugs(validSlugs);
+    if (!tabStore.activeWorkspaceSlug && workspaces.length > 0) {
+      tabStore.switchWorkspace(workspaces[0].slug);
+    }
+  }, [workspaces]);
+
+  // Bidirectional new-workspace overlay: visible when there are no
+  // workspaces to enter, hidden as soon as one exists. Gated on
+  // `workspaceListFetched` so the initial render doesn't flash the
+  // overlay before the list arrives. The overlay's own `invite` type is
+  // not touched here — that's an in-flight task owned by the user.
+  useEffect(() => {
+    if (!user) return;
+    if (!workspaceListFetched) return;
+    const { overlay, open, close } = useWindowOverlayStore.getState();
+    const isEmpty = wsCount === 0;
+    if (isEmpty) {
+      if (!overlay) open({ type: "new-workspace" });
+    } else if (overlay?.type === "new-workspace") {
+      close();
+    }
+  }, [user, workspaceListFetched, wsCount]);
+  // 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">
         <MulticaIcon className="size-6 animate-pulse" />
@@ -67,9 +166,14 @@ function AppContent() {
 const DAEMON_TARGET_API_URL =
   import.meta.env.VITE_API_URL || "http://localhost:8080";
 
-// On logout, clear any cached PAT and stop the daemon so that a subsequent
-// login as a different user never inherits the previous user's credentials.
+// On logout, wipe desktop-only in-memory state and stop the daemon so that
+// a subsequent login as a different user never inherits the previous user's
+// tabs, overlay, or credentials. Zustand persist only writes to localStorage;
+// useLogout clears the storage key, but the live stores stay populated until
+// we explicitly reset them here.
 async function handleDaemonLogout() {
+  useTabStore.getState().reset();
+  useWindowOverlayStore.getState().close();
   try {
     await window.daemonAPI.clearToken();
   } catch {

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,16 +6,19 @@ 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 { 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 { TabBar } from "./tab-bar";
 import { TabContent } from "./tab-content";
+import { WindowOverlay } from "./window-overlay";
 
 function SidebarTopBar() {
   const { canGoBack, canGoForward, goBack, goForward } = useTabHistory();
@@ -51,17 +54,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>
   );
@@ -86,34 +100,42 @@ export function DesktopShell() {
   useInternalLinkHandler();
   useActiveTitleSync();
 
+  // 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>
-      <DashboardGuard
-        loginPath="/login"
-        loadingFallback={
-          <div className="flex h-screen items-center justify-center">
-            <MulticaIcon className="size-6 animate-pulse" />
-          </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 see the window-level overlay (new-workspace flow)
+          triggered by IndexRedirect, not a route. */}
+      <WorkspaceSlugProvider slug={slug}>
         <div className="flex h-screen">
           <SidebarProvider className="flex-1">
-            <AppSidebar topSlot={<SidebarTopBar />} searchSlot={<SearchTrigger />} />
+            {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 />
-                <ChatWindow />
-                <ChatFab />
+                {slug && <ChatWindow />}
+                {slug && <ChatFab />}
               </div>
             </div>
           </SidebarProvider>
         </div>
-        <ModalRegistry />
-        <SearchCommand />
-      </DashboardGuard>
+        {slug && <ModalRegistry />}
+        {slug && <SearchCommand />}
+        <WindowOverlay />
+      </WorkspaceSlugProvider>
     </DesktopNavigationProvider>
   );
 }

apps/desktop/src/renderer/src/components/tab-bar.tsx

@@ -29,7 +29,8 @@ import {
 } from "@dnd-kit/modifiers";
 import { CSS } from "@dnd-kit/utilities";
 import { cn } from "@multica/ui/lib/utils";
-import { useTabStore, resolveRouteIcon, type Tab } from "@/stores/tab-store";
+import { useTabStore, useActiveGroup, resolveRouteIcon, type Tab } from "@/stores/tab-store";
+import { paths } from "@multica/core/paths";
 
 const TAB_ICONS: Record<string, LucideIcon> = {
   Inbox,
@@ -66,16 +67,13 @@ function SortableTabItem({ tab, isActive, isOnly }: { tab: Tab; isActive: boolea
   const handleClick = () => {
     if (isActive) return;
     setActiveTab(tab.id);
-    // No navigate() — Activity handles visibility
   };
 
   const handleClose = (e: React.MouseEvent) => {
     e.stopPropagation();
     closeTab(tab.id);
-    // No navigate() — store handles activeTabId switch
   };
 
-  // Stop pointer down on close so it doesn't start a drag on the parent button.
   const stopDragOnClose = (e: React.PointerEvent) => {
     e.stopPropagation();
   };
@@ -124,10 +122,13 @@ function NewTabButton() {
   const setActiveTab = useTabStore((s) => s.setActiveTab);
 
   const handleClick = () => {
-    const path = "/issues";
+    // New tab opens in the currently active workspace — tabs are scoped
+    // per workspace, so there is no cross-workspace ambiguity to resolve.
+    const activeSlug = useTabStore.getState().activeWorkspaceSlug;
+    if (!activeSlug) return;
+    const path = paths.workspace(activeSlug).issues();
     const tabId = addTab(path, "Issues", resolveRouteIcon(path));
-    setActiveTab(tabId);
-    // No navigate() — new tab's router starts at /issues automatically
+    if (tabId) setActiveTab(tabId);
   };
 
   return (
@@ -142,17 +143,17 @@ function NewTabButton() {
 }
 
 export function TabBar() {
-  const tabs = useTabStore((s) => s.tabs);
-  const activeTabId = useTabStore((s) => s.activeTabId);
+  const group = useActiveGroup();
   const moveTab = useTabStore((s) => s.moveTab);
 
-  // distance: 5 — pointer must move 5px to start a drag, otherwise it's a click.
   const sensors = useSensors(
     useSensor(PointerSensor, {
       activationConstraint: { distance: 5 },
     }),
   );
 
+  const tabs = group?.tabs ?? [];
+  const activeTabId = group?.activeTabId ?? "";
   const tabIds = tabs.map((t) => t.id);
 
   const handleDragEnd = (event: DragEndEvent) => {
@@ -182,7 +183,7 @@ export function TabBar() {
           ))}
         </SortableContext>
       </DndContext>
-      <NewTabButton />
+      {group && <NewTabButton />}
     </div>
   );
 }

apps/desktop/src/renderer/src/components/tab-content.tsx

@@ -1,40 +1,52 @@
 import { Activity, useEffect } from "react";
 import { RouterProvider } from "react-router-dom";
-import { useTabStore } from "@/stores/tab-store";
+import { useActiveGroup } from "@/stores/tab-store";
 import { TabNavigationProvider } from "@/platform/navigation";
 import { useTabRouterSync } from "@/hooks/use-tab-router-sync";
+import type { Tab } from "@/stores/tab-store";
 
-/** Inner wrapper rendered inside each tab's RouterProvider. */
-function TabRouterInner({ tabId }: { tabId: string }) {
-  const tab = useTabStore((s) => s.tabs.find((t) => t.id === tabId));
-  useTabRouterSync(tabId, tab!.router);
+/**
+ * Inner wrapper rendered inside each tab's RouterProvider. The router
+ * reference is stable for a tab's lifetime, so passing it in directly
+ * (instead of re-deriving from the store) avoids needless re-renders.
+ */
+function TabRouterInner({ tab }: { tab: Tab }) {
+  useTabRouterSync(tab.id, tab.router);
   return null;
 }
 
 /**
- * Renders all tabs using Activity for state preservation.
+ * Renders the active workspace's tabs using Activity for state preservation.
  * Only the active tab is visible; hidden tabs keep their DOM and React state.
+ *
+ * When switching workspaces, the previous workspace's tabs unmount entirely
+ * and the new workspace's tabs mount fresh — cross-workspace state
+ * preservation is an explicit non-goal (keeping all workspaces' tabs warm
+ * simultaneously would bloat memory and make workspace switching feel
+ * anything but "switching").
  */
 export function TabContent() {
-  const tabs = useTabStore((s) => s.tabs);
-  const activeTabId = useTabStore((s) => s.activeTabId);
+  const group = useActiveGroup();
 
-  // Sync document.title when switching tabs
+  // Sync document.title when switching tabs within the active workspace.
   useEffect(() => {
-    const tab = tabs.find((t) => t.id === activeTabId);
+    if (!group) return;
+    const tab = group.tabs.find((t) => t.id === group.activeTabId);
     if (tab) document.title = tab.title;
-  }, [activeTabId, tabs]);
+  }, [group?.activeTabId, group?.tabs]);
+
+  if (!group) return null;
 
   return (
     <>
-      {tabs.map((tab) => (
+      {group.tabs.map((tab) => (
         <Activity
           key={tab.id}
-          mode={tab.id === activeTabId ? "visible" : "hidden"}
+          mode={tab.id === group.activeTabId ? "visible" : "hidden"}
         >
           <TabNavigationProvider router={tab.router}>
             <RouterProvider router={tab.router} />
-            <TabRouterInner tabId={tab.id} />
+            <TabRouterInner tab={tab} />
           </TabNavigationProvider>
         </Activity>
       ))}

apps/desktop/src/renderer/src/components/updates-settings-tab.tsx

@@ -0,0 +1,86 @@
+import { useCallback, useState } from "react";
+import { AlertCircle, ArrowDownToLine, Check, Loader2 } from "lucide-react";
+import { Button } from "@multica/ui/components/ui/button";
+
+type CheckState =
+  | { status: "idle" }
+  | { status: "checking" }
+  | { status: "up-to-date"; currentVersion: string }
+  | { status: "available"; latestVersion: string }
+  | { status: "error"; message: string };
+
+export function UpdatesSettingsTab() {
+  const [state, setState] = useState<CheckState>({ status: "idle" });
+
+  const handleCheck = useCallback(async () => {
+    setState({ status: "checking" });
+    const result = await window.updater.checkForUpdates();
+    if (!result.ok) {
+      setState({ status: "error", message: result.error });
+      return;
+    }
+    setState(
+      result.available
+        ? { status: "available", latestVersion: result.latestVersion }
+        : { status: "up-to-date", currentVersion: result.currentVersion },
+    );
+  }, []);
+
+  return (
+    <div>
+      <h2 className="text-lg font-semibold">Updates</h2>
+      <p className="text-sm text-muted-foreground mt-1">
+        The desktop app checks for new versions automatically once an hour and
+        shortly after launch.
+      </p>
+
+      <div className="mt-6 divide-y">
+        <div className="flex items-start justify-between gap-6 py-4">
+          <div className="min-w-0">
+            <p className="text-sm font-medium">Check for updates</p>
+            <p className="text-sm text-muted-foreground mt-0.5">
+              Trigger a check now instead of waiting for the next automatic
+              poll. Available updates appear as a notification in the corner.
+            </p>
+            {state.status === "up-to-date" && (
+              <p className="text-sm text-muted-foreground mt-2 inline-flex items-center gap-1.5">
+                <Check className="size-3.5 text-success" />
+                You&apos;re on the latest version (v{state.currentVersion}).
+              </p>
+            )}
+            {state.status === "available" && (
+              <p className="text-sm text-muted-foreground mt-2 inline-flex items-center gap-1.5">
+                <ArrowDownToLine className="size-3.5 text-primary" />
+                v{state.latestVersion} is available — see the download prompt
+                in the corner.
+              </p>
+            )}
+            {state.status === "error" && (
+              <p className="text-sm text-destructive mt-2 inline-flex items-center gap-1.5">
+                <AlertCircle className="size-3.5" />
+                {state.message}
+              </p>
+            )}
+          </div>
+          <div className="shrink-0">
+            <Button
+              variant="outline"
+              size="sm"
+              onClick={handleCheck}
+              disabled={state.status === "checking"}
+            >
+              {state.status === "checking" ? (
+                <>
+                  <Loader2 className="size-3.5 animate-spin" />
+                  Checking…
+                </>
+              ) : (
+                "Check now"
+              )}
+            </Button>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

apps/desktop/src/renderer/src/components/window-overlay.tsx

@@ -0,0 +1,85 @@
+import { useQuery } from "@tanstack/react-query";
+import { useImmersiveMode } from "@multica/views/platform";
+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 { useWindowOverlayStore } from "@/stores/window-overlay-store";
+
+/**
+ * Window-level transition overlay: renders above the tab system when the
+ * user is in a pre-workspace flow (create workspace, accept invite).
+ *
+ * This component is a thin **platform shell**:
+ *  - Hands the window-drag strip and macOS traffic-light hiding
+ *    (`useImmersiveMode`) — both are platform-specific, web has neither
+ *  - Covers the tab system (fixed inset, z-50) so the Shell's own TabBar
+ *    doesn't leak through
+ *
+ * All UX affordances (Back button, Log out button, welcome copy, invite
+ * card) live inside the shared `NewWorkspacePage` / `InvitePage`
+ * components under `packages/views/`, so web and desktop render identical
+ * content. The platform split is: UX in shared code, chrome here.
+ */
+export function WindowOverlay() {
+  const overlay = useWindowOverlayStore((s) => s.overlay);
+  if (!overlay) return null;
+  return <WindowOverlayInner />;
+}
+
+function WindowOverlayInner() {
+  const overlay = useWindowOverlayStore((s) => s.overlay);
+  const close = useWindowOverlayStore((s) => s.close);
+  const { push } = useNavigation();
+  const { data: wsList = [] } = useQuery(workspaceListOptions());
+
+  useImmersiveMode();
+
+  if (!overlay) return null;
+
+  // Back is only meaningful when there's somewhere to go — i.e. the user
+  // has at least one workspace. Zero-workspace users can only Log out or
+  // complete the flow.
+  const onBack = wsList.length > 0 ? close : undefined;
+
+  return (
+    <div className="fixed inset-0 z-50 flex flex-col bg-background">
+      {/* Window-drag strip. Rendered as a flex *child* (not absolute
+          overlay) so it owns its own 48px of real layout space — the
+          prior absolute-positioned approach relied on z-index stacking
+          to beat the content wrapper's no-drag, which in practice didn't
+          hit-test reliably for `-webkit-app-region` on the welcome
+          screen. A real flex row with nothing else in it has no such
+          ambiguity: any pixel at top-48 is drag, full stop.
+
+          Height matches `MainTopBar` (48px) so the drag-to-grab area
+          feels consistent with the rest of the app. The strip is
+          invisible; macOS traffic lights would normally sit here but
+          `useImmersiveMode` has hidden them for the overlay's lifetime. */}
+      <div
+        aria-hidden
+        className="h-12 shrink-0"
+        style={{ WebkitAppRegion: "drag" } as React.CSSProperties}
+      />
+
+      <div
+        className="flex-1 min-h-0 overflow-auto"
+        style={{ WebkitAppRegion: "no-drag" } as React.CSSProperties}
+      >
+        {overlay.type === "new-workspace" && (
+          <NewWorkspacePage
+            onSuccess={(ws) => push(paths.workspace(ws.slug).issues())}
+            onBack={onBack}
+          />
+        )}
+        {overlay.type === "invite" && (
+          <InvitePage
+            invitationId={overlay.invitationId}
+            onBack={onBack}
+          />
+        )}
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,88 @@
+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,
+  workspaceListOptions,
+} from "@multica/core/workspace";
+import { setCurrentWorkspace } from "@multica/core/platform";
+import { useAuthStore } from "@multica/core/auth";
+import { useWorkspaceSeen } from "@multica/views/workspace/use-workspace-seen";
+import { useTabStore } from "@/stores/tab-store";
+
+/**
+ * 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).
+ *
+ * Unlike web, desktop never renders a "workspace not available" page: the
+ * app has no URL bar and no clickable links from outside the session, so
+ * landing on an inaccessible slug can only mean stale state (a persisted
+ * tab group for a workspace the current user no longer has access to, or
+ * active eviction). Both cases resolve by dropping the stale tab group
+ * from the tab store — the TabBar then renders a different workspace or
+ * the WindowOverlay takes over (zero valid workspaces).
+ */
+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, bounce to /login.
+  useEffect(() => {
+    if (!isAuthLoading && !user) navigate(paths.login(), { replace: true });
+  }, [isAuthLoading, user, navigate]);
+
+  const { data: workspace, isFetched: listFetched } = useQuery({
+    ...workspaceBySlugOptions(workspaceSlug ?? ""),
+    enabled: !!user && !!workspaceSlug,
+  });
+
+  const { data: wsList } = useQuery({
+    ...workspaceListOptions(),
+    enabled: !!user,
+  });
+
+  // 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.
+  if (workspace && workspaceSlug) {
+    setCurrentWorkspace(workspaceSlug, workspace.id);
+  }
+
+  const hasBeenSeen = useWorkspaceSeen(workspaceSlug, !!workspace);
+
+  // Stale-slug auto-heal: when this tab's slug fails to resolve, drop the
+  // whole workspace group from the tab store. Per-workspace tab grouping
+  // means the cleanup is a single validator call — the TabContent will
+  // unmount this tab (and all siblings in the stale group) once the store
+  // updates. We don't navigate this tab's router because the tab's path
+  // is scoped to the stale slug; navigating to "/" would create an
+  // inconsistent "tab in group X with path /" state.
+  useEffect(() => {
+    if (!user) return;
+    if (!listFetched) return;
+    if (workspace) return;
+    if (hasBeenSeen) return; // active eviction in flight — let the other path win
+    if (!wsList) return;
+    const validSlugs = new Set(wsList.map((w) => w.slug));
+    useTabStore.getState().validateWorkspaceSlugs(validSlugs);
+  }, [user, listFetched, workspace, hasBeenSeen, wsList]);
+
+  if (isAuthLoading) return null;
+  if (!workspaceSlug) return null;
+  if (!listFetched) return null;
+  if (!workspace) return null; // auto-heal effect above handles the cleanup
+
+  return (
+    <WorkspaceSlugProvider slug={workspaceSlug}>
+      <Outlet />
+    </WorkspaceSlugProvider>
+  );
+}

apps/desktop/src/renderer/src/hooks/use-tab-history.ts

@@ -1,6 +1,6 @@
 import { useCallback } from "react";
 import type { DataRouter } from "react-router-dom";
-import { useTabStore } from "@/stores/tab-store";
+import { useActiveTabRouter, useActiveTabHistory } from "@/stores/tab-store";
 
 /**
  * Shared hint map so useTabRouterSync can distinguish back vs forward POP.
@@ -9,32 +9,32 @@ import { useTabStore } from "@/stores/tab-store";
 export const popDirectionHints = new Map<DataRouter, "back" | "forward">();
 
 /**
- * Per-tab back/forward navigation derived from the active tab's history state.
- * Replaces the old global useNavigationHistory() hook.
+ * Per-tab back/forward navigation derived from the active workspace's
+ * active tab.
+ *
+ * Subscribed via primitive selectors so this hook only re-renders when
+ * the numeric history state actually changes — path ticks on the active
+ * tab (which don't shift historyIndex) don't churn the back/forward
+ * buttons.
  */
 export function useTabHistory() {
-  // Return the actual tab object from the store — stable reference.
-  // Do NOT create a new object in the selector (causes infinite re-renders).
-  const activeTab = useTabStore((s) =>
-    s.tabs.find((t) => t.id === s.activeTabId),
-  );
+  const router = useActiveTabRouter();
+  const { historyIndex, historyLength } = useActiveTabHistory();
 
-  const canGoBack = (activeTab?.historyIndex ?? 0) > 0;
-  const canGoForward =
-    (activeTab?.historyIndex ?? 0) < (activeTab?.historyLength ?? 1) - 1;
+  const canGoBack = historyIndex > 0;
+  const canGoForward = historyIndex < historyLength - 1;
 
   const goBack = useCallback(() => {
-    if (!activeTab || activeTab.historyIndex <= 0) return;
-    popDirectionHints.set(activeTab.router, "back");
-    activeTab.router.navigate(-1);
-  }, [activeTab]);
+    if (!router || historyIndex <= 0) return;
+    popDirectionHints.set(router, "back");
+    router.navigate(-1);
+  }, [router, historyIndex]);
 
   const goForward = useCallback(() => {
-    if (!activeTab || activeTab.historyIndex >= activeTab.historyLength - 1)
-      return;
-    popDirectionHints.set(activeTab.router, "forward");
-    activeTab.router.navigate(1);
-  }, [activeTab]);
+    if (!router || historyIndex >= historyLength - 1) return;
+    popDirectionHints.set(router, "forward");
+    router.navigate(1);
+  }, [router, historyIndex, historyLength]);
 
   return { canGoBack, canGoForward, goBack, goForward };
 }

apps/desktop/src/renderer/src/hooks/use-tab-sync.ts

@@ -2,20 +2,23 @@ import { useEffect } from "react";
 import { useTabStore } from "@/stores/tab-store";
 
 /**
- * Watches document.title via MutationObserver and updates the active tab's title.
- *
- * Pages set document.title via TitleSync (route handle.title) or useDocumentTitle().
- * This observer picks up the change and syncs it to the tab store.
+ * Watches document.title via MutationObserver and updates the active tab's
+ * title. Pages set document.title via TitleSync (route handle.title) or
+ * useDocumentTitle(). This observer picks up the change and syncs it to
+ * the tab store.
  */
 export function useActiveTitleSync() {
   useEffect(() => {
     const observer = new MutationObserver(() => {
       const title = document.title;
       if (!title) return;
-      const { tabs, activeTabId } = useTabStore.getState();
-      const activeTab = tabs.find((t) => t.id === activeTabId);
+      const state = useTabStore.getState();
+      if (!state.activeWorkspaceSlug) return;
+      const group = state.byWorkspace[state.activeWorkspaceSlug];
+      if (!group) return;
+      const activeTab = group.tabs.find((t) => t.id === group.activeTabId);
       if (activeTab && activeTab.title !== title) {
-        useTabStore.getState().updateTab(activeTabId, { title });
+        state.updateTab(activeTab.id, { title });
       }
     });
 

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

@@ -1,11 +1,9 @@
 import { LoginPage } from "@multica/views/auth";
 import { MulticaIcon } from "@multica/ui/components/common/multica-icon";
 
-const WEB_URL = import.meta.env.VITE_WEB_URL || "http://localhost:3000";
+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/platform/navigation.tsx

@@ -5,16 +5,94 @@ import {
   type NavigationAdapter,
 } from "@multica/views/navigation";
 import { useAuthStore } from "@multica/core/auth";
-import { useTabStore, resolveRouteIcon } from "@/stores/tab-store";
+import { isReservedSlug } from "@multica/core/paths";
+import {
+  useTabStore,
+  resolveRouteIcon,
+  useActiveTabIdentity,
+  useActiveTabRouter,
+  getActiveTab,
+} from "@/stores/tab-store";
+import { useWindowOverlayStore } from "@/stores/window-overlay-store";
 
-// Public web app URL — injected at build time via .env.production. Falls
-// back to the production host for dev builds so "Copy link" yields a URL
-// that actually points somewhere a teammate can open.
-const APP_URL = import.meta.env.VITE_APP_URL || "https://multica.ai";
+// Public web app URL — injected at build time via .env.production. In dev
+// (no VITE_APP_URL set) falls back to the local web dev server so "Copy
+// link" in a dev build yields a URL that points at the running dev
+// frontend, not the prod host. Matches the fallback used in pages/login.tsx.
+const APP_URL = import.meta.env.VITE_APP_URL || "http://localhost:3000";
 
 /**
- * Root-level navigation provider for components outside the per-tab RouterProviders
- * (sidebar, search dialog, modals, etc.).
+ * Extract the leading workspace slug from a path, or null if the path isn't
+ * workspace-scoped (root, login, any reserved prefix).
+ */
+function extractWorkspaceSlug(path: string): string | null {
+  const first = path.split("/").filter(Boolean)[0] ?? "";
+  if (!first) return null;
+  if (isReservedSlug(first)) return null;
+  return first;
+}
+
+/**
+ * Intercept navigation to "transition" paths — pre-workspace flows that on
+ * desktop are rendered as a window-level overlay instead of a tab route.
+ * Returns `true` if the navigation was handled (caller should NOT proceed).
+ *
+ * Side effect: when opening the new-workspace overlay, the tab router is
+ * ALSO reset to "/". Rationale — the only way a push lands on
+ * /workspaces/new is that the workspace context is gone (fresh install,
+ * delete-last, leave-last). Leaving the tab parked on a workspace-scoped
+ * path would keep those components mounted under the overlay; the next
+ * render after the list cache updates would then throw (useWorkspaceId
+ * etc) because the slug no longer resolves.
+ */
+function tryRouteToOverlay(path: string, router?: DataRouter): boolean {
+  const overlay = useWindowOverlayStore.getState();
+  if (path === "/workspaces/new") {
+    overlay.open({ type: "new-workspace" });
+    if (router && router.state.location.pathname !== "/") {
+      router.navigate("/", { replace: true });
+    }
+    return true;
+  }
+  if (path.startsWith("/invite/")) {
+    let id = "";
+    try {
+      id = decodeURIComponent(path.slice("/invite/".length));
+    } catch {
+      return true;
+    }
+    if (id) {
+      overlay.open({ type: "invite", invitationId: id });
+      return true;
+    }
+  }
+  // Any other navigation cancels a live overlay.
+  if (overlay.overlay) overlay.close();
+  return false;
+}
+
+/**
+ * Intercept pushes that change workspace. Returns `true` if the navigation
+ * was delegated to the tab store (caller should NOT proceed).
+ *
+ * This is the entry point that makes shared code platform-agnostic:
+ * sidebar dropdown, cmd+k "switch workspace", post-delete redirects,
+ * invite-accept flow — they all call `useNavigation().push(path)` with a
+ * full workspace URL, and on desktop we translate "target slug differs
+ * from active" into "switch the tab-group that's visible in the TabBar".
+ */
+function tryRouteToOtherWorkspace(path: string): boolean {
+  const targetSlug = extractWorkspaceSlug(path);
+  if (!targetSlug) return false;
+  const { activeWorkspaceSlug, switchWorkspace } = useTabStore.getState();
+  if (targetSlug === activeWorkspaceSlug) return false;
+  switchWorkspace(targetSlug, path);
+  return true;
+}
+
+/**
+ * Root-level navigation provider for components outside the per-tab
+ * RouterProviders (sidebar, search dialog, modals, WindowOverlay contents).
  *
  * Reads from the active tab's memory router via router.subscribe().
  * Does NOT use any react-router hooks — it's above all RouterProviders.
@@ -24,50 +102,61 @@ export function DesktopNavigationProvider({
 }: {
   children: React.ReactNode;
 }) {
-  const activeTab = useTabStore((s) => s.tabs.find((t) => t.id === s.activeTabId));
-  const [pathname, setPathname] = useState(activeTab?.path ?? "/issues");
+  // Primitive-only subscriptions so this component doesn't re-render on
+  // unrelated store updates (e.g. an inactive tab's router tick). We
+  // resolve the active router here only to subscribe once per tab switch.
+  const { tabId: activeTabId } = useActiveTabIdentity();
+  const router = useActiveTabRouter();
+  const [pathname, setPathname] = useState(
+    router?.state.location.pathname ?? "/",
+  );
 
-  // Subscribe to the active tab's router for pathname updates
   useEffect(() => {
-    if (!activeTab) return;
-    setPathname(activeTab.router.state.location.pathname);
-    return activeTab.router.subscribe((state) => {
+    if (!router) {
+      setPathname("/");
+      return;
+    }
+    setPathname(router.state.location.pathname);
+    return router.subscribe((state) => {
       setPathname(state.location.pathname);
     });
-  }, [activeTab?.id]); // eslint-disable-line react-hooks/exhaustive-deps
+  }, [activeTabId, router]);
 
   const adapter: NavigationAdapter = useMemo(
     () => ({
       push: (path: string) => {
         if (path === "/login") {
-          // DashboardGuard token expired — force back to login screen
           useAuthStore.getState().logout();
           return;
         }
-        const tab = useTabStore.getState().tabs.find(
-          (t) => t.id === useTabStore.getState().activeTabId,
-        );
-        tab?.router.navigate(path);
+        const active = currentActiveTab();
+        if (tryRouteToOverlay(path, active?.router)) return;
+        if (tryRouteToOtherWorkspace(path)) return;
+        active?.router.navigate(path);
       },
       replace: (path: string) => {
-        const tab = useTabStore.getState().tabs.find(
-          (t) => t.id === useTabStore.getState().activeTabId,
-        );
-        tab?.router.navigate(path, { replace: true });
+        const active = currentActiveTab();
+        if (tryRouteToOverlay(path, active?.router)) return;
+        if (tryRouteToOtherWorkspace(path)) return;
+        active?.router.navigate(path, { replace: true });
       },
       back: () => {
-        const tab = useTabStore.getState().tabs.find(
-          (t) => t.id === useTabStore.getState().activeTabId,
-        );
-        tab?.router.navigate(-1);
+        currentActiveTab()?.router.navigate(-1);
       },
       pathname,
       searchParams: new URLSearchParams(),
       openInNewTab: (path: string, title?: string) => {
-        const icon = resolveRouteIcon(path);
+        // Cross-workspace "open in new tab" switches workspace and opens
+        // the path there; same-workspace just adds a tab in the current group.
+        const slug = extractWorkspaceSlug(path);
         const store = useTabStore.getState();
+        if (slug && slug !== store.activeWorkspaceSlug) {
+          store.switchWorkspace(slug, path);
+          return;
+        }
+        const icon = resolveRouteIcon(path);
         const tabId = store.openTab(path, title ?? path, icon);
-        store.setActiveTab(tabId);
+        if (tabId) store.setActiveTab(tabId);
       },
       getShareableUrl: (path: string) => `${APP_URL}${path}`,
     }),
@@ -77,6 +166,10 @@ export function DesktopNavigationProvider({
   return <NavigationProvider value={adapter}>{children}</NavigationProvider>;
 }
 
+function currentActiveTab() {
+  return getActiveTab(useTabStore.getState());
+}
+
 /**
  * Per-tab navigation provider rendered inside each tab's Activity wrapper.
  * Subscribes to the tab's own router for up-to-date pathname.
@@ -101,16 +194,29 @@ export function TabNavigationProvider({
 
   const adapter: NavigationAdapter = useMemo(
     () => ({
-      push: (path: string) => router.navigate(path),
-      replace: (path: string) => router.navigate(path, { replace: true }),
+      push: (path: string) => {
+        if (tryRouteToOverlay(path, router)) return;
+        if (tryRouteToOtherWorkspace(path)) return;
+        router.navigate(path);
+      },
+      replace: (path: string) => {
+        if (tryRouteToOverlay(path, router)) return;
+        if (tryRouteToOtherWorkspace(path)) return;
+        router.navigate(path, { replace: true });
+      },
       back: () => router.navigate(-1),
       pathname: location.pathname,
       searchParams: new URLSearchParams(location.search),
       openInNewTab: (path: string, title?: string) => {
-        const icon = resolveRouteIcon(path);
+        const slug = extractWorkspaceSlug(path);
         const store = useTabStore.getState();
-        const newTabId = store.openTab(path, title ?? path, icon);
-        store.setActiveTab(newTabId);
+        if (slug && slug !== store.activeWorkspaceSlug) {
+          store.switchWorkspace(slug, path);
+          return;
+        }
+        const icon = resolveRouteIcon(path);
+        const tabId = store.openTab(path, title ?? path, icon);
+        if (tabId) store.setActiveTab(tabId);
       },
       getShareableUrl: (path: string) => `${APP_URL}${path}`,
     }),

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

@@ -19,11 +19,10 @@ 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 { InvitePage } from "@multica/views/invite";
-import { useNavigation } from "@multica/views/navigation";
-import { Server } from "lucide-react";
+import { Download, Server } from "lucide-react";
 import { DaemonSettingsTab } from "./components/daemon-settings-tab";
+import { UpdatesSettingsTab } from "./components/updates-settings-tab";
+import { WorkspaceRouteLayout } from "./components/workspace-route-layout";
 
 /**
  * Sets document.title from the deepest matched route's handle.title.
@@ -55,88 +54,95 @@ function PageShell() {
   );
 }
 
-function OnboardingRoute() {
-  const nav = useNavigation();
-  return <OnboardingWizard onComplete={() => nav.push("/issues")} />;
-}
-
-function InviteRoute() {
-  const matches = useMatches();
-  const match = matches.find((m) => (m.params as { id?: string }).id);
-  const id = (match?.params as { id?: string })?.id ?? "";
-  return <InvitePage invitationId={id} />;
-}
-
-/** Route definitions shared by all tabs (no layout wrapper). */
+/**
+ * Route definitions shared by all tabs.
+ *
+ * Every tab path is workspace-scoped: `/{slug}/{route}/...`. Pre-workspace
+ * flows (create workspace, accept invite) are NOT routes — they render as a
+ * window-level overlay via `WindowOverlay`, dispatched by the navigation
+ * adapter's transition-path interception. The `activeWorkspaceSlug` in the
+ * tab store decides which workspace's tabs are visible in the TabBar;
+ * workspace-less state (zero-workspace user) shows the overlay instead.
+ *
+ * The root index route stays as a harmless safety net. With per-workspace
+ * tabs, nothing should construct a tab at `/` — but if one ever slips
+ * through (malformed persisted state that dodges the migration, direct
+ * router.navigate from unforeseen code), the index falls back to null
+ * rather than 404; App.tsx's bootstrap repoints activeWorkspaceSlug on the
+ * next render pass.
+ */
 export const appRoutes: RouteObject[] = [
   {
     element: <PageShell />,
     children: [
-      { index: true, element: <Navigate to="/issues" replace /> },
-      { path: "issues", element: <IssuesPage />, handle: { title: "Issues" } },
+      { index: true, element: null },
       {
-        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: "invite/:id",
-        element: <InviteRoute />,
-        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 />,
+                  },
+                  {
+                    value: "updates",
+                    label: "Updates",
+                    icon: Download,
+                    content: <UpdatesSettingsTab />,
+                  },
+                ]}
+              />
+            ),
+            handle: { title: "Settings" },
+          },
+        ],
       },
     ],
   },

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

@@ -0,0 +1,224 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+
+// createTabRouter transitively pulls in route modules that expect a browser
+// router context. For pure store tests we stub it to a minimal disposable.
+const createTabRouterMock = vi.hoisted(() =>
+  vi.fn(() => ({
+    dispose: vi.fn(),
+    state: { location: { pathname: "/" } },
+    navigate: vi.fn(),
+    subscribe: vi.fn(() => () => {}),
+  })),
+);
+vi.mock("../routes", () => ({
+  createTabRouter: createTabRouterMock,
+}));
+
+import {
+  sanitizeTabPath,
+  migrateV1ToV2,
+  useTabStore,
+} from "./tab-store";
+
+beforeEach(() => {
+  createTabRouterMock.mockClear();
+  useTabStore.getState().reset();
+});
+
+describe("sanitizeTabPath", () => {
+  it("rejects the root sentinel — tabs must be workspace-scoped", () => {
+    expect(sanitizeTabPath("/")).toBeNull();
+    expect(sanitizeTabPath("")).toBeNull();
+  });
+
+  it("silently rejects transition paths (no warn — navigation adapter intercepts them)", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    expect(sanitizeTabPath("/workspaces/new")).toBeNull();
+    expect(sanitizeTabPath("/invite/abc")).toBeNull();
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it("passes through valid workspace-scoped paths", () => {
+    expect(sanitizeTabPath("/acme/issues")).toBe("/acme/issues");
+    expect(sanitizeTabPath("/my-team/projects/abc")).toBe("/my-team/projects/abc");
+  });
+
+  it("rejects paths whose first segment is a reserved slug (missing workspace prefix)", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    expect(sanitizeTabPath("/issues")).toBeNull();
+    expect(sanitizeTabPath("/settings")).toBeNull();
+    expect(warn).toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it("passes through user slugs that happen to look path-like but aren't reserved", () => {
+    expect(sanitizeTabPath("/acme-issues/issues")).toBe("/acme-issues/issues");
+    expect(sanitizeTabPath("/project-x/inbox")).toBe("/project-x/inbox");
+  });
+});
+
+describe("migrateV1ToV2", () => {
+  it("groups v1 flat tabs by workspace slug", () => {
+    const v1 = {
+      tabs: [
+        { id: "t1", path: "/acme/issues", title: "Issues", icon: "ListTodo" },
+        { id: "t2", path: "/acme/projects", title: "Projects", icon: "FolderKanban" },
+        { id: "t3", path: "/butter/issues", title: "Issues", icon: "ListTodo" },
+      ],
+      activeTabId: "t2",
+    };
+    const v2 = migrateV1ToV2(v1);
+    expect(Object.keys(v2.byWorkspace).sort()).toEqual(["acme", "butter"]);
+    expect(v2.byWorkspace.acme.tabs).toHaveLength(2);
+    expect(v2.byWorkspace.butter.tabs).toHaveLength(1);
+    expect(v2.byWorkspace.acme.activeTabId).toBe("t2");
+    expect(v2.byWorkspace.butter.activeTabId).toBe("t3"); // first tab in group
+    expect(v2.activeWorkspaceSlug).toBe("acme"); // contained v1.activeTabId
+  });
+
+  it("drops tabs at root / transition / reserved-slug paths", () => {
+    const v1 = {
+      tabs: [
+        { id: "t1", path: "/", title: "Issues", icon: "ListTodo" },
+        { id: "t2", path: "/workspaces/new", title: "New", icon: "Plus" },
+        { id: "t3", path: "/invite/abc", title: "Invite", icon: "Mail" },
+        { id: "t4", path: "/acme/issues", title: "Issues", icon: "ListTodo" },
+      ],
+      activeTabId: "t1",
+    };
+    const v2 = migrateV1ToV2(v1);
+    expect(Object.keys(v2.byWorkspace)).toEqual(["acme"]);
+    expect(v2.byWorkspace.acme.tabs).toHaveLength(1);
+    // v1.activeTabId was dropped; active falls back to first group's first tab.
+    expect(v2.activeWorkspaceSlug).toBe("acme");
+    expect(v2.byWorkspace.acme.activeTabId).toBe("t4");
+  });
+
+  it("handles empty v1 state gracefully", () => {
+    const v2 = migrateV1ToV2({ tabs: [], activeTabId: "" });
+    expect(v2.byWorkspace).toEqual({});
+    expect(v2.activeWorkspaceSlug).toBeNull();
+  });
+
+  it("handles v1 with no tabs field (corrupted state)", () => {
+    const v2 = migrateV1ToV2({});
+    expect(v2.byWorkspace).toEqual({});
+    expect(v2.activeWorkspaceSlug).toBeNull();
+  });
+});
+
+describe("useTabStore actions", () => {
+  it("switchWorkspace creates a new group with a default tab on first entry", () => {
+    useTabStore.getState().switchWorkspace("acme");
+    const s = useTabStore.getState();
+    expect(s.activeWorkspaceSlug).toBe("acme");
+    expect(s.byWorkspace.acme.tabs).toHaveLength(1);
+    expect(s.byWorkspace.acme.tabs[0].path).toBe("/acme/issues");
+  });
+
+  it("switchWorkspace without openPath restores the group's last active tab", () => {
+    const store = useTabStore.getState();
+    store.switchWorkspace("acme");
+    store.addTab("/acme/projects", "Projects", "FolderKanban");
+    const acmeProjectsId = useTabStore.getState().byWorkspace.acme.tabs[1].id;
+    store.setActiveTab(acmeProjectsId);
+
+    // Enter a different workspace then come back
+    store.switchWorkspace("butter");
+    expect(useTabStore.getState().activeWorkspaceSlug).toBe("butter");
+
+    store.switchWorkspace("acme");
+    const s = useTabStore.getState();
+    expect(s.activeWorkspaceSlug).toBe("acme");
+    expect(s.byWorkspace.acme.activeTabId).toBe(acmeProjectsId);
+  });
+
+  it("switchWorkspace with openPath dedupes into an existing tab with same path", () => {
+    const store = useTabStore.getState();
+    store.switchWorkspace("acme"); // creates default /acme/issues
+    store.addTab("/acme/projects", "Projects", "FolderKanban");
+
+    store.switchWorkspace("acme", "/acme/issues");
+    const s = useTabStore.getState();
+    expect(s.byWorkspace.acme.tabs).toHaveLength(2); // no duplicate created
+    const activeTab = s.byWorkspace.acme.tabs.find(
+      (t) => t.id === s.byWorkspace.acme.activeTabId,
+    );
+    expect(activeTab?.path).toBe("/acme/issues");
+  });
+
+  it("switchWorkspace with openPath not matching any tab adds a new tab", () => {
+    const store = useTabStore.getState();
+    store.switchWorkspace("acme");
+    store.switchWorkspace("acme", "/acme/issues/bug-42");
+    const s = useTabStore.getState();
+    expect(s.byWorkspace.acme.tabs).toHaveLength(2);
+    const activeTab = s.byWorkspace.acme.tabs.find(
+      (t) => t.id === s.byWorkspace.acme.activeTabId,
+    );
+    expect(activeTab?.path).toBe("/acme/issues/bug-42");
+  });
+
+  it("openTab dedupes by path within the active workspace", () => {
+    const store = useTabStore.getState();
+    store.switchWorkspace("acme");
+    const id1 = store.openTab("/acme/projects", "Projects", "FolderKanban");
+    const id2 = store.openTab("/acme/projects", "Projects", "FolderKanban");
+    expect(id1).toBe(id2);
+    expect(useTabStore.getState().byWorkspace.acme.tabs).toHaveLength(2); // default + projects
+  });
+
+  it("closeTab on the last tab in a workspace reseeds the default tab", () => {
+    const store = useTabStore.getState();
+    store.switchWorkspace("acme");
+    const onlyTabId = useTabStore.getState().byWorkspace.acme.tabs[0].id;
+    store.closeTab(onlyTabId);
+    const s = useTabStore.getState();
+    expect(s.byWorkspace.acme.tabs).toHaveLength(1);
+    expect(s.byWorkspace.acme.tabs[0].path).toBe("/acme/issues");
+    expect(s.byWorkspace.acme.tabs[0].id).not.toBe(onlyTabId); // fresh tab
+  });
+
+  it("validateWorkspaceSlugs drops groups for slugs not in the valid set and repoints active", () => {
+    const store = useTabStore.getState();
+    store.switchWorkspace("acme");
+    store.switchWorkspace("butter");
+    store.switchWorkspace("acme");
+    expect(useTabStore.getState().activeWorkspaceSlug).toBe("acme");
+
+    // Admin removed the user from acme
+    store.validateWorkspaceSlugs(new Set(["butter"]));
+    const s = useTabStore.getState();
+    expect(Object.keys(s.byWorkspace)).toEqual(["butter"]);
+    expect(s.activeWorkspaceSlug).toBe("butter");
+  });
+
+  it("validateWorkspaceSlugs sets activeWorkspaceSlug to null when all groups are dropped", () => {
+    const store = useTabStore.getState();
+    store.switchWorkspace("acme");
+    store.validateWorkspaceSlugs(new Set());
+    const s = useTabStore.getState();
+    expect(s.byWorkspace).toEqual({});
+    expect(s.activeWorkspaceSlug).toBeNull();
+  });
+
+  it("reset wipes the whole store", () => {
+    const store = useTabStore.getState();
+    store.switchWorkspace("acme");
+    store.switchWorkspace("butter");
+    store.reset();
+    const s = useTabStore.getState();
+    expect(s.activeWorkspaceSlug).toBeNull();
+    expect(s.byWorkspace).toEqual({});
+  });
+
+  it("setActiveTab across workspaces also flips the active workspace", () => {
+    const store = useTabStore.getState();
+    store.switchWorkspace("acme");
+    store.switchWorkspace("butter");
+    const acmeTabId = useTabStore.getState().byWorkspace.acme.tabs[0].id;
+    store.setActiveTab(acmeTabId);
+    expect(useTabStore.getState().activeWorkspaceSlug).toBe("acme");
+  });
+});

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 { isReservedSlug } from "@multica/core/paths";
 import type { DataRouter } from "react-router-dom";
 import { createTabRouter } from "../routes";
 
@@ -12,6 +13,7 @@ import { createTabRouter } from "../routes";
 
 export interface Tab {
   id: string;
+  /** Every tab path is workspace-scoped: `/{workspaceSlug}/{route}/...`. */
   path: string;
   title: string;
   icon: string;
@@ -20,24 +22,77 @@ export interface Tab {
   historyLength: number;
 }
 
-interface TabStore {
+export interface WorkspaceTabGroup {
   tabs: Tab[];
+  /** Must be a valid tab.id in `tabs`; the empty-tabs state is transient only. */
   activeTabId: string;
+}
 
-  /** Open a background tab. Deduplicates by path. Returns the tab id. */
+interface TabStore {
+  /**
+   * The workspace currently visible in the TabBar / TabContent. Null in three
+   * cases:
+   *   - Fresh install, before any workspace exists or is selected.
+   *   - Logged-out state (reset() wipes it).
+   *   - Every workspace the user had access to got deleted / revoked.
+   * When null, TabContent renders nothing and the WindowOverlay takes over.
+   */
+  activeWorkspaceSlug: string | null;
+
+  /**
+   * Tab groups keyed by workspace slug. Each slug maps to an independent
+   * (tabs, activeTabId) pair; switching workspaces swaps the visible set
+   * without affecting any other group. Cross-workspace tab leakage — the
+   * bug that drove this refactor — is impossible by construction because
+   * there is no global tab array anymore.
+   */
+  byWorkspace: Record<string, WorkspaceTabGroup>;
+
+  /**
+   * Switch to a workspace.
+   *   - If the group doesn't exist yet, create it with a single default tab.
+   *   - If `openPath` is given, find a tab with that exact path and activate
+   *     it; otherwise add a new tab and activate it.
+   *   - If `openPath` is omitted, restore the group's last active tab
+   *     (VSCode / Slack behavior — workspaces resume where you left off).
+   */
+  switchWorkspace: (slug: string, openPath?: string) => void;
+  /** Open-or-activate (dedupes by path) a tab in the active workspace. */
   openTab: (path: string, title: string, icon: string) => string;
-  /** Always create a new tab (no dedup). Returns the tab id. */
+  /** Always creates a new tab (no dedupe) in the active workspace. */
   addTab: (path: string, title: string, icon: string) => string;
-  /** Close a tab. Disposes router. */
+  /**
+   * Close a tab. Finds it across all workspaces (callers like the X button
+   * only know the tab id, not the owning workspace). If this is the last
+   * tab in its workspace, reseed a default tab so the invariant
+   * "every live workspace has at least one tab" holds.
+   */
   closeTab: (tabId: string) => void;
-  /** Switch to a tab by id. */
+  /**
+   * Activate a tab. Finds it across all workspaces. Sets both the owning
+   * workspace as active and that group's activeTabId; needed for any code
+   * path that "jumps" to a tab belonging to a non-active workspace.
+   */
   setActiveTab: (tabId: string) => void;
-  /** Update a tab's metadata (path, title, icon — partial). */
+  /** Patch metadata of a tab (router-sync, title-sync). Finds across groups. */
   updateTab: (tabId: string, patch: Partial<Pick<Tab, "path" | "title" | "icon">>) => void;
-  /** Update a tab's history tracking. */
+  /** Patch history tracking of a tab. Finds across groups. */
   updateTabHistory: (tabId: string, historyIndex: number, historyLength: number) => void;
-  /** Reorder tabs by moving one from fromIndex to toIndex. Preserves router/history. */
+  /** Reorder within the active workspace's group only. */
   moveTab: (fromIndex: number, toIndex: number) => void;
+  /**
+   * After the workspace list arrives/changes (login, realtime delete), drop
+   * any tab group whose slug is no longer in `validSlugs`, and repoint
+   * `activeWorkspaceSlug` if it pointed at one of the dropped groups.
+   */
+  validateWorkspaceSlugs: (validSlugs: Set<string>) => void;
+  /**
+   * Wipe everything. Called from logout so the next user doesn't inherit
+   * the prior user's tabs. Zustand persist only writes to localStorage;
+   * clearing the storage key alone would leave this live store intact
+   * until app restart.
+   */
+  reset: () => void;
 }
 
 // ---------------------------------------------------------------------------
@@ -45,29 +100,82 @@ 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.
+ *
+ * Tab paths are always workspace-scoped: `/{slug}/{route}/...`, so the route
+ * segment lives at index 1. Pre-workspace flows (create, invite) are rendered
+ * by the window overlay, never as tabs.
+ *
+ * Title is NOT determined here — it comes from document.title.
+ */
 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);
+  return ROUTE_ICONS[segments[1] ?? ""] ?? "ListTodo";
+}
+
+/** Extract the leading workspace slug from a path, or null if the path
+ *  isn't workspace-scoped (global path, root, or empty). */
+function extractWorkspaceSlug(path: string): string | null {
+  const first = path.split("/").filter(Boolean)[0] ?? "";
+  if (!first) return null;
+  if (isReservedSlug(first)) return null;
+  return first;
 }
 
 // ---------------------------------------------------------------------------
-// Store
+// Path sanitization (defensive)
 // ---------------------------------------------------------------------------
 
-const DEFAULT_PATH = "/issues";
+/**
+ * Defensive: catch paths that don't belong in the tab store.
+ *
+ * Two kinds of rejects:
+ *  1. **Transition paths** (`/workspaces/new`, `/invite/...`). These are
+ *     pre-workspace flows rendered by the window overlay on desktop, not
+ *     tab routes. The navigation adapter normally intercepts these before
+ *     they reach the store; this guard catches older persisted state.
+ *  2. **Malformed workspace-scoped paths** like a stray `/issues/abc` that
+ *     was constructed without the workspace prefix. The router would
+ *     interpret `issues` as a workspace slug → NoAccessPage.
+ *
+ * Returns null for rejects (caller decides how to recover — usually by
+ * dropping the tab or substituting a default). Unlike the prior design,
+ * there is no root "/" sentinel — tabs are always scoped.
+ */
+export function sanitizeTabPath(path: string): string | null {
+  const firstSegment = path.split("/").filter(Boolean)[0] ?? "";
+  if (!firstSegment) return null;
+  if (isReservedSlug(firstSegment)) {
+    // Don't log for known transition paths — these are legitimate inputs
+    // at the interception boundary (older persisted state or stale callers).
+    const isTransition = path === "/workspaces/new" || path.startsWith("/invite/");
+    if (!isTransition) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[tab-store] tab path "${path}" starts with reserved slug "${firstSegment}" — ` +
+          `caller likely forgot the workspace prefix. Dropping.`,
+      );
+    }
+    return null;
+  }
+  return path;
+}
+
+// ---------------------------------------------------------------------------
+// Tab factory
+// ---------------------------------------------------------------------------
 
 function createId(): string {
   return createSafeId();
@@ -85,112 +193,513 @@ function makeTab(path: string, title: string, icon: string): Tab {
   };
 }
 
-const initialTab = makeTab(DEFAULT_PATH, "Issues", resolveRouteIcon(DEFAULT_PATH));
+/** Default entry point for a workspace — its issues list. */
+function defaultPathFor(slug: string): string {
+  return `/${slug}/issues`;
+}
+
+function defaultTabFor(slug: string): Tab {
+  const path = defaultPathFor(slug);
+  return makeTab(path, "Issues", resolveRouteIcon(path));
+}
+
+// ---------------------------------------------------------------------------
+// Group helpers
+// ---------------------------------------------------------------------------
+
+function findTabLocation(
+  byWorkspace: Record<string, WorkspaceTabGroup>,
+  tabId: string,
+): { slug: string; group: WorkspaceTabGroup; index: number } | null {
+  for (const slug of Object.keys(byWorkspace)) {
+    const group = byWorkspace[slug];
+    const index = group.tabs.findIndex((t) => t.id === tabId);
+    if (index >= 0) return { slug, group, index };
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Store
+// ---------------------------------------------------------------------------
 
 export const useTabStore = create<TabStore>()(
   persist(
     (set, get) => ({
-  tabs: [initialTab],
-  activeTabId: initialTab.id,
+      activeWorkspaceSlug: null,
+      byWorkspace: {},
 
-  openTab(path, title, icon) {
-    const { tabs } = get();
-    const existing = tabs.find((t) => t.path === path);
-    if (existing) return existing.id;
+      switchWorkspace(slug, openPath) {
+        // Defensive no-op if slug is empty/invalid — callers like the
+        // NavigationAdapter's path-parser should already have filtered
+        // these, but belt-and-braces keeps garbage out of the store.
+        if (!slug) return;
+        const { byWorkspace } = get();
+        const existing = byWorkspace[slug];
 
-    const tab = makeTab(path, title, icon);
-    set({ tabs: [...tabs, tab] });
-    return tab.id;
-  },
+        // Decide the desired active path for this workspace.
+        const desiredPath = openPath ?? (existing ? null : defaultPathFor(slug));
 
-  addTab(path, title, icon) {
-    const tab = makeTab(path, title, icon);
-    set((s) => ({ tabs: [...s.tabs, tab] }));
-    return tab.id;
-  },
+        if (!existing) {
+          // First time entering this workspace — create the group.
+          const seedPath =
+            desiredPath && sanitizeTabPath(desiredPath) === desiredPath
+              ? desiredPath
+              : defaultPathFor(slug);
+          const tab = makeTab(seedPath, "Issues", resolveRouteIcon(seedPath));
+          set({
+            activeWorkspaceSlug: slug,
+            byWorkspace: {
+              ...byWorkspace,
+              [slug]: { tabs: [tab], activeTabId: tab.id },
+            },
+          });
+          return;
+        }
 
-  closeTab(tabId) {
-    const { tabs, activeTabId } = get();
+        // Workspace already has tabs. Either dedupe into an existing tab or
+        // add a new one (when openPath was supplied and no tab matches it).
+        if (desiredPath) {
+          const clean = sanitizeTabPath(desiredPath);
+          if (clean) {
+            const match = existing.tabs.find((t) => t.path === clean);
+            if (match) {
+              set({
+                activeWorkspaceSlug: slug,
+                byWorkspace: {
+                  ...byWorkspace,
+                  [slug]: { ...existing, activeTabId: match.id },
+                },
+              });
+              return;
+            }
+            const tab = makeTab(clean, "Issues", resolveRouteIcon(clean));
+            set({
+              activeWorkspaceSlug: slug,
+              byWorkspace: {
+                ...byWorkspace,
+                [slug]: {
+                  tabs: [...existing.tabs, tab],
+                  activeTabId: tab.id,
+                },
+              },
+            });
+            return;
+          }
+        }
 
-    const closingTab = tabs.find((t) => t.id === tabId);
+        // No openPath (or openPath was rejected) — just restore the group.
+        set({ activeWorkspaceSlug: slug });
+      },
 
-    // Never close the last tab — replace with default
-    if (tabs.length === 1) {
-      closingTab?.router.dispose();
-      const fresh = makeTab(DEFAULT_PATH, "Issues", resolveRouteIcon(DEFAULT_PATH));
-      set({ tabs: [fresh], activeTabId: fresh.id });
-      return;
-    }
+      openTab(path, title, icon) {
+        const { activeWorkspaceSlug, byWorkspace } = get();
+        const clean = sanitizeTabPath(path);
+        if (!activeWorkspaceSlug || !clean) return "";
+        const group = byWorkspace[activeWorkspaceSlug];
+        if (!group) return "";
 
-    const idx = tabs.findIndex((t) => t.id === tabId);
-    if (idx === -1) return;
+        const existing = group.tabs.find((t) => t.path === clean);
+        if (existing) {
+          set({
+            byWorkspace: {
+              ...byWorkspace,
+              [activeWorkspaceSlug]: { ...group, activeTabId: existing.id },
+            },
+          });
+          return existing.id;
+        }
 
-    closingTab?.router.dispose();
-    const next = tabs.filter((t) => t.id !== tabId);
+        const tab = makeTab(clean, title, icon);
+        set({
+          byWorkspace: {
+            ...byWorkspace,
+            [activeWorkspaceSlug]: {
+              tabs: [...group.tabs, tab],
+              activeTabId: group.activeTabId,
+            },
+          },
+        });
+        return tab.id;
+      },
 
-    if (tabId === activeTabId) {
-      const newActive = next[Math.min(idx, next.length - 1)];
-      set({ tabs: next, activeTabId: newActive.id });
-    } else {
-      set({ tabs: next });
-    }
-  },
+      addTab(path, title, icon) {
+        const { activeWorkspaceSlug, byWorkspace } = get();
+        const clean = sanitizeTabPath(path);
+        if (!activeWorkspaceSlug || !clean) return "";
+        const group = byWorkspace[activeWorkspaceSlug];
+        if (!group) return "";
 
-  setActiveTab(tabId) {
-    set({ activeTabId: tabId });
-  },
+        const tab = makeTab(clean, title, icon);
+        set({
+          byWorkspace: {
+            ...byWorkspace,
+            [activeWorkspaceSlug]: {
+              tabs: [...group.tabs, tab],
+              activeTabId: group.activeTabId,
+            },
+          },
+        });
+        return tab.id;
+      },
 
-  updateTab(tabId, patch) {
-    set((s) => ({
-      tabs: s.tabs.map((t) =>
-        t.id === tabId ? { ...t, ...patch } : t,
-      ),
-    }));
-  },
+      closeTab(tabId) {
+        const { byWorkspace } = get();
+        const hit = findTabLocation(byWorkspace, tabId);
+        if (!hit) return;
+        const { slug, group, index } = hit;
 
-  updateTabHistory(tabId, historyIndex, historyLength) {
-    set((s) => ({
-      tabs: s.tabs.map((t) =>
-        t.id === tabId ? { ...t, historyIndex, historyLength } : t,
-      ),
-    }));
-  },
+        const closing = group.tabs[index];
+        closing.router.dispose();
 
-  moveTab(fromIndex, toIndex) {
-    if (fromIndex === toIndex) return;
-    set((s) => ({ tabs: arrayMove(s.tabs, fromIndex, toIndex) }));
-  },
+        if (group.tabs.length === 1) {
+          // Last tab in this workspace — reseed a default so the workspace
+          // always has at least one tab. Closing a workspace as an explicit
+          // action is a separate concern (Leave/Delete in Settings).
+          const fresh = defaultTabFor(slug);
+          set({
+            byWorkspace: {
+              ...byWorkspace,
+              [slug]: { tabs: [fresh], activeTabId: fresh.id },
+            },
+          });
+          return;
+        }
+
+        const nextTabs = group.tabs.filter((t) => t.id !== tabId);
+        const nextActiveTabId =
+          group.activeTabId === tabId
+            ? nextTabs[Math.min(index, nextTabs.length - 1)].id
+            : group.activeTabId;
+
+        set({
+          byWorkspace: {
+            ...byWorkspace,
+            [slug]: { tabs: nextTabs, activeTabId: nextActiveTabId },
+          },
+        });
+      },
+
+      setActiveTab(tabId) {
+        const { byWorkspace, activeWorkspaceSlug } = get();
+        const hit = findTabLocation(byWorkspace, tabId);
+        if (!hit) return;
+        const { slug, group } = hit;
+        if (slug === activeWorkspaceSlug && group.activeTabId === tabId) return;
+        set({
+          activeWorkspaceSlug: slug,
+          byWorkspace: {
+            ...byWorkspace,
+            [slug]: { ...group, activeTabId: tabId },
+          },
+        });
+      },
+
+      updateTab(tabId, patch) {
+        const { byWorkspace } = get();
+        const hit = findTabLocation(byWorkspace, tabId);
+        if (!hit) return;
+        const { slug, group, index } = hit;
+        const current = group.tabs[index];
+        const next: Tab = { ...current, ...patch };
+        const nextTabs = [...group.tabs];
+        nextTabs[index] = next;
+        set({
+          byWorkspace: {
+            ...byWorkspace,
+            [slug]: { ...group, tabs: nextTabs },
+          },
+        });
+      },
+
+      updateTabHistory(tabId, historyIndex, historyLength) {
+        const { byWorkspace } = get();
+        const hit = findTabLocation(byWorkspace, tabId);
+        if (!hit) return;
+        const { slug, group, index } = hit;
+        const current = group.tabs[index];
+        const next: Tab = { ...current, historyIndex, historyLength };
+        const nextTabs = [...group.tabs];
+        nextTabs[index] = next;
+        set({
+          byWorkspace: {
+            ...byWorkspace,
+            [slug]: { ...group, tabs: nextTabs },
+          },
+        });
+      },
+
+      moveTab(fromIndex, toIndex) {
+        if (fromIndex === toIndex) return;
+        const { activeWorkspaceSlug, byWorkspace } = get();
+        if (!activeWorkspaceSlug) return;
+        const group = byWorkspace[activeWorkspaceSlug];
+        if (!group) return;
+        set({
+          byWorkspace: {
+            ...byWorkspace,
+            [activeWorkspaceSlug]: {
+              ...group,
+              tabs: arrayMove(group.tabs, fromIndex, toIndex),
+            },
+          },
+        });
+      },
+
+      validateWorkspaceSlugs(validSlugs) {
+        const { activeWorkspaceSlug, byWorkspace } = get();
+        let changed = false;
+        const nextByWorkspace: Record<string, WorkspaceTabGroup> = {};
+        for (const slug of Object.keys(byWorkspace)) {
+          if (validSlugs.has(slug)) {
+            nextByWorkspace[slug] = byWorkspace[slug];
+          } else {
+            changed = true;
+            for (const t of byWorkspace[slug].tabs) t.router.dispose();
+          }
+        }
+
+        let nextActive = activeWorkspaceSlug;
+        if (nextActive && !validSlugs.has(nextActive)) {
+          nextActive = Object.keys(nextByWorkspace)[0] ?? null;
+          changed = true;
+        }
+
+        if (!changed) return;
+        set({ byWorkspace: nextByWorkspace, activeWorkspaceSlug: nextActive });
+      },
+
+      reset() {
+        const { byWorkspace } = get();
+        for (const slug of Object.keys(byWorkspace)) {
+          for (const t of byWorkspace[slug].tabs) t.router.dispose();
+        }
+        set({ activeWorkspaceSlug: null, byWorkspace: {} });
+      },
     }),
     {
       name: "multica_tabs",
-      version: 1,
+      version: 2,
       storage: createJSONStorage(() => createPersistStorage(defaultStorage)),
+      migrate: (persistedState, version) => {
+        // v1 → v2: flat `tabs` array → per-workspace grouping.
+        // Tabs whose path isn't workspace-scoped (root `/`, login, etc.)
+        // are dropped — they have no workspace to belong to, and the new
+        // model's invariant is "every tab lives in a workspace group".
+        if (version < 2 && persistedState && typeof persistedState === "object") {
+          return migrateV1ToV2(persistedState as Partial<V1Persisted>);
+        }
+        return persistedState as V2Persisted;
+      },
       partialize: (state) => ({
-        tabs: state.tabs.map(
-          ({ router, historyIndex, historyLength, ...rest }) => rest,
+        activeWorkspaceSlug: state.activeWorkspaceSlug,
+        byWorkspace: Object.fromEntries(
+          Object.entries(state.byWorkspace).map(([slug, group]) => [
+            slug,
+            {
+              activeTabId: group.activeTabId,
+              tabs: group.tabs.map(
+                ({ router: _router, historyIndex: _hi, historyLength: _hl, ...rest }) =>
+                  rest,
+              ),
+            },
+          ]),
         ),
-        activeTabId: state.activeTabId,
       }),
       merge: (persistedState, currentState) => {
-        const persisted = persistedState as
-          | Pick<TabStore, "tabs" | "activeTabId">
-          | undefined;
-        if (!persisted?.tabs?.length) return currentState;
+        const persisted = persistedState as Partial<V2Persisted> | undefined;
+        if (!persisted?.byWorkspace) return currentState;
 
-        const tabs: Tab[] = persisted.tabs.map((tab) => ({
-          ...tab,
-          router: createTabRouter(tab.path),
-          historyIndex: 0,
-          historyLength: 1,
-        }));
+        const byWorkspace: Record<string, WorkspaceTabGroup> = {};
+        for (const [slug, pGroup] of Object.entries(persisted.byWorkspace)) {
+          const tabs: Tab[] = [];
+          for (const pTab of pGroup.tabs) {
+            const clean = sanitizeTabPath(pTab.path);
+            // Persisted path may have come from a stale version or a
+            // manual edit. Drop rather than rewrite so we never silently
+            // put users on a path that doesn't match the group's slug.
+            if (!clean || extractWorkspaceSlug(clean) !== slug) {
+              // eslint-disable-next-line no-console
+              console.warn(
+                `[tab-store] dropping persisted tab "${pTab.path}" from ` +
+                  `group "${slug}" — path/slug mismatch`,
+              );
+              continue;
+            }
+            tabs.push({
+              id: pTab.id,
+              path: clean,
+              title: pTab.title,
+              icon: pTab.icon,
+              router: createTabRouter(clean),
+              historyIndex: 0,
+              historyLength: 1,
+            });
+          }
+          if (tabs.length === 0) continue;
+          const activeTabId = tabs.some((t) => t.id === pGroup.activeTabId)
+            ? pGroup.activeTabId
+            : tabs[0].id;
+          byWorkspace[slug] = { tabs, activeTabId };
+        }
 
-        // Validate activeTabId — fall back to first tab if stale
-        const activeTabId = tabs.some((t) => t.id === persisted.activeTabId)
-          ? persisted.activeTabId
-          : tabs[0].id;
+        const activeWorkspaceSlug =
+          persisted.activeWorkspaceSlug && byWorkspace[persisted.activeWorkspaceSlug]
+            ? persisted.activeWorkspaceSlug
+            : (Object.keys(byWorkspace)[0] ?? null);
 
-        return { ...currentState, tabs, activeTabId };
+        return { ...currentState, byWorkspace, activeWorkspaceSlug };
       },
     },
   ),
 );
+
+// ---------------------------------------------------------------------------
+// Persisted shapes (for migration)
+// ---------------------------------------------------------------------------
+
+interface V1Tab {
+  id: string;
+  path: string;
+  title: string;
+  icon: string;
+}
+
+interface V1Persisted {
+  tabs: V1Tab[];
+  activeTabId: string;
+}
+
+interface V2PersistedTab {
+  id: string;
+  path: string;
+  title: string;
+  icon: string;
+}
+
+interface V2PersistedGroup {
+  tabs: V2PersistedTab[];
+  activeTabId: string;
+}
+
+interface V2Persisted {
+  activeWorkspaceSlug: string | null;
+  byWorkspace: Record<string, V2PersistedGroup>;
+}
+
+export function migrateV1ToV2(v1: Partial<V1Persisted>): V2Persisted {
+  const byWorkspace: Record<string, V2PersistedGroup> = {};
+  const oldTabs = v1.tabs ?? [];
+  for (const tab of oldTabs) {
+    const slug = extractWorkspaceSlug(tab.path);
+    if (!slug) continue; // drop root / global-path tabs
+    if (!byWorkspace[slug]) byWorkspace[slug] = { tabs: [], activeTabId: "" };
+    byWorkspace[slug].tabs.push({
+      id: tab.id,
+      path: tab.path,
+      title: tab.title,
+      icon: tab.icon,
+    });
+  }
+
+  // Each group needs a valid activeTabId. Prefer the one from v1 if it
+  // landed in this group; otherwise fall back to the first tab.
+  for (const slug of Object.keys(byWorkspace)) {
+    const group = byWorkspace[slug];
+    const hasOldActive = group.tabs.some((t) => t.id === v1.activeTabId);
+    group.activeTabId = hasOldActive
+      ? (v1.activeTabId as string)
+      : group.tabs[0].id;
+  }
+
+  // Active workspace: whichever group inherited the v1 activeTab, falling
+  // back to the first group we created (arbitrary but deterministic given
+  // Object.keys iteration order on string keys).
+  let activeWorkspaceSlug: string | null = null;
+  for (const slug of Object.keys(byWorkspace)) {
+    if (byWorkspace[slug].activeTabId === v1.activeTabId) {
+      activeWorkspaceSlug = slug;
+      break;
+    }
+  }
+  if (!activeWorkspaceSlug) {
+    activeWorkspaceSlug = Object.keys(byWorkspace)[0] ?? null;
+  }
+
+  return { activeWorkspaceSlug, byWorkspace };
+}
+
+// ---------------------------------------------------------------------------
+// Selectors (convenience hooks)
+// ---------------------------------------------------------------------------
+
+/**
+ * Pure non-hook helper — useful from event handlers / effects that already
+ * need `.getState()`. For React subscriptions prefer the stable selectors
+ * below.
+ */
+export function getActiveTab(s: TabStore): Tab | null {
+  if (!s.activeWorkspaceSlug) return null;
+  const group = s.byWorkspace[s.activeWorkspaceSlug];
+  if (!group) return null;
+  return group.tabs.find((t) => t.id === group.activeTabId) ?? null;
+}
+
+/**
+ * The active workspace's tab group, or null when no workspace is active.
+ *
+ * Zustand compares selector returns with `Object.is`. Because `updateTab`
+ * /  `updateTabHistory` replace the group object on every router tick
+ * (immutable update), this selector returns a new reference on every
+ * router event — that's fine for TabBar which needs to observe tab-list
+ * changes, but don't use this selector from components that only care
+ * about one primitive (use `useActiveTabHistory` / `useActiveTabRouter`
+ * instead).
+ */
+export function useActiveGroup(): WorkspaceTabGroup | null {
+  return useTabStore((s) =>
+    s.activeWorkspaceSlug ? (s.byWorkspace[s.activeWorkspaceSlug] ?? null) : null,
+  );
+}
+
+/**
+ * Active tab id + active workspace slug as a compact pair. Both primitives
+ * are stable across unrelated store updates — e.g. an inactive tab's
+ * router tick doesn't churn these, so consumers don't re-render.
+ *
+ * Useful anywhere you'd previously have reached for `useActiveTab()` and
+ * only needed the identity (for memoization, effect deps, ipc).
+ */
+export function useActiveTabIdentity(): { slug: string | null; tabId: string | null } {
+  const slug = useTabStore((s) => s.activeWorkspaceSlug);
+  const tabId = useTabStore((s) =>
+    s.activeWorkspaceSlug
+      ? (s.byWorkspace[s.activeWorkspaceSlug]?.activeTabId ?? null)
+      : null,
+  );
+  return { slug, tabId };
+}
+
+/**
+ * Active tab's router — a stable reference across tab updates, because
+ * routers are created once per tab and never replaced by `updateTab`.
+ * Subscribers only re-render when the active tab *changes*, not on
+ * router events within the current tab.
+ */
+export function useActiveTabRouter(): DataRouter | null {
+  return useTabStore((s) => getActiveTab(s)?.router ?? null);
+}
+
+/**
+ * History tracking for the active tab as primitives. Subscribers re-render
+ * only when the numeric index / length change (i.e. on actual navigations),
+ * not on unrelated store updates.
+ */
+export function useActiveTabHistory(): {
+  historyIndex: number;
+  historyLength: number;
+} {
+  const historyIndex = useTabStore((s) => getActiveTab(s)?.historyIndex ?? 0);
+  const historyLength = useTabStore((s) => getActiveTab(s)?.historyLength ?? 1);
+  return { historyIndex, historyLength };
+}

apps/desktop/src/renderer/src/stores/window-overlay-store.ts

@@ -0,0 +1,29 @@
+import { create } from "zustand";
+
+/**
+ * Window-level transition overlay: pre-workspace flows that are NOT pages
+ * inside a tab. Triggered by navigation-adapter interception, zero-workspace
+ * auto-redirect, or deep link; rendered above the tab system as a full-window
+ * takeover.
+ *
+ * These flows used to be routes (`/workspaces/new`, `/invite/:id`) but on
+ * desktop the URL is invisible to users — routes are an implementation detail
+ * of the tab system. Representing transitions as routes meant tabs tried to
+ * persist them, TabBar rendered on top, and invite deep-linking had no clean
+ * dispatch target. Modeling them as application state removes all three.
+ */
+export type WindowOverlay =
+  | { type: "new-workspace" }
+  | { type: "invite"; invitationId: string };
+
+interface WindowOverlayStore {
+  overlay: WindowOverlay | null;
+  open: (overlay: WindowOverlay) => void;
+  close: () => void;
+}
+
+export const useWindowOverlayStore = create<WindowOverlayStore>((set) => ({
+  overlay: null,
+  open: (overlay) => set({ overlay }),
+  close: () => set({ overlay: null }),
+}));

apps/desktop/test/setup.ts

@@ -0,0 +1 @@
+import "@testing-library/jest-dom/vitest";

apps/desktop/tsconfig.web.json

@@ -4,7 +4,8 @@
     "src/renderer/src/env.d.ts",
     "src/renderer/src/**/*",
     "src/renderer/src/**/*.tsx",
-    "src/preload/*.d.ts"
+    "src/preload/*.d.ts",
+    "test/setup.ts"
   ],
   "compilerOptions": {
     "composite": true,

apps/desktop/vitest.config.ts

@@ -1,10 +1,13 @@
 import { defineConfig } from "vitest/config";
+import react from "@vitejs/plugin-react";
 
 export default defineConfig({
+  plugins: [react()],
   test: {
     globals: true,
-    include: ["src/**/*.test.ts", "scripts/**/*.test.mjs"],
-    environment: "node",
+    include: ["src/**/*.test.{ts,tsx}", "scripts/**/*.test.mjs"],
+    environment: "jsdom",
+    setupFiles: ["./test/setup.ts"],
     passWithNoTests: true,
   },
 });

apps/docs/app/(home)/layout.tsx

@@ -1,7 +0,0 @@
-import type { ReactNode } from "react";
-import { HomeLayout } from "fumadocs-ui/layouts/home";
-import { baseOptions } from "@/app/layout.config";
-
-export default function Layout({ children }: { children: ReactNode }) {
-  return <HomeLayout {...baseOptions}>{children}</HomeLayout>;
-}

apps/docs/app/(home)/page.tsx

@@ -1,29 +0,0 @@
-import Link from "next/link";
-
-export default function HomePage() {
-  return (
-    <main className="flex min-h-screen flex-col items-center justify-center gap-6 text-center px-4">
-      <h1 className="text-4xl font-bold tracking-tight sm:text-5xl">
-        Multica Documentation
-      </h1>
-      <p className="max-w-2xl text-lg text-fd-muted-foreground">
-        The open-source managed agents platform. Turn coding agents into real
-        teammates — assign tasks, track progress, compound skills.
-      </p>
-      <div className="flex gap-4">
-        <Link
-          href="/docs"
-          className="inline-flex items-center rounded-md bg-fd-primary px-6 py-3 text-sm font-medium text-fd-primary-foreground transition-colors hover:bg-fd-primary/90"
-        >
-          Get Started
-        </Link>
-        <Link
-          href="https://github.com/multica-ai/multica"
-          className="inline-flex items-center rounded-md border border-fd-border px-6 py-3 text-sm font-medium transition-colors hover:bg-fd-accent"
-        >
-          GitHub
-        </Link>
-      </div>
-    </main>
-  );
-}

apps/docs/app/[...slug]/page.tsx

@@ -10,7 +10,7 @@ import defaultMdxComponents from "fumadocs-ui/mdx";
 import type { Metadata } from "next";
 
 export default async function Page(props: {
-  params: Promise<{ slug?: string[] }>;
+  params: Promise<{ slug: string[] }>;
 }) {
   const params = await props.params;
   const page = source.getPage(params.slug);
@@ -29,12 +29,12 @@ export default async function Page(props: {
   );
 }
 
-export async function generateStaticParams() {
-  return source.generateParams();
+export function generateStaticParams() {
+  return source.generateParams().filter((p) => p.slug.length > 0);
 }
 
 export async function generateMetadata(props: {
-  params: Promise<{ slug?: string[] }>;
+  params: Promise<{ slug: string[] }>;
 }): Promise<Metadata> {
   const params = await props.params;
   const page = source.getPage(params.slug);

apps/docs/app/docs/layout.tsx

@@ -1,12 +0,0 @@
-import { DocsLayout } from "fumadocs-ui/layouts/docs";
-import type { ReactNode } from "react";
-import { baseOptions } from "@/app/layout.config";
-import { source } from "@/lib/source";
-
-export default function Layout({ children }: { children: ReactNode }) {
-  return (
-    <DocsLayout tree={source.pageTree} {...baseOptions}>
-      {children}
-    </DocsLayout>
-  );
-}

apps/docs/app/layout.config.tsx

@@ -1,5 +1,4 @@
 import type { BaseLayoutProps } from "fumadocs-ui/layouts/shared";
-import { BookOpen, Terminal, Rocket, Code } from "lucide-react";
 
 export const baseOptions: BaseLayoutProps = {
   nav: {
@@ -8,11 +7,6 @@ export const baseOptions: BaseLayoutProps = {
     ),
   },
   links: [
-    {
-      text: "Documentation",
-      url: "/docs",
-      active: "nested-url",
-    },
     {
       text: "GitHub",
       url: "https://github.com/multica-ai/multica",

apps/docs/app/layout.tsx

@@ -1,7 +1,10 @@
 import "./global.css";
 import { RootProvider } from "fumadocs-ui/provider";
+import { DocsLayout } from "fumadocs-ui/layouts/docs";
 import type { ReactNode } from "react";
 import type { Metadata } from "next";
+import { baseOptions } from "@/app/layout.config";
+import { source } from "@/lib/source";
 
 export const metadata: Metadata = {
   title: {
@@ -16,7 +19,11 @@ export default function Layout({ children }: { children: ReactNode }) {
   return (
     <html lang="en" suppressHydrationWarning>
       <body>
-        <RootProvider>{children}</RootProvider>
+        <RootProvider>
+          <DocsLayout tree={source.pageTree} {...baseOptions}>
+            {children}
+          </DocsLayout>
+        </RootProvider>
       </body>
     </html>
   );

apps/docs/app/not-found.tsx

@@ -0,0 +1,18 @@
+import Link from "next/link";
+
+export default function NotFound() {
+  return (
+    <main className="flex flex-1 flex-col items-center justify-center gap-4 px-4 py-24 text-center">
+      <h1 className="text-3xl font-semibold">Page not found</h1>
+      <p className="text-fd-muted-foreground">
+        The page you are looking for doesn&apos;t exist.
+      </p>
+      <Link
+        href="/"
+        className="inline-flex items-center rounded-md bg-fd-primary px-4 py-2 text-sm font-medium text-fd-primary-foreground transition-colors hover:bg-fd-primary/90"
+      >
+        Back to docs
+      </Link>
+    </main>
+  );
+}

apps/docs/app/page.tsx

@@ -0,0 +1,37 @@
+import { source } from "@/lib/source";
+import {
+  DocsPage,
+  DocsBody,
+  DocsDescription,
+  DocsTitle,
+} from "fumadocs-ui/page";
+import { notFound } from "next/navigation";
+import defaultMdxComponents from "fumadocs-ui/mdx";
+import type { Metadata } from "next";
+
+export default function Page() {
+  const page = source.getPage([]);
+  if (!page) notFound();
+
+  const MDX = page.data.body;
+
+  return (
+    <DocsPage toc={page.data.toc}>
+      <DocsTitle>{page.data.title}</DocsTitle>
+      <DocsDescription>{page.data.description}</DocsDescription>
+      <DocsBody>
+        <MDX components={{ ...defaultMdxComponents }} />
+      </DocsBody>
+    </DocsPage>
+  );
+}
+
+export function generateMetadata(): Metadata {
+  const page = source.getPage([]);
+  if (!page) notFound();
+
+  return {
+    title: page.data.title,
+    description: page.data.description,
+  };
+}

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

@@ -68,7 +68,7 @@ multica setup
 
 This configures the CLI for Multica Cloud, opens your browser for login, discovers your workspaces, and starts the agent daemon.
 
-For self-hosted servers, use `multica setup self-host` instead. See [Self-Hosting](/docs/getting-started/self-hosting) for details.
+For self-hosted servers, use `multica setup self-host` instead. See [Self-Hosting](/getting-started/self-hosting) for details.
 
 ## Verify
 
@@ -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/cli/reference.mdx

@@ -212,7 +212,7 @@ multica issue list --priority urgent --assignee "Agent Name"
 multica issue list --limit 20 --output json
 ```
 
-Available filters: `--status`, `--priority`, `--assignee`, `--limit`.
+Available filters: `--status`, `--priority`, `--assignee`, `--project`, `--limit`.
 
 ### Get Issue
 
@@ -227,7 +227,7 @@ multica issue get <id> --output json
 multica issue create --title "Fix login bug" --description "..." --priority high --assignee "Lambda"
 ```
 
-Flags: `--title` (required), `--description`, `--status`, `--priority`, `--assignee`, `--parent`, `--due-date`.
+Flags: `--title` (required), `--description`, `--status`, `--priority`, `--assignee`, `--parent`, `--project`, `--due-date`.
 
 ### Update Issue
 
@@ -281,6 +281,70 @@ multica issue run-messages <task-id> --output json
 multica issue run-messages <task-id> --since 42 --output json
 ```
 
+## Projects
+
+Projects group related issues (e.g. a sprint, an epic, a workstream). Every project
+belongs to a workspace and can optionally have a lead (member or agent).
+
+### List Projects
+
+```bash
+multica project list
+multica project list --status in_progress
+multica project list --output json
+```
+
+Available filters: `--status`.
+
+### Get Project
+
+```bash
+multica project get <id>
+multica project get <id> --output json
+```
+
+### Create Project
+
+```bash
+multica project create --title "2026 Week 16 Sprint" --icon "🏃" --lead "Lambda"
+```
+
+Flags: `--title` (required), `--description`, `--status`, `--icon`, `--lead`.
+
+### Update Project
+
+```bash
+multica project update <id> --title "New title" --status in_progress
+multica project update <id> --lead "Lambda"
+```
+
+Flags: `--title`, `--description`, `--status`, `--icon`, `--lead`.
+
+### Change Status
+
+```bash
+multica project status <id> in_progress
+```
+
+Valid statuses: `planned`, `in_progress`, `paused`, `completed`, `cancelled`.
+
+### Delete Project
+
+```bash
+multica project delete <id>
+```
+
+### Associating Issues with Projects
+
+Use the `--project` flag on `issue create` / `issue update` to attach an issue to a
+project, or on `issue list` to filter issues by project:
+
+```bash
+multica issue create --title "Login bug" --project <project-id>
+multica issue update <issue-id> --project <project-id>
+multica issue list --project <project-id>
+```
+
 ## Configuration
 
 ### View Config

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/getting-started/self-hosting.mdx

@@ -31,7 +31,7 @@ curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/ins
 multica setup self-host
 ```
 
-This clones the repo, starts all services, installs the CLI, and configures it for localhost. Then open http://localhost:3000 — log in with any email + code **`888888`**.
+This clones the repo, starts all services, installs the CLI, and configures it for localhost. Then open http://localhost:3000 and pick a login method: configure `RESEND_API_KEY` in `.env` for email-based codes (recommended), or set `APP_ENV=development` in `.env` to enable the dev master code **`888888`**. See [Step 2 — Log In](#step-2--log-in) for details.
 
 <Callout>
 If the self-host server is already running and you only need the CLI on a macOS/Linux machine, install it with Homebrew: `brew install multica-ai/tap/multica`.
@@ -64,10 +64,14 @@ If you prefer running the Docker Compose steps manually: `cp .env.example .env`,
 
 ### Step 2 — Log In
 
-Open http://localhost:3000. Enter any email address and use verification code **`888888`** to log in.
+Open http://localhost:3000. The Docker self-host stack defaults to `APP_ENV=production` (set in `docker-compose.selfhost.yml`), so the dev master code is **disabled by default** for safety on public deployments. Pick one of the following to log in:
+
+- **Recommended (production):** configure `RESEND_API_KEY` in `.env`, then restart the backend. Real verification codes will be sent to the email address you enter. See [Configuration](#configuration) below.
+- **Evaluation / private network:** set `APP_ENV=development` in `.env` and restart the backend. Verification code **`888888`** will then work for any email address.
+- **Without configuring either:** the verification code is generated server-side and printed to the backend container logs (look for `[DEV] Verification code for ...:`). Useful for one-off testing on a single machine.
 
 <Callout>
-This master code works in all non-production environments (when `APP_ENV` is not set to `production`). For production, configure an email provider — see [Configuration](#configuration) below.
+**Warning:** do **not** set `APP_ENV=development` on a publicly reachable instance — anyone who knows an email address can then log in with `888888`.
 </Callout>
 
 ### Step 3 — Install CLI & Start Daemon
@@ -198,7 +202,14 @@ For file uploads and attachments, configure S3 and CloudFront:
 | `CLOUDFRONT_DOMAIN` | CloudFront distribution domain |
 | `CLOUDFRONT_KEY_PAIR_ID` | CloudFront key pair ID for signed URLs |
 | `CLOUDFRONT_PRIVATE_KEY` | CloudFront private key (PEM format) |
-| `COOKIE_DOMAIN` | Domain for CloudFront auth cookies |
+
+### Cookies
+
+| Variable | Description |
+|----------|-------------|
+| `COOKIE_DOMAIN` | Optional `Domain` attribute for session + CloudFront cookies. **Leave empty** for single-host deployments (localhost, LAN IP, or a single hostname). Only set it when the frontend and backend sit on different subdomains of one registered domain (e.g. `.example.com`). **Do not use an IP literal** — RFC 6265 forbids IP addresses in the cookie `Domain` attribute and browsers will drop such `Set-Cookie` headers. |
+
+The `Secure` flag on session cookies is derived automatically from the scheme of `FRONTEND_ORIGIN`: HTTPS origins get `Secure` cookies; plain-HTTP origins (LAN / private-network self-host) get non-secure cookies so the browser can actually store them.
 
 ### Server
 

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/docs/content/docs/index.mdx

@@ -41,7 +41,7 @@ No more copy-pasting prompts. No more babysitting runs. Your agents show up on t
 
 ## Next Steps
 
-- [Cloud Quickstart](/docs/getting-started/cloud-quickstart)
-- [Self-Hosting](/docs/getting-started/self-hosting)
-- [CLI Installation](/docs/cli/installation)
-- [Contributing](/docs/developers/contributing)
+- [Cloud Quickstart](/getting-started/cloud-quickstart)
+- [Self-Hosting](/getting-started/self-hosting)
+- [CLI Installation](/cli/installation)
+- [Contributing](/developers/contributing)

apps/docs/lib/source.ts

@@ -2,6 +2,6 @@ import { docs } from "@/.source";
 import { loader } from "fumadocs-core/source";
 
 export const source = loader({
-  baseUrl: "/docs",
+  baseUrl: "/",
   source: docs.toFumadocsSource(),
 });

apps/docs/next.config.mjs

@@ -5,6 +5,7 @@ const withMDX = createMDX();
 /** @type {import('next').NextConfig} */
 const config = {
   reactStrictMode: true,
+  basePath: "/docs",
 };
 
 export default withMDX(config);

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

@@ -2,7 +2,10 @@
 
 import { useEffect } from "react";
 import { useRouter, useParams } from "next/navigation";
+import { useQuery } from "@tanstack/react-query";
 import { useAuthStore } from "@multica/core/auth";
+import { paths } from "@multica/core/paths";
+import { workspaceListOptions } from "@multica/core/workspace/queries";
 import { InvitePage } from "@multica/views/invite";
 
 export default function InviteAcceptPage() {
@@ -10,15 +13,24 @@ export default function InviteAcceptPage() {
   const params = useParams<{ id: string }>();
   const user = useAuthStore((s) => s.user);
   const isLoading = useAuthStore((s) => s.isLoading);
+  const { data: wsList = [] } = useQuery({
+    ...workspaceListOptions(),
+    enabled: !!user,
+  });
 
   // 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]);
 
   if (isLoading || !user) return null;
 
-  return <InvitePage invitationId={params.id} />;
+  const onBack =
+    wsList.length > 0 ? () => router.push(paths.root()) : undefined;
+
+  return <InvitePage invitationId={params.id} onBack={onBack} />;
 }

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

@@ -11,35 +11,51 @@ function createWrapper() {
   );
 }
 
-const { mockSendCode, mockVerifyCode, mockHydrateWorkspace } = vi.hoisted(
-  () => ({
-    mockSendCode: vi.fn(),
-    mockVerifyCode: vi.fn(),
-    mockHydrateWorkspace: vi.fn(),
-  }),
-);
+const {
+  mockSendCode,
+  mockVerifyCode,
+  mockIssueCliToken,
+  searchParamsState,
+  authStateRef,
+} = vi.hoisted(() => ({
+  mockSendCode: vi.fn(),
+  mockVerifyCode: vi.fn(),
+  mockIssueCliToken: vi.fn(),
+  searchParamsState: { params: new URLSearchParams() },
+  authStateRef: {
+    state: {
+      sendCode: vi.fn(),
+      verifyCode: vi.fn(),
+      user: null as null | { id: string; email: string },
+      isLoading: false,
+    },
+  },
+}));
 
 // Mock next/navigation
 vi.mock("next/navigation", () => ({
   useRouter: () => ({ push: vi.fn(), replace: vi.fn() }),
   usePathname: () => "/login",
-  useSearchParams: () => new URLSearchParams(),
+  useSearchParams: () => searchParamsState.params,
 }));
 
 // Mock auth store — shared LoginPage uses getState().sendCode/verifyCode,
-// web wrapper uses useAuthStore((s) => s.user/isLoading)
-vi.mock("@multica/core/auth", () => {
-  const authState = {
-    sendCode: mockSendCode,
-    verifyCode: mockVerifyCode,
-    user: null,
-    isLoading: false,
-  };
+// web wrapper uses useAuthStore((s) => s.user/isLoading). Keep the real
+// sanitizeNextUrl so the redirect-sanitization rules are exercised rather
+// than silently drifting behind a mock reimplementation.
+vi.mock("@multica/core/auth", async () => {
+  const actual =
+    await vi.importActual<typeof import("@multica/core/auth")>(
+      "@multica/core/auth",
+    );
+  authStateRef.state.sendCode = mockSendCode;
+  authStateRef.state.verifyCode = mockVerifyCode;
   const useAuthStore = Object.assign(
-    (selector: (s: typeof authState) => unknown) => selector(authState),
-    { getState: () => authState },
+    (selector: (s: typeof authStateRef.state) => unknown) =>
+      selector(authStateRef.state),
+    { getState: () => authStateRef.state },
   );
-  return { useAuthStore };
+  return { ...actual, useAuthStore };
 });
 
 // Mock auth-cookie
@@ -47,16 +63,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: {
@@ -64,6 +70,7 @@ vi.mock("@multica/core/api", () => ({
     verifyCode: vi.fn(),
     setToken: vi.fn(),
     getMe: vi.fn(),
+    issueCliToken: mockIssueCliToken,
   },
 }));
 
@@ -72,6 +79,9 @@ import LoginPage from "./page";
 describe("LoginPage", () => {
   beforeEach(() => {
     vi.clearAllMocks();
+    searchParamsState.params = new URLSearchParams();
+    authStateRef.state.user = null;
+    authStateRef.state.isLoading = false;
   });
 
   it("renders login form with email input and continue button", () => {
@@ -144,4 +154,44 @@ describe("LoginPage", () => {
       expect(screen.getByText("Network error")).toBeInTheDocument();
     });
   });
+
+  // Regression: MUL-1080 — if the user is already authenticated on the web
+  // and the Desktop app redirects them to /login?platform=desktop, the web
+  // must exchange the cookie session for a bearer token and hand it off via
+  // the multica:// deep link, not silently redirect to the workspace page.
+  it("mints a token and deep-links to Desktop when already logged in with platform=desktop", async () => {
+    searchParamsState.params = new URLSearchParams({ platform: "desktop" });
+    authStateRef.state.user = { id: "u1", email: "test@multica.ai" };
+    mockIssueCliToken.mockImplementation(() =>
+      Promise.resolve({ token: "handoff-jwt" }),
+    );
+
+    const hrefSetter = vi.fn();
+    const originalLocation = window.location;
+    Object.defineProperty(window, "location", {
+      configurable: true,
+      value: { ...originalLocation, set href(value: string) { hrefSetter(value); } },
+    });
+
+    try {
+      render(<LoginPage />, { wrapper: createWrapper() });
+
+      await waitFor(() => {
+        expect(mockIssueCliToken).toHaveBeenCalledTimes(1);
+      });
+      await waitFor(() => {
+        expect(hrefSetter).toHaveBeenCalledWith(
+          "multica://auth/callback?token=handoff-jwt",
+        );
+      });
+      expect(
+        await screen.findByRole("button", { name: "Open Multica Desktop" }),
+      ).toBeInTheDocument();
+    } finally {
+      Object.defineProperty(window, "location", {
+        configurable: true,
+        value: originalLocation,
+      });
+    }
+  });
 });

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

@@ -1,9 +1,22 @@
 "use client";
 
-import { Suspense, useEffect } from "react";
+import { Suspense, useEffect, useState } from "react";
 import { useSearchParams, useRouter } from "next/navigation";
-import { useAuthStore } from "@multica/core/auth";
-import { useWorkspaceStore } from "@multica/core/workspace";
+import { useQueryClient } from "@tanstack/react-query";
+import { sanitizeNextUrl, useAuthStore } from "@multica/core/auth";
+import { workspaceKeys } from "@multica/core/workspace/queries";
+import { paths } from "@multica/core/paths";
+import { api } from "@multica/core/api";
+import type { Workspace } from "@multica/core/types";
+import {
+  Card,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+  CardContent,
+} from "@multica/ui/components/ui/card";
+import { Button } from "@multica/ui/components/ui/button";
+import { Loader2 } from "lucide-react";
 import { setLoggedInCookie } from "@/features/auth/auth-cookie";
 import { LoginPage, validateCliCallback } from "@multica/views/auth";
 
@@ -11,6 +24,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,34 +32,119 @@ 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";
+  const isDesktopHandoff = platform === "desktop" && !cliCallbackRaw;
+  // `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. Sanitize first so a crafted `?next=https://evil`
+  // cannot bounce the user off-origin after a successful login.
+  const nextUrl = sanitizeNextUrl(searchParams.get("next"));
 
-  // Already authenticated — redirect to dashboard (skip if CLI callback)
+  const [desktopToken, setDesktopToken] = useState<string | null>(null);
+  const [desktopError, setDesktopError] = useState("");
+
+  // Already authenticated — honor ?next= or fall back to first workspace
+  // (or /workspaces/new if the user has none). Skip this entire path when
+  // the user arrived to authorize the CLI.
   useEffect(() => {
-    if (!isLoading && user && !cliCallbackRaw) {
-      router.replace(nextUrl);
+    if (isLoading || !user || cliCallbackRaw) return;
+    if (isDesktopHandoff) {
+      // Desktop opened the browser for login but the web session is already
+      // authenticated — mint a bearer token from the cookie session and hand
+      // it off via deep link instead of silently redirecting to the workspace.
+      api
+        .issueCliToken()
+        .then(({ token }) => {
+          setDesktopToken(token);
+          window.location.href = `multica://auth/callback?token=${encodeURIComponent(token)}`;
+        })
+        .catch((err) => {
+          setDesktopError(
+            err instanceof Error ? err.message : "Failed to prepare Desktop sign-in",
+          );
+        });
+      return;
     }
-  }, [isLoading, user, router, nextUrl, cliCallbackRaw]);
-
-  const lastWorkspaceId =
-    typeof window !== "undefined"
-      ? localStorage.getItem("multica_workspace_id")
-      : null;
+    if (nextUrl) {
+      router.replace(nextUrl);
+      return;
+    }
+    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, isDesktopHandoff, 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;
 
+  // While the desktop handoff is in progress (or has produced a token/error),
+  // render a dedicated screen instead of flashing the login form or redirecting
+  // away to a workspace page.
+  if (isDesktopHandoff && user) {
+    if (desktopError) {
+      return (
+        <div className="flex min-h-screen items-center justify-center">
+          <Card className="w-full max-w-sm">
+            <CardHeader className="text-center">
+              <CardTitle className="text-2xl">Sign-in Failed</CardTitle>
+              <CardDescription>{desktopError}</CardDescription>
+            </CardHeader>
+          </Card>
+        </div>
+      );
+    }
+    return (
+      <div className="flex min-h-screen items-center justify-center">
+        <Card className="w-full max-w-sm">
+          <CardHeader className="text-center">
+            <CardTitle className="text-2xl">Opening Multica</CardTitle>
+            <CardDescription>
+              {desktopToken
+                ? "You should see a prompt to open the Multica desktop app. If nothing happens, click the button below."
+                : "Preparing Desktop sign-in..."}
+            </CardDescription>
+          </CardHeader>
+          <CardContent className="flex justify-center">
+            {desktopToken ? (
+              <Button
+                variant="outline"
+                onClick={() => {
+                  window.location.href = `multica://auth/callback?token=${encodeURIComponent(desktopToken)}`;
+                }}
+              >
+                Open Multica Desktop
+              </Button>
+            ) : (
+              <Loader2 className="h-6 w-6 animate-spin text-muted-foreground" />
+            )}
+          </CardContent>
+        </Card>
+      </div>
+    );
+  }
+
   return (
     <LoginPage
       onSuccess={handleSuccess}
@@ -63,7 +162,6 @@ function LoginPageContent() {
           ? { url: cliCallbackRaw, state: cliState }
           : undefined
       }
-      lastWorkspaceId={lastWorkspaceId}
       onTokenObtained={setLoggedInCookie}
     />
   );

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

@@ -1,23 +0,0 @@
-"use client";
-
-import { useEffect } from "react";
-import { useRouter } from "next/navigation";
-import { useAuthStore } from "@multica/core/auth";
-import { OnboardingWizard } from "@multica/views/onboarding";
-
-export default function OnboardingPage() {
-  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");
-  }, [isLoading, user, router]);
-
-  if (isLoading || !user) return null;
-
-  return (
-    <OnboardingWizard onComplete={() => router.push("/issues")} />
-  );
-}

apps/web/app/(auth)/workspaces/new/page.tsx

@@ -0,0 +1,38 @@
+"use client";
+
+import { useRouter } from "next/navigation";
+import { useEffect } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { useAuthStore } from "@multica/core/auth";
+import { paths } from "@multica/core/paths";
+import { workspaceListOptions } from "@multica/core/workspace/queries";
+import { NewWorkspacePage } from "@multica/views/workspace/new-workspace-page";
+
+export default function Page() {
+  const router = useRouter();
+  const user = useAuthStore((s) => s.user);
+  const isLoading = useAuthStore((s) => s.isLoading);
+  const { data: wsList = [] } = useQuery({
+    ...workspaceListOptions(),
+    enabled: !!user,
+  });
+
+  useEffect(() => {
+    if (!isLoading && !user) router.replace(paths.login());
+  }, [isLoading, user, router]);
+
+  if (isLoading || !user) return null;
+
+  // Back goes to the root path — the workspace layout redirects from
+  // there to the user's default workspace. Only show Back when there's
+  // somewhere to go back to (user already has at least one workspace).
+  const onBack =
+    wsList.length > 0 ? () => router.push(paths.root()) : undefined;
+
+  return (
+    <NewWorkspacePage
+      onSuccess={(ws) => router.push(paths.workspace(ws.slug).issues())}
+      onBack={onBack}
+    />
+  );
+}

apps/web/app/(dashboard)/loading.tsx

@@ -1,28 +0,0 @@
-import { Skeleton } from "@multica/ui/components/ui/skeleton";
-
-export default function DashboardLoading() {
-  return (
-    <div className="flex flex-1 min-h-0 flex-col">
-      {/* Header skeleton */}
-      <div className="flex h-12 shrink-0 items-center gap-2 border-b px-4">
-        <Skeleton className="h-5 w-5 rounded" />
-        <Skeleton className="h-4 w-32" />
-      </div>
-      {/* Toolbar skeleton */}
-      <div className="flex h-12 shrink-0 items-center justify-between border-b px-4">
-        <Skeleton className="h-5 w-24" />
-        <Skeleton className="h-8 w-24" />
-      </div>
-      {/* Content skeleton */}
-      <div className="flex-1 p-4 space-y-3">
-        {Array.from({ length: 6 }).map((_, i) => (
-          <div key={i} className="flex items-center gap-3">
-            <Skeleton className="h-4 w-4 rounded" />
-            <Skeleton className="h-4 flex-1 max-w-md" />
-            <Skeleton className="h-4 w-16" />
-          </div>
-        ))}
-      </div>
-    </div>
-  );
-}

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,91 @@
+"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 { MulticaIcon } from "@multica/ui/components/common/multica-icon";
+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);
+
+  const loadingIndicator = (
+    <div className="flex h-svh items-center justify-center">
+      <MulticaIcon className="size-6 animate-pulse" />
+    </div>
+  );
+
+  if (isAuthLoading) return loadingIndicator;
+  // 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 loadingIndicator;
+  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.test.tsx

@@ -0,0 +1,86 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, waitFor } from "@testing-library/react";
+import { paths } from "@multica/core/paths";
+
+const { mockPush, mockSearchParams, mockLoginWithGoogle, mockListWorkspaces } =
+  vi.hoisted(() => ({
+    mockPush: vi.fn(),
+    mockSearchParams: new URLSearchParams(),
+    mockLoginWithGoogle: vi.fn(),
+    mockListWorkspaces: vi.fn(),
+  }));
+
+vi.mock("next/navigation", () => ({
+  useRouter: () => ({ push: mockPush }),
+  useSearchParams: () => mockSearchParams,
+}));
+
+vi.mock("@tanstack/react-query", () => ({
+  useQueryClient: () => ({ setQueryData: vi.fn() }),
+}));
+
+// Preserve the real sanitizeNextUrl so the "drop unsafe ?next=" behavior is
+// exercised rather than silently diverging from the source of truth.
+vi.mock("@multica/core/auth", async () => {
+  const actual =
+    await vi.importActual<typeof import("@multica/core/auth")>(
+      "@multica/core/auth",
+    );
+  return {
+    ...actual,
+    useAuthStore: (selector: (s: unknown) => unknown) =>
+      selector({ loginWithGoogle: mockLoginWithGoogle }),
+  };
+});
+
+vi.mock("@multica/core/workspace/queries", () => ({
+  workspaceKeys: { list: () => ["workspaces"] },
+}));
+
+vi.mock("@multica/core/api", () => ({
+  api: {
+    listWorkspaces: mockListWorkspaces,
+    googleLogin: vi.fn(),
+  },
+}));
+
+import CallbackPage from "./page";
+
+describe("CallbackPage", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockSearchParams.forEach((_v, k) => mockSearchParams.delete(k));
+    mockSearchParams.set("code", "test-code");
+    mockLoginWithGoogle.mockResolvedValue(undefined);
+    mockListWorkspaces.mockResolvedValue([]);
+  });
+
+  it("falls back to paths.newWorkspace() when no next= is present and the user has no workspace", async () => {
+    render(<CallbackPage />);
+
+    await waitFor(() => {
+      expect(mockPush).toHaveBeenCalledWith(paths.newWorkspace());
+    });
+  });
+
+  it("ignores unsafe next= targets from the OAuth state and still lands on the default destination", async () => {
+    mockSearchParams.set("state", "next:https://evil.example");
+
+    render(<CallbackPage />);
+
+    await waitFor(() => {
+      expect(mockPush).toHaveBeenCalledWith(paths.newWorkspace());
+    });
+    expect(mockPush).not.toHaveBeenCalledWith("https://evil.example");
+  });
+
+  it("honors a safe next= target (e.g. /invite/{id})", async () => {
+    mockSearchParams.set("state", "next:/invite/abc123");
+
+    render(<CallbackPage />);
+
+    await waitFor(() => {
+      expect(mockPush).toHaveBeenCalledWith("/invite/abc123");
+    });
+  });
+});

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

@@ -3,9 +3,9 @@
 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 { sanitizeNextUrl, useAuthStore } from "@multica/core/auth";
 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);
 
@@ -43,7 +42,9 @@ function CallbackContent() {
     const stateParts = state.split(",");
     const isDesktop = stateParts.includes("platform:desktop");
     const nextPart = stateParts.find((p) => p.startsWith("next:"));
-    const nextUrl = nextPart ? nextPart.slice(5) : null; // strip "next:" prefix
+    // Strip "next:" prefix, then drop anything that isn't a safe relative path
+    // so an attacker-controlled `state=next:https://evil` cannot redirect here.
+    const nextUrl = sanitizeNextUrl(nextPart ? nextPart.slice(5) : null);
 
     const redirectUri = `${window.location.origin}/auth/callback`;
 
@@ -64,17 +65,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 /workspaces/new 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 +116,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/components/pageview-tracker.tsx

@@ -0,0 +1,29 @@
+"use client";
+
+import { useEffect } from "react";
+import { usePathname, useSearchParams } from "next/navigation";
+import { capturePageview } from "@multica/core/analytics";
+
+/**
+ * Fires a PostHog $pageview whenever the Next.js App Router path or query
+ * string changes. Mounted once at the root so every route transition is
+ * covered, including transitions into workspace-scoped subtrees.
+ *
+ * PostHog's own `capture_pageview: true` auto-capture is deliberately
+ * disabled in `initAnalytics` so we own the event shape — this component
+ * is what actually fires the event. Before this existed the acquisition
+ * funnel's `/ → signup` step was empty.
+ */
+export function PageviewTracker() {
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+
+  useEffect(() => {
+    if (!pathname) return;
+    const qs = searchParams?.toString();
+    const url = qs ? `${pathname}?${qs}` : pathname;
+    capturePageview(url);
+  }, [pathname, searchParams]);
+
+  return null;
+}

apps/web/components/web-providers.tsx

@@ -1,11 +1,13 @@
 "use client";
 
+import { Suspense } from "react";
 import { CoreProvider } from "@multica/core/platform";
 import { WebNavigationProvider } from "@/platform/navigation";
 import {
   setLoggedInCookie,
   clearLoggedInCookie,
 } from "@/features/auth/auth-cookie";
+import { PageviewTracker } from "./pageview-tracker";
 
 // Legacy token in localStorage → keep this session in token mode so users who
 // logged in before the cookie-auth migration stay authed. They migrate to
@@ -42,6 +44,11 @@ export function WebProviders({ children }: { children: React.ReactNode }) {
       onLogin={setLoggedInCookie}
       onLogout={clearLoggedInCookie}
     >
+      {/* Suspense boundary is required by Next.js for useSearchParams in
+          a client component mounted this high in the tree. */}
+      <Suspense fallback={null}>
+        <PageviewTracker />
+      </Suspense>
       <WebNavigationProvider>{children}</WebNavigationProvider>
     </CoreProvider>
   );

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}