Status Semantics

Read the state of your fleet

Grove shows workspace status, agent activity, and task phase so you can see what needs attention.

●

Active

Session up. Pane output within the activity threshold.

◐

Idle

Session up. Pane quiet past the threshold.

‖

Paused

Worktree removed, branch retained. R resumes.

○

Offline

Session vanished externally. o respawns from the worktree.

⊘

Orphaned

Worktree directory missing. No respawn. k only.

✗

Error

Init failed with fail_fast: false. Review the log. k only.

The three status axes

Workspace status tells you whether the worktree and session are ready.
Agent activity tells you whether the agent is working, waiting, blocked, idle, or in error.
Task phase tells you how far the agent has reached in the job.
A workspace can be ACTIVE while its agent is WAITING and its task phase is verifying.

The spectrum

The chips use the running TUI palette from src/grove/tui/theme.py.
ACTIVE and IDLE mean the session is up, with recent output deciding which one you see.
PAUSED keeps the branch and removes the worktree, while OFFLINE keeps the worktree and needs a respawn.
ORPHANED has no worktree to recover, and ERROR needs log review before you remove it.

What each status means

Status	Domain	Meaning
`RUNNING`	persisted	Grove last recorded that the workspace should run.
`ACTIVE`	computed	RUNNING, activity within `activity_threshold_seconds`.
`IDLE`	computed	RUNNING, no recent activity.
`OFFLINE`	computed	RUNNING, tmux gone. Respawn recovers it.
`ORPHANED`	computed	RUNNING, worktree gone. Not recoverable, kill only.
`PROVISIONING`	computed	Container mid build. Wait, do not respawn or kill.
`PAUSED`	persisted	Worktree removed, branch kept. Resume recreates it.
`ERROR`	persisted	Init failed with `fail_fast: false`. Review the log, then kill.

RUNNING, PAUSED, and ERROR record the last lifecycle action.
ACTIVE, IDLE, OFFLINE, ORPHANED, and PROVISIONING describe the workspace now.
Wait while a container is PROVISIONING instead of respawning or killing it.
Older saved stale values load as the intent that produced them, usually RUNNING.

The other axis: agent activity

Agent state	Meaning
`STARTING`	Session id known, transcript not yet on disk.
`WORKING`	In the tool loop or mid response.
`WAITING`	Turn ended. May need you.
`BLOCKED`	A permission or input prompt is open.
`IDLE`	Session alive but quiet.
`ERROR`	Parse error, process error, or a failed run.
`UNKNOWN`	Unreadable or suppressed, for example a generic agent with no adapter.

Agent activity is independent of workspace status.
An agent can finish output while the workspace remains ACTIVE and the agent becomes WAITING.
The Activity Dashboard shows workspace status and agent activity together.
Agents explains the activity states for each agent kind.

The third axis: task phase

Task phase reports job progress without requiring you to read the transcript.

Phase	Meaning
`scoping`	Reading the ticket and code, scoping the job.
`planning`	Understands the problem, choosing an approach.
`implementing`	Editing files.
`verifying`	Running tests, linters, the build, reviewing its own diff.
`delivering`	Committing, pushing, opening or updating the PR.
`done`	Handed off.

An agent can return from verifying to planning when verification changes the approach.
No reported phase is distinct from scoping and means the agent has not reported yet.
An agent writes its phase to the file named by GROVE_PHASE_FILE.

{"phase": "implementing", "note": "wiring the parser"}

Each agent gets a separate phase file, while a missing variable uses .grove/phase.json.
The file works for container workspaces, and a host workspace can also use CLI: grove phase or MCP tools.
The TUI, web dashboard, and ticket comment from issue-ops show the latest phase and note.
A blocked flag marks the current phase as stuck without adding another phase.

Recovery decision tree

Use the action named for the status you see.

flowchart TD
    Q{"Status?"}
    Q -->|ACTIVE / IDLE| A["Running.<br/>Attach, pause or kill."]
    Q -->|PAUSED| P["Resume recreates<br/>the worktree.<br/>Or kill to remove."]
    Q -->|OFFLINE| O["Respawn rebuilds tmux<br/>from the existing worktree."]
    Q -->|ORPHANED| R["Kill is the only path.<br/>The worktree dir is gone."]
    Q -->|ERROR| E["Review the init log,<br/>then kill.<br/>Init will not re-run."]

Attach, pause, or kill an ACTIVE or IDLE workspace.
Resume a PAUSED workspace to recreate its worktree.
Respawn an OFFLINE workspace from its existing worktree.
Kill an ORPHANED workspace or an ERROR workspace after reviewing its log.