More cleanup

Author: jahooma

cli/src/components/freebuff-session-countdown.tsx

@@ -1,15 +1,12 @@
 import { TextAttributes } from '@opentui/core'
-import { useKeyboard } from '@opentui/react'
-import React, { useCallback } from 'react'
+import React from 'react'
 
+import { useFreebuffCtrlCExit } from '../hooks/use-freebuff-ctrl-c-exit'
 import { useLogo } from '../hooks/use-logo'
 import { useTerminalDimensions } from '../hooks/use-terminal-dimensions'
 import { useTheme } from '../hooks/use-theme'
-import { exitFreebuffCleanly } from '../utils/freebuff-exit'
 import { getLogoAccentColor, getLogoBlockColor } from '../utils/theme-system'
 
-import type { KeyEvent } from '@opentui/core'
-
 /**
  * Terminal state shown after a 409 session_superseded response. Another CLI on
  * the same account rotated our instance id and we've stopped polling — the
@@ -26,16 +23,7 @@ export const FreebuffSupersededScreen: React.FC = () => {
     blockColor,
   })
 
-  // Ctrl+C exits. Stdin is in raw mode, so SIGINT never fires — the key comes
-  // through as a normal OpenTUI key event.
-  useKeyboard(
-    useCallback((key: KeyEvent) => {
-      if (key.ctrl && key.name === 'c') {
-        key.preventDefault?.()
-        exitFreebuffCleanly()
-      }
-    }, []),
-  )
+  useFreebuffCtrlCExit()
 
   return (
     <box

cli/src/components/freebuff-superseded-screen.tsx

@@ -1,11 +1,12 @@
 import { TextAttributes } from '@opentui/core'
-import { useKeyboard, useRenderer } from '@opentui/react'
-import React, { useCallback, useMemo, useState } from 'react'
+import { useRenderer } from '@opentui/react'
+import React, { useMemo, useState } from 'react'
 
 import { AdBanner } from './ad-banner'
 import { Button } from './button'
 import { ChoiceAdBanner } from './choice-ad-banner'
 import { ShimmerText } from './shimmer-text'
+import { useFreebuffCtrlCExit } from '../hooks/use-freebuff-ctrl-c-exit'
 import { useGravityAd } from '../hooks/use-gravity-ad'
 import { useLogo } from '../hooks/use-logo'
 import { useNow } from '../hooks/use-now'
@@ -16,7 +17,6 @@ import { exitFreebuffCleanly } from '../utils/freebuff-exit'
 import { getLogoAccentColor, getLogoBlockColor } from '../utils/theme-system'
 
 import type { FreebuffSessionResponse } from '../types/freebuff-session'
-import type { KeyEvent } from '@opentui/core'
 
 interface WaitingRoomScreenProps {
   session: FreebuffSessionResponse | null
@@ -77,16 +77,7 @@ export const WaitingRoomScreen: React.FC<WaitingRoomScreenProps> = ({
     forceStart: true,
   })
 
-  // Ctrl+C exits. Stdin is in raw mode, so SIGINT never fires — the key comes
-  // through as a normal OpenTUI key event. Shared with the top-right X button.
-  useKeyboard(
-    useCallback((key: KeyEvent) => {
-      if (key.ctrl && key.name === 'c') {
-        key.preventDefault?.()
-        exitFreebuffCleanly()
-      }
-    }, []),
-  )
+  useFreebuffCtrlCExit()
 
   const [exitHover, setExitHover] = useState(false)
 

cli/src/components/waiting-room-screen.tsx

@@ -0,0 +1,23 @@
+import { useKeyboard } from '@opentui/react'
+import { useCallback } from 'react'
+
+import { exitFreebuffCleanly } from '../utils/freebuff-exit'
+
+import type { KeyEvent } from '@opentui/core'
+
+/**
+ * Bind Ctrl+C on a full-screen freebuff view to `exitFreebuffCleanly`. Stdin
+ * is in raw mode, so SIGINT never fires — the key arrives as a normal OpenTUI
+ * key event and we route it through the shared cleanup path (flush analytics,
+ * release the session seat, then process.exit).
+ */
+export function useFreebuffCtrlCExit(): void {
+  useKeyboard(
+    useCallback((key: KeyEvent) => {
+      if (key.ctrl && key.name === 'c') {
+        key.preventDefault?.()
+        exitFreebuffCleanly()
+      }
+    }, []),
+  )
+}

