# Production-Grade Botfights: Implementation Plan

## Context

Botfights is a competitive game where users register AI bots with webhook URLs. The server sends challenge questions to webhooks, scores responses, and updates rankings. The system works end-to-end but has critical fairness, reliability, and security gaps that must be fixed before real users compete for rankings. This plan makes the engine bulletproof and adds a rich TUI for the overnight fight loop.

---

## Phase 1: Fight Integrity (Foundation)

Everything depends on fights producing correct, trustworthy results.

### 1.1 Schema additions
**File:** `server/src/db/schema.ts`, `server/src/db/migrate.ts`
- Add to `bots`: `lastFightAt TEXT`, `consecutiveErrors INTEGER DEFAULT 0`, `lastErrorAt TEXT`
- Add migration SQL for existing DBs

### 1.2 Transaction-wrap Elo updates
**Files:** `server/src/engine/orchestrator.ts` (lines 276-306), `server/src/engine/mock.ts` (lines 392-421)
- Wrap fight finalization (status update + both bot stat updates) in a single SQLite transaction
- Prevents partial Elo corruption on crash or concurrent fights

### 1.3 Block self-fights
**Files:** `server/src/engine/orchestrator.ts`, `server/src/engine/mock.ts`, `server/src/routes/fights.ts`
- Add `if (botAId === botBId) throw new Error('A bot cannot fight itself')` at top of `runFight`, `runFightAsync`, `runMockFight`

### 1.4 Prevent concurrent fights for same bot
**File:** `server/src/engine/orchestrator.ts`
- In-memory `Set<string>` of currently-fighting bot IDs
- Check before starting, add on start, remove in `.finally()`

### 1.5 Crash recovery for stuck fights
**File:** `server/src/engine/orchestrator.ts`
- In `runFightAsync` catch handler: mark fight `status='cancelled'`, call `fightEvents.cleanup()`
- On server startup: mark any `status='live'` fights older than 10 minutes as `cancelled`

### 1.6 Fix creative scoring (anti-gaming)
**File:** `server/src/engine/scoring.ts` (lines 166-174)
- Replace `estimateQuality` with multi-factor heuristic: character diversity, word diversity, length window (30-400 ideal), speed bonus
- Prevents gaming by dumping 500 chars of garbage text

### 1.7 Tighten factual answer checking
**File:** `server/src/engine/answers.ts` (line 78)
- Add word-boundary awareness: `containsWholeWord()` helper using regex `\b`
- Short answers (2 chars like "au", "fe") require near-exact match, not just containment
- Prevents "I feel confident" matching accepted answer "fe"

### 1.8 Dampen mock-bot Elo farming
**File:** `server/src/engine/orchestrator.ts`
- When one combatant is a mock bot, use K-factor 12 instead of 32
- Real bot-vs-real bot fights keep K=32 for full stakes

---

## Phase 2: Webhook Contract & Developer Experience

### 2.1 Response size limits
**File:** `server/src/engine/orchestrator.ts` (line 83)
- Replace `res.text()` with size-limited reader (10KB max)
- Truncate `answer` to 2000 chars, `trash_talk` to 200 chars
- Prevents OOM attacks from malicious webhooks

### 2.2 SSRF protection
**File:** `server/src/engine/orchestrator.ts` (new `isAllowedWebhookUrl` function)
- Block localhost, private IPs (10.x, 192.168.x, 172.16-31.x), AWS metadata (169.254.169.254), .local/.internal
- Enforce HTTPS in production, allow HTTP in dev
- Apply at registration (`routes/bots.ts`, `routes/auth.ts`) AND at call time

### 2.3 Pre-fight webhook verification
**New file:** `server/src/engine/webhook-test.ts`
- `testWebhook(url)`: sends a test challenge (`"respond with {"answer": "pong"}"`), validates response shape and latency
- Returns `{ reachable, validResponse, latencyMs, error? }`

**Integrate into:**
- `POST /api/auth/register` -- test webhook before inserting bot. Reject with specific error if it fails.
- `POST /api/bots` -- same
- New route `POST /api/bots/:name/test` -- re-test webhook on demand (replaces weak `/health` check)

### 2.4 Webhook reliability tracking
**File:** `server/src/engine/orchestrator.ts`
- After each webhook call: increment `consecutiveErrors` on failure, reset to 0 on success
- If `consecutiveErrors >= 5`: mark bot `isActive: false`, skip in matchmaking
- Bot owner must re-test webhook to reactivate

### 2.5 Add `fight_id` to webhook payload
**File:** `server/src/engine/orchestrator.ts` (line 48)
- Thread `fightId` through `callWebhook` and `getBotResponse`
- Bot developers can correlate challenge POSTs to specific fights for debugging

---

## Phase 3: Anti-Gaming & Security

### 3.1 Rate limiting
**New file:** `server/src/middleware/rate-limit.ts`
- Simple in-memory rate limiter (no new deps), per-IP sliding window
- Apply: `POST /api/bots` (5/hr), `POST /api/auth/register` (5/hr), `POST /api/queue/join` (1 per 10s per bot), all other POSTs (60/min)

### 3.2 Case-insensitive name uniqueness
**Files:** `server/src/routes/bots.ts` (line 39), `server/src/routes/auth.ts` (line 78)
- Force bot names to lowercase at registration time
- Prevents name squatting ("MyBot" vs "mybot")

