Task lifecycle

Every task moves through one state machine, defined in exactly one place in the source. Both the API (which returns 409 on an invalid action) and the execution engine consult it, so “what may happen next” has a single definition — and every task representation carries available_actions, so no client ever restates it.

This page is about tasks. A chat has its own, much smaller vocabulary — idle, running, awaiting_input, archived, handed_off, closed — kept deliberately separate so no task query or board legend has to decide whether it means chats too. It is documented with the chat routes. The one place the two meet is chatting with a stopped task, below.

• The diagram
• States
• Human actions
• Chatting with a stopped task
• Step outcomes
• Failure reasons
• Interruption is not failure

The diagram

                 create
                   │
                   ▼
              ┌────────┐   slot free    ┌─────────┐  input request  ┌────────────────┐
   ┌─────────►│ queued ├───────────────►│ running │◄───────────────►│ awaiting_input │
   │          └────────┘  (scheduler)   └──┬──┬──┬┘    answer       └────────────────┘
   │   approve ▲   ▲ retry/skip            │  │  │
   │           │   │                       │  │  │ all steps
   │      ┌────┴───┴─┐   manual step       │  │  │ succeeded
   │      │ awaiting │◄────────────────────┘  │  ▼
   │      │  _gate   │                        │ ┌──────┐
   │      └────┬─────┘      step failed,      │ │ done │
   │           │ reject     retries exhausted ▼ └──┬───┘
   │           └─────────►┌─────────┐              │
   │                      │ blocked │              │ archive
   │ resume               └──┬──────┘              ▼
