fix(billing): harden sandbox usage durability

Author: Bill Leoutsakos

apps/sim/lib/billing/cycle-close.test.ts

@@ -407,6 +407,17 @@ describe('closeElapsedBillingPeriod', () => {
     expect(dbChainMockFns.update).not.toHaveBeenCalled()
   })
 
+  it('defers while sandbox usage can still write the elapsed period', async () => {
+    queueOrgCloseReads()
+    queueTableRows(schemaMock.outboxEvent, [{ id: 'sandbox-usage-event' }])
+
+    const result = await closeElapsedBillingPeriod(subRow())
+
+    expect(result.status).toBe('skipped')
+    expect(mockEnqueueOutboxEvent).not.toHaveBeenCalled()
+    expect(dbChainMockFns.update).not.toHaveBeenCalled()
+  })
+
   it('books enterprise periods without collecting money', async () => {
     mockIsEnterprise.mockReturnValue(true)
     queueOrgCloseReads()

apps/sim/lib/billing/cycle-close.ts

@@ -19,6 +19,7 @@ import {
 } from '@/lib/billing/core/usage-log'
 import { computeWeeklyRefreshConsumed } from '@/lib/billing/credits/weekly-refresh'
 import { getPlanWeeklyRefreshDollars, isEnterprise, isFree } from '@/lib/billing/plan-helpers'
+import { hasOutstandingSandboxUsageForPeriod } from '@/lib/billing/sandbox-period-close'
 import { ENTITLED_SUBSCRIPTION_STATUSES, getPlanPricing } from '@/lib/billing/subscriptions/utils'
 import { toDecimal, toNumber } from '@/lib/billing/utils/decimal'
 import { OUTBOX_EVENT_TYPES } from '@/lib/billing/webhooks/outbox-handlers'
@@ -282,6 +283,29 @@ async function claimCloseMarker(
   return claimed.length > 0
 }
 
+async function guardCycleCloseAgainstSandboxWriters(
+  tx: DbOrTx,
+  subscriptionId: string,
+  periodStart: Date,
+  billingEntity: { type: 'user' | 'organization'; id: string }
+): Promise<'ready' | 'already-closed' | 'writers-pending'> {
+  const [current] = await tx
+    .select({ lastClosedPeriodStart: subscriptionTable.lastClosedPeriodStart })
+    .from(subscriptionTable)
+    .where(eq(subscriptionTable.id, subscriptionId))
+    .for('update')
+    .limit(1)
+  if (
+    current?.lastClosedPeriodStart &&
+    current.lastClosedPeriodStart.getTime() >= periodStart.getTime()
+  ) {
+    return 'already-closed'
+  }
+  return (await hasOutstandingSandboxUsageForPeriod(tx, billingEntity, periodStart))
+    ? 'writers-pending'
+    : 'ready'
+}
+
 /**
  * Close the most recently elapsed billing period for one subscription.
  *
@@ -385,8 +409,22 @@ export async function closeElapsedBillingPeriod(
   }
   if (closeFrom.getTime() >= periodStart.getTime()) {
     // Degenerate window (clock skew or a shortened period) — just advance.
-    const advanced = await db.transaction(async (tx) => claimCloseMarker(tx, sub.id, periodStart))
-    return { ...base, status: advanced ? 'closed' : 'already-closed' }
+    const claim = await db.transaction(async (tx) => {
+      await tx.execute(sql.raw(`SET LOCAL lock_timeout = '${BILLING_LOCK_TIMEOUT_MS}ms'`))
+      const guard = await guardCycleCloseAgainstSandboxWriters(
+        tx,
+        sub.id,
+        periodStart,
+        billingEntity
+      )
+      if (guard !== 'ready') return guard
+      return (await claimCloseMarker(tx, sub.id, periodStart)) ? 'closed' : 'already-closed'
+    })
+    return {
+      ...base,
+      status:
+        claim === 'closed' ? 'closed' : claim === 'already-closed' ? 'already-closed' : 'skipped',
+    }
   }
 
   const closedRange = { from: closeFrom, to: periodStart }
@@ -396,8 +434,22 @@ export async function closeElapsedBillingPeriod(
     // Reporting-anchor orgs derive every usage window live from the anchor;
     // there is nothing to bill or book here. Advance the marker so the sweep
     // stays quiet.
-    const advanced = await db.transaction(async (tx) => claimCloseMarker(tx, sub.id, periodStart))
-    return { ...base, status: advanced ? 'closed' : 'already-closed' }
+    const claim = await db.transaction(async (tx) => {
+      await tx.execute(sql.raw(`SET LOCAL lock_timeout = '${BILLING_LOCK_TIMEOUT_MS}ms'`))
+      const guard = await guardCycleCloseAgainstSandboxWriters(
+        tx,
+        sub.id,
+        periodStart,
+        billingEntity
+      )
+      if (guard !== 'ready') return guard
+      return (await claimCloseMarker(tx, sub.id, periodStart)) ? 'closed' : 'already-closed'
+    })
+    return {
+      ...base,
+      status:
+        claim === 'closed' ? 'closed' : claim === 'already-closed' ? 'already-closed' : 'skipped',
+    }
   }
 
   const [usageByUser, copilotByUser] = await Promise.all([
@@ -485,7 +537,7 @@ export async function closeElapsedBillingPeriod(
     async (
       tx
     ): Promise<{
-      status: 'closed' | 'already-closed' | 'membership-changed'
+      status: 'closed' | 'already-closed' | 'membership-changed' | 'writers-pending'
       billed: number
       creditsApplied: number
     }> => {
@@ -519,17 +571,18 @@ export async function closeElapsedBillingPeriod(
       // Re-check the marker under the locks: a concurrent closer that already
       // committed makes this a no-op (its billedOverage reset must not be
       // mistaken for unbilled overage).
-      const [current] = await tx
-        .select({ lastClosedPeriodStart: subscriptionTable.lastClosedPeriodStart })
-        .from(subscriptionTable)
-        .where(eq(subscriptionTable.id, sub.id))
-        .limit(1)
-      if (
-        current?.lastClosedPeriodStart &&
-        current.lastClosedPeriodStart.getTime() >= periodStart.getTime()
-      ) {
+      const sandboxWriterGuard = await guardCycleCloseAgainstSandboxWriters(
+        tx,
+        sub.id,
+        periodStart,
+        billingEntity
+      )
+      if (sandboxWriterGuard === 'already-closed') {
         return { status: 'already-closed', billed: 0, creditsApplied: 0 }
       }
+      if (sandboxWriterGuard === 'writers-pending') {
+        return { status: 'writers-pending', billed: 0, creditsApplied: 0 }
+      }
 
       // Re-read the roster under the locks, mirroring threshold billing: an
       // owner transfer moves `billedOverageThisPeriod` between rows, so a
@@ -667,6 +720,14 @@ export async function closeElapsedBillingPeriod(
     })
     return base
   }
+  if (closeResult.status === 'writers-pending') {
+    logger.info('Deferring cycle close for outstanding sandbox usage', {
+      subscriptionId: sub.id,
+      billingEntity,
+      periodEnd: periodStart.toISOString(),
+    })
+    return base
+  }
 
   logger.info('Closed billing period', {
     subscriptionId: sub.id,

apps/sim/lib/billing/sandbox-period-close.ts

@@ -0,0 +1,28 @@
+import { outboxEvent } from '@sim/db/schema'
+import { and, eq, inArray, sql } from 'drizzle-orm'
+import type { BillingEntity } from '@/lib/billing/core/usage-log'
+import type { DbOrTx } from '@/lib/db/types'
+
+export const SANDBOX_USAGE_OUTBOX_EVENT_TYPE = 'sandbox.usage.finalize'
+
+/** Whether cycle close must wait for sandbox usage that can still write this period. */
+export async function hasOutstandingSandboxUsageForPeriod(
+  tx: DbOrTx,
+  billingEntity: BillingEntity,
+  periodEnd: Date
+): Promise<boolean> {
+  const [row] = await tx
+    .select({ id: outboxEvent.id })
+    .from(outboxEvent)
+    .where(
+      and(
+        eq(outboxEvent.eventType, SANDBOX_USAGE_OUTBOX_EVENT_TYPE),
+        inArray(outboxEvent.status, ['pending', 'processing']),
+        sql`coalesce(${outboxEvent.payload}::jsonb -> 'billingPeriod' ->> 'end', ${outboxEvent.payload}::jsonb -> 'billingAttribution' -> 'billingPeriod' ->> 'end') = ${periodEnd.toISOString()}`,
+        sql`${outboxEvent.payload}::jsonb -> 'billingAttribution' -> 'billingEntity' ->> 'type' = ${billingEntity.type}`,
+        sql`${outboxEvent.payload}::jsonb -> 'billingAttribution' -> 'billingEntity' ->> 'id' = ${billingEntity.id}`
+      )
+    )
+    .limit(1)
+  return Boolean(row)
+}

apps/sim/lib/billing/sandbox-pricing.test.ts

@@ -3,7 +3,11 @@
  */
 
 import { describe, expect, it } from 'vitest'
-import { createSandboxPricingSnapshot, priceSandboxUsage } from '@/lib/billing/sandbox-pricing'
+import {
+  assertSandboxPricingSnapshot,
+  createSandboxPricingSnapshot,
+  priceSandboxUsage,
+} from '@/lib/billing/sandbox-pricing'
 
 const STARTED_AT = new Date('2026-08-27T12:00:00.000Z')
 const ONE_HOUR_LATER = new Date('2026-08-27T13:00:00.000Z')
@@ -48,4 +52,11 @@ describe('sandbox pricing', () => {
     expect(priced.durationMs).toBe(15_000)
     expect(priced.sandboxSeconds).toBe(15)
   })
+
+  it('rejects a zero multiplier for new usage while preserving historical V1 replay', () => {
+    expect(() => createSandboxPricingSnapshot('e2b', 0)).toThrow('finite positive')
+
+    const historical = createSandboxPricingSnapshot('e2b', 1)
+    expect(assertSandboxPricingSnapshot({ ...historical, multiplier: 0 }).multiplier).toBe(0)
+  })
 })

