Summary

KR-P2-I-integration ST5 of 5. Flips /api/operational-state from the hardcoded stub to a live read of the OperationalStateHolder, and adds the in-memory transition-history ring that the admin panel renders. Stacked on top of #34 (ST3) — base is feat/kora-KR-P2-I-integration-st3-provider-wire. Retarget to main once ST3 merges.

Two changes in this PR

1. OperationalStateHolder — transition history ring buffer

• New TransitionRecord frozen dataclass: (timestamp, from_state, to_state, trigger). to_dict() matches the endpoint's transition_history row shape.
• _history: deque[TransitionRecord] with maxlen=10. Appended under the holder lock at the end of transition_to (after the held-state swap) so ordering matches the swap.
• New holder.history(limit=10) returns a snapshot list of dicts.
• Bounded at 10 deliberately — durable history lives in the chain-event log (every transition writes kora.operational_state.transitioned via ST2's emit listener). The ring is for the admin panel's immediate-history view and dies on process restart, matching Hermes-fork session-state semantics.

2. /api/operational-state — endpoint flip

• When get_holder() is initialized: response carries the live state. transition_history from holder.history(limit=10); valid_next_states derived from transitions_from(state.primary_state); the stub flag is dropped. CC#2's admin panel auto-stops rendering its stub banner when the field is absent.
• When get_holder() returns None (boot incomplete, or the IsoKron provider failed to construct): response uses the stub-shape with stub: True PLUS an error field set to "OperationalStateHolder not yet initialized". The panel can render this distinctly from the cold-stub banner so operators can distinguish "no wire-in yet" from "real runtime is up."

Tests — tests/test_operational_state_endpoint.py (266 LOC)

8 cases:

Ring buffer mechanics

• transition_to appends the (from, to, trigger) record under the lock
• Ring is bounded at 10 — 12 transitions ⇒ oldest 2 dropped
• history(limit=N) clamps the snapshot size; asking for more than we have returns all
• TransitionRecord.to_dict() shape matches the endpoint dict
• Timestamps are ISO-8601 UTC (%Y-%m-%dT%H:%M:%SZ) — round-trippable

Endpoint flip

• Uninitialized holder branch: stub: True + error field + empty history/next-states
• Initialized branch: no stub key, no error key, live state surfaces correctly
• degradation_reasons rendered alphabetically (cockpit diff stability)
• All 6 keys from the v1 stub still present on the live path — CC#2's panel wiring stays compatible

Honest scope

• No CC#2 OPS-PANEL changes. Per spec §6 ship checklist: "CC#2's OPS-PANEL still renders correctly after stub-flip (manual smoke check on flyctl proxy 9119:9119 or equivalent local run)." I haven't touched the panel; if any banner stops rendering correctly after this lands, that's a CC#2-side fix.
• In-memory ring resets on restart. The chain-event log is the durable source of truth. The ring is intentionally throwaway.

Sub-task chain (this bucket)

Test plan

• CI green on pytest tests/test_operational_state_endpoint.py
• Manual smoke (CC#2 panel compatibility): after merge, run flyctl proxy 9119:9119 against a live Kora and confirm the admin panel renders the operational-state card with no stub banner. Trigger a synthetic transition (e.g. via a future test command) and watch the history ring populate
• Manual smoke (uninitialized branch): boot with MEMORY_PROVIDER unset so the IsoKron provider never constructs; confirm the panel renders the new OperationalStateHolder not yet initialized banner instead of the cold-stub banner

🤖 Generated with Claude Code