From 3b8770a91d2ec8c5e5f81ff3ed1395dc5619eb62 Mon Sep 17 00:00:00 2001
From: viktormarinho <viktormpcs@gmail.com>
Date: Mon, 23 Feb 2026 16:09:29 -0300
Subject: [PATCH 01/21] docs: add ConnectionsSetup component design

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
---
 .../2026-02-23-connections-setup-design.md    | 136 ++++++++++++++++++
 1 file changed, 136 insertions(+)
 create mode 100644 docs/plans/2026-02-23-connections-setup-design.md

diff --git a/docs/plans/2026-02-23-connections-setup-design.md b/docs/plans/2026-02-23-connections-setup-design.md
new file mode 100644
index 0000000000..cdf5466dbc
--- /dev/null
+++ b/docs/plans/2026-02-23-connections-setup-design.md
@@ -0,0 +1,136 @@
+# ConnectionsSetup Component Design
+
+**Date:** 2026-02-23
+**Status:** Approved
+
+## Overview
+
+`ConnectionsSetup` is a context-agnostic React component that guides a user through installing, authenticating, and configuring a declared set of MCP connections. It is used in onboarding flows (project templates, agent installs) where a known set of MCPs must be present and ready before the user can proceed.
+
+It renders all slots vertically — no multi-step navigation. Satisfied slots collapse; unsatisfied slots show inline forms.
+
+## Component API
+
+```typescript
+type ConnectionSlot = {
+  label: string
+  registry: string   // registry connection app_name or id
+  item_id: string    // registry item id
+}
+
+type ConnectionsSetupProps = {
+  slots: Record<string, ConnectionSlot>
+  onComplete: (connections: Record<string, string>) => void  // slotId → connection_id
+}
+```
+
+The component owns no persistence. Callers fetch specs from wherever they live (agent records, template configs, etc.) and pass them as props. `onComplete` fires once every slot is satisfied — the returned record maps each slot ID to the resolved connection ID, leaving wiring decisions entirely to the caller.
+
+## Slot Resolution
+
+On mount, each slot queries existing connections filtered by `metadata.registry_item_id === slot.item_id`.
+
+- **One+ found, at least one satisfied** → `DONE` (first satisfied match selected)
+- **One+ found, none satisfied** → `PICKER` (user selects an existing connection or installs fresh)
+- **None found** → `FORM` (straight to install)
+- **Registry item not found** → `ERROR` ("Registry item not found. Check your registry connection.")
+
+## Render States
+
+### DONE
+Collapsed card showing connection name and icon. Includes a `[change ▾]` button that reopens the PICKER or FORM inline.
+
+### LOADING
+Skeleton card shown during initial slot resolution.
+
+### PICKER
+Shown when compatible connections already exist. Displays a dropdown of existing matching connections. User can select one and confirm, or choose "Install fresh" to expand the FORM inline.
+
+### FORM (INSTALL → AUTH → CONFIG → DONE)
+A single slot card that progresses through up to three sub-phases:
+
+**INSTALL**
+- `extractConnectionData(registryItem)` pre-fills connection params
+- User submits → `CONNECTION_CREATE` mutation
+- On success → determine next phase based on registry item metadata
+
+**AUTH — OAuth** (if registry item has `oauth_config`)
+- Renders "Authorize with [Provider]" button
+- Opens OAuth redirect (same flow as connection detail page)
+- On `oauth-callback` → polls for `status === "active"`
+
+**AUTH — Token** (if registry item requires token/header, no OAuth)
+- Renders token or header input
+- Submit → `CONNECTION_UPDATE` (encrypted via vault)
+- Polls for `status === "active"`
+
+**AUTH — None** (MCP works without auth)
+- Skipped. Polls for `status === "active"` immediately after install.
+
+**CONFIG** (only if connection has a `configuration_state` schema)
+- Renders form derived from the config schema
+- Submit → `CONNECTION_CONFIGURE` (or equivalent update)
+
+**Polling**: after each mutation, poll `CONNECTION_GET` every 2s, up to 15s, waiting for `status === "active"`. On timeout → error state with retry option on the slot.
+
+## Satisfaction Criteria
+
+A connection is considered satisfied when:
+1. `status === "active"` (tools listed successfully, no 401)
+2. If the connection has a `configuration_state` schema → config has been submitted and is valid
+
+`onComplete` fires when every slot in the `slots` record is simultaneously satisfied.
+
+## File Structure
+
+```
+apps/mesh/src/web/components/connections-setup/
+  index.ts                    ← re-exports ConnectionsSetup
+  connections-setup.tsx       ← root component, maps slots → SlotCard list
+  slot-card.tsx               ← single slot, owns phase state machine
+  slot-install-form.tsx       ← INSTALL phase
+  slot-auth-oauth.tsx         ← AUTH phase — OAuth button + polling
+  slot-auth-token.tsx         ← AUTH phase — token/header input
+  slot-config-form.tsx        ← CONFIG phase — config schema form
+  slot-done.tsx               ← collapsed done card with [change]
+  use-slot-resolution.ts      ← resolves initial slot state from existing connections
+  use-connection-poller.ts    ← polls CONNECTION_GET until active or timeout
+```
+
+## Usage Examples
+
+**Project template onboarding:**
+```tsx
+<ConnectionsSetup
+  slots={{
+    model: { label: "AI Model", registry: "official", item_id: "openai" },
+    email: { label: "Email Provider", registry: "official", item_id: "resend" },
+  }}
+  onComplete={({ model, email }) => {
+    enablePlugins(projectId, ["chat", "email"])
+    wireConnections(projectId, { modelConnectionId: model, emailConnectionId: email })
+    redirect(`/${org}/${project}`)
+  }}
+/>
+```
+
+**Marketplace agent install:**
+```tsx
+<ConnectionsSetup
+  slots={{
+    search: { label: "Web Search", registry: "official", item_id: "brave-search" },
+    browser: { label: "Browser", registry: "official", item_id: "puppeteer" },
+  }}
+  onComplete={(connections) => {
+    wireToAgent(agentId, connections)
+    closeDialog()
+  }}
+/>
+```
+
+## What This Is Not
+
+- Not a multi-step wizard — no next/back navigation
+- Not responsible for persisting slot specs — caller owns that
+- Not responsible for wiring connections to agents/projects — caller owns that via `onComplete`
+- Does not support binding-based (flexible) slots — exact registry item reference only for now

From fda11262f211c22e3238fc29a7db63017790b053 Mon Sep 17 00:00:00 2001
From: viktormarinho <viktormpcs@gmail.com>
Date: Mon, 23 Feb 2026 16:17:56 -0300
Subject: [PATCH 02/21] docs: add ConnectionsSetup implementation plan

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
---
 .../2026-02-23-connections-setup-plan.md      | 1195 +++++++++++++++++
 1 file changed, 1195 insertions(+)
 create mode 100644 docs/plans/2026-02-23-connections-setup-plan.md

diff --git a/docs/plans/2026-02-23-connections-setup-plan.md b/docs/plans/2026-02-23-connections-setup-plan.md
new file mode 100644
index 0000000000..c64c35fd8b
--- /dev/null
+++ b/docs/plans/2026-02-23-connections-setup-plan.md
@@ -0,0 +1,1195 @@
+# ConnectionsSetup Component Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Build a `ConnectionsSetup` component that guides users through installing, authenticating, and verifying a declared set of MCP connections—used in onboarding flows and marketplace agent installs.
+
+**Architecture:** Context-agnostic component that accepts a `Record<string, ConnectionSlot>` prop and fires `onComplete(Record<string, string>)` when all slots are satisfied. Each slot resolves against existing connections by `metadata.registry_item_id` and renders either a done card, a picker (existing connections), or an inline install+auth flow. No multi-step navigation—all slots are visible at once, satisfied slots collapse.
+
+**Tech Stack:** React 19, TanStack React Query v5, react-hook-form + Zod, `@decocms/mesh-sdk` hooks (`useConnectionActions`, `useConnections`, `useProjectContext`, `createMCPClient`, `SELF_MCP_ALIAS_ID`, `authenticateMcp`, `isConnectionAuthenticated`), existing utilities: `extractConnectionData`, `callRegistryTool`, `extractItemsFromResponse`, `findListToolName` from `@/web/utils/`.
+
+---
+
+## Reference: Key Imports
+
+```typescript
+// From @decocms/mesh-sdk
+import {
+  useConnectionActions,
+  useConnections,
+  useProjectContext,
+  createMCPClient,
+  SELF_MCP_ALIAS_ID,
+  authenticateMcp,
+  isConnectionAuthenticated,
+  type ConnectionEntity,
+  type McpAuthStatus,
+} from "@decocms/mesh-sdk";
+
+// Internal utilities
+import { extractConnectionData } from "@/web/utils/extract-connection-data";
+import {
+  callRegistryTool,
+  extractItemsFromResponse,
+  findListToolName,
+} from "@/web/utils/registry-utils";
+import { useRegistryConnections } from "@/web/hooks/use-binding";
+import { KEYS } from "@/web/lib/query-keys";
+
+// React Query
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+
+// Auth
+import { authClient } from "@/web/lib/auth-client";
+
+// Types
+import type { RegistryItem } from "@/web/components/store/types";
+```
+
+## Reference: Slot Types
+
+```typescript
+// Defined in connections-setup.tsx and re-exported via index.ts
+export interface ConnectionSlot {
+  label: string;
+  registry: string; // registry connection id or app_name
+  item_id: string;  // registry item id (matched against metadata.registry_item_id)
+}
+
+export interface ConnectionsSetupProps {
+  slots: Record<string, ConnectionSlot>;
+  onComplete: (connections: Record<string, string>) => void; // slotId → connection_id
+}
+```
+
+## Reference: Phase State Machine (per slot)
+
+```
+loading → picker (existing matching connections found)
+        → install (no matching connections)
+
+picker → done (user selects a satisfied connection)
+       → install (user clicks "Install fresh")
+
+install → polling (after successful CONNECTION_CREATE)
+
+polling → done (connection.status === "active")
+        → auth-oauth (timeout/error + supportsOAuth)
+        → auth-token (timeout/error + !supportsOAuth)
+
+auth-oauth → polling (after authenticateMcp success + update trigger)
+auth-token → polling (after token save + update trigger)
+
+done → picker (user clicks [change])
+     → install (no existing connections when [change] clicked)
+```
+
+---
+
+## Task 1: Add query keys for registry item and connection polling
+
+**Files:**
+- Modify: `apps/mesh/src/web/lib/query-keys.ts`
+
+**Step 1: Read the file**
+
+Open `apps/mesh/src/web/lib/query-keys.ts` and find the `KEYS` object.
+
+**Step 2: Add two new keys**
+
+Add after the `isMCPAuthenticated` key:
+
+```typescript
+  registryItem: (registryId: string, itemId: string) =>
+    ["registry-item", registryId, itemId] as const,
+
+  connectionPoll: (connectionId: string) =>
+    ["connection-poll", connectionId] as const,
+```
+
+**Step 3: Format and commit**
+
+```bash
+bun run fmt
+git add apps/mesh/src/web/lib/query-keys.ts
+git commit -m "feat(connections-setup): add registry-item and connection-poll query keys"
+```
+
+---
+
+## Task 2: Pure slot resolution logic + test
+
+**Files:**
+- Create: `apps/mesh/src/web/components/connections-setup/slot-resolution.ts`
+- Create: `apps/mesh/src/web/components/connections-setup/slot-resolution.test.ts`
+
+**Step 1: Write the failing test**
+
+Create `apps/mesh/src/web/components/connections-setup/slot-resolution.test.ts`:
+
+```typescript
+import { describe, expect, it } from "bun:test";
+import type { ConnectionEntity } from "@decocms/mesh-sdk";
+import { resolveInitialPhase } from "./slot-resolution";
+
+function makeConn(
+  overrides: Partial<ConnectionEntity> & { metadata?: Record<string, unknown> },
+): ConnectionEntity {
+  return {
+    id: "conn_test",
+    title: "Test",
+    status: "inactive",
+    connection_type: "HTTP",
+    connection_url: null,
+    connection_token: null,
+    connection_headers: null,
+    oauth_config: null,
+    configuration_state: null,
+    configuration_scopes: null,
+    description: null,
+    icon: null,
+    app_name: null,
+    app_id: null,
+    tools: null,
+    bindings: null,
+    organization_id: "org_1",
+    created_by: "user_1",
+    updated_by: "user_1",
+    created_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+    ...overrides,
+  } as unknown as ConnectionEntity;
+}
+
+describe("resolveInitialPhase", () => {
+  it("returns 'install' when no matching connections exist", () => {
+    const connections: ConnectionEntity[] = [
+      makeConn({ metadata: { registry_item_id: "other-item" } }),
+    ];
+    expect(resolveInitialPhase(connections, "my-item")).toBe("install");
+  });
+
+  it("returns 'done' when a matching active connection exists", () => {
+    const connections: ConnectionEntity[] = [
+      makeConn({
+        id: "conn_active",
+        status: "active",
+        metadata: { registry_item_id: "my-item" },
+      }),
+    ];
+    expect(resolveInitialPhase(connections, "my-item")).toBe("done");
+  });
+
+  it("returns 'picker' when matching connections exist but none are active", () => {
+    const connections: ConnectionEntity[] = [
+      makeConn({
+        id: "conn_inactive",
+        status: "inactive",
+        metadata: { registry_item_id: "my-item" },
+      }),
+    ];
+    expect(resolveInitialPhase(connections, "my-item")).toBe("picker");
+  });
+
+  it("returns 'done' for first active match when multiple exist", () => {
+    const connections: ConnectionEntity[] = [
+      makeConn({ status: "inactive", metadata: { registry_item_id: "my-item" } }),
+      makeConn({ id: "conn_2", status: "active", metadata: { registry_item_id: "my-item" } }),
+    ];
+    expect(resolveInitialPhase(connections, "my-item")).toBe("done");
+  });
+});
+
+describe("findMatchingConnections", () => {
+  it("filters connections by registry_item_id", () => {
+    const connections: ConnectionEntity[] = [
+      makeConn({ id: "conn_a", metadata: { registry_item_id: "item-1" } }),
+      makeConn({ id: "conn_b", metadata: { registry_item_id: "item-2" } }),
+      makeConn({ id: "conn_c", metadata: { registry_item_id: "item-1" } }),
+    ];
+    const { findMatchingConnections } = await import("./slot-resolution");
+    const result = findMatchingConnections(connections, "item-1");
+    expect(result).toHaveLength(2);
+    expect(result.map((c) => c.id)).toEqual(["conn_a", "conn_c"]);
+  });
+});
+```
+
+**Step 2: Run test to confirm it fails**
+
+```bash
+bun test apps/mesh/src/web/components/connections-setup/slot-resolution.test.ts
+```
+
+Expected: FAIL — module not found.
+
+**Step 3: Create the implementation**
+
+Create `apps/mesh/src/web/components/connections-setup/slot-resolution.ts`:
+
+```typescript
+import type { ConnectionEntity } from "@decocms/mesh-sdk";
+
+export type SlotPhase =
+  | "loading"
+  | "picker"
+  | "install"
+  | "polling"
+  | "auth-oauth"
+  | "auth-token"
+  | "done";
+
+export function findMatchingConnections(
+  connections: ConnectionEntity[],
+  itemId: string,
+): ConnectionEntity[] {
+  return connections.filter(
+    (c) =>
+      (c.metadata as Record<string, unknown> | null)?.registry_item_id === itemId,
+  );
+}
+
+export function resolveInitialPhase(
+  connections: ConnectionEntity[],
+  itemId: string,
+): "done" | "picker" | "install" {
+  const matches = findMatchingConnections(connections, itemId);
+  if (matches.length === 0) return "install";
+  const hasActive = matches.some((c) => c.status === "active");
+  return hasActive ? "done" : "picker";
+}
+```
+
+**Step 4: Run tests to confirm they pass**
+
+```bash
+bun test apps/mesh/src/web/components/connections-setup/slot-resolution.test.ts
+```
+
+Expected: PASS (4 tests).
+
+**Step 5: Format and commit**
+
+```bash
+bun run fmt
+git add apps/mesh/src/web/components/connections-setup/
+git commit -m "feat(connections-setup): add slot resolution pure logic with tests"
+```
+
+---
+
+## Task 3: `use-slot-resolution.ts` hook
+
+**Files:**
+- Create: `apps/mesh/src/web/components/connections-setup/use-slot-resolution.ts`
+
+**Step 1: Write the hook**
+
+This hook combines the pure resolution logic with async registry item fetching.
+
+Create `apps/mesh/src/web/components/connections-setup/use-slot-resolution.ts`:
+
+```typescript
+import { useQuery } from "@tanstack/react-query";
+import {
+  useConnections,
+  useProjectContext,
+  type ConnectionEntity,
+} from "@decocms/mesh-sdk";
+import { useRegistryConnections } from "@/web/hooks/use-binding";
+import {
+  callRegistryTool,
+  extractItemsFromResponse,
+  findListToolName,
+} from "@/web/utils/registry-utils";
+import { KEYS } from "@/web/lib/query-keys";
+import type { RegistryItem } from "@/web/components/store/types";
+import {
+  findMatchingConnections,
+  resolveInitialPhase,
+  type SlotPhase,
+} from "./slot-resolution";
+
+export interface ConnectionSlot {
+  label: string;
+  registry: string;
+  item_id: string;
+}
+
+export interface SlotResolution {
+  initialPhase: SlotPhase;
+  registryItem: RegistryItem | null;
+  matchingConnections: ConnectionEntity[];
+  satisfiedConnection: ConnectionEntity | null;
+  isLoading: boolean;
+  registryError: string | null;
+}
+
+export function useSlotResolution(slot: ConnectionSlot): SlotResolution {
+  const { org } = useProjectContext();
+  const allConnections = useConnections();
+  const registryConnections = useRegistryConnections(allConnections);
+
+  const registryConn = registryConnections.find(
+    (c) => c.id === slot.registry || c.app_name === slot.registry,
+  );
+
+  const { data: registryItem, isLoading: isLoadingItem } = useQuery({
+    queryKey: KEYS.registryItem(slot.registry, slot.item_id),
+    queryFn: async (): Promise<RegistryItem | null> => {
+      if (!registryConn) return null;
+      const listTool = findListToolName(registryConn.tools);
+      if (!listTool) return null;
+      const result = await callRegistryTool<unknown>(
+        registryConn.id,
+        org.id,
+        listTool,
+        { where: { id: slot.item_id } },
+      );
+      const items = extractItemsFromResponse<RegistryItem>(result);
+      return items[0] ?? null;
+    },
+    enabled: Boolean(registryConn && org),
+    staleTime: 60 * 60 * 1000,
+  });
+
+  const connections = allConnections ?? [];
+  const matchingConnections = findMatchingConnections(connections, slot.item_id);
+  const satisfiedConnection =
+    matchingConnections.find((c) => c.status === "active") ?? null;
+
+  if (!allConnections || isLoadingItem) {
+    return {
+      initialPhase: "loading",
+      registryItem: null,
+      matchingConnections: [],
+      satisfiedConnection: null,
+      isLoading: true,
+      registryError: null,
+    };
+  }
+
+  const registryError =
+    !isLoadingItem && !registryItem ? "Registry item not found." : null;
+
+  const initialPhase = resolveInitialPhase(connections, slot.item_id);
+
+  return {
+    initialPhase,
+    registryItem: registryItem ?? null,
+    matchingConnections,
+    satisfiedConnection,
+    isLoading: false,
+    registryError,
+  };
+}
+```
+
+**Step 2: Format and commit**
+
+```bash
+bun run fmt
+git add apps/mesh/src/web/components/connections-setup/use-slot-resolution.ts
+git commit -m "feat(connections-setup): add use-slot-resolution hook"
+```
+
+---
+
+## Task 4: `use-connection-poller.ts` hook
+
+**Files:**
+- Create: `apps/mesh/src/web/components/connections-setup/use-connection-poller.ts`
+
+**Step 1: Write the hook**
+
+Polls `COLLECTION_CONNECTIONS_GET` every 2s until `status === "active"` or `status === "error"`. Stops after 15s (timeout).
+
+Create `apps/mesh/src/web/components/connections-setup/use-connection-poller.ts`:
+
+```typescript
+import { useRef } from "react";
+import { useQuery } from "@tanstack/react-query";
+import {
+  createMCPClient,
+  SELF_MCP_ALIAS_ID,
+  useProjectContext,
+  type ConnectionEntity,
+} from "@decocms/mesh-sdk";
+import { KEYS } from "@/web/lib/query-keys";
+
+const POLL_INTERVAL_MS = 2000;
+const POLL_TIMEOUT_MS = 15000;
+
+export interface ConnectionPollerResult {
+  connection: ConnectionEntity | null;
+  isActive: boolean;
+  isTimedOut: boolean;
+  isPolling: boolean;
+}
+
+export function useConnectionPoller(
+  connectionId: string | null,
+): ConnectionPollerResult {
+  const { org } = useProjectContext();
+  const startTimeRef = useRef<number>(0);
+
+  if (connectionId && startTimeRef.current === 0) {
+    startTimeRef.current = Date.now();
+  }
+  if (!connectionId) {
+    startTimeRef.current = 0;
+  }
+
+  const { data: connection } = useQuery({
+    queryKey: KEYS.connectionPoll(connectionId ?? ""),
+    queryFn: async (): Promise<ConnectionEntity | null> => {
+      if (!connectionId) return null;
+      const client = await createMCPClient({
+        connectionId: SELF_MCP_ALIAS_ID,
+        orgId: org.id,
+      });
+      try {
+        const result = (await client.callTool({
+          name: "COLLECTION_CONNECTIONS_GET",
+          arguments: { id: connectionId },
+        })) as { structuredContent?: ConnectionEntity } | ConnectionEntity;
+        return (
+          (result as { structuredContent?: ConnectionEntity }).structuredContent ??
+          (result as ConnectionEntity)
+        );
+      } finally {
+        await client.close().catch(console.error);
+      }
+    },
+    refetchInterval: (query) => {
+      const conn = query.state.data;
+      if (!connectionId) return false;
+      if (conn?.status === "active" || conn?.status === "error") return false;
+      if (Date.now() - startTimeRef.current > POLL_TIMEOUT_MS) return false;
+      return POLL_INTERVAL_MS;
+    },
+    enabled: Boolean(connectionId && org),
+    staleTime: 0,
+  });
+
+  const isTimedOut =
+    Boolean(connectionId) &&
+    startTimeRef.current > 0 &&
+    Date.now() - startTimeRef.current > POLL_TIMEOUT_MS &&
+    connection?.status !== "active";
+
+  return {
+    connection: connection ?? null,
+    isActive: connection?.status === "active",
+    isTimedOut,
+    isPolling:
+      Boolean(connectionId) &&
+      connection?.status !== "active" &&
+      connection?.status !== "error" &&
+      !isTimedOut,
+  };
+}
+```
+
+**Step 2: Format and commit**
+
+```bash
+bun run fmt
+git add apps/mesh/src/web/components/connections-setup/use-connection-poller.ts
+git commit -m "feat(connections-setup): add use-connection-poller hook"
+```
+
+---
+
+## Task 5: `slot-done.tsx` — collapsed done state
+
+**Files:**
+- Create: `apps/mesh/src/web/components/connections-setup/slot-done.tsx`
+
+**Step 1: Write the component**
+
+Create `apps/mesh/src/web/components/connections-setup/slot-done.tsx`:
+
+```typescript
+import { CheckCircle, ChevronDown } from "lucide-react";
+import { Button } from "@deco/ui/components/button.tsx";
+import type { ConnectionEntity } from "@decocms/mesh-sdk";
+
+interface SlotDoneProps {
+  label: string;
+  connection: ConnectionEntity;
+  onReset: () => void;
+}
+
+export function SlotDone({ label, connection, onReset }: SlotDoneProps) {
+  return (
+    <div className="flex items-center gap-3 rounded-lg border border-success/30 bg-success/5 px-4 py-3">
+      <CheckCircle className="size-4 shrink-0 text-success" />
+      <div className="flex-1 min-w-0">
+        <p className="text-sm font-medium text-foreground">{label}</p>
+        <p className="text-xs text-muted-foreground truncate">{connection.title}</p>
+      </div>
+      <Button variant="ghost" size="sm" onClick={onReset} className="gap-1 shrink-0">
+        Change <ChevronDown className="size-3" />
+      </Button>
+    </div>
+  );
+}
+```
+
+**Step 2: Format and commit**
+
+```bash
+bun run fmt
+git add apps/mesh/src/web/components/connections-setup/slot-done.tsx
+git commit -m "feat(connections-setup): add slot-done component"
+```
+
+---
+
+## Task 6: `slot-install-form.tsx` — install phase
+
+**Files:**
+- Create: `apps/mesh/src/web/components/connections-setup/slot-install-form.tsx`
+
+**Step 1: Write the component**
+
+Pre-fills a connection form from the registry item via `extractConnectionData`. On submit creates the connection.
+
+Create `apps/mesh/src/web/components/connections-setup/slot-install-form.tsx`:
+
+```typescript
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { z } from "zod";
+import {
+  useConnectionActions,
+  useProjectContext,
+  type ConnectionEntity,
+} from "@decocms/mesh-sdk";
+import { authClient } from "@/web/lib/auth-client";
+import { extractConnectionData } from "@/web/utils/extract-connection-data";
+import { Button } from "@deco/ui/components/button.tsx";
+import {
+  Form,
+  FormControl,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from "@deco/ui/components/form.tsx";
+import { Input } from "@deco/ui/components/input.tsx";
+import type { RegistryItem } from "@/web/components/store/types";
+
+const installSchema = z.object({
+  title: z.string().min(1, "Name is required"),
+});
+
+type InstallFormData = z.infer<typeof installSchema>;
+
+interface SlotInstallFormProps {
+  registryItem: RegistryItem;
+  onInstalled: (connectionId: string) => void;
+}
+
+export function SlotInstallForm({
+  registryItem,
+  onInstalled,
+}: SlotInstallFormProps) {
+  const { org } = useProjectContext();
+  const { data: session } = authClient.useSession();
+  const actions = useConnectionActions();
+
+  const connectionData = extractConnectionData(
+    registryItem,
+    org.id,
+    session?.user?.id ?? "system",
+  );
+
+  const form = useForm<InstallFormData>({
+    resolver: zodResolver(installSchema),
+    defaultValues: { title: connectionData.title ?? "" },
+  });
+
+  const handleSubmit = async (data: InstallFormData) => {
+    const payload: ConnectionEntity = {
+      ...(connectionData as ConnectionEntity),
+      title: data.title,
+    };
+    await actions.create.mutateAsync(payload);
+    onInstalled(connectionData.id);
+  };
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(handleSubmit)} className="space-y-3">
+        <FormField
+          control={form.control}
+          name="title"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Connection name</FormLabel>
+              <FormControl>
+                <Input placeholder="e.g. OpenAI" {...field} />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <Button type="submit" disabled={actions.create.isPending} className="w-full">
+          {actions.create.isPending ? "Installing..." : "Install"}
+        </Button>
+      </form>
+    </Form>
+  );
+}
+```
+
+**Step 2: Format and commit**
+
+```bash
+bun run fmt
+git add apps/mesh/src/web/components/connections-setup/slot-install-form.tsx
+git commit -m "feat(connections-setup): add slot-install-form component"
+```
+
+---
+
+## Task 7: `slot-auth-oauth.tsx` — OAuth authorize phase
+
+**Files:**
+- Create: `apps/mesh/src/web/components/connections-setup/slot-auth-oauth.tsx`
+
+**Step 1: Write the component**
+
+Mirrors `handleAuthenticate` from `apps/mesh/src/web/components/details/connection/index.tsx:340-409`.
+
+Create `apps/mesh/src/web/components/connections-setup/slot-auth-oauth.tsx`:
+
+```typescript
+import { useState } from "react";
+import { toast } from "sonner";
+import {
+  authenticateMcp,
+  useConnectionActions,
+  useProjectContext,
+} from "@decocms/mesh-sdk";
+import { useQueryClient } from "@tanstack/react-query";
+import { KEYS } from "@/web/lib/query-keys";
+import { Button } from "@deco/ui/components/button.tsx";
+
+interface SlotAuthOAuthProps {
+  connectionId: string;
+  providerName: string;
+  onAuthed: () => void;
+}
+
+export function SlotAuthOAuth({
+  connectionId,
+  providerName,
+  onAuthed,
+}: SlotAuthOAuthProps) {
+  const [isPending, setIsPending] = useState(false);
+  const actions = useConnectionActions();
+  const queryClient = useQueryClient();
+  const mcpProxyUrl = new URL(`/mcp/${connectionId}`, window.location.origin);
+
+  const handleAuthorize = async () => {
+    setIsPending(true);
+    try {
+      const { token, tokenInfo, error } = await authenticateMcp({ connectionId });
+
+      if (error || !token) {
+        toast.error(`Authorization failed: ${error ?? "Unknown error"}`);
+        return;
+      }
+
+      if (tokenInfo) {
+        const response = await fetch(`/api/connections/${connectionId}/oauth-token`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          credentials: "include",
+          body: JSON.stringify({
+            accessToken: tokenInfo.accessToken,
+            refreshToken: tokenInfo.refreshToken,
+            expiresIn: tokenInfo.expiresIn,
+            scope: tokenInfo.scope,
+            clientId: tokenInfo.clientId,
+            clientSecret: tokenInfo.clientSecret,
+            tokenEndpoint: tokenInfo.tokenEndpoint,
+          }),
+        });
+        if (!response.ok) {
+          await actions.update.mutateAsync({
+            id: connectionId,
+            data: { connection_token: token },
+          });
+        } else {
+          // Trigger tool re-discovery
+          await actions.update.mutateAsync({ id: connectionId, data: {} });
+        }
+      } else {
+        await actions.update.mutateAsync({
+          id: connectionId,
+          data: { connection_token: token },
+        });
+      }
+
+      await queryClient.invalidateQueries({
+        queryKey: KEYS.isMCPAuthenticated(mcpProxyUrl.href, null),
+      });
+
+      onAuthed();
+    } finally {
+      setIsPending(false);
+    }
+  };
+
+  return (
+    <div className="space-y-3">
+      <p className="text-sm text-muted-foreground">
+        Authorize Mesh to access {providerName} on your behalf.
+      </p>
+      <Button onClick={handleAuthorize} disabled={isPending} className="w-full">
+        {isPending ? "Authorizing..." : `Authorize with ${providerName}`}
+      </Button>
+    </div>
+  );
+}
+```
+
+**Step 2: Format and commit**
+
+```bash
+bun run fmt
+git add apps/mesh/src/web/components/connections-setup/slot-auth-oauth.tsx
+git commit -m "feat(connections-setup): add slot-auth-oauth component"
+```
+
+---
+
+## Task 8: `slot-auth-token.tsx` — token input phase
+
+**Files:**
+- Create: `apps/mesh/src/web/components/connections-setup/slot-auth-token.tsx`
+
+**Step 1: Write the component**
+
+Create `apps/mesh/src/web/components/connections-setup/slot-auth-token.tsx`:
+
+```typescript
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { z } from "zod";
+import { useConnectionActions } from "@decocms/mesh-sdk";
+import { Button } from "@deco/ui/components/button.tsx";
+import {
+  Form,
+  FormControl,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from "@deco/ui/components/form.tsx";
+import { Input } from "@deco/ui/components/input.tsx";
+
+const tokenSchema = z.object({
+  token: z.string().min(1, "Token is required"),
+});
+
+type TokenFormData = z.infer<typeof tokenSchema>;
+
+interface SlotAuthTokenProps {
+  connectionId: string;
+  onAuthed: () => void;
+}
+
+export function SlotAuthToken({ connectionId, onAuthed }: SlotAuthTokenProps) {
+  const actions = useConnectionActions();
+
+  const form = useForm<TokenFormData>({
+    resolver: zodResolver(tokenSchema),
+    defaultValues: { token: "" },
+  });
+
+  const handleSubmit = async (data: TokenFormData) => {
+    await actions.update.mutateAsync({
+      id: connectionId,
+      data: { connection_token: data.token },
+    });
+    // Trigger tool re-discovery
+    await actions.update.mutateAsync({ id: connectionId, data: {} });
+    onAuthed();
+  };
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(handleSubmit)} className="space-y-3">
+        <FormField
+          control={form.control}
+          name="token"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>API Token</FormLabel>
+              <FormControl>
+                <Input type="password" placeholder="sk-..." {...field} />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <Button type="submit" disabled={actions.update.isPending} className="w-full">
+          {actions.update.isPending ? "Saving..." : "Save token"}
+        </Button>
+      </form>
+    </Form>
+  );
+}
+```
+
+**Step 2: Format and commit**
+
+```bash
+bun run fmt
+git add apps/mesh/src/web/components/connections-setup/slot-auth-token.tsx
+git commit -m "feat(connections-setup): add slot-auth-token component"
+```
+
+---
+
+## Task 9: `slot-card.tsx` — full phase state machine
+
+**Files:**
+- Create: `apps/mesh/src/web/components/connections-setup/slot-card.tsx`
+
+This is the main orchestrator. It owns the per-slot phase state and transitions between all phases.
+
+**Step 1: Write the component**
+
+Create `apps/mesh/src/web/components/connections-setup/slot-card.tsx`:
+
+```typescript
+import { useState } from "react";
+import { AlertCircle, Loader2 } from "lucide-react";
+import { isConnectionAuthenticated } from "@decocms/mesh-sdk";
+import { Button } from "@deco/ui/components/button.tsx";
+import { useSlotResolution, type ConnectionSlot } from "./use-slot-resolution";
+import { useConnectionPoller } from "./use-connection-poller";
+import { findMatchingConnections, type SlotPhase } from "./slot-resolution";
+import { SlotDone } from "./slot-done";
+import { SlotInstallForm } from "./slot-install-form";
+import { SlotAuthOAuth } from "./slot-auth-oauth";
+import { SlotAuthToken } from "./slot-auth-token";
+import type { ConnectionEntity } from "@decocms/mesh-sdk";
+
+interface SlotCardProps {
+  slot: ConnectionSlot;
+  onComplete: (connectionId: string) => void;
+}
+
+export function SlotCard({ slot, onComplete }: SlotCardProps) {
+  const resolution = useSlotResolution(slot);
+  const [phase, setPhase] = useState<SlotPhase | null>(null);
+  const [pollingConnectionId, setPollingConnectionId] = useState<string | null>(null);
+  const [selectedConnection, setSelectedConnection] = useState<ConnectionEntity | null>(null);
+
+  const poller = useConnectionPoller(pollingConnectionId);
+
+  // Derive effective phase: explicit override takes priority, else from resolution
+  const effectivePhase: SlotPhase = phase ?? resolution.initialPhase;
+
+  // React to poller becoming active
+  if (pollingConnectionId && poller.isActive && poller.connection) {
+    setPollingConnectionId(null);
+    setSelectedConnection(poller.connection);
+    setPhase("done");
+    onComplete(poller.connection.id);
+  }
+
+  // React to poller timeout/error — determine auth type needed
+  if (
+    pollingConnectionId &&
+    (poller.isTimedOut || poller.connection?.status === "error")
+  ) {
+    const connectionId = pollingConnectionId;
+    setPollingConnectionId(null);
+
+    // Async: check auth status to determine next phase
+    const url = new URL(`/mcp/${connectionId}`, window.location.origin).href;
+    isConnectionAuthenticated({ url, token: null }).then((authStatus) => {
+      if (authStatus.supportsOAuth) {
+        setPhase("auth-oauth");
+      } else {
+        setPhase("auth-token");
+      }
+    });
+  }
+
+  const handleInstalled = (connectionId: string) => {
+    setPollingConnectionId(connectionId);
+    setPhase("polling");
+  };
+
+  const handleAuthed = () => {
+    // Re-enter polling after auth — poller will reset via connectionId change
+    const id = pollingConnectionId ?? selectedConnection?.id ?? null;
+    if (id) {
+      setPollingConnectionId(id);
+      setPhase("polling");
+    }
+  };
+
+  const handleReset = () => {
+    const hasExisting = resolution.matchingConnections.length > 0;
+    setPhase(hasExisting ? "picker" : "install");
+    setSelectedConnection(null);
+    setPollingConnectionId(null);
+    onComplete(""); // signal slot is no longer complete
+  };
+
+  const resolvedConnection =
+    selectedConnection ??
+    resolution.satisfiedConnection ??
+    null;
+
+  if (effectivePhase === "loading") {
+    return (
+      <div className="flex items-center gap-3 rounded-lg border bg-muted/30 px-4 py-3">
+        <Loader2 className="size-4 animate-spin text-muted-foreground" />
+        <p className="text-sm text-muted-foreground">{slot.label}</p>
+      </div>
+    );
+  }
+
+  if (resolution.registryError) {
+    return (
+      <div className="flex items-center gap-3 rounded-lg border border-destructive/30 bg-destructive/5 px-4 py-3">
+        <AlertCircle className="size-4 shrink-0 text-destructive" />
+        <div>
+          <p className="text-sm font-medium">{slot.label}</p>
+          <p className="text-xs text-muted-foreground">{resolution.registryError}</p>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="rounded-lg border bg-card px-4 py-4 space-y-3">
+      <p className="text-sm font-medium text-foreground">{slot.label}</p>
+
+      {effectivePhase === "done" && resolvedConnection && (
+        <SlotDone
+          label={slot.label}
+          connection={resolvedConnection}
+          onReset={handleReset}
+        />
+      )}
+
+      {effectivePhase === "picker" && (
+        <div className="space-y-2">
+          <p className="text-xs text-muted-foreground">Already installed:</p>
+          <div className="space-y-1">
+            {resolution.matchingConnections.map((conn) => (
+              <button
+                key={conn.id}
+                type="button"
+                onClick={() => {
+                  if (conn.status === "active") {
+                    setSelectedConnection(conn);
+                    setPhase("done");
+                    onComplete(conn.id);
+                  } else {
+                    setSelectedConnection(conn);
+                    setPollingConnectionId(conn.id);
+                    setPhase("polling");
+                  }
+                }}
+                className="w-full flex items-center justify-between rounded border px-3 py-2 text-sm hover:bg-accent transition-colors"
+              >
+                <span>{conn.title}</span>
+                <span className="text-xs text-muted-foreground">{conn.status}</span>
+              </button>
+            ))}
+          </div>
+          <Button
+            variant="outline"
+            size="sm"
+            className="w-full"
+            onClick={() => setPhase("install")}
+          >
+            Install fresh
+          </Button>
+        </div>
+      )}
+
+      {effectivePhase === "install" && resolution.registryItem && (
+        <SlotInstallForm
+          registryItem={resolution.registryItem}
+          onInstalled={handleInstalled}
+        />
+      )}
+
+      {effectivePhase === "polling" && (
+        <div className="flex items-center gap-2 text-sm text-muted-foreground">
+          <Loader2 className="size-4 animate-spin" />
+          Connecting...
+        </div>
+      )}
+
+      {effectivePhase === "auth-oauth" && selectedConnection && (
+        <SlotAuthOAuth
+          connectionId={selectedConnection.id}
+          providerName={resolution.registryItem?.title ?? slot.label}
+          onAuthed={handleAuthed}
+        />
+      )}
+
+      {effectivePhase === "auth-token" && selectedConnection && (
+        <SlotAuthToken
+          connectionId={selectedConnection.id}
+          onAuthed={handleAuthed}
+        />
+      )}
+    </div>
+  );
+}
+```
+
+> **Note:** The `onComplete("")` call in `handleReset` is a sentinel to signal the slot is no longer done. `connections-setup.tsx` will filter out empty strings when checking completion.
+
+**Step 2: Format and commit**
+
+```bash
+bun run fmt
+git add apps/mesh/src/web/components/connections-setup/slot-card.tsx
+git commit -m "feat(connections-setup): add slot-card state machine component"
+```
+
+---
+
+## Task 10: `connections-setup.tsx` — root component
+
+**Files:**
+- Create: `apps/mesh/src/web/components/connections-setup/connections-setup.tsx`
+
+**Step 1: Write the component**
+
+Create `apps/mesh/src/web/components/connections-setup/connections-setup.tsx`:
+
+```typescript
+import { useState } from "react";
+import { SlotCard } from "./slot-card";
+import type { ConnectionSlot } from "./use-slot-resolution";
+
+export interface ConnectionsSetupProps {
+  slots: Record<string, ConnectionSlot>;
+  onComplete: (connections: Record<string, string>) => void;
+}
+
+export function ConnectionsSetup({ slots, onComplete }: ConnectionsSetupProps) {
+  const [completed, setCompleted] = useState<Record<string, string>>({});
+
+  const handleSlotComplete = (slotId: string, connectionId: string) => {
+    const next = { ...completed };
+    if (connectionId === "") {
+      delete next[slotId];
+    } else {
+      next[slotId] = connectionId;
+    }
+    setCompleted(next);
+
+    const slotIds = Object.keys(slots);
+    const allDone = slotIds.every((id) => next[id]);
+    if (allDone) {
+      onComplete(next);
+    }
+  };
+
+  return (
+    <div className="space-y-3">
+      {Object.entries(slots).map(([slotId, slot]) => (
+        <SlotCard
+          key={slotId}
+          slot={slot}
+          onComplete={(connectionId) => handleSlotComplete(slotId, connectionId)}
+        />
+      ))}
+    </div>
+  );
+}
+```
+
+**Step 2: Format and commit**
+
+```bash
+bun run fmt
+git add apps/mesh/src/web/components/connections-setup/connections-setup.tsx
+git commit -m "feat(connections-setup): add root connections-setup component"
+```
+
+---
+
+## Task 11: `index.ts` barrel export
+
+**Files:**
+- Create: `apps/mesh/src/web/components/connections-setup/index.ts`
+
+**Step 1: Write the barrel**
+
+Create `apps/mesh/src/web/components/connections-setup/index.ts`:
+
+```typescript
+export { ConnectionsSetup } from "./connections-setup";
+export type { ConnectionsSetupProps } from "./connections-setup";
+export type { ConnectionSlot } from "./use-slot-resolution";
+```
+
+**Step 2: Format and commit**
+
+```bash
+bun run fmt
+git add apps/mesh/src/web/components/connections-setup/index.ts
+git commit -m "feat(connections-setup): add barrel export"
+```
+
+---
+
+## Task 12: Verify full implementation
+
+**Step 1: Run all tests**
+
+```bash
+bun test apps/mesh/src/web/components/connections-setup/
+```
+
+Expected: PASS (slot-resolution tests).
+
+**Step 2: Type-check**
+
+```bash
+bun run check
+```
+
+Expected: no errors in the new files.
+
+**Step 3: Lint**
+
+```bash
+bun run lint
+```
+
+Fix any reported issues (kebab-case filenames, query key constants, no useEffect).
+
+**Step 4: Format**
+
+```bash
+bun run fmt
+```
+
+---
+
+## TODO (deferred)
+
+- **CONFIG phase**: For MCPs with a `configuration_state` schema (configurable MCPs), add a config form phase after AUTH. Reuse `MCPConfigurationForm` from `apps/mesh/src/web/components/details/connection/settings-tab/mcp-configuration-form.tsx`. Trigger this phase when `isActive && connection.configuration_state !== null && configFormNotYetSubmitted`.
+
+- **PICKER satisfied-connection preselection**: When the DONE state is entered from a PICKER selection of an already-active connection, `SlotDone` should show that connection without going through polling.

