Sculptured docs

States and evidence

Every state an agent, a question and a result can be in, what each one means, and what you can do next.

Sculptured shows three separate things about an agent: whether its process is running (its lifecycle), what it is doing right now (its activity), and how much you can trust its result (its evidence). Each state has a shape and a word as well as a colour, so it reads the same without colour.

Agent lifecycle

An agent's lifecycle says whether a process exists for it. Your agent runner reports most changes as it sees them. A few are inferred by Sculptured, for example when the link to a computer is lost; those are labelled heuristic in the agent's history.

stateDiagram-v2
  [*] --> planned: "team started"
  planned --> launching: "runner got the launch"
  planned --> attention: "no Claude Code / Codex on the computer"
  launching --> running: "session ready"
  launching --> attention: "exited before ready, or 60 s passed"
  running --> stopping: "Stop sent"
  stopping --> stopped: "process exited"
  running --> attention: "exited unexpectedly"
  running --> stale: "computer's link lost"
  stale --> running: "computer back, process still alive"
  stale --> attention: "computer back, process gone"
  attention --> launching: "Restart, or Resume / Start fresh"
  attention --> stopped: "Leave stopped"
  stopped --> launching: "Restart, or start the team again"
StateShown asWhat it meansWhat you can do
Planned○ plannedOn the design, not launched yet in this run.Wait for its turn, or start the team.
Launching◌ launchingThe runner is starting Claude Code or Codex. It must be ready within 60 seconds.Wait.
Running● runningA process is running. Its activity says whether it is working.Send guidance, interrupt, soft stop or hard stop.
Stopping◑ stoppingA stop was sent and Sculptured is waiting for the process to exit. If the computer is offline, the stop is carried out as soon as it reconnects.Wait.
Stopped■ stoppedNo process. Its history is kept.Restart the agent, or start the team again.
Stale◇ staleThe computer's link was lost while the agent was running. What you see is the last known state, not the current one.Wait for the computer to reconnect, or check the computer.
Needs attention▲ needs attentionThe agent stopped when it should not have, could not start, or was lost in a restart. The agent's page says why.Read the reason, then Restart, Resume, Start fresh or Leave stopped.

Activity

Activity is only current while the agent is running. While it is stale, the activity is the last known one. Otherwise it is not shown.

ActivityShown asMeaning
Working⚙ workingA turn is in progress.
Waiting for input? waiting for inputThe agent asked a question and is waiting for an answer.
Idle· idleThe session is open, but no turn runs. An idle agent is not doing anything.
Unknown∅ unknownSculptured cannot tell.

What the board shows

The board and the Run view combine lifecycle and activity into one word per agent. Blocked agents are sorted first.

Board stateShown whenWhat to do
◉ needs youThe agent waits for your answer, or needs attention.Open it and answer, or read its reason.
▲ stuckThe agent is idle and its handoffs cannot go on by themselves. The pane says why.Use Hand over again or Resend handoff, or send guidance.
⧗ waiting for a slotIts next message waits until fewer of the run's agents work at once (the run budget's Most agents working at once). The agent's page says "waiting for a slot to run". It is not stuck.Nothing: it starts when a slot frees. Raise the limit in Run budgets to run more at once.
⣟ workingA turn is running.Watch, or send guidance.
✓ doneA turn ended since you last looked. It does not mean the work is right.Read the result and its evidence.
○ idleRunning, with nothing to do.Nothing, or send new work.
∅ unknownThe computer is unreachable, or no state is known.Check the computer.

Launching, stopping, stopped and planned agents show their lifecycle word.

Questions

A question comes from an agent's request_input tool, from the CLI's own question prompt, or (for a restricted agent) from a permission prompt. See Questions and approvals.

StateMeaning
OpenWaiting for your answer. It shows in Needs you.
AnsweredYou answered before the timeout.
ExpiredThe timeout (10 minutes by default) passed first. The agent decides for itself and says what it decided. A late answer is sent as an overriding instruction.
WithdrawnThe question can no longer reach the agent, for example because the agent stopped. The reason is shown.

An open question stays open while a computer is briefly offline. You can answer it, and the answer reaches the agent when the computer reconnects. See When a computer drops off.

Evidence: reported, observed, verified

Every claim on the board carries where it came from. Sculptured never upgrades an agent's words to a fact.

LabelShown asWhere it comes from
Verified◆ verifiedAn independent check, such as a test command Sculptured ran itself, and its exit status.
Observed◆ observedSomething Sculptured saw: the runner's protocol, a file on disk, a captured tool call and result, or your own action.
Reported◇ reportedThe agent's own words, such as its report or "done".
Heuristic≈ heuristicSculptured's own reading, for example how it classified a tool call. It never blocks an agent.
Unknown∅ unknownNo source is recorded. It stays unknown; nothing is invented.

Outcome of a piece of work

A finished assignment shows one of these outcomes:

OutcomeMeaning
Reported completeThe agent said it finished. Nothing checked it.
Captured tool resultA tool call's result was captured as evidence.
VerifiedA check ran and passed.
Settled, unverifiedThe work ended, but no check ran.
Check failedA check ran and failed.

Work items in a workflow also show progress words: pending, in progress, waiting for you, blocked, reported complete, failed, canceled and handed off.

Next steps