@alumbwe/anvil 1.0.0 → 1.0.2

package/src/hooks/use-freebuff-session.ts

@@ -1,806 +0,0 @@
-import { isDirectDeepSeekMode } from '@anvil/common/constants/deepseek-direct'
-import {
-  FALLBACK_FREEBUFF_MODEL_ID,
-  getFreebuffModel,
-  isFreebuffLimitedOfferModelId,
-  LIMITED_FREEBUFF_MODEL_ID,
-  resolveFreebuffModelForAccessTier,
-} from '@anvil/common/constants/freebuff-models'
-import {
-  getLimitedModelOffers,
-  getRateLimitsByModel,
-  getReferralInfo,
-} from '@anvil/common/types/freebuff-session'
-import { useEffect } from 'react'
-
-import {
-  getSelectedFreebuffModel,
-  useFreebuffModelStore,
-} from '../state/freebuff-model-store'
-import { useChatStore } from '../state/chat-store'
-import { useFreebuffSessionStore } from '../state/freebuff-session-store'
-import { getAuthTokenDetails } from '../utils/auth'
-import { stopActiveRun } from '../utils/active-run'
-import { IS_FREEBUFF } from '../utils/constants'
-import {
-  isFreebuffInstanceOwnedByDeadLocalProcess,
-  recordFreebuffInstanceOwner,
-} from '../utils/freebuff-instance-owner'
-import { logger } from '../utils/logger'
-import { getSystemMessage } from '../utils/message-history'
-import {
-  clearReferralCache,
-  getCachedReferral,
-  rememberReferral,
-} from '../utils/freebuff-referral-cache'
-import {
-  callFreebuffSession,
-  classifyFreebuffSessionRequestFailure,
-  FreebuffSessionRequestError,
-  holdsLiveFreebuffSlot,
-  isFreebuffSessionTimeoutError,
-  mergeCompactActiveSession,
-  releaseFreebuffSlot,
-} from '../utils/freebuff-session-api'
-import {
-  failedPollDelayMs,
-  jitterPollIntervalMs,
-} from '../utils/polling-backoff'
-import { saveFreebuffModelPreference } from '../utils/settings'
-
-import type { FreebuffSessionResponse } from '../types/freebuff-session'
-import type {
-  FreebuffCountryBlockReason,
-  FreebuffIpPrivacySignal,
-} from '@anvil/common/types/freebuff-session'
-
-const POLL_INTERVAL_ACTIVE_MS = 30_000
-
-/** Play the terminal bell so users get an audible notification on admission. */
-const playAdmissionSound = () => {
-  try {
-    process.stdout.write('\x07')
-  } catch {
-    // Silent fallback — some terminals/pipes disallow writing to stdout.
-  }
-}
-
-/** Picks the poll delay after a successful tick. Returns null when the state
- *  is terminal (no further polling). */
-function nextDelayMs(next: FreebuffSessionResponse): number | null {
-  const activeCadenceMs = jitterPollIntervalMs({
-    intervalMs: POLL_INTERVAL_ACTIVE_MS,
-  })
-  switch (next.status) {
-    case 'active':
-      // Poll at the normal cadence, but ensure we land just after
-      // `expires_at` so the transition shows up promptly instead of leaving
-      // the countdown stuck at 0 for up to a full interval.
-      return Math.max(
-        1_000,
-        Math.min(activeCadenceMs, next.remainingMs + 1_000),
-      )
-    case 'ended':
-      // Inside the grace window we keep checking so the post-grace transition
-      // (server returns `none`, we synthesize ended-no-instanceId) is prompt.
-      return next.instanceId ? activeCadenceMs : null
-    case 'none':
-    case 'superseded':
-    case 'takeover_prompt':
-    case 'country_blocked':
-    case 'banned':
-    case 'model_locked':
-    case 'rate_limited':
-    case 'spend_limited':
-    case 'ip_capped':
-    case 'model_unavailable':
-    case 'premium_slot_taken':
-      return null
-  }
-}
-
-// --- Poll-loop control surface ---------------------------------------------
-//
-// The hook below registers a controller object here on mount; module-level
-// imperative functions (restart / mark superseded / mark ended / etc.) talk
-// to it without going through React. Non-React callers (chat-completions
-// gate, exit paths) hit those functions directly.
-
-/** How the next tick should behave after a forced restart.
- *   - 'rejoin'  → POST: claim/rotate a seat (used after explicit end-and-rejoin
- *                 or when the chat gate kicks us back to the queue).
- *   - 'landing' → GET: drop to the model-picker (status 'none') so the user
- *                 reconfirms a model before rejoining. */
-type RestartMode = 'rejoin' | 'landing'
-
-interface PollController {
-  /** Cancel the in-flight tick + timer and start a fresh one in `mode`. */
-  restart: (mode: RestartMode) => Promise<void>
-  apply: (next: FreebuffSessionResponse) => void
-  abort: () => void
-}
-
-let controller: PollController | null = null
-
-/**
- * The model of the most recent EXPLICIT user pick (startFreebuffSession),
- * consumed by the first server response that follows it. Lets the
- * `model_locked` branch tell a deliberate pick apart from a background
- * rejoin/race: only the former deserves a visible explanation. Cleared on
- * every response so a stale pick can never annotate a later, unrelated lock.
- */
-let pendingExplicitPickModel: string | null = null
-
-/** Read the current instance id for outgoing chat requests. Defined via
- *  `holdsLiveFreebuffSlot` so the two can't drift: an id exists exactly while
- *  we hold a live slot (active, or `ended` inside the server-side grace
- *  window where the row stays alive until `expires_at + grace`). */
-export function getFreebuffInstanceId(): string | undefined {
-  // Direct-to-DeepSeek mode has no server-side session; hand back a stable
-  // local id so the chat gate (which requires a live slot) lets messages
-  // through instead of holding them for a rejoin that can never happen.
-  if (isDirectDeepSeekMode()) return 'local-deepseek'
-  const current = useFreebuffSessionStore.getState().session
-  if (!current || !holdsLiveFreebuffSlot(current)) return undefined
-  return 'instanceId' in current ? current.instanceId : undefined
-}
-
-/** True when the session represents a server-side slot the caller is
- *  holding (active, or in the post-expiry grace window with a live
- *  instance id). Chat requests are only admissible in these states — once
- *  the slot is gone, `getFreebuffInstanceId` returns undefined and the
- *  server rejects the request — so the message queue gates on this before
- *  firing queued work. Same predicate gates DELETE on exit: outside these
- *  states there is no server row to release. */
-function toLandingSession(
-  current: FreebuffSessionResponse | null,
-): Extract<FreebuffSessionResponse, { status: 'none' }> {
-  const accessTier =
-    current && 'accessTier' in current ? current.accessTier : undefined
-  const rateLimitsByModel = getRateLimitsByModel(current)
-  const referral = accessTier
-    ? (getReferralInfo(current) ?? getCachedReferral(accessTier))
-    : undefined
-  const countryCode =
-    current && 'countryCode' in current ? current.countryCode : undefined
-  const countryBlockReason =
-    current && 'countryBlockReason' in current
-      ? current.countryBlockReason
-      : undefined
-  const ipPrivacySignals =
-    current && 'ipPrivacySignals' in current
-      ? current.ipPrivacySignals
-      : undefined
-  // Carried over so the picker doesn't lose the limited-offer row for the one
-  // frame between synthesizing this state and the GET that refreshes it. The
-  // GET is authoritative: if the wave has since been spent, the next response
-  // simply omits the offer and the row disappears.
-  const limitedModelOffers = getLimitedModelOffers(current)
-
-  return {
-    status: 'none',
-    ...(accessTier ? { accessTier } : {}),
-    ...(rateLimitsByModel ? { rateLimitsByModel } : {}),
-    ...(referral ? { referral } : {}),
-    ...(limitedModelOffers.length > 0 ? { limitedModelOffers } : {}),
-    ...(countryCode ? { countryCode } : {}),
-    ...(countryBlockReason ? { countryBlockReason } : {}),
-    ...(ipPrivacySignals ? { ipPrivacySignals } : {}),
-  }
-}
-
-interface RestartOpts {
-  resetChat?: boolean
-  /** DELETE the held slot before restarting so the next POST starts clean. */
-  releaseSlot?: boolean
-}
-
-async function restartFreebuffSession(
-  mode: RestartMode,
-  opts: RestartOpts = {},
-): Promise<void> {
-  if (!IS_FREEBUFF) return
-  // A reset changes chat ownership. Stop and checkpoint the old run before
-  // resetting its store so late deltas cannot land in the next session.
-  if (opts.resetChat) {
-    stopActiveRun('session-transition')
-    useChatStore.getState().reset()
-  }
-  // Halt the running poll loop before we touch local stores or DELETE the
-  // slot. Otherwise an in-flight GET could land mid-reset and overwrite
-  // state, or the next scheduled tick could fire between DELETE and
-  // restart() with stale assumptions. restart() re-aborts and re-arms
-  // below; the extra abort here is cheap.
-  controller?.abort()
-  if (opts.releaseSlot) await releaseFreebuffSlot()
-  await controller?.restart(mode)
-}
-
-/**
- * Re-POST to the server (rejoining the queue / rotating the instance id).
- * Pass `resetChat: true` to also wipe local chat history — used when
- * rejoining after a session ended so the next admitted session starts fresh.
- */
-export function refreshFreebuffSession(
-  opts: { resetChat?: boolean } = {},
-): Promise<void> {
-  return restartFreebuffSession('rejoin', { resetChat: opts.resetChat })
-}
-
-/**
- * Drop back to the pre-join landing state (model picker) instead of auto
- * re-queuing. Used after a session ends: the user lands on the picker so
- * they consciously choose a model and hit Enter to join, rather than being
- * silently re-queued for whatever model they last used.
- */
-export function returnToFreebuffLanding(
-  opts: { resetChat?: boolean } = {},
-): Promise<void> {
-  return restartFreebuffSession('landing', {
-    resetChat: opts.resetChat,
-    releaseSlot: true,
-  })
-}
-
-/** Refresh picker-only metadata (quota and queue depths) while staying on the
- * model selection screen. Used when a midnight-Pacific session quota reset
- * passes while the landing screen is open. */
-export function refreshFreebuffLandingMetadata(): Promise<void> {
-  return restartFreebuffSession('landing')
-}
-
-/**
- * Start a session on `model` (admitted immediately server-side). Dual-purpose:
- *   - First start: called from the pre-chat landing picker. The session starts
- *     at `none` (GET-only); this is the user's explicit commitment to enter.
- *   - Switch: called when the user picks a different model from the landing
- *     screen. The server admits them on the new model right away.
- *
- * If the server has already admitted them on a different model, it responds
- * with `model_locked`; because this is a deliberate pick, the tick loop ends
- * that session and re-claims on the requested model (see the model_locked
- * branch). Background rejoins hitting the same lock revert silently instead.
- */
-export function startFreebuffSession(model: string): Promise<void> {
-  if (!IS_FREEBUFF) return Promise.resolve()
-  // This is the only explicit user-pick path (called from the picker on
-  // click / Enter), so persistence belongs here — and ONLY here. Server-
-  // driven flips (`model_locked`, `model_unavailable`, takeover) go
-  // through `setSelectedModel` directly, which never writes to disk.
-  const current = useFreebuffSessionStore.getState().session
-  const accessTier =
-    current && 'accessTier' in current ? current.accessTier : 'full'
-  const resolved = resolveFreebuffModelForAccessTier(model, accessTier)
-  // Remember that the next POST is a deliberate pick, so a `model_locked`
-  // rejection explains itself in chat instead of reverting silently.
-  pendingExplicitPickModel = resolved
-  useFreebuffModelStore.getState().setSelectedModel(resolved)
-  saveFreebuffModelPreference(resolved)
-  return restartFreebuffSession('rejoin')
-}
-
-let takeoverInFlight: Promise<void> | null = null
-
-export function takeOverFreebuffSession(): Promise<void> {
-  if (!IS_FREEBUFF) return Promise.resolve()
-  if (takeoverInFlight) return takeoverInFlight
-
-  const { session } = useFreebuffSessionStore.getState()
-  if (session?.status !== 'takeover_prompt') {
-    return Promise.resolve()
-  }
-
-  useFreebuffModelStore.getState().setSelectedModel(session.model)
-  takeoverInFlight = restartFreebuffSession('rejoin').finally(() => {
-    takeoverInFlight = null
-  })
-  return takeoverInFlight
-}
-
-export function markFreebuffSessionSuperseded(): void {
-  if (!IS_FREEBUFF) return
-  controller?.abort()
-  controller?.apply({ status: 'superseded' })
-}
-
-/** Flip into the terminal `country_blocked` state from outside the poll loop.
- *  Used when the chat-completions gate rejects on country even though the
- *  session-level country check did not catch the request first.
- *  Transitioning the session state here unmounts the Chat surface in favor of
- *  the landing screen's country_blocked message, so the user can't keep typing
- *  and sending doomed requests. */
-export function markFreebuffSessionCountryBlocked(params: {
-  countryCode: string
-  countryBlockReason?: FreebuffCountryBlockReason
-  ipPrivacySignals?: FreebuffIpPrivacySignal[]
-}): void {
-  if (!IS_FREEBUFF) return
-  controller?.abort()
-  controller?.apply({ status: 'country_blocked', ...params })
-  // Best-effort DELETE so we don't hold a session row the server is already
-  // refusing to serve at chat time.
-  releaseFreebuffSlot().catch(() => {})
-}
-
-/** Flip into the local `ended` state without an instanceId (server has lost
- *  our row). The chat surface stays mounted with the rejoin banner.
- *  Preserves any `rateLimitsByModel` snapshot from the prior session so the
- *  banner can show today's session count without an extra fetch. */
-export function markFreebuffSessionEnded(): void {
-  if (!IS_FREEBUFF) return
-  controller?.abort()
-  const current = useFreebuffSessionStore.getState().session
-  const rateLimitsByModel = getRateLimitsByModel(current)
-  controller?.apply({
-    status: 'ended',
-    accessTier:
-      current && 'accessTier' in current ? current.accessTier : undefined,
-    rateLimitsByModel,
-  })
-}
-
-interface UseFreebuffSessionResult {
-  session: FreebuffSessionResponse | null
-  failure: ReturnType<typeof useFreebuffSessionStore.getState>['failure']
-}
-
-/**
- * Manages the freebuff session lifecycle:
- *   - GET on mount to probe state (no auto-join; the user picks a model in
- *     the landing screen, which calls startFreebuffSession)
- *   - if the probe sees an existing seat, auto-takes-over when the prior
- *     local owner process is gone; otherwise asks before POSTing to rotate
- *     the instance id so any other CLI on the same account is superseded
- *   - polls GET while active to keep state fresh
- *   - re-POSTs on explicit refresh (chat gate rejected us, user switched
- *     models, user rejoined after ending)
- *   - DELETE on unmount so the slot frees up for the next user
- *   - plays a bell on admission to an active session
- */
-export function useFreebuffSession(): UseFreebuffSessionResult {
-  const session = useFreebuffSessionStore((s) => s.session)
-  const failure = useFreebuffSessionStore((s) => s.failure)
-
-  useEffect(() => {
-    const { setSession, setFailure } = useFreebuffSessionStore.getState()
-
-    if (!IS_FREEBUFF) {
-      // Non-freebuff (Anvil) builds never gate on a free session; leave the
-      // store empty (app.tsx's session routing is all behind IS_FREEBUFF).
-      setSession(null)
-      return
-    }
-
-    if (isDirectDeepSeekMode()) {
-      // No server-side session to poll in direct-to-DeepSeek mode. Set a
-      // synthetic active session so the chat surface mounts normally and
-      // getFreebuffInstanceId() satisfies the message-send gate.
-      setSession({
-        status: 'active',
-        accessTier: 'full',
-        instanceId: 'local-deepseek',
-        model: getSelectedFreebuffModel() || FALLBACK_FREEBUFF_MODEL_ID,
-        admittedAt: new Date().toISOString(),
-        expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
-        remainingMs: 24 * 60 * 60 * 1000,
-      })
-      setFailure(null)
-      return
-    }
-
-    const { token } = getAuthTokenDetails()
-    if (!token) {
-      logger.warn(
-        {},
-        '[freebuff-session] No auth token; skipping free-session admission',
-      )
-      setFailure({
-        type: 'other',
-        message: 'Not authenticated',
-        retry: null,
-        outcomeUnknown: false,
-      })
-      return
-    }
-
-    let cancelled = false
-    let abortController = new AbortController()
-    let timer: ReturnType<typeof setTimeout> | null = null
-    let previousStatus: FreebuffSessionResponse['status'] | null = null
-    // A compact response for an unexpected session identity has no safe quota
-    // snapshot to retain, so force exactly one rich poll to restore it.
-    let needsFullActivePoll = false
-    let restartGeneration = 0
-    let consecutiveFailures = 0
-    // Method for the NEXT tick. GET is read-only; POST claims/rotates a seat.
-    // Startup is GET (probe before committing). After any POST completes we
-    // flip back to GET. refresh() sets it to 'POST' for explicit join/rejoin;
-    // the startup takeover branch does the same when the probe finds a seat.
-    let nextMethod: 'GET' | 'POST' = 'GET'
-
-    const apply = (next: FreebuffSessionResponse) => {
-      rememberReferral(next)
-      if (next.status === 'active') {
-        useFreebuffModelStore.getState().setSelectedModel(next.model)
-        recordFreebuffInstanceOwner(next.instanceId)
-      } else if (next.status === 'none' && next.accessTier === 'limited') {
-        useFreebuffModelStore
-          .getState()
-          .setSelectedModel(LIMITED_FREEBUFF_MODEL_ID)
-      }
-      setSession(next)
-      setFailure(null)
-      previousStatus = next.status
-    }
-
-    const clearTimer = () => {
-      if (timer) {
-        clearTimeout(timer)
-        timer = null
-      }
-    }
-
-    const schedule = (ms: number) => {
-      if (cancelled) return
-      clearTimer()
-      timer = setTimeout(tick, ms)
-    }
-
-    const tick = async () => {
-      if (cancelled) return
-      const method = nextMethod
-      const instanceId = getFreebuffInstanceId()
-      const model = getSelectedFreebuffModel()
-      const compact =
-        method === 'GET' && previousStatus === 'active' && !needsFullActivePoll
-      const fetchController = abortController
-      const generation = restartGeneration
-      try {
-        const next = await callFreebuffSession(method, token, {
-          signal: fetchController.signal,
-          instanceId,
-          model,
-          compact,
-        })
-        if (
-          cancelled ||
-          fetchController.signal.aborted ||
-          generation !== restartGeneration
-        ) {
-          return
-        }
-        consecutiveFailures = 0
-        // After any successful call, default back to GET polling. The
-        // takeover and model_locked branches below override this when they
-        // need another POST.
-        nextMethod = 'GET'
-
-        // Consume the explicit-pick marker: it annotates exactly the first
-        // response after a user pick, whatever that response turns out to be.
-        const explicitPickModel = pendingExplicitPickModel
-        pendingExplicitPickModel = null
-
-        // The session is model-locked server-side: an active session on
-        // another model rejects the switch. Two cases:
-        //   - DELIBERATE pick (the explicit-pick marker was set): honor the
-        //     click — end the locked session (usually a stale row from a
-        //     crashed CLI; DELETE is keyed on user, not instance) and
-        //     re-claim on the requested model. The marker is consume-once,
-        //     so if the retried POST races another instance back into
-        //     model_locked we take the revert branch instead of looping.
-        //   - Background rejoin racing an admission: revert the local
-        //     selection so the active session stays intact. Reverting a
-        //     deliberate pick silently made "I clicked GLM 5.2 and it
-        //     switched to DeepSeek V4 Flash" a recurring bug report
-        //     (2026-07-30): sessions live 1h even when idle, so users
-        //     constantly pick a model while a row is still active.
-        if (next.status === 'model_locked') {
-          if (explicitPickModel && explicitPickModel !== next.currentModel) {
-            const current = getFreebuffModel(next.currentModel).displayName
-            const requested = getFreebuffModel(explicitPickModel).displayName
-            let released = false
-            try {
-              await callFreebuffSession('DELETE', token, {
-                signal: fetchController.signal,
-              })
-              released = true
-            } catch {
-              // DELETE failed — fall through to the revert-with-explanation
-              // path below rather than stranding the user mid-switch.
-            }
-            if (
-              cancelled ||
-              fetchController.signal.aborted ||
-              generation !== restartGeneration
-            ) {
-              return
-            }
-            if (released) {
-              useChatStore
-                .getState()
-                .setMessages((prev) => [
-                  ...prev,
-                  getSystemMessage(
-                    `Ended your previous session on ${current} and switched to ${requested}.`,
-                  ),
-                ])
-              nextMethod = 'POST'
-              schedule(0)
-              return
-            }
-            useChatStore
-              .getState()
-              .setMessages((prev) => [
-                ...prev,
-                getSystemMessage(
-                  `You're already in an active session on ${current}, and ending it failed, so the switch to ${requested} was not applied. Run /end-session, then pick ${requested}. (Sessions end on their own after 1 hour.)`,
-                ),
-              ])
-          }
-          useFreebuffModelStore.getState().setSelectedModel(next.currentModel)
-          schedule(0)
-          return
-        }
-        if (next.status === 'model_unavailable') {
-          // Server says the requested model isn't available right now. Flip
-          // to the always-available fallback for this run. In-memory only —
-          // `setSelectedModel` doesn't persist, so the user's saved preference
-          // is preserved for their next launch.
-          //
-          // A limited-offer model gets a sentence about it. Silence is fine for
-          // deployment hours (the picker row says when they open), but here the
-          // user pressed Enter on a row that was on screen a second ago and
-          // would otherwise land on a different model with no explanation —
-          // they lost a race for the wave's last slot.
-          if (isFreebuffLimitedOfferModelId(next.requestedModel)) {
-            const requested = getFreebuffModel(next.requestedModel).displayName
-            const fallback = getFreebuffModel(
-              FALLBACK_FREEBUFF_MODEL_ID,
-            ).displayName
-            useChatStore
-              .getState()
-              .setMessages((prev) => [
-                ...prev,
-                getSystemMessage(
-                  `${requested}'s trial sessions just ran out, so this session started on ${fallback} instead. Check back later — we release more in batches.`,
-                ),
-              ])
-          }
-          useFreebuffModelStore
-            .getState()
-            .setSelectedModel(FALLBACK_FREEBUFF_MODEL_ID)
-          // The unavailable response came from a POST attempt. Re-POST with
-          // the fallback model; a GET would only redisplay the old ended row
-          // and leave the restart banner stuck in its pending state.
-          nextMethod = 'POST'
-          schedule(0)
-          return
-        }
-
-        // Startup takeover: the initial probe GET saw we already hold a seat
-        // (from a prior CLI instance). Stop here and ask before POSTing to
-        // rotate our instance id; otherwise opening a second freebuff would
-        // immediately supersede the first one.
-        // `previousStatus === null` fences this to the very first tick only.
-        // Pin the selected model to whatever the server thinks we're on so
-        // an explicit takeover preserves our queue position instead of
-        // switching queues.
-        if (
-          method === 'GET' &&
-          previousStatus === null &&
-          next.status === 'active'
-        ) {
-          useFreebuffModelStore.getState().setSelectedModel(next.model)
-          // A fast restart after Ctrl+C can observe the old server row before
-          // best-effort DELETE lands. If the row belongs to a dead local
-          // process, silently do the same POST as the Take over button.
-          if (isFreebuffInstanceOwnedByDeadLocalProcess(next.instanceId)) {
-            nextMethod = 'POST'
-            schedule(0)
-            return
-          }
-          apply({ status: 'takeover_prompt', model: next.model })
-          return
-        }
-
-        // Bell on admission: the user committed to a model on the landing
-        // screen (status 'none'), which POSTs and lands them straight on an
-        // active session (admission is immediate).
-        if (previousStatus === 'none' && next.status === 'active') {
-          playAdmissionSound()
-        }
-
-        // active|ended → none means we've passed the server's hard cutoff.
-        // Synthesize a no-instanceId ended state so the chat surface stays
-        // mounted with the Enter-to-rejoin banner instead of looping back
-        // through the landing screen. Carry forward whichever rate-limit
-        // snapshot we have — preferring the fresh `none` snapshot, falling
-        // back to whatever was on the prior active/ended row — so the
-        // banner's "N of M used today" line stays populated.
-        if (
-          (previousStatus === 'active' || previousStatus === 'ended') &&
-          next.status === 'none'
-        ) {
-          const current = useFreebuffSessionStore.getState().session
-          const rateLimitsByModel =
-            next.rateLimitsByModel ?? getRateLimitsByModel(current)
-          apply({
-            status: 'ended',
-            accessTier:
-              next.accessTier ??
-              (current && 'accessTier' in current
-                ? current.accessTier
-                : undefined),
-            rateLimitsByModel,
-          })
-          return
-        }
-
-        if (compact && next.status === 'active') {
-          const merged = mergeCompactActiveSession(
-            useFreebuffSessionStore.getState().session,
-            next,
-          )
-          needsFullActivePoll = merged === null
-          apply(merged ?? next)
-        } else {
-          needsFullActivePoll = false
-          apply(next)
-        }
-        if (needsFullActivePoll) {
-          schedule(0)
-          return
-        }
-        const delay = nextDelayMs(next)
-        if (delay !== null) schedule(delay)
-      } catch (err) {
-        if (
-          cancelled ||
-          fetchController.signal.aborted ||
-          generation !== restartGeneration
-        ) {
-          return
-        }
-        const msg = err instanceof Error ? err.message : String(err)
-        consecutiveFailures++
-        const disposition = classifyFreebuffSessionRequestFailure(method, err)
-        const shouldRetry = disposition === 'retry'
-        const retryAfterMs =
-          err instanceof FreebuffSessionRequestError
-            ? err.retryAfterMs
-            : undefined
-        const delayMs = shouldRetry
-          ? failedPollDelayMs({
-              consecutiveFailures,
-              retryAfterMs,
-            })
-          : null
-        logger.warn(
-          { error: msg, method, consecutiveFailures, delayMs, shouldRetry },
-          shouldRetry
-            ? '[freebuff-session] fetch failed; backing off'
-            : '[freebuff-session] fetch failed; automatic retry stopped',
-        )
-        const retry =
-          delayMs === null
-            ? null
-            : {
-                attempt: consecutiveFailures + 1,
-                retryAtMs: Date.now() + delayMs,
-              }
-        const failure = {
-          message: msg,
-          retry,
-          outcomeUnknown: disposition === 'unknown',
-        }
-        if (err instanceof FreebuffSessionRequestError) {
-          setFailure({
-            ...failure,
-            type: 'http',
-            statusCode: err.statusCode,
-          })
-        } else if (isFreebuffSessionTimeoutError(err)) {
-          setFailure({ ...failure, type: 'timeout' })
-        } else {
-          setFailure({ ...failure, type: 'other' })
-        }
-        if (delayMs !== null) schedule(delayMs)
-      }
-    }
-
-    controller = {
-      restart: async (mode) => {
-        const generation = ++restartGeneration
-        clearTimer()
-        // Abort any in-flight fetch so it can't race us and overwrite state.
-        abortController.abort()
-        abortController = new AbortController()
-        // Reset previousStatus so the admission bell still fires after
-        // a forced restart, and so the active|ended → none synthesis below
-        // doesn't bounce a 'landing' restart straight back to 'ended'.
-        previousStatus = null
-        needsFullActivePoll = false
-        consecutiveFailures = 0
-        setFailure(null)
-        if (mode === 'landing') {
-          nextMethod = 'GET'
-          // Land on the picker immediately. We can't go through the normal
-          // tick/apply path because a server-side row that hasn't been
-          // swept yet would trip the startup-takeover branch into an
-          // auto-POST — the exact silent-rejoin this mode exists to
-          // prevent. But the picker still needs live quota snapshots, so kick
-          // off a fire-and-forget GET and extract only picker metadata from
-          // the response, ignoring whatever status it claims. Polling resumes
-          // when the user commits to a model via startFreebuffSession.
-          const landingSession = toLandingSession(
-            useFreebuffSessionStore.getState().session,
-          )
-          apply(landingSession)
-          const fetchController = abortController
-          callFreebuffSession('GET', token, {
-            signal: fetchController.signal,
-          })
-            .then((response) => {
-              if (
-                cancelled ||
-                fetchController.signal.aborted ||
-                generation !== restartGeneration
-              ) {
-                return
-              }
-              if (response.status === 'none') {
-                // Preserve cached quota/location fields only when the tier is
-                // unchanged (or an older response omitted it). Fresh response
-                // fields win through the following object spread.
-                const canReuseLandingMetadata =
-                  response.accessTier === undefined ||
-                  response.accessTier === landingSession.accessTier
-                apply({
-                  ...(canReuseLandingMetadata ? landingSession : {}),
-                  ...response,
-                  status: 'none',
-                  accessTier: response.accessTier ?? landingSession.accessTier,
-                  // A clean `none` response is authoritative for referral
-                  // state. Do not retain the cached landing value when the
-                  // server omits it (program disabled / identity removed).
-                  referral: response.referral,
-                })
-              }
-            })
-            .catch(() => {
-              // Silent — blank hints are acceptable if the fetch fails.
-            })
-          return
-        }
-        nextMethod = 'POST'
-        await tick()
-      },
-      apply,
-      abort: () => {
-        clearTimer()
-        abortController.abort()
-      },
-    }
-
-    tick()
-
-    return () => {
-      cancelled = true
-      abortController.abort()
-      clearTimer()
-      const current = useFreebuffSessionStore.getState().session
-      controller = null
-      clearReferralCache()
-
-      // Fire-and-forget DELETE. Only release if we actually held a slot so
-      // we don't generate spurious DELETEs (e.g. HMR before POST completes).
-      if (holdsLiveFreebuffSlot(current)) {
-        callFreebuffSession('DELETE', token).catch(() => {})
-      }
-      setSession(null)
-      setFailure(null)
-    }
-  }, [])
-
-  return { session, failure }
-}