┌──┴─────┐  pause            │ abort         ┌──────────┐
│ paused │◄───────┐          ▼               │ archived │
└────────┘ (from  │      ┌─────────┐ archive └──────────┘
           queued/│      │ aborted ├──────────────▲
           running┘      └─────────┘

Tasks are queued immediately on creation, unless the create asked for paused — vincent task add --paused, or the new-task form’s start row — which puts the task straight into paused, an edge the diagram leaves off. It waits there, with no worktree and no agent started, until you resume it. There is no separate draft state.

done and aborted have one more edge out of them that the diagram leaves off to stay readable: follow_up re-queues either of them to run more work in the task’s existing worktree, and returns it to the state it came from. See human actions.

States

Three of these are worth dwelling on.

queued covers two different waits. Usually it means “waiting for a free slot”. But a task can also be queued waiting on a clock rather than on the queue, and it says so through two fields: queued_reason and admit_not_before, the instant vincent will try again. Either way it holds no slot while it waits, keeps its place in the queue, and needs nothing from you — when the wait is over the step runs on its own. The board shows the resume time on the row (queued → 14:20) and the detail header names the reason. Cancelling, pausing or otherwise acting on the task drops the wait immediately — a human action always means go.

Two reasons produce that wait, and they are worth telling apart:

retry_backoff is a queued_reason only, and is never a step’s failure reason either — the step’s row keeps whatever actually failed. usage_limit is a queued_reason in the default mode and a block_reason in the modes that do not wait; it names the same condition either way.

awaiting_children holds no slot, and offers cancel and retry. A fan-out parent waiting on its lanes owns no process, so keeping a slot would starve the queue for hours — and it is what makes fan-out deadlock-free at any depth, since a parent releases its slot before its children need one. It is not a reuse of awaiting_gate because approve, reject and skip would all be meaningless while children are still running: the states differ in what a human can do about them, which is the only thing the lifecycle is for.

The parent resumes on its own once every lane has settled — finished or ended — or, under a fan-out’s schedule: eager, as soon as a further lane settles, so such a parent parks and resumes more than once. A lane that is blocked, at a gate, or paused holds the join open until you deal with it; the children rollup on GET /v1/tasks/{id} (and the TUI’s awaiting_children (×2 ●1) row, where × counts blocked lanes) is where you see that. For blocked lanes, dealing with them is one retry on the parent: it re-admits every blocked lane beneath it, at any depth, without touching the parent’s own row, and the join closes itself when they finish. Fix the cause first — the retry re-runs each lane’s step exactly as it was.

awaiting_input keeps its concurrency slot. The agent process is alive mid-step, idle on its stdin; killing or re-queueing it would lose the very session the answer belongs to. So a forgotten question does occupy a slot, until input_timeout (default 24h) expires.

blocked is a resting state, not a failure. Nothing is silently abandoned: a step that exhausts its retries stops and waits for a person, and the task keeps its worktree, its branch and its transcripts while it does.

Repair when the worktree is what is wrong. retry re-runs an unchanged step, edit + retry can rewrite only that step’s own prompt or command, and skip advances past an unsatisfied check — none of them changes a file. When the fix is in the worktree, repair runs one throwaway agent there: you write what it should do, the daemon hands it the task’s context and the blocked step’s failure (its rendered prompt or command, the reason and exit codes, the tail of the failed attempt’s transcript and where to read the rest), and it works on the task’s own branch in the task’s own worktree.

It decides nothing. However the repair agent exits, the task comes back to blocked at the same step with the same reason, so you read the diff and then choose — retry, repair again, skip or cancel. It is recorded as a step run of its own under the reserved step id __repair at the blocked step’s index, which is why the timeline shows it as its own entry and why it does not eat the blocked step’s retries: after any number of repairs, a retry gets exactly the attempts it would have had with none.

Repair is offered from blocked whatever the reason. A task blocked before its worktree existed re-blocks on the same reason without starting an agent, and one blocked because its agent CLI is missing has its repair fail the same way — both honest outcomes rather than a hidden filter.

A finished task is not finished with until you archive it. done and aborted both keep the worktree, the branch and the commits, and follow_up is how you do one more piece of work in them without leaving vincent. You supply one of three things — an agent prompt, a shell command, or the name of a workflow from the registry — and the daemon runs it on the task’s own branch, in the task’s own worktree, recorded in the task’s own ledger with a step run, a transcript, events and cost accounting.

It decides nothing about the verdict: a done task comes back done and an aborted one comes back aborted, whatever the run did. That is deliberate — a command that exits 0 should not be able to reverse an abort you made on purpose. Follow-ups are repeatable, and each is a round: round 1’s rows sit one past the workflow’s last step index, round 2’s one past that, so the timeline shows ↳ follow-up 1, ↳ follow-up 2 rather than pretending the workflow grew.

A follow-up step that fails blocks the task at the follow-up’s own index. From there retry re-runs the follow-up where it stopped, repair runs an ad-hoc agent against that failure, skip abandons the follow-up and puts the task back where it came from, and cancel aborts. Edit-and-retry is refused there: an override rewrites a step in the task’s snapshot, and a follow-up is deliberately not in it.

One edge worth knowing about: because a follow-up’s process is live while it runs, cancel during one aborts the task — so done → aborted is reachable, which it was not before follow-ups existed.

Human actions

In the TUI these are the action bar keys (a, x, r, R, E, s, p, c, A, F, T); over the API they are POST /v1/tasks/{id}/{action}; from the CLI, vincent task <action> <id> — one subcommand each, spelled in kebab-case (follow_up is vincent task follow-up). set priority is the exception: it is a PATCH, and has no subcommand.

An action the current state does not allow returns 409 with details.state set to the state actually found — so a client branches on a value rather than parsing prose.

An action the state does allow never fails on a race. Each one is a compare-and-swap on the state the request read, and the task can move under it — the scheduler admitting a queued task is the usual way. When it does, the action is re-applied once from the state actually found, provided the table above allows it from there: cancel on a task the scheduler admits at that instant aborts the now-running task rather than reporting a conflict, and pause becomes the deferred kind that holds at the next step boundary.

Chatting with a stopped task

repair is one prompt and one run. When the fix needs a conversation — look at the failure, try something, check, adjust — open a chat on the task instead. It is offered from blocked, awaiting_gate, done and aborted, and it is an ordinary chat with one difference: it works in the task’s own worktree and on its branch, so the agent starts from the files exactly as the task left them and its edits are the task’s edits.

Its first message is preceded by what the task already knows, put together by the daemon: the title, description and fields, and then what the stop is about — for blocked, the same failure context a repair gets, including the tail of the failed attempt’s transcript and where to read the rest; for awaiting_gate, the gate’s instructions; for done and aborted, the last step’s summary and the abort reason. What you type follows it as written.

While the chat is open, the task is locked. Nothing moves it, and no action but cancel is accepted — retry, skip, approve, follow_up, archive and the rest are all refused with 409 task_locked_by_chat, naming the chat. A retry can never race the conversation, even between two of its turns. available_actions shows only cancel, where cancel is legal, or nothing; the task also carries open_chat_id, which is how a client finds the conversation. The task’s state, step, block reason and retry budget are exactly as they were when you close the chat. PATCH /v1/tasks/{id} and the pull-request actions are not actions on this page, and still work.

When you are done, close the chat. That ends the conversation and lifts the lock; it never touches the worktree or the branch, so you read the diff and then choose what the task does next — retry, skip, approve, archive. There is no “close and retry” in one step, on purpose. cancel on the locked task is the other way out: it stops the chat’s live turn, closes the chat and aborts the task, together.

A task can have at most one open chat. After you close it, the next stop can have a new one, and the closed ones stay listed on the task as its history.

A few edges:

• No worktree, no chat. A task blocked on branch_exists or base_branch_missing, or aborted before it ever started, has no worktree, and opening a chat on it is refused with 409 task_has_no_worktree — vincent does not create a worktree for a conversation. A git operation in progress is not a refusal: a half-finished rebase is a fine thing to talk about.
• A fan-out lane with an open chat is skipped by the parent’s cascading retry: it stays blocked, is not counted, and is retried by hand after its chat closes. The parent’s cancel does to such a lane what cancel always does to a locked task.
• Cost stays on the chat. Its turns are the chat’s, not step runs, so they do not count toward max_task_cost_usd.
• A daemon restart during one of its turns marks that turn interrupted and does not re-run it, like any chat’s. The chat stays open, so the task stays locked.
• A task that runs in a container has its chat’s turns run inside that container too, with the container’s own home — so the agent configuration mount_agent_config mounts is the one it reads. Its skill list is the container’s as well, obtained by the image’s CLI inside it; if the container is gone, that list answers unknown rather than falling back to your host.

Open one with vincent task chat or POST /v1/tasks/{id}/chat, and close it with vincent chat close or POST /v1/chats/{id}/close — see the API for the details.

Step outcomes

Each attempt of each step is a step run row, and every attempt is kept — that is what the TUI’s timeline lists.

A step succeeds only when all of its criteria hold:

• agent — the process exits 0, and the event stream produced a terminal result rather than an error, and any declared check exits 0.
• command — the command exits 0, and any declared check exits 0.
• manual — a person approves.

On a retryable failure the step re-runs, up to max_retries (default 1, so two attempts). For agent steps the previous failure is appended to the retried prompt as a structured block, so the agent is told exactly what went wrong rather than asked to guess.

The re-run is immediate unless the step sets retry_backoff, in which case the task waits that long in queued — holding no slot — and the step re-runs when the wait is over. The budget is unchanged either way: the backoff decides when an attempt happens, never whether.

What a step says about itself

Beside the outcome, a step run carries two pieces of text that are not vincent’s words:

• status_message — a line the running step wrote about itself through vincent status. While the step runs it is the live answer to “what is this doing”; the last value it set stays on the finished attempt. Empty unless the workflow asked for it, and empty always for the step types that run no process (manual, parallel, fan_out, condition, loop, break).
• result_summary — the agent’s final result text, or the last 200 lines of a command step’s output: both its stdout and its stderr, because a step that failed with a stderr-only diagnostic must not summarize as blank. Capped at 4096 bytes, keeping the end — where a failure’s error is — cut at a line boundary where possible and marked … N earlier bytes when anything was dropped. Recorded on every attempt, and what the board, the detail view and the repair prompt show. A later step’s {{ .Steps.<id>.Result }} reads it for an agent step, and for a command step reads a narrower record of the same attempt — the 200-line tail of its stdout alone, so that a for_each: over it cannot pick up a progress meter or a Switched to branch … as an item. An attempt that recorded no stdout tail, which is any that ran before vincent kept one, falls back to result_summary.

Neither is a failure reason, and no surface renders either as one. The reasons below are a closed set vincent authors; these two are whatever the step produced, possibly long before it stopped.

Failure reasons

The reason is recorded on the step run and on the task when it blocks. The vocabulary is shared across the engine and the worktree layer: a reason means the same thing wherever it originated.

One reason is a step run’s skip_reason rather than a failure:

The worktree layer adds its own, raised while vincent prepares the task’s branch and worktree:

A branch_exists block is recoverable without losing the task: POST /v1/tasks/{id}/retry accepts a branch_override that renames the branch and re-admits it. See Troubleshooting.

Three more belong to a task created from a pull request (--github-pull), whose branch is the pull request’s head rather than one vincent cut:

branch_override is refused on such a task: renaming its branch would detach it from the pull request it was created for.

Interruption is not failure

Vincent is crash-first: every transition is persisted before it is acted on. When the daemon starts, recovery:

1. finalizes any step run still marked running as interrupted, keeping whatever status message that step had set — “what was it doing when the machine went down” is exactly what you want off that row;
2. kills verified orphan processes — the recorded PID must still exist and still hold the very process the run spawned, checked against a platform-native identity recorded at spawn (start ticks plus boot id on Linux, the kernel fork stamp on macOS, the creation time on Windows, each paired with the PID, because the operating system’s stamp is a clock tick wide and processes started inside one share it). That is the guard against PID reuse killing an innocent process: anything vincent cannot prove is the same process is left running. A run recorded before vincent kept that identity — by an earlier version, or on a machine where the read is unavailable — falls back to the older check, a start time within five seconds of the recorded one;
3. re-queues the owning task and re-runs the interrupted step as a fresh attempt that does not consume a retry.

Tasks found in awaiting_input are treated identically: the pending request is discarded with the process, and the fresh session may re-ask.

This is safe by construction because every agent step is a fresh session operating on a worktree whose committed state survives. Workflow authors help by having agents commit incrementally.

A graceful stop (vincent daemon stop, SIGTERM, a service stop) takes the same path: a daemon.shutting_down event, admission stops, running processes get 15 seconds before being killed, and their runs are marked interrupted. The API — SSE streams included — stays up through the grace period, so clients watch the wind-down live.

See also

• Concepts — how a step runs.
• HTTP API — the action endpoints and the event stream.
• Using the TUI.