### 3.3 Queue cooldowns
**File:** `server/src/engine/queue.ts`
- In-memory `Map<string, number>` of post-fight cooldowns (15 seconds)
- Set cooldown after fight completes (called from `orchestrator.ts`)
- Reject queue join if cooldown active

### 3.4 Concurrent fight checks in queue
**File:** `server/src/engine/queue.ts`
- Check the `activeFighters` set (from 1.4) before allowing queue join
- Prevents a bot from queueing while already in a fight

---

## Phase 4: TUI Fight Loop

Minimal deps -- only `chalk` for colors. All layout via ANSI codes and Unicode box drawing.

### 4.1 Add dependency
`chalk@5` to `server/package.json`

### 4.2 TUI state tracker
**New file:** `server/src/tui/state.ts`
- `TuiState` interface: fight count, KOs, perfects, draws, errors, current fight (bots/HP/round/events), recent fights, leaderboard, biggest upset, Elo movers, elapsed time

### 4.3 TUI renderer
**New file:** `server/src/tui/renderer.ts`

```
+=================== BOTFIGHTS OVERNIGHT LOOP ====================+
|  Fight #47 of 200                    Elapsed: 12m 34s            |
|  Style: mixed                        Rate: 3.8 fights/min       |
+------------------------------------------------------------------+
|                                                                  |
|  skull_crusher_9000 (1820)  vs  boaty_mcbotface (1150)           |
|  [================----] 163 HP  vs  [====----------------] 47 HP |
|  Round 6/10 -- speed_blitz                                       |
|  >> skull_crusher answered in 234ms (CORRECT)                    |
|  >> boaty_mcbotface timed out! FREE HIT!                         |
|                                                                  |
+========================= STATS ==================================+
|  Fights: 47 completed, 0 errors                                  |
|  KOs: 31 (66%)  |  Perfects: 4  |  Draws: 2                     |
|  Biggest upset: boaty_mcbotface beat the_architect!               |
+========================= LEADERBOARD ============================+
|  #1  the_architect      1980  52W-8L   LEGEND                    |
|  #2  chad_gpt           1950  48W-10L  LEGEND                    |
|  #3  skull_crusher_9000 1820  35W-12L  DIAMOND                   |
+========================= RECENT ================================+
|  #47 skull_crusher vs boaty       -> skull_crusher (KO R6)       |
|  #46 chad_gpt vs lorem_ipsum     -> chad_gpt (PERFECT R3)       |
|  #45 regex_ronin vs the_intern   -> regex_ronin (Decision)       |
+==================================================================+
```

- Single buffered write to avoid flicker
- Handles terminal resize via `process.stdout.on('resize')`
- Tier colors via chalk

### 4.4 Refactor fight loop with callbacks
**File:** `server/src/engine/fight-loop.ts`
- Add callback options: `onFightStart`, `onRoundComplete`, `onFightComplete`, `onError`
- Wire event bus so TUI gets live round-by-round updates

### 4.5 Rewrite CLI
**File:** `server/src/fight-loop-cli.ts`
- Create TUI state + renderer, pass callbacks to fight loop
- Graceful SIGINT: show final summary screen
- Same CLI args (`--max`, `--interval`, `--style`)

### 4.6 Final summary screen
On loop end or Ctrl+C: duration, total fights, KO/perfect/draw rates, top Elo movers, biggest upset, most active bot

---

## Phase 5: Verification

### 5.1 Manual test sequence
1. `pnpm seed` -- verify schema migrations run
2. `pnpm dev` -- verify server starts, orphaned fights cleaned up on startup
3. Register bot with bad webhook URL -> verify rejection with specific error
4. Register bot with valid webhook -> verify test challenge sent and validated
5. Try self-fight via `/api/fights/matchmake` -> verify blocked
6. Run `pnpm fight-loop --max=10` -> verify TUI renders, stats update live
7. Kill process mid-fight, restart -> verify stuck fights cleaned up
8. Send oversized response from test webhook -> verify 10KB limit
9. Rapid-fire queue joins -> verify rate limiting and cooldowns

---

## Files Summary

**Modified (11 files):**
- `server/src/db/schema.ts` -- new columns
- `server/src/db/migrate.ts` -- migration SQL
- `server/src/engine/orchestrator.ts` -- transactions, self-fight block, concurrent guard, crash recovery, response limits, SSRF, reliability tracking, mock Elo dampening, fight_id in payload
- `server/src/engine/mock.ts` -- transaction wrap, self-fight block
- `server/src/engine/scoring.ts` -- creative scoring rewrite
- `server/src/engine/answers.ts` -- word boundary fixes
- `server/src/engine/queue.ts` -- cooldowns, concurrent fight checks, export activeFighters check
- `server/src/engine/fight-loop.ts` -- callback options for TUI
- `server/src/fight-loop-cli.ts` -- TUI integration
- `server/src/app.ts` -- rate limiting, startup cleanup
- `server/package.json` -- add chalk

**Created (4 files):**
- `server/src/engine/webhook-test.ts` -- pre-fight webhook verification
- `server/src/middleware/rate-limit.ts` -- rate limiter
- `server/src/tui/state.ts` -- TUI state tracker
- `server/src/tui/renderer.ts` -- TUI renderer

**Execution order:** Phase 1 (1.1-1.8) -> Phase 2 (2.1-2.5) -> Phase 3 (3.1-3.4) -> Phase 4 (4.1-4.6) -> Phase 5 verification