Show per-model "N ahead" in freebuff selector

Server returns a queueDepthByModel snapshot with every queued session
response via a single GROUP BY read, so each row of the model selector
can show a live "3 ahead" / "No wait" hint instead of the static
tagline.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: jahooma

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

@@ -1,12 +1,13 @@
 import { TextAttributes } from '@opentui/core'
 import { useKeyboard } from '@opentui/react'
-import React, { useCallback, useState } from 'react'
+import React, { useCallback, useMemo, useState } from 'react'
 
 import { Button } from './button'
 import { FREEBUFF_MODELS } from '@codebuff/common/constants/freebuff-models'
 
 import { switchFreebuffModel } from '../hooks/use-freebuff-session'
 import { useFreebuffModelStore } from '../state/freebuff-model-store'
+import { useFreebuffSessionStore } from '../state/freebuff-session-store'
 import { useTheme } from '../hooks/use-theme'
 
 import type { KeyEvent } from '@opentui/core'
@@ -15,13 +16,33 @@ import type { KeyEvent } from '@opentui/core'
  * Lets the user pick which model's queue they're in. Tapping (or pressing the
  * row's number key) on a different model triggers a re-POST: the server moves
  * them to the back of the new model's queue.
+ *
+ * Each row shows a live "N ahead" count sourced from the server's
+ * `queueDepthByModel` snapshot so the choice is informed (e.g. "3 ahead" vs
+ * "12 ahead") rather than a blind preference toggle.
  */
 export const FreebuffModelSelector: React.FC = () => {
   const theme = useTheme()
   const selectedModel = useFreebuffModelStore((s) => s.selectedModel)
+  const session = useFreebuffSessionStore((s) => s.session)
   const [pending, setPending] = useState<string | null>(null)
   const [hoveredId, setHoveredId] = useState<string | null>(null)
 
+  // For the user's current queue, "ahead" is `position - 1` (themselves don't
+  // count). For every other queue, switching would land them at the back, so
+  // it's that queue's full depth. Null before the first queued snapshot so
+  // the UI doesn't flash misleading zeros.
+  const aheadByModel = useMemo<Record<string, number> | null>(() => {
+    if (session?.status !== 'queued') return null
+    const depths = session.queueDepthByModel ?? {}
+    const out: Record<string, number> = {}
+    for (const { id } of FREEBUFF_MODELS) {
+      out[id] =
+        id === session.model ? Math.max(0, session.position - 1) : depths[id] ?? 0
+    }
+    return out
+  }, [session])
+
   const pick = useCallback(
     (modelId: string) => {
       if (pending) return
@@ -71,6 +92,13 @@ export const FreebuffModelSelector: React.FC = () => {
         const indicatorColor = isSelected ? theme.primary : theme.muted
         const labelColor = isSelected ? theme.foreground : theme.muted
         const interactable = !pending && !isSelected
+        const ahead = aheadByModel?.[model.id]
+        const hint =
+          ahead === undefined
+            ? model.tagline
+            : ahead === 0
+              ? 'No wait'
+              : `${ahead} ahead`
         return (
           <Button
             key={model.id}
@@ -88,7 +116,7 @@ export const FreebuffModelSelector: React.FC = () => {
               >
                 {model.displayName}
               </span>
-              <span fg={theme.muted}>  {model.tagline}</span>
+              <span fg={theme.muted}>  {hint}</span>
               {isPending && <span fg={theme.muted}>  switching…</span>}
               {isHovered && interactable && !isPending && (
                 <span fg={theme.muted}>  ↵</span>

common/src/types/freebuff-session.ts

@@ -26,6 +26,11 @@ export type FreebuffSessionServerResponse =
       /** 1-indexed position in the queue for `model`. */
       position: number
       queueDepth: number
+      /** Current depth of every model's queue, so the CLI can show a live
+       *  "N ahead" hint on each row of the model selector. Models with no
+       *  queued rows at snapshot time may be absent; the CLI should treat a
+       *  missing entry as 0. */
+      queueDepthByModel: Record<string, number>
       estimatedWaitMs: number
       queuedAt: string
     }

docs/freebuff-waiting-room.md

@@ -183,6 +183,10 @@ Response shapes:
   "model": "z-ai/glm-5.1",
   "position": 17,          // 1-indexed within this model's queue
   "queueDepth": 43,        // size of this model's queue
+  "queueDepthByModel": {   // snapshot of every model's queue — powers the
+    "z-ai/glm-5.1": 43,    //  "N ahead" hint in the selector. Missing
+    "minimax/minimax-m2.7": 4  //  entries should be treated as 0.
+  },
   "estimatedWaitMs": 384000,
   "queuedAt": "2026-04-17T12:00:00Z"
 }

web/src/app/api/v1/freebuff/session/__tests__/session.test.ts

@@ -39,7 +39,14 @@ function makeSessionDeps(overrides: Partial<SessionDeps> = {}): SessionDeps & {
     graceMs: 30 * 60 * 1000,
     now: () => now,
     getSessionRow: async (userId) => rows.get(userId) ?? null,
-    queueDepth: async () => [...rows.values()].filter((r) => r.status === 'queued').length,
+    queueDepthsByModel: async () => {
+      const out: Record<string, number> = {}
+      for (const r of rows.values()) {
+        if (r.status !== 'queued') continue
+        out[r.model] = (out[r.model] ?? 0) + 1
+      }
+      return out
+    },
     queuePositionFor: async () => 1,
     endSession: async (userId) => {
       rows.delete(userId)

web/src/server/free-session/__tests__/public-api.test.ts

@@ -43,12 +43,13 @@ function makeDeps(overrides: Partial<SessionDeps> = {}): SessionDeps & {
     endSession: async (userId) => {
       rows.delete(userId)
     },
-    queueDepth: async ({ model }) => {
-      let n = 0
+    queueDepthsByModel: async () => {
+      const out: Record<string, number> = {}
       for (const r of rows.values()) {
-        if (r.status === 'queued' && r.model === model) n++
+        if (r.status !== 'queued') continue
+        out[r.model] = (out[r.model] ?? 0) + 1
       }
-      return n
+      return out
     },
     queuePositionFor: async ({ userId, model, queuedAt }) => {
       let pos = 0
@@ -142,6 +143,22 @@ describe('requestSession', () => {
     expect(state.instanceId).toBe('inst-1')
   })
 
+  test('queued response includes a per-model depth snapshot for the selector', async () => {
+    // Seed 2 users in glm + 1 in minimax so the returned map captures both.
+    await requestSession({ userId: 'u1', model: DEFAULT_MODEL, deps })
+    deps._tick(new Date(deps._now().getTime() + 1000))
+    await requestSession({ userId: 'u2', model: DEFAULT_MODEL, deps })
+    deps._tick(new Date(deps._now().getTime() + 1000))
+    await requestSession({ userId: 'u3', model: 'minimax/minimax-m2.7', deps })
+
+    const state = await getSessionState({ userId: 'u1', deps })
+    if (state.status !== 'queued') throw new Error('unreachable')
+    expect(state.queueDepthByModel).toEqual({
+      [DEFAULT_MODEL]: 2,
+      'minimax/minimax-m2.7': 1,
+    })
+  })
+
   test('second call from same user rotates instance id, keeps queue position', async () => {
     await requestSession({ userId: 'u1', model: DEFAULT_MODEL, deps })
     const second = await requestSession({ userId: 'u1', model: DEFAULT_MODEL, deps })

web/src/server/free-session/__tests__/session-view.test.ts

@@ -44,13 +44,13 @@ describe('toSessionStateResponse', () => {
   const now = new Date('2026-04-17T12:00:00Z')
   const baseArgs = {
     graceMs: GRACE_MS,
+    queueDepthByModel: {},
   }
 
   test('returns null when row is null', () => {
     const view = toSessionStateResponse({
       row: null,
       position: 0,
-      queueDepth: 0,
       ...baseArgs,
       now,
     })
@@ -61,8 +61,8 @@ describe('toSessionStateResponse', () => {
     const view = toSessionStateResponse({
       row: row({ status: 'queued' }),
       position: 3,
-      queueDepth: 10,
       ...baseArgs,
+      queueDepthByModel: { [TEST_MODEL]: 10, 'minimax/minimax-m2.7': 4 },
       now,
     })
     expect(view).toEqual({
@@ -71,6 +71,7 @@ describe('toSessionStateResponse', () => {
       model: TEST_MODEL,
       position: 3,
       queueDepth: 10,
+      queueDepthByModel: { [TEST_MODEL]: 10, 'minimax/minimax-m2.7': 4 },
       estimatedWaitMs: 2 * WAIT_PER_SPOT_MS,
       queuedAt: now.toISOString(),
     })
@@ -82,7 +83,6 @@ describe('toSessionStateResponse', () => {
     const view = toSessionStateResponse({
       row: row({ status: 'active', admitted_at: admittedAt, expires_at: expiresAt }),
       position: 0,
-      queueDepth: 0,
       ...baseArgs,
       now,
     })
@@ -102,7 +102,6 @@ describe('toSessionStateResponse', () => {
     const view = toSessionStateResponse({
       row: row({ status: 'active', admitted_at: admittedAt, expires_at: expiresAt }),
       position: 0,
-      queueDepth: 0,
       ...baseArgs,
       now,
     })
@@ -124,7 +123,6 @@ describe('toSessionStateResponse', () => {
         expires_at: new Date(now.getTime() - GRACE_MS - 1),
       }),
       position: 0,
-      queueDepth: 0,
       ...baseArgs,
       now,
     })

web/src/server/free-session/public-api.ts

@@ -13,7 +13,7 @@ import {
   FreeSessionModelLockedError,
   getSessionRow,
   joinOrTakeOver,
-  queueDepth,
+  queueDepthsByModel,
   queuePositionFor,
 } from './store'
 import { toSessionStateResponse } from './session-view'
@@ -29,7 +29,7 @@ export interface SessionDeps {
     now: Date
   }) => Promise<InternalSessionRow>
   endSession: (userId: string) => Promise<void>
-  queueDepth: (params: { model: string }) => Promise<number>
+  queueDepthsByModel: () => Promise<Record<string, number>>
   queuePositionFor: (params: {
     userId: string
     model: string
@@ -47,7 +47,7 @@ const defaultDeps: SessionDeps = {
   getSessionRow,
   joinOrTakeOver,
   endSession,
-  queueDepth,
+  queueDepthsByModel,
   queuePositionFor,
   isWaitingRoomEnabled,
   get graceMs() {
@@ -65,21 +65,21 @@ async function viewForRow(
   deps: SessionDeps,
   row: InternalSessionRow,
 ): Promise<SessionStateResponse | null> {
-  const [position, depth] =
+  const [position, depthsByModel] =
     row.status === 'queued'
       ? await Promise.all([
           deps.queuePositionFor({
             userId,
             model: row.model,
             queuedAt: row.queued_at,
           }),
-          deps.queueDepth({ model: row.model }),
+          deps.queueDepthsByModel(),
         ])
-      : [0, 0]
+      : [0, {}]
   return toSessionStateResponse({
     row,
     position,
-    queueDepth: depth,
+    queueDepthByModel: depthsByModel,
     graceMs: deps.graceMs,
     now: nowOf(deps),
   })

web/src/server/free-session/session-view.ts

@@ -12,11 +12,13 @@ import type { InternalSessionRow, SessionStateResponse } from './types'
 export function toSessionStateResponse(params: {
   row: InternalSessionRow | null
   position: number
-  queueDepth: number
+  /** Snapshot of every model's queue depth at response time. Only consumed
+   *  by the `queued` variant — active/ended don't need the selector. */
+  queueDepthByModel: Record<string, number>
   graceMs: number
   now: Date
 }): SessionStateResponse | null {
-  const { row, position, queueDepth, graceMs, now } = params
+  const { row, position, queueDepthByModel, graceMs, now } = params
   if (!row) return null
 
   if (row.status === 'active' && row.expires_at) {
@@ -51,7 +53,8 @@ export function toSessionStateResponse(params: {
       instanceId: row.active_instance_id,
       model: row.model,
       position,
-      queueDepth,
+      queueDepth: queueDepthByModel[row.model] ?? 0,
+      queueDepthByModel,
       estimatedWaitMs: estimateWaitMs({ position }),
       queuedAt: row.queued_at.toISOString(),
     }

web/src/server/free-session/store.ts

@@ -158,6 +158,24 @@ export async function queueDepth(params: { model: string }): Promise<number> {
   return Number(rows[0]?.n ?? 0)
 }
 
+/**
+ * Single-query read of queued-row counts bucketed by model. Powers the
+ * per-model "N ahead" hint in the waiting-room model selector — one round-trip
+ * covers every model's queue depth, so the UI stays cheap to refresh.
+ * Models with no queued rows are absent from the map; callers should default
+ * missing keys to 0.
+ */
+export async function queueDepthsByModel(): Promise<Record<string, number>> {
+  const rows = await db
+    .select({ model: schema.freeSession.model, n: count() })
+    .from(schema.freeSession)
+    .where(eq(schema.freeSession.status, 'queued'))
+    .groupBy(schema.freeSession.model)
+  const out: Record<string, number> = {}
+  for (const row of rows) out[row.model] = Number(row.n)
+  return out
+}
+
 export async function activeCount(): Promise<number> {
   const rows = await db
     .select({ n: count() })