cli/src/hooks/use-freebuff-ctrl-c-exit.ts

@@ -4,7 +4,7 @@
 
 The waiting room is the admission control layer for **free-mode** requests against the freebuff Fireworks deployment. It has three jobs:
 
-1. **Drip-admit users** — admit at a steady trickle (default 1 per 15s) so load ramps up gradually rather than stampeding the deployment when the queue is long.
+1. **Drip-admit users** — admit at a steady trickle (default 1 per `ADMISSION_TICK_MS`, currently 15s) so load ramps up gradually rather than stampeding the deployment when the queue is long.
 2. **Gate on upstream health** — before each admission tick, probe the Fireworks metrics endpoint with a short timeout (`isFireworksAdmissible` in `web/src/server/free-session/admission.ts`). If it doesn't respond OK, admission halts until it does — this is the primary concurrency control, not a static cap.
 3. **One instance per account** — prevent a single user from running N concurrent freebuff CLIs to get N× throughput.
 
@@ -132,14 +132,13 @@ One pod runs the admission loop at a time, coordinated via Postgres advisory loc
 Each tick does (in order):
 
 1. **Sweep expired.** `DELETE FROM free_session WHERE status='active' AND expires_at < now() - grace`. Runs regardless of upstream health so zombie sessions are cleaned up even during an outage.
-2. **Admit.** `admitFromQueue()` first calls `isFireworksAdmissible()` (short-timeout GET against the Fireworks metrics endpoint). If the probe fails, returns `{ skipped: 'health' }` — admission pauses and the queue grows until recovery. Otherwise opens a transaction, takes `pg_try_advisory_xact_lock(FREEBUFF_ADMISSION_LOCK_ID)`, and `SELECT ... WHERE status='queued' ORDER BY queued_at, user_id LIMIT MAX_ADMITS_PER_TICK FOR UPDATE SKIP LOCKED` → `UPDATE` the rows to `status='active'` with `admitted_at=now()`, `expires_at=now()+sessionLength`. Staggering at `MAX_ADMITS_PER_TICK=1` / 15s keeps Fireworks from a thundering herd of newly-admitted CLIs.
+2. **Admit.** `admitFromQueue()` first calls `isFireworksAdmissible()` (short-timeout GET against the Fireworks metrics endpoint). If the probe fails, returns `{ skipped: 'health' }` — admission pauses and the queue grows until recovery. Otherwise opens a transaction, takes `pg_try_advisory_xact_lock(FREEBUFF_ADMISSION_LOCK_ID)`, and `SELECT ... WHERE status='queued' ORDER BY queued_at, user_id LIMIT 1 FOR UPDATE SKIP LOCKED` → `UPDATE` the row to `status='active'` with `admitted_at=now()`, `expires_at=now()+sessionLength`. One admit per tick keeps Fireworks from a thundering herd of newly-admitted CLIs.
 
 ### Tunables
 
 | Constant | Location | Default | Purpose |
 |---|---|---|---|
-| `ADMISSION_TICK_MS` | `config.ts` | 15000 | How often the ticker fires |
-| `MAX_ADMITS_PER_TICK` | `config.ts` | 1 | Upper bound on admits per tick |
+| `ADMISSION_TICK_MS` | `config.ts` | 15000 | How often the ticker fires. One user is admitted per tick. |
 | `FREEBUFF_SESSION_LENGTH_MS` | env | 3_600_000 | Session lifetime |
 | `FREEBUFF_SESSION_GRACE_MS` | env | 1_800_000 | Drain window after expiry — gate still admits requests so an in-flight agent can finish, but the CLI is expected to block new prompts. Hard cutoff at `expires_at + grace`. |
 
@@ -224,6 +223,7 @@ For free-mode requests (`codebuff_metadata.cost_mode === 'free'`), `_post.ts` ca
 
 | HTTP | `error` | When |
 |---|---|---|
+| 426 | `freebuff_update_required` | Request did not include a `freebuff_instance_id` — the client is a pre-waiting-room build. The CLI shows the server-supplied message verbatim. |
 | 428 | `waiting_room_required` | No session row exists. Client should call POST /session. |
 | 429 | `waiting_room_queued` | Row exists with `status='queued'`. Client should keep polling GET. |
 | 409 | `session_superseded` | Claimed `instance_id` does not match stored one — another CLI took over. |
