Fix the fold experience: honest actions, matched state, action identity

Reported as "folding looks broken". It was five separate defects.

1. Fold silently became Check. sanitise() rewrote FOLD to CHECK whenever
   checking was free, so a UI showing a Fold button folded nothing and the
   player kept being asked to act. Folding is legal at any turn — it simply
   mucks — so FOLD is now honoured literally. The engine must never substitute a
   different action than the caller asked for. The reverse rewrite (an illegal
   CHECK facing a bet becoming FOLD) is legitimate and stays.

   Safe by construction: no bot emits FOLD when it can check, and the 20k-hand
   simulation reproduces byte-identical numbers (289.12 / 113.19 / -195.64).

2. Snapshot and offer could describe different moments. The 32-deep frame
   channel let the engine race far ahead of the animation, so the action on
   offer could belong to a later street, or another hand. The channel is now
   RENDEZVOUS, capping the engine at one frame ahead, and UiState.liveOffer()
   only surfaces an offer whose hand and street match the table on screen.

3. Stale and double taps could act on a later decision. DecisionOffer now
   carries a token; submit() requires it and rejects anything stale, so a second
   tap is dropped rather than applied to whatever comes next.

4. A real fold was invisible. The hero kept normal cards and no folded state, so
   a correctly processed fold looked like a bug. Cards now dim, FOLDED shows in
   red, and the action bar explains the player is sitting out.

5. Non-atomic UiState updates from two coroutines now use update {}.

Also: Fold is hidden when checking is free (folding a free hand is never
correct, and offering it invites an accidental muck), and onCleared no longer
calls human.cancel() — viewModelScope is already cancelled by then so the launch
never ran; scope cancellation already propagates into act()'s finally.

The delivery tests were weak as charged: no slow consumer, and not the app's
capacity. Replaced with a genuinely slow consumer measuring how far the engine
runs ahead — asserting <= 1 on RENDEZVOUS, and > 1 on a 32-deep buffer to
document why the buffer was removed.

Verified on the emulator (physical device untouched): folded facing a bet, hero
showed FOLDED, was never asked again that hand, and play advanced to hand 2.

Tests: 55 -> 62, green on jvmTest and testAndroidHostTest.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

app/src/main/java/com/jsjdesigns/poker/PokerViewModel.kt

@@ -8,6 +8,7 @@ import com.jsjdesigns.poker.bot.PlayStyle
 import com.jsjdesigns.poker.bot.SkillLevel
 import com.jsjdesigns.poker.game.Action
 import com.jsjdesigns.poker.game.ActionType
+import com.jsjdesigns.poker.game.DecisionOffer
 import com.jsjdesigns.poker.game.HumanAgent
 import com.jsjdesigns.poker.game.Seat
 import com.jsjdesigns.poker.game.Table
@@ -18,6 +19,7 @@ import kotlinx.coroutines.delay
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.flow.update
 import kotlinx.coroutines.launch
 import kotlin.random.Random
 
