feat: hand history tracking

[lox]

Hand History Tracking with PHH Format

Implements hand history recording using the PHH (Poker Hand History) standard format - a TOML-based academic standard (IEEE CoG 2024) designed for poker AI research. Enables post-game analysis, bot debugging, and ML training dataset creation.

Key Features

100% PHH Spec Compliance: Implements all required and optional fields from the official specification. No custom extensions.

Chronological Board Tracking: Fixed board card ordering by tracking actual dealing sequence instead of bitset iteration. Flop/turn/river cards emit in correct order.

Player Rotation: SB-first ordering per PHH spec with proper blind tracking per position.

High-Performance Buffered Recording: In-memory buffering with async disk I/O. Flushes every 10s/100 hands. Zero performance impact (350+ hands/sec maintained).

Multi-Game Architecture: Per-game file isolation (hands/game-{id}/session.phhs), mutex-protected buffers, partial flush recovery, section counter resumption on restart.

Failure Recovery: 3-strike disable policy, graceful degradation, no data loss on partial flush failures.

Privacy Controls: Hole cards masked as ???? by default during deal. Showdown cards (publicly revealed) always recorded. Opt-in with --hand-history-hole-cards to include all private hole cards.

UTC Timestamps: All timestamps normalized to UTC for consistency.

Usage

# Enable recording
pokerforbots spawn --spec "complex:6" --hand-limit 100 --hand-history

# Include private hole cards (debugging only)
pokerforbots spawn --spec "complex:6" --hand-limit 100 --hand-history --hand-history-hole-cards

# Render/replay hands
pokerforbots hand-history render hands/game-default/session.phhs
pokerforbots hand-history render hands/game-default/session.phhs --limit 3

Example Output

[1]
variant = "NT"
table = "default"
seat_count = 3
seats = [2, 3, 1]
antes = [0, 0, 0]
blinds_or_straddles = [5, 10, 0]
min_bet = 10
starting_stacks = [995, 990, 1000]
finishing_stacks = [985, 1000, 1000]
winnings = [0, 10, 0]
actions = [
  "d dh p1 ????",
  "d dh p2 ????",
  "d dh p3 ????",
  "p3 cc",
  "p1 cc",
  "p2 cc",
  "d db Kh7d4s",
  "p1 cc",
  "p2 cc",
  "p3 cc",
  "d db 6s",
  "p1 cc",
  "p2 cc",
  "p3 cc",
  "d db Ah",
  "p1 cc",
  "p2 cc",
  "p3 cc",
  "p2 sm 5cAc",
  "p1 sm 9h2d",
  "p3 sm KsQs",
]
players = ["bob", "charlie", "alice"]
hand = "hand-1"
time = "12:34:56"
time_zone = "UTC"
day = 16
month = 11
year = 2025

Player-indexed arrays (players, seats, antes, blinds_or_straddles, starting_stacks, finishing_stacks, winnings) start with the small blind and wrap clockwise per PHH spec.

Implementation

Core Changes:

• internal/game/hand.go - Added boardOrder slice and BoardCards() method for chronological tracking
• internal/phh/ - PHH encoder, types, card notation helpers, bulk .phhs format
• internal/server/hand_history/ - Buffered monitor with player rotation, manager with flush coordination
• cmd/pokerforbots/hand_history_cmd.go - Render command with playback engine

Configuration Flags:

• --hand-history - Enable recording (default: disabled)
• --hand-history-dir - Base directory (default: hands)
• --hand-history-flush-secs - Flush interval (default: 10s)
• --hand-history-flush-hands - Flush count threshold (default: 100)
• --hand-history-hole-cards - Include all private hole cards (default: false)

Performance: ~200KB memory per game, ~2MB per 1000 hands, <1% throughput overhead

Testing

• Comprehensive unit tests with race detection (go test -race ./...)
• Integration tests for multi-game isolation, graceful shutdown, partial flush recovery
• Board ordering verified with deterministic seeded decks
• Section counter resumption verified across restarts
• Showdown tracking accuracy tests

Documentation

• docs/hand-history.md - Format guide and usage
• docs/operations.md - Server configuration
• plans/hand-history-tracking.md - Implementation plan

Breaking Changes

None. Opt-in feature, disabled by default.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[lox]

@codex review please?

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[lox]

@codex issues addressed, review again please.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".