State Machine

Deterministic session state transitions. Files → State → Light.

Session Lifecycle

Every session follows a deterministic lifecycle from process discovery through transcript creation to eventual cleanup. The state machine never guesses — it reacts to concrete filesystem and process events.

State Transitions

Once a session is active, it moves between exactly three states: working, waiting, and ready. These map directly to the three light colors in the menu bar.

Impossible Transitions

Two transitions are structurally impossible and the state machine enforces this:

Detection Logic

The state machine reads raw transcript events and applies two key predicates to determine transitions.

NeedsUserAttention() — triggers waiting

Evaluates to true when all of the following hold:

• HasOpenToolCall = true
• LastOpenToolName is one of {AskUserQuestion, ExitPlanMode}

When this predicate fires, the session transitions to waiting. The light turns orange.

IsAgentDone() — triggers ready

Two detection paths, checked in order:

• Primary: LastEventType == "turn_done"
• Fallback: HasOpenToolCall = false AND LastEventType is one of {assistant, assistant_output}

When either path matches, the session transitions to ready. The light turns green.

Turn Completion Signals

Two transcript event types signal the end of an agent turn:

• turn_duration — emitted at the end of each agent turn. This is the primary signal.
• stop_hook_summary — emitted after stop hooks run. Used as a fallback when turn_duration is not present.

Pre-Sessions

When the daemon's process scanner (pgrep -x claude) discovers a new Claude Code process, it creates a synthetic pre-session with the ID proc-<pid>. This pre-session exists because the user has opened Claude Code but has not yet sent a message — no transcript file exists yet.

The pre-session lifecycle:

1. Process scanner detects a new claude PID not already tracked.
2. A synthetic session proc-<pid> is created in ready state.
3. The daemon watches for a .jsonl transcript file to appear via fsnotify.
4. When the real transcript appears, the pre-session is deleted and replaced by a real session keyed to the transcript path.
5. If the process exits before any transcript appears, the pre-session is simply cleaned up.

Subagent Detection

Claude Code can spawn sub-agents (child tasks). Irrlicht detects parent-child relationships between sessions and exposes this through the subagentSummary structure (JSON key subagents).

The summary tracks subagent counts by state:

type subagentSummary struct {
    Total   int  // total subagent count across all states
    Working int  // subagents currently executing
    Waiting int  // subagents blocked on user input
    Ready   int  // subagents that have finished their turn
}

The parent session's state display incorporates subagent status. If the parent is ready but a child subagent is working, the parent's effective state adjusts accordingly — the light reflects the most "active" state across the tree.

Orthogonal Axes

Beyond the three core states, the state machine tracks several orthogonal dimensions that do not affect the primary state transition logic but provide additional context.

Adapter

Identifies which AI coding agent is running:

• claude-code — Anthropic's Claude Code CLI
• codex — OpenAI's Codex CLI
• pi — Pi (Inflection) agent
• aider — Aider (transcript-driven REPL)
• opencode — OpenCode (SQLite-backed storage)
• kiro-cli — AWS Kiro CLI (JSONL transcripts + metadata sidecar)
• gemini-cli — Google Gemini CLI (JSONL transcripts under ~/.gemini/tmp)
• antigravity — Antigravity CLI/IDE (JSONL transcripts under ~/.gemini/antigravity{,-cli}/brain)
• mistral-vibe — Mistral Vibe (JSONL transcripts + meta.json sidecar under ~/.vibe/logs/session)

The adapter determines which transcript format is parsed and which process signatures are scanned. Frontends should look up adapter display name and icon via GET /api/v1/agents rather than hardcoding switches.

PressureLevel

Tracks context window utilization as a pressure indicator:

Cancellation

When the user presses ESC during an agent turn, Claude Code writes a user event whose text content starts with [Request interrupted by user. Irrlicht detects this specific marker to distinguish a real ESC from benign tool failures (a grep with no matches, a failing build, a find hitting a protected directory) which also set is_error=true but should not end the turn.

Cancellation maps directly to ready. There is no intermediate "cancelled" state. The detection logic:

• LastWasUserInterrupt = true signals the ESC marker was seen.
• The agent stops executing, so IsAgentDone() fires.
• The session transitions to ready.

This is a deliberate design choice. From the user's perspective, a cancelled turn is equivalent to a completed turn — the agent is idle and waiting for the next message. The three-state model (working / waiting / ready) remains clean and unambiguous.

Lifecycle Event Kinds

Underneath the three-state model, the daemon records a lower-level stream of typed events for session recording and replay — not just transcript-derived state transitions but also process lifecycle, filesystem, debounce, and parent-child signals. Each event carries a Kind discriminant (core/domain/lifecycle/event.go); this table enumerates all 18 constants, grouped as the source file itself groups them.