Say what each verb replaces, so the agent is pointed at it instead of a shell command (hq ADR 0245)

A seat's verb names the shell commands it is the mesh's way to do, and a module says it for its own
tools in its manifest; the tools verb and module list --json carry both, for the mesh MCP server's
search, the agent's instructions and the guard on its shell.

cmd/mesh-controller/modules.go

@@ -182,6 +182,9 @@ func moduleCommand(ctx context.Context, args []string) error {
 				Requires     []string `json:"requires,omitempty"`
 				Claims       []string `json:"claims,omitempty"`
 				Capabilities []string `json:"capabilities,omitempty"`
+				// Replaces is what each of its own tools replaces (novox/hq ADR 0245), for the console's
+				// search and the agent's instructions.
+				Replaces map[string][]string `json:"replaces,omitempty"`
 			}
 			out := make([]listed, 0, len(entries))
 			for _, e := range entries {
@@ -189,7 +192,7 @@ func moduleCommand(ctx context.Context, args []string) error {
 				l := listed{Module: m.Module, Version: m.Version, Built: e.Source.BuiltFrom, Head: e.Source.Head,
 					Current: e.Provided || e.Source.Repository == "" || e.Source.Current(), Provided: e.Provided,
 					On: append([]string{}, e.On...), Provides: m.Offers(), Requires: m.Requires,
-					Capabilities: m.Capabilities, Tools: declaresTools(m)}
+					Capabilities: m.Capabilities, Tools: declaresTools(m), Replaces: m.Replaces}
 				for _, c := range m.Claims {
 					l.Claims = append(l.Claims, c.At()+"/"+c.Name)
 				}

cmd/mesh-controller/plan.go

@@ -128,7 +128,7 @@ func planFor(ctx context.Context, open *stores, nodeName string) (catalogue.Reso
 	}
 
 	// A recorded module is composed at the build this machine runs, on any send but a person's push
-	// (novox/hq issue 295, ADR 0242).
+	// (novox/hq issue 295, ADR 0245).
 	if _, err := keepRecorded(ctx, open, nodeName, shelf); err != nil {
 		return catalogue.Resolution{}, nil, err
 	}
@@ -439,7 +439,7 @@ func declarationWith(ctx context.Context, open *stores, node string,
 			names = append(names, m.Module)
 		}
 		out.Builds = carriedBuilds(names, composed.LeftOut, current, before)
-		// A recorded module kept at the build the machine runs is recorded as carrying that one (ADR 0242).
+		// A recorded module kept at the build the machine runs is recorded as carrying that one (ADR 0245).
 		kept, err := recordedKept(ctx, open, node)
 		if err != nil {
 			return sendable{}, err

cmd/mesh-controller/push.go

@@ -1082,7 +1082,7 @@ func sendToEach(ctx context.Context, open *stores, names []string) ([]string, er
 		return nil, err
 	}
 
-	// **A recorded build moves only by a person's push** (novox/hq issue 295, ADR 0242): this send — a
+	// **A recorded build moves only by a person's push** (novox/hq issue 295, ADR 0245): this send — a
 	// plan's, a release plan's, a rollback's, a healer's, a rotation's — composes every recorded module at
 	// the build its machine runs. The bus step is a person's word for the bus alone.
 	if ctx, err = sendKeeps(ctx, inv); err != nil {

cmd/mesh-controller/recorded_kept.go

@@ -9,7 +9,7 @@ import (
 	"github.com/novox/mesh-controller/internal/inventory"
 )
 
-// A recorded build reaches a machine only by a person's push (novox/hq issue 295, ADR 0242).
+// A recorded build reaches a machine only by a person's push (novox/hq issue 295, ADR 0245).
 //
 // **A send carries the machine's whole declaration** (ADR 0221), composed from the build the mesh holds
 // of every module on it. A module whose upgrade policy records — postgres, mongodb, keycloak, the
@@ -121,7 +121,7 @@ func keepRecorded(ctx context.Context, open *stores, node string, shelf map[stri
 		if !found {
 			return nil, fmt.Errorf("%s records rather than rolls out, and %s runs its build %s, which the build "+
 				"records no longer hold: this send cannot keep it and does not move it — `push %s` sends the new "+
-				"one on a person's word (novox/hq ADR 0242)", m, node, short(kept[m]), node)
+				"one on a person's word (novox/hq ADR 0245)", m, node, short(kept[m]), node)
 		}
 		shelf[m] = ran
 	}

cmd/mesh-controller/recorded_kept_test.go

@@ -11,7 +11,7 @@ import (
 	"github.com/novox/mesh-controller/internal/link"
 )
 
-// A recorded build reaches a machine only by a person's push (novox/hq issue 295, ADR 0242).
+// A recorded build reaches a machine only by a person's push (novox/hq issue 295, ADR 0245).
 
 // aContainerBuild is a build outcome of a module of containers, each named by id with the image and the
 // health it is given; a policy when one is said.
@@ -189,7 +189,7 @@ func TestARecordedBuildIsCarriedOnlyByAPersonsPush(t *testing.T) {
 	}
 }
 
-// The send says what it recreates (ADR 0242): mail's health checks adopted recreate both its
+// The send says what it recreates (ADR 0245): mail's health checks adopted recreate both its
 // containers, with no new image, every one at once.
 func TestASendSaysWhatItRecreates(t *testing.T) {
 	image := "registry.invalid:5000/mailu/smtp@sha256:" + strings.Repeat("c", 64)

cmd/mesh-controller/release.go

@@ -671,7 +671,7 @@ func backlogCommand(ctx context.Context, sub string, args []string) error {
 }
 
 // sayRecreations says, on each move a send carries, what it does to the module's containers (novox/hq
-// ADR 0242): the build the machine ran against the one it is sent, container by container. Left unsaid
+// ADR 0245): the build the machine ran against the one it is sent, container by container. Left unsaid
 // for a move whose earlier build is not in the records.
 func sayRecreations(ctx context.Context, open *stores, moves []inventory.CarriedMove) {
 	if len(moves) == 0 {

cmd/mesh-controller/release_plan.go

@@ -904,7 +904,7 @@ func firstSend(ctx context.Context, open *stores, p *inventory.Plan, node string
 		strings.Join(sent, ", "))
 	fmt.Printf("%s: tier %d built; sent %d module(s) to %s first in one send (%s), the rest once its gate passes\n",
 		p.ID, p.Tier, len(modules), strings.Join(sent, ", "), strings.Join(modules, ", "))
-	// What the send recreates, said with it (novox/hq ADR 0242).
+	// What the send recreates, said with it (novox/hq ADR 0245).
 	if said := recreationsSaid(carried); said != "" {
 		p.Note += "; " + said
 		fmt.Printf("%s: %s\n", p.ID, said)
@@ -1287,7 +1287,7 @@ func plansCommand(ctx context.Context, args []string) error {
 				case s != nil && s.Gate != nil:
 					fmt.Printf("    %-22s %s\n", "", gateLine(s.Gate))
 				}
-				// What the send to its first machine did to its containers (ADR 0242).
+				// What the send to its first machine did to its containers (ADR 0245).
 				if s != nil && s.Gate != nil {
 					for _, c := range s.Gate.Carried {
 						if c.Recreates != "" {

cmd/mesh-controller/seatverbs.go

@@ -970,9 +970,15 @@ func seatTools() map[string]any {
 		}
 		var tools []map[string]any
 		for _, v := range s.Serves {
-			tools = append(tools, map[string]any{
+			tool := map[string]any{
 				"name": v.Name, "description": v.Description, "input": v.Input, "output": v.Output,
-			})
+			}
+			// What the verb is the mesh's way to do (novox/hq ADR 0245): read by the console's search and
+			// the agent's instructions.
+			if len(v.Replaces) > 0 {
+				tool["replaces"] = v.Replaces
+			}
+			tools = append(tools, tool)
 		}
 		seats = append(seats, map[string]any{"seat": s.Name, "scope": s.Scope, "tools": tools})
 	}

cmd/mesh-controller/seatverbs_test.go

@@ -144,6 +144,23 @@ func TestToolsAnswersTheSeatsRecords(t *testing.T) {
 	if !found {
 		t.Fatal("the mesh-controller seat is not in the listing")
 	}
+	// And what a verb replaces travels with it (novox/hq ADR 0245): the console and the agent's
+	// instructions read it from here.
+	var journal []string
+	for _, s := range seats {
+		if s["seat"] != catalogue.ServiceManagerSeat {
+			continue
+		}
+		tools, _ := s["tools"].([]map[string]any)
+		for _, tool := range tools {
+			if tool["name"] == "journal" {
+				journal, _ = tool["replaces"].([]string)
+			}
+		}
+	}
+	if len(journal) == 0 || journal[0] != "journalctl" {
+		t.Fatalf("the service manager's journal does not say it replaces journalctl: %v", journal)
+	}
 }
 
 // A JSON verb's answer is parsed from what the command wrote to standard output alone; a warning it

internal/catalogue/manifest.go

@@ -426,6 +426,13 @@ type Manifest struct {
 	// module claiming a seat answers what that seat's protocol promises (novox/hq ADR 0118).
 	Tools []string `json:"tools,omitempty"`
 
+	// Replaces says, for a tool of this module's own, the shell commands it is the mesh's way to do —
+	// `{"docker_logs": ["docker logs"]}` — as a seat's verb says it in its definition (novox/hq ADR
+	// 0241). A seat's verb carries its own: what a role replaces is the role's, so a module never says it
+	// for a verb it serves under a claim. The console's search, the agent's instructions and the guard on
+	// its shell are built from both.
+	Replaces map[string][]string `json:"replaces,omitempty"`
+
 	// Instances says whether this module's instances are the same anywhere — `interchangeable` —
 	// so a call that names no machine may be answered by any of them (novox/hq ADR 0160). A fact
 	// about the software, not about the bus: a stateless web tool says it; a database does not,
@@ -1692,6 +1699,7 @@ func ParseManifest(raw []byte) (Manifest, error) {
 		}
 	}
 	problems = append(problems, invokeProblems(m)...)
+	problems = append(problems, replacesProblems(m)...)
 	problems = append(problems, endpointNameProblems(m)...)
 	problems = append(problems, RouteProblems(m)...)
 	for _, port := range m.Guards {
@@ -2306,6 +2314,53 @@ func EndpointPort(m Manifest, name string) (int, bool) {
 	return 0, false
 }
 
+// MaxReplaced is the longest command a tool may say it replaces: a command's name and the words that
+// make it this command, never a script.
+const MaxReplaced = 80
+
+// replacesProblems judges what a module says its tools replace (novox/hq ADR 0245): each key a tool it
+// declares, each entry a command line of one line, short, and said once.
+func replacesProblems(m Manifest) []string {
+	var problems []string
+	tools := map[string]bool{}
+	for _, t := range m.Tools {
+		tools[t] = true
+	}
+	keys := make([]string, 0, len(m.Replaces))
+	for k := range m.Replaces {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	for _, tool := range keys {
+		if !tools[tool] {
+			problems = append(problems, fmt.Sprintf("%s says what %q replaces, and declares no such tool: "+
+				"a module says it for a tool in its `tools`; a seat's verb says it in the seat's definition "+
+				"(novox/hq ADR 0245)", m.Module, tool))
+			continue
+		}
+		if len(m.Replaces[tool]) == 0 {
+			problems = append(problems, fmt.Sprintf("%s says %s replaces nothing: leave it out", m.Module, tool))
+		}
+		seen := map[string]bool{}
+		for _, c := range m.Replaces[tool] {
+			c = strings.TrimSpace(c)
+			switch {
+			case c == "":
+				problems = append(problems, fmt.Sprintf("%s: %s replaces an empty command", m.Module, tool))
+			case strings.ContainsAny(c, "\n\r"):
+				problems = append(problems, fmt.Sprintf("%s: %s replaces %q, which is more than one line", m.Module, tool, c))
+			case len(c) > MaxReplaced:
+				problems = append(problems, fmt.Sprintf("%s: %s replaces %q, longer than %d characters: "+
+					"the command's name and the words that make it this command", m.Module, tool, c, MaxReplaced))
+			case seen[c]:
+				problems = append(problems, fmt.Sprintf("%s: %s replaces %q twice", m.Module, tool, c))
+			}
+			seen[c] = true
+		}
+	}
+	return problems
+}
+
 // invokeProblems judges what a module says it calls (novox/hq ADR 0152).
 //
 // Refused here, in the manifest's words, rather than at the next composition of the bus's user

internal/catalogue/operators_machine_test.go

@@ -42,7 +42,7 @@ func TestTheServiceManagerSeatServesTheUnitVerbs(t *testing.T) {
 	if seat.Scope != ScopeNode {
 		t.Fatalf("the service manager is a role each machine has once, and the seat is %s-scoped", seat.Scope)
 	}
-	want := []string{"units", "status", "start", "stop", "restart", "enable", "disable", "journal"}
+	want := []string{"units", "status", "start", "stop", "restart", "enable", "disable", "journal", "failed"}
 	var got []string
 	for _, v := range seat.Serves {
 		got = append(got, v.Name)
@@ -58,3 +58,53 @@ func TestTheServiceManagerSeatServesTheUnitVerbs(t *testing.T) {
 		t.Fatalf("the seat serves %v, not %v", got, want)
 	}
 }
+
+// **`failed` joins the seat optional** (the operator's direction 2026-10-07): the holder running today,
+// which does not serve it, still holds the seat; the holder that serves it is not refused; and a verb
+// the seat does not promise is still refused, and one it requires is still required.
+func TestFailedIsAnOptionalVerbOfTheServiceManager(t *testing.T) {
+	seat, _ := SeatNamed(ServiceManagerSeat)
+	holder := func(serves ...string) Manifest {
+		return Manifest{Module: "systemd", Version: "1", Claims: []Claim{{Name: ServiceManagerSeat, Scope: ScopeNode, Serves: serves}}}
+	}
+	eight := []string{"units", "status", "start", "stop", "restart", "enable", "disable", "journal"}
+	if err := CanHold(holder(eight...), seat); err != nil {
+		t.Fatalf("today's holder, without failed, is refused: %v", err)
+	}
+	if err := CanHold(holder(append(eight, "failed")...), seat); err != nil {
+		t.Fatalf("a holder serving failed is refused: %v", err)
+	}
+	if err := CanHold(holder(append(eight, "fail")...), seat); err == nil || !strings.Contains(err.Error(), "does not promise") {
+		t.Fatalf("a verb the seat does not promise was accepted: %v", err)
+	}
+	if err := CanHold(holder(eight[1:]...), seat); err == nil || !strings.Contains(err.Error(), "does not serve units") {
+		t.Fatalf("a holder missing a required verb was accepted: %v", err)
+	}
+	for _, v := range seat.Serves {
+		if v.Optional != (v.Name == "failed") {
+			t.Errorf("%s optional: %v", v.Name, v.Optional)
+		}
+	}
+}
+
+// The optional mark is not stored, so a seat set read back from the store's rows takes it from the
+// compiled seat: otherwise `failed`, seeded into the row, would come back required.
+func TestAnOptionalVerbStaysOptionalInASetReadFromTheStore(t *testing.T) {
+	defer UseSeats(DefaultSeats())
+	var rows []Seat
+	for _, s := range DefaultSeats() {
+		row := s
+		row.Serves = nil
+		for _, v := range s.Serves {
+			row.Serves = append(row.Serves, Verb{Name: v.Name, Description: v.Description, Input: v.Input})
+		}
+		rows = append(rows, row)
+	}
+	UseSeats(rows)
+	seat, _ := SeatNamed(ServiceManagerSeat)
+	holder := Manifest{Module: "systemd", Version: "1", Claims: []Claim{{Name: ServiceManagerSeat, Scope: ScopeNode,
+		Serves: []string{"units", "status", "start", "stop", "restart", "enable", "disable", "journal"}}}}
+	if err := CanHold(holder, seat); err != nil {
+		t.Fatalf("a set read from rows refuses today's holder: %v", err)
+	}
+}

internal/catalogue/recreates.go

@@ -8,7 +8,7 @@ import (
 	"strings"
 )
 
-// What a move does to a module's containers (novox/hq ADR 0242).
+// What a move does to a module's containers (novox/hq ADR 0245).
 //
 // A container whose declaration changes is recreated, whatever changed in it: an image, an environment
 // variable, a health check adopted. A module whose containers are recreated in one send is down while

internal/catalogue/replaces_test.go

@@ -0,0 +1,119 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+// The verbs an agent works around most say what they replace (novox/hq ADR 0245): the journal, a
+// restart, a unit's status, the hosts file — each the command the agent would otherwise type over ssh.
+func TestTheVerbsWorkedAroundSayWhatTheyReplace(t *testing.T) {
+	want := map[string]string{
+		ServiceManagerSeat + ".journal": "journalctl",
+		ServiceManagerSeat + ".restart": "systemctl restart",
+		ServiceManagerSeat + ".status":  "systemctl status",
+		"node-hostname.add":             "edit /etc/hosts",
+		ControllerSeatName + ".node":    "hostnamectl",
+	}
+	for _, s := range DefaultSeats() {
+		for _, v := range s.Serves {
+			cmd, ok := want[s.Name+"."+v.Name]
+			if !ok {
+				continue
+			}
+			delete(want, s.Name+"."+v.Name)
+			found := false
+			for _, r := range v.Replaces {
+				found = found || r == cmd
+			}
+			if !found {
+				t.Errorf("%s.%s does not say it replaces %q: %v", s.Name, v.Name, cmd, v.Replaces)
+			}
+		}
+	}
+	for verb := range want {
+		t.Errorf("%s is not a verb of the compiled seats", verb)
+	}
+}
+
+// Every command a seat's verb replaces is one short line, said once — what the guard and the search match.
+func TestEveryReplacedCommandIsOneShortLine(t *testing.T) {
+	for _, s := range DefaultSeats() {
+		for _, v := range s.Serves {
+			seen := map[string]bool{}
+			for _, r := range v.Replaces {
+				if strings.TrimSpace(r) == "" || strings.ContainsAny(r, "\n\r") || len(r) > MaxReplaced || seen[r] {
+					t.Errorf("%s.%s replaces %q, which is not one short line said once", s.Name, v.Name, r)
+				}
+				seen[r] = true
+			}
+		}
+	}
+}
+
+// A verb's definition in a manifest may say what it replaces, like the mesh's own.
+func TestAVerbDefinitionCarriesWhatItReplaces(t *testing.T) {
+	m, err := ParseManifest([]byte(`{"module":"till","version":"1","tools":["refund"],` +
+		`"seats":[{"name":"shop-till","serves":[{"name":"refund","replaces":["psql -c refund"]}]}],` +
+		`"claims":[{"name":"shop-till","scope":"mesh"}]}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := m.DefinesSeats[0].Serves[0].Replaces; len(got) != 1 || got[0] != "psql -c refund" {
+		t.Fatalf("replaces not read: %v", got)
+	}
+}
+
+// A module says what its own tools replace, and only for a tool it declares.
+func TestAModuleSaysWhatItsOwnToolsReplace(t *testing.T) {
+	m, err := ParseManifest([]byte(`{"module":"docker","version":"1","tools":["docker_logs","docker_list"],` +
+		`"replaces":{"docker_logs":["docker logs"],"docker_list":["docker ps"]}}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if m.Replaces["docker_logs"][0] != "docker logs" || m.Replaces["docker_list"][0] != "docker ps" {
+		t.Fatalf("replaces not read: %v", m.Replaces)
+	}
+	for _, c := range []struct{ manifest, says string }{
+		{`{"module":"docker","version":"1","tools":["docker_logs"],"replaces":{"docker_lgos":["docker logs"]}}`,
+			"declares no such tool"},
+		{`{"module":"docker","version":"1","tools":["docker_logs"],"replaces":{"docker_logs":[]}}`, "replaces nothing"},
+		{`{"module":"docker","version":"1","tools":["docker_logs"],"replaces":{"docker_logs":[" "]}}`, "empty command"},
+		{`{"module":"docker","version":"1","tools":["docker_logs"],"replaces":{"docker_logs":["docker logs\nrm -rf /"]}}`,
+			"more than one line"},
+		{`{"module":"docker","version":"1","tools":["docker_logs"],"replaces":{"docker_logs":["docker logs","docker logs"]}}`,
+			"twice"},
+		{`{"module":"docker","version":"1","tools":["docker_logs"],"replaces":{"docker_logs":["` + strings.Repeat("x", MaxReplaced+1) + `"]}}`,
+			"longer than"},
+	} {
+		if _, err := ParseManifest([]byte(c.manifest)); err == nil || !strings.Contains(err.Error(), c.says) {
+			t.Errorf("%s: want a refusal saying %q, got %v", c.manifest, c.says, err)
+		}
+	}
+}
+
+// A seat row the store seeded before `replaces` existed carries none; the working set takes the compiled
+// one, so the `tools` answer says it on a mesh whose rows exist.
+func TestASeededRowTakesWhatItsVerbsReplaceFromTheCompiledSeat(t *testing.T) {
+	was := Seats()
+	t.Cleanup(func() { UseSeats(was) })
+	var row Seat
+	for _, s := range DefaultSeats() {
+		if s.Name == ServiceManagerSeat {
+			row = s
+		}
+	}
+	stored := make([]Verb, len(row.Serves))
+	for i, v := range row.Serves {
+		v.Replaces = nil
+		stored[i] = v
+	}
+	row.Serves = stored
+	UseSeats([]Seat{row})
+	got, _ := SeatNamed(ServiceManagerSeat)
+	for _, v := range got.Serves {
+		if v.Name == "journal" && (len(v.Replaces) == 0 || v.Replaces[0] != "journalctl") {
+			t.Fatalf("the seeded journal verb says it replaces %v", v.Replaces)
+		}
+	}
+}

internal/catalogue/seats.go

@@ -102,10 +102,10 @@ var defaultSeats = append([]Seat{
 	{Name: "mesh-store", Scope: ScopeMesh, Delivers: "postgres-database", Decision: "novox/hq ADR 0079",
 		Serves: []Verb{
 			{Name: "databases", Description: "Every database the store holds, with its on-disk size.",
-				Input: schema(map[string]string{}, nil)},
+				Input: schema(map[string]string{}, nil), Replaces: []string{"psql -l"}},
 			{Name: "query", Description: "One read-only statement against one database the store holds.",
 				Input: schema(map[string]string{"database": "the database to query", "sql": "the read-only statement"},
-					[]string{"database", "sql"})},
+					[]string{"database", "sql"}), Replaces: []string{"psql"}},
 		}},
 	// **Delivers the mesh's own bus, not `amqp`.** Those were the same word until
 	// ADR 0127 separated them: `amqp` is a backing service a module may require, and this seat is
@@ -174,15 +174,16 @@ var defaultSeats = append([]Seat{
 		Serves: []Verb{
 			{Name: "entries", Description: "Every line of this machine's /etc/hosts, each marked whose it is: " +
 				"the operator's, or the block of the module or tool that writes it.",
-				Input: schema(map[string]string{}, nil)},
+				Input: schema(map[string]string{}, nil), Replaces: []string{"cat /etc/hosts", "getent hosts"}},
 			{Name: "add", Description: "Add one address and its names to the operator's lines of this machine's " +
 				"/etc/hosts — a name for this machine's own programs, not the mesh's.",
 				Input: schema(map[string]string{"address": "the IPv4 or IPv6 address",
-					"names": "the names for it, separated by spaces"}, []string{"address", "names"})},
+					"names": "the names for it, separated by spaces"}, []string{"address", "names"}),
+				Replaces: []string{"edit /etc/hosts", "HOSTALIASES"}},
 			{Name: "remove", Description: "Remove one name, or every line of one address, from the operator's " +
 				"lines of this machine's /etc/hosts. A line a module writes is refused, naming the module.",
 				Input: schema(map[string]string{"name": "a host name, or an address to remove every line of"},
-					[]string{"name"})},
+					[]string{"name"}), Replaces: []string{"sed -i /etc/hosts"}},
 		}},
 	// The intrusion prevention's verbs (novox/hq ADR 0179): what a person asks a machine's ban list
 	// whatever keeps it — who is banned and why, ban one address, let one go. Every holder serves all
@@ -191,15 +192,17 @@ var defaultSeats = append([]Seat{
 		Serves: []Verb{
 			{Name: "status", Description: "Every jail on this machine with how many it is watching and " +
 				"holding now, and the totals since the jail started; one jail's detail when named.",
-				Input: schema(map[string]string{"jail": "one jail (optional)"}, nil)},
+				Input: schema(map[string]string{"jail": "one jail (optional)"}, nil), Replaces: []string{"fail2ban-client status"}},
 			{Name: "banned", Description: "Every address banned on this machine right now, with the jail " +
 				"that holds it and when the ban ends.",
-				Input: schema(map[string]string{"jail": "one jail (optional)"}, nil)},
+				Input: schema(map[string]string{"jail": "one jail (optional)"}, nil), Replaces: []string{"fail2ban-client banned"}},
 			{Name: "ban", Description: "Ban one address in one jail now, for the jail's ban time — an " +
 				"operator's act on the live ban list, which the mesh never writes itself.",
-				Input: schema(map[string]string{"ip": "the address", "jail": "the jail to hold it"}, []string{"ip", "jail"})},
+				Input:    schema(map[string]string{"ip": "the address", "jail": "the jail to hold it"}, []string{"ip", "jail"}),
+				Replaces: []string{"fail2ban-client set banip"}},
 			{Name: "unban", Description: "Let one address go, from one jail or from every jail when none is named.",
-				Input: schema(map[string]string{"ip": "the address", "jail": "one jail (optional)"}, []string{"ip"})},
+				Input:    schema(map[string]string{"ip": "the address", "jail": "one jail (optional)"}, []string{"ip"}),
+				Replaces: []string{"fail2ban-client unban", "fail2ban-client set unbanip"}},
 		}},
 	// The packet filter's verbs (novox/hq ADR 0170): what a person asks a machine's filter whatever
 	// filter answers — the rules as enforced, reload the mesh's own, remove one thing the mesh did
@@ -210,15 +213,17 @@ var defaultSeats = append([]Seat{
 				"ruleset and, where the tool exists, the legacy filter's listings. Narrowed to one table or " +
 				"chain when asked.",
 				Input: schema(map[string]string{"table": "one nftables table, as `family name` (optional)",
-					"chain": "one chain of that table (optional)"}, nil)},
+					"chain": "one chain of that table (optional)"}, nil),
+				Replaces: []string{"nft list ruleset", "iptables -L", "iptables-save"}},
 			{Name: "reload", Description: "Load the mesh's own filter again from the file the mesh writes, " +
 				"and answer with the mesh's table as loaded.",
-				Input: schema(map[string]string{}, nil)},
+				Input: schema(map[string]string{}, nil), Replaces: []string{"nft -f"}},
 			{Name: "remove", Description: "Remove one rule set the mesh did not write, named exactly as the " +
 				"host reports it (novox/hq ADR 0168) — `chain X (iptables-legacy)` or `table ip6 filter, chain " +
 				"DOCKER-USER`. Refuses the mesh's tables, the runtime's own chains, a built-in chain and an " +
 				"active found firewall's chains. An operator's act, by name, never a flush.",
-				Input: schema(map[string]string{"where": "the rule set, as `node show` lists it"}, []string{"where"})},
+				Input:    schema(map[string]string{"where": "the rule set, as `node show` lists it"}, []string{"where"}),
+				Replaces: []string{"nft delete", "iptables -X"}},
 		}},
 	// The machine's service manager (novox/hq ADR 0177). The host applies every declared unit,
 	// system or user scope; the holder answers questions and operator acts about them, each verb
