Sync public snapshot from freebuff-private

Source: CodebuffAI/freebuff-private@7341c0549f4d8062b312ea0660a49d53f96724ea

Author: github-actions[bot]

bun.lock

@@ -774,7 +774,8 @@ describe('GLM selection uses the applicable meter', () => {
           : DEFAULT_FREEBUFF_MODEL_ID,
       )
       if (balance >= 5)
-        expect(setup.captureCharFrame()).toContain('5 Freebucks')
+        // The price reads `5/hr`; the balance lives in the header line.
+        expect(setup.captureCharFrame()).toContain('5/hr')
     },
   )
 
@@ -982,7 +983,7 @@ test('a funded Luna row does not show its exhausted legacy quota in the section
   useFreebuffModelStore.getState().setSelectedModel(id)
   const setup = await renderSelector()
   await setup.renderOnce()
-  expect(setup.captureCharFrame()).toContain('20 Freebucks')
+  expect(setup.captureCharFrame()).toContain('20/hr')
   expect(setup.captureCharFrame()).not.toContain('1 of 1 used')
   expect(getSelectedFreebuffModel()).toBe(id)
 })

cli/src/components/__tests__/freebuff-model-selector.test.tsx

@@ -0,0 +1,66 @@
+import { TextAttributes } from '@opentui/core'
+import { useKeyboard } from '@opentui/react'
+import { useEffect, useState } from 'react'
+
+import { FREEBUCKS_INTRO } from '../utils/freebucks'
+import { hasSeenFreebucksIntro, markFreebucksIntroSeen } from '../utils/settings'
+import { useTheme } from '../hooks/use-theme'
+
+/**
+ * The one-time introduction to Freebucks, above the picker on the landing.
+ *
+ * Shown the FIRST launch on which the account is METERED — the caller passes
+ * `metered`, read off the session's `freebucks` block like every other
+ * surface — and never again. The seen mark is written the moment this
+ * RENDERS, not on dismissal: a launch that ends before the user presses
+ * anything must not be shown it twice. It is a card and not a modal because
+ * the CLI landing has no modal layer and the picker below it keeps working;
+ * any key the picker handles also retires the card for this launch.
+ */
+export function FreebucksIntroCard({
+  metered,
+  width,
+}: {
+  metered: boolean
+  width: number
+}) {
+  const theme = useTheme()
+  const [show, setShow] = useState<boolean>(() => metered && !hasSeenFreebucksIntro())
+  useEffect(() => {
+    if (!metered) return
+    if (hasSeenFreebucksIntro()) return
+    markFreebucksIntroSeen()
+    setShow(true)
+  }, [metered])
+  // Any key retires it for this launch; the picker still receives the key.
+  useKeyboard(() => {
+    if (show) setShow(false)
+  })
+  if (!show) return null
+  return (
+    <box
+      style={{
+        flexDirection: 'column',
+        width: Math.max(24, width),
+        border: true,
+        borderStyle: 'rounded',
+        borderColor: theme.secondary,
+        paddingLeft: 1,
+        paddingRight: 1,
+        marginBottom: 1,
+        flexShrink: 0,
+      }}
+    >
+      <text style={{ fg: theme.foreground }} attributes={TextAttributes.BOLD}>
+        ★ {FREEBUCKS_INTRO.title}
+      </text>
+      <text style={{ fg: theme.muted, wrapMode: 'word' }}>{FREEBUCKS_INTRO.lead}</text>
+      {FREEBUCKS_INTRO.points.map((point) => (
+        <text key={point} style={{ fg: theme.foreground, wrapMode: 'word' }}>
+          <span fg={theme.secondary}>•</span> {point}
+        </text>
+      ))}
+      <text style={{ fg: theme.muted }}>{FREEBUCKS_INTRO.dismiss}</text>
+    </box>
+  )
+}

cli/src/components/freebucks-intro-card.tsx

@@ -2,9 +2,16 @@ import { TextAttributes } from '@opentui/core'
 import { useKeyboard, useRenderer } from '@opentui/react'
 import React, { useCallback, useEffect, useRef, useState } from 'react'
 
+import {
+  FREEBUCKS_LABEL,
+  formatFreebucks,
+  freebucksOf,
+  freebucksPriceLabel,
+} from '../utils/freebucks'
 import { Button } from './button'
 import { ChoiceAdBanner, AD_CARD_HEIGHT } from './ad-banner'
 import { visibleWaitingRoomPlacementIds } from '@codebuff/common/ads/waiting-room-placements'
