Orchestration overview — Glueprint Docs

Orchestration is how one coordinator breaks a larger objective into tasks, hands each task to a worker session, and finds out what happened. The pieces are deliberately small: a run, its private tasks, the dependencies between them, the worker sessions dispatched against them, decision gates that pause a task for a human answer, and an inbox the coordinator reads to learn what changed.

The durable records — runs, tasks, gates, and dispatch rows — live on the host that owns the run. There are no server tables for them. What does travel is routing metadata: a worker placed on another host receives the run id, task id, and delegation details it needs to report back, and its reports come home through the relay.

The vocabulary

Run. A run is one objective with a set of private tasks. A run is owned either by a coordinator session (any ordinary session, or an assistant’s session) or by an operator with no session at all — someone driving the glueprint CLI. A run is open until it is closed, and closing records one of completed, failed, cancelled, or abandoned.

Task. A private task belongs to exactly one run. Its stored status is one of pending, dispatched, completed, failed, or cancelled. Private tasks are not the product Tasks & Boards store; they never appear on a board, and the board tools never see them.

Dependency. A task can depend on other tasks in the same run. Dependencies form a directed acyclic graph (DAG): the engine refuses an edge that would create a cycle. A run holds at most 200 tasks, and a task at most 50 dependencies.

Readiness. Readiness is derived, never stored. A pending task is ready when every task it depends on is completed and no open gate is attached to it. Otherwise it is blocked, and the blocked state names the tasks and gates in the way. When a blocker has failed or been cancelled anywhere up the dependency chain, the blocked state is marked unresolvable. The derived states you will see are ready, blocked, dispatched, completed, failed, and cancelled.

Worker and dispatch. A worker is an ordinary session started for one ready task. Starting it creates a dispatch, which is one attempt: the record that ties the task to the child session, with an attempt number and a lineage back to any prior attempt. A dispatch settles as completed, failed, superseded, or cancelled. Retrying a worker creates a new dispatch and supersedes the prior one; reports from a superseded attempt are informational and cannot complete the task.

Decision gate. A gate is a question attached to a task: a prompt, optional preset answers, and optionally a free-form reply. While a gate is open, the task is blocked. Resolving or withdrawing the gate unblocks it. A gate created with defer_until_dependencies_settle holds its question until the task’s dependencies have completed, so checkpoints can be planned up front without asking them early. A gate never changes the coordinator session’s own status; it only changes derived readiness. A task can carry at most 10 open gates, and a gate at most 20 options.

Inbox. Every coordinator has a durable inbox. Orchestration writes records into it when a task becomes ready (task_ready), when a gate is answered (gate_resolved), when a worker reports a terminal outcome (worker_done), when the run can no longer make progress (dag_stuck), and when a worker stops making observable progress (stalled). Plain progress reports arrive as status. Records stay until they are acknowledged by exact id; delivery is not acknowledgment.

Liveness. Whether a local worker is alive is derived by the engine from the process and the session’s activity. There is no heartbeat tool for workers to call. A worker on another host reports through its inbox records instead, and its liveness reads as unknown.

Who coordinates

Three kinds of coordinator use the same store:

A session you started. From inside the session, the coding agent uses the gp_orch_* tools of the built-in MCP server for runs, tasks, dependencies, dispatch reads, and gates; it normally starts inline workers with gp_spawn_subagent, uses gp_create_session for a separate tab or another host, and reads its inbox with gp_check_inbox and gp_ack_inbox. See MCP tools for orchestration.
An assistant. An assistant’s session also uses gp_spawn_subagent for inline workers. For a separate tab or another host it uses gp_start_session with a delegation block. Both paths follow the delegation rules its role permits. Eligible inbox records can wake the assistant.
An operator with no session. The glueprint CLI can create an operator-owned run, start workers against it, and poll the run’s inbox. See Orchestration from the CLI.

Runs can also be owned on behalf of a session from the CLI, so a script can prepare work for a coordinator session that is already open.

Inline subagents and full sessions

gp_spawn_subagent starts a child session inside the parent’s transcript as a collapsible card. It is available to human-initiated and assistant-attached sessions, requires a prompt, and starts without a spawn approval card. The child has its own agent process, transcript, questions, and permissions; approving its creation is separate from approving the actions it takes.

Inline subagents run on the same host as their parent. You can still follow them remotely through desktop, portal, or mobile when you have full cloud relay access. For example, if you view a server’s parent session from your laptop, both the parent and its subagents run on the server. Expanding a child card shows its activity and lets you answer its questions and permission requests. Open shows a full-chat sheet on desktop and portal, or a session detail page on mobile.

Use gp_create_session from a human-initiated session, or gp_start_session from an assistant, when the worker needs a separate workspace tab or must run on another host. Those full-session creation calls require approval. Passing another host to gp_spawn_subagent is refused before a child is created. See Cross-host work and recovery.

Where it shows up

When a session coordinates an open run, or works on one, the card above the composer gains a Plan tab beside Subagents. The desktop shows it for sessions on this computer and on your other hosts, and the web portal shows it for sessions on any of your hosts. The tab header shows progress (“4/13 done”) and flags a run that is stuck or has a decision waiting, so you can read it without opening the tab.

