CodebuffAI
diff --git a/‎docs/freebuff-freebucks.md‎
Lines changed: 81 additions & 0 deletions b/‎docs/freebuff-freebucks.md‎
Lines changed: 81 additions & 0 deletions
diff --git a/‎freebuff/web/src/components/earn/BountyBoard.tsx‎
Lines changed: 47 additions & 2 deletions b/‎freebuff/web/src/components/earn/BountyBoard.tsx‎
Lines changed: 47 additions & 2 deletions
diff --git a/‎freebuff/web/src/components/earn/FreebucksConvertCard.tsx‎
Lines changed: 15 additions & 0 deletions b/‎freebuff/web/src/components/earn/FreebucksConvertCard.tsx‎
Lines changed: 15 additions & 0 deletions
diff --git a/‎freebuff/web/src/server/bounties/balance.ts‎
Lines changed: 50 additions & 2 deletions b/‎freebuff/web/src/server/bounties/balance.ts‎
Lines changed: 50 additions & 2 deletions
@@ -263,6 +263,87 @@ multi-session admissions free). Keyed on `active_instance_id`; the reclaim
 retry mints a new one, so a session that loses the pre-read race can charge
 twice — rare, and closing it needs `admitOrTakeOver` to return the admit id.
 
+## A metered session must NOT also debit a reward grant (2026-09-05)
+
+`consumeRewardGrantForAdmission` runs after every fresh admission and, until
+this date, did so without looking at which pool granted it. On the meter that
+was a second charge for one session, in a second currency: GLM 5.3 Flash costs
+**5 Freebucks**, and the bounty unit it also took is worth **15**
+(`FREEBUCKS_PER_EARNED_SESSION`). The user paid 20 for a 5-Freebuck session.
+
+The unit was **destroyed, not converted**. Only
+`convertEarnedSessionsToFreebucks` writes a `grant_convert` credit, and the
+admission path does not call it — so the earnings left
+`freebuff_manual_session_grant` and arrived nowhere. It was invisible in the
+ledger by construction, because the ledger only ever sees the session debit.
+
+Then it was actively misreported. `getBountyBalance` derives `spent` from
+`consumed_units`, which a GLM session decrements exactly as a cash-out does,
+and the Earn page rendered that on the meter as **"Cashed out — already in
+your wallet"**. A user wrote in saying it claimed they had cashed out when
+they never had, which is how any of this was found. The tile now reads the
+LEDGER (`cashedOutFreebucks`), and sessions genuinely spent on GLM are named
+in a line under the tiles instead of being folded into the wallet figure.
+
+**Rule: the grant pools and the meter are alternatives, never both.** A
+metered account does not consult the free session pools for its ENTITLEMENT,
+and it must not consult them for a DEBIT either. `grantedPool ===
+FREEBUCKS_ADMIT_POOL` is the guard, with a regression test in
+`public-api.test.ts` that asserts the meter's charge still happens and the
+grant debit does not.
+
+Scope, measured: 9 sessions, 6 accounts, all on 2026-09-04; repaid at 15 each
+by `scripts/freebuff-freebucks-double-charge-remediation.ts` (idempotent, and
+it re-verifies each event against the admit row before paying). It could only
+ever be six because `consumed_units` carries no timestamp — the attribution
+comes from correlating the `[FreeSession] session debited against a reward
+grant` log lines against the pool on the admit row at that instant, and Axiom
+retention is what bounds how far back that can be done. **That is the reason
+the cash-out route now logs its previews too**: for its first two days the
+only line it could emit was the success line on POST, and there were zero of
+those — a reading that means either "nobody pressed the button" or "every
+press failed", with no way at all to tell which.
+
+## Earned sessions CLAIM THEMSELVES; the button is a shortcut (2026-09-05)
+
+Cashing out shipped as a control on the Bounties page. Measured across the
+first two days of its life it was pressed **zero times** — while **107 metered
+accounts held 199 earned units worth 2,985 Freebucks**, and six of them were
+shown *"You're out of Freebucks — back in 3h 58m"* beside an $8/mo upgrade in
+a single 24 hours, holding money they had already worked for. The endpoint was
+fine the whole time (probed in prod: 200, one account previewing 165). A
+control nobody finds is not a way to get paid, and upselling somebody their
+own unclaimed earnings is the worst version of not finding it.
+
+So the claim now fires **where it changes the outcome**, in two places, both
+gated on the account being unable to afford any row it is offered:
+
+- **The admission gate**, immediately before refusing for balance. Claim, then
+  re-read, then re-test the price.
+- **The display block**, which is what draws the picker's wall. A poll never
+  reaches the admission gate, so without this the panel keeps rendering the
+  countdown and the upsell to someone who is one claim away from a session.
+
+**Not on the happy path.** Both sites check the balance first — free, already
+in hand — so the extra grant read is paid only by accounts that are stuck. An
+account that can afford a row is never touched, which is a cost argument and
+also a consent one: moving somebody's earnings for them at a moment they had
+no reason to want it is not a favour.
+
+**GRANTS ONLY. Referrals still need the button.** A grant is a stock consumed
+transactionally, so claiming one spends it everywhere at once. A referral is
+not: one cashed out here still feeds the daily GLM entitlement on the CLI
+(`getGlmReferralEntitlement` reads the same count and knows nothing about the
+ledger). That bounded overpayment is fine when a user opts into it by pressing
+a button, and not something to widen silently for everybody from an admission
+gate.
+
+`claimEarnedFreebucks` drives `convertEarnedSessionsToFreebucks` off the
+session deps rather than reimplementing it — one owner for the consume-then-
+credit order and the once-ever keying, because two of those would be two
+chances to consume without crediting. It is TOTAL: every failure returns 0 and
+the caller refuses on the balance it already read.
+
 ## The wire block
 
 `FreebuffFreebucksInfo` on every authenticated session response inside the
 