+import { FreebucksIntroCard } from './freebucks-intro-card'
 import { FreebuffModelSelector } from './freebuff-model-selector'
 import { ShimmerText } from './shimmer-text'
 import {
@@ -674,6 +681,16 @@ export const FreebuffLandingScreen: React.FC<FreebuffLandingScreenProps> = ({
                 gap: 0,
               }}
             >
+              {/* The one-time Freebucks introduction, only where it fits:
+                  on a short terminal it would push the picker off the
+                  bottom, and an unseen card is shown on the next launch
+                  instead (it is marked seen only when it renders). */}
+              {terminalHeight >= 30 && (
+                <FreebucksIntroCard
+                  metered={freebucksOf(session) !== undefined}
+                  width={Math.min(contentMaxWidth, 72)}
+                />
+              )}
               <LandingHeadingRow
                 streakLine={streakOnHeadingRow ? streakLine : null}
                 marginBottom={textMarginBottom}
@@ -795,26 +812,59 @@ export const FreebuffLandingScreen: React.FC<FreebuffLandingScreenProps> = ({
           {session?.status === 'rate_limited' && (
             <>
               <text style={{ fg: theme.secondary, marginBottom: 1 }}>
-                ⚠ Session limit reached
-              </text>
-              <text style={{ fg: theme.muted, wrapMode: 'word' }}>
-                You've used{' '}
-                <span fg={theme.foreground}>
-                  {formatSessionUnits(session.recentCount)} of {session.limit}
-                </span>{' '}
-                sessions{' '}
-                {session.period === 'pacific_month'
-                  ? 'this month'
-                  : session.period === 'pacific_week'
-                    ? 'this week'
-                    : 'today'}
-                . Try
-                again in{' '}
-                <span fg={theme.foreground}>
-                  {formatRetryAfter(session.retryAfterMs)}
-                </span>
-                . Press Ctrl+C to exit.
+                {session.freebucksShortfall
+                  ? `⚠ Not enough ${FREEBUCKS_LABEL}`
+                  : '⚠ Session limit reached'}
               </text>
+              {/* THE METER'S REFUSAL, when the server sent one.
+                  
+                  `freebucksShortfall` is what distinguishes "you are out of
+                  Freebucks" from "you have used your sessions", and the two
+                  want completely different sentences: the counts on this
+                  response are shaped like a session pool for older clients,
+                  so rendering them here would tell a metered user they had
+                  spent N of M sessions — a meter they are no longer on.
+
+                  The monthly wall arrives in the SAME shape with no shortfall
+                  attached and `period: 'pacific_month'`, which is why the
+                  period copy below still has to be right: telling somebody to
+                  come back at midnight for an allowance that returns on the
+                  1st sends them back to the same wall in the morning. */}
+              {session.freebucksShortfall ? (
+                <text style={{ fg: theme.muted, wrapMode: 'word' }}>
+                  This model costs{' '}
+                  <span fg={theme.foreground}>
+                    {freebucksPriceLabel(session.freebucksShortfall.price)}
+                  </span>
+                  , and you have{' '}
+                  <span fg={theme.foreground}>
+                    {formatFreebucks(session.freebucksShortfall.balance)}
+                  </span>{' '}
+                  left. More in{' '}
+                  <span fg={theme.foreground}>
+                    {formatRetryAfter(session.retryAfterMs)}
+                  </span>
+                  , or pick a cheaper model. Press Ctrl+C to exit.
+                </text>
+              ) : (
+                <text style={{ fg: theme.muted, wrapMode: 'word' }}>
+                  You've used{' '}
+                  <span fg={theme.foreground}>
+                    {formatSessionUnits(session.recentCount)} of {session.limit}
+                  </span>{' '}
+                  {session.period === 'pacific_month' ? 'this month' : 'sessions'}{' '}
+                  {session.period === 'pacific_month'
+                    ? ''
+                    : session.period === 'pacific_week'
+                      ? 'this week'
+                      : 'today'}
+                  . Try again in{' '}
+                  <span fg={theme.foreground}>
+                    {formatRetryAfter(session.retryAfterMs)}
+                  </span>
+                  . Press Ctrl+C to exit.
+                </text>
+              )}
               {/* The paywall half (2026-09-01): the server's structured hint
                   when it sent one, the plans page otherwise — a quota wall is
                   never a dead end. */}