@@ -338,12 +343,48 @@ func UseSeats(s []Seat) {
 		if d, known := byName[row.Name]; known {
 			row.Receives = d.Receives
 			row.Replicated = d.Replicated
+			row.Serves = optionalAsCompiled(row.Serves, d.Serves)
 		}
 		merged = append(merged, row)
 	}
 	seats = merged
 }
 
+// optionalAsCompiled is a row's verbs with each one the compiled seat marks optional marked so. The mark
+// is never stored (Verb.Optional), and a row is what the working set holds once the store is read: a verb
+// the seeding added to the row — `failed`, `checks` — would otherwise come back required, and every holder
+// not serving it yet would be refused at registration and at handover, which the mark exists to prevent.
+//
+// **And what a verb replaces is the compiled one** (novox/hq ADR 0245): a row seeded before the field
+// existed carries none, and re-seeding widens a verb's arguments only, so read from the row alone the
+// `tools` answer — what the mesh MCP server's search and the agent's instructions are built from — would
+// say no verb replaces anything on a mesh whose rows exist. The mesh's statement of what a role replaces
+// is this binary's, like the optional mark.
+func optionalAsCompiled(row, compiled []Verb) []Verb {
+	optional := map[string]bool{}
+	replaces := map[string][]string{}
+	for _, v := range compiled {
+		if v.Optional {
+			optional[v.Name] = true
+		}
+		if len(v.Replaces) > 0 {
+			replaces[v.Name] = v.Replaces
+		}
+	}
+	if len(optional) == 0 && len(replaces) == 0 {
+		return row
+	}
+	out := make([]Verb, len(row))
+	for i, v := range row {
+		v.Optional = optional[v.Name]
+		if r, ok := replaces[v.Name]; ok {
+			v.Replaces = r
+		}
+		out[i] = v
+	}
+	return out
+}
+
 // aliases maps a seat's former names to its current canonical name (novox/hq ADR 0122). Loaded from
 // the store alongside the set, so a reference to a name a seat used to have — a manifest's claim, a
 // held record — still resolves to it after a rename, and nothing downstream has to change.
