v4.5.0 - Orchestration: an orchestrator, a supervisor and a dashboard for each board

A roadmap loop used to need a person next to it. You started a group in one terminal and watched a second terminal for a stop. You also ran small scripts. The scripts continued after a usage limit, resumed a lost session and asked for a handoff when the context filled. A loop that failed a gate or reached a budget could wait with nobody looking. With four loops open, you kept the state of all four in your head.

This release moves that work into Dispatch. Each board can have an orchestrator, a Claude session that coordinates the groups of the board. The supervisor does the fixed jobs that need no judgment. A new dashboard shows what needs you first. Version 4.3.0 shipped the server parts of this. This release adds the screens and the orchestrator session on top of them.

The orchestrator

Open a board and choose Add orchestrator in the page header. The orchestrator panel opens beside the board. It has four tabs: Terminal, Decisions, Policy and Orchestrators. Choose Start orchestrator. When the board has no orchestrator yet, Dispatch adds the main orchestrator first.

The orchestrator is a Claude session in tmux. It starts with the Board Orchestrator playbook and the Dispatch tools. Its file tools are Read, Glob and Grep. It has no Bash, Write, Edit or NotebookEdit, so it cannot change code. It also cannot change the policy of the board. Only you can.

What the orchestrator does:

• It turns a goal into a ticket proposal. A proposal is a decision item. The orchestrator creates tickets only after you approve it.
• It writes a direction for each group, and it starts groups inside the concurrency cap.
• It approves a roadmap or asks you, as the policy says.
• It answers loop inputs, waits for events, and ships groups in order when the ship rights allow it.
• It raises a decision item when a person must decide.

A first real run showed three gaps, and this release closes them.

• It reads the board first. The orchestrator reads the folder and the repositories of the board with the get_board_workspace tool. It never asks you for a repository path or a base branch.
• It waits between turns, and Dispatch wakes it. When the orchestrator waits at its prompt, Dispatch types one line that starts with "Dispatch wake:". Dispatch does this when you answer a decision item, and when a group reaches Agent done or needs input. It also wakes the orchestrator when a group fails to start, ships, stops its ship flow, hits a loop error or reaches a usage limit. The wake timer of the policy is the last trigger.
• It ships a group that ran no roadmap loop. The group card must be in Agent done. Each branch must be ahead of its base, and the worktree must be clean.

The Orchestrators tab shows the reasons and the time of the last wake of each orchestrator.

The panel header shows the state of the session as a badge, for example Working, Needs input or Session lost. Stop interrupts the current turn. Resume orchestrator shows when the session is lost or Claude exited. The Decisions tab lists the open decision items. The Orchestrators tab lists the orchestrators of the board. You can add an extra orchestrator with a scope of groups or tickets, after the main orchestrator exists.

A start can fail. The panel then shows "The orchestrator did not start" with a reason, and a Try again button.

The policy and the supervisor

The Policy tab holds the rules that the orchestrator and the supervisor follow on this board.

• Roadmap approval: ask you for each roadmap, approve when the rules pass, or approve each roadmap.
• Loops at once: 1 to 10. The default is 3. A group that waits for its dependencies stays queued, and the supervisor starts it when a slot is free.
• Group playbook: the playbook that create_group uses when the orchestrator names none. The default is None.
• Orchestrator model: Opus 5.5, Sonnet 5.5 or Fable 5.1. The default is Opus 5.5.
• Wake timer (minutes): Dispatch wakes an idle orchestrator after this many quiet minutes. The default is 15. 0 turns the timer off.
• Handoff at context percent (default 50) and Hard handoff at context percent (default 80).
• At a usage limit: wait for the reset, or stop and ask you.
• Ship rights: none, open PRs, or open and merge PRs. The default is none.
• Budget per group (USD): empty means no limit.
• Supervisor: on or off. A new board starts with it on. The default board, Local, starts with it off. An orchestrator needs the supervisor on.

The supervisor runs inside the Dispatch server. It reads the loop files and the status line of each session.

• At the handoff percent, it sends one handoff request. The loop finishes its work in progress and writes its resume notes. The supervisor then clears the conversation, sends the resume prompt and checks that the new session id is in the engine file. At the hard handoff percent, it sends one hard request.
• At a usage limit, it picks the wait or stop row of the dialog and never a row that offers usage credits. With Wait for the reset, it sends one continue prompt two minutes after the reset. With Stop and ask me, the loop waits for you.
• When the cost of a group reaches its budget, the loop stops and waits for you. You can raise the budget or resume the loop.
• It resumes a lost session, and it keeps the Mac awake with caffeinate while a supervised session runs.
• It sends the wake of the orchestrator as one typed line in the orchestrator pane. It sends each wake reason one time only, and it never types while the pane is busy.

