archy/.planning/phases/09-botfights-platform-upgrade/deferred-items.md

Deferred Items — Phase 9 Plan 01 (arena-proxy tracer)

Out-of-scope discoveries found while executing 09-01-PLAN.md. Not fixed (per Scope Boundary rule — these are pre-existing, unrelated to the files this plan touches).

1. server/src/db/migrate.ts is stale vs server/src/db/schema.ts (blocks a clean local pnpm vitest run --project server)

• Found during: Task 1/2 verification (pnpm vitest run --project server).
• Symptom: SqliteError: no such column: "sats_won" (and similar) on a freshly migrated local dev DB (server/data/botfights.db, gitignored). Causes ~14-20 pre-existing test failures in auth.test.ts, auth-audit.test.ts, auth-edge.test.ts, tournaments.test.ts — all going through the real db/index.ts singleton against a table missing columns that schema.ts declares (e.g. satsWon / sats_won in the bots table).
• Root cause: server/src/db/migrate.ts hand-writes CREATE TABLE IF NOT EXISTS DDL that has drifted out of sync with schema.ts (payments/wallet columns were added to the Drizzle schema without updating the raw migration script). drizzle-kit push also fails against the existing db for the same reason (introspection step queries a column drizzle-kit itself expects to exist).
• Verified unrelated to this plan's changes: the failing requests never touch arena-proxy.ts — ARENA_UPSTREAM_URL is unset in the test env, so arenaProxy is a pure next() no-op; the SQL error occurs deep in db.select(...) inside routes/auth.ts/routes/tournaments.ts, completely independent of the proxy mount added in app.ts. Confirmed by reproducing the identical error on the fresh migrated DB before making any arena-proxy changes were involved in that code path.
• Recommendation: A future plan should either update migrate.ts's DDL to match schema.ts column-for-column, or replace it with real drizzle-kit generated migrations (drizzle-kit generate + drizzle-kit migrate) so the two never diverge again.

2. Timing-sensitive perf tests are flaky under parallel CPU load