@@ -561,7 +602,8 @@ func SeatsWithAProtocol() []Seat {
 // serviceManagerVerbs is the contract every holder of node-service-manager serves (novox/hq ADR
 // 0177): the units on the machine in both scopes, read and acted on by name. Every verb takes an
 // optional scope — "system" when absent, "user" for the operator account's own manager — so a
-// caller asks for a user unit the way it asks for a system one.
+// caller asks for a user unit the way it asks for a system one; `failed` alone reads both managers
+// when none is named, and is optional (Verb.Optional).
 func serviceManagerVerbs() []Verb {
 	scoped := func(more map[string]string, required []string) map[string]any {
 		props := map[string]string{"scope": "\"system\" (the default) or \"user\": the operator account's own manager"}
@@ -573,21 +615,43 @@ func serviceManagerVerbs() []Verb {
 	unit := map[string]string{"unit": "the unit's name, as the service manager knows it"}
 	return []Verb{
 		{Name: "units", Description: "The units the service manager knows in a scope, each with its load, active and sub state; narrowed to a pattern when asked.",
-			Input: scoped(map[string]string{"pattern": "a glob the unit's name must match (optional)"}, nil)},
+			Input: scoped(map[string]string{"pattern": "a glob the unit's name must match (optional)"}, nil), Replaces: []string{"systemctl list-units"}},
 		{Name: "status", Description: "One unit as the service manager sees it now: its states, whether it starts at boot, its main process, and whether the mesh declares it.",
-			Input: scoped(unit, []string{"unit"})},
+			Input: scoped(unit, []string{"unit"}), Replaces: []string{"systemctl status", "systemctl is-active"}},
 		{Name: "start", Description: "Start one unit. For a unit the mesh declares, the answer says the host will restore what its declaration says at the next apply.",
-			Input: scoped(unit, []string{"unit"})},
+			Input: scoped(unit, []string{"unit"}), Replaces: []string{"systemctl start"}},
 		{Name: "stop", Description: "Stop one unit; for a mesh-declared unit the answer says the host will restore its declared state.",
-			Input: scoped(unit, []string{"unit"})},
+			Input: scoped(unit, []string{"unit"}), Replaces: []string{"systemctl stop"}},
 		{Name: "restart", Description: "Restart one unit.",
-			Input: scoped(unit, []string{"unit"})},
+			Input: scoped(unit, []string{"unit"}), Replaces: []string{"systemctl restart"}},
 		{Name: "enable", Description: "Make one unit start at boot (or at the account's login, in user scope).",
-			Input: scoped(unit, []string{"unit"})},
+			Input: scoped(unit, []string{"unit"}), Replaces: []string{"systemctl enable"}},
 		{Name: "disable", Description: "Stop one unit starting at boot (or at login, in user scope).",
-			Input: scoped(unit, []string{"unit"})},
-		{Name: "journal", Description: "The last lines of one unit's journal.",
-			Input: scoped(map[string]string{"unit": unit["unit"], "lines": "how many lines from the end (default 100)"}, []string{"unit"})},
+			Input: scoped(unit, []string{"unit"}), Replaces: []string{"systemctl disable"}},
+		// **A window, not only a tail** (the operator's direction 2026-10-07): an incident is read for the
+		// minutes it happened in, and with no window on the verb a person reached for a shell. Every
+		// argument is the holder's to validate — passed to journalctl as one word of its own, never through
+		// a shell — and what the unit printed of a secret is redacted before it is answered.
+		{Name: "journal", Description: "The last lines of one unit's journal (at most 2000), in a time window and " +
+			"narrowed to a priority and to lines holding a text when asked. A secret the unit printed is shown as " +
+			"[redacted: <what it was>].",
+			Input: scoped(map[string]string{
+				"unit":     unit["unit"],
+				"lines":    "how many lines from the end of what matches (default 100, at most 2000)",
+				"since":    "the window's start: an RFC 3339 time (2026-10-07T09:30:00Z) or relative to now (-30min, -2h, yesterday) (optional)",
+				"until":    "the window's end, in the same forms (optional; now when absent)",
+				"match":    "only the lines holding this text, as written — a fixed string, not a pattern (optional)",
+				"priority": "only entries this severe or more: 0-7 or emerg, alert, crit, err, warning, notice, info, debug (optional)",
+			}, []string{"unit"}),
+			Replaces: []string{"journalctl"}},
+		// What has failed, on the seat rather than as one holder's own tool: whatever holds the role answers
+		// it, so a caller asks every machine the same way. **Optional while its holders catch up**: the
+		// systemd module running today serves it as its own systemd_failed, and a required verb would
+		// refuse it before the version serving `failed` could be delivered.
+		{Name: "failed", Optional: true, Description: "Every failed unit on this machine, in the system manager and in the operator " +
+			"account's; a manager that does not answer is reported with its error, never as nothing failed.",
+			Input:    schema(map[string]string{"scope": "\"system\" or \"user\": only that manager (both when absent)"}, nil),
+			Replaces: []string{"systemctl --failed"}},
 	}
 }
 
