[OPIK-5898] [FE] fix: pairing page V2 routing and workspace-version gate (#6269)

* [OPIK-5898] [FE] fix: route /pair/v1 to V2 app and gate pairing on workspace version

* [OPIK-5898] [FE] fix: make V2-only path detection basepath-independent

* [OPIK-5898] [FE] fix: make pairing route basepath-relative

TanStack strips the router basepath before matching, so the route path
must be basepath-relative like every other route in the tree. With the
hardcoded /opik/ prefix, the route only matched on OSS (basepath "/")
and missed on cloud (basepath "/opik"), where the internal path is
/pair/v1 after stripping — causing the pair link to fall through to
the home redirect.

* [OPIK-5898] [FE] fix: pairing UX polish and OSS fallback route

- Add /opik/pair/v1 alias for OSS: the Python SDK hardcodes the /opik/
  prefix, which only strips on cloud where basepath is /opik. Marked
  with a TODO to remove once the SDK builds basepath-aware URLs.
- Resolve workspace version synchronously at module load when possible
  (override, V2-only path, or no workspace in URL) so the first paint
  renders the correct App — no Loader flash on /pair/*.
- PairingPage: use project icons (CheckCircle2, CircleAlert, Spinner),
  redirect to agent-configuration on success instead of window.close,
  and treat 409 (runner already paired) as success so the user still
  gets redirected.

* [OPIK-5898] [FE] fix: surface parse errors before workspace-version check

- Check parseError before the workspacePhase === "checking" branch so a
  malformed pairing fragment doesn't sit on "Connecting…" while the
  version query is in flight.
- Drop the useMemo around workspaceName so any re-render picks up the
  current query string instead of the value frozen at mount.

Author: awkoy

apps/opik-frontend/src/WorkspaceVersionGate.tsx

@@ -9,10 +9,14 @@
  *
  * Level 1 — WorkspaceVersionGate (this component, BEFORE the router):
  *   1. Check localStorage override ("opik-version-override") → use immediately
- *   2. Try to parse workspace name from window.location.pathname
- *   3. If found → fetch version from API with per-request Comet-Workspace header
- *   4. If not found (e.g. root "/") → default to v1 optimistically
- *   5. Render the correct App (V1App or V2App) based on resolved version
+ *   2. Check if the path forces a version (e.g. /pair/* is V2-only)
+ *   3. Else parse the workspace name from window.location.pathname
+ *   4. If found → fetch version from API with per-request Comet-Workspace header
+ *   5. If not found (e.g. root "/") → default to v1 optimistically
+ *
+ * Steps 1, 2, 5 are synchronous and run at module load, so the first paint
+ * already knows which App to render — no Loader flash in the common cases.
+ * Only step 4 (workspace in URL, version unknown) falls back to a Loader.
  *
  * Level 2 — WorkspaceVersionResolver (INSIDE the router, after WorkspacePreloader):
  *   1. Workspace is now fully resolved (auth, access, header set)
@@ -27,40 +31,36 @@ import React, { Suspense, useEffect } from "react";
 import useAppStore, { useWorkspaceVersion } from "@/store/AppStore";
 import { fetchWorkspaceVersion } from "@/api/workspaces/useWorkspaceVersion";
 import {
-  DEFAULT_WORKSPACE_VERSION,
-  getVersionOverride,
   getWorkspaceNameFromPath,
+  resolveSyncWorkspaceVersion,
 } from "@/lib/workspaceVersion";
 import Loader from "@/shared/Loader/Loader";
 
 const V1App = React.lazy(() => import("@/v1/App"));
 const V2App = React.lazy(() => import("@/v2/App"));
 
+// Populate the store synchronously at module load so the first render
+// already has a version — avoids a Loader flash on /pair/*, root "/", and
+// any path with a localStorage version override.
+const initialVersion = resolveSyncWorkspaceVersion();
+if (initialVersion) {
+  useAppStore.getState().setWorkspaceVersion(initialVersion);
+}
+
 const WorkspaceVersionGate = () => {
   const version = useWorkspaceVersion();
 
   useEffect(() => {
-    let cancelled = false;
+    if (useAppStore.getState().workspaceVersion) return;
+    const workspaceName = getWorkspaceNameFromPath();
+    if (!workspaceName) return;
 
-    async function resolve() {
-      const override = getVersionOverride();
-      if (override) {
-        useAppStore.getState().setWorkspaceVersion(override);
-        return;
-      }
-
-      const workspaceName = getWorkspaceNameFromPath();
-      if (workspaceName) {
-        const resolved = await fetchWorkspaceVersion({ workspaceName });
-        if (!cancelled) {
-          useAppStore.getState().setWorkspaceVersion(resolved);
-        }
-      } else {
-        useAppStore.getState().setWorkspaceVersion(DEFAULT_WORKSPACE_VERSION);
+    let cancelled = false;
+    fetchWorkspaceVersion({ workspaceName }).then((resolved) => {
+      if (!cancelled) {
+        useAppStore.getState().setWorkspaceVersion(resolved);
       }
-    }
-    resolve();
-
+    });
     return () => {
       cancelled = true;
     };

apps/opik-frontend/src/lib/workspaceVersion.ts

@@ -4,17 +4,51 @@ export const DEFAULT_WORKSPACE_VERSION: WorkspaceVersion = "v1";
 
 const OPIK_VERSION_OVERRIDE_KEY = "opik-version-override";
 
+// Path segments (directly under basepath) that are only valid in V2.
+// Add new V2-only top-level routes here — nothing else needs to change.
+const V2_ONLY_SEGMENTS: ReadonlySet<string> = new Set(["pair"]);
+
 export function getVersionOverride(): WorkspaceVersion | null {
   const override = localStorage.getItem(OPIK_VERSION_OVERRIDE_KEY);
   return override === "v1" || override === "v2" ? override : null;
 }
 
-export function getWorkspaceNameFromPath(): string | null {
+function getRelativePathSegments(): string[] {
   const basePath = (import.meta.env.VITE_BASE_URL || "/").replace(/\/$/, "");
   const pathname = window.location.pathname;
   const relative = pathname.startsWith(basePath)
     ? pathname.slice(basePath.length)
     : pathname;
-  const segments = relative.split("/").filter(Boolean);
-  return segments[0] || null;
+  return relative.split("/").filter(Boolean);
+}
+
+export function getWorkspaceNameFromPath(): string | null {
+  return getRelativePathSegments()[0] || null;
+}
+
+// Returns a version that the current path forces regardless of workspace.
+// Used by WorkspaceVersionGate to short-circuit V2-only routes (e.g. /pair/*)
+// without an API call and without touching localStorage.
+//
+// The pairing URL from the SDK is always of the form `.../opik/pair/v1`.
+// On cloud (VITE_BASE_URL=/opik), the `/opik` prefix is stripped by
+// getRelativePathSegments so the first segment is "pair". On OSS
+// (VITE_BASE_URL=/), nothing is stripped and "opik" remains as the first
+// segment — skip it so detection works in both deployments.
+export function getForcedVersionFromPath(): WorkspaceVersion | null {
+  const segments = getRelativePathSegments();
+  const head = segments[0] === "opik" ? segments[1] : segments[0];
+  return head && V2_ONLY_SEGMENTS.has(head) ? "v2" : null;
+}
+
+// Resolves the workspace version synchronously when possible. Returns null
+// only when the workspace name is in the URL but its version requires an
+// API fetch — the one case that needs to fall back to a Loader.
+export function resolveSyncWorkspaceVersion(): WorkspaceVersion | null {
+  const override = getVersionOverride();
+  if (override) return override;
+  const forced = getForcedVersionFromPath();
+  if (forced) return forced;
+  if (!getWorkspaceNameFromPath()) return DEFAULT_WORKSPACE_VERSION;
+  return null;
 }

apps/opik-frontend/src/v2/pages/PairingPage/PairingPage.tsx

@@ -1,5 +1,10 @@
-import React, { useEffect, useMemo, useState } from "react";
+import React, { useEffect, useMemo } from "react";
+import { useMutation, useQuery } from "@tanstack/react-query";
+import { useNavigate } from "@tanstack/react-router";
+import { CheckCircle2, CircleAlert } from "lucide-react";
 import api from "@/api/api";
+import { fetchWorkspaceVersion } from "@/api/workspaces/useWorkspaceVersion";
+import { Spinner } from "@/ui/spinner";
 
 // ---------------------------------------------------------------------------
 // Binary helpers
@@ -123,23 +128,20 @@ async function deriveBridgeKey(
 // Activate + derive + store — runs once on mount
 // ---------------------------------------------------------------------------
 
-async function activate(payload: PairingPayload): Promise<void> {
-  const workspace = new URLSearchParams(window.location.search).get(
-    "workspace",
-  );
-  if (workspace) {
-    api.defaults.headers.common["Comet-Workspace"] = workspace;
-  }
-
+async function activate(
+  payload: PairingPayload,
+  workspace: string | null,
+): Promise<void> {
   const hmac = await computeActivationHmac(
     payload.activationKey,
     payload.sessionId,
     payload.runnerName,
   );
-  await api.post(`/v1/private/pairing/sessions/${payload.sessionId}/activate`, {
-    runner_name: payload.runnerName,
-    hmac,
-  });
+  await api.post(
+    `/v1/private/pairing/sessions/${payload.sessionId}/activate`,
+    { runner_name: payload.runnerName, hmac },
+    workspace ? { headers: { "Comet-Workspace": workspace } } : undefined,
+  );
 
   // Only CONNECT runners use bridge keys for HMAC-signed file commands.
   // ENDPOINT runners don't need one — storing it would overwrite the
@@ -160,7 +162,11 @@ async function activate(payload: PairingPayload): Promise<void> {
 // Page component
 // ---------------------------------------------------------------------------
 
+type WorkspacePhase = "missing" | "checking" | "ok" | "v1";
+type Status = "loading" | "success" | "error";
+
 const PairingPage: React.FC = () => {
+  const navigate = useNavigate();
   const fragment = window.location.hash.slice(1);
 
   const [payload, parseError] = useMemo<
@@ -174,52 +180,119 @@ const PairingPage: React.FC = () => {
     }
   }, [fragment]);
 
-  const [status, setStatus] = useState<"busy" | "done" | "error">(
-    parseError ? "error" : "busy",
+  const workspaceName = new URLSearchParams(window.location.search).get(
+    "workspace",
   );
-  const [error, setError] = useState(parseError ?? "");
 
-  // Auto-activate on mount
-  useEffect(() => {
-    if (!payload) return;
-    if (!crypto?.subtle) {
-      setStatus("error");
-      setError("Pairing requires a secure connection (HTTPS).");
-      return;
-    }
-    activate(payload)
-      .then(() => setStatus("done"))
-      .catch((err: unknown) => {
-        setStatus("error");
-        const s =
+  const versionQuery = useQuery({
+    queryKey: ["pairing-workspace-version", workspaceName],
+    queryFn: ({ signal }) =>
+      fetchWorkspaceVersion({ workspaceName: workspaceName!, signal }),
+    enabled: !!workspaceName,
+    staleTime: 5 * 60 * 1000,
+  });
+
+  const workspacePhase: WorkspacePhase = useMemo(() => {
+    if (!workspaceName) return "missing";
+    if (versionQuery.isPending) return "checking";
+    if (versionQuery.data === "v2") return "ok";
+    return "v1";
+  }, [workspaceName, versionQuery.isPending, versionQuery.data]);
+
+  const {
+    mutate: runActivation,
+    isIdle: activationIdle,
+    isError: activationIsError,
+    isSuccess: activationIsSuccess,
+    error: activationError,
+  } = useMutation({
+    mutationFn: async (p: PairingPayload) => {
+      if (!crypto?.subtle) throw new Error("SECURE_CONTEXT_REQUIRED");
+      try {
+        await activate(p, workspaceName);
+      } catch (err) {
+        // 409 = runner already paired; treat as success so the user still
+        // gets redirected to their agent instead of seeing an error screen.
+        const status =
           err && typeof err === "object" && "response" in err
             ? (err as { response?: { status?: number } }).response?.status
             : undefined;
-        if (s === 403)
-          setError("This pairing link is invalid or has been tampered with.");
-        else if (s === 404)
-          setError("This pairing link has expired. Run the CLI command again.");
-        else if (s === 409)
-          setError("This runner is already connected. You can close this tab.");
-        else setError("Could not reach Opik. Check your connection.");
+        if (status !== 409) throw err;
+      }
+    },
+    onSuccess: (_data, variables) => {
+      if (!workspaceName) return;
+      navigate({
+        to: "/$workspaceName/projects/$projectId/agent-configuration",
+        params: { workspaceName, projectId: variables.projectId },
       });
-  }, [payload]);
+    },
+  });
 
-  // Auto-close on success
   useEffect(() => {
-    if (status !== "done") return;
-    const t = setTimeout(() => window.close(), 1500);
-    return () => clearTimeout(t);
-  }, [status]);
+    if (workspacePhase !== "ok" || !payload || !activationIdle) return;
+    runActivation(payload);
+  }, [workspacePhase, payload, activationIdle, runActivation]);
+
+  function getActivationErrorMessage(err: unknown): string {
+    if (err instanceof Error && err.message === "SECURE_CONTEXT_REQUIRED") {
+      return "Pairing requires a secure connection (HTTPS).";
+    }
+    const s =
+      err && typeof err === "object" && "response" in err
+        ? (err as { response?: { status?: number } }).response?.status
+        : undefined;
+    if (s === 403)
+      return "This pairing link is invalid or has been tampered with.";
+    if (s === 404)
+      return "This pairing link has expired. Run the CLI command again.";
+    return "Could not reach Opik. Check your connection.";
+  }
+
+  function getDisplay(): { status: Status; message: string } {
+    // Fragment-level errors surface first: a bad link is invalid regardless
+    // of workspace state, and we shouldn't block on the version query to
+    // tell the user.
+    if (parseError) return { status: "error", message: parseError };
+    if (workspacePhase === "missing") {
+      return { status: "error", message: "This pairing link is invalid." };
+    }
+    if (workspacePhase === "v1") {
+      return {
+        status: "error",
+        message:
+          "Opik Connect requires Opik 2.0. Please upgrade your workspace to continue.",
+      };
+    }
+    if (workspacePhase === "checking") {
+      return { status: "loading", message: "Connecting…" };
+    }
+    if (activationIsError) {
+      return {
+        status: "error",
+        message: getActivationErrorMessage(activationError),
+      };
+    }
+    if (activationIsSuccess) return { status: "success", message: "Connected" };
+    return { status: "loading", message: "Connecting…" };
+  }
+
+  const { status, message } = getDisplay();
+
+  const icon =
+    status === "loading" ? (
+      <Spinner size="medium" />
+    ) : status === "success" ? (
+      <CheckCircle2 className="size-8 shrink-0 text-green-600" />
+    ) : (
+      <CircleAlert className="size-8 shrink-0 text-destructive" />
+    );
 
   return (
-    <p>
-      {status === "done"
-        ? "Connected ✔"
-        : status === "error"
-          ? error
-          : "Connecting…"}
-    </p>
+    <div className="flex min-h-screen flex-col items-center justify-center gap-3 p-6">
+      {icon}
+      <p className="comet-body text-center text-muted-slate">{message}</p>
+    </div>
   );
 };
 

apps/opik-frontend/src/v2/router.tsx

@@ -99,7 +99,22 @@ const workspaceGuardEmptyLayoutRoute = createRoute({
 });
 
 // ----------- pairing (root-level, no layout)
+// TanStack strips the router basepath before matching, so the canonical
+// route is basepath-relative: "/pair/v1" covers cloud (basepath "/opik"
+// → URL "/opik/pair/v1" strips to "/pair/v1").
+//
+// The legacy "/opik/pair/v1" alias below is an OSS-only fallback: the
+// Python SDK hardcodes "{origin}/opik/pair/v1" regardless of deployment
+// (see sdks/python/src/opik/cli/pairing.py), so on OSS (basepath "/") the
+// "/opik/" prefix isn't stripped and the router sees "/opik/pair/v1".
+// TODO: make the Python SDK build basepath-aware pairing URLs and drop
+// this alias once shipped CLI versions roll over.
 const pairingRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: "/pair/v1",
+  component: PairingPage,
+});
+const pairingRouteOssAlias = createRoute({
   getParentRoute: () => rootRoute,
   path: "/opik/pair/v1",
   component: PairingPage,
@@ -540,6 +555,7 @@ const v1RedirectRoutes = createV1RedirectRoutes(workspaceRoute);
 
 const routeTree = rootRoute.addChildren([
   pairingRoute,
+  pairingRouteOssAlias,
   workspaceGuardEmptyLayoutRoute.addChildren([automationLogsRoute]),
   workspaceGuardPartialLayoutRoute.addChildren([
     quickstartRoute,