Skip to content

Latest commit

 

History

History
54 lines (30 loc) · 7.49 KB

dispatch.md

File metadata and controls

54 lines (30 loc) · 7.49 KB

Dispatch

The supervisor is the one thing in sdlc that runs continuously while work is in flight, and it is deliberately the least stateful part of the system. It holds no memory of what it has already done. Every time it wakes, it looks at beads, the process table, git and the worktrees again, decides what follows from what it sees, and acts. Nothing is carried over from one look to the next except a handful of housekeeping details — which tasks it has already reported as blocked, so it doesn't repeat itself — that exist purely to avoid noise, not to remember decisions.

Why it holds no state

A supervisor that remembered its own model of "what's running" would need to keep that model in sync with reality by hand, and it would be wrong the moment anything changed outside its notice: a person editing a bead, a worker crashing silently, a second machine dispatching the same repository. Task lifecycle explains why every task state is read off beads, processes and worktrees rather than written down by the supervisor. Dispatch is the same idea applied to the whole run: since every fact it needs already lives somewhere durable, the supervisor doesn't need a memory of its own, and taking a fresh look every time is not a performance compromise so much as the reason a takeover or a crash mid-round costs nothing.

Waking up

The supervisor sleeps between rounds rather than polling. It wakes on:

  • a wake signal written by the beads hooks (something in beads changed) or by a worker as it starts or ends
  • a sweep, a fixed interval after its last round ends, which exists to catch anything a wake signal missed and to check pull-request gates, since a merged pull request on GitHub doesn't itself notify beads
  • its own start
  • SIGTERM from a newer supervisor taking over its lock

Each wake produces one fresh look at the world, and the supervisor acts on that look before going back to sleep. A wake it can't yet act on because a bead operation failed mid-flight — a worker writing to the database at the same moment, say — is simply retried on the next wake; nothing about a missed round is lost, because nothing about it was ever the supervisor's own state to lose.

Acting in a fixed order

Every round considers, in the same order: crashed workers first (recording or resuming them, since a crash can free a slot that a start decision later in the same round should see), then tasks whose review gate has just closed, then, on a sweep, pull requests that may have merged, and finally starting ready tasks within the parallel limit. The order matters because later decisions in a round depend on earlier ones — a slot freed by recording a crash is available to the start decision in the same round, not the next one — so the round settles to a consistent view of what's dispatchable before anything new starts.

Why it never exits when work is done

The supervisor's exit condition is not "the queue is empty." It is "a person is needed, new work has appeared outside what was asked for, or a newer supervisor has taken the lock." Those are different things: dispatched work finishing cleanly produces no exit at all, because there's nothing for a person to act on — the supervisor just goes back to sleep and waits for the next thing to dispatch, review, or report. Exiting on an empty queue would mean restarting it constantly for no reason, and would give it a notion of "done" that isn't actually the point: sdlc is meant to keep going as new tasks appear, not to run once and stop. What each of the lines it prints on exit means for a person to do next is in messages.

Work order

When more than one task is ready to start, the supervisor doesn't pick arbitrarily:

  1. Tasks that belong to an epic already in progress — one with a task claimed or closed — come first, highest epic priority first. Finishing an epic that has already started keeps the number of half-open epics small: each epic in progress holds its own branch and its own merge queue, and starting a new one before an old one lands only grows how much is in flight at once.
  2. Then tasks of other epics, and tasks with no epic, ordered by priority.
  3. Within one epic, the task that would unblock the most other tasks goes first, then priority, then age. Clearing the tasks that gate the most siblings widens what can run in parallel as early as possible; age as the last tiebreaker keeps an old, low-priority task from waiting forever behind a stream of newer ones.

Slots and the parallel limit

The parallel limit, set in settings, counts slots, and a slot is held by a claimed task — in progress, with a session recorded — whether or not a process for it is still alive. A crashed task keeps its slot until the supervisor has decided what to do with it, because the machine resources and API concurrency a worker used are only actually free once that decision is made, not the instant the process happens to die. Recording or failing a crashed task frees its slot in the same round it's decided, so a new task can start without waiting for a whole extra wake; resuming a crashed task keeps the slot held, since the same worker is about to occupy it again.

Generations and takeover

Every supervisor run carries a generation, the timestamp of when it was started. Taking the lock signals whatever supervisor currently holds it and waits for it to exit, unless that holder's generation is higher — in which case the newcomer backs off instead of interrupting a run that started later than itself. This lets a person restart dispatch from a second session without two supervisors ever fighting over the same lock: whichever one actually started most recently wins, no matter which one asks for the lock second. Running dispatch on several sessions covers taking over deliberately.

What "dispatchable" means

A task is dispatchable when it is ready in beads (no open blocker), has no children of its own, and carries a verify command — or is an epic's integration task, which is exempt from needing one because its job is to merge rather than to satisfy its own acceptance criteria.

Why a failed worker is retried three times, then failed

A crash with no result in its log gets resumed, not failed, because most crashes are transient: a process killed by the host, a machine that rebooted mid-session. But a worker that keeps crashing without ever producing a result, run after run, is telling you something a retry can't fix — a broken environment, a task that can't be completed as written. After three resumes with still no result, the supervisor stops trying and fails the task instead, so a stuck task costs three attempts, not an unbounded number.

Why the dispatch skill restarts the supervisor after it prints

The supervisor exits the moment there's something a person should see, even though the rest of the dispatched work has nothing to do with that one blocked task. If nothing restarted it, every task that hits a review gate, a stopped worker, or a failure would silently stall every other task behind it, because there would be no supervisor left running to dispatch them. So the skill that started the supervisor restarts it immediately, with the same scope and generation, the moment it exits — before it does anything at all with what was printed — so the rest of the work keeps moving while a person is told what needs their attention. The supervisor itself, and everything it calls to act on a decision, is listed in scripts.