Merge remote-tracking branch 'origin/main' into feat/upgrade-safety

A held merge was asked again by the rule of a first merge, which finds nothing once a sibling module of the
same merge registered, so it stayed held forever; and a second refusal in a merge already held fell through to
a failed build. The hold now keeps a list of module, path and word, a refusal in a held waiting merge joins it,
and the delivery of build-agent asks each held path again on the merge's Approve warrant.

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,61 @@
+//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)
+	}
+	want := []inventory.PackageDeclared{{Package: "curl", Modules: []string{"fetcher", "viewer"}},
+		{Package: "nano", Modules: []string{"viewer"}, Absent: true}}
+	if len(got.Packages) != len(want) {
+		t.Fatalf("anchor declares %+v, want %+v", got.Packages, want)
+	}
+	for i, p := range want {
+		if g := got.Packages[i]; g.Package != p.Package || g.Absent != p.Absent || len(g.Modules) != len(p.Modules) ||
+			(len(p.Modules) > 0 && g.Modules[0] != p.Modules[0]) {
+			t.Errorf("package %d is %+v, want %+v", i, g, p)
+		}
+	}
+	if string(first["laptop"]) != `{"node":"laptop","packages":[]}` {
+		t.Errorf("a node declaring none is %s", first["laptop"])
+	}
+	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/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.20261022123624-5ea6c215a48b
 	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.20261022123624-5ea6c215a48b h1:5bYfSahHJbfPWV2D4h1ejmRyvUevJtrWSpbtiVCsaOQ=
+git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261022123624-5ea6c215a48b/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)
@@ -738,11 +743,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,6 +787,12 @@ func contextFrom(ctx context.Context, run Runner, workspace, artifact, credentia
 	if err := os.RemoveAll(dir); err != nil {
 		return "", err
 	}
+	// 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 := run(ctx, workspace, "git", cloneWith(credentials, "clone", "--quiet", url, dir)...); err != nil {
 		return "", fmt.Errorf("cannot clone %s: %w", url, err)
 	}
@@ -1143,6 +1184,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 +1223,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 +1249,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
@@ -572,6 +613,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 +783,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 +1150,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 +1637,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 +1660,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/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.

internal/link/builds_nats.go

@@ -163,6 +163,8 @@ type natsMachine struct {
 	// build waits, then the checks of pull requests marked ready, then every other check (novox/hq ADR 0406 §3).
 	subs []*takeQueue
 	opts MachineOptions
+	// duplicate stands in for runningElsewhere in tests; nil is the real one.
+	duplicate func(context.Context, BuildRequest) string
 	// gate is what the loop asks of the bus to hold checks while a delivery builds; nil is the bus's (a test sets a fake).
 	gate checkGate
 	// said is the faults of the hold already said, letKey whether this holder created the let-through key for the check it
@@ -405,18 +407,7 @@ func (m *natsMachine) handOver(ctx context.Context, msg *nats.Msg, q *takeQueue,
 			return
 		}
 	}
-	// **Drained in the moment it was fetched** (novox/hq ADR 0335): handed back at once, as a pause
-	// landing then is.
-	if m.opts.Claim != nil && !m.opts.Claim() {
-		_ = msg.Nak()
-		return
-	}
-	// **A duplicate of a check another builder is running is dropped** (issue 1649): an ask redelivered to this machine
-	// because its first holder did not say, in time, that it had it. The running key names that builder and this same
-	// ask; running it a second time would spend a second place on one check.
-	if why := m.runningElsewhere(ctx, request); why != "" {
-		fmt.Fprintf(os.Stderr, "%s is handed out again while another builder runs it and is dropped: %s\n", request.ID, why)
-		_ = msg.Ack()
+	if !m.admit(ctx, msg, request) {
 		return
 	}
 	// A build outlives the acknowledgement window many times over; said while it runs,
@@ -460,6 +451,33 @@ func (m *natsMachine) quiesce(keep *takeQueue) {
 	}
 }
 
