Summary

KR-P2-CLEANUP ST5 of 5. KR-P2-I-integration ST5 (PR #35) flipped /api/operational-state from the hardcoded stub to a live OperationalStateHolder read without updating these tests. 4 of the 8 tests were failing on main — they asserted stub semantics that no longer apply, and the file lacked a holder-reset fixture so state leaked across tests.

Full rewrite around the two-branch endpoint shape

Uninitialized branch (autouse fixture clears holder; get_holder() returns None)

• test_uninitialized_branch_returns_stub_with_error — asserts stub: True + error field + "not yet initialized" in the message
• test_uninitialized_branch_top_level_shape — asserts the 8-key shape (incl. stub + error) + cold defaults (primary_state="booting", claim_permission="none", empty transition_history, empty valid_next_states)
• test_uninitialized_branch_uses_only_valid_enum_values

Live branch (init_holder + transition)

• test_live_branch_returns_real_state_without_stub_or_error — confirms neither field appears on the live path
• test_live_branch_transition_history_populated_after_transition — after one transition the history ring has the entry with the documented shape + correct from_state / to_state / trigger
• test_live_branch_valid_next_states_derived_from_transition_table — READY advertises ACTIVE / PAUSED / STOPPED arrows
• test_live_branch_degradation_reasons_render_sorted — stable alphabetical ordering + is_degraded=True with multiple reasons

Plus

• Existing 200 sanity check
• Cron-regression sanity

New autouse fixture — _reset_holder

Clears the OperationalStateHolder singleton via _reset_holder_for_tests before AND after every test. Without this, prior test runs in the same file (or run-order) leak holder state, which is why the original 4 tests intermittently passed/failed depending on ordering.

Mock-fixture pattern documented

The module docstring spells out the two-branch coverage requirement so future endpoint changes update both branches in lockstep. The "PR #35 flipped without updating tests" gap is the load-bearing reason this ST exists; documenting the pattern is half the fix.

Honest scope

• Tests-only change. Zero production-code edits — the endpoint itself is correct as-merged in PR feat(KR-P2-I-integration ST5): flip /api/operational-state stub → real + add history ring #35. ST5's job is realignment, not redesign.
• The _VALID_* enum-value sets retained from the original test file.

Sub-task chain — final ST of this bucket

Test plan

• CI green on pytest tests/kora_cli/test_web_server_operational_state.py
• All 4 previously-failing tests now pass

🤖 Generated with Claude Code