# 05 — Failure modes

Every entry below was observed **live**, caused a real infinite loop or a
stalled run, and has a fix in the code. None are theoretical.

The general lesson: this interface is full of actions that report
`{"status": "ok"}` while doing nothing. **Never trust `ok`. Trust the state.**

---

## 1. `claim_reward(index=0)` forever

`rewards.items[]` is rebuilt and **re-indexed from 0 after every claim**.
Claiming index 0 repeatedly reclaims the same slot forever.

Observed: 65 consecutive rejected `claim_reward(index=0)` calls.

**Fix:** claim right-to-left, `items[-1]`.

## 2. A potion reward with full slots silently vanishes

When all potion slots are full, `claim_reward` on a potion reward returns
`ok` and is **silently dropped**. The item never leaves `items[]`, so the loop
never terminates.

Observed:

```
potions: 3 of max_potion_slots 3
claim_reward(1) -> ok | Claiming reward: potion (Energy Potion)
   items now: [gold, potion]        <- unchanged
claim_reward(0) -> ok | Claiming reward: gold (19)
   items now: [potion]              <- re-indexed
```

**Fix:** if the last item is a potion and `len(potions) >= max_potion_slots`,
discard the weakest potion first, then claim. Weakness comes from a small
`POTION_VALUE` table in `brain.py`.

## 3. `select_card` twice on one index freezes the screen

On grid screens `select_card` **toggles**. The second call deselects, so the
state never changes and the loop stalls.

Observed: `select_card(index=0)` twice, then 10 unchanged reads.

**Fix:** when `preview_showing` and `can_confirm` are true, the action is
`confirm_selection`, never another `select_card`.

## 4. A stale preview makes `confirm_selection` a no-op

`confirm_selection` returns `ok` while changing nothing, when the preview was
left over from a desynchronised state.

Observed:

```
confirm_selection -> ok  "Confirming selection from preview"
state_type before/after: card_select -> card_select
sig changed: False
```

**Fix:** if the identical `card_select` state is seen twice in a row, the
confirm did not take effect. Send `cancel_selection` to reset, then re-select.
Verified working:

```
cancel_selection -> preview False
select_card(0)   -> preview True
confirm_selection-> state_type becomes 'event'
```

## 5. `rest_site` options use `name`, not `title`

Reading `options[].title` yields `None` for every option, so the handler
concluded there were no options and fell through to a rejected `proceed`.

**Fix:** read `name` (plus `id`), and honour `is_enabled`.

## 6. `treasure` claims a relic before the chest opens

The chest auto-opens. During opening the response has no `relics` key and no
`can_proceed`, so `claim_treasure_relic` is rejected repeatedly.

Observed: 4 consecutive rejections.

**Fix:** wait while `relics` is absent; claim only when present.

## 7. Acting during transitions

The loop re-decided faster than the game animated:

- `choose_map_node` fired **3 times in a row** during a single travel.
- `end_turn` fired repeatedly during the enemy turn.

**Fix, two parts:**

- `__wait__` when `battle.is_play_phase` is false.
- An **unchanged-state guard** in `run.py`: if the state signature repeats and
  the **last action succeeded**, wait. If the last action was **rejected**,
  re-decide instead, so a different action can be tried.

The second condition matters: waiting on a rejected action would prevent
recovery and stall until the stuck counter fires.

## 8. `unknown` and `overlay` treated as dead ends

Both are transitions, not terminal states. Returning "stop" ended the session
while the game was mid-transition into combat.

**Fix:** wait and re-observe. The unchanged-state guard bounds this, so a
genuine dead end still stops after 10 reads.

## 9. The confidence gate rejected a correct answer

Not a loop, but a wrong decision, and worth recording because the bug was in
**our** gate rather than in the model.

Measured: 5 cards offered. Jev picked `Bash` at **0.61** probability with
`Defend` at 0.29, and reported `confidence 0.50`. A fixed 0.55 floor rejected
it and fell back to a heuristic that chose to block instead.

`confidence` measures peakedness, so it falls as the option count rises:
`(5 × 0.61 − 1) / 4 = 0.50`.

**Fix:** gate a `Choice` on margin over the runner-up
(`top >= 0.45 and top - runner >= 0.20`), which is scale-free. See
[02](02-system-one-jev.md).

---

## Checklist for a new `state_type`

1. Capture the real shape. Do not code from documentation.
2. Check which fields are **absent** in some states.
3. Ask: what does this action return when it is a no-op?
4. Prefer `__wait__` over stopping for anything that looks transitional.
5. Add a guard so a repeated identical state does not loop forever.

