Code review P3: robustness — loud failures instead of hangs, silent skips, and bare AssertionErrors

[HansGR]

Third of five stacked code-review PRs (performed by Anthropic Fable 5, June, 2026). Based on the P2 PR — merge P1 and P2 first. This tier's own commits are 9e69bc4..471fbd8.

What's included (4 commits)

• 9e69bc4 — validation asserts → informative exceptions in seed-generation paths. Asserts vanish under python -O and give users a bare AssertionError when they fire. Converted: the choose_reward gating-deadlock check (event/event_reward.py, the failure documented in agents.md — now names the reward types involved), the CHARACTER_ESPER_ONLY_REWARDS count validation (event/events.py), Space.clear() size mismatch (now reports both sizes), Set/ClearEventBit range checks (now also reject negative bits, which would corrupt the opcode), and args/starting_party.py user-input asserts (now parser.error() like other arg modules).
• 7556821 — guards on unbounded retry loops. Three rejection-sampling loops could spin forever if their progress assumption broke: esper spell shuffle (data/espers.py) and shop shuffle (data/shops.py) now raise a descriptive error after 10,000 consecutive failed picks (false-trigger probability when progress is possible: ~(26/27)^10000 ≈ 10⁻¹⁶³) or when the candidate pool empties; the character-gating loop (event/events.py) raises a clear "deadlock" error where it previously crashed with a bare TypeError; utils/truncated_discrete_distribution.py's unbounded recursion became a capped loop — impossible bounds now raise ValueError instead of recursing forever (test added). The guards consume no RNG and the success paths are unchanged.
• 72473eb — bare except: → specific exceptions in six args/ modules (ValueError for int conversion, AttributeError for non-string menu values), so real bugs in menu generation can no longer be swallowed.
• 471fbd8 — Pillow import guard + UTF-8 log. The PNG conversion tools import PIL, contradicting the documented "standard library only" requirement — a missing install now produces a clear message, and agents.md documents the optional dependency. The spoiler log encoding was platform-dependent (cp1252 on Windows); now explicitly UTF-8.

Seed compatibility

Verified byte-identical ROMs (SHA-256) against the pre-change baseline for three flagsets, including -ess -sisr 25 which runs through both modified shuffle loops. Spoiler logs identical.

https://claude.ai/code/session_01QnF26DB2TYi1hpJE8L6EJr

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive suite of unit tests, improves error handling by replacing bare assertions and generic exceptions with specific errors, and fixes several bugs, including an incorrect calculation for character run success and potential infinite loops in randomizer shufflers. However, the review identified two critical issues: first, a return opts statement was accidentally deleted in args/challenges.py, which will break menu and metadata generation; second, the truthiness checks for bounds in utils/truncated_discrete_distribution.py will fail when a bound is set to 0, so explicit is not None checks should be used instead.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The return opts statement was accidentally removed from the options function while deleting the duplicate _format_spells_log_entries definition. This will cause options(args) to implicitly return None, breaking menu/metadata generation.

Suggested change

	]
	return opts
	def _format_spells_log_entries(spell_ids):
	from constants.spells import id_spell
	spell_entries = []
	for i, spell_id in enumerate(spell_ids):
	spell_entries.append(("", id_spell[spell_id], f"rls_{i}"))
	return spell_entries
	]
	return opts

[gemini-code-assist]

Using if minimum and if maximum to check if bounds are specified will fail if minimum or maximum is 0, because 0 is falsy in Python. This would cause the bounds check to be skipped when 0 is used as a bound. Use is not None to safely check for bounds.

Suggested change

	if minimum and result < minimum:
	continue
	if maximum and result > maximum:
	continue
	if minimum is not None and result < minimum:
	continue
	if maximum is not None and result > maximum:
	continue