Drop MAX_CONCURRENT_SESSIONS; drip admission is sole concurrency control

FREEBUFF_MAX_CONCURRENT_SESSIONS is gone. Admission now runs purely
as a drip (MAX_ADMITS_PER_TICK=1 every 15s) gated by the Fireworks
health monitor — utilisation ramps up slowly and pauses the moment
metrics degrade, so a static cap is redundant.

Renamed SessionDeps' getMaxConcurrentSessions/getSessionLengthMs to
getAdmissionTickMs/getMaxAdmitsPerTick (those are what the wait-time
estimate actually needs now). estimateWaitMs is rewritten from the
session-cycle model to the drip model:
  waitMs = ceil((position - 1) / maxAdmitsPerTick) * admissionTickMs
Dropped the 'full' branch of AdmissionTickResult and the full-capacity
admission test — the only reason admission skips now is health.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jahooma

docs/freebuff-waiting-room.md

@@ -4,8 +4,8 @@
 
 The waiting room is the admission control layer for **free-mode** requests against the freebuff Fireworks deployment. It has three jobs:
 
-1. **Bound concurrency** — cap the number of simultaneously-active free users so one deployment does not degrade under load.
-2. **Gate on upstream health** — only admit new users while the Fireworks deployment is reporting `healthy` (via the separate monitor in `web/src/server/fireworks-monitor/`).
+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.
+2. **Gate on upstream health** — only admit new users while the Fireworks deployment is reporting `healthy` (via the separate monitor in `web/src/server/fireworks-monitor/`). Once metrics degrade, admission halts until they recover — 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.
 
 Users who cannot be admitted immediately are placed in a FIFO queue and given an estimated wait time. Admitted users get a fixed-length session (default 1h) during which they can make free-mode requests subject to the existing per-user rate limits.
@@ -20,7 +20,6 @@ FREEBUFF_WAITING_ROOM_ENABLED=false
 
 # Other knobs (only read when enabled)
 FREEBUFF_SESSION_LENGTH_MS=3600000         # 1 hour