@@ -1,6 +1,10 @@
 'use client'
 
-import { FREEBUCKS_PER_EARNED_SESSION } from '@codebuff/common/constants/freebuff-freebucks'
+import {
+  FREEBUCKS_LABEL,
+  FREEBUCKS_PER_EARNED_SESSION,
+} from '@codebuff/common/constants/freebuff-freebucks'
+import { FREEBUFF_REWARD_MODEL_DISPLAY_NAME } from '@codebuff/common/constants/freebuff-models'
 import { useCallback, useEffect, useMemo, useState } from 'react'
 
 import { Button } from '@/vly/components/ui/button'
@@ -17,6 +21,9 @@ interface BountyBalance {
   earned: number
   spent: number
   remaining: number
+  /** Freebucks a cash-out actually credited, read off the ledger. Never
+   *  derived from `spent` — see the field docs on the server's BountyBalance. */
+  cashedOutFreebucks: number
 }
 
 /** Sessions are fractional — ending one early charges only tenths — so a whole
@@ -126,6 +133,21 @@ export function BountyBoard() {
   }
   const openTask = tasks?.find((task) => task.id === openTaskId) ?? null
 
+  /** Reward sessions that went on GLM rather than into the wallet: everything
+   *  consumed, minus what the ledger says a cash-out actually paid for. Floored
+   *  at zero so a rounding difference between the two sources — units to a
+   *  tenth, Freebucks to a whole — can never render a negative sentence. */
+  const spentOnSessions = balance
+    ? Math.max(
+        0,
+        Math.round(
+          (balance.spent -
+            balance.cashedOutFreebucks / FREEBUCKS_PER_EARNED_SESSION) *
+            10,
+        ) / 10,
+      )
+    : 0
+
   return (
     <section className="flex flex-col gap-5">
       {/* The pitch used to live here, in a dithered header with an eyebrow and
@@ -162,11 +184,19 @@ export function BountyBoard() {
             }
             detail="From approved bounties, all time"
           />
+          {/* On the meter this reads the LEDGER, not `spent`. They are
+              different things and the page used to print one as the other:
+              `spent` counts every reward session ever consumed, so an account
+              that had simply used its bounties on GLM was told they were
+              "already in your wallet" — money nobody had credited. A user
+              reported exactly that on 2026-09-05. The sessions they spent are
+              named by the line under the tiles instead, which is what actually
+              happened to them. */}
           <BalanceStat
             label={metered ? 'Cashed out' : 'Used'}
             value={
               metered
-                ? formatSessions(balance.spent * FREEBUCKS_PER_EARNED_SESSION)
+                ? formatSessions(balance.cashedOutFreebucks)
                 : formatSessions(balance.spent)
             }
             detail={metered ? 'Already in your wallet' : 'Spent on reward sessions'}
@@ -188,6 +218,21 @@ export function BountyBoard() {
         </div>
       )}
 
