ADR 0219: the build queue is controlled through the controller and the build seat

The operator asked for tools to see, cancel, clear, stop, pause, continue,
restart and replay builds; none existed. Queue actions are the controller's,
process actions the build seat's per machine, and every action that drops
work leaves a failed outcome so no plan waits on it. To-be 18 amended.

03-DESIGN/01-to-be/18-building-a-module.md

@@ -7,6 +7,7 @@ code:
   - mesh-catalog modules/build-agent
 updated: 2026-10-05
 decisions:
+  - 02-DECISIONS/0219-the-build-queue-is-controlled-through-the-controller-and-the-build-seat.md
   - 02-DECISIONS/0190-a-seats-work-is-shared-by-its-holders-and-building-is-the-first-such-role.md
   - 02-DECISIONS/0157-a-build-says-what-it-does-on-the-bus-as-it-happens.md
   - 02-DECISIONS/0189-the-store-keeps-what-the-records-name.md
@@ -394,3 +395,26 @@ not of the recipe: one artifact declared per target, one build each.
 A component's version stops being stamped in at link time. It is unpacked into a directory named for
 its version, so it reads its version from its own path, and a build no longer has to know what it will
 be called.
+
+## The build queue is controlled
+
+*2026-10-05 — [ADR 0219](../../02-DECISIONS/0219-the-build-queue-is-controlled-through-the-controller-and-the-build-seat.md).*
+
+What is asked of the build seat can be seen and controlled from the console. The controller holds the
+queue, and each machine's build agent holds its own process.
+
+- **The controller's verbs:**
+  - `queue` lists every ask, waiting, in flight or dead;
+  - `cancel` and `clear` take asks back;
+  - `rebuild` asks again under a new id;
+  - `replay` asks again for a past build at its commit, as a dry run unless told to register, and never
+    over a newer build without saying so;
+  - `kill`, `pause` and `resume` are passed on to the seat on the right machine.
+- **The build seat's verbs, on each machine:**
+  - `current` says what is building here and whether this holder is paused;
+  - `kill` ends the build's whole process group and every container it started;
+  - `pause` and `resume` set a flag the holder reads before it takes the next ask, which survives its
+    restart.
+
+Every action that drops work leaves a failed outcome, so a plan waiting on that build fails and says why
+rather than waiting. A plan keeps the id of every build it asked for.