How Legion, Dispatch and the broker fit together

Four components share the work. Dispatch holds the record: the issues, their documents, and every decision a person makes about them. Legion works the issues handed to it by running coding agents. The Secrets Broker gives those agents credentials, with a person’s approval, on the broker’s own page that Dispatch’s Inbox links to, when the secret’s owner and tier require one. Envoy carries events between them.

flowchart TB
  people([People])
  github[(GitHub)]
  subgraph dispatch [Dispatch]
    record[Issues and documents]
    inbox[Inbox]
  end
  envoy{{Envoy}}
  subgraph legion [Legion]
    coordinator[Coordinator]
    agents[Agents]
  end
  subgraph secrets [Secrets Broker]
    broker[Requests and grants]
    approve[Approval page]
  end

  people -->|file issues, answer asks, approve specs| dispatch
  people -->|approve secret requests| approve
  people -->|merge| github
  dispatch -->|events| envoy
  github -->|pull request and CI events| envoy
  envoy -->|events| coordinator
  envoy -->|messages| agents
  coordinator -->|runs| agents
  agents -->|specs, comments, asks, status| dispatch
  agents -->|pull requests| github
  agents -->|request a secret| broker
  broker -->|pending requests, each linking its page| inbox
  inbox -->|link| approve

Dispatch: the record of work and decisions

Dispatch is a web dashboard and an HTTP API over one store of projects and issues. Each issue has a lifecycle status, from Triage, Icebox, Backlog and Todo through In Progress, Testing, Needs Review and Retro to Done.

An issue carries documents, the first of which is its spec. People and agents comment on a document, suggest exact replacements for its text, and ask questions. An ask is a decision put to a named person: it waits in that person’s Inbox until they answer it, and an approval request is an ask whose answer approves a document at one version or requests changes with a reason.

People use the dashboard: they file issues, answer asks, approve specs and watch the agents working on the Agents page. Agents use the dispatch command and the API to write specs, post comments and messages, open asks and move issues. Dispatch publishes its issue, document and project events on Envoy, so nothing that reacts to Dispatch has to poll it.

Legion: the coordinator and its agents

Legion’s coordinator works only the issues handed to it, which are the ones carrying the Dispatch label legion. That lets Legion share a project with people and other agents. A person sets the label from the issue header, or asks Legion’s own controller agent to set it for them; the controller never hands over work on its own. An agent that finds a problem outside its own issue files no issue: a defect with a clear fix in code its own tree touches or depends on is fixed in that tree’s pull request, any other goes to the controller, which gives it to the tree that owns that code and files it for Legion only when none does, and a problem that needs a decision goes to a person in a Dispatch ask.

Each admitted issue gets an architect, which owns the issue’s tree. It writes the spec, splits large work into child issues, and runs each change through phase workers in turn: a planner, an implementer, a tester and a reviewer, then a merger. Every agent works in a workspace of its own, and every phase records a structured handoff on the issue in Dispatch, which the next role reads and a restarted agent recovers from. The coordinator writes the issue’s status back to Dispatch as the work moves (In Progress, Testing, Needs Review, Retro).

Two decisions stay with people:

• The design gate. Before implementation starts, a person approves the root issue’s spec at a specific version in Dispatch. A later version of the spec closes the gate again until someone approves it, unless that version is the person’s own answer to a decision block and the answer is the whole change since the version they approved: then Dispatch records their approval at the new version and the gate reopens. The gate is on by default; a deployment can turn it off.
• The merge. The merger reads the pull request and merges it itself, at the head it read and under a message it writes. The repository’s own rules decide whether and when it lands, so a check it requires, or a review a person must give, stays theirs; the coordinator submits no merge and turns auto-merge on nowhere.

The coordinator runs its agents as Oh My Pi sessions, either in tmux panes on one host or as Agent Sandbox pods in a Kubernetes cluster.

Secrets Broker: credentials a person approved

An agent that needs a secret, such as a token for a service its task touches, asks the broker for it by name. The agent’s session or pod first enrolls with the broker under a signing key of its own, so every request is signed by the session making it. Two tags on each secret, its owner and its tier, then decide whether to grant the request automatically (the owner’s own sessions asking for an agent-tier secret), send it to a person for approval (its owner, or anyone for a shared human-tier secret), or refuse it.

A secret request appears in that person’s Dispatch Inbox, labelled as a secret request, as a link to its page on the broker. The person opens it, signs in to the broker with their Workspace account if their last sign-in there has lapsed, reads the request the broker prints from its own record, the reason the agent gave included, and approves or denies it on that page, which the broker accepts only from its own origin. No route Dispatch or any other service calls decides a secret request. A machine login, labelled as one, is approved in Dispatch by typing the code the machine shows, and Dispatch relays that decision, and a person’s revoke of a grant or a machine login, under the signed-in person’s identity. The broker opens no ask and writes nothing in Dispatch: Dispatch reads the pending requests from the broker, and the broker reads one thing back, whether an issue its model judge was given is open. A grant lasts the lifetime its request named, else 15 minutes for a request that names a human-tier secret and 12 hours for any other (until its session ends for secrets tagged default-grant=session), and agent-secrets NAME -- <command> runs a command with the granted value in that command’s environment rather than printing it. The secrets themselves are created and changed in the broker’s own store (AWS Secrets Manager or GCP Secret Manager), under whatever cloud credential the store’s IAM lets write them, with agent-secrets secret, which has the broker serve each change at once.

Envoy: the events between them

Envoy is the event transport, built on NATS JetStream. Dispatch publishes each issue’s events to a topic of the form notifications.dispatch.issue.<KEY>.<event>, and Envoy turns GitHub’s webhooks into events on topics for each repository and pull request. Legion’s coordinator reads both streams with durable consumers, so an event that arrives while it is down is read when it comes back.

Envoy also delivers messages to agent sessions directly: a message to one session, to whichever session holds a role, or a broadcast a person sends from the Dispatch Agents page. The listener keeps a durable consumer for each Oh My Pi or Claude Code session and hands it the stored messages in order, each counted as delivered only once the session has it, so a session that was stopped or lost its connection gets what was sent to it, the messages to a role it holds, and what was published on the issue topics it follows, once, when it is back, for up to 72 hours. Envoy decides only where an event goes; what to do about it is the coordinator’s and the agents’ business.

An issue, start to finish

1. Someone files an issue in a Dispatch project. It starts in Triage.
2. When it is ready, a person moves it to Todo with the legion label, or asks the controller to.
3. The coordinator admits it and starts its architect, which writes the spec.
4. The architect requests approval. The request reaches the approver’s Inbox, they approve that version, and Dispatch publishes the approval on Envoy. The coordinator opens the design gate.
5. The planner, implementer, tester and reviewer take the change in turn. A review that requests changes sends it back to the implementer, and through the tester again.
6. Once the reviewer approves, the architect reads the evidence and accepts the change (or sends it back), and the retrospective runs. The merger then reads the pull request and merges it itself, at the head it read, under a message it writes rather than GitHub’s default; it lands under the repository’s own rules, and the coordinator closes the issue when it reads that merge: it is Done.
7. After the close, the role projects.<KEY>.production_check names — the tester, by default — drives the change in production and records what it observed on the pull request. The merge itself starts the first look; after that the agent names its own next look on each pending report, and nothing a deployment publishes wakes it. A project that sets off opens no check.

Read on in Legion, Dispatch and the Secrets Broker.