belote-cli 3.2.0__tar.gz → 3.3.2__tar.gz

{belote_cli-3.2.0 → belote_cli-3.3.2}/CHANGELOG.md

@@ -5,6 +5,81 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.3.2] - 2026-05-10
+
+Residual-audit release — a fresh full-codebase pass after 3.3.1 turned up three real findings (a HIGH live-HUD divergence under La Rupture, a MEDIUM determinism leak in `replay.analyze_round`, and a LOW cosmetic chips display). The same pass flagged ~5 plausible-sounding "performance wins" and other claims that fell apart on verification — catalogued in the plan file at `/home/mrrobot/.claude/plans/bug-hunt-code-performance-cheeky-globe.md` so they aren't re-investigated. 537 tests passing (up from 535), ruff and mypy strict still clean.
+
+### Fixed
+
+- **`src/belote/scoring.py::is_capot` + `src/belote/game.py::compute_trick_winners` (F1)** — `is_capot(state, tricks=[…])` now honors La Rupture (`no_consecutive_team_wins`) in the explicit-tricks branch, matching the default-branch behaviour the 3.3.1 La Rupture fix established. The 8th-trick live-HUD CAPOT announcement (`gameflow.py:211-217`) passes an explicit list (`completed_tricks + [current_trick]`) and previously re-derived winners with raw `trick_winner_seat`, falsely shouting "CAPOT!" under La Rupture even though the final score correctly resolved as non-capot. Fix: `compute_trick_winners` now accepts an optional `tricks` override and `is_capot` delegates both branches through it — single source of truth for Rupture-aware winner resolution. Regression test in `tests/belatro/test_boss_modifiers_integration.py::test_is_capot_honors_rupture_in_explicit_tricks_branch`.
+- **`src/belote/replay.py::analyze_round` + `src/belote/gameflow.py` (F2)** — The 3.3.1 fix made `AIPlayer.__init__` accept a seeded `rng` parameter; the round driver threaded it through, but `replay.analyze_round` kept the legacy unseeded fallback. Post-round replay analysis on the 'R' key thus ran the Hard AI with an unseeded `random.Random()`, so "Optimal plays: 6/8 (75%)" could become "5/8 (62%)" between consecutive runs on the same data — most visibly under Sans Atout, where `_hard_play` falls through to `_easy_play` and `rng.choice(legal)` is the sole arbiter. Fix: `analyze_round` takes an optional `rng`, and the gameflow caller passes `current._rng` from the final round state. Regression test in `tests/test_replay.py::test_analyze_round_deterministic_under_seeded_rng`.
+- **`src/belote/belatro/core/scoring.py::get_popup_lines` (F3)** — Score popup now displays clamped chips (`max(0, state._chips)`) to match `get_total()`'s clamp boundary. Pre-3.3.2 L'Égoïste partner-win-heavy rounds rendered "Chips -12 × Mult 2.0 = 0" — internally consistent but visually a bug. Cosmetic only; no logic change.
+
+### Internal
+
+- **Tests**: 535 → 537 (+2 regressions for F1 and F2).
+- **Strict gates**: pytest 537/537, mypy 0 errors (76 files), ruff 0 violations.
+- **`compute_trick_winners` signature widened**: optional `tricks` parameter (default `None` preserves the existing behaviour). Single source of truth for La Rupture-aware winner resolution across both live-HUD and final-scoring paths.
+
+### Rejected — performance "wins" catalogued (so they aren't re-investigated)
+
+- **"`_hard_play` recomputes `Counter` per candidate card"** — falsified. `hand_suit_counts` is hoisted at `ai.py:531` *before* the `for card in legal:` loop and threaded into `_score_card_play` as a parameter.
+- **"`score_round` walks tricks 4×"** — falsified post-3.2.0. `winners` is computed once at `scoring.py:600` and threaded into `_calculate_base_points` and `_apply_scoring_modifiers`. Remaining trick-count passes are two cheap `sum(1 for …)` walks of an 8-element list.
+- **"`play_card` does a wholesale `replace()`"** — true but irreducible. Frozen+slotted GameState is a deliberate design choice; the "fix" would re-introduce the mutation class of bugs the 2.x rewrites eliminated.
+- **"`stats.py` per-round full-rewrite is a regression"** — falsified. It's the B2 (3.3.1) fix for crash-safety, intentional.
+- **"Event-bus `list(self._handlers)` per emit is wasteful"** — defensive copy enabling sub/unsub during emit. Handler counts are static and tiny.
+
+## [3.3.1] - 2026-05-10
+
+Audit-of-audit release — an inbound LLM audit produced a 18-bug list with mixed accuracy (B1/B2/B7/B8/B9/B10/B14/B16/B17 real; B3/B5/B12/B18 and the ruff-violation claim either self-refuted or hallucinated). The verified subset was fixed, then a fresh independent pass turned up seven additional high-confidence bugs the original audit missed — chiefly La Rupture and L'Anarchie scoring divergences, an unseeded AI RNG that broke ghost-run determinism, and a stale-void inference leak across mid-round undo. All 17 fixes ship in this release. 535 tests passing, ruff and mypy strict still clean.
+
+### Fixed — audit findings
+
+- **`src/belote/scoring.py::trick_card_points` (B1)** — `ban_clubs` zero rule now matches `_calculate_base_points`: the whole trick zeros when *any* card is a club, not just when the lead is. Pre-3.3.1 the live HUD running total diverged from the final round score whenever a non-lead card was a club under the `LesClubsBannis` boss.
+- **`src/belote/stats.py::StatisticsManager.update_stats_round` (B2)** — Now calls `flush_stats()` after every round, not just at end-of-game. A crash between rounds no longer silently loses round-level stats and achievement unlocks.
+- **`src/belote/belatro/items/base.py::fuse_jokers` (B7)** — Fused joker now carries over the better edition of the two inputs (POLY > HOLO > FOIL > NONE; NEGATIVE collapses to NONE since its slot bonus was already granted at purchase) and inherits `is_corrupted` if either input was corrupted. Pre-3.3.1 `type(a)()` returned a class-default instance, silently erasing any Foil/Holo/Polychrome the player had paid for.
+- **`src/belote/belatro/ui/rules.py` (B8)** — Reroll cost doc text now reads `$5` to match `Shop.reroll_cost = 5` in code.
+- **`src/belote/belatro/engine/modifier_patch.py::patch` (B9)** — Replaced `assert not attr.startswith("_")` with an explicit `if … raise ValueError(...)`. The `assert` was strippable with `python -O`.
+- **`src/belote/belatro/progression/unlocks.py` + `src/belote/belatro/main.py::BelAtroGame._drain_unlock_announcements` (B10)** — Unlock notifications no longer `print()` raw to stdout (which scrolled and corrupted the alt-screen). Notices are queued on `UnlockTracker.pending_announcements` and drained by the host loop through `BelAtroAnnounce.banner`.
+- **`src/belote/belatro/run/ante_themes.py` + `src/belote/belatro/main.py::_play_blind` + `src/belote/belatro/core/run_state.py::target_score` (B14)** — The Phase 3.1 ante-themes module is now wired into the live game loop: `roll_theme(rng_value)` fires at the start of each ante (`blind_index == 0`) using the run's seeded RNG, `target_score` applies the theme's `target_multiplier(blind_index)`, and `on_blind_won` runs after each successful blind. Tests already covered the module in isolation; production code never invoked it.
+- **`src/belote/belatro/ui/trust_bar.py` (B16)** — Three-tier color: ≤3 red, 4–6 gold (neutral), ≥7 green. Default trust value 5 used to render red under the old `> 5` threshold, falsely signalling distrust at the start of every run.
+- **`src/belote/belatro/partner/personality.py::should_coinche` (B17 + wiring gap)** — Signature now takes a `Random` parameter; `LeFlambeur` consumes the round-driver's seeded RNG instead of the bare module-level `random.random()`. The round driver (`engine/round_driver.py:215-235`) also now calls `partner.personality.should_coinche(state, rng)` when the human player declines a coinche on an EW taker, giving the AI partner a chance to act on its own initiative (gated by `partner.trust.ai_degraded`). Pre-3.3.1 `should_coinche` had no production caller at all.
+
+### Fixed — independent bug-hunt pass (not in original audit)
+
+- **`src/belote/scoring.py::compute_trick_winners` (new helper in `game.py`) — La Rupture scoring divergence** — `play_card` reassigned the trick winner for the live HUD whenever `no_consecutive_team_wins` (La Rupture boss) would flip the win, but `score_round`, `_calculate_base_points`, `_apply_scoring_modifiers`, and `is_capot` all re-derived winners via raw `trick_winner_seat` calls — silently restoring the un-flipped winner and producing impossible capots / double-credited rounds. A new `compute_trick_winners(state, trump, is_sa)` helper in `game.py` carries the Rupture rule once and is used by every scoring path. Live HUD and final score now agree under La Rupture.
+- **`src/belote/game.py::GameState.belote_announcer` + `src/belote/scoring.py::score_round` — L'Anarchie + Belote/Rebelote** — Under L'Anarchie (dynamic trump), `state.trump` rotates mid-round. Scoring's `belote_holders.get(state.trump)` lookup then keyed on the *post-rotation* trump and missed any Belote announced on the original trump, silently zeroing the 20/40 bonus. New `belote_announcer: Seat | None` field on `GameState` captures the announcing seat at the moment `belote_tracker[0]` flips True; scoring reads it directly instead of going through the rotated-trump lookup.
+- **`src/belote/scoring.py::score_round` chute branch — `no_dix_de_der` ignored on chute** — The chute formula at line ~774 unconditionally added `LAST_TRICK_BONUS` (+10) to the defender total, even when the `Le Zéro Final` boss was active. The in-round path at line ~606 already gated the bonus on `no_dix_de_der`; the chute branch is now gated symmetrically.
+- **`src/belote/scoring.py::_apply_scoring_modifiers` — La Compétition (`separate_scoring`) parity** — Two parallel bugs to B1 / the chute fix above: (a) the separate-scoring branch zeroed only the *lead-clubs* trick under `ban_clubs` (same divergence we fixed in `trick_card_points`); (b) it unconditionally added +10 de der to the individual last-trick winner, ignoring `no_dix_de_der`. Both now mirror the main scoring path.
+- **`src/belote/ai.py::AIPlayer.__init__` + `src/belote/belatro/engine/round_driver.py` — AI RNG was unseeded** — `AIPlayer.__init__` constructed `random.Random()` (no seed) regardless of the round's seed. Easy-AI random plays, personality jitter, and any other stochastic AI decision randomised per process even at a fixed run seed — silently breaking ghost-run reproducibility, replay determinism, and seeded benchmarks. The round driver now passes its seeded `rng` into every AIPlayer it constructs; the constructor accepts an optional `rng` arg with the old unseeded `Random()` as fallback for legacy callers.
+- **`src/belote/ai.py::AIPlayer.update_memory` — stale void inference across undo** — `known_voids` and `processed_tricks_count` were monotonic; a mid-round undo (which reverts `state` from `gameflow.history`) left voids inferred from now-rolled-back tricks in place, causing the AI to misplay based on cards that no longer existed in the game. `update_memory` now detects regression (current `(completed_count, current_trick_len)` strictly less than `last_voids_key`) and rebuilds the inference set from the live state.
+- **`src/belote/ai.py::_hard_play` — first-legal-card under Sans Atout** — `_hard_play` bailed to `return legal[0]` when `state.trump is None` (the legitimate SA contract), making hard AI strictly worse than medium under SA — `_medium_play` falls through to `_easy_play` (uniform random) in the same case. Hard now does the same; the deterministic-worst-case path is gone.
+
+### Internal
+
+- **Tests**: 535 / 535 still passing.
+- **Strict gates**: mypy 0 errors (75 files), ruff 0 violations.
+- **One new GameState field**: `belote_announcer: Seat | None = None`, threaded through `play_card` and `reset_round_fields`. Default-None matches pre-3.3.1 serialisation for the legacy non-Anarchie path.
+- **One new public helper**: `belote.game.compute_trick_winners(state, trump, is_sans_atout) -> list[Seat | None]` — the single source of truth for La Rupture-aware winner resolution. `play_card`'s own Rupture branch is retained for the live HUD; the helper is what scoring now uses.
+
+## [3.3.0] - 2026-05-10
+
+BelAtro history overlay release — the [H] key in BelAtro mode now opens a populated, run-aware overlay instead of always showing "No rounds completed yet." Classic Belote's H-key path is unchanged. 535 tests passing (up from 528), ruff and mypy strict still clean.
+
+### Fixed
+
+- **`src/belote/belatro/ui/history.py` (new) + `src/belote/belatro/core/run_state.py::BelAtroRun.history` + `src/belote/belatro/main.py::BelAtroGame._record_history_entry`** — Pressing **H** in BelAtro now shows a per-blind ledger (ante, blind label, target, boss, taker, contract, score, status, money Δ, declarations) instead of an empty "No rounds completed yet." screen. Root cause: the classic [H] overlay (`belote.ui.prompts.show_history`) reads `state.score_history`, but the BelAtro round driver (`belatro.engine.round_driver.drive_round`) never invokes `apply_round_score` — the sole writer of `score_history` — and the existing BelAtro `on_round_end` callback was just `pass`. Fix: `BelAtroRun` now carries a parallel `history: list[BelAtroHistoryEntry]`, populated after each round in `_play_blind` from the score breakdown + run snapshot, and rendered by the new `show_belatro_history` overlay (wide table on ≥90-col terminals, three-line-per-row compact layout below).
+
+### Added
+
+- **`src/belote/ui/prompts.py::set_history_override`** — Module-level hook the BelAtro launcher installs in `BelAtroGame.start` (closure over `self.run.history`) and clears in its `finally` block. `show_history` short-circuits to the override when set, otherwise falls through to the classic `state.score_history` renderer. This is the seam that lets BelAtro own its overlay without forking `prompt_card` or threading a renderer through every UI call site.
+- **`tests/belatro/test_history_overlay.py`** — 7 new tests covering `BelAtroRun.history` default-empty, the four status branches (WON / FAILED / CAPOT / SURVIVED), and the override hook's routing + cleanup contract. An autouse fixture clears `_history_override` between tests so leaks across the test session are impossible.
+
+### Internal
+
+- **Tests**: 528 → 535 (+7).
+- **Strict gates**: pytest 535/535, mypy 0 errors, ruff 0 violations across `src/` and `tests/`.
+
 ## [3.2.0] - 2026-05-10
 
 Two-audit reconciliation release — the prioritized fix list distilled from Qwen 3.6 27B + Ring 1T audits (~30 raw claims, ~half held up under verification). Twelve real bugs fixed across joker logic, registry hygiene, RNG determinism, and UI offsets; one new finding (Tarot RNG was also unseeded) caught by the fresh-hunt pass. Eleven audit claims rejected as false positives are catalogued in the plan file so they aren't re-investigated. 528 tests passing (up from 525), ruff and mypy strict still clean.

