Activity states

Four independent layers feed a terminal pane’s state, and the latest report sets it. A hook report holds off the title layer for a moment, and the process layer only claims a pane that no other layer has claimed. A chat reports its own state, since Sirio drives its agent: running while a turn streams, even while a question waits in the dock, and done once a turn has ended.

The layers

1. Hooks (Layer A). Agents with hooks call sirioctl notify --status … themselves; see Hooks and sirioctl notify. This is authoritative when present, and it holds off the title layer for a second and a half afterwards.
2. Terminal title (Layer B). Every CLI has its own title convention. Claude idles as ✳ … and works as . … or a braille spinner; Pi titles π - <cwd>; Oh-My-Pi titles π: <cwd>. Sirio reads identity and status from these.
3. Screen content (Layer C). When output settles, Sirio matches the end of the pane’s output against prompts and permission requests.
4. Foreground process (Layer D). Sirio inspects the pane shell’s child processes and matches them against the agent catalogue. This is the only layer that sees agents with no usable title.

The states

State	Meaning
Running	The agent is working, or Sirio has found its process and no other layer says more
Needs input	A question, a permission prompt, or an agent waiting at its idle prompt
Done	The agent finished: a chat’s turn ended, a hook reported done, or the pane’s own process exited with status 0
Error	A hook reported an error, or the pane’s own process exited with a failure
Idle	No layer reports a state, as in a plain shell or a chat before its first turn

Where a state shows

• The worktree card in the sidebar shows the most urgent state among its own tabs as a bloom. It keeps moving while an agent runs, and stops once the state settles: green for done, amber for needs input, red for an error. Each terminal and chat mark on the card carries a dot for its own state, and a folded project shows the most urgent state among its worktrees.
• The Sessions tab lists every agent session with its state. While Projects is showing, the tab carries a dot when a session needs input or has hit an error, and an error wins.
• The tray switches to its attention icon when a worktree’s most urgent state is needs input, and its menu lists each worktree that has an agent state, most urgent first.

A worktree you switched away from keeps its state for as long as its agent works, and each worktree shows only its own agents. Sidebar and Sessions describes the marks, and Tray, notifications and persistence covers the tray and the notifications a change raises.

Who may clear a state

An agent Sirio recognised from its title keeps its state until the title stops matching, and an agent it found as a process keeps its state until the process is gone. The exit of the shell behind them never overwrites that evidence. A pane whose own process exits takes its state from the exit instead: done for status 0, error for anything else. Only the layer that found the agent can clear its state.