Show and change the build queue through the controller, and have plans follow it (hq ADR 0219)

Nothing showed what waited for a build machine, and an ask could not be
dropped without leaving the plan that made it waiting for ever. New verbs:
queue, cancel, clear, rebuild, replay, kill, pause, resume, and plans retry.
Every ask a person drops is recorded failed through the same take-in as a
failed build; a plan keeps the id it asked each module under and matches
its outcome by it. replay is a dry run unless registered, and registering
an older commit than one registered since needs --older (hq issue 207).
A plan waiting on a seat paused on every holder says so and is not late;
a failed plan can be retried, and a rebuild joins the plan holding the
module instead of running beside it.

internal/catalogue/verbs.go

@@ -97,6 +97,7 @@ var ControllerVerbs = []Verb{
 			"id":         "a plan's id (as `plans` lists them): that plan, tier by tier",
 			"stop":       "a plan's id: stop it — what was asked still builds, nothing further is asked",
 			"close":      "a plan's id: close a plan that will not move again, as failed by hand (novox/hq issue 254)",
+			"retry":      "a failed plan's id: ask its failed builds again under new ids, and carry the plan on from that tier (novox/hq ADR 0219)",
 			"repository": "owner/repository: the plan a merge there would produce, saving nothing (what-if); with paths or modules",
 			"paths":      "with repository: the files the merge would change, comma-separated, from the repository's root",
 			"modules":    "with repository: or the modules it would change, comma-separated",
@@ -156,6 +157,36 @@ var ControllerVerbs = []Verb{
 		Input: schema(map[string]string{
 			"command": "the command line, as the controller's binary takes it; quotes group a word with spaces",
 		}, []string{"command"})},
+	// The build queue, controlled by hand (novox/hq ADR 0219). Every verb that drops an ask leaves a
+	// failed outcome for it, so a plan waiting on it fails visibly instead of hanging.
+	{Name: "queue", Description: "Every ask in the build queue: waiting, in flight (on which machine, for how long), " +
+		"and dead (handed out as often as allowed and never settled) — each with its id, repository, path, ref and when it was asked.",
+		Input: schema(nil, nil)},
+	{Name: "cancel", Description: "Drop one waiting or dead ask from the build queue; its outcome is recorded failed, " +
+		"cancelled by hand, and a plan that asked for it fails. One in flight is refused: `kill` ends it where it runs.",
+		Input: schema(map[string]string{"id": "the ask's build id, as `queue` lists it"}, []string{"id"})},
+	{Name: "clear", Description: "Cancel every waiting ask in the build queue — and with dead, every dead one too — each " +
+		"recorded failed, cancelled by hand. Never touches one in flight.",
+		Input: schema(map[string]string{"dead": "\"true\" to cancel the dead asks as well"}, nil)},
+	{Name: "rebuild", Description: "Ask a module's current source again under a new id — the branch it follows — or, given a " +
+		"build's id, that build's repository, path and ref. A module a plan holds unbuilt or failed joins that plan. Answers the new id.",
+		Input: schema(map[string]string{"what": "a module's name, or a build's id"}, []string{"what"})},
+	{Name: "replay", Description: "Ask a recorded build's repository and path again at the commit it built, under a new id. " +
+		"A dry run unless register: nothing recorded or registered. Registering is refused when a newer build of the module " +
+		"is registered — it would roll the older commit out (novox/hq issue 207) — unless older says so.",
+		Input: schema(map[string]string{
+			"id":       "the build's id",
+			"register": "\"true\" to register what it builds",
+			"older":    "\"true\", with register: even though a newer build of the module is registered",
+		}, []string{"id"})},
+	{Name: "kill", Description: "End a build where it runs: the machine that took it stops its commands and containers and " +
+		"announces it failed, killed by hand — settled, never handed to another machine.",
+		Input: schema(map[string]string{"id": "the build's id"}, []string{"id"})},
+	{Name: "pause", Description: "The build seat's holder on one machine — or every holder — takes no new build until resumed; " +
+		"a build running finishes. Kept across a restart of the holder. A plan waiting on a paused seat says so and is not late.",
+		Input: schema(map[string]string{"node": "one machine; every holder when absent"}, nil)},
+	{Name: "resume", Description: "The build seat's holder on one machine — or every holder — takes builds again.",
+		Input: schema(map[string]string{"node": "one machine; every holder when absent"}, nil)},
 	{Name: "build", Description: "Have the build machine build a repository. Answers at once with the build's id: " +
 		"`builds` with that id follows it line by line, and the module is registered when the outcome comes.",
 		Input: schema(map[string]string{

internal/inventory/builds.go

@@ -3,8 +3,11 @@ package inventory
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"sort"
 	"time"
+
+	"github.com/jackc/pgx/v5"
 )
 
 // What has been built.
@@ -161,6 +164,33 @@ func (i *Inventory) Builds(ctx context.Context, module string, limit int) ([]Bui
 	return out, rows.Err()
 }
 
+// BuildByID is one build's record, by the id its request carried — what a plan matches its outcome
+// by when the outcome names no module (novox/hq ADR 0219), and what `rebuild` and `replay` read the
+// repository, path, ref and commit from. False when no outcome with that id was recorded.
+func (i *Inventory) BuildByID(ctx context.Context, id string) (Build, bool, error) {
+	var b Build
+	var made []byte
+	var asked *time.Time
+	err := i.store.Pool().QueryRow(ctx,
+		`select id, repository, ref, coalesce(module,''), commit_hash, built_on, failed, made,
+		        coalesce(source_path,''), asked, at
+		   from build where id = $1`, id).Scan(&b.ID, &b.Repository, &b.Ref, &b.Module, &b.Commit,
+		&b.On, &b.Failed, &made, &b.Path, &asked, &b.At)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return Build{}, false, nil
+	}
+	if err != nil {
+		return Build{}, false, err
+	}
+	if asked != nil {
+		b.Asked = *asked
+	}
+	if err := json.Unmarshal(made, &b.Made); err != nil {
+		return Build{}, false, err
+	}
+	return b, true, nil
+}
+
 // Held is every artifact this mesh has built, keyed "<module>/<artifact>".
 //
 // **The successful build of each module asked last wins**, which is the same rule the rest of the

internal/inventory/plans.go

@@ -49,6 +49,11 @@ type PlanModule struct {
 	FirstAt *time.Time `json:"first_at,omitempty"`
 	Commit  string     `json:"commit,omitempty"`
 	Why     string     `json:"why,omitempty"`
+	// Build is the id of the build the plan asked for this module (novox/hq ADR 0219), so the plan
+	// matches its outcome by id — the one thing every outcome echoes, a failed one that never learnt
+	// its module's name included. Empty in a plan from before it was kept, which is matched by
+	// module, or by repository and path, as before.
+	Build string `json:"build,omitempty"`
 }
 
 // The states a plan passes through.