belote-cli 3.7.1__tar.gz → 3.8.2__tar.gz

{belote_cli-3.7.1 → belote_cli-3.8.2}/CHANGELOG.md

@@ -5,6 +5,86 @@ 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.8.2] - 2026-05-14
+
+Final logic audit and performance hardening. This release addresses the remaining edge cases identified during the deep-dive audit, focusing on BelAtro joker persistence, declaration scoring correctness, and test suite optimization. All 655 tests passing.
+
+### Fixed
+
+- **`src/belote/belatro/main.py` (HIGH) — Tout Atout streak now persists between rounds.** Fixed a bug where `ToutStreak` state was lost on every round transition because it wasn't being "drained" into the run-level state. It now correctly persists in `BelAtroRun.card_enhancements`.
+- **`src/belote/belatro/items/jokers/annonces.py::QuinteRoyale` (MEDIUM) — Fixed trigger logic.** The joker previously armed on any declaration >= 100 points, including high-rank Carrés. It now correctly only arms on sequences of 5+ cards (Quintes).
+- **`src/belote/belatro/items/jokers/economy.py::LeNotaire` and `contract.py::LeRebelle` (MEDIUM) — Refined belote-pair timing.** These jokers now trigger on the `rebelote` (second card played) instead of the first. This ensures they only subtract the 20-point bonus once it has actually been awarded to the team.
+- **`src/belote/scoring.py::score_round` (MEDIUM) — Sequence scoring correctness.** Fixed a bug where sequences longer than 5 cards (e.g., 6 or 7 cards) were worth 0 points. They now correctly cap at 100 points (Quinte).
+- **`src/belote/scoring.py::get_declaration_points` (MEDIUM) — Carré scoring fix.** Fixed a logic bug where Carrés were always worth 0 points due to a rank-lookup type mismatch.
+- **`src/belote/scoring.py::_score_capot_outcome` (MEDIUM) — Capot/Zero-Final consistency.** Fixed a bug where the Capot reward did not respect the `no_dix_de_der` boss modifier. It now correctly drops the base reward by 10 points when the last-trick bonus is suppressed.
+- **`tests/test_gameflow.py` (PERF) — Mocked `interruptible_sleep` in tests.** Resolved a 4-second delay in the test suite by ensuring UI-centric sleeps are bypassed during unit testing.
+
+## [3.8.1] - 2026-05-14
+
+Bug-hunt + logic audit pass. Five parallel audit agents (BelAtro core, classic engine, BelAtro items/run/partner, UI layer, performance) ran across the codebase; verification turned 8 raw findings into **3 confirmed critical bugs**, **3 medium correctness fixes**, and **1 documentation typo**. Two agent claims (`_card_beats` under Tout Atout, `_compute_belote_points` 20-when-only-K-played) were refuted on re-trace and not changed — both are working as designed. **+5 regression tests** (650 → 655).
+
+### Fixed
+
+- **`src/belote/game.py::_resolve_trick_winner` (CRITICAL) — La Rupture no longer drifts between play_card and score_round.** Pre-3.8.1 `_resolve_trick_winner` derived the previous trick's winner via `trick_winner_seat(state.completed_tricks[-1], …)` — the RAW result. Meanwhile `compute_trick_winners` (the final-scoring authority) threads the *resolved* previous winner through the chain. On trick 3+, whenever Rupture flipped trick N-1, the two paths disagreed: `state.last_trick_winner` (and downstream HUD running totals, dix-de-der attribution) reported a winner that did NOT match the final scoring tally. Fixed by reading `state.last_trick_winner` (already stored as the resolved value). Regression test in `tests/belatro/test_boss_modifiers_integration.py::test_rupture_play_card_resolves_consistently_with_scoring`.
+- **`src/belote/belatro/engine/round_driver.py:135-148` (CRITICAL) — boss modifiers are now applied BEFORE `acc.trigger_round_start`.** Pre-3.8.1 the call order was `trigger_round_start` (which snapshots `state.boss_modifiers.no_dix_de_der` into `joker_state["no_dix_de_der"]`) → `boss.apply` (which patches the flag onto the live state). Any joker reading `state.get("no_dix_de_der", …)` (e.g. `trick_timing.py` last-trick scoring) saw the BossModifiers default `False` rather than the live boss flag — so the boss-aware joker code paths silently no-op'd on Le Zéro Final blinds. Fixed by reordering. Regression test in `tests/belatro/test_round_driver.py::test_boss_flags_applied_before_trigger_round_start`.
+- **`src/belote/belatro/engine/round_driver.py:393-401` (CRITICAL, La Rupture follow-on) — `TrickWonEvent.winner` now carries the resolved (Rupture-aware) seat.** Pre-3.8.1 the event was emitted with `winner = trick_winner_seat(last_trick, …)` (raw); under La Rupture every joker keyed on `team_of(event.winner) == 0` would credit the team that did NOT actually receive the trick in `score_round`. Fixed by emitting `winner = state.last_trick_winner`; `trick_winner_seat` import removed from the round driver.
+- **`src/belote/belatro/items/jokers/contract.py::LeRebelle` and `economy.py::LeNotaire` (HIGH) — belote-pair jokers no longer double-fire on `BeloteAnnouncedEvent`.** `round_driver.py` emits `BeloteAnnouncedEvent` twice per round (once when belote flips, once when rebelote flips). Pre-3.8.1 LeRebelle returned `times_mult=3.0` on both, yielding ×9 net Mult instead of ×3. LeNotaire awarded $10 instead of $5. Both now gate on `not event.is_rebelote` so the bonus fires once on the belote announce; the description ("Belote/Rebelote is worth …") matches the intent. Regression tests in `tests/belatro/test_phase2_content.py::test_le_rebelle_fires_once_per_belote_pair` and `…::test_le_notaire_pays_once_per_belote_pair`.
+- **`src/belote/belatro/items/jokers/corrupted.py::LAgentDouble` (HIGH) — partner-sabotage half of the joker now actually triggers.** Pre-3.8.1 the joker tracked `_sabotage_remaining` in joker_state, but the AI sabotage path (`ai.py:283`) keys on `state.boss_modifiers.agent_double_active`, which the joker never set. Result: the +4 Mult half worked but "Partner plays optimally for the opponents for 2 tricks" was a no-op. Fixed by mirroring `LeTraitre`'s wiring: `on_purchase` flags `run.agent_double_joker`; `round_driver` picks it up, flips `agent_double_active=True`, and populates `agent_double_tricks` with 2 random tricks (same precedence rule — boss agent_double takes priority). New field `BelAtroRun.agent_double_joker: bool`. Regression test in `tests/belatro/test_phase2_content.py::test_lagent_double_purchase_flags_run`.
+- **`src/belote/belatro/core/scoring.py:219,231,270` (MEDIUM, typing hardening) — `reward.get(…, 0)` defaults widened to `0.0` for the float-typed contract reward fields.** `honor_bonus` (Moon / Sans Atout), `bonus_mult_per_trick` (Sun / Tout Atout), and `coinche_multiplier` (Libra / Coinche) are declared `float` in `ContractReward` (3.7.1 BA-L1). The int-zero default propagated `int` through type inference at the consumer site, defeating part of the BA-L1 fix. Cosmetic at runtime, real for `mypy --strict` line of defense.
+- **`src/belote/ui/layout.py:39` and `render.py:637` (DOC TYPO) — "press T for full history" → "press H for full history".** The key was renamed from T to H prior to 3.8.0; the layout comment and the last-trick-sidebar comment in render still pointed at the stale binding. T now binds to Cycle Theme; H is the canonical history key (see `input.py:163-165`, `prompts.py:217`). Visible behavior change versus pre-May-2026 builds: if you reach for T expecting history, you'll cycle the theme instead.
+
+### Verified clean — audit findings rejected after source verification
+
+- **`game.py::_card_beats` under Tout Atout (HIGH claim)** — agent claimed off-suit cards could beat lead-suit under TA (e.g. J♦ beating lead 7♠). Re-traced: `is_trump_card` evaluates `card.suit == trump` where `trump == Suit.TOUT_ATOUT`. Since no actual card carries `suit=TOUT_ATOUT` (the enum's `is_card_suit()` returns `False` for it), the check yields `False` for both candidates and the function correctly falls through to `return card.suit == lead_suit`. Different-suit cards never win under TA. No change.
+- **`scoring.py::_compute_belote_points` 20-when-only-K-played (MEDIUM claim)** — agent flagged that `BELOTE_POINTS=20` is awarded when `belote_tracker[1]` is False. Reading `config.py`: `BELOTE_POINTS=20`, `REBELOTE_POINTS=40` — the design models the rebelote tier as a strict upgrade (40 total when both K and Q play, 20 partial credit when only one plays). Working as configured.
+
+### Internal
+
+- **Tests**: 650 → 655 (+5). Regression coverage for every CRITICAL/HIGH fix above.
+- **Strict gates**: pytest 655/655 green, mypy `--strict` 0 errors (78 files), ruff 0 violations.
+- **Version markers bumped**: `pyproject.toml`, `src/belote/__init__.py`.
+
+## [3.8.0] - 2026-05-13
+
+UI-cutoff pass, audit polish, and minor perf wins. The session began with a user-reported bug — the main-menu croissant art clipped at the top on certain terminal heights — and broadened into a full UI-fit overhaul (live "terminal too small" overlay, BelAtro screens rebuilt around vertical centering, shop action buttons relocated below the cards). A second three-Explore-agent audit ran across the classic engine, BelAtro mode, and render/AI hot paths: **no critical findings**, but three minor hardening items (zip-strict, voucher idempotency, all-pass-bidding test gap) and three modest perf wins shipped. **+15 regression tests** (635 → 650). Plan file at `/home/mrrobot/.claude/plans/i-want-to-fix-swirling-pelican.md`.
+
+### Fixed
+
+- **`src/belote/ui/menu.py:116` — classic main-menu croissant no longer clips at the top.** Pre-3.8.0 the guard read `if term_h < 42: return final_cup`, but the full content needs 41 art + 2 footer = 43 rows. At `term_h == 42` the croissant was rendered and the top row scrolled off the alt-screen; at 43 it sat flush against the top with zero margin. New threshold is derived from `len(get_cards_art()) + 1 + len(CUP_TEMPLATE) + 2 + 1` (= 44), so the croissant only shows when there is genuine room for it plus one row of breathing space.
+- **`src/belote/ui/main.py:115-123` — startup "terminal too small" hard-fail replaced with a live overlay.** Pre-3.8.0 a sub-80×32 terminal got `print()` + `sys.exit(1)` before the alt-screen was entered, polluting scrollback and offering no recovery. New `src/belote/ui/fit_guard.py::require_minimum` paints a centered "Resize to 80×32 (currently NN×MM) — Press Q to quit" inside the alt-screen, refreshes on SIGWINCH (the existing handler at `render.py:99` invalidates the size cache), and returns the moment the terminal is large enough. `FitAbortedError` raised on Q/EOF.
+- **BelAtro screens converted to a list-build + vcenter pattern; absolute-row writes removed.** `belatro/ui/{shop,menu,announce,collection,consumables}.py` previously pinned content to hardcoded `move(N, …)` rows (e.g. shop description at row 18, BelAtro art at rows 3-9, boss reveal at rows 10/13/15). New `src/belote/ui/layout.py::vcenter_lines(lines, term_h)` — extracted from `render.py:899-903` — pads top + bottom so every BelAtro screen centers vertically and never clips. `history.py` and `rules.py` (already responsive) only gain a `require_minimum` call at loop entry.
+- **`belatro/ui/shop.py::_render` — reroll / forge buttons moved BELOW the card row.** Pre-3.8.0 the bracket-text labels (`[ Reroll $5 ]`, `[ Forge x3/3 ]`) rendered at `card_start_row + 3` — mid-frame across the card art — and `_card_col`'s 18-cell spacing × 5+ columns overflowed at 80 cols when the forge slot was visible. New layout places the action strip on its own row directly below the cards, centered. No card frame width change, no inventory cap. `_card_col` now centers the card strip and tightens inter-card gap (down to 0) before any card would extend past `term_w - 2`.
+- **`src/belote/belatro/run/shop.py::_apply_item` — voucher idempotency guard (B1 audit finding, MINOR hardening).** `LaTelescope`, `LaDoubleDonne`, `LesCartesDorees`, `LeCouteau` use `+=` against `BelAtroRun` state in their `apply()`. The only call site is `Shop.buy_item`, which fires apply() exactly once per purchase — so the existing code was safe in practice. But a future save/load round-trip that re-invokes apply() on a voucher already in `run.vouchers` would silently double the bonus. New `BelAtroRun._applied_voucher_ids: set[str]` field; the shop checks-and-marks before each apply(). LaVoute's `max()` floor pattern is its own idempotency mechanism and is unchanged. 6 regression tests in `tests/belatro/test_voucher_idempotency.py`.
+
+### Changed
+
+- **`src/belote/ui/render.py::patch_trick_card` — HUD rebuild is now opt-in via `force_hud: bool = False` (P1).** Pre-3.8.0 every of the 32 card-play patches per round rebuilt the entire HUD bar at row 1, even though `_build_hud` reads `state.current_round_points` / `state.team_scores`, neither of which advance until `play_card` commits the completed trick (which the caller then re-renders via `display()`). New default skips the rebuild; pass `force_hud=True` when a caller knows HUD-affecting state has changed externally. Saves ~300 µs per round plus a chunk of ANSI bytes; preserves correctness because the next `display()` call refreshes the HUD anyway.
+- **`src/belote/ai.py::AIMemory` — partner_hand rebuild memoised on the same trick-progress key as void inference (P2).** Pre-3.8.0 every `decide_card()` call (32 × per round) cleared and rebuilt `partner_hand` from `state.hand_of(partner(self.seat))`, even though the partner's hand only changes when they play a card. New `last_partner_hand_key: tuple[int, int]` mirrors the existing `last_voids_key` pattern (`(completed_count, current_trick_len)`); skip rebuild on a no-op repeat call. Saves ~200 µs per round; reset properly on new round and mid-round undo (mirrors the existing void-cache reset paths).
+- **`src/belote/ai.py::_hard_bid` — pre-compute suit-bucketed hand in one pass (P4).** Pre-3.8.0 each of the four suit iterations re-filtered `hand` (twice for trump/honour counts, plus inner cross-suit counts) — 12 hand walks per bid evaluation. New `suit_cards: dict[Suit, list[Card]]` is built with a single `for c in hand` pass and reused. Readability win is bigger than the µs perf win on 8-card hands; pattern matches what `_special_bid` already does.
+- **`src/belote/scoring.py:298,301,313,316` — declaration tie-break zips upgraded to `strict=True` (C1).** Walks `ns_carres` / `ns_carre_seats` (and `ns_seqs` / `ns_seq_seats`) in lockstep with the parallel lists built at `scoring.py:274`. Today the invariant holds; `strict=True` defends against a future edit that breaks it silently.
+
+### Added
+
+- **`src/belote/ui/fit_guard.py` (new) — `require_minimum(reader, min_cols, min_rows)` + `FitAbortedError`.** Live overlay used by `main.py` (once at startup) and every BelAtro screen loop. Refreshes on SIGWINCH, dismisses automatically once the user resizes past the floor, raises `FitAbortedError` on Q / EOF for clean caller cleanup.
+- **`src/belote/ui/layout.py::vcenter_lines(lines, term_h)`** — pure helper extracted from `render.py:899-903`. Pads top + bottom so a list of lines sits centered in `term_h`; truncates if oversized. Used by every BelAtro screen and by classic `render()`.
+- **`tests/test_bidding_all_pass.py` (new, 5 tests)** — pins all-pass redeal edge cases beyond the basic `test_new_coverage.py::test_all_pass_redeal` smoke. Covers full state reset (bids / bidder_index / bidding_round / trump / taker), multi-redeal dealer rotation, the "round 2 + all pass" path that must redeal (not advance to a phantom round 3), and successful post-redeal bidding.
+- **`tests/belatro/test_voucher_idempotency.py` (new, 6 tests)** — pins the B1 guard contract.
+- **`tests/belatro/test_shop_empty_pools.py` (new, 4 tests)** — B2 audit gap: regression test for empty registry pools (degenerate Profile / full-unlock state). `_empty_pools` helper monkeypatches and bumps the registry generation so cached `get_available_*` views miss.
+
+### Verified clean — audit findings rejected after source verification
+
+Documented so the next cycle doesn't re-investigate:
+
+- **`render.py:807-809` "unconditional `legal_cards` call" (P3 candidate)** — the call IS inside `if state.phase == Phase.PLAYING and state.turn == Seat.SOUTH`; the perf agent misread the guard. No change needed.
+- **Tout Atout void-in-lead-suit discard logic (`game.py:560-578`, initial agent CRITICAL claim)** — verified correct per official rules: off-suit cards may be played when void but never win tricks. Comments and code agree.
+- **Memory-documented 3.6.0 / 3.7.1 fixes** (L'Accumulateur team check, Libra reachability via NS-taker coinche, synergy validation under `python -O`, event-bus handler isolation, `PatchedGameState` underscore narrowing) — all still in place; grep for `boss.id ==` returns zero hits in production paths.
+
+### Internal
+
+- **Tests**: 635 → 650 (+15). Three new test files (`test_bidding_all_pass.py` ×5, `test_voucher_idempotency.py` ×6, `test_shop_empty_pools.py` ×4).
+- **Strict gates**: pytest 650/650 green, mypy `--strict` 0 errors (78 files), ruff 0 violations.
+- **Version markers bumped**: `pyproject.toml`, `src/belote/__init__.py`.
+
 ## [3.7.1] - 2026-05-13
 
 Bug-hunt, performance, and logic audit pass plus the three items 3.6.0 deferred to 3.7.0. Three Explore agents ran in parallel against the documented false-positive catalogue. The classic-engine sweep returned **no novel findings** — the 3.4.x → 3.6.0 audits have absorbed the available correctness surface. The BelAtro layer produced **2 confirmed bugs** (one HIGH, one MEDIUM) and **1 polish item**. The deferred 3.7.0 items — `score_round` / `play_card` refactor, partner-joker test coverage, player-facing NS-taker surcoinche — all land here. **+36 regression tests** (599 → 635). Plan file at `/home/mrrobot/.claude/plans/bug-hunt-code-performance-sequential-map.md`.

{belote_cli-3.7.1 → belote_cli-3.8.2}/DEVELOPMENT.md

@@ -84,14 +84,19 @@ PYTHONPATH=src mypy --strict src/
 # Linting (0 violations expected)
 ruff check src/ tests/
 
-# Full test suite (635 tests expected)
+# Full test suite (655 tests expected)
 PYTHONPATH=src pytest
 ```
 
-Current baseline (3.7.1):
-- **mypy**: 0 errors (strict mode, 77 files)
-- **ruff**: 0 violations
-- **pytest**: 635 tests, 0 failures
+Current baseline (3.8.1):
+Current baseline (3.8.2):
+
+- **655 tests** passing.
+- 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.
+
+- 3.8.0 ships UI-fit fixes (croissant cutoff at term_h=42-43, BelAtro hardcoded-row clipping, live "terminal too small" overlay replacing the startup hard-fail, shop reroll/forge moved below cards) plus a fresh three-agent audit. Audit produced **no critical findings**; three minor hardening items (zip-strict in declaration tie-breaks, voucher idempotency guard, all-pass-bidding test gap) and three modest perf wins (skip HUD rebuild in `patch_trick_card`, memoise AI `partner_hand`, single-pass `_hard_bid` suit bucketing) shipped. **+15 regression tests** (635 → 650). Plan file at `/home/mrrobot/.claude/plans/i-want-to-fix-swirling-pelican.md`.
 - 3.7.1 lands the deferred 3.7.0 items plus a fresh audit pass. Three Explore agents ran in parallel against the documented false-positive catalogue. The classic-engine sweep returned no novel findings (3.4.x → 3.6.0 absorbed the surface); the BelAtro layer produced **BA-L2** (L'Accumulateur team→seat bug, HIGH) and **BA-L1** (`ContractReward` TypedDict float annotations, MEDIUM). Deferred items: **D1** — `score_round` and `play_card` extracted behind `_ScoringContext` / `_PlayContext` (zero test edits, behaviour-preserving); **D2** — `tests/belatro/test_partner_jokers.py` adds 26 tests, **100% coverage** for `passive` / `risky` / `shaper` partner-joker modules; **D3** — `prompt_surcoinche` callback on `RoundUICallbacks` plus NS-taker player-surcoinche path in `round_driver.py:268-283`. **+36 regression tests** (599 → 635). Plan file at `/home/mrrobot/.claude/plans/bug-hunt-code-performance-sequential-map.md`.
 - 3.6.0 lands a verified bug-hunt and refactor pass over the classic engine and the BelAtro roguelite layer. Three Explore agents produced ~50 candidate findings; verification against current code rejected several as false positives (notably "dix-de-der double counting" — separate counters; "underscore-boss-attr anti-pattern" — already pinned by tests) and confirmed the items shipped here. **+4 regression tests** (595 → 599). Plan file at `/home/mrrobot/.claude/plans/bug-hunt-code-performance-functional-naur.md`.
   - **H1** (`belatro/engine/round_driver.py:210-289`) — EW AI can now coinche an NS taker via a new `_ew_should_coinche` heuristic. Pre-3.6.0 there was no path that set `coinche_level > 0` when NS was taker (outside `auto_coinche` / `start_coinched`), making the Libra planet effectively unreachable in natural play.

{belote_cli-3.7.1 → belote_cli-3.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: belote-cli
-Version: 3.7.1
+Version: 3.8.2
 Summary: A 4-player terminal card game
 Project-URL: Homepage, https://github.com/ElysiumDisc/belote
 Project-URL: Repository, https://github.com/ElysiumDisc/belote
@@ -71,6 +71,8 @@ belatro
 | **Le Vétéran** | Start with a random **Planet** card pre-applied to level up a contract |
 | **Le Flambeur** | Starts with **L'Aventurier** Partner Joker (×2 Mult if both win ≥3 tricks) |
 | L'Anarchiste | Start $19 — Corrupted pool visible |
+| **Le Marseillais** | Annonces (Tierce / Quarte / Quinte) score ×2. Belote / Rebelote disabled |
+| **Le Coincheur** | Every round starts pre-coinched. +50 starting Chips, $8 starting cash |
 
 ### Notable Vouchers
 | Voucher | Effect |
@@ -252,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 (635 tests)
+├── tests/             # Comprehensive test suite (655 tests)
 ├── scripts/           # Performance benchmarks
 ├── pyproject.toml      # Build system and dev dependencies (ruff/mypy)
 ├── LICENSE             # MIT License
@@ -268,14 +270,14 @@ belote/
 PYTHONPATH=src pytest
 ```
 
-Currently **635 tests** passing with 100% coverage on game-logic modules.
+Currently **655 tests** passing with 100% coverage on game-logic modules (3.8.2).
 
 ## Technical Integrity
 
 The codebase is strictly validated with the following tools:
 - **mypy**: 0 errors (strict type safety)
 - **ruff**: 0 violations (linting & formatting)
-- **pytest**: 635/635 passed
+- **pytest**: 655/655 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.7.1 → belote_cli-3.8.2}/README.md

@@ -28,6 +28,8 @@ belatro
 | **Le Vétéran** | Start with a random **Planet** card pre-applied to level up a contract |
 | **Le Flambeur** | Starts with **L'Aventurier** Partner Joker (×2 Mult if both win ≥3 tricks) |
 | L'Anarchiste | Start $19 — Corrupted pool visible |
+| **Le Marseillais** | Annonces (Tierce / Quarte / Quinte) score ×2. Belote / Rebelote disabled |
+| **Le Coincheur** | Every round starts pre-coinched. +50 starting Chips, $8 starting cash |
 
 ### Notable Vouchers
 | Voucher | Effect |
@@ -209,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 (635 tests)
+├── tests/             # Comprehensive test suite (655 tests)
 ├── scripts/           # Performance benchmarks
 ├── pyproject.toml      # Build system and dev dependencies (ruff/mypy)
 ├── LICENSE             # MIT License
@@ -225,14 +227,14 @@ belote/
 PYTHONPATH=src pytest
 ```
 
-Currently **635 tests** passing with 100% coverage on game-logic modules.
+Currently **655 tests** passing with 100% coverage on game-logic modules (3.8.2).
 
 ## Technical Integrity
 
 The codebase is strictly validated with the following tools:
 - **mypy**: 0 errors (strict type safety)
 - **ruff**: 0 violations (linting & formatting)
-- **pytest**: 635/635 passed
+- **pytest**: 655/655 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.7.1 → belote_cli-3.8.2}/pyproject.toml

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

{belote_cli-3.7.1 → belote_cli-3.8.2}/src/belote/__init__.py

@@ -1,3 +1,3 @@
-__version__ = "3.7.1"
+__version__ = "3.8.2"
 
 __all__ = ["__version__"]

{belote_cli-3.7.1 → belote_cli-3.8.2}/src/belote/ai.py

@@ -38,6 +38,10 @@ class AIMemory:
         # (completed_count, current_trick_len) of the last _update_voids call.
         # Lets us skip re-scanning a stable transient trick on each decision.
         self.last_voids_key: tuple[int, int] | None = None
+        # (completed_count, current_trick_len) of the last partner_hand
+        # rebuild. The partner's hand only changes when they play a card or
+        # a new round starts; same memo pattern as `last_voids_key`.
+        self.last_partner_hand_key: tuple[int, int] | None = None
 
 
 class AIPlayer:
@@ -76,6 +80,7 @@ class AIPlayer:
             self.memory.partner_hand.clear()
             self.memory.processed_tricks_count = 0
             self.memory.last_voids_key = None
+            self.memory.last_partner_hand_key = None
         elif (
             self.memory.last_voids_key is not None
             and (completed_count, current_count) < self.memory.last_voids_key
@@ -90,6 +95,7 @@ class AIPlayer:
                 self.memory.known_voids[s].clear()
             self.memory.processed_tricks_count = 0
             self.memory.last_voids_key = None
+            self.memory.last_partner_hand_key = None
 
         # Track all cards in completed tricks
         for trick in state.completed_tricks:
@@ -98,16 +104,21 @@ class AIPlayer:
         for tc in state.current_trick:
             self.memory.played.add(tc.card)
 
-        # Partner's hand is visible (for NS team, South sees North's plays)
-        # In this implementation, AI tracks what it can see
-        p = partner(self.seat)
-        self.memory.partner_hand.clear()
-        if (
-            state.phase in (Phase.PLAYING, Phase.SCORING)
-            and not state.boss_modifiers.hide_partner_hand
-        ):
-            for card in state.hand_of(p):
-                self.memory.partner_hand.add(card)
+        # Partner's hand is visible (for NS team, South sees North's plays).
+        # It only changes when partner plays a card (i.e. when
+        # (completed_count, current_count) advances). Memo on the same key
+        # the void cache uses; skip the rebuild on a no-op repeat call.
+        partner_key = (completed_count, current_count)
+        if self.memory.last_partner_hand_key != partner_key:
+            p = partner(self.seat)
+            self.memory.partner_hand.clear()
+            if (
+                state.phase in (Phase.PLAYING, Phase.SCORING)
+                and not state.boss_modifiers.hide_partner_hand
+            ):
+                for card in state.hand_of(p):
+                    self.memory.partner_hand.add(card)
+            self.memory.last_partner_hand_key = partner_key
 
     def decide_bid(self, state: GameState) -> BidValue:
         """Decide whether to bid and which contract.
@@ -467,8 +478,17 @@ class AIPlayer:
         suit_scores: dict[Suit, float] = dict.fromkeys(card_suits, 0.0)
         personality = self._rng.uniform(-0.8, 0.8)
 
+        # Bucket the hand by suit in a single pass. Pre-3.8.0 each suit-loop
+        # iteration re-filtered the hand twice (4 suits × 2 walks), and the
+        # inner cross-suit lookup re-counted other suits — 12 hand walks
+        # total. Single-pass bucketing collapses that to one walk.
+        suit_cards: dict[Suit, list[Card]] = {s: [] for s in card_suits}
+        for c in hand:
+            if c.suit in suit_cards:
+                suit_cards[c.suit].append(c)
+
         for suit in card_suits:
-            trump_cards = [c for c in hand if c.suit == suit]
+            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)
 
@@ -482,7 +502,7 @@ class AIPlayer:
 
             for other in card_suits:
                 if other != suit:
-                    other_count = sum(1 for c in hand if c.suit == other)
+                    other_count = len(suit_cards[other])
                     if other_count == 0:
                         suit_scores[suit] += 2
                     elif other_count == 1:

{belote_cli-3.7.1 → belote_cli-3.8.2}/src/belote/belatro/core/run_state.py

@@ -47,7 +47,8 @@ class BelAtroRun:
     guarantee_tarot_in_shop: bool = False
     show_partner_bid_tendency: bool = False
     tie_breaks_for_taker: bool = False
-    partner_throws_trick: bool = False
+    partner_throws_trick: bool = False  # Le Traître joker (1 random trick/round)
+    agent_double_joker: bool = False  # L'Agent Double joker (2 random tricks/round)
     capot_insurance: bool = False  # one-shot: halve a chute loss
 
     # ── Phase 1+ feature flags ──────────────────────────────
@@ -96,6 +97,15 @@ class BelAtroRun:
     seed: int | None = None
     _rng: Any = None
 
+    # ── 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.
+    _applied_voucher_ids: set[str] = field(default_factory=set)
+
     def consume(self, item: Any, context: object = None) -> None:
         """Centralised consumable activation.
 

{belote_cli-3.7.1 → belote_cli-3.8.2}/src/belote/belatro/core/scoring.py

@@ -216,7 +216,7 @@ class ScoreAccumulator:
                 # The Moon (Sans Atout): honor bonus per honor won
                 if event.trump is None:
                     moon_reward = self.contract_levels.get("sans_atout", {})
-                    honor_bonus = moon_reward.get("honor_bonus", 0)
+                    honor_bonus = moon_reward.get("honor_bonus", 0.0)
                     if honor_bonus:
                         honors = sum(
                             1 for c in event.cards
@@ -228,7 +228,7 @@ class ScoreAccumulator:
                 # The Sun (Tout Atout): +X Mult per trick beyond the 4th
                 if event.trump == Suit.TOUT_ATOUT and event.trick_number > 4:
                     sun_reward = self.contract_levels.get("tout_atout", {})
-                    sun_mult = sun_reward.get("bonus_mult_per_trick", 0)
+                    sun_mult = sun_reward.get("bonus_mult_per_trick", 0.0)
                     if sun_mult:
                         new_mult += sun_mult
                         self._log.append(
@@ -267,7 +267,7 @@ class ScoreAccumulator:
                     and not event.breakdown.is_failed
                 ):
                     libra_reward = self.contract_levels.get("coinche", {})
-                    libra_mult: float = libra_reward.get("coinche_multiplier", 0)
+                    libra_mult: float = libra_reward.get("coinche_multiplier", 0.0)
                     if libra_mult:
                         libra_bonus: float = libra_mult * event.coinche_level
                         new_mult += libra_bonus

{belote_cli-3.7.1 → belote_cli-3.8.2}/src/belote/belatro/engine/round_driver.py

@@ -6,7 +6,7 @@ from dataclasses import replace
 from typing import TYPE_CHECKING
 
 from belote.ai import AIPlayer, Difficulty
-from belote.deck import Card, Contract, Suit
+from belote.deck import Card, Suit
 from belote.game import (
     SANS_ATOUT_BID,
     BidValue,
@@ -18,7 +18,6 @@ from belote.game import (
     play_card,
     process_bid,
     start_round,
-    trick_winner_seat,
 )
 from belote.scoring import get_declaration_points, is_capot, score_round
 
@@ -132,10 +131,21 @@ def drive_round(
         new_jstate2 = {**state._joker_state, "agent_double_tricks": sabotage}
         state = replace(state, boss_modifiers=new_bm, _joker_state=new_jstate2)
 
-    if acc is not None:
-        state = acc.trigger_round_start(state)
-
-    # B1: Apply boss modifier flags onto the frozen GameState so play_card sees them
+    # L'Agent Double joker (corrupted): like Le Traître but two sabotage tricks.
+    # Same precedence rule — boss agent_double takes priority.
+    if (
+        state._joker_state.get("agent_double_joker_active")
+        and not state.boss_modifiers.agent_double_active
+    ):
+        sabotage2 = frozenset(rng.sample(range(1, 9), 2))
+        new_bm2 = replace(state.boss_modifiers, agent_double_active=True)
+        new_jstate3 = {**state._joker_state, "agent_double_tricks": sabotage2}
+        state = replace(state, boss_modifiers=new_bm2, _joker_state=new_jstate3)
+
+    # B1: Apply boss modifier flags onto the frozen GameState so play_card sees them.
+    # Must run BEFORE acc.trigger_round_start so the accumulator's snapshot of
+    # boss-derived flags (e.g. joker_state["no_dix_de_der"]) reflects the live
+    # boss state instead of the BossModifiers defaults.
     if boss is not None:
         from ..engine.modifier_patch import PatchedGameState
 
@@ -147,6 +157,9 @@ def drive_round(
         # Ensure boss modifiers don't use stale cached logic/values
         clear_legal_cards_cache()
 
+    if acc is not None:
+        state = acc.trigger_round_start(state)
+
     # Populate sabotage_tricks for any path that flagged agent_double_active.
     # Sources: L'Agent Double boss (3 random tricks), BetrayalArc (tricks 4-8 via
     # agent_double_late_only flag), traitre joker (already populated above).
@@ -377,11 +390,14 @@ def drive_round(
         if is_last_in_trick(state):
             last_trick = state.completed_tricks[-1]
 
-            winner = trick_winner_seat(
-                last_trick,
-                state.trump,
-                state.boss_modifiers.seven_eight_trump,
-                state.contract == Contract.SANS_ATOUT,
+            # Use the resolved winner cached by play_card (Rupture-aware).
+            # 3.8.1: pre-fix this re-derived via trick_winner_seat, which
+            # returns the RAW winner; under La Rupture the event.winner
+            # would disagree with the team scoring authority.
+            winner = state.last_trick_winner
+            assert winner is not None, (
+                "last_trick_winner unset after a complete trick — "
+                "GameState invariant violated."
             )
             # Use state diff to get points; perfectly handles all boss-aware points and Dix de Der
             points = sum(state.current_round_points) - old_pts_total

{belote_cli-3.7.1 → belote_cli-3.8.2}/src/belote/belatro/items/jokers/annonces.py

@@ -73,7 +73,11 @@ class QuinteRoyale(Joker):
     def on_declaration(
         self, event: DeclarationScoredEvent, state: dict[str, Any]
     ) -> JokerResult | None:
-        if event.seat in (Seat.SOUTH, Seat.NORTH) and event.points >= 100:
+        if (
+            event.seat in (Seat.SOUTH, Seat.NORTH)
+            and event.declaration_type == "sequence"
+            and event.points >= 100
+        ):
             # Quinte = 100 pts in classic belote scoring; mark for round-end mult.
             state[f"{self.id}_armed"] = True
         return None

{belote_cli-3.7.1 → belote_cli-3.8.2}/src/belote/belatro/items/jokers/contract.py

@@ -93,8 +93,13 @@ class LeRebelle(Joker):
     description = "The Belote/Rebelote declaration gives ×3 Mult instead of a flat 20 points."
     cost = 8
 
-    def on_belote(self, event: BeloteAnnouncedEvent, state: dict[str, Any]) -> JokerResult | None:
-        if event.seat == Seat.SOUTH:
+    def on_belote(
+        self, event: BeloteAnnouncedEvent, state: dict[str, Any]
+    ) -> JokerResult | None:
+        # Belote/Rebelote points (20) are only awarded if both cards are played.
+        # Gate on the second event (rebelote) so we only subtract points that
+        # the player actually earned.
+        if event.seat == Seat.SOUTH and event.is_rebelote:
             return JokerResult(add_chips=-20, times_mult=3.0)
         return None
 

{belote_cli-3.7.1 → belote_cli-3.8.2}/src/belote/belatro/items/jokers/corrupted.py

@@ -69,18 +69,12 @@ class LAgentDouble(Joker):
     cost = 9
     is_corrupted = True
 
-    def on_round_start(self, state: dict[str, Any]) -> JokerResult | None:
-        state[f"{self.id}_sabotage_remaining"] = 2
-        return None
+    def on_purchase(self, run: BelAtroRun) -> None:
+        # Flag the run so round_driver flips agent_double_active + populates
+        # a 2-trick sabotage set every round. Mirrors Le Traître's wiring.
+        run.agent_double_joker = True
 
     def on_trick_won(self, event: TrickWonEvent, state: dict[str, Any]) -> JokerResult | None:
-        # Count down the sabotage window once per trick regardless of who won —
-        # otherwise NS sweeping the round leaves the sabotage flag stuck on for
-        # the whole game. The "for 2 tricks" wording in the description is
-        # absolute, not "until the opponents have won 2".
-        remaining = state.get(f"{self.id}_sabotage_remaining", 0)
-        if remaining > 0:
-            state[f"{self.id}_sabotage_remaining"] = remaining - 1
         if event.winner == Seat.SOUTH:
             return JokerResult(add_mult=4.0)
         return None

{belote_cli-3.7.1 → belote_cli-3.8.2}/src/belote/belatro/items/jokers/economy.py

@@ -46,7 +46,12 @@ class LeNotaire(Joker):
     description = "Belote/Rebelote is worth $5 cash instead of 20 flat points."
     cost = 6
 
-    def on_belote(self, event: BeloteAnnouncedEvent, state: dict[str, Any]) -> JokerResult | None:
-        if event.seat == Seat.SOUTH:
+    def on_belote(
+        self, event: BeloteAnnouncedEvent, state: dict[str, Any]
+    ) -> JokerResult | None:
+        # Belote/Rebelote points (20) are only awarded if both cards are played.
+        # Gate on the second event (rebelote) so we only subtract points that
+        # the player actually earned.
+        if event.seat == Seat.SOUTH and event.is_rebelote:
             return JokerResult(add_chips=-20, add_money=5)
         return None

{belote_cli-3.7.1 → belote_cli-3.8.2}/src/belote/belatro/main.py

@@ -327,6 +327,10 @@ class BelAtroGame:
             # Le Traître joker: partner sabotages one random trick per round.
             # round_driver picks the trick + reuses the agent_double AI path.
             round_flags["traitre_active"] = True
+        if self.run.agent_double_joker:
+            # L'Agent Double joker: partner sabotages two random tricks per round.
+            # round_driver picks the tricks + reuses the agent_double AI path.
+            round_flags["agent_double_joker_active"] = True
         if self.run.surcoinche_unlocked:
             round_flags["surcoinche_unlocked"] = True
 
@@ -359,6 +363,11 @@ class BelAtroGame:
         if isinstance(pending, int) and pending > 0:
             self.run.tierce_charges += pending
 
+        # Phase 2.1: persist Tout Atout streak between rounds.
+        streak = final_state._joker_state.get("tout_streak_streak", 0)
+        if isinstance(streak, int):
+            self.run.card_enhancements["tout_streak_streak"] = streak
+
         # Phase 2.3: refresh partner_mood for HUD display.
         self.run.partner_mood = trust.mood()
 

{belote_cli-3.7.1 → belote_cli-3.8.2}/src/belote/belatro/run/shop.py

@@ -172,6 +172,13 @@ class Shop:
                 item.on_purchase(self.run)
         elif isinstance(item, Voucher):
             self.run.vouchers.append(item)
-            item.apply(self.run)
+            # 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)
         elif len(self.run.consumables) < self.run.consumable_slots:
             self.run.consumables.append(item)

{belote_cli-3.7.1 → belote_cli-3.8.2}/src/belote/belatro/ui/announce.py

@@ -40,16 +40,21 @@ class BelAtroAnnounce:
         from belote.ui.render import get_term_size
 
         term_w, term_h = get_term_size()
+        mid = max(4, term_h // 2)
 
         print(clear_screen(), end="")
-        for i in range(1, 10):
-            print(move(i, 1) + " ")
-        print(move(10, 1) + ansi_center(red_fg() + BOLD + "! BOSS BLIND REVEALED !" + RESET, term_w))
+        print(
+            move(mid - 3, 1)
+            + ansi_center(red_fg() + BOLD + "! BOSS BLIND REVEALED !" + RESET, term_w)
+        )
         interruptible_sleep(1.0, reader)
-        print(move(13, 1) + ansi_center(gold_fg() + BOLD + boss.name.upper() + RESET, term_w))
+        print(move(mid, 1) + ansi_center(gold_fg() + BOLD + boss.name.upper() + RESET, term_w))
         interruptible_sleep(1.0, reader)
-        print(move(15, 1) + ansi_center(white_fg() + boss.description + RESET, term_w))
-        print(move(20, 1) + ansi_center(BOLD + "[ Press any key to continue ]" + RESET, term_w))
+        print(move(mid + 2, 1) + ansi_center(white_fg() + boss.description + RESET, term_w))
+        print(
+            move(max(mid + 5, term_h - 2), 1)
+            + ansi_center(BOLD + "[ Press any key to continue ]" + RESET, term_w)
+        )
         interruptible_sleep(2.0, reader)
 
     @staticmethod
@@ -108,7 +113,7 @@ class BelAtroAnnounce:
         if not lines:
             return
         toggle_overlay()
-        start_row = 24
+        start_row = max(1, term_h - len(lines) - 4)
         for i, line in enumerate(lines):
             print(move(start_row + i, 1) + ansi_center(gold_fg() + line + RESET, term_w))
         end = time.time() + 1.5

{belote_cli-3.7.1 → belote_cli-3.8.2}/src/belote/belatro/ui/collection.py

@@ -41,7 +41,10 @@ def show_collection(reader: KeyReader, profile: Profile) -> None:
     cat_idx = 0
     item_idx = 0
 
+    from belote.ui.fit_guard import require_minimum
+
     while True:
+        require_minimum(reader)
         term_w, term_h = get_term_size()
         cat_name, items = categories[cat_idx]
         item_idx = min(item_idx, len(items) - 1) if items else 0
@@ -82,10 +85,17 @@ def show_collection(reader: KeyReader, profile: Profile) -> None:
 
             # Show details for discovered item on the right
             if real_idx == item_idx:
-                info_col = 40
+                info_col = max(40, term_w // 2)
+                wrap_w = max(20, term_w - info_col - 2)
+                divider_w = min(30, wrap_w)
                 if is_discovered:
                     out.append(move(start_row, info_col) + gold_fg() + BOLD + item_cls.name + RESET)
-                    out.append(move(start_row + 1, info_col) + menu_border_fg() + "─" * 30 + RESET)
+                    out.append(
+                        move(start_row + 1, info_col)
+                        + menu_border_fg()
+                        + "─" * divider_w
+                        + RESET
+                    )
 
                     # Try to show ASCII art if available
                     art = getattr(item_cls, "ascii_art", [])
@@ -100,7 +110,7 @@ def show_collection(reader: KeyReader, profile: Profile) -> None:
                     line = ""
                     r = desc_start
                     for w in words:
-                        if len(line) + len(w) + 1 > 40:
+                        if len(line) + len(w) + 1 > wrap_w:
                             out.append(move(r, info_col) + white_fg() + line + RESET)
                             line = w
                             r += 1