Session statuses (the eleven states)

What it is

Eleven states, one colour each, and a plain meaning behind every one. They come from the app's single status list (src/shared/types/session-status.ts, the tuple at :21-41), and the label and dot colour each one shows come from one display table (src/renderer/src/lib/status-display.ts, :26-116):

• starting — shows as Starting, in grey. The CLI is being launched, and the session has not begun working yet.
• running — shows as Running, in green. The agent is working, right now.
• needs_you — shows as Needs You, in amber. The agent has stopped and is waiting on you: a question, a plan to approve, or a permission to grant. This is the only state that asks for you.
• ready — shows as Ready, in cyan. The session has started and is waiting for its first message.
• stalled — shows as Stalled?, in red. No output for a while, so the session may be wedged — a watch on the session flips it into this state.
• error — shows as Error, in red. The process died; the row says so and a message retries it.
• terminating — shows as Terminating, in grey. The process is shutting down.
• ended — shows as Interrupted, in red. The process is gone but the session is resumable: a message picks the conversation back up.
• paused — shows as Paused, in grey. You parked it deliberately; pressing P again resumes it.
• archived — shows as Archived, in grey. Filed away into the project's Archived section. This is the only true terminal state; nothing is deleted.
• waiting — shows as Rate Limited, in ember orange. The system parked the session on account capacity; it is alive and resumes by itself when a limit resets or an account frees up.

Where to find it

• The coloured dot on the session row in the sidebar, and the same dot in the session header.
• The inbox and the Needs You counts, which only ever contain attention states.
• The taskbar / dock badge on the app icon, which counts the same attention states.

How it behaves

• Every state sits in one of five buckets, and each state belongs to exactly one of them: live, needs-you, interrupted, paused, archived (src/shared/types/session-status.ts, :66-78). The bucket is what decides where a session appears rather than what it is called.
• One rule decides who is allowed to ask for you. A single predicate is the only route the inbox, the needs-you counts, the chime, the Overseer count and the mobile surfaces go through (src/shared/session-attention.ts), so a state that is not owed your attention cannot reach any of them by another path.
• Failures are quiet on purpose. An errored or stalled session collects in the sidebar's Interrupted section rather than nagging from Needs You — no inbox row, no badge, no chime. A session you stopped yourself is quiet the same way, and a session that has permanently given up on recovery is the exception: it surfaces in Needs You.
• Waiting is never amber. A capacity park is ember orange — the rate-limit colour — and it deliberately never enters the amber needs-you bucket, the inbox or the chime, because nothing is being asked of you.
• Some states resume by themselves after a restart. Only genuinely active sessions — running, starting or stalled — are brought back when the app relaunches; anything you parked or finished stays where you left it.
• Transitions are what notify you. The OS and in-app alerts fire on the change into a state that needs you, not on a timer.

Related

• Sessions — the lifecycle and its controls — the whole life of a session, and the pages that own each step.
• Session stuck in "needs you" — what the Needs You sub-labels mean (question, plan review, permission, and the rest).
• The Interrupted section — where the quiet failures collect.
• Paused session triage — what to do with a session you parked.
• Quiet chip — the small elapsed-time badge on a session row.