## Checklist for a new action

1. Does it report `ok` on a no-op? (Most do.)
2. Does it re-index the collection it acts on?
3. Is there a precondition the state exposes (`can_confirm`, `can_proceed`,
   `is_stocked`, `can_afford`) that should be checked first?
4. Does it toggle?

---

# Session 2 additions

## 10. An event option ended the run, and the gate allowed it

Measured on a deciphering event:

```
[102] jev chose Keep Deciphering    conf=0.28
[104] jev chose Lose Everything     conf=0.49
```

"Lose Everything" **set the player's max HP to 1**. The margin gate passed it,
because the gate only measured how *decisive* the answer was, never how
*consequential* the action was.

**Fix, in two parts:**

1. A stricter gate for events: `top >= 0.60 AND margin >= 0.30`.
2. A deterministic safety net. When the model is not confident, choose the
   option with the lowest `event_safety_rank`, which counts risk words
   ("everything", "keep", "continue", "gamble", "lose") minus stop words
   ("stop", "leave", "refuse", "decline", "take what").

**A "does this risk losing the run?" Noul was tried and REMOVED.** Measured on
the same event:

| Option | Risk Noul |
|---|---|
| "Lose Everything" | **0.46** |
| "Keep Deciphering" | **0.52** |
| "Stop" | 0.38 |

It ranked the run-ending option as *less* risky than a moderate one. A
misleading signal is worse than no signal, so danger is detected by keywords
instead. Keep the model for the confident case; use code for the dangerous one.

## 11. `hp=1/1` was reported as "healthy"

An effect reduced max HP to 1. `_hp_bucket` bucketed by percentage alone, so
`1/1` was 100% and returned `healthy`. The bot walked into a normal fight at
1 HP and died.

**Fix:** absolute HP is now part of the bucket. `hp <= 5` is always `critical`.

```python
def _hp_bucket(pct, hp=None):
    if hp is not None and hp <= 5:
        return HP_CRITICAL
    ...
```

## 12. `hand_select` blindly selected index 0

`combat_select_card(index=0)` failed with:

```
Card index 0 out of range (0 selectable cards)
```

`hand_select` has `cards` (still selectable) and `selected_cards` (already
chosen). When `cards` is empty the only useful action is
`combat_confirm_selection`.

**Fix:** confirm when nothing remains selectable; otherwise give up basic
Strikes first, then Defends.

## 13. `bundle_select` has the same preview trap as `card_select`

```
A bundle preview is already open - confirm or cancel it first
```

Same shape (`preview_showing`, `can_confirm`) and same fix: confirm when a
preview is showing, and reset with `cancel_bundle_selection` if the identical
state repeats.

## 14. Error text lives in `error`, not `message`

`ActionResult` read only `message`, so every rejection printed as
`action rejected:` with nothing after it. This hid four separate bugs for a
whole session.

**Fix:** `message = data.get("message") or data.get("error") or ""`.

**Lesson:** make failures loud before chasing them. A blank error message is
worse than no error handling.

## 15. `can_proceed` is not reliable

For shops, `shop.can_proceed` was `false` while `proceed()` worked and moved the
game to the map. Waiting on that flag stalls forever.

**Fix:** do not gate an exit on `can_proceed`. Attempt `proceed` and let the
rejection counter bound the retries.

## 16. The unchanged-state guard was count-based

A boss death animation plus the rewards transition exceeded 10 reads, so the
guard declared STUCK while the game was still animating.

**Fix:** the guard is now time-based (`--stuck-seconds`, default 25 s).

## 17. Transient rejections are normal

`proceed` at a rest site right after a heal is rejected for a moment and then
succeeds. The retry loop was too impatient.

**Fix:** on rejection, back off 3x the normal pause, and allow 6 attempts.

---

# Session 3 — the programmatic audit

Prompted by observing that the bot "was only upgrading common attack cards".
These are usage bugs, not decision-quality issues, and are listed separately
from the tuning items.

## 18. `card_select` fallback was hardcoded to `cards[0]`

The upgrade screen fell back to the first card in the list, and the list is
ordered with basic Strikes first. So every fallback upgraded a Strike.

Measured across runs:

```
[156] [fallback] select_card(index=0)  # select the first card
[263] [fallback] select_card(index=0)  # low confidence; select the first
[378] [fallback] select_card(index=0)  # low confidence; select the first
```

The fallback fired often because a single `Choice` over a 13+ card deck
dilutes, exactly like the shop.

**Fix, two parts:**