The dashboard

Each board has a dashboard page. Open it from the Dashboard row in the sidebar or from Go to Dashboard in the palette. The sidebar row shows when the board has a main orchestrator. It has six sections.

1. Attention queue. Each item that needs you, oldest wait first. The item kinds are a decision, needs input, no progress, a permission prompt, a usage limit stop, a budget stop, a failed gate and a failed resume. You can answer a decision, reply to a loop, resume a loop and try a failed resume again from the queue. A permission prompt has no approve button. You answer it in the terminal.
2. Progress per group. One row for each loop: a bar with one segment for each unit and the position as text (for example "Unit 2 of 3, phase 4 of 9"). The row also shows the last gate, the context percent, the session time and an estimate of the time left.
3. Tickets by column, with the count of cards that the orchestrator created.
4. Activity log of orchestrator tool calls and supervisor actions, with filters for actor and group.
5. PRs and merge order for each group, with the ship state, the check state and the author check.
6. Cost and usage: the cost of each group against its budget, and the usage meters with their reset times.

The page updates from the board stream with no reload. Every state has a glyph and a text label, so the page reads without color. If the connection drops, the page keeps the last data and shows "Data from" and the time. It disables the reply, resume and decision buttons until the stream returns.

The boards page gains two columns. Attention shows the number of items that need you on each board. Loops shows each running loop as a group id and a percent.

The ship flow

When the ship rights allow it, the orchestrator ships a finished group with the ship flow. The flow handles each branch in order. It merges main, runs the check command of the repository, pushes, opens the PR and waits for the checks. With Open and merge PRs, it then merges the PR as a squash merge. It checks the author and the message of the new tip of main against your git identity. With Open PRs, it waits for you to merge. If a branch fails, the flow stops. The dashboard shows the step and the reason, and a decision item appears in the queue.

Proven end to end

We ran a real orchestrator on a sandbox board with a bare local origin. It built a real group and shipped it in 2.1 minutes, for 0.43 USD in total on Sonnet 5.5. Nobody typed into a session after the start. The first start_ship call refused the group because its branch had no commit. The orchestrator told the group to commit, and the second call shipped it.

The five scenario tests pass on the final tree of this release: the orchestrated board, parity with 4.2.0, the upgrade, the ship of a group with no loop, and the wake.

Also in this release

• Docs. docs/user-guide.md explains the whole feature. It includes a reference for the five seeded playbooks, and a table of the manual scripts that Dispatch replaces: watch-loops.zsh, resume-loop.zsh, resume-after-reset.zsh, handoff-request.md and the keepawake tmux session. docs/ARCHITECTURE.md gains an API section, which includes the board workspace tool.
• Tests. Scenarios 4 (the ship of a group with no loop) and 5 (the wake) join scenarios 1 to 3 in tests/e2e.

Known limits

• You cannot approve a permission prompt from the queue. Open the terminal.
• The queue refuses a reply in four cases. The session shows a permission prompt, the session shows the usage limit dialog, the session waits for the usage reset, or Claude exited.
• A reply of more than 500 characters goes to the loop as a file with a one-line pointer.
• The queue has no length limit.
• A Needs input item can take up to about 2 seconds to show, because the marker watcher reads the panes every 2 seconds.
• The sidebar Dashboard row and the Go to Dashboard command show only on a board with a main orchestrator.
• When a start fails, the reason in "The orchestrator did not start" can be raw text from the Claude pane.
• A wake line clears a message that you typed but did not send in the orchestrator terminal.

Upgrade notes

• The store schema stays at 3, as in 4.3.0 and 4.4.0. The first start adds one column, orchestrators, to the boards table of board.db when it is absent. The release makes no version change, and a 4.3.0 or 4.4.0 build keeps the value.
• A board policy that an older build saved gets the defaults of the two new fields: Group playbook None and Wake timer 15 minutes. A 4.3.0 or 4.4.0 build keeps the stored values.
• For contributors: the scenario tests are in tests/e2e. Build first, then run the *.e2e.ts files with the Node test runner as the user guide shows. They need tmux. The visual suite now covers the boards page, the orchestrator panel and the dashboard.

See it

dispatch-v4.5.0-orchestration.mp4

Higher-quality video with narration: dispatch-v4.5.0-orchestration.mp4

Full changelog: v4.4.0...v4.5.0

Requires Node ≥ 22.22, tmux, ttyd, git, and the Claude Code CLI. Setup is in the README.