The Plan tab lists the run’s objective and then every task in dependency order, so each task appears after the tasks it waits on:

A waiting task names only what unblocks it next, for example after P7, P9, P6C. Hover a row to see every task it waits on.
A task the coordinator can start reads Ready. A task held by a gate reads Needs decision, and the decision appears above the list. A gate whose question is still held until the tasks before it finish appears there as Upcoming decision, and the tab header does not count it as a decision waiting on you.
A dispatched task shows its worker session’s live status and running time. Click the row to go to the worker, on whichever host it runs. On the desktop and in the portal, an inline subagent opens in its sheet; on the desktop, a full session opens in its tab. On mobile, an inline subagent opens inside the sheet, and a full session opens its own session page.
When a dependency failed or was cancelled, the tasks behind it read Can’t start and name the task that failed, and the run shows a stuck notice.
For a worker session on the coordinator’s host, the plan marks its own task and links back to the coordinator. A worker running on another host shows no plan of its own; open its coordinator to follow the run.

Collapsing the card or picking a tab is remembered for that session while the app or browser tab is open. Sessions without an open run keep the plain Subagents card.

On mobile, a bar above the composer sums up the same work, for example Plan 4/13 done and Subagents 2 active, with flags for a stuck run, a waiting decision, and subagents that need your input. It appears when the session has an open run or any subagent. Tap it to open a sheet; when the session has both a plan and subagents, the sheet has Plan and Subagents tabs; tapping the Plan or Subagents part of the bar opens that tab. The Plan tab shows the same tasks, decisions, and stuck notice. The Subagents tab lists active subagents first, then finished ones, including Claude and Codex subagents. Tap a Glueprint session subagent, or a task whose worker is an inline subagent, and its session opens inside the same sheet: its live messages, its questions and permission requests, which you can answer there, and a message bar to steer it. The header shows its name and status, a back arrow, Open full session and Close. Harness rows (Claude Task/Agent, Codex collab) open an activity page inside the sheet with Back and Close. A Glueprint session subagent’s own subagents open one level deeper. Back, or the system back gesture, returns one level at a time to the list you left; Close, or dragging the sheet down, closes it from any level. A task whose worker is a full session closes the sheet and opens that session.

Session info (in the session’s overflow menu on the desktop) keeps the run history for sessions on this computer: every run the session coordinated or worked on, open runs first, each with its status, the same task list, and its dispatch attempts with attempt numbers and liveness.

Orchestration is read-only in all of these views.

Gates surface as ordinary question cards on the coordinator session, the same card you see when an agent asks you something, on the desktop, in the portal, and on mobile. Answering the card on any of them resolves the gate, and the plan updates everywhere. The card is pinned like any other question, but the coordinator session keeps running; it does not flip to waiting. On the desktop, for a session on this computer, the decision in the Plan tab also has a Show question button that brings the card back into view.

A run always stays on its host. Another device reads it through the end-to-end encrypted cloud relay and refreshes it as the run changes:

Older hosts show subagents only. A host on an older version of Glueprint cannot send its plan, so its sessions show just the Subagents list. Update Glueprint on that host; the plan appears once the host reconnects.
Very large plans. When a session’s open runs are too large to send through the relay at once, the Plan tab shows “This plan is too large to show here.” with a Retry button instead of the task list. It does not retry on its own. Closing runs you no longer need makes the plan smaller.
Account plans. Reading a run from another device follows your plan’s relay access: the desktop and mobile apps show it on Lite and higher. The web portal needs Pro or higher. The desktop always shows the plan of a session on this computer. See Plans.

A short lifecycle

A coordinator creates a run with the objective “Ship the release” and three tasks: implement, verify (depends on implement), and deploy (depends on verify).
Only implement is ready. The coordinator starts a worker for it; the task becomes dispatched.
The worker finishes and reports completed. The dispatch settles, the task completes, verify becomes ready, and a worker_done record plus a task_ready record land in the inbox.
The coordinator starts a worker for verify. Meanwhile it attaches a gate to deploy asking “Deploy now?” with the options Yes and No. Deploy stays blocked even after verify completes.
You answer the question card on the coordinator session with Yes. The gate resolves, deploy becomes ready, and gate_resolved and task_ready records arrive.
The deploy worker completes. If the run was created with auto-close, it closes as completed once every task is terminal; otherwise the coordinator closes it. Closing withdraws any open gates but never stops live workers.

Had the verify worker failed, deploy would have read as blocked and unresolvable, the run would have been marked stuck, and a single dag_stuck record would have been delivered. The coordinator could then retry the worker or reset the failed task and try again.

What the engine guarantees

Readiness is recomputed from stored status on every read; there is no separate flag to get out of sync.
Each task has at most one active dispatch. Starting a second worker for a dispatched task is refused, as is starting one for a task that is not ready.
Crash recovery runs at boot and every 30 seconds after that: lost local workers are settled, abandoned coordinators close their runs, stuck runs are reported once per episode, and auto-close runs close when every task is terminal. See Cross-host work and recovery.
Closed runs are kept for 30 days, up to the 100 most recent, then removed.