1. Re-ranking: one absolute `Noul` per card, argmax in code.
2. Screen-aware deterministic fallback (`upgrade_rank`, `removal_rank`) that
   never picks index 0 blindly:
   - upgrade prefers a non-basic card, then Bash, then Strikes, then Defends,
     and never an already-upgraded card
   - remove/transform invert the order: shed basic Strikes and Defends first,
     and never target an upgraded card

Verified live after the fix:

```
[197] jev chose Perfected Strike (noul=0.67)
[205] jev chose Bludgeon        (noul=0.66)
[212] jev chose Rampage         (noul=0.67)
[303] jev chose Bash            (noul=0.62)
```

## 19. `hand_select` fed good cards to a "choose any number" prompt

The give-up ranking returned `2` for anything that was not a Strike or Defend,
so once the basics ran out it started offering real cards:

```
[023] give up Uppercut
[086] give up Stomp
[171] give up Bash        <- the deck's only Vulnerable source
```

**Fix:** only basic Strikes and Defends are candidates. When none remain,
confirm and keep the good cards. A selection is forced only when
`can_confirm` is false.

## 20. `card_reward` had a redundant gate that skipped almost everything

A `want_any` Noul ("does this deck want any of these?") gated the whole
decision. When it was merely *uncertain* (0.54–0.59) the bot skipped, so it
skipped nearly every card reward and ran a 10-card deck.

**Fix:** the per-card Nouls ARE the signal. Skip only when no card clears
`CARD_PICK_THRESHOLD`.

## 21. A skipped card reward is NOT consumed — infinite loop

```
[409] skip_card_reward()          # no card cleared 0.6
[410] claim_reward(index=2)
[411] skip_card_reward()
[412] claim_reward(index=2)       ... forever
```

Skipping returns to the rewards screen with the card **still listed**. Claiming
it again reopens the card screen, and the cycle repeats.

Verified directly: `skip_card_reward` -> `ok`, then the rewards list still
contains `[2] card: Add a card to your deck.`

**Fix:** record that a card reward was skipped, and ignore card rewards on the
rewards screen afterwards. `rewards` and `card_reward` are declared one
**screen group** so the flag survives the hop between them — otherwise it is
cleared on every transition and the loop returns.

## 22. Module-level guards leaked across screens

Found by the new `test_brain.py`. A fresh fake-merchant shop was reported as
"unchanged after a purchase" because a shop signature from an earlier screen
was still set.

**Fix:** `_reset_screen_guards()` clears all per-screen state whenever the
screen group changes. Also made the shop guard precise: it now only fires when
we actually purchased from that exact shop state.

## 23. `fake_merchant` nests its inventory one level deeper

The shop is at `fake_merchant.shop.items`, not `shop.items`. Reading only
`obs["shop"]` made every fake-merchant shop look empty, so the bot left
immediately without buying.

**Fix:** resolve `obs["shop"]`, else `obs["fake_merchant"]["shop"]`, else
`obs["fake_merchant"]`.

## 24. `embark` is rejected without a character selected

```
action rejected: Embark button not available — select a character first
```

An earlier version assumed `embark` defaults to the first unlocked character.
It only worked once because a character happened to be selected already.

**Fix:** read the game's own `message`:
- `"Select a character."` -> select one
- `"Selected The Ironclad. Use 'confirm' to embark."` -> embark

## 25. `relic_select` used a diluted Choice and ignored `can_skip`

Verified shape: `relic_select.relics[]` with `index/id/name/description/rarity`
plus `can_skip`. It now uses the same re-ranking pattern, honours `can_skip`,
and falls back to the rarest relic rather than index 0.

## New: `test_brain.py`

A structural regression suite, deliberately separate from decision quality.
It asserts:

1. **Every `state_type` produces an action that is LEGAL for that state.**
   Compares against `sts2.LEGAL_ACTIONS`. This is what would have caught a
   handler emitting `end_turn` during someone else's turn.
2. **Every action the decision layer can emit is declared somewhere**, so a
   typo cannot silently produce an invalid action.
3. **Every fallback respects its inputs** — removal does not target an
   upgraded card, upgrade does not target a basic one, card reward takes the
   rarest rather than index 0, `hand_select` gives up a Strike rather than
   Bash.

54 assertions, runs offline with `client=None`, no model calls, no game.
Run it before every session.

---

# Session 4 — the toggle and transition traps

Found by running the bot for long stretches. Every one of these was a stall or a
crash, not a decision-quality issue.

## 26. `combat_select_card` TOGGLES — re-selecting deselects

The same trap as `card_select`, in a different action. Measured: **18
consecutive** `combat_select_card(card_index=0) # give up Defend` with the state
never changing, because selecting an already-selected card deselects it.