+      {/* The three tiles no longer add up on the meter, and that is the honest
+          state rather than a rounding slip: a reward session spent on GLM is
+          earned, gone, and never became Freebucks. Saying so is the whole
+          point — silently folding it into "cashed out" is what made a user
+          believe we had taken their wallet. */}
+      {metered && balance && spentOnSessions > 0 && (
+        <p className="text-[13px] leading-relaxed text-muted-foreground">
+          {formatSessions(spentOnSessions)} reward{' '}
+          {spentOnSessions === 1 ? 'session' : 'sessions'} were spent on{' '}
+          {FREEBUFF_REWARD_MODEL_DISPLAY_NAME} before your account moved to{' '}
+          {FREEBUCKS_LABEL}, so they were used rather than cashed out. Anything
+          still showing under &ldquo;to cash out&rdquo; is yours to convert.
+        </p>
+      )}
+
       {/* Earned sessions are worth what they convert to on the meter. The
           tiles' outstanding figure is handed over as a CROSS-CHECK: it and the
           card read different queries, and a user was left staring at "30 to
 
@@ -161,6 +161,21 @@ export function FreebucksConvertCard({
                   `Your earned ${FREEBUCKS_LABEL} are already in your wallet. If the total above still shows ${formatFreebucks(pendingHint)}, reload — and tell us if it stays.`
                 : 'Nothing left to cash out. New referrals and bounties show up here.'}
           </p>
+          {/* The press is a SHORTCUT now, not the only way through. Bounty
+              sessions claim themselves the moment an empty balance would
+              otherwise stop you — which is the fix for this control having
+              been used zero times in its first two days while 107 accounts
+              sat on unclaimed earnings. Saying so matters as much as doing
+              it: a user who does not know their earnings are safe behaves
+              exactly like a user whose earnings are gone, and one of them
+              wrote in to tell us so. Referrals are the exception and say
+              nothing about being automatic, because they are not. */}
+          {preview.total > 0 && preview.grantUnits > 0 && (
+            <p className="mt-1 text-[13px] leading-5 text-muted-foreground">
+              Your bounty {FREEBUCKS_LABEL} are added automatically when you run
+              out — this button just does it now.
+            </p>
+          )}
           {credited !== null && credited > 0 && (
             <p className="mt-1 text-[13px] font-medium text-brand dark:text-brand">
               +{formatFreebucks(credited)} {FREEBUCKS_LABEL} added to your
 
@@ -1,5 +1,7 @@
 import { and, eq, sql } from 'drizzle-orm'
 
+import { FREEBUCKS_GRANT_CONVERT_REASON } from '@codebuff/common/constants/freebuff-freebucks'
+
 import { logger } from '@/util/logger'
 
 import db from '@codebuff/internal/db'
@@ -20,13 +22,33 @@ import * as schema from '@codebuff/internal/db/schema'
 export interface BountyBalance {
   /** Sessions every approved bounty ever paid, expired ones included. */
   earned: number
-  /** Of those, sessions already spent on GLM. */
+  /** Of those, sessions no longer available — spent on GLM or cashed out. */
   spent: number
   /** Spendable right now: live grants, minus what they have funded. */
   remaining: number
+  /**
+   * FREEBUCKS actually credited by a cash-out, read off the ledger.
+   *
+   * This is NOT `spent * FREEBUCKS_PER_EARNED_SESSION`, and conflating the two
+   * is the bug this field exists to close. `spent` is `consumed_units`, which
+   * a GLM session decrements just as a cash-out does — so on the meter the
+   * page rendered every session a user had ever spent as "Cashed out —
+   * already in your wallet", for money that was never credited to anyone.
+   * Reported by a user on 2026-09-05 as "it says cashed out but I didn't even
+   * do it", which is exactly right: they never pressed anything.
+   *
+   * The only thing that means a cash-out happened is a `grant_convert` credit
+   * in the Freebucks ledger, so that is what this counts.
+   */
+  cashedOutFreebucks: number
 }
 
-const ZERO: BountyBalance = { earned: 0, spent: 0, remaining: 0 }
+const ZERO: BountyBalance = {
+  earned: 0,
+  spent: 0,
+  remaining: 0,
+  cashedOutFreebucks: 0,
+}
 
 /** Sessions round to a tenth everywhere else in this system; an early-ended
  *  session charges only part of one, and a balance that renders 0.30000000004
@@ -65,10 +87,36 @@ export async function getBountyBalance(userId: string): Promise<BountyBalance> {
         ),
       )
 
+    // Credits only (`amount < 0` is a credit — see the ledger's sign
+    // convention). Unscoped by grant: a cash-out consumes every grant the
+    // account holds and writes one credit for the lot, so there is nothing on
+    // the credit row to attribute back to a bounty, and inventing a split here
+    // would report a number the ledger cannot back.
+    const [credited] = await db
+      .select({
+        freebucks: sql<
+          string | null
+        >`sum(-${schema.freebuffFreebucksLedger.amount})`,
+      })
+      .from(schema.freebuffFreebucksLedger)
+      .where(
+        and(
+          eq(schema.freebuffFreebucksLedger.user_id, userId),
+          eq(
+            schema.freebuffFreebucksLedger.reason,
+            FREEBUCKS_GRANT_CONVERT_REASON,
+          ),
+        ),
+      )
+
     return {
       earned: round(Number(row?.earned ?? 0)),
       spent: round(Number(row?.spent ?? 0)),
       remaining: Math.max(0, round(Number(row?.remaining ?? 0))),
+      cashedOutFreebucks: Math.max(
+        0,
+        Math.round(Number(credited?.freebucks ?? 0)),
+      ),
     }
   } catch (error) {
     // The board itself must still render. A missing balance costs three tiles;