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 four states: working, waiting, ready, and error. Each maps to one light color in the menu bar.

error means the session's own machinery failed — the provider refused or failed the call, credentials were rejected, the agent process died mid-turn, or Irrlicht could not read the session. It is not a tool failure: a grep that matched nothing and a build that broke are the agent working normally.

Two things clear it, on different conditions. Your next message clears it immediately, before the new turn's outcome is known — someone who has typed again has moved on, and holding the old failure against the new turn would pin the session red for the rest of its life. A completed turn also clears it, but only when the failure was a retrying one; a terminal failure is not retired by a turn boundary. Neither edge is a timeout and neither has a minimum hold.

A process that died mid-turn is always recorded as terminal — a process that exited will not try again — so neither of those applies to it. Its row is kept in error for 12 hours and then reaped, so a crash at 22:00 is still visible at 08:00.

Note that the last two rows clear the failure on different conditions: your next message clears it outright, while a completed turn clears it only when the failure was a retrying one. A process death is terminal, so it leaves error by neither — it ages out of the list instead.

Impossible Transitions

Two transitions are structurally impossible and the state machine enforces this. Both constrain only working, waiting and ready — no impossibility is claimed about error in either direction.

Whether error or waiting wins is decided per cause, not once. A dead process outranks waiting: it leaves any open question unanswerable forever, and sending someone to answer a question in a process that no longer exists is worse than saying nothing. A provider failure on a live session is the other way round — if that session then opens a blocking tool, it reads waiting.

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 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)
• copilot — GitHub Copilot CLI (JSONL events.jsonl under ~/.copilot/session-state, relocatable via $COPILOT_HOME)
• hermes — Hermes Agent (no transcript files; one shared SQLite store at ~/.hermes/state.db, relocatable via $HERMES_HOME)

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. Folding it into ready keeps the state model free of a value that would carry no information the user could act on.

Lifecycle Event Kinds

Underneath the state machine, 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.