@@ -600,10 +664,10 @@ func backupVerbs() []Verb {
 	return []Verb{
 		{Name: "backed-up", Description: "What this machine backs up: each module, what it declared, " +
 			"its last good night, how many restore points are kept and the repository's size.",
-			Input: schema(map[string]string{"module": "one module (optional)"}, nil)},
+			Input: schema(map[string]string{"module": "one module (optional)"}, nil), Replaces: []string{"restic snapshots"}},
 		{Name: "now", Description: "Take a backup now, of one module or of every module on this " +
 			"machine — before a migration, a retirement or anything else that could go wrong.",
-			Input: schema(map[string]string{"module": "one module (optional)"}, nil)},
+			Input: schema(map[string]string{"module": "one module (optional)"}, nil), Replaces: []string{"restic backup"}},
 		{Name: "restore", Description: "Restore one module's data from a restore point BESIDE the live " +
 			"data, never over it: each directory as <path>.restored-<date>. Swapping it in is a " +
 			"person's act. Lists the restore points when none is named.",
@@ -611,7 +675,7 @@ func backupVerbs() []Verb {
 				"module":   "the module",
 				"snapshot": "the restore point (from `backed-up`; the newest when omitted)",
 				"path":     "one of the module's directories (all of them when omitted)",
-			}, []string{"module"})},
+			}, []string{"module"}), Replaces: []string{"restic restore"}},
 	}
 }
 