@@ -249,13 +249,11 @@ This is a **trust-the-client** design: the server still admits requests during t
 Computed in `session-view.ts` from the drip-admission rate:
 
 ```
-ticksAhead = ceil((position - 1) / maxAdmitsPerTick)
-waitMs     = ticksAhead * admissionTickMs
+waitMs = (position - 1) * admissionTickMs
 ```
 
 - Position 1 → 0 (next tick admits you)
-- Position `maxAdmitsPerTick` + 1 → one tick
-- and so on.
+- Position 2 → one tick, and so on.
 
 This estimate **ignores health-gated pauses**: during a Fireworks incident admission halts entirely, so the actual wait can be longer. We choose to under-report here because showing "unknown" / "indefinite" is worse UX for the common case where the deployment is healthy.
 

docs/freebuff-waiting-room.md

@@ -147,6 +147,7 @@ const STATUS_BY_GATE_CODE = {
   waiting_room_queued: 429,
   session_superseded: 409,
   session_expired: 410,
+  freebuff_update_required: 426,
 } satisfies Record<GateRejectCode, number>
 
 export async function postChatCompletions(params: {
@@ -412,30 +413,8 @@ export async function postChatCompletions(params: {
     if (isFreeModeRequest) {
       const claimedInstanceId =
         typedBody.codebuff_metadata?.freebuff_instance_id
-      const gate = await checkSession({
-        userId,
-        claimedInstanceId,
-      })
+      const gate = await checkSession({ userId, claimedInstanceId })
       if (!gate.ok) {
-        // Old freebuff clients (pre-waiting-room) never send an instance_id.
-        // Return a 426 with a clear "please restart to upgrade" message that
-        // their existing error banner will render verbatim.
-        if (!claimedInstanceId) {
-          trackEvent({
-            event: AnalyticsEvent.CHAT_COMPLETIONS_VALIDATION_ERROR,
-            userId,
-            properties: { error: 'freebuff_update_required' },
-            logger,
-          })
-          return NextResponse.json(
-            {
-              error: 'freebuff_update_required',
-              message:
-                'This version of freebuff is out of date. Please restart freebuff to upgrade and continue using free mode.',
-            },
-            { status: 426 },
-          )
-        }
         trackEvent({
           event: AnalyticsEvent.CHAT_COMPLETIONS_VALIDATION_ERROR,
           userId,

web/src/app/api/v1/chat/completions/_post.ts

@@ -34,7 +34,6 @@ function makeSessionDeps(overrides: Partial<SessionDeps> = {}): SessionDeps & {
     rows,
     isWaitingRoomEnabled: () => true,
     admissionTickMs: 15_000,
-    maxAdmitsPerTick: 1,
     graceMs: 30 * 60 * 1000,
     now: () => now,
     getSessionRow: async (userId) => rows.get(userId) ?? null,

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

@@ -12,7 +12,6 @@ import type { InternalSessionRow } from '../types'
 
 const SESSION_LEN = 60 * 60 * 1000
 const TICK_MS = 15_000
-const ADMITS_PER_TICK = 1
 const GRACE_MS = 30 * 60 * 1000
 
 function makeDeps(overrides: Partial<SessionDeps> = {}): SessionDeps & {
@@ -38,7 +37,6 @@ function makeDeps(overrides: Partial<SessionDeps> = {}): SessionDeps & {
     _now: () => currentNow,
     isWaitingRoomEnabled: () => true,
     admissionTickMs: TICK_MS,
-    maxAdmitsPerTick: ADMITS_PER_TICK,
     graceMs: GRACE_MS,
     now: () => currentNow,
     getSessionRow: async (userId) => rows.get(userId) ?? null,
@@ -329,7 +327,9 @@ describe('checkSessionAdmissible', () => {
     expect(result.code).toBe('session_superseded')
   })
 
-  test('active + missing instance id → session_superseded (fails closed)', async () => {
+  test('missing instance id → freebuff_update_required (pre-waiting-room CLI)', async () => {
+    // Classified up front regardless of row state: old clients never send an
+    // id, so we surface a distinct code that maps to 426 Upgrade Required.
     await requestSession({ userId: 'u1', deps })
     const row = deps.rows.get('u1')!
     row.status = 'active'
@@ -342,7 +342,7 @@ describe('checkSessionAdmissible', () => {
       deps,
     })
     if (result.ok) throw new Error('unreachable')
-    expect(result.code).toBe('session_superseded')
+    expect(result.code).toBe('freebuff_update_required')
   })
 
   test('active inside grace window → ok with reason=draining', async () => {

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

@@ -5,7 +5,6 @@ import { estimateWaitMs, toSessionStateResponse } from '../session-view'
 import type { InternalSessionRow } from '../types'
 
 const TICK_MS = 15_000
-const ADMITS_PER_TICK = 1
 const GRACE_MS = 30 * 60_000
 
 function row(overrides: Partial<InternalSessionRow> = {}): InternalSessionRow {
@@ -25,34 +24,24 @@ function row(overrides: Partial<InternalSessionRow> = {}): InternalSessionRow {
 
 describe('estimateWaitMs', () => {
   test('position 1 → 0 wait (next tick picks you up)', () => {
-    expect(estimateWaitMs({ position: 1, admissionTickMs: TICK_MS, maxAdmitsPerTick: ADMITS_PER_TICK })).toBe(0)
+    expect(estimateWaitMs({ position: 1, admissionTickMs: TICK_MS })).toBe(0)
   })
 
-  test('position N → (N-1) ticks ahead at 1 admit/tick', () => {
-    expect(estimateWaitMs({ position: 2, admissionTickMs: TICK_MS, maxAdmitsPerTick: 1 })).toBe(TICK_MS)
-    expect(estimateWaitMs({ position: 10, admissionTickMs: TICK_MS, maxAdmitsPerTick: 1 })).toBe(9 * TICK_MS)
-  })
-
-  test('batched admission divides wait', () => {
-    // 5 admits/tick: positions 2-6 all sit one tick ahead.
-    expect(estimateWaitMs({ position: 2, admissionTickMs: TICK_MS, maxAdmitsPerTick: 5 })).toBe(TICK_MS)
-    expect(estimateWaitMs({ position: 6, admissionTickMs: TICK_MS, maxAdmitsPerTick: 5 })).toBe(TICK_MS)
-    // Position 7 enters the second tick.
-    expect(estimateWaitMs({ position: 7, admissionTickMs: TICK_MS, maxAdmitsPerTick: 5 })).toBe(2 * TICK_MS)
+  test('position N → (N-1) ticks ahead', () => {
+    expect(estimateWaitMs({ position: 2, admissionTickMs: TICK_MS })).toBe(TICK_MS)
+    expect(estimateWaitMs({ position: 10, admissionTickMs: TICK_MS })).toBe(9 * TICK_MS)
   })
 
   test('degenerate inputs return 0', () => {
-    expect(estimateWaitMs({ position: 0, admissionTickMs: TICK_MS, maxAdmitsPerTick: 1 })).toBe(0)
-    expect(estimateWaitMs({ position: 5, admissionTickMs: 0, maxAdmitsPerTick: 1 })).toBe(0)
-    expect(estimateWaitMs({ position: 5, admissionTickMs: TICK_MS, maxAdmitsPerTick: 0 })).toBe(0)
+    expect(estimateWaitMs({ position: 0, admissionTickMs: TICK_MS })).toBe(0)
+    expect(estimateWaitMs({ position: 5, admissionTickMs: 0 })).toBe(0)
   })
 })
 
 describe('toSessionStateResponse', () => {
   const now = new Date('2026-04-17T12:00:00Z')
   const baseArgs = {
     admissionTickMs: TICK_MS,
-    maxAdmitsPerTick: ADMITS_PER_TICK,
     graceMs: GRACE_MS,
   }
 

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

@@ -2,7 +2,6 @@ import { env } from '@codebuff/internal/env'
 
 import {
   ADMISSION_TICK_MS,
-  MAX_ADMITS_PER_TICK,
   getSessionGraceMs,
   getSessionLengthMs,
   isWaitingRoomEnabled,
@@ -153,7 +152,7 @@ export function startFreeSessionAdmission(): boolean {
   if (typeof interval.unref === 'function') interval.unref()
   runTick() // fire first tick immediately
   logger.info(
-    { tickMs: ADMISSION_TICK_MS, maxAdmitsPerTick: MAX_ADMITS_PER_TICK },
+    { tickMs: ADMISSION_TICK_MS },
     '[FreeSessionAdmission] Started',
   )
   return true