@stigmer/react 3.12.4 → 3.12.5

package/src/library/ResourceVisibilityControl.tsx

@@ -1,15 +1,16 @@
 "use client";
 
 import { useCallback } from "react";
-import type { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
 import { useDeploymentMode } from "../deployment-mode.js";
 import { PermissionGate } from "../iam-policy/PermissionGate.js";
 import { useSsoProvider } from "../identity-provider/useSsoProvider.js";
+import { useCanSetPublicVisibility } from "./useCanSetPublicVisibility.js";
 import { VisibilityBadge, VisibilitySelector } from "./VisibilitySelector.js";
 import {
   blueprintVisibilityLevels,
   environmentVisibilityLevels,
-  INSTANCE_VISIBILITY_LEVELS,
+  instanceVisibilityLevels,
 } from "./visibilityLevels.js";
 import {
   useUpdateVisibility,
@@ -85,9 +86,19 @@ export interface ResourceVisibilityControlProps {
  *   the org boundary. In `local` mode there are no levels to choose (the
  *   OSS backend is single-user), so the control degrades to a badge.
  *
+ * The Public level is operator-gated in the cloud edition (publishing is a
+ * curation decision): for callers without `can_set_public_visibility`
+ * ({@link useCanSetPublicVisibility}) the option renders locked with copy
+ * naming the path forward. The same permission opens the operator takedown
+ * lane — on a currently-public resource, an operator gets the interactive
+ * selector even without resource `can_edit`, so noisy public resources can
+ * be un-published directly from the console (every offered move off PUBLIC
+ * is a downgrade, which the backend allows operators unilaterally).
+ *
  * The backend remains the enforcer (`ValidateVisibilityStep` rejects
- * platform without an IdP); the gate here only prevents offering an option
- * that is guaranteed to fail.
+ * platform without an IdP; `AuthorizeVisibilityTransitionStep` gates the
+ * PUBLIC level); the gates here only prevent offering an option that is
+ * guaranteed to fail.
  */
 export function ResourceVisibilityControl({
   kind,
@@ -99,6 +110,7 @@ export function ResourceVisibilityControl({
 }: ResourceVisibilityControlProps) {
   const { updateVisibility, isPending } = useUpdateVisibility(kind, resourceId);
   const deploymentMode = useDeploymentMode();
+  const canSetPublic = useCanSetPublicVisibility();
 
   const isInstance = INSTANCE_KINDS.has(kind);
   const isEnvironment = kind === "environment";
@@ -113,10 +125,13 @@ export function ResourceVisibilityControl({
   const options = isEnvironment
     ? environmentVisibilityLevels(deploymentMode)
     : isInstance
-      ? INSTANCE_VISIBILITY_LEVELS
+      ? instanceVisibilityLevels({
+          canSetPublicVisibility: canSetPublic.allowed,
+        })
       : blueprintVisibilityLevels({
           deploymentMode,
           hasIdentityProvider: ssoProvider !== null,
+          canSetPublicVisibility: canSetPublic.allowed,
         });
 
   const handleChange = useCallback(
@@ -141,6 +156,31 @@ export function ResourceVisibilityControl({
     return badge;
   }
 
+  const selector = (
+    <VisibilitySelector
+      visibility={visibility}
+      options={options}
+      onVisibilityChange={handleChange}
+      isPending={isPending}
+      ariaLabel={isInstance ? "Instance visibility" : "Resource visibility"}
+      className={className}
+    />
+  );
+
+  // Operator takedown lane: on a currently-public resource, a caller holding
+  // can_set_public_visibility gets the control without resource can_edit —
+  // every offered move is a downgrade off PUBLIC, which the backend allows
+  // operators unilaterally (AuthorizeVisibilityTransitionStep), so no
+  // offered action can fail authorization. Scoped to the public state on
+  // purpose: on non-public foreign resources most transitions would be
+  // denied, and publishing those stays a request-to-operator flow.
+  if (
+    canSetPublic.allowed &&
+    visibility === ApiResourceVisibility.visibility_public
+  ) {
+    return selector;
+  }
+
   return (
     <PermissionGate
       resource={{ kind: FGA_KIND[kind], id: resourceId }}
@@ -148,14 +188,7 @@ export function ResourceVisibilityControl({
       fallback={badge}
       loading={badge}
     >
-      <VisibilitySelector
-        visibility={visibility}
-        options={options}
-        onVisibilityChange={handleChange}
-        isPending={isPending}
-        ariaLabel={isInstance ? "Instance visibility" : "Resource visibility"}
-        className={className}
-      />
+      {selector}
     </PermissionGate>
   );
 }

package/src/library/VisibilityOptionRow.tsx

@@ -53,6 +53,12 @@ export interface VisibilityOptionRowProps {
  * label, one-line description, and a check when current. Shared by the
  * {@link VisibilitySelector} popover and its create-mode inline list so
  * option presentation has exactly one source.
+ *
+ * A level carrying {@link VisibilityLevelOption.lockedReason} renders
+ * non-interactive with a lock affordance and the reason as its detail line
+ * — the level stays discoverable (the reason names the path forward)
+ * without being selectable. The locked row keeps its normal opacity: it is
+ * informative, not in a transient disabled state.
  */
 export const VisibilityOptionRow = forwardRef<
   HTMLButtonElement,
@@ -71,6 +77,7 @@ export const VisibilityOptionRow = forwardRef<
   },
   ref,
 ) {
+  const locked = option.lockedReason !== undefined;
   const selectionAttr =
     role === "radio"
       ? { "aria-checked": isSelected }
@@ -82,16 +89,20 @@ export const VisibilityOptionRow = forwardRef<
       type="button"
       role={role}
       {...selectionAttr}
+      aria-disabled={locked || undefined}
       tabIndex={tabIndex}
-      disabled={disabled}
+      disabled={disabled || locked}
       onClick={onSelect}
       onMouseEnter={onMouseEnter}
       onKeyDown={onKeyDown}
       className={cn(
         "stg:flex stg:w-full stg:items-start stg:gap-2 stg:rounded-md stg:px-2.5 stg:py-2 stg:text-left stg:transition-colors",
         "stg:focus-visible:outline-none stg:focus-visible:ring-2 stg:focus-visible:ring-ring",
-        "stg:disabled:pointer-events-none stg:disabled:opacity-50",
-        isHighlighted ? "stg:bg-accent stg:text-foreground" : "stg:hover:bg-accent-hover",
+        locked
+          ? "stg:disabled:pointer-events-none stg:cursor-default"
+          : "stg:disabled:pointer-events-none stg:disabled:opacity-50",
+        !locked &&
+          (isHighlighted ? "stg:bg-accent stg:text-foreground" : "stg:hover:bg-accent-hover"),
       )}
     >
       <VisibilityIcon
@@ -99,14 +110,25 @@ export const VisibilityOptionRow = forwardRef<
         className="stg:mt-0.5 stg:size-3.5 stg:shrink-0 stg:text-muted-foreground"
       />
       <span className="stg:min-w-0 stg:flex-1">
-        <span className="stg:block stg:text-xs stg:font-medium stg:text-foreground">
+        <span
+          className={cn(
+            "stg:block stg:text-xs stg:font-medium",
+            locked ? "stg:text-muted-foreground" : "stg:text-foreground",
+          )}
+        >
           {option.label}
         </span>
         <span className="stg:block stg:text-[0.65rem] stg:leading-snug stg:text-muted-foreground">
-          {option.description}
+          {locked ? option.lockedReason : option.description}
         </span>
       </span>
-      {isSelected && <CheckIcon className="stg:mt-0.5 stg:size-3.5 stg:shrink-0 stg:text-primary" />}
+      {locked ? (
+        <LockIcon className="stg:mt-0.5 stg:size-3.5 stg:shrink-0 stg:text-muted-foreground" />
+      ) : (
+        isSelected && (
+          <CheckIcon className="stg:mt-0.5 stg:size-3.5 stg:shrink-0 stg:text-primary" />
+        )
+      )}
     </button>
   );
 });

package/src/library/VisibilitySelector.tsx

@@ -150,6 +150,12 @@ export function VisibilitySelector({
 
   const handleSelect = useCallback(
     (option: VisibilityLevelOption) => {
+      // Locked levels are not selectable; the row is disabled, this guard
+      // is defense in depth for programmatic activation.
+      if (option.lockedReason !== undefined) {
+        return;
+      }
+
       const value = option.value;
       if (value === visibility) {
         setPendingInline(null);
@@ -193,11 +199,17 @@ export function VisibilitySelector({
   const moveFocus = useCallback(
     (from: number, delta: number) => {
       const count = effectiveOptions.length;
-      const next = (from + delta + count) % count;
+      // Skip locked rows: their buttons are disabled and cannot take focus,
+      // so landing on one would strand the roving tabindex.
+      let next = from;
+      for (let step = 0; step < count; step++) {
+        next = (next + delta + count) % count;
+        if (effectiveOptions[next]?.lockedReason === undefined) break;
+      }
       setHighlightIdx(next);
       optionRefs.current[next]?.focus();
     },
-    [effectiveOptions.length],
+    [effectiveOptions],
   );
 
   const handleRowKeyDown = useCallback(

package/src/library/__tests__/VisibilitySelector.test.tsx

@@ -13,10 +13,14 @@ import {
   VisibilityBadge,
 } from "../VisibilitySelector";
 import {
-  INSTANCE_VISIBILITY_LEVELS,
+  instanceVisibilityLevels,
   blueprintVisibilityLevels,
 } from "../visibilityLevels";
 
+const INSTANCE_VISIBILITY_LEVELS = instanceVisibilityLevels({
+  canSetPublicVisibility: true,
+});
+
 // Base UI's Popover positioner observes its anchor; happy-dom lacks
 // ResizeObserver, so provide a no-op shim.
 beforeAll(() => {
@@ -35,6 +39,7 @@ afterEach(cleanup);
 const BLUEPRINT_LEVELS = blueprintVisibilityLevels({
   deploymentMode: "cloud",
   hasIdentityProvider: true,
+  canSetPublicVisibility: true,
 });
 
 // Option accessible names are "<label> <description>"; anchor on the label so
@@ -118,6 +123,48 @@ describe("VisibilitySelector — create mode (inline list)", () => {
   });
 });
 
+describe("VisibilitySelector — operator-gated Public (locked row)", () => {
+  // The caller may not publish: the level builders lock the Public row.
+  const GATED_LEVELS = instanceVisibilityLevels({
+    canSetPublicVisibility: false,
+  });
+
+  it("renders the locked Public row non-interactive with the platform-team copy", () => {
+    const onChange = vi.fn();
+    render(
+      <VisibilitySelector
+        mode="create"
+        visibility={ApiResourceVisibility.visibility_private}
+        options={GATED_LEVELS}
+        onVisibilityChange={onChange}
+      />,
+    );
+
+    const publicRow = screen.getByRole("radio", { name: /Public/i });
+    expect((publicRow as HTMLButtonElement).disabled).toBe(true);
+    expect(publicRow.getAttribute("aria-disabled")).toBe("true");
+    expect(publicRow.textContent).toContain("granted by the platform team");
+
+    fireEvent.click(publicRow);
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it("keeps every other level selectable — only publishing is operator-granted", () => {
+    const onChange = vi.fn();
+    render(
+      <VisibilitySelector
+        mode="create"
+        visibility={ApiResourceVisibility.visibility_private}
+        options={GATED_LEVELS}
+        onVisibilityChange={onChange}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole("radio", { name: /^Organization/i }));
+    expect(onChange).toHaveBeenCalledWith(ApiResourceVisibility.visibility_org);
+  });
+});
+
 describe("VisibilitySelector — manage mode (popover + confirmation)", () => {
   it("shows the current level on the trigger and lists levels on open", async () => {
     render(

package/src/library/__tests__/visibilityLevels.test.ts

@@ -1,6 +1,12 @@
 import { describe, it, expect } from "vitest";
 import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
-import { environmentVisibilityLevels } from "../visibilityLevels";
+import {
+  blueprintVisibilityLevels,
+  environmentVisibilityLevels,
+  instanceVisibilityLevels,
+  PUBLIC_LOCKED_REASON,
+  type VisibilityLevelOption,
+} from "../visibilityLevels";
 
 describe("environmentVisibilityLevels", () => {
   it("offers exactly Private and Organization in cloud mode", () => {
@@ -31,3 +37,63 @@ describe("environmentVisibilityLevels", () => {
     expect(environmentVisibilityLevels("local")).toHaveLength(1);
   });
 });
+
+describe("operator-gated PUBLIC level", () => {
+  const publicOf = (levels: readonly VisibilityLevelOption[]) =>
+    levels.find((l) => l.value === ApiResourceVisibility.visibility_public);
+
+  it("locks Public with the platform-team copy when the caller may not publish", () => {
+    const blueprint = publicOf(
+      blueprintVisibilityLevels({
+        deploymentMode: "cloud",
+        hasIdentityProvider: false,
+        canSetPublicVisibility: false,
+      }),
+    );
+    const instance = publicOf(
+      instanceVisibilityLevels({ canSetPublicVisibility: false }),
+    );
+
+    expect(blueprint?.lockedReason).toBe(PUBLIC_LOCKED_REASON);
+    expect(instance?.lockedReason).toBe(PUBLIC_LOCKED_REASON);
+  });
+
+  it("offers Public unlocked for callers with the publish grant", () => {
+    const blueprint = publicOf(
+      blueprintVisibilityLevels({
+        deploymentMode: "cloud",
+        hasIdentityProvider: true,
+        canSetPublicVisibility: true,
+      }),
+    );
+    const instance = publicOf(
+      instanceVisibilityLevels({ canSetPublicVisibility: true }),
+    );
+
+    expect(blueprint?.lockedReason).toBeUndefined();
+    expect(instance?.lockedReason).toBeUndefined();
+  });
+
+  it("never locks any level below Public — org/platform sharing stays self-service", () => {
+    const levels = blueprintVisibilityLevels({
+      deploymentMode: "cloud",
+      hasIdentityProvider: true,
+      canSetPublicVisibility: false,
+    });
+    for (const level of levels) {
+      if (level.value === ApiResourceVisibility.visibility_public) continue;
+      expect(level.lockedReason, `${level.label} must stay self-service`).toBeUndefined();
+    }
+  });
+
+  it("keeps the instance Public row's execution-oriented description when locked", () => {
+    // The lock replaces the rendered detail line, but the option data keeps
+    // its identity (label, tone, confirmation) so an unlock is a pure
+    // context change.
+    const instance = publicOf(
+      instanceVisibilityLevels({ canSetPublicVisibility: false }),
+    );
+    expect(instance?.lockedReason).toBe(PUBLIC_LOCKED_REASON);
+    expect(instance?.confirmDialog).toBeDefined();
+  });
+});

package/src/library/index.ts

@@ -63,12 +63,14 @@ export type {
 
 export {
   blueprintVisibilityLevels,
-  INSTANCE_VISIBILITY_LEVELS,
+  instanceVisibilityLevels,
+  PUBLIC_LOCKED_REASON,
   visibilityLabel,
   visibilityOption,
 } from "./visibilityLevels.js";
 export type {
   BlueprintVisibilityLevelsContext,
+  InstanceVisibilityLevelsContext,
   VisibilityLevelOption,
 } from "./visibilityLevels.js";
 
@@ -81,5 +83,8 @@ export type {
   UseUpdateVisibilityReturn,
 } from "./useUpdateVisibility.js";
 
+export { useCanSetPublicVisibility } from "./useCanSetPublicVisibility.js";
+export type { UseCanSetPublicVisibilityReturn } from "./useCanSetPublicVisibility.js";
+
 export { InstanceVisibilitySelector } from "./InstanceVisibilitySelector.js";
 export type { InstanceVisibilitySelectorProps } from "./InstanceVisibilitySelector.js";

package/src/library/useCanSetPublicVisibility.ts

@@ -0,0 +1,56 @@
+"use client";
+
+import { useDeploymentMode } from "../deployment-mode.js";
+import { useCheckPermission } from "../iam-policy/useCheckPermission.js";
+
+/**
+ * The `platform` singleton — platform-level permissions are always checked
+ * against this one resource (mirrors the server-side `resource_id = "stigmer"`
+ * RPC config).
+ */
+const PLATFORM_RESOURCE = { kind: "platform", id: "stigmer" } as const;
+
+/** Return value of {@link useCanSetPublicVisibility}. */
+export interface UseCanSetPublicVisibilityReturn {
+  /** Whether the current user may set resources to PUBLIC visibility. */
+  readonly allowed: boolean;
+  /** `true` while the permission check is in flight (cloud only). */
+  readonly isLoading: boolean;
+}
+
+/**
+ * Whether the current user may set a resource's visibility to PUBLIC — the
+ * only level that crosses every org boundary (the cross-org "explore"
+ * catalog).
+ *
+ * In the cloud edition, publishing is a curation decision: the backend
+ * gates both write doors (updateVisibility escalation and
+ * create-with-public) on `can_set_public_visibility` on `platform:stigmer`,
+ * an explicit platform-operator capability. This hook runs the same check
+ * so selectors can present the Public option as locked instead of letting
+ * the request fail.
+ *
+ * Fail-closed, deliberately the opposite of the `useCheckPermission`
+ * default: an escalation gate must not open while the check is loading or
+ * when it errors — a locked option that unlocks a moment later is a far
+ * better failure than an unlocked option the server then rejects.
+ *
+ * In `local` deployment mode (OSS Go backend) the answer is always `true`:
+ * the self-hosted operator owns the store, the same scoping cloud#320
+ * applied to reserved labels.
+ */
+export function useCanSetPublicVisibility(): UseCanSetPublicVisibilityReturn {
+  const deploymentMode = useDeploymentMode();
+  // Hooks run unconditionally; in local mode the null resource skips the
+  // RPC entirely and the fail mode's answer is discarded below.
+  const { allowed, isLoading } = useCheckPermission(
+    deploymentMode === "cloud" ? PLATFORM_RESOURCE : null,
+    "can_set_public_visibility",
+    { fail: "closed" },
+  );
+
+  if (deploymentMode === "local") {
+    return { allowed: true, isLoading: false };
+  }
+  return { allowed, isLoading };
+}

package/src/library/visibilityLevels.ts

@@ -43,8 +43,28 @@ export interface VisibilityLevelOption {
   };
   /** Color treatment for the selected segment and the confirmation prompt. */
   readonly tone: "private" | "org" | "platform" | "public";
+  /**
+   * When present, the level cannot be selected by the current caller and the
+   * row renders locked (disabled, lock affordance) with this copy explaining
+   * why and what to do instead. Computed by the level builders from caller
+   * context — the component stays free of per-level branching, exactly like
+   * the confirmation ladder.
+   *
+   * Today's only locked level is Public in the cloud edition for callers
+   * without `can_set_public_visibility` (publishing is operator-granted);
+   * the backend independently enforces the same gate.
+   */
+  readonly lockedReason?: string;
 }
 
+/**
+ * The locked-row copy for a caller who may not set PUBLIC visibility. Names
+ * the path forward (ask the platform team) rather than a bare "disabled" —
+ * the option stays discoverable even though it is not self-service.
+ */
+export const PUBLIC_LOCKED_REASON =
+  "Public listing is granted by the platform team — contact us to publish this resource.";
+
 const PRIVATE_OPTION: VisibilityLevelOption = {
   value: ApiResourceVisibility.visibility_private,
   label: "Private",
@@ -97,10 +117,27 @@ const PUBLIC_OPTION: VisibilityLevelOption = {
  *   operate an IdentityProvider — the backend rejects it otherwise
  *   (`ValidateVisibilityStep`), so the option only renders when the signal
  *   is present (use `useSsoProvider`, the permission-free lookup).
+ * - `canSetPublicVisibility`: entering PUBLIC is operator-gated in the
+ *   cloud edition; when the caller lacks the grant the Public option
+ *   renders locked instead of disappearing (use
+ *   `useCanSetPublicVisibility`, which is always `true` in local mode).
  */
 export interface BlueprintVisibilityLevelsContext {
   readonly deploymentMode: "cloud" | "local";
   readonly hasIdentityProvider: boolean;
+  readonly canSetPublicVisibility: boolean;
+}
+
+/**
+ * The PUBLIC option, locked with {@link PUBLIC_LOCKED_REASON} when the
+ * caller may not publish. Locked rather than hidden: the level (and the
+ * path to it) stays discoverable, matching how the option keeps rendering
+ * as the current state on already-public resources.
+ */
+function publicOption(canSetPublicVisibility: boolean): VisibilityLevelOption {
+  return canSetPublicVisibility
+    ? PUBLIC_OPTION
+    : { ...PUBLIC_OPTION, lockedReason: PUBLIC_LOCKED_REASON };
 }
 
 /**
@@ -114,12 +151,22 @@ export interface BlueprintVisibilityLevelsContext {
 export function blueprintVisibilityLevels(
   context: BlueprintVisibilityLevelsContext,
 ): readonly VisibilityLevelOption[] {
+  const publicLevel = publicOption(context.canSetPublicVisibility);
   if (context.deploymentMode === "local") {
-    return [PRIVATE_OPTION, PUBLIC_OPTION];
+    return [PRIVATE_OPTION, publicLevel];
   }
   return context.hasIdentityProvider
-    ? [PRIVATE_OPTION, ORG_OPTION, PLATFORM_OPTION, PUBLIC_OPTION]
-    : [PRIVATE_OPTION, ORG_OPTION, PUBLIC_OPTION];
+    ? [PRIVATE_OPTION, ORG_OPTION, PLATFORM_OPTION, publicLevel]
+    : [PRIVATE_OPTION, ORG_OPTION, publicLevel];
+}
+
+/**
+ * Inputs that gate the instance level set — only the publish gate; the set
+ * itself is fixed (instances have no platform level and no deployment-mode
+ * collapse).
+ */
+export interface InstanceVisibilityLevelsContext {
+  readonly canSetPublicVisibility: boolean;
 }
 
 /**
@@ -131,17 +178,21 @@ export function blueprintVisibilityLevels(
  * boundary). Descriptions are execution-oriented because org visibility on
  * an instance is about who can run it and see its executions.
  */
-export const INSTANCE_VISIBILITY_LEVELS: readonly VisibilityLevelOption[] = [
-  PRIVATE_OPTION,
-  {
-    ...ORG_OPTION,
-    description: "All org members can view executions",
-  },
-  {
-    ...PUBLIC_OPTION,
-    description: "All authenticated users can view",
-  },
-];
+export function instanceVisibilityLevels(
+  context: InstanceVisibilityLevelsContext,
+): readonly VisibilityLevelOption[] {
+  return [
+    PRIVATE_OPTION,
+    {
+      ...ORG_OPTION,
+      description: "All org members can view executions",
+    },
+    {
+      ...publicOption(context.canSetPublicVisibility),
+      description: "All authenticated users can view",
+    },
+  ];
+}
 
 /**
  * The levels an environment selector offers, in escalation order:

package/src/mcp-server/__tests__/useMcpServerConnect.asyncLane.test.tsx

@@ -0,0 +1,117 @@
+// Pins the connect hook's ride on the async connect lane (stigmer#425):
+// startConnect + poll on a backend that serves it, and the blocking-RPC
+// fallback on one that does not (the byoaEditionDegradation idiom — every
+// OTHER mcp-server test in this suite exercises the fallback implicitly, this
+// file pins BOTH lanes explicitly so neither can regress silently). The
+// protocol's own edge cases (deadlines, rehydration codes) are pinned in
+// @stigmer/sdk's mcpserver-connect.test.ts — this is the hook-level contract.
+
+import { describe, it, expect, afterEach } from "vitest";
+import { renderHook, act, cleanup } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { create } from "@bufbuild/protobuf";
+import { createRouterTransport } from "@connectrpc/connect";
+import { Stigmer } from "@stigmer/sdk";
+import { McpServerCommandController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/command_pb";
+import { McpServerQueryController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/query_pb";
+import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { ConnectPhase } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/status_pb";
+import { StigmerContext } from "../../context";
+import { useMcpServerConnect } from "../useMcpServerConnect";
+
+afterEach(cleanup);
+
+const SERVER_ID = "mcps_01test";
+const ORG = "acme";
+
+function mcpServer(phase: ConnectPhase, extras?: { failureMessage?: string; toolName?: string }) {
+  return create(McpServerSchema, {
+    metadata: { id: SERVER_ID, name: "Test Server" },
+    status: {
+      ...(extras?.toolName !== undefined
+        ? { discoveredCapabilities: { tools: [{ name: extras.toolName }] } }
+        : {}),
+      connectStatus: {
+        phase,
+        workflowId: `stigmer/mcp-server/connect/${SERVER_ID}`,
+        failureCode: extras?.failureMessage !== undefined ? "FailedPrecondition" : "",
+        failureMessage: extras?.failureMessage ?? "",
+      },
+    },
+  });
+}
+
+function renderConnectHook(register: Parameters<typeof createRouterTransport>[0]) {
+  const client = new Stigmer({
+    baseUrl: "/",
+    getAccessToken: () => "test-token",
+    customTransport: createRouterTransport(register),
+  });
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <StigmerContext.Provider value={client}>{children}</StigmerContext.Provider>
+  );
+  return renderHook(() => useMcpServerConnect(), { wrapper });
+}
+
+describe("useMcpServerConnect — async lane", () => {
+  it("resolves through startConnect + polling when the backend serves the lane", async () => {
+    let blockingConnectCalled = false;
+    const { result } = renderConnectHook((router) => {
+      router.service(McpServerCommandController, {
+        startConnect: () => mcpServer(ConnectPhase.connecting),
+        connect: () => {
+          blockingConnectCalled = true;
+          return mcpServer(ConnectPhase.succeeded);
+        },
+      });
+      router.service(McpServerQueryController, {
+        get: () => mcpServer(ConnectPhase.succeeded, { toolName: "search_code" }),
+      });
+    });
+
+    await act(async () => {
+      const settled = await result.current.connect(SERVER_ID, ORG);
+      expect(settled.status?.discoveredCapabilities?.tools[0]?.name).toBe("search_code");
+    });
+    expect(blockingConnectCalled).toBe(false);
+    expect(result.current.error).toBeNull();
+    expect(result.current.isConnecting).toBe(false);
+  }, 15_000);
+
+  it("surfaces a failed operation with the persisted user-facing message", async () => {
+    const { result } = renderConnectHook((router) => {
+      router.service(McpServerCommandController, {
+        startConnect: () => mcpServer(ConnectPhase.connecting),
+      });
+      router.service(McpServerQueryController, {
+        get: () =>
+          mcpServer(ConnectPhase.failed, {
+            failureMessage: "connect failed for MCP server 'Test Server': missing credentials",
+          }),
+      });
+    });
+
+    await act(async () => {
+      await expect(result.current.connect(SERVER_ID, ORG)).rejects.toThrow("missing credentials");
+    });
+    expect(result.current.error?.message).toContain("missing credentials");
+    expect(result.current.isConnecting).toBe(false);
+  }, 15_000);
+
+  it("falls back to the blocking connect on a backend without the lane", async () => {
+    // startConnect deliberately unregistered: the router answers
+    // UNIMPLEMENTED, exactly what a pre-#425 backend (e.g. the hosted
+    // edition until its parity lands) returns.
+    const { result } = renderConnectHook((router) => {
+      router.service(McpServerCommandController, {
+        connect: () => mcpServer(ConnectPhase.succeeded, { toolName: "search_code" }),
+      });
+    });
+
+    await act(async () => {
+      const settled = await result.current.connect(SERVER_ID, ORG);
+      expect(settled.status?.discoveredCapabilities?.tools[0]?.name).toBe("search_code");
+    });
+    expect(result.current.error).toBeNull();
+  });
+});