internal/catalogue/verbs.go

@@ -30,6 +30,13 @@ type Verb struct {
 	// the mark is removed and the verb is a condition of holding like the rest. Never stored or said: the
 	// seat set's protocol is the compiled one.
 	Optional bool `json:"-"`
+	// Replaces are the shell commands this verb is the mesh's way to do, each as it is typed —
+	// `journalctl`, `systemctl restart` — so the agent finds the verb by the command it would have run
+	// and is told to call it instead (novox/hq ADR 0245): the mesh MCP server's search matches them, the agent's
+	// instructions list them, and the guard on its shell names the verb when it refuses a work-around.
+	// A command line is matched by its words in order, the first being the command's name; `edit
+	// /etc/hosts` and `HOSTALIASES` name the guard's two local work-arounds for a mesh name.
+	Replaces []string `json:"replaces,omitempty"`
 }
 
 func (v *Verb) UnmarshalJSON(raw []byte) error {
@@ -94,7 +101,8 @@ var ControllerVerbs = []Verb{
 	{Name: "nodes", Description: "Every machine the mesh knows, with whether it is converged or adopted.",
 		Input: schema(nil, nil)},
 	{Name: "node", Description: "What one machine reported it can do, what it is assigned, and why.",
-		Input: schema(map[string]string{"node": "the machine's name"}, []string{"node"})},
+		Input:    schema(map[string]string{"node": "the machine's name"}, []string{"node"}),
+		Replaces: []string{"hostnamectl", "uptime"}},
 	{Name: "modules", Description: "Every module the mesh holds: version, the commit it was built from, " +
 		"and which machines run it.",
 		Input: schema(nil, nil)},

internal/inventory/plans.go

@@ -153,7 +153,7 @@ type CarriedMove struct {
 	To     string `json:"to"`
 	Build  string `json:"build,omitempty"`
 	// Recreates is what the send does to the module's containers, in the mesh's words — how many it
-	// recreates, and whether with a new image or only their declaration (novox/hq ADR 0242); empty when
+	// recreates, and whether with a new image or only their declaration (novox/hq ADR 0245); empty when
 	// it recreates none, or when the build the machine ran is not known.
 	Recreates string `json:"recreates,omitempty"`
 }

internal/inventory/seats.go

@@ -126,6 +126,16 @@ func (i *Inventory) widenProtocol(ctx context.Context, s catalogue.Seat) error {
 		if s.Name == catalogue.ControllerSeatName && !sameVerb(row.Serves[at], v) {
 			row.Serves[at] = v
 			changed = true
+			continue
+		}
+		// **Any other seat's verb gains the arguments the binary names and the row lacks** — additive,
+		// as the rest of the protocol is. The console refuses an argument the row does not name (issue
+		// 244), so a holder taught a new argument (the service manager's journal window) would be
+		// unreachable through it while the row kept the older schema. Nothing the row has is removed or
+		// made required; the description is the binary's, since it describes the arguments added.
+		if widened, ok := widenInput(row.Serves[at], v); ok {
+			row.Serves[at] = widened
+			changed = true
 		}
 	}
 	if !changed {
@@ -296,6 +306,45 @@ func (i *Inventory) Holdings(ctx context.Context) ([]catalogue.Held, error) {
 	return out, rows.Err()
 }
 
+// widenInput is the row's verb with every input property the binary's names and the row's lacks, and
+// the binary's description; and whether anything was added.
+func widenInput(row, binary catalogue.Verb) (catalogue.Verb, bool) {
+	want, _ := binary.Input["properties"].(map[string]any)
+	if len(want) == 0 {
+		return row, false
+	}
+	have, _ := row.Input["properties"].(map[string]any)
+	added := map[string]any{}
+	for name, p := range want {
+		if _, kept := have[name]; !kept {
+			added[name] = p
+		}
+	}
+	if len(added) == 0 {
+		return row, false
+	}
+	input := map[string]any{}
+	for k, v := range row.Input {
+		input[k] = v
+	}
+	if input["type"] == nil {
+		input["type"] = "object"
+	}
+	props := map[string]any{}
+	for k, v := range have {
+		props[k] = v
+	}
+	for k, v := range added {
+		props[k] = v
+	}
+	input["properties"] = props
+	row.Input = input
+	if binary.Description != "" {
+		row.Description = binary.Description
+	}
+	return row, true
+}
+
 // sameVerb is whether two definitions of a verb say the same, read as the row stores them.
 func sameVerb(a, b catalogue.Verb) bool {
 	ja, errA := json.Marshal(a)

internal/inventory/seats_test.go

@@ -156,3 +156,74 @@ func TestTheControllersVerbsInTheRowAreTheBinarys(t *testing.T) {
 		t.Fatal("a verb this binary adds was not added")
 	}
 }
+
+// **A seat's verb gains the arguments a newer binary names** (the service manager's journal window,
+// 2026-10-07): the console refuses an argument the row does not name, so a row seeded before them would
+// keep the holder's new arguments unreachable. Added, never removed — an argument only the row has stays,
+// and nothing becomes required — and a verb the binary adds optional is optional in the working set read back.
+func TestASeatsVerbGainsTheArgumentsTheBinaryNames(t *testing.T) {
+	inv := ForTest(t)
+	ctx := t.Context()
+	if _, err := inv.SeedSeats(ctx, catalogue.DefaultSeats()); err != nil {
+		t.Fatal(err)
+	}
+	old := `[{"name":"journal","description":"The last lines of one unit's journal.","input":{"type":"object",
+	          "properties":{"unit":{"type":"string"},"lines":{"type":"string"},"scope":{"type":"string"},"kept":{"type":"string"}},
+	          "required":["unit"]}}]`
+	if _, err := inv.store.Pool().Exec(ctx, `update seat set serves = $1 where name = $2`,
+		[]byte(old), catalogue.ServiceManagerSeat); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := inv.SeedSeats(ctx, catalogue.DefaultSeats()); err != nil {
+		t.Fatal(err)
+	}
+	seats, err := inv.Seats(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	verbs := map[string]catalogue.Verb{}
+	for _, s := range seats {
+		if s.Name == catalogue.ServiceManagerSeat {
+			for _, v := range s.Serves {
+				verbs[v.Name] = v
+			}
+		}
+	}
+	props, _ := verbs["journal"].Input["properties"].(map[string]any)
+	for _, arg := range []string{"since", "until", "match", "priority", "unit", "lines", "scope", "kept"} {
+		if _, has := props[arg]; !has {
+			t.Errorf("journal in the row does not take %s: %v", arg, props)
+		}
+	}
+	if req, _ := verbs["journal"].Input["required"].([]any); len(req) != 1 || req[0] != "unit" {
+		t.Errorf("what journal requires changed: %v", verbs["journal"].Input["required"])
+	}
+	if _, added := verbs["failed"]; !added {
+		t.Fatal("failed was not added to the row")
+	}
+	// The optional mark is not stored; the working set read from the rows takes it from the compiled seat,
+	// so today's holder, which does not serve failed, still holds the seat.
+	catalogue.UseSeats(seats)
+	defer catalogue.UseSeats(catalogue.DefaultSeats())
+	live, _ := catalogue.SeatNamed(catalogue.ServiceManagerSeat)
+	holder := catalogue.Manifest{Module: "systemd", Version: "1", Claims: []catalogue.Claim{{Name: catalogue.ServiceManagerSeat,
+		Scope: catalogue.ScopeNode, Serves: []string{"units", "status", "start", "stop", "restart", "enable", "disable", "journal"}}}}
+	if err := catalogue.CanHold(holder, live); err != nil {
+		t.Fatalf("the seat read from the store refuses today's holder: %v", err)
+	}
+	// Seeding again changes nothing more.
+	before := verbs["journal"]
+	if _, err := inv.SeedSeats(ctx, catalogue.DefaultSeats()); err != nil {
+		t.Fatal(err)
+	}
+	after, _ := inv.Seats(ctx)
+	for _, s := range after {
+		if s.Name == catalogue.ServiceManagerSeat {
+			for _, v := range s.Serves {
+				if v.Name == "journal" && !sameVerb(v, before) {
+					t.Fatalf("re-seeding changed journal again: %+v", v)
+				}
+			}
+		}
+	}
+}