From 1eefc72c300e3b2fc3c3fc332106da74e40ddcf2 Mon Sep 17 00:00:00 2001
From: viktormarinho <viktormpcs@gmail.com>
Date: Mon, 23 Feb 2026 16:20:15 -0300
Subject: [PATCH 03/21] feat(connections-setup): add registry-item and
 connection-poll query keys

---
 apps/mesh/src/web/lib/query-keys.ts | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/apps/mesh/src/web/lib/query-keys.ts b/apps/mesh/src/web/lib/query-keys.ts
index 20a38913a7..a54ef3b238 100644
--- a/apps/mesh/src/web/lib/query-keys.ts
+++ b/apps/mesh/src/web/lib/query-keys.ts
@@ -49,6 +49,12 @@ export const KEYS = {
   isMCPAuthenticated: (url: string, token: string | null) =>
     ["is-mcp-authenticated", url, token] as const,
 
+  registryItem: (registryId: string, itemId: string) =>
+    ["registry-item", registryId, itemId] as const,
+
+  connectionPoll: (connectionId: string) =>
+    ["connection-poll", connectionId] as const,
+
   // MCP tools (scoped by URL and optional token)
   mcpTools: (url: string, token?: string | null) =>
     ["mcp", "tools", url, token] as const,

From 6ee122578190bf4b7f614d8818b10dc9e550d3b5 Mon Sep 17 00:00:00 2001
From: viktormarinho <viktormpcs@gmail.com>
Date: Mon, 23 Feb 2026 16:23:15 -0300
Subject: [PATCH 04/21] feat(connections-setup): add slot resolution pure logic
 with tests

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
---
 .../connections-setup/slot-resolution.test.ts | 92 +++++++++++++++++++
 .../connections-setup/slot-resolution.ts      | 31 +++++++
 2 files changed, 123 insertions(+)
 create mode 100644 apps/mesh/src/web/components/connections-setup/slot-resolution.test.ts
 create mode 100644 apps/mesh/src/web/components/connections-setup/slot-resolution.ts

diff --git a/apps/mesh/src/web/components/connections-setup/slot-resolution.test.ts b/apps/mesh/src/web/components/connections-setup/slot-resolution.test.ts
new file mode 100644
index 0000000000..c54cbebf96
--- /dev/null
+++ b/apps/mesh/src/web/components/connections-setup/slot-resolution.test.ts
@@ -0,0 +1,92 @@
+import { describe, expect, it } from "bun:test";
+import type { ConnectionEntity } from "@decocms/mesh-sdk";
+import { resolveInitialPhase } from "./slot-resolution";
+
+function makeConn(
+  overrides: Partial<ConnectionEntity> & { metadata?: Record<string, unknown> },
+): ConnectionEntity {
+  return {
+    id: "conn_test",
+    title: "Test",
+    status: "inactive",
+    connection_type: "HTTP",
+    connection_url: null,
+    connection_token: null,
+    connection_headers: null,
+    oauth_config: null,
+    configuration_state: null,
+    configuration_scopes: null,
+    description: null,
+    icon: null,
+    app_name: null,
+    app_id: null,
+    tools: null,
+    bindings: null,
+    organization_id: "org_1",
+    created_by: "user_1",
+    updated_by: "user_1",
+    created_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+    ...overrides,
+  } as unknown as ConnectionEntity;
+}
+
+describe("resolveInitialPhase", () => {
+  it("returns 'install' when no matching connections exist", () => {
+    const connections: ConnectionEntity[] = [
+      makeConn({ metadata: { registry_item_id: "other-item" } }),
+    ];
+    expect(resolveInitialPhase(connections, "my-item")).toBe("install");
+  });
+
+  it("returns 'done' when a matching active connection exists", () => {
+    const connections: ConnectionEntity[] = [
+      makeConn({
+        id: "conn_active",
+        status: "active",
+        metadata: { registry_item_id: "my-item" },
+      }),
+    ];
+    expect(resolveInitialPhase(connections, "my-item")).toBe("done");
+  });
+
+  it("returns 'picker' when matching connections exist but none are active", () => {
+    const connections: ConnectionEntity[] = [
+      makeConn({
+        id: "conn_inactive",
+        status: "inactive",
+        metadata: { registry_item_id: "my-item" },
+      }),
+    ];
+    expect(resolveInitialPhase(connections, "my-item")).toBe("picker");
+  });
+
+  it("returns 'done' for first active match when multiple exist", () => {
+    const connections: ConnectionEntity[] = [
+      makeConn({
+        status: "inactive",
+        metadata: { registry_item_id: "my-item" },
+      }),
+      makeConn({
+        id: "conn_2",
+        status: "active",
+        metadata: { registry_item_id: "my-item" },
+      }),
+    ];
+    expect(resolveInitialPhase(connections, "my-item")).toBe("done");
+  });
+});
+
+describe("findMatchingConnections", () => {
+  it("filters connections by registry_item_id", async () => {
+    const connections: ConnectionEntity[] = [
+      makeConn({ id: "conn_a", metadata: { registry_item_id: "item-1" } }),
+      makeConn({ id: "conn_b", metadata: { registry_item_id: "item-2" } }),
+      makeConn({ id: "conn_c", metadata: { registry_item_id: "item-1" } }),
+    ];
+    const { findMatchingConnections } = await import("./slot-resolution");
+    const result = findMatchingConnections(connections, "item-1");
+    expect(result).toHaveLength(2);
+    expect(result.map((c) => c.id)).toEqual(["conn_a", "conn_c"]);
+  });
+});
diff --git a/apps/mesh/src/web/components/connections-setup/slot-resolution.ts b/apps/mesh/src/web/components/connections-setup/slot-resolution.ts
new file mode 100644
index 0000000000..834148f00e
--- /dev/null
+++ b/apps/mesh/src/web/components/connections-setup/slot-resolution.ts
@@ -0,0 +1,31 @@
+import type { ConnectionEntity } from "@decocms/mesh-sdk";
+
+export type SlotPhase =
+  | "loading"
+  | "picker"
+  | "install"
+  | "polling"
+  | "auth-oauth"
+  | "auth-token"
+  | "done";
+
+export function findMatchingConnections(
+  connections: ConnectionEntity[],
+  itemId: string,
+): ConnectionEntity[] {
+  return connections.filter(
+    (c) =>
+      (c.metadata as Record<string, unknown> | null)?.registry_item_id ===
+      itemId,
+  );
+}
+
+export function resolveInitialPhase(
+  connections: ConnectionEntity[],
+  itemId: string,
+): "done" | "picker" | "install" {
+  const matches = findMatchingConnections(connections, itemId);
+  if (matches.length === 0) return "install";
+  const hasActive = matches.some((c) => c.status === "active");
+  return hasActive ? "done" : "picker";
+}

From 64e9adcca1e7051522ec566d6473b385946079ea Mon Sep 17 00:00:00 2001
From: viktormarinho <viktormpcs@gmail.com>
Date: Mon, 23 Feb 2026 16:24:44 -0300
Subject: [PATCH 05/21] fix(connections-setup): replace dynamic import with
 static import in slot-resolution tests

Removes the unnecessary `await import()` in the `findMatchingConnections`
test that caused TS errors (module-not-found and implicit-any on the map
callback). `findMatchingConnections` is now included in the top-level
static import alongside `resolveInitialPhase`.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
---
 .../components/connections-setup/slot-resolution.test.ts  | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/apps/mesh/src/web/components/connections-setup/slot-resolution.test.ts b/apps/mesh/src/web/components/connections-setup/slot-resolution.test.ts
index c54cbebf96..7cb8c8be5e 100644
--- a/apps/mesh/src/web/components/connections-setup/slot-resolution.test.ts
+++ b/apps/mesh/src/web/components/connections-setup/slot-resolution.test.ts
@@ -1,6 +1,9 @@
 import { describe, expect, it } from "bun:test";
 import type { ConnectionEntity } from "@decocms/mesh-sdk";
-import { resolveInitialPhase } from "./slot-resolution";
+import {
+  findMatchingConnections,
+  resolveInitialPhase,
+} from "./slot-resolution";
 
 function makeConn(
   overrides: Partial<ConnectionEntity> & { metadata?: Record<string, unknown> },
@@ -78,13 +81,12 @@ describe("resolveInitialPhase", () => {
 });
 
 describe("findMatchingConnections", () => {
-  it("filters connections by registry_item_id", async () => {
+  it("filters connections by registry_item_id", () => {
     const connections: ConnectionEntity[] = [
       makeConn({ id: "conn_a", metadata: { registry_item_id: "item-1" } }),
       makeConn({ id: "conn_b", metadata: { registry_item_id: "item-2" } }),
       makeConn({ id: "conn_c", metadata: { registry_item_id: "item-1" } }),
     ];
-    const { findMatchingConnections } = await import("./slot-resolution");
     const result = findMatchingConnections(connections, "item-1");
     expect(result).toHaveLength(2);
     expect(result.map((c) => c.id)).toEqual(["conn_a", "conn_c"]);

From 089de1b3a95867009371189fe96db350c4072095 Mon Sep 17 00:00:00 2001
From: viktormarinho <viktormpcs@gmail.com>
Date: Mon, 23 Feb 2026 16:34:49 -0300
Subject: [PATCH 06/21] fix(connections-setup): fix misleading test description
 in slot-resolution

---
 .../web/components/connections-setup/slot-resolution.test.ts    | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/mesh/src/web/components/connections-setup/slot-resolution.test.ts b/apps/mesh/src/web/components/connections-setup/slot-resolution.test.ts
index 7cb8c8be5e..33851cff3c 100644
--- a/apps/mesh/src/web/components/connections-setup/slot-resolution.test.ts
+++ b/apps/mesh/src/web/components/connections-setup/slot-resolution.test.ts
@@ -64,7 +64,7 @@ describe("resolveInitialPhase", () => {
     expect(resolveInitialPhase(connections, "my-item")).toBe("picker");
   });
 
-  it("returns 'done' for first active match when multiple exist", () => {
+  it("returns 'done' when at least one active match exists among multiple", () => {
     const connections: ConnectionEntity[] = [
       makeConn({
         status: "inactive",

From 6d768c6c2baaa9142615951df211c039c7366551 Mon Sep 17 00:00:00 2001
From: viktormarinho <viktormpcs@gmail.com>
Date: Mon, 23 Feb 2026 16:36:40 -0300
Subject: [PATCH 07/21] feat(connections-setup): add use-slot-resolution hook

---
 .../connections-setup/use-slot-resolution.ts  | 96 +++++++++++++++++++
 1 file changed, 96 insertions(+)
 create mode 100644 apps/mesh/src/web/components/connections-setup/use-slot-resolution.ts

diff --git a/apps/mesh/src/web/components/connections-setup/use-slot-resolution.ts b/apps/mesh/src/web/components/connections-setup/use-slot-resolution.ts
new file mode 100644
index 0000000000..71d8d10763
--- /dev/null
+++ b/apps/mesh/src/web/components/connections-setup/use-slot-resolution.ts
@@ -0,0 +1,96 @@
+import { useQuery } from "@tanstack/react-query";
+import {
+  useConnections,
+  useProjectContext,
+  type ConnectionEntity,
+} from "@decocms/mesh-sdk";
+import { useRegistryConnections } from "@/web/hooks/use-binding";
+import {
+  callRegistryTool,
+  extractItemsFromResponse,
+  findListToolName,
+} from "@/web/utils/registry-utils";
+import { KEYS } from "@/web/lib/query-keys";
+import type { RegistryItem } from "@/web/components/store/types";
+import {
+  findMatchingConnections,
+  resolveInitialPhase,
+  type SlotPhase,
+} from "./slot-resolution";
+
+export interface ConnectionSlot {
+  label: string;
+  registry: string;
+  item_id: string;
+}
+
+export interface SlotResolution {
+  initialPhase: SlotPhase;
+  registryItem: RegistryItem | null;
+  matchingConnections: ConnectionEntity[];
+  satisfiedConnection: ConnectionEntity | null;
+  isLoading: boolean;
+  registryError: string | null;
+}
+
+export function useSlotResolution(slot: ConnectionSlot): SlotResolution {
+  const { org } = useProjectContext();
+  const allConnections = useConnections();
+  const registryConnections = useRegistryConnections(allConnections);
+
+  const registryConn = registryConnections.find(
+    (c) => c.id === slot.registry || c.app_name === slot.registry,
+  );
+
+  const { data: registryItem, isLoading: isLoadingItem } = useQuery({
+    queryKey: KEYS.registryItem(slot.registry, slot.item_id),
+    queryFn: async (): Promise<RegistryItem | null> => {
+      if (!registryConn) return null;
+      const listTool = findListToolName(registryConn.tools);
+      if (!listTool) return null;
+      const result = await callRegistryTool<unknown>(
+        registryConn.id,
+        org.id,
+        listTool,
+        { where: { id: slot.item_id } },
+      );
+      const items = extractItemsFromResponse<RegistryItem>(result);
+      return items[0] ?? null;
+    },
+    enabled: Boolean(registryConn && org),
+    staleTime: 60 * 60 * 1000,
+  });
+
+  const connections = allConnections ?? [];
+  const matchingConnections = findMatchingConnections(
+    connections,
+    slot.item_id,
+  );
+  const satisfiedConnection =
+    matchingConnections.find((c) => c.status === "active") ?? null;
+
+  if (!allConnections || isLoadingItem) {
+    return {
+      initialPhase: "loading",
+      registryItem: null,
+      matchingConnections: [],
+      satisfiedConnection: null,
+      isLoading: true,
+      registryError: null,
+    };
+  }
+
+  const registryError =
+    !isLoadingItem && !registryItem ? "Registry item not found." : null;
+
+  const initialPhase = resolveInitialPhase(connections, slot.item_id);
+
+  return {
+    initialPhase,
+    registryItem: registryItem ?? null,
+    matchingConnections,
+    satisfiedConnection,
+    isLoading: false,
+    registryError,
+  };
+}

From 4f8b36bd9f85d6144793f558bc3099ec72f8db39 Mon Sep 17 00:00:00 2001
From: viktormarinho <viktormpcs@gmail.com>
Date: Mon, 23 Feb 2026 16:40:45 -0300
Subject: [PATCH 08/21] fix(connections-setup): fix dead null-check and improve
 registry error messages

---
 .../connections-setup/use-slot-resolution.ts  | 26 ++++++++++---------
 1 file changed, 14 insertions(+), 12 deletions(-)

diff --git a/apps/mesh/src/web/components/connections-setup/use-slot-resolution.ts b/apps/mesh/src/web/components/connections-setup/use-slot-resolution.ts
index 71d8d10763..fa2c0eae20 100644
--- a/apps/mesh/src/web/components/connections-setup/use-slot-resolution.ts
+++ b/apps/mesh/src/web/components/connections-setup/use-slot-resolution.ts
@@ -61,15 +61,7 @@ export function useSlotResolution(slot: ConnectionSlot): SlotResolution {
     staleTime: 60 * 60 * 1000,
   });
 
-  const connections = allConnections ?? [];
-  const matchingConnections = findMatchingConnections(
-    connections,
-    slot.item_id,
-  );
-  const satisfiedConnection =
-    matchingConnections.find((c) => c.status === "active") ?? null;
-
-  if (!allConnections || isLoadingItem) {
+  if (isLoadingItem) {
     return {
       initialPhase: "loading",
       registryItem: null,
@@ -80,10 +72,20 @@ export function useSlotResolution(slot: ConnectionSlot): SlotResolution {
     };
   }
 
-  const registryError =
-    !isLoadingItem && !registryItem ? "Registry item not found." : null;
+  const matchingConnections = findMatchingConnections(
+    allConnections,
+    slot.item_id,
+  );
+  const satisfiedConnection =
+    matchingConnections.find((c) => c.status === "active") ?? null;
+
+  const registryError = !registryConn
+    ? "Registry connection not found."
+    : !registryItem
+      ? "Registry item not found."
+      : null;
 
-  const initialPhase = resolveInitialPhase(connections, slot.item_id);
+  const initialPhase = resolveInitialPhase(allConnections, slot.item_id);
 
   return {
     initialPhase,

From 9bec0c4aad17550e1a7e77a1624868ea9d162bd0 Mon Sep 17 00:00:00 2001
From: viktormarinho <viktormpcs@gmail.com>
Date: Mon, 23 Feb 2026 16:41:54 -0300
Subject: [PATCH 09/21] feat(connections-setup): add use-connection-poller hook

---
 .../use-connection-poller.ts                  | 82 +++++++++++++++++++
 1 file changed, 82 insertions(+)
 create mode 100644 apps/mesh/src/web/components/connections-setup/use-connection-poller.ts

diff --git a/apps/mesh/src/web/components/connections-setup/use-connection-poller.ts b/apps/mesh/src/web/components/connections-setup/use-connection-poller.ts
new file mode 100644
index 0000000000..8324ca8a54
--- /dev/null
+++ b/apps/mesh/src/web/components/connections-setup/use-connection-poller.ts
@@ -0,0 +1,82 @@
+import { useRef } from "react";
+import { useQuery } from "@tanstack/react-query";
+import {
+  createMCPClient,
+  SELF_MCP_ALIAS_ID,
+  useProjectContext,
+  type ConnectionEntity,
+} from "@decocms/mesh-sdk";
+import { KEYS } from "@/web/lib/query-keys";
+
+const POLL_INTERVAL_MS = 2000;
+const POLL_TIMEOUT_MS = 15000;
+
+export interface ConnectionPollerResult {
+  connection: ConnectionEntity | null;
+  isActive: boolean;
+  isTimedOut: boolean;
+  isPolling: boolean;
+}
+
+export function useConnectionPoller(
+  connectionId: string | null,
+): ConnectionPollerResult {
+  const { org } = useProjectContext();
+  const startTimeRef = useRef<number>(0);
+
+  if (connectionId && startTimeRef.current === 0) {
+    startTimeRef.current = Date.now();
+  }
+  if (!connectionId) {
+    startTimeRef.current = 0;
+  }
+
+  const { data: connection } = useQuery({
+    queryKey: KEYS.connectionPoll(connectionId ?? ""),
+    queryFn: async (): Promise<ConnectionEntity | null> => {
+      if (!connectionId) return null;
+      const client = await createMCPClient({
+        connectionId: SELF_MCP_ALIAS_ID,
+        orgId: org.id,
+      });
+      try {
+        const result = (await client.callTool({
+          name: "COLLECTION_CONNECTIONS_GET",
+          arguments: { id: connectionId },
+        })) as { structuredContent?: ConnectionEntity } | ConnectionEntity;
+        return (
+          (result as { structuredContent?: ConnectionEntity })
+            .structuredContent ?? (result as ConnectionEntity)
+        );
+      } finally {
+        await client.close().catch(console.error);
+      }
+    },
+    refetchInterval: (query) => {
+      const conn = query.state.data;
+      if (!connectionId) return false;
+      if (conn?.status === "active" || conn?.status === "error") return false;
+      if (Date.now() - startTimeRef.current > POLL_TIMEOUT_MS) return false;
+      return POLL_INTERVAL_MS;
+    },
+    enabled: Boolean(connectionId && org),
+    staleTime: 0,
+  });
+
+  const isTimedOut =
+    Boolean(connectionId) &&
+    startTimeRef.current > 0 &&
+    Date.now() - startTimeRef.current > POLL_TIMEOUT_MS &&
+    connection?.status !== "active";
+
+  return {
+    connection: connection ?? null,
+    isActive: connection?.status === "active",
+    isTimedOut,
+    isPolling:
+      Boolean(connectionId) &&
+      connection?.status !== "active" &&
+      connection?.status !== "error" &&
+      !isTimedOut,
+  };
+}

From f903a8afcbcb2a3532b9cd6be4e2f146be63c243 Mon Sep 17 00:00:00 2001
From: viktormarinho <viktormpcs@gmail.com>
Date: Mon, 23 Feb 2026 16:44:09 -0300
Subject: [PATCH 10/21] feat(connections-setup): add slot-done component

---
 .../connections-setup/slot-done.tsx           | 31 +++++++++++++++++++
 1 file changed, 31 insertions(+)
 create mode 100644 apps/mesh/src/web/components/connections-setup/slot-done.tsx

diff --git a/apps/mesh/src/web/components/connections-setup/slot-done.tsx b/apps/mesh/src/web/components/connections-setup/slot-done.tsx
new file mode 100644
index 0000000000..1fbceecd8c
--- /dev/null
+++ b/apps/mesh/src/web/components/connections-setup/slot-done.tsx
@@ -0,0 +1,31 @@
+import { CheckCircle, ChevronDown } from "lucide-react";
+import { Button } from "@deco/ui/components/button.tsx";
+import type { ConnectionEntity } from "@decocms/mesh-sdk";
+
+interface SlotDoneProps {
+  label: string;
+  connection: ConnectionEntity;
+  onReset: () => void;
+}
+
+export function SlotDone({ label, connection, onReset }: SlotDoneProps) {
+  return (
+    <div className="flex items-center gap-3 rounded-lg border border-success/30 bg-success/5 px-4 py-3">
+      <CheckCircle className="size-4 shrink-0 text-success" />
+      <div className="flex-1 min-w-0">
+        <p className="text-sm font-medium text-foreground">{label}</p>
+        <p className="text-xs text-muted-foreground truncate">
+          {connection.title}
+        </p>
+      </div>
+      <Button
+        variant="ghost"
+        size="sm"
+        onClick={onReset}
+        className="gap-1 shrink-0"
+      >
+        Change <ChevronDown className="size-3" />
+      </Button>
+    </div>
+  );
+}

From c992085813efa43a7f7ad6da05f77e84cfabfdb1 Mon Sep 17 00:00:00 2001
From: viktormarinho <viktormpcs@gmail.com>
Date: Mon, 23 Feb 2026 16:44:43 -0300
Subject: [PATCH 11/21] feat(connections-setup): add slot-install-form
 component

---
 .../connections-setup/slot-install-form.tsx   | 88 +++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100644 apps/mesh/src/web/components/connections-setup/slot-install-form.tsx

diff --git a/apps/mesh/src/web/components/connections-setup/slot-install-form.tsx b/apps/mesh/src/web/components/connections-setup/slot-install-form.tsx
new file mode 100644
index 0000000000..25360bc194
--- /dev/null
+++ b/apps/mesh/src/web/components/connections-setup/slot-install-form.tsx
@@ -0,0 +1,88 @@
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { z } from "zod";
+import {
+  useConnectionActions,
+  useProjectContext,
+  type ConnectionEntity,
+} from "@decocms/mesh-sdk";
+import { authClient } from "@/web/lib/auth-client";
+import { extractConnectionData } from "@/web/utils/extract-connection-data";
+import { Button } from "@deco/ui/components/button.tsx";
+import {
+  Form,
+  FormControl,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from "@deco/ui/components/form.tsx";
+import { Input } from "@deco/ui/components/input.tsx";
+import type { RegistryItem } from "@/web/components/store/types";
+
+const installSchema = z.object({
+  title: z.string().min(1, "Name is required"),
+});
+
+type InstallFormData = z.infer<typeof installSchema>;
+
+interface SlotInstallFormProps {
+  registryItem: RegistryItem;
+  onInstalled: (connectionId: string) => void;
+}
+
+export function SlotInstallForm({
+  registryItem,
+  onInstalled,
+}: SlotInstallFormProps) {
+  const { org } = useProjectContext();
+  const { data: session } = authClient.useSession();
+  const actions = useConnectionActions();
+
+  const connectionData = extractConnectionData(
+    registryItem,
+    org.id,
+    session?.user?.id ?? "system",
+  );
+
+  const form = useForm<InstallFormData>({
+    resolver: zodResolver(installSchema),
+    defaultValues: { title: connectionData.title ?? "" },
+  });
+
+  const handleSubmit = async (data: InstallFormData) => {
+    const payload: ConnectionEntity = {
+      ...(connectionData as ConnectionEntity),
+      title: data.title,
+    };
+    await actions.create.mutateAsync(payload);
+    onInstalled(connectionData.id);
+  };
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(handleSubmit)} className="space-y-3">
+        <FormField
+          control={form.control}
+          name="title"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Connection name</FormLabel>
+              <FormControl>
+                <Input placeholder="e.g. OpenAI" {...field} />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <Button
+          type="submit"
+          disabled={actions.create.isPending}
+          className="w-full"
+        >
+          {actions.create.isPending ? "Installing..." : "Install"}
+        </Button>
+      </form>
+    </Form>
+  );
+}

From 722bcc203257d93bbfe8493a4530baaa570bebd6 Mon Sep 17 00:00:00 2001
From: viktormarinho <viktormpcs@gmail.com>
Date: Mon, 23 Feb 2026 16:45:18 -0300
Subject: [PATCH 12/21] feat(connections-setup): add slot-auth-oauth component

---
 .../connections-setup/slot-auth-oauth.tsx     | 90 +++++++++++++++++++
 1 file changed, 90 insertions(+)
 create mode 100644 apps/mesh/src/web/components/connections-setup/slot-auth-oauth.tsx

diff --git a/apps/mesh/src/web/components/connections-setup/slot-auth-oauth.tsx b/apps/mesh/src/web/components/connections-setup/slot-auth-oauth.tsx
new file mode 100644
index 0000000000..b7137e2330
--- /dev/null
+++ b/apps/mesh/src/web/components/connections-setup/slot-auth-oauth.tsx
@@ -0,0 +1,90 @@
+import { useState } from "react";
+import { toast } from "sonner";
+import { authenticateMcp, useConnectionActions } from "@decocms/mesh-sdk";
+import { useQueryClient } from "@tanstack/react-query";
+import { KEYS } from "@/web/lib/query-keys";
+import { Button } from "@deco/ui/components/button.tsx";
+
+interface SlotAuthOAuthProps {
+  connectionId: string;
+  providerName: string;
+  onAuthed: () => void;
+}
+
+export function SlotAuthOAuth({
+  connectionId,
+  providerName,
+  onAuthed,
+}: SlotAuthOAuthProps) {
+  const [isPending, setIsPending] = useState(false);
+  const actions = useConnectionActions();
+  const queryClient = useQueryClient();
+  const mcpProxyUrl = new URL(`/mcp/${connectionId}`, window.location.origin);
+
+  const handleAuthorize = async () => {
+    setIsPending(true);
+    try {
+      const { token, tokenInfo, error } = await authenticateMcp({
+        connectionId,
+      });
+
+      if (error || !token) {
+        toast.error(`Authorization failed: ${error ?? "Unknown error"}`);
+        return;
+      }
+
+      if (tokenInfo) {
+        const response = await fetch(
+          `/api/connections/${connectionId}/oauth-token`,
+          {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            credentials: "include",
+            body: JSON.stringify({
+              accessToken: tokenInfo.accessToken,
+              refreshToken: tokenInfo.refreshToken,
+              expiresIn: tokenInfo.expiresIn,
+              scope: tokenInfo.scope,
+              clientId: tokenInfo.clientId,
+              clientSecret: tokenInfo.clientSecret,
+              tokenEndpoint: tokenInfo.tokenEndpoint,
+            }),
+          },
+        );
+        if (!response.ok) {
+          await actions.update.mutateAsync({
+            id: connectionId,
+            data: { connection_token: token },
+          });
+        } else {
+          // Trigger tool re-discovery
+          await actions.update.mutateAsync({ id: connectionId, data: {} });
+        }
+      } else {
+        await actions.update.mutateAsync({
+          id: connectionId,
+          data: { connection_token: token },
+        });
+      }
+
+      await queryClient.invalidateQueries({
+        queryKey: KEYS.isMCPAuthenticated(mcpProxyUrl.href, null),
+      });
+
+      onAuthed();
+    } finally {
+      setIsPending(false);
+    }
+  };
+
+  return (
+    <div className="space-y-3">
+      <p className="text-sm text-muted-foreground">
+        Authorize Mesh to access {providerName} on your behalf.
+      </p>
+      <Button onClick={handleAuthorize} disabled={isPending} className="w-full">
+        {isPending ? "Authorizing..." : `Authorize with ${providerName}`}
+      </Button>
+    </div>
+  );
+}

From d94b896bd64228ea18eec5542c6443342e7fc3d8 Mon Sep 17 00:00:00 2001
From: viktormarinho <viktormpcs@gmail.com>
Date: Mon, 23 Feb 2026 16:45:52 -0300
Subject: [PATCH 13/21] feat(connections-setup): add slot-auth-token component

---
 .../connections-setup/slot-auth-token.tsx     | 71 +++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 apps/mesh/src/web/components/connections-setup/slot-auth-token.tsx

diff --git a/apps/mesh/src/web/components/connections-setup/slot-auth-token.tsx b/apps/mesh/src/web/components/connections-setup/slot-auth-token.tsx
new file mode 100644
index 0000000000..b9e63baae0
--- /dev/null
+++ b/apps/mesh/src/web/components/connections-setup/slot-auth-token.tsx
@@ -0,0 +1,71 @@
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { z } from "zod";
+import { useConnectionActions } from "@decocms/mesh-sdk";
+import { Button } from "@deco/ui/components/button.tsx";
+import {
+  Form,
+  FormControl,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from "@deco/ui/components/form.tsx";
+import { Input } from "@deco/ui/components/input.tsx";
+
+const tokenSchema = z.object({
+  token: z.string().min(1, "Token is required"),
+});
+
+type TokenFormData = z.infer<typeof tokenSchema>;
+
+interface SlotAuthTokenProps {
+  connectionId: string;
+  onAuthed: () => void;
+}
+
+export function SlotAuthToken({ connectionId, onAuthed }: SlotAuthTokenProps) {
+  const actions = useConnectionActions();
+
+  const form = useForm<TokenFormData>({
+    resolver: zodResolver(tokenSchema),
+    defaultValues: { token: "" },
+  });
+
+  const handleSubmit = async (data: TokenFormData) => {
+    await actions.update.mutateAsync({
+      id: connectionId,
+      data: { connection_token: data.token },
+    });
+    // Trigger tool re-discovery
+    await actions.update.mutateAsync({ id: connectionId, data: {} });
+    onAuthed();
+  };
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(handleSubmit)} className="space-y-3">
+        <FormField
+          control={form.control}
+          name="token"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>API Token</FormLabel>
+              <FormControl>
+                <Input type="password" placeholder="sk-..." {...field} />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <Button
+          type="submit"
+          disabled={actions.update.isPending}
+          className="w-full"
+        >
+          {actions.update.isPending ? "Saving..." : "Save token"}
+        </Button>
+      </form>
+    </Form>
+  );
+}

From cb6a7be2df4b00e68b1da99afd517745a1117999 Mon Sep 17 00:00:00 2001
From: viktormarinho <viktormpcs@gmail.com>
Date: Mon, 23 Feb 2026 16:52:45 -0300
Subject: [PATCH 14/21] fix(connections-setup): fix poller response shape,
 install ID, oauth error handling, icon source

---
 .../connections-setup/slot-auth-oauth.tsx     | 51 +++++++++++--------
 .../connections-setup/slot-done.tsx           |  2 +-
 .../connections-setup/slot-install-form.tsx   |  4 +-
 .../use-connection-poller.ts                  |  7 +--
 4 files changed, 35 insertions(+), 29 deletions(-)

diff --git a/apps/mesh/src/web/components/connections-setup/slot-auth-oauth.tsx b/apps/mesh/src/web/components/connections-setup/slot-auth-oauth.tsx
index b7137e2330..303bab4844 100644
--- a/apps/mesh/src/web/components/connections-setup/slot-auth-oauth.tsx
+++ b/apps/mesh/src/web/components/connections-setup/slot-auth-oauth.tsx
@@ -34,31 +34,39 @@ export function SlotAuthOAuth({
       }
 
       if (tokenInfo) {
-        const response = await fetch(
-          `/api/connections/${connectionId}/oauth-token`,
-          {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            credentials: "include",
-            body: JSON.stringify({
-              accessToken: tokenInfo.accessToken,
-              refreshToken: tokenInfo.refreshToken,
-              expiresIn: tokenInfo.expiresIn,
-              scope: tokenInfo.scope,
-              clientId: tokenInfo.clientId,
-              clientSecret: tokenInfo.clientSecret,
-              tokenEndpoint: tokenInfo.tokenEndpoint,
-            }),
-          },
-        );
-        if (!response.ok) {
+        try {
+          const response = await fetch(
+            `/api/connections/${connectionId}/oauth-token`,
+            {
+              method: "POST",
+              headers: { "Content-Type": "application/json" },
+              credentials: "include",
+              body: JSON.stringify({
+                accessToken: tokenInfo.accessToken,
+                refreshToken: tokenInfo.refreshToken,
+                expiresIn: tokenInfo.expiresIn,
+                scope: tokenInfo.scope,
+                clientId: tokenInfo.clientId,
+                clientSecret: tokenInfo.clientSecret,
+                tokenEndpoint: tokenInfo.tokenEndpoint,
+              }),
+            },
+          );
+          if (!response.ok) {
+            await actions.update.mutateAsync({
+              id: connectionId,
+              data: { connection_token: token },
+            });
+          } else {
+            // Trigger tool re-discovery
+            await actions.update.mutateAsync({ id: connectionId, data: {} });
+          }
+        } catch (err) {
+          console.error("Error saving OAuth token:", err);
           await actions.update.mutateAsync({
             id: connectionId,
             data: { connection_token: token },
           });
-        } else {
-          // Trigger tool re-discovery
-          await actions.update.mutateAsync({ id: connectionId, data: {} });
         }
       } else {
         await actions.update.mutateAsync({
@@ -71,6 +79,7 @@ export function SlotAuthOAuth({
         queryKey: KEYS.isMCPAuthenticated(mcpProxyUrl.href, null),
       });
 
+      toast.success("Authorization successful");
       onAuthed();
     } finally {
       setIsPending(false);
diff --git a/apps/mesh/src/web/components/connections-setup/slot-done.tsx b/apps/mesh/src/web/components/connections-setup/slot-done.tsx
index 1fbceecd8c..333e81f9d7 100644
--- a/apps/mesh/src/web/components/connections-setup/slot-done.tsx
+++ b/apps/mesh/src/web/components/connections-setup/slot-done.tsx
@@ -1,4 +1,4 @@
-import { CheckCircle, ChevronDown } from "lucide-react";
+import { CheckCircle, ChevronDown } from "@untitledui/icons";
 import { Button } from "@deco/ui/components/button.tsx";
 import type { ConnectionEntity } from "@decocms/mesh-sdk";
 
diff --git a/apps/mesh/src/web/components/connections-setup/slot-install-form.tsx b/apps/mesh/src/web/components/connections-setup/slot-install-form.tsx
index 25360bc194..deac7ab8a8 100644
--- a/apps/mesh/src/web/components/connections-setup/slot-install-form.tsx
+++ b/apps/mesh/src/web/components/connections-setup/slot-install-form.tsx
@@ -55,8 +55,8 @@ export function SlotInstallForm({
       ...(connectionData as ConnectionEntity),
       title: data.title,
     };
-    await actions.create.mutateAsync(payload);
-    onInstalled(connectionData.id);
+    const created = await actions.create.mutateAsync(payload);
+    onInstalled(created.id);
   };
 
   return (
diff --git a/apps/mesh/src/web/components/connections-setup/use-connection-poller.ts b/apps/mesh/src/web/components/connections-setup/use-connection-poller.ts
index 8324ca8a54..b98b7e002d 100644
--- a/apps/mesh/src/web/components/connections-setup/use-connection-poller.ts
+++ b/apps/mesh/src/web/components/connections-setup/use-connection-poller.ts
@@ -43,11 +43,8 @@ export function useConnectionPoller(
         const result = (await client.callTool({
           name: "COLLECTION_CONNECTIONS_GET",
           arguments: { id: connectionId },
-        })) as { structuredContent?: ConnectionEntity } | ConnectionEntity;
-        return (
-          (result as { structuredContent?: ConnectionEntity })
-            .structuredContent ?? (result as ConnectionEntity)
-        );
+        })) as { structuredContent?: { item: ConnectionEntity | null } };
+        return result.structuredContent?.item ?? null;
       } finally {
         await client.close().catch(console.error);
       }

From 023147f7ba995e8b7e33bc2ec39d29daac650b82 Mon Sep 17 00:00:00 2001
From: viktormarinho <viktormpcs@gmail.com>
Date: Mon, 23 Feb 2026 16:55:02 -0300
Subject: [PATCH 15/21] feat(connections-setup): add slot-card state machine
 component

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
---
 .../connections-setup/slot-card.tsx           | 190 ++++++++++++++++++
 1 file changed, 190 insertions(+)
 create mode 100644 apps/mesh/src/web/components/connections-setup/slot-card.tsx

diff --git a/apps/mesh/src/web/components/connections-setup/slot-card.tsx b/apps/mesh/src/web/components/connections-setup/slot-card.tsx
new file mode 100644
index 0000000000..d098182b59
--- /dev/null
+++ b/apps/mesh/src/web/components/connections-setup/slot-card.tsx
@@ -0,0 +1,190 @@
+import { useState } from "react";
+import { AlertCircle, Loader2 } from "lucide-react";
+import {
+  isConnectionAuthenticated,
+  type ConnectionEntity,
+} from "@decocms/mesh-sdk";
+import { Button } from "@deco/ui/components/button.tsx";
+import { useSlotResolution, type ConnectionSlot } from "./use-slot-resolution";
+import { useConnectionPoller } from "./use-connection-poller";
+import { type SlotPhase } from "./slot-resolution";
+import { SlotDone } from "./slot-done";
+import { SlotInstallForm } from "./slot-install-form";
+import { SlotAuthOAuth } from "./slot-auth-oauth";
+import { SlotAuthToken } from "./slot-auth-token";
+
+interface SlotCardProps {
+  slot: ConnectionSlot;
+  onComplete: (connectionId: string) => void;
+}
+
+export function SlotCard({ slot, onComplete }: SlotCardProps) {
+  const resolution = useSlotResolution(slot);
+  const [phase, setPhase] = useState<SlotPhase | null>(null);
+  const [pollingConnectionId, setPollingConnectionId] = useState<string | null>(
+    null,
+  );
+  const [selectedConnection, setSelectedConnection] =
+    useState<ConnectionEntity | null>(null);
+
+  const poller = useConnectionPoller(pollingConnectionId);
+
+  // Derive effective phase: explicit override takes priority, else from resolution
+  const effectivePhase: SlotPhase = phase ?? resolution.initialPhase;
+
+  // React to poller becoming active
+  if (pollingConnectionId && poller.isActive && poller.connection) {
+    setPollingConnectionId(null);
+    setSelectedConnection(poller.connection);
+    setPhase("done");
+    onComplete(poller.connection.id);
+  }
+
+  // React to poller timeout/error — determine auth type needed
+  if (
+    pollingConnectionId &&
+    (poller.isTimedOut || poller.connection?.status === "error")
+  ) {
+    const connectionId = pollingConnectionId;
+    setPollingConnectionId(null);
+
+    // Async: check auth status to determine next phase
+    const url = new URL(`/mcp/${connectionId}`, window.location.origin).href;
+    isConnectionAuthenticated({ url, token: null }).then((authStatus) => {
+      if (authStatus.supportsOAuth) {
+        setPhase("auth-oauth");
+      } else {
+        setPhase("auth-token");
+      }
+    });
+  }
+
+  const handleInstalled = (connectionId: string) => {
+    setPollingConnectionId(connectionId);
+    setPhase("polling");
+  };
+
+  const handleAuthed = () => {
+    const id = pollingConnectionId ?? selectedConnection?.id ?? null;
+    if (id) {
+      setPollingConnectionId(id);
+      setPhase("polling");
+    }
+  };
+
+  const handleReset = () => {
+    const hasExisting = resolution.matchingConnections.length > 0;
+    setPhase(hasExisting ? "picker" : "install");
+    setSelectedConnection(null);
+    setPollingConnectionId(null);
+    onComplete("");
+  };
+
+  const resolvedConnection =
+    selectedConnection ?? resolution.satisfiedConnection ?? null;
+
+  if (effectivePhase === "loading") {
+    return (
+      <div className="flex items-center gap-3 rounded-lg border bg-muted/30 px-4 py-3">
+        <Loader2 className="size-4 animate-spin text-muted-foreground" />
+        <p className="text-sm text-muted-foreground">{slot.label}</p>
+      </div>
+    );
+  }
+
+  if (resolution.registryError) {
+    return (
+      <div className="flex items-center gap-3 rounded-lg border border-destructive/30 bg-destructive/5 px-4 py-3">
+        <AlertCircle className="size-4 shrink-0 text-destructive" />
+        <div>
+          <p className="text-sm font-medium">{slot.label}</p>
+          <p className="text-xs text-muted-foreground">
+            {resolution.registryError}
+          </p>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="rounded-lg border bg-card px-4 py-4 space-y-3">
+      <p className="text-sm font-medium text-foreground">{slot.label}</p>
+
+      {effectivePhase === "done" && resolvedConnection && (
+        <SlotDone
+          label={slot.label}
+          connection={resolvedConnection}
+          onReset={handleReset}
+        />
+      )}
+
+      {effectivePhase === "picker" && (
+        <div className="space-y-2">
+          <p className="text-xs text-muted-foreground">Already installed:</p>
+          <div className="space-y-1">
+            {resolution.matchingConnections.map((conn) => (
+              <button
+                key={conn.id}
+                type="button"
+                onClick={() => {
+                  if (conn.status === "active") {
+                    setSelectedConnection(conn);
+                    setPhase("done");
+                    onComplete(conn.id);
+                  } else {
+                    setSelectedConnection(conn);
+                    setPollingConnectionId(conn.id);
+                    setPhase("polling");
+                  }
+                }}
+                className="w-full flex items-center justify-between rounded border px-3 py-2 text-sm hover:bg-accent transition-colors"
+              >
+                <span>{conn.title}</span>
+                <span className="text-xs text-muted-foreground">
+                  {conn.status}
+                </span>
+              </button>
+            ))}
+          </div>
+          <Button
+            variant="outline"
+            size="sm"
+            className="w-full"
+            onClick={() => setPhase("install")}
+          >
+            Install fresh
+          </Button>
+        </div>
+      )}
+
+      {effectivePhase === "install" && resolution.registryItem && (
+        <SlotInstallForm
+          registryItem={resolution.registryItem}
+          onInstalled={handleInstalled}
+        />
+      )}
+
+      {effectivePhase === "polling" && (
+        <div className="flex items-center gap-2 text-sm text-muted-foreground">
+          <Loader2 className="size-4 animate-spin" />
+          Connecting...
+        </div>
+      )}
+
+      {effectivePhase === "auth-oauth" && selectedConnection && (
+        <SlotAuthOAuth
+          connectionId={selectedConnection.id}
+          providerName={resolution.registryItem?.title ?? slot.label}
+          onAuthed={handleAuthed}
+        />
+      )}
+
+      {effectivePhase === "auth-token" && selectedConnection && (
+        <SlotAuthToken
+          connectionId={selectedConnection.id}
+          onAuthed={handleAuthed}
+        />
+      )}
+    </div>
+  );
+}

From 81c3f530e5f45e9d2166b2ea4260a1b6e2485c0d Mon Sep 17 00:00:00 2001
From: viktormarinho <viktormpcs@gmail.com>
Date: Mon, 23 Feb 2026 17:31:28 -0300
Subject: [PATCH 16/21] feat(connections-setup): fix auth phase bug, add root
 component and barrel export

---
 .../connections-setup/connections-setup.tsx   | 41 +++++++++++++++++++
 .../web/components/connections-setup/index.ts |  3 ++
 .../connections-setup/slot-card.tsx           | 22 ++++++----
 3 files changed, 58 insertions(+), 8 deletions(-)
 create mode 100644 apps/mesh/src/web/components/connections-setup/connections-setup.tsx
 create mode 100644 apps/mesh/src/web/components/connections-setup/index.ts

diff --git a/apps/mesh/src/web/components/connections-setup/connections-setup.tsx b/apps/mesh/src/web/components/connections-setup/connections-setup.tsx
new file mode 100644
index 0000000000..0282b80f45
--- /dev/null
+++ b/apps/mesh/src/web/components/connections-setup/connections-setup.tsx
@@ -0,0 +1,41 @@
+import { useState } from "react";
+import { SlotCard } from "./slot-card";
+import type { ConnectionSlot } from "./use-slot-resolution";
+
+export interface ConnectionsSetupProps {
+  slots: Record<string, ConnectionSlot>;
+  onComplete: (connections: Record<string, string>) => void;
+}
+
+export function ConnectionsSetup({ slots, onComplete }: ConnectionsSetupProps) {
+  const [completed, setCompleted] = useState<Record<string, string>>({});
+
+  const handleSlotComplete = (slotId: string, connectionId: string) => {
+    const next = { ...completed };
+    if (connectionId === "") {
+      delete next[slotId];
+    } else {
+      next[slotId] = connectionId;
+    }
+    setCompleted(next);
+
+    const allDone = Object.keys(slots).every((id) => next[id]);
+    if (allDone) {
+      onComplete(next);
+    }
+  };
+
+  return (
+    <div className="space-y-3">
+      {Object.entries(slots).map(([slotId, slot]) => (
+        <SlotCard
+          key={slotId}
+          slot={slot}
+          onComplete={(connectionId) =>
+            handleSlotComplete(slotId, connectionId)
+          }
+        />
+      ))}
+    </div>
+  );
+}
diff --git a/apps/mesh/src/web/components/connections-setup/index.ts b/apps/mesh/src/web/components/connections-setup/index.ts
new file mode 100644
index 0000000000..52e411d0bd
--- /dev/null
+++ b/apps/mesh/src/web/components/connections-setup/index.ts
@@ -0,0 +1,3 @@
+export { ConnectionsSetup } from "./connections-setup";
+export type { ConnectionsSetupProps } from "./connections-setup";
+export type { ConnectionSlot } from "./use-slot-resolution";
diff --git a/apps/mesh/src/web/components/connections-setup/slot-card.tsx b/apps/mesh/src/web/components/connections-setup/slot-card.tsx
index d098182b59..fa03f4d301 100644
--- a/apps/mesh/src/web/components/connections-setup/slot-card.tsx
+++ b/apps/mesh/src/web/components/connections-setup/slot-card.tsx
@@ -46,17 +46,21 @@ export function SlotCard({ slot, onComplete }: SlotCardProps) {
     (poller.isTimedOut || poller.connection?.status === "error")
   ) {
     const connectionId = pollingConnectionId;
+    // Capture the fetched connection entity so auth phases can use its id
+    if (poller.connection) setSelectedConnection(poller.connection);
     setPollingConnectionId(null);
 
     // Async: check auth status to determine next phase
     const url = new URL(`/mcp/${connectionId}`, window.location.origin).href;
-    isConnectionAuthenticated({ url, token: null }).then((authStatus) => {
-      if (authStatus.supportsOAuth) {
-        setPhase("auth-oauth");
-      } else {
-        setPhase("auth-token");
-      }
-    });
+    isConnectionAuthenticated({ url, token: null })
+      .then((authStatus) => {
+        if (authStatus.supportsOAuth) {
+          setPhase("auth-oauth");
+        } else {
+          setPhase("auth-token");
+        }
+      })
+      .catch(() => setPhase("auth-token"));
   }
 
   const handleInstalled = (connectionId: string) => {
@@ -108,7 +112,9 @@ export function SlotCard({ slot, onComplete }: SlotCardProps) {
 
   return (
     <div className="rounded-lg border bg-card px-4 py-4 space-y-3">
-      <p className="text-sm font-medium text-foreground">{slot.label}</p>
+      {effectivePhase !== "done" && (
+        <p className="text-sm font-medium text-foreground">{slot.label}</p>
+      )}
 
       {effectivePhase === "done" && resolvedConnection && (
         <SlotDone

From 5b4eec23cdaf805c73456090df67b39cc5bd0bc7 Mon Sep 17 00:00:00 2001
From: viktormarinho <viktormpcs@gmail.com>
Date: Tue, 24 Feb 2026 12:07:06 -0300
Subject: [PATCH 17/21] fix(connections-setup): fix render-phase side effects
 and stuck auth state

- Move isConnectionAuthenticated out of render body into useQuery (authCheckId
  state triggers the query after poller timeout/error)
- Add completedIdRef guard so onComplete fires exactly once per connection
  even under concurrent-mode re-renders
- Fix stuck UI when poller.connection is null on timeout: auth phases now
  fall back to authCheckId for the connection ID
- Use functional setCompleted updater in ConnectionsSetup to avoid stale
  closure on rapid slot completions; move allDone/onComplete check to render
  with a wasAllDoneRef guard
- Reset startTimeRef in useConnectionPoller whenever connectionId changes
  (not only when it was previously 0) to prevent a new connection inheriting
  a stale start time

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
---
 .../connections-setup/connections-setup.tsx   | 35 +++++----
 .../connections-setup/slot-card.tsx           | 72 ++++++++++++-------
 .../use-connection-poller.ts                  |  9 ++-
 3 files changed, 74 insertions(+), 42 deletions(-)

diff --git a/apps/mesh/src/web/components/connections-setup/connections-setup.tsx b/apps/mesh/src/web/components/connections-setup/connections-setup.tsx
index 0282b80f45..ea9166eae4 100644
--- a/apps/mesh/src/web/components/connections-setup/connections-setup.tsx
+++ b/apps/mesh/src/web/components/connections-setup/connections-setup.tsx
@@ -1,4 +1,4 @@
-import { useState } from "react";
+import { useState, useRef } from "react";
 import { SlotCard } from "./slot-card";
 import type { ConnectionSlot } from "./use-slot-resolution";
 
@@ -9,22 +9,31 @@ export interface ConnectionsSetupProps {
 
 export function ConnectionsSetup({ slots, onComplete }: ConnectionsSetupProps) {
   const [completed, setCompleted] = useState<Record<string, string>>({});
+  const wasAllDoneRef = useRef(false);
 
   const handleSlotComplete = (slotId: string, connectionId: string) => {
-    const next = { ...completed };
-    if (connectionId === "") {
-      delete next[slotId];
-    } else {
-      next[slotId] = connectionId;
-    }
-    setCompleted(next);
-
-    const allDone = Object.keys(slots).every((id) => next[id]);
-    if (allDone) {
-      onComplete(next);
-    }
+    setCompleted((prev) => {
+      const next = { ...prev };
+      if (connectionId === "") {
+        delete next[slotId];
+      } else {
+        next[slotId] = connectionId;
+      }
+      return next;
+    });
   };
 
+  const allSlotIds = Object.keys(slots);
+  const allDone =
+    allSlotIds.length > 0 && allSlotIds.every((id) => completed[id]);
+
+  if (allDone && !wasAllDoneRef.current) {
+    wasAllDoneRef.current = true;
+    onComplete(completed);
+  } else if (!allDone) {
+    wasAllDoneRef.current = false;
+  }
+
   return (
     <div className="space-y-3">
       {Object.entries(slots).map(([slotId, slot]) => (
diff --git a/apps/mesh/src/web/components/connections-setup/slot-card.tsx b/apps/mesh/src/web/components/connections-setup/slot-card.tsx
index fa03f4d301..7fe43e26a8 100644
--- a/apps/mesh/src/web/components/connections-setup/slot-card.tsx
+++ b/apps/mesh/src/web/components/connections-setup/slot-card.tsx
@@ -1,10 +1,12 @@
-import { useState } from "react";
+import { useState, useRef } from "react";
+import { useQuery } from "@tanstack/react-query";
 import { AlertCircle, Loader2 } from "lucide-react";
 import {
   isConnectionAuthenticated,
   type ConnectionEntity,
 } from "@decocms/mesh-sdk";
 import { Button } from "@deco/ui/components/button.tsx";
+import { KEYS } from "@/web/lib/query-keys";
 import { useSlotResolution, type ConnectionSlot } from "./use-slot-resolution";
 import { useConnectionPoller } from "./use-connection-poller";
 import { type SlotPhase } from "./slot-resolution";
@@ -26,41 +28,56 @@ export function SlotCard({ slot, onComplete }: SlotCardProps) {
   );
   const [selectedConnection, setSelectedConnection] =
     useState<ConnectionEntity | null>(null);
+  // Tracks which connection needs an auth check after polling times out/errors
+  const [authCheckId, setAuthCheckId] = useState<string | null>(null);
+  // Prevents onComplete from firing more than once per unique connection
+  const completedIdRef = useRef<string | null>(null);
 
   const poller = useConnectionPoller(pollingConnectionId);
 
+  const authUrl = authCheckId
+    ? new URL(`/mcp/${authCheckId}`, window.location.origin).href
+    : "";
+
+  const { data: authStatus } = useQuery({
+    queryKey: KEYS.isMCPAuthenticated(authUrl, null),
+    queryFn: () => isConnectionAuthenticated({ url: authUrl, token: null }),
+    enabled: Boolean(authCheckId),
+    staleTime: Infinity,
+  });
+
   // Derive effective phase: explicit override takes priority, else from resolution
   const effectivePhase: SlotPhase = phase ?? resolution.initialPhase;
 
   // React to poller becoming active
   if (pollingConnectionId && poller.isActive && poller.connection) {
-    setPollingConnectionId(null);
-    setSelectedConnection(poller.connection);
-    setPhase("done");
-    onComplete(poller.connection.id);
+    if (completedIdRef.current !== poller.connection.id) {
+      completedIdRef.current = poller.connection.id;
+      setPollingConnectionId(null);
+      setSelectedConnection(poller.connection);
+      setPhase("done");
+      onComplete(poller.connection.id);
+    }
   }
 
-  // React to poller timeout/error — determine auth type needed
+  // React to poller timeout/error — queue an auth check instead of firing async in render
   if (
     pollingConnectionId &&
     (poller.isTimedOut || poller.connection?.status === "error")
   ) {
-    const connectionId = pollingConnectionId;
-    // Capture the fetched connection entity so auth phases can use its id
     if (poller.connection) setSelectedConnection(poller.connection);
+    setAuthCheckId(pollingConnectionId);
     setPollingConnectionId(null);
+  }
 
-    // Async: check auth status to determine next phase
-    const url = new URL(`/mcp/${connectionId}`, window.location.origin).href;
-    isConnectionAuthenticated({ url, token: null })
-      .then((authStatus) => {
-        if (authStatus.supportsOAuth) {
-          setPhase("auth-oauth");
-        } else {
-          setPhase("auth-token");
-        }
-      })
-      .catch(() => setPhase("auth-token"));
+  // React to auth check result — set the appropriate auth phase
+  if (
+    authCheckId &&
+    authStatus &&
+    phase !== "auth-oauth" &&
+    phase !== "auth-token"
+  ) {
+    setPhase(authStatus.supportsOAuth ? "auth-oauth" : "auth-token");
   }
 
   const handleInstalled = (connectionId: string) => {
@@ -69,8 +86,10 @@ export function SlotCard({ slot, onComplete }: SlotCardProps) {
   };
 
   const handleAuthed = () => {
-    const id = pollingConnectionId ?? selectedConnection?.id ?? null;
+    const id =
+      pollingConnectionId ?? selectedConnection?.id ?? authCheckId ?? null;
     if (id) {
+      setAuthCheckId(null);
       setPollingConnectionId(id);
       setPhase("polling");
     }
@@ -81,12 +100,17 @@ export function SlotCard({ slot, onComplete }: SlotCardProps) {
     setPhase(hasExisting ? "picker" : "install");
     setSelectedConnection(null);
     setPollingConnectionId(null);
+    setAuthCheckId(null);
+    completedIdRef.current = null;
     onComplete("");
   };
 
   const resolvedConnection =
     selectedConnection ?? resolution.satisfiedConnection ?? null;
 
+  // Fallback to authCheckId when connection entity wasn't fetched before timeout
+  const authConnectionId = selectedConnection?.id ?? authCheckId;
+
   if (effectivePhase === "loading") {
     return (
       <div className="flex items-center gap-3 rounded-lg border bg-muted/30 px-4 py-3">
@@ -177,17 +201,17 @@ export function SlotCard({ slot, onComplete }: SlotCardProps) {
         </div>
       )}
 
-      {effectivePhase === "auth-oauth" && selectedConnection && (
+      {effectivePhase === "auth-oauth" && authConnectionId && (
         <SlotAuthOAuth
-          connectionId={selectedConnection.id}
+          connectionId={authConnectionId}
           providerName={resolution.registryItem?.title ?? slot.label}
           onAuthed={handleAuthed}
         />
       )}
 
-      {effectivePhase === "auth-token" && selectedConnection && (
+      {effectivePhase === "auth-token" && authConnectionId && (
         <SlotAuthToken
-          connectionId={selectedConnection.id}
+          connectionId={authConnectionId}
           onAuthed={handleAuthed}
         />
       )}
diff --git a/apps/mesh/src/web/components/connections-setup/use-connection-poller.ts b/apps/mesh/src/web/components/connections-setup/use-connection-poller.ts
index b98b7e002d..cc06d1f6c6 100644
--- a/apps/mesh/src/web/components/connections-setup/use-connection-poller.ts
+++ b/apps/mesh/src/web/components/connections-setup/use-connection-poller.ts
@@ -23,12 +23,11 @@ export function useConnectionPoller(
 ): ConnectionPollerResult {
   const { org } = useProjectContext();
   const startTimeRef = useRef<number>(0);
+  const prevConnectionIdRef = useRef<string | null>(null);
 
-  if (connectionId && startTimeRef.current === 0) {
-    startTimeRef.current = Date.now();
-  }
-  if (!connectionId) {
-    startTimeRef.current = 0;
+  if (connectionId !== prevConnectionIdRef.current) {
+    prevConnectionIdRef.current = connectionId;
+    startTimeRef.current = connectionId ? Date.now() : 0;
   }
 
   const { data: connection } = useQuery({

From 2cca6eae1a9e11449532cfe54037bad92b1084f8 Mon Sep 17 00:00:00 2001
From: viktormarinho <viktormpcs@gmail.com>
Date: Tue, 24 Feb 2026 17:16:02 -0300
Subject: [PATCH 18/21] test(connections-setup): add DOM component tests with
 @testing-library/react
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Sets up happy-dom + RTL infrastructure and adds component-level tests for
SlotCard and ConnectionsSetup alongside the existing pure-function tests.

Infrastructure:
- bunfig.toml: two-stage preload (dom registration before RTL import)
- apps/mesh/test-setup.ts: GlobalRegistrator.register({ url: ... })
- apps/mesh/test-setup-rtl.ts: expect.extend(jest-dom matchers) + afterEach cleanup
- src/types/bun-testing.d.ts: extends bun:test Matchers with jest-dom types

SlotCard tests (slot-card.test.tsx) — 20 tests:
- All phase transitions: loading, error, install, polling, done, picker
- install → polling → done (calls onComplete once, guarded against re-render duplication)
- polling timeout → auth-oauth / auth-token (including null-connection fix)
- OAuth/token → back to polling
- done → picker / install on Change; picker select active/inactive; Install fresh

ConnectionsSetup tests (connections-setup.test.tsx) — 5 tests:
- Renders one card per slot
- Does not call onComplete until all slots satisfy
- Calls onComplete with correct slotId → connectionId map
- Does not call onComplete twice on re-renders
- Calls onComplete again after reset + re-completion

Mocking strategy (Option A): hooks (useSlotResolution, useConnectionPoller) and
child components are stubbed so tests cover rendering and state-machine wiring
without network calls. connections-setup.test.tsx deliberately does NOT mock
./slot-card to avoid cross-file module registry contamination in Bun 1.3.5.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
---
 apps/mesh/package.json                        |   5 +-
 apps/mesh/src/types/bun-testing.d.ts          |  14 +
 .../connections-setup.test.tsx                | 288 ++++++++
 .../slot-card-transitions.test.ts             | 207 ++++++
 .../slot-card-transitions.ts                  | 106 +++
 .../connections-setup/slot-card.test.tsx      | 632 ++++++++++++++++++
 .../connections-setup/slot-card.tsx           |  78 ++-
 .../connections-setup/use-slot-resolution.ts  |   2 +-
 apps/mesh/src/web/routes/orgs/connections.tsx |  44 +-
 .../web/utils/extract-connection-data.test.ts | 130 ++++
 .../src/web/utils/extract-connection-data.ts  |   2 +-
 apps/mesh/test-setup-rtl.ts                   |  11 +
 apps/mesh/test-setup.ts                       |   6 +
 bunfig.toml                                   |   2 +
 14 files changed, 1497 insertions(+), 30 deletions(-)
 create mode 100644 apps/mesh/src/types/bun-testing.d.ts
 create mode 100644 apps/mesh/src/web/components/connections-setup/connections-setup.test.tsx
 create mode 100644 apps/mesh/src/web/components/connections-setup/slot-card-transitions.test.ts
 create mode 100644 apps/mesh/src/web/components/connections-setup/slot-card-transitions.ts
 create mode 100644 apps/mesh/src/web/components/connections-setup/slot-card.test.tsx
 create mode 100644 apps/mesh/src/web/utils/extract-connection-data.test.ts
 create mode 100644 apps/mesh/test-setup-rtl.ts
 create mode 100644 apps/mesh/test-setup.ts
 create mode 100644 bunfig.toml

diff --git a/apps/mesh/package.json b/apps/mesh/package.json
index 5e4664c68d..99533d5613 100644
--- a/apps/mesh/package.json
+++ b/apps/mesh/package.json
@@ -54,6 +54,7 @@
     "@decocms/runtime": "workspace:*",
     "@decocms/vite-plugin": "workspace:*",
     "@floating-ui/react": "^0.27.16",
+    "@happy-dom/global-registrator": "^20.7.0",
     "@hookform/resolvers": "^5.2.2",
     "@modelcontextprotocol/sdk": "1.26.0",
     "@monaco-editor/react": "^4.7.0",
@@ -83,6 +84,8 @@
     "@tailwindcss/vite": "^4.1.17",
     "@tanstack/react-query": "5.90.11",
     "@tanstack/react-router": "^1.139.7",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
     "@tiptap/core": "^3.15.3",
     "@tiptap/extension-mention": "^3.13.0",
     "@tiptap/extension-placeholder": "^3.15.3",
@@ -113,8 +116,8 @@
     "marked": "^15.0.6",
     "mesh-plugin-object-storage": "workspace:*",
     "mesh-plugin-private-registry": "workspace:*",
-    "mesh-plugin-user-sandbox": "workspace:*",
     "mesh-plugin-reports": "workspace:*",
+    "mesh-plugin-user-sandbox": "workspace:*",
     "mesh-plugin-workflows": "workspace:*",
     "nanoid": "^5.1.6",
     "pg": "^8.16.3",
diff --git a/apps/mesh/src/types/bun-testing.d.ts b/apps/mesh/src/types/bun-testing.d.ts
new file mode 100644
index 0000000000..cee12a3835
--- /dev/null
+++ b/apps/mesh/src/types/bun-testing.d.ts
@@ -0,0 +1,14 @@
+// Extend Bun's test Matchers with @testing-library/jest-dom matchers
+// so toBeInTheDocument(), toHaveTextContent(), etc. are properly typed.
+import type { TestingLibraryMatchers } from "@testing-library/jest-dom/matchers";
+import type { expect } from "bun:test";
+
+export {};
+
+declare module "bun:test" {
+  interface Matchers<T = unknown>
+    extends TestingLibraryMatchers<
+      ReturnType<typeof expect.stringContaining>,
+      T
+    > {}
+}
diff --git a/apps/mesh/src/web/components/connections-setup/connections-setup.test.tsx b/apps/mesh/src/web/components/connections-setup/connections-setup.test.tsx
new file mode 100644
index 0000000000..ad19c2c846
--- /dev/null
+++ b/apps/mesh/src/web/components/connections-setup/connections-setup.test.tsx
@@ -0,0 +1,288 @@
+/// <reference lib="dom" />
+/// <reference types="@testing-library/jest-dom/matchers" />
+import { beforeEach, describe, expect, it, mock } from "bun:test";
+import { fireEvent, render, screen } from "@testing-library/react";
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { ConnectionEntity } from "@decocms/mesh-sdk";
+import type { SlotResolution } from "./use-slot-resolution";
+import type { ConnectionPollerResult } from "./use-connection-poller";
+
+// ── Module mocks ──────────────────────────────────────────────────────────────
+// NOTE: deliberately NOT mocking ./slot-card — ConnectionsSetup is tested with
+// the real SlotCard to avoid polluting the shared module registry for slot-card.test.tsx.
+
+const mockUseSlotResolution = mock(() => makeResolution());
+const mockUseConnectionPoller = mock(() => makePoller());
+const mockIsConnectionAuthenticated = mock(() =>
+  Promise.resolve({ supportsOAuth: false }),
+);
+
+mock.module("./use-slot-resolution", () => ({
+  useSlotResolution: mockUseSlotResolution,
+}));
+mock.module("./use-connection-poller", () => ({
+  useConnectionPoller: mockUseConnectionPoller,
+}));
+mock.module("@decocms/mesh-sdk", () => ({
+  isConnectionAuthenticated: mockIsConnectionAuthenticated,
+}));
+
+mock.module("./slot-install-form", () => ({
+  SlotInstallForm: ({ onInstalled }: { onInstalled: (id: string) => void }) =>
+    React.createElement(
+      "button",
+      { "data-testid": "install-btn", onClick: () => onInstalled("conn_new") },
+      "Install",
+    ),
+}));
+
+mock.module("./slot-done", () => ({
+  SlotDone: ({
+    label,
+    connection,
+    onReset,
+  }: {
+    label: string;
+    connection: ConnectionEntity;
+    onReset: () => void;
+  }) =>
+    React.createElement(
+      "div",
+      { "data-testid": `done-${label}` },
+      React.createElement(
+        "span",
+        { "data-testid": `done-title-${label}` },
+        connection.title,
+      ),
+      React.createElement(
+        "button",
+        { "data-testid": `change-${label}`, onClick: onReset },
+        "Change",
+      ),
+    ),
+}));
+
+mock.module("./slot-auth-oauth", () => ({
+  SlotAuthOAuth: ({ onAuthed }: { onAuthed: () => void }) =>
+    React.createElement("button", { onClick: onAuthed }, "Authorize"),
+}));
+
+mock.module("./slot-auth-token", () => ({
+  SlotAuthToken: ({ onAuthed }: { onAuthed: () => void }) =>
+    React.createElement("button", { onClick: onAuthed }, "Submit Token"),
+}));
+
+import { ConnectionsSetup } from "./connections-setup";
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function makeConn(overrides: Partial<ConnectionEntity> = {}): ConnectionEntity {
+  return {
+    id: "conn_test",
+    title: "Test Connection",
+    status: "active",
+    connection_type: "HTTP",
+    connection_url: null,
+    connection_token: null,
+    connection_headers: null,
+    oauth_config: null,
+    configuration_state: null,
+    configuration_scopes: null,
+    description: null,
+    icon: null,
+    app_name: null,
+    app_id: null,
+    tools: null,
+    bindings: null,
+    organization_id: "org_1",
+    created_by: "user_1",
+    updated_by: "user_1",
+    created_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+    ...overrides,
+  } as unknown as ConnectionEntity;
+}
+
+function makeResolution(
+  overrides: Partial<SlotResolution> = {},
+): SlotResolution {
+  return {
+    initialPhase: "install",
+    registryItem: {
+      id: "item_1",
+      title: "Test MCP",
+      server: { name: "deco/test" },
+      created_at: "",
+      updated_at: "",
+    } as SlotResolution["registryItem"],
+    matchingConnections: [],
+    satisfiedConnection: null,
+    isLoading: false,
+    registryError: null,
+    ...overrides,
+  };
+}
+
+function makePoller(
+  overrides: Partial<ConnectionPollerResult> = {},
+): ConnectionPollerResult {
+  return {
+    connection: null,
+    isActive: false,
+    isTimedOut: false,
+    isPolling: false,
+    ...overrides,
+  };
+}
+
+function createWrapper() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return ({ children }: { children: React.ReactNode }) =>
+    React.createElement(QueryClientProvider, { client: queryClient }, children);
+}
+
+const twoSlots = {
+  model: {
+    label: "model",
+    registry: "deco-registry",
+    item_id: "deco/openrouter",
+  },
+  github: {
+    label: "github",
+    registry: "deco-registry",
+    item_id: "deco/github",
+  },
+};
+
+// Returns picker phase with a unique active connection per slot label so tests
+// can click individual slots by text even after re-renders.
+function setupPickerPerSlot() {
+  mockUseSlotResolution.mockImplementation(
+    // @ts-expect-error — Bun's mock type doesn't infer the slot arg but it is passed at runtime
+    (slot: ConnectionSlot) => {
+      const label = slot?.label ?? "unknown";
+      return makeResolution({
+        initialPhase: "picker",
+        matchingConnections: [
+          makeConn({
+            id: `conn_${label}`,
+            title: `${label}_conn`,
+            status: "active",
+          }),
+        ],
+      });
+    },
+  );
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+beforeEach(() => {
+  mockUseSlotResolution.mockReset();
+  mockUseConnectionPoller.mockReset();
+  mockUseConnectionPoller.mockReturnValue(makePoller());
+  mockUseSlotResolution.mockReturnValue(
+    makeResolution({ initialPhase: "install" }),
+  );
+});
+
+describe("ConnectionsSetup", () => {
+  it("renders a card for each slot", () => {
+    render(
+      React.createElement(ConnectionsSetup, {
+        slots: twoSlots,
+        onComplete: () => {},
+      }),
+      { wrapper: createWrapper() },
+    );
+
+    // Both slots in install phase → each shows an install button
+    expect(screen.getAllByTestId("install-btn").length).toBe(2);
+  });
+
+  it("does not call onComplete when only one of two slots is satisfied", () => {
+    setupPickerPerSlot();
+    const onComplete = mock(() => {});
+
+    render(
+      React.createElement(ConnectionsSetup, { slots: twoSlots, onComplete }),
+      { wrapper: createWrapper() },
+    );
+
+    // Complete only the model slot
+    fireEvent.click(screen.getByText("model_conn"));
+
+    expect(onComplete).not.toHaveBeenCalled();
+  });
+
+  it("calls onComplete with slotId → connectionId map when all slots satisfy", () => {
+    setupPickerPerSlot();
+    const onComplete = mock(() => {});
+
+    render(
+      React.createElement(ConnectionsSetup, { slots: twoSlots, onComplete }),
+      { wrapper: createWrapper() },
+    );
+
+    fireEvent.click(screen.getByText("model_conn"));
+    fireEvent.click(screen.getByText("github_conn"));
+
+    expect(onComplete).toHaveBeenCalledTimes(1);
+    expect(onComplete).toHaveBeenCalledWith({
+      model: "conn_model",
+      github: "conn_github",
+    });
+  });
+
+  it("does not call onComplete a second time on re-renders after completion", () => {
+    setupPickerPerSlot();
+    const onComplete = mock(() => {});
+
+    const { rerender } = render(
+      React.createElement(ConnectionsSetup, { slots: twoSlots, onComplete }),
+      { wrapper: createWrapper() },
+    );
+
+    fireEvent.click(screen.getByText("model_conn"));
+    fireEvent.click(screen.getByText("github_conn"));
+
+    rerender(
+      React.createElement(ConnectionsSetup, { slots: twoSlots, onComplete }),
+    );
+    rerender(
+      React.createElement(ConnectionsSetup, { slots: twoSlots, onComplete }),
+    );
+
+    expect(onComplete).toHaveBeenCalledTimes(1);
+  });
+
+  it("calls onComplete again after a completed slot is reset and re-satisfied", () => {
+    setupPickerPerSlot();
+    const onComplete = mock(() => {});
+
+    render(
+      React.createElement(ConnectionsSetup, { slots: twoSlots, onComplete }),
+      { wrapper: createWrapper() },
+    );
+
+    // Complete both slots via picker
+    fireEvent.click(screen.getByText("model_conn"));
+    fireEvent.click(screen.getByText("github_conn"));
+    expect(onComplete).toHaveBeenCalledTimes(1);
+
+    // Reset model slot → goes back to picker (matchingConnections still exist)
+    fireEvent.click(screen.getByTestId("change-model"));
+
+    // Re-pick the active connection from the picker
+    fireEvent.click(screen.getByText("model_conn"));
+
+    expect(onComplete).toHaveBeenCalledTimes(2);
+    expect(onComplete).toHaveBeenLastCalledWith({
+      model: "conn_model",
+      github: "conn_github",
+    });
+  });
+});
diff --git a/apps/mesh/src/web/components/connections-setup/slot-card-transitions.test.ts b/apps/mesh/src/web/components/connections-setup/slot-card-transitions.test.ts
new file mode 100644
index 0000000000..beacd14bc6
--- /dev/null
+++ b/apps/mesh/src/web/components/connections-setup/slot-card-transitions.test.ts
@@ -0,0 +1,207 @@
+import { describe, expect, it } from "bun:test";
+import type { ConnectionEntity } from "@decocms/mesh-sdk";
+import {
+  onAuthed,
+  onInstallFresh,
+  onInstalled,
+  onPickActive,
+  onPickInactive,
+  onPollerActive,
+  onPollerTimeout,
+  onAuthStatus,
+  onReset,
+} from "./slot-card-transitions";
+
+function makeConn(overrides: Partial<ConnectionEntity> = {}): ConnectionEntity {
+  return {
+    id: "conn_test",
+    title: "Test Connection",
+    status: "inactive",
+    connection_type: "HTTP",
+    connection_url: null,
+    connection_token: null,
+    connection_headers: null,
+    oauth_config: null,
+    configuration_state: null,
+    configuration_scopes: null,
+    description: null,
+    icon: null,
+    app_name: null,
+    app_id: null,
+    tools: null,
+    bindings: null,
+    organization_id: "org_1",
+    created_by: "user_1",
+    updated_by: "user_1",
+    created_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+    ...overrides,
+  } as unknown as ConnectionEntity;
+}
+
+describe("onInstalled", () => {
+  it("transitions to polling phase", () => {
+    expect(onInstalled("conn_abc").phase).toBe("polling");
+  });
+
+  it("sets pollingConnectionId to the new connection", () => {
+    expect(onInstalled("conn_abc").pollingConnectionId).toBe("conn_abc");
+  });
+});
+
+describe("onPollerActive", () => {
+  it("transitions to done", () => {
+    const conn = makeConn({ id: "conn_abc", status: "active" });
+    expect(onPollerActive(conn).phase).toBe("done");
+  });
+
+  it("clears pollingConnectionId", () => {
+    const conn = makeConn({ id: "conn_abc", status: "active" });
+    expect(onPollerActive(conn).pollingConnectionId).toBeNull();
+  });
+
+  it("stores the active connection as selectedConnection", () => {
+    const conn = makeConn({ id: "conn_abc", status: "active" });
+    expect(onPollerActive(conn).selectedConnection).toBe(conn);
+  });
+});
+
+describe("onPollerTimeout", () => {
+  it("sets authCheckId to the connectionId so the auth query fires", () => {
+    const result = onPollerTimeout("conn_abc", makeConn({ id: "conn_abc" }));
+    expect(result.authCheckId).toBe("conn_abc");
+  });
+
+  it("clears pollingConnectionId", () => {
+    const result = onPollerTimeout("conn_abc", makeConn());
+    expect(result.pollingConnectionId).toBeNull();
+  });
+
+  it("captures the connection entity when the poller fetched it before timing out", () => {
+    const conn = makeConn({ id: "conn_abc" });
+    expect(onPollerTimeout("conn_abc", conn).selectedConnection).toBe(conn);
+  });
+
+  it("stores null selectedConnection when the poller never fetched the entity", () => {
+    expect(onPollerTimeout("conn_abc", null).selectedConnection).toBeNull();
+  });
+});
+
+describe("onAuthStatus", () => {
+  it("routes to auth-oauth when the endpoint supports OAuth", () => {
+    expect(onAuthStatus(true).phase).toBe("auth-oauth");
+  });
+
+  it("routes to auth-token when the endpoint does not support OAuth", () => {
+    expect(onAuthStatus(false).phase).toBe("auth-token");
+  });
+});
+
+describe("onAuthed", () => {
+  it("restarts polling using authCheckId when selectedConnection is null", () => {
+    const result = onAuthed({
+      pollingConnectionId: null,
+      selectedConnection: null,
+      authCheckId: "conn_abc",
+    });
+    expect(result.pollingConnectionId).toBe("conn_abc");
+    expect(result.authCheckId).toBeNull();
+    expect(result.phase).toBe("polling");
+  });
+
+  it("restarts polling using selectedConnection.id as fallback", () => {
+    const conn = makeConn({ id: "conn_abc" });
+    const result = onAuthed({
+      pollingConnectionId: null,
+      selectedConnection: conn,
+      authCheckId: null,
+    });
+    expect(result.pollingConnectionId).toBe("conn_abc");
+    expect(result.phase).toBe("polling");
+  });
+
+  it("prefers pollingConnectionId over selectedConnection.id", () => {
+    const conn = makeConn({ id: "conn_selected" });
+    const result = onAuthed({
+      pollingConnectionId: "conn_polling",
+      selectedConnection: conn,
+      authCheckId: null,
+    });
+    expect(result.pollingConnectionId).toBe("conn_polling");
+  });
+
+  it("clears authCheckId after auth", () => {
+    const result = onAuthed({
+      pollingConnectionId: null,
+      selectedConnection: null,
+      authCheckId: "conn_abc",
+    });
+    expect(result.authCheckId).toBeNull();
+  });
+
+  it("returns empty object when no connection id is available", () => {
+    const result = onAuthed({
+      pollingConnectionId: null,
+      selectedConnection: null,
+      authCheckId: null,
+    });
+    expect(result).toEqual({});
+  });
+});
+
+describe("onReset", () => {
+  it("goes to picker when existing connections are available", () => {
+    expect(onReset(true).phase).toBe("picker");
+  });
+
+  it("goes to install when no existing connections", () => {
+    expect(onReset(false).phase).toBe("install");
+  });
+
+  it("clears selectedConnection", () => {
+    expect(onReset(false).selectedConnection).toBeNull();
+  });
+
+  it("clears pollingConnectionId", () => {
+    expect(onReset(false).pollingConnectionId).toBeNull();
+  });
+
+  it("clears authCheckId", () => {
+    expect(onReset(false).authCheckId).toBeNull();
+  });
+});
+
+describe("onPickActive", () => {
+  it("transitions to done", () => {
+    const conn = makeConn({ id: "conn_abc", status: "active" });
+    expect(onPickActive(conn).phase).toBe("done");
+  });
+
+  it("stores the picked connection", () => {
+    const conn = makeConn({ id: "conn_abc", status: "active" });
+    expect(onPickActive(conn).selectedConnection).toBe(conn);
+  });
+});
+
+describe("onPickInactive", () => {
+  it("starts polling for the picked connection", () => {
+    const conn = makeConn({ id: "conn_abc", status: "inactive" });
+    expect(onPickInactive(conn).phase).toBe("polling");
+  });
+
+  it("sets pollingConnectionId to the picked connection id", () => {
+    const conn = makeConn({ id: "conn_abc", status: "inactive" });
+    expect(onPickInactive(conn).pollingConnectionId).toBe("conn_abc");
+  });
+
+  it("stores the picked connection as selectedConnection", () => {
+    const conn = makeConn({ id: "conn_abc", status: "inactive" });
+    expect(onPickInactive(conn).selectedConnection).toBe(conn);
+  });
+});
+
+describe("onInstallFresh", () => {
+  it("transitions to install phase", () => {
+    expect(onInstallFresh().phase).toBe("install");
+  });
+});
diff --git a/apps/mesh/src/web/components/connections-setup/slot-card-transitions.ts b/apps/mesh/src/web/components/connections-setup/slot-card-transitions.ts
new file mode 100644
index 0000000000..455d191468
--- /dev/null
+++ b/apps/mesh/src/web/components/connections-setup/slot-card-transitions.ts
@@ -0,0 +1,106 @@
+import type { ConnectionEntity } from "@decocms/mesh-sdk";
+import type { SlotPhase } from "./slot-resolution";
+
+export type SlotCardState = {
+  phase: SlotPhase | null;
+  pollingConnectionId: string | null;
+  selectedConnection: ConnectionEntity | null;
+  authCheckId: string | null;
+};
+
+/** User confirmed the install form — start polling for the new connection. */
+export function onInstalled(connectionId: string): Partial<SlotCardState> {
+  return {
+    pollingConnectionId: connectionId,
+    phase: "polling",
+  };
+}
+
+/** Poller observed the connection is active — mark slot as done. */
+export function onPollerActive(
+  connection: ConnectionEntity,
+): Partial<SlotCardState> {
+  return {
+    pollingConnectionId: null,
+    selectedConnection: connection,
+    phase: "done",
+  };
+}
+
+/**
+ * Poller timed out or the connection errored before going active.
+ * Queue an auth check to determine whether OAuth or token auth is needed.
+ */
+export function onPollerTimeout(
+  connectionId: string,
+  connection: ConnectionEntity | null,
+): Partial<SlotCardState> {
+  return {
+    selectedConnection: connection,
+    authCheckId: connectionId,
+    pollingConnectionId: null,
+  };
+}
+
+/** Auth check completed — transition to the appropriate auth phase. */
+export function onAuthStatus(supportsOAuth: boolean): Partial<SlotCardState> {
+  return {
+    phase: supportsOAuth ? "auth-oauth" : "auth-token",
+  };
+}
+
+/** User completed auth — restart polling to verify the connection activates. */
+export function onAuthed(
+  state: Pick<
+    SlotCardState,
+    "pollingConnectionId" | "selectedConnection" | "authCheckId"
+  >,
+): Partial<SlotCardState> {
+  const id =
+    state.pollingConnectionId ??
+    state.selectedConnection?.id ??
+    state.authCheckId ??
+    null;
+  if (!id) return {};
+  return {
+    authCheckId: null,
+    pollingConnectionId: id,
+    phase: "polling",
+  };
+}
+
+/** User chose to change the connection — go back to picker or install. */
+export function onReset(hasExisting: boolean): Partial<SlotCardState> {
+  return {
+    phase: hasExisting ? "picker" : "install",
+    selectedConnection: null,
+    pollingConnectionId: null,
+    authCheckId: null,
+  };
+}
+
+/** User picked an already-active existing connection. */
+export function onPickActive(
+  connection: ConnectionEntity,
+): Partial<SlotCardState> {
+  return {
+    selectedConnection: connection,
+    phase: "done",
+  };
+}
+
+/** User picked an existing connection that isn't active yet — poll for it. */
+export function onPickInactive(
+  connection: ConnectionEntity,
+): Partial<SlotCardState> {
+  return {
+    selectedConnection: connection,
+    pollingConnectionId: connection.id,
+    phase: "polling",
+  };
+}
+
+/** User chose "Install fresh" from the picker. */
+export function onInstallFresh(): Partial<SlotCardState> {
+  return { phase: "install" };
+}
diff --git a/apps/mesh/src/web/components/connections-setup/slot-card.test.tsx b/apps/mesh/src/web/components/connections-setup/slot-card.test.tsx
new file mode 100644
index 0000000000..24f735ae78
--- /dev/null
+++ b/apps/mesh/src/web/components/connections-setup/slot-card.test.tsx
@@ -0,0 +1,632 @@
+/// <reference lib="dom" />
+import { beforeEach, describe, expect, it, mock } from "bun:test";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { ConnectionEntity } from "@decocms/mesh-sdk";
+import type { SlotResolution } from "./use-slot-resolution";
+import type { ConnectionPollerResult } from "./use-connection-poller";
+
+// ── Module mocks (hoisted by Bun before imports) ─────────────────────────────
+
+const mockUseSlotResolution = mock(() => makeResolution());
+const mockUseConnectionPoller = mock(() => makePoller());
+const mockIsConnectionAuthenticated = mock(() =>
+  Promise.resolve({ supportsOAuth: false }),
+);
+
+mock.module("./use-slot-resolution", () => ({
+  useSlotResolution: mockUseSlotResolution,
+}));
+
+mock.module("./use-connection-poller", () => ({
+  useConnectionPoller: mockUseConnectionPoller,
+}));
+
+mock.module("@decocms/mesh-sdk", () => ({
+  isConnectionAuthenticated: mockIsConnectionAuthenticated,
+}));
+
+// Stub child components — expose only what SlotCard passes to them
+mock.module("./slot-install-form", () => ({
+  SlotInstallForm: ({ onInstalled }: { onInstalled: (id: string) => void }) =>
+    React.createElement(
+      "button",
+      { "data-testid": "install-btn", onClick: () => onInstalled("conn_new") },
+      "Install",
+    ),
+}));
+
+mock.module("./slot-done", () => ({
+  SlotDone: ({
+    label,
+    connection,
+    onReset,
+  }: {
+    label: string;
+    connection: ConnectionEntity;
+    onReset: () => void;
+  }) =>
+    React.createElement(
+      "div",
+      { "data-testid": "slot-done" },
+      React.createElement("span", { "data-testid": "done-label" }, label),
+      React.createElement(
+        "span",
+        { "data-testid": "done-connection" },
+        connection.title,
+      ),
+      React.createElement(
+        "button",
+        { "data-testid": "change-btn", onClick: onReset },
+        "Change",
+      ),
+    ),
+}));
+
+mock.module("./slot-auth-oauth", () => ({
+  SlotAuthOAuth: ({
+    connectionId,
+    onAuthed,
+  }: {
+    connectionId: string;
+    onAuthed: () => void;
+  }) =>
+    React.createElement(
+      "button",
+      {
+        "data-testid": "oauth-btn",
+        "data-connection-id": connectionId,
+        onClick: onAuthed,
+      },
+      "Authorize",
+    ),
+}));
+
+mock.module("./slot-auth-token", () => ({
+  SlotAuthToken: ({
+    connectionId,
+    onAuthed,
+  }: {
+    connectionId: string;
+    onAuthed: () => void;
+  }) =>
+    React.createElement(
+      "button",
+      {
+        "data-testid": "token-btn",
+        "data-connection-id": connectionId,
+        onClick: onAuthed,
+      },
+      "Submit Token",
+    ),
+}));
+
+// ── Import component after mocks ─────────────────────────────────────────────
+
+// Bun hoists mock.module calls, so static import gets the mocked dependencies
+import { SlotCard } from "./slot-card";
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function makeConn(
+  overrides: Partial<ConnectionEntity> & {
+    metadata?: Record<string, unknown>;
+  } = {},
+): ConnectionEntity {
+  return {
+    id: "conn_test",
+    title: "Test Connection",
+    status: "active",
+    connection_type: "HTTP",
+    connection_url: null,
+    connection_token: null,
+    connection_headers: null,
+    oauth_config: null,
+    configuration_state: null,
+    configuration_scopes: null,
+    description: null,
+    icon: null,
+    app_name: null,
+    app_id: null,
+    tools: null,
+    bindings: null,
+    organization_id: "org_1",
+    created_by: "user_1",
+    updated_by: "user_1",
+    created_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+    ...overrides,
+  } as unknown as ConnectionEntity;
+}
+
+function makeResolution(
+  overrides: Partial<SlotResolution> = {},
+): SlotResolution {
+  return {
+    initialPhase: "install",
+    registryItem: {
+      id: "item_1",
+      title: "Test MCP",
+      server: { name: "deco/test" },
+      created_at: "",
+      updated_at: "",
+    } as SlotResolution["registryItem"],
+    matchingConnections: [],
+    satisfiedConnection: null,
+    isLoading: false,
+    registryError: null,
+    ...overrides,
+  };
+}
+
+function makePoller(
+  overrides: Partial<ConnectionPollerResult> = {},
+): ConnectionPollerResult {
+  return {
+    connection: null,
+    isActive: false,
+    isTimedOut: false,
+    isPolling: false,
+    ...overrides,
+  };
+}
+
+function createWrapper() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return ({ children }: { children: React.ReactNode }) =>
+    React.createElement(QueryClientProvider, { client: queryClient }, children);
+}
+
+const slot = {
+  label: "Test MCP",
+  registry: "deco-registry",
+  item_id: "deco/test",
+};
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+beforeEach(() => {
+  mockUseSlotResolution.mockReset();
+  mockUseConnectionPoller.mockReset();
+  mockIsConnectionAuthenticated.mockReset();
+  mockIsConnectionAuthenticated.mockReturnValue(
+    Promise.resolve({ supportsOAuth: false }),
+  );
+});
+
+describe("SlotCard", () => {
+  describe("loading state", () => {
+    it("shows slot label and no form while registry item loads", () => {
+      mockUseSlotResolution.mockReturnValue(
+        makeResolution({ initialPhase: "loading", isLoading: true }),
+      );
+      mockUseConnectionPoller.mockReturnValue(makePoller());
+
+      render(React.createElement(SlotCard, { slot, onComplete: () => {} }), {
+        wrapper: createWrapper(),
+      });
+
+      expect(screen.getByText("Test MCP")).toBeInTheDocument();
+      expect(screen.queryByTestId("install-btn")).toBeNull();
+      expect(screen.queryByTestId("slot-done")).toBeNull();
+    });
+  });
+
+  describe("registry error state", () => {
+    it("shows the error message when the registry item is not found", () => {
+      mockUseSlotResolution.mockReturnValue(
+        makeResolution({ registryError: "Registry item not found." }),
+      );
+      mockUseConnectionPoller.mockReturnValue(makePoller());
+
+      render(React.createElement(SlotCard, { slot, onComplete: () => {} }), {
+        wrapper: createWrapper(),
+      });
+
+      expect(screen.getByText("Registry item not found.")).toBeInTheDocument();
+      expect(screen.queryByTestId("install-btn")).toBeNull();
+    });
+  });
+
+  describe("install phase", () => {
+    it("renders the install form when no existing connections", () => {
+      mockUseSlotResolution.mockReturnValue(
+        makeResolution({ initialPhase: "install" }),
+      );
+      mockUseConnectionPoller.mockReturnValue(makePoller());
+
+      render(React.createElement(SlotCard, { slot, onComplete: () => {} }), {
+        wrapper: createWrapper(),
+      });
+
+      expect(screen.getByTestId("install-btn")).toBeInTheDocument();
+    });
+
+    it("transitions to polling when the install form submits", () => {
+      mockUseSlotResolution.mockReturnValue(
+        makeResolution({ initialPhase: "install" }),
+      );
+      mockUseConnectionPoller.mockReturnValue(makePoller());
+
+      render(React.createElement(SlotCard, { slot, onComplete: () => {} }), {
+        wrapper: createWrapper(),
+      });
+
+      fireEvent.click(screen.getByTestId("install-btn"));
+
+      expect(screen.getByText("Connecting...")).toBeInTheDocument();
+      expect(screen.queryByTestId("install-btn")).toBeNull();
+    });
+  });
+
+  describe("polling phase", () => {
+    it("shows Connecting... spinner while polling", () => {
+      mockUseSlotResolution.mockReturnValue(
+        makeResolution({ initialPhase: "install" }),
+      );
+      mockUseConnectionPoller.mockReturnValue(makePoller({ isPolling: true }));
+
+      render(React.createElement(SlotCard, { slot, onComplete: () => {} }), {
+        wrapper: createWrapper(),
+      });
+      fireEvent.click(screen.getByTestId("install-btn"));
+
+      expect(screen.getByText("Connecting...")).toBeInTheDocument();
+    });
+
+    it("transitions to done and calls onComplete when the connection becomes active", () => {
+      const conn = makeConn({
+        id: "conn_abc",
+        title: "OpenRouter",
+        status: "active",
+      });
+      const onComplete = mock(() => {});
+
+      mockUseSlotResolution.mockReturnValue(
+        makeResolution({ initialPhase: "install" }),
+      );
+      mockUseConnectionPoller.mockReturnValue(makePoller());
+
+      const { rerender } = render(
+        React.createElement(SlotCard, { slot, onComplete }),
+        { wrapper: createWrapper() },
+      );
+      fireEvent.click(screen.getByTestId("install-btn"));
+
+      mockUseConnectionPoller.mockReturnValue(
+        makePoller({ isActive: true, connection: conn }),
+      );
+      rerender(React.createElement(SlotCard, { slot, onComplete }));
+
+      expect(screen.getByTestId("done-connection")).toHaveTextContent(
+        "OpenRouter",
+      );
+      expect(onComplete).toHaveBeenCalledTimes(1);
+      expect(onComplete).toHaveBeenCalledWith("conn_abc");
+    });
+
+    it("only calls onComplete once across multiple re-renders with the same active connection", () => {
+      const conn = makeConn({ id: "conn_abc", status: "active" });
+      const onComplete = mock(() => {});
+
+      mockUseSlotResolution.mockReturnValue(
+        makeResolution({ initialPhase: "install" }),
+      );
+      mockUseConnectionPoller.mockReturnValue(makePoller());
+
+      const { rerender } = render(
+        React.createElement(SlotCard, { slot, onComplete }),
+        { wrapper: createWrapper() },
+      );
+      // Click install to set pollingConnectionId, then poller goes active
+      fireEvent.click(screen.getByTestId("install-btn"));
+
+      mockUseConnectionPoller.mockReturnValue(
+        makePoller({ isActive: true, connection: conn }),
+      );
+      rerender(React.createElement(SlotCard, { slot, onComplete }));
+      rerender(React.createElement(SlotCard, { slot, onComplete }));
+      rerender(React.createElement(SlotCard, { slot, onComplete }));
+
+      expect(onComplete).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("auth-oauth phase", () => {
+    it("shows OAuth button when polling times out and endpoint supports OAuth", async () => {
+      const conn = makeConn({ id: "conn_auth", status: "inactive" });
+      mockIsConnectionAuthenticated.mockResolvedValue({ supportsOAuth: true });
+
+      mockUseSlotResolution.mockReturnValue(
+        makeResolution({ initialPhase: "install" }),
+      );
+      mockUseConnectionPoller.mockReturnValue(makePoller());
+
+      const { rerender } = render(
+        React.createElement(SlotCard, { slot, onComplete: () => {} }),
+        { wrapper: createWrapper() },
+      );
+      fireEvent.click(screen.getByTestId("install-btn"));
+
+      mockUseConnectionPoller.mockReturnValue(
+        makePoller({ isTimedOut: true, connection: conn }),
+      );
+      rerender(React.createElement(SlotCard, { slot, onComplete: () => {} }));
+
+      await waitFor(() =>
+        expect(screen.getByTestId("oauth-btn")).toBeInTheDocument(),
+      );
+    });
+
+    it("shows OAuth button even when the poller never fetched a connection entity (null connection fix)", async () => {
+      mockIsConnectionAuthenticated.mockResolvedValue({ supportsOAuth: true });
+
+      mockUseSlotResolution.mockReturnValue(
+        makeResolution({ initialPhase: "install" }),
+      );
+      mockUseConnectionPoller.mockReturnValue(makePoller());
+
+      const { rerender } = render(
+        React.createElement(SlotCard, { slot, onComplete: () => {} }),
+        { wrapper: createWrapper() },
+      );
+      fireEvent.click(screen.getByTestId("install-btn"));
+
+      // connection is null — this was the "stuck state" bug
+      mockUseConnectionPoller.mockReturnValue(
+        makePoller({ isTimedOut: true, connection: null }),
+      );
+      rerender(React.createElement(SlotCard, { slot, onComplete: () => {} }));
+
+      await waitFor(() =>
+        expect(screen.getByTestId("oauth-btn")).toBeInTheDocument(),
+      );
+    });
+
+    it("returns to polling after OAuth completes", async () => {
+      const conn = makeConn({ id: "conn_auth" });
+      mockIsConnectionAuthenticated.mockResolvedValue({ supportsOAuth: true });
+
+      mockUseSlotResolution.mockReturnValue(
+        makeResolution({ initialPhase: "install" }),
+      );
+      mockUseConnectionPoller.mockReturnValue(makePoller());
+
+      const { rerender } = render(
+        React.createElement(SlotCard, { slot, onComplete: () => {} }),
+        { wrapper: createWrapper() },
+      );
+      fireEvent.click(screen.getByTestId("install-btn"));
+
+      mockUseConnectionPoller.mockReturnValue(
+        makePoller({ isTimedOut: true, connection: conn }),
+      );
+      rerender(React.createElement(SlotCard, { slot, onComplete: () => {} }));
+
+      await waitFor(() => screen.getByTestId("oauth-btn"));
+      fireEvent.click(screen.getByTestId("oauth-btn"));
+
+      expect(screen.getByText("Connecting...")).toBeInTheDocument();
+    });
+  });
+
+  describe("auth-token phase", () => {
+    it("shows token input when polling times out and endpoint does not support OAuth", async () => {
+      const conn = makeConn({ id: "conn_token" });
+      mockIsConnectionAuthenticated.mockResolvedValue({ supportsOAuth: false });
+
+      mockUseSlotResolution.mockReturnValue(
+        makeResolution({ initialPhase: "install" }),
+      );
+      mockUseConnectionPoller.mockReturnValue(makePoller());
+
+      const { rerender } = render(
+        React.createElement(SlotCard, { slot, onComplete: () => {} }),
+        { wrapper: createWrapper() },
+      );
+      fireEvent.click(screen.getByTestId("install-btn"));
+
+      mockUseConnectionPoller.mockReturnValue(
+        makePoller({ isTimedOut: true, connection: conn }),
+      );
+      rerender(React.createElement(SlotCard, { slot, onComplete: () => {} }));
+
+      await waitFor(() =>
+        expect(screen.getByTestId("token-btn")).toBeInTheDocument(),
+      );
+    });
+
+    it("returns to polling after token auth completes", async () => {
+      const conn = makeConn({ id: "conn_token" });
+      mockIsConnectionAuthenticated.mockResolvedValue({ supportsOAuth: false });
+
+      mockUseSlotResolution.mockReturnValue(
+        makeResolution({ initialPhase: "install" }),
+      );
+      mockUseConnectionPoller.mockReturnValue(makePoller());
+
+      const { rerender } = render(
+        React.createElement(SlotCard, { slot, onComplete: () => {} }),
+        { wrapper: createWrapper() },
+      );
+      fireEvent.click(screen.getByTestId("install-btn"));
+
+      mockUseConnectionPoller.mockReturnValue(
+        makePoller({ isTimedOut: true, connection: conn }),
+      );
+      rerender(React.createElement(SlotCard, { slot, onComplete: () => {} }));
+
+      await waitFor(() => screen.getByTestId("token-btn"));
+      fireEvent.click(screen.getByTestId("token-btn"));
+
+      expect(screen.getByText("Connecting...")).toBeInTheDocument();
+    });
+  });
+
+  describe("done phase", () => {
+    it("shows the done card when an existing connection is already active", () => {
+      const conn = makeConn({ id: "conn_abc", title: "OpenRouter" });
+      mockUseSlotResolution.mockReturnValue(
+        makeResolution({ initialPhase: "done", satisfiedConnection: conn }),
+      );
+      mockUseConnectionPoller.mockReturnValue(makePoller());
+
+      render(React.createElement(SlotCard, { slot, onComplete: () => {} }), {
+        wrapper: createWrapper(),
+      });
+
+      expect(screen.getByTestId("done-connection")).toHaveTextContent(
+        "OpenRouter",
+      );
+    });
+
+    it("goes to picker when Change is clicked and existing connections are present", () => {
+      const conn = makeConn({ id: "conn_abc", title: "OpenRouter" });
+      mockUseSlotResolution.mockReturnValue(
+        makeResolution({
+          initialPhase: "done",
+          satisfiedConnection: conn,
+          matchingConnections: [conn],
+        }),
+      );
+      mockUseConnectionPoller.mockReturnValue(makePoller());
+
+      render(React.createElement(SlotCard, { slot, onComplete: () => {} }), {
+        wrapper: createWrapper(),
+      });
+      fireEvent.click(screen.getByTestId("change-btn"));
+
+      expect(screen.getByText("Already installed:")).toBeInTheDocument();
+    });
+
+    it("goes to install when Change is clicked and no existing connections remain", () => {
+      const conn = makeConn({ id: "conn_abc", title: "OpenRouter" });
+      mockUseSlotResolution.mockReturnValue(
+        makeResolution({
+          initialPhase: "done",
+          satisfiedConnection: conn,
+          matchingConnections: [],
+        }),
+      );
+      mockUseConnectionPoller.mockReturnValue(makePoller());
+
+      render(React.createElement(SlotCard, { slot, onComplete: () => {} }), {
+        wrapper: createWrapper(),
+      });
+      fireEvent.click(screen.getByTestId("change-btn"));
+
+      expect(screen.getByTestId("install-btn")).toBeInTheDocument();
+    });
+
+    it("calls onComplete with empty string when the user resets", () => {
+      const conn = makeConn({ id: "conn_abc" });
+      const onComplete = mock(() => {});
+      mockUseSlotResolution.mockReturnValue(
+        makeResolution({
+          initialPhase: "done",
+          satisfiedConnection: conn,
+          matchingConnections: [],
+        }),
+      );
+      mockUseConnectionPoller.mockReturnValue(makePoller());
+
+      render(React.createElement(SlotCard, { slot, onComplete }), {
+        wrapper: createWrapper(),
+      });
+      fireEvent.click(screen.getByTestId("change-btn"));
+
+      expect(onComplete).toHaveBeenCalledWith("");
+    });
+  });
+
+  describe("picker phase", () => {
+    it("lists all matching connections", () => {
+      const conns = [
+        makeConn({ id: "conn_1", title: "OpenRouter #1", status: "active" }),
+        makeConn({ id: "conn_2", title: "OpenRouter #2", status: "inactive" }),
+      ];
+      mockUseSlotResolution.mockReturnValue(
+        makeResolution({ initialPhase: "picker", matchingConnections: conns }),
+      );
+      mockUseConnectionPoller.mockReturnValue(makePoller());
+
+      render(React.createElement(SlotCard, { slot, onComplete: () => {} }), {
+        wrapper: createWrapper(),
+      });
+
+      expect(screen.getByText("OpenRouter #1")).toBeInTheDocument();
+      expect(screen.getByText("OpenRouter #2")).toBeInTheDocument();
+    });
+
+    it("transitions to done and calls onComplete when an active connection is selected", () => {
+      const conn = makeConn({
+        id: "conn_active",
+        title: "OpenRouter",
+        status: "active",
+      });
+      const onComplete = mock(() => {});
+      mockUseSlotResolution.mockReturnValue(
+        makeResolution({
+          initialPhase: "picker",
+          matchingConnections: [conn],
+        }),
+      );
+      mockUseConnectionPoller.mockReturnValue(makePoller());
+
+      render(React.createElement(SlotCard, { slot, onComplete }), {
+        wrapper: createWrapper(),
+      });
+      fireEvent.click(screen.getByText("OpenRouter"));
+
+      expect(screen.getByTestId("slot-done")).toBeTruthy();
+      expect(onComplete).toHaveBeenCalledWith("conn_active");
+    });
+
+    it("starts polling when an inactive connection is selected", () => {
+      const conn = makeConn({
+        id: "conn_inactive",
+        title: "OpenRouter",
+        status: "inactive",
+      });
+      mockUseSlotResolution.mockReturnValue(
+        makeResolution({
+          initialPhase: "picker",
+          matchingConnections: [conn],
+        }),
+      );
+      mockUseConnectionPoller.mockReturnValue(makePoller());
+
+      render(React.createElement(SlotCard, { slot, onComplete: () => {} }), {
+        wrapper: createWrapper(),
+      });
+      fireEvent.click(screen.getByText("OpenRouter"));
+
+      expect(screen.getByText("Connecting...")).toBeTruthy();
+    });
+
+    it("transitions to install when Install fresh is clicked", () => {
+      const conn = makeConn({
+        id: "conn_1",
+        title: "OpenRouter",
+        status: "active",
+      });
+      mockUseSlotResolution.mockReturnValue(
+        makeResolution({
+          initialPhase: "picker",
+          matchingConnections: [conn],
+        }),
+      );
+      mockUseConnectionPoller.mockReturnValue(makePoller());
+
+      render(React.createElement(SlotCard, { slot, onComplete: () => {} }), {
+        wrapper: createWrapper(),
+      });
+      fireEvent.click(screen.getByText("Install fresh"));
+
+      expect(screen.getByTestId("install-btn")).toBeInTheDocument();
+    });
+  });
+});
diff --git a/apps/mesh/src/web/components/connections-setup/slot-card.tsx b/apps/mesh/src/web/components/connections-setup/slot-card.tsx
index 7fe43e26a8..47928c1e32 100644
--- a/apps/mesh/src/web/components/connections-setup/slot-card.tsx
+++ b/apps/mesh/src/web/components/connections-setup/slot-card.tsx
@@ -10,6 +10,18 @@ import { KEYS } from "@/web/lib/query-keys";
 import { useSlotResolution, type ConnectionSlot } from "./use-slot-resolution";
 import { useConnectionPoller } from "./use-connection-poller";
 import { type SlotPhase } from "./slot-resolution";
+import {
+  onAuthed,
+  onInstallFresh,
+  onInstalled,
+  onPickActive,
+  onPickInactive,
+  onPollerActive,
+  onPollerTimeout,
+  onAuthStatus,
+  onReset,
+  type SlotCardState,
+} from "./slot-card-transitions";
 import { SlotDone } from "./slot-done";
 import { SlotInstallForm } from "./slot-install-form";
 import { SlotAuthOAuth } from "./slot-auth-oauth";
@@ -20,6 +32,24 @@ interface SlotCardProps {
   onComplete: (connectionId: string) => void;
 }
 
+/** Apply a partial state transition to the individual React state setters. */
+function applyTransition(
+  t: Partial<SlotCardState>,
+  setters: {
+    setPhase: (v: SlotPhase | null) => void;
+    setPollingConnectionId: (v: string | null) => void;
+    setSelectedConnection: (v: ConnectionEntity | null) => void;
+    setAuthCheckId: (v: string | null) => void;
+  },
+) {
+  if ("phase" in t) setters.setPhase(t.phase ?? null);
+  if ("pollingConnectionId" in t)
+    setters.setPollingConnectionId(t.pollingConnectionId ?? null);
+  if ("selectedConnection" in t)
+    setters.setSelectedConnection(t.selectedConnection ?? null);
+  if ("authCheckId" in t) setters.setAuthCheckId(t.authCheckId ?? null);
+}
+
 export function SlotCard({ slot, onComplete }: SlotCardProps) {
   const resolution = useSlotResolution(slot);
   const [phase, setPhase] = useState<SlotPhase | null>(null);
@@ -33,6 +63,13 @@ export function SlotCard({ slot, onComplete }: SlotCardProps) {
   // Prevents onComplete from firing more than once per unique connection
   const completedIdRef = useRef<string | null>(null);
 
+  const setters = {
+    setPhase,
+    setPollingConnectionId,
+    setSelectedConnection,
+    setAuthCheckId,
+  };
+
   const poller = useConnectionPoller(pollingConnectionId);
 
   const authUrl = authCheckId
@@ -53,9 +90,7 @@ export function SlotCard({ slot, onComplete }: SlotCardProps) {
   if (pollingConnectionId && poller.isActive && poller.connection) {
     if (completedIdRef.current !== poller.connection.id) {
       completedIdRef.current = poller.connection.id;
-      setPollingConnectionId(null);
-      setSelectedConnection(poller.connection);
-      setPhase("done");
+      applyTransition(onPollerActive(poller.connection), setters);
       onComplete(poller.connection.id);
     }
   }
@@ -65,9 +100,10 @@ export function SlotCard({ slot, onComplete }: SlotCardProps) {
     pollingConnectionId &&
     (poller.isTimedOut || poller.connection?.status === "error")
   ) {
-    if (poller.connection) setSelectedConnection(poller.connection);
-    setAuthCheckId(pollingConnectionId);
-    setPollingConnectionId(null);
+    applyTransition(
+      onPollerTimeout(pollingConnectionId, poller.connection ?? null),
+      setters,
+    );
   }
 
   // React to auth check result — set the appropriate auth phase
@@ -77,30 +113,23 @@ export function SlotCard({ slot, onComplete }: SlotCardProps) {
     phase !== "auth-oauth" &&
     phase !== "auth-token"
   ) {
-    setPhase(authStatus.supportsOAuth ? "auth-oauth" : "auth-token");
+    applyTransition(onAuthStatus(authStatus.supportsOAuth), setters);
   }
 
   const handleInstalled = (connectionId: string) => {
-    setPollingConnectionId(connectionId);
-    setPhase("polling");
+    applyTransition(onInstalled(connectionId), setters);
   };
 
   const handleAuthed = () => {
-    const id =
-      pollingConnectionId ?? selectedConnection?.id ?? authCheckId ?? null;
-    if (id) {
-      setAuthCheckId(null);
-      setPollingConnectionId(id);
-      setPhase("polling");
-    }
+    applyTransition(
+      onAuthed({ pollingConnectionId, selectedConnection, authCheckId }),
+      setters,
+    );
   };
 
   const handleReset = () => {
     const hasExisting = resolution.matchingConnections.length > 0;
-    setPhase(hasExisting ? "picker" : "install");
-    setSelectedConnection(null);
-    setPollingConnectionId(null);
-    setAuthCheckId(null);
+    applyTransition(onReset(hasExisting), setters);
     completedIdRef.current = null;
     onComplete("");
   };
@@ -158,13 +187,10 @@ export function SlotCard({ slot, onComplete }: SlotCardProps) {
                 type="button"
                 onClick={() => {
                   if (conn.status === "active") {
-                    setSelectedConnection(conn);
-                    setPhase("done");
+                    applyTransition(onPickActive(conn), setters);
                     onComplete(conn.id);
                   } else {
-                    setSelectedConnection(conn);
-                    setPollingConnectionId(conn.id);
-                    setPhase("polling");
+                    applyTransition(onPickInactive(conn), setters);
                   }
                 }}
                 className="w-full flex items-center justify-between rounded border px-3 py-2 text-sm hover:bg-accent transition-colors"
@@ -180,7 +206,7 @@ export function SlotCard({ slot, onComplete }: SlotCardProps) {
             variant="outline"
             size="sm"
             className="w-full"
-            onClick={() => setPhase("install")}
+            onClick={() => applyTransition(onInstallFresh(), setters)}
           >
             Install fresh
           </Button>
diff --git a/apps/mesh/src/web/components/connections-setup/use-slot-resolution.ts b/apps/mesh/src/web/components/connections-setup/use-slot-resolution.ts
index fa2c0eae20..e83393ac2b 100644
--- a/apps/mesh/src/web/components/connections-setup/use-slot-resolution.ts
+++ b/apps/mesh/src/web/components/connections-setup/use-slot-resolution.ts
@@ -52,7 +52,7 @@ export function useSlotResolution(slot: ConnectionSlot): SlotResolution {
         registryConn.id,
         org.id,
         listTool,
-        { where: { id: slot.item_id } },
+        { where: { appName: slot.item_id } },
       );
       const items = extractItemsFromResponse<RegistryItem>(result);
       return items[0] ?? null;
diff --git a/apps/mesh/src/web/routes/orgs/connections.tsx b/apps/mesh/src/web/routes/orgs/connections.tsx
index 67517f5a63..fe27e68395 100644
--- a/apps/mesh/src/web/routes/orgs/connections.tsx
+++ b/apps/mesh/src/web/routes/orgs/connections.tsx
@@ -1,4 +1,5 @@
 import { generatePrefixedId } from "@/shared/utils/generate-id";
+import { ConnectionsSetup } from "@/web/components/connections-setup";
 import { CollectionDisplayButton } from "@/web/components/collections/collection-display-button.tsx";
 import { CollectionSearch } from "@/web/components/collections/collection-search.tsx";
 import { CollectionTableWrapper } from "@/web/components/collections/collection-table-wrapper.tsx";
@@ -90,7 +91,7 @@ import {
   Terminal,
   Trash01,
 } from "@untitledui/icons";
-import { Suspense, useEffect, useReducer } from "react";
+import { Suspense, useEffect, useReducer, useState } from "react";
 import { useForm } from "react-hook-form";
 import { z } from "zod";
 import { formatTimeAgo } from "@/web/lib/format-time";
@@ -419,6 +420,7 @@ function OrgMcpsContent() {
   const connections = useConnections(listState);
 
   const [dialogState, dispatch] = useReducer(dialogReducer, { mode: "idle" });
+  const [isSetupOpen, setIsSetupOpen] = useState(false);
 
   // Optional registry lookup: use first available registry connection as a name/description source
   const registryConnection = useRegistryConnections(connections)[0];
@@ -1000,6 +1002,14 @@ function OrgMcpsContent() {
 
   const ctaButton = (
     <div className="flex items-center gap-2">
+      <Button
+        variant="outline"
+        onClick={() => setIsSetupOpen(true)}
+        size="sm"
+        className="h-7 px-3 rounded-lg text-sm font-medium"
+      >
+        Quick Setup
+      </Button>
       <Button
         variant="outline"
         onClick={() =>
@@ -1430,6 +1440,38 @@ function OrgMcpsContent() {
         </AlertDialogContent>
       </AlertDialog>
 
+      {/* Quick Setup Dialog */}
+      <Dialog open={isSetupOpen} onOpenChange={setIsSetupOpen}>
+        <DialogContent className="sm:max-w-lg">
+          <DialogHeader>
+            <DialogTitle>Quick Setup</DialogTitle>
+            <DialogDescription>
+              Install and authenticate a set of essential connections.
+            </DialogDescription>
+          </DialogHeader>
+          <ConnectionsSetup
+            slots={{
+              openrouter: {
+                label: "AI Model (OpenRouter)",
+                registry: "deco-registry",
+                item_id: "deco/openrouter",
+              },
+              github: {
+                label: "GitHub",
+                registry: "deco-registry",
+                item_id: "deco/github",
+              },
+              gmail: {
+                label: "Google Gmail",
+                registry: "deco-registry",
+                item_id: "deco/google-gmail",
+              },
+            }}
+            onComplete={() => setIsSetupOpen(false)}
+          />
+        </DialogContent>
+      </Dialog>
+
       {/* Page Header */}
       <Page.Header>
         <Page.Header.Left>
diff --git a/apps/mesh/src/web/utils/extract-connection-data.test.ts b/apps/mesh/src/web/utils/extract-connection-data.test.ts
new file mode 100644
index 0000000000..9184127758
--- /dev/null
+++ b/apps/mesh/src/web/utils/extract-connection-data.test.ts
@@ -0,0 +1,130 @@
+import { describe, expect, it } from "bun:test";
+import type { ConnectionEntity } from "@decocms/mesh-sdk";
+import type { RegistryItem } from "@/web/components/store/types";
+import { findMatchingConnections } from "@/web/components/connections-setup/slot-resolution";
+import { extractConnectionData } from "./extract-connection-data";
+
+const MCP_MESH_KEY = "mcp.mesh";
+
+function makeRegistryItem(overrides: Partial<RegistryItem> = {}): RegistryItem {
+  return {
+    id: "test-uuid-1234",
+    title: "Test MCP",
+    created_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+    server: {
+      name: "deco/test-mcp",
+      ...(overrides.server ?? {}),
+    },
+    ...overrides,
+  } as RegistryItem;
+}
+
+function makeConn(
+  overrides: Partial<ConnectionEntity> & {
+    metadata?: Record<string, unknown>;
+  } = {},
+): ConnectionEntity {
+  return {
+    id: "conn_test",
+    title: "Test",
+    status: "inactive",
+    connection_type: "HTTP",
+    connection_url: null,
+    connection_token: null,
+    connection_headers: null,
+    oauth_config: null,
+    configuration_state: null,
+    configuration_scopes: null,
+    description: null,
+    icon: null,
+    app_name: null,
+    app_id: null,
+    tools: null,
+    bindings: null,
+    organization_id: "org_1",
+    created_by: "user_1",
+    updated_by: "user_1",
+    created_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+    ...overrides,
+  } as unknown as ConnectionEntity;
+}
+
+// ── title extraction ────────────────────────────────────────────────────────
+
+describe("extractConnectionData title", () => {
+  it("uses friendlyName from mcp.mesh meta", () => {
+    const item = makeRegistryItem({
+      _meta: { [MCP_MESH_KEY]: { id: "some-id", friendlyName: "OpenRouter" } },
+    });
+    expect(extractConnectionData(item, "org_1", "user_1").title).toBe(
+      "OpenRouter",
+    );
+  });
+
+  it("falls back to item.title when no meta friendlyName", () => {
+    const item = makeRegistryItem({ title: "GitHub" });
+    expect(extractConnectionData(item, "org_1", "user_1").title).toBe("GitHub");
+  });
+
+  it("falls back to server.name when no item.title", () => {
+    const item = makeRegistryItem({
+      title: undefined,
+      server: { name: "deco/test" },
+    });
+    expect(extractConnectionData(item, "org_1", "user_1").title).toBe(
+      "deco/test",
+    );
+  });
+
+  it("always produces a non-empty title for any valid registry item", () => {
+    const data = extractConnectionData(makeRegistryItem(), "org_1", "user_1");
+    expect(data.title.length).toBeGreaterThan(0);
+  });
+});
+
+// ── registry_item_id ────────────────────────────────────────────────────────
+
+describe("extractConnectionData registry_item_id", () => {
+  it("uses server.name so it matches slot.item_id (appName format)", () => {
+    const item = makeRegistryItem({ server: { name: "deco/openrouter" } });
+    const data = extractConnectionData(item, "org_1", "user_1");
+    expect(data.metadata.registry_item_id).toBe("deco/openrouter");
+  });
+
+  it("round-trips: connections installed from a registry item are found by findMatchingConnections when searching by slot.item_id", () => {
+    const slotItemId = "deco/github";
+    const item = makeRegistryItem({ server: { name: slotItemId } });
+    const connectionData = extractConnectionData(item, "org_1", "user_1");
+
+    // Simulate what the DB stores after creation
+    const storedConn = makeConn({
+      metadata: {
+        registry_item_id: connectionData.metadata.registry_item_id,
+      },
+    });
+
+    // slot.item_id is the appName — must match what was stored
+    const matches = findMatchingConnections([storedConn], slotItemId);
+    expect(matches).toHaveLength(1);
+  });
+
+  it("falls back to item.id when server.name is absent", () => {
+    const item = makeRegistryItem({
+      id: "some-uuid-1234",
+      server: { name: undefined as unknown as string },
+    });
+    const data = extractConnectionData(item, "org_1", "user_1");
+    expect(data.metadata.registry_item_id).toBe("some-uuid-1234");
+  });
+
+  it("prefers mcp.mesh appName over server.name when present", () => {
+    const item = makeRegistryItem({
+      server: { name: "deco/openrouter" },
+      _meta: { [MCP_MESH_KEY]: { id: "some-id", appName: "deco/openrouter" } },
+    });
+    const data = extractConnectionData(item, "org_1", "user_1");
+    expect(data.metadata.registry_item_id).toBe("deco/openrouter");
+  });
+});
diff --git a/apps/mesh/src/web/utils/extract-connection-data.ts b/apps/mesh/src/web/utils/extract-connection-data.ts
index 646b439a25..b1dfe38761 100644
--- a/apps/mesh/src/web/utils/extract-connection-data.ts
+++ b/apps/mesh/src/web/utils/extract-connection-data.ts
@@ -192,7 +192,7 @@ export function extractConnectionData(
     configuration_scopes: configScopes ?? null,
     metadata: {
       source: "store",
-      registry_item_id: item.id,
+      registry_item_id: meshMeta?.appName || server?.name || item.id,
       verified: meshMeta?.verified ?? false,
       scopeName: meshMeta?.scopeName ?? null,
       toolsCount: meshMeta?.tools?.length ?? 0,
diff --git a/apps/mesh/test-setup-rtl.ts b/apps/mesh/test-setup-rtl.ts
new file mode 100644
index 0000000000..cab9cc8622
--- /dev/null
+++ b/apps/mesh/test-setup-rtl.ts
@@ -0,0 +1,11 @@
+// Step 2: extend Bun's expect with jest-dom matchers and register RTL cleanup.
+// Must run AFTER test-setup.ts so happy-dom is already active.
+import { afterEach, expect } from "bun:test";
+import { cleanup } from "@testing-library/react";
+import * as matchers from "@testing-library/jest-dom/matchers";
+
+expect.extend(matchers);
+
+afterEach(() => {
+  cleanup();
+});
diff --git a/apps/mesh/test-setup.ts b/apps/mesh/test-setup.ts
new file mode 100644
index 0000000000..52c0a5f0fd
--- /dev/null
+++ b/apps/mesh/test-setup.ts
@@ -0,0 +1,6 @@
+// Step 1: register happy-dom globals BEFORE any testing-library code loads.
+// This file is listed first in bunfig.toml [test] preload so DOM APIs are
+// available when test-setup-rtl.ts imports @testing-library/react.
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+
+GlobalRegistrator.register({ url: "http://localhost:3000" });
diff --git a/bunfig.toml b/bunfig.toml
new file mode 100644
index 0000000000..34c89bbbcc
--- /dev/null
+++ b/bunfig.toml
@@ -0,0 +1,2 @@
+[test]
+preload = ["./apps/mesh/test-setup.ts", "./apps/mesh/test-setup-rtl.ts"]

From ed8a2f4769584532ae385dc659c213d0cd8c81a3 Mon Sep 17 00:00:00 2001
From: viktormarinho <viktormpcs@gmail.com>
Date: Tue, 24 Feb 2026 17:28:49 -0300
Subject: [PATCH 19/21] fix(connections-setup): always check auth after poller
 goes active
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous state machine went straight to "done" when the poller saw
status === "active". This was wrong: many connections (Gmail, Google Docs,
etc.) become transport-active immediately after creation even without OAuth
— the MCP server responds 200 because it's reachable, but the connection
still needs an OAuth token to actually function.

The fix: onPollerActive now queues an auth check (exactly like onPollerTimeout)
instead of immediately marking the slot done. The auth check result then decides:

  active + supportsOAuth: true  → auth-oauth  (connection up, OAuth needed)
  active + supportsOAuth: false → done         (connection up, no auth needed)
  timeout + supportsOAuth: true  → auth-oauth  (same)
  timeout + supportsOAuth: false → auth-token  (not working, needs bearer token)

onAuthStatus now takes a required `source: "active" | "timeout"` parameter.
Tests and component updated to match.

Also removes the DOM component tests added in the previous commit — they
were mocking the hooks so they couldn't catch this class of real-world bug.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
---
 apps/mesh/package.json                        |   3 -
 apps/mesh/src/types/bun-testing.d.ts          |  14 -
 .../connections-setup.test.tsx                | 288 --------
 .../slot-card-transitions.test.ts             |  30 +-
 .../slot-card-transitions.ts                  |  31 +-
 .../connections-setup/slot-card.test.tsx      | 632 ------------------
 .../connections-setup/slot-card.tsx           |  44 +-
 apps/mesh/test-setup-rtl.ts                   |  11 -
 apps/mesh/test-setup.ts                       |   6 -
 bunfig.toml                                   |   2 -
 10 files changed, 80 insertions(+), 981 deletions(-)
 delete mode 100644 apps/mesh/src/types/bun-testing.d.ts
 delete mode 100644 apps/mesh/src/web/components/connections-setup/connections-setup.test.tsx
 delete mode 100644 apps/mesh/src/web/components/connections-setup/slot-card.test.tsx
 delete mode 100644 apps/mesh/test-setup-rtl.ts
 delete mode 100644 apps/mesh/test-setup.ts
 delete mode 100644 bunfig.toml

diff --git a/apps/mesh/package.json b/apps/mesh/package.json
index 99533d5613..df5491a867 100644
--- a/apps/mesh/package.json
+++ b/apps/mesh/package.json
@@ -54,7 +54,6 @@
     "@decocms/runtime": "workspace:*",
     "@decocms/vite-plugin": "workspace:*",
     "@floating-ui/react": "^0.27.16",
-    "@happy-dom/global-registrator": "^20.7.0",
     "@hookform/resolvers": "^5.2.2",
     "@modelcontextprotocol/sdk": "1.26.0",
     "@monaco-editor/react": "^4.7.0",
@@ -84,8 +83,6 @@
     "@tailwindcss/vite": "^4.1.17",
     "@tanstack/react-query": "5.90.11",
     "@tanstack/react-router": "^1.139.7",
-    "@testing-library/jest-dom": "^6.9.1",
-    "@testing-library/react": "^16.3.2",
     "@tiptap/core": "^3.15.3",
     "@tiptap/extension-mention": "^3.13.0",
     "@tiptap/extension-placeholder": "^3.15.3",
diff --git a/apps/mesh/src/types/bun-testing.d.ts b/apps/mesh/src/types/bun-testing.d.ts
deleted file mode 100644
index cee12a3835..0000000000
--- a/apps/mesh/src/types/bun-testing.d.ts
+++ /dev/null
@@ -1,14 +0,0 @@
-// Extend Bun's test Matchers with @testing-library/jest-dom matchers
-// so toBeInTheDocument(), toHaveTextContent(), etc. are properly typed.
-import type { TestingLibraryMatchers } from "@testing-library/jest-dom/matchers";
-import type { expect } from "bun:test";
-
-export {};
-
-declare module "bun:test" {
-  interface Matchers<T = unknown>
-    extends TestingLibraryMatchers<
-      ReturnType<typeof expect.stringContaining>,
-      T
-    > {}
-}
diff --git a/apps/mesh/src/web/components/connections-setup/connections-setup.test.tsx b/apps/mesh/src/web/components/connections-setup/connections-setup.test.tsx
deleted file mode 100644
index ad19c2c846..0000000000
--- a/apps/mesh/src/web/components/connections-setup/connections-setup.test.tsx
+++ /dev/null
@@ -1,288 +0,0 @@
-/// <reference lib="dom" />
-/// <reference types="@testing-library/jest-dom/matchers" />
-import { beforeEach, describe, expect, it, mock } from "bun:test";
-import { fireEvent, render, screen } from "@testing-library/react";
-import React from "react";
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import type { ConnectionEntity } from "@decocms/mesh-sdk";
-import type { SlotResolution } from "./use-slot-resolution";
-import type { ConnectionPollerResult } from "./use-connection-poller";
-
-// ── Module mocks ──────────────────────────────────────────────────────────────
-// NOTE: deliberately NOT mocking ./slot-card — ConnectionsSetup is tested with
-// the real SlotCard to avoid polluting the shared module registry for slot-card.test.tsx.
-
-const mockUseSlotResolution = mock(() => makeResolution());
-const mockUseConnectionPoller = mock(() => makePoller());
-const mockIsConnectionAuthenticated = mock(() =>
-  Promise.resolve({ supportsOAuth: false }),
-);
-
-mock.module("./use-slot-resolution", () => ({
-  useSlotResolution: mockUseSlotResolution,
-}));
-mock.module("./use-connection-poller", () => ({
-  useConnectionPoller: mockUseConnectionPoller,
-}));
-mock.module("@decocms/mesh-sdk", () => ({
-  isConnectionAuthenticated: mockIsConnectionAuthenticated,
-}));
-
-mock.module("./slot-install-form", () => ({
-  SlotInstallForm: ({ onInstalled }: { onInstalled: (id: string) => void }) =>
-    React.createElement(
-      "button",
-      { "data-testid": "install-btn", onClick: () => onInstalled("conn_new") },
-      "Install",
-    ),
-}));
-
-mock.module("./slot-done", () => ({
-  SlotDone: ({
-    label,
-    connection,
-    onReset,
-  }: {
-    label: string;
-    connection: ConnectionEntity;
-    onReset: () => void;
-  }) =>
-    React.createElement(
-      "div",
-      { "data-testid": `done-${label}` },
-      React.createElement(
-        "span",
-        { "data-testid": `done-title-${label}` },
-        connection.title,
-      ),
-      React.createElement(
-        "button",
-        { "data-testid": `change-${label}`, onClick: onReset },
-        "Change",
-      ),
-    ),
-}));
-
-mock.module("./slot-auth-oauth", () => ({
-  SlotAuthOAuth: ({ onAuthed }: { onAuthed: () => void }) =>
-    React.createElement("button", { onClick: onAuthed }, "Authorize"),
-}));
-
-mock.module("./slot-auth-token", () => ({
-  SlotAuthToken: ({ onAuthed }: { onAuthed: () => void }) =>
-    React.createElement("button", { onClick: onAuthed }, "Submit Token"),
-}));
-
-import { ConnectionsSetup } from "./connections-setup";
-
-// ── Helpers ───────────────────────────────────────────────────────────────────
-
-function makeConn(overrides: Partial<ConnectionEntity> = {}): ConnectionEntity {
-  return {
-    id: "conn_test",
-    title: "Test Connection",
-    status: "active",
-    connection_type: "HTTP",
-    connection_url: null,
-    connection_token: null,
-    connection_headers: null,
-    oauth_config: null,
-    configuration_state: null,
-    configuration_scopes: null,
-    description: null,
-    icon: null,
-    app_name: null,
-    app_id: null,
-    tools: null,
-    bindings: null,
-    organization_id: "org_1",
-    created_by: "user_1",
-    updated_by: "user_1",
-    created_at: new Date().toISOString(),
-    updated_at: new Date().toISOString(),
-    ...overrides,
-  } as unknown as ConnectionEntity;
-}
-
-function makeResolution(
-  overrides: Partial<SlotResolution> = {},
-): SlotResolution {
-  return {
-    initialPhase: "install",
-    registryItem: {
-      id: "item_1",
-      title: "Test MCP",
-      server: { name: "deco/test" },
-      created_at: "",
-      updated_at: "",
-    } as SlotResolution["registryItem"],
-    matchingConnections: [],
-    satisfiedConnection: null,
-    isLoading: false,
-    registryError: null,
-    ...overrides,
-  };
-}
-
-function makePoller(
-  overrides: Partial<ConnectionPollerResult> = {},
-): ConnectionPollerResult {
-  return {
-    connection: null,
-    isActive: false,
-    isTimedOut: false,
-    isPolling: false,
-    ...overrides,
-  };
-}
-
-function createWrapper() {
-  const queryClient = new QueryClient({
-    defaultOptions: { queries: { retry: false } },
-  });
-  return ({ children }: { children: React.ReactNode }) =>
-    React.createElement(QueryClientProvider, { client: queryClient }, children);
-}
-
-const twoSlots = {
-  model: {
-    label: "model",
-    registry: "deco-registry",
-    item_id: "deco/openrouter",
-  },
-  github: {
-    label: "github",
-    registry: "deco-registry",
-    item_id: "deco/github",
-  },
-};
-
-// Returns picker phase with a unique active connection per slot label so tests
-// can click individual slots by text even after re-renders.
-function setupPickerPerSlot() {
-  mockUseSlotResolution.mockImplementation(
-    // @ts-expect-error — Bun's mock type doesn't infer the slot arg but it is passed at runtime
-    (slot: ConnectionSlot) => {
-      const label = slot?.label ?? "unknown";
-      return makeResolution({
-        initialPhase: "picker",
-        matchingConnections: [
-          makeConn({
-            id: `conn_${label}`,
-            title: `${label}_conn`,
-            status: "active",
-          }),
-        ],
-      });
-    },
-  );
-}
-
-// ── Tests ─────────────────────────────────────────────────────────────────────
-
-beforeEach(() => {
-  mockUseSlotResolution.mockReset();
-  mockUseConnectionPoller.mockReset();
-  mockUseConnectionPoller.mockReturnValue(makePoller());
-  mockUseSlotResolution.mockReturnValue(
-    makeResolution({ initialPhase: "install" }),
-  );
-});
-
-describe("ConnectionsSetup", () => {
-  it("renders a card for each slot", () => {
-    render(
-      React.createElement(ConnectionsSetup, {
-        slots: twoSlots,
-        onComplete: () => {},
-      }),
-      { wrapper: createWrapper() },
-    );
-
-    // Both slots in install phase → each shows an install button
-    expect(screen.getAllByTestId("install-btn").length).toBe(2);
-  });
-
-  it("does not call onComplete when only one of two slots is satisfied", () => {
-    setupPickerPerSlot();
-    const onComplete = mock(() => {});
-
-    render(
-      React.createElement(ConnectionsSetup, { slots: twoSlots, onComplete }),
-      { wrapper: createWrapper() },
-    );
-
-    // Complete only the model slot
-    fireEvent.click(screen.getByText("model_conn"));
-
-    expect(onComplete).not.toHaveBeenCalled();
-  });
-
-  it("calls onComplete with slotId → connectionId map when all slots satisfy", () => {
-    setupPickerPerSlot();
-    const onComplete = mock(() => {});
-
-    render(
-      React.createElement(ConnectionsSetup, { slots: twoSlots, onComplete }),
-      { wrapper: createWrapper() },
-    );
-
-    fireEvent.click(screen.getByText("model_conn"));
-    fireEvent.click(screen.getByText("github_conn"));
-
-    expect(onComplete).toHaveBeenCalledTimes(1);
-    expect(onComplete).toHaveBeenCalledWith({
-      model: "conn_model",
-      github: "conn_github",
-    });
-  });
-
-  it("does not call onComplete a second time on re-renders after completion", () => {
-    setupPickerPerSlot();
-    const onComplete = mock(() => {});
-
-    const { rerender } = render(
-      React.createElement(ConnectionsSetup, { slots: twoSlots, onComplete }),
-      { wrapper: createWrapper() },
-    );
-
-    fireEvent.click(screen.getByText("model_conn"));
-    fireEvent.click(screen.getByText("github_conn"));
-
-    rerender(
-      React.createElement(ConnectionsSetup, { slots: twoSlots, onComplete }),
-    );
-    rerender(
-      React.createElement(ConnectionsSetup, { slots: twoSlots, onComplete }),
-    );
-
-    expect(onComplete).toHaveBeenCalledTimes(1);
-  });
-
-  it("calls onComplete again after a completed slot is reset and re-satisfied", () => {
-    setupPickerPerSlot();
-    const onComplete = mock(() => {});
-
-    render(
-      React.createElement(ConnectionsSetup, { slots: twoSlots, onComplete }),
-      { wrapper: createWrapper() },
-    );
-
-    // Complete both slots via picker
-    fireEvent.click(screen.getByText("model_conn"));
-    fireEvent.click(screen.getByText("github_conn"));
-    expect(onComplete).toHaveBeenCalledTimes(1);
-
-    // Reset model slot → goes back to picker (matchingConnections still exist)
-    fireEvent.click(screen.getByTestId("change-model"));
-
-    // Re-pick the active connection from the picker
-    fireEvent.click(screen.getByText("model_conn"));
-
-    expect(onComplete).toHaveBeenCalledTimes(2);
-    expect(onComplete).toHaveBeenLastCalledWith({
-      model: "conn_model",
-      github: "conn_github",
-    });
-  });
-});
diff --git a/apps/mesh/src/web/components/connections-setup/slot-card-transitions.test.ts b/apps/mesh/src/web/components/connections-setup/slot-card-transitions.test.ts
index beacd14bc6..bef309c894 100644
--- a/apps/mesh/src/web/components/connections-setup/slot-card-transitions.test.ts
+++ b/apps/mesh/src/web/components/connections-setup/slot-card-transitions.test.ts
@@ -50,9 +50,15 @@ describe("onInstalled", () => {
 });
 
 describe("onPollerActive", () => {
-  it("transitions to done", () => {
+  it("does NOT immediately go to done — queues an auth check instead", () => {
     const conn = makeConn({ id: "conn_abc", status: "active" });
-    expect(onPollerActive(conn).phase).toBe("done");
+    // phase must not be set here; the auth check will decide done vs auth-oauth
+    expect(onPollerActive(conn).phase).toBeUndefined();
+  });
+
+  it("sets authCheckId so the auth query fires", () => {
+    const conn = makeConn({ id: "conn_abc", status: "active" });
+    expect(onPollerActive(conn).authCheckId).toBe("conn_abc");
   });
 
   it("clears pollingConnectionId", () => {
@@ -88,12 +94,24 @@ describe("onPollerTimeout", () => {
 });
 
 describe("onAuthStatus", () => {
-  it("routes to auth-oauth when the endpoint supports OAuth", () => {
-    expect(onAuthStatus(true).phase).toBe("auth-oauth");
+  describe("source: active (poller confirmed connection is up)", () => {
+    it("routes to auth-oauth when OAuth is required", () => {
+      expect(onAuthStatus(true, "active").phase).toBe("auth-oauth");
+    });
+
+    it("routes to done when no OAuth required — connection is working", () => {
+      expect(onAuthStatus(false, "active").phase).toBe("done");
+    });
   });
 
-  it("routes to auth-token when the endpoint does not support OAuth", () => {
-    expect(onAuthStatus(false).phase).toBe("auth-token");
+  describe("source: timeout (connection never became active)", () => {
+    it("routes to auth-oauth when OAuth is required", () => {
+      expect(onAuthStatus(true, "timeout").phase).toBe("auth-oauth");
+    });
+
+    it("routes to auth-token when no OAuth — needs a bearer/API token", () => {
+      expect(onAuthStatus(false, "timeout").phase).toBe("auth-token");
+    });
   });
 });
 
diff --git a/apps/mesh/src/web/components/connections-setup/slot-card-transitions.ts b/apps/mesh/src/web/components/connections-setup/slot-card-transitions.ts
index 455d191468..a99ad3db55 100644
--- a/apps/mesh/src/web/components/connections-setup/slot-card-transitions.ts
+++ b/apps/mesh/src/web/components/connections-setup/slot-card-transitions.ts
@@ -16,14 +16,19 @@ export function onInstalled(connectionId: string): Partial<SlotCardState> {
   };
 }
 
-/** Poller observed the connection is active — mark slot as done. */
+/**
+ * Poller observed the connection is active at the transport level.
+ * We don't go to "done" yet — we always check auth first, because some
+ * connections (e.g. Gmail) respond 200 before OAuth is configured.
+ * onAuthStatus("active") then decides: no-OAuth → done, OAuth → auth-oauth.
+ */
 export function onPollerActive(
   connection: ConnectionEntity,
 ): Partial<SlotCardState> {
   return {
     pollingConnectionId: null,
     selectedConnection: connection,
-    phase: "done",
+    authCheckId: connection.id,
   };
 }
 
@@ -42,11 +47,23 @@ export function onPollerTimeout(
   };
 }
 
-/** Auth check completed — transition to the appropriate auth phase. */
-export function onAuthStatus(supportsOAuth: boolean): Partial<SlotCardState> {
-  return {
-    phase: supportsOAuth ? "auth-oauth" : "auth-token",
-  };
+/**
+ * Auth check completed.
+ *
+ * source "active"  → poller confirmed the connection is up
+ *   supportsOAuth: false → connection is working and needs no extra auth → done
+ *   supportsOAuth: true  → connection is up but OAuth token is required → auth-oauth
+ *
+ * source "timeout" → connection never became active on its own
+ *   supportsOAuth: false → needs a bearer/API token → auth-token
+ *   supportsOAuth: true  → needs OAuth → auth-oauth
+ */
+export function onAuthStatus(
+  supportsOAuth: boolean,
+  source: "active" | "timeout",
+): Partial<SlotCardState> {
+  if (supportsOAuth) return { phase: "auth-oauth" };
+  return { phase: source === "active" ? "done" : "auth-token" };
 }
 
 /** User completed auth — restart polling to verify the connection activates. */
diff --git a/apps/mesh/src/web/components/connections-setup/slot-card.test.tsx b/apps/mesh/src/web/components/connections-setup/slot-card.test.tsx
deleted file mode 100644
index 24f735ae78..0000000000
--- a/apps/mesh/src/web/components/connections-setup/slot-card.test.tsx
+++ /dev/null
@@ -1,632 +0,0 @@
-/// <reference lib="dom" />
-import { beforeEach, describe, expect, it, mock } from "bun:test";
-import { fireEvent, render, screen, waitFor } from "@testing-library/react";
-import React from "react";
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import type { ConnectionEntity } from "@decocms/mesh-sdk";
-import type { SlotResolution } from "./use-slot-resolution";
-import type { ConnectionPollerResult } from "./use-connection-poller";
-
-// ── Module mocks (hoisted by Bun before imports) ─────────────────────────────
-
-const mockUseSlotResolution = mock(() => makeResolution());
-const mockUseConnectionPoller = mock(() => makePoller());
-const mockIsConnectionAuthenticated = mock(() =>
-  Promise.resolve({ supportsOAuth: false }),
-);
-
-mock.module("./use-slot-resolution", () => ({
-  useSlotResolution: mockUseSlotResolution,
-}));
-
-mock.module("./use-connection-poller", () => ({
-  useConnectionPoller: mockUseConnectionPoller,
-}));
-
-mock.module("@decocms/mesh-sdk", () => ({
-  isConnectionAuthenticated: mockIsConnectionAuthenticated,
-}));
-
-// Stub child components — expose only what SlotCard passes to them
-mock.module("./slot-install-form", () => ({
-  SlotInstallForm: ({ onInstalled }: { onInstalled: (id: string) => void }) =>
-    React.createElement(
-      "button",
-      { "data-testid": "install-btn", onClick: () => onInstalled("conn_new") },
-      "Install",
-    ),
-}));
-
-mock.module("./slot-done", () => ({
-  SlotDone: ({
-    label,
-    connection,
-    onReset,
-  }: {
-    label: string;
-    connection: ConnectionEntity;
-    onReset: () => void;
-  }) =>
-    React.createElement(
-      "div",
-      { "data-testid": "slot-done" },
-      React.createElement("span", { "data-testid": "done-label" }, label),
-      React.createElement(
-        "span",
-        { "data-testid": "done-connection" },
-        connection.title,
-      ),
-      React.createElement(
-        "button",
-        { "data-testid": "change-btn", onClick: onReset },
-        "Change",
-      ),
-    ),
-}));
-
-mock.module("./slot-auth-oauth", () => ({
-  SlotAuthOAuth: ({
-    connectionId,
-    onAuthed,
-  }: {
-    connectionId: string;
-    onAuthed: () => void;
-  }) =>
-    React.createElement(
-      "button",
-      {
-        "data-testid": "oauth-btn",
-        "data-connection-id": connectionId,
-        onClick: onAuthed,
-      },
-      "Authorize",
-    ),
-}));
-
-mock.module("./slot-auth-token", () => ({
-  SlotAuthToken: ({
-    connectionId,
-    onAuthed,
-  }: {
-    connectionId: string;
-    onAuthed: () => void;
-  }) =>
-    React.createElement(
-      "button",
-      {
-        "data-testid": "token-btn",
-        "data-connection-id": connectionId,
-        onClick: onAuthed,
-      },
-      "Submit Token",
-    ),
-}));
-
-// ── Import component after mocks ─────────────────────────────────────────────
-
-// Bun hoists mock.module calls, so static import gets the mocked dependencies
-import { SlotCard } from "./slot-card";
-
-// ── Helpers ──────────────────────────────────────────────────────────────────
-
-function makeConn(
-  overrides: Partial<ConnectionEntity> & {
-    metadata?: Record<string, unknown>;
-  } = {},
-): ConnectionEntity {
-  return {
-    id: "conn_test",
-    title: "Test Connection",
-    status: "active",
-    connection_type: "HTTP",
-    connection_url: null,
-    connection_token: null,
-    connection_headers: null,
-    oauth_config: null,
-    configuration_state: null,
-    configuration_scopes: null,
-    description: null,
-    icon: null,
-    app_name: null,
-    app_id: null,
-    tools: null,
-    bindings: null,
-    organization_id: "org_1",
-    created_by: "user_1",
-    updated_by: "user_1",
-    created_at: new Date().toISOString(),
-    updated_at: new Date().toISOString(),
-    ...overrides,
-  } as unknown as ConnectionEntity;
-}
-
-function makeResolution(
-  overrides: Partial<SlotResolution> = {},
-): SlotResolution {
-  return {
-    initialPhase: "install",
-    registryItem: {
-      id: "item_1",
-      title: "Test MCP",
-      server: { name: "deco/test" },
-      created_at: "",
-      updated_at: "",
-    } as SlotResolution["registryItem"],
-    matchingConnections: [],
-    satisfiedConnection: null,
-    isLoading: false,
-    registryError: null,
-    ...overrides,
-  };
-}
-
-function makePoller(
-  overrides: Partial<ConnectionPollerResult> = {},
-): ConnectionPollerResult {
-  return {
-    connection: null,
-    isActive: false,
-    isTimedOut: false,
-    isPolling: false,
-    ...overrides,
-  };
-}
-
-function createWrapper() {
-  const queryClient = new QueryClient({
-    defaultOptions: { queries: { retry: false } },
-  });
-  return ({ children }: { children: React.ReactNode }) =>
-    React.createElement(QueryClientProvider, { client: queryClient }, children);
-}
-
-const slot = {
-  label: "Test MCP",
-  registry: "deco-registry",
-  item_id: "deco/test",
-};
-
-// ── Tests ─────────────────────────────────────────────────────────────────────
-
-beforeEach(() => {
-  mockUseSlotResolution.mockReset();
-  mockUseConnectionPoller.mockReset();
-  mockIsConnectionAuthenticated.mockReset();
-  mockIsConnectionAuthenticated.mockReturnValue(
-    Promise.resolve({ supportsOAuth: false }),
-  );
-});
-
-describe("SlotCard", () => {
-  describe("loading state", () => {
-    it("shows slot label and no form while registry item loads", () => {
-      mockUseSlotResolution.mockReturnValue(
-        makeResolution({ initialPhase: "loading", isLoading: true }),
-      );
-      mockUseConnectionPoller.mockReturnValue(makePoller());
-
-      render(React.createElement(SlotCard, { slot, onComplete: () => {} }), {
-        wrapper: createWrapper(),
-      });
-
-      expect(screen.getByText("Test MCP")).toBeInTheDocument();
-      expect(screen.queryByTestId("install-btn")).toBeNull();
-      expect(screen.queryByTestId("slot-done")).toBeNull();
-    });
-  });
-
-  describe("registry error state", () => {
-    it("shows the error message when the registry item is not found", () => {
-      mockUseSlotResolution.mockReturnValue(
-        makeResolution({ registryError: "Registry item not found." }),
-      );
-      mockUseConnectionPoller.mockReturnValue(makePoller());
-
-      render(React.createElement(SlotCard, { slot, onComplete: () => {} }), {
-        wrapper: createWrapper(),
-      });
-
-      expect(screen.getByText("Registry item not found.")).toBeInTheDocument();
-      expect(screen.queryByTestId("install-btn")).toBeNull();
-    });
-  });
-
-  describe("install phase", () => {
-    it("renders the install form when no existing connections", () => {
-      mockUseSlotResolution.mockReturnValue(
-        makeResolution({ initialPhase: "install" }),
-      );
-      mockUseConnectionPoller.mockReturnValue(makePoller());
-
-      render(React.createElement(SlotCard, { slot, onComplete: () => {} }), {
-        wrapper: createWrapper(),
-      });
-
-      expect(screen.getByTestId("install-btn")).toBeInTheDocument();
-    });
-
-    it("transitions to polling when the install form submits", () => {
-      mockUseSlotResolution.mockReturnValue(
-        makeResolution({ initialPhase: "install" }),
-      );
-      mockUseConnectionPoller.mockReturnValue(makePoller());
-
-      render(React.createElement(SlotCard, { slot, onComplete: () => {} }), {
-        wrapper: createWrapper(),
-      });
-
-      fireEvent.click(screen.getByTestId("install-btn"));
-
-      expect(screen.getByText("Connecting...")).toBeInTheDocument();
-      expect(screen.queryByTestId("install-btn")).toBeNull();
-    });
-  });
-
-  describe("polling phase", () => {
-    it("shows Connecting... spinner while polling", () => {
-      mockUseSlotResolution.mockReturnValue(
-        makeResolution({ initialPhase: "install" }),
-      );
-      mockUseConnectionPoller.mockReturnValue(makePoller({ isPolling: true }));
-
-      render(React.createElement(SlotCard, { slot, onComplete: () => {} }), {
-        wrapper: createWrapper(),
-      });
-      fireEvent.click(screen.getByTestId("install-btn"));
-
-      expect(screen.getByText("Connecting...")).toBeInTheDocument();
-    });
-
-    it("transitions to done and calls onComplete when the connection becomes active", () => {
-      const conn = makeConn({
-        id: "conn_abc",
-        title: "OpenRouter",
-        status: "active",
-      });
-      const onComplete = mock(() => {});
-
-      mockUseSlotResolution.mockReturnValue(
-        makeResolution({ initialPhase: "install" }),
-      );
-      mockUseConnectionPoller.mockReturnValue(makePoller());
-
-      const { rerender } = render(
-        React.createElement(SlotCard, { slot, onComplete }),
-        { wrapper: createWrapper() },
-      );
-      fireEvent.click(screen.getByTestId("install-btn"));
-
-      mockUseConnectionPoller.mockReturnValue(
-        makePoller({ isActive: true, connection: conn }),
-      );
-      rerender(React.createElement(SlotCard, { slot, onComplete }));
-
-      expect(screen.getByTestId("done-connection")).toHaveTextContent(
-        "OpenRouter",
-      );
-      expect(onComplete).toHaveBeenCalledTimes(1);
-      expect(onComplete).toHaveBeenCalledWith("conn_abc");
-    });
-
-    it("only calls onComplete once across multiple re-renders with the same active connection", () => {
-      const conn = makeConn({ id: "conn_abc", status: "active" });
-      const onComplete = mock(() => {});
-
-      mockUseSlotResolution.mockReturnValue(
-        makeResolution({ initialPhase: "install" }),
-      );
-      mockUseConnectionPoller.mockReturnValue(makePoller());
-
-      const { rerender } = render(
-        React.createElement(SlotCard, { slot, onComplete }),
-        { wrapper: createWrapper() },
-      );
-      // Click install to set pollingConnectionId, then poller goes active
-      fireEvent.click(screen.getByTestId("install-btn"));
-
-      mockUseConnectionPoller.mockReturnValue(
-        makePoller({ isActive: true, connection: conn }),
-      );
-      rerender(React.createElement(SlotCard, { slot, onComplete }));
-      rerender(React.createElement(SlotCard, { slot, onComplete }));
-      rerender(React.createElement(SlotCard, { slot, onComplete }));
-
-      expect(onComplete).toHaveBeenCalledTimes(1);
-    });
-  });
-
-  describe("auth-oauth phase", () => {
-    it("shows OAuth button when polling times out and endpoint supports OAuth", async () => {
-      const conn = makeConn({ id: "conn_auth", status: "inactive" });
-      mockIsConnectionAuthenticated.mockResolvedValue({ supportsOAuth: true });
-
-      mockUseSlotResolution.mockReturnValue(
-        makeResolution({ initialPhase: "install" }),
-      );
-      mockUseConnectionPoller.mockReturnValue(makePoller());
-
-      const { rerender } = render(
-        React.createElement(SlotCard, { slot, onComplete: () => {} }),
-        { wrapper: createWrapper() },
-      );
-      fireEvent.click(screen.getByTestId("install-btn"));
-
-      mockUseConnectionPoller.mockReturnValue(
-        makePoller({ isTimedOut: true, connection: conn }),
-      );
-      rerender(React.createElement(SlotCard, { slot, onComplete: () => {} }));
-
-      await waitFor(() =>
-        expect(screen.getByTestId("oauth-btn")).toBeInTheDocument(),
-      );
-    });
-
-    it("shows OAuth button even when the poller never fetched a connection entity (null connection fix)", async () => {
-      mockIsConnectionAuthenticated.mockResolvedValue({ supportsOAuth: true });
-
-      mockUseSlotResolution.mockReturnValue(
-        makeResolution({ initialPhase: "install" }),
-      );
-      mockUseConnectionPoller.mockReturnValue(makePoller());
-
-      const { rerender } = render(
-        React.createElement(SlotCard, { slot, onComplete: () => {} }),
-        { wrapper: createWrapper() },
-      );
-      fireEvent.click(screen.getByTestId("install-btn"));
-
-      // connection is null — this was the "stuck state" bug
-      mockUseConnectionPoller.mockReturnValue(
-        makePoller({ isTimedOut: true, connection: null }),
-      );
-      rerender(React.createElement(SlotCard, { slot, onComplete: () => {} }));
-
-      await waitFor(() =>
-        expect(screen.getByTestId("oauth-btn")).toBeInTheDocument(),
-      );
-    });
-
-    it("returns to polling after OAuth completes", async () => {
-      const conn = makeConn({ id: "conn_auth" });
-      mockIsConnectionAuthenticated.mockResolvedValue({ supportsOAuth: true });
-
-      mockUseSlotResolution.mockReturnValue(
-        makeResolution({ initialPhase: "install" }),
-      );
-      mockUseConnectionPoller.mockReturnValue(makePoller());
-
-      const { rerender } = render(
-        React.createElement(SlotCard, { slot, onComplete: () => {} }),
-        { wrapper: createWrapper() },
-      );
-      fireEvent.click(screen.getByTestId("install-btn"));
-
-      mockUseConnectionPoller.mockReturnValue(
-        makePoller({ isTimedOut: true, connection: conn }),
-      );
-      rerender(React.createElement(SlotCard, { slot, onComplete: () => {} }));
-
-      await waitFor(() => screen.getByTestId("oauth-btn"));
-      fireEvent.click(screen.getByTestId("oauth-btn"));
-
-      expect(screen.getByText("Connecting...")).toBeInTheDocument();
-    });
-  });
-
-  describe("auth-token phase", () => {
-    it("shows token input when polling times out and endpoint does not support OAuth", async () => {
-      const conn = makeConn({ id: "conn_token" });
-      mockIsConnectionAuthenticated.mockResolvedValue({ supportsOAuth: false });
-
-      mockUseSlotResolution.mockReturnValue(
-        makeResolution({ initialPhase: "install" }),
-      );
-      mockUseConnectionPoller.mockReturnValue(makePoller());
-
-      const { rerender } = render(
-        React.createElement(SlotCard, { slot, onComplete: () => {} }),
-        { wrapper: createWrapper() },
-      );
-      fireEvent.click(screen.getByTestId("install-btn"));
-
-      mockUseConnectionPoller.mockReturnValue(
-        makePoller({ isTimedOut: true, connection: conn }),
-      );
-      rerender(React.createElement(SlotCard, { slot, onComplete: () => {} }));
-
-      await waitFor(() =>
-        expect(screen.getByTestId("token-btn")).toBeInTheDocument(),
-      );
-    });
-
-    it("returns to polling after token auth completes", async () => {
-      const conn = makeConn({ id: "conn_token" });
-      mockIsConnectionAuthenticated.mockResolvedValue({ supportsOAuth: false });
-
-      mockUseSlotResolution.mockReturnValue(
-        makeResolution({ initialPhase: "install" }),
-      );
-      mockUseConnectionPoller.mockReturnValue(makePoller());
-
-      const { rerender } = render(
-        React.createElement(SlotCard, { slot, onComplete: () => {} }),
-        { wrapper: createWrapper() },
-      );
-      fireEvent.click(screen.getByTestId("install-btn"));
-
-      mockUseConnectionPoller.mockReturnValue(
-        makePoller({ isTimedOut: true, connection: conn }),
-      );
-      rerender(React.createElement(SlotCard, { slot, onComplete: () => {} }));
-
-      await waitFor(() => screen.getByTestId("token-btn"));
-      fireEvent.click(screen.getByTestId("token-btn"));
-
-      expect(screen.getByText("Connecting...")).toBeInTheDocument();
-    });
-  });
-
-  describe("done phase", () => {
-    it("shows the done card when an existing connection is already active", () => {
-      const conn = makeConn({ id: "conn_abc", title: "OpenRouter" });
-      mockUseSlotResolution.mockReturnValue(
-        makeResolution({ initialPhase: "done", satisfiedConnection: conn }),
-      );
-      mockUseConnectionPoller.mockReturnValue(makePoller());
-
-      render(React.createElement(SlotCard, { slot, onComplete: () => {} }), {
-        wrapper: createWrapper(),
-      });
-
-      expect(screen.getByTestId("done-connection")).toHaveTextContent(
-        "OpenRouter",
-      );
-    });
-
-    it("goes to picker when Change is clicked and existing connections are present", () => {
-      const conn = makeConn({ id: "conn_abc", title: "OpenRouter" });
-      mockUseSlotResolution.mockReturnValue(
-        makeResolution({
-          initialPhase: "done",
-          satisfiedConnection: conn,
-          matchingConnections: [conn],
-        }),
-      );
-      mockUseConnectionPoller.mockReturnValue(makePoller());
-
-      render(React.createElement(SlotCard, { slot, onComplete: () => {} }), {
-        wrapper: createWrapper(),
-      });
-      fireEvent.click(screen.getByTestId("change-btn"));
-
-      expect(screen.getByText("Already installed:")).toBeInTheDocument();
-    });
-
-    it("goes to install when Change is clicked and no existing connections remain", () => {
-      const conn = makeConn({ id: "conn_abc", title: "OpenRouter" });
-      mockUseSlotResolution.mockReturnValue(
-        makeResolution({
-          initialPhase: "done",
-          satisfiedConnection: conn,
-          matchingConnections: [],
-        }),
-      );
-      mockUseConnectionPoller.mockReturnValue(makePoller());
-
-      render(React.createElement(SlotCard, { slot, onComplete: () => {} }), {
-        wrapper: createWrapper(),
-      });
-      fireEvent.click(screen.getByTestId("change-btn"));
-
-      expect(screen.getByTestId("install-btn")).toBeInTheDocument();
-    });
-
-    it("calls onComplete with empty string when the user resets", () => {
-      const conn = makeConn({ id: "conn_abc" });
-      const onComplete = mock(() => {});
-      mockUseSlotResolution.mockReturnValue(
-        makeResolution({
-          initialPhase: "done",
-          satisfiedConnection: conn,
-          matchingConnections: [],
-        }),
-      );
-      mockUseConnectionPoller.mockReturnValue(makePoller());
-
-      render(React.createElement(SlotCard, { slot, onComplete }), {
-        wrapper: createWrapper(),
-      });
-      fireEvent.click(screen.getByTestId("change-btn"));
-
-      expect(onComplete).toHaveBeenCalledWith("");
-    });
-  });
-
-  describe("picker phase", () => {
-    it("lists all matching connections", () => {
-      const conns = [
-        makeConn({ id: "conn_1", title: "OpenRouter #1", status: "active" }),
-        makeConn({ id: "conn_2", title: "OpenRouter #2", status: "inactive" }),
-      ];
-      mockUseSlotResolution.mockReturnValue(
-        makeResolution({ initialPhase: "picker", matchingConnections: conns }),
-      );
-      mockUseConnectionPoller.mockReturnValue(makePoller());
-
-      render(React.createElement(SlotCard, { slot, onComplete: () => {} }), {
-        wrapper: createWrapper(),
-      });
-
-      expect(screen.getByText("OpenRouter #1")).toBeInTheDocument();
-      expect(screen.getByText("OpenRouter #2")).toBeInTheDocument();
-    });
-
-    it("transitions to done and calls onComplete when an active connection is selected", () => {
-      const conn = makeConn({
-        id: "conn_active",
-        title: "OpenRouter",
-        status: "active",
-      });
-      const onComplete = mock(() => {});
-      mockUseSlotResolution.mockReturnValue(
-        makeResolution({
-          initialPhase: "picker",
-          matchingConnections: [conn],
-        }),
-      );
-      mockUseConnectionPoller.mockReturnValue(makePoller());
-
-      render(React.createElement(SlotCard, { slot, onComplete }), {
-        wrapper: createWrapper(),
-      });
-      fireEvent.click(screen.getByText("OpenRouter"));
-
-      expect(screen.getByTestId("slot-done")).toBeTruthy();
-      expect(onComplete).toHaveBeenCalledWith("conn_active");
-    });
-
-    it("starts polling when an inactive connection is selected", () => {
-      const conn = makeConn({
-        id: "conn_inactive",
-        title: "OpenRouter",
-        status: "inactive",
-      });
-      mockUseSlotResolution.mockReturnValue(
-        makeResolution({
-          initialPhase: "picker",
-          matchingConnections: [conn],
-        }),
-      );
-      mockUseConnectionPoller.mockReturnValue(makePoller());
-
-      render(React.createElement(SlotCard, { slot, onComplete: () => {} }), {
-        wrapper: createWrapper(),
-      });
-      fireEvent.click(screen.getByText("OpenRouter"));
-
-      expect(screen.getByText("Connecting...")).toBeTruthy();
-    });
-
-    it("transitions to install when Install fresh is clicked", () => {
-      const conn = makeConn({
-        id: "conn_1",
-        title: "OpenRouter",
-        status: "active",
-      });
-      mockUseSlotResolution.mockReturnValue(
-        makeResolution({
-          initialPhase: "picker",
-          matchingConnections: [conn],
-        }),
-      );
-      mockUseConnectionPoller.mockReturnValue(makePoller());
-
-      render(React.createElement(SlotCard, { slot, onComplete: () => {} }), {
-        wrapper: createWrapper(),
-      });
-      fireEvent.click(screen.getByText("Install fresh"));
-
-      expect(screen.getByTestId("install-btn")).toBeInTheDocument();
-    });
-  });
-});
diff --git a/apps/mesh/src/web/components/connections-setup/slot-card.tsx b/apps/mesh/src/web/components/connections-setup/slot-card.tsx
index 47928c1e32..64ef173d2c 100644
--- a/apps/mesh/src/web/components/connections-setup/slot-card.tsx
+++ b/apps/mesh/src/web/components/connections-setup/slot-card.tsx
@@ -11,6 +11,7 @@ import { useSlotResolution, type ConnectionSlot } from "./use-slot-resolution";
 import { useConnectionPoller } from "./use-connection-poller";
 import { type SlotPhase } from "./slot-resolution";
 import {
+  onAuthStatus,
   onAuthed,
   onInstallFresh,
   onInstalled,
@@ -18,7 +19,6 @@ import {
   onPickInactive,
   onPollerActive,
   onPollerTimeout,
-  onAuthStatus,
   onReset,
   type SlotCardState,
 } from "./slot-card-transitions";
@@ -58,8 +58,12 @@ export function SlotCard({ slot, onComplete }: SlotCardProps) {
   );
   const [selectedConnection, setSelectedConnection] =
     useState<ConnectionEntity | null>(null);
-  // Tracks which connection needs an auth check after polling times out/errors
+  // ID of the connection whose auth status is being checked
   const [authCheckId, setAuthCheckId] = useState<string | null>(null);
+
+  // Tracks whether the auth check was triggered by an active poller ("active")
+  // or a timeout/error ("timeout"). Determines the done-vs-auth-token outcome.
+  const authCheckSourceRef = useRef<"active" | "timeout">("timeout");
   // Prevents onComplete from firing more than once per unique connection
   const completedIdRef = useRef<string | null>(null);
 
@@ -86,34 +90,50 @@ export function SlotCard({ slot, onComplete }: SlotCardProps) {
   // Derive effective phase: explicit override takes priority, else from resolution
   const effectivePhase: SlotPhase = phase ?? resolution.initialPhase;
 
-  // React to poller becoming active
+  // React to poller becoming active — always check auth before marking done.
+  // Some connections (e.g. Gmail) respond 200 at the transport level even
+  // without OAuth, so we can't trust "active" to mean "authenticated".
   if (pollingConnectionId && poller.isActive && poller.connection) {
-    if (completedIdRef.current !== poller.connection.id) {
-      completedIdRef.current = poller.connection.id;
-      applyTransition(onPollerActive(poller.connection), setters);
-      onComplete(poller.connection.id);
-    }
+    authCheckSourceRef.current = "active";
+    applyTransition(onPollerActive(poller.connection), setters);
   }
 
-  // React to poller timeout/error — queue an auth check instead of firing async in render
+  // React to poller timeout/error — check auth to determine token vs OAuth
   if (
     pollingConnectionId &&
     (poller.isTimedOut || poller.connection?.status === "error")
   ) {
+    authCheckSourceRef.current = "timeout";
     applyTransition(
       onPollerTimeout(pollingConnectionId, poller.connection ?? null),
       setters,
     );
   }
 
-  // React to auth check result — set the appropriate auth phase
+  // React to auth check result
   if (
     authCheckId &&
     authStatus &&
     phase !== "auth-oauth" &&
-    phase !== "auth-token"
+    phase !== "auth-token" &&
+    phase !== "done"
   ) {
-    applyTransition(onAuthStatus(authStatus.supportsOAuth), setters);
+    const source = authCheckSourceRef.current;
+    const connId = selectedConnection?.id ?? authCheckId;
+
+    if (authStatus.supportsOAuth) {
+      applyTransition(onAuthStatus(true, source), setters);
+    } else if (source === "active") {
+      // Connection is up and needs no OAuth — it's truly ready
+      if (completedIdRef.current !== connId) {
+        completedIdRef.current = connId;
+        applyTransition(onAuthStatus(false, "active"), setters);
+        onComplete(connId);
+      }
+    } else {
+      // Timed out and no OAuth — needs a bearer/API token
+      applyTransition(onAuthStatus(false, "timeout"), setters);
+    }
   }
 
   const handleInstalled = (connectionId: string) => {
diff --git a/apps/mesh/test-setup-rtl.ts b/apps/mesh/test-setup-rtl.ts
deleted file mode 100644
index cab9cc8622..0000000000
--- a/apps/mesh/test-setup-rtl.ts
+++ /dev/null
@@ -1,11 +0,0 @@
-// Step 2: extend Bun's expect with jest-dom matchers and register RTL cleanup.
-// Must run AFTER test-setup.ts so happy-dom is already active.
-import { afterEach, expect } from "bun:test";
-import { cleanup } from "@testing-library/react";
-import * as matchers from "@testing-library/jest-dom/matchers";
-
-expect.extend(matchers);
-
-afterEach(() => {
-  cleanup();
-});
diff --git a/apps/mesh/test-setup.ts b/apps/mesh/test-setup.ts
deleted file mode 100644
index 52c0a5f0fd..0000000000
--- a/apps/mesh/test-setup.ts
+++ /dev/null
@@ -1,6 +0,0 @@
-// Step 1: register happy-dom globals BEFORE any testing-library code loads.
-// This file is listed first in bunfig.toml [test] preload so DOM APIs are
-// available when test-setup-rtl.ts imports @testing-library/react.
-import { GlobalRegistrator } from "@happy-dom/global-registrator";
-
-GlobalRegistrator.register({ url: "http://localhost:3000" });
diff --git a/bunfig.toml b/bunfig.toml
deleted file mode 100644
index 34c89bbbcc..0000000000
--- a/bunfig.toml
+++ /dev/null
@@ -1,2 +0,0 @@
-[test]
-preload = ["./apps/mesh/test-setup.ts", "./apps/mesh/test-setup-rtl.ts"]

From d98b5ee90689d6f26e22f463a395709fb4db5786 Mon Sep 17 00:00:00 2001
From: viktormarinho <viktormpcs@gmail.com>
Date: Tue, 24 Feb 2026 17:35:30 -0300
Subject: [PATCH 20/21] fix(connections-setup): detect OAuth need via
 oauth_config, not just 401+WWW-Auth
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

isConnectionAuthenticated() only sets supportsOAuth:true when the server returns
a 401 with a WWW-Authenticate header. Many OAuth services (e.g. Gmail) respond
200 to the MCP initialize call even without a token — so supportsOAuth was always
false and the slot incorrectly transitioned to "done".

The fix: replace onAuthStatus(supportsOAuth, source) with resolveAuthPhase() which
checks the connection's own oauth_config field alongside hasOAuthToken:

  if (connection.oauth_config && !hasOAuthToken) → auth-oauth
  if (!isAuthenticated && supportsOAuth)          → auth-oauth  (explicit 401 challenge)
  if (source === "active" && isAuthenticated)     → done
  otherwise                                        → auth-token

Tests updated to cover the Gmail case explicitly:
  active + oauth_config + no token → auth-oauth  ✓
  active + oauth_config + has token → done        ✓
  active + no oauth_config → done                 ✓
  timeout + no oauth_config → auth-token          ✓
  any + 401+WWW-Auth → auth-oauth                 ✓

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
---
 .../slot-card-transitions.test.ts             | 101 +++++++++++++++---
 .../slot-card-transitions.ts                  |  39 ++++---
 .../connections-setup/slot-card.tsx           |  14 ++-
 3 files changed, 121 insertions(+), 33 deletions(-)

diff --git a/apps/mesh/src/web/components/connections-setup/slot-card-transitions.test.ts b/apps/mesh/src/web/components/connections-setup/slot-card-transitions.test.ts
index bef309c894..abb28e2bfc 100644
--- a/apps/mesh/src/web/components/connections-setup/slot-card-transitions.test.ts
+++ b/apps/mesh/src/web/components/connections-setup/slot-card-transitions.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, it } from "bun:test";
 import type { ConnectionEntity } from "@decocms/mesh-sdk";
+import type { McpAuthStatus } from "@decocms/mesh-sdk";
 import {
   onAuthed,
   onInstallFresh,
@@ -8,7 +9,7 @@ import {
   onPickInactive,
   onPollerActive,
   onPollerTimeout,
-  onAuthStatus,
+  resolveAuthPhase,
   onReset,
 } from "./slot-card-transitions";
 
@@ -93,24 +94,100 @@ describe("onPollerTimeout", () => {
   });
 });
 
-describe("onAuthStatus", () => {
-  describe("source: active (poller confirmed connection is up)", () => {
-    it("routes to auth-oauth when OAuth is required", () => {
-      expect(onAuthStatus(true, "active").phase).toBe("auth-oauth");
+// Helper to build a McpAuthStatus quickly
+function makeAuthStatus(overrides: Partial<McpAuthStatus> = {}): McpAuthStatus {
+  return {
+    isAuthenticated: true,
+    supportsOAuth: false,
+    hasOAuthToken: false,
+    ...overrides,
+  };
+}
+
+describe("resolveAuthPhase", () => {
+  describe("connections with oauth_config (e.g. Gmail)", () => {
+    // Cast because OAuthConfig shape is complex — we just need it to be non-null
+    const oauthConn = {
+      ...makeConn(),
+      oauth_config: {},
+    } as unknown as ConnectionEntity;
+
+    it("returns auth-oauth when connection has oauth_config but no token yet — even if server returned 200", () => {
+      // Gmail initialize returns 200 without a token, so supportsOAuth is false,
+      // but we detect the need via oauth_config + !hasOAuthToken.
+      const status = makeAuthStatus({
+        isAuthenticated: true,
+        supportsOAuth: false,
+        hasOAuthToken: false,
+      });
+      expect(resolveAuthPhase(status, oauthConn, "active")).toBe("auth-oauth");
+    });
+
+    it("returns done once OAuth token has been obtained", () => {
+      const status = makeAuthStatus({
+        isAuthenticated: true,
+        supportsOAuth: false,
+        hasOAuthToken: true,
+      });
+      expect(resolveAuthPhase(status, oauthConn, "active")).toBe("done");
     });
+  });
+
+  describe("connections without oauth_config (e.g. simple HTTP MCPs)", () => {
+    const simpleConn = makeConn();
+
+    it("returns done when active and no auth needed", () => {
+      const status = makeAuthStatus({
+        isAuthenticated: true,
+        supportsOAuth: false,
+        hasOAuthToken: false,
+      });
+      expect(resolveAuthPhase(status, simpleConn, "active")).toBe("done");
+    });
+
+    it("returns auth-token when timed out with no OAuth cues", () => {
+      const status = makeAuthStatus({
+        isAuthenticated: false,
+        supportsOAuth: false,
+        hasOAuthToken: false,
+      });
+      expect(resolveAuthPhase(status, simpleConn, "timeout")).toBe(
+        "auth-token",
+      );
+    });
+  });
 
-    it("routes to done when no OAuth required — connection is working", () => {
-      expect(onAuthStatus(false, "active").phase).toBe("done");
+  describe("connections that return 401 + WWW-Authenticate (explicit OAuth challenge)", () => {
+    it("returns auth-oauth regardless of oauth_config when server returns OAuth challenge", () => {
+      const status = makeAuthStatus({
+        isAuthenticated: false,
+        supportsOAuth: true,
+        hasOAuthToken: false,
+      });
+      expect(
+        resolveAuthPhase(status, makeConn({ oauth_config: null }), "active"),
+      ).toBe("auth-oauth");
+      expect(
+        resolveAuthPhase(status, makeConn({ oauth_config: null }), "timeout"),
+      ).toBe("auth-oauth");
     });
   });
 
-  describe("source: timeout (connection never became active)", () => {
-    it("routes to auth-oauth when OAuth is required", () => {
-      expect(onAuthStatus(true, "timeout").phase).toBe("auth-oauth");
+  describe("null selectedConnection (entity not fetched before timeout)", () => {
+    it("returns auth-token when timed out with no info", () => {
+      const status = makeAuthStatus({
+        isAuthenticated: false,
+        supportsOAuth: false,
+      });
+      expect(resolveAuthPhase(status, null, "timeout")).toBe("auth-token");
     });
 
-    it("routes to auth-token when no OAuth — needs a bearer/API token", () => {
-      expect(onAuthStatus(false, "timeout").phase).toBe("auth-token");
+    it("returns auth-oauth when server signals OAuth on timeout", () => {
+      const status = makeAuthStatus({
+        isAuthenticated: false,
+        supportsOAuth: true,
+      });
+      expect(resolveAuthPhase(status, null, "timeout")).toBe("auth-oauth");
     });
   });
 });
diff --git a/apps/mesh/src/web/components/connections-setup/slot-card-transitions.ts b/apps/mesh/src/web/components/connections-setup/slot-card-transitions.ts
index a99ad3db55..980987eb2e 100644
--- a/apps/mesh/src/web/components/connections-setup/slot-card-transitions.ts
+++ b/apps/mesh/src/web/components/connections-setup/slot-card-transitions.ts
@@ -1,4 +1,4 @@
-import type { ConnectionEntity } from "@decocms/mesh-sdk";
+import type { ConnectionEntity, McpAuthStatus } from "@decocms/mesh-sdk";
 import type { SlotPhase } from "./slot-resolution";
 
 export type SlotCardState = {
@@ -48,22 +48,35 @@ export function onPollerTimeout(
 }
 
 /**
- * Auth check completed.
+ * Determine which auth phase to enter after the auth check completes.
  *
- * source "active"  → poller confirmed the connection is up
- *   supportsOAuth: false → connection is working and needs no extra auth → done
- *   supportsOAuth: true  → connection is up but OAuth token is required → auth-oauth
+ * source "active"  — poller confirmed the connection responds to initialize.
+ *   OAuth needed?   → "auth-oauth"  (connection has oauth_config but no token yet,
+ *                                    OR server returned 401 + WWW-Authenticate)
+ *   No auth needed  → "done"        (working without auth, or OAuth already done)
  *
- * source "timeout" → connection never became active on its own
- *   supportsOAuth: false → needs a bearer/API token → auth-token
- *   supportsOAuth: true  → needs OAuth → auth-oauth
+ * source "timeout" — connection never became active before the poll timeout.
+ *   OAuth needed?   → "auth-oauth"
+ *   No OAuth cue    → "auth-token"  (not working; probably needs an API token)
+ *
+ * NOTE: supportsOAuth is only reliable when the server returns 401 + WWW-Authenticate.
+ * Many services (e.g. Gmail) accept initialize without auth, so we also check
+ * connection.oauth_config + hasOAuthToken to catch the "active but needs OAuth" case.
  */
-export function onAuthStatus(
-  supportsOAuth: boolean,
+export function resolveAuthPhase(
+  authStatus: McpAuthStatus,
+  selectedConnection: ConnectionEntity | null,
   source: "active" | "timeout",
-): Partial<SlotCardState> {
-  if (supportsOAuth) return { phase: "auth-oauth" };
-  return { phase: source === "active" ? "done" : "auth-token" };
+): "auth-oauth" | "auth-token" | "done" {
+  const needsOAuth =
+    // Connection was created with OAuth config and the token hasn't been obtained yet
+    (!!selectedConnection?.oauth_config && !authStatus.hasOAuthToken) ||
+    // Server returned 401 + WWW-Authenticate (the reliable OAuth detection path)
+    (!authStatus.isAuthenticated && authStatus.supportsOAuth);
+
+  if (needsOAuth) return "auth-oauth";
+  if (source === "active" && authStatus.isAuthenticated) return "done";
+  return "auth-token";
 }
 
 /** User completed auth — restart polling to verify the connection activates. */
diff --git a/apps/mesh/src/web/components/connections-setup/slot-card.tsx b/apps/mesh/src/web/components/connections-setup/slot-card.tsx
index 64ef173d2c..62f6f60693 100644
--- a/apps/mesh/src/web/components/connections-setup/slot-card.tsx
+++ b/apps/mesh/src/web/components/connections-setup/slot-card.tsx
@@ -11,7 +11,7 @@ import { useSlotResolution, type ConnectionSlot } from "./use-slot-resolution";
 import { useConnectionPoller } from "./use-connection-poller";
 import { type SlotPhase } from "./slot-resolution";
 import {
-  onAuthStatus,
+  resolveAuthPhase,
   onAuthed,
   onInstallFresh,
   onInstalled,
@@ -120,19 +120,17 @@ export function SlotCard({ slot, onComplete }: SlotCardProps) {
   ) {
     const source = authCheckSourceRef.current;
     const connId = selectedConnection?.id ?? authCheckId;
+    const nextPhase = resolveAuthPhase(authStatus, selectedConnection, source);
 
-    if (authStatus.supportsOAuth) {
-      applyTransition(onAuthStatus(true, source), setters);
-    } else if (source === "active") {
-      // Connection is up and needs no OAuth — it's truly ready
+    if (nextPhase === "done") {
+      // Only call onComplete once per connection
       if (completedIdRef.current !== connId) {
         completedIdRef.current = connId;
-        applyTransition(onAuthStatus(false, "active"), setters);
+        setPhase("done");
         onComplete(connId);
       }
     } else {
-      // Timed out and no OAuth — needs a bearer/API token
-      applyTransition(onAuthStatus(false, "timeout"), setters);
+      setPhase(nextPhase);
     }
   }
 

From 5e4a3b6ae8d2a831d195545869206a598d616868 Mon Sep 17 00:00:00 2001
From: viktormarinho <viktormpcs@gmail.com>
Date: Tue, 24 Feb 2026 17:54:06 -0300
Subject: [PATCH 21/21] fix(connections-setup): remove staleTime:Infinity from
 auth check query
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The auth check (isConnectionAuthenticated) was configured with staleTime:Infinity,
meaning the very first result was cached forever. When the query fired immediately
after connection creation the proxy might return 200 (not yet ready to enforce
OAuth), so the cache was permanently poisoned with supportsOAuth:false and the
auth phase was never shown.

The connection detail page uses useSuspenseQuery with no staleTime (defaults to 0)
so it always gets fresh data — which is why it correctly detected OAuth was needed.

The fix: drop staleTime:Infinity so the query behaves like every other auth-status
check in the codebase. The existing cache invalidation in slot-auth-oauth.tsx and
slot-auth-token.tsx still ensures a fresh check after each auth step.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
---
 apps/mesh/src/web/components/connections-setup/slot-card.tsx | 1 -
 1 file changed, 1 deletion(-)

diff --git a/apps/mesh/src/web/components/connections-setup/slot-card.tsx b/apps/mesh/src/web/components/connections-setup/slot-card.tsx
index 62f6f60693..75b3413b4a 100644
--- a/apps/mesh/src/web/components/connections-setup/slot-card.tsx
+++ b/apps/mesh/src/web/components/connections-setup/slot-card.tsx
@@ -84,7 +84,6 @@ export function SlotCard({ slot, onComplete }: SlotCardProps) {
     queryKey: KEYS.isMCPAuthenticated(authUrl, null),
     queryFn: () => isConnectionAuthenticated({ url: authUrl, token: null }),
     enabled: Boolean(authCheckId),
-    staleTime: Infinity,
   });
 
   // Derive effective phase: explicit override takes priority, else from resolution