• Found during: same full-suite run.
• Symptom: answers.test.ts ("completes 1000 checks in under 50ms"), lifecycle.test.ts ("10,000 automated fight simulations", "throughput

  500 fights/second"), bot-auth.test.ts ("constant-time comparison... variance is minimal") intermittently fail when Vitest's parallel workers contend for CPU on this machine. Pre-existing, unrelated to arena-proxy.

• Recommendation: Not this plan's concern; note if a future hardening pass wants to raise these budgets or mark them --sequential.

---

Deferred Items — 2026-07-31 demo-day session (09-06/09-07 hotfix cycle)

Found live while verifying 09-07's blocking human checkpoints (real signer login, cross-node visibility, cloud bot from prompt). Fixed in-line where demo-blocking (shipped as botfights 1.2.2-1.2.8, see 09-07-SUMMARY.md deviations once written); these are the remainder — real but not that session's blocker. (This section was lost once already to a shared-tree overwrite mid-session — recreated and committed immediately this time; see CLAUDE.md "Concurrent agent in shared tree".)

3. FightViewer/round display can open mid-fight instead of at round 1

• Reported: live during demo verification — opening a fight ("botfights training") landed straight on round 5 instead of round 1.
• Fixed same session (botfight commit ca5b634, part of 1.2.7): FightPage.vue's backfillCompletedRounds() — loadFight() already fetched already-completed rounds via GET /api/fights/:id's rounds array, but nothing rendered them into the visible log; only live SSE round_end events ever pushed into liveLogItems. Backfill now renders a compact (non-animated) summary of already-completed rounds and sets HP/round-counter to current state on mount, before wireSSE() connects.

4. DocsPage.vue's promptUrl display link was proxy-unaware

• Same root cause as the JoinBoutPage/BotProfilePage {{ARENA_URL}} leak (item 5 below) but for a displayed URL string, not fetched content. Fixed same session (botfight commit 2512265, part of 1.2.6): promptUrl now resolves the real arena origin by parsing it out of the fetched prompt's own (correctly proxy-resolved) content, instead of window.location.origin.

5. Client-side "copy AI setup guide" flows leaked proxy-mode local addresses

• Root cause, found live during a real demo incident: a bot got a Tailscale address (http://100.69.68.39:9100) in its AI setup guide and correctly refused to act on it, suspecting prompt injection — it wasn't injection, it was real output from real code. JoinBoutPage.vue and BotProfilePage.vue fetched the static /docs/BOTFIGHTS.md file and substituted {{ARENA_URL}} client-side with window.location.origin — on a proxy-mode instance (ARENA_UPSTREAM_URL set), that's whatever address the browser happens to be on, not the real externally-reachable arena. Fixed same session (botfight commits 2512265/ffd4dfd, part of 1.2.6): both flows now fetch the server-rendered /api/docs/prompt instead, which is under /api/* and therefore correctly forwarded by arena-proxy to the real upstream arena in proxy mode.

6. Decentralization roadmap: Tor/FIPS-aware standalone-arena addressing

• User explicitly parked this for later. Today's fix (item 5) solves it for proxy-mode instances by construction — the hub always reports its own correct origin. The gap is standalone arenas (no ARENA_UPSTREAM_URL): server/src/routes/docs.ts falls back to new URL(c.req.url).origin when PUBLIC_ARENA_URL isn't set — same class of problem for an operator only reachable over Tailscale/Tor/FIPS. PUBLIC_ARENA_URL is already the correct escape hatch (explicit config, same pattern as our own ARENA_UPSTREAM_URL); wiring it to FIPS/Tor auto-discovery automatically is new scope, not a bug fix. Design deliberately later, not accidentally now.

7. Decentralization roadmap: arena-less (nostr-event-based) match state

• Also explicitly deferred. Today's implementation is federated-by-choice (any node can be a hub via unset ARENA_UPSTREAM_URL), not peer-to-peer — one SQLite DB per arena is still the single source of truth for whoever points at it. A genuinely arena-less design (fight results/registrations as signed, independently-verifiable nostr events propagated across many relays, no server authoritative) is a real architecture change. Design later.

8. External bots that "fix" a webhook_test 401 by disabling signature verification entirely

• Not a bug in this codebase — a warning for the unified prompt's audience. webhook_test (the registration-time verification call) is deliberately unsigned (no BOT_SECRET exists yet at registration). A bot that generalizes "this one request was unsigned" into "disable signature checking entirely" reopens its own webhook to spoofed challenges from anyone, not just the real arena — confirmed real fight deliveries ARE always signed (server/src/engine/orchestrator.ts, secretHash unconditionally stored at registration). Fixed in the doc itself (BOTFIGHTS.md section 4 + Option B example + troubleshooting table, botfight commit ffd4dfd, part of 1.2.6) to special-case type === 'webhook_test' only.

9. Broken profile images — CSP img-src missing https:

• Reported live: "images in profile and such coming up as broken links." Root cause: secureHeaders()'s CSP img-src only allowed 'self', data:, blob:' — nostr profile pictures come from kind:0 metadata, a URL the user sets via their own client, hosted on whatever domain they picked. There's no central image host for a decentralized identity system. Fixed same session (botfight commit 877d1f6, part of 1.2.8): added https: (broad) to img-src — safe since images can't execute script even from an untrusted origin, unlike script-src, which stays locked to 'self'.

10. AI-answer feature discoverability

• The new "let BotFights answer for me" feature (1.2.7) was reported as invisible after shipping — it was gated behind picking POLLING (not the default WEBHOOK) AND behind a collapsed toggle within that. Fixed same session (botfight commit 877d1f6, part of 1.2.8): POLLING is now the default connection mode (also BOTFIGHTS.md's own documented default), the AI section is expanded by default, and the POLLING button's own description mentions the option.

11. Cashu fixed-stake entry fee ("winner takes all, 21 sats each, only ever") — SCOPED, NOT IMPLEMENTED

• User-directed feature request, explicitly asked to be scoped properly before any code, given real bearer-instrument money is involved.
• What exists today: server/src/engine/payments.ts only mints outbound cashu tokens to pay a winner from the arena's own configured mint. There is no code path that accepts a user-submitted token as an entry stake — this is genuinely new work, not a wire-up.
• Mint chosen and verified live (not guessed): Minibits, https://mint.minibits.cash/Bitcoin — confirmed NUT-4 (mint, bolt11/sat), NUT-5 (melt), NUT-7 (spend-check), NUT-11 (P2PK) all present via its /v1/info endpoint. BOTFIGHTS_CASHU_MINT_URL set on the canonical arena (botfight commit 7341ca0) — config-only, moves no funds by itself (the existing payout branch is only reached from ranked-mode fights, which still requires the still-unset BOTFIGHTS_NWC_URL).
• Threat register worked through before any implementation:
  1. Bearer-token custody window — must swap a posted token into server-owned proofs immediately on receipt (NUT-7), never hold the raw wire-format token as state (crash-loses-money risk otherwise).
  2. Mint trust — inherent to any Cashu design; mitigated by choosing an established, verified-live mint whose own operators recommend small amounts (matches the 21-sat cap).
  3. Amount enforcement — must hard-reject anything that isn't exactly 21 sats, server-side, at submission — the whole point of the cap is bounding any bug's blast radius to a trivial amount.
  4. Double-posting / replay — must validate/swap with the mint (NUT-7) at submission time, not trust the token string at face value.
  5. Refund path — an unmatched/cancelled/timed-out stake must return to its poster; no refund path = silent fund loss on the (common, for anonymous poll-mode bots) timeout case.
  6. Payout destination — resolved: NUT-11 P2PK lets a payout be locked to the winner's own pubkey with no interactive receive step required.
  7. Logging hygiene — a raw token string is money; same rule as API keys, never logged, never in error messages.
• Recommendation for the actual implementation (not done): a new escrow-and-swap flow (post token → validate exact amount + NUT-7 check → immediate mint-side swap to server custody → hold server-owned proof reference in DB, never the raw token → on fight resolution, mint a fresh 42-sat P2PK token to the winner's pubkey → on timeout/cancellation, mint a refund token back to the poster's pubkey if they provided one, or require pubkey-at-submission specifically so a refund destination always exists). This should be its own properly-planned unit of work, not folded into an already-massive hotfix batch.