Formalize session lifecycle as explicit state machine

[james-in-a-box]

Context

The Entireio CLI models session lifecycle as an explicit state machine:

• Three phases: IDLE → ACTIVE → ENDED
• Five triggering events: TurnStart, TurnEnd, GitCommit, SessionStart, SessionStop
• Context-aware transitions that declare actions (not execute them)
• Automatic Mermaid diagram generation for documentation

This makes session behavior predictable and debuggable — every state transition is explicit and logged.

Current State

Our gateway manages session lifecycle (creation, heartbeat, deletion) but transitions are implicit — they happen as side effects of API calls rather than through a formal state machine. This makes it harder to reason about edge cases (e.g., what happens if a session gets a heartbeat after it's been marked for cleanup?).

Proposal

Formalize session lifecycle as an explicit state machine in the gateway:

• Define states: CREATED → ACTIVE → ENDING → ENDED (and error states)
• Define events that trigger transitions
• Make transitions declare side effects rather than executing them inline
• Log all transitions for debugging
• Generate state diagram documentation

This would make session management more predictable and easier to debug, especially for edge cases around container crashes and cleanup races.

Reference

See entireio/cli — session state machine in the strategy package.

Authored-by: egg