Fix reliability bugs: win detection, sell, editions, re-entrancy, blind override

A collection of reliability and correctness fixes developed while running
the balatrobot framework against a headless bot that plays thousands of
rounds unattended.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: DrLatBC

src/lua/endpoints/buy.lua

@@ -238,28 +238,49 @@ return {
           end
         elseif args.pack then
           local money_deducted = (G.GAME.dollars == initial_money - card.cost.buy)
-          local pack_ready = (
-            G.pack_cards
-            and not G.pack_cards.REMOVED
-            and G.pack_cards.cards[1]
-            and G.STATE_COMPLETE
-            and G.STATE == G.STATES.SMODS_BOOSTER_OPENED
-          )
+          local has_pack = G.pack_cards and not G.pack_cards.REMOVED and G.pack_cards.cards and G.pack_cards.cards[1]
+          local state_ok = G.STATE_COMPLETE and G.STATE == G.STATES.SMODS_BOOSTER_OPENED
+          local pack_ready = has_pack and state_ok
+
+          if not pack_ready then
+            -- Debug: log what's blocking
+            local state_name = "?"
+            if G.STATES then
+              for name, value in pairs(G.STATES) do
+                if value == G.STATE then state_name = name break end
+              end
+            end
+            sendDebugMessage(string.format(
+              "buy(pack) waiting: money_ok=%s pack_exists=%s state=%s state_complete=%s",
+              tostring(money_deducted), tostring(has_pack ~= nil), state_name, tostring(G.STATE_COMPLETE)
+            ), "BB.ENDPOINTS")
+          end
+
           if money_deducted and pack_ready then
-            -- Check if this pack type needs hand (Arcana/Spectral packs)
-            local pack_key = G.pack_cards.cards[1].ability and G.pack_cards.cards[1].ability.set
-            local needs_hand = pack_key == "Tarot" or pack_key == "Spectral"
+            -- Check if this pack type needs hand (Arcana/Spectral packs deal hand cards)
+            -- Don't infer pack type from the first card's set — Black Hole is
+            -- set=Spectral but appears in Celestial packs, causing a false match.
+            local needs_hand = G.hand and G.hand.cards and #G.hand.cards > 0
 
             if needs_hand then
               -- Wait for hand to be fully loaded and positioned
               local hand_limit = G.hand and G.hand.config and G.hand.config.card_limit or 8
+              local deck_size = G.deck and G.deck.config and G.deck.config.card_count or 52
+              local expected = math.min(deck_size, hand_limit)
+              local hand_count = G.hand and G.hand.cards and #G.hand.cards or 0
               local hand_ready = G.hand
                 and not G.hand.REMOVED
                 and G.hand.cards
-                and #G.hand.cards == hand_limit
+                and hand_count >= expected
                 and G.hand.T
                 and G.hand.T.x
               local cards_positioned = hand_ready and G.hand.cards[1] and G.hand.cards[1].T and G.hand.cards[1].T.x
+              if not done and money_deducted then
+                sendDebugMessage(string.format(
+                  "buy(pack) hand wait: count=%d expected=%d limit=%d deck=%d positioned=%s",
+                  hand_count, expected, hand_limit, deck_size, tostring(cards_positioned ~= nil)
+                ), "BB.ENDPOINTS")
+              end
               done = hand_ready and cards_positioned
             else
               done = true

src/lua/endpoints/discard.lua

@@ -97,8 +97,6 @@ return {
     G.E_MANAGER:add_event(Event({
       trigger = "immediate",
       blocking = false,
-      blockable = false,
-      created_on_pause = true,
       func = function()
         -- State progression for discard:
         -- Discard always continues current round: HAND_PLAYED -> DRAW_TO_HAND -> SELECTING_HAND

src/lua/endpoints/pack.lua

@@ -3,6 +3,10 @@
 ---@type BB_LOGGER
 local BB_LOGGER = assert(SMODS.load_file("src/lua/utils/logger.lua"))()
 
+-- Re-entrancy guard: prevents double-firing use_card when a previous
+-- pack selection is still being processed (e.g. Black Hole animations).
+local selection_in_progress = false
+
 -- ==========================================================================
 -- Pack Select Endpoint Params
 -- ==========================================================================
@@ -110,6 +114,15 @@ return {
       return
     end
 
+    -- Block re-entrant calls while a previous selection is processing
+    if selection_in_progress then
+      send_response({
+        message = "Pack selection already in progress",
+        name = BB_ERROR_NAMES.NOT_ALLOWED,
+      })
+      return
+    end
+
     -- Validate pack_cards exists
     if not G.pack_cards or G.pack_cards.REMOVED then
       send_response({
@@ -239,6 +252,7 @@ return {
 
       local pack_choices_before = G.GAME.pack_choices or 0
 
+      selection_in_progress = true
       G.FUNCS.use_card(btn)
 
       -- Wait for action to complete - check pack_choices to determine expected state
@@ -255,6 +269,7 @@ return {
               and G.STATE == G.STATES.SMODS_BOOSTER_OPENED
 
             if pack_stable then
+              selection_in_progress = false
               sendDebugMessage("Return pack() after selection (more choices remain)", "BB.ENDPOINTS")
               send_response(BB_GAMESTATE.get_gamestate())
               return true
@@ -265,10 +280,24 @@ return {
             local back_to_shop = G.STATE == G.STATES.SHOP
 
             if pack_closed and back_to_shop then
+              selection_in_progress = false
               sendDebugMessage("Return pack() after selection", "BB.ENDPOINTS")
               send_response(BB_GAMESTATE.get_gamestate())
               return true
             end
+
+            -- Debug: log what's blocking
+            local state_name = "?"
+            if G.STATES then
+              for name, value in pairs(G.STATES) do
+                if value == G.STATE then state_name = name break end
+              end
+            end
+            sendDebugMessage(string.format(
+              "pack() wait: closed=%s state=%s complete=%s choices=%s won=%s",
+              tostring(pack_closed), state_name, tostring(G.STATE_COMPLETE),
+              tostring(G.GAME.pack_choices), tostring(G.GAME.won)
+            ), "BB.ENDPOINTS")
           end
           return false
         end,
@@ -279,6 +308,7 @@ return {
 
     -- Handle skip
     if args.skip then
+      selection_in_progress = false  -- Clear guard so skip can proceed after stuck selection
       local pack_count = G.pack_cards.config and G.pack_cards.config.card_count or 0
       sendDebugMessage(string.format("Pack: skipping (%d cards remaining)", pack_count), "BB.ENDPOINTS")
       G.FUNCS.skip_booster({})
@@ -304,12 +334,10 @@ return {
     end
 
     -- Wait for hand cards to load for Arcana and Spectral packs
-    local pack_key = G.pack_cards
-      and G.pack_cards.cards
-      and G.pack_cards.cards[1]
-      and G.pack_cards.cards[1].ability
-      and G.pack_cards.cards[1].ability.set
-    local needs_hand = pack_key == "Tarot" or pack_key == "Spectral"
+    -- Check if hand cards are dealt (Arcana/Spectral packs deal hand cards).
+    -- Don't infer pack type from the first card's set — Black Hole is
+    -- set=Spectral but appears in Celestial packs, causing a false match.
+    local needs_hand = G.hand and G.hand.cards and #G.hand.cards > 0
 
     if needs_hand then
       -- Wait for hand cards to be fully loaded and positioned

src/lua/endpoints/play.lua

@@ -3,6 +3,8 @@
 ---@type BB_LOGGER
 local BB_LOGGER = assert(SMODS.load_file("src/lua/utils/logger.lua"))()
 
+-- Win overlay state is now tracked in BB_GAMESTATE (shared with love.update)
+
 -- ==========================================================================
 -- Play Endpoint Params
 -- ==========================================================================
@@ -92,8 +94,6 @@ return {
     G.E_MANAGER:add_event(Event({
       trigger = "condition",
       blocking = false,
-      blockable = false,
-      created_on_pause = true,
       func = function()
         -- State progression:
         -- Loss: HAND_PLAYED -> NEW_ROUND -> (game paused) -> GAME_OVER
@@ -121,12 +121,10 @@ return {
             return false
           end
 
-          -- Game is won
-          if G.GAME.won then
-            sendDebugMessage("Return play() - won", "BB.ENDPOINTS")
-            local state_data = BB_GAMESTATE.get_gamestate()
-            send_response(state_data)
-            return true
+          -- Game is won — love.update auto-dismisses the overlay.
+          -- Wait here until that's done before looking for cash_out button.
+          if G.GAME.won and not BB_GAMESTATE.win_overlay_dismissed then
+            return false
           end
 
           -- Wait for first scoring row (blind1) to be added to the UI

src/lua/endpoints/rearrange.lua

@@ -185,8 +185,10 @@ return {
       G.consumeables.cards = new_array
     end
 
-    -- Update order fields on each card
+    -- Update order fields, rank, and visual positions on each card
     for i, card in ipairs(new_array) do
+      -- Set rank so align_cards() respects our ordering
+      card.rank = i
       if rearrange_type == "hand" then
         card.config.card.order = i
         if card.config.center then
@@ -202,6 +204,19 @@ return {
       end
     end
 
+    -- Trigger visual re-layout (mirrors gamepad d-pad reordering in controller.lua)
+    local area
+    if rearrange_type == "hand" then
+      area = G.hand
+    elseif rearrange_type == "jokers" then
+      area = G.jokers
+    else
+      area = G.consumeables
+    end
+    table.sort(area.cards, function(a, b) return a.rank < b.rank end)
+    area:set_ranks()
+    area:align_cards()
+
     -- Wait for completion: state should remain stable after rearranging
     G.E_MANAGER:add_event(Event({
       trigger = "condition",

src/lua/endpoints/sell.lua

@@ -121,17 +121,13 @@ return {
       trigger = "condition",
       blocking = false,
       func = function()
-        -- Check all 5 completion criteria
         local current_area = sell_type == "joker" and G.jokers or G.consumeables
         local current_array = current_area.cards
 
-        -- 1. Card count decreased by 1
-        local count_decreased = (current_area.config.card_count == initial_count - 1)
-
-        -- 2. Money increased by sell_cost
+        -- 1. Money increased by sell_cost
         local money_increased = (G.GAME.dollars == expected_money)
 
-        -- 3. Card no longer exists (verify by unique_val)
+        -- 2. Card no longer exists (by sort_id)
         local card_gone = true
         for _, c in ipairs(current_array) do
           if c.sort_id == card_id then
@@ -140,14 +136,16 @@ return {
           end
         end
 
-        -- 4. State stability
+        -- 3. State stability
         local state_stable = G.STATE_COMPLETE == true
 
-        -- 5. Still in valid state
+        -- 4. Still in valid state
         local valid_state = (G.STATE == G.STATES.SHOP or G.STATE == G.STATES.SELECTING_HAND)
 
-        -- All conditions must be met
-        if count_decreased and money_increased and card_gone and state_stable and valid_state then
+        -- Note: card count is NOT checked here — some jokers (e.g. Invisible Joker)
+        -- spawn a replacement on sell, leaving count unchanged. card_gone + money_increased
+        -- uniquely identify completion without relying on count.
+        if money_increased and card_gone and state_stable and valid_state then
           sendDebugMessage("Return sell()", "BB.ENDPOINTS")
           send_response(BB_GAMESTATE.get_gamestate())
           return true

src/lua/endpoints/set.lua

@@ -12,6 +12,7 @@
 ---@field hands integer? New number of hands left number
 ---@field discards integer? New number of discards left number
 ---@field shop boolean? Re-stock shop with new items
+---@field blind string? Boss blind key (e.g. "bl_flint") — sets the upcoming boss blind
 
 -- ==========================================================================
 -- Set Endpoint
@@ -60,6 +61,11 @@ return {
       required = false,
       description = "Re-stock shop with new items",
     },
+    blind = {
+      type = "string",
+      required = false,
+      description = "Boss blind key (e.g. 'bl_flint') — sets the upcoming boss blind",
+    },
   },
 
   requires_state = nil,
@@ -87,6 +93,7 @@ return {
       and args.hands == nil
       and args.discards == nil
       and args.shop == nil
+      and args.blind == nil
     then
       send_response({
         message = "Must provide at least one field to set",
@@ -167,6 +174,19 @@ return {
       G.GAME.current_round.discards_left = args.discards
     end
 
+    -- Set boss blind
+    if args.blind then
+      if not G.P_BLINDS[args.blind] then
+        send_response({
+          message = "Unknown blind key: " .. tostring(args.blind),
+          name = BB_ERROR_NAMES.BAD_REQUEST,
+        })
+        return
+      end
+      G.GAME.round_resets.blind_choices.Boss = args.blind
+      G.RESET_BLIND_STATES = true
+    end
+
     if args.shop then
       if G.STATE ~= G.STATES.SHOP then
         send_response({

src/lua/endpoints/start.lua

@@ -102,9 +102,16 @@ return {
       return
     end
 
+    -- Reset win overlay flags from previous run
+    BB_GAMESTATE.win_overlay_dismissed = false
+    BB_GAMESTATE.win_overlay_dismissing = false
+
     -- Reset the game (setup_run and exit_overlay_menu)
-    G.FUNCS.setup_run({ config = {} })
-    G.FUNCS.exit_overlay_menu()
+    -- Use pcall to handle cases where the overlay isn't fully ready
+    pcall(function()
+      G.FUNCS.setup_run({ config = {} })
+      G.FUNCS.exit_overlay_menu()
+    end)
 
     -- Find and set the deck using the mapped deck name
     local deck_found = false
@@ -144,7 +151,21 @@ return {
         .. tostring(args.seed or "none"),
       "BB.ENDPOINTS"
     )
-    G.FUNCS.start_run(nil, run_params)
+    local ok, err = pcall(G.FUNCS.start_run, nil, run_params)
+    if not ok then
+      sendDebugMessage("start_run failed: " .. tostring(err) .. " — retrying after delete_run", "BB.ENDPOINTS")
+      -- Clean up stale state and retry
+      pcall(function() G:delete_run() end)
+      local ok2, err2 = pcall(G.FUNCS.start_run, nil, run_params)
+      if not ok2 then
+        sendDebugMessage("start_run retry also failed: " .. tostring(err2), "BB.ENDPOINTS")
+        send_response({
+          message = "Failed to start run: " .. tostring(err2),
+          name = BB_ERROR_NAMES.INTERNAL_ERROR,
+        })
+        return
+      end
+    end
 
     -- Wait for run to start using Balatro's Event Manager
     G.E_MANAGER:add_event(Event({