fix(billing): judge mid-run usage against the payer's current period

- Mid-run checks always judge the admitted payer's current subscription
  period (cached for a minute), so an early anchor move or a rollover is
  judged against the period charges now land in; a straddling read is judged
  again against the next period.
- A direct-v1 continuation checks the payer saved in its account decision,
  against that payer's current period, never a payer chosen from the actor's
  current memberships.
- An unreadable usage read no longer reports a spent-limit message; new turns
  refused for it get neutral copy.
- Dispatch-time refusals pass the verdict scope, so a member over the cap
  their organization set gets the member card.

Author: waleedlatif1

apps/sim/app/api/billing/update-cost/route.test.ts

@@ -49,6 +49,7 @@ vi.mock('@/lib/billing/threshold-billing', () => ({
 }))
 
 import { billingUpdateCostResponseSchema } from '@/lib/api/contracts/subscription'
+import { resetMidRunPeriodCache } from '@/lib/billing/core/mid-run-usage'
 import { resetUsageGateCache } from '@/lib/billing/core/usage-gate-cache'
 import {
   BillingCallbackBody,
@@ -896,11 +897,13 @@ describe('POST /api/billing/update-cost — mid-run usage gate', () => {
 
   beforeEach(() => {
     resetUsageGateCache()
+    resetMidRunPeriodCache()
     setEnvFlags({ isBillingEnabled: true, isHosted: true })
     mockCheckInternalApiKey.mockReturnValue({ success: true })
     mockRecordCumulativeUsage.mockResolvedValue({ billed: true, delta: 0.5, total: 0.5 })
     mockCheckAndBillPayerOverageThreshold.mockResolvedValue(undefined)
     mockRequireBillingAttributionHeader.mockReturnValue(CURRENT_ATTRIBUTION)
+    mockRefreshAttributionPeriod.mockImplementation(async (attribution: unknown) => attribution)
     mockToBillingContext.mockReturnValue({
       billingEntity: { type: 'organization', id: 'org-1' },
       billingPeriod: {
@@ -1099,6 +1102,22 @@ describe('POST /api/billing/update-cost — mid-run usage gate', () => {
     expect(body.usageExceeded).toBe(true)
   })
 
+  it('judges a run whose payer period moved early against the moved period', async () => {
+    const moved = {
+      ...CURRENT_ATTRIBUTION,
+      billingPeriod: { start: '2026-07-15T00:00:00.000Z', end: '2099-02-01T00:00:00.000Z' },
+    }
+    mockRefreshAttributionPeriod.mockResolvedValue(moved)
+    mockCheckAttributedUsageLimits.mockImplementation(async (attribution: typeof moved) => ({
+      isExceeded: attribution.billingPeriod.start === moved.billingPeriod.start,
+      scope: 'payer',
+    }))
+
+    const body = await (await POST(attributedCallback())).json()
+
+    expect(body.usageExceeded).toBe(true)
+  })
+
   it('keeps a run going when its current period cannot be read', async () => {
     mockRequireBillingAttributionHeader.mockReturnValue(ATTRIBUTION)
     mockRefreshAttributionPeriod.mockRejectedValue(new Error('subscription read timed out'))

apps/sim/app/api/copilot/api-keys/validate/route.test.ts

@@ -6,6 +6,7 @@ import {
   schemaMock,
   setEnvFlags,
 } from '@sim/testing'
+import { billingCoreMock, billingCoreMockFns } from '@sim/testing/mocks/billing-core.mock'
 import { billingPlanMock, billingPlanMockFns } from '@sim/testing/mocks/billing-plan.mock'
 import {
   billingSubscriptionMock,
@@ -118,6 +119,8 @@ vi.mock('@/lib/billing/calculations/usage-monitor', () => billingUsageMonitorMoc
 
 vi.mock('@/lib/billing/core/plan', () => billingPlanMock)
 
+vi.mock('@/lib/billing/core/billing', () => billingCoreMock)
+
 vi.mock('@/lib/billing/core/subscription', () => billingSubscriptionMock)
 
 vi.mock('@/lib/billing/core/usage-log', () => billingUsageLogMock)
@@ -138,6 +141,7 @@ vi.mock('@/lib/workspaces/permissions/utils', () => permissionsMock)
 vi.mock('@/lib/workspaces/utils', () => workspacesUtilsMock)
 
 import { validateCopilotApiKeyBodySchema } from '@/lib/api/contracts/copilot'
+import { resetMidRunPeriodCache } from '@/lib/billing/core/mid-run-usage'
 import { resetUsageGateCache } from '@/lib/billing/core/usage-gate-cache'
 import { POST } from '@/app/api/copilot/api-keys/validate/route'
 
@@ -147,6 +151,7 @@ const { mockAuthorizeOrganizationChatDelegation: mockAuthorizeOrganizationChat }
   mothershipOrganizationChatsMockFns
 const { mockDeriveBillingContext } = billingUsageLogMockFns
 const { mockGetHighestPrioritySubscription } = billingPlanMockFns
+const { mockGetOrganizationSubscription } = billingCoreMockFns
 const { mockCheckServerSideUsageLimits, mockCheckUsageStatus } = billingUsageMonitorMockFns
 
 const mockIsEnterprisePlan = billingSubscriptionMockFns.mockIsEnterprisePlan
@@ -510,7 +515,16 @@ describe('validation lifecycle purposes', () => {
     mockCheckAttributedUsageLimits.mockResolvedValue({ isExceeded: false })
     mockCheckUsageStatus.mockResolvedValue({ isExceeded: false, currentUsage: 1, limit: 10 })
     mockIsEnterprisePlan.mockResolvedValue(false)
+    mockGetOrganizationSubscription.mockResolvedValue({
+      id: 'sub-org-1',
+      referenceId: 'org-1',
+      plan: 'enterprise',
+      status: 'active',
+      periodStart: new Date(ATTRIBUTION.billingPeriod.start),
+      periodEnd: new Date(ATTRIBUTION.billingPeriod.end),
+    })
     resetUsageGateCache()
+    resetMidRunPeriodCache()
   })
 
   it('defaults older callers to full admission and rejects unknown purposes', () => {
@@ -531,7 +545,6 @@ describe('validation lifecycle purposes', () => {
     expect(mockAuthorizeCallback.mock.invocationCallOrder[0]).toBeLessThan(
       mockCheckContinuationBilling.mock.invocationCallOrder[0]
     )
-    expect(mockCheckAttributedUsageLimits).toHaveBeenCalledWith(ATTRIBUTION)
     expect(mockCheckServerSideUsageLimits).not.toHaveBeenCalled()
     expect(mockResolveLegacyV0BillingAttribution).not.toHaveBeenCalled()
     expect(mockGetHighestPrioritySubscription).not.toHaveBeenCalled()
@@ -729,6 +742,60 @@ describe('validation lifecycle purposes', () => {
     expect(mockCheckAttributedUsageLimits).toHaveBeenCalledTimes(3)
   })
 
+  it('refuses a new turn whose usage cannot be read with neutral copy', async () => {
+    mockCheckAttributedUsageLimits.mockResolvedValueOnce({
+      isExceeded: true,
+      reason: 'usage_unavailable',
+      message: 'Usage limit exceeded: $0.00 used of $0.00 limit.',
+      scope: 'payer',
+    })
+    const refused = await POST(request({ ...body, purpose: 'new-turn' }, attributedHeaders))
+    expect(refused.status).toBe(402)
+    const refusal = await refused.json()
+    expect(refusal.code).toBe('USAGE_UNAVAILABLE')
+    expect(refusal.error).not.toMatch(/\$/)
+  })
+
+  it('checks the payer saved at admission for a direct-v1 run whose actor changed orgs', async () => {
+    const endedDecision = {
+      ...ACCOUNT_BILLING_DECISION,
+      billingPeriod: { start: '2026-06-01T00:00:00.000Z', end: '2026-07-01T00:00:00.000Z' },
+    }
+    mockGetHighestPrioritySubscription.mockResolvedValue({
+      id: 'sub-new-org',
+      referenceId: 'new-org',
+      plan: 'team',
+      status: 'active',
+      periodStart: new Date('2026-07-01T00:00:00.000Z'),
+      periodEnd: new Date('2099-01-01T00:00:00.000Z'),
+    })
+    mockGetOrganizationSubscription.mockResolvedValue({
+      id: 'sub-account-org',
+      referenceId: 'account-org',
+      plan: 'team',
+      status: 'active',
+      periodStart: new Date('2026-07-01T00:00:00.000Z'),
+      periodEnd: new Date('2099-01-01T00:00:00.000Z'),
+    })
+    mockCheckUsageStatus.mockImplementation(
+      async (
+        _userId: string,
+        _subscription: unknown,
+        context?: { billingEntity: { id: string } }
+      ) => ({
+        isExceeded: context?.billingEntity.id === 'account-org',
+        currentUsage: 12,
+        limit: 10,
+      })
+    )
+
+    const response = await POST(
+      request(body, { ...directHeaders, 'x-sim-billing-account-decision': encode(endedDecision) })
+    )
+
+    expect(response.status).toBe(402)
+  })
+
   it('refuses a blocked new turn with the blocked body the contract declares', async () => {
     mockCheckAttributedUsageLimits.mockResolvedValueOnce({
       isExceeded: true,

apps/sim/app/api/copilot/api-keys/validate/route.ts

@@ -15,6 +15,7 @@ import {
 } from '@/lib/api/contracts/copilot'
 import { parseRequest, validationErrorResponse } from '@/lib/api/server'
 import { checkServerSideUsageLimits } from '@/lib/billing/calculations/usage-monitor'
+import { USAGE_UNAVAILABLE_MESSAGE } from '@/lib/billing/constants'
 import {
   type AccountBillingDecision,
   type BillingAttributionSnapshot,
@@ -68,7 +69,6 @@ const logger = createLogger('CopilotApiKeysValidate')
 
 const CONTINUATION_BLOCKED_MESSAGE = 'Continuation billing account is blocked'
 const BILLING_BLOCKED_MESSAGE = 'Billing account is blocked'
-const USAGE_UNAVAILABLE_MESSAGE = 'Usage could not be verified. Please try again.'
 
 function invalidBillingProtocolResponse(): NextResponse {
   return NextResponse.json({ error: 'Invalid billing attribution protocol' }, { status: 400 })
@@ -269,10 +269,7 @@ async function admissionRefusal(
     return { code: COPILOT_BILLING_BLOCKED_CODE, error: usage.message ?? BILLING_BLOCKED_MESSAGE }
   }
   if (usage.reason === 'usage_unavailable') {
-    return {
-      code: COPILOT_USAGE_UNAVAILABLE_CODE,
-      error: usage.message ?? USAGE_UNAVAILABLE_MESSAGE,
-    }
+    return { code: COPILOT_USAGE_UNAVAILABLE_CODE, error: USAGE_UNAVAILABLE_MESSAGE }
   }
   const usageUpgrade = await resolveUsageUpgradePayload(
     userId,

apps/sim/lib/billing/calculations/usage-monitor.test.ts

@@ -213,6 +213,23 @@ describe('checkServerSideUsageLimits', () => {
     mockGetBillingPeriodUsageCost.mockResolvedValue(125)
   })
 
+  it('does not describe an unreadable ledger as a spent limit', async () => {
+    dbChainMockFns.limit.mockResolvedValueOnce([{ blocked: false }])
+    mockGetBillingPeriodUsageCost.mockRejectedValueOnce(new Error('canceling statement'))
+
+    const result = await checkServerSideUsageLimits('user-1', {
+      referenceId: 'user-1',
+      plan: 'free',
+      status: 'active',
+      seats: 1,
+      periodStart: new Date('2026-06-01T00:00:00.000Z'),
+      periodEnd: new Date('2026-07-01T00:00:00.000Z'),
+    })
+
+    expect(result).toMatchObject({ isExceeded: true, reason: 'usage_unavailable' })
+    expect(result.message ?? '').not.toMatch(/\$/)
+  })
+
   it('keeps blocked accounts blocked while reporting their real ledger usage', async () => {
     dbChainMockFns.limit.mockResolvedValueOnce([{ blocked: true, blockedReason: 'payment_failed' }])
     const subscription = {

apps/sim/lib/billing/calculations/usage-monitor.ts

@@ -3,6 +3,7 @@ import { userStats } from '@sim/db/schema'
 import { createLogger } from '@sim/logger'
 import { toError } from '@sim/utils/errors'
 import { eq } from 'drizzle-orm'
+import { USAGE_UNAVAILABLE_MESSAGE } from '@/lib/billing/constants'
 import { isOrganizationBillingBlocked } from '@/lib/billing/core/access'
 import { defaultBillingPeriod } from '@/lib/billing/core/billing-period'
 import { getHighestPrioritySubscription } from '@/lib/billing/core/plan'
@@ -366,7 +367,11 @@ export async function checkServerSideUsageLimits(
       isExceeded: usageData.isExceeded,
       currentUsage: usageData.currentUsage,
       limit: usageData.limit,
-      message: usageData.isExceeded ? exceededMessage : undefined,
+      message: usageData.unavailable
+        ? USAGE_UNAVAILABLE_MESSAGE
+        : usageData.isExceeded
+          ? exceededMessage
+          : undefined,
       ...(usageData.unavailable ? { reason: 'usage_unavailable' as const } : {}),
     }
   } catch (error) {

apps/sim/lib/billing/constants.ts

@@ -103,3 +103,7 @@ export const ANNUAL_DISCOUNT_RATE = 0.15
  * Effectively unlimited — any limit >= this threshold is treated as uncapped.
  */
 export const ON_DEMAND_UNLIMITED = 999999
+
+/** Shown when usage could not be read, instead of a limit the read never measured. */
+export const USAGE_UNAVAILABLE_MESSAGE =
+  'Usage could not be verified right now. Please try again in a moment.'

apps/sim/lib/billing/core/billing-attribution.test.ts

@@ -449,10 +449,9 @@ describe('checkAttributedUsageLimits', () => {
       scope: 'user',
       unavailable: true,
     })
-    await expect(checkAttributedUsageLimits(attribution)).resolves.toMatchObject({
-      isExceeded: true,
-      reason: 'usage_unavailable',
-    })
+    const unavailable = await checkAttributedUsageLimits(attribution)
+    expect(unavailable).toMatchObject({ isExceeded: true, reason: 'usage_unavailable' })
+    expect(unavailable.message ?? '').not.toMatch(/\$/)
   })
 
   it('returns payer exhaustion before checking the actor member cap', async () => {

apps/sim/lib/billing/core/billing-attribution.ts

@@ -10,6 +10,7 @@ import {
   checkUsageStatus,
 } from '@/lib/billing/calculations/usage-monitor'
 import { parseBillingConcurrencyLimit } from '@/lib/billing/concurrency-defaults'
+import { USAGE_UNAVAILABLE_MESSAGE } from '@/lib/billing/constants'
 import { getOrganizationSubscription } from '@/lib/billing/core/billing'
 import { defaultBillingPeriod } from '@/lib/billing/core/billing-period'
 import { getHighestPriorityPersonalSubscription } from '@/lib/billing/core/plan'
@@ -970,8 +971,9 @@ export async function checkAttributedUsageLimits(
   if (payerUsage.isExceeded) {
     const formattedUsage = payerUsage.currentUsage.toFixed(2)
     const formattedLimit = payerUsage.limit.toFixed(2)
-    const message =
-      validatedAttribution.billingEntity.type === 'organization'
+    const message = payerUsage.unavailable
+      ? USAGE_UNAVAILABLE_MESSAGE
+      : validatedAttribution.billingEntity.type === 'organization'
         ? `Organization usage limit exceeded: $${formattedUsage} pooled of $${formattedLimit} organization limit. Ask a team admin to raise the organization usage limit to continue.`
         : `Usage limit exceeded: $${formattedUsage} used of $${formattedLimit} limit. Please upgrade your plan or raise your usage limit to continue.`