fix(billing): roll forward-moved periods, lock only past period end, skip ended admissions

- Roll a cumulative charge into the payer's current period whenever that
  period starts after the latest row's, so an anchor reset or resync inside
  the old period never tops up a closed period.
- Share-lock the payer's subscription row only once the latest row's period
  has ended; before that no close can be due, and the lock would starve the
  rollover update for a busy payer.
- Mid-run usage checks report unknown (continue) once the run's admitted
  period has ended, instead of judging the old period against its allowance.
- Refuse request keys containing "@" when period rows are in play, so they
  cannot collide with another request's period rows.
- Document the mixed-version and rollback window: code that predates period
  rows can double-count a run's post-rollover spend only between a rollover
  and that period's close (at least an hour); the exposure is cents to dollars.

Author: waleedlatif1

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

@@ -852,6 +852,10 @@ describe('POST /api/billing/update-cost — workspaceId attribution', () => {
 
 describe('POST /api/billing/update-cost — mid-run usage gate', () => {
   let callbackSequence = 0
+  const CURRENT_ATTRIBUTION = {
+    ...ATTRIBUTION,
+    billingPeriod: { start: '2026-07-01T00:00:00.000Z', end: '2099-01-01T00:00:00.000Z' },
+  }
 
   function attributedCallback() {
     callbackSequence += 1
@@ -881,7 +885,7 @@ describe('POST /api/billing/update-cost — mid-run usage gate', () => {
     mockCheckInternalApiKey.mockReturnValue({ success: true })
     mockRecordCumulativeUsage.mockResolvedValue({ billed: true, delta: 0.5, total: 0.5 })
     mockCheckAndBillPayerOverageThreshold.mockResolvedValue(undefined)
-    mockRequireBillingAttributionHeader.mockReturnValue(ATTRIBUTION)
+    mockRequireBillingAttributionHeader.mockReturnValue(CURRENT_ATTRIBUTION)
     mockToBillingContext.mockReturnValue({
       billingEntity: { type: 'organization', id: 'org-1' },
       billingPeriod: {
@@ -906,12 +910,12 @@ describe('POST /api/billing/update-cost — mid-run usage gate', () => {
         message: expect.stringContaining('usage limit'),
       },
     })
-    expect(mockCheckAttributedUsageLimits).toHaveBeenCalledWith(ATTRIBUTION)
+    expect(mockCheckAttributedUsageLimits).toHaveBeenCalledWith(CURRENT_ATTRIBUTION)
   })
 
   it('offers a paid organization payer the increase-limit card', async () => {
     mockRequireBillingAttributionHeader.mockReturnValue({
-      ...ATTRIBUTION,
+      ...CURRENT_ATTRIBUTION,
       payerSubscription: { id: 'sub-1', plan: 'team', status: 'active', seats: 4 },
     })
     mockCheckAttributedUsageLimits.mockResolvedValue({ isExceeded: true, scope: 'payer' })
@@ -971,7 +975,7 @@ describe('POST /api/billing/update-cost — mid-run usage gate', () => {
     beforeEach(() => {
       mockCheckAttributedUsageLimits.mockResolvedValue({ isExceeded: false })
       mockRequireBillingAttributionHeader.mockReturnValue({
-        ...ATTRIBUTION,
+        ...CURRENT_ATTRIBUTION,
         payerSubscription: PAYER_SUBSCRIPTION,
       })
     })
@@ -1061,6 +1065,16 @@ describe('POST /api/billing/update-cost — mid-run usage gate', () => {
     })
   })
 
+  it('does not judge a run against an admitted period that has already ended', async () => {
+    mockRequireBillingAttributionHeader.mockReturnValue(ATTRIBUTION)
+    mockCheckAttributedUsageLimits.mockResolvedValue({ isExceeded: true, scope: 'payer' })
+
+    const body = await (await POST(attributedCallback())).json()
+
+    expect(body.usageExceeded).toBe(false)
+    expect(mockCheckAttributedUsageLimits).not.toHaveBeenCalled()
+  })
+
   it('keeps a recorded charge successful when the gate read fails', async () => {
     mockCheckAttributedUsageLimits.mockRejectedValue(new Error('ledger read timed out'))
 

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

@@ -63,7 +63,7 @@ const ATTRIBUTION = {
   billingEntity: { type: 'organization' as const, id: 'org-1' },
   billingPeriod: {
     start: '2026-07-01T00:00:00.000Z',
-    end: '2026-08-01T00:00:00.000Z',
+    end: '2099-01-01T00:00:00.000Z',
     source: 'reporting' as const,
   },
   payerSubscription: null,

apps/sim/lib/billing/core/mid-run-usage.ts

@@ -14,9 +14,9 @@ const logger = createLogger('MidRunUsage')
  *   upgrade card.
  * - `blocked`: the account is blocked (payment failed, dispute); the run is refused as a blocked
  *   account, never with the upgrade card.
- * - `unknown`: the gate could not read usage. Admission fails closed on this, but a run already
- *   under way continues: a database blip must not end a paying user's long run, and the next
- *   step or re-check reads again.
+ * - `unknown`: the gate could not read usage, or the run's admitted period has ended. Admission
+ *   fails closed on an unreadable ledger, but a run already under way continues: a database
+ *   blip must not end a paying user's long run, and the next step or re-check reads again.
  */
 export type MidRunUsageVerdict =
   | { status: 'within' }
@@ -27,6 +27,12 @@ export type MidRunUsageVerdict =
 export async function readMidRunUsageVerdict(
   attribution: BillingAttributionSnapshot
 ): Promise<MidRunUsageVerdict> {
+  // The gate judges the admitted snapshot's period. Once that period has ended it would keep
+  // counting the old period against the old allowance, so a run just past a reset is not judged
+  // until its next admission reads the new one.
+  if (Date.now() >= new Date(attribution.billingPeriod.end).getTime()) {
+    return { status: 'unknown' }
+  }
   let usage: AttributedUsageLimitsResult
   try {
     usage = await checkExecutionUsageLimits(attribution)

apps/sim/lib/billing/core/usage-log.integration.ts

@@ -314,38 +314,52 @@ describe('Cumulative billing with PostgreSQL', () => {
   )
 
   describe('a request that outlives its billing period', () => {
+    // Past periods: the old period's row is written under the subscription lock only once
+    // that period has ended.
     const periods = [
-      new Date('2026-09-01T00:00:00.000Z'),
-      new Date('2026-10-01T00:00:00.000Z'),
-      new Date('2026-11-01T00:00:00.000Z'),
-      new Date('2026-12-01T00:00:00.000Z'),
+      new Date('2025-09-01T00:00:00.000Z'),
+      new Date('2025-10-01T00:00:00.000Z'),
+      new Date('2025-11-01T00:00:00.000Z'),
+      new Date('2025-12-01T00:00:00.000Z'),
     ]
     const payer = { type: 'organization', id: 'payer' } as const
 
-    async function setSubscriptionPeriod(index: number) {
+    async function setSubscriptionWindow(start: Date, end: Date) {
       await connection`
         insert into subscription (id, period_start, period_end)
-        values ('sub-1', ${periods[index].toISOString()}::timestamptz at time zone 'UTC', ${periods[index + 1].toISOString()}::timestamptz at time zone 'UTC')
+        values ('sub-1', ${start.toISOString()}::timestamptz at time zone 'UTC', ${end.toISOString()}::timestamptz at time zone 'UTC')
         on conflict (id) do update
           set period_start = excluded.period_start, period_end = excluded.period_end
       `
     }
 
-    function charge(cost: number) {
-      return recordCumulativeUsage({ ...usage(cost), payerSubscriptionId: 'sub-1' })
+    async function setSubscriptionPeriod(index: number) {
+      await setSubscriptionWindow(periods[index], periods[index + 1])
+    }
+
+    function charge(cost: number, frozen = { start: periods[0], end: periods[1] }) {
+      return recordCumulativeUsage({
+        ...usage(cost),
+        billingPeriod: frozen,
+        payerSubscriptionId: 'sub-1',
+      })
     }
 
     /** What the cycle close invoices for one period: the ledger rows stamped with it. */
-    async function stampedTotal(index: number) {
+    async function stampedWindowTotal(from: Date, to: Date) {
       const byUser = await getStampedPeriodRangeUsageCostByUser(
         payer,
-        { from: periods[index], to: periods[index + 1] },
+        { from, to },
         undefined,
         database
       )
       return [...byUser.values()].reduce((total, cost) => total + cost, 0)
     }
 
+    function stampedTotal(index: number) {
+      return stampedWindowTotal(periods[index], periods[index + 1])
+    }
+
     it('invoices a charge that spans a period close exactly once in total', async () => {
       await setSubscriptionPeriod(0)
       expect(await charge(0.4)).toMatchObject({ billed: true, total: 0.4 })
@@ -410,5 +424,50 @@ describe('Cumulative billing with PostgreSQL', () => {
       }
       expect(await stampedTotal(0)).toBeCloseTo(0.6, 9)
     })
+
+    it('rolls into a period whose start moved forward before the old period ended', async () => {
+      await setSubscriptionPeriod(0)
+      await charge(0.4)
+      const resetStart = new Date('2025-09-15T00:00:00.000Z')
+      const resetEnd = new Date('2025-10-15T00:00:00.000Z')
+      await setSubscriptionWindow(resetStart, resetEnd)
+
+      expect(await charge(1)).toMatchObject({
+        billed: true,
+        billingPeriod: { start: resetStart, end: resetEnd },
+      })
+      expect(await stampedTotal(0)).toBeCloseTo(0.4, 9)
+      expect(await stampedWindowTotal(resetStart, resetEnd)).toBeCloseTo(0.6, 9)
+    })
+
+    it('does not hold the rollover while the latest period is still running', async () => {
+      const start = new Date(Date.now() - 24 * 60 * 60 * 1000)
+      const end = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000)
+      await setSubscriptionWindow(start, end)
+      await charge(0.4, { start, end })
+      const pause = pauseNextTransaction()
+      const inFlight = charge(0.6, { start, end })
+      try {
+        await pause.reached.promise
+        await connection.begin(async (tx) => {
+          await tx`select set_config('lock_timeout', '300ms', true)`
+          await tx`update subscription set period_end = period_end where id = 'sub-1'`
+        })
+      } finally {
+        pause.release.resolve()
+        await inFlight
+      }
+    })
+
+    it('refuses a request key that could collide with its period rows', async () => {
+      await setSubscriptionPeriod(0)
+      await expect(
+        recordCumulativeUsage({
+          ...usage(0.4, 'update-cost:request@1'),
+          payerSubscriptionId: 'sub-1',
+        })
+      ).rejects.toThrow('@')
+      expect(await ledgerRows()).toEqual([])
+    })
   })
 })

apps/sim/lib/billing/core/usage-log.ts

@@ -591,6 +591,13 @@ export interface RecordCumulativeUsageParams {
    * recorded in a new row stamped with the subscription's current period, so a request that
    * outlives its billing period is invoiced by the period it was spent in rather than topping up
    * a period that has already been closed. Omit it for reporting-window and free payers.
+   *
+   * Mixed versions: code that predates period rows reads only the request key. If such code
+   * (during a deploy, or after a rollback) handles a later callback for a request that already
+   * has period rows, it re-adds those rows' amount to the first row. That only double-counts
+   * when it lands between the rollover and that period's close, which waits at least an hour,
+   * and only for runs spanning a rollover; the exposure is one run's post-rollover spend, cents
+   * to dollars.
    */
   payerSubscriptionId?: string
 }
@@ -612,7 +619,10 @@ export interface RecordCumulativeUsageResult {
  */
 const MAX_CUMULATIVE_PERIOD_ROWS = 12
 
-/** The ledger key of the `index`-th period a cumulative request rolled into; 0 is the request key. */
+/**
+ * The ledger key of the `index`-th period a cumulative request rolled into; 0 is the request key.
+ * A request key may not itself contain `@`, so these keys never collide with another request's.
+ */
 function cumulativePeriodEventKey(eventKey: string, index: number): string {
   return index === 0 ? eventKey : `${eventKey}@${index}`
 }
@@ -774,6 +784,9 @@ export async function recordCumulativeUsage(
   }
 
   const billingContext = await resolveBillingContext(userId, billingEntity, billingPeriod)
+  if (payerSubscriptionId && eventKey.includes('@')) {
+    throw new Error(`Cumulative usage event "${eventKey}" must not contain "@"`)
+  }
 
   const startedAt = Date.now()
   let stage: CumulativeUsageStage = 'pool'
@@ -808,20 +821,6 @@ export async function recordCumulativeUsage(
       await acquireAdvisoryXactLock(tx, 'usage_log_event', eventKey)
 
       enterStage('read')
-      // The payer's current period, share-locked so a rollover of the subscription waits for
-      // this top-up to commit: whatever a close later sums for the old period is final.
-      const [currentPeriod] = payerSubscriptionId
-        ? await tx
-            .select({
-              start: subscriptionTable.periodStart,
-              end: subscriptionTable.periodEnd,
-            })
-            .from(subscriptionTable)
-            .where(eq(subscriptionTable.id, payerSubscriptionId))
-            .for('share')
-            .limit(1)
-        : []
-
       const rows = await tx
         .select({
           id: usageLog.id,
@@ -881,12 +880,34 @@ export async function recordCumulativeUsage(
         return { billed: false, delta: 0, total: recorded, billingPeriod: latestPeriod }
       }
 
-      // Only ever forward: a subscription period that is not past the latest row keeps topping
-      // up that row, whatever the wall clock or a replayed webhook says.
+      // The payer's current period. Once the latest row's period has ended, the read is
+      // share-locked so a rollover of the subscription waits for this top-up to commit, and
+      // whatever the close later sums for the old period is final. Before that no close can be
+      // due, and locking every callback would starve the rollover UPDATE for a busy payer.
+      const periodQuery = payerSubscriptionId
+        ? tx
+            .select({
+              start: subscriptionTable.periodStart,
+              end: subscriptionTable.periodEnd,
+            })
+            .from(subscriptionTable)
+            .where(eq(subscriptionTable.id, payerSubscriptionId))
+            .limit(1)
+        : null
+      const [currentPeriod] = periodQuery
+        ? Date.now() >= latestPeriod.end.getTime()
+          ? await periodQuery.for('share')
+          : await periodQuery
+        : []
+
+      // Only ever forward: a subscription period that does not start after the latest row's
+      // keeps topping up that row, whatever the wall clock or a replayed webhook says. A start
+      // that moved forward inside the old period (anchor reset, resync) still rolls, so the old
+      // period's close is never topped up after the fact.
       const rolledPeriod =
         currentPeriod?.start &&
         currentPeriod.end &&
-        currentPeriod.start.getTime() >= latestPeriod.end.getTime()
+        currentPeriod.start.getTime() > latestPeriod.start.getTime()
           ? { start: currentPeriod.start, end: currentPeriod.end }
           : null
       if (rolledPeriod && latest && chain.length >= MAX_CUMULATIVE_PERIOD_ROWS) {

apps/sim/lib/mothership/request/lifecycle/admission.test.ts

@@ -22,7 +22,7 @@ const attribution = {
   organizationId: 'original-org',
   billedAccountUserId: 'original-owner',
   billingEntity: { type: 'organization' as const, id: 'original-org' },
-  billingPeriod: { start: '2026-09-01T00:00:00.000Z', end: '2026-10-01T00:00:00.000Z' },
+  billingPeriod: { start: '2026-09-01T00:00:00.000Z', end: '2099-01-01T00:00:00.000Z' },
   payerSubscription: null,
 }
 const context = {
@@ -121,4 +121,18 @@ describe('continuation admission', () => {
     await expect(refusal).rejects.toBeInstanceOf(OrchestrationError)
     await expect(refusal).rejects.toThrow('blocked')
   })
+  it('lets a leg run once its admitted period has ended instead of judging the old period', async () => {
+    mockCheckExecutionUsageLimits.mockResolvedValue({ isExceeded: true, scope: 'payer' })
+
+    await expect(
+      authorizeLifecycleContinuation({
+        ...context,
+        billingAttribution: {
+          ...attribution,
+          billingPeriod: { start: '2026-07-01T00:00:00.000Z', end: '2026-08-01T00:00:00.000Z' },
+        },
+      })
+    ).resolves.toBeUndefined()
+    expect(mockCheckExecutionUsageLimits).not.toHaveBeenCalled()
+  })
 })

apps/sim/lib/mothership/request/lifecycle/run.test.ts

@@ -2343,7 +2343,7 @@ describe('runCopilotLifecycle', () => {
       organizationId: 'org-1',
       billedAccountUserId: 'original-owner',
       billingEntity: { type: 'organization' as const, id: 'org-1' },
-      billingPeriod: { start: '2026-07-01T00:00:00.000Z', end: '2026-08-01T00:00:00.000Z' },
+      billingPeriod: { start: '2026-07-01T00:00:00.000Z', end: '2099-01-01T00:00:00.000Z' },
       payerSubscription: null,
     }
     setEnvFlags({ isHosted: true })
@@ -2430,7 +2430,7 @@ describe('runCopilotLifecycle', () => {
       organizationId: 'org-1',
       billedAccountUserId: 'user-1',
       billingEntity: { type: 'organization' as const, id: 'org-1' },
-      billingPeriod: { start: '2026-07-01T00:00:00.000Z', end: '2026-08-01T00:00:00.000Z' },
+      billingPeriod: { start: '2026-07-01T00:00:00.000Z', end: '2099-01-01T00:00:00.000Z' },
       payerSubscription: null,
     }
     setEnvFlags({ isHosted: true })