Session status
Every session carries one of a small set of states, and they mean the same thing whichever vendor's CLI produced them. This is the layer the rest of the fleet view is built on: you cannot rank what needs you if you cannot tell what each session is doing.
The vocabulary
| State | What it means | What to do |
|---|---|---|
| working | The agent is mid-turn and producing output. | Nothing. Stage your next message in the Queue tab if you have one. |
| ready | The turn finished and the agent is waiting for input. | Type, or send a queued message. |
| awaiting | The agent is blocked on you specifically: an approval, a question, a choice. | This is the one to watch. It is not a stall. |
| blocked | Something outside the conversation is in the way. | Read the pane. The sub-reason names what. |
| idle | Nothing is happening in the terminal. | Not the same as finished. Background work can be running. |
idle is never reported as finished on its own. An agent waiting on you and an agent with background work still running render identically in a quiet terminal and mean the opposite, so nothing in swe-mux collapses them.
Where the reading comes from
Four independent sources, because no single one of them is reliable alone:
- Provider hooksThe structured events a CLI emits about its own turn. The strongest signal where a harness publishes one.
- The transcriptWhat the conversation file on disk says happened, read as the branching structure it actually is rather than as a flat log.
- The terminal itselfWhat is on the screen. The weakest signal, and deliberately never the one an approval decision is made from.
- The CLI's own state filesWhatever the harness writes about itself outside the transcript.
Every transition is kept in a durable ledger, which is what makes a status that went wrong investigable afterwards rather than a matter of opinion. A watchdog exists for the case a session gets stuck reporting one state.
Approvals
When a harness asks permission, the decision is made from its structured permission request, never from what is on the terminal screen. There is a floor in the code that is checked before any configured mode, so no setting can reach past it.
swe-mux never decides to deny. That is deliberately not a decision it makes; a denial stays yours. Approval modes are per-conversation and live in Settings, Prompt queue, Approvals.
Why a status is not a done signal
The prompt queue does not wait for a binary done. It waits for a readiness gate and a stability window, because a state that just changed and a state that has settled are different facts and only the second one is safe to act on. The prompt queue covers what that means when you turn automatic delivery on.
When status looks wrong
mux doctor carries a fleet status-health check, and mux doctor --export includes the status timeline's sink statistics. A status that is wrong for one session is a bug worth reporting with that export attached; a status that is wrong for every session usually means a harness updated underneath swe-mux and moved something it reads.