diff --git a/app/components/organisms/ConnectRepoDialog.vue b/app/components/organisms/ConnectRepoDialog.vue
index d84f053..fa36e5b 100644
--- a/app/components/organisms/ConnectRepoDialog.vue
+++ b/app/components/organisms/ConnectRepoDialog.vue
@@ -129,6 +129,18 @@ async function connectRepo() {
     open.value = false
   }
   catch (e: unknown) {
+    const status = (e as { statusCode?: number, data?: { statusCode?: number, requiresCheckout?: boolean } }).statusCode
+      ?? (e as { data?: { statusCode?: number } }).data?.statusCode
+    const requiresCheckout = (e as { data?: { requiresCheckout?: boolean } }).data?.requiresCheckout
+
+    // Plan modal is opened globally by resolveApiError. Close this dialog so
+    // the user lands on the plan picker, not a stacked surface.
+    if (status === 402 && requiresCheckout) {
+      open.value = false
+      resolveApiError(e, t('projects.connected_error'))
+      return
+    }
+
     toast.error(resolveApiError(e, t('projects.connected_error')))
   }
   finally {
diff --git a/app/composables/usePlanModal.ts b/app/composables/usePlanModal.ts
new file mode 100644
index 0000000..46f4c49
--- /dev/null
+++ b/app/composables/usePlanModal.ts
@@ -0,0 +1,22 @@
+/**
+ * Global plan-selection modal state.
+ *
+ * Mounted once per layout (`default`, `workspace`) and triggered from
+ * anywhere via `usePlanModal().show()`. The primary trigger is the
+ * client-side 402 + `requiresCheckout` handler in `resolveApiError`,
+ * so any API call that hits a billing-locked state surfaces the
+ * checkout flow instead of dying as a toast.
+ */
+export function usePlanModal() {
+  const open = useState<boolean>('plan-modal-open', () => false)
+
+  function show() {
+    open.value = true
+  }
+
+  function hide() {
+    open.value = false
+  }
+
+  return { open, show, hide }
+}
diff --git a/app/layouts/default.vue b/app/layouts/default.vue
index 768f5e2..7bc093a 100644
--- a/app/layouts/default.vue
+++ b/app/layouts/default.vue
@@ -2,6 +2,8 @@
 const { t } = useContent()
 const { open: commandPaletteOpen } = useCommandPalette()
 const { toggle: toggleMobileSidebar } = useMobileSidebar()
+const { open: planModalOpen } = usePlanModal()
+const deployment = useDeployment()
 </script>
 
 <template>
@@ -37,5 +39,14 @@ const { toggle: toggleMobileSidebar } = useMobileSidebar()
     <ClientOnly>
       <OrganismsCommandPalette v-model:open="commandPaletteOpen" />
     </ClientOnly>
+
+    <!-- Plan selection modal — opened by usePlanModal() globally on
+         402 + requiresCheckout, plus any explicit upgrade CTA. Hidden
+         on profiles without managed billing. -->
+    <OrganismsPlanSelectionModal
+      v-if="deployment.hasManagedBilling.value"
+      :open="planModalOpen"
+      @update:open="planModalOpen = $event"
+    />
   </div>
 </template>
diff --git a/app/layouts/workspace.vue b/app/layouts/workspace.vue
index 956e7d4..c2d52b1 100644
--- a/app/layouts/workspace.vue
+++ b/app/layouts/workspace.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 const contextOpen = ref(true)
-const planModalOpen = ref(false)
+const { open: planModalOpen, show: showPlanModal } = usePlanModal()
 
 const { openPortal } = useBilling()
 const deployment = useDeployment()
@@ -24,7 +24,7 @@ provide('contextPanel', { open: contextOpen, toggle: toggleContext })
     <!-- Main -->
     <main class="flex min-w-0 flex-1 flex-col overflow-y-auto">
       <MoleculesTrialBanner
-        @choose-plan="planModalOpen = true"
+        @choose-plan="showPlanModal()"
         @manage-billing="openPortal()"
       />
       <slot />
diff --git a/app/utils/api-error.ts b/app/utils/api-error.ts
index 8f59959..f60eea5 100644
--- a/app/utils/api-error.ts
+++ b/app/utils/api-error.ts
@@ -15,7 +15,7 @@
 interface FetchError {
   statusCode?: number
   status?: number
-  data?: { message?: string, statusCode?: number, statusMessage?: string }
+  data?: { message?: string, statusCode?: number, statusMessage?: string, requiresCheckout?: boolean }
   message?: string
 }
 
@@ -44,6 +44,19 @@ export function resolveApiError(error: unknown, fallback: string): string {
     ?? err.data?.statusCode
     ?? 0
 
+  // 402 + requiresCheckout → trigger the global plan-selection modal so the
+  // user can pay instead of staring at a toast. Falls back to toast text below
+  // when no modal is mounted (e.g. /auth, error page).
+  if (status === 402 && err.data?.requiresCheckout && import.meta.client) {
+    try {
+      usePlanModal().show()
+    }
+    catch {
+      // No Nuxt context (rare — e.g. utility called outside setup). Swallow;
+      // the caller will still render the toast string from the return value.
+    }
+  }
+
   // 4xx client errors — backend message is user-friendly (from errorMessage())
   if (status >= 400 && status < 500) {
     const message = err.data?.message ?? err.message