Sync public snapshot from freebuff-private

Source: CodebuffAI/freebuff-private@77bccf5c423c70981b49738e0a07d174868741fd

Author: github-actions[bot]

cli/src/hooks/use-freebuff-session.ts

@@ -96,6 +96,9 @@ function nextDelayMs(next: FreebuffSessionResponse): number | null {
     case 'ip_capped':
     case 'model_unavailable':
     case 'premium_slot_taken':
+    case 'purchase_claim_released':
+    case 'purchase_in_use':
+    case 'purchase_capacity':
       return null
   }
 }

common/src/constants/freebuff-desktop-sessions.ts

@@ -69,3 +69,7 @@ export function occupiesFreebuffDesktopSlot(
 
 /** Idle time after which Desktop may reclaim a constrained session slot. */
 export const FREEBUFF_DESKTOP_IDLE_RELEASE_MS = 10 * 60 * 1000
+
+/** Versioned opt-in: instance ids become single-use execution claims. */
+export const FREEBUFF_PURCHASE_CONTINUITY_HEADER =
+  'x-freebuff-purchase-continuity'

common/src/types/freebuff-session.ts

@@ -953,6 +953,17 @@ export type FreebuffSessionAdmissionResponse = (
       /** The way out of this refusal, when there is one to sell. */
       upgrade?: FreebuffUpgradeHint
     }
+  | {
+      /** Retired single-use Desktop claim; persist a new id before retrying. */
+      status: 'purchase_claim_released'
+      accessTier?: FreebuffAccessTier
+    }
+  | {
+      status: 'purchase_in_use' | 'purchase_capacity'
+      accessTier?: FreebuffAccessTier
+      requestedModel: string
+      currentInstanceId: string
+    }
   | {
       /** Freebuff Desktop only: every slot-bound session is occupied. Free
        *  accounts get one slot-bound and three multi-tab sessions; subscribers
@@ -972,6 +983,10 @@ export type FreebuffSessionAdmissionResponse = (
       currentInstanceId: string
     }
 ) & {
+  /** Unexpired Desktop purchases, including occupied hours. Picker metadata;
+   * admission still checks ownership, liveness, and capacity atomically. */
+  desktopPurchases?: FreebuffDesktopPurchaseInfo[]
+  desktopRefunds?: FreebuffDesktopRefundInfo[]
   /** Multi-session Desktop responses only. Counts live, unexpired rows across
    * all Desktop processes for this user. */
   desktopSessionCounts?: FreebuffDesktopSessionCounts
@@ -987,8 +1002,31 @@ export type FreebuffSessionServerResponse =
        *  surfaces it as a 409 for fast in-flight feedback. */
       status: 'superseded'
       desktopSessionCounts?: FreebuffDesktopSessionCounts
+      desktopPurchases?: FreebuffDesktopPurchaseInfo[]
+      desktopRefunds?: FreebuffDesktopRefundInfo[]
     }
 
+/** Emitted only after the reversal ledger entry and purchase marker commit. */
+export interface FreebuffDesktopRefundInfo {
+  /** Durable execution claims belonging to this purchase; omitted by older APIs. */
+  claimInstanceIds?: string[]
+  purchaseId: string
+  model: string
+  amount: number
+  walletAmount: number
+  /** Refunded bonus retired in the same settlement; absent on older APIs. */
+  expiredBonusAmount?: number
+  refundedAt: string
+  /** Original debit's accounting instant; identifies the daily pool restored. */
+  poolDate: string
+}
+
+export interface FreebuffDesktopPurchaseInfo {
+  model: string
+  expiresAt: string
+  holderInstanceId?: string
+}
+
 /**
  * The session gate on `/api/v1/chat/completions`, as a wire contract.
  *