Task lifecycle

How a task moves through statuses, with the fix loop and the approval gates.

In simple words

Every task moves through a fixed sequence of statuses, and Vibestrate will not let it skip a step or jump backward.

Open a run and its status hero carries the flow’s steps as a rail with the current one marked Now; the Live timeline panel ticks them over as they finish. The Status column on All runs is the same value for every run at once.

Tip

If a status looks stuck, the sequence is the first thing to check. A task waiting at an approval gate and a task whose step crashed look similar from a distance and need completely different responses.

Why a fixed sequence

You can tell where it is One status, read from a saved value, never inferred.

No impossible history A task cannot reach a status along a path the state machine does not allow.

Stuck looks different from working Waiting on you and crashed are distinct states, not one ambiguous “not done”.

Replayable afterwards The sequence is the record, so a finished task can be re-read rather than remembered.

Did you know

The moves are enforced, not merely recorded. A task cannot land in a status nobody defined, so the history you read is the history that happened.

The happy path

When nothing goes wrong, a task walks its flow’s statuses once and finishes ready to merge.

created → planning → planned
  → executing → validating
  → reviewing → merge_ready

It leaves a diff on the worktree branch. The deep flow adds architecting → architected before execution and a verifying gate before merge_ready.

When the reviewer asks for changes

The review step can send work back. When it does, the default flow re-enters the implement step itself with the findings: the task returns to executing, runs validation again, and comes back to reviewing instead of moving on. deep hands the findings to its dedicated fixer instead, so the task passes through fixing. The run’s status hero grows a review loop figure reading the pass you are on against the budget.

Note

The review loop has a budget. The default flow allows 3 passes - the first implementation plus 2 redo passes. A run still asking for changes when the budget runs out ends blocked. workflow.maxReviewLoops can lower any flow’s budget; a Crew’s own maxReviewLoops overrides both.

When a stage needs your approval

A stage can be set to hold for you once its work is done. The task steps sideways into waiting_for_approval and then back into the status it paused in, so it never skips ahead.

The run page shows an approval banner with Approve, Reject and, for an agent-raised gate, Request changes. Mission control collects the same gates in Waiting on you; the shell’s Approvals tab decides them with a, r and c.

Note

The gate holds until you decide. List a stage under policies.requireApprovalAtStages and the run pauses there once, on the first pass through it, with the reason “project policy requires approval before continuing past the stage stage.” An agent can also ask for a gate of its own by emitting HUMAN_APPROVAL: REQUIRED.

Unattended runs cannot hold. With --unattended nobody is there to decide, so the request expires after policies.unattendedApprovalTimeoutMs (default 0, at once) and the run ends blocked, with the cause on the event and in the decision feed. The request stays in the Approvals inbox: answer it there and resume, or re-run attended.

When you pause it yourself

Pause on the run page sets a flag the orchestrator picks up at the next stage boundary, so pausing has the same sideways shape: the task holds at paused, then returns to the status it was in. pausedAtStatus records where, and Resume clears the flag. The shell’s : palette carries both; a script uses vibe pause <runId> and vibe resume <runId>.

Where a task comes to rest

The four terminal statuses in more detail:

merge_ready - The review approved and validation passed; in deep, the verifier passed too. The diff is ready to ship.
blocked - The reviewer said the run should not continue, or deep’s verifier refused. The assurance panel names the lane that refused and offers View review for the findings and Re-run with fixes, which forks a run reusing the upstream steps this one already completed. The shell run view lists the first three finding headlines under the review line.
failed - Unrecoverable error during a stage. The run page names the error it stopped on; the Events tab under Inspect has the timeline around it.
aborted - User explicitly aborted. Worktree is preserved.

What a run leaves on disk

Each flow step writes its prompt and the provider’s reply under the run folder, named after the step rather than the status. The Artifacts tab under Inspect reads all of this without leaving the dashboard. For the default flow the step ids are:

planimplementvalidationreview

.vibestrate/runs/<runId>/
  state.json        current status, transitions
  events.ndjson     every event, append-only
  actions.ndjson    brokered actions + verdicts
  artifacts/flows/
    <step-id>/prompt.md    what it was sent
    <step-id>/output.md    what it replied
    <step-id>/validation-results.json
    findings.json          reviewer findings
    finding-responses.json how a fixer seat answered (deep)

validation-results.json holds the commands that ran and their exit codes. The code changes themselves are commits in the run’s worktree, not files here. events.ndjson is the record to trust: one JSON line per event, append-only.

Run state - what each status means in detail.
Workflow - the stage definitions.
Run-state reference - the full enum and transition rules.