Add freebuff session grace window

Keep admitting requests for FREEBUFF_SESSION_GRACE_MS (default 30m) after a
session's expires_at so in-flight agent runs can drain; hard cutoff past that.
Also: replicas=0 → unhealthy, hoist chat/completions gate status map, fix
stale threshold comment and a pre-existing free-mode test missing the
checkSessionAdmissible override.

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

Author: jahooma

packages/internal/src/env-schema.ts

@@ -42,6 +42,7 @@ 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_SESSION_GRACE_MS: z.coerce.number().int().nonnegative().default(30 * 60 * 1000),
 })
 export const serverEnvVars = serverEnvSchema.keyof().options
 export type ServerEnvVar = (typeof serverEnvVars)[number]
@@ -93,4 +94,5 @@ 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_SESSION_GRACE_MS: process.env.FREEBUFF_SESSION_GRACE_MS,
 }

web/src/app/api/v1/chat/completions/__tests__/completions.test.ts

@@ -583,6 +583,7 @@ describe('/api/v1/chat/completions POST endpoint', () => {
         fetch: mockFetch,
         insertMessageBigquery: mockInsertMessageBigquery,
         loggerWithContext: mockLoggerWithContext,
+        checkSessionAdmissible: mockCheckSessionAdmissibleAllow,
       })
 
       expect(response.status).toBe(200)

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

@@ -68,6 +68,8 @@ import {
   OpenRouterError,
 } from '@/llm-api/openrouter'
 import { checkSessionAdmissible } from '@/server/free-session/public-api'
+
+import type { SessionGateResult } from '@/server/free-session/public-api'
 import { extractApiKeyFromHeader } from '@/util/auth'
 import { withDefaultProperties } from '@codebuff/common/analytics'
 import { checkFreeModeRateLimit } from './free-mode-rate-limiter'
@@ -138,6 +140,15 @@ export const formatQuotaResetCountdown = (
 
 export type CheckSessionAdmissibleFn = typeof checkSessionAdmissible
 
+type GateRejectCode = Extract<SessionGateResult, { ok: false }>['code']
+
+const STATUS_BY_GATE_CODE = {
+  waiting_room_required: 428,
+  waiting_room_queued: 429,
+  session_superseded: 409,
+  session_expired: 410,
+} satisfies Record<GateRejectCode, number>
+
 export async function postChatCompletions(params: {
   req: NextRequest
   getUserInfoFromApiKey: GetUserInfoFromApiKeyFn
@@ -410,15 +421,9 @@ export async function postChatCompletions(params: {
           properties: { error: gate.code },
           logger,
         })
-        const statusByCode: Record<string, number> = {
-          waiting_room_required: 428,
-          waiting_room_queued: 429,
-          session_superseded: 409,
-          session_expired: 410,
-        }
         return NextResponse.json(
           { error: gate.code, message: gate.message },
-          { status: statusByCode[gate.code] ?? 429 },
+          { status: STATUS_BY_GATE_CODE[gate.code] },
         )
       }
     }

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

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

web/src/server/fireworks-monitor/compute-health.ts

@@ -38,10 +38,8 @@ export interface HealthThresholds {
   ttftMsUnhealthy: number
 }
 
-// Default thresholds are calibrated to the observed freebuff workload on
-// glm-5.1 / kimi-k2.5. They are intentionally loose at first so a cold
-// deployment does not flap; expect to tighten once you have a week of
-// live data. Override per-instance via startFireworksMonitor({ thresholds }).
+// Tuned to trip 'degraded' before users feel it on glm-5.1. Override per-instance
+// via startFireworksMonitor({ thresholds }).
 export const DEFAULT_HEALTH_THRESHOLDS: HealthThresholds = {
   staleSnapshotMs: 3 * 60 * 1000,
   minRequestRateForErrorCheck: 0.1,

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

@@ -22,6 +22,7 @@ function makeAdmissionDeps(overrides: Partial<AdmissionDeps> = {}): AdmissionDep
     isFireworksAdmissible: () => true,
     getMaxAdmitsPerTick: () => 1,
     getSessionLengthMs: () => 60 * 60 * 1000,
+    getSessionGraceMs: () => 30 * 60 * 1000,
     now: () => NOW,
     ...overrides,
   }
@@ -73,4 +74,17 @@ describe('runAdmissionTick', () => {
     expect(result.expired).toBe(2)
     expect(result.admitted).toBe(1)
   })
+
+  test('forwards grace ms to sweepExpired', async () => {
+    const received: number[] = []
+    const deps = makeAdmissionDeps({
+      getSessionGraceMs: () => 12_345,
+      sweepExpired: async (_now, graceMs) => {
+        received.push(graceMs)
+        return 0
+      },
+    })
+    await runAdmissionTick(deps)
+    expect(received).toEqual([12_345])
+  })
 })

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