+// admit decides whether a fetched request is run here, and answers the message when it is not.
+//
+// **The duplicate is judged before the request is claimed** (issue 1768): a claim marks the build in hand, and a request
+// dropped after it left the mark behind, so every later claim failed and every ask was handed back at once until all
+// had spent their deliveries. A request dropped here has marked nothing.
+//
+// **Drained in the moment it was fetched** (novox/hq ADR 0335): handed back at once, as a pause landing then is.
+func (m *natsMachine) admit(ctx context.Context, msg *nats.Msg, request BuildRequest) bool {
+	// **A duplicate of a check another builder is running is dropped** (issue 1649): an ask redelivered to this machine
+	// because its first holder did not say, in time, that it had it. The running key names that builder and this same
+	// ask; running it a second time would spend a second place on one check.
+	elsewhere := m.runningElsewhere
+	if m.duplicate != nil {
+		elsewhere = m.duplicate
+	}
+	if why := elsewhere(ctx, request); why != "" {
+		fmt.Fprintf(os.Stderr, "%s is handed out again while another builder runs it and is dropped: %s\n", request.ID, why)
+		_ = msg.Ack()
+		return false
+	}
+	if m.opts.Claim != nil && !m.opts.Claim() {
+		_ = msg.Nak()
+		return false
+	}
+	return true
+}
+
 // runningElsewhere says why an ask need not run here, or nothing: the bucket of the checks running says another builder
 // runs this very ask (its id, its head and its trunk commit). A key that cannot be read runs the check.
 func (m *natsMachine) runningElsewhere(ctx context.Context, r BuildRequest) string {

internal/ownmanifest/image_place_test.go

@@ -0,0 +1,92 @@
+package ownmanifest
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// imagesOutOfPlace lists the image artifacts among manifests (module name to its manifest's text) whose Dockerfile
+// is not a file inside that module's own directory, root/<module> (novox/hq ADR 0487 clause 13, which replaced the
+// refusal of the image kind of ADR 0480 clause 11). The image builder builds a module from its directory alone.
+// It reads the manifest as plain JSON, since the catalogue parser refuses some of these itself. It mirrors mesh-catalog's checks/imageplace: an empty from, an absolute one, one leaving the directory with ..,
+// or a name that is no file there, is refused.
+func imagesOutOfPlace(t *testing.T, root string, manifests map[string][]byte) []string {
+	t.Helper()
+	var out []string
+	for module, raw := range manifests {
+		var m struct {
+			Build struct {
+				Artifacts []struct{ Name, Kind, From string } `json:"artifacts"`
+			} `json:"build"`
+		}
+		if err := json.Unmarshal(raw, &m); err != nil {
+			t.Fatalf("%s does not parse: %v", module, err)
+		}
+		for _, a := range m.Build.Artifacts {
+			if a.Kind != "image" {
+				continue
+			}
+			clean := filepath.Clean(a.From)
+			bad := a.From == "" || filepath.IsAbs(clean) || clean == ".." || strings.HasPrefix(clean, ".."+string(filepath.Separator))
+			if !bad {
+				info, err := os.Stat(filepath.Join(root, module, clean))
+				bad = err != nil || info.IsDir()
+			}
+			if bad {
+				out = append(out, module+" ("+a.Name+" from "+a.From+")")
+			}
+		}
+	}
+	return out
+}
+
+// Every image a module of this repository declares is built from a Dockerfile in the module's own directory
+// (novox/hq ADR 0487 clause 13). The catalogue's own modules are held to the same by checks/imageplace in mesh-catalog.
+func TestEveryImageArtifactBuildsFromADockerfileInItsOwnModuleDirectory(t *testing.T) {
+	root := filepath.Join("..", "..", "modules")
+	paths, err := filepath.Glob(filepath.Join(root, "*", "module.json"))
+	if err != nil || len(paths) == 0 {
+		t.Fatalf("no module manifests found in this repository's modules: %v", err)
+	}
+	manifests := map[string][]byte{}
+	for _, p := range paths {
+		raw, err := os.ReadFile(p)
+		if err != nil {
+			t.Fatal(err)
+		}
+		manifests[filepath.Base(filepath.Dir(p))] = raw
+	}
+	if got := imagesOutOfPlace(t, root, manifests); len(got) != 0 {
+		t.Errorf("these image artifacts do not build from a Dockerfile in their own module's directory "+
+			"(ADR 0487 clause 13): %v", got)
+	}
+}
+
+// The check fails on each bad case and passes on a good one, so it holds something.
+func TestAnImageWhoseDockerfileIsOutOfPlaceIsFoundAndOneInPlaceIsNot(t *testing.T) {
+	root := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(root, "x", "sub"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	for _, f := range []string{"x/Dockerfile", "x/sub/Dockerfile", "outside"} {
+		if err := os.WriteFile(filepath.Join(root, f), nil, 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	manifest := func(from string) map[string][]byte {
+		return map[string][]byte{"x": []byte(`{"module":"x","version":"1","build":{"artifacts":[{"name":"server","kind":"image","from":"` + from + `"}]}}`)}
+	}
+	for _, from := range []string{"Dockerfile", "sub/Dockerfile", "./Dockerfile"} {
+		if got := imagesOutOfPlace(t, root, manifest(from)); len(got) != 0 {
+			t.Errorf("from %q: found %v, want none", from, got)
+		}
+	}
+	for _, from := range []string{"", "/etc/Dockerfile", "../outside", "..", "sub/../../outside", "Missing", "sub"} {
+		if got := imagesOutOfPlace(t, root, manifest(from)); len(got) != 1 {
+			t.Errorf("from %q: found %v, want it refused", from, got)
+		}
+	}
+}

internal/ownmanifest/public_issuer_test.go

@@ -11,7 +11,7 @@ import (
 //
 // route-proxy keeps each ACME authority's account and certificates in a directory named after a
 // digest of the directory URL and of the root bundle its `trust` container copies in
-// (examples/route-proxy, forThisAuthority). Until ADR 0226 the URL was rendered from a binding to
+// (modules/route-proxy/cmd/route-proxy, forThisAuthority). Until ADR 0226 the URL was rendered from a binding to
 // `public-acme`'s `acme-ca`, spelled with the port. A URL spelled any other way — even the same
 // authority without `:443` — or a root bundle from another image is a new authority to the proxy:
 // a new account, and every routed name ordered again, on two machines at once, against Let's
@@ -36,8 +36,11 @@ func TestRouteProxyKeepsItsPublicAccountDirectory(t *testing.T) {
 	}
 
 	// As a build would leave it: each artifact a container names resolved to an image. Which image
-	// does not matter to the file checked here.
+	// does not matter to the file checked here. An archive resource carries no image: it unpacks a bundle.
 	for _, res := range m.Resources {
+		if res["type"] == "archive" {
+			continue
+		}
 		if artifact, ok := res["artifact"].(string); ok {
 			delete(res, "artifact")
 			res["image"] = "registry.invalid/route-proxy/" + artifact +
@@ -86,3 +89,57 @@ func TestRouteProxyKeepsItsPublicAccountDirectory(t *testing.T) {
 			"plan for the account (ADR 0226)", trust, trustImage)
 	}
 }
+
+// The proxy's program is mounted into the pinned trust image, not baked into an image (novox/hq ADR 0480 clauses 1,
+// 2 and 4): a Go bundle of the module's own Go module stamped for alpine, unpacked by an archive resource, mounted
+// read-only at /opt/mesh, called through args, and named under restart-on so a new program never leaves the old
+// one running. The container's name, network and logging are what the jail and the routes rely on.
+func TestRouteProxyRunsItsMountedProgramOnTheTrustImage(t *testing.T) {
+	m := catalogueManifest(t, "route-proxy")
+	var bundle *Artifact
+	for i, a := range m.Build.Artifacts {
+		if a.Name == "server" {
+			bundle = &m.Build.Artifacts[i]
+		}
+		if a.Kind == "image" {
+			t.Errorf("artifact %s is an image built from a Dockerfile (ADR 0452 §1)", a.Name)
+		}
+	}
+	if bundle == nil || bundle.Kind != "bundle" || bundle.Language != "go" || bundle.System != "alpine" ||
+		bundle.From != "cmd/route-proxy" || bundle.Binary != "route-proxy" {
+		t.Fatalf("the server artifact is not a Go bundle of cmd/route-proxy stamped for alpine: %+v", bundle)
+	}
+	var archive, server map[string]any
+	for _, r := range m.Resources {
+		switch {
+		case r["type"] == "archive" && r["artifact"] == "server":
+			archive = r
+		case r["id"] == "server":
+			server = r
+		}
+	}
+	if archive == nil || server == nil {
+		t.Fatalf("archive %v or server container %v is missing", archive, server)
+	}
+	if server["artifact"] != "trust" || server["name"] != "route-proxy" || server["network"] != "host" || server["logging"] != "journald" {
+		t.Errorf("the server container moved: %v", server)
+	}
+	mount := archive["path"].(string) + ":/opt/mesh:ro"
+	mounted := false
+	for _, v := range server["volumes"].([]any) {
+		mounted = mounted || v == mount
+	}
+	if !mounted {
+		t.Errorf("the archive is not mounted read-only at /opt/mesh (%s): %v", mount, server["volumes"])
+	}
+	if args, _ := server["args"].([]any); len(args) != 1 || args[0] != "/opt/mesh/route-proxy" {
+		t.Errorf("args are %v, want the mounted program", server["args"])
+	}
+	restarts := false
+	for _, v := range server["restart-on"].([]any) {
+		restarts = restarts || v == archive["id"]
+	}
+	if !restarts {
+		t.Errorf("restart-on %v does not name the archive %v", server["restart-on"], archive["id"])
+	}
+}