-FREEBUFF_MAX_CONCURRENT_SESSIONS=50
 ```
 
 Flipping the flag is safe at runtime: existing rows stay in the DB and will be admitted / expired correctly whenever the flag is flipped back on.
@@ -127,17 +126,15 @@ Each tick does (in order):
 
 1. **Sweep expired.** `DELETE FROM free_session WHERE status='active' AND expires_at < now()`. Runs regardless of upstream health so zombie sessions are cleaned up even during an outage.
 2. **Check upstream health.** `isFireworksAdmissible()` from the monitor. If not `healthy`, skip admission for this tick (queue grows; users see `status: 'queued'` with increasing position).
-3. **Measure capacity.** `capacity = min(MAX_CONCURRENT - activeCount, MAX_ADMITS_PER_TICK)`. `MAX_ADMITS_PER_TICK=20` caps thundering-herd admission when a large block of sessions expires simultaneously.
-4. **Admit.** `SELECT ... WHERE status='queued' ORDER BY queued_at, user_id LIMIT capacity FOR UPDATE SKIP LOCKED`, then `UPDATE` those rows to `status='active'` with `admitted_at=now()`, `expires_at=now()+sessionLength`.
+3. **Admit.** `SELECT ... WHERE status='queued' ORDER BY queued_at, user_id LIMIT MAX_ADMITS_PER_TICK FOR UPDATE SKIP LOCKED`, then `UPDATE` those rows to `status='active'` with `admitted_at=now()`, `expires_at=now()+sessionLength`. Staggering the queue at `MAX_ADMITS_PER_TICK=1` / 15s keeps Fireworks from getting hit by a thundering herd of newly-admitted CLIs; once metrics show the deployment is saturated, step 2 halts further admissions.
 
 ### Tunables
 
 | Constant | Location | Default | Purpose |
 |---|---|---|---|
-| `ADMISSION_TICK_MS` | `config.ts` | 5000 | How often the ticker fires |
-| `MAX_ADMITS_PER_TICK` | `config.ts` | 20 | Upper bound on admits per tick |
+| `ADMISSION_TICK_MS` | `config.ts` | 15000 | How often the ticker fires |
+| `MAX_ADMITS_PER_TICK` | `config.ts` | 1 | Upper bound on admits per tick |
 | `FREEBUFF_SESSION_LENGTH_MS` | env | 3_600_000 | Session lifetime |
-| `FREEBUFF_MAX_CONCURRENT_SESSIONS` | env | 50 | Global active-session cap |
 
 ## HTTP API
 
@@ -210,18 +207,18 @@ When the waiting room is disabled, the gate returns `{ ok: true, reason: 'disabl
 
 ## Estimated Wait Time
 
-Computed in `session-view.ts` as an **upper bound** that assumes uniform session expiry:
+Computed in `session-view.ts` from the drip-admission rate:
 
 ```
-waves      = floor((position - 1) / maxConcurrent)
-waitMs     = waves * sessionLengthMs
+ticksAhead = ceil((position - 1) / maxAdmitsPerTick)
+waitMs     = ticksAhead * admissionTickMs
 ```
 
-- Position 1..`maxConcurrent` → 0 (next tick will admit them)
-- Position `maxConcurrent`+1..`2*maxConcurrent` → one full session length
+- Position 1 → 0 (next tick admits you)
+- Position `maxAdmitsPerTick` + 1 → one tick
 - and so on.
 
-Actual wait is usually shorter because users call `DELETE /session` on CLI exit and sessions turn over naturally. We show an upper bound because under-promising on wait time is better UX than surprise delays.
+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.
 
 ## CLI Integration (frontend-side contract)
 

packages/internal/src/env-schema.ts

@@ -42,7 +42,6 @@ export const serverEnvSchema = clientEnvSchema.extend({
     .default('false')
     .transform((v) => v === 'true'),
   FREEBUFF_SESSION_LENGTH_MS: z.coerce.number().int().positive().default(60 * 60 * 1000),
-  FREEBUFF_MAX_CONCURRENT_SESSIONS: z.coerce.number().int().positive().default(50),
 })
 export const serverEnvVars = serverEnvSchema.keyof().options
 export type ServerEnvVar = (typeof serverEnvVars)[number]
@@ -94,5 +93,4 @@ export const serverProcessEnv: ServerInput = {
   // Freebuff waiting room
   FREEBUFF_WAITING_ROOM_ENABLED: process.env.FREEBUFF_WAITING_ROOM_ENABLED,
   FREEBUFF_SESSION_LENGTH_MS: process.env.FREEBUFF_SESSION_LENGTH_MS,
-  FREEBUFF_MAX_CONCURRENT_SESSIONS: process.env.FREEBUFF_MAX_CONCURRENT_SESSIONS,
 }

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

@@ -28,8 +28,8 @@ function makeSessionDeps(overrides: Partial<SessionDeps> = {}): SessionDeps & {
   return {
     rows,
     isWaitingRoomEnabled: () => true,
-    getMaxConcurrentSessions: () => 10,
-    getSessionLengthMs: () => 60 * 60_000,
+    getAdmissionTickMs: () => 15_000,
+    getMaxAdmitsPerTick: () => 1,
     now: () => now,
     getSessionRow: async (userId) => rows.get(userId) ?? null,
     queueDepth: async () => [...rows.values()].filter((r) => r.status === 'queued').length,

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

@@ -20,53 +20,36 @@ function makeAdmissionDeps(overrides: Partial<AdmissionDeps> = {}): AdmissionDep
       return Array.from({ length: limit }, (_, i) => ({ user_id: `u${i}` }))
     },
     isFireworksAdmissible: () => true,
-    getMaxConcurrentSessions: () => 10,
+    getMaxAdmitsPerTick: () => 1,
     getSessionLengthMs: () => 60 * 60 * 1000,
     now: () => NOW,
     ...overrides,
   }
 }
 
 describe('runAdmissionTick', () => {
-  test('admits up to (max - active) when healthy', async () => {
-    const deps = makeAdmissionDeps({
-      countActive: async () => 3,
-      getMaxConcurrentSessions: () => 10,
-    })
+  test('admits maxAdmitsPerTick when healthy', async () => {
+    const deps = makeAdmissionDeps({ getMaxAdmitsPerTick: () => 2 })
     const result = await runAdmissionTick(deps)
-    expect(result.admitted).toBe(7)
+    expect(result.admitted).toBe(2)
     expect(result.skipped).toBeNull()
   })
 
-  test('caps admits per tick at MAX_ADMITS_PER_TICK', async () => {
-    const deps = makeAdmissionDeps({
-      countActive: async () => 0,
-      getMaxConcurrentSessions: () => 1000,
-    })
+  test('defaults to 1 admit per tick', async () => {
+    const deps = makeAdmissionDeps()
     const result = await runAdmissionTick(deps)
-    expect(result.admitted).toBe(20)
+    expect(result.admitted).toBe(1)
   })
 
   test('skips admission when Fireworks not healthy', async () => {
     const deps = makeAdmissionDeps({
       isFireworksAdmissible: () => false,
-      countActive: async () => 0,
     })
     const result = await runAdmissionTick(deps)
     expect(result.admitted).toBe(0)
     expect(result.skipped).toBe('health')
   })
 
-  test('skips when at capacity', async () => {
-    const deps = makeAdmissionDeps({
-      countActive: async () => 10,
-      getMaxConcurrentSessions: () => 10,
-    })
-    const result = await runAdmissionTick(deps)
-    expect(result.admitted).toBe(0)
-    expect(result.skipped).toBe('full')
-  })
-
   test('sweeps expired sessions even when skipping admission', async () => {
     let swept = 0
     const deps = makeAdmissionDeps({
@@ -85,10 +68,9 @@ describe('runAdmissionTick', () => {
     const deps = makeAdmissionDeps({
       sweepExpired: async () => 2,
       countActive: async () => 5,
-      getMaxConcurrentSessions: () => 8,
     })
     const result = await runAdmissionTick(deps)
     expect(result.expired).toBe(2)
-    expect(result.admitted).toBe(3)
+    expect(result.admitted).toBe(1)
   })
 })

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

@@ -11,7 +11,8 @@ import type { SessionDeps } from '../public-api'
 import type { InternalSessionRow } from '../types'
 
 const SESSION_LEN = 60 * 60 * 1000
-const MAX_CONC = 10
+const TICK_MS = 15_000
+const ADMITS_PER_TICK = 1
 
 function makeDeps(overrides: Partial<SessionDeps> = {}): SessionDeps & {
   rows: Map<string, InternalSessionRow>
@@ -35,8 +36,8 @@ function makeDeps(overrides: Partial<SessionDeps> = {}): SessionDeps & {
     },
     _now: () => currentNow,
     isWaitingRoomEnabled: () => true,
-    getMaxConcurrentSessions: () => MAX_CONC,
-    getSessionLengthMs: () => SESSION_LEN,
+    getAdmissionTickMs: () => TICK_MS,
+    getMaxAdmitsPerTick: () => ADMITS_PER_TICK,
     now: () => currentNow,
     getSessionRow: async (userId) => rows.get(userId) ?? null,
     endSession: async (userId) => {

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

@@ -4,8 +4,8 @@ import { estimateWaitMs, toSessionStateResponse } from '../session-view'
 
 import type { InternalSessionRow } from '../types'
 
-const SESSION_LEN = 60 * 60 * 1000
-const MAX_CONC = 50
+const TICK_MS = 15_000
+const ADMITS_PER_TICK = 1
 
 function row(overrides: Partial<InternalSessionRow> = {}): InternalSessionRow {
   const now = new Date('2026-04-17T12:00:00Z')
@@ -23,35 +23,43 @@ function row(overrides: Partial<InternalSessionRow> = {}): InternalSessionRow {
 }
 
 describe('estimateWaitMs', () => {
-  test('position <= capacity → 0 wait', () => {
-    expect(estimateWaitMs({ position: 1, maxConcurrent: MAX_CONC, sessionLengthMs: SESSION_LEN })).toBe(0)
-    expect(estimateWaitMs({ position: MAX_CONC, maxConcurrent: MAX_CONC, sessionLengthMs: SESSION_LEN })).toBe(0)
+  test('position 1 → 0 wait (next tick picks you up)', () => {
+    expect(estimateWaitMs({ position: 1, admissionTickMs: TICK_MS, maxAdmitsPerTick: ADMITS_PER_TICK })).toBe(0)
   })
 
-  test('position in second wave → one full session length', () => {
-    expect(estimateWaitMs({ position: MAX_CONC + 1, maxConcurrent: MAX_CONC, sessionLengthMs: SESSION_LEN })).toBe(SESSION_LEN)
+  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('position in third wave → two full session lengths', () => {
-    expect(estimateWaitMs({ position: 2 * MAX_CONC + 1, maxConcurrent: MAX_CONC, sessionLengthMs: SESSION_LEN })).toBe(2 * SESSION_LEN)
+  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('degenerate inputs return 0', () => {
-    expect(estimateWaitMs({ position: 0, maxConcurrent: 10, sessionLengthMs: 1000 })).toBe(0)
-    expect(estimateWaitMs({ position: 5, maxConcurrent: 0, sessionLengthMs: 1000 })).toBe(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)
   })
 })
 
 describe('toSessionStateResponse', () => {
   const now = new Date('2026-04-17T12:00:00Z')
+  const baseArgs = {
+    admissionTickMs: TICK_MS,
+    maxAdmitsPerTick: ADMITS_PER_TICK,
+  }
 
   test('returns null when row is null', () => {
     const view = toSessionStateResponse({
       row: null,
       position: 0,
       queueDepth: 0,
-      maxConcurrent: MAX_CONC,
-      sessionLengthMs: SESSION_LEN,
+      ...baseArgs,
       now,
     })
     expect(view).toBeNull()
@@ -60,18 +68,17 @@ describe('toSessionStateResponse', () => {
   test('queued row maps to queued response with position + wait estimate', () => {
     const view = toSessionStateResponse({
       row: row({ status: 'queued' }),
-      position: 51,
-      queueDepth: 100,
-      maxConcurrent: MAX_CONC,
-      sessionLengthMs: SESSION_LEN,
+      position: 3,
+      queueDepth: 10,
+      ...baseArgs,
       now,
     })
     expect(view).toEqual({
       status: 'queued',
       instanceId: 'inst-1',
-      position: 51,
-      queueDepth: 100,
-      estimatedWaitMs: SESSION_LEN,
+      position: 3,
+      queueDepth: 10,
+      estimatedWaitMs: 2 * TICK_MS,
       queuedAt: now.toISOString(),
     })
   })
@@ -83,8 +90,7 @@ describe('toSessionStateResponse', () => {
       row: row({ status: 'active', admitted_at: admittedAt, expires_at: expiresAt }),
       position: 0,
       queueDepth: 0,
-      maxConcurrent: MAX_CONC,
-      sessionLengthMs: SESSION_LEN,
+      ...baseArgs,
       now,
     })
     expect(view).toEqual({
@@ -101,8 +107,7 @@ describe('toSessionStateResponse', () => {
       row: row({ status: 'active', admitted_at: now, expires_at: new Date(now.getTime() - 1) }),
       position: 0,
       queueDepth: 0,
-      maxConcurrent: MAX_CONC,
-      sessionLengthMs: SESSION_LEN,
+      ...baseArgs,
       now,
     })
     expect(view).toBeNull()

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

@@ -1,7 +1,6 @@
 import {
   ADMISSION_TICK_MS,
   MAX_ADMITS_PER_TICK,
-  getMaxConcurrentSessions,
   getSessionLengthMs,
   isWaitingRoomEnabled,
 } from './config'
@@ -20,8 +19,8 @@ let state: AdmissionState | null = null
 
 /** Emit a `[FreeSessionAdmission] snapshot` log every N ticks even when
  *  nothing changed, so dashboards / alerts have a reliable heartbeat of
- *  queue depth and active count. At ADMISSION_TICK_MS=5s, 12 ticks = 1 min. */
-const SNAPSHOT_EVERY_N_TICKS = 12
+ *  queue depth and active count. At ADMISSION_TICK_MS=15s, 10 ticks = 2.5 min. */
+const SNAPSHOT_EVERY_N_TICKS = 10
 
 export interface AdmissionDeps {
   sweepExpired: (now: Date) => Promise<number>
@@ -33,7 +32,7 @@ export interface AdmissionDeps {
     now: Date
   }) => Promise<{ user_id: string }[]>
   isFireworksAdmissible: () => boolean
-  getMaxConcurrentSessions: () => number
+  getMaxAdmitsPerTick: () => number
   getSessionLengthMs: () => number
   now?: () => Date
 }
@@ -44,7 +43,7 @@ const defaultDeps: AdmissionDeps = {
   queueDepth,
   admitFromQueue,
   isFireworksAdmissible,
-  getMaxConcurrentSessions,
+  getMaxAdmitsPerTick: () => MAX_ADMITS_PER_TICK,
   getSessionLengthMs,
 }
 
@@ -53,14 +52,19 @@ export interface AdmissionTickResult {
   admitted: number
   active: number
   queueDepth: number
-  skipped: 'health' | 'full' | null
+  skipped: 'health' | null
 }
 
 /**
  * Run a single admission tick:
  *   1. Expire sessions past their expires_at.
  *   2. If Fireworks is not 'healthy', skip admission (waiting queue grows).
- *   3. Admit up to (maxConcurrent - activeCount, MAX_ADMITS_PER_TICK) users.
+ *   3. Admit up to maxAdmitsPerTick queued users.
+ *
+ * There is no global concurrency cap — the Fireworks health monitor is the
+ * primary gate. Admission drips at (maxAdmitsPerTick / ADMISSION_TICK_MS),
+ * which drives utilization up slowly; once metrics degrade, step 2 halts
+ * admission until things recover.
  *
  * Returns counts for observability. Safe to call concurrently across pods —
  * the underlying admit query takes an advisory xact lock.
@@ -80,15 +84,8 @@ export async function runAdmissionTick(
   }
 
   const active = await deps.countActive(now)
-  const max = deps.getMaxConcurrentSessions()
-  const capacity = Math.min(Math.max(0, max - active), MAX_ADMITS_PER_TICK)
-  if (capacity === 0) {
-    const depth = await deps.queueDepth()
-    return { expired, admitted: 0, active, queueDepth: depth, skipped: 'full' }
-  }
-
   const admitted = await deps.admitFromQueue({
-    limit: capacity,
+    limit: deps.getMaxAdmitsPerTick(),
     sessionLengthMs: deps.getSessionLengthMs(),
     now,
   })
@@ -129,7 +126,6 @@ function runTick() {
             expired: result.expired,
             active: result.active,
             queueDepth: result.queueDepth,
-            maxConcurrent: getMaxConcurrentSessions(),
             skipped: result.skipped,
           },
           changed ? '[FreeSessionAdmission] tick' : '[FreeSessionAdmission] snapshot',
@@ -158,7 +154,7 @@ export function startFreeSessionAdmission(): boolean {
   state = { timer: null, inFlight: null, tickCount: 0 }
   runTick()
   logger.info(
-    { tickMs: ADMISSION_TICK_MS, maxConcurrent: getMaxConcurrentSessions() },
+    { tickMs: ADMISSION_TICK_MS, maxAdmitsPerTick: MAX_ADMITS_PER_TICK },
     '[FreeSessionAdmission] Started',
   )
   return true

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

@@ -24,7 +24,3 @@ export function isWaitingRoomEnabled(): boolean {
 export function getSessionLengthMs(): number {
   return env.FREEBUFF_SESSION_LENGTH_MS
 }
-
-export function getMaxConcurrentSessions(): number {
-  return env.FREEBUFF_MAX_CONCURRENT_SESSIONS
-}