Open every explanation with what the operator needs to do, and offer the answers

The operator could not tell from a notification whether to act, and was told to
have an agent do it. Each condition now says "Nothing for you to do." or
"Needs you:" with one thing they can do themselves, and carries the actions the
operator channel performs when chosen (hq ADR 0253).

cmd/mesh-controller/plain_words_test.go

@@ -14,29 +14,40 @@ import (
 // each keeps its summary for whoever looks closer, and now carries a headline, an explanation and a
 // resolved line the operator reads at a glance — no plan id, commit, key, verb or clock time in them.
 
-// plainExample checks one finding's words: plain, within their bounds, and saying what the operator needs.
-func plainExample(t *testing.T, o conditions.Observation, headline string, says ...string) {
+// plainExample checks one finding's words as the keeper will keep them: plain, within their bounds,
+// opened by the verdict, and saying what the operator needs; and its actions by label.
+func plainExample(t *testing.T, o conditions.Observation, headline, explanation string, actions ...string) {
 	t.Helper()
 	machines := append([]string{o.Machine}, o.Also...)
-	w := conditions.Words{Headline: o.Headline, Explanation: o.Explanation, Resolved: o.Resolved}
+	w := conditions.Words{Headline: o.Headline, Explanation: o.Explanation, Resolved: o.Resolved, Needs: o.Needs,
+		Actions: o.Actions}
 	if why, ok := conditions.PlainWords(w, machines...); !ok {
 		t.Errorf("%s: not plain: %s\n  %+v", o.Key(), why, w)
 	}
-	if o.Headline != headline {
-		t.Errorf("%s: headline %q, want %q", o.Key(), o.Headline, headline)
+	said := conditions.Verdict(o.Needs, o.Explanation)
+	if o.Headline != headline || said != explanation {
+		t.Errorf("%s: says\n  %q\n  %q\nwant\n  %q\n  %q", o.Key(), o.Headline, said, headline, explanation)
 	}
-	for _, s := range says {
-		if !strings.Contains(o.Explanation+" | "+o.Resolved, s) {
-			t.Errorf("%s: the words do not say %q:\n  %s | %s", o.Key(), s, o.Explanation, o.Resolved)
-		}
+	var labels []string
+	for _, a := range o.Actions {
+		labels = append(labels, a.Label)
 	}
-	t.Logf("\nBEFORE: %s\nAFTER:  %s\n        %s\nCLEARS: %s", o.Summary, o.Headline, o.Explanation, o.Resolved)
+	if strings.Join(labels, ",") != strings.Join(actions, ",") {
+		t.Errorf("%s: actions %v, want %v", o.Key(), labels, actions)
+	}
+	quiet := ""
+	if o.Needs == "" && o.Severity == conditions.Warning {
+		quiet = "   (needs nothing and is a warning: no popup; it stays in conditions and the history)"
+	}
+	t.Logf("\nBEFORE: %s\nAFTER:  %s%s\n        %s\n        actions %v\nCLEARS: %s", o.Summary, o.Headline, quiet,
+		said, labels, o.Resolved)
 }
 
 // **A delivery waiting**: the popup read "the walk of novox/mesh-catalog a6385479 has waited 56m0s for
 // mesh-delivery's word to start: `mesh-delivery.show` for the delivery that landed as a6385479 says why;
-// `plans go plan-1791454185265004861 --why …` starts it by hand".
-func TestADeliveryWaitingIsSaidByItsModulesAndWhatToDo(t *testing.T) {
+// `plans go plan-1791454185265004861 --why …` starts it by hand". Under four hours it needs nothing — no
+// popup; past them, the operator starts or stops it from the notification.
+func TestADeliveryWaitingNeedsNothingUntilItsBoundThenOffersStartAndStop(t *testing.T) {
 	now := time.Date(2026, 10, 8, 11, 36, 0, 0, time.UTC)
 	f := calm(now)
 	f.waits = []waitFacts{{id: "plan-1791454185265004861", repository: "novox/mesh-catalog", commit: "a6385479c0ffee",
@@ -45,36 +56,59 @@ func TestADeliveryWaitingIsSaidByItsModulesAndWhatToDo(t *testing.T) {
 	if len(got) != 1 {
 		t.Fatalf("%+v", got)
 	}
-	plainExample(t, got[0], "openrazer delivery waiting to start", "56 minutes", "mesh-delivery (the module that decides",
-		"Nothing to do yet", "openrazer delivery no longer waiting")
+	plainExample(t, got[0], "openrazer delivery waiting to start",
+		"Nothing for you to do. The change to openrazer is merged and built, and has waited 56 minutes for "+
+			"mesh-delivery (the module that decides when a delivery goes out) to let it start. It becomes a question "+
+			"for you if it still waits after 4 hours.")
 	if !strings.Contains(got[0].Summary, "plans go plan-1791454185265004861") {
 		t.Errorf("the summary lost the way on for whoever looks closer: %q", got[0].Summary)
 	}
 
-	// Past four hours it is urgent, and says it needs the operator.
+	// Past four hours it is urgent, and offers the controller's own answers.
 	f.waits[0].since = now.Add(-5 * time.Hour)
 	got = watchWaits(f)
-	plainExample(t, got[0], "openrazer delivery waiting to start", "It needs you")
+	plainExample(t, got[0], "openrazer delivery waiting to start",
+		"Needs you: start it, or stop it. The change to openrazer is merged and built, and mesh-delivery (the "+
+			"module that decides when a delivery goes out) has not let it start for 5 hours, so mesh-delivery may "+
+			"be stuck.", "Start", "Stop")
+	if a := got[0].Actions[0]; a.Verb != "mesh-controller.plans" || a.Arguments["go"] != "plan-1791454185265004861" {
+		t.Errorf("start: %+v", a)
+	}
+	if a := got[0].Actions[1]; a.Verb != "mesh-controller.plans" || a.Arguments["stop"] != "plan-1791454185265004861" {
+		t.Errorf("stop: %+v", a)
+	}
 
 	// Many modules are counted, not listed in the headline.
 	f.waits[0].modules = []string{"a", "b", "c", "d"}
 	got = watchWaits(f)
-	plainExample(t, got[0], "mesh-catalog delivery waiting to start", "4 modules of mesh-catalog")
+	if got[0].Headline != "mesh-catalog delivery waiting to start" || !strings.Contains(got[0].Explanation, "4 modules of mesh-catalog") {
+		t.Errorf("%+v", got[0])
+	}
 }
 
 // **A module unhealthy**: "openrazer on g14 is not healthy: its unit openrazer-daemon.service failed in the
-// account's own service manager (exit-code)".
-func TestAModuleUnhealthyNamesItsServiceInWords(t *testing.T) {
+// account's own service manager (exit-code)". The operator restarts it from the notification.
+func TestAModuleUnhealthyOffersARestartOfItsService(t *testing.T) {
 	o := moduleUnhealthyObservation("openrazer", "g14", []inventory.ResourceHealth{{Kind: link.KindUnit,
 		Resource: "openrazer-daemon", Target: "openrazer-daemon.service",
 		Reason: "failed in the account's own service manager (exit-code)", Since: time.Now()}})
-	plainExample(t, o, "openrazer not working on g14", "is not healthy: its service openrazer-daemon stopped with an error",
-		"openrazer works again on g14")
+	plainExample(t, o, "openrazer not working on g14",
+		"Needs you: restart it; if it fails again, the details say why. openrazer on g14 is not healthy: its "+
+			"service openrazer-daemon stopped with an error. It clears as soon as it runs again.", "Restart")
+	if a := o.Actions[0]; a.Verb != "node-service-manager.restart" || a.Machine != "g14" ||
+		a.Arguments["unit"] != "openrazer-daemon.service" || a.Arguments["scope"] != "user" {
+		t.Errorf("restart: %+v", a)
+	}
+	// An account waiting for a new login (ADR 0252) asks for the login, which no button can give.
+	o = moduleUnhealthyObservation("openrazer", "g14", []inventory.ResourceHealth{{Kind: "account",
+		Resource: "operator-in-group", Target: "jochen", Reason: "relogin needed: the account is in the group"}})
+	if o.Needs != "log out of every session on g14 and log in again." || len(o.Actions) != 0 {
+		t.Errorf("relogin: %q %+v", o.Needs, o.Actions)
+	}
 }
 
 // **Failed units on a machine**: "shanks's service manager is degraded: 3 failed unit(s) no module places —
-// mnt-recalbox.mount, storage-media.mount, greenclip.service (the account's own manager). Each is the
-// machine's own: mend or remove it there, or have a module place it".
+// mnt-recalbox.mount, storage-media.mount, greenclip.service (the account's own manager). …"
 func TestFailedUnitsOnAMachineAreNamedWithoutTheirSuffixes(t *testing.T) {
 	o, raise := machineUnitsObservation("shanks", &link.UnitsHealth{State: "degraded", Failed: []link.FailedUnit{
 		{Unit: "mnt-recalbox.mount", Result: "exit-code"}, {Unit: "storage-media.mount", Result: "exit-code"},
@@ -83,12 +117,14 @@ func TestFailedUnitsOnAMachineAreNamedWithoutTheirSuffixes(t *testing.T) {
 		t.Fatal("not raised")
 	}
 	plainExample(t, o, "3 failed services on shanks",
-		"mnt-recalbox (a mount), storage-media (a mount) and greenclip failed", "mend or remove them on shanks")
+		"Needs you: mend or remove them on shanks, or silence this if they do not matter. On shanks, "+
+			"mnt-recalbox (a mount), storage-media (a mount) and greenclip failed. No module manages them, so the "+
+			"mesh does not repair them.", "Silence for a week")
 }
 
-// **A healer wanted**: "\"push\" was repaired by hand 35 times in 14 days, the last by g14.node-tools,
-// through the mesh-controller seat: a healer is wanted for it".
-func TestAHealerWantedSaysNothingIsBroken(t *testing.T) {
+// **A healer wanted**: "\"push\" was repaired by hand 35 times in 14 days, the last by g14.node-tools, through
+// the mesh-controller seat: a healer is wanted for it". Nothing is broken: no popup.
+func TestAHealerWantedNeedsNothingFromTheOperator(t *testing.T) {
 	now := time.Date(2026, 10, 8, 12, 0, 0, 0, time.UTC)
 	f := calm(now)
 	for i := 0; i < 35; i++ {
@@ -100,15 +136,22 @@ func TestAHealerWantedSaysNothingIsBroken(t *testing.T) {
 	if len(got) != 1 {
 		t.Fatalf("%+v", got)
 	}
-	plainExample(t, got[0], "Push keeps being fixed by hand", "35 times in 14 days", "nothing is broken now")
+	plainExample(t, got[0], "Push keeps being fixed by hand",
+		"Nothing for you to do. A person repaired push by hand 35 times in 14 days, so an automatic repair is "+
+			"wanted for it. Nothing is broken now.")
 }
 
 // **A delivery held past its bound**, as mesh-delivery says it: "the delivery novox/hq@055550802096 has been
 // held for 36h2m6s, past its bound of 24h0m0s (it waits for the operator): healer H2 may none: …".
-func TestADeliveryHeldSaysItWaitsForTheOperator(t *testing.T) {
+func TestADeliveryHeldOffersReleaseAndStop(t *testing.T) {
 	got := stalledObservations([]stalledLine{{ID: "novox/hq@055550802096", State: "held", For: "36h2m6s",
 		Bound: "24h0m0s", H2: "none: the state is the operator's", Says: "it waits for the operator"}})
-	plainExample(t, got[0], "Delivery of hq held for 36 hours", "It waits for you: release it, or stop it.")
+	plainExample(t, got[0], "Delivery of hq held for 36 hours",
+		"Needs you: release it, or stop it. A delivery of hq has been held for 36 hours, past its limit.",
+		"Release", "Stop")
+	if a := got[0].Actions[0]; a.Verb != "mesh-delivery.release" || a.Arguments["id"] != "novox/hq@055550802096" {
+		t.Errorf("release: %+v", a)
+	}
 }
 
 // **Every kind the controller raises has plain words**, and its words are plain for a subject of every
@@ -134,6 +177,7 @@ func TestEveryWordingIsPlain(t *testing.T) {
 		for _, s := range subjects {
 			s.Kind = kind
 			w := fn(s)
+			w.Explanation = conditions.Verdict(w.Needs, w.Explanation)
 			if why, ok := conditions.PlainWords(w, s.Machine); !ok {
 				t.Errorf("%s about %s %s: %s\n  %+v", kind, s.Scope, s.ID, why, w)
 			}