{belote_cli-3.2.0 → belote_cli-3.3.2}/DEVELOPMENT.md

@@ -84,14 +84,14 @@ PYTHONPATH=src mypy --strict src/
 # Linting (0 violations expected)
 ruff check src/ tests/
 
-# Full test suite (528 tests expected)
+# Full test suite (535 tests expected)
 PYTHONPATH=src pytest
 ```
 
-Current baseline (3.2.0):
+Current baseline (3.3.1):
 - **mypy**: 0 errors (strict mode)
 - **ruff**: 0 violations
-- **pytest**: 528 tests, 0 failures
+- **pytest**: 535 tests, 0 failures
 
 Run all gates before committing:
 

{belote_cli-3.2.0 → belote_cli-3.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: belote-cli
-Version: 3.2.0
+Version: 3.3.2
 Summary: A 4-player terminal card game
 Project-URL: Homepage, https://github.com/ElysiumDisc/belote
 Project-URL: Repository, https://github.com/ElysiumDisc/belote
@@ -45,6 +45,22 @@ Description-Content-Type: text/markdown
 
 Complete implementation of the French card game Belote for the terminal, with a full-screen green felt table and full card graphics at compass positions (N/W/E/S).
 
+## What's new in 3.3.1
+
+- **Scoring correctness under bosses** — La Rupture (`no_consecutive_team_wins`) used to be applied to the live HUD but silently ignored by `score_round`, so the running total and final score diverged and impossible capots could be reported. L'Anarchie (dynamic trump) rotated `state.trump` mid-round, after which scoring's `belote_holders.get(trump)` lookup missed any Belote announced on the original trump and silently zeroed the 20/40 bonus. Both are fixed: a new `compute_trick_winners` helper is the single source of truth for La Rupture-aware winner resolution, and a new `belote_announcer: Seat` field captures the announcing seat at declaration time so the rotated trump no longer matters.
+- **Boss interactions** — Le Zéro Final (`no_dix_de_der`) is now honored by the chute branch and by La Compétition's per-player tally (both used to unconditionally add +10 de der). La Compétition's `ban_clubs` check now matches the main scoring path (`any` rather than `lead-only`).
+- **Determinism** — `AIPlayer` now accepts and threads a seeded `Random` from the round driver. Pre-3.3.1 it constructed an unseeded `Random()` regardless of the run seed, breaking ghost-run reproducibility and replay determinism. Partner's `should_coinche` (Le Flambeur) was also using the global `random` module; now uses the driver's seeded RNG and is actually wired into the coinche flow (it had no production caller before).
+- **AI memory across undo** — Hard AI's void inference is no longer stuck with stale voids after a mid-round undo: `update_memory` detects state regression and rebuilds inferences from the live tricks.
+- **Hard AI under Sans Atout** — Used to deterministically return `legal[0]`; now falls back to easy (random) like medium, removing the worst-case under SA.
+- **Audit fixes** — `ban_clubs` HUD/final divergence (was real); per-round stats now flush to disk (achievement unlocks no longer lost on crash); `fuse_jokers` now carries over edition (FOIL/HOLO/POLY) and corruption; `assert` in `modifier_patch` replaced with `raise ValueError` (was strippable by `python -O`); unlock notifications routed through the TUI banner instead of raw `print()` (no more alt-screen scroll); ante themes (Café/Tournoi) wired into the live game loop (the Phase 3.1 module was previously test-only).
+- **UI** — Trust bar is three-tier (red ≤3, gold 4–6, green ≥7). Pre-3.3.1 the default trust of 5 rendered red, falsely signalling distrust at run start.
+- **Test coverage** — 535 tests still passing. Strict gates clean: pytest 535/535, mypy 0 errors, ruff 0 violations.
+
+## What's new in 3.3.0
+
+- **BelAtro [H] history overlay** — Pressing **H** during a BelAtro run now opens a populated, run-aware ledger: one row per blind with ante, blind label (Small/Big/Boss), target, boss name (when active), taker, contract, NS/EW trick split, BelAtro score, status (`WON` / `FAILED` / `CAPOT` / `SURVIVED`), and money delta. Before 3.3, [H] always showed "No rounds completed yet." in BelAtro because the round driver never invoked `apply_round_score` — the classic-mode writer of `state.score_history`. The fix keeps a parallel `BelAtroRun.history` ledger and routes [H] to a new BelAtro renderer via a small override hook in `belote.ui.prompts`. Classic Belote's [H] path is unchanged.
+- **Test coverage** — 535 tests (up from 528). Strict gates still clean: pytest 535/535, mypy 0 errors, ruff 0 violations.
+
 ## What's new in 3.2.0
 
 - **Joker correctness** — La Sentinelle and Le Dernier Mot both used to key on `Seat.SOUTH` instead of the NS team, so the joker silently no-op'd when North (the AI partner) held the trump Jack or won the last trick. Both now correctly fire on team membership.

{belote_cli-3.2.0 → belote_cli-3.3.2}/README.md

@@ -2,6 +2,22 @@
 
 Complete implementation of the French card game Belote for the terminal, with a full-screen green felt table and full card graphics at compass positions (N/W/E/S).
 
+## What's new in 3.3.1
+
+- **Scoring correctness under bosses** — La Rupture (`no_consecutive_team_wins`) used to be applied to the live HUD but silently ignored by `score_round`, so the running total and final score diverged and impossible capots could be reported. L'Anarchie (dynamic trump) rotated `state.trump` mid-round, after which scoring's `belote_holders.get(trump)` lookup missed any Belote announced on the original trump and silently zeroed the 20/40 bonus. Both are fixed: a new `compute_trick_winners` helper is the single source of truth for La Rupture-aware winner resolution, and a new `belote_announcer: Seat` field captures the announcing seat at declaration time so the rotated trump no longer matters.
+- **Boss interactions** — Le Zéro Final (`no_dix_de_der`) is now honored by the chute branch and by La Compétition's per-player tally (both used to unconditionally add +10 de der). La Compétition's `ban_clubs` check now matches the main scoring path (`any` rather than `lead-only`).
+- **Determinism** — `AIPlayer` now accepts and threads a seeded `Random` from the round driver. Pre-3.3.1 it constructed an unseeded `Random()` regardless of the run seed, breaking ghost-run reproducibility and replay determinism. Partner's `should_coinche` (Le Flambeur) was also using the global `random` module; now uses the driver's seeded RNG and is actually wired into the coinche flow (it had no production caller before).
+- **AI memory across undo** — Hard AI's void inference is no longer stuck with stale voids after a mid-round undo: `update_memory` detects state regression and rebuilds inferences from the live tricks.
+- **Hard AI under Sans Atout** — Used to deterministically return `legal[0]`; now falls back to easy (random) like medium, removing the worst-case under SA.
+- **Audit fixes** — `ban_clubs` HUD/final divergence (was real); per-round stats now flush to disk (achievement unlocks no longer lost on crash); `fuse_jokers` now carries over edition (FOIL/HOLO/POLY) and corruption; `assert` in `modifier_patch` replaced with `raise ValueError` (was strippable by `python -O`); unlock notifications routed through the TUI banner instead of raw `print()` (no more alt-screen scroll); ante themes (Café/Tournoi) wired into the live game loop (the Phase 3.1 module was previously test-only).
+- **UI** — Trust bar is three-tier (red ≤3, gold 4–6, green ≥7). Pre-3.3.1 the default trust of 5 rendered red, falsely signalling distrust at run start.
+- **Test coverage** — 535 tests still passing. Strict gates clean: pytest 535/535, mypy 0 errors, ruff 0 violations.
+
+## What's new in 3.3.0
+
+- **BelAtro [H] history overlay** — Pressing **H** during a BelAtro run now opens a populated, run-aware ledger: one row per blind with ante, blind label (Small/Big/Boss), target, boss name (when active), taker, contract, NS/EW trick split, BelAtro score, status (`WON` / `FAILED` / `CAPOT` / `SURVIVED`), and money delta. Before 3.3, [H] always showed "No rounds completed yet." in BelAtro because the round driver never invoked `apply_round_score` — the classic-mode writer of `state.score_history`. The fix keeps a parallel `BelAtroRun.history` ledger and routes [H] to a new BelAtro renderer via a small override hook in `belote.ui.prompts`. Classic Belote's [H] path is unchanged.
+- **Test coverage** — 535 tests (up from 528). Strict gates still clean: pytest 535/535, mypy 0 errors, ruff 0 violations.
+
 ## What's new in 3.2.0
 
 - **Joker correctness** — La Sentinelle and Le Dernier Mot both used to key on `Seat.SOUTH` instead of the NS team, so the joker silently no-op'd when North (the AI partner) held the trump Jack or won the last trick. Both now correctly fire on team membership.

{belote_cli-3.2.0 → belote_cli-3.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "belote-cli"
-version = "3.2.0"
+version = "3.3.2"
 description = "A 4-player terminal card game"
 readme = "README.md"
 requires-python = ">=3.10"

{belote_cli-3.2.0 → belote_cli-3.3.2}/src/belote/__init__.py

@@ -1,3 +1,3 @@
-__version__ = "3.2.0"
+__version__ = "3.3.1"
 
 __all__ = ["__version__"]

{belote_cli-3.2.0 → belote_cli-3.3.2}/src/belote/ai.py

@@ -41,18 +41,31 @@ class AIMemory:
 
 
 class AIPlayer:
-    def __init__(self, seat: Seat, difficulty: Difficulty = Difficulty.MEDIUM) -> None:
+    def __init__(
+        self,
+        seat: Seat,
+        difficulty: Difficulty = Difficulty.MEDIUM,
+        rng: random.Random | None = None,
+    ) -> None:
         self.seat = seat
         self.difficulty = difficulty
         self.memory = AIMemory()
-        self._rng = random.Random()
+        # Accept the caller's seeded RNG (round driver / replay tooling) so
+        # easy-AI plays, personality jitter, and any other stochastic AI
+        # decisions are reproducible under a fixed seed. Falls back to an
+        # unseeded Random() for legacy callers that construct an AIPlayer
+        # directly (e.g. test fixtures).
+        self._rng = rng if rng is not None else random.Random()
         # Set per decide_card() call from state.boss_modifiers.seven_eight_trump.
         # All ranking helpers in this class read it via self._se.
         self._se = False
 
     def update_memory(self, state: GameState) -> None:
         """Update memory with currently visible information."""
-        if len(state.completed_tricks) == 0 and len(state.current_trick) == 0:
+        completed_count = len(state.completed_tricks)
+        current_count = len(state.current_trick)
+
+        if completed_count == 0 and current_count == 0:
             # New round - reset memory. Including the void-cache key — without
             # this a (0, 0) / (0, 1) key from the first decision of *this* round
             # could coincidentally match a leftover from the previous round and
@@ -63,6 +76,20 @@ class AIPlayer:
             self.memory.partner_hand.clear()
             self.memory.processed_tricks_count = 0
             self.memory.last_voids_key = None
+        elif (
+            self.memory.last_voids_key is not None
+            and (completed_count, current_count) < self.memory.last_voids_key
+        ):
+            # Mid-round undo: the state regressed below the highest point
+            # we've processed. `known_voids` and `processed_tricks_count`
+            # are monotonic and would carry stale inferences forward
+            # (a void inferred from a now-rolled-back trick). Rebuild from
+            # the current state instead of trying to subtract.
+            self.memory.played.clear()
+            for s in Seat:
+                self.memory.known_voids[s].clear()
+            self.memory.processed_tricks_count = 0
+            self.memory.last_voids_key = None
 
         # Track all cards in completed tricks
         for trick in state.completed_tricks:
@@ -473,7 +500,12 @@ class AIPlayer:
         trick = state.current_trick
 
         if not trump:
-            return legal[0]
+            # Sans Atout: the lookahead scoring uses `trick_rank(c, trump, ...)`
+            # which is meaningless without a trump suit. Fall back to easy
+            # (random over legal) rather than `legal[0]` so we don't degrade
+            # to a fully deterministic worst-case under SA — matches what
+            # `_medium_play` does at its own trump==None guard.
+            return self._easy_play(state, legal)
 
         # Update void inferences from completed tricks
         self._update_voids(state)

{belote_cli-3.2.0 → belote_cli-3.3.2}/src/belote/belatro/core/run_state.py

@@ -7,6 +7,7 @@ if TYPE_CHECKING:
     from ..items.base import Joker, Voucher
     from ..progression.save import Profile
     from ..run.ante import Ante
+    from ..ui.history import BelAtroHistoryEntry
 
 from ..partner.partner_state import PartnerState
 from .economy import Economy
@@ -76,6 +77,12 @@ class BelAtroRun:
     # this; tests assert it. Cleared whenever a new tarot is used.
     last_tarot_message: str | None = None
 
+    # ── Per-blind history (powers the [H] overlay) ─────────
+    # Appended by `BelAtroGame._play_blind` after each Belote round. The
+    # classic `state.score_history` is never written under BelAtro (see
+    # `belatro/ui/history.py` header for the full rationale).
+    history: list[BelAtroHistoryEntry] = field(default_factory=list)
+
     # ── Determinism ────────────────────────────────────────
     seed: int | None = None
     _rng: Any = None
@@ -167,7 +174,23 @@ class BelAtroRun:
 
     @property
     def target_score(self) -> int:
-        return self.current_blind.target
+        base = self.current_blind.target
+        theme = self.get_ante_theme()
+        if theme is None:
+            return base
+        # Soft target adjustments (e.g. Café reduces boss target by 5%).
+        # Round to int after the float multiply so downstream scoring
+        # comparisons stay integral.
+        return max(1, int(round(base * theme.target_multiplier(self.blind_index))))
+
+    def get_ante_theme(self) -> Any:
+        """Resolve `ante_theme` (id) back to an AnteTheme instance, or None."""
+        if not self.ante_theme:
+            return None
+        from ..run.ante_themes import THEME_BY_ID
+
+        cls = THEME_BY_ID.get(self.ante_theme)
+        return cls() if cls is not None else None
 
     def advance_blind(self) -> None:
         if self.blind_index < 2:

{belote_cli-3.2.0 → belote_cli-3.3.2}/src/belote/belatro/core/scoring.py

@@ -253,5 +253,9 @@ class ScoreAccumulator:
         return int(chips * mult)
 
     def get_popup_lines(self, state: GameState) -> list[str]:
-        return [*self._log, f"Chips {state._chips} × Mult {state._mult:.1f} = {self.get_total(state)}"]
+        # Match the clamp in get_total(): L'Égoïste can push _chips negative
+        # mid-round; the popup line would otherwise read "Chips -12 × Mult …
+        # = 0" which looks like a UI bug rather than the intended clamp.
+        chips_display = max(0, state._chips)
+        return [*self._log, f"Chips {chips_display} × Mult {state._mult:.1f} = {self.get_total(state)}"]
 

{belote_cli-3.2.0 → belote_cli-3.3.2}/src/belote/belatro/engine/modifier_patch.py

@@ -33,10 +33,11 @@ class PatchedGameState:
         against in tests/belatro/test_boss_modifiers_integration.py
         `test_invariant_no_underscore_boss_attrs`.
         """
-        assert not attr.startswith("_"), (
-            f"patch() received leading-underscore attr {attr!r}; the 3.0.x shim "
-            "was removed in 3.1.0 — use the unprefixed boss field name."
-        )
+        if attr.startswith("_"):
+            raise ValueError(
+                f"patch() received leading-underscore attr {attr!r}; the 3.0.x shim "
+                "was removed in 3.1.0 — use the unprefixed boss field name."
+            )
 
         if attr in _BOSS_FIELDS:
             current_bm = self.boss_modifiers

{belote_cli-3.2.0 → belote_cli-3.3.2}/src/belote/belatro/engine/round_driver.py

@@ -134,10 +134,14 @@ def drive_round(
         "medium": Difficulty.MEDIUM,
         "hard": Difficulty.HARD,
     }.get(_north_diff_str, Difficulty.MEDIUM)
+    # Thread the round's seeded RNG into every AI seat so easy-AI plays and
+    # personality jitter stay reproducible under a fixed seed. Ghost-run and
+    # replay tooling rely on this — without it, AIPlayer's old unseeded
+    # default RNG randomised behavior per process even at a fixed seed.
     ai_players = {
-        Seat.EAST: AIPlayer(Seat.EAST, Difficulty.MEDIUM),
-        Seat.NORTH: AIPlayer(Seat.NORTH, _north_diff),
-        Seat.WEST: AIPlayer(Seat.WEST, Difficulty.MEDIUM),
+        Seat.EAST: AIPlayer(Seat.EAST, Difficulty.MEDIUM, rng=rng),
+        Seat.NORTH: AIPlayer(Seat.NORTH, _north_diff, rng=rng),
+        Seat.WEST: AIPlayer(Seat.WEST, Difficulty.MEDIUM, rng=rng),
     }
 
     if acc is not None:
@@ -219,7 +223,19 @@ def drive_round(
             surcoinche_unlocked = bool(state._joker_state.get("surcoinche_unlocked"))
             if surcoinche_unlocked and rng.random() < 0.3:
                 coinche_level = 2
-            # L'Avocat boss forces at least coinche=1 (existing auto_coinche flag).
+        else:
+            # Player declined — give the AI partner (North, same defending team)
+            # a chance to coinche on its own initiative. Personality-driven and
+            # gated by trust: a degraded partner won't act independently.
+            if (
+                not partner.trust.ai_degraded
+                and partner.personality.should_coinche(state, rng)
+            ):
+                coinche_level = 1
+                surcoinche_unlocked = bool(state._joker_state.get("surcoinche_unlocked"))
+                if surcoinche_unlocked and rng.random() < 0.3:
+                    coinche_level = 2
+        # L'Avocat boss forces at least coinche=1 (existing auto_coinche flag).
         if state.boss_modifiers.auto_coinche:
             coinche_level = max(coinche_level, 1)
         # Re-emit the final BidMadeEvent so jokers/HUD see the coinche level.

{belote_cli-3.2.0 → belote_cli-3.3.2}/src/belote/belatro/items/base.py

@@ -175,6 +175,29 @@ def fuse_jokers(a: Joker, b: Joker) -> Joker:
     new_idx = min(base_idx + 1, _RARITY_LADDER.index(Rarity.RARE))
     fused.rarity = _RARITY_LADDER[new_idx]
     fused.fusable = False  # one-time fusion only
+    # Carry over the better edition. type(a)() returns a fresh instance with
+    # the class default (NONE), so without this the player would silently lose
+    # any Foil/Holo/Polychrome they paid for. NEGATIVE is purchase-time only
+    # (the extra slot was already granted) so it doesn't propagate through
+    # fusion — fall back to NONE in that case.
+    fused.edition = _better_edition(a.edition, b.edition)
+    # Corruption is sticky — if either input was corrupted, so is the fusion.
+    fused.is_corrupted = a.is_corrupted or b.is_corrupted
     # Stamp a marker so callers can identify fused jokers
     fused.name = f"{a.name} + {b.name}"
     return fused
+
+
+_EDITION_RANK: dict[Edition, int] = {
+    Edition.NONE: 0,
+    Edition.NEGATIVE: 0,  # purchase-time only, doesn't survive fusion
+    Edition.FOIL: 1,
+    Edition.HOLO: 2,
+    Edition.POLYCHROME: 3,
+}
+
+
+def _better_edition(a: Edition, b: Edition) -> Edition:
+    pick = a if _EDITION_RANK[a] >= _EDITION_RANK[b] else b
+    # NEGATIVE collapses to NONE post-fusion (slot already counted).
+    return Edition.NONE if pick == Edition.NEGATIVE else pick

{belote_cli-3.2.0 → belote_cli-3.3.2}/src/belote/belatro/main.py

@@ -61,11 +61,24 @@ class BelAtroGame:
                         seed=self.run.seed if self.run.seed is not None else 0,
                         deck_id=self.run.deck_id,
                     )
+                # 3.3.0: route the in-game [H] key to the BelAtro history
+                # overlay (reading `self.run.history`) for the duration of
+                # the run. Cleared in the finally block so the classic
+                # Belote menu returns to the default `state.score_history`
+                # path on exit.
+                from ..ui.prompts import set_history_override
+                from .ui.history import show_belatro_history
+                run = self.run  # capture for the closure (mypy: narrowed)
+                set_history_override(
+                    lambda reader: show_belatro_history(reader, run.history)
+                )
                 self._run_loop()
         except KeyboardInterrupt:
             # Catch exit signals to return to the Belote main menu
             return
         finally:
+            from ..ui.prompts import set_history_override
+            set_history_override(None)
             # 3.0.0: append a one-line summary of the just-ended run for the
             # player's own analysis. Best-effort; swallowed on failure.
             if self.run is not None:
@@ -75,6 +88,19 @@ class BelAtroGame:
                     label = "won" if self.run.run_won else f"ante{self.run.ante_number}"
                     self._ghost_recorder.save(label=label)
 
+    def _drain_unlock_announcements(self) -> None:
+        """Render any queued unlock notices through the TUI banner.
+
+        Replaces the old raw-stdout `print()` notices in UnlockTracker, which
+        scrolled and corrupted the alt-screen buffer.
+        """
+        if self.reader is None:
+            self.unlock_tracker.drain_announcements()
+            return
+        from .ui.announce import BelAtroAnnounce
+        for msg in self.unlock_tracker.drain_announcements():
+            BelAtroAnnounce.banner(msg, self.reader, hold=1.5)
+
     def _run_loop(self) -> None:
         """Main game loop: Blind -> Shop -> Next."""
         if self.run is None:
@@ -84,6 +110,7 @@ class BelAtroGame:
             while not self.run.run_over:
                 # 1. Round (Blind)
                 self._play_blind()
+                self._drain_unlock_announcements()
 
                 if self.run.run_over:
                     break
@@ -97,8 +124,10 @@ class BelAtroGame:
                 # 3. Advance
                 self.run.advance_blind()
                 self.unlock_tracker.check_ante_unlocks(self.run.ante_number)
+                self._drain_unlock_announcements()
                 if self.run.run_won:
                     self.unlock_tracker.notify_run_won()
+                    self._drain_unlock_announcements()
                     if self.reader is not None:
                         BelAtroAnnounce.banner("YOU WON!", self.reader, hold=2.5)
                         # 3.0.0: offer Endless mode after the canonical 8 antes.
@@ -121,6 +150,20 @@ class BelAtroGame:
         """Execute one Belote round for the current blind."""
         if self.run is None or self.reader is None:
             return
+        # Phase 3.1: roll an Ante theme at the start of each ante (blind 0).
+        # Uses the run's seeded RNG so themes are deterministic per seed.
+        # The roll runs once per ante; subsequent blinds re-use the same theme.
+        if self.run.blind_index == 0:
+            from .run.ante_themes import roll_theme
+            theme = roll_theme(self.run._get_rng().random())
+            self.run.ante_theme = theme.id if theme is not None else None
+            if theme is not None:
+                theme.on_ante_start(self.run)
+        # 3.3.0: snapshots used at end of round to build the [H] history entry.
+        history_ante = self.run.ante_number
+        history_blind_index = self.run.blind_index
+        history_target = self.run.target_score
+        money_before = self.run.economy.money
         bus = EventBus()
         self.unlock_tracker.subscribe_to(bus)
         acc = ScoreAccumulator()
@@ -306,12 +349,12 @@ class BelAtroGame:
         self.run.partner_mood = trust.mood()
 
         effective_target = acc.target_score  # doubled for L'Avocat, normal otherwise
+        survived_via_insurance = False
         if total < effective_target:
             # Phase 2.1: Capot Insurance halves the chute loss (one-shot).
-            failure_softened = False
             if bd.is_failed and self.run.capot_insurance:
                 self.run.capot_insurance = False
-                failure_softened = True
+                survived_via_insurance = True
                 # Defer run-over by one blind: the player paid for a safety net.
                 # We treat the round as a survived chute (no run-over flag).
                 BelAtroAnnounce.banner(
@@ -319,7 +362,7 @@ class BelAtroGame:
                     self.reader,
                     hold=2.0,
                 )
-            if not failure_softened:
+            if not survived_via_insurance:
                 self.run.run_over = True
                 BelAtroAnnounce.banner(
                     f"RUN OVER — Failed to meet target {effective_target} (scored {total}).",
@@ -360,6 +403,12 @@ class BelAtroGame:
                 else:
                     trust.blind_beaten()
 
+            # Phase 3.1: fire the ante theme's per-blind-won hook (e.g. Tournoi
+            # awards bonus money, Café gives +1 trust on big-blind wins).
+            theme = self.run.get_ante_theme()
+            if theme is not None:
+                theme.on_blind_won(self.run, self.run.blind_index)
+
         # Partner-specific trust events (skipped under Le Divorce)
         if not lock_trust:
             if bd.taker_team == 0 and bd.is_failed:
@@ -367,6 +416,101 @@ class BelAtroGame:
             elif bd.is_capot and bd.taker_team == 0:
                 trust.capot_together()
 
+        # 3.3.0: append a BelAtro-side history entry (the [H] overlay reads
+        # `self.run.history` via the override hook installed in `start()`).
+        self._record_history_entry(
+            ante=history_ante,
+            blind_index=history_blind_index,
+            target=history_target,
+            boss=boss,
+            final_state=final_state,
+            bd=bd,
+            total=total,
+            money_delta=self.run.economy.money - money_before,
+            survived_via_insurance=survived_via_insurance,
+        )
+
+    def _record_history_entry(
+        self,
+        *,
+        ante: int,
+        blind_index: int,
+        target: int,
+        boss: object,
+        final_state: object,
+        bd: object,
+        total: int,
+        money_delta: int,
+        survived_via_insurance: bool,
+    ) -> None:
+        """Build and append one BelAtroHistoryEntry to `self.run.history`.
+
+        Pulled out of `_play_blind` so the long round body stays readable.
+        Kept private — callers should never construct entries directly.
+        """
+        if self.run is None:
+            return
+        from .ui.history import BelAtroHistoryEntry
+
+        blind_label = ("Small", "Big", "Boss")[blind_index] if 0 <= blind_index <= 2 else "?"
+        boss_name = getattr(boss, "name", None) if boss is not None else None
+
+        taker = getattr(final_state, "taker", None)
+        if taker is None:
+            taker_label = "—"
+        else:
+            team = "NS" if taker.value % 2 == 0 else "EW"
+            taker_label = f"{taker.name[0]} ({team})"
+
+        contract_field = getattr(final_state, "contract", None)
+        trump = getattr(final_state, "trump", None)
+        if contract_field == "sans_atout":
+            contract_str = "SA"
+        elif contract_field == "tout_atout":
+            contract_str = "TA"
+        elif trump is not None and hasattr(trump, "symbol"):
+            contract_str = trump.symbol
+        else:
+            contract_str = "—"
+
+        is_capot = bool(getattr(bd, "is_capot", False))
+        taker_team = getattr(bd, "taker_team", None)
+        if total >= target and is_capot and taker_team == 0:
+            status = "CAPOT"
+        elif total >= target:
+            status = "WON"
+        elif survived_via_insurance:
+            status = "SURVIVED"
+        else:
+            status = "FAILED"
+
+        tricks_ns = int(getattr(bd, "tricks_ns", 0))
+        tricks_ew = int(getattr(bd, "tricks_ew", 0))
+
+        # Pull declaration summaries off the breakdown when present. score_round
+        # doesn't currently expose them, so this is best-effort and falls back
+        # to empty tuples — the renderer treats those as "─".
+        decl_ns: tuple[str, ...] = tuple(getattr(bd, "decl_summary_ns", ()) or ())
+        decl_ew: tuple[str, ...] = tuple(getattr(bd, "decl_summary_ew", ()) or ())
+
+        self.run.history.append(
+            BelAtroHistoryEntry(
+                ante=ante,
+                blind_label=blind_label,
+                target=target,
+                boss_name=boss_name,
+                taker_label=taker_label,
+                contract=contract_str,
+                tricks_ns=tricks_ns,
+                tricks_ew=tricks_ew,
+                score=total,
+                status=status,
+                money_delta=money_delta,
+                decl_summary_ns=decl_ns,
+                decl_summary_ew=decl_ew,
+            )
+        )
+
 
 def main() -> None:
     import argparse