`hand_select.selected_cards` is the authoritative list of what is already
chosen. Exclude those from the candidate list.

**Watch out:** `cards[].index` and `selected_cards[].index` are **different
index spaces** (different arrays, independent counters). Names are the only
reliable way to match between them.

## 27. `hand_select` has a mode that only needs confirming

Measured state:

```
mode         = "upgrade_select"
prompt       = "Confirm Card to Upgrade"
cards        = [(0, "Defend")]
selected     = []
can_confirm  = true
```

Sending `combat_select_card` is a silent no-op here. The card is already picked;
`combat_confirm_selection` closes the screen and moves to `monster`.

**Fix:** mode-aware.

| mode | action |
|---|---|
| `upgrade_select` | `combat_confirm_selection` |
| `simple_select` | select cards, then confirm when nothing selectable remains |

## 28. Character select: no indicator, and flaky embark

Two problems at once:

1. **The state carries no "selected" indicator.** The mod hardcodes
   `result["message"] = "Select a character."` whatever is chosen. Verified in
   `AddCharacterSelectMenuState`. So the message cannot be used to tell whether
   a character is picked.
2. **Embarking right after selecting is flaky.** Measured three consecutive
   `Embark button not available - select a character first` rejections, because
   the selection had not registered yet.

**Fix:** ALTERNATE — select, embark, select, embark. A rejected embark is always
followed by a fresh select, so the sequence is self-correcting regardless of
timing.

An earlier attempt used signature comparison ("if the screen is unchanged, a
character was already selected"). It failed because the signature keeps changing
during the embark transition, restarting the cycle.

## 29. The run loop's guard blocked the brain's own recovery

`run.py` waited whenever the state was unchanged after a successful action, and
it did so **before calling `brain.decide`**. That made it impossible for any
handler to notice a repeated state and react differently — which is exactly how
`character_select` and multi-line dialogue work.

**Fix:** move the check to AFTER deciding, and suppress only a **repeated
action**, never acting in general. Proposing a *different* action is always
allowed.

## 30. A bounded retry is required

Even the corrected guard stalled on Ancient dialogue: one click was issued, the
state had not updated yet, and the guard then refused to retry forever.

**Fix:** `--max-duplicate-waits` (default 3). After that many suppressions on an
unchanged state, re-execute the action. Some actions legitimately need repeating
and some transitions are just slow.

## 31. `unknown` and `overlay` are transitions, not screens

Resetting the per-screen guards on them wiped state mid-flow. During embark the
state flickers through `unknown`, which cleared the character-select guard and
restarted the select/embark cycle.

**Fix:** `_reset_screen_guards` returns early for `unknown` and `overlay`.

## 32. `menu_screen` must be part of the screen key

`main`, `singleplayer`, `character_select` and `tutorial_prompt` all share
`state_type == "menu"` but have completely different valid actions. Keying only
on `state_type` meant moving from the main menu to character select did not
reset anything.

**Fix:** `_screen_group()` returns `menu:<menu_screen>` for the menu state.

## 33. `RemoteDisconnected` crashed a run

```
http.client.RemoteDisconnected: Remote end closed connection without response
```

`RemoteDisconnected` is an `http.client.HTTPException`, **not** a `URLError`, so
it escaped `jev.py`'s transport handler and killed the process mid-fight.

**Fix, both layers:**

- `jev.py` also catches `http.client.HTTPException` and `OSError`, and retries.
- `run.py` wraps `brain.decide` in a broad `except Exception`, falls back to the
  deterministic handlers, and keeps playing.

## 34. Known, self-correcting: stale-state rejections

Occasionally the game rejects a card we chose:

```
Card 'Infection' cannot be played: HasUnplayableKeyword
Card 'Evil Eye' cannot be played: EnergyCostTooHigh
```

`can_play` comes from the game's own `card.CanPlay()`, so the state was correct
when read. A Jev call takes ~0.75 s, so the state we decided on can be about a
second stale by the time the action lands.

This is a **race, not a logic bug**, and it self-corrects: the rejection sets
`last_ok = False`, so the loop re-decides immediately against a fresh state
instead of waiting. Cost is one wasted action. No revalidation pass is needed.

## Test coverage after this session

`test_brain.py`: **78 assertions**. New this session:

- indices must come from the data, never from list position (hostile-index
  cases where `index` deliberately differs from array position)
- `hand_select` skips already-chosen cards, including duplicate names
- `hand_select` confirms for `upgrade_select`
- character select alternates select/embark and resets correctly
- a `StubClient` makes the model paths testable offline and deterministically