belote-cli 3.9.0__tar.gz → 3.9.3__tar.gz

{belote_cli-3.9.0 → belote_cli-3.9.3}/CHANGELOG.md

@@ -5,6 +5,65 @@ 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.9.3] - 2026-05-15
+
+Multi-agent audit pass (six Explore agents — three broad-sweep + three targeted deep-dives on AI, scoring edge cases, per-joker mechanics, endless mode, meta-progression). Every load-bearing finding verified against the live code before patching; **8 false positives** caught and documented (corrupted-joker seat semantics being intentional, ToutStreak persistence working correctly via `card_enhancements`, `_card_back` LRU cache being theme-keyed, etc.). **Six real fixes (R1–R7)** landed plus three larger phases: render-diff layer, endless-mode boss-variety guard, and a Quinte Royale unlock that had been marked `is_unlockable` for releases without a trigger. **Rematch entirely removed** at user request — game-over screen keeps only `[Enter/Q] Menu` and `[H] History`; players who want to play again use the menu. **+30 regression tests** (661 → 691).
+
+### Fixed
+
+- **`src/belote/ai.py::_hard_special` + `_hard_bid` (R1, MED) — AI bidding now honors zero-rank boss flags.** Pre-3.9.3 the heuristic summed raw `card_points` even when `jacks_zero` / `aces_zero` / `kings_zero` / `tens_zero` / `ban_clubs` were active, so the AI overbid Tout Atout on a jack-heavy hand under Le Sauvage even though those jacks would score 0. The fix routes evaluation through the new public `scoring.card_points_with_modifiers(card, trump, bm)` helper (a thin wrapper over the existing `_card_points_with_zero_ranks` — same canonical zero-rank logic the live HUD and final scoring use). Honor-counting in the regular-suit branch also drops a rank if its boss flag is active. Regression: `tests/test_ai.py::test_hard_ai_does_not_bid_ta_when_jacks_zero_suppresses_jacks`.
+- **`src/belote/game.py::_record_belote_announcement` + new `GameState.belote_trump` field (R2, LOW) — L'Anarchie preserves rebelote across mid-belote trump rotation.** When trump rotates after trick 2/4/6 (`dynamic_trump`), a K-trump played in trick 2 and Q-of-original-trump in trick 3 would silently drop the rebelote because the K/Q match used `card.suit == current_trump`. The fix captures the trump at first-belote into a new `belote_trump: Suit | None` GameState field (mirrors the existing `belote_announcer` pattern) and matches the rebelote K/Q against the captured suit. Regression: `tests/test_belote.py::test_anarchie_rebelote_survives_cross_rotation_play` + non-rotation sanity test.
+- **`src/belote/belatro/ui/hud.py::BelAtroHUD.render` + `_render_compact` (R3, LOW) — HUD score line gated under La Compétition boss.** The live running total (sequential trick-point sum) diverges from the final score under `separate_scoring` (which picks per-seat max). The HUD now shows a "Compétition: score par siège — total final caché" disclaimer instead of a misleading running total when this boss is active.
+- **`src/belote/belatro/items/jokers/economy.py::LeBanquier` (R4, LOW) — bonus cash now suppressed on failed rounds and on EW-taker rounds.** Description says "Earn $1 for every 10 card points you score above the Blind target"; that framing presumes NS held a successful contract. Pre-3.9.3 the joker paid out unconditionally — even on chute, even when EW was taker. Now gates on `not breakdown.is_failed and taker_seat in (SOUTH, NORTH)`. Other on-round-end jokers (LAvare, LeFantome, LaSentinelle, LAccumulateur, LaSentinelleP) were audited and intentionally remain ungated — their descriptions are state-based (cards in hand, jack never used to win, etc.), not win-conditional.
+
+### Changed
+
+- **`src/belote/belatro/items/base.py::Voucher` + `belatro/items/vouchers.py` + `belatro/run/shop.py` (R5) — voucher idempotency guard relocated from `Shop._apply_item` into the `Voucher` base class.** Subclasses now implement `_apply_once(run)`; the base's `apply(run)` consults `run._applied_voucher_ids` and short-circuits a second invocation. Any future caller (replay reconstruction, deck-builder preview, hypothetical save/load) inherits the same protection automatically — pre-3.9.3 the guard only fired when the shop was the call site, so a different caller would silently double-stack `+=` vouchers (LaTelescope, LaDoubleDonne, LesCartesDorees, LeCouteau). Regression: `tests/belatro/test_voucher_idempotency.py::test_direct_voucher_apply_is_idempotent_without_shop`.
+- **`src/belote/belatro/ui/hud.py` (R7) — every bare `print()` call batched into one `sys.stdout.write` + `flush`** per render entry point (`render`, `_render_compact`, `render_joker_pip_strip`, `render_synergy_tooltip`). ~9 fewer syscalls per BelAtro HUD frame. Mirrors the canonical `render.py:1002` pattern.
+- **`src/belote/ai.py:627` (R6) — comment fix.** Said "prefer keeping high value cards if not winning" but the code adds points to the play-score (i.e. biases toward *playing* high cards). Rewritten as "Small per-card tiebreaker: when win/loss heuristics are otherwise equal, slightly bias toward playing the higher-value card."
+
+### Added
+
+- **`src/belote/ui/render.py` (Phase 6) — diff-based render emit.** `display()` now compares each frame's per-row line list against the previously committed frame and writes only the rows that actually changed. Idle re-renders (polling input between keystrokes, hovering on a card without moving) collapse from ~28 row writes to zero. New module-level `_last_emitted_lines` baseline; reset on layout change (via the existing `_last_render_key` invalidation), theme change (via the existing `theme_manager.register_callback(clear_card_cache)` callback — `clear_card_cache` now also clears `_card_back` LRU + the diff baseline), and explicit `display(state, force=True)`. Escape hatch: `BELOTE_NO_DIFF=1`. The full `render()` string contract is unchanged — tests calling `render(state)` directly still get the complete frame. Regression: `tests/test_render_diff.py` (6 tests).
+- **`src/belote/scoring.py::card_points_with_modifiers` (public)** — thin wrapper exposing the existing `_card_points_with_zero_ranks` for callers outside `scoring.py` (notably `ai.py` for R1).
+- **`src/belote/game.py::GameState.belote_trump: Suit | None`** — new field set when `belote_tracker[0]` first flips True, read by the rebelote check (R2).
+- **`src/belote/belatro/core/run_state.py::BelAtroRun._recent_boss_ids: list[str]` (Phase 5) — endless-mode boss variety guard.** The boss selector in `belatro/main.py` now suppresses immediate boss repeats in endless by rerolling against the last-2 window (capped at 8 reroll attempts to never loop on degenerate pools / monkeypatched single-boss tests). Normal-run boss selection is unchanged — variety is only enforced when `run.endless` is True. Regression: `tests/belatro/test_endless.py::test_recent_boss_window_is_bounded_to_two`.
+- **`src/belote/belatro/progression/unlocks.py::UnlockTracker._handle_declaration` (Phase 8) — Quinte Royale now unlocks on a Quinte announcement.** The Legendary joker was marked `is_unlockable = True` in `annonces.py:71` for several releases but had no path to actually unlock — `_handle_round_end` never set the flag, so the joker was filtered out of every shop pool. `UnlockTracker.on_event` now also dispatches `DeclarationScoredEvent`; when NS announces a sequence ≥ 100 pts, `quinte_royale` unlocks and the pending-announcement banner fires. Regression: `tests/belatro/test_progression.py::test_quinte_declaration_unlocks_quinte_royale` + negative tests (short sequence / opponent quinte).
+- **`src/belote/gameflow.py::_undo_pop_to_south` + visible undo banner (Phase 7b user request).** Pressing `Z` previously popped one history-stack entry — but the stack records *every* play including AI moves, so a Z after the AI finished a trick landed on an AI mid-trick state, and the AI re-played deterministically with no visible effect. The new helper pops until the restored state has `turn == SOUTH` (the user's actual prior decision point), bounded by `stack_base` so undo can't cross round boundaries. After each successful pop, `announce("↶ Undo", duration=0.8, reader=reader)` paints a 0.8 s banner before the rolled-back position is redrawn so the player sees the undo take effect. Same UX applied to the bidding-undo path. Regression: `tests/test_undo.py::test_undo_pop_to_south_skips_intermediate_ai_states` + 2 boundary tests.
+
+### Removed
+
+- **Rematch feature (user request).** `src/belote/main.py` no longer offers `[R] Rematch` on the game-over screen; the only post-game choices are `[Enter/Q] Menu` and `[H] History`. The `rematch` variable, the conditional-menu-skip flag, and the dedicated reset path are all gone. `src/belote/ui/prompts.py::show_help` line `"[R] Rematch (Game Over)"` deleted.
+
+### Audit verdict — verified clean, false positives caught
+
+Six Explore agents flagged a number of "critical" issues that were verified against the actual code and rejected:
+
+1. **Corrupted jokers (Le Traître / Le Démon / L'Égoïste / L'Agent Double) using `event.winner == Seat.SOUTH` instead of team scope** — intentional design. The class names and descriptions ("partner is irrelevant", "partner plays for opponents", "partner throws one trick per round") explicitly mark these as themed sabotage jokers. South-only is the design contract.
+2. **Tout Streak streak persistence at `main.py:367-369` being "dead code"** — false. Verified at `round_driver.py:121-123`: `card_enhancements` is merged into `state._joker_state` at the start of every round, so the persisted `tout_streak_streak` flows back in. The persistence works.
+3. **`_card_back` LRU cache going stale on theme change** — false. The cache is keyed by `theme_name` so a new theme produces a new key and a fresh render; old entries are LRU-evicted naturally. (3.9.3 still adds `_card_back.cache_clear()` to `clear_card_cache()` for memory hygiene since the diff-layer change now invalidates the frame baseline on theme change too — but the original "stale render" concern was wrong.)
+4. **Negative-edition jokers "bypassing" the slot check** — intentional. `_can_accept` at `shop.py:152-154` returns True for Negative jokers by design; that's the whole point of the Negative edition.
+5. **The Sun (Tout Atout) planet firing regardless of taker** — false. The parent block at `belatro/core/scoring.py:198+` gates on `event.winner in _NS_TEAM` already.
+6. **BelAtro HUD `print()` calls causing "torn frames"** — theoretical only. Python stdout is single-threaded line-buffered; a bare `print()` is atomic per call in a TTY. We batched anyway (R7) as a micro-perf win, but there was no visual bug.
+7. **L'Anarchie rebelote always broken** — partially false. Within the standard sequence (K then Q in the same trick or in trick 1+2 before the first rotation), rebelote already worked. Only the cross-rotation case was real (fixed as R2).
+8. **`clear_card_cache()` being "incomplete"** — cosmetic at worst. Both LRU caches are theme-keyed, so staleness is impossible.
+
+The "fake risky" agent finding (jokers in `risky.py` / `shaper.py` needing `is_failed` gates) cited files that don't exist — the real joker files are `annonces` / `coinche` / `contract` / `corrupted` / `economy` / `hand_comp` / `trick_timing` + `partner_jokers/{passive,shaper}`. Audit re-done against the actual files; only LeBanquier needed gating (R4).
+
+### Performance verdict
+
+- Benchmark smoke: 203–235 rounds/sec end-to-end (was 235 pre-3.9.3; well within budget, variance is system load).
+- New render diff layer: idle re-render byte count drops to < 25% of the first frame (regression test pins this).
+- No measured hotspot in scoring, AI decision, or trick-play paths. The 3.6 / 3.7.1 / 3.8.0 audits already covered the obvious cost centers.
+
+### Internal
+
+- **Tests**: 661 → 691 (+30). R1 (×1), R2 (×2), R4 (×3), R5 (×2), Phase 6 (×6), Phase 5 (×6), Phase 7b (×3), Phase 8 (×7).
+- **Strict gates**: pytest 691/691 green; benchmark smoke green.
+- **Version markers bumped**: `pyproject.toml`, `src/belote/__init__.py`.
+- **Plan file**: `/home/mrrobot/.claude/plans/bug-hunt-code-performance-mutable-blanket.md`.
+
+
 ## [3.9.0] - 2026-05-14
 
 Comprehensive bug-hunt, logic, and performance audit pass. Three parallel Explore agents covered the classic engine (`game.py` / `scoring.py` / `ai.py` / `gameflow.py` / `deck.py`), the BelAtro engine (`round_driver.py` / `modifier_patch.py` / `event_bus.py` / `belatro/core/scoring.py` / `boss.py` / `run_state.py` / `shop.py` / `belatro/main.py`), and the items catalogue + UI hot paths (`registry.py` + every joker / planet / tarot / voucher + `render.py` / `hud.py` / shop UI). Every load-bearing claim was spot-checked against the current code. **One real bug** (LOW), **one feature gap** filled, and a defensive cosmetic cleanup. Performance verdict: no measured hotspot — prior 3.6 / 3.7.1 / 3.8.0 audits already addressed the obvious paths. All 21 boss modifiers, 36 jokers, 8 planets, 12 tarots, 12 vouchers verified wired end-to-end. **+6 regression tests** (655 → 661). Plan file at `/home/mrrobot/.claude/plans/bug-hunt-code-performance-wise-puzzle.md`.

{belote_cli-3.9.0 → belote_cli-3.9.3}/DEVELOPMENT.md

@@ -84,17 +84,27 @@ PYTHONPATH=src mypy --strict src/
 # Linting (0 violations expected)
 ruff check src/ tests/
 
-# Full test suite (661 tests expected)
+# Full test suite (691 tests expected)
 PYTHONPATH=src pytest
 ```
 
-Current baseline (3.9.0):
+Current baseline (3.9.3):
 
-- **661 tests** passing (3.8.2 had 655; +6 in 3.9.0: yes_no EOF, NO_COLOR ×4, benchmark smoke).
-- 3.9.0 ships a clean three-agent audit pass (classic engine / BelAtro engine / items+UI). Confirmed bugs: one (LOW) — `BelAtroAnnounce.yes_no()` hung on `Key.EOF`, fixed in `src/belote/belatro/ui/announce.py:98`. New feature: `NO_COLOR` env-var support in `src/belote/ansi.py`. Cosmetic: deduped seat-order computation in `scoring.py` tie-break helpers. Tooling: `scripts/benchmark.py` gains an end-to-end `drive_round` rounds/sec probe and a `--smoke` flag pinned by `tests/test_benchmark_smoke.py`. Performance verdict: no measured hotspot — prior L1/L2/L3/D-pass audits already addressed the obvious paths. All 21 boss modifiers, 36 jokers, 8 planets, 12 tarots, 12 vouchers wired end-to-end. Plan file at `/home/mrrobot/.claude/plans/bug-hunt-code-performance-wise-puzzle.md`.
+- **691 tests** passing (3.9.0 had 661; +30 in 3.9.3 across R1/R2/R4/R5 regressions + 3 new test files: `test_render_diff.py`, `test_endless.py`, expanded `test_progression.py` / `test_undo.py` / `test_voucher_idempotency.py` / `test_phase2_content.py`).
+- 3.9.3 ships a multi-agent audit pass (six Explore agents — three broad-sweep + three targeted deep-dives on AI, scoring edge cases, per-joker mechanics, endless mode, meta-progression). **8 false positives caught and documented** (corrupted-joker seat semantics intentional, ToutStreak persistence working via `card_enhancements`, `_card_back` LRU theme-keyed, etc.). **Six real fixes (R1–R7)** plus three larger phases (render-diff layer, endless boss-variety guard, Quinte Royale unlock). **Rematch removed** at user request — game-over screen now `[Enter/Q] Menu  [H] History` only. Headline changes:
+  - **R1 — AI bidding zero-rank awareness** (`src/belote/ai.py::_hard_special` / `_hard_bid`): new public `scoring.card_points_with_modifiers(card, trump, bm)` helper threads the same canonical zero-rank logic the live HUD uses into the AI's bid evaluation; AI no longer overbids Tout Atout on jack-heavy hands under Le Sauvage. Honor-counting in regular-suit branch also boss-aware.
+  - **R2 — L'Anarchie rebelote preservation** (`src/belote/game.py:919-920` + new `GameState.belote_trump: Suit | None` field): rebelote check matches against the captured belote trump, not `state.trump`, so a K-trump in trick 2 + Q in trick 3 still fires rebelote across the post-trick-2 rotation.
+  - **R5 — voucher idempotency relocated to `Voucher.apply()`** (`src/belote/belatro/items/base.py`): subclasses now implement `_apply_once(run)`; the base wrapper consults `run._applied_voucher_ids` so any future caller (replay, save/load) gets idempotency, not just the shop.
+  - **Phase 6 — diff-based render emit** (`src/belote/ui/render.py::display`): idle re-renders drop from ~28 row writes to zero by diffing the post-vcenter line list against `_last_emitted_lines`. Layout/theme changes invalidate the baseline automatically. `BELOTE_NO_DIFF=1` escape hatch.
+  - **Phase 5 — endless boss-variety guard** (`belatro/main.py:285+`): in endless, reroll if the picked boss is in the last-2 window (`run._recent_boss_ids`).
+  - **Phase 7b — undo improvements** (`gameflow.py::_undo_pop_to_south`): `Z` now pops past AI snapshots to the player's actual prior decision point and displays a 0.8 s "↶ Undo" banner so the action is visible.
+  - **Phase 8 — Quinte Royale unlock** (`belatro/progression/unlocks.py::_handle_declaration`): the Legendary joker was marked `is_unlockable` but had no path to actually unlock; `UnlockTracker.on_event` now dispatches `DeclarationScoredEvent` and grants on NS sequence ≥ 100 pts.
+  Performance verdict: 203–235 rounds/sec end-to-end (unchanged); render-diff idle byte count < 25% of full frame. Plan file at `/home/mrrobot/.claude/plans/bug-hunt-code-performance-mutable-blanket.md`.
 
 Past baselines:
 
+- 3.9.0 shipped a clean three-agent audit pass (classic engine / BelAtro engine / items+UI). One LOW bug — `BelAtroAnnounce.yes_no()` hung on `Key.EOF`. Added `NO_COLOR` env-var support and the `--smoke` benchmark flag. Plan file at `/home/mrrobot/.claude/plans/bug-hunt-code-performance-wise-puzzle.md`.
+
 - 3.8.2 completes the five-agent audit pass. Final hardening includes Tout Atout streak persistence in BelAtro, Quinte trigger refinement, belote-pair timing fixes for jokers, and declaration scoring correctness for carrés and long sequences.
 - Performance: test suite speed increased by mocking `interruptible_sleep`.
 - Regression coverage maintained at 100% for game-logic modules.

{belote_cli-3.9.0 → belote_cli-3.9.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: belote-cli
-Version: 3.9.0
+Version: 3.9.3
 Summary: A 4-player terminal card game
 Project-URL: Homepage, https://github.com/ElysiumDisc/belote
 Project-URL: Repository, https://github.com/ElysiumDisc/belote
@@ -254,7 +254,7 @@ belote/
 │   ├── input.py       # Platform-dispatched key reader and interruptible sleep
 │   ├── stats.py       # Global and session statistics tracking
 │   └── rules.py       # Game rules content
-├── tests/             # Comprehensive test suite (661 tests)
+├── tests/             # Comprehensive test suite (691 tests)
 ├── scripts/           # Performance benchmarks
 ├── pyproject.toml      # Build system and dev dependencies (ruff/mypy)
 ├── LICENSE             # MIT License
@@ -270,14 +270,14 @@ belote/
 PYTHONPATH=src pytest
 ```
 
-Currently **661 tests** passing with 100% coverage on game-logic modules (3.9.0).
+Currently **691 tests** passing with 100% coverage on game-logic modules (3.9.3).
 
 ## Technical Integrity
 
 The codebase is strictly validated with the following tools:
 - **mypy**: 0 errors (strict type safety)
 - **ruff**: 0 violations (linting & formatting)
-- **pytest**: 661/661 passed
+- **pytest**: 691/691 passed
 - **Functional Architecture**: Purely immutable state transitions using `dataclasses.replace`
 - **Performance**: High-efficiency rendering and sub-millisecond AI decision times (see `scripts/benchmark.py`)
 

{belote_cli-3.9.0 → belote_cli-3.9.3}/README.md

@@ -211,7 +211,7 @@ belote/
 │   ├── input.py       # Platform-dispatched key reader and interruptible sleep
 │   ├── stats.py       # Global and session statistics tracking
 │   └── rules.py       # Game rules content
-├── tests/             # Comprehensive test suite (661 tests)
+├── tests/             # Comprehensive test suite (691 tests)
 ├── scripts/           # Performance benchmarks
 ├── pyproject.toml      # Build system and dev dependencies (ruff/mypy)
 ├── LICENSE             # MIT License
@@ -227,14 +227,14 @@ belote/
 PYTHONPATH=src pytest
 ```
 
-Currently **661 tests** passing with 100% coverage on game-logic modules (3.9.0).
+Currently **691 tests** passing with 100% coverage on game-logic modules (3.9.3).
 
 ## Technical Integrity
 
 The codebase is strictly validated with the following tools:
 - **mypy**: 0 errors (strict type safety)
 - **ruff**: 0 violations (linting & formatting)
-- **pytest**: 661/661 passed
+- **pytest**: 691/691 passed
 - **Functional Architecture**: Purely immutable state transitions using `dataclasses.replace`
 - **Performance**: High-efficiency rendering and sub-millisecond AI decision times (see `scripts/benchmark.py`)
 

{belote_cli-3.9.0 → belote_cli-3.9.3}/pyproject.toml

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

{belote_cli-3.9.0 → belote_cli-3.9.3}/src/belote/__init__.py

@@ -1,3 +1,3 @@
-__version__ = "3.9.0"
+__version__ = "3.9.3"
 
 __all__ = ["__version__"]

{belote_cli-3.9.0 → belote_cli-3.9.3}/src/belote/ai.py

@@ -16,6 +16,7 @@ from .game import (
     legal_cards,
     partner,
 )
+from .scoring import card_points_with_modifiers
 
 # trick_rank(Card(trump, Rank.NINE), trump) == 8 + 6 == 14 for any trump
 _NINE_TRUMP_RANK = 14
@@ -249,12 +250,25 @@ class AIPlayer:
         TA: every card scores on the trump scale; threshold against the average
             taker total (~62 raw). Plus a Jack-count bonus.
         SA: every card scores on the non-trump scale; flat-Aces hand favored.
+
+        3.9.3: card values are evaluated through `card_points_with_modifiers`
+        so active zero-rank bosses (jacks_zero / aces_zero / kings_zero /
+        tens_zero / ban_clubs) suppress those ranks in the bid heuristic.
+        Pre-3.9.3 the raw `card_points` totals made the AI overbid TA on a
+        jack-heavy hand under Le Sauvage even though those jacks would score
+        zero in actual play.
         """
-        ta_pts = sum(card_points_fn(c, Suit.TOUT_ATOUT) for c in hand)
-        jack_bonus = sum(1 for c in hand if c.rank == Rank.JACK) * 6  # Jacks dominate TA
+        bm = state.boss_modifiers
+        ta_pts = sum(card_points_with_modifiers(c, Suit.TOUT_ATOUT, bm) for c in hand)
+        # The Jack-count bonus is the AI's TA strength signal — drop it if
+        # jacks are suppressed.
+        jack_bonus = (
+            0 if bm.jacks_zero
+            else sum(1 for c in hand if c.rank == Rank.JACK) * 6
+        )
         ta_score = ta_pts + jack_bonus
 
-        sa_pts = sum(card_points_fn(c, None) for c in hand)
+        sa_pts = sum(card_points_with_modifiers(c, None, bm) for c in hand)
         # Long suits are bad under SA — opponents won't follow your suit.
         long_suit_penalty = sum(max(0, n - 3) ** 2 for n in lengths.values()) * 4
         sa_score = sa_pts - long_suit_penalty
@@ -487,10 +501,19 @@ class AIPlayer:
             if c.suit in suit_cards:
                 suit_cards[c.suit].append(c)
 
+        bm = state.boss_modifiers
         for suit in card_suits:
             trump_cards = suit_cards[suit]
-            honor_count = sum(1 for c in trump_cards if c.rank in (Rank.JACK, Rank.NINE, Rank.ACE))
-            point_total = sum(card_points_fn(c, suit, self._se) for c in trump_cards)
+            # Honors are J/9/A; drop a rank from the count if it's zeroed by a
+            # boss flag (3.9.3 — honor-counting was previously boss-blind).
+            def _is_honor(c: Card) -> bool:
+                if c.rank == Rank.JACK and bm.jacks_zero:
+                    return False
+                if c.rank == Rank.ACE and bm.aces_zero:
+                    return False
+                return c.rank in (Rank.JACK, Rank.NINE, Rank.ACE)
+            honor_count = sum(1 for c in trump_cards if _is_honor(c))
+            point_total = sum(card_points_with_modifiers(c, suit, bm) for c in trump_cards)
 
             suit_scores[suit] = point_total * 0.5 + honor_count * 3
 
@@ -601,7 +624,10 @@ class AIPlayer:
         """Score a card play decision with advanced heuristics."""
         score = 0.0
         points = card_points_fn(card, trump, self._se)
-        # Base: card point value (prefer keeping high value cards if not winning)
+        # Small per-card tiebreaker: when win/loss heuristics are otherwise
+        # equal, slightly bias toward playing the higher-value card. The
+        # 0.1 coefficient keeps this strictly subordinate to the win/loss
+        # bonuses (~+5 to ~-9) below.
         score += points * 0.1
 
         if not trick:

{belote_cli-3.9.0 → belote_cli-3.9.3}/src/belote/belatro/core/run_state.py

@@ -99,13 +99,18 @@ class BelAtroRun:
 
     # ── Idempotency guard for voucher.apply() ──────────────
     # Several vouchers (LaTelescope, LaDoubleDonne, LesCartesDorees, LeCouteau)
-    # use `+=` against run-level counters in their `apply()`. Today the only
-    # call site is `Shop.buy_item`, which fires apply() exactly once per
-    # purchase. This set lets the shop short-circuit re-application if a
-    # future save/load path ever re-invokes apply() on a voucher already in
-    # `vouchers` — preventing silent double-stacking.
+    # use `+=` against run-level counters in their `apply()`. The guard now
+    # lives on `Voucher.apply()` (3.9.3 R5) so any caller — shop, replay, a
+    # future save/load round-trip — gets the same protection automatically.
     _applied_voucher_ids: set[str] = field(default_factory=set)
 
+    # ── Recent-boss tracker (3.9.3 Phase 5) ────────────────
+    # Used by the BelAtro main loop to suppress immediate boss repeats in
+    # endless mode. The deque holds at most 2 recent boss ids; the selector
+    # rerolls if its pick is in this window. Empty by default — bounded so
+    # the run-state JSON snapshot stays small.
+    _recent_boss_ids: list[str] = field(default_factory=list)
+
     def consume(self, item: Any, context: object = None) -> None:
         """Centralised consumable activation.
 

{belote_cli-3.9.0 → belote_cli-3.9.3}/src/belote/belatro/items/base.py

@@ -144,6 +144,19 @@ class Tarot(ABC):
 
 
 class Voucher(ABC):
+    """Permanent run-level upgrade.
+
+    Subclasses implement `_apply_once(run)` for the actual effect. The base
+    class wraps it with `apply(run)` which consults `run._applied_voucher_ids`
+    to guarantee a no-op on a second invocation — important for vouchers that
+    use `+=` semantics (LaTelescope's `+=` on joker_slots, LeCouteau's `+=`
+    on consumable_slots, etc.) that would silently double-stack on a future
+    save/load or replay round-trip.
+
+    3.9.3 — guard relocated here from `Shop._apply_item` so any future
+    caller of `voucher.apply()` (replays, deck-builder previews, etc.)
+    inherits the same protection.
+    """
     id: str
     name: str
     description: str
@@ -151,9 +164,16 @@ class Voucher(ABC):
     rarity: Rarity = Rarity.COMMON
     purchased: bool = False
 
-    @abstractmethod
     def apply(self, run: BelAtroRun) -> None:
-        """Apply permanent effect to the run."""
+        """Idempotent wrapper. Calls `_apply_once` only the first time per run."""
+        if self.id in run._applied_voucher_ids:
+            return
+        run._applied_voucher_ids.add(self.id)
+        self._apply_once(run)
+
+    @abstractmethod
+    def _apply_once(self, run: BelAtroRun) -> None:
+        """Subclass-defined permanent effect. Called exactly once per run."""
         ...
 
 

{belote_cli-3.9.0 → belote_cli-3.9.3}/src/belote/belatro/items/jokers/economy.py

@@ -15,11 +15,18 @@ class LeBanquier(Joker):
     cost = 7
 
     def on_round_end(self, event: RoundEndEvent, state: dict[str, Any]) -> JokerResult | None:
-        points = (
-            event.breakdown.taker_total
-            if event.taker_seat in (Seat.SOUTH, Seat.NORTH)
-            else event.breakdown.defender_total
-        )
+        # Description: "Earn $1 for every 10 card points you score above the
+        # Blind target." That framing presumes NS won the contract — under a
+        # chute the points aren't "scored" in the meaningful sense, so the
+        # bonus doesn't apply. 3.9.3.
+        if event.breakdown.is_failed:
+            return None
+        # Bonus only makes sense when NS held the contract — defender points
+        # under chute are computed differently and don't represent "above
+        # target" score.
+        if event.taker_seat not in (Seat.SOUTH, Seat.NORTH):
+            return None
+        points = event.breakdown.taker_total
         # Use a dynamic threshold from state or default to 80
         threshold = state.get("target_score", 80)
         bonus = max(0, (points - threshold) // 10)

{belote_cli-3.9.0 → belote_cli-3.9.3}/src/belote/belatro/items/vouchers.py

@@ -13,7 +13,7 @@ class LaTelescope(Voucher):
     name = "La Télescope"
     description = "Permanent: Earn +$1 bonus after each round."
 
-    def apply(self, run: BelAtroRun) -> None:
+    def _apply_once(self, run: BelAtroRun) -> None:
         run.economy.bonus_per_round += 1
 
 
@@ -22,7 +22,7 @@ class LaVoute(Voucher):
     name = "La Voûte"
     description = "Earn $1 per $5 held at round end, max $5/round."
 
-    def apply(self, run: BelAtroRun) -> None:
+    def _apply_once(self, run: BelAtroRun) -> None:
         # Use max() rather than `=` so LaVoute can't wipe additive bonuses
         # already granted by LesCartesDorees (which is `+=` against the same
         # fields). LaVoute defines a floor of (rate=1, cap=5).
@@ -35,7 +35,7 @@ class LeGrimoire(Voucher):
     name = "Le Grimoire"
     description = "Shop always stocks at least one Tarot card. Permanent."
 
-    def apply(self, run: BelAtroRun) -> None:
+    def _apply_once(self, run: BelAtroRun) -> None:
         run.guarantee_tarot_in_shop = True
 
 
@@ -44,7 +44,7 @@ class LaDoubleDonne(Voucher):
     name = "La Double Donne"
     description = "Gain one extra Joker slot (default 5 → 6)."
 
-    def apply(self, run: BelAtroRun) -> None:
+    def _apply_once(self, run: BelAtroRun) -> None:
         run.joker_slots += 1
 
 
@@ -53,7 +53,7 @@ class LEncyclopedie(Voucher):
     name = "L'Encyclopédie"
     description = "Know your AI partner's bidding tendency before each round. Permanent."
 
-    def apply(self, run: BelAtroRun) -> None:
+    def _apply_once(self, run: BelAtroRun) -> None:
         run.show_partner_bid_tendency = True
 
 
@@ -62,7 +62,7 @@ class LesCartesDorees(Voucher):
     name = "Les Cartes Dorées"
     description = "Permanently gain +1 interest rate and +5 interest cap."
 
-    def apply(self, run: BelAtroRun) -> None:
+    def _apply_once(self, run: BelAtroRun) -> None:
         run.economy.interest_rate += 1
         run.economy.max_interest += 5
 
@@ -72,7 +72,7 @@ class LeCouteau(Voucher):
     name = "Le Couteau"
     description = "Gain one extra consumable slot."
 
-    def apply(self, run: BelAtroRun) -> None:
+    def _apply_once(self, run: BelAtroRun) -> None:
         run.consumable_slots += 1
 
 
@@ -81,7 +81,7 @@ class LaBalance(Voucher):
     name = "La Balance"
     description = "If both teams tie in card points, your team wins the round automatically."
 
-    def apply(self, run: BelAtroRun) -> None:
+    def _apply_once(self, run: BelAtroRun) -> None:
         run.tie_breaks_for_taker = True
 
 
@@ -91,7 +91,7 @@ class LaSurcoinche(Voucher):
     description = "Unlocks the Surcoinche contract (AI may surcoinche when you coinche)."
     is_unlockable = True
 
-    def apply(self, run: BelAtroRun) -> None:
+    def _apply_once(self, run: BelAtroRun) -> None:
         run.surcoinche_unlocked = True
 
 
@@ -100,7 +100,7 @@ class LeCarnet(Voucher):
     name = "Le Carnet"
     description = "You see partner's full hand. +1 Mult each time YOU (South) win a trick."
 
-    def apply(self, run: BelAtroRun) -> None:
+    def _apply_once(self, run: BelAtroRun) -> None:
         run.show_north_hand = True
 
 
@@ -110,7 +110,7 @@ class CapotInsurance(Voucher):
     description = "One-shot: if you chute next round, the cash penalty is halved."
     cost = 8
 
-    def apply(self, run: BelAtroRun) -> None:
+    def _apply_once(self, run: BelAtroRun) -> None:
         run.capot_insurance = True
 
 
@@ -120,7 +120,7 @@ class TierceForge(Voucher):
     description = "Spend 3 Tierce charges in the shop to level up a Planet contract for free."
     cost = 6
 
-    def apply(self, run: BelAtroRun) -> None:
+    def _apply_once(self, run: BelAtroRun) -> None:
         # No-op at apply time. Owning the voucher enables `run.forge_tierce`
         # which the shop UI calls when the player chooses to spend charges.
         pass

{belote_cli-3.9.0 → belote_cli-3.9.3}/src/belote/belatro/main.py

@@ -288,8 +288,24 @@ class BelAtroGame:
                 # determinism fix the 3.2.0 release applied to shop generation
                 # and the three RNG-using tarots. Boss assignment was the last
                 # unseeded RNG site in the BelAtro round flow.
-                boss_cls = self.run._get_rng().choice(ALL_BOSS_MODIFIERS)
+                #
+                # 3.9.3 (Phase 5): in endless mode, suppress immediate boss
+                # repeats by rejecting a pick that's in the last-2 window.
+                # We cap the reroll attempts so we never loop on a degenerate
+                # pool (e.g. tests that monkeypatch a single boss).
+                rng = self.run._get_rng()
+                recent = self.run._recent_boss_ids
+                boss_cls = rng.choice(ALL_BOSS_MODIFIERS)
+                if self.run.endless and len(ALL_BOSS_MODIFIERS) > 3:
+                    attempts = 0
+                    while boss_cls().id in recent and attempts < 8:
+                        boss_cls = rng.choice(ALL_BOSS_MODIFIERS)
+                        attempts += 1
                 boss = boss_cls()
+                # Update the recent-boss window (keep last 2).
+                recent.append(boss.id)
+                if len(recent) > 2:
+                    del recent[: len(recent) - 2]
                 BelAtroAnnounce.boss_reveal(boss, self.reader)
 
         # Boss-specific pre-round setup, driven by boss_modifiers flags rather

{belote_cli-3.9.0 → belote_cli-3.9.3}/src/belote/belatro/progression/unlocks.py

@@ -4,7 +4,7 @@ from typing import TYPE_CHECKING
 
 from belote.game import Seat
 
-from ..engine.event_bus import RoundEndEvent
+from ..engine.event_bus import DeclarationScoredEvent, RoundEndEvent
 from .save import Profile, SaveManager
 
 if TYPE_CHECKING:
@@ -40,12 +40,30 @@ class UnlockTracker:
 
         if isinstance(event, RoundEndEvent):
             dirty |= self._handle_round_end(event)
-
-        # Potentially more event handlers (e.g. for specific trick-based unlocks)
+        elif isinstance(event, DeclarationScoredEvent):
+            dirty |= self._handle_declaration(event)
 
         if dirty:
             self.save_manager.save_profile(self.profile)
 
+    def _handle_declaration(self, event: DeclarationScoredEvent) -> bool:
+        """3.9.3 Phase 8: unlock Quinte Royale (legendary joker) when NS
+        announces a Quinte. Pre-3.9.3 the joker was marked `is_unlockable`
+        but had no path to actually unlock, leaving it unreachable in the
+        shop pool.
+        """
+        if (
+            event.seat in (Seat.SOUTH, Seat.NORTH)
+            and event.declaration_type == "sequence"
+            and event.points >= 100
+            and self.profile.unlock("quinte_royale")
+        ):
+            self.pending_announcements.append(
+                "UNLOCKED: Quinte Royale (Legendary — announced a Quinte)"
+            )
+            return True
+        return False
+
     def _handle_round_end(self, event: RoundEndEvent) -> bool:
         dirty = False
 

{belote_cli-3.9.0 → belote_cli-3.9.3}/src/belote/belatro/run/shop.py

@@ -172,13 +172,11 @@ class Shop:
                 item.on_purchase(self.run)
         elif isinstance(item, Voucher):
             self.run.vouchers.append(item)
-            # Idempotency guard: several vouchers use `+=` in apply(); if a
-            # save/load round-trip ever re-invokes apply() on a voucher
-            # already in `vouchers`, bonuses would silently double. Track
-            # applied ids so re-apply is a no-op. The normal purchase path
-            # hits this exactly once.
-            if item.id not in self.run._applied_voucher_ids:
-                self.run._applied_voucher_ids.add(item.id)
-                item.apply(self.run)
+            # 3.9.3: idempotency guard relocated to Voucher.apply() itself,
+            # so any caller (shop, replay, future save/load) gets the same
+            # protection. The base wraps the subclass's `_apply_once` and
+            # consults `run._applied_voucher_ids` automatically. Calling
+            # apply() unconditionally is now safe.
+            item.apply(self.run)
         elif len(self.run.consumables) < self.run.consumable_slots:
             self.run.consumables.append(item)