@@ -13,6 +13,7 @@ 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 & {
   rows: Map<string, InternalSessionRow>
@@ -38,6 +39,7 @@ function makeDeps(overrides: Partial<SessionDeps> = {}): SessionDeps & {
     isWaitingRoomEnabled: () => true,
     getAdmissionTickMs: () => TICK_MS,
     getMaxAdmitsPerTick: () => ADMITS_PER_TICK,
+    getSessionGraceMs: () => GRACE_MS,
     now: () => currentNow,
     getSessionRow: async (userId) => rows.get(userId) ?? null,
     endSession: async (userId) => {
@@ -250,12 +252,30 @@ describe('checkSessionAdmissible', () => {
     expect(result.code).toBe('session_superseded')
   })
 
-  test('active but expires_at in the past → session_expired', async () => {
+  test('active inside grace window → ok with reason=draining', async () => {
+    await requestSession({ userId: 'u1', deps })
+    const row = deps.rows.get('u1')!
+    row.status = 'active'
+    row.admitted_at = new Date(deps._now().getTime() - SESSION_LEN - 60_000)
+    // 1 minute past expiry, well within the 30-minute grace window
+    row.expires_at = new Date(deps._now().getTime() - 60_000)
+
+    const result = await checkSessionAdmissible({
+      userId: 'u1',
+      claimedInstanceId: row.active_instance_id,
+      deps,
+    })
+    expect(result.ok).toBe(true)
+    if (!result.ok || result.reason !== 'draining') throw new Error('unreachable')
+    expect(result.gracePeriodRemainingMs).toBe(GRACE_MS - 60_000)
+  })
+
+  test('active past the grace window → session_expired', async () => {
     await requestSession({ userId: 'u1', deps })
     const row = deps.rows.get('u1')!
     row.status = 'active'
     row.admitted_at = new Date(deps._now().getTime() - 2 * SESSION_LEN)
-    row.expires_at = new Date(deps._now().getTime() - 1)
+    row.expires_at = new Date(deps._now().getTime() - GRACE_MS - 1)
 
     const result = await checkSessionAdmissible({
       userId: 'u1',
@@ -265,6 +285,22 @@ describe('checkSessionAdmissible', () => {
     if (result.ok) throw new Error('unreachable')
     expect(result.code).toBe('session_expired')
   })
+
+  test('draining + wrong instance id still rejects with session_superseded', async () => {
+    await requestSession({ userId: 'u1', deps })
+    const row = deps.rows.get('u1')!
+    row.status = 'active'
+    row.admitted_at = new Date(deps._now().getTime() - SESSION_LEN - 60_000)
+    row.expires_at = new Date(deps._now().getTime() - 60_000)
+
+    const result = await checkSessionAdmissible({
+      userId: 'u1',
+      claimedInstanceId: 'stale-token',
+      deps,
+    })
+    if (result.ok) throw new Error('unreachable')
+    expect(result.code).toBe('session_superseded')
+  })
 })
 
 describe('endUserSession', () => {

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

@@ -6,6 +6,7 @@ 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 {
   const now = new Date('2026-04-17T12:00:00Z')
@@ -52,6 +53,7 @@ describe('toSessionStateResponse', () => {
   const baseArgs = {
     admissionTickMs: TICK_MS,
     maxAdmitsPerTick: ADMITS_PER_TICK,
+    graceMs: GRACE_MS,
   }
 
   test('returns null when row is null', () => {
@@ -102,9 +104,33 @@ describe('toSessionStateResponse', () => {
     })
   })
 
-  test('active but expired row maps to null (caller should re-queue)', () => {
+  test('active row inside grace window maps to draining response', () => {
+    const admittedAt = new Date(now.getTime() - 65 * 60_000)
+    const expiresAt = new Date(now.getTime() - 5 * 60_000) // 5 min past expiry
     const view = toSessionStateResponse({
-      row: row({ status: 'active', admitted_at: now, expires_at: new Date(now.getTime() - 1) }),
+      row: row({ status: 'active', admitted_at: admittedAt, expires_at: expiresAt }),
+      position: 0,
+      queueDepth: 0,
+      ...baseArgs,
+      now,
+    })
+    expect(view).toEqual({
+      status: 'draining',
+      instanceId: 'inst-1',
+      admittedAt: admittedAt.toISOString(),
+      expiresAt: expiresAt.toISOString(),
+      gracePeriodEndsAt: new Date(expiresAt.getTime() + GRACE_MS).toISOString(),
+      gracePeriodRemainingMs: GRACE_MS - 5 * 60_000,
+    })
+  })
+
+  test('active row past the grace window maps to null (caller should re-queue)', () => {
+    const view = toSessionStateResponse({
+      row: row({
+        status: 'active',
+        admitted_at: now,
+        expires_at: new Date(now.getTime() - GRACE_MS - 1),
+      }),
       position: 0,
       queueDepth: 0,
       ...baseArgs,

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

@@ -1,6 +1,7 @@
 import {
   ADMISSION_TICK_MS,
   MAX_ADMITS_PER_TICK,
+  getSessionGraceMs,
   getSessionLengthMs,
   isWaitingRoomEnabled,
 } from './config'
@@ -23,7 +24,7 @@ let state: AdmissionState | null = null
 const SNAPSHOT_EVERY_N_TICKS = 10
 
 export interface AdmissionDeps {
-  sweepExpired: (now: Date) => Promise<number>
+  sweepExpired: (now: Date, graceMs: number) => Promise<number>
   countActive: (now: Date) => Promise<number>
   queueDepth: () => Promise<number>
   admitFromQueue: (params: {
@@ -34,6 +35,7 @@ export interface AdmissionDeps {
   isFireworksAdmissible: () => boolean
   getMaxAdmitsPerTick: () => number
   getSessionLengthMs: () => number
+  getSessionGraceMs: () => number
   now?: () => Date
 }
 
@@ -45,6 +47,7 @@ const defaultDeps: AdmissionDeps = {
   isFireworksAdmissible,
   getMaxAdmitsPerTick: () => MAX_ADMITS_PER_TICK,
   getSessionLengthMs,
+  getSessionGraceMs,
 }
 
 export interface AdmissionTickResult {
@@ -73,7 +76,7 @@ export async function runAdmissionTick(
   deps: AdmissionDeps = defaultDeps,
 ): Promise<AdmissionTickResult> {
   const now = (deps.now ?? (() => new Date()))()
-  const expired = await deps.sweepExpired(now)
+  const expired = await deps.sweepExpired(now, deps.getSessionGraceMs())
 
   if (!deps.isFireworksAdmissible()) {
     const [active, depth] = await Promise.all([

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

@@ -24,3 +24,11 @@ export function isWaitingRoomEnabled(): boolean {
 export function getSessionLengthMs(): number {
   return env.FREEBUFF_SESSION_LENGTH_MS
 }
+
+/** Drain window after a session's `expires_at`. During this window the gate
+ *  still admits requests so an in-flight agent run can finish, but the CLI is
+ *  expected to stop accepting new user prompts. Hard cutoff at
+ *  `expires_at + grace`; past that the gate returns `session_expired`. */
+export function getSessionGraceMs(): number {
+  return env.FREEBUFF_SESSION_GRACE_MS
+}