Merge pull request 'Clone from the forge again when the resolver does not answer, so a passing lookup failure does not fail a build (issue 1773)' (#440) from fix/1773-clone-retries-a-lookup into main

The check's floor of free space reads the disk the test runs on, so
every mesh-controller check failed while its build node had under
20 GiB free, whatever the change (seen in the try of issue 1773's fix).
The replay stubs the free space, as internal/builder's tests do.

Makefile

@@ -90,15 +90,6 @@ redis-provisioner-image:
 	@echo
 	@docker image inspect $(REDIS_PROVISIONER_IMAGE) --format 'built {{.RepoTags}}  {{.Size}} bytes'
 
-# The proxy that turns a route grant into traffic reaching a workload.
-PROXY_IMAGE ?= mesh-route-proxy:$(VERSION)
-PROXY_DEV_TAG ?= mesh-route-proxy:development
-
-proxy-image:
-	docker build --build-arg GO_BASE=$(GO_BASE) -f modules/route-proxy/Dockerfile -t $(PROXY_IMAGE) -t $(PROXY_DEV_TAG) .
-	@echo
-	@docker image inspect $(PROXY_IMAGE) --format 'built {{.RepoTags}}  {{.Size}} bytes'
-
 # The whole check. Raises a database, runs the repository's own check against it -- merge-check.sh,
 # the very script `mesh/repo-check` runs -- and takes the database down again, including when the
 # check fails, which is why the teardown is not conditional and the script's exit status is the
@@ -117,7 +108,7 @@ proxy-image:
 # as the script runs them: a bus per test, of the release the mesh runs, makes the suite the same in any
 # order, and the timeout bounds a hang to a failure with a stack, never a stalled gate.
 check: postgres
-	@sh merge-check.sh ; status=$$? ; docker rm -f $(PG_CONTAINER) >/dev/null 2>&1 || true ; exit $$status
+	@sh merge-check.sh ; status=$$? ; docker rm -f -v $(PG_CONTAINER) >/dev/null 2>&1 || true ; exit $$status
 
 # The unit level alone (untagged: no bus, no store, no other process), which a developer runs continuously. The tests
 # that need a bus or the store carry `//go:build integration` and run in `check`, not here; without a database the
@@ -135,7 +126,7 @@ fmt:
 	if [ -n "$$unformatted" ] ; then echo "not gofmt'd:" ; echo "$$unformatted" ; exit 1 ; fi
 
 postgres:
-	@docker rm -f $(PG_CONTAINER) >/dev/null 2>&1 || true
+	@docker rm -f -v $(PG_CONTAINER) >/dev/null 2>&1 || true
 	@docker run -d --name $(PG_CONTAINER) -e POSTGRES_PASSWORD=check \
 		-p 127.0.0.1:$(PG_PORT):5432 $(PG_IMAGE) >/dev/null
 	@printf 'waiting for postgres'
@@ -147,7 +138,7 @@ postgres:
 	echo ' — never came up' ; docker logs $(PG_CONTAINER) | tail -20 ; exit 1
 
 postgres-stop:
-	@docker rm -f $(PG_CONTAINER) >/dev/null 2>&1 || true
+	@docker rm -f -v $(PG_CONTAINER) >/dev/null 2>&1 || true
 
 clean:
 	rm -rf build/

cmd/mesh-builder/busy.go

@@ -6,7 +6,11 @@ import (
 	"os"
 	"path/filepath"
 	"strings"
+	"sync"
+	"sync/atomic"
 	"time"
+
+	"github.com/novox/mesh-controller/internal/builder"
 )
 
 // **The build agent says whether it is busy, and being asked drains it** (novox/hq ADR 0335 §1, §5). Its
@@ -73,14 +77,77 @@ func drainedTooLong(now time.Time) error {
 		"within %s (novox/hq ADR 0335)", began.UTC().Format(time.RFC3339), drainTooLong)
 }
 
+// inHand is true while this process has claimed a build and not yet released it. The mark in the temporary directory
+// is only believed while it is: a mark with no build of this process behind it is stale (a crash, a fault in an
+// earlier path) and is removed, because left alone it hands back every ask for ever (issue 1768).
+var inHand atomic.Bool
+
+// markRetry is how long an agent that cannot mark a build in hand takes no work, and markFault when it last failed to.
+// Taking nothing is the point: an ask fetched and handed back at once, many times a second, spends all its deliveries.
+const markRetry = 30 * time.Second
+
+var (
+	markMu    sync.Mutex
+	markFault time.Time
+	markSaid  string
+)
+
+// markFaulty says the agent could not mark a build in hand and has not yet been able to since: it takes no work. Once
+// markRetry has passed it tries the mark itself, with no ask in hand, so that an ask is fetched only when marking works.
+func markFaulty(now time.Time) bool {
+	markMu.Lock()
+	failed := markFault
+	markMu.Unlock()
+	if failed.IsZero() {
+		return false
+	}
+	if now.Sub(failed) < markRetry {
+		return true
+	}
+	f, err := os.OpenFile(inHandMark(), os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o644)
+	if err != nil && errors.Is(err, os.ErrExist) && !inHand.Load() {
+		_ = os.Remove(inHandMark())
+		f, err = os.OpenFile(inHandMark(), os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o644)
+	}
+	if err != nil {
+		markFailed(err)
+		return true
+	}
+	_ = f.Close()
+	_ = os.Remove(inHandMark())
+	markMu.Lock()
+	markFault, markSaid = time.Time{}, ""
+	markMu.Unlock()
+	fmt.Fprintf(os.Stderr, "the mark of a build in hand can be made again (%s): taking builds\n", inHandMark())
+	return false
+}
+
+// markFailed notes that a build could not be marked in hand, and says it when it is a new reason.
+func markFailed(err error) {
+	markMu.Lock()
+	defer markMu.Unlock()
+	markFault = time.Now()
+	if said := err.Error(); said != markSaid {
+		markSaid = said
+		fmt.Fprintf(os.Stderr, "cannot mark a build in hand (%s), so this agent takes no build for %s and tries again: %v\n",
+			inHandMark(), markRetry, err)
+	}
+}
+
 // claim marks a request in hand, unless the agent is drained: then nothing is in hand, and the request goes
 // back to the queue.
 func claim() bool {
+	if !inHand.Load() {
+		// Nothing of this process is in hand, so a mark already there is stale.
+		if err := os.Remove(inHandMark()); err == nil {
+			fmt.Fprintf(os.Stderr, "removed the mark of a build in hand (%s): no build of this agent is in hand\n", inHandMark())
+		}
+	}
 	// Made, never written over: one build at a time, and a mark already there is a build in hand.
 	f, err := os.OpenFile(inHandMark(), os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o644)
 	if err != nil {
 		// Unmarked, an ask would say idle while this build runs: the build is not taken.
-		fmt.Fprintf(os.Stderr, "cannot mark a build in hand (%s), so it is handed back: %v\n", inHandMark(), err)
+		markFailed(err)
 		return false
 	}
 	_, err = f.WriteString(time.Now().UTC().Format(time.RFC3339) + "\n")
@@ -89,7 +156,7 @@ func claim() bool {
 	}
 	if err != nil {
 		_ = os.Remove(inHandMark())
-		fmt.Fprintf(os.Stderr, "cannot mark a build in hand (%s), so it is handed back: %v\n", inHandMark(), err)
+		markFailed(err)
 		return false
 	}
 	if drained() {
@@ -97,6 +164,7 @@ func claim() bool {
 		fmt.Fprintln(os.Stderr, "asked whether busy, so this agent takes no new build: handed back")
 		return false
 	}
+	inHand.Store(true)
 	return true
 }
 
@@ -107,6 +175,7 @@ func holding(what string) {
 
 // released ends the build in hand.
 func released() {
+	inHand.Store(false)
 	if err := os.Remove(inHandMark()); err != nil && !errors.Is(err, os.ErrNotExist) {
 		fmt.Fprintf(os.Stderr, "cannot remove the mark of the build in hand (%s): %v\n", inHandMark(), err)
 	}
@@ -144,3 +213,23 @@ func busy() (string, error) {
 	}
 	return fmt.Sprintf("busy: %s, in hand since %s; taking no new build", what, since), nil
 }
+
+var (
+	roomMu   sync.Mutex
+	roomSaid bool
+)
+
+// noRoom says this node is under the floor of free space (novox/hq issue 1834): it takes no work, so another build node
+// takes the ask instead of this one taking it and ending it in an error. Said once when it starts and again when it ends.
+func noRoom(workspace string) bool {
+	err := builder.RoomToWork("/", workspace)
+	roomMu.Lock()
+	defer roomMu.Unlock()
+	if err != nil && !roomSaid {
+		fmt.Fprintf(os.Stderr, "taking no builds: %v\n", err)
+	} else if err == nil && roomSaid {
+		fmt.Fprintf(os.Stderr, "there is room again: taking builds\n")
+	}
+	roomSaid = err != nil
+	return err != nil
+}

cmd/mesh-builder/busy_test.go

@@ -1,6 +1,7 @@
 package main
 
 import (
+	"github.com/novox/mesh-controller/internal/builder"
 	"os"
 	"strings"
 	"sync"
@@ -160,3 +161,79 @@ func TestAnUnknownCommandFails(t *testing.T) {
 		t.Fatalf("help failed: %v", err)
 	}
 }
+
+// 1768/AC2: a mark naming no build of this agent (left by a crash or a fault) is stale: the next ask removes it and is
+// run, never fetched and handed back in a loop.
+func TestAStaleInHandMarkIsRemovedAndTheAskRuns(t *testing.T) {
+	t.Setenv("TMPDIR", t.TempDir())
+	inHand.Store(false)
+	if err := undrained(); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(inHandMark(), []byte("2026-10-21T18:45:06Z\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if !claim() {
+		t.Fatal("a stale in-hand mark made the agent hand back an ask")
+	}
+	// A live one — this agent's own build in hand — is never taken over.
+	if claim() {
+		t.Fatal("a second build was taken while one is in hand")
+	}
+	if _, err := busy(); err != nil {
+		t.Fatalf("the build in hand was lost: %v", err)
+	}
+	released()
+}
+
+// 1768/AC3: an agent that cannot mark a build in hand for another reason takes no work, instead of fetching asks and
+// handing them back; it takes work again once marking works.
+func TestAnAgentThatCannotMarkABuildTakesNoWorkUntilItCan(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("TMPDIR", dir)
+	inHand.Store(false)
+	markFault, markSaid = time.Time{}, ""
+	t.Cleanup(func() { markFault, markSaid = time.Time{}, "" })
+	if err := undrained(); err != nil {
+		t.Fatal(err)
+	}
+	// The mark's place is a directory that cannot be removed or made over: a directory named as the mark.
+	if err := os.MkdirAll(inHandMark()+"/x", 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if claim() {
+		t.Fatal("an agent that cannot mark a build took it")
+	}
+	if !markFaulty(time.Now()) {
+		t.Fatal("an agent that cannot mark a build still takes work")
+	}
+	// Still failing after the retry time: still takes nothing, and no ask was needed to find out.
+	if !markFaulty(time.Now().Add(2 * markRetry)) {
+		t.Fatal("an agent whose mark still cannot be made takes work")
+	}
+	if err := os.RemoveAll(inHandMark()); err != nil {
+		t.Fatal(err)
+	}
+	if markFaulty(time.Now().Add(4 * markRetry)) {
+		t.Fatal("an agent whose mark can be made again takes no work")
+	}
+	if !claim() {
+		t.Fatal("an agent that can mark takes no build")
+	}
+	released()
+}
+
+// 1834/AC4: given a node under the floor of free space, when the taking loop asks, then it takes nothing, and takes again
+// once there is room.
+func TestANodeUnderTheFloorOfFreeSpaceTakesNoWork(t *testing.T) {
+	was := builder.FreeBytes
+	t.Cleanup(func() { builder.FreeBytes = was })
+	builder.FreeBytes = func(string) (uint64, error) { return 2 << 30, nil }
+	if !noRoom(t.TempDir()) {
+		t.Error("a node with 2 GiB free took work")
+	}
+	builder.FreeBytes = func(string) (uint64, error) { return 200 << 30, nil }
+	if noRoom(t.TempDir()) {
+		t.Error("a node with 200 GiB free refused work")
+	}
+}

cmd/mesh-builder/check_spec_test.go

@@ -36,3 +36,17 @@ func TestTheSiblingsAnAskNamesReachTheSpecAndTheOutcome(t *testing.T) {
 		t.Fatalf("a request that names none has siblings %+v", plain.Siblings)
 	}
 }
+
+// 1826/AC2: the held values a check request carries reach the spec; a request that carries none leaves it empty.
+func TestTheHeldValuesAnAskCarriesReachTheSpec(t *testing.T) {
+	spec := checkSpecOf(link.BuildRequest{Check: &link.CheckRequest{Owner: "novox", Repo: "mesh-catalog",
+		HeldConfig: []link.HeldConfig{{Pull: "novox/mesh-catalog#434", Head: "a", Node: "ace", Module: "n8n", Key: "media-gid",
+			Value: []byte("2000"), Approved: "the operator"}}}})
+	if len(spec.Held) != 1 || spec.Held[0].Node != "ace" || spec.Held[0].Key != "media-gid" || string(spec.Held[0].Value) != "2000" ||
+		spec.Held[0].Approved != "the operator" {
+		t.Fatalf("the spec reads %+v", spec.Held)
+	}
+	if plain := checkSpecOf(link.BuildRequest{Check: &link.CheckRequest{Owner: "o", Repo: "r"}}); plain.Held != nil {
+		t.Fatalf("a request that carries none has %+v", plain.Held)
+	}
+}

cmd/mesh-builder/holder_test.go

@@ -91,7 +91,7 @@ func TestKillEndsTheBuildRunningHereAndNoOther(t *testing.T) {
 		t.Errorf("kill said %q", said)
 	}
 	// Removed at the kill and again once the build had ended: a container made in between is caught.
-	if len(removed) != 4 || !strings.Contains(removed[0], "label=mesh.build=build-1") || !strings.Contains(removed[2], "label=mesh.build=build-1") {
+	if len(removed) != 6 || !strings.Contains(removed[0], "label=mesh.build=build-1") || !strings.Contains(removed[3], "label=mesh.build=build-1") {
 		t.Errorf("removed %v", removed)
 	}
 	if c := h.current(); c.Running != nil {
@@ -160,7 +160,7 @@ func TestAHolderStartingRemovesWhatEarlierBuildsLeftHere(t *testing.T) {
 		}
 		return "", nil
 	}
-	if n := h.removeLeftBehind(); n != 2 || len(removed) != 2 || removed[1] != "docker rm -f c1 c2" {
+	if n := h.removeLeftBehind(); n != 2 || len(removed) != 3 || removed[2] != "docker rm -f -v c1 c2" {
 		t.Fatalf("removed %d: %v", n, removed)
 	}
 	h.remove = func(context.Context, string, string, ...string) (string, error) {

cmd/mesh-builder/main.go

@@ -64,6 +64,8 @@ is dialled except the broker.
   MESH_NPM_TOKEN     the token for it, likewise
   MESH_NPM_SCOPE     the scope it answers for (default: @novox)
   MESH_WORKSPACE     where to clone and build (default: a temporary directory)
+  MESH_BUILD_CGROUP_PARENT  the slice every container a build or check starts joins, which carries the
+                     machine's limits on builds (novox/hq issue 1798; default: the runtime's own)
 
 It also builds one module and stops, which is how a mesh is raised — before there is a
 broker to take work from or a registry to publish into:
@@ -137,6 +139,10 @@ func run() error {
 	if err != nil {
 		return err
 	}
+	// A build and a check run below the machine's own work (novox/hq issue 1798): the agent itself at the
+	// lowest priority, which its git and go children inherit, and every container in the build slice.
+	_ = syscall.Setpriority(syscall.PRIO_PROCESS, 0, 19)
+	builder.CgroupParent = strings.TrimSpace(os.Getenv("MESH_BUILD_CGROUP_PARENT"))
 	workspace := os.Getenv("MESH_WORKSPACE")
 	if workspace == "" {
 		workspace = os.TempDir() + "/mesh-builder"
@@ -184,7 +190,7 @@ func run() error {
 	// Paused or drained, it takes nothing new (novox/hq ADR 0219, ADR 0335): a drained agent finishes the build
 	// in hand and then says idle, and its container is replaced between builds.
 	machine := link.MachineOverNATSWith(js, on, seat, link.MachineOptions{
-		Paused: func() bool { return h.Paused() || drained() },
+		Paused: func() bool { return h.Paused() || drained() || markFaulty(time.Now()) || noRoom(workspace) },
 		Taking: func() { taking(seat) },
 		Claim:  claim,
 	})
@@ -499,6 +505,10 @@ func checkSpecOf(request link.BuildRequest) builder.CheckSpec {
 		Modules: c.Modules, New: c.New, Manifests: c.Manifests, Judge: c.Judge, Base: c.Base,
 		Toolchain: builder.ToolchainOf(request.Held), Toolchains: builder.ToolchainsOf(request.Held),
 		Tests: c.Tests, StoreOnly: c.StoreOnly, SiblingsUnknown: c.SiblingsUnknown}
+	for _, h := range c.HeldConfig {
+		spec.Held = append(spec.Held, builder.HeldValue{Pull: h.Pull, Head: h.Head, Node: h.Node, Module: h.Module, Key: h.Key,
+			Value: h.Value, Approved: h.Approved, By: h.By, At: h.At})
+	}
 	for _, s := range c.Siblings {
 		spec.Siblings = append(spec.Siblings, builder.Sibling{Repository: s.Repository, Number: s.Number, Head: s.Head,
 			Base: s.Base, Dir: s.Dir})

cmd/mesh-controller/asker.go

@@ -645,6 +645,10 @@ func doesWords(act conditions.Action) string {
 		return "the delivery is stopped"
 	case act.Verb == broker.ControllerSeat+".plans" && act.Arguments["retry"] != "":
 		return "the failed builds are asked again"
+	case act.Verb == broker.ControllerSeat+".push" && act.Arguments["node"] != "":
+		return "the held builds are sent to " + act.Arguments["node"]
+	case act.Verb == broker.ControllerSeat+".upgrade" && act.Arguments["release-backlog"] != "":
+		return "the builds held after the failed delivery are released"
 	case strings.HasSuffix(act.Verb, ".restart"):
 		return "its service is restarted on " + act.Machine
 	}

cmd/mesh-controller/batches.go

@@ -800,6 +800,9 @@ type keptMerge struct {
 	// FirstBuild says the merge is a first merge into a repository the mesh builds nothing from, kept to ask the first
 	// build of its modules once mesh-delivery's word on it is kept (novox/hq ADR 0432, issue 1146).
 	FirstBuild bool `json:"first_build,omitempty"`
+	// Held says which first builds of the merge were refused for a word the running build-agent does not read: the merge
+	// waits for a build-agent that reads them, and is never failed (novox/hq ADR 0482 §5, issue 1173).
+	Held []heldFirstBuild `json:"held,omitempty"`
 }
 
 // announcedOf is a kept merge as the forge announced it, and what it moved; empty where the record says none.

cmd/mesh-controller/checks.go

@@ -191,6 +191,16 @@ func (f following) pullUpdated(ctx context.Context, p link.PullUpdated, w io.Wri
 		scope.Modules, scope.Dependents, scope.New, scope.Manifests = nil, nil, nil, nil
 		composedGate(&direct)
 	}
+	// **Mesh-config is told what the head declares at every announced head of a pull request in a repository that holds
+	// modules** (novox/hq ADR 0502 clauses 2 and 6, issue 1826), also when the head touches no module: a head that reverts
+	// the change must drop the value held for it. Asked of nothing else here.
+	this := pullAtOf(p)
+	if this.Truncated {
+		this.Paths, this.Truncated = truncatedPaths(entries, p.Owner, p.Repo, scope.Modules), false
+	}
+	if scope.gated() || holdsModules(entries, p.Owner, p.Repo) {
+		tellPullDeclares(ctx, w, []pullAt{this})
+	}
 	switch {
 	case !scope.gated() && !scope.Mesh:
 		fmt.Fprintf(w, "%s/%s#%d (%.8s): %s, and the repository is not the mesh's: said, nothing run\n",
@@ -209,6 +219,9 @@ func (f following) pullUpdated(ctx context.Context, p link.PullUpdated, w io.Wri
 	}
 	request.Check.Plan = &plan
 	request.Check.Composed = composed
+	if !composed {
+		carryHeld(ctx, w, &request, []pullAt{this})
+	}
 	// **The group's other open pull requests are read beside it** (novox/hq ADR 0382 §1).
 	siblingsFrom(&request, p, entries, lines, groupsErr)
 	seat := buildSeatHeld(ctx)
@@ -594,11 +607,13 @@ func checkedOf(result link.BuildResult) link.Checked {
 		// A delivery group's composed check (novox/hq ADR 0239): every head it judged, this one first.
 		if g := result.Checked; g.Group != "" {
 			c.Group = g.Group
+			// Every member is named with its trunk commit (novox/hq issue 1106): the seat's word, else the one the forge
+			// announced with the head, so the forge's merge tool never meets a member whose verdict names none.
 			c.Members = append(c.Members, link.CheckedMember{Owner: g.Owner, Repo: g.Repo, Number: g.Number,
-				Commit: result.Ref, Trunk: c.Trunk})
+				Commit: result.Ref, Trunk: firstTrunk(c.Trunk, g.Trunk)})
 			for _, m := range g.Members {
 				c.Members = append(c.Members, link.CheckedMember{Owner: m.Owner, Repo: m.Repo, Number: m.Number,
-					Commit: m.Ref, Trunk: memberTrunk(result.Check, m)})
+					Commit: m.Ref, Trunk: firstTrunk(memberTrunk(result.Check, m), m.Trunk)})
 			}
 		}
 	}
@@ -627,6 +642,16 @@ func checkedOf(result link.BuildResult) link.Checked {
 	return c
 }
 
+// firstTrunk is the first trunk commit named, as twelve characters; empty when none is.
+func firstTrunk(named ...string) string {
+	for _, n := range named {
+		if n != "" {
+			return twelve(n)
+		}
+	}
+	return ""
+}
+
 // memberTrunk is the trunk commit the build seat merged one of a group's heads into (novox/hq ADR 0323 §6), empty
 // when it said none.
 func memberTrunk(outcome *link.CheckOutcome, m link.GroupMember) string {

cmd/mesh-controller/checks_test.go

@@ -250,6 +250,31 @@ func TestAVerdictNamesTheTrunkCommitItJudged(t *testing.T) {
 	}
 }
 
+// **A group's composed verdict names every member's trunk commit** (novox/hq issue 1106): a member the build seat named no
+// trunk for (an SDK member whose base the seat did not merge, or a seat from before the rule) is named by the trunk the forge
+// announced with its head, and the primary the same, so the merge tool never reads "names no trunk commit" on a member
+// whose trunk did not move.
+func TestAGroupVerdictNamesEveryMembersTrunkTheSDKMemberToo(t *testing.T) {
+	group := &link.CheckRequest{Owner: "novox", Repo: "mesh-catalog", Number: 7, Base: "main", Group: "feat/x",
+		Trunk: "dddddddddddd0000",
+		Members: []link.GroupMember{
+			{Owner: "novox", Repo: "mesh-sdk", Number: 8, Ref: "cccccccccccc0000", Base: "main", Trunk: "eeeeeeeeeeee0000"},
+			{Owner: "novox", Repo: "mesh-host", Number: 9, Ref: "bbbbbbbbbbbb0000", Base: "main", Trunk: "ffffffffffff0000"}}}
+	c := checkedOf(link.BuildResult{ID: "g", Ref: "aaaaaaaaaaaa0000", Checked: group, Check: &link.CheckOutcome{
+		Verdict: "pass", Head: "aaaaaaaaaaaa", Gate: &link.CheckLayer{Verdict: "pass"},
+		Members: []link.CheckedMember{{Owner: "novox", Repo: "mesh-host", Commit: "bbbbbbbbbbbb", Trunk: "222222222222"}}}})
+	want := []string{"dddddddddddd", "eeeeeeeeeeee", "222222222222"}
+	if len(c.Members) != 3 {
+		t.Fatalf("the composed check names its members %+v", c.Members)
+	}
+	for i, m := range c.Members {
+		if m.Trunk != want[i] {
+			t.Fatalf("member %d (%s/%s) is named with trunk %q, want %q (the seat's word first, else the announced one): %+v",
+				i, m.Owner, m.Repo, m.Trunk, want[i], c.Members)
+		}
+	}
+}
+
 // **The merge made for a check is never registered** (novox/hq ADR 0323 §2): a build of it — a commit on no branch
 // of the forge — is refused, naming the trunk. The rule of ADR 0238 §1 stands unchanged; this holds it for the
 // merge commit a check makes.

cmd/mesh-controller/compose_sdk.go

@@ -239,7 +239,11 @@ func markUnresolvable(err error) error {
 // still names anything foreseen is refused, said, and never sent.
 func composeSend(ctx context.Context, open *stores, node string) (sendable, error) {
 	declared, _, err := composeSendValidated(ctx, open, node)
-	return declared, err
+	if err != nil {
+		return declared, err
+	}
+	// Never a declaration naming an image the store does not hold (novox/hq issue 1742): that module is left out.
+	return withoutMissingImages(ctx, open, node, declared), nil
 }
 
 // composeSendValidated is composeSend and what the node-engine's validator refuses of the declaration it composed, for the

cmd/mesh-controller/declared_packages_integration_test.go

@@ -0,0 +1,89 @@
+//go:build integration
+
+package main
+
+import (
+	"encoding/json"
+	"testing"
+
+	"git.novox.be/novox/mesh-sdk/go/catalogue"
+	"github.com/novox/mesh-controller/internal/inventory"
+)
+
+// 1840/AC5 (ADR 0507 §5): the source of the declared-packages mirror composes each node and names, for a package two modules
+// declare and one declared absent, the modules that declare it; the same records give the same bytes on a second pass, so
+// the mirror writes nothing; a node with no package has a key that says so.
+func TestTheDeclaredPackagesMirrorNamesWhatEachNodesModulesDeclare(t *testing.T) {
+	open := aMesh(t)
+	ctx := t.Context()
+	register(t, open, catalogue.Manifest{Module: "viewer", Version: "1", Resources: []map[string]any{
+		{"id": "pkg-curl", "type": "package", "package": "curl"},
+		{"id": "pkg-nano", "type": "package", "package": "nano", "absent": true}}})
+	register(t, open, catalogue.Manifest{Module: "fetcher", Version: "1", Resources: []map[string]any{
+		{"id": "pkg-curl", "type": "package", "package": "curl"}}})
+	for _, module := range []string{"viewer", "fetcher"} {
+		if _, err := assign(ctx, open, "anchor", module); err != nil {
+			t.Fatalf("assign anchor %s: %v", module, err)
+		}
+	}
+	source := declaredPackagesMirror(open)
+	first, err := source(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var got inventory.DeclaredPackagesMirrored
+	if err := json.Unmarshal(first["anchor"], &got); err != nil {
+		t.Fatalf("anchor has no value: %v", err)
+	}
+	// Every node also runs the mesh's own modules, which declare packages of their own: curl and nano are looked
+	// up by name, and no package names viewer or fetcher but those they declare.
+	byName := map[string]inventory.PackageDeclared{}
+	for _, p := range got.Packages {
+		byName[p.Package] = p
+	}
+	same := func(a, b []string) bool {
+		if len(a) != len(b) {
+			return false
+		}
+		for i := range a {
+			if a[i] != b[i] {
+				return false
+			}
+		}
+		return true
+	}
+	for _, p := range []inventory.PackageDeclared{{Package: "curl", Modules: []string{"fetcher", "viewer"}},
+		{Package: "nano", Modules: []string{"viewer"}, Absent: true}} {
+		if g, ok := byName[p.Package]; !ok || g.Absent != p.Absent || !same(g.Modules, p.Modules) {
+			t.Errorf("anchor declares %s as %+v, want %+v (all: %+v)", p.Package, g, p, got.Packages)
+		}
+	}
+	for _, p := range got.Packages {
+		if p.Package == "curl" || p.Package == "nano" {
+			continue
+		}
+		for _, m := range p.Modules {
+			if m == "viewer" || m == "fetcher" {
+				t.Errorf("%s is said to be declared by %s, which does not declare it", p.Package, m)
+			}
+		}
+	}
+	var laptop inventory.DeclaredPackagesMirrored
+	if err := json.Unmarshal(first["laptop"], &laptop); err != nil || laptop.Node != "laptop" || laptop.Packages == nil {
+		t.Errorf("a node assigned neither module has no value of its own: %s (%v)", first["laptop"], err)
+	}
+	for _, p := range laptop.Packages {
+		if p.Package == "curl" || p.Package == "nano" {
+			t.Errorf("laptop is assigned neither module and declares %+v", p)
+		}
+	}
+	second, err := source(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for node, value := range first {
+		if string(second[node]) != string(value) {
+			t.Errorf("the value of %s changed between two passes over the same records:\n%s\n%s", node, value, second[node])
+		}
+	}
+}

cmd/mesh-controller/delivery.go

@@ -1177,6 +1177,12 @@ func askGroupCheck(ctx context.Context, open *stores, group string, members []or
 		return "", err
 	}
 	request.Check.Group = group
+	// **The values held for the keys the members introduce are told and carried** (novox/hq ADR 0502, issue 1826).
+	var pulls []pullAt
+	for i, s := range changeSourcesOf(members, entries, reach) {
+		pulls = append(pulls, pullAt{changeSource: s, Number: members[i].pull().Number})
+	}
+	withHeldConfig(ctx, os.Stderr, &request, pulls, true)
 	// A group's check is queued as ready when any member's pull request is marked ready.
 	request.Check.Ready = slices.ContainsFunc(members, func(m orderMember) bool { return m.Ready })
 	world, err := restOfTheMesh(ctx, open, shelfOf(entries), "")
@@ -1204,7 +1210,7 @@ func askGroupCheck(ctx context.Context, open *stores, group string, members []or
 			return "", fmt.Errorf("%s cannot be cloned for the group's check: %w", m.ID, err)
 		}
 		request.Check.Members = append(request.Check.Members, link.GroupMember{Owner: mp.Owner, Repo: mp.Repo,
-			Number: mp.Number, Repository: url, Ref: mp.Commit, Paths: mp.Paths, Base: mp.Base})
+			Number: mp.Number, Repository: url, Ref: mp.Commit, Paths: mp.Paths, Base: mp.Base, Trunk: mp.BaseSHA})
 	}
 	seat := buildSeatHeld(ctx)
 	ask, err := askOverOn(seat)

cmd/mesh-controller/delivery_conditions.go

@@ -58,8 +58,17 @@ type stalledLine struct {
 	// Severity is "urgent" for a group held or half merged and a refused member (novox/hq issues 1275, 1278); empty
 	// or anything else is a warning, as before.
 	Severity string `json:"severity,omitempty"`
+	// Needs is "new-head" for a delivery whose cure is its author's new head (novox/hq ADR 0505 §5), Author that author
+	// as the operator reads it ("the author of feat/x", with the session that pushed it when its pull request names one)
+	// and Branch its branch. A mesh-delivery from before says none, and the words are as before.
+	Needs  string `json:"needs,omitempty"`
+	Author string `json:"author,omitempty"`
+	Branch string `json:"branch,omitempty"`
 }
 
+// needsNewHead is what a stalled line needs when its cure is its author's new head (ADR 0505 §5).
+const needsNewHead = "new-head"
+
 // severity is the condition's severity a stalled line asks: urgent when it says so, a warning otherwise.
 func (l stalledLine) severity() conditions.Severity {
 	if l.Severity == string(conditions.Urgent) {

cmd/mesh-controller/delivery_integration_test.go

@@ -59,6 +59,18 @@ func TestAMergeWaitsForItsDeliverysWordAndThePersonsWordWorksWithoutIt(t *testin
 		}
 	}
 
+	// heardOf has this mesh's own view of the plans take in the plan as the bucket holds it. A verb of the
+	// controller (deliveryCommand, plansCommand) opens an inventory of its own and writes the plan there; this
+	// mesh's inventory learns of the write from the bucket's watch, a moment later, and a loaded machine makes the
+	// moment long enough for advanceHeld to read the plan as it was, still waiting for its word, and ask nothing
+	// (issue 1399). Reading the plan from the bucket puts it into the view at once, with no wait to bound.
+	heardOf := func(id string) {
+		t.Helper()
+		if _, err := inv.PlanByID(ctx, id); err != nil {
+			t.Fatal(err)
+		}
+	}
+
 	// No holder on record: the merge starts its walk, as before.
 	p := merge("c1aaaaaaaa", "modules/app/index.ts")
 	if p.Waiting() || len(*asked) != 1 {
@@ -90,6 +102,7 @@ func TestAMergeWaitsForItsDeliverysWordAndThePersonsWordWorksWithoutIt(t *testin
 	if err := deliveryCommand(ctx, []string{"go", p.ID}); err == nil {
 		t.Fatal("a walk was let go twice")
 	}
+	heardOf(p.ID)
 	advanceHeld(ctx, open)
 	if len(*asked) != 2 {
 		t.Fatalf("the word did not start the walk: %v", *asked)
@@ -119,6 +132,7 @@ func TestAMergeWaitsForItsDeliverysWordAndThePersonsWordWorksWithoutIt(t *testin
 	if err := plansCommand(ctx, []string{"go", p.ID, "--why", "mesh-delivery is down"}); err != nil {
 		t.Fatal(err)
 	}
+	heardOf(p.ID)
 	advanceHeld(ctx, open)
 	got, _ = inv.PlanByID(ctx, p.ID)
 	if got.Waiting() || !strings.HasPrefix(got.Delivery.By, "a person") || len(*asked) < 4 {

cmd/mesh-controller/first_builds.go

@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"regexp"
 	"strings"
 	"time"
 
@@ -102,7 +103,7 @@ func (f following) resumeFirstBuilds(ctx context.Context, d deliveryMerge) error
 	}
 	for _, w := range waiting {
 		k := announcedOf(w)
-		if !k.FirstBuild || !strings.EqualFold(k.Owner+"/"+k.Repo, d.Owner+"/"+d.Repo) || k.Number != d.Number ||
+		if !k.FirstBuild || len(k.Held) > 0 || !strings.EqualFold(k.Owner+"/"+k.Repo, d.Owner+"/"+d.Repo) || k.Number != d.Number ||
 			k.HeadSHA != d.HeadSHA {
 			continue
 		}
@@ -172,12 +173,122 @@ func firstBuildsOf(ctx context.Context, inv catalogueReader, m link.SourceMoved,
 	return nil, "", err
 }
 
+// heldFirstBuild says a first build was refused because its manifest uses a word the running build-agent does not read,
+// and its merge is kept waiting for a build-agent that reads it (novox/hq ADR 0482 §5, issue 1173).
+type heldFirstBuild struct {
+	Module string    `json:"module"`
+	Path   string    `json:"path"`
+	Word   string    `json:"word"`
+	At     time.Time `json:"at"`
+}
+
+// judgeRefusedFirstBuild is the hold a first build's outcome puts its merge under: every module the merge holds already,
+// and this one, unless it is among them; nil unless the build failed on a word of its manifest the running build-agent
+// does not know, and was asked for a first merge, answered by the record of merges no plan answers or put back to waiting
+// by an earlier hold (a second refusal in one merge is held too, review of issue 1173).
+func judgeRefusedFirstBuild(result link.BuildResult, req inventory.BuildRequest, merge inventory.BatchedMerge) []heldFirstBuild {
+	word := refusedWord(result.Failed)
+	if word == "" || req.For != "merge" {
+		return nil
+	}
+	var held []heldFirstBuild
+	switch k := announcedOf(merge); {
+	case merge.Plan == inventory.WaitingRecord:
+		// Answered when its builds were asked: a hold from before (a build asked again) is over, and starts anew.
+	case merge.Plan == "" && len(k.Held) > 0:
+		held = k.Held
+	default:
+		return nil
+	}
+	this := heldFirstBuild{Module: req.Name(), Path: strings.Trim(req.Path, "/"), Word: word, At: time.Now().UTC()}
+	for i, h := range held {
+		if strings.Trim(h.Path, "/") == this.Path {
+			out := append([]heldFirstBuild(nil), held...)
+			out[i] = this
+			return out
+		}
+	}
+	return append(append([]heldFirstBuild(nil), held...), this)
+}
+
+// heldDirsOf is the directories a held merge asks again: its held modules' own, each once, "." for the repository's root.
+func heldDirsOf(k keptMerge) []string {
+	var dirs []string
+	seen := map[string]bool{}
+	for _, h := range k.Held {
+		dir := strings.Trim(h.Path, "/")
+		if dir == "" {
+			dir = "."
+		}
+		if !seen[dir] {
+			seen[dir] = true
+			dirs = append(dirs, dir)
+		}
+	}
+	return dirs
+}
+
+// unknownWord is how the strict reading of a manifest says a word is not one it knows: encoding/json's own words, which
+// the build-agent's answer carries whole. The build's answer has no typed field for it (Failed is the builder's words).
+var unknownWord = regexp.MustCompile(`json: unknown field "([^"]+)"`)
+
+// refusedWord is the word a build's failure says the reader did not know; empty when it says none.
+func refusedWord(failed string) string {
+	if m := unknownWord.FindStringSubmatch(failed); m != nil {
+		return m[1]
+	}
+	return ""
+}
+
+// holdRefusedFirstBuild keeps a first build's merge waiting when the build was refused for a word the running build-agent
+// does not read (novox/hq ADR 0482 §5, issue 1173): no failed build is recorded, nothing expires the merge, and it is
+// named by a condition until a delivery of build-agent asks the build again. Answers whether the outcome was dealt with.
+func holdRefusedFirstBuild(ctx context.Context, inv *inventory.Inventory, result link.BuildResult) (bool, error) {
+	if result.Failed == "" || refusedWord(result.Failed) == "" {
+		return false, nil
+	}
+	req, found, err := inv.BuildRequestByID(ctx, result.ID)
+	if err != nil || !found {
+		return false, err
+	}
+	merge, found, err := inv.MergeOf(ctx, req.Repository, req.Commit)
+	if err != nil || !found {
+		return false, err
+	}
+	held := judgeRefusedFirstBuild(result, req, merge)
+	if len(held) == 0 {
+		return false, nil
+	}
+	k := announcedOf(merge)
+	k.Held = held
+	event, err := json.Marshal(k)
+	if err != nil {
+		return false, err
+	}
+	if err := inv.HoldMerge(ctx, merge.Repository, merge.Commit, event); err != nil {
+		return false, err
+	}
+	this := held[len(held)-1]
+	for _, h := range held {
+		if h.Path == strings.Trim(req.Path, "/") {
+			this = h
+		}
+	}
+	fmt.Printf("%s: the first build of %s was refused for the word %q, which the running build-agent does not read; the "+
+		"merge %.8s of %s is kept waiting for a build-agent that reads it (holding %s), and the build is asked again when "+
+		"one is delivered\n", result.ID, this.Module, this.Word, merge.Commit, merge.Repository, heldNames(held))
+	return true, nil
+}
+
 // probeFirstBuildsID is the probe that reads the first merges waiting for mesh-delivery's word.
 const probeFirstBuildsID = "D18"
 
 // kindFirstBuildUnasked is what a first merge waiting too long for mesh-delivery's word raises.
 const kindFirstBuildUnasked = "first-build-unasked"
 
+// kindFirstBuildHeld is what a first merge held for a build-agent that reads its manifest raises.
+const kindFirstBuildHeld = "first-build-held"
+
 // firstBuildWaitBound is how long a first merge waits for mesh-delivery's announcement of the operator's Approve before
 // it is said: a bound in the sense of ADR 0426 §3, not a delay. Nothing waits on it: the word's arrival asks the builds
 // at once, and the merge is said, never dropped, once it is past this (issue 1146).
@@ -189,6 +300,10 @@ func firstBuildObservations(waiting []inventory.BatchedMerge, now time.Time) []c
 	var out []conditions.Observation
 	for _, w := range waiting {
 		k := announcedOf(w)
+		if len(k.Held) > 0 {
+			out = append(out, heldFirstBuildObservation(k))
+			continue
+		}
 		if !k.FirstBuild || now.Sub(w.Heard) <= firstBuildWaitBound {
 			continue
 		}
@@ -211,6 +326,37 @@ func firstBuildObservations(waiting []inventory.BatchedMerge, now time.Time) []c
 	return out
 }
 
+// heldNames is the modules a merge holds, each with the word it waits for: "watchman (key-ttl), view (per-machine)".
+func heldNames(held []heldFirstBuild) string {
+	names := make([]string, 0, len(held))
+	for _, h := range held {
+		names = append(names, fmt.Sprintf("%s (%q)", h.Module, h.Word))
+	}
+	return strings.Join(names, ", ")
+}
+
+// heldFirstBuildObservation names a first merge held for a build-agent that reads its manifests: at once, since nothing
+// is lost and nothing times out, but the operator can see what the merge waits for. One condition names every module held.
+func heldFirstBuildObservation(k keptMerge) conditions.Observation {
+	repository := k.Owner + "/" + k.Repo
+	modules := make([]string, 0, len(k.Held))
+	for _, h := range k.Held {
+		modules = append(modules, h.Module)
+	}
+	held := heldNames(k.Held)
+	return conditions.Observation{Scope: conditions.ScopeMerge, ID: fmt.Sprintf("%s_%.8s", repository, k.Commit),
+		Kind: kindFirstBuildHeld, Severity: conditions.Warning,
+		Summary: fmt.Sprintf("the merge %.8s of %s adds modules whose manifests use words the running build-agent does not "+
+			"read: %s; the merge waits for a build-agent that reads them", k.Commit, repository, held),
+		Said:     fmt.Sprintf("%s at %s waits for a build-agent that reads the words of %s", repository, k.Commit, held),
+		Headline: fmt.Sprintf("The first build of %s waits for a newer build-agent", strings.Join(modules, ", ")),
+		Explanation: fmt.Sprintf("The merge %.8s into %s adds modules whose manifests use words the build-agent now "+
+			"running does not know: %s. The merge is kept, not failed: their first builds are asked again when a delivery "+
+			"of build-agent ends.", k.Commit, repository, held),
+		Resolved: "a delivery of build-agent ends and the first builds register the modules, or a hand `build` does",
+	}
+}
+
 // probeFirstBuilds is D18: no first merge waits past its bound for mesh-delivery's word unsaid.
 func probeFirstBuilds(ctx context.Context, d *doctor) ([]conditions.Observation, error) {
 	waiting, err := d.open.inventory.WaitingMerges(ctx)
@@ -219,3 +365,61 @@ func probeFirstBuilds(ctx context.Context, d *doctor) ([]conditions.Observation,
 	}
 	return firstBuildObservations(waiting, time.Now().UTC()), nil
 }
+
+// askHeldFirstBuildsAgain asks again the first build of each first merge held for a build-agent that reads its manifest,
+// when the plan that ended delivered build-agent (novox/hq issue 1173): once for each end, since the ask answers the merge
+// and a refusal that comes again holds it anew. Answers how many merges it asked for.
+func askHeldFirstBuildsAgain(ctx context.Context, open *stores, p inventory.Plan) int {
+	if !deliversBuildAgent(p) {
+		return 0
+	}
+	actingOnMerges.Lock()
+	defer actingOnMerges.Unlock()
+	inv := open.inventory
+	waiting, err := inv.WaitingMerges(ctx)
+	if err != nil {
+		fmt.Printf("%s delivered build-agent, and the first merges held for it could not be read: %v\n", p.ID, err)
+		return 0
+	}
+	asked := 0
+	for _, w := range waiting {
+		k := announcedOf(w)
+		if len(k.Held) == 0 {
+			continue
+		}
+		// Its own held modules, not the rule of a first merge: a module of the merge that passed is registered by now,
+		// and the repository no longer counts as one the mesh builds nothing from (review of issue 1173).
+		why, err := approvedAnnounced(ctx, inv, k.Owner, k.Repo, keptMerge{SourceMoved: k.SourceMoved})
+		if err != nil {
+			fmt.Printf("%s delivered build-agent, and the merge %.8s of %s held for it asks no build now (%v): it stays "+
+				"waiting\n", p.ID, w.Commit, w.Repository, err)
+			continue
+		}
+		dirs := heldDirsOf(k)
+		fmt.Printf("%s delivered build-agent: the first builds of %s are asked again\n", p.ID, heldNames(k.Held))
+		paths := make([]string, 0, len(dirs))
+		for _, dir := range dirs {
+			if dir == "." {
+				dir = ""
+			}
+			paths = append(paths, dir)
+		}
+		repository := k.Owner + "/" + k.Repo
+		askBuilds(withFirstBuildWarrant(ctx, repository, paths, why), inv, k.SourceMoved,
+			buildSource{Repository: repository, Seat: gitSeat}, dirs)
+		// Answered: it no longer waits, so this end asks nothing twice; a refusal that comes again holds it anew.
+		if err := inv.AnswerMerge(ctx, w.Repository, w.Commit, inventory.WaitingRecord, false); err != nil {
+			fmt.Printf("  and the merge could not be marked answered: %v\n", err)
+			continue
+		}
+		asked++
+	}
+	return asked
+}
+
+// deliversBuildAgent says a delivery plan ended delivered with build-agent built in it: the reader a held first build
+// waits for is the one now running.
+func deliversBuildAgent(p inventory.Plan) bool {
+	m := p.Modules["build-agent"]
+	return p.WalkSaid == inventory.WalkEnded && p.Outcome() == inventory.WalkDelivered && m != nil && m.State == "built"
+}

cmd/mesh-controller/first_builds_held_integration_test.go

@@ -0,0 +1,221 @@
+//go:build integration
+
+package main
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"testing"
+	"time"
+
+	"git.novox.be/novox/mesh-sdk/go/asks"
+	"github.com/novox/mesh-controller/internal/inventory"
+	"github.com/novox/mesh-controller/internal/link"
+)
+
+// 1173/AC1, 1173/AC3 whole against the store: a first merge's build refused for a word the running build-agent does not
+// read keeps the merge waiting with no failed build recorded; a delivery plan that does not deliver build-agent asks
+// nothing; the one that ends delivering it asks the first build again once, and its pass registers the module.
+func TestAHeldFirstMergeIsAskedAgainWhenABuildAgentIsDelivered(t *testing.T) {
+	const head, commit = "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1", "0177ea7a00000000"
+	open := aMesh(t)
+	ctx := t.Context()
+	inv := open.inventory
+
+	a := aDeliveryMergeOf(t, head, map[string]string{"novox/mesh-delivery@a1a1a1a1a1a1": head})
+	wasKept, wasAsk, realAsk := keptDeliveryMerge, routerAskOf, askABuild
+	keptDeliveryMerge = func(context.Context, string, string, int, string) (deliveryMerge, bool, error) {
+		return a.merge, true, nil
+	}
+	routerAskOf = func(context.Context, catalogueReader, string, string) (*asks.Ask, *asks.Warrant, error) {
+		return &a.ask, &a.warrant, nil
+	}
+	var asked []string
+	askABuild = func(_ context.Context, source buildSource, path, ref string) (string, error) {
+		id := "build-" + string(rune('1'+len(asked)))
+		asked = append(asked, id)
+		return id, nil
+	}
+	t.Cleanup(func() { keptDeliveryMerge, routerAskOf, askABuild = wasKept, wasAsk, realAsk })
+
+	m := link.SourceMoved{Owner: "novox", Repo: "mesh-delivery", Base: "main", HeadSHA: head, Commit: commit, Number: 7,
+		MergedAt: time.Now().Add(-time.Hour).UTC().Format(time.RFC3339Nano), Paths: []string{"module.json", "main.go"},
+		ModuleDirs: []string{"."}, ModuleDirsSaid: true}
+	if err := (following{open: open}).SourceMoved(ctx, m); err != nil {
+		t.Fatal(err)
+	}
+	if len(asked) != 1 {
+		t.Fatalf("1173/AC3: the first merge asked %v, want the one first build", asked)
+	}
+
+	// The running build-agent refuses the manifest's word.
+	refused := onTrunk("build-1", "novox/mesh-delivery", "git", "", nil)
+	refused.Failed, refused.Manifest, refused.Commit = refusedKeyTTL, nil, commit
+	if err := (builds{inv: inv, open: open}).Built(ctx, refused); err != nil {
+		t.Fatal(err)
+	}
+	if _, recorded, _ := inv.BuildByID(ctx, "build-1"); recorded {
+		t.Fatal("1173/AC1: a refused first build was recorded as a failed build")
+	}
+	waiting, err := inv.WaitingMerges(ctx)
+	if err != nil || len(waiting) != 1 || len(announcedOf(waiting[0]).Held) == 0 {
+		t.Fatalf("1173/AC1: the merges waiting are %+v (%v), want the first merge, held", waiting, err)
+	}
+	if obs := firstBuildObservations(waiting, time.Now()); len(obs) != 1 || obs[0].Kind != kindFirstBuildHeld {
+		t.Fatalf("1173/AC2: the held merge is named by %+v", obs)
+	}
+
+	// A plan that ended without delivering build-agent asks nothing; one that delivered it asks once.
+	other := inventory.Plan{ID: "p1", State: inventory.PlanDone, WalkSaid: inventory.WalkEnded,
+		Modules: map[string]*inventory.PlanModule{"mesh-delivery": {State: "built"}}}
+	if n := askHeldFirstBuildsAgain(ctx, open, other); n != 0 || len(asked) != 1 {
+		t.Fatalf("1173/AC3: a plan that delivered no build-agent asked %d builds again (%v)", n, asked)
+	}
+	delivered := inventory.Plan{ID: "p2", State: inventory.PlanDone, WalkSaid: inventory.WalkEnded,
+		Modules: map[string]*inventory.PlanModule{"build-agent": {State: "built"}}}
+	if n := askHeldFirstBuildsAgain(ctx, open, delivered); n != 1 || len(asked) != 2 {
+		t.Fatalf("1173/AC3: the plan that delivered build-agent asked %d builds again (%v), want one", n, asked)
+	}
+	if n := askHeldFirstBuildsAgain(ctx, open, delivered); n != 0 || len(asked) != 2 {
+		t.Fatalf("1173/AC3: the same end asked again: %d (%v)", n, asked)
+	}
+
+	// Its pass registers the module.
+	pass := onTrunk("build-2", "novox/mesh-delivery", "git", "", map[string]any{"module": "mesh-delivery-watchman", "version": "1"})
+	pass.Commit = commit
+	if err := (builds{inv: inv, open: open}).Built(ctx, pass); err != nil {
+		t.Fatal(err)
+	}
+	if _, known := inventoryHolds(t, inv, "mesh-delivery-watchman"); !known {
+		t.Fatal("1173/AC3: the module is not registered after the first build passed")
+	}
+}
+
+// aTwoModuleFirstMerge is a first merge into novox/mesh-delivery adding the modules watchman and view, made on the
+// operator's Approve of its head, whose first builds are asked; asked says the build id asked for each path, in order.
+func aTwoModuleFirstMerge(t *testing.T, open *stores, commit string) *[][2]string {
+	t.Helper()
+	const head = "b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2"
+	a := aDeliveryMergeOf(t, head, map[string]string{"novox/mesh-delivery@b2b2b2b2b2b2": head})
+	wasKept, wasAsk, realAsk := keptDeliveryMerge, routerAskOf, askABuild
+	keptDeliveryMerge = func(context.Context, string, string, int, string) (deliveryMerge, bool, error) {
+		return a.merge, true, nil
+	}
+	routerAskOf = func(context.Context, catalogueReader, string, string) (*asks.Ask, *asks.Warrant, error) {
+		return &a.ask, &a.warrant, nil
+	}
+	asked := &[][2]string{}
+	askABuild = func(_ context.Context, _ buildSource, path, _ string) (string, error) {
+		id := fmt.Sprintf("build-%d", len(*asked)+1)
+		*asked = append(*asked, [2]string{path, id})
+		return id, nil
+	}
+	t.Cleanup(func() { keptDeliveryMerge, routerAskOf, askABuild = wasKept, wasAsk, realAsk })
+	m := link.SourceMoved{Owner: "novox", Repo: "mesh-delivery", Base: "main", HeadSHA: head, Commit: commit, Number: 7,
+		MergedAt:   time.Now().Add(-time.Hour).UTC().Format(time.RFC3339Nano),
+		Paths:      []string{"view/module.json", "view/main.go", "watchman/module.json", "watchman/main.go"},
+		ModuleDirs: []string{"view", "watchman"}, ModuleDirsSaid: true}
+	if err := (following{open: open}).SourceMoved(t.Context(), m); err != nil {
+		t.Fatal(err)
+	}
+	if len(*asked) != 2 {
+		t.Fatalf("the first merge asked %v, want the two first builds", *asked)
+	}
+	return asked
+}
+
+// idOf is the build asked last for path.
+func idOf(t *testing.T, asked [][2]string, path string) string {
+	t.Helper()
+	for i := len(asked) - 1; i >= 0; i-- {
+		if asked[i][0] == path {
+			return asked[i][1]
+		}
+	}
+	t.Fatalf("no build asked for %s: %v", path, asked)
+	return ""
+}
+
+// built hands the controller a build's outcome: refused for the word, or passing as module.
+func built(t *testing.T, open *stores, id, path, commit, refusedFor, module string) {
+	t.Helper()
+	r := onTrunk(id, "novox/mesh-delivery", "git", path, map[string]any{"module": module, "version": "1"})
+	r.Commit = commit
+	if refusedFor != "" {
+		r.Failed, r.Manifest = `this is not a module manifest: json: unknown field "`+refusedFor+`"`, nil
+	}
+	if err := (builds{inv: open.inventory, open: open}).Built(t.Context(), r); err != nil {
+		t.Fatal(err)
+	}
+}
+
+var buildAgentDelivered = inventory.Plan{ID: "p-ba", State: inventory.PlanDone, WalkSaid: inventory.WalkEnded,
+	Modules: map[string]*inventory.PlanModule{"build-agent": {State: "built"}}}
+
+// 1173/AC3 (review round 1, item 1): in a first merge of two modules where view passes and watchman is refused, the
+// held watchman is asked again when build-agent is delivered, though the repository builds view by then.
+func TestAHeldModuleIsAskedAgainAfterItsSiblingRegistered(t *testing.T) {
+	const commit = "0177ea7b00000000"
+	open := aMesh(t)
+	ctx := t.Context()
+	asked := aTwoModuleFirstMerge(t, open, commit)
+
+	built(t, open, idOf(t, *asked, "view"), "view", commit, "", "mesh-delivery-view")
+	if _, known := inventoryHolds(t, open.inventory, "mesh-delivery-view"); !known {
+		t.Fatal("view is not registered after its first build passed")
+	}
+	refused := idOf(t, *asked, "watchman")
+	built(t, open, refused, "watchman", commit, "key-ttl", "")
+	if _, recorded, _ := open.inventory.BuildByID(ctx, refused); recorded {
+		t.Fatal("1173/AC1: the refused first build of watchman was recorded as a failed build")
+	}
+	waiting, err := open.inventory.WaitingMerges(ctx)
+	if err != nil || len(waiting) != 1 || len(announcedOf(waiting[0]).Held) != 1 {
+		t.Fatalf("1173/AC1: the merges waiting are %+v (%v), want the first merge, holding watchman", waiting, err)
+	}
+
+	if n := askHeldFirstBuildsAgain(ctx, open, buildAgentDelivered); n != 1 || len(*asked) != 3 || (*asked)[2][0] != "watchman" {
+		t.Fatalf("1173/AC3: the delivery of build-agent asked %d merges again (%v), want watchman's first build alone", n, *asked)
+	}
+	built(t, open, idOf(t, *asked, "watchman"), "watchman", commit, "", "mesh-delivery-watchman")
+	if _, known := inventoryHolds(t, open.inventory, "mesh-delivery-watchman"); !known {
+		t.Fatal("1173/AC3: watchman is not registered after the first build asked again passed")
+	}
+}
+
+// 1173/AC1, AC2, AC3 (review round 1, item 2): in a first merge of two modules both refused, neither is recorded as a
+// failed build, the condition names both, and the delivery of build-agent asks both again.
+func TestTwoRefusedModulesOfOneFirstMergeAreBothHeld(t *testing.T) {
+	const commit = "0177ea7c00000000"
+	open := aMesh(t)
+	ctx := t.Context()
+	asked := aTwoModuleFirstMerge(t, open, commit)
+
+	for _, path := range []string{"watchman", "view"} {
+		id := idOf(t, *asked, path)
+		built(t, open, id, path, commit, "key-ttl", "")
+		if _, recorded, _ := open.inventory.BuildByID(ctx, id); recorded {
+			t.Fatalf("1173/AC1: the refused first build of %s was recorded as a failed build", path)
+		}
+	}
+	waiting, err := open.inventory.WaitingMerges(ctx)
+	if err != nil || len(waiting) != 1 || len(announcedOf(waiting[0]).Held) != 2 {
+		t.Fatalf("1173/AC1: the merges waiting are %+v (%v), want the first merge, holding both", waiting, err)
+	}
+	obs := firstBuildObservations(waiting, time.Now())
+	if len(obs) != 1 || !strings.Contains(obs[0].Summary, "watchman") || !strings.Contains(obs[0].Summary, "view") {
+		t.Fatalf("1173/AC2: the held merge is named by %+v, want one condition naming both", obs)
+	}
+
+	if n := askHeldFirstBuildsAgain(ctx, open, buildAgentDelivered); n != 1 || len(*asked) != 4 {
+		t.Fatalf("1173/AC3: the delivery of build-agent asked %d merges again (%v), want both first builds", n, *asked)
+	}
+	built(t, open, idOf(t, *asked, "watchman"), "watchman", commit, "", "mesh-delivery-watchman")
+	built(t, open, idOf(t, *asked, "view"), "view", commit, "", "mesh-delivery-view")
+	for _, module := range []string{"mesh-delivery-watchman", "mesh-delivery-view"} {
+		if _, known := inventoryHolds(t, open.inventory, module); !known {
+			t.Fatalf("1173/AC3: %s is not registered after the first build asked again passed", module)
+		}
+	}
+}

cmd/mesh-controller/first_builds_held_test.go

@@ -0,0 +1,141 @@
+package main
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/novox/mesh-controller/internal/conditions"
+	"github.com/novox/mesh-controller/internal/inventory"
+	"github.com/novox/mesh-controller/internal/link"
+)
+
+const refusedKeyTTL = `this is not a module manifest: a state is either a name or {name, history, ttl-seconds, per-machine}: ` +
+	`json: unknown field "key-ttl"`
+
+// aFirstMergeAnswered is a first merge as askFirstBuilds leaves it: answered by the record of merges no plan answers.
+func aFirstMergeAnswered() (inventory.BuildRequest, inventory.BatchedMerge) {
+	req := inventory.BuildRequest{ID: "build-1", Repository: "novox/mesh-delivery", Seat: "git", Path: "watchman", Ref: "main",
+		Commit: "0177ea7a00", For: "merge"}
+	event, _ := json.Marshal(keptMerge{SourceMoved: link.SourceMoved{Owner: "novox", Repo: "mesh-delivery", Base: "main",
+		Commit: "0177ea7a00", Number: 3, HeadSHA: "a1a1a1a1a1a1"}, FirstBuild: true})
+	return req, inventory.BatchedMerge{Repository: "novox/mesh-delivery", Branch: "main", Commit: "0177ea7a00",
+		Plan: inventory.WaitingRecord, Event: event}
+}
+
+// 1173/AC1: a first build refused for a word its manifest uses and the running build-agent does not know holds its merge.
+func TestAFirstBuildRefusedForAnUnknownWordHoldsItsMerge(t *testing.T) {
+	req, merge := aFirstMergeAnswered()
+	held := judgeRefusedFirstBuild(link.BuildResult{ID: "build-1", Failed: refusedKeyTTL}, req, merge)
+	if len(held) != 1 || held[0].Word != "key-ttl" || held[0].Module != "watchman" || held[0].Path != "watchman" {
+		t.Fatalf("1173/AC1: a first build refused for \"key-ttl\" is judged %+v, want a hold on that word for watchman", held)
+	}
+}
+
+// 1173/AC2: a held first merge is named at once by one condition: the merge, the module, the word and what it waits for.
+func TestAHeldFirstMergeIsNamedByACondition(t *testing.T) {
+	now := time.Date(2026, 10, 22, 14, 0, 0, 0, time.UTC)
+	_, merge := aFirstMergeAnswered()
+	var k keptMerge
+	_ = json.Unmarshal(merge.Event, &k)
+	k.Held = []heldFirstBuild{{Module: "watchman", Path: "watchman", Word: "key-ttl", At: now},
+		{Module: "view", Path: "view", Word: "per-machine", At: now}}
+	merge.Event, _ = json.Marshal(k)
+	merge.Heard = now.Add(-time.Second)
+	got := firstBuildObservations([]inventory.BatchedMerge{merge}, now)
+	if len(got) != 1 {
+		t.Fatalf("1173/AC2: %d conditions for a held first merge, want one: %+v", len(got), got)
+	}
+	o := got[0]
+	if o.Kind != kindFirstBuildHeld || o.Scope != conditions.ScopeMerge {
+		t.Fatalf("1173/AC2: the condition is %+v", o)
+	}
+	for _, want := range []string{"0177ea7a", "watchman", "key-ttl", "view", "per-machine", "build-agent"} {
+		if !strings.Contains(o.Summary, want) {
+			t.Fatalf("1173/AC2: the summary %q does not name %q", o.Summary, want)
+		}
+	}
+}
+
+// 1173/AC4: a first build that fails for any other reason is not held.
+func TestAFirstBuildFailingForAnyOtherReasonIsNotHeld(t *testing.T) {
+	req, merge := aFirstMergeAnswered()
+	if judgeRefusedFirstBuild(link.BuildResult{Failed: refusedKeyTTL}, req, merge) == nil {
+		t.Fatal("1173/AC4: the control, a refusal for an unknown word, is not held")
+	}
+	for _, c := range []struct {
+		what   string
+		failed string
+		change func(*inventory.BuildRequest, *inventory.BatchedMerge)
+	}{
+		{what: "a compile error", failed: "main.go:3: undefined: foo"},
+		{what: "no failure", failed: ""},
+		{what: "a missing field", failed: `json: cannot unmarshal string into Go struct field`},
+		{what: "a build a person asked", failed: refusedKeyTTL, change: func(r *inventory.BuildRequest, _ *inventory.BatchedMerge) { r.For = "build" }},
+		{what: "a merge a plan answers", failed: refusedKeyTTL, change: func(_ *inventory.BuildRequest, m *inventory.BatchedMerge) { m.Plan = "plan-7" }},
+		{what: "a waiting merge held for nothing", failed: refusedKeyTTL, change: func(_ *inventory.BuildRequest, m *inventory.BatchedMerge) { m.Plan = "" }},
+	} {
+		r, m := req, merge
+		if c.change != nil {
+			c.change(&r, &m)
+		}
+		if held := judgeRefusedFirstBuild(link.BuildResult{Failed: c.failed}, r, m); held != nil {
+			t.Fatalf("1173/AC4: %s is held: %+v", c.what, held)
+		}
+	}
+}
+
+// 1173/AC1, AC2 (review round 1, item 2): a second refusal in a merge already held is held too, its module added to the
+// hold, so no failed build is recorded and the condition names both.
+func TestASecondRefusalInAHeldMergeIsAddedToTheHold(t *testing.T) {
+	req, merge := aFirstMergeAnswered()
+	first := judgeRefusedFirstBuild(link.BuildResult{Failed: refusedKeyTTL}, req, merge)
+	k := announcedOf(merge)
+	k.Held = first
+	merge.Event, _ = json.Marshal(k)
+	merge.Plan = "" // HoldMerge put it back to waiting
+	req.ID, req.Path = "build-2", "view"
+	held := judgeRefusedFirstBuild(link.BuildResult{Failed: `json: unknown field "per-machine"`}, req, merge)
+	if len(held) != 2 || held[0].Module != "watchman" || held[1].Module != "view" || held[1].Word != "per-machine" {
+		t.Fatalf("1173/AC1: the second refusal in a held merge is judged %+v, want watchman and view held", held)
+	}
+	// The same module refused again is held once.
+	k.Held = held
+	merge.Event, _ = json.Marshal(k)
+	if again := judgeRefusedFirstBuild(link.BuildResult{Failed: refusedKeyTTL}, req, merge); len(again) != 2 {
+		t.Fatalf("1173/AC1: view refused again is held as %+v, want it once", again)
+	}
+}
+
+// 1173/AC3 (review round 1, item 1): a held merge is asked again for its own held modules' directories, not by the rule of
+// a first merge, which finds nothing once another module of the repository is registered.
+func TestAHeldMergeIsAskedAgainForItsHeldModulesAlone(t *testing.T) {
+	k := keptMerge{Held: []heldFirstBuild{{Module: "watchman", Path: "watchman"}, {Module: "mesh-delivery", Path: ""},
+		{Module: "watchman", Path: "/watchman/"}}}
+	if got := heldDirsOf(k); strings.Join(got, ",") != "watchman,." {
+		t.Fatalf("1173/AC3: a held merge asks again %v, want watchman and the root once each", got)
+	}
+}
+
+// 1173/AC3 (the part that needs no store): only a plan that ended delivered with build-agent built in it is the end a held
+// first build waits for.
+func TestOnlyADeliveredPlanOfBuildAgentIsWhatAHeldFirstBuildWaitsFor(t *testing.T) {
+	plan := func(state, walk string, modules map[string]*inventory.PlanModule) inventory.Plan {
+		return inventory.Plan{ID: "p", State: state, WalkSaid: walk, Modules: modules}
+	}
+	built := map[string]*inventory.PlanModule{"build-agent": {State: "built"}}
+	if !deliversBuildAgent(plan(inventory.PlanDone, inventory.WalkEnded, built)) {
+		t.Fatal("1173/AC3: a plan that delivered build-agent is not the end a held first build waits for")
+	}
+	for what, p := range map[string]inventory.Plan{
+		"a plan still running":  plan(inventory.PlanBuilding, "", built),
+		"a plan that failed":    plan(inventory.PlanFailed, inventory.WalkEnded, built),
+		"a failed build-agent":  plan(inventory.PlanDone, inventory.WalkEnded, map[string]*inventory.PlanModule{"build-agent": {State: "failed"}}),
+		"another module's plan": plan(inventory.PlanDone, inventory.WalkEnded, map[string]*inventory.PlanModule{"mailu": {State: "built"}}),
+	} {
+		if deliversBuildAgent(p) {
+			t.Fatalf("1173/AC3: %s is the end a held first build waits for", what)
+		}
+	}
+}

cmd/mesh-controller/forge_wait_test.go

@@ -68,7 +68,7 @@ func TestTheForgeNotAnsweringInTimeIsNotAskedAgain(t *testing.T) {
 // An ask that hangs past the bound is cut off at the bound, not at its own wait, and the failure still says it
 // waited: the receive loop is held no longer than the bound (novox/hq issue 486).
 func TestAnAskHangingPastTheBoundIsCutOffAtIt(t *testing.T) {
-	w := waitOut{bound: 200 * time.Millisecond, first: 10 * time.Millisecond, most: 50 * time.Millisecond,
+	w := waitOut{bound: 100 * time.Millisecond, first: 10 * time.Millisecond, most: 50 * time.Millisecond,
 		now: time.Now, sleep: sleepOrDone}
 	asked := 0
 	began := time.Now()

cmd/mesh-controller/held_moves.go

@@ -0,0 +1,198 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"sort"
+	"strings"
+
+	"github.com/novox/mesh-controller/internal/conditions"
+	"github.com/novox/mesh-controller/internal/inventory"
+)
+
+// A move held for a person is asked of the person (novox/hq issue 1732, issue 1320; ADR 0377, ADR 0259).
+//
+// **A wait only a person can end is said to that person at once.** ADR 0377 holds a recorded module's move that
+// recreates a container or touches its data until a person pushes the machine. The walk said so in its note and
+// ended "done", `status` named the machine behind, and nobody was asked: on 2026-10-21 mailu's new build waited on
+// novox for 40 minutes behind a plan that read "done, 3 tier(s)", and on 2026-10-19 mssql waited on ace the same way.
+// Row S24 raises one condition per machine that has such a move, for the operator, with the answer **Release**: the
+// push of that machine, which the controller's own `push` verb performs on the operator's warrant (ADR 0259). It ends
+// when the machine no longer waits, whoever pushed it.
+//
+// A hold a person chose is not asked again — a module they set to `record` with a why, and the bus, whose step has
+// its own row (S17).
+
+// kindMovesHeld is S24's kind: machine.<node>.moves-held.
+const kindMovesHeld = "moves-held"
+
+// heldFacts is one machine and the moves of recorded modules that wait there for a person.
+type heldFacts struct {
+	node  string
+	moves []heldMove
+}
+
+// gatherHeldMoves is, per machine that holds at least one move no person chose to hold, all its held moves, by machine.
+func gatherHeldMoves(ctx context.Context, inv *inventory.Inventory) ([]heldFacts, error) {
+	nodes, err := inv.Nodes(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("the machines cannot be read: %w", err)
+	}
+	f, err := readMoveFacts(ctx, inv)
+	if err != nil {
+		return nil, err
+	}
+	var out []heldFacts
+	for _, n := range nodes {
+		moves, err := heldMovesOn(ctx, inv, f, n.Name)
+		if err != nil {
+			return nil, err
+		}
+		h := heldFacts{node: n.Name, moves: moves}
+		if len(h.asked()) > 0 {
+			out = append(out, h)
+		}
+	}
+	return out, nil
+}
+
+// asked are the moves no person chose to hold, and chosen the ones a person did (a module set to record with a why, the bus).
+func (h heldFacts) asked() []heldMove  { return h.byChoice(false) }
+func (h heldFacts) chosen() []heldMove { return h.byChoice(true) }
+
+func (h heldFacts) byChoice(chosen bool) []heldMove {
+	var out []heldMove
+	for _, m := range h.moves {
+		if m.Chosen == chosen {
+			out = append(out, m)
+		}
+	}
+	return out
+}
+
+// modules are the held moves' modules, in order, of all of them.
+func (h heldFacts) modules() []string { return moduleNames(h.moves) }
+
+func moduleNames(moves []heldMove) []string {
+	out := make([]string, 0, len(moves))
+	for _, m := range moves {
+		out = append(out, m.Module)
+	}
+	return out
+}
+
+// releaseAction is the one answer a held move offers: the push of the machine, approved by the operator. The push
+// names every module whose move waits there as one that may move its data: the operator's Approve is the word
+// ADR 0217 asks for, and the ask says so. Offered only where no person's own hold is on the machine too: a push
+// composes every recorded module at its current build, so it would send that move as well, which the ask never named
+// (ADR 0259 §6), and hold the whole machine if that module's data would move.
+func (h heldFacts) releaseAction() conditions.Action {
+	return conditions.Action{Label: "Release", Verb: "mesh-controller.push", Level: conditions.LevelApprove,
+		Arguments: map[string]string{"node": h.node, "move": strings.Join(moduleNames(h.asked()), ","), "why": "",
+			"cause": conditions.CauseOperatorAnswer}}
+}
+
+// heldWords are the plain words of a machine's held moves: which modules wait, why in general, and what an Approve does.
+func heldWords(h heldFacts) (headline, explanation, needs string, resolved string) {
+	names := namesWords(moduleNames(h.asked()), 3)
+	headline = clipWords(conditions.Capital(names)+" waits for you on "+h.node, conditions.HeadlineMax)
+	recreates, data := false, false
+	for _, m := range h.asked() {
+		switch {
+		case strings.Contains(m.Why, "recreates"):
+			recreates = true
+		default:
+			data = true
+		}
+	}
+	why := "would change what it runs"
+	switch {
+	case recreates && data:
+		why = "would restart a container or touch its data"
+	case recreates:
+		why = "would restart one of its containers"
+	case data:
+		why = "would touch its files or data"
+	}
+	explanation = clipWords(fmt.Sprintf("The new version of %s %s on %s, so it does not go out with its delivery; "+
+		"it waits for you. Release sends %s everything it is owed, these among it, and lets their data move where it "+
+		"has to. Nothing is sent until you answer.", names, why, h.node, h.node), conditions.ExplanationMax)
+	needs = "release them " + FromMeshMCPServer
+	if chosen := h.chosen(); len(chosen) > 0 {
+		// A push of the machine would send the move a person chose to hold as well: no answer is offered here.
+		explanation = clipWords(fmt.Sprintf("The new version of %s %s on %s, so it does not go out with its delivery; "+
+			"it waits for you. %s is also held there by your own choice, and a push of %s would send that too, so "+
+			"nothing is offered here: the push is yours at the controller's terminal.",
+			names, why, h.node, conditions.Capital(namesWords(moduleNames(chosen), 3)), h.node), conditions.ExplanationMax)
+		needs = fmt.Sprintf("push %s at the controller's terminal, once you have decided about %s.", h.node,
+			namesWords(moduleNames(chosen), 3))
+	}
+	resolved = "Resolved: " + names + " is no longer waiting on " + h.node
+	return
+}
+
+// watchMovesHeld is S24: a machine that has moves of recorded modules waiting for a person, said to the operator with the
+// answer that sends them. The condition ends when the machine no longer waits: it is no longer among the facts.
+func watchMovesHeld(f *signalFacts) []conditions.Observation {
+	var out []conditions.Observation
+	for _, h := range f.held {
+		var said []string
+		for _, m := range h.moves {
+			said = append(said, fmt.Sprintf("%s %s → %s %s", m.Module, short(m.From), short(m.To), m.Why))
+		}
+		headline, explanation, needs, resolved := heldWords(h)
+		if c := h.chosen(); len(c) > 0 {
+			said = append(said, "held by a person's own choice: "+strings.Join(moduleNames(c), ", "))
+		}
+		var actions []conditions.Action
+		if len(h.chosen()) == 0 {
+			actions = []conditions.Action{h.releaseAction()}
+		}
+		out = append(out, conditions.Observation{Scope: conditions.ScopeMachine, ID: h.node, Kind: kindMovesHeld,
+			Machine: h.node, Severity: conditions.Warning, Resolver: conditions.ResolverOperator,
+			Summary: fmt.Sprintf("%s has %d move(s) of recorded modules waiting for a person's push: %s — `push %s` sends them",
+				h.node, len(h.moves), strings.Join(h.modules(), ", "), h.node),
+			Said:     strings.Join(said, "; "),
+			Headline: headline, Explanation: explanation, Needs: needs, Resolved: resolved,
+			Actions: actions})
+	}
+	return out
+}
+
+// planHeld is, for a plan that ended or is running, the moves its modules carried that a machine still holds for a
+// person: "module on machine", sorted. The plan's own record says the move waited when it was judged
+// (PlanModule.Recorded); the machines say whether it still does, and for the build this plan carried, so a plan older
+// than the build now held is not named.
+func planHeld(p inventory.Plan, held []heldFacts) []string {
+	var out []string
+	for _, h := range held {
+		for _, m := range h.moves {
+			s := p.Modules[m.Module]
+			if s == nil || !strings.HasPrefix(s.Recorded[h.node], "waits:") || !sameCommit(s.Commit, m.To) {
+				continue
+			}
+			out = append(out, m.Module+" on "+h.node)
+		}
+	}
+	sort.Strings(out)
+	return out
+}
+
+// heldSaid is what a plan's line adds when it carries a move that a machine holds for a person (novox/hq issue 1732): a
+// plan whose module waits for a push is not plainly "done".
+func heldSaid(p inventory.Plan, held []heldFacts) string {
+	waiting := planHeld(p, held)
+	if len(waiting) == 0 {
+		return ""
+	}
+	return fmt.Sprintf(" — %d held for a person: %s (the operator is asked)", len(waiting), strings.Join(waiting, ", "))
+}
+
+// heldNow reads the machines' held moves for a plan's line, nil when they cannot be read: the line then reads as before.
+func heldNow(ctx context.Context, inv *inventory.Inventory) []heldFacts {
+	held, err := gatherHeldMoves(ctx, inv)
+	if err != nil {
+		return nil // empty-on-error: a plan's line then reads as it did before; the watchdog (S24) says it cannot read
+	}
+	return held
+}

cmd/mesh-controller/held_moves_integration_test.go

@@ -0,0 +1,92 @@
+//go:build integration
+
+package main
+
+import (
+	"context"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/novox/mesh-controller/internal/inventory"
+)
+
+func inventoryUpgrade(why string) inventory.Upgrade { return inventory.Upgrade{Why: why, By: "jochen"} }
+
+func mustMoveFacts(t *testing.T, rm *recordedMesh) moveFacts {
+	t.Helper()
+	f, err := readMoveFacts(t.Context(), rm.open.inventory)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return f
+}
+
+// 1732/AC8 (integration): a mesh running mailu at c1 on two machines, whose registered c2 recreates a container, is read
+// as two machines each holding mailu's move for a person; a bundle-only c3 on top changes nothing of it; after a machine
+// is sent c2 (as a push records it) it is no longer among them, and plans that carried c2 say nothing more of it.
+func TestMachinesHoldingAMoveForAPersonAreReadFromTheRecords(t *testing.T) {
+	rm := aRecordedMesh(t, aMailu(true))
+	c2 := aMailu(true)
+	resourceOf(&c2, "imap")["image"] = "registry.invalid/imap@sha256:2"
+	rm.register(t, c2, "c2", time.Now().Add(-time.Minute))
+	ctx := t.Context()
+	held, err := gatherHeldMoves(ctx, rm.open.inventory)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(held) != 2 || held[0].node != "anchor" || held[1].node != "laptop" || len(held[0].moves) != 1 ||
+		held[0].moves[0].Module != "mailu" || held[0].moves[0].To != "c2" || !strings.Contains(held[0].moves[0].Why, "recreates") {
+		t.Fatalf("held %+v", held)
+	}
+	if err := rm.open.inventory.RecordSent(ctx, nodeID(t, rm.open, "anchor"), "d-anchor-c2", map[string]string{"mailu": "c2"}); err != nil {
+		t.Fatal(err)
+	}
+	held, err = gatherHeldMoves(ctx, rm.open.inventory)
+	if err != nil || len(held) != 1 || held[0].node != "laptop" {
+		t.Fatalf("after anchor was sent c2: %+v (%v)", held, err)
+	}
+}
+
+// 1732/AC9 (integration): a module a person set to record is no ask: they chose the hold.
+func TestAHoldAPersonChoseIsNotAsked(t *testing.T) {
+	rm := aRecordedMesh(t, aMailu(false))
+	c2 := aMailu(false)
+	c2.Bundles[0].Digest = "sha256:bbb"
+	rm.register(t, c2, "c2", time.Now().Add(-time.Minute))
+	if err := rm.open.inventory.SetUpgradeOf(t.Context(), "mailu", inventoryUpgrade("the migration week")); err != nil {
+		t.Fatal(err)
+	}
+	held, err := gatherHeldMoves(t.Context(), rm.open.inventory)
+	if err != nil || len(held) != 0 {
+		t.Fatalf("a machine holding only a person's own hold is asked: %+v (%v)", held, err)
+	}
+	if moves, _ := heldMovesOn(t.Context(), rm.open.inventory, mustMoveFacts(t, rm), "anchor"); len(moves) != 1 || !moves[0].Chosen {
+		t.Fatalf("status still names it, marked as chosen: %+v", moves)
+	}
+}
+
+// 1742/AC4 (integration): a registered build naming an image of the store that the store lacks is read as a missing
+// image on each machine that runs the module; one the store holds is not; and what the store holds is not asked twice.
+func TestARegisteredBuildNamingAnImageTheStoreLacksIsRead(t *testing.T) {
+	m := aMailu(true)
+	resourceOf(&m, "imap")["image"] = "artifact-store://mailu/imap@sha256:" + strings.Repeat("e", 64)
+	rm := aRecordedMesh(t, m)
+	asked := 0
+	lacking := func(_ context.Context, reference string) (bool, error) { asked++; return false, nil }
+	imagesHeld.Lock()
+	imagesHeld.held = map[string]bool{}
+	imagesHeld.Unlock()
+	got, err := gatherMissingImages(t.Context(), rm.open.inventory, lacking)
+	if err != nil || len(got) != 2 || got[0].Module != "mailu" || got[0].Node != "anchor" || got[1].Node != "laptop" {
+		t.Fatalf("missing %+v (%v)", got, err)
+	}
+	holding := func(_ context.Context, reference string) (bool, error) { asked++; return true, nil }
+	if got, err := gatherMissingImages(t.Context(), rm.open.inventory, holding); err != nil || len(got) != 0 {
+		t.Fatalf("an image the store holds is missing: %+v (%v)", got, err)
+	}
+	before := asked
+	if _, err := gatherMissingImages(t.Context(), rm.open.inventory, lacking); err != nil || asked != before {
+		t.Fatalf("an image the store was found to hold was asked about again (%d, %v)", asked-before, err)
+	}
+}

cmd/mesh-controller/held_moves_test.go

@@ -0,0 +1,237 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+	"time"
+
+	"git.novox.be/novox/mesh-sdk/go/asks"
+	"github.com/novox/mesh-controller/internal/broker"
+	"github.com/novox/mesh-controller/internal/conditions"
+	"github.com/novox/mesh-controller/internal/inventory"
+)
+
+// **A move held for a person is asked of the person** (novox/hq issue 1732, issue 1320; ADR 0377, ADR 0259).
+
+// aHeldMailu is novox holding mailu's new build because it would recreate a container: the walk's own words.
+func aHeldMailu() heldFacts {
+	return heldFacts{node: "novox", moves: []heldMove{{Module: "mailu", From: "b2f5ebb2aaaa", To: "3259765dbbbb",
+		Why: "waits: recreates 1 of mailu's 12 container(s) (with a new image: automx)"}}}
+}
+
+func heldConditionOn(f *signalFacts) conditions.Condition {
+	o := watchMovesHeld(f)[0]
+	return conditions.Condition{Key: o.Key(), Kind: o.Kind, Severity: o.Severity, Headline: o.Headline,
+		Explanation: conditions.Verdict(o.Needs, o.Explanation), Needs: o.Needs, Actions: o.Actions}
+}
+
+// 1732/AC1: a machine holding a move of a recorded module for a person raises one condition for the operator, with
+// Release as its only answer: the machine's push, approved, naming the modules whose moves wait there.
+func TestAHeldMoveIsRaisedWithReleaseAsItsOnlyAction(t *testing.T) {
+	f := calm(time.Date(2026, 10, 21, 17, 30, 0, 0, time.UTC))
+	f.held = []heldFacts{aHeldMailu()}
+	got := watchMovesHeld(f)
+	if len(got) != 1 {
+		t.Fatalf("%+v", got)
+	}
+	o := got[0]
+	if o.Kind != "moves-held" || o.Scope != conditions.ScopeMachine || o.ID != "novox" || o.Severity != conditions.Warning ||
+		o.Resolver != conditions.ResolverOperator || o.Key() != "machine.novox.moves-held" {
+		t.Fatalf("kind, scope, subject, severity or resolver: %+v (%s)", o, o.Key())
+	}
+	if len(o.Actions) != 1 {
+		t.Fatalf("actions: %+v", o.Actions)
+	}
+	a := o.Actions[0]
+	if a.Label != "Release" || a.Verb != "mesh-controller.push" || a.Level != conditions.LevelApprove ||
+		a.Arguments["node"] != "novox" || a.Arguments["move"] != "mailu" || a.Arguments["cause"] != conditions.CauseOperatorAnswer {
+		t.Fatalf("the action is not the push of novox: %+v", a)
+	}
+	if _, takes := a.Arguments["why"]; !takes {
+		t.Fatal("the push takes a why, which the asker fills in with the operator's answer")
+	}
+	for _, want := range []string{"mailu", "novox"} {
+		if !strings.Contains(o.Headline+o.Explanation, want) {
+			t.Errorf("the words do not name %q: %q / %q", want, o.Headline, o.Explanation)
+		}
+	}
+	if !strings.Contains(o.Said, "recreates 1 of mailu's 12") {
+		t.Errorf("the evidence does not carry the walk's own words: %q", o.Said)
+	}
+	if w := (conditions.Observation{Headline: o.Headline, Explanation: o.Explanation, Needs: o.Needs, Resolved: o.Resolved}); w.Headline == "" || len(o.Headline) > conditions.HeadlineMax {
+		t.Errorf("headline: %q", o.Headline)
+	}
+}
+
+// 1732/AC2: a machine with nothing held raises nothing, so the condition ends the look after the move is sent.
+func TestAMachineHoldingNothingRaisesNoHeldMoveCondition(t *testing.T) {
+	f := calm(time.Date(2026, 10, 21, 17, 30, 0, 0, time.UTC))
+	if got := watchMovesHeld(f); len(got) != 0 {
+		t.Fatalf("%+v", got)
+	}
+}
+
+// 1732/AC3: the condition is asked on a channel at the approve level in words that say what Release does, and the
+// operator's warrant calls the controller's own push with the machine and the modules, once.
+func TestAHeldMovesReleaseIsAskedAndAWarrantPushesTheMachine(t *testing.T) {
+	f := calm(time.Date(2026, 10, 21, 17, 30, 0, 0, time.UTC))
+	f.held = []heldFacts{aHeldMailu()}
+	c := heldConditionOn(f)
+	r := newAskerRig(t)
+	r.open = []conditions.Condition{c}
+	if err := r.a.reconcile(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	sent := r.asksSent(t)
+	if len(sent) != 1 || len(sent[0].Options) != 1 {
+		t.Fatalf("asked %+v", sent)
+	}
+	o := sent[0].Options[0]
+	if o.Label != "Release" || o.Level != asks.Approve || o.Does != "the held builds are sent to novox" {
+		t.Errorf("the option is %+v", o)
+	}
+	if err := sent[0].Check(r.now); err != nil {
+		t.Errorf("the ask is refused as made: %v", err)
+	}
+	w := r.warrantFor(t, c.Key, "Release")
+	answerWith(t, r, w)
+	answerWith(t, r, w)
+	if len(r.called) != 1 || !strings.HasPrefix(r.called[0], "mesh-controller.push@ ") ||
+		!strings.Contains(r.called[0], `"node":"novox"`) || !strings.Contains(r.called[0], `"move":"mailu"`) ||
+		!strings.Contains(r.called[0], `"cause":"`+conditions.CauseOperatorAnswer+`"`) ||
+		!strings.Contains(r.called[0], "chose Release") {
+		t.Fatalf("called %v", r.called)
+	}
+}
+
+// 1732/AC4: the controller may call its own push and upgrade verbs on a warrant: the grant names them.
+func TestTheControllerMayActOnAWarrantForPushAndUpgrade(t *testing.T) {
+	for _, verb := range []string{"push", "upgrade"} {
+		granted := false
+		for _, v := range broker.VerbsTheControllerActsOnAWarrant {
+			granted = granted || (v.Seat == broker.ControllerSeat && v.Verb == verb)
+		}
+		if !granted {
+			t.Errorf("the controller may not act on a warrant for %s", verb)
+		}
+	}
+}
+
+func aDoneMailuPlan() inventory.Plan {
+	return inventory.Plan{ID: "plan-1792585970446304628", Repository: "novox/mesh-catalog", State: inventory.PlanDone,
+		Tiers: [][]string{{"a"}, {"b"}, {"mailu"}},
+		Modules: map[string]*inventory.PlanModule{"mailu": {State: "built", Commit: "3259765dbbbbcccc",
+			Recorded: map[string]string{"novox": "waits: recreates 1 of mailu's 12 container(s)"}}}}
+}
+
+// 1732/AC5: a done plan that carries a move a machine still holds for a person says so on its line; once the machine
+// no longer holds it, or holds another build of the module, the line says nothing more.
+func TestADonePlanSaysWhatItHoldsForAPerson(t *testing.T) {
+	p := aDoneMailuPlan()
+	line := planLine(p, time.Date(2026, 10, 21, 16, 0, 0, 0, time.UTC)) + heldSaid(p, []heldFacts{aHeldMailu()})
+	if !strings.Contains(line, "done, 3 tier(s)") || !strings.Contains(line, "1 held for a person: mailu on novox") {
+		t.Errorf("the line: %q", line)
+	}
+	if said := heldSaid(p, nil); said != "" {
+		t.Errorf("a plan whose moves were sent says %q", said)
+	}
+	other := aHeldMailu()
+	other.moves[0].To = "9999999ffff"
+	if said := heldSaid(p, []heldFacts{other}); said != "" {
+		t.Errorf("a plan older than the build now held says %q", said)
+	}
+	p.Modules["mailu"].Recorded = map[string]string{"novox": recordedRollsWhy}
+	if said := heldSaid(p, []heldFacts{aHeldMailu()}); said != "" {
+		t.Errorf("a move the plan sent says %q", said)
+	}
+}
+
+// 1732/AC6: the builds held after a failed release are asked of the operator: the held-release condition offers
+// Release, which calls the controller's own `upgrade` with release-backlog and nothing else, once, on a warrant.
+func TestTheBuildsHeldAfterAFailedReleaseAreAskedAndReleasedOnAWarrant(t *testing.T) {
+	saved := backlogNow
+	t.Cleanup(func() { backlogNow = saved })
+	backlogNow.held = "release-1792595552499982311 failed (failed on novox); what waits is released again by a person"
+	backlogNow.waiting = map[string][]inventory.CarriedMove{"novox": {{Module: "indexer"}, {Module: "nextcloud"}}}
+	got := backlogObservation()
+	if len(got) != 1 || len(got[0].Actions) != 1 {
+		t.Fatalf("raised %+v", got)
+	}
+	a := got[0].Actions[0]
+	if a.Label != "Release" || a.Verb != "mesh-controller.upgrade" || a.Level != conditions.LevelApprove ||
+		a.Arguments["release-backlog"] != "true" || a.Arguments["cause"] != conditions.CauseOperatorAnswer {
+		t.Fatalf("the action: %+v", a)
+	}
+	o := got[0]
+	c := conditions.Condition{Key: o.Key(), Kind: o.Kind, Severity: o.Severity, Headline: o.Headline,
+		Explanation: conditions.Verdict(o.Needs, o.Explanation), Needs: o.Needs, Actions: o.Actions}
+	r := newAskerRig(t)
+	r.open = []conditions.Condition{c}
+	if err := r.a.reconcile(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	sent := r.asksSent(t)
+	if len(sent) != 1 || len(sent[0].Options) != 1 || sent[0].Options[0].Does != "the builds held after the failed delivery are released" {
+		t.Fatalf("asked %+v", sent)
+	}
+	w := r.warrantFor(t, c.Key, "Release")
+	answerWith(t, r, w)
+	answerWith(t, r, w)
+	if len(r.called) != 1 || !strings.HasPrefix(r.called[0], "mesh-controller.upgrade@ ") ||
+		!strings.Contains(r.called[0], `"release-backlog":"true"`) || !strings.Contains(r.called[0], "chose Release") {
+		t.Fatalf("called %v", r.called)
+	}
+}
+
+// 1732/AC7: a plan whose send waits for a gate while the builds are held after a failed release reads as waiting for
+// a person to release them, not "building ... LATE"; with nothing held it still reads as the wait it is.
+func TestAPlanWaitingForAGateBehindAFailedReleaseIsNotLate(t *testing.T) {
+	saved := backlogNow
+	t.Cleanup(func() { backlogNow = saved })
+	now := time.Date(2026, 10, 21, 18, 50, 0, 0, time.UTC)
+	p := inventory.Plan{ID: "plan-1", Repository: "novox/mesh-sdk", Commit: "c0ffee00", State: inventory.PlanBuilding,
+		Tiers: [][]string{{"indexer"}}, TierEntered: now.Add(-100 * time.Minute), Created: now.Add(-110 * time.Minute),
+		Modules: map[string]*inventory.PlanModule{"indexer": {State: "built"}},
+		Note:    refusalNote(0, errors.New("a build waits there for its gate: novox"))}
+	backlogNow.held = ""
+	if line := planLine(p, now); !strings.Contains(line, "a build waits there for its gate: novox") {
+		t.Errorf("the wait is not said: %q", line)
+	}
+	backlogNow.held = "release-1 failed (failed on novox); what waits is released again by a person"
+	line := planLine(p, now)
+	if strings.Contains(line, "LATE") || strings.Contains(line, "building") ||
+		!strings.Contains(line, "until a person releases it") {
+		t.Errorf("a plan held behind a failed release reads %q", line)
+	}
+}
+
+// 1732/AC10: a machine that also holds a move a person chose to hold gets no Release, since a push would send that move
+// too; the condition names both and says the push is the controller's terminal. A machine with only asked moves keeps it.
+func TestAMachineAlsoHoldingAPersonsOwnHoldIsOfferedNoRelease(t *testing.T) {
+	f := calm(time.Date(2026, 10, 21, 17, 30, 0, 0, time.UTC))
+	h := aHeldMailu()
+	h.moves = append(h.moves, heldMove{Module: "nftables", From: "n1aaaa", To: "n2bbbb",
+		Why: "waits: a person set it to record, and holds every move of it until they push", Chosen: true})
+	f.held = []heldFacts{h}
+	got := watchMovesHeld(f)
+	if len(got) != 1 || len(got[0].Actions) != 0 {
+		t.Fatalf("%+v", got)
+	}
+	o := got[0]
+	text := o.Headline + o.Explanation + o.Needs + o.Summary + o.Said
+	for _, want := range []string{"mailu", "nftables", "terminal", "push novox"} {
+		if !strings.Contains(text, want) {
+			t.Errorf("does not say %q: %q", want, text)
+		}
+	}
+	w := conditions.Words{Headline: o.Headline, Explanation: o.Explanation, Resolved: o.Resolved, Needs: o.Needs}
+	if why, ok := conditions.PlainWords(w, "novox"); !ok {
+		t.Errorf("not plain: %s", why)
+	}
+	f.held = []heldFacts{aHeldMailu()}
+	if got := watchMovesHeld(f); len(got) != 1 || len(got[0].Actions) != 1 || got[0].Actions[0].Arguments["move"] != "mailu" {
+		t.Fatalf("a machine with only asked moves: %+v", got)
+	}
+}

cmd/mesh-controller/image_missing.go

@@ -0,0 +1,245 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"slices"
+	"sort"
+	"strings"
+	"sync"
+
+	"git.novox.be/novox/mesh-sdk/go/catalogue"
+	"github.com/novox/mesh-controller/internal/artifacts"
+	"github.com/novox/mesh-controller/internal/conditions"
+	"github.com/novox/mesh-controller/internal/inventory"
+)
+
+// No declaration is sent that names an image the artifact store does not hold (novox/hq issue 1742).
+//
+// On 2026-10-21 at 17:13 a send to novox named `mailu/automx@sha256:c62150b8…`; the build record keeps that digest
+// ("recent-build") and the store did not hold it. The node-engine removed the running container, then could not pull
+// the replacement, and every later apply on novox failed for the next hour while the mail clients' autoconfiguration
+// had no backend. The node-engine's half (pull first, replace after) is its own change; this is the controller's: **a
+// module whose image the store lacks is left out of the declaration**, as a module whose setting nobody gave is
+// (ADR 0163, rule 6) — the node-engine keeps what it has of it and touches none of its containers — and **it is said**,
+// row S25: a condition naming the module, the machine and the image, until the store holds the image again (a new build
+// of the module, or the copy put back).
+//
+// Judged only for an image the store's own address names, from the send's own resources; an image of another registry
+// is no business of the store's. A store that cannot be asked judges nothing: a send is not refused for a question
+// that did not answer.
+
+// kindImageMissing is S25's kind: module.<module>.<machine>.image-missing.
+const kindImageMissing = "image-missing"
+
+// missingImage is a module held out of a machine's declaration because the store lacks an image it names.
+type missingImage struct {
+	Node, Module, Image string
+}
+
+// storeHolds is whether the store holds the manifest an image reference at its address names.
+type storeHolds func(ctx context.Context, reference string) (bool, error)
+
+// imageInStore is the artifact-store reference of an image the store's address names, "" for any other.
+func imageInStore(image, address string) string {
+	if address == "" || !strings.HasPrefix(image, address+"/") || !strings.Contains(image, "@sha256:") {
+		return ""
+	}
+	reference := catalogue.Recorded(image)
+	if _, ours := catalogue.InArtifactStore(reference); !ours {
+		return ""
+	}
+	return reference
+}
+
+// holdBackMissingImages leaves out of the declaration every module that names an image the store does not hold,
+// and answers what it left out. The module's resources go, it joins LeftOut with the reason, and its build stays the
+// one the machine was last sent (`was`).
+func holdBackMissingImages(ctx context.Context, node string, s *sendable, address string, holds storeHolds,
+	was map[string]string) []missingImage {
+	lacks := map[string]bool{} // reference → the store does not hold it; absent: not asked, or no answer
+	asked := map[string]bool{}
+	lacking := map[string]string{} // module → the image
+	for _, r := range s.Resources {
+		if fmt.Sprint(r["type"]) != "container" {
+			continue
+		}
+		image, _ := r["image"].(string)
+		reference := imageInStore(image, address)
+		module := s.moduleOf[fmt.Sprint(r["id"])]
+		if reference == "" || module == "" || lacking[module] != "" {
+			continue
+		}
+		if !asked[reference] {
+			asked[reference] = true
+			held, err := holds(ctx, reference)
+			// empty-on-error: the store did not answer, so nothing is held back for a question unanswered
+			lacks[reference] = err == nil && !held
+		}
+		if lacks[reference] {
+			lacking[module] = image
+		}
+	}
+	if len(lacking) == 0 {
+		return nil
+	}
+	kept := s.Resources[:0:0]
+	for _, r := range s.Resources {
+		if _, out := lacking[s.moduleOf[fmt.Sprint(r["id"])]]; !out {
+			kept = append(kept, r)
+		}
+	}
+	s.Resources = kept
+	if s.leftOutWhy == nil {
+		s.leftOutWhy = map[string]string{}
+	}
+	var found []missingImage
+	for module, image := range lacking {
+		s.leftOutWhy[module] = "its image " + image + " is not in the artifact store"
+		if !slices.Contains(s.LeftOut, module) {
+			s.LeftOut = append(s.LeftOut, module)
+		}
+		if s.Builds != nil {
+			if prior, sent := was[module]; sent {
+				s.Builds[module] = prior
+			} else {
+				delete(s.Builds, module)
+			}
+		}
+		found = append(found, missingImage{Node: node, Module: module, Image: image})
+	}
+	sort.Strings(s.LeftOut)
+	sort.Slice(found, func(i, j int) bool { return found[i].Module < found[j].Module })
+	return found
+}
+
+// withoutMissingImages is composeSend's last step: the store asked about the images the declaration names, the modules
+// whose image it lacks left out and kept in the ledger S25 reads. A store that cannot be found or asked leaves the
+// declaration as composed.
+func withoutMissingImages(ctx context.Context, open *stores, node string, s sendable) sendable {
+	inv := open.inventory
+	shelf, err := inv.Catalogue(ctx)
+	if err != nil {
+		return s
+	}
+	address, err := artifactStoreAddress(ctx, inv, shelf, node)
+	if err != nil || address == "" {
+		return s
+	}
+	sent, known, err := inv.SentBuilds(ctx, node)
+	if err != nil || !known {
+		sent = nil
+	}
+	store := artifacts.Store{Address: address}
+	found := holdBackMissingImages(ctx, node, &s, address, store.HoldsManifest, sent)
+	for _, m := range found {
+		fmt.Printf("%s: %s is left out of the declaration: its image %s is not in the artifact store\n", node, m.Module, m.Image)
+	}
+	return s
+}
+
+// imageFacts are the images S25 raises: a module whose registered build names an image the store lacks, on each machine
+// that runs it.
+type imageFacts struct {
+	missingImage
+}
+
+// imagesHeld remembers the images the store was found to hold: a stored image is named by its digest and stays what it
+// is, so it is asked about once; one it lacks is asked again at every look.
+var imagesHeld = struct {
+	sync.Mutex
+	held map[string]bool
+}{held: map[string]bool{}}
+
+// gatherMissingImages is every machine's module whose registered build — the one a send would carry — names an image of
+// the artifact store that the store does not hold. Read from the catalogue and the store, never from what a send did:
+// a push is a command of its own, and the serving controller's watchdog hears nothing of it.
+func gatherMissingImages(ctx context.Context, inv *inventory.Inventory, holds storeHolds) ([]imageFacts, error) {
+	shelf, err := inv.Catalogue(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("the catalogue cannot be read: %w", err)
+	}
+	var out []imageFacts
+	for _, module := range sortedKeysOf(modulesOf(shelf)) {
+		for _, r := range shelf[module].Resources {
+			if fmt.Sprint(r["type"]) != "container" {
+				continue
+			}
+			image, _ := r["image"].(string)
+			if _, ours := catalogue.InArtifactStore(image); !ours || !strings.Contains(image, "@sha256:") {
+				continue
+			}
+			imagesHeld.Lock()
+			known := imagesHeld.held[image]
+			imagesHeld.Unlock()
+			if !known {
+				held, err := holds(ctx, image)
+				if err != nil {
+					return nil, fmt.Errorf("the artifact store cannot be asked about %s: %w", image, err)
+				}
+				if held {
+					imagesHeld.Lock()
+					imagesHeld.held[image] = true
+					imagesHeld.Unlock()
+					continue
+				}
+			} else {
+				continue
+			}
+			running, err := inv.Running(ctx, module)
+			if err != nil {
+				return nil, err
+			}
+			for _, node := range running {
+				out = append(out, imageFacts{missingImage{Node: node, Module: module, Image: image}})
+			}
+		}
+	}
+	return out, nil
+}
+
+// modulesOf is the shelf's modules as a map of names, for sortedKeysOf.
+func modulesOf(shelf map[string]catalogue.Manifest) map[string]string {
+	out := make(map[string]string, len(shelf))
+	for m := range shelf {
+		out[m] = m
+	}
+	return out
+}
+
+// watchMissingImages is S25: a module left out of a machine's declaration because the store lacks its image, said at
+// once. The condition ends when the store holds the image, or a send names another.
+func watchMissingImages(f *signalFacts) []conditions.Observation {
+	var out []conditions.Observation
+	for _, m := range f.images {
+		out = append(out, conditions.Observation{Scope: conditions.ScopeModule, ID: m.Module + "." + m.Node, Kind: kindImageMissing,
+			Machine: m.Node, Severity: conditions.Warning, Resolver: conditions.ResolverOperator,
+			Summary: fmt.Sprintf("%s is left out of every send to %s: its declaration names an image that the artifact store does "+
+				"not hold (the evidence names it); the running container is untouched", m.Module, m.Node),
+			Said:     "image " + m.Image + " is not in the store",
+			Headline: clipWords(conditions.Capital(m.Module)+" is not updated on "+m.Node, conditions.HeadlineMax),
+			Explanation: clipWords(fmt.Sprintf("The new version of %s names a container image that the mesh's store does not "+
+				"hold, so it was not sent to %s. What runs there is untouched, and the rest of %s is sent as usual.",
+				m.Module, m.Node, m.Node), conditions.ExplanationMax),
+			Needs:    fmt.Sprintf("build %s again; the details name the image.", m.Module),
+			Resolved: "Resolved: the store holds the image of " + m.Module + " again"})
+	}
+	return out
+}
+
+// gatherMissingImagesHere is gatherMissingImages asking the mesh's own artifact store; nothing to ask where the mesh has
+// none on its network yet.
+func gatherMissingImagesHere(ctx context.Context, inv *inventory.Inventory) ([]imageFacts, error) {
+	shelf, err := inv.Catalogue(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("the catalogue cannot be read: %w", err)
+	}
+	address, err := artifactStoreAddress(ctx, inv, shelf, "")
+	if err != nil {
+		return nil, err
+	}
+	if address == "" {
+		return nil, nil
+	}
+	return gatherMissingImages(ctx, inv, artifacts.Store{Address: address}.HoldsManifest)
+}

cmd/mesh-controller/image_missing_test.go

@@ -0,0 +1,125 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/novox/mesh-controller/internal/conditions"
+)
+
+// **No declaration is sent that names an image the artifact store does not hold** (novox/hq issue 1742).
+
+const storeAt = "novox.internal:5100"
+
+// automx is the image the send of 2026-10-21 17:13 named and the store lacked; the others are held.
+const (
+	automxImage = storeAt + "/mailu/automx@sha256:c62150b8e2cbcc18cb911b098c2877f928761a1e6251667f39ea18251ea35591"
+	imapImage   = storeAt + "/mailu/imap@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+)
+
+func aMailSend() sendable {
+	return sendable{
+		Resources: []map[string]any{
+			{"id": "mailu.automx", "type": "container", "image": automxImage},
+			{"id": "mailu.automx-config", "type": "file", "path": "/etc/automx.conf"},
+			{"id": "mailu.imap", "type": "container", "image": imapImage},
+			{"id": "other.web", "type": "container", "image": "docker.io/library/nginx@sha256:" + strings.Repeat("b", 64)},
+			{"id": "dns.dnsmasq", "type": "container", "image": storeAt + "/dnsmasq/main@sha256:" + strings.Repeat("c", 64)},
+		},
+		moduleOf: map[string]string{"mailu.automx": "automx", "mailu.automx-config": "automx", "mailu.imap": "mailu",
+			"other.web": "other", "dns.dnsmasq": "dnsmasq"},
+		Builds: map[string]string{"automx": "b2f5ebb2new", "mailu": "m2", "other": "o1", "dnsmasq": "d1"},
+	}
+}
+
+func storeHolding(missing ...string) (storeHolds, *[]string) {
+	var asked []string
+	return func(_ context.Context, reference string) (bool, error) {
+		asked = append(asked, reference)
+		for _, m := range missing {
+			if strings.Contains(reference, m) {
+				return false, nil
+			}
+		}
+		return true, nil
+	}, &asked
+}
+
+// 1742/AC1: given a send naming automx's image, which the store does not hold, when the declaration is judged, then
+// every resource of automx is out of it, automx is among the modules left out with the reason, its build is the one the
+// machine was last sent, and every other module — an image of another registry among them — is as composed.
+func TestAModuleWhoseImageTheStoreLacksIsLeftOutOfTheSend(t *testing.T) {
+	s := aMailSend()
+	holds, asked := storeHolding("mailu/automx@")
+	found := holdBackMissingImages(t.Context(), "novox", &s, storeAt, holds, map[string]string{"automx": "b2f5ebb2old"})
+	if len(found) != 1 || found[0].Module != "automx" || found[0].Node != "novox" || found[0].Image != automxImage {
+		t.Fatalf("found %+v", found)
+	}
+	var ids []string
+	for _, r := range s.Resources {
+		ids = append(ids, r["id"].(string))
+	}
+	if got := strings.Join(ids, ","); got != "mailu.imap,other.web,dns.dnsmasq" {
+		t.Errorf("the declaration keeps %s", got)
+	}
+	if len(s.LeftOut) != 1 || s.LeftOut[0] != "automx" || !strings.Contains(s.leftOutWhy["automx"], "not in the artifact store") {
+		t.Errorf("left out %v because %v", s.LeftOut, s.leftOutWhy)
+	}
+	if s.Builds["automx"] != "b2f5ebb2old" || s.Builds["mailu"] != "m2" || s.Builds["other"] != "o1" {
+		t.Errorf("builds %v", s.Builds)
+	}
+	for _, a := range *asked {
+		if strings.Contains(a, "docker.io") {
+			t.Errorf("the store was asked about an image of another registry: %s", a)
+		}
+	}
+}
+
+// 1742/AC2: given a module never sent to the machine, when its image is missing, then it has no build in the record of the
+// send; given the store does not answer, then nothing is held back for a question unanswered.
+func TestAnUnansweredStoreHoldsNothingBackAndANewModuleHasNoBuild(t *testing.T) {
+	s := aMailSend()
+	holds, _ := storeHolding("mailu/automx@")
+	found := holdBackMissingImages(t.Context(), "novox", &s, storeAt, holds, nil)
+	if len(found) != 1 {
+		t.Fatalf("%+v", found)
+	}
+	if _, has := s.Builds["automx"]; has {
+		t.Errorf("a module never sent is recorded as sent: %v", s.Builds)
+	}
+	s = aMailSend()
+	silent := func(context.Context, string) (bool, error) { return false, errors.New("registry: connection refused") }
+	if found := holdBackMissingImages(t.Context(), "novox", &s, storeAt, silent, nil); len(found) != 0 || len(s.LeftOut) != 0 ||
+		len(s.Resources) != 5 {
+		t.Errorf("an unanswered store held back %+v, left out %v", found, s.LeftOut)
+	}
+}
+
+// 1742/AC3: a module left out for its image raises a condition for the operator naming the module, the machine and the
+// image in the evidence, plain words, and no answer to give; a mesh whose images are all held raises nothing.
+func TestAMissingImageIsRaisedForTheOperator(t *testing.T) {
+	f := calm(time.Date(2026, 10, 21, 17, 40, 0, 0, time.UTC))
+	if got := watchMissingImages(f); len(got) != 0 {
+		t.Fatalf("%+v", got)
+	}
+	f.images = []imageFacts{{missingImage{Node: "novox", Module: "automx", Image: automxImage}}}
+	got := watchMissingImages(f)
+	if len(got) != 1 {
+		t.Fatalf("%+v", got)
+	}
+	o := got[0]
+	if o.Kind != "image-missing" || o.Key() != "module.automx.novox.image-missing" || o.Resolver != conditions.ResolverOperator ||
+		o.Severity != conditions.Warning || o.Machine != "novox" {
+		t.Fatalf("%+v (%s)", o, o.Key())
+	}
+	if !strings.Contains(o.Said, "c62150b8") || !strings.Contains(o.Headline+o.Explanation, "automx") {
+		t.Errorf("words: %q / %q / %q", o.Headline, o.Explanation, o.Said)
+	}
+	w := conditions.Words{Headline: o.Headline, Explanation: o.Explanation, Resolved: o.Resolved, Needs: o.Needs}
+	if why, ok := conditions.PlainWords(w, "novox"); !ok {
+		t.Errorf("not plain: %s", why)
+	}
+}

cmd/mesh-controller/issue611_test.go

@@ -35,7 +35,7 @@ func TestAMergeSaysTheModulesWhoseBuildSourceItLeftUnchanged(t *testing.T) {
 			{Own: true, Paths: []string{"modules/build-agent/Dockerfile", "modules/build-agent/module.json"}},
 		},
 		"route-proxy": {
-			{Repository: "novox/mesh-controller", Ref: "main", Paths: []string{"go.mod", "examples/route-proxy/"}},
+			{Repository: "novox/mesh-controller", Ref: "main", Paths: []string{"go.mod", "modules/route-proxy/cmd/route-proxy/"}},
 			{Own: true, Paths: []string{"modules/route-proxy/Dockerfile", "modules/route-proxy/module.json"}},
 		},
 	}

cmd/mesh-controller/main.go

@@ -408,6 +408,13 @@ func (b builds) Built(ctx context.Context, result link.BuildResult) error {
 		fmt.Printf("%s: a dry run of %s on %s, not taken in\n", result.ID, result.Repository, result.Ref)
 		return nil
 	}
+	// **A first build refused for a word the running build-agent does not read waits for one that does** (novox/hq ADR
+	// 0482 §5, issue 1173): its merge is kept, named, and never failed; no failed build is recorded.
+	if held, err := holdRefusedFirstBuild(ctx, b.inv, result); err != nil {
+		return err
+	} else if held {
+		return nil
+	}
 	manifest, _, err := takeIn(ctx, b.inv, result)
 	// The assignments pending on this build, made or ended (novox/hq issue 325), said in the daemon's log
 	// after what became of the build.

cmd/mesh-controller/merge_gate.go

@@ -65,6 +65,9 @@ type mergeCheckInput struct {
 	// group are the other heads of a delivery group composed with this one (novox/hq ADR 0239), each laid
 	// over the mesh after the one before: the group judged as one future state.
 	group []groupChange
+	// held are the approved config values held for the keys the pull requests introduce (novox/hq ADR 0502 clause 4),
+	// laid over the composition with the change only.
+	held []heldValue
 	// admin is a PostgreSQL the gate may create and drop databases in.
 	admin string
 	// beside is the directory holding the core clones beside the check (MESH_CHECK_BESIDE), for finding moves.
@@ -189,6 +192,8 @@ func mergeGateCommand(ctx context.Context, args []string) error {
 		"--changed, for a list too long for an argument (novox/hq issue 1247)")
 	group := set.String("group", "", "a delivery group's other heads, as JSON [{repository, tree, changed}], composed "+
 		"with this one as one future state (novox/hq ADR 0239)")
+	heldFile := set.String("held", "", "a file of the config values approved for keys the change's pull requests introduce, as JSON "+
+		"[{pull, node, module, key, value, approved_by}], laid over the composition with the change (novox/hq ADR 0502)")
 	asJSON := set.Bool("json", false, "print the verdict as JSON")
 	if _, err := parseAround(set, args); err != nil {
 		return err
@@ -208,6 +213,10 @@ func mergeGateCommand(ctx context.Context, args []string) error {
 	if err != nil {
 		return err
 	}
+	held, err := readHeld(*heldFile)
+	if err != nil {
+		return err
+	}
 	out := io.Writer(os.Stdout)
 	stdout := os.Stdout
 	if *asJSON {
@@ -223,7 +232,7 @@ func mergeGateCommand(ctx context.Context, args []string) error {
 		return err
 	}
 	v, err := judgeChange(ctx, mergeCheckInput{facts: f, repository: *repository, tree: *tree, changed: changedList,
-		group: others, admin: *admin, say: out, beside: os.Getenv("MESH_CHECK_BESIDE")})
+		group: others, held: held, admin: *admin, say: out, beside: os.Getenv("MESH_CHECK_BESIDE")})
 	os.Stdout = stdout
 	if err != nil {
 		return err
@@ -387,7 +396,16 @@ func judgeChange(ctx context.Context, in mergeCheckInput) (mergeVerdict, error)
 		}
 	}
 	sort.Strings(added)
-	after, tried, notes, err := composeEveryMachine(ctx, in, change, changeSources, added)
+	// **The held values are laid in this composition only** (novox/hq ADR 0502 clause 4): the mesh as it is does not
+	// declare their keys, so the base composition would refuse them.
+	withHeld := in
+	var heldNotes []string
+	withHeld.facts, heldNotes = layHeld(in.facts, in.held, change)
+	for _, n := range heldNotes {
+		say("%s", n)
+	}
+	v.Notes = append(v.Notes, heldNotes...)
+	after, tried, notes, err := composeEveryMachine(ctx, withHeld, change, changeSources, added)
 	if err != nil {
 		return v, fmt.Errorf("the mesh with the change could not be raised: %w", err)
 	}

cmd/mesh-controller/merge_gate_held.go

@@ -0,0 +1,135 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"sort"
+	"strings"
+
+	"git.novox.be/novox/mesh-sdk/go/catalogue"
+	snapshot "git.novox.be/novox/mesh-sdk/go/facts"
+)
+
+// Config values held for the keys an open pull request introduces (novox/hq ADR 0502 clause 4, issue 1826): the gate
+// lays each approved one over its module's values on its node in the composition with the change, and in that one
+// only. In the mesh as it is the key is not declared, so the value would be refused there.
+
+// heldValue is one approved held value as the build agent writes it (--held): the value of Key for Module on Node,
+// a machine's real name, which the snapshot holds only as a pseudonym.
+type heldValue struct {
+	Pull     string          `json:"pull"`
+	Head     string          `json:"head,omitempty"`
+	Node     string          `json:"node"`
+	Module   string          `json:"module"`
+	Key      string          `json:"key"`
+	Value    json.RawMessage `json:"value"`
+	Approved string          `json:"approved,omitempty"`
+	By       string          `json:"by,omitempty"`
+	At       string          `json:"at,omitempty"`
+}
+
+// readHeld reads the file --held names; none named, none held.
+func readHeld(path string) ([]heldValue, error) {
+	if path == "" {
+		return nil, nil
+	}
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return nil, err
+	}
+	var held []heldValue
+	if err := json.Unmarshal(raw, &held); err != nil {
+		return nil, fmt.Errorf("the held values are not readable: %w", err)
+	}
+	for _, h := range held {
+		if h.Node == "" || h.Module == "" || h.Key == "" || len(h.Value) == 0 {
+			return nil, fmt.Errorf("a held value of %s names no node, module, key or value", h.Pull)
+		}
+	}
+	return held, nil
+}
+
+// layHeld is the snapshot with each held value laid as the value of its key in its node's layer of its module, and what
+// it said of them. The snapshot given is not changed. **A held value for a machine the snapshot does not hold, or a
+// module the change does not define, is said and not laid**, never dropped silently; one for a module not assigned to
+// its machine is laid and said. The notes name machines as the snapshot does (roles and pseudonym), not by their names.
+func layHeld(f snapshot.Facts, held []heldValue, shelf map[string]catalogue.Manifest) (snapshot.Facts, []string) {
+	if len(held) == 0 {
+		return f, nil
+	}
+	out := f
+	out.Machines = make([]snapshot.Machine, len(f.Machines))
+	copy(out.Machines, f.Machines)
+	var notes, laid []string
+	pulls := map[string]bool{}
+	for _, h := range held {
+		at := -1
+		pseudonym := snapshot.Pseudonym("machine", h.Node)
+		for i, m := range out.Machines {
+			if m.Name == pseudonym {
+				at = i
+			}
+		}
+		if at < 0 {
+			notes = append(notes, fmt.Sprintf("the value held for %s of %s (%s=%s) is not composed: the snapshot holds no machine %s",
+				h.Module, h.Pull, h.Key, h.Value, pseudonym))
+			continue
+		}
+		if _, defined := shelf[h.Module]; !defined {
+			notes = append(notes, fmt.Sprintf("the value held for %s of %s (%s=%s) is not composed: the change defines no module %s",
+				h.Module, h.Pull, h.Key, h.Value, h.Module))
+			continue
+		}
+		var value any
+		if err := json.Unmarshal(h.Value, &value); err != nil {
+			notes = append(notes, fmt.Sprintf("the value held for %s of %s (%s) is not composed: it is not a value: %v",
+				h.Module, h.Pull, h.Key, err))
+			continue
+		}
+		m := &out.Machines[at]
+		layers := make([]snapshot.Settings, len(m.Settings))
+		copy(layers, m.Settings)
+		found := false
+		for i := range layers {
+			if layers[i].Module == h.Module {
+				values := make(map[string]any, len(layers[i].Values)+1)
+				for k, v := range layers[i].Values {
+					values[k] = v
+				}
+				values[h.Key] = value
+				layers[i].Values = values
+				found = true
+			}
+		}
+		if !found {
+			layers = append(layers, snapshot.Settings{Module: h.Module, Values: map[string]any{h.Key: value}})
+			sort.Slice(layers, func(a, b int) bool { return layers[a].Module < layers[b].Module })
+		}
+		m.Settings = layers
+		assigned := false
+		for _, a := range m.Assigned {
+			assigned = assigned || a == h.Module
+		}
+		by := ""
+		if h.Approved != "" {
+			by = ", approved by " + h.Approved
+		}
+		line := fmt.Sprintf("%s on %s %s=%s%s", h.Module, m.Described(), h.Key, h.Value, by)
+		if !assigned {
+			line += " (not assigned there in the snapshot)"
+		}
+		laid = append(laid, line)
+		pulls[h.Pull] = true
+	}
+	if len(laid) > 0 {
+		var names []string
+		for p := range pulls {
+			names = append(names, p)
+		}
+		sort.Strings(names)
+		notes = append([]string{fmt.Sprintf("composed with %d value(s) held for %s: %s", len(laid), strings.Join(names, ", "),
+			strings.Join(laid, "; "))}, notes...)
+	}
+	return out, notes
+}

cmd/mesh-controller/merge_gate_held_test.go

@@ -0,0 +1,85 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"git.novox.be/novox/mesh-sdk/go/catalogue"
+	snapshot "git.novox.be/novox/mesh-sdk/go/facts"
+)
+
+func heldGateFacts() snapshot.Facts {
+	return snapshot.Facts{Machines: []snapshot.Machine{
+		{Name: snapshot.Pseudonym("machine", "ace"), Roles: []string{"the build node"}, Assigned: []string{"n8n"},
+			Settings: []snapshot.Settings{{Module: "n8n", Values: map[string]any{"port": 5678.0}}}},
+		{Name: snapshot.Pseudonym("machine", "g14")},
+	}}
+}
+
+var heldShelf = map[string]catalogue.Manifest{"n8n": {Module: "n8n"}}
+
+// 1826/AC3: a held value is laid in its node's layer of its module, beside what the layer holds, and said.
+func TestAHeldValueIsLaidOverItsNodesLayerAndSaid(t *testing.T) {
+	f := heldGateFacts()
+	got, notes := layHeld(f, []heldValue{{Pull: "novox/mesh-catalog#434", Node: "ace", Module: "n8n", Key: "media-gid",
+		Value: []byte("2000"), Approved: "the operator"}}, heldShelf)
+	layer := got.Machines[0].Settings[0].Values
+	if layer["media-gid"] != 2000.0 || layer["port"] != 5678.0 {
+		t.Fatalf("the layer holds %v", layer)
+	}
+	if _, has := f.Machines[0].Settings[0].Values["media-gid"]; has {
+		t.Fatal("the snapshot given was changed")
+	}
+	if len(notes) != 1 || !strings.Contains(notes[0], "composed with 1 value(s) held for novox/mesh-catalog#434") ||
+		!strings.Contains(notes[0], "media-gid=2000") || !strings.Contains(notes[0], "approved by the operator") ||
+		strings.Contains(notes[0], "ace") {
+		t.Fatalf("said %q", notes)
+	}
+}
+
+// 1826/AC3: a machine with no layer of the module gets one.
+func TestAHeldValueMakesTheLayerAMachineLacks(t *testing.T) {
+	got, _ := layHeld(heldGateFacts(), []heldValue{{Pull: "p", Node: "g14", Module: "n8n", Key: "k", Value: []byte(`"x"`)}}, heldShelf)
+	s := got.Machines[1].Settings
+	if len(s) != 1 || s[0].Module != "n8n" || s[0].Values["k"] != "x" {
+		t.Fatalf("layers %+v", s)
+	}
+}
+
+// 1826/AC3: a held value for a machine or a module the snapshot or the change does not hold is said, never laid.
+func TestAHeldValueForWhatIsNotHeldIsSaidNotLaid(t *testing.T) {
+	f := heldGateFacts()
+	got, notes := layHeld(f, []heldValue{
+		{Pull: "p", Node: "nowhere", Module: "n8n", Key: "k", Value: []byte("1")},
+		{Pull: "p", Node: "ace", Module: "ghost", Key: "k", Value: []byte("1")},
+	}, heldShelf)
+	if len(notes) != 2 || !strings.Contains(notes[0], "holds no machine") || !strings.Contains(notes[1], "defines no module ghost") {
+		t.Fatalf("said %q", notes)
+	}
+	if _, has := got.Machines[0].Settings[0].Values["k"]; has {
+		t.Fatal("laid")
+	}
+}
+
+// 1826/AC3: none held lays nothing and says nothing; the file is read and refuses a value without a node.
+func TestNoHeldValuesLayNothingAndTheFileIsRead(t *testing.T) {
+	if got, notes := layHeld(heldGateFacts(), nil, heldShelf); len(notes) != 0 || len(got.Machines) != 2 {
+		t.Fatalf("%v %v", got, notes)
+	}
+	dir := t.TempDir()
+	good := filepath.Join(dir, "good.json")
+	os.WriteFile(good, []byte(`[{"pull":"p","node":"ace","module":"n8n","key":"k","value":1}]`), 0o644)
+	if h, err := readHeld(good); err != nil || len(h) != 1 || h[0].Key != "k" {
+		t.Fatalf("%v %v", h, err)
+	}
+	bad := filepath.Join(dir, "bad.json")
+	os.WriteFile(bad, []byte(`[{"pull":"p","module":"n8n","key":"k","value":1}]`), 0o644)
+	if _, err := readHeld(bad); err == nil {
+		t.Fatal("a value without a node was read")
+	}
+	if h, err := readHeld(""); h != nil || err != nil {
+		t.Fatalf("%v %v", h, err)
+	}
+}

cmd/mesh-controller/merge_gate_integration_test.go

@@ -526,3 +526,57 @@ func TestAMemberJudgedAloneSeesAMoveThroughTheClonesBeside(t *testing.T) {
 		t.Errorf("nothing beside, yet moves %v", got)
 	}
 }
+
+// 1826/AC3 (integration level, a throwaway store): a change whose container says ${config:media-gid} fails the gate for
+// want of the value, passes it with the value the operator approved held for its pull request, and the mesh as it is
+// composes the same either way.
+func TestAChangeNeedingAHeldValueFailsWithoutItAndPassesWithIt(t *testing.T) {
+	open := aMesh(t)
+	ctx := t.Context()
+	trunk := `{"module":"n8n","version":"1","resources":[{"id":"server","type":"container","name":"n8n",
+		"image":"n8nio/n8n@sha256:4846eb2f4b874ab04cde7fc1e249d2ddaec66e9aea64439beb2972cfea88e3c0"}]}`
+	m, err := catalogue.ParseManifest([]byte(trunk))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := open.inventory.RegisterModule(ctx, m, inventory.Source{Repository: "novox/mesh-catalog",
+		Path: "modules/n8n", BuiltFrom: "c0ffee"}); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := assign(ctx, open, "laptop", "n8n"); err != nil {
+		t.Fatal(err)
+	}
+	f, err := gatherFacts(ctx, open, "2.11.17")
+	if err != nil {
+		t.Fatal(err)
+	}
+	for i := range f.Machines {
+		f.Machines[i].Capabilities = append(f.Machines[i].Capabilities, snapshot.Capability{Name: "container-groups", Present: true})
+	}
+	tree := aTree(t, map[string]string{"n8n": n8nWithAGroup})
+	judge := func(held []heldValue) mergeVerdict {
+		v, err := judgeChange(t.Context(), mergeCheckInput{facts: f, admin: os.Getenv("MESH_TEST_POSTGRES"),
+			repository: "novox/mesh-catalog", tree: tree, changed: []string{"modules/n8n/module.json"}, held: held})
+		if err != nil {
+			t.Fatal(err)
+		}
+		return v
+	}
+	without := judge(nil)
+	if without.Verdict != "fail" || !strings.Contains(without.Report(), "media-gid") {
+		t.Fatalf("a required value nothing sets passed, or failed for another reason:\n%s", without.Report())
+	}
+	with := judge([]heldValue{{Pull: "novox/mesh-catalog#434", Node: "laptop", Module: "n8n", Key: "media-gid",
+		Value: []byte("2000"), Approved: "the operator"}})
+	if with.Verdict == "fail" || with.Verdict == "error" {
+		t.Fatalf("the held value did not make it compose:\n%s", with.Report())
+	}
+	if !strings.Contains(with.Report(), "composed with 1 value(s) held for novox/mesh-catalog#434") {
+		t.Fatalf("the value laid is not said:\n%s", with.Report())
+	}
+	for i := range with.Machines {
+		if with.Machines[i].Base.Composes != without.Machines[i].Base.Composes {
+			t.Fatalf("the mesh as it is composes differently with a held value: %+v / %+v", with.Machines[i].Base, without.Machines[i].Base)
+		}
+	}
+}

cmd/mesh-controller/new_head_words_test.go

@@ -0,0 +1,40 @@
+package main
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/novox/mesh-controller/internal/conditions"
+)
+
+// novox/hq ADR 0505 §5: a delivery whose cure is its author's new head reaches the operator in words that name its
+// author and say a new head is needed, offer no Stop and never call it the operator's; the line as mesh-delivery-gate
+// says it (ready.go readyLines: needs "new-head", author, branch).
+func TestADeliveryThatNeedsANewHeadNamesItsAuthorAndOffersNoStop(t *testing.T) {
+	l := stalledLine{ID: "novox/mesh-controller@499ff5c21861", Number: 432, State: "rejected", For: "2h1m0s", Bound: "2h0m0s",
+		H2: "none: a new head from its author, or a recheck that passes", Needs: needsNewHead,
+		Author: "the author of feat/quiet-deliveries (quiet-deliveries on shanks)", Branch: "feat/quiet-deliveries",
+		Says: "novox/mesh-controller#432 passed its checks at 499ff5c21861 and is not merged: a conflict"}
+	o := stalledObservations([]stalledLine{l})[0]
+	for _, words := range []string{o.Headline, o.Explanation, o.Resolved, o.Needs} {
+		if why, ok := conditions.Plain(words); !ok {
+			t.Errorf("%q is not plain: %s", words, why)
+		}
+		for _, never := range []string{"stop it", "operator's"} {
+			if strings.Contains(words, never) {
+				t.Errorf("%q says %q", words, never)
+			}
+		}
+	}
+	if o.Headline != "Pull request 432 of mesh-controller needs a new head from its author" ||
+		!strings.Contains(o.Explanation, "until the author of feat/quiet-deliveries (quiet-deliveries on shanks) pushes a new head") ||
+		!strings.Contains(o.Explanation, "for 2 hours") || len(o.Actions) != 0 ||
+		o.Needs != "ask the author of feat/quiet-deliveries (quiet-deliveries on shanks) for a new head." {
+		t.Fatalf("words: %q / %q / %q / %v", o.Headline, o.Explanation, o.Needs, o.Actions)
+	}
+	// A branch in code is not said; the author is then "its author".
+	l.Author = "the author of fix/a1b2c3d4e5f6"
+	if o := stalledObservations([]stalledLine{l})[0]; !strings.Contains(o.Needs, "ask its author") {
+		t.Fatalf("a dotted branch was said: %q", o.Needs)
+	}
+}

cmd/mesh-controller/plain_words.go

@@ -457,6 +457,18 @@ var plainWordings = map[string]func(conditions.Observation) words{
 			Explanation: "A delivery did not finish. Nothing is tried again until you say so.",
 			Resolved:    "Resolved: the delivery is no longer failed"}
 	}),
+	kindMovesHeld: worded(func(o conditions.Observation) words {
+		return words{Headline: "An update waits for you",
+			Explanation: "A new version of a module would restart a container or touch its data, so it waits for you.",
+			Resolved:    "Resolved: the update is no longer waiting"}
+	}),
+	kindImageMissing: worded(func(o conditions.Observation) words {
+		return words{Headline: "A module is not updated",
+			Explanation: "The new version of a module names a container image that the mesh's store does not hold, so it " +
+				"was not sent. What runs is untouched.",
+			Needs:    "build the module again; the details name the image.",
+			Resolved: "Resolved: the store holds the image again"}
+	}),
 	"ask-lost": worded(func(o conditions.Observation) words {
 		return words{Headline: "A build has no result",
 			Explanation: "A build was asked for and never answered. It is asked again with the next delivery.",
@@ -954,6 +966,9 @@ func stalledWords(l stalledLine, o conditions.Observation) (headline, explanatio
 	if l.State == "unanswered" {
 		return unansweredWords(l, o)
 	}
+	if l.Needs == needsNewHead {
+		return newHeadWords(l, name)
+	}
 	held := l.State
 	if held == "" {
 		held = "held"
@@ -987,6 +1002,29 @@ func stalledWords(l stalledLine, o conditions.Observation) (headline, explanatio
 		fmt.Sprintf("Delivery of %s is no longer %s", name, held), needs, actions
 }
 
+// newHeadWords are the words of a delivery whose cure is its author's new head (novox/hq ADR 0505 §5): it names the
+// author and says a new head is needed; it offers no Stop and never calls it the operator's, because the operator
+// hears of it only once the author's own watch has failed, after two hours with no new head.
+func newHeadWords(l stalledLine, name string) (headline, explanation, resolved, needs string, actions []conditions.Action) {
+	pull := "A pull request of " + name
+	if l.Number > 0 {
+		pull = fmt.Sprintf("Pull request %d of %s", l.Number, name)
+	}
+	author := l.Author
+	if _, plain := conditions.Plain(author); !plain {
+		author = "its author" // a branch named in code (a dotted name, a number) is not said
+	}
+	long := "for a long time"
+	if d, err := time.ParseDuration(l.For); err == nil {
+		long = "for " + humanDuration(d)
+	}
+	return pull + " needs a new head from its author",
+		fmt.Sprintf("%s cannot merge until %s pushes a new head: its check failed after its Approve, and no new head "+
+			"came %s.", pull, author, long),
+		pull + " has a new head, or is closed",
+		"ask " + author + " for a new head.", nil
+}
+
 // stoppedNeeds is what ends a delivery that is already stopped, from the stalled line's healer words ("none: a
 // merge that delivers its modules ends it — the operator's"): the part that says what ends it.
 func stoppedNeeds(l stalledLine) string {

cmd/mesh-controller/plain_words_test.go

@@ -260,7 +260,7 @@ func TestUpdatesHeldNameWhatWaitsAndWhereItIsReleased(t *testing.T) {
 	plainExample(t, got[0], "Updates of openrazer and sensors wait for your release",
 		"Needs you: release them from the mesh MCP server; this notification cannot do it. Updates of openrazer and "+
 			"sensors on g14 and shanks wait for a person to release them, because the last walk failed. "+
-			"They are not delivered until then, and stay held if you leave them.")
+			"They are not delivered until then, and stay held if you leave them.", "Release")
 }
 
 // **What held them is said in the glossary's words** (2026-10-08 review): the backlog is held after any

cmd/mesh-controller/plan_looks.go

@@ -192,7 +192,7 @@ func startRolloutEvents(ctx context.Context, open *stores, js *broker.JetStream)
 	if err := startProvAppliedLooks(ctx, js); err != nil {
 		fmt.Printf("plans: the provisioner clients' words could not be watched (%v); a walk waits for them until the next look\n", err)
 	}
-	if err := startPlanMovedLooks(ctx, js); err != nil {
+	if err := startPlanMovedLooks(ctx, js, open); err != nil {
 		fmt.Printf("plans: the plans moved by other processes could not be followed (%v)\n", err)
 	}
 	done := startPlanLooks(ctx, open)
@@ -209,6 +209,10 @@ func servingPlanSaved(ctx context.Context, bus link.Bus, open *stores) func(*inv
 		keepBuildingKey(ctx, p)
 		if p.WalkSaid == inventory.WalkEnded {
 			go forgetChecksOfWalk(context.WithoutCancel(ctx), open.inventory, p)
+			// A first build refused for a word only a newer build-agent reads is asked again (novox/hq issue 1173).
+			if deliversBuildAgent(p) {
+				go askHeldFirstBuildsAgain(context.WithoutCancel(ctx), open, p)
+			}
 		}
 	}
 }
@@ -563,7 +567,7 @@ func startProvAppliedLooks(ctx context.Context, js *broker.JetStream) error {
 // `plan-moved`, so a plan a person moved with a verb at the control node's terminal — a process this one did not spawn,
 // whose saves it does not hear — is looked at all the same (novox/hq ADR 0406 §2, §5, issue 974). New messages only; the
 // first look reads the rest. A look its own save asks is the same look: asks are one.
-func startPlanMovedLooks(ctx context.Context, js *broker.JetStream) error {
+func startPlanMovedLooks(ctx context.Context, js *broker.JetStream, open *stores) error {
 	api, err := jetstream.New(js.Conn())
 	if err != nil {
 		return err
@@ -578,7 +582,18 @@ func startPlanMovedLooks(ctx context.Context, js *broker.JetStream) error {
 	if err != nil {
 		return fmt.Errorf("following the plans moved: %w", err)
 	}
-	consuming, err := consumer.Consume(func(jetstream.Msg) { askToLook() })
+	var bus link.Bus
+	if core, err := js.Conn().JetStream(); err == nil {
+		bus = link.OverNATS{Conn: js.Conn(), JS: core}
+	}
+	consuming, err := consumer.Consume(func(m jetstream.Msg) {
+		askToLook()
+		if bus != nil && open != nil {
+			// A walk's start or end, said by this controller or a verb: said again with the machines whose
+			// declaration it changes (novox/hq ADR 0505 §2, walk_declared.go).
+			go sayDeclared(context.WithoutCancel(ctx), bus, open, m.Data())
+		}
+	})
 	if err != nil {
 		return fmt.Errorf("following the plans moved: %w", err)
 	}

cmd/mesh-controller/plan_looks_integration_test.go

@@ -174,7 +174,7 @@ func TestAPlanMovedByAnotherProcessAsksForALook(t *testing.T) {
 	ctx, stop := context.WithCancel(context.Background())
 	defer stop()
 	go l.run(ctx)
-	if err := startPlanMovedLooks(ctx, js); err != nil {
+	if err := startPlanMovedLooks(ctx, js, nil); err != nil {
 		t.Fatal(err)
 	}
 	legacy, err := js.Conn().JetStream()

cmd/mesh-controller/plan_moved_every_writer_test.go

@@ -31,7 +31,8 @@ func TestNoPlanIsWrittenButThroughSavePlansMoving(t *testing.T) {
 				return err
 			}
 			text := string(raw)
-			if write.MatchString(text) {
+			// The regular expression is the costly part of reading every source: only a file that names the table can match.
+			if strings.Contains(strings.ToLower(text), "release_plan") && write.MatchString(text) {
 				found = append(found, path+" writes the plan table")
 			}
 			// A plan record is written by the bucket's raw create and update, which only the plans' own file calls.

cmd/mesh-controller/planner_records_test.go

@@ -52,7 +52,7 @@ func TestASharedRepositoryIsPlannedFromTheRecordedBuildSources(t *testing.T) {
 		{Repository: "novox/mesh-controller", Ref: "main", Paths: append([]string{"cmd/mesh-builder/", "internal/broker/"}, gomod...)}}
 	sourcesOf["route-proxy"] = []inventory.BuildSource{
 		{Paths: []string{"modules/route-proxy/Dockerfile", "modules/route-proxy/module.json"}},
-		{Repository: "novox/mesh-controller", Ref: "main", Paths: append([]string{"examples/route-proxy/", "internal/broker/"}, gomod...)}}
+		{Repository: "novox/mesh-controller", Ref: "main", Paths: append([]string{"modules/route-proxy/cmd/route-proxy/", "internal/broker/"}, gomod...)}}
 	register(catalogue.Manifest{Module: "mesh-controller", Version: "1"}, "novox/mesh-controller", "", nil, nil)
 	register(agent, "novox/mesh-catalog", "modules/build-agent", nil, controllerRead)
 	register(catalogue.Manifest{Module: "route-proxy", Version: "1"}, "novox/mesh-catalog", "modules/route-proxy", nil, controllerRead)
@@ -133,7 +133,7 @@ func TestASharedRepositoryIsPlannedFromTheRecordedBuildSources(t *testing.T) {
 		{"a package only the controller builds from: the controller alone", "mesh-controller",
 			[]string{"internal/conditions/condition.go"}, "mesh-controller", true},
 		{"the route proxy's program: the route proxy alone", "mesh-controller",
-			[]string{"examples/route-proxy/main.go"}, "route-proxy", true},
+			[]string{"modules/route-proxy/cmd/route-proxy/main.go"}, "route-proxy", true},
 		{"a package all three build from: all three", "mesh-controller",
 			[]string{"internal/broker/broker.go"}, "mesh-controller,route-proxy | build-agent", false},
 		{"the route proxy's directory in the catalogue: it alone", "mesh-catalog",

cmd/mesh-controller/planner_rules_test.go

@@ -259,7 +259,7 @@ func TestASharedRepositoryMovesOnlyWhatItsBuildSourceHolds(t *testing.T) {
 			{Own: true, Paths: []string{"modules/build-agent/Dockerfile", "modules/build-agent/module.json"}},
 		},
 		"route-proxy": {
-			{Repository: "novox/mesh-controller", Ref: "main", Paths: with("examples/route-proxy/", "internal/broker/",
+			{Repository: "novox/mesh-controller", Ref: "main", Paths: with("modules/route-proxy/cmd/route-proxy/", "internal/broker/",
 				"vendor/github.com/nats-io/nats.go/")},
 			{Own: true, Paths: []string{"modules/route-proxy/Dockerfile", "modules/route-proxy/module.json"}},
 		},
@@ -288,7 +288,7 @@ func TestASharedRepositoryMovesOnlyWhatItsBuildSourceHolds(t *testing.T) {
 		{"a README of the controller's repository: no module (338)", "mesh-controller",
 			[]string{"README.md"}, read, "", "README.md"},
 		{"the route proxy's program alone: the route proxy alone (338)", "mesh-controller",
-			[]string{"examples/route-proxy/main.go"}, read, "route-proxy", ""},
+			[]string{"modules/route-proxy/cmd/route-proxy/main.go"}, read, "route-proxy", ""},
 		{"the build seat's program alone: its holder alone", "mesh-controller",
 			[]string{"cmd/mesh-builder/main.go"}, read, "build-agent", ""},
 		{"a package the build seat's program and the controller build from: both", "mesh-controller",
@@ -305,7 +305,7 @@ func TestASharedRepositoryMovesOnlyWhatItsBuildSourceHolds(t *testing.T) {
 		{"go.sum: all three", "mesh-controller",
 			[]string{"go.sum"}, read, "mesh-controller,route-proxy | build-agent", ""},
 		{"a file added to the proxy's package: the proxy", "mesh-controller",
-			[]string{"examples/route-proxy/new.go"}, read, "route-proxy", ""},
+			[]string{"modules/route-proxy/cmd/route-proxy/new.go"}, read, "route-proxy", ""},
 		// Before any build source is said: as before.
 		{"no build source said: a README moves all three, as before", "mesh-controller",
 			[]string{"README.md"}, unsaid, "mesh-controller,route-proxy | build-agent", ""},
@@ -345,7 +345,7 @@ func TestAModuleAPlanOvertookIsReadWhole(t *testing.T) {
 	built := time.Date(2026, 10, 10, 1, 0, 0, 0, time.UTC)
 	read := map[string][]inventory.ReadRepository{
 		"route-proxy": {
-			{Repository: "novox/mesh-controller", Ref: "main", Paths: []string{"examples/route-proxy/", "go.mod"}, Built: built},
+			{Repository: "novox/mesh-controller", Ref: "main", Paths: []string{"modules/route-proxy/cmd/route-proxy/", "go.mod"}, Built: built},
 			{Own: true, Paths: []string{"modules/route-proxy/module.json"}, Built: built},
 		},
 		"mesh-controller": {{Own: true, Paths: []string{"module.json", "cmd/mesh-controller/"}, Built: built}},
@@ -396,11 +396,11 @@ func TestAMissedMergeMovingOnlyAPackagingModuleIsActedOnOnce(t *testing.T) {
 	}
 	read := map[string][]inventory.ReadRepository{
 		"mesh-controller": {{Own: true, Paths: []string{"module.json", "cmd/mesh-controller/"}, Built: merged.Add(-time.Hour)}},
-		"route-proxy": {{Repository: "novox/mesh-controller", Ref: "main", Paths: []string{"examples/route-proxy/"},
+		"route-proxy": {{Repository: "novox/mesh-controller", Ref: "main", Paths: []string{"modules/route-proxy/cmd/route-proxy/"},
 			Built: merged.Add(-time.Hour), Looked: merged.Add(-time.Hour)}},
 	}
 	m := link.SourceMoved{Owner: "novox", Repo: "mesh-controller", Base: "main", Commit: "c1",
-		MergedAt: merged.Format(time.RFC3339), Paths: []string{"examples/route-proxy/main.go"}}
+		MergedAt: merged.Format(time.RFC3339), Paths: []string{"modules/route-proxy/cmd/route-proxy/main.go"}}
 	if got := wouldMove(m, entries, planningView(read, nil)); len(got) != 1 || got[0].Manifest.Module != "route-proxy" {
 		t.Fatalf("a missed merge of the proxy's program would move %v", got)
 	}
@@ -599,14 +599,14 @@ func TestTheGatePlansFromTheBuildSourcesTheSnapshotCarries(t *testing.T) {
 			Sources: []snapshot.BuildSource{{Own: true, Paths: []string{"module.json", "cmd/mesh-controller/", "internal/broker/"}}}},
 		{Name: "route-proxy", Repository: "novox/mesh-catalog", Path: "modules/route-proxy", Manifest: manifest("route-proxy"),
 			Reads: []string{"novox/mesh-controller"},
-			Sources: []snapshot.BuildSource{{Repository: "novox/mesh-controller", Paths: []string{"examples/route-proxy/", "internal/broker/"}},
+			Sources: []snapshot.BuildSource{{Repository: "novox/mesh-controller", Paths: []string{"modules/route-proxy/cmd/route-proxy/", "internal/broker/"}},
 				{Own: true, Paths: []string{"modules/route-proxy/module.json"}}}},
 	}}
 	for paths, want := range map[string]string{
-		"cmd/mesh-controller/main.go":  "mesh-controller",
-		"examples/route-proxy/main.go": "route-proxy",
-		"internal/broker/broker.go":    "mesh-controller,route-proxy",
-		"README.md":                    "",
+		"cmd/mesh-controller/main.go":                 "mesh-controller",
+		"modules/route-proxy/cmd/route-proxy/main.go": "route-proxy",
+		"internal/broker/broker.go":                   "mesh-controller,route-proxy",
+		"README.md":                                   "",
 	} {
 		r, err := reachOfChange(facts, "novox/mesh-controller", []string{paths}, "")
 		if err != nil {

cmd/mesh-controller/plans_follow.go

@@ -153,7 +153,7 @@ func planWaitCommand(ctx context.Context, inv *inventory.Inventory, id, untilAsk
 	line := planLineSaid(p, now, pause, bounds.of(p.Repository), func(module string) []string {
 		on, _ := inv.Running(ctx, module)
 		return on
-	}, waitsOf(ctx, inv, one))
+	}, waitsOf(ctx, inv, one)) + heldSaid(p, heldNow(ctx, inv))
 	doc := planWaitedDoc(p, planStatuses(one, now, pause, bounds)[0], until, came, now.Sub(began), line)
 	return json.NewEncoder(os.Stdout).Encode(doc)
 }

cmd/mesh-controller/pull_declares.go

@@ -0,0 +1,211 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"path"
+	"reflect"
+	"slices"
+	"time"
+
+	"github.com/nats-io/nats.go"
+
+	"github.com/novox/mesh-controller/internal/broker"
+	"github.com/novox/mesh-controller/internal/inventory"
+	"github.com/novox/mesh-controller/internal/link"
+)
+
+// What the controller tells mesh-config of an open pull request, and asks it back (novox/hq ADR 0502 clauses 2 and 4,
+// issue 1826): a config key a pull request introduces is not declared on the trunk, so a value for it can be judged
+// only against the pull request's own declaration, which the core reads from the forge and mesh-config never does
+// (ADR 0495 §1). The call is mesh-config's `config` verb in the controller's own name, actions `pull-declares` and
+// `held`; the shapes are those of the interface the two sides agreed.
+
+// meshConfigWait is how long the controller waits for mesh-config before it goes on without: a check is never held up
+// by a module that does not answer.
+const meshConfigWait = 10 * time.Second
+
+// meshConfigAsk is one call of mesh-config's `config` verb in the controller's own name, answering its result. A
+// variable so a test needs no bus.
+var meshConfigAsk = func(ctx context.Context, args map[string]any) ([]byte, error) {
+	var result []byte
+	err := onTheBus(func(conn *nats.Conn) error {
+		answer, err := link.AskMeshSeatToolAs(ctx, conn, broker.ControllerName, "mesh-config", "config", args, meshConfigWait)
+		if err != nil {
+			return err
+		}
+		if answer.Error != "" {
+			return fmt.Errorf("%s", answer.Error)
+		}
+		result = answer.Result
+		return nil
+	})
+	return result, err
+}
+
+// pullAt is an open pull request at a head: the change to read, and its number.
+type pullAt struct {
+	changeSource
+	Number int
+}
+
+// pullAtOf is a pull request announced, as the change it makes over what it merges into.
+func pullAtOf(p link.PullUpdated) pullAt {
+	old := p.BaseSHA
+	if old == "" {
+		old = p.Base
+	}
+	return pullAt{Number: p.Number, changeSource: changeSource{Owner: p.Owner, Repo: p.Repo, New: p.Commit, Old: old,
+		Paths: p.Paths, Truncated: p.PathsTruncated, Removed: p.Removed}}
+}
+
+func pullKey(owner, repo string, number int) string {
+	return fmt.Sprintf("%s/%s#%d", owner, repo, number)
+}
+
+func (p pullAt) key() string { return pullKey(p.Owner, p.Repo, p.Number) }
+
+// pullDeclarations are the config declarations a pull request's head adds or changes over what it merges into, by
+// module, in the shape of the declared-config mirror. The bool says the head could be read: false for a pull request whose
+// paths are cut (the caller cuts them to the manifests of the modules it moves) or whose base is unknown, which is then
+// told nothing, never an empty set.
+func pullDeclarations(ctx context.Context, p pullAt) ([]inventory.DeclaredConfigMirrored, bool, error) {
+	var out []inventory.DeclaredConfigMirrored
+	if p.Truncated || p.Old == "" {
+		return nil, false, nil
+	}
+	for _, file := range p.Paths {
+		if path.Base(file) != moduleManifestFile || slices.Contains(p.Removed, file) {
+			continue
+		}
+		now, exists, err := manifestCached(ctx, p.Owner, p.Repo, file, p.New)
+		if err != nil {
+			return nil, false, err
+		}
+		if !exists || now.Module == "" {
+			continue
+		}
+		was, _, err := manifestCached(ctx, p.Owner, p.Repo, file, p.Old)
+		if err != nil {
+			return nil, false, err
+		}
+		have, err := inventory.DeclaredOf(now.Settings)
+		if err != nil {
+			return nil, false, fmt.Errorf("%s at %.8s: %w", file, p.New, err)
+		}
+		had, err := inventory.DeclaredOf(was.Settings)
+		if err != nil {
+			return nil, false, fmt.Errorf("%s at %.8s: %w", file, p.Old, err)
+		}
+		changed := map[string]inventory.DeclaredMirrored{}
+		for key, d := range have {
+			if before, there := had[key]; !there || !reflect.DeepEqual(before, d) {
+				changed[key] = d
+			}
+		}
+		if len(changed) > 0 {
+			out = append(out, inventory.DeclaredConfigMirrored{Module: now.Module, Settings: changed})
+		}
+	}
+	return out, true, nil
+}
+
+// tellPullDeclares tells mesh-config, for each pull request at every announced head, what the head declares, an empty set
+// when it declares nothing new: mesh-config re-judges the values held at every head, so a head that reverts the change
+// drops them (ADR 0502 clause 6). A
+// failure is said to w and the check goes on: the held values are then none (ADR 0502 clause 2).
+func tellPullDeclares(ctx context.Context, w io.Writer, pulls []pullAt) {
+	for _, p := range pulls {
+		mods, readable, err := pullDeclarations(ctx, p)
+		if err != nil {
+			fmt.Fprintf(w, "%s: what its head declares cannot be read, so mesh-config is told nothing: %v\n", p.key(), err)
+			continue
+		}
+		if !readable {
+			continue
+		}
+		declares := map[string]map[string]inventory.DeclaredMirrored{}
+		for _, m := range mods {
+			declares[m.Module] = m.Settings
+		}
+		if _, err := meshConfigAsk(ctx, map[string]any{"action": "pull-declares", "pull": p.key(), "head": p.New,
+			"declares": declares}); err != nil {
+			fmt.Fprintf(w, "%s: mesh-config cannot be told what its head declares (%v); the check goes on without held values\n",
+				p.key(), err)
+		}
+	}
+}
+
+// heldFor asks mesh-config for the approved held values of these pull requests at their heads (ADR 0502 clause 4). Only
+// those of the pull requests asked about are carried. A failure is said to w and answers none.
+func heldFor(ctx context.Context, w io.Writer, pulls []pullAt) []link.HeldConfig {
+	if len(pulls) == 0 {
+		return nil
+	}
+	type pullHead struct {
+		Pull string `json:"pull"`
+		Head string `json:"head"`
+	}
+	asked := make([]pullHead, 0, len(pulls))
+	for _, p := range pulls {
+		asked = append(asked, pullHead{p.key(), p.New})
+	}
+	raw, err := meshConfigAsk(ctx, map[string]any{"action": "held", "pulls": asked})
+	if err != nil {
+		fmt.Fprintf(w, "mesh-config cannot say what it holds for these pull requests (%v); the check goes on without held values\n", err)
+		return nil // empty-on-error: said above; a check without held values fails for want of the value and says so, it never passes on a guess
+	}
+	var answer struct {
+		Held    []link.HeldConfig `json:"held"`
+		Skipped []struct {
+			Pull string `json:"pull"`
+			Why  string `json:"why"`
+		} `json:"skipped"`
+	}
+	if len(raw) == 0 {
+		return nil
+	}
+	if err := json.Unmarshal(raw, &answer); err != nil {
+		fmt.Fprintf(w, "mesh-config's held values cannot be read (%v); the check goes on without them\n", err)
+		return nil // empty-on-error: said above; a check without held values fails for want of the value and says so, it never passes on a guess
+	}
+	for _, s := range answer.Skipped {
+		fmt.Fprintf(w, "%s: mesh-config holds a value it does not carry: %s\n", s.Pull, s.Why)
+	}
+	var out []link.HeldConfig
+	for _, h := range answer.Held {
+		for _, p := range pulls {
+			if h.Pull == p.key() {
+				out = append(out, h)
+				break
+			}
+		}
+	}
+	return out
+}
+
+// withHeldConfig tells mesh-config what these pull requests declare and puts the approved held values of them on the
+// check request (ADR 0502 clause 4). With carry false, a member of a group whose composed check composes, only the
+// declarations are told.
+func withHeldConfig(ctx context.Context, w io.Writer, request *link.BuildRequest, pulls []pullAt, carry bool) {
+	tellPullDeclares(ctx, w, pulls)
+	if carry {
+		carryHeld(ctx, w, request, pulls)
+	}
+}
+
+// carryHeld puts the approved held values of these pull requests on the check request.
+func carryHeld(ctx context.Context, w io.Writer, request *link.BuildRequest, pulls []pullAt) {
+	if request.Check != nil {
+		request.Check.HeldConfig = heldFor(ctx, w, pulls)
+	}
+}
+
+// holdsModules is whether a module of the mesh is built from this repository.
+func holdsModules(entries []inventory.Entry, owner, repo string) bool {
+	return slices.ContainsFunc(entries, func(e inventory.Entry) bool {
+		return sameRepository(e.Source.Repository, link.SourceMoved{Owner: owner, Repo: repo})
+	})
+}

cmd/mesh-controller/pull_declares_test.go

@@ -0,0 +1,209 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"strings"
+	"testing"
+
+	"git.novox.be/novox/mesh-sdk/go/catalogue"
+	"github.com/novox/mesh-controller/internal/inventory"
+	"github.com/novox/mesh-controller/internal/link"
+)
+
+const (
+	headSHA = "2222222222222222222222222222222222222222"
+	baseSHA = "1111111111111111111111111111111111111111"
+)
+
+// fakeManifests serves manifests by ref, and counts what the forge was asked. Issue 1826/AC1 (unit level).
+func fakeManifests(t *testing.T, at map[string]*catalogue.Manifest) {
+	t.Helper()
+	was := manifestAt
+	t.Cleanup(func() { manifestAt = was })
+	manifestsReadMu.Lock()
+	clear(manifestsRead)
+	manifestsReadMu.Unlock()
+	manifestAt = func(_ context.Context, _, _, _, ref string) (catalogue.Manifest, bool, error) {
+		if m := at[ref]; m != nil {
+			return *m, true, nil
+		}
+		return catalogue.Manifest{}, false, nil
+	}
+}
+
+// fakeConfig records the calls to mesh-config and answers each action from answers.
+func fakeConfig(t *testing.T, answers map[string]string) *[]map[string]any {
+	t.Helper()
+	var calls []map[string]any
+	was := meshConfigAsk
+	t.Cleanup(func() { meshConfigAsk = was })
+	meshConfigAsk = func(_ context.Context, args map[string]any) ([]byte, error) {
+		calls = append(calls, args)
+		return []byte(answers[args["action"].(string)]), nil
+	}
+	return &calls
+}
+
+func manifest(module string, keys map[string]catalogue.SettingDeclaration) *catalogue.Manifest {
+	return &catalogue.Manifest{Module: module, Settings: keys}
+}
+
+func thePull() pullAt {
+	return pullAt{Number: 434, changeSource: changeSource{Owner: "novox", Repo: "mesh-catalog", New: headSHA, Old: baseSHA,
+		Paths: []string{"modules/n8n/module.json", "modules/n8n/README.md"}}}
+}
+
+// 1826/AC1: a key the head adds is sent with its declaration, under the pull request and the head.
+func TestAKeyThePullRequestAddsIsToldToMeshConfig(t *testing.T) {
+	fakeManifests(t, map[string]*catalogue.Manifest{
+		baseSHA: manifest("n8n", map[string]catalogue.SettingDeclaration{"port": {Type: "number"}}),
+		headSHA: manifest("n8n", map[string]catalogue.SettingDeclaration{"port": {Type: "number"},
+			"media-gid": {Type: "number", Required: true}}),
+	})
+	calls := fakeConfig(t, map[string]string{"pull-declares": `{"kept":1}`})
+	tellPullDeclares(context.Background(), io.Discard, []pullAt{thePull()})
+	if len(*calls) != 1 {
+		t.Fatalf("mesh-config was asked %d times: %v", len(*calls), *calls)
+	}
+	c := (*calls)[0]
+	if c["action"] != "pull-declares" || c["pull"] != "novox/mesh-catalog#434" || c["head"] != headSHA {
+		t.Fatalf("the call is %v", c)
+	}
+	body, _ := json.Marshal(c["declares"])
+	var declares map[string]map[string]inventory.DeclaredMirrored
+	if err := json.Unmarshal(body, &declares); err != nil || len(declares) != 1 || declares["n8n"] == nil {
+		t.Fatalf("declares %s: %v", body, err)
+	}
+	mods := []inventory.DeclaredConfigMirrored{{Module: "n8n", Settings: declares["n8n"]}}
+	if _, has := mods[0].Settings["port"]; has || len(mods[0].Settings) != 1 {
+		t.Fatalf("only the added key is told, got %v", mods[0].Settings)
+	}
+	d := mods[0].Settings["media-gid"]
+	if d.Type != "number" || !d.Required {
+		t.Fatalf("the declaration is %+v", d)
+	}
+}
+
+// 1826/AC1: a key whose declaration the head changes is sent; one it leaves as it was is not.
+func TestAnUnchangedKeyIsNotToldAndAChangedOneIs(t *testing.T) {
+	fakeManifests(t, map[string]*catalogue.Manifest{
+		baseSHA: manifest("n8n", map[string]catalogue.SettingDeclaration{"port": {Type: "number"}, "x": {Type: "string"}}),
+		headSHA: manifest("n8n", map[string]catalogue.SettingDeclaration{"port": {Type: "number"}, "x": {Type: "string", Pattern: "a+"}}),
+	})
+	mods, touched, err := pullDeclarations(context.Background(), thePull())
+	if err != nil || !touched || len(mods) != 1 || len(mods[0].Settings) != 1 || mods[0].Settings["x"].Pattern != "a+" {
+		t.Fatalf("%+v %v %v", mods, touched, err)
+	}
+}
+
+// 1826/AC1: a head that changes no module.json, or removes it, is still told, with declares {}: mesh-config re-judges at every
+// head, so a head that reverts the change drops the value held for it (review round 1, finding 1).
+func TestAHeadThatDeclaresNothingIsToldAsEmpty(t *testing.T) {
+	fakeManifests(t, map[string]*catalogue.Manifest{baseSHA: manifest("n8n", nil), headSHA: manifest("n8n", nil)})
+	calls := fakeConfig(t, nil)
+	p := thePull()
+	p.Paths = []string{"modules/n8n/README.md"}
+	tellPullDeclares(context.Background(), io.Discard, []pullAt{p})
+	p = thePull()
+	p.Removed = p.Paths
+	tellPullDeclares(context.Background(), io.Discard, []pullAt{p})
+	if len(*calls) != 2 {
+		t.Fatalf("mesh-config was told %v", *calls)
+	}
+	for _, c := range *calls {
+		if d, _ := json.Marshal(c["declares"]); string(d) != "{}" || c["head"] != headSHA {
+			t.Fatalf("told %v", c)
+		}
+	}
+}
+
+// 1826/AC1: a head whose paths are cut, or whose base is unknown, cannot be read: nothing is told, never an empty set.
+func TestAHeadThatCannotBeReadIsNotToldAsEmpty(t *testing.T) {
+	calls := fakeConfig(t, nil)
+	p := thePull()
+	p.Truncated = true
+	tellPullDeclares(context.Background(), io.Discard, []pullAt{p})
+	if len(*calls) != 0 {
+		t.Fatalf("told %v", *calls)
+	}
+}
+
+// 1826/AC1: a module.json changed without a declaration changing is told as an empty set, so mesh-config re-judges what it holds.
+func TestAChangedManifestWithNoNewDeclarationIsToldAsEmpty(t *testing.T) {
+	m := manifest("n8n", map[string]catalogue.SettingDeclaration{"port": {Type: "number"}})
+	fakeManifests(t, map[string]*catalogue.Manifest{baseSHA: m, headSHA: m})
+	calls := fakeConfig(t, nil)
+	tellPullDeclares(context.Background(), io.Discard, []pullAt{thePull()})
+	if len(*calls) != 1 {
+		t.Fatalf("calls %v", *calls)
+	}
+	if d, _ := json.Marshal((*calls)[0]["declares"]); string(d) != "{}" {
+		t.Fatalf("declares %s", d)
+	}
+}
+
+// 1826/AC1: mesh-config not answering is said and goes on; the check is not stopped.
+func TestMeshConfigNotAnsweringIsSaidAndGoneOn(t *testing.T) {
+	fakeManifests(t, map[string]*catalogue.Manifest{baseSHA: manifest("n8n", nil),
+		headSHA: manifest("n8n", map[string]catalogue.SettingDeclaration{"k": {Type: "string"}})})
+	was := meshConfigAsk
+	t.Cleanup(func() { meshConfigAsk = was })
+	meshConfigAsk = func(context.Context, map[string]any) ([]byte, error) { return nil, io.ErrUnexpectedEOF }
+	var said strings.Builder
+	tellPullDeclares(context.Background(), &said, []pullAt{thePull()})
+	got := heldFor(context.Background(), &said, []pullAt{thePull()})
+	if len(got) != 0 || !strings.Contains(said.String(), "mesh-config") {
+		t.Fatalf("held %v, said %q", got, said.String())
+	}
+}
+
+// 1826/AC2: the held values mesh-config answers for the check's pull requests are what the check request carries.
+func TestTheHeldValuesOfTheChecksPullRequestsAreAsked(t *testing.T) {
+	calls := fakeConfig(t, map[string]string{"held": `{"held":[{"pull":"novox/mesh-catalog#434","head":"` + headSHA +
+		`","node":"ace","module":"n8n","key":"media-gid","value":2000,"approved":"the operator"}]}`})
+	other := pullAt{Number: 7, changeSource: changeSource{Owner: "novox", Repo: "mesh-controller", New: baseSHA}}
+	got := heldFor(context.Background(), io.Discard, []pullAt{thePull(), other})
+	if len(got) != 1 || got[0].Node != "ace" || got[0].Key != "media-gid" || string(got[0].Value) != "2000" {
+		t.Fatalf("got %+v", got)
+	}
+	c := (*calls)[0]
+	pulls, _ := json.Marshal(c["pulls"])
+	if c["action"] != "held" || string(pulls) != `[{"pull":"novox/mesh-catalog#434","head":"`+headSHA+
+		`"},{"pull":"novox/mesh-controller#7","head":"`+baseSHA+`"}]` {
+		t.Fatalf("asked %v %s", c, pulls)
+	}
+}
+
+// 1826/AC2: a value held for a pull request the check is not of is never carried.
+func TestAHeldValueOfAnotherPullRequestIsNotCarried(t *testing.T) {
+	fakeConfig(t, map[string]string{"held": `{"held":[{"pull":"novox/mesh-catalog#999","head":"x","node":"ace","module":"n8n","key":"k","value":1}]}`})
+	if got := heldFor(context.Background(), io.Discard, []pullAt{thePull()}); len(got) != 0 {
+		t.Fatalf("carried %+v", got)
+	}
+}
+
+// 1826/AC2: the check request carries what mesh-config answered; a member of a composed group asks none.
+func TestTheCheckRequestCarriesTheHeldValues(t *testing.T) {
+	fakeManifests(t, map[string]*catalogue.Manifest{baseSHA: manifest("n8n", nil), headSHA: manifest("n8n", nil)})
+	fakeConfig(t, map[string]string{"held": `{"held":[{"pull":"novox/mesh-catalog#434","node":"ace","module":"n8n","key":"media-gid","value":2000}]}`})
+	request := link.BuildRequest{Check: &link.CheckRequest{}}
+	withHeldConfig(context.Background(), io.Discard, &request, []pullAt{thePull()}, true)
+	if len(request.Check.HeldConfig) != 1 || request.Check.HeldConfig[0].Key != "media-gid" {
+		t.Fatalf("the request carries %+v", request.Check.HeldConfig)
+	}
+	request = link.BuildRequest{Check: &link.CheckRequest{}}
+	withHeldConfig(context.Background(), io.Discard, &request, []pullAt{thePull()}, false)
+	if len(request.Check.HeldConfig) != 0 {
+		t.Fatalf("a composed member carries %+v", request.Check.HeldConfig)
+	}
+}
+
+// 1826/AC1: a repository that builds a module of the mesh holds modules; another does not.
+func TestARepositoryThatBuildsAModuleHoldsModules(t *testing.T) {
+	entries := []inventory.Entry{{Manifest: catalogue.Manifest{Module: "a"}, Source: inventory.Source{Repository: "novox/mesh-catalog", Path: "modules/a"}}}
+	if !holdsModules(entries, "novox", "mesh-catalog") || holdsModules(entries, "novox", "hq") {
+		t.Fatal("wrong")
+	}
+}

cmd/mesh-controller/push.go

@@ -281,7 +281,7 @@ func serve(ctx context.Context) (err error) {
 	// The provisioner's plan of each handed module, as its machine was last sent it (design 57 P6), in the module's
 	// assignment.
 	inv.SetProvisioningPlans(inv.SentProvisioningPlans)
-	go mirroringRecords(ctx, inv, bus.Conn, bus)
+	go mirroringRecords(ctx, open, inv, bus.Conn, bus)
 	// And the bucket of the files that travel by digest, judged against what each machine's latest declaration names (ADR 0486 §3).
 	go sweepingDeclarationFiles(ctx, inv, bus.Conn)
 	// And the key of each plan in its build phase, which holds the build seat's checks while a delivery builds (ADR 0483 clause 2).

cmd/mesh-controller/record_mirrors.go

@@ -7,6 +7,7 @@ import (
 	"sort"
 	"time"
 
+	"git.novox.be/novox/mesh-sdk/go/compose"
 	"github.com/nats-io/nats.go"
 	"github.com/nats-io/nats.go/jetstream"
 
@@ -29,7 +30,7 @@ import (
 const mirrorEvery = 10 * time.Second
 
 // mirroringRecords keeps the mirrors current for as long as this controller serves: ctx ends when it stops.
-func mirroringRecords(ctx context.Context, inv *inventory.Inventory, conn *nats.Conn, announce recordmirror.Announcer) {
+func mirroringRecords(ctx context.Context, open *stores, inv *inventory.Inventory, conn *nats.Conn, announce recordmirror.Announcer) {
 	api, err := jetstream.New(conn)
 	if err != nil {
 		fmt.Printf("the record mirrors are not kept: %v\n", err)
@@ -44,8 +45,9 @@ func mirroringRecords(ctx context.Context, inv *inventory.Inventory, conn *nats.
 		return e
 	}
 	sources := map[string]func(context.Context) (map[string][]byte, error){
-		recordmirror.DeclaredConfig.Name: inv.DeclaredConfigMirror,
-		recordmirror.Predefined.Name:     inv.PredefinedMirror,
+		recordmirror.DeclaredConfig.Name:   inv.DeclaredConfigMirror,
+		recordmirror.Predefined.Name:       inv.PredefinedMirror,
+		recordmirror.DeclaredPackages.Name: declaredPackagesMirror(open),
 	}
 	writers := map[string]*recordmirror.Writer{}
 	failing := map[string]string{}
@@ -176,3 +178,36 @@ func keepingAssignments(ctx context.Context, inv *inventory.Inventory, announce
 	}
 	events.known = now
 }
+
+// declaredPackagesMirror is the source of the declared-packages mirror (ADR 0507 §5): each node's composition, asked as a
+// question that makes nothing, and the packages it declares with the modules that declare them. A node whose own set does
+// not compose has no key, and any other failure to read is the pass's error, so a key is never purged for a store that
+// could not be read.
+func declaredPackagesMirror(open *stores) func(context.Context) (map[string][]byte, error) {
+	return func(ctx context.Context) (map[string][]byte, error) {
+		in, err := inputFor(ctx, open)
+		if err != nil {
+			return nil, err
+		}
+		// Which module owns each resource is carried only for a node-engine that reads it, so every node is asked as one that does.
+		asked := in.Input
+		asked.Nodes = append([]compose.Node(nil), in.Nodes...)
+		for i := range asked.Nodes {
+			asked.Nodes[i].ReadsModules = true
+		}
+		out := map[string][]byte{}
+		for _, n := range in.sortedNodes() {
+			d, _, err := compose.ComposeIn(asked, n.Name, compose.Foreseeing)
+			if compose.IsUnresolvable(err) {
+				continue
+			}
+			if err != nil {
+				return nil, fmt.Errorf("the packages %s declares cannot be read: %w", n.Name, err)
+			}
+			if out[n.Name], err = inventory.DeclaredPackagesValue(n.Name, d.Resources, d.ModuleOf); err != nil {
+				return nil, err
+			}
+		}
+		return out, nil
+	}
+}

cmd/mesh-controller/recorded_moves.go

@@ -181,15 +181,24 @@ func planModuleNames(p inventory.Plan) map[string]string {
 	return out
 }
 
-// recordedWaiting is, on one machine, every move of a recorded module that waits for a person, each said with why
-// (ADR 0377 §6): what `status` names the machine behind for, with `push <node>` as the remedy. A move under a
-// module's own `record` that recreates nothing and moves no data is not among them: it goes with its walk.
-func recordedWaiting(ctx context.Context, inv *inventory.Inventory, f moveFacts, node string) ([]string, error) {
+// heldMove is one move of a recorded module that waits for a person on one machine (ADR 0377 §6).
+type heldMove struct {
+	Module   string
+	From, To string
+	// Why is the walk's own word for it: "waits: " and the recreate words, the data change, or the hold.
+	Why string
+	// Chosen is whether a person's own choice holds it — a module they set to record, or the bus's step — which the
+	// operator is not asked about again: they chose that hold, and the bus has its own condition (S17).
+	Chosen bool
+}
+
+// heldMovesOn is, on one machine, every move of a recorded module that waits for a person, in module order.
+func heldMovesOn(ctx context.Context, inv *inventory.Inventory, f moveFacts, node string) ([]heldMove, error) {
 	sent, known, err := inv.SentBuilds(ctx, node)
 	if err != nil || !known {
 		return nil, err
 	}
-	var out []string
+	var out []heldMove
 	for _, m := range sortedKeysOf(sent) {
 		was := sent[m]
 		now, held := f.current[m]
@@ -197,12 +206,25 @@ func recordedWaiting(ctx context.Context, inv *inventory.Inventory, f moveFacts,
 			continue
 		}
 		if v := f.recordedMove(m, was); !v.rolls {
-			out = append(out, fmt.Sprintf("%s %s → %s %s", m, short(was), short(now.Commit), v.said))
+			out = append(out, heldMove{Module: m, From: was, To: now.Commit, Why: v.said,
+				Chosen: now.From == catalogue.FromPerson || now.From == catalogue.FromBus})
 		}
 	}
 	return out, nil
 }
 
+// recordedWaiting is, on one machine, every move of a recorded module that waits for a person, each said with why
+// (ADR 0377 §6): what `status` names the machine behind for, with `push <node>` as the remedy. A move under a
+// module's own `record` that recreates nothing and moves no data is not among them: it goes with its walk.
+func recordedWaiting(ctx context.Context, inv *inventory.Inventory, f moveFacts, node string) ([]string, error) {
+	moves, err := heldMovesOn(ctx, inv, f, node)
+	var out []string
+	for _, h := range moves {
+		out = append(out, fmt.Sprintf("%s %s → %s %s", h.Module, short(h.From), short(h.To), h.Why))
+	}
+	return out, err
+}
+
 // stringsKeys is a map of lists as a map of its keys, for sortedKeysOf.
 func stringsKeys(m map[string][]string) map[string]string {
 	out := map[string]string{}

cmd/mesh-controller/release.go

@@ -1371,6 +1371,10 @@ func backlogObservation() []conditions.Observation {
 			"them, `upgrade release-backlog --why …` releases them", n, strings.Join(machines, ", "), backlogNow.held)}
 	w := releaseHeldWords(modules, machines)
 	o.Headline, o.Explanation, o.Resolved, o.Needs = w.Headline, w.Explanation, w.Resolved, w.Needs
+	// Asked of the operator, who releases them with an Approve (novox/hq issue 1732): the controller's own
+	// `upgrade release-backlog`, which opens the release plan that walks them through the machines, each judged.
+	o.Actions = []conditions.Action{{Label: "Release", Verb: "mesh-controller.upgrade", Level: conditions.LevelApprove,
+		Arguments: map[string]string{"release-backlog": "true", "why": "", "cause": conditions.CauseOperatorAnswer}}}
 	return []conditions.Observation{o}
 }
 

cmd/mesh-controller/release_plan.go

@@ -2064,6 +2064,12 @@ func planLineSaid(p inventory.Plan, now time.Time, pause pauseView, bound time.D
 		// refused ("a build waits there for its gate: <machine> (...)") is kept there. "building" with LATE
 		// hid that reason from `plans`, `status` and the stalled condition (novox/hq issue 920).
 		what = p.Note
+		// And when the builds are held after a failed release, they wait for a person, not for a build, and the
+		// operator is asked to release them (novox/hq issue 1732): said so, and not late.
+		if strings.Contains(p.Note, errUngated.Error()) && backlogNow.held != "" {
+			what += " — held after a failed delivery until a person releases it (the operator is asked)"
+			late = ""
+		}
 		return fmt.Sprintf("%s · %s, held: %s, for %s%s", name, where, what, since, late)
 	}
 	return fmt.Sprintf("%s · %s, %s for %s%s", name, where, what, since, late)
@@ -2271,7 +2277,7 @@ func plansCommand(ctx context.Context, args []string) error {
 			bounds.of(p.Repository), func(module string) []string {
 				on, _ := inv.Running(ctx, module)
 				return on
-			}, waitsOf(ctx, inv, []inventory.Plan{p})))
+			}, waitsOf(ctx, inv, []inventory.Plan{p}))+heldSaid(p, heldNow(ctx, inv)))
 		if r := p.Release; r != nil {
 			// A release plan's walk (ADR 0236): machines done, the one judged, those to come.
 			fmt.Printf("  machines in order: %s; done: %s; skipped: %s\n", strings.Join(r.Order, ", "),
@@ -2466,11 +2472,12 @@ func plansCommand(ctx context.Context, args []string) error {
 		return on
 	}
 	waits := waitsOf(ctx, inv, plans)
+	held := heldNow(ctx, inv)
 	for _, p := range plans {
 		if p.Batch() {
 			continue
 		}
-		fmt.Printf("%-28s %s\n", p.ID, planLineSaid(p, now, pause, bounds.of(p.Repository), running, waits))
+		fmt.Printf("%-28s %s%s\n", p.ID, planLineSaid(p, now, pause, bounds.of(p.Repository), running, waits), heldSaid(p, held))
 	}
 	return nil
 }

cmd/mesh-controller/replay867_test.go

@@ -46,6 +46,11 @@ func replay867(t *testing.T, recheck bool) {
 	if _, err := exec.LookPath("go"); err != nil {
 		t.Skip("no Go toolchain on this machine to build a judge with")
 	}
+	// The check's floor of free space (novox/hq issue 1834) reads the disk the test runs on, which is none of this
+	// replay's business: a build node under the floor failed every mesh-controller check here (issue 1834, note 12).
+	wasFree := builder.FreeBytes
+	builder.FreeBytes = func(string) (uint64, error) { return 500 << 30, nil }
+	t.Cleanup(func() { builder.FreeBytes = wasFree })
 	r := theGroupOfIssue867(t)
 	for _, c := range []struct {
 		what, repo string

cmd/mesh-controller/sayable_test.go

@@ -152,7 +152,7 @@ func answersRightly(q dnsmessage.Question) *dnsmessage.Message {
 func quickResolvers(t *testing.T, port string) {
 	t.Helper()
 	before, within, pause := resolverPort, resolverWithin, resolverPause
-	resolverPort, resolverWithin, resolverPause = port, 150*time.Millisecond, 10*time.Millisecond
+	resolverPort, resolverWithin, resolverPause = port, 60*time.Millisecond, 5*time.Millisecond
 	t.Cleanup(func() { resolverPort, resolverWithin, resolverPause = before, within, pause })
 }
 

cmd/mesh-controller/signals.go

@@ -244,6 +244,22 @@ var signalsTable = []signalRow{
 		newest: func(f *signalFacts) time.Time {
 			return newestOf(f.failed, func(p failedPlanFacts) time.Time { return p.since })
 		}},
+	{Row: "S24", Signal: "a move of a recorded module that waits for a person's push is asked of the operator",
+		Emitter: "controller's plan", Trigger: "each machine with a move of a recorded module held for a person (novox/hq ADR 0377, issue 1732)",
+		Bound: "none: raised on the first look that finds the machine holding such a move, naming the modules and the " +
+			"machine, with Release (the machine's push) as the answer; ended when the machine no longer waits, whoever " +
+			"pushed it. A hold a person chose (a module set to record with a why, the bus) is not asked.",
+		Kind: kindMovesHeld, Severity: conditions.Warning, Phase: 3,
+		needs: func(f *signalFacts) error { return f.heldErr }, watch: watchMovesHeld,
+		newest: func(f *signalFacts) time.Time { return time.Time{} }},
+	{Row: "S25", Signal: "a module left out of a send because the artifact store lacks an image it names",
+		Emitter: "controller's send", Trigger: "each send whose declaration names an image of the store that the store does not hold (novox/hq issue 1742)",
+		Bound: "none: raised on the first look at a registered build that names such an image, naming the module, each " +
+			"machine that runs it and the image; every send leaves that module out; the store is asked again at each " +
+			"look and the condition ends when it holds the image",
+		Kind: kindImageMissing, Severity: conditions.Warning, Phase: 3,
+		needs: func(f *signalFacts) error { return f.imagesErr }, watch: watchMissingImages,
+		newest: func(f *signalFacts) time.Time { return time.Time{} }},
 	{Row: "S20", Signal: "a send refused for the assignment generation it was composed from",
 		Emitter: "node-engine", Trigger: "each refusal (novox/hq issue 234)",
 		Bound: "none: raised at the first refusal, naming its sender, the generation it came from and the one the " +

cmd/mesh-controller/signals_test.go

@@ -171,6 +171,19 @@ var suppressions = map[string]suppression{
 				since: f.now.Add(-time.Second)}}
 		},
 	},
+	// A machine holding a move of a recorded module for a person is asked at its first look (novox/hq issue 1732).
+	// Inside: nothing waits there.
+	"S24": {
+		inside: func(f *signalFacts) { f.held = nil },
+		past:   func(f *signalFacts) { f.held = []heldFacts{aHeldMailu()} },
+	},
+	// A registered build naming an image the artifact store lacks is raised at the first look (novox/hq issue 1742).
+	"S25": {
+		inside: func(f *signalFacts) { f.images = nil },
+		past: func(f *signalFacts) {
+			f.images = []imageFacts{{missingImage{Node: "anchor", Module: "automx", Image: automxImage}}}
+		},
+	},
 	// A batch queued behind an open walk past that walk's bound, named.
 	"S19": {
 		inside: func(f *signalFacts) {

cmd/mesh-controller/walk_declared.go

@@ -0,0 +1,163 @@
+package main
+
+// The machines whose declaration a walk's merges change (novox/hq ADR 0505 §2): beside what the walk sends, a merge
+// can change what another machine is to run — an assignment, a provision or a requirement added or removed — and a
+// problem raised there as the walk runs, or as it settles, is the walk's as much as one on a machine it sends to. The
+// router holds what a walk touches (ADR 0308 §1); these are touches of their own, marked `declared`.
+//
+// **Compared as the mesh compares whether a machine is up to date.** Each machine's declaration is composed as a push
+// would compose it, with the number, epoch and generation it was last sent, and its digest held against the one it was
+// last sent (wouldSend, inventory.Waiting): byte for byte what it was sent when nothing changed, so a secret, a sequence
+// or a lease's epoch never makes a machine differ by itself. A machine whose declaration cannot be worked out now and
+// was sent one before is taken as changed: not known is changed, never "unchanged" (a merge that leaves a machine
+// unable to compose is the case this exists for, the 11:03 message of ADR 0505's context).
+//
+// **Said again, not waited for.** Composing every machine takes seconds; the walk's start and end are said at once as
+// before, and the serving controller, which hears every `plan-moved` — its own and a verb's — says a start or an end
+// again with the declared touches added, marked `declared_read`, which it never reads twice. The router merges a walk
+// said again (messenger walks.go).
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"sort"
+	"time"
+
+	"github.com/novox/mesh-controller/internal/inventory"
+	"github.com/novox/mesh-controller/internal/link"
+)
+
+// walkDeclaredRead marks a walk's start or end said again with its declared touches: read once.
+const walkDeclaredRead = "declared_read"
+
+// declaredWithin bounds the comparison of every machine for one walk's start or end.
+const declaredWithin = time.Minute
+
+// changedDeclarations is every machine whose declaration differs from what it was last sent, and every machine sent
+// one before whose declaration cannot be worked out now. A seam a test replaces.
+var changedDeclarations = func(ctx context.Context, open *stores) ([]string, error) {
+	nodes, err := open.inventory.Nodes(ctx)
+	if err != nil {
+		return nil, err
+	}
+	ctx = withInputCache(ctx)
+	would, err := wouldSend(ctx, open, nodes)
+	if err != nil {
+		return nil, err
+	}
+	behind, err := open.inventory.Waiting(ctx, would)
+	if err != nil {
+		return nil, err
+	}
+	sent := map[string]bool{}
+	for _, n := range nodes {
+		if s, known, err := open.inventory.SentTo(ctx, n.Name); err == nil && known && s.Digest != "" {
+			sent[n.Name] = true
+		}
+	}
+	return changedOf(nodes, would, behind, sent), nil
+}
+
+// changedOf is changedDeclarations over what was read: the machines behind, and those sent one before that could not
+// be worked out. Pure; sorted.
+func changedOf(nodes []inventory.Node, would map[string]string, behind []inventory.Machine, sent map[string]bool) []string {
+	set := map[string]bool{}
+	for _, m := range behind {
+		set[m.Node] = true
+	}
+	for _, n := range nodes {
+		if _, worked := would[n.Name]; !worked && sent[n.Name] {
+			set[n.Name] = true
+		}
+	}
+	out := make([]string, 0, len(set))
+	for n := range set {
+		out = append(out, n)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// withDeclared is a walk's start or end said again with the machines whose declaration changed added as declared
+// touches: false when the body says no start or end, was said again already, or names no machine it does not touch.
+func withDeclared(body []byte, changed []string) ([]byte, bool, error) {
+	said, wanted, err := toSayAgain(body)
+	if err != nil || !wanted {
+		return nil, false, err
+	}
+	var touches []walkTouch
+	if raw := said["touches"]; raw != nil && string(raw) != "null" {
+		if err := json.Unmarshal(raw, &touches); err != nil {
+			return nil, false, fmt.Errorf("its touches are not a list of {machine, modules}: %w", err)
+		}
+	}
+	added := declaredTouches(touches, changed)
+	if len(added) == 0 {
+		return nil, false, nil
+	}
+	touches = append(touches, added...)
+	sort.Slice(touches, func(i, j int) bool { return touches[i].Machine < touches[j].Machine })
+	if said["touches"], err = json.Marshal(touches); err != nil {
+		return nil, false, err
+	}
+	said[walkDeclaredRead] = json.RawMessage(`true`)
+	out, err := json.Marshal(said)
+	return out, err == nil, err
+}
+
+// toSayAgain reads a plan-moved: whether it says a walk's start or end not said again yet.
+func toSayAgain(body []byte) (map[string]json.RawMessage, bool, error) {
+	var said map[string]json.RawMessage
+	if err := json.Unmarshal(body, &said); err != nil {
+		return nil, false, fmt.Errorf("a plan-moved that is not an object: %w", err)
+	}
+	var phase string
+	_ = json.Unmarshal(said["phase"], &phase)
+	return said, (phase == inventory.WalkStarted || phase == inventory.WalkEnded) && said[walkDeclaredRead] == nil, nil
+}
+
+// declaredTouches are the machines changed that a walk's touches do not name, each a declared touch. Pure; sorted.
+func declaredTouches(touches []walkTouch, changed []string) []walkTouch {
+	named := map[string]bool{}
+	for _, t := range touches {
+		named[t.Machine] = true
+	}
+	var out []walkTouch
+	for _, n := range changed {
+		if !named[n] {
+			out = append(out, walkTouch{Machine: n, Modules: []string{}, Declared: true})
+			named[n] = true
+		}
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Machine < out[j].Machine })
+	return out
+}
+
+// sayDeclared says a walk's start or end again with its declared touches, when it has any. What cannot be read is
+// said on the controller's log: the walk is then held as before, never less.
+func sayDeclared(ctx context.Context, bus link.Bus, open *stores, body []byte) {
+	if _, wanted, _ := toSayAgain(body); !wanted {
+		return // no start or end, or said again already: nothing to compare
+	}
+	comparing, cancel := context.WithTimeout(ctx, declaredWithin)
+	defer cancel()
+	changed, err := changedDeclarations(comparing, open)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "plan-moved: which machines' declarations the walk changes cannot be read: %v\n", err)
+		return
+	}
+	again, ok, err := withDeclared(body, changed)
+	if err != nil || !ok {
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "plan-moved: the walk cannot be said again with its declared machines: %v\n", err)
+		}
+		return
+	}
+	stating, stop := context.WithTimeout(context.WithoutCancel(ctx), 10*time.Second)
+	defer stop()
+	if err := bus.PublishSeatEvent(stating, link.MeshControllerSeat, link.KeyPlanMoved, again); err != nil {
+		fmt.Fprintf(os.Stderr, "plan-moved: the walk could not be said again with its declared machines: %v\n", err)
+	}
+}

cmd/mesh-controller/walk_declared_test.go

@@ -0,0 +1,61 @@
+package main
+
+import (
+	"encoding/json"
+	"reflect"
+	"testing"
+
+	"github.com/novox/mesh-controller/internal/inventory"
+)
+
+// novox/hq ADR 0505 §2: the machines whose declaration a walk's merges change are said as declared touches.
+
+// The machines behind what they were last sent, and those sent one before that cannot be worked out now, are changed;
+// one never sent and not worked out is not.
+func TestAMachineBehindOrNoLongerComposableIsChanged(t *testing.T) {
+	nodes := []inventory.Node{{Name: "ace"}, {Name: "g14"}, {Name: "novox"}, {Name: "shanks"}, {Name: "new"}}
+	would := map[string]string{"ace": "d1", "g14": "d2", "novox": "d3"}
+	behind := []inventory.Machine{{Node: "ace"}}
+	sent := map[string]bool{"ace": true, "g14": true, "novox": true, "shanks": true}
+	if got := changedOf(nodes, would, behind, sent); !reflect.DeepEqual(got, []string{"ace", "shanks"}) {
+		t.Fatalf("changed: %v, want ace (behind) and shanks (no longer composes)", got)
+	}
+}
+
+// A walk's start said by plan-moved (walk_said.go's body), said again with the changed machines it does not touch as
+// declared touches, once.
+func TestAWalksStartIsSaidAgainWithTheMachinesItsMergesChange(t *testing.T) {
+	body, err := json.Marshal(planMovedBody{Plan: inventory.Plan{ID: "plan-1", State: inventory.PlanBuilding},
+		walkSaid: &walkSaid{Walk: "plan-1", Phase: inventory.WalkStarted, BudgetClass: "leaf", BoundSeconds: 600,
+			Touches: []walkTouch{{Machine: "novox", Modules: []string{"gitea"}}}}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	again, ok, err := withDeclared(body, []string{"novox", "shanks"})
+	if err != nil || !ok {
+		t.Fatalf("not said again: %v %v", ok, err)
+	}
+	var said struct {
+		ID           string      `json:"id"`
+		Phase        string      `json:"phase"`
+		Touches      []walkTouch `json:"touches"`
+		DeclaredRead bool        `json:"declared_read"`
+	}
+	if err := json.Unmarshal(again, &said); err != nil {
+		t.Fatal(err)
+	}
+	want := []walkTouch{{Machine: "novox", Modules: []string{"gitea"}}, {Machine: "shanks", Modules: []string{}, Declared: true}}
+	if said.ID != "plan-1" || said.Phase != inventory.WalkStarted || !said.DeclaredRead || !reflect.DeepEqual(said.Touches, want) {
+		t.Fatalf("said again: %+v", said)
+	}
+	if _, ok, _ := withDeclared(again, []string{"ace"}); ok {
+		t.Fatalf("a start said again was said a third time")
+	}
+	if _, ok, _ := withDeclared(body, []string{"novox"}); ok {
+		t.Fatalf("said again with nothing it does not touch")
+	}
+	moved, _ := json.Marshal(inventory.Plan{ID: "plan-2", State: inventory.PlanBuilding})
+	if _, ok, _ := withDeclared(moved, []string{"shanks"}); ok {
+		t.Fatalf("a move inside a walk was said as its start")
+	}
+}

cmd/mesh-controller/walk_said.go

@@ -59,6 +59,9 @@ type walkTouch struct {
 	// Carried names those of Modules that are there only because a moved tool runner or node-engine carries
 	// them: what restarts with it, not what the walk builds.
 	Carried []string `json:"carried,omitempty"`
+	// Declared marks a machine the walk sends nothing to whose declaration its merges change (novox/hq ADR 0505 §2):
+	// said again by the serving controller once it has compared every machine (walk_declared.go).
+	Declared bool `json:"declared,omitempty"`
 }
 
 // planMovedBody is `plan-moved`'s body: the walk whole, as before, and on its start and end what it touches.

cmd/mesh-controller/walk_said_integration_test.go

@@ -264,3 +264,46 @@ func TestAWalkStoppedByHandAndRetriedEndsFailedWhenItFailsAgain(t *testing.T) {
 		}
 	}
 }
+
+// novox/hq ADR 0505 §2: a walk's start is said again, over the real bus and against the real store, with a machine it
+// sends nothing to whose declaration differs from what it was last sent (here: assigned a module and never pushed),
+// marked declared.
+func TestAWalksStartIsSaidAgainWithAMachineWhoseDeclarationChanged(t *testing.T) {
+	open := aMesh(t)
+	ctx := t.Context()
+	next := planMovedHeard(t)
+	register(t, open, catalogue.Manifest{Module: "app", Version: "1"})
+	if _, err := assign(ctx, open, "anchor", "app"); err != nil {
+		t.Fatal(err)
+	}
+	js, err := broker.Dial(testbus.URL(t))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(js.Close)
+	core, err := js.Conn().JetStream()
+	if err != nil {
+		t.Fatal(err)
+	}
+	body, err := json.Marshal(planMovedBody{Plan: inventory.Plan{ID: "plan-505", State: inventory.PlanBuilding},
+		walkSaid: &walkSaid{Walk: "plan-505", Phase: inventory.WalkStarted, BudgetClass: inventory.ClassLeaf,
+			BoundSeconds: 360, Touches: []walkTouch{}}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	sayDeclared(ctx, link.OverNATS{Conn: js.Conn(), JS: core}, open, body)
+	again := next(inventory.WalkStarted)
+	raw, _ := json.Marshal(again["touches"])
+	var touches []walkTouch
+	_ = json.Unmarshal(raw, &touches)
+	anchor := false
+	for _, tc := range touches {
+		anchor = anchor || (tc.Machine == "anchor" && tc.Declared && len(tc.Modules) == 0)
+		if !tc.Declared {
+			t.Fatalf("a machine the walk sends nothing to was said sent: %s", raw)
+		}
+	}
+	if again["walk"] != "plan-505" || again[walkDeclaredRead] != true || !anchor {
+		t.Fatalf("said again: %v", again)
+	}
+}

cmd/mesh-controller/watchdogs.go

@@ -58,6 +58,12 @@ type signalFacts struct {
 	// failed are the delivery plans that failed and are asked of the operator (S23, novox/hq ADR 0449).
 	failed    []failedPlanFacts
 	failedErr error
+	// held are the machines with moves of recorded modules waiting for a person's push (S24, novox/hq issue 1732).
+	held    []heldFacts
+	heldErr error
+	// images are the modules left out of a send because the artifact store lacks an image they name (S25, issue 1742).
+	images    []imageFacts
+	imagesErr error
 	// refusedSends are the sends a machine refused within the hour for the generation they were composed
 	// from, each naming its sender (S20, novox/hq issue 234).
 	refusedSends    []inventory.Send
@@ -357,6 +363,8 @@ func (w *watchdogs) gather(ctx context.Context) *signalFacts {
 		f.batches, f.plansErr = gatherBatches(ctx, inv, now)
 	}
 	f.failed, f.failedErr = gatherFailedPlans(ctx, inv, now)
+	f.held, f.heldErr = gatherHeldMoves(ctx, inv)
+	f.images, f.imagesErr = gatherMissingImagesHere(ctx, inv)
 	f.loop, f.loopErr = w.gatherLoop()
 	f.asks, f.asksErr = w.gatherAsks(ctx, inv)
 	if open, err := w.keeper.Open(ctx); err != nil {

go.mod

@@ -3,7 +3,7 @@ module github.com/novox/mesh-controller
 go 1.26.0
 
 require (
-	git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261021153908-725590e06e75
+	git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261022161324-8892a1176800
 	github.com/jackc/pgx/v5 v5.10.0
 	github.com/nats-io/nats-server/v2 v2.11.17
 	github.com/nats-io/nats.go v1.54.0

go.sum

@@ -1,7 +1,7 @@
 git.novox.be/novox/mesh-host v0.0.0-20261018171808-9d9e3a46c4f5 h1:E5stfIeCN6uYgA9TCv+4K8JgaURg3zQppvUgJLaDMP4=
 git.novox.be/novox/mesh-host v0.0.0-20261018171808-9d9e3a46c4f5/go.mod h1:4wyoCr6IIIIarEUuROThWDj7DAvJvIidqMjWcpSnOwE=
-git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261021153908-725590e06e75 h1:AcYfyJpYaUufhI93VG76+b001msXY4XX7kuRjnf33HY=
-git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261021153908-725590e06e75/go.mod h1:ouERNpZizzwZ0HLEtAypsY9FR20FyUgUYRni6J7kVCY=
+git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261022161324-8892a1176800 h1:Q29osS06HHcXH1WXURDyITbOLnJG7XJYgCzmZD++Nws=
+git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261022161324-8892a1176800/go.mod h1:ouERNpZizzwZ0HLEtAypsY9FR20FyUgUYRni6J7kVCY=
 github.com/antithesishq/antithesis-sdk-go v0.7.0-default-no-op h1:Z/MZK75wC/NSrkgqeNIa7jexam9uWzhLmFTSCPI/kn0=
 github.com/antithesishq/antithesis-sdk-go v0.7.0-default-no-op/go.mod h1:FQyySiasQQM8735Ddel3MRojmy4dA1IqCeyJ5jmPMbI=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=

internal/broker/controller_buckets.go

@@ -104,6 +104,9 @@ var (
 	AssignmentsBucket    = BucketName(ControllerSeat, MirrorAssignments)
 	DeclaredConfigBucket = BucketName(ControllerSeat, MirrorDeclaredConfig)
 	PredefinedBucket     = BucketName(ControllerSeat, MirrorPredefined)
+	// DeclaredPackagesBucket holds, keyed by the node, each package the modules assigned to it declare, present or absent,
+	// with the declaring modules: what the pacman module's verbs read to say a package is declared (ADR 0507 §5).
+	DeclaredPackagesBucket = BucketName(ControllerSeat, MirrorDeclaredPackages)
 )
 
 // The mirrors' local names, as a reader names them in `reads` after `mesh-controller.`.
@@ -111,6 +114,8 @@ const (
 	MirrorAssignments    = "assignments"
 	MirrorDeclaredConfig = "declared-config"
 	MirrorPredefined     = "predefined"
+	// MirrorDeclaredPackages is the local name of the packages each node's modules declare (ADR 0507 §5, issue 1840/S3).
+	MirrorDeclaredPackages = "declared-packages"
 )
 
 // The chain's buckets (novox/hq ADR 0408, issue 1089): builds, rollouts and assignments are one chain kept on the bus
@@ -153,7 +158,7 @@ func ChainBuckets() []string { return []string{BuildsBucket, RolloutsBucket, Ass
 // ControllerMirrors are the local names of the controller's buckets a module may read: the record mirrors and the
 // chain's buckets.
 func ControllerMirrors() []string {
-	return []string{MirrorAssignments, MirrorDeclaredConfig, MirrorPredefined, ChainBuilds, ChainRollouts, ChecksRunning}
+	return []string{MirrorAssignments, MirrorDeclaredConfig, MirrorPredefined, ChainBuilds, ChainRollouts, ChecksRunning, PlansBuilding, MirrorDeclaredPackages}
 }
 
 // MirrorsWrittenByAnother are the controller's mirrors whose writer is not the controller, each with its reason: the rule
@@ -222,6 +227,7 @@ func IsControllerBucket(bucket string) bool {
 	return bucket == CallsBucket || bucket == HandActsBucket || bucket == ConditionsBucket ||
 		bucket == ConditionHistoryBucket || bucket == LeaseBucket || bucket == AskedBucket ||
 		bucket == AssignmentsBucket || bucket == DeclaredConfigBucket || bucket == PredefinedBucket ||
+		bucket == DeclaredPackagesBucket ||
 		bucket == MergeWindowBucket || bucket == RolloutSilentBucket || bucket == CheckRunningBucket ||
 		bucket == DeliveryMergesBucket || bucket == BuildsBucket || bucket == RolloutsBucket ||
 		bucket == PlansBuildingBucket || bucket == delivery.HaveBucket
@@ -230,7 +236,7 @@ func IsControllerBucket(bucket string) bool {
 // ControllerBuckets are the controller's own buckets, in the order they are asserted.
 func ControllerBuckets() []string {
 	return []string{LeaseBucket, CallsBucket, HandActsBucket, ConditionsBucket, ConditionHistoryBucket, AskedBucket,
-		AssignmentsBucket, DeclaredConfigBucket, PredefinedBucket, MergeWindowBucket, RolloutSilentBucket, CheckRunningBucket,
+		AssignmentsBucket, DeclaredConfigBucket, PredefinedBucket, DeclaredPackagesBucket, MergeWindowBucket, RolloutSilentBucket, CheckRunningBucket,
 		DeliveryMergesBucket, PlansBuildingBucket, BuildsBucket, RolloutsBucket, delivery.HaveBucket}
 }
 
@@ -446,6 +452,9 @@ func (j *JetStream) EnsureControllerBuckets() error {
 		{PredefinedBucket, "the list of predefined keys the mesh published, the newest trunk build's of the " +
 			"catalogue, one key `list` (novox/hq ADR 0348 §7, design 57 K3): written by the controller alone from " +
 			"its store when a newer list is kept, read through `reads`"},
+		{DeclaredPackagesBucket, "each package the modules assigned to a node declare, present or absent, with the " +
+			"declaring modules, keyed by the node (novox/hq ADR 0507 §5): written by the controller alone when it " +
+			"composes the node, only on a change, read through `reads`"},
 	} {
 		if _, err := js.CreateOrUpdateKeyValue(ctx, jetstream.KeyValueConfig{
 			Bucket:         m.bucket,

internal/broker/declared_packages_mirror_test.go

@@ -0,0 +1,41 @@
+package broker
+
+import (
+	"slices"
+	"testing"
+)
+
+// Issue 1840/S3 (ADR 0507 §5), 1840/AC5: a module whose manifest reads mesh-controller.declared-packages may name it in
+// `reads`, and reads the bucket and writes none; the controller writes it, so it is no mirror written by another, and it is
+// one of the controller's own buckets, asserted at its start.
+func TestAModuleReadingDeclaredPackagesReadsAndWritesNone(t *testing.T) {
+	if !slices.Contains(ControllerMirrors(), "declared-packages") ||
+		BucketName(ControllerSeat, MirrorDeclaredPackages) != DeclaredPackagesBucket {
+		t.Fatalf("a module cannot name %s in `reads`: %v", DeclaredPackagesBucket, ControllerMirrors())
+	}
+	if _, other := MirrorsWrittenByAnother[MirrorDeclaredPackages]; other {
+		t.Error("the controller writes the declared packages itself")
+	}
+	if !IsControllerBucket(DeclaredPackagesBucket) || !slices.Contains(ControllerBuckets(), DeclaredPackagesBucket) {
+		t.Errorf("%s is not among the controller's buckets", DeclaredPackagesBucket)
+	}
+	perms, err := PermissionsFor(Principal{Kind: KindModule, Node: "one", Module: "pacman", PasswordHash: "x",
+		Reads: []string{"mesh-controller.declared-packages"}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	stream := "KV_" + DeclaredPackagesBucket
+	has(t, perms.Publish, "$JS.API.STREAM.INFO."+stream)
+	has(t, perms.Publish, "$JS.API.DIRECT.GET."+stream+".>")
+	has(t, perms.Publish, "$JS.API.CONSUMER.CREATE."+stream+".>")
+	for _, p := range perms.Publish {
+		if SubjectsOverlap(p, "$KV."+DeclaredPackagesBucket+".one") {
+			t.Errorf("the reading module may write %s through %q", DeclaredPackagesBucket, p)
+		}
+	}
+	controller, err := PermissionsFor(Principal{Kind: KindController, PasswordHash: "x"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	has(t, controller.Publish, "$KV."+DeclaredPackagesBucket+".>")
+}

internal/broker/jetstream.go

@@ -2,10 +2,7 @@ package broker
 
 import (
 	"context"
-	"crypto/sha256"
 	"crypto/tls"
-	"crypto/x509"
-	"encoding/hex"
 	"errors"
 	"fmt"
 	"os"
@@ -112,25 +109,6 @@ func DialPinned(url, fingerprint string, opts ...nats.Option) (*JetStream, error
 	return Dial(url, opts...)
 }
 
-// PinnedToFingerprint accepts exactly the certificate with this SHA-256 and no other.
-func PinnedToFingerprint(want string) *tls.Config {
-	return &tls.Config{
-		InsecureSkipVerify: true, //nolint:gosec // replaced by the pin below, which is stricter
-		MinVersion:         tls.VersionTLS12,
-		VerifyPeerCertificate: func(rawCerts [][]byte, _ [][]*x509.Certificate) error {
-			if len(rawCerts) == 0 {
-				return errors.New("the bus presented no certificate")
-			}
-			sum := sha256.Sum256(rawCerts[0])
-			got := "sha256:" + hex.EncodeToString(sum[:])
-			if got != want {
-				return fmt.Errorf("the bus presented a certificate this mesh does not know (%s…), expected %s…", got[:23], want[:23])
-			}
-			return nil
-		},
-	}
-}
-
 // Conn is the connection itself, for what the mesh keeps off JetStream on purpose — a heartbeat,
 // a tool call — where a lost message is answered by the next one or by a timeout the caller
 // already handles (design 25 §3).

internal/broker/log.go

@@ -98,17 +98,6 @@ func (l Log) Config() jetstream.StreamConfig {
 	}
 }
 
-// LogIssued is one log an assignment may reach, by the name its module uses for it (novox/hq ADR
-// 0297): its stream, the subject its entries go under, and whether it may append. Only the owner's
-// instances are issued a log, so Writes is always true today; it is said so the runtime need not
-// assume it.
-type LogIssued struct {
-	Name    string `json:"name"`
-	Stream  string `json:"stream"`
-	Subject string `json:"subject"`
-	Writes  bool   `json:"writes"`
-}
-
 // logsIssuedFor is every log a module's code may reach, as its membership lists them: its own.
 func logsIssuedFor(d Declared) []LogIssued {
 	var out []LogIssued

internal/broker/membership.go

@@ -1,7 +1,6 @@
 package broker
 
 import (
-	"encoding/json"
 	"slices"
 	"sort"
 	"strings"
@@ -16,81 +15,6 @@ import (
 // grant is the same composition read the other way. The shape issued today is the shape the mesh
 // already had, so nothing moves when a membership first arrives; only who decides it moves.
 
-// Membership is one assignment's subjects: what this instance of a module on this machine serves,
-// and what it may reach.
-type Membership struct {
-	Node   string `json:"node"`
-	Module string `json:"module"`
-	// Serves is every address a tool of this instance answers on. `{tool}` stands for the tool's
-	// own name, which the module knows and the mesh does not need to: the mesh issues the address,
-	// the runtime fills the name. An address with a queue is shared with the module's other
-	// instances, and the bus hands each call to one of them; an address without is this instance's.
-	Serves []Served `json:"serves"`
-	// Seats is every verb of a seat this instance holds, at the subject the seat's callers use.
-	Seats []SeatServed `json:"seats,omitempty"`
-	// Emits is where an event of this module lands; `{event}` stands for the event's name.
-	Emits string `json:"emits"`
-	// Reaches is each tool this module may call, `<module>.<tool>`, to the subjects that reach it:
-	// the first is whichever instance answers, when the mesh issued one; the rest name a machine.
-	Reaches map[string][]string `json:"reaches,omitempty"`
-	// Tools is where this instance answers what it serves — the runtime's one verb of its own.
-	Tools string `json:"tools"`
-	// Receives is what this assignment is given for each requirement it receives, by requirement:
-	// the contributions of every module that asked for it, as the catalogue composed them (novox/hq
-	// ADR 0167). The same list its received file is written from, so the two cannot disagree; a
-	// requirement nobody contributed to is an empty list, never absent. Kept as JSON because the
-	// catalogue owns the shape of a contribution and the bus only carries it.
-	Receives map[string]json.RawMessage `json:"receives,omitempty"`
-	// Mesh is every machine's address on the private network — what a rule saying "from the mesh"
-	// resolves to in the packet filter, issued here from the same list (novox/hq ADR 0167). A
-	// module that must tell the mesh from the world, the route proxy serving an internal name, reads
-	// it here rather than keeping a definition of its own.
-	Mesh []string `json:"mesh,omitempty"`
-	// State is every bucket this module's code may reach, by the name it uses for each, and whether
-	// it may write it (novox/hq ADR 0201): the runtime answers a bundle's state verbs from this list
-	// and refuses, with the reason, what is not on it — the bus enforces only the union over every
-	// module on the machine.
-	State []StateIssued `json:"state,omitempty"`
-	// Logs is every log this module's code may reach, by the name it uses for each (novox/hq ADR 0297):
-	// its own and no other's, since a log is its owner's alone. The runtime answers a bundle's log verbs
-	// from this list and refuses, with the reason, a log not on it.
-	Logs []LogIssued `json:"logs,omitempty"`
-	// SeatTraffic is what this module's code may submit, say, hear, take, ask, answer and read on seats
-	// that name their caller or their kind (novox/hq ADR 0259 §3). The runtime carrying the module
-	// publishes, takes and answers for it only what is listed here: the bus enforces only the union
-	// over every module on the machine, so one module's code reaching another's name or kind through
-	// the runtime is the runtime's to refuse.
-	SeatTraffic *SeatTraffic `json:"seat-traffic,omitempty"`
-	// Streams are this module's own streams (novox/hq ADR 0363 §2): an event one of them carries is published
-	// on that stream's subject, never on Emits. Hears are the module streams it hears, each through a durable
-	// consumer on that stream the runtime binds beside the one on EVENTS (§8).
-	Streams []StreamIssued `json:"streams,omitempty"`
-	Hears   []HeardIssued  `json:"hears,omitempty"`
-	// Waits are the event families a session may wait on through the mesh MCP server, the tool runner's
-	// alone (novox/hq ADR 0367 §2): the subjects its account is granted, under the names a session asks for.
-	// The tool runner refuses any family not listed here.
-	Waits []WaitIssued `json:"waits,omitempty"`
-}
-
-// Served is one address a tool is answered on.
-type Served struct {
-	Subject string `json:"subject"`
-	Queue   string `json:"queue,omitempty"`
-}
-
-// SeatServed is one verb of a held seat, where its callers ask.
-type SeatServed struct {
-	Seat    string `json:"seat"`
-	Verb    string `json:"verb"`
-	Subject string `json:"subject"`
-}
-
-// MembershipSubject is the one address a runtime derives for itself: where its own membership is
-// published, from the two names its credential carries. Everything else is in the membership.
-func MembershipSubject(node, module string) string {
-	return "mesh.assignment." + node + "." + module
-}
-
 // Placements is where every module runs, for deciding which instance answers for the module.
 type Placements struct {
 	// Nodes is each module's machines.

internal/broker/modstreams.go

@@ -260,21 +260,6 @@ func ownStreamGrants(module string, streams []ModuleStream) []string {
 	return out
 }
 
-// StreamIssued is one of a module's own streams as its membership names it (ADR 0363 §2): the events it
-// carries, as the bus spells them, and the subject an event of them is published on, `{event}` the event.
-type StreamIssued struct {
-	Stream  string   `json:"stream"`
-	Events  []string `json:"events"`
-	Subject string   `json:"subject"`
-}
-
-// HeardIssued is one module stream an assignment hears, as its membership names it (ADR 0363 §8): the
-// stream and the durable consumer on it the runtime binds.
-type HeardIssued struct {
-	Stream   string `json:"stream"`
-	Consumer string `json:"consumer"`
-}
-
 // streamsIssuedFor is every stream of its own a module's membership names.
 func streamsIssuedFor(d Declared) []StreamIssued {
 	var out []StreamIssued

internal/broker/nats.go

@@ -361,9 +361,11 @@ var VaultNodeKey = SeatVerb{Seat: "mesh-vault", Verb: "node-key"}
 
 // VerbsTheControllerActsOnAWarrant are the other seat verbs the controller calls when the operator's warrant
 // chooses them (novox/hq ADR 0259): a machine's service restarted, and a walk started or stopped through the
-// controller's own `plans`. Named one by one; a node seat's on any machine, a mesh seat's flat.
+// controller's own `plans`, a machine's held builds sent by its own `push` and the builds held after a failed release
+// sent by its own `upgrade release-backlog` (novox/hq issue 1732). Named one by one; a node seat's on any machine, a
+// mesh seat's flat.
 var VerbsTheControllerActsOnAWarrant = []SeatVerb{{Seat: "node-service-manager", Verb: "restart"},
-	{Seat: ControllerSeat, Verb: "plans"}}
+	{Seat: ControllerSeat, Verb: "plans"}, {Seat: ControllerSeat, Verb: "push"}, {Seat: ControllerSeat, Verb: "upgrade"}}
 
 // VerbsTheControllerAsksTheOperatorChannel are the operator channel's verbs the controller calls (novox/hq
 // ADR 0380): `tell`, one plain message with no condition behind it — a module's own secret given, named,
@@ -387,6 +389,16 @@ type DegradableGrant struct {
 // works. Every other grant stays required — missing one of those is a controller that comes up and is
 // refused on the first thing it tries, with no fallback that covers it.
 var DegradableGrants = []DegradableGrant{
+	{
+		Subject: "mesh.seat." + ControllerSeat + ".tool.push",
+		Reason: "refused: the ask of a held move (Release) is answered, and the refusal told, while the operator's own " +
+			"push at the terminal still sends the machine (issue 1732; ADR 0259)",
+	},
+	{
+		Subject: "mesh.seat." + ControllerSeat + ".tool.upgrade",
+		Reason: "refused: the ask of the builds held after a failed release is answered, and the refusal told, while the " +
+			"operator's own `upgrade release-backlog` at the terminal still releases them (issue 1732; ADR 0259)",
+	},
 	{
 		Subject: "mesh.seat." + VerbsTheControllerAsksTheOperatorChannel[0].Seat + ".tool." + VerbsTheControllerAsksTheOperatorChannel[0].Verb,
 		Reason:  "refused: the controller raises the secret-given condition as before (ADR 0380 §9)",
@@ -417,6 +429,11 @@ var DegradableGrants = []DegradableGrant{
 		Reason: "refused: the controller then says no plan builds, and no check is held while a delivery builds — a check run " +
 			"wrongly costs a delivery a place, a check held wrongly costs a pull request its turn (ADR 0483 clause 2, issue 1687)",
 	},
+	{
+		Subject: "$KV." + DeclaredPackagesBucket + ".>",
+		Reason: "carried only at genesis: the controller composes its own permissions and pushes them to the bus at its " +
+			"first push, and keeps the packages each node declares only after that, holding the lease (ADR 0507 §5, issue 1840)",
+	},
 	{
 		Subject: "mesh.seat." + ControllerSeat + ".event.sent",
 		Reason: "refused: the controller says a tier sent to a machine only for outsiders, and a send that could not " +
@@ -702,7 +719,7 @@ func PermissionsFor(p Principal) (Permissions, error) {
 		// And asking the operator (novox/hq ADR 0259): an ask and its cancel under its own name, its warrants
 		// heard under its own name, the record of its asks read under its own name — as any user of the seat,
 		// derived the same way, from the seat its holder declares.
-		tp, ts := SeatTrafficOf(ControllerSeat, nil, p.Uses, nil).grants()
+		tp, ts := seatTrafficGrants(SeatTrafficOf(ControllerSeat, nil, p.Uses, nil))
 		pub = append(pub, tp...)
 		sub = append(sub, ts...)
 		// And asks who answers (novox/hq to-be 45 §4, D3): the self-check finds every seat's holder by
@@ -1035,7 +1052,7 @@ func PermissionsFor(p Principal) (Permissions, error) {
 
 		// 6. Its traffic on seats that name their caller or their kind, ask proofs or keep records
 		//    (novox/hq ADR 0259 §3).
-		tp, ts := SeatTrafficOf(p.Module, p.Holds, p.Uses, p.Watches).grants()
+		tp, ts := seatTrafficGrants(SeatTrafficOf(p.Module, p.Holds, p.Uses, p.Watches))
 		pub = append(pub, tp...)
 		sub = append(sub, ts...)
 
@@ -1159,7 +1176,7 @@ func PermissionsFor(p Principal) (Permissions, error) {
 		// not publish under another's name or kind through it is the runtime's to keep, from the seat
 		// traffic each module's membership lists.
 		for _, d := range p.Carries {
-			tp, ts := SeatTrafficOf(d.Module, d.Holds, d.Uses, d.Watches).grants()
+			tp, ts := seatTrafficGrants(SeatTrafficOf(d.Module, d.Holds, d.Uses, d.Watches))
 			pub = append(pub, tp...)
 			sub = append(sub, ts...)
 		}

internal/broker/onnats.go

@@ -35,39 +35,6 @@ func OnNATS() (address string, on bool, err error) {
 	return address, true, nil
 }
 
-// CredentialIn reads the user and password out of a bus address, and the address without them.
-//
-// The controller's own credential arrives in its address, the way the old bus's does. Split out so the
-// controller can record a hash of what it is actually using: its user is created by the installer at a
-// bootstrap password, before the controller exists to mint one, and a composition that left itself out
-// would produce a bus the writer cannot connect to.
-func CredentialIn(address string) (user, password, bare string) {
-	at := strings.LastIndex(address, "@")
-	if at < 0 {
-		return "", "", address
-	}
-	scheme := ""
-	rest := address[:at]
-	if i := strings.Index(rest, "://"); i >= 0 {
-		scheme, rest = rest[:i+3], rest[i+3:]
-	}
-	user, password, _ = strings.Cut(rest, ":")
-	return user, password, scheme + address[at+1:]
-}
-
-// BareAddress is a bus address with any credential stripped, for something that only needs to know
-// whether a server is answering there.
-func BareAddress(address string) string {
-	_, _, bare := CredentialIn(address)
-	if bare == "" {
-		return address
-	}
-	if strings.Contains(bare, "://") {
-		return bare
-	}
-	return "nats://" + bare
-}
-
 // BusAddress is where the mesh's bus is, with this process's credential, and refuses to be empty:
 // there is one bus, and a control plane without it can hold records and answer nothing (novox/hq
 // ADR 0131, design 28 task 5.5).

internal/broker/onnats_test.go

@@ -1,28 +0,0 @@
-package broker
-
-import (
-	"testing"
-)
-
-// Which bus the mesh is on is one fact, and being told about both is refused.
-//
-
-// The controller's own credential arrives in its address, and has to be readable out of it — its user
-// is created by the installer at a bootstrap password, before the controller exists to mint one.
-func TestACredentialIsReadOutOfABusAddress(t *testing.T) {
-	for _, c := range []struct{ in, user, password, bare string }{
-		{"nats://controller:secret@127.0.0.1:4222", "controller", "secret", "nats://127.0.0.1:4222"},
-		{"controller:secret@127.0.0.1:4222", "controller", "secret", "127.0.0.1:4222"},
-		{"nats://127.0.0.1:4222", "", "", "nats://127.0.0.1:4222"},
-		{"127.0.0.1:4222", "", "", "127.0.0.1:4222"},
-		// A password containing an at-sign: split on the last one, or the address becomes part of the
-		// credential and the connection goes somewhere nobody named.
-		{"nats://controller:a@b@127.0.0.1:4222", "controller", "a@b", "nats://127.0.0.1:4222"},
-	} {
-		user, password, bare := CredentialIn(c.in)
-		if user != c.user || password != c.password || bare != c.bare {
-			t.Errorf("%q read as %q/%q at %q; wanted %q/%q at %q",
-				c.in, user, password, bare, c.user, c.password, c.bare)
-		}
-	}
-}

internal/broker/plans_building_mirror_test.go

@@ -0,0 +1,30 @@
+package broker
+
+import (
+	"slices"
+	"testing"
+)
+
+// Issue 1687 (ADR 0483 clause 2): a module whose manifest reads mesh-controller.plans-building may name it in `reads`, and
+// reads the bucket and writes none; the controller writes it, so it is no mirror written by another.
+func TestAModuleReadingPlansBuildingReadsAndWritesNone(t *testing.T) {
+	if !slices.Contains(ControllerMirrors(), "plans-building") || BucketName(ControllerSeat, PlansBuilding) != PlansBuildingBucket {
+		t.Fatalf("a module cannot name %s in `reads`: %v", PlansBuildingBucket, ControllerMirrors())
+	}
+	if _, other := MirrorsWrittenByAnother[PlansBuilding]; other {
+		t.Error("the controller writes the plans building itself")
+	}
+	perms, err := PermissionsFor(Principal{Kind: KindModule, Node: "one", Module: "mesh-delivery-checker", PasswordHash: "x",
+		Reads: []string{"mesh-controller.plans-building"}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	stream := "KV_" + PlansBuildingBucket
+	has(t, perms.Publish, "$JS.API.STREAM.INFO."+stream)
+	has(t, perms.Publish, "$JS.API.DIRECT.GET."+stream+".>")
+	for _, p := range perms.Publish {
+		if SubjectsOverlap(p, "$KV."+PlansBuildingBucket+".plan-1") {
+			t.Errorf("the reading module may write %s through %q", PlansBuildingBucket, p)
+		}
+	}
+}

internal/broker/process_state_watch_test.go

@@ -0,0 +1,41 @@
+package broker
+
+import "testing"
+
+// 1840/AC9: a process account declaring the state `x` may watch and list the keys of its module's own bucket (a consumer
+// created and deleted on KV_<module>_x), read and write it, and has no grant on another module's bucket or on a mirror of the
+// controller's, whatever it is named after.
+func TestAProcessMayWatchItsOwnStateAndNoOthers(t *testing.T) {
+	p := Principal{Kind: KindProcess, Node: "novox", Module: "mesh-mail", Process: "send", State: []string{"x"}}
+	got := perms(t, p)
+	for _, s := range []string{
+		"$JS.API.CONSUMER.CREATE.KV_mesh-mail_x",
+		"$JS.API.CONSUMER.CREATE.KV_mesh-mail_x.watcher",
+		"$JS.API.CONSUMER.CREATE.KV_mesh-mail_x.watcher.$KV.mesh-mail_x.>",
+		"$JS.API.CONSUMER.DELETE.KV_mesh-mail_x.watcher",
+		"$JS.API.DIRECT.GET.KV_mesh-mail_x.$KV.mesh-mail_x.key",
+		"$JS.API.STREAM.INFO.KV_mesh-mail_x",
+		"$JS.FC.KV_mesh-mail_x.watcher",
+		"$KV.mesh-mail_x.key",
+	} {
+		if !allowed(got.Publish, s) {
+			t.Errorf("the process may not publish %s, so it cannot watch or list its own state", s)
+		}
+	}
+	for _, other := range []string{"mesh-other_x", "mesh-mail_y", DeclaredPackagesBucket, AssignmentsBucket} {
+		for _, s := range []string{
+			"$JS.API.CONSUMER.CREATE.KV_" + other,
+			"$JS.API.CONSUMER.CREATE.KV_" + other + ".watcher",
+			"$JS.API.CONSUMER.CREATE.KV_" + other + ".watcher.$KV." + other + ".>",
+			"$JS.API.CONSUMER.DELETE.KV_" + other + ".watcher",
+			"$JS.API.DIRECT.GET.KV_" + other + ".$KV." + other + ".key",
+			"$JS.API.STREAM.INFO.KV_" + other,
+			"$JS.FC.KV_" + other + ".watcher",
+			"$KV." + other + ".key",
+		} {
+			if allowed(got.Publish, s) {
+				t.Errorf("the process may publish %s, on a bucket that is not its own state", s)
+			}
+		}
+	}
+}

internal/broker/sdk_membership.go

@@ -0,0 +1,38 @@
+package broker
+
+import (
+	"git.novox.be/novox/mesh-sdk/go/membership"
+	"git.novox.be/novox/mesh-sdk/go/process"
+)
+
+// The membership the mesh issues an assignment (novox/hq ADR 0160), its subject, its stream, the bare address and the
+// pin are mesh-sdk's, public so that a module's program outside this Go module, the route proxy, reads them too
+// (novox/hq ADR 0480 clause 4, issue 1633). This package keeps no second copy: what follows only names them where the
+// controller already did.
+type (
+	Membership   = membership.Membership
+	Served       = membership.Served
+	SeatServed   = membership.SeatServed
+	StateIssued  = membership.StateIssued
+	LogIssued    = membership.LogIssued
+	Worker       = membership.Worker
+	SeatTraffic  = membership.SeatTraffic
+	KindHeld     = membership.KindHeld
+	StreamIssued = membership.StreamIssued
+	HeardIssued  = membership.HeardIssued
+	WaitIssued   = membership.WaitIssued
+)
+
+// AssignmentsStream holds every assignment's membership, the newest per subject.
+const AssignmentsStream = membership.AssignmentsStream
+
+var (
+	// MembershipSubject is where an assignment's own membership is published.
+	MembershipSubject = membership.Subject
+	// CredentialIn reads the user and password out of a bus address, and the address without them.
+	CredentialIn = membership.CredentialIn
+	// BareAddress is a bus address with any credential stripped.
+	BareAddress = membership.BareAddress
+	// PinnedToFingerprint accepts exactly the certificate with this SHA-256 and no other.
+	PinnedToFingerprint = process.PinnedToFingerprint
+)

internal/broker/seattraffic.go

@@ -24,44 +24,6 @@ import "sort"
 // And one read: **a holder's records**, a bucket the seat names, read by each user under its own name only
 // (`$KV.<bucket>.<module>.>`), so an asker reads the state of its own asks and no other asker's.
 
-// Worker is one durable consumer a holder pulls a seat's work from.
-type Worker struct {
-	Stream   string
-	Consumer string
-	Filter   string
-}
-
-// SeatTraffic is one module's seat traffic beyond tools. Publish and Subscribe are subject patterns, in the
-// server's wildcards; the runtime that carries the module checks a bundle's request against them, since
-// the runtime's own principal holds the union of every module it carries.
-type SeatTraffic struct {
-	// Publish is what it submits (accepts of seats it uses), says (events of seats it holds) and asks
-	// (proofs of seats it holds a kind of).
-	Publish []string `json:"publish,omitempty"`
-	// Subscribe is what it hears: events of seats it uses that are named by caller, events of seats it
-	// watches, and accepts of seats it holds.
-	Subscribe []string `json:"subscribe,omitempty"`
-	// Answers is the proof subjects it answers, as a watcher of a kinded seat.
-	Answers []string `json:"answers,omitempty"`
-	// Workers are the work queues it takes from, as a holder.
-	Workers []Worker `json:"workers,omitempty"`
-	// Records is the direct-get subjects of the records it reads under its own name.
-	Records []string `json:"records,omitempty"`
-	// Kinds are the holders of every kinded bench it uses or watches, with what each promises: the one
-	// account of which channel is which, and what it can carry, that the router judges an answer by. The
-	// controller's, from the claims, never a channel's word (novox/hq ADR 0259 §5).
-	Kinds []KindHeld `json:"kinds,omitempty"`
-}
-
-// KindHeld is one kind of a kinded bench and who holds it.
-type KindHeld struct {
-	Seat         string   `json:"seat"`
-	Kind         string   `json:"kind"`
-	Module       string   `json:"module"`
-	Node         string   `json:"node"`
-	Capabilities []string `json:"capabilities,omitempty"`
-}
-
 // KindedBenches are the seats that may be kinded (ADR 0234 §2): making another is a decision, recorded.
 var KindedBenches = map[string]bool{"channel": true, "intake": true}
 
@@ -175,9 +137,9 @@ func SeatTrafficOf(module string, holds, uses, watches []Seat) SeatTraffic {
 	return t
 }
 
-// grants is the bus permissions seat traffic needs: the subjects themselves, and the JetStream API a
+// seatTrafficGrants is the bus permissions seat traffic needs: the subjects themselves, and the JetStream API a
 // worker is pulled and acknowledged through and a record is read through.
-func (t SeatTraffic) grants() (pub, sub []string) {
+func seatTrafficGrants(t SeatTraffic) (pub, sub []string) {
 	pub = append(pub, t.Publish...)
 	sub = append(sub, t.Subscribe...)
 	sub = append(sub, t.Answers...)

internal/broker/state.go

@@ -186,16 +186,6 @@ func perMachineNames(buckets []Bucket) []string {
 	return out
 }
 
-// StateIssued is one bucket an assignment may reach, by the name its module uses for it: its own
-// state by the local name, another's as `<module>.<name>` (novox/hq ADR 0201). Key, when set, is the
-// one key it may reach (novox/hq ADR 0260): this machine's.
-type StateIssued struct {
-	Name   string `json:"name"`
-	Bucket string `json:"bucket"`
-	Writes bool   `json:"writes,omitempty"`
-	Key    string `json:"key,omitempty"`
-}
-
 // stateIssuedFor is every bucket a module's code may reach on a machine, as its membership lists them.
 func stateIssuedFor(d Declared, node string) []StateIssued {
 	var out []StateIssued

internal/broker/streams.go

@@ -80,9 +80,6 @@ const RestrictedMetadata = "mesh-restricted"
 // it under: never set by a mesh-internal work-queue stream (a seat's, a check's), only by Stream.WorkQueue.
 const WorkQueueMetadata = "mesh-work-queue"
 
-// AssignmentsStream holds every assignment's membership, the newest per subject.
-const AssignmentsStream = "ASSIGNMENTS"
-
 // What a durable consumer gave up on is kept (novox/hq issue 330, design 25 §3).
 //
 // **The server says it and keeps it; the controller copies it.** A consumer that handed a message over

internal/broker/testdata/composed.conf

@@ -29,7 +29,7 @@ accounts {
     ]
     users = [
       { user: "controller", password: "$2a$11$cccccccccccccccccccccc", permissions: {
-        publish: { allow: ["$JS.ACK.CONTROL.controller.>", "$JS.ACK.DEAD_LETTER_NOTICES.controller.>", "$JS.ACK.EVENTS.controller-merges.>", "$JS.ACK.EVENTS.controller.>", "$JS.API.>", "$KV.SEAT_MESH_BUILD_MACHINE_cancelled.>", "$KV.SEAT_NODE_BUILD_AGENT_cancelled.>", "$KV.mesh-controller_asked.>", "$KV.mesh-controller_assignments.>", "$KV.mesh-controller_builds.>", "$KV.mesh-controller_calls.>", "$KV.mesh-controller_checks-running.>", "$KV.mesh-controller_condition-history.>", "$KV.mesh-controller_conditions.>", "$KV.mesh-controller_declared-config.>", "$KV.mesh-controller_delivery-merges.>", "$KV.mesh-controller_hand-acts.>", "$KV.mesh-controller_lease.>", "$KV.mesh-controller_merge-window.>", "$KV.mesh-controller_plans-building.>", "$KV.mesh-controller_predefined.>", "$KV.mesh-controller_rollout-silent.>", "$KV.mesh-controller_rollouts.>", "$SRV.INFO", "_INBOX.enrol.>", "mesh.again.>", "mesh.assignment.>", "mesh.events.dead.>", "mesh.mod.*.tool.>", "mesh.node.>", "mesh.seat.mesh-build-machine.accept.>", "mesh.seat.mesh-build-machine.tool.>", "mesh.seat.mesh-controller.event.applied", "mesh.seat.mesh-controller.event.assignment-changed", "mesh.seat.mesh-controller.event.built-before", "mesh.seat.mesh-controller.event.checked", "mesh.seat.mesh-controller.event.condition-changed", "mesh.seat.mesh-controller.event.condition-cleared", "mesh.seat.mesh-controller.event.condition-raised", "mesh.seat.mesh-controller.event.declared-config-changed", "mesh.seat.mesh-controller.event.doctor-heartbeat", "mesh.seat.mesh-controller.event.healer-acted", "mesh.seat.mesh-controller.event.plan-moved", "mesh.seat.mesh-controller.event.predefined-changed", "mesh.seat.mesh-controller.event.refused", "mesh.seat.mesh-controller.event.rolled-back", "mesh.seat.mesh-controller.event.secret-replaced", "mesh.seat.mesh-controller.event.sent", "mesh.seat.mesh-controller.tool.plans", "mesh.seat.mesh-delivery.tool.close", "mesh.seat.mesh-delivery.tool.groups", "mesh.seat.mesh-delivery.tool.release", "mesh.seat.mesh-delivery.tool.stalled", "mesh.seat.mesh-delivery.tool.stop", "mesh.seat.mesh-delivery.tool.times", "mesh.seat.node-backup.tool.backed-up.*", "mesh.seat.node-backup.tool.now.*", "mesh.seat.node-build-agent.accept.>", "mesh.seat.node-build-agent.check.>", "mesh.seat.node-build-agent.tool.>", "mesh.seat.node-intrusion-prevention.tool.banned.*", "mesh.seat.node-launcher.tool.secret.*", "mesh.seat.node-service-manager.tool.restart.*", "mesh.seat.operator-channel.tool.tell"] }
+        publish: { allow: ["$JS.ACK.CONTROL.controller.>", "$JS.ACK.DEAD_LETTER_NOTICES.controller.>", "$JS.ACK.EVENTS.controller-merges.>", "$JS.ACK.EVENTS.controller.>", "$JS.API.>", "$KV.SEAT_MESH_BUILD_MACHINE_cancelled.>", "$KV.SEAT_NODE_BUILD_AGENT_cancelled.>", "$KV.mesh-controller_asked.>", "$KV.mesh-controller_assignments.>", "$KV.mesh-controller_builds.>", "$KV.mesh-controller_calls.>", "$KV.mesh-controller_checks-running.>", "$KV.mesh-controller_condition-history.>", "$KV.mesh-controller_conditions.>", "$KV.mesh-controller_declared-config.>", "$KV.mesh-controller_declared-packages.>", "$KV.mesh-controller_delivery-merges.>", "$KV.mesh-controller_hand-acts.>", "$KV.mesh-controller_lease.>", "$KV.mesh-controller_merge-window.>", "$KV.mesh-controller_plans-building.>", "$KV.mesh-controller_predefined.>", "$KV.mesh-controller_rollout-silent.>", "$KV.mesh-controller_rollouts.>", "$SRV.INFO", "_INBOX.enrol.>", "mesh.again.>", "mesh.assignment.>", "mesh.events.dead.>", "mesh.mod.*.tool.>", "mesh.node.>", "mesh.seat.mesh-build-machine.accept.>", "mesh.seat.mesh-build-machine.tool.>", "mesh.seat.mesh-controller.event.applied", "mesh.seat.mesh-controller.event.assignment-changed", "mesh.seat.mesh-controller.event.built-before", "mesh.seat.mesh-controller.event.checked", "mesh.seat.mesh-controller.event.condition-changed", "mesh.seat.mesh-controller.event.condition-cleared", "mesh.seat.mesh-controller.event.condition-raised", "mesh.seat.mesh-controller.event.declared-config-changed", "mesh.seat.mesh-controller.event.doctor-heartbeat", "mesh.seat.mesh-controller.event.healer-acted", "mesh.seat.mesh-controller.event.plan-moved", "mesh.seat.mesh-controller.event.predefined-changed", "mesh.seat.mesh-controller.event.refused", "mesh.seat.mesh-controller.event.rolled-back", "mesh.seat.mesh-controller.event.secret-replaced", "mesh.seat.mesh-controller.event.sent", "mesh.seat.mesh-controller.tool.plans", "mesh.seat.mesh-controller.tool.push", "mesh.seat.mesh-controller.tool.upgrade", "mesh.seat.mesh-delivery.tool.close", "mesh.seat.mesh-delivery.tool.groups", "mesh.seat.mesh-delivery.tool.release", "mesh.seat.mesh-delivery.tool.stalled", "mesh.seat.mesh-delivery.tool.stop", "mesh.seat.mesh-delivery.tool.times", "mesh.seat.node-backup.tool.backed-up.*", "mesh.seat.node-backup.tool.now.*", "mesh.seat.node-build-agent.accept.>", "mesh.seat.node-build-agent.check.>", "mesh.seat.node-build-agent.tool.>", "mesh.seat.node-intrusion-prevention.tool.banned.*", "mesh.seat.node-launcher.tool.secret.*", "mesh.seat.node-service-manager.tool.restart.*", "mesh.seat.operator-channel.tool.tell"] }
         subscribe: { allow: ["$JS.API.>", "$JS.EVENT.ADVISORY.CONSUMER.DELETED.>", "$JS.EVENT.ADVISORY.CONSUMER.MAX_DELIVERIES.>", "$SRV.INFO", "$SRV.INFO.mesh-controller", "$SRV.INFO.mesh-controller.>", "$SRV.PING", "$SRV.PING.mesh-controller", "$SRV.PING.mesh-controller.>", "$SRV.STATS", "$SRV.STATS.mesh-controller", "$SRV.STATS.mesh-controller.>", "_DELIVER.controller", "_DELIVER.controller.>", "_INBOX.controller.>", "mesh.control.>", "mesh.mod.*.event.provisioner.failing", "mesh.mod.*.event.provisioner.recovered", "mesh.mod.*.event.provisioner.retirement", "mesh.mod.gitea.event.pull.merged", "mesh.mod.gitea.event.pull.updated", "mesh.mod.mesh-catalog.event.catching-up", "mesh.mod.mesh-catalog.event.upgraded", "mesh.seat.mesh-build-machine.event.built", "mesh.seat.mesh-controller.tool.>", "mesh.seat.node-build-agent.event.built", "mesh.seat.operator-channel.event.decided.mesh-controller"] }
         allow_responses: { max: 1, ttl: "1m" }
       } }

internal/broker/waits.go

@@ -31,12 +31,6 @@ type Wait struct {
 	Last string
 }
 
-// WaitIssued is one family as a membership issues it: the name a session asks for, and its subject.
-type WaitIssued struct {
-	Event   string `json:"event"`
-	Subject string `json:"subject"`
-}
-
 // WaitSubject is where a family's events land. Each token is checked before it becomes a subject: a
 // wildcard, a dot inside a name or an empty token would widen the grant.
 func WaitSubject(w Wait) (string, error) {

internal/broker/writers.go

@@ -177,7 +177,7 @@ var WritersTable = []WriterRow{
 		KeptIn: "key-value " + CheckRunningBucket + ", aged out when not renewed", Others: "the build seat's holders read it to drop a duplicate request",
 		Subjects: kvOf(CheckRunningBucket), Writes: holdsTheBuildSeat,
 		Shared: "every machine holding the build seat puts the key of the check it runs and deletes it when the check ends"},
-	{State: "a delivery plan in its build phase", Writer: "controller (lease holder), at the first build's ask and at each refresh",
+	{State: "the plans-building mirror", Writer: "controller (lease holder), at the first build's ask and at each refresh",
 		KeptIn:   "key-value " + PlansBuildingBucket + ", aged out when not refreshed",
 		Others:   "the build seat's holders read it and take no new check while a key is there (ADR 0483)",
 		Subjects: kvOf(PlansBuildingBucket), Writes: isController},
@@ -236,6 +236,9 @@ var WritersTable = []WriterRow{
 	{State: "the predefined-keys mirror", Writer: "controller (lease holder), from its store, only on a change",
 		KeptIn: "key-value " + PredefinedBucket, Others: "read through `reads` as mesh-controller." + MirrorPredefined,
 		Subjects: kvOf(PredefinedBucket), Writes: isController},
+	{State: "the declared-packages mirror", Writer: "controller (lease holder), from the composition of each node, only on a change",
+		KeptIn: "key-value " + DeclaredPackagesBucket, Others: "read through `reads` as mesh-controller." + MirrorDeclaredPackages,
+		Subjects: kvOf(DeclaredPackagesBucket), Writes: isController},
 	// What a machine's provisioner client placed of a module's files (novox/hq ADR 0349 §4, design 57 P6): its own
 	// machine's word alone, which a walk's end and a gate wait for (ADR 0362, ADR 0349 §15). Kept newest per module
 	// in the stream ProvAppliedStream, and by the client in the provisioner server's `applied` bucket.

internal/broker/writers_test.go

@@ -30,7 +30,7 @@ var designRows = []string{
 	"a pull request's check asked",
 	"a pull request's check running",
 	// The plans in their build phase, a bucket the build seat's holders read (ADR 0483 clause 2, issue 1687).
-	"a delivery plan in its build phase",
+	"the plans-building mirror",
 	"a merge announced",
 	"a pull request's head announced",
 	"a pull request's merge check",
@@ -49,6 +49,7 @@ var designRows = []string{
 	"a declaration's large files",
 	"the declared-config mirror",
 	"the predefined-keys mirror",
+	"the declared-packages mirror",
 	// The provisioner client's word on what it placed (novox/hq ADR 0349 §4, design 57 P6).
 	"a module's files placed on a machine",
 }

internal/builder/build_source_test.go

@@ -86,11 +86,14 @@ func TestAnImageCompilingGoIsHandedItsBuildSourceAndSaysIt(t *testing.T) {
 	}
 	for file, want := range map[string]bool{"proxy/main.go": true, "internal/shared/s.go": true, "go.mod": true,
 		"cmd/ctl/main.go": false, "internal/only/o.go": false, "README.md": false} {
-		_, err := os.Stat(filepath.Join(workspace, "narrow-server", filepath.FromSlash(file)))
-		if (err == nil) != want {
-			t.Errorf("%s handed to the recipe: %v, wanted %v", file, err == nil, want)
+		held := slices.Contains(r.builtFrom, file)
+		if held != want {
+			t.Errorf("%s handed to the recipe: %v, wanted %v", file, held, want)
 		}
 	}
+	if _, err := os.Stat(filepath.Join(workspace, "narrow-server")); err == nil {
+		t.Error("the narrowed build source was left in the workspace")
+	}
 
 	// Said per repository: its own, the manifest and the recipe; the context's, the closure.
 	if len(got.Sources) != 2 {

internal/builder/builder.go

@@ -219,6 +219,11 @@ func build(ctx context.Context, run Runner, publish Publisher,
 	if err := os.MkdirAll(workspace, 0o755); err != nil {
 		return Result{}, err
 	}
+	// **A node with no room takes no build** (novox/hq issue 1834).
+	if err := RoomToWork("/", workspace); err != nil {
+		say("clone", "refused: %v", err)
+		return Result{}, err
+	}
 	// The credential is a file git reads, never an argument: a URL carrying a password in argv
 	// would be readable by anything that can list processes for as long as a clone runs.
 	credentials, forget, err := storeCredential(workspace, forge)
@@ -236,7 +241,8 @@ func build(ctx context.Context, run Runner, publish Publisher,
 	// A fresh clone every time rather than a fetch into a tree that is already there. A build
 	// that reuses a working tree can succeed because of something a previous build left behind,
 	// and that is a build nobody can reproduce.
-	if _, err := run(ctx, workspace, "git", cloneWith(credentials, "clone", "--quiet", repository, tree)...); err != nil {
+	if err := cloneFromForge(ctx, run, workspace, repository, tree,
+		cloneWith(credentials, "clone", "--quiet", repository, tree), say); err != nil {
 		say("clone", "FAILED: %v", err)
 		return Result{}, fmt.Errorf("cannot clone %s: %w", repository, err)
 	}
@@ -738,11 +744,41 @@ func logging(log Log) func(step, format string, args ...any) {
 	}
 }
 
+// keepsImageLocally says the publisher leaves the image in the machine's runtime as the artifact itself.
+func keepsImageLocally(publish Publisher) bool {
+	switch publish.(type) {
+	case Local, *Local:
+		return true
+	}
+	return false
+}
+
+// PushedNames is implemented by a publisher that tags the image under other names to push it: the names it leaves in the
+// machine's runtime for a repository, which go with the build's own tag (novox/hq issue 1834).
+type PushedNames interface {
+	PushedNames(repository string) []string
+}
+
+// releaseImage removes the names an image was given on the node, in one command: its layers go only with the last. It runs
+// with a context of its own, the build's may be cancelled. A name never made (the build failed before it) is no fault;
+// one that cannot be removed is said, and removal is said only when the image is gone.
+func releaseImage(ctx context.Context, run Runner, names []string, say func(step, format string, args ...any)) {
+	removing, done := context.WithTimeout(context.WithoutCancel(ctx), time.Minute)
+	defer done()
+	if _, err := run(removing, "", "docker", append([]string{"rmi"}, names...)...); err != nil {
+		if !strings.Contains(err.Error(), "No such image") {
+			say("image", "the local image %s could not be removed, and goes with the week's sweep: %v", strings.Join(names, ", "), err)
+		}
+		return
+	}
+	say("image", "the local image %s is removed: the registry holds it", strings.Join(names, ", "))
+}
+
 // contextFrom clones an image artifact's own build context, when it names one apart from this
 // module's own repository — a fresh tree, the same way the module's own is, keyed by artifact
 // name so two artifacts of one module naming different contexts do not collide.
 func contextFrom(ctx context.Context, run Runner, workspace, artifact, credentials string,
-	from catalogue.ArtifactContext, seats map[string]string, say func(step, format string, args ...any)) (string, error) {
+	from catalogue.ArtifactContext, seats map[string]string, say func(step, format string, args ...any)) (_ string, err error) {
 	url, err := contextURL(from, seats)
 	if err != nil {
 		return "", err
@@ -752,7 +788,13 @@ func contextFrom(ctx context.Context, run Runner, workspace, artifact, credentia
 	if err := os.RemoveAll(dir); err != nil {
 		return "", err
 	}
-	if _, err := run(ctx, workspace, "git", cloneWith(credentials, "clone", "--quiet", url, dir)...); err != nil {
+	// A clone that failed half-way is no context to leave behind (novox/hq issue 1834).
+	defer func() {
+		if err != nil {
+			os.RemoveAll(dir)
+		}
+	}()
+	if err := cloneFromForge(ctx, run, workspace, url, dir, cloneWith(credentials, "clone", "--quiet", url, dir), say); err != nil {
 		return "", fmt.Errorf("cannot clone %s: %w", url, err)
 	}
 	if err := recordedWithoutUserinfo(ctx, run, dir, url); err != nil {
@@ -1143,6 +1185,8 @@ func one(ctx context.Context, run Runner, publish Publisher,
 				src.contexts[a.Name] = t
 			}
 			buildDir = cloned
+			// Let go of when the image is built, whatever became of it (novox/hq issue 1834).
+			defer os.RemoveAll(cloned)
 			if t, _ := trunkOf(ctx, run, cloned, "HEAD"); t == "" || !atTrunkHead(ctx, run, cloned, "HEAD", t) {
 				src.contextOffHead()
 			}
@@ -1180,6 +1224,7 @@ func one(ctx context.Context, run Runner, publish Publisher,
 				src.ownHas(paths...)
 			}
 			buildDir = narrowed
+			defer os.RemoveAll(narrowed)
 		} else if a.Context != nil {
 			src.readWhole(*a.Context)
 		}
@@ -1205,6 +1250,16 @@ func one(ctx context.Context, run Runner, publish Publisher,
 		}
 		invocation = append(invocation, ".")
 		say("image", "docker build -f %s", recipePath)
+		// **The local tag goes with the build** (novox/hq issue 1834): an image published to a registry is held there, and
+		// a tag per module and commit left on the node was the 96 GB of a full disk. Only a node publishing nowhere (a
+		// mesh being raised) keeps it, since the local image is then the artifact.
+		if !keepsImageLocally(publish) {
+			names := []string{local}
+			if p, ok := publish.(PushedNames); ok {
+				names = append(names, p.PushedNames(module+"/"+a.Name)...)
+			}
+			defer releaseImage(ctx, run, names, say)
+		}
 		if _, err := run(ctx, buildDir, "docker", invocation...); err != nil {
 			return catalogue.Built{}, fmt.Errorf("%s: building %s failed: %w", module, a.Name, err)
 		}

internal/builder/builder_test.go

@@ -38,6 +38,9 @@ type recorded struct {
 	stamped time.Time
 	// tree is what git names as the tree of the module's directory; empty answers as for a commit.
 	tree string
+	// builtFrom is the files (slash-separated, relative) of the folder the last `docker build` ran in, read as it ran:
+	// the build removes that folder when it ends (novox/hq issue 1834).
+	builtFrom []string
 }
 
 func (r *recorded) run(_ context.Context, dir, name string, args ...string) (string, error) {
@@ -53,6 +56,16 @@ func (r *recorded) run(_ context.Context, dir, name string, args ...string) (str
 			break
 		}
 	}
+	if name == "docker" && len(args) > 0 && args[0] == "build" {
+		r.builtFrom = nil
+		_ = filepath.WalkDir(dir, func(p string, d os.DirEntry, err error) error {
+			if err == nil && !d.IsDir() {
+				rel, _ := filepath.Rel(dir, p)
+				r.builtFrom = append(r.builtFrom, filepath.ToSlash(rel))
+			}
+			return nil
+		})
+	}
 	switch {
 	case name == "git" && isClone:
 		repository := args[len(args)-2]

internal/builder/check.go

@@ -123,8 +123,41 @@ type CheckSpec struct {
 	// controller could not learn them, and the verdict says so.
 	Siblings        []Sibling
 	SiblingsUnknown string
+	// Held are the approved held values of the check's pull requests (novox/hq ADR 0502 clause 4): written to a file and
+	// handed to the gate, which lays them over the change's composition only. None: no flag, no file.
+	Held []HeldValue
 }
 
+// HeldValue is one approved config value held for a key an open pull request introduces: the value of Key for Module on
+// Node (a machine's real name; the gate finds it in the snapshot by its pseudonym). The gate reads this document.
+type HeldValue struct {
+	Pull     string          `json:"pull"`
+	Head     string          `json:"head,omitempty"`
+	Node     string          `json:"node"`
+	Module   string          `json:"module"`
+	Key      string          `json:"key"`
+	Value    json.RawMessage `json:"value"`
+	Approved string          `json:"approved,omitempty"`
+	By       string          `json:"by,omitempty"`
+	At       string          `json:"at,omitempty"`
+}
+
+// writeHeld writes the held values to held.json under root and answers its path; empty, and nothing written, for none.
+func writeHeld(root string, held []HeldValue) (string, error) {
+	if len(held) == 0 {
+		return "", nil
+	}
+	raw, err := json.Marshal(held)
+	if err != nil {
+		return "", err
+	}
+	file := filepath.Join(root, "held.json")
+	return file, os.WriteFile(file, raw, 0o644)
+}
+
+// heldFlag is how the gate is given the held values: only when there are some, so a judge from before --held still runs.
+const heldFlag = `${MESH_CHECK_HELD:+--held "$MESH_CHECK_HELD"}`
+
 // Sibling is one other open pull request of a delivery group (novox/hq ADR 0382): the repository it is in as
 // owner/repo, its number, its whole head, the branch it merges into, and Dir, the directory the check finds that
 // repository under beside it (an entry of Beside).
@@ -272,6 +305,8 @@ const (
 	// EnvGroup is a delivery group's other heads, as JSON, for the gate (novox/hq ADR 0239); empty for a
 	// pull request checked alone.
 	EnvGroup = "MESH_CHECK_GROUP"
+	// EnvHeld is the file of the approved held values of the check's pull requests (novox/hq ADR 0502); empty for none.
+	EnvHeld = "MESH_CHECK_HELD"
 	// EnvTests is a `go test -run` pattern and EnvStoreOnly is 1 when a branch tried before its pull request
 	// asks for only those tests, or only the store tests (novox/hq issue 686). Never set for a pull request's
 	// check. A script that reads neither runs whole.
@@ -357,6 +392,12 @@ func Check(ctx context.Context, run Runner, spec CheckSpec, workspace, registry
 	ctx, stop := context.WithTimeout(ctx, CheckTimeout)
 	defer stop()
 
+	// **A node with no room takes no check** (novox/hq issue 1834): said as the check's verdict, never a throwaway store
+	// that dies at once on a full disk.
+	if err := RoomToWork("/", workspace); err != nil {
+		say("check", "refused: %v", err)
+		return CheckVerdict{}, err
+	}
 	root := filepath.Join(workspace, "check")
 	if err := os.RemoveAll(root); err != nil {
 		return CheckVerdict{}, err
@@ -387,7 +428,8 @@ func Check(ctx context.Context, run Runner, spec CheckSpec, workspace, registry
 	// clone clones a repository and checks out ref; readAt keeps which, by directory.
 	readAt := map[string]string{}
 	clone := func(repository, ref, dir string) error {
-		if _, err := run(ctx, root, "git", cloneWith(credentials, "clone", "--quiet", repository, dir)...); err != nil {
+		if err := cloneFromForge(ctx, run, root, redact.redact(repository), filepath.Join(root, dir),
+			cloneWith(credentials, "clone", "--quiet", repository, dir), say); err != nil {
 			return fmt.Errorf("cannot clone %s: %s", redact.redact(repository), redact.redact(err.Error()))
 		}
 		if err := recordedWithoutUserinfo(ctx, run, filepath.Join(root, dir), repository); err != nil {
@@ -572,6 +614,15 @@ func Check(ctx context.Context, run Runner, spec CheckSpec, workspace, registry
 		}
 	}
 
+	// The approved held values of the check's pull requests, for the gate (novox/hq ADR 0502 clause 4).
+	heldFile, err := writeHeld(root, spec.Held)
+	if err != nil {
+		return CheckVerdict{}, err
+	}
+	if heldFile != "" {
+		say("check", "with %d config value(s) held for its pull request(s)", len(spec.Held))
+	}
+
 	// Every clone is made: the credential is gone before anything of the check runs (novox/hq issue 462).
 	forget()
 
@@ -733,7 +784,7 @@ func Check(ctx context.Context, run Runner, spec CheckSpec, workspace, registry
 		EnvTestStore + "=" + storeURL, EnvTestBus + "=nats://" + bus, EnvRepository + "=" + spec.Owner + "/" + spec.Repo,
 		EnvBeside + "=" + root,
 		EnvModules + "=" + strings.Join(append(append([]string{}, spec.Modules...), spec.New...), ","),
-		EnvGroup + "=" + groupFile,
+		EnvGroup + "=" + groupFile, EnvHeld + "=" + heldFile,
 		"GOCACHE=" + filepath.Join(workspace, "go-cache"), "GOMODCACHE=" + filepath.Join(workspace, "go-modules")}
 	env = append(env, changedEnv...)
 	env = append(env, selection(spec)...)
@@ -1100,7 +1151,7 @@ func gateLayer(ctx context.Context, spec CheckSpec, tree, root, gate, verdictFil
 	if err := running(inToolchain(tree, append(env, EnvVerdict+"="+verdictFile), "sh", "-c",
 		`"$MESH_GATE" merge-gate --facts "$MESH_FACTS" --store "$MESH_GATE_POSTGRES" `+
 			`--repository "$MESH_CHECK_REPOSITORY" --tree . `+gateChangedFlag(env)+` `+
-			`${MESH_CHECK_GROUP:+--group "$MESH_CHECK_GROUP"} --json > "$MESH_CHECK_VERDICT"`)); err != nil {
+			`${MESH_CHECK_GROUP:+--group "$MESH_CHECK_GROUP"} `+heldFlag+` --json > "$MESH_CHECK_VERDICT"`)); err != nil {
 		if ctx.Err() != nil {
 			return "error", "the check was ended during the merge gate"
 		}
@@ -1587,7 +1638,9 @@ func BusImage(version string) string {
 
 // throwaway starts a container publishing one port on loopback, and answers where it is reached.
 func throwaway(ctx context.Context, run, plain Runner, name, image string, port int, opts, args []string) (string, error) {
-	invocation := []string{"run", "-d", "--rm", "--name", name, "-p", fmt.Sprintf("127.0.0.1::%d", port)}
+	// Never with --rm (novox/hq issue 1834): a store that dies at once took its log with it. The check removes what it
+	// raised, with its volumes, after it has read why one stopped (RemoveContainersOf).
+	invocation := []string{"run", "-d", "--name", name, "-p", fmt.Sprintf("127.0.0.1::%d", port)}
 	invocation = append(invocation, opts...)
 	invocation = append(invocation, image)
 	invocation = append(invocation, args...)
@@ -1608,17 +1661,45 @@ func throwaway(ctx context.Context, run, plain Runner, name, image string, port
 
 // waitFor runs a readiness command in a container until it answers, for a minute.
 func waitFor(ctx context.Context, run Runner, name string, ready []string) error {
-	for i := 0; i < 60; i++ {
+	return waitReady(ctx, run, name, ready, 60)
+}
+
+// waitReady is waitFor for a number of tries, a second apart. A container that never answers is not left a mystery
+// (novox/hq issue 1834): its state and exit code and the last 20 lines of its log are in the error, read before the
+// check removes it.
+func waitReady(ctx context.Context, run Runner, name string, ready []string, attempts int) error {
+	for i := 0; i < attempts; i++ {
 		if _, err := run(ctx, "", "docker", append([]string{"exec", name}, ready...)...); err == nil {
 			return nil
 		}
+		if i == attempts-1 {
+			break
+		}
 		select {
 		case <-ctx.Done():
 			return ctx.Err()
 		case <-time.After(time.Second):
 		}
 	}
-	return fmt.Errorf("%s never became ready", name)
+	return fmt.Errorf("%s never became ready%s", name, whyItStopped(ctx, run, name))
+}
+
+// whyItStopped is ": <state>, exit code N; its last log lines: …" for a container, or "" when docker says nothing.
+func whyItStopped(ctx context.Context, run Runner, name string) string {
+	reading, done := context.WithTimeout(context.WithoutCancel(ctx), 30*time.Second)
+	defer done()
+	var said []string
+	if out, err := run(reading, "", "docker", "inspect", "--format",
+		"{{.State.Status}}, exit code {{.State.ExitCode}}", name); err == nil && strings.TrimSpace(out) != "" {
+		said = append(said, strings.TrimSpace(out))
+	}
+	if out, err := run(reading, "", "docker", "logs", "--tail", "20", name); err == nil && strings.TrimSpace(out) != "" {
+		said = append(said, "its last log lines: "+strings.TrimSpace(out))
+	}
+	if len(said) == 0 {
+		return ""
+	}
+	return ": " + strings.Join(said, "; ")
 }
 
 // dialable waits for an address to take a connection, for a minute.

internal/builder/check_held_test.go

@@ -0,0 +1,33 @@
+package builder
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// 1826/AC2: the held values are written whole to held.json, and the gate is given the flag only when there are some.
+func TestHeldValuesAreWrittenForTheGateAndNoneWriteNothing(t *testing.T) {
+	root := t.TempDir()
+	if file, err := writeHeld(root, nil); err != nil || file != "" {
+		t.Fatalf("none wrote %q %v", file, err)
+	}
+	if _, err := os.Stat(filepath.Join(root, "held.json")); err == nil {
+		t.Fatal("none wrote a file")
+	}
+	file, err := writeHeld(root, []HeldValue{{Pull: "novox/mesh-catalog#434", Node: "ace", Module: "n8n", Key: "media-gid",
+		Value: []byte("2000"), Approved: "the operator"}})
+	if err != nil || file != filepath.Join(root, "held.json") {
+		t.Fatalf("wrote %q %v", file, err)
+	}
+	raw, _ := os.ReadFile(file)
+	for _, want := range []string{`"node":"ace"`, `"module":"n8n"`, `"key":"media-gid"`, `"value":2000`} {
+		if !strings.Contains(string(raw), want) {
+			t.Fatalf("%s lacks %s", raw, want)
+		}
+	}
+	if !strings.Contains(heldFlag, `--held "$MESH_CHECK_HELD"`) || !strings.HasPrefix(heldFlag, "${MESH_CHECK_HELD:+") {
+		t.Fatalf("the flag is %s", heldFlag)
+	}
+}

internal/builder/clone_lookup.go

@@ -0,0 +1,114 @@
+package builder
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"strings"
+	"time"
+)
+
+// A clone from the forge waits out a resolver that did not answer, for a bounded time (novox/hq issue 1773).
+//
+// **Why.** A build or a check failed now and then on "Could not resolve host: novox.internal" while cloning, between
+// clones that resolved the same name a second before and after, and the whole delivery failed with it. The lookup
+// failing is the resolver's passing fault, not the repository's: nothing reached the forge, so cloning again cannot
+// do anything twice. This is issue 457's shape (a build waits out a registry held still) applied to the name lookup.
+//
+// **Only the lookup.** Any other failure of git — authentication, a repository or a ref that is not there, a 404 —
+// fails at once, as it always did: trying it again would only make a real failure slower.
+//
+// **Bounded, and loud.** Each retry is said in the build's log as the resolver's failure, and past lookupWait the
+// build fails saying the resolver did not answer for that long.
+
+var (
+	// lookupWait is how long a clone waits for a resolver that does not answer.
+	lookupWait = 60 * time.Second
+	// lookupFirstPause is the first pause between tries; each pause doubles, up to lookupMostPause.
+	lookupFirstPause = time.Second
+)
+
+// lookupMostPause is the longest pause between two tries.
+const lookupMostPause = 10 * time.Second
+
+// lookupFailures are what git (through curl) and Go's resolver say when a name did not resolve, in lower case.
+var lookupFailures = []string{
+	"could not resolve host",
+	"temporary failure in name resolution",
+}
+
+// failedLookup is whether an error is a name lookup that failed: git's "Could not resolve host", the system's
+// "Temporary failure in name resolution", or a lookup that timed out.
+func failedLookup(err error) bool {
+	if err == nil {
+		return false
+	}
+	said := strings.ToLower(err.Error())
+	for _, f := range lookupFailures {
+		if strings.Contains(said, f) {
+			return true
+		}
+	}
+	return strings.Contains(said, "lookup ") && strings.Contains(said, "i/o timeout")
+}
+
+// cloneFromForge runs `git clone` of url into dest (git's arguments in args, run from dir), and while it fails on the
+// name lookup, clones again with a growing pause until lookupWait has passed. What a failed try left at dest is
+// removed before the next. Any other failure is returned at once.
+func cloneFromForge(ctx context.Context, run Runner, dir, url, dest string, args []string,
+	say func(step, format string, args ...any)) error {
+	_, err := run(ctx, dir, "git", args...)
+	if !failedLookup(err) {
+		return err
+	}
+	started := time.Now()
+	pause := lookupFirstPause
+	for {
+		elapsed := time.Since(started)
+		left := lookupWait - elapsed
+		if left <= 0 {
+			say("clone", "the resolver did not answer for %s, cloning %s, for %s; the clone fails",
+				urlHost(url), url, elapsed.Round(time.Second))
+			return fmt.Errorf("the resolver did not answer a lookup of %s for %s, cloning %s: %w",
+				urlHost(url), elapsed.Round(time.Millisecond), url, err)
+		}
+		wait := min(pause, left)
+		say("clone", "the resolver did not answer for %s, cloning %s; trying again in %s, for up to %s "+
+			"(novox/hq issue 1773)", urlHost(url), url, wait, lookupWait)
+		select {
+		case <-ctx.Done():
+			return fmt.Errorf("stopped while waiting for the resolver to answer for %s: %w (last: %v)",
+				urlHost(url), ctx.Err(), err)
+		case <-time.After(wait):
+		}
+		pause = min(pause*2, lookupMostPause)
+		if err := os.RemoveAll(dest); err != nil {
+			return err
+		}
+		if _, err = run(ctx, dir, "git", args...); !failedLookup(err) {
+			if err == nil {
+				say("clone", "the resolver answered for %s after %s; the clone worked", urlHost(url),
+					time.Since(started).Round(time.Millisecond))
+			}
+			return err
+		}
+	}
+}
+
+// urlHost is the host (and port) a URL names, or the URL itself when it names none.
+func urlHost(url string) string {
+	rest := url
+	if _, after, ok := strings.Cut(url, "://"); ok {
+		rest = after
+	}
+	if i := strings.IndexAny(rest, "/?#"); i >= 0 {
+		rest = rest[:i]
+	}
+	if i := strings.LastIndex(rest, "@"); i >= 0 {
+		rest = rest[i+1:]
+	}
+	if rest == "" {
+		return url
+	}
+	return rest
+}

internal/builder/clone_lookup_test.go

@@ -0,0 +1,162 @@
+package builder
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+// Issue 1773: a build or a check failed now and then on "Could not resolve host: novox.internal" while cloning from
+// the forge, between clones that resolved the same name, and its whole delivery failed with it. A clone that fails on
+// the name lookup is tried again within a bound, says each retry in the build's log as the resolver's failure, and
+// only past the bound fails, saying the resolver did not answer. Any other failure of git fails at once, as before.
+
+const lookupFailure = "exit status 128\nfatal: unable to access 'http://novox.internal:20000/novox/x.git/': " +
+	"Could not resolve host: novox.internal"
+
+// failingClones is a runner whose first n forge clones fail with failure, then clone as r does; n < 0 fails every one.
+type failingClones struct {
+	r       *recorded
+	n       int
+	failure string
+	clones  int
+}
+
+func (f *failingClones) run(ctx context.Context, dir, name string, args ...string) (string, error) {
+	if name == "git" && isACloneOf(args) {
+		f.clones++
+		if f.n < 0 || f.clones <= f.n {
+			return "", fmt.Errorf("git %s: %s", strings.Join(args, " "), f.failure)
+		}
+	}
+	return f.r.run(ctx, dir, name, args...)
+}
+
+func isACloneOf(args []string) bool {
+	for _, a := range args {
+		if a == "clone" {
+			return true
+		}
+	}
+	return false
+}
+
+// buildLog collects what a build says in its own log.
+func buildLog() (Log, func() []string) {
+	var mu sync.Mutex
+	var lines []string
+	return func(step, message string) {
+			mu.Lock()
+			defer mu.Unlock()
+			lines = append(lines, step+": "+message)
+		}, func() []string {
+			mu.Lock()
+			defer mu.Unlock()
+			return append([]string(nil), lines...)
+		}
+}
+
+const nothingToBuild = `{"module":"x","version":"1"}`
+
+// 1773/AC1: a clone failing twice on the lookup, then working, is tried again, each retry said, and the build goes on.
+func TestACloneThatFailsOnTheLookupIsTriedAgainAndTheBuildGoesOn(t *testing.T) {
+	quickLookups(t)
+	r, workspace := aRepository(t, nothingToBuild, nil)
+	f := &failingClones{r: r, n: 2, failure: lookupFailure}
+	log, said := buildLog()
+	_, err := Build(context.Background(), f.run, r, "http://novox.internal:20000/novox/x.git", "", "", workspace, nil,
+		Npmrc{}, GitCredential{}, log)
+	if err != nil {
+		t.Fatalf("a clone the resolver failed twice, then answered, ended the build: %v", err)
+	}
+	if f.clones != 3 {
+		t.Errorf("the clone ran %d times, want 3 (two lookups failed, the third worked)", f.clones)
+	}
+	retries := 0
+	for _, line := range said() {
+		if strings.Contains(line, "the resolver did not answer") && strings.Contains(line, "novox.internal") {
+			retries++
+		}
+	}
+	if retries != 2 {
+		t.Errorf("the build's log said %d retries as the resolver's failure, want 2:\n%s", retries,
+			strings.Join(said(), "\n"))
+	}
+}
+
+// 1773/AC2: a lookup that keeps failing past the bound fails the build, saying the resolver did not answer.
+func TestACloneWhoseLookupNeverAnswersFailsSayingTheResolverDidNotAnswer(t *testing.T) {
+	quickLookups(t)
+	r, workspace := aRepository(t, nothingToBuild, nil)
+	f := &failingClones{r: r, n: -1, failure: lookupFailure}
+	_, err := Build(context.Background(), f.run, r, "http://novox.internal:20000/novox/x.git", "", "", workspace, nil,
+		Npmrc{}, GitCredential{}, nil)
+	if err == nil {
+		t.Fatal("a clone whose lookup never answered built")
+	}
+	if !strings.Contains(err.Error(), "the resolver did not answer") ||
+		!strings.Contains(err.Error(), "http://novox.internal:20000/novox/x.git") {
+		t.Errorf("the failure does not say the resolver did not answer for the forge's URL: %v", err)
+	}
+	if f.clones < 2 {
+		t.Errorf("the clone ran %d times; a failed lookup is tried again within the bound", f.clones)
+	}
+}
+
+// 1773/AC3: any other failure of git (authentication, a missing repository) is not tried again and fails at once.
+func TestACloneFailingForAnotherReasonIsNotTriedAgain(t *testing.T) {
+	quickLookups(t)
+	for _, failure := range []string{
+		"exit status 128\nfatal: Authentication failed for 'http://novox.internal:20000/novox/x.git/'",
+		"exit status 128\nremote: Not found.\nfatal: repository 'http://novox.internal:20000/novox/x.git/' not found",
+		"exit status 128\nfatal: unable to access 'http://novox.internal:20000/novox/x.git/': The requested URL returned error: 404",
+	} {
+		r, workspace := aRepository(t, nothingToBuild, nil)
+		f := &failingClones{r: r, n: -1, failure: failure}
+		_, err := Build(context.Background(), f.run, r, "http://novox.internal:20000/novox/x.git", "", "", workspace, nil,
+			Npmrc{}, GitCredential{}, nil)
+		if err == nil || !strings.Contains(err.Error(), "cannot clone") {
+			t.Errorf("a clone failing with %q said %v", failure, err)
+		}
+		if f.clones != 1 {
+			t.Errorf("a clone failing with %q ran %d times; it is not a lookup and is not tried again", failure, f.clones)
+		}
+	}
+}
+
+// quickLookups shortens the bound and the pauses, so a test waits for milliseconds.
+func quickLookups(t *testing.T) {
+	t.Helper()
+	wasBound, wasFirst := lookupWait, lookupFirstPause
+	lookupWait, lookupFirstPause = 200*time.Millisecond, 10*time.Millisecond
+	t.Cleanup(func() { lookupWait, lookupFirstPause = wasBound, wasFirst })
+}
+
+// 1773/AC1, 1773/AC3: a check's clones are the same: a failed lookup is tried again, and the failure after it (here
+// an authentication refused) ends the check at once, not tried again.
+func TestACheckCloneTriesAFailedLookupAgain(t *testing.T) {
+	quickLookups(t)
+	clones := 0
+	run := func(_ context.Context, _ string, name string, args ...string) (string, error) {
+		if name == "git" && isACloneOf(args) {
+			clones++
+			if clones <= 2 {
+				return "", fmt.Errorf("git clone: %s", lookupFailure)
+			}
+			return "", fmt.Errorf("git clone: exit status 128\nfatal: Authentication failed")
+		}
+		return "", nil
+	}
+	_, err := Check(context.Background(), run, CheckSpec{ID: "build-1", Owner: "novox", Repo: "x", Number: 1,
+		Repository: "http://novox.internal:20000/novox/x.git", Ref: "abc"}, t.TempDir(), "registry.invalid",
+		GitCredential{}, nil)
+	if err == nil || !strings.Contains(err.Error(), "cannot clone") || !strings.Contains(err.Error(), "Authentication failed") {
+		t.Fatalf("the check said %v", err)
+	}
+	if clones != 3 {
+		t.Errorf("the check's clone ran %d times, want 3: two failed lookups, then the refusal, not tried again", clones)
+	}
+}

internal/builder/disk_1834_test.go

@@ -0,0 +1,216 @@
+package builder
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// Issue 1834: a build node's root disk filled and every check there ended "the store never became ready". A node
+// frees what each build and check leaves, refuses to take work under a floor of free space, and a store that does
+// not come up says why.
+
+func init() {
+	// The disk the tests run on is none of their business; the tests of the floor say their own.
+	FreeBytes = func(string) (uint64, error) { return 500 << 30, nil }
+}
+
+func withFree(t *testing.T, bytes uint64) {
+	t.Helper()
+	was := FreeBytes
+	FreeBytes = func(string) (uint64, error) { return bytes, nil }
+	t.Cleanup(func() { FreeBytes = was })
+}
+
+// 1834/AC2: given 3 GiB free, when a check or a build is asked, then it refuses at once, saying so, running nothing.
+func TestACheckUnderTheFloorOfFreeSpaceRefusesSayingSo(t *testing.T) {
+	withFree(t, 3<<30)
+	var ran []string
+	run := func(_ context.Context, _ string, name string, args ...string) (string, error) {
+		ran = append(ran, name+" "+strings.Join(args, " "))
+		return "", nil
+	}
+	_, err := Check(context.Background(), run, CheckSpec{ID: "build-1"}, t.TempDir(), "registry.invalid", GitCredential{}, nil)
+	if err == nil || !strings.Contains(err.Error(), "the build node has 3 GiB free on /, under the floor of 20 GiB") {
+		t.Fatalf("a check on a full disk said %v", err)
+	}
+	if len(ran) != 0 {
+		t.Errorf("a refused check ran %v", ran)
+	}
+}
+
+func TestABuildUnderTheFloorOfFreeSpaceRefusesSayingSo(t *testing.T) {
+	withFree(t, 3<<30)
+	r := &recorded{}
+	_, err := Build(context.Background(), r.run, r, "https://forge.invalid/x.git", "", "", t.TempDir(), nil, Npmrc{}, GitCredential{}, nil)
+	if err == nil || !strings.Contains(err.Error(), "under the floor of 20 GiB") {
+		t.Fatalf("a build on a full disk said %v", err)
+	}
+	if len(r.ran) != 0 {
+		t.Errorf("a refused build ran %v", r.ran)
+	}
+}
+
+// The workspace's filesystem is read too, and a workspace not made yet is read at its nearest folder.
+func TestTheWorkspacesFilesystemIsReadToo(t *testing.T) {
+	was := FreeBytes
+	t.Cleanup(func() { FreeBytes = was })
+	missing := filepath.Join(t.TempDir(), "not", "yet")
+	FreeBytes = func(p string) (uint64, error) {
+		if p == "/" {
+			return 100 << 30, nil
+		}
+		if _, err := os.Stat(p); err != nil {
+			t.Errorf("read the free space of %s, which is not there", p)
+		}
+		return 1 << 30, nil
+	}
+	err := RoomToWork("/", missing)
+	if err == nil || !strings.Contains(err.Error(), "1 GiB free on "+missing) {
+		t.Errorf("the workspace's disk, under the floor, said %v", err)
+	}
+	FreeBytes = func(string) (uint64, error) { return 0, errors.New("no") }
+	if RoomToWork("/") == nil {
+		t.Error("a disk that cannot be read was taken as having room")
+	}
+}
+
+// 1834/AC3: given a store that stops at once, when the check waits for it, then its exit code and last log lines are
+// in the error and the container is removed afterwards, not by --rm before anyone could read it.
+func TestAStoreThatDiesSaysWhyItDied(t *testing.T) {
+	var ran []string
+	run := func(_ context.Context, _ string, name string, args ...string) (string, error) {
+		line := name + " " + strings.Join(args, " ")
+		ran = append(ran, line)
+		switch {
+		case args[0] == "exec":
+			return "", errors.New("Error response from daemon: container is not running")
+		case args[0] == "inspect":
+			return "exited exit code 1\n", nil
+		case args[0] == "logs":
+			return "initdb: error: could not create directory: No space left on device\n", nil
+		}
+		return "", nil
+	}
+	err := waitReady(context.Background(), run, "build-1-store", []string{"pg_isready"}, 1)
+	for _, want := range []string{"build-1-store never became ready", "exit code 1", "No space left on device"} {
+		if err == nil || !strings.Contains(err.Error(), want) {
+			t.Errorf("the verdict %q lacks %q", err, want)
+		}
+	}
+	logs := ""
+	for _, l := range ran {
+		if strings.HasPrefix(l, "docker logs") {
+			logs = l
+		}
+	}
+	if logs != "docker logs --tail 20 build-1-store" {
+		t.Errorf("the log was read as %q", logs)
+	}
+}
+
+func TestTheThrowawayStoreIsNotStartedWithRm(t *testing.T) {
+	var started []string
+	run := func(_ context.Context, _ string, name string, args ...string) (string, error) {
+		if args[0] == "run" {
+			started = args
+		}
+		return "127.0.0.1:40000\n", nil
+	}
+	if _, err := throwaway(context.Background(), run, run, "build-1-store", "postgres:17-alpine", 5432, nil, nil); err != nil {
+		t.Fatal(err)
+	}
+	for _, a := range started {
+		if a == "--rm" {
+			t.Errorf("started with --rm, which erases why it died: %v", started)
+		}
+	}
+}
+
+// 1834/AC1: given an image built for a check or a walk and published to the registry, when the build ends, then the
+// local image tag, the narrowed source and the context clone it left are gone; an image published nowhere (a mesh
+// being raised) is kept, since it is the artifact.
+// pushedNamed is a publisher that tags the image as <registry>/<repository> to push it, as the registry one does.
+type pushedNamed struct{ *recorded }
+
+func (pushedNamed) PushedNames(repository string) []string {
+	return []string{"registry.invalid/" + repository}
+}
+
+func TestABuildRemovesWhatItLeftOnTheNode(t *testing.T) {
+	r := &recorded{
+		contents:  map[string]string{"modules/m/" + ManifestName: anImageWithAContext, "modules/m/Dockerfile": "FROM scratch\n"},
+		secondary: map[string]map[string]string{"https://forge.invalid/ctl.git": {"go.mod": "module x\n"}},
+	}
+	workspace := t.TempDir()
+	if _, err := Build(context.Background(), r.run, pushedNamed{r}, "https://forge.invalid/c.git", "modules/m", "", workspace, nil, Npmrc{},
+		GitCredential{}, nil); err != nil {
+		t.Fatal(err)
+	}
+	// Both names go in one rmi: the layers stay while either is left (the push tagged the image with the registry's).
+	if !strings.Contains(strings.Join(r.ran, "\n"), "docker rmi m-server:c0ffeec0 registry.invalid/m/server") {
+		t.Errorf("the image built for it and its pushed name were not removed: %v", r.ran)
+	}
+	left, _ := filepath.Glob(filepath.Join(workspace, "*"))
+	if len(left) != 0 {
+		t.Errorf("the build left %v in its workspace", left)
+	}
+}
+
+const anImageWithAContext = `{"module":"m","version":"1",
+  "build":{"artifacts":[{"name":"server","kind":"image","from":"Dockerfile",
+    "context":{"repository":"https://forge.invalid/ctl.git","ref":"main"}}]}}`
+
+func TestAnImageKeptLocallyIsNotRemoved(t *testing.T) {
+	r := &recorded{contents: map[string]string{"modules/m/" + ManifestName: anImageWithAContext, "modules/m/Dockerfile": "FROM scratch\n"}}
+	local := Local{Run: func(ctx context.Context, dir, name string, args ...string) (string, error) {
+		if args[0] == "image" {
+			return "sha256:" + strings.Repeat("a", 64) + "\n", nil
+		}
+		return r.run(ctx, dir, name, args...)
+	}}
+	if _, err := Build(context.Background(), local.Run, local, "https://forge.invalid/c.git", "modules/m", "", t.TempDir(), nil, Npmrc{},
+		GitCredential{}, nil); err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(strings.Join(r.ran, "\n"), "docker rmi") {
+		t.Errorf("the artifact of a mesh being raised was removed: %v", r.ran)
+	}
+}
+
+// The held image the comparison pulls to read is let go of once read.
+func TestTheHeldImageAComparisonPullsIsRemovedAfterReading(t *testing.T) {
+	var ran []string
+	run := func(_ context.Context, _ string, name string, args ...string) (string, error) {
+		ran = append(ran, name+" "+strings.Join(args, " "))
+		if args[0] == "create" {
+			return "abcdef0123456789\n", nil
+		}
+		if args[0] == "image" {
+			return "", errors.New("stop here")
+		}
+		return "", nil
+	}
+	_, _ = imageContent(context.Background(), run, t.TempDir(), "reg.invalid/m/server@sha256:"+strings.Repeat("a", 64))
+	if got := ran[len(ran)-1]; !strings.HasPrefix(got, "docker rmi reg.invalid/m/server@sha256:") {
+		t.Errorf("the last command was %q, not the removal of the pulled image: %v", got, ran)
+	}
+}
+
+func TestAnImageThatCannotBeRemovedIsNotSaidRemoved(t *testing.T) {
+	var said []string
+	run := func(context.Context, string, string, ...string) (string, error) {
+		return "", errors.New("image is being used")
+	}
+	releaseImage(context.Background(), run, []string{"a:1"}, func(step, format string, args ...any) {
+		said = append(said, format)
+	})
+	for _, s := range said {
+		if strings.Contains(s, "is removed") {
+			t.Errorf("said removed: %q", s)
+		}
+	}
+}

internal/builder/floor.go

@@ -0,0 +1,46 @@
+package builder
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"syscall"
+)
+
+// FreeSpaceFloor is the free space a build node must have, on / and on its workspace's filesystem, before it takes
+// a build or a check (novox/hq issue 1834): under it, a throwaway store cannot initialise its data directory and
+// dies at once, and the check ended "never became ready" instead of saying the disk was full.
+const FreeSpaceFloor = 20 << 30
+
+// FreeBytes reads the bytes an unprivileged writer can still use on the filesystem holding path. A variable so a
+// test answers for a disk it does not have.
+var FreeBytes = func(path string) (uint64, error) {
+	var s syscall.Statfs_t
+	if err := syscall.Statfs(path, &s); err != nil {
+		return 0, err
+	}
+	return s.Bavail * uint64(s.Bsize), nil
+}
+
+// RoomToWork refuses, saying how much is free, when any of the paths' filesystems is under FreeSpaceFloor. A path
+// that does not exist yet (a workspace not made) is read at its nearest folder that does.
+func RoomToWork(paths ...string) error {
+	for _, p := range paths {
+		at := p
+		for {
+			if _, err := os.Stat(at); err == nil || filepath.Dir(at) == at {
+				break
+			}
+			at = filepath.Dir(at)
+		}
+		free, err := FreeBytes(at)
+		if err != nil {
+			return fmt.Errorf("the free space on %s cannot be read: %w", p, err)
+		}
+		if free < FreeSpaceFloor {
+			return fmt.Errorf("the build node has %d GiB free on %s, under the floor of %d GiB",
+				free>>30, p, FreeSpaceFloor>>30)
+		}
+	}
+	return nil
+}

internal/builder/gosource_test.go

@@ -172,11 +172,11 @@ func TestANarrowedTreeHoldsTheBuildSourceAndNothingElse(t *testing.T) {
 	}
 }
 
-// This repository's own programs: the route proxy's build source is not the controller's, and neither
-// holds the other's command.
+// This repository's own programs: the route proxy lives in its module's own Go module, so its build source is
+// not the controller's, and neither holds the other's command.
 func TestThisRepositorysProgramsHaveBuildSourcesOfTheirOwn(t *testing.T) {
 	root := filepath.Join("..", "..")
-	proxy, err := GoBuildSource(root, "examples/route-proxy")
+	proxy, err := GoBuildSource(filepath.Join(root, "modules", "route-proxy"), "cmd/route-proxy")
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -194,15 +194,15 @@ func TestThisRepositorysProgramsHaveBuildSourcesOfTheirOwn(t *testing.T) {
 		file    string
 		held    bool
 	}{
-		{proxy, "the route proxy", "examples/route-proxy/main.go", true},
-		{proxy, "the route proxy", "internal/broker/broker.go", true},
-		{proxy, "the route proxy", "cmd/mesh-controller/main.go", false},
-		{proxy, "the route proxy", "internal/conditions/condition.go", false},
+		{proxy, "the route proxy", "cmd/route-proxy/main.go", true},
+		{proxy, "the route proxy", "cmd/route-proxy/bus.go", true},
+		{proxy, "the route proxy", "go.mod", true},
+		{proxy, "the route proxy", "cmd/route-provider/main.go", false},
 		{proxy, "the route proxy", "README.md", false},
 		{controller, "the controller", "cmd/mesh-controller/main.go", true},
 		{controller, "the controller", "internal/conditions/condition.go", true},
 		{controller, "the controller", "internal/inventory/migrations/0001-nodes.sql", true},
-		{controller, "the controller", "examples/route-proxy/main.go", false},
+		{controller, "the controller", "modules/route-proxy/cmd/route-proxy/main.go", false},
 		{controller, "the controller", "cmd/mesh-builder/main.go", false},
 		{controller, "the controller", "README.md", false},
 		{builder, "the build seat's program", "cmd/mesh-builder/main.go", true},

internal/builder/kill.go

@@ -3,6 +3,7 @@ package builder
 import (
 	"context"
 	"os/exec"
+	"regexp"
 	"strings"
 	"syscall"
 	"time"
@@ -41,6 +42,11 @@ func inItsOwnGroup(cmd *exec.Cmd) {
 	cmd.WaitDelay = KillWait
 }
 
+// CgroupParent is the slice every container a build or check starts joins (novox/hq issue 1798), so the node's own
+// weights and cap bind it: the build-agent module declares the slice with the machine's CPU weight, IO weight and
+// memory limits, and names it in MESH_BUILD_CGROUP_PARENT. Empty, a container joins the runtime's default.
+var CgroupParent string
+
 // Labelled is a Runner that marks every container a build starts with the build's id, so a kill
 // finds what outlived the docker client (novox/hq ADR 0219). Applied at the one place every command
 // passes rather than at each `docker run` the builder composes: a run added later is labelled too.
@@ -55,8 +61,11 @@ func LabelledArgs(name string, args []string, id string) []string {
 	if name != "docker" || len(args) == 0 || args[0] != "run" || id == "" {
 		return args
 	}
-	out := make([]string, 0, len(args)+2)
+	out := make([]string, 0, len(args)+4)
 	out = append(out, "run", "--label", BuildLabel+"="+id)
+	if CgroupParent != "" {
+		out = append(out, "--cgroup-parent", CgroupParent)
+	}
 	return append(out, args[1:]...)
 }
 
@@ -71,12 +80,45 @@ func RemoveContainersOf(ctx context.Context, run Runner, id string) (int, error)
 	if len(ids) == 0 {
 		return 0, nil
 	}
-	if _, err := run(ctx, "", "docker", append([]string{"rm", "-f"}, ids...)...); err != nil {
+	if err := removeWithVolumes(ctx, run, ids); err != nil {
 		return 0, err
 	}
 	return len(ids), nil
 }
 
+// MountedVolumes is the template `docker inspect --format` reads the names of a container's volumes with.
+const MountedVolumes = `{{range .Mounts}}{{if eq .Type "volume"}}{{println .Name}}{{end}}{{end}}`
+
+// anonymousVolume is the name docker gives a volume it makes for an image's VOLUME line: 64 hex digits.
+var anonymousVolume = regexp.MustCompile(`^[0-9a-f]{64}$`)
+
+// removeWithVolumes removes containers together with their anonymous volumes (novox/hq issue 1772). A throwaway
+// store declares its data directory a VOLUME, docker makes an anonymous volume for it, and `docker rm -f`
+// without -v leaves that volume for ever: 1,629 of them, 107 GB, on one build node. So the volumes the
+// containers mount are read first, the containers are removed with -v, and an anonymous volume still there
+// afterwards is removed by name. Only a volume one of these containers mounted, and only one with an anonymous
+// volume's name, is touched: a named volume — an operator's own data — never is. A volume already gone is
+// no failure.
+func removeWithVolumes(ctx context.Context, run Runner, ids []string) error {
+	var volumes []string
+	if out, err := run(ctx, "", "docker", append([]string{"inspect", "--format", MountedVolumes}, ids...)...); err == nil {
+		seen := map[string]bool{}
+		for _, name := range strings.Fields(out) {
+			if anonymousVolume.MatchString(name) && !seen[name] {
+				seen[name] = true
+				volumes = append(volumes, name)
+			}
+		}
+	}
+	if _, err := run(ctx, "", "docker", append([]string{"rm", "-f", "-v"}, ids...)...); err != nil {
+		return err
+	}
+	if len(volumes) > 0 {
+		_, _ = run(ctx, "", "docker", append([]string{"volume", "rm"}, volumes...)...)
+	}
+	return nil
+}
+
 // A holder that stops mid-build leaves its containers running (novox/hq issue 306).
 //
 // A build's containers are removed by the build itself, by a kill, or by the next delivery of the same
@@ -106,7 +148,7 @@ func RemoveLeftBehind(ctx context.Context, run Runner) (int, error) {
 	if len(ids) == 0 {
 		return 0, nil
 	}
-	if _, err := run(ctx, "", "docker", append([]string{"rm", "-f"}, ids...)...); err != nil {
+	if err := removeWithVolumes(ctx, run, ids); err != nil {
 		return 0, err
 	}
 	return len(ids), nil

internal/builder/kill_test.go

@@ -2,6 +2,7 @@ package builder
 
 import (
 	"context"
+	"errors"
 	"reflect"
 	"strings"
 	"testing"
@@ -49,7 +50,8 @@ func TestAKillRemovesTheContainersLabelledWithTheBuild(t *testing.T) {
 	if err != nil || n != 2 {
 		t.Fatalf("%d %v", n, err)
 	}
-	if want := []string{"docker ps -aq --filter label=mesh.build=build-3", "docker rm -f c1 c2"}; !reflect.DeepEqual(ran, want) {
+	if want := []string{"docker ps -aq --filter label=mesh.build=build-3", "docker inspect --format " + MountedVolumes + " c1 c2",
+		"docker rm -f -v c1 c2"}; !reflect.DeepEqual(ran, want) {
 		t.Errorf("ran %v", ran)
 	}
 }
@@ -73,7 +75,7 @@ func TestAStartingHolderRemovesWhatEarlierHoldersLeftAndNothingElse(t *testing.T
 	if n != 3 {
 		t.Errorf("removed %d", n)
 	}
-	if len(ran) != 2 || !reflect.DeepEqual(ran[1], []string{"docker", "rm", "-f", "c1", "c2", "c7"}) {
+	if len(ran) != 3 || !reflect.DeepEqual(ran[2], []string{"docker", "rm", "-f", "-v", "c1", "c2", "c7"}) {
 		t.Fatalf("ran %v", ran)
 	}
 	if !strings.Contains(strings.Join(ran[0], " "), "--filter label=mesh.build") {
@@ -90,3 +92,75 @@ func TestAStartingHolderRemovesWhatEarlierHoldersLeftAndNothingElse(t *testing.T
 		t.Errorf("with nothing of the seat's: %d %v %v", n, err, ran)
 	}
 }
+
+// **Issue 1772**: a throwaway store declares its data directory a VOLUME, so docker makes an anonymous volume for
+// it, and `docker rm -f` without -v leaves that volume behind (1,629 of them, 107 GB, on one build node). Every
+// container a build or check removes is removed with its anonymous volumes (-v), and any volume the container
+// mounted that is still there afterwards is removed by name — those, and only those, never a named volume.
+func TestARemovedContainerTakesItsAnonymousVolumesWithIt(t *testing.T) {
+	anon := strings.Repeat("a", 64)
+	other := strings.Repeat("b", 64)
+	var ran []string
+	run := func(_ context.Context, _ string, name string, args ...string) (string, error) {
+		ran = append(ran, name+" "+strings.Join(args, " "))
+		switch args[0] {
+		case "ps":
+			return "c1\n", nil
+		case "inspect":
+			return anon + "\n" + "compose_data\n" + other + "\n", nil
+		}
+		return "", nil
+	}
+	if n, err := RemoveContainersOf(context.Background(), run, "build-4"); err != nil || n != 1 {
+		t.Fatalf("%d %v", n, err)
+	}
+	last := ran[len(ran)-1]
+	if want := "docker volume rm " + anon + " " + other; last != want {
+		t.Errorf("last command %q, want %q", last, want)
+	}
+	if !strings.Contains(strings.Join(ran, "\n"), "docker rm -f -v c1") {
+		t.Errorf("ran %v", ran)
+	}
+	if strings.Contains(last, "compose_data") {
+		t.Errorf("a named volume was removed: %q", last)
+	}
+}
+
+// A volume already gone when the sweep looks (rm -v took it) is no failure.
+func TestAVolumeAlreadyGoneIsNoFailure(t *testing.T) {
+	run := func(_ context.Context, _ string, name string, args ...string) (string, error) {
+		switch args[0] {
+		case "ps":
+			return "c1\n", nil
+		case "inspect":
+			return strings.Repeat("c", 64) + "\n", nil
+		case "volume":
+			return "", errors.New("no such volume")
+		}
+		return "", nil
+	}
+	if n, err := RemoveContainersOf(context.Background(), run, "build-5"); err != nil || n != 1 {
+		t.Fatalf("%d %v", n, err)
+	}
+}
+
+// A node's build slice limits everything a build or check starts (novox/hq issue 1798): with a parent
+// set, every `docker run` joins it, so the node's CPU and IO weights and memory cap bind the container;
+// with none set the arguments are as they always were.
+func TestEveryContainerJoinsTheNodesBuildSlice(t *testing.T) {
+	was := CgroupParent
+	defer func() { CgroupParent = was }()
+	CgroupParent = "meshbuild.slice"
+	got := LabelledArgs("docker", []string{"run", "--rm", "img", "sh"}, "build-1")
+	want := []string{"run", "--label", "mesh.build=build-1", "--cgroup-parent", "meshbuild.slice", "--rm", "img", "sh"}
+	if !reflect.DeepEqual(got, want) {
+		t.Errorf("1798/AC1: docker run became %v", got)
+	}
+	if got := LabelledArgs("docker", []string{"build", "."}, "build-1"); !reflect.DeepEqual(got, []string{"build", "."}) {
+		t.Errorf("a docker build became %v", got)
+	}
+	CgroupParent = ""
+	if got := LabelledArgs("docker", []string{"run", "img"}, "build-1"); !reflect.DeepEqual(got, []string{"run", "--label", "mesh.build=build-1", "img"}) {
+		t.Errorf("1798/AC1: with no slice, docker run became %v", got)
+	}
+}

internal/builder/registry.go

@@ -43,6 +43,11 @@ type Registry struct {
 	HTTP *http.Client
 }
 
+// PushedNames are the names PublishImage leaves the image under on the node.
+func (r Registry) PushedNames(repository string) []string {
+	return []string{r.Address + "/" + repository}
+}
+
 // PublishImage pushes a locally built image and returns a reference pinned by digest.
 //
 // The digest is read back from the registry's own answer rather than computed here. What matters
@@ -59,15 +64,35 @@ func (r Registry) PublishImage(ctx context.Context, localTag, repository string)
 	}); err != nil {
 		return "", err
 	}
-	out, err := r.Run(ctx, "", "docker", "inspect", "--format", "{{index .RepoDigests 0}}", remote)
+	// Every digest the daemon lists for the image, one per line: the image may have been pushed under other names before
+	// (a check's scratch copy, another registry), and the first of them is not the one this push made (novox/hq issue
+	// 1742: a build recorded a digest the store never held).
+	out, err := r.Run(ctx, "", "docker", "inspect", "--format", "{{range .RepoDigests}}{{println .}}{{end}}", remote)
 	if err != nil {
 		return "", fmt.Errorf("pushed %s and cannot read back what it was pinned as: %w", remote, err)
 	}
-	pinned := strings.TrimSpace(out)
-	if !strings.Contains(pinned, "@sha256:") {
+	first, pinned := "", ""
+	for _, line := range strings.Split(out, "\n") {
+		line = strings.TrimSpace(line)
+		if line == "" {
+			continue
+		}
+		if first == "" {
+			first = line
+		}
+		if strings.HasPrefix(line, remote+"@sha256:") {
+			pinned = line
+			break
+		}
+	}
+	if pinned == "" {
+		if strings.Contains(first, "@sha256:") {
+			return "", fmt.Errorf("pushed %s, but the daemon lists no digest for that name (only %q): the digest of another "+
+				"repository is not what this registry serves", remote, first)
+		}
 		// A tag is not a pin. It can be made to point at something else, and this file is applied
 		// on machines with no mesh to ask about anything (novox/hq ADR 0006).
-		return "", fmt.Errorf("%s came back as %q, which is not pinned by digest", remote, pinned)
+		return "", fmt.Errorf("%s came back as %q, which is not pinned by digest", remote, first)
 	}
 	return pinned, nil
 }

internal/builder/registry_test.go

@@ -252,3 +252,32 @@ func TestAPushedImageComesBackPinned(t *testing.T) {
 		t.Fatalf("it did not tag and then push: %v", ran)
 	}
 }
+
+// 1742: an image pushed under other names before lists their digests too, and the digest recorded is the one of the name
+// this push made — never the first listed, which may be another repository's.
+func TestThePinnedDigestIsTheOneOfTheNamePushed(t *testing.T) {
+	want := "registry.invalid/shell/server@sha256:" + strings.Repeat("b", 64)
+	earlier := "registry.invalid/scratch/shell/server@sha256:" + strings.Repeat("a", 64)
+	r := Registry{Address: "registry.invalid", Run: func(
+		_ context.Context, _, name string, args ...string) (string, error) {
+		if name == "docker" && len(args) > 0 && args[0] == "inspect" {
+			return earlier + "\n" + want + "\n", nil
+		}
+		return "", nil
+	}}
+	got, err := r.PublishImage(context.Background(), "local", "shell/server")
+	if err != nil || got != want {
+		t.Fatalf("pinned %q (%v); want %q", got, err, want)
+	}
+	// Only another repository's digest is listed: the push is not taken for pinned.
+	r.Run = func(_ context.Context, _, name string, args ...string) (string, error) {
+		if name == "docker" && len(args) > 0 && args[0] == "inspect" {
+			return earlier + "\n", nil
+		}
+		return "", nil
+	}
+	if _, err := r.PublishImage(context.Background(), "local", "shell/server"); err == nil ||
+		!strings.Contains(err.Error(), "no digest for that name") {
+		t.Fatalf("a digest of another repository was taken for the push's own: %v", err)
+	}
+}

internal/builder/reuse.go

@@ -253,6 +253,13 @@ func (s scratchPublisher) PublishImage(ctx context.Context, localTag, repository
 	return s.to.PublishImage(ctx, localTag, ScratchPrefix+repository)
 }
 
+func (s scratchPublisher) PushedNames(repository string) []string {
+	if p, ok := s.to.(PushedNames); ok {
+		return p.PushedNames(ScratchPrefix + repository)
+	}
+	return nil
+}
+
 func (s scratchPublisher) PublishArchive(ctx context.Context, repository string, body []byte, digest string) (string, error) {
 	return s.to.PublishArchive(ctx, ScratchPrefix+repository, body, digest)
 }

internal/builder/same_program.go

@@ -88,6 +88,9 @@ func imageContent(ctx context.Context, run Runner, dir, ref string) (string, err
 	if _, err := run(ctx, dir, "docker", "pull", "--quiet", ref); err != nil {
 		return "", fmt.Errorf("pulling %s: %w", ref, err)
 	}
+	// The image is on the node only for the reading (novox/hq issue 1834); one a container still runs is refused by
+	// docker and stays.
+	defer func() { _, _ = run(context.WithoutCancel(ctx), dir, "docker", "rmi", ref) }()
 	config, err := run(ctx, dir, "docker", "image", "inspect", "--format",
 		"{{.Os}}/{{.Architecture}}/{{.Variant}} {{json .Config}}", ref)
 	if err != nil {
@@ -105,7 +108,7 @@ func imageContent(ctx context.Context, run Runner, dir, ref string) (string, err
 	if id == "" {
 		return "", errors.New("the container engine named no container for " + ref)
 	}
-	defer func() { _, _ = run(context.WithoutCancel(ctx), dir, "docker", "rm", "--force", id) }()
+	defer func() { _, _ = run(context.WithoutCancel(ctx), dir, "docker", "rm", "--force", "--volumes", id) }()
 	if err := os.MkdirAll(dir, 0o700); err != nil {
 		return "", err
 	}

internal/inventory/batches.go

@@ -114,6 +114,16 @@ func (i *Inventory) AnswerMerge(ctx context.Context, repository, commit, plan st
 	return i.chainSavePlans(ctx, c, nil, []MergeMove{{Repository: repository, Commit: commit, Plan: plan, Alone: alone}})
 }
 
+// HoldMerge puts a merge back to waiting, no plan answering it, with the event it is kept under replaced (novox/hq issue 1173:
+// a first merge held for a build-agent that reads its manifest, the hold said in its event).
+func (i *Inventory) HoldMerge(ctx context.Context, repository, commit string, event json.RawMessage) error {
+	c, err := i.theChain(ctx)
+	if err != nil {
+		return err
+	}
+	return i.chainSavePlans(ctx, c, nil, []MergeMove{{Repository: repository, Commit: commit, Event: event}})
+}
+
 // Batches is every batch not yet cut: assembling or queued, oldest first. One at a time is the rule; more
 // are read so a fault is seen.
 func (i *Inventory) Batches(ctx context.Context) ([]Plan, error) {

internal/inventory/builds_test.go

@@ -185,7 +185,7 @@ func TestABuildsBuildSourceComesBackOverWhatItRead(t *testing.T) {
 	said.Read = []ReadRepository{{Repository: "novox/mesh-controller", Ref: "main"}, {Repository: "novox/other"}}
 	said.Sources = []BuildSource{
 		{Paths: []string{"modules/route-proxy/Dockerfile", "modules/route-proxy/module.json"}},
-		{Repository: "novox/mesh-controller", Ref: "main", Paths: []string{"examples/route-proxy/", "go.mod"}},
+		{Repository: "novox/mesh-controller", Ref: "main", Paths: []string{"modules/route-proxy/cmd/route-proxy/", "go.mod"}},
 		{Repository: "novox/unread", Paths: []string{"x"}},
 	}
 	unsaid := aBuild("unsaid", "build-agent", "")
@@ -200,7 +200,7 @@ func TestABuildsBuildSourceComesBackOverWhatItRead(t *testing.T) {
 		t.Fatal(err)
 	}
 	want := []ReadRepository{
-		{Repository: "novox/mesh-controller", Ref: "main", Paths: []string{"examples/route-proxy/", "go.mod"}},
+		{Repository: "novox/mesh-controller", Ref: "main", Paths: []string{"modules/route-proxy/cmd/route-proxy/", "go.mod"}},
 		{Repository: "novox/other"},
 		{Paths: []string{"modules/route-proxy/Dockerfile", "modules/route-proxy/module.json"}, Own: true},
 	}
@@ -238,7 +238,7 @@ func TestAFailedNewerBuildLeavesTheBuildSourceStale(t *testing.T) {
 	worked.Asked = time.Now().Add(-time.Hour)
 	worked.Read = []ReadRepository{{Repository: "novox/mesh-controller", Ref: "main"}}
 	worked.Sources = []BuildSource{{Paths: []string{"modules/route-proxy/module.json"}},
-		{Repository: "novox/mesh-controller", Ref: "main", Paths: []string{"examples/route-proxy/"}}}
+		{Repository: "novox/mesh-controller", Ref: "main", Paths: []string{"modules/route-proxy/cmd/route-proxy/"}}}
 	failed := aBuild("failed", "route-proxy", "compile error")
 	failed.Asked = time.Now()
 	for _, b := range []Build{worked, failed} {

internal/inventory/chain_rollouts.go

@@ -634,6 +634,10 @@ func (e *recordEdit) apply(held []chain.HeldMerge) []chain.HeldMerge {
 		}
 		if f, has := e.flag[k]; has {
 			h.Waiting, h.Alone = f.Waiting, f.Alone
+			// A merge put back to waiting may carry a new announcement (HoldMerge); every other flag copies its own.
+			if len(f.Event) > 0 {
+				h.Event = f.Event
+			}
 		}
 		out = append(out, h)
 	}
@@ -758,6 +762,9 @@ func (i *Inventory) chainSavePlans(ctx context.Context, c *chain.Chain, plans []
 		if m.Plan == "" {
 			f := w.m
 			f.Waiting, f.Alone = true, m.Alone
+			if m.Event != nil {
+				f.Event = m.Event
+			}
 			editOf(w.plan).flag[key] = f
 			continue
 		}

internal/inventory/declared_packages_test.go

@@ -0,0 +1,83 @@
+package inventory
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"reflect"
+	"slices"
+	"testing"
+)
+
+// aNodesPackages is the resources of a node whose modules declare packages: one package two modules declare present, one
+// declared absent, and a resource that is no package.
+func aNodesPackages() ([]map[string]any, map[string]string) {
+	return []map[string]any{
+			{"id": "web.pkg-curl", "type": "package", "package": "curl"},
+			{"id": "backup.pkg-curl", "type": "package", "package": "curl"},
+			{"id": "web.pkg-nano", "type": "package", "package": "nano", "absent": true},
+			{"id": "web.conf", "type": "file", "path": "/etc/web.conf"},
+		},
+		map[string]string{"web.pkg-curl": "web", "backup.pkg-curl": "backup", "web.pkg-nano": "web", "web.conf": "web"}
+}
+
+// 1840/AC5: the declared-packages mirror's value for a node names each package with the modules that declare it and whether
+// they declare it absent, and the same declaration is the same bytes however its resources are ordered, so a pass over an
+// unchanged node writes nothing.
+func TestTheDeclaredPackagesValueNamesEachPackageWithItsModules(t *testing.T) {
+	resources, owner := aNodesPackages()
+	got, err := DeclaredPackagesValue("one", resources, owner)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := `{"node":"one","packages":[{"package":"curl","modules":["backup","web"],"absent":false},` +
+		`{"package":"nano","modules":["web"],"absent":true}]}`
+	if string(got) != want {
+		t.Errorf("the value is\n%s\nwant\n%s", got, want)
+	}
+	reversed := slices.Clone(resources)
+	slices.Reverse(reversed)
+	again, err := DeclaredPackagesValue("one", reversed, owner)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !bytes.Equal(got, again) {
+		t.Errorf("the same declaration in another order is other bytes:\n%s\n%s", got, again)
+	}
+	if got := jsonFields(reflect.TypeOf(DeclaredPackagesMirrored{})); !slices.Equal(got, []string{"node", "packages"}) {
+		t.Errorf("the value carries %v", got)
+	}
+}
+
+// A node declaring no package has a value that says so, an empty list and not null.
+func TestANodeDeclaringNoPackageHasAnEmptyList(t *testing.T) {
+	got, err := DeclaredPackagesValue("one", nil, nil)
+	if err != nil || string(got) != `{"node":"one","packages":[]}` {
+		t.Errorf("the value is %s (%v)", got, err)
+	}
+}
+
+// 1840/S3: a node's value stays under the 64 KiB a mirror's key holds at far more packages than a node declares: 600
+// packages, each declared by four modules, is a few times what the largest node declares today.
+func TestTheDeclaredPackagesValueOfABigNodeFitsAKey(t *testing.T) {
+	var resources []map[string]any
+	owner := map[string]string{}
+	for p := 0; p < 600; p++ {
+		for m := 0; m < 4; m++ {
+			id := fmt.Sprintf("module-%d.pkg-%d", m, p)
+			resources = append(resources, map[string]any{"id": id, "type": "package", "package": fmt.Sprintf("package-%d", p)})
+			owner[id] = fmt.Sprintf("module-%d", m)
+		}
+	}
+	got, err := DeclaredPackagesValue("one", resources, owner)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var v DeclaredPackagesMirrored
+	if err := json.Unmarshal(got, &v); err != nil || len(v.Packages) != 600 {
+		t.Fatalf("the value holds %d packages (%v)", len(v.Packages), err)
+	}
+	if len(got) >= 64<<10 {
+		t.Errorf("the value is %d bytes, over the 64 KiB a key holds", len(got))
+	}
+}

internal/inventory/mirrors.go

@@ -5,7 +5,10 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"sort"
 	"time"
+
+	"git.novox.be/novox/mesh-sdk/go/catalogue"
 )
 
 // The values of the controller's record mirrors, built from the store (novox/hq ADR 0289, design 54 §1,
@@ -179,3 +182,75 @@ func (i *Inventory) PredefinedMirror(ctx context.Context) (map[string][]byte, er
 	}
 	return map[string][]byte{PredefinedMirrorKey: value}, nil
 }
+
+// DeclaredOf is a manifest's config declarations as the mirror holds them (DeclaredMirrored), so a pull request's
+// declarations are told to mesh-config in the one shape it reads the trunk's in (novox/hq ADR 0502 clause 2).
+func DeclaredOf(settings map[string]catalogue.SettingDeclaration) (map[string]DeclaredMirrored, error) {
+	raw, err := json.Marshal(settings)
+	if err != nil {
+		return nil, err
+	}
+	return declaredMirrored(raw)
+}
+
+// PackageDeclared is one package a node's modules declare, as the declared-packages mirror holds it (ADR 0507 §5): its
+// name, the modules that declare it that way, sorted, and whether they declare it absent. A package some modules declare
+// present and others absent is two entries; the composition refuses that pair, so it is seen only while it is refused.
+type PackageDeclared struct {
+	Package string   `json:"package"`
+	Modules []string `json:"modules"`
+	Absent  bool     `json:"absent"`
+}
+
+// DeclaredPackagesMirrored is one node's value of the declared-packages mirror, keyed by the node: its packages sorted by
+// name (absent after present). Fixed fields and no time, so the same declaration is the same bytes (ADR 0289 §1).
+type DeclaredPackagesMirrored struct {
+	Node     string            `json:"node"`
+	Packages []PackageDeclared `json:"packages"`
+}
+
+// DeclaredPackagesValue is the mirror's value for one node, from the resources its composition declares and the module that
+// owns each (Composed.Owner, by resource id). A resource that is no package, or names none, is left out.
+func DeclaredPackagesValue(node string, resources []map[string]any, owner map[string]string) ([]byte, error) {
+	type key struct {
+		name   string
+		absent bool
+	}
+	by := map[key]map[string]bool{}
+	for _, r := range resources {
+		if fmt.Sprint(r["type"]) != "package" {
+			continue
+		}
+		name, _ := r["package"].(string)
+		if name == "" {
+			continue
+		}
+		k := key{name, r["absent"] == true}
+		if by[k] == nil {
+			by[k] = map[string]bool{}
+		}
+		if module := owner[fmt.Sprint(r["id"])]; module != "" {
+			by[k][module] = true
+		}
+	}
+	keys := make([]key, 0, len(by))
+	for k := range by {
+		keys = append(keys, k)
+	}
+	sort.Slice(keys, func(i, j int) bool {
+		if keys[i].name != keys[j].name {
+			return keys[i].name < keys[j].name
+		}
+		return !keys[i].absent && keys[j].absent
+	})
+	v := DeclaredPackagesMirrored{Node: node, Packages: []PackageDeclared{}}
+	for _, k := range keys {
+		modules := make([]string, 0, len(by[k]))
+		for m := range by[k] {
+			modules = append(modules, m)
+		}
+		sort.Strings(modules)
+		v.Packages = append(v.Packages, PackageDeclared{Package: k.name, Modules: modules, Absent: k.absent})
+	}
+	return json.Marshal(v)
+}

internal/inventory/plans.go

@@ -2,6 +2,7 @@ package inventory
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"fmt"
 	"slices"
@@ -677,6 +678,8 @@ func (i *Inventory) SavePlan(ctx context.Context, p *Plan) error {
 type MergeMove struct {
 	Repository, Commit, Plan string
 	Alone                    bool
+	// Event replaces the merge's kept announcement when it is put back to waiting (Plan empty); nil leaves it.
+	Event json.RawMessage
 }
 
 // SavePlansMoving writes plans, as SavePlan does each, and gives merges to the plans that answer them, all in one

internal/link/admit_test.go

@@ -0,0 +1,28 @@
+package link
+
+import (
+	"context"
+	"testing"
+
+	"github.com/nats-io/nats.go"
+)
+
+// 1768/AC1: a request dropped as a duplicate of one another builder runs marks nothing in hand: the claim is not made,
+// so no mark is left behind to fail every later claim.
+func TestADuplicateDropIsJudgedBeforeTheClaimSoLeavesNoMark(t *testing.T) {
+	claims := 0
+	m := &natsMachine{
+		opts:      MachineOptions{Claim: func() bool { claims++; return true }},
+		duplicate: func(context.Context, BuildRequest) string { return "ace is running it" },
+	}
+	if m.admit(context.Background(), &nats.Msg{}, BuildRequest{ID: "build-1"}) {
+		t.Fatal("a duplicate was admitted")
+	}
+	if claims != 0 {
+		t.Fatalf("a dropped duplicate was claimed %d times, which leaves the in-hand mark behind", claims)
+	}
+	m.duplicate = func(context.Context, BuildRequest) string { return "" }
+	if !m.admit(context.Background(), &nats.Msg{}, BuildRequest{ID: "build-2"}) || claims != 1 {
+		t.Fatalf("a request that is no duplicate was not claimed once: claims=%d", claims)
+	}
+}

internal/link/build.go

@@ -218,6 +218,25 @@ type CheckRequest struct {
 	Try       bool   `json:"try,omitempty"`
 	Tests     string `json:"tests,omitempty"`
 	StoreOnly bool   `json:"store-only,omitempty"`
+	// HeldConfig are the approved held values of the pull requests this check is of (novox/hq ADR 0502 clause 4): each
+	// a config value the operator approved for a key an open pull request introduces. The merge gate lays them over
+	// their module's values on their node in the composition with the change only, never in the mesh as it is. Empty
+	// from a controller from before it, or when mesh-config held none or did not answer.
+	HeldConfig []HeldConfig `json:"held_config,omitempty"`
+}
+
+// HeldConfig is one approved held value (novox/hq ADR 0502), as mesh-config's `held` action answers it.
+type HeldConfig struct {
+	Pull   string          `json:"pull"`
+	Head   string          `json:"head,omitempty"`
+	Node   string          `json:"node"`
+	Module string          `json:"module"`
+	Key    string          `json:"key"`
+	Value  json.RawMessage `json:"value"`
+	// Approved says who approved it, in words, as mesh-config states it; By and At are who held it and when.
+	Approved string `json:"approved,omitempty"`
+	By       string `json:"by,omitempty"`
+	At       string `json:"at,omitempty"`
 }
 
 // StepTried is the step a build seat says a try's outcome under, in the build's log: one line, a Tried as JSON
@@ -292,6 +311,10 @@ type GroupMember struct {
 	// Base is the branch it merges into: the build seat merges the head into that trunk's head before the
 	// group is composed (novox/hq ADR 0323 §6). A build seat from before it composes the head alone.
 	Base string `json:"base,omitempty"`
+	// Trunk is the base branch's head the forge announced with the head (novox/hq issue 1106): the trunk commit the
+	// composed verdict names for this member when the build seat named none, so a member whose trunk did not move is
+	// never merged-refused for a verdict that names no trunk.
+	Trunk string `json:"trunk,omitempty"`
 }
 
 // Who judges a merge check's gate.