feat: free debate discovery and budget-limit copy (#70)

* feat: surface free debate on arrival and honest budget-wall copy

* fix: address review - key status check, abort cleanup, honest mid-debate budget copy

* style: format welcome hero effect

Author: aiedwardyi

src/__tests__/api-key-errors.test.ts

@@ -1,30 +1,50 @@
 import { describe, expect, it } from "vitest"
 import {
   getApiKeyPromptMessage,
+  getBudgetExceededMessage,
   getMissingApiKeyMessage,
-  parseNoKeyProvider,
-  parseNoKeyProviderFromResponse,
+  parse402Payload,
+  parse402FromResponse,
 } from "@/lib/api-key-errors"
 
 describe("api key error helpers", () => {
-  it("recognizes no_key responses with a known provider", () => {
-    expect(parseNoKeyProvider({ error: "no_key", provider: "gemini" })).toBe("gemini")
-    expect(parseNoKeyProvider({ error: "no_key", provider: "bogus" })).toBeNull()
-    expect(parseNoKeyProvider({ error: "other", provider: "gemini" })).toBeNull()
+  it("classifies no_key responses and keeps a known provider", () => {
+    expect(parse402Payload({ error: "no_key", provider: "gemini" })).toEqual({
+      kind: "no_key",
+      provider: "gemini",
+    })
+    expect(parse402Payload({ error: "no_key", provider: "bogus" })).toEqual({
+      kind: "no_key",
+      provider: null,
+    })
+    expect(parse402Payload({ error: "other", provider: "gemini" })).toBeNull()
   })
 
-  it("returns null for malformed no_key payloads", () => {
-    expect(parseNoKeyProvider(null)).toBeNull()
-    expect(parseNoKeyProvider(undefined)).toBeNull()
-    expect(parseNoKeyProvider("no_key")).toBeNull()
-    expect(parseNoKeyProvider({ error: "no_key" })).toBeNull()
-    expect(parseNoKeyProvider({ error: "no_key", provider: 123 })).toBeNull()
+  it("classifies host_budget_exceeded responses", () => {
+    expect(parse402Payload({ error: "host_budget_exceeded", provider: "claude" })).toEqual({
+      kind: "host_budget_exceeded",
+      provider: "claude",
+    })
   })
 
-  it("parses no_key provider from a response body", async () => {
+  it("returns null for malformed payloads", () => {
+    expect(parse402Payload(null)).toBeNull()
+    expect(parse402Payload(undefined)).toBeNull()
+    expect(parse402Payload("no_key")).toBeNull()
+    expect(parse402Payload({ error: "no_key" })).toEqual({ kind: "no_key", provider: null })
+    expect(parse402Payload({ error: "no_key", provider: 123 })).toEqual({
+      kind: "no_key",
+      provider: null,
+    })
+  })
+
+  it("parses a 402 body from a response", async () => {
     const response = Response.json({ error: "no_key", provider: "claude" }, { status: 402 })
 
-    await expect(parseNoKeyProviderFromResponse(response)).resolves.toBe("claude")
+    await expect(parse402FromResponse(response)).resolves.toEqual({
+      kind: "no_key",
+      provider: "claude",
+    })
   })
 
   it("returns null when response JSON parsing fails", async () => {
@@ -33,7 +53,13 @@ describe("api key error helpers", () => {
       headers: { "Content-Type": "application/json" },
     })
 
-    await expect(parseNoKeyProviderFromResponse(response)).resolves.toBeNull()
+    await expect(parse402FromResponse(response)).resolves.toBeNull()
+  })
+
+  it("keeps the free debate promise honest at the budget wall", () => {
+    expect(getBudgetExceededMessage(true)).toContain("an unused free debate stays yours")
+    expect(getBudgetExceededMessage(false)).toContain("come back tomorrow")
+    expect(getBudgetExceededMessage(true, "ko")).toContain("아직 안 쓴 무료 토론")
   })
 
   it("formats the user-facing Settings message", () => {

src/components/WelcomeHero.tsx

@@ -1,8 +1,12 @@
 "use client"
 
 import type { CSSProperties } from "react"
+import { useEffect, useState } from "react"
 import { motion } from "framer-motion"
+import { useSession } from "next-auth/react"
 import { Provider, Locale } from "@/types"
+import { authEnabled } from "@/lib/deploy-config"
+import { isFirstRunKeyless } from "@/lib/client-api-keys"
 
 const suggestions = {
   en: [
@@ -21,6 +25,17 @@ const suggestions = {
 
 const tryMeLabel = { en: "Try me", ko: "클릭해 보세요" }
 
+const freeDebateHint = {
+  en: {
+    signin: "Sign in with Google - your first debate is free",
+    ready: "Your free debate is ready - no API keys needed",
+  },
+  ko: {
+    signin: "Google로 로그인하면 첫 토론이 무료예요",
+    ready: "무료 토론이 준비돼 있어요 - API 키 없이 시작하세요",
+  },
+}
+
 const translations = {
   en: {
     title: "Quorum",
@@ -306,6 +321,45 @@ export default function WelcomeHero({
 }) {
   const t = translations[locale]
   const s = suggestions[locale]
+  const { status } = useSession()
+  const [freeHint, setFreeHint] = useState<"signin" | "ready" | null>(null)
+
+  useEffect(() => {
+    if (!authEnabled()) return
+    let cancelled = false
+    const controller = new AbortController()
+    const decide = async (): Promise<"signin" | "ready" | null> => {
+      if (status === "unauthenticated") return isFirstRunKeyless(true) ? "signin" : null
+      if (status !== "authenticated") return null
+      const [grant, keyStatus] = await Promise.all([
+        fetch("/api/free-debate", { signal: controller.signal }).then((r) =>
+          r.ok ? r.json() : null
+        ),
+        fetch("/api/user-api-keys", { signal: controller.signal }).then((r) =>
+          r.ok ? r.json() : null
+        ),
+      ])
+      if (!grant) return null
+      // Saved keys win over the grant server-side, so "free debate ready" would lie to key holders.
+      // Key status values are objects - check the configured flag, not truthiness.
+      const hasKey = Boolean(
+        keyStatus?.keys &&
+        Object.values(keyStatus.keys).some(
+          (k) => (k as { configured?: boolean } | null)?.configured
+        )
+      )
+      return grant.remaining > 0 && !grant.active && !hasKey ? "ready" : null
+    }
+    decide()
+      .then((hint) => {
+        if (!cancelled) setFreeHint(hint)
+      })
+      .catch(() => {})
+    return () => {
+      cancelled = true
+      controller.abort()
+    }
+  }, [status])
 
   return (
     <div className="flex flex-col items-center justify-center min-h-[70vh] text-center px-4 sm:px-6 py-8 sm:py-12">
@@ -347,6 +401,20 @@ export default function WelcomeHero({
           {t.description}
         </motion.p>
 
+        {/* -- Free debate hint -- */}
+        {freeHint && (
+          <motion.div
+            initial={{ opacity: 0, y: 8 }}
+            animate={{ opacity: 1, y: 0 }}
+            transition={{ delay: 0.9, duration: 0.4 }}
+          >
+            <span className="inline-flex items-center gap-2 rounded-full border border-emerald-500/30 bg-emerald-500/10 px-4 py-1.5 text-[13px] font-medium text-emerald-600 dark:text-emerald-300">
+              <span aria-hidden>✦</span>
+              {freeDebateHint[locale][freeHint]}
+            </span>
+          </motion.div>
+        )}
+
         {/* -- Model badges -- */}
         <motion.div
           initial={{ opacity: 0, scale: 0.95 }}

src/hooks/useDebateEngine.ts

@@ -8,8 +8,9 @@ import { hasDirectUrlReference, prioritizePerplexity } from "@/lib/url-access"
 import { waitForDrain } from "@/lib/drain-registry"
 import {
   getApiKeyPromptMessage,
+  getBudgetExceededMessage,
   getMissingApiKeyMessage,
-  parseNoKeyProviderFromResponse,
+  parse402FromResponse,
 } from "@/lib/api-key-errors"
 import { getClientKey, getAccessCode, isFirstRunKeyless } from "@/lib/client-api-keys"
 import { authEnabled } from "@/lib/deploy-config"
@@ -403,7 +404,15 @@ export function useDebateEngine(config: {
         }
 
         if (res.status === 402) {
-          const missingProvider = (await parseNoKeyProviderFromResponse(res)) ?? provider
+          const blocked = await parse402FromResponse(res)
+          if (blocked?.kind === "host_budget_exceeded") {
+            // Daily host budget wall, not a key problem - the key toast would mislead.
+            updatePlaceholder(getBudgetExceededMessage(!isAnonymousRef.current, locale))
+            stopRef.current = true
+            clearTypingIfCurrentSession()
+            return null
+          }
+          const missingProvider = blocked?.provider ?? provider
           onApiKeyRequired?.(missingProvider)
           // A keyless first-run visitor gets a generic welcome; the panel's
           // lead provider (perplexity) is arbitrary, so don't single it out.
@@ -549,8 +558,11 @@ export function useDebateEngine(config: {
           .then(async (res) => {
             if (sessionIdRef.current !== sessionId || stopRef.current) return
             if (res.status === 402) {
-              const missingProvider = await parseNoKeyProviderFromResponse(res)
-              if (missingProvider) onApiKeyRequired?.(missingProvider)
+              // Budget wall stays silent here - the chat calls surface it.
+              const blocked = await parse402FromResponse(res)
+              if (blocked?.kind === "no_key" && blocked.provider) {
+                onApiKeyRequired?.(blocked.provider)
+              }
               return
             }
             if (!res.ok) return
@@ -693,14 +705,21 @@ export function useDebateEngine(config: {
                   logDebate("verdict:skipped-stopped", {})
                 } else if (res.status === 402) {
                   if (sessionIdRef.current !== thisSession) return
-                  const missingProvider = await parseNoKeyProviderFromResponse(res)
-                  if (missingProvider) onApiKeyRequired?.(missingProvider)
-                  else onApiKeyRequired?.("gemini")
-                  dispatch({
-                    type: "UPDATE_MESSAGE",
-                    id: analyzingMsg.id,
-                    content: SYSTEM_MESSAGES.missingConsensusKey(locale, !isAnonymousRef.current),
-                  })
+                  const blocked = await parse402FromResponse(res)
+                  if (blocked?.kind === "host_budget_exceeded") {
+                    dispatch({
+                      type: "UPDATE_MESSAGE",
+                      id: analyzingMsg.id,
+                      content: getBudgetExceededMessage(!isAnonymousRef.current, locale),
+                    })
+                  } else {
+                    onApiKeyRequired?.(blocked?.provider ?? "gemini")
+                    dispatch({
+                      type: "UPDATE_MESSAGE",
+                      id: analyzingMsg.id,
+                      content: SYSTEM_MESSAGES.missingConsensusKey(locale, !isAnonymousRef.current),
+                    })
+                  }
                 } else if (!res.ok) {
                   const failMsg = await consensusFailureMessage(res, locale)
                   logDebate("verdict:failed", { status: res.status, message: failMsg })
@@ -822,9 +841,16 @@ export function useDebateEngine(config: {
         .then(async (res) => {
           if (res.status === 402) {
             if (sessionIdRef.current !== stoppedSession) return null
-            const missingProvider = await parseNoKeyProviderFromResponse(res)
-            if (missingProvider) onApiKeyRequired?.(missingProvider)
-            else onApiKeyRequired?.("gemini")
+            const blocked = await parse402FromResponse(res)
+            if (blocked?.kind === "host_budget_exceeded") {
+              dispatch({
+                type: "UPDATE_MESSAGE",
+                id: analyzingMsg.id,
+                content: getBudgetExceededMessage(!isAnonymousRef.current, locale),
+              })
+              return null
+            }
+            onApiKeyRequired?.(blocked?.provider ?? "gemini")
             dispatch({
               type: "UPDATE_MESSAGE",
               id: analyzingMsg.id,

src/lib/api-key-errors.ts

@@ -11,22 +11,43 @@ const PROVIDER_NAMES: Record<Provider, string> = {
 
 const PROVIDERS = new Set<Provider>(Object.keys(PROVIDER_NAMES) as Provider[])
 
-export function parseNoKeyProvider(payload: unknown): Provider | null {
+export type Blocked402 = {
+  kind: "no_key" | "host_budget_exceeded"
+  provider: Provider | null
+}
+
+export function parse402Payload(payload: unknown): Blocked402 | null {
   if (!payload || typeof payload !== "object") return null
   const obj = payload as Record<string, unknown>
-  if (obj.error !== "no_key") return null
-  if (typeof obj.provider !== "string") return null
-  return PROVIDERS.has(obj.provider as Provider) ? (obj.provider as Provider) : null
+  if (obj.error !== "no_key" && obj.error !== "host_budget_exceeded") return null
+  const provider =
+    typeof obj.provider === "string" && PROVIDERS.has(obj.provider as Provider)
+      ? (obj.provider as Provider)
+      : null
+  return { kind: obj.error, provider }
 }
 
-export async function parseNoKeyProviderFromResponse(response: Response): Promise<Provider | null> {
+export async function parse402FromResponse(response: Response): Promise<Blocked402 | null> {
   try {
-    return parseNoKeyProvider(await response.json())
+    return parse402Payload(await response.json())
   } catch {
     return null
   }
 }
 
+// The budget wall blocks before an UNUSED grant is consumed, but it can also
+// hit mid-debate after the grant was already claimed - promise only the unused case.
+export function getBudgetExceededMessage(signedIn: boolean, locale: Locale = "en"): string {
+  if (signedIn) {
+    return locale === "ko"
+      ? "오늘의 무료 토론이 모두 소진됐어요. 아직 안 쓴 무료 토론은 내일 그대로 쓸 수 있어요. Settings에서 API 키를 추가하면 바로 시작할 수 있어요."
+      : "Today's free debates are maxed out - an unused free debate stays yours for tomorrow. Or add your own API key in Settings to start now."
+  }
+  return locale === "ko"
+    ? "오늘의 무료 토론이 모두 소진됐어요. 내일 다시 오거나 Settings에서 API 키를 추가해 시작하세요."
+    : "Today's free debates are maxed out - come back tomorrow, or add your own API key in Settings to start now."
+}
+
 export function getMissingApiKeyMessage(provider: Provider, locale: Locale = "en"): string {
   if (locale === "ko") {
     return `Settings에서 ${PROVIDER_NAMES[provider]} API 키를 추가해 토론을 시작하세요.`

src/lib/file-parser.ts

@@ -1,7 +1,7 @@
 /** Client-side PDF/DOCX/Excel/text extraction for AI prompts. */
 
 import type { Provider } from "@/types"
-import { parseNoKeyProviderFromResponse } from "@/lib/api-key-errors"
+import { parse402FromResponse } from "@/lib/api-key-errors"
 import { getClientKey, getAccessCode } from "@/lib/client-api-keys"
 
 const MAX_FILE_CHARS = 50000
@@ -250,8 +250,10 @@ async function parsePDF(
       })
 
       if (res.status === 402) {
-        const missingProvider = await parseNoKeyProviderFromResponse(res)
-        if (missingProvider) options?.onApiKeyRequired?.(missingProvider)
+        const blocked = await parse402FromResponse(res)
+        if (blocked?.kind === "no_key" && blocked.provider) {
+          options?.onApiKeyRequired?.(blocked.provider)
+        }
         throw new Error("OCR API key required")
       }
       if (!res.ok) throw new Error(`OCR API error: ${res.status}`)