refactor(billing): use canonical status and preserve legacy rail (#14614)

## Summary
Part 3/4 of the workspace/billing rollout retirement stack. Standardizes
Cloud subscription discovery on canonical workspace billing status while
preserving explicit `legacy_stripe` account operations.

Predecessor:
[#14613](#14613).
Successor:
[#14615](#14615).

## Root cause
Cloud subscription state was read from both
`/customers/cloud-subscription-status` and `/api/billing/status` with
different response types and cancellation fields (`end_date` versus
`cancel_at`). That allowed stale rail selection and could mix workspace
status/balance with legacy top-up and management behavior.

## Changes
- Read Cloud subscription status only from `/api/billing/status` using
the canonical type and `cancel_at`.
- Avoid ingress status requests for non-Cloud builds.
- Preserve `legacy_stripe` balance, top-up, and management while unified
checkout remains workspace-backed.
- Keep `consolidated_billing_enabled` routing intact.
- Dispatch the production pending-checkout event in the Playwright
helper.
- Strengthen the rail regression to prove canonical discovery, no
old-status request, legacy balance/credits visibility, and rejection of
stale workspace zero balance.

## AS IS
Two status contracts can compete, and cancellation/rail state can be
stale or translated inconsistently.

## TO BE
Canonical status selects the rail; explicit legacy Stripe continues
legacy account operations and unified checkout. No intended visual
change, so no screenshot is required.

## Regression coverage
- Canonical Cloud status and non-Cloud no-ingress behavior.
- Canonical cancellation in watcher and legacy adapter.
- Adapter switching and stale-rail failure.
- Playwright regression serves `consolidated_billing_enabled: true` +
`legacy_stripe`, observes canonical status and legacy balance, proves
old status absent, and verifies credits/top-up UI without stale zero
balance.

## Validation
- 4 focused Vitest files: 79 tests passed.
- `pnpm typecheck` and `pnpm typecheck:browser` passed via commit hooks.
- targeted format/lint passed via commit hooks.
- `git diff --check dante/retire-team-workspace-flag...HEAD` passed.
- `pnpm knip --cache` passed via push hook.
- Focused Playwright legacy-rail regression passed against local Cloud
dev server (1 passed). The full two-test file had one transient initial
boot timeout on its first run; its second pricing-flow test passed, and
the focused failed case passed on rerun.

## Review focus
Review only canonical status/cancellation semantics and the
legacy-account/unified-checkout boundary. Consolidated flag retirement
belongs to part 4.

## Stack/deployment order
1. [#14612](#14612) —
recovery foundation
2. [#14613](#14613) —
retire team workspace rollout flag
3. **This PR** — canonical status and legacy rail preservation
4. [#14615](#14615) —
retire consolidated billing rollout flag

Deploy the frontend stack before the backend removes `/api/features`
compatibility keys.

---------

Co-authored-by: Connor Byrne <c.byrne@comfy.org>
Co-authored-by: Amp <amp@ampcode.com>

Author: 3 people

browser_tests/fixtures/ComfyPage.ts

@@ -14,10 +14,7 @@ import {
   EMPTY_BILLING_PLANS,
   LEGACY_PERSONAL_BILLING_STATUS
 } from '@e2e/fixtures/data/cloudWorkspace'
-import {
-  UNSUBSCRIBED,
-  ZERO_BALANCE
-} from '@e2e/fixtures/data/subscriptionFixtures'
+import { ZERO_BALANCE } from '@e2e/fixtures/data/subscriptionFixtures'
 import { ComfyActionbar } from '@e2e/fixtures/components/Actionbar'
 import { ComfyTemplates } from '@e2e/fixtures/components/Templates'
 import { ComfyMouse } from '@e2e/fixtures/ComfyMouse'
@@ -587,9 +584,6 @@ export const comfyPageFixture = base.extend<{
       await context.route('**/api/billing/plans', (route) =>
         route.fulfill({ json: EMPTY_BILLING_PLANS })
       )
-      await context.route('**/customers/cloud-subscription-status', (route) =>
-        route.fulfill({ json: UNSUBSCRIBED })
-      )
       await context.route('**/customers/balance', (route) =>
         route.fulfill({ json: ZERO_BALANCE })
       )

browser_tests/fixtures/data/cloudWorkspace.ts

@@ -11,9 +11,7 @@ import type {
 } from '@/platform/workspace/api/workspaceApi'
 import type { RemoteConfig } from '@/platform/remoteConfig/types'
 
-export const CLOUD_REMOTE_CONFIG: RemoteConfig = {
-  consolidated_billing_enabled: true
-}
+export const CLOUD_REMOTE_CONFIG: RemoteConfig = {}
 
 export const LEGACY_PERSONAL_BILLING_STATUS = {
   billing_rail: 'legacy_stripe',

browser_tests/fixtures/data/subscriptionFixtures.ts

@@ -1,22 +1,18 @@
 import type { operations } from '@comfyorg/registry-types'
 
-export type SubscriptionStatusResponse =
-  operations['GetCloudSubscriptionStatus']['responses']['200']['content']['application/json']
+import type { BillingStatusResponse } from '@/platform/workspace/api/workspaceApi'
 
 export type BalanceResponse =
   operations['GetCustomerBalance']['responses']['200']['content']['application/json']
 
 export function createSubscriptionStatus(
-  overrides: Partial<SubscriptionStatusResponse> = {}
-): SubscriptionStatusResponse {
+  overrides: Partial<BillingStatusResponse> = {}
+): BillingStatusResponse {
   return {
     is_active: false,
-    subscription_id: null,
     subscription_tier: 'FREE',
-    subscription_duration: null,
-    has_fund: false,
-    renewal_date: null,
-    end_date: null,
+    has_funds: false,
+    billing_rail: 'legacy_stripe',
     ...overrides
   }
 }
@@ -35,13 +31,10 @@ export function createBalance(
   }
 }
 
-export const UNSUBSCRIBED: SubscriptionStatusResponse =
-  createSubscriptionStatus({
-    is_active: false,
-    subscription_id: null,
-    subscription_tier: 'FREE',
-    end_date: null
-  })
+export const UNSUBSCRIBED: BillingStatusResponse = createSubscriptionStatus({
+  is_active: false,
+  subscription_tier: 'FREE'
+})
 
 export const ZERO_BALANCE: BalanceResponse = createBalance({
   amount_micros: 0,

browser_tests/fixtures/helpers/SubscriptionHelper.ts

@@ -1,21 +1,22 @@
 import { expect } from '@playwright/test'
 import type { Page, Route } from '@playwright/test'
 
-import { PENDING_SUBSCRIPTION_CHECKOUT_STORAGE_KEY } from '@/platform/cloud/subscription/utils/subscriptionCheckoutTracker'
+import {
+  PENDING_SUBSCRIPTION_CHECKOUT_EVENT,
+  PENDING_SUBSCRIPTION_CHECKOUT_STORAGE_KEY
+} from '@/platform/cloud/subscription/utils/subscriptionCheckoutTracker'
+import type { BillingStatusResponse } from '@/platform/workspace/api/workspaceApi'
 import {
   createBalance,
   createSubscriptionStatus,
   UNSUBSCRIBED,
   ZERO_BALANCE
 } from '@e2e/fixtures/data/subscriptionFixtures'
-import type {
-  BalanceResponse,
-  SubscriptionStatusResponse
-} from '@e2e/fixtures/data/subscriptionFixtures'
+import type { BalanceResponse } from '@e2e/fixtures/data/subscriptionFixtures'
 import { TestIds } from '@e2e/fixtures/selectors'
 
 export interface SubscriptionConfig {
-  status: SubscriptionStatusResponse
+  status: BillingStatusResponse
   balance: BalanceResponse
 }
 
@@ -31,7 +32,7 @@ export type SubscriptionOperator = (
 ) => SubscriptionConfig
 
 function withSubscriptionStatus(
-  overrides: Partial<SubscriptionStatusResponse>
+  overrides: Partial<BillingStatusResponse>
 ): SubscriptionOperator {
   return (config) => ({
     ...config,
@@ -40,35 +41,31 @@ function withSubscriptionStatus(
 }
 
 export function withActiveSubscription(
-  tier: NonNullable<SubscriptionStatusResponse['subscription_tier']> = 'CREATOR'
+  tier: NonNullable<BillingStatusResponse['subscription_tier']> = 'CREATOR'
 ): SubscriptionOperator {
   return withSubscriptionStatus({
     is_active: true,
     subscription_tier: tier,
-    renewal_date: '2099-12-31T00:00:00.000Z',
-    end_date: null
+    renewal_date: '2099-12-31T00:00:00.000Z'
   })
 }
 
 export function withFreeTier(): SubscriptionOperator {
   return withSubscriptionStatus({
     is_active: true,
-    subscription_tier: 'FREE',
-    end_date: null
+    subscription_tier: 'FREE'
   })
 }
 
 export function withUnsubscribed(): SubscriptionOperator {
   return withSubscriptionStatus({
     is_active: false,
-    subscription_tier: 'FREE',
-    end_date: null,
-    renewal_date: null
+    subscription_tier: 'FREE'
   })
 }
 
 export class SubscriptionHelper {
-  private statusResponse: SubscriptionStatusResponse
+  private statusResponse: BillingStatusResponse
   private balanceResponse: BalanceResponse
   private routeHandlers: Array<{
     pattern: string
@@ -104,7 +101,7 @@ export class SubscriptionHelper {
     })
     await this.page.route(featuresPattern, featuresHandler)
 
-    const statusPattern = '**/customers/cloud-subscription-status'
+    const statusPattern = '**/api/billing/status'
     const statusHandler = async (route: Route) => {
       await route.fulfill({ json: this.statusResponse })
     }
@@ -155,7 +152,7 @@ export class SubscriptionHelper {
     this.balanceResponse = { ...config.balance }
   }
 
-  setStatus(overrides: Partial<SubscriptionStatusResponse>): void {
+  setStatus(overrides: Partial<BillingStatusResponse>): void {
     this.statusResponse = { ...this.statusResponse, ...overrides }
   }
 
@@ -191,14 +188,14 @@ export class SubscriptionHelper {
   }
 
   /**
-   * Dispatch `visibilitychange` to simulate returning from Stripe checkout.
-   * The app re-fetches subscription status when a pending checkout attempt
-   * exists in localStorage (seeded via `seedPendingCheckout`).
+   * Notify the app that a pending checkout attempt needs to be recovered.
    */
   async triggerSubscriptionRefetch(): Promise<void> {
-    await this.page.evaluate(() => {
-      document.dispatchEvent(new Event('visibilitychange'))
-    })
+    const eventName = PENDING_SUBSCRIPTION_CHECKOUT_EVENT
+    await this.page.evaluate(
+      (name) => window.dispatchEvent(new Event(name)),
+      eventName
+    )
   }
 
   /**

browser_tests/fixtures/utils/cloudAppSetup.ts

@@ -14,13 +14,6 @@ import { mockWorkspace } from '@e2e/fixtures/utils/workspaceMocks'
 export const APP_URL =
   process.env.PLAYWRIGHT_TEST_URL || 'http://localhost:8188'
 
-// consolidated_billing_enabled routes personal workspaces to the unified
-// billing surfaces the cloud specs assert; without it they fall back to the
-// legacy variants.
-const DEFAULT_FEATURES = {
-  consolidated_billing_enabled: true
-} satisfies RemoteConfig
-
 // Disable the experimental Asset API: with it on (cloud default) the unmocked
 // asset endpoints 403 and workflow restore throws uncaught, aborting the
 // GraphCanvas onMounted chain before the URL action loaders.
@@ -63,7 +56,7 @@ export async function setupCloudApp(
   { workspace, members = [], features }: CloudAppSetupOptions
 ) {
   await mockCloudBoot(page, {
-    features: { ...DEFAULT_FEATURES, ...features },
+    features: features ?? {},
     settings: DEFAULT_SETTINGS
   })
   await mockGraphBootExtras(page)

browser_tests/fixtures/utils/cloudBillingMocks.ts

@@ -29,9 +29,6 @@ export async function mockBilling(page: Page) {
   await page.route('**/api/billing/plans', (r) =>
     r.fulfill(jsonRoute({ plans: [] }))
   )
-  await page.route('**/customers/cloud-subscription-status', (r) =>
-    r.fulfill(jsonRoute({ is_active: false }))
-  )
   await page.route('**/customers/balance', (r) =>
     r.fulfill(jsonRoute({ amount_micros: 0, currency: 'usd' }))
   )

browser_tests/tests/billingFacadeConsumers.spec.ts

@@ -1,8 +1,11 @@
 import { expect } from '@playwright/test'
 import type { Page } from '@playwright/test'
 
-import type { CloudSubscriptionStatusResponse } from '@/platform/cloud/subscription/composables/useSubscription'
 import type { RemoteConfig } from '@/platform/remoteConfig/types'
+import {
+  PENDING_SUBSCRIPTION_CHECKOUT_EVENT,
+  PENDING_SUBSCRIPTION_CHECKOUT_STORAGE_KEY
+} from '@/platform/cloud/subscription/utils/subscriptionCheckoutTracker'
 import type {
   BillingBalanceResponse,
   BillingStatusResponse
@@ -33,21 +36,6 @@ const jsonRoute = (body: unknown) => ({
   body: JSON.stringify(body)
 })
 
-// The workspace `/api/billing/status` shape mirrors the legacy subscription
-// status; map the fields so a single test fixture drives both backends.
-const toWorkspaceStatus = (
-  s: CloudSubscriptionStatusResponse
-): BillingStatusResponse => ({
-  is_active: s.is_active ?? false,
-  max_seats: 1,
-  occupied_seats: 1,
-  subscription_tier: s.subscription_tier ?? undefined,
-  subscription_duration: s.subscription_duration ?? undefined,
-  renewal_date: s.renewal_date ?? undefined,
-  cancel_at: s.end_date ?? undefined,
-  has_funds: s.has_fund ?? true
-})
-
 const mockBalance: BillingBalanceResponse = {
   amount_micros: 6000, // -> 12,660 credits
   currency: 'usd',
@@ -62,7 +50,7 @@ const mockWorkspaceBalance: BillingBalanceResponse = {
 
 async function mockCloudBoot(
   page: Page,
-  subscriptionStatus: CloudSubscriptionStatusResponse,
+  subscriptionStatus: BillingStatusResponse,
   remoteConfig: RemoteConfig = {},
   billingRail?: BillingStatusResponse['billing_rail']
 ) {
@@ -117,22 +105,21 @@ async function mockCloudBoot(
     )
   )
 
-  // Legacy endpoints remain mocked for consumers that explicitly use them.
-  await page.route('**/customers/cloud-subscription-status', (r) => {
-    billingRequests.legacyStatus++
-    return r.fulfill(jsonRoute(subscriptionStatus))
-  })
   await page.route('**/customers/balance', (r) => {
     billingRequests.legacyBalance++
     return r.fulfill(jsonRoute(mockBalance))
   })
+  await page.route('**/customers/cloud-subscription-status', (r) => {
+    billingRequests.legacyStatus++
+    return r.fulfill(jsonRoute(subscriptionStatus))
+  })
 
   // Cloud personal workspaces route through `/api/billing/*`.
   await page.route('**/api/billing/status', (r) => {
     billingRequests.workspaceStatus++
     return r.fulfill(
       jsonRoute({
-        ...toWorkspaceStatus(subscriptionStatus),
+        ...subscriptionStatus,
         billing_rail: billingRail
       })
     )
@@ -174,21 +161,42 @@ test.describe('Billing facade consumers (FE-933)', { tag: '@cloud' }, () => {
         subscription_tier: 'PRO',
         subscription_duration: 'MONTHLY',
         renewal_date: '2099-02-20T10:00:00Z',
-        end_date: null
+        has_funds: true
       },
-      { consolidated_billing_enabled: true },
+      {},
       'legacy_stripe'
     )
     await bootApp(page)
+    await expect.poll(() => billingRequests.workspaceStatus).toBeGreaterThan(1)
 
     await page.getByRole('button', { name: 'Current user' }).click()
     const popover = page.locator('.current-user-popover')
     await expect(popover).toBeVisible()
+    await expect(popover.getByText('12,660')).toBeVisible()
+
+    await page.evaluate((storageKey) => {
+      localStorage.setItem(
+        storageKey,
+        JSON.stringify({
+          attempt_id: 'rail-selection-regression',
+          started_at_ms: Date.now(),
+          tier: 'pro',
+          cycle: 'monthly',
+          checkout_type: 'change'
+        })
+      )
+    }, PENDING_SUBSCRIPTION_CHECKOUT_STORAGE_KEY)
+    billingRequests.workspaceStatus = 0
+    await page.evaluate(
+      (eventName) => window.dispatchEvent(new Event(eventName)),
+      PENDING_SUBSCRIPTION_CHECKOUT_EVENT
+    )
 
     await expect(popover.getByText('12,660')).toBeVisible()
+    await expect(popover.getByText('0', { exact: true })).toHaveCount(0)
     await expect(popover.getByTestId('add-credits-button')).toBeVisible()
-    expect(billingRequests.workspaceStatus).toBeGreaterThan(0)
-    expect(billingRequests.legacyStatus).toBeGreaterThan(0)
+    await expect.poll(() => billingRequests.workspaceStatus).toBeGreaterThan(0)
+    expect(billingRequests.legacyStatus).toBe(0)
     expect(billingRequests.legacyBalance).toBeGreaterThan(0)
   })
 
@@ -211,12 +219,12 @@ test.describe('Billing facade consumers (FE-933)', { tag: '@cloud' }, () => {
         subscription_duration: 'MONTHLY',
         // 10:00Z keeps the en-US calendar date stable across CI timezones.
         renewal_date: '2099-02-20T10:00:00Z',
-        end_date: null
+        has_funds: false
       },
       {
-        subscription_required: true,
-        consolidated_billing_enabled: true
-      }
+        subscription_required: true
+      },
+      'stripe'
     )
     await bootApp(page)