Statuses and status machines

A status answers one question: where is this thing right now. Disco Parrot uses statuses in two distinct ways, and the difference is the key to this page. Your work records, initiatives, plans, bugs, and test cases, move through a status machine: a fixed set of states with defined transitions between them, which the platform enforces and which you can customize. Your runs and your infrastructure, a flow run, a step, a background task, a sandbox, an environment, report a runtime status: a state the system sets as work happens, so you can read what it is doing without driving it.

This page is the catalog of both. The work-model machines come first, with each one's states and the moves allowed between them. The runtime statuses follow, with what each value means and when you see it. The fields that carry these statuses are named on the work items reference; the concept behind the machines is on the workflows page, and customizing them is covered under customizing workflows.

How a status machine works

A work-model status machine has three parts: an ordered set of statuses, one of them the starting status, and a set of allowed transitions that say which status can move to which. When you move a record, the platform checks the move against that machine and refuses any transition the machine does not allow, so a plan cannot jump straight from draft to complete if no transition connects them. Moving a record to the status it already holds is always allowed and does nothing.

Five record types have a status machine: initiatives, plans, bugs, test cases, and flows. You can tailor the statuses and the transitions for initiatives, plans, and bugs to match how your team works. Test cases use a fixed machine, since their passing and failing states come from running the test rather than from editing it. A flow's lifecycle is driven by the run engine rather than by manual moves, so its states are covered with the runtime statuses below. Goals have no status machine at all: a goal's status is a health label you set, and its progress is a number derived from its key results.

Initiative statuses

The initiative machine starts at planning and ends at done, with blocked and cancelled reachable from the active states. Both end states can be reopened.

Starting status: planning. End states: done and cancelled, each reopenable.

Plan statuses

The plan machine is the simplest of the three you can customize: draft to in-progress to complete, with blocked alongside and cancelled as the off-ramp.

Starting status: draft. End states: complete and cancelled, each reopenable. A plan's pull-request status is a separate field from this lifecycle: a merged PR sets the plan's PR status without moving its workflow status, so completing the plan stays a deliberate step.

Bug statuses

The bug machine is the longest, walking a defect from triage through review to a verified fix.

Starting status: triage. Moving a bug to canceled requires a resolution, so a canceled bug always records why it was settled. When a pull request that fixes a bug opens and merges, the platform advances the bug's status from the webhook, which is the one path that moves a status without a manual transition.

On a sprint board, these nine statuses map onto three columns, so a long machine still reads at a glance.

Test case statuses

A test case has two kinds of state. Its authoring states, draft, active, and obsolete, you set by editing the test. Its outcome states, passing and failing, are recorded by exercising the test against a plan, not by editing the record.

Starting status: draft. The passing and failing states are recorded only by running the test, which is why this machine is fixed rather than customizable.

Runtime statuses

Runtime statuses are set by the platform as work runs. You read them rather than drive them, and they answer what a run, a task, a sandbox, or an environment is doing right now.

Five things report a runtime status: a flow run and the steps inside it, a background task, a sandbox, and an environment. The first two are the run itself, the last three are the machinery a run uses, and each table below says what every value means and when you see it.

Flow run statuses

A flow run reports one of nine statuses. The first four are the happy path; the rest are the ways a run pauses, stops, or needs attention.

The completed, failed, and interrupted runs can be started again, which sends them back to pending. A cancelled run is the one true end. See running a flow and managing checkpoints for how these play out in a run.

Flow step statuses

Each step inside a run reports its own status.

Background task statuses

A background task is agent work you are not watching. It carries a status that tells you where it stands.

A backgrounded chat settles into review, which is your cue to open it, look at what changed, and continue in chat if you want to take it further. A background flow can run further still, all the way to merged, because it has a pull request to land its work in.

Sandbox statuses

A sandbox reports where its container is in its short life.

A sandbox pauses on its own once it has been idle past its timeout, and resumes when work comes back to it. If a profile, image, host, or identity behind a sandbox changes, the platform destroys the old container and creates a fresh one so a run never inherits stale settings.

Environment health statuses

An environment reports a health status derived from the open blockers against it.

A blocker is an event with a severity, blocking or warning, and a reason that says what it is about. A person resolves or dismisses it to clear it. The platform raises a blocker for one of these reasons:

When an environment is blocked, the flow runs that depend on it park at their blocked status until a person clears the event. The connection between the two is what makes propose-only environments enforceable rather than advisory; the governance view is on human oversight and approvals.

Why statuses work this way

The split between a status machine and a runtime status is the whole idea, and it is worth saying why it holds. A work record's status is a promise about process. When your team agrees that a plan goes draft, to in-progress, to complete, that agreement is only worth anything if the platform keeps it, which is why the transitions are enforced rather than suggested and why a move the machine does not allow is refused. You get to write the rule, by customizing the machine, and then the rule holds for everyone, including the agent, because the agent moves a record through the same transitions a person does.

A runtime status is the opposite kind of thing. Nobody agrees that a sandbox should pause when it goes idle; it pauses because it went idle, and the status is the platform telling you so. Trying to make those states editable would be a category error, because they are observations, not decisions. Keeping the two kinds of status apart, one you govern and one you read, is what lets a status mean something precise in both directions: a plan in review is there because someone moved it, and a run that is blocked is there because something is genuinely in its way.

For an administrator, the transition tables here are the starting point for a custom workflow. When you add a status or a transition to the initiative, plan, or bug machine, these defaults are what you are changing, and the customizing workflows page is how.

For a power user, the status values are exactly what a board column maps to and what a filtered view matches. A view that gathers every bug in triage or in-review keys off the values listed here.

For an engineer, the runtime statuses are the vocabulary of a run. A blocked run, an interrupted-by-deploy run, a sandbox that recreated itself, each has a precise meaning here, so a blocked status on a card tells you to clear a precondition and an interrupted-by-deploy status tells you to retry, with no guesswork about which.

For a prospect, the enforcement is the point worth weighing. A platform that lets agents move work is only trustworthy if the work follows the same rules people do, and a status machine the platform actually enforces is how that rule gets kept.