The Controller

The Controller is the brain of the entire fleet. It is a single, long-lived process that lives in the NEXUS workspace (the control plane) and is the only component that talks to Coder's API to create workspaces and coordinate the agents.

What the Controller does

Its responsibilities are the checklist of "how the team coordinates":

• Ingest. Pull GitHub issues into tickets the team can work on.
• Dispatch. Assign each ticket to an idle worker (FORGE, SENTINEL, VESSEL, or LORE).
• Provision. Create Coder workspaces for each agent and bind the right task to each.
• Coordinate. Route work between roles as each step completes.
• Recover. Watch for stalled, orphaned, or crashed work and repair it — with bounded retries before escalating to a human.
• Escalate. Park tickets that need a person and notify across Slack, Discord, or WhatsApp.
• Host the relay. Run the small internal relay used for reviewing evidence.

How it drives the team

The Controller doesn't command agents with ad-hoc messages. It runs a flow — an ordered map of steps and the allowed transitions between them. It is the single place the possible transitions are declared: NEXUS hands a build to FORGE, FORGE's result goes to SENTINEL for review, an approved review goes to VESSEL to merge, and merged work goes to LORE to document, then back around to NEXUS.

Each step, in turn, follows a fixed rhythm:

1. Read the current state.
2. Act — do the external work called for (provisioning a workspace, starting a chat, opening a merge).
3. Record and route — write the result and hand control to the next allowed step.

Because every possible transition is declared in one place, the system can't wander off into an unplanned path — and if an unexpected path is ever taken, the Controller treats it as an anomaly and escalates rather than silently ignoring it.

The rhythm: steady, repeatable passes

The Controller works on a steady cadence, not by reacting to events. Roughly every few seconds it:

1. Re-reads the entire state from the coordination store.
2. Advances every in-flight piece of work by exactly one step.
3. Repairs anything broken that it can.
4. Goes back to sleep until the next beat.

This "read everything, nudge everything, repeat" loop is what makes the system self-healing and convergent: even after a partial failure, the next beat re-discovers the real state and sets things right.

It never dies over a bad moment

A core design rule: a single bad pass must never take down the Controller. If a step errors, it is logged and simply retried on the next beat. One transient hiccup — a network blip, a slow API, a workspace that didn't come up — is absorbed instead of crashing the process. The only way the Controller stops is by being deliberately stopped.

Where its knowledge lives

The Controller keeps almost no important knowledge in its own memory. Everything durable lives in the coordination store, which it re-reads on every pass. That is why it can restart mid-flight and pick up exactly where it left off: the state is in the store, not in the process.

The control surface

The Controller also answers to operators. Through the control panel (and its command-line equivalent), you can:

• See live status.
• Edit the agent registry with no restart.
• Pause, drain, or target the fleet — halt new work, stop picking up tickets, or focus on a specific repository, issue, or label.

These control actions live in the store too, so the change applies on the very next beat — no downtime.