Skip to content

Latest commit

 

History

History
53 lines (27 loc) · 8.23 KB

task-lifecycle.md

File metadata and controls

53 lines (27 loc) · 8.23 KB

Task lifecycle

A task moves through a small set of states between being created and being closed. None of these states is a flag someone sets on purpose to mean "this task is now running" — every one of them is read off facts that already exist for other reasons: a bead's status and metadata, a git worktree, a process the operating system still schedules. That is what makes the lifecycle recoverable: nothing about it lives only in the memory of whichever session happened to start the task.

Task states: waiting or ready, claimed, running, merged; crashed, awaiting review, stopped and failed route back to running, and stopped or failed can also restart at ready

Open: waiting or ready

A task starts open. Whether it is waiting or ready is not stored anywhere as such — it falls out of its dependencies. A task with an unclosed blocks dependency is waiting; once every blocker closes, the same task is ready, with nothing written to the task itself. Being ready is also not enough to be dispatched: a task with children isn't (its children are dispatched instead), and a leaf task needs a verify command, unless it is an epic's integration task, which is exempted because its job is to merge rather than to satisfy acceptance criteria of its own.

Claimed

Dispatch starts a ready task by claiming it: the bead becomes in_progress, carrying a session id, the base and branch it will work on, and the host it runs on (see task fields for the exact metadata). Claiming and starting the worker process are two different actions, so claimed is briefly a state on its own — a task can be claimed and then fail to become a worktree at all, for instance because the base branch is missing or because a project hook has never been approved on this machine. When that happens, dispatch undoes the claim and the task goes straight back to fully open, as though nothing had happened, and reports why it could not start.

Running

There is no stored value that means "running." A task's worker is running when three facts hold at once: the task is claimed (in progress, with a session id), a process still answers to that session, and no attempt outcome has been recorded yet. Every one of those facts comes from somewhere other than the supervisor: the bead, the process table, and the absence of a result in the worker's own log. Reading the state this way, instead of writing "running" into a bead, is what lets any session — including one that didn't start the worker — tell a live task apart from a dead one just by looking.

Crashed

A crashed task is claimed with no recorded outcome and no live process: the same claimed state as running, but the process fact has flipped. It means a worker died without going through its own finishing sequence — killed, out of memory, the machine rebooted. Dispatch decides what to do with a crashed task from the evidence in its log: if the log shows the worker actually finished and only the bookkeeping after it never ran, dispatch records that outcome as if the worker had ended normally. Otherwise it resumes the worker's own session in the same worktree, unless the worktree or the session transcript is gone, or this is the fourth crash in a row with no result in between — those three cases end the task as failed instead, because retrying a task that can't produce a result, or that has nothing left to resume into, only spends money without changing the outcome.

Merged

A merged task closed successfully: its change is on the base branch (or the epic branch, in epic-merge and epic-pr modes) and the bead is closed. This is the only outcome that removes the task's worktree, because there is nothing left in it that isn't already on a branch somewhere.

Awaiting review

A task in this state is claimed, blocked by an open human review gate, and has no live worker — the finish step stopped it there on purpose after seeing that the task's review level is human. Its worktree stays, because the diff a person is about to read lives in it. It moves on when a person resolves the gate, at which point dispatch resumes the same worker session with a prompt to read what the review asked for and continue.

Pull-request opened

Only an integration task in epic-pr mode reaches this state: its finish step pushed the epic branch and opened a pull request instead of merging directly, and the task is blocked by a gate that watches the pull request rather than a person's own decision. It resolves to merged once the pull request merges, and to stopped if the pull request is closed without merging — a person's call, made on GitHub rather than through a review gate.

Stopped

A task stopped by a person keeps its worktree and whatever it had committed. Nothing further happens to it until a person acts: the finish step refuses to merge a stopped task even if it is otherwise ready, so a fix made by hand in its worktree needs a person to explicitly resume, finish, or restart the task (see handling a stopped or failed task).

Failed

A task fails either because a worker's session itself ended in error, or because dispatch gave up trying to recover a crash (see handling a crashed worker). Like stopped, it needs a person: it stays claimed, with a comment saying what went wrong, until someone resumes it, fixes it and reruns the finish step, or resets it to start over.

Back to open: starting over

Resetting a task releases whatever merge queue it might hold, removes its worktree and branch, clears every trace of the attempt from its metadata, and reopens it exactly as if it had never been dispatched. This is the one transition that erases history rather than building on it, and it exists for tasks where resuming the old attempt isn't worth it — the worktree is in a state nobody wants to inherit, or the task turns out to be bigger than one worker should carry and needs to be split into several before it's tried again.

The worker's own lifecycle inside "running"

Everything above treats "running" as one state, but the worker itself moves through a sequence inside it, and that sequence is what actually decides whether the task ends up merged, blocked, or needing a person. It starts in its own worktree, on its own branch, cut from the task's base. It implements the task — itself, or by handing the work to another agent — and commits: only committed work counts toward anything that follows. It then runs its finishing sequence, which reviews the change at the task's review level, rebases onto the base, verifies, and merges. If that sequence finds something the worker itself can fix — a requested change, a failing check, a conflict with a sibling task that merged first — the worker fixes it and runs the finishing sequence again. If it finds something only a person can resolve — an unapproved project check, a pending human review — the worker records why and stops, and dispatch picks the task back up once a person has acted. If the worker can't finish for some other reason, it records what's missing and stops the same way. Only once a process tied to the task's session actually ends does anything get recorded as an outcome; the recording step reads the worker's log for its final result, sets the task's state from it, and, for a merged task, removes the worktree. The scripts behind each of these steps are listed in scripts.

Why state lives in beads and the worktree, not in the supervisor

None of the facts a decision here depends on — a task's status, its metadata, whether a process still answers to its session, what's committed on its branch — belongs to whichever tool happens to be watching. They are facts a bead database, git and a worktree manager already keep, for reasons that have nothing to do with dispatch. A supervisor that kept its own notion of task state would drift from those facts the moment a person edited a bead by hand, a worker crashed without telling it, or a second session started dispatching the same repository. Reading the state back from beads and the worktree every time, instead of remembering it, is what makes a crash, a restart, or a second machine dispatching the same work unremarkable: whichever session looks next sees the same thing.