States and attention

Every pane has one state. The daemon keeps it, so it's correct even when no window is open.

State	Means	Shows as
idle	At a prompt, or nothing has reported another state	nothing
running	A command or agent is working	a mark, and a percentage if one is reported
waiting	Blocked on you	a mark, counted as attention
done	Finished since you last looked	a mark, counted as attention
failed	Finished with an error since you last looked	a mark, counted as attention
exited	The program ended and the pane was kept (isc run --keep). It shows done or failed until you've seen it, then this.	a mark

Each state has its own mark, drawn in the state's colour:

• running: a ring of eight dots that spins, with the leading dot brightest. It's the only mark that moves, so you can tell at a glance what's still working and what has stopped. It moves one step every tenth of a second, and every such mark in the window spins together.
• waiting: a dot with a ring around it.
• done: a tick. failed: a cross. exited: a ring with a bar across it.

While no pane is running, nothing spins and the window redraws nothing for it.

done and failed mean unseen. When you look at the pane, it's marked seen and returns to idle. Looking at a pane means it has the keyboard, in a window that's in front.

Where a state shows

• On the pane's header and the line under it, its tab, its sidebar row and its dock chip. It also shows as a count in the top bar, in the colour of the most urgent state.
• In the sidebar, a project or a tab shows a state only while it's folded. Unfolded, the rows beneath it show their own states and its row shows none. Folded, it shows the most urgent state of what it holds, and a project shows how many of its panes need you. If the settings list no rows beneath it, it always shows a state.
• A pane's header shows its state as a word, along with what the pane says about it. On a tab, in the sidebar and on a dock chip, the state is a mark only. Hover over the mark to see the same words, for example "waiting: Needs permission: Bash".
• A tab, a project or the top bar shows the most urgent state of what it holds: waiting, then failed, then done, then running. The mark of a tab or a project gives the words of the pane it stands for.
• A dock chip is the small box a minimized pane becomes in the dock, with its icon, name and state. When the dock has more chips than it has room for, the chips of panes that are idle share one chip that reads, for example, "3 idle". Click it to open the palette, which lists them. A chip whose pane has a state always keeps its own chip.
• Nothing is ever reordered because of a state. Tabs, rows and chips stay where they are.

Going to the pane that needs you

• Press Ctrl+Shift+A, or click the count in the top bar, to go to the pane that needs you most. If the pane was minimized, it's restored. Do it again to step through the others.
• The palette opens with every pane that needs you at the top, most urgent first.
• The overview shows every tab of every project with each pane's state. For a pane that wants you, it also shows what the pane is asking.

Where a state comes from

Strongest first:

1. A report from an agent's own hooks or a script: isc status running|waiting|done|failed|idle [-m "what about"]. A running or waiting reported this way overrides everything below until the next report or until the command ends. A report carries the time it was made. A report that was made earlier and arrives later is ignored.
2. What the program writes to its terminal.
   • Progress (OSC 9;4): set or indeterminate gives running with the percentage; removed gives done if the pane was running; error gives failed; paused gives waiting.
   • A notification (OSC 9, 777 or 99) gives waiting with its text, until you look at the pane. It doesn't change a done or failed that was reported: an agent that says it finished, and then announces it, hasn't asked you for anything.
   • The bell, while nobody is looking, gives waiting until you look at the pane. The bell marks a pane and never sends a desktop notification, because shells ring it on every failed completion.
3. The command in the foreground ending: done if the pane was running, or if the command ran for 30 seconds or more. This doesn't need shell integration.
4. The program itself ending in a kept pane: failed if it exited with a non-zero status.

States aren't only for agents. Any command that runs for 30 seconds gives its pane a state. So does any program that reports progress, sends a notification or rings the bell, and any script that calls isc status.

isc status explain [--pane N] tells you why a pane is in its current state.

Commands that fail, and short commands

• A long command is one that ran for 30 seconds. There's no setting for this.
• Without shell integration, a failed command shows as done, not failed. The end of a command is read from the terminal's foreground process, which gives no exit code.
• With a shell that marks its commands, a failed command is failed, with a note such as "failed with 2 after 1m 35s".
  • fish 4 and later does this with no setup.
  • For bash, put eval "$(isc shell-integration bash)" in ~/.bashrc. For zsh, put eval "$(isc shell-integration zsh)" in ~/.zshrc. For a fish older than 4, put isc shell-integration fish | source in ~/.config/fish/config.fish. Each one does nothing outside a pane.
  • bash must be 4.4 or later. An older one, such as the /bin/bash on a Mac (3.2), is left alone, and a command that fails in it shows as done.
  • Other terminals' integrations that write the same marks (OSC 133 C and D) work too.
• An exit status of 130, which is what you get when you press Ctrl+C, counts as finished, not failed.
• A short command isn't marked at all, even if it fails. If it ran for under 30 seconds in a pane that wasn't running, nothing is shown.