apps/sim/lib/billing/sandbox-pricing.ts

@@ -6,7 +6,7 @@ import {
 } from '@/lib/execution/remote-sandbox/function-resources'
 import type { SandboxProviderId } from '@/lib/execution/remote-sandbox/types'
 
-const PRICING_VERIFIED_AT = '2026-08-27' as const
+const PRICING_V1_VERIFIED_AT = '2026-08-27' as const
 const E2B_CPU_USD_PER_VCPU_SECOND = 0.000014
 const E2B_MEMORY_USD_PER_GIB_SECOND = 0.0000045
 const DAYTONA_CPU_USD_PER_VCPU_SECOND = 0.0504 / 3600
@@ -25,15 +25,17 @@ export interface SandboxUnitRates {
   diskUsdPerGiBSecond: number
 }
 
-export interface SandboxPricingSnapshot {
+export interface SandboxPricingSnapshotV1 {
   version: 1
   provider: SandboxProviderId
-  verifiedAt: typeof PRICING_VERIFIED_AT
+  verifiedAt: typeof PRICING_V1_VERIFIED_AT
   multiplier: number
   resources: SandboxResourceProfile
   rates: SandboxUnitRates
 }
 
+export type SandboxPricingSnapshot = SandboxPricingSnapshotV1
+
 export interface PricedSandboxUsage {
   durationMs: number
   sandboxSeconds: number
@@ -84,16 +86,22 @@ function assertFiniteNonNegative(value: number, field: string): void {
   }
 }
 
+function assertFinitePositive(value: number, field: string): void {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`Sandbox pricing ${field} must be a finite positive number`)
+  }
+}
+
 export function createSandboxPricingSnapshot(
   provider: SandboxProviderId,
   multiplier = getCostMultiplier()
 ): SandboxPricingSnapshot {
-  assertFiniteNonNegative(multiplier, 'multiplier')
+  assertFinitePositive(multiplier, 'multiplier')
   const pricing = PRICING_BY_PROVIDER[provider]
   return {
     version: 1,
     provider,
-    verifiedAt: PRICING_VERIFIED_AT,
+    verifiedAt: PRICING_V1_VERIFIED_AT,
     multiplier,
     resources: { ...pricing.resources },
     rates: { ...pricing.rates },
@@ -104,16 +112,20 @@ export function assertSandboxPricingSnapshot(value: unknown): SandboxPricingSnap
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
     throw new Error('Sandbox pricing snapshot must be an object')
   }
-  const snapshot = value as Partial<SandboxPricingSnapshot>
+  const snapshot = value as Partial<SandboxPricingSnapshotV1>
   if (snapshot.version !== 1 || (snapshot.provider !== 'e2b' && snapshot.provider !== 'daytona')) {
     throw new Error('Sandbox pricing snapshot version or provider is invalid')
   }
-  if (snapshot.verifiedAt !== PRICING_VERIFIED_AT) {
+  // V1 is immutable. A future pricing release must add a new version branch
+  // instead of changing this literal, because queued events carry frozen V1 rates.
+  if (snapshot.verifiedAt !== PRICING_V1_VERIFIED_AT) {
     throw new Error('Sandbox pricing snapshot verification date is invalid')
   }
   if (!snapshot.resources || !snapshot.rates) {
     throw new Error('Sandbox pricing snapshot resources and rates are required')
   }
+  // Historical V1 payloads allowed zero. Keep that parser contract immutable;
+  // new intents reject zero in createSandboxPricingSnapshot before provider work.
   assertFiniteNonNegative(snapshot.multiplier ?? Number.NaN, 'multiplier')
   assertFiniteNonNegative(snapshot.resources.vcpu, 'resources.vcpu')
   assertFiniteNonNegative(snapshot.resources.memoryGiB, 'resources.memoryGiB')