@@ -30,7 +32,25 @@ data class UiState(
     val snapshot: TableSnapshot? = null,
     val handsPlayed: Int = 0,
     val message: String? = null,
-)
+) {
+    /**
+     * The decision to show, or null.
+     *
+     * An offer is only live when the table on screen is the one it belongs to.
+     * The engine can be a frame ahead of the animation, so a raw offer could
+     * otherwise be rendered against a stale board — or worse, against a different
+     * hand entirely.
+     */
+    fun liveOffer(offer: DecisionOffer?): DecisionOffer? {
+        val snap = snapshot ?: return null
+        if (offer == null) return null
+        return offer.takeIf {
+            it.handNumber == snap.handNumber &&
+                snap.toAct == HERO_SEAT &&
+                it.street == snap.street
+        }
+    }
+}
 
 /**
  * Drives a continuous cash game and publishes it to Compose.
@@ -47,7 +67,11 @@ data class UiState(
 class PokerViewModel : ViewModel() {
 
     private val human = HumanAgent()
-    private val frames = Channel<TableSnapshot>(capacity = 32)
+    // RENDEZVOUS, not a buffer. A 32-deep queue let the engine race dozens of
+    // frames ahead of the animation, so the board on screen and the action being
+    // offered could belong to different moments — even different hands. With no
+    // buffer the engine is at most one frame ahead of what the player can see.
+    private val frames = Channel<TableSnapshot>(capacity = Channel.RENDEZVOUS)
 
     private val _state = MutableStateFlow(UiState())
     val state: StateFlow<UiState> = _state.asStateFlow()
@@ -87,7 +111,7 @@ class PokerViewModel : ViewModel() {
 
     private suspend fun consumeFrames() {
         for (frame in frames) {
-            _state.value = _state.value.copy(snapshot = frame.maskedFor(HERO_SEAT))
+            _state.update { it.copy(snapshot = frame.maskedFor(HERO_SEAT)) }
             delay(pacingMillis(frame))
         }
     }
@@ -112,27 +136,33 @@ class PokerViewModel : ViewModel() {
             for (s in seats) if (s.stack < BIG_BLIND) s.stack = STARTING_STACK
             table.advanceButton()
             runCatching { table.playHand() }
-                .onSuccess { _state.value = _state.value.copy(handsPlayed = _state.value.handsPlayed + 1) }
+                .onSuccess { _state.update { s -> s.copy(handsPlayed = s.handsPlayed + 1) } }
                 .onFailure { return }   // scope cancelled: the screen went away
         }
     }
 
-    fun submit(action: Action) {
-        viewModelScope.launch { human.submit(action) }
+    /**
+     * Submits against the token the button was rendered from, so a stale or
+     * doubled tap is dropped rather than applied to whatever comes next.
+     */
+    fun submit(token: Long, action: Action) {
+        viewModelScope.launch { human.submit(token, action) }
     }
 
-    fun fold() = submit(Action(ActionType.FOLD))
+    fun fold(token: Long) = submit(token, Action(ActionType.FOLD))
 
-    fun checkOrCall() {
+    fun checkOrCall(token: Long) {
         val o = offer.value ?: return
-        submit(if (o.canCheck) Action(ActionType.CHECK) else Action(ActionType.CALL, o.toCall))
+        if (o.token != token) return
+        submit(token, if (o.canCheck) Action(ActionType.CHECK) else Action(ActionType.CALL, o.toCall))
     }
 
-    fun raiseTo(amount: Int) = submit(Action(ActionType.RAISE, amount))
+    fun raiseTo(token: Long, amount: Int) = submit(token, Action(ActionType.RAISE, amount))
 
     override fun onCleared() {
-        // Release a hand parked on human input so the coroutine can finish.
-        viewModelScope.launch { human.cancel() }
+        // No explicit human.cancel() here: viewModelScope is already cancelled by
+        // this point, so a launch would never run. Cancelling the scope propagates
+        // into HumanAgent.act()'s await, whose finally clears the pending state.
         frames.close()
         super.onCleared()
     }

app/src/main/java/com/jsjdesigns/poker/TableScreen.kt

@@ -44,8 +44,10 @@ private val Felt = Color(0xFF0B3D26)
 @Composable
 fun TableScreen(vm: PokerViewModel) {
     val state by vm.state.collectAsStateWithLifecycle()
-    val offer by vm.offer.collectAsStateWithLifecycle()
+    val rawOffer by vm.offer.collectAsStateWithLifecycle()
     val snap = state.snapshot
+    // Only show an action bar that belongs to the table currently on screen.
+    val offer = state.liveOffer(rawOffer)
 
     Column(
         modifier = Modifier
@@ -117,6 +119,7 @@ fun TableScreen(vm: PokerViewModel) {
 
         ActionBar(
             offer = offer,
+            heroFolded = hero?.folded == true,
             onFold = vm::fold,
             onCheckCall = vm::checkOrCall,
             onRaise = vm::raiseTo,
@@ -172,12 +175,17 @@ private fun OpponentSeat(seat: SeatSnapshot, isTurn: Boolean) {
 
 @Composable
 private fun HeroSeat(seat: SeatSnapshot?, isTurn: Boolean) {
+    val folded = seat?.folded == true
     Row(
         modifier = Modifier.fillMaxWidth(),
         verticalAlignment = Alignment.CenterVertically,
         horizontalArrangement = Arrangement.spacedBy(12.dp),
     ) {
-        Row(horizontalArrangement = Arrangement.spacedBy(4.dp)) {
+        // A processed fold has to *look* folded, or a correct fold reads as a bug.
+        Row(
+            horizontalArrangement = Arrangement.spacedBy(4.dp),
+            modifier = Modifier.alpha(if (folded) 0.25f else 1f),
+        ) {
             repeat(2) { i ->
                 CardImage(seat?.hole?.getOrNull(i), Modifier.size(64.dp, 96.dp))
             }
@@ -185,9 +193,16 @@ private fun HeroSeat(seat: SeatSnapshot?, isTurn: Boolean) {
         Column {
             Text(
                 (seat?.name ?: "You") + if (seat?.isButton == true) "  ⏺" else "",
-                color = if (isTurn) Color(0xFFE3C179) else Color.White,
+                color = when {
+                    folded -> Color.White.copy(alpha = 0.4f)
+                    isTurn -> Color(0xFFE3C179)
+                    else -> Color.White
+                },
                 fontWeight = FontWeight.Bold,
             )
+            if (folded) {
+                Text("FOLDED", color = Color(0xFFC9545B), fontSize = 12.sp, fontWeight = FontWeight.Bold)
+            }
             Text("${seat?.stack ?: 0}", color = Color.White.copy(alpha = 0.75f))
             if ((seat?.committedThisRound ?: 0) > 0) {
                 Text("bet ${seat?.committedThisRound}", color = Color(0xFFE3C179), fontSize = 12.sp)
@@ -199,13 +214,17 @@ private fun HeroSeat(seat: SeatSnapshot?, isTurn: Boolean) {
 @Composable
 private fun ActionBar(
     offer: com.jsjdesigns.poker.game.DecisionOffer?,
-    onFold: () -> Unit,
-    onCheckCall: () -> Unit,
-    onRaise: (Int) -> Unit,
+    heroFolded: Boolean,
+    onFold: (Long) -> Unit,
+    onCheckCall: (Long) -> Unit,
+    onRaise: (Long, Int) -> Unit,
 ) {
     if (offer == null) {
         Box(Modifier.fillMaxWidth().height(96.dp), contentAlignment = Alignment.Center) {
-            Text("Waiting…", color = Color.White.copy(alpha = 0.4f))
+            Text(
+                if (heroFolded) "You folded — sitting out this hand" else "Waiting…",
+                color = Color.White.copy(alpha = 0.4f),
+            )
         }
         return
     }
@@ -227,21 +246,25 @@ private fun ActionBar(
             modifier = Modifier.fillMaxWidth(),
             horizontalArrangement = Arrangement.spacedBy(8.dp),
         ) {
-            Button(
-                onClick = onFold,
-                modifier = Modifier.weight(1f),
-                colors = ButtonDefaults.buttonColors(containerColor = Color(0xFF8F1218)),
-            ) { Text("Fold") }
+            // No Fold button when checking is free: folding a free hand is never
+            // correct, and offering it invites the player to muck by accident.
+            if (!offer.canCheck) {
+                Button(
+                    onClick = { onFold(offer.token) },
+                    modifier = Modifier.weight(1f),
+                    colors = ButtonDefaults.buttonColors(containerColor = Color(0xFF8F1218)),
+                ) { Text("Fold") }
+            }
 
             Button(
-                onClick = onCheckCall,
+                onClick = { onCheckCall(offer.token) },
                 modifier = Modifier.weight(1f),
                 colors = ButtonDefaults.buttonColors(containerColor = Color(0xFF2C6E49)),
             ) { Text(if (offer.canCheck) "Check" else "Call ${offer.toCall}") }
 
             if (offer.canRaise && offer.maxRaiseTo > offer.minRaiseTo) {
                 Button(
-                    onClick = { onRaise(raiseTo) },
+                    onClick = { onRaise(offer.token, raiseTo) },
                     modifier = Modifier.weight(1f),
                     colors = ButtonDefaults.buttonColors(containerColor = Color(0xFF14357A)),
                 ) { Text(if (raiseTo >= offer.maxRaiseTo) "All in" else "Raise") }