Collapse freebuff session states into the wire shape

The CLI used to layer two client-only states (`superseded`, `ended`) on
top of the server's response and translate `draining` → `ended` in a
mapper. Replaces all of that with a single union the server emits
directly:

  - GET /session now reads `X-Freebuff-Instance-Id` and returns
    `{ status: 'superseded' }` when the active row's id no longer
    matches. Previously this was inferred client-side from the chat
    gate's 409.
  - The wire's `draining` is renamed to `ended` and carries the same
    grace fields. The CLI's post-grace synthetic `ended` (no
    instanceId) reuses that shape.

Also drops the zustand `driver` indirection — imperative session
controls (refresh / mark superseded / mark ended) live as module-level
functions on the hook, talking to a private controller ref. Combines
`refreshFreebuffSession` and `rejoinFreebuffSession` into one with an
optional `{ resetChat }` flag. Inlines the constant getters in
`SessionDeps`/`AdmissionDeps` so tests pass plain numbers, drops the
`limit` parameter from `admitFromQueue` (always 1), and consolidates
the three 1-Hz UI tickers into a shared `useNow` hook.

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

Author: jahooma

cli/src/chat.tsx

@@ -1473,8 +1473,8 @@ export const Chat = ({
         )}
 
         {reviewMode ? (
-          // Review takes precedence over the session-ended banner: during a
-          // draining session the agent may still be asking to run tools, and
+          // Review takes precedence over the session-ended banner: during the
+          // grace window the agent may still be asking to run tools, and
           // those approvals must be reachable for the run to finish.
           <ReviewScreen
             onSelectOption={handleReviewOptionSelect}

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

@@ -1,5 +1,6 @@
-import React, { useEffect, useState } from 'react'
+import React from 'react'
 
+import { useNow } from '../hooks/use-now'
 import { useTheme } from '../hooks/use-theme'
 import { IS_FREEBUFF } from '../utils/constants'
 
@@ -31,12 +32,7 @@ export const FreebuffSessionCountdown: React.FC<{
   const expiresAtMs =
     session?.status === 'active' ? Date.parse(session.expiresAt) : null
 
-  const [now, setNow] = useState(() => Date.now())
-  useEffect(() => {
-    if (!expiresAtMs) return
-    const id = setInterval(() => setNow(Date.now()), 1000)
-    return () => clearInterval(id)
-  }, [expiresAtMs])
+  const now = useNow(1000, expiresAtMs !== null)
 
   if (!IS_FREEBUFF || !expiresAtMs) return null
 

cli/src/components/session-ended-banner.tsx

@@ -3,7 +3,7 @@ import { useKeyboard } from '@opentui/react'
 import React, { useCallback, useState } from 'react'
 
 import { Button } from './button'
-import { rejoinFreebuffSession } from '../hooks/use-freebuff-session'
+import { refreshFreebuffSession } from '../hooks/use-freebuff-session'
 import { useTheme } from '../hooks/use-theme'
 import { BORDER_CHARS } from '../utils/ui-constants'
 
@@ -38,7 +38,7 @@ export const SessionEndedBanner: React.FC<SessionEndedBannerProps> = ({
     // Once the POST lands, the hook flips status to 'queued' and app.tsx
     // swaps us into <WaitingRoomScreen>, unmounting this banner. No need to
     // clear `rejoining` on success — the component will be gone.
-    rejoinFreebuffSession().catch(() => setRejoining(false))
+    refreshFreebuffSession({ resetChat: true }).catch(() => setRejoining(false))
   }, [canRejoin])
 
   useKeyboard(

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

@@ -1,13 +1,14 @@
 import { TextAttributes } from '@opentui/core'
 import { useKeyboard, useRenderer } from '@opentui/react'
-import React, { useCallback, useEffect, useMemo, useState } from 'react'
+import React, { useCallback, 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 { useGravityAd } from '../hooks/use-gravity-ad'
 import { useLogo } from '../hooks/use-logo'
+import { useNow } from '../hooks/use-now'
 import { useSheenAnimation } from '../hooks/use-sheen-animation'
 import { useTerminalDimensions } from '../hooks/use-terminal-dimensions'
 import { useTheme } from '../hooks/use-theme'
@@ -95,11 +96,7 @@ export const WaitingRoomScreen: React.FC<WaitingRoomScreenProps> = ({
     if (session?.status === 'queued') return Date.parse(session.queuedAt)
     return null
   }, [session])
-  const [now, setNow] = useState(() => Date.now())
-  useEffect(() => {
-    const id = setInterval(() => setNow(Date.now()), 1000)
-    return () => clearInterval(id)
-  }, [])
+  const now = useNow(1000, queuedAtMs !== null)
   const elapsedMs = queuedAtMs ? now - queuedAtMs : 0
 
   const isQueued = session?.status === 'queued'

cli/src/hooks/helpers/send-message.ts

@@ -520,6 +520,8 @@ function handleFreebuffGateError(
       updater.setError(
         "You're still in the waiting room. Please wait for admission before sending messages.",
       )
+      // Re-sync without resetting chat — this is a "we'll wait", not a
+      // "let's start fresh".
       refreshFreebuffSession().catch(() => {})
       return
     case 'session_superseded':

cli/src/hooks/use-freebuff-session-progress.ts

@@ -0,0 +1,34 @@
+import { useNow } from './use-now'
+import { IS_FREEBUFF } from '../utils/constants'
+
+import type { FreebuffSessionResponse } from '../types/freebuff-session'
+
+export interface FreebuffSessionProgress {
+  /** 0..1, fraction of the session remaining. 1 at admission, 0 at expiry. */
+  fraction: number
+  remainingMs: number
+}
+
+/**
+ * Computes a live progress value for the active freebuff session, ticking at
+ * 1Hz. Returns null outside of active state or in non-freebuff builds, so
+ * callers can short-circuit their rendering.
+ */
+export function useFreebuffSessionProgress(
+  session: FreebuffSessionResponse | null,
+): FreebuffSessionProgress | null {
+  const expiresAtMs =
+    session?.status === 'active' ? Date.parse(session.expiresAt) : null
+  const admittedAtMs =
+    session?.status === 'active' ? Date.parse(session.admittedAt) : null
+
+  const nowMs = useNow(1000, expiresAtMs !== null)
+
+  if (!IS_FREEBUFF || !expiresAtMs || !admittedAtMs) return null
+
+  const totalMs = expiresAtMs - admittedAtMs
+  if (totalMs <= 0) return null
+  const remainingMs = Math.max(0, expiresAtMs - nowMs)
+  const fraction = Math.max(0, Math.min(1, remainingMs / totalMs))
+  return { fraction, remainingMs }
+}