modules/messenger/README.md

@@ -35,6 +35,15 @@ what is said is decided by the state now and by when a thing happened, never by
 - **Start grace.** Nothing is sent in the **first minute** after start but that one urgent message;
   what arrives meanwhile goes out, coalesced, when the minute ends.
 
+**A message reads in one glance** (novox/hq ADR 0253). Its title is the condition's headline — a few
+plain words such as "openrazer not working on g14" — prefixed "Urgent:", "Still open:" or "Now urgent:"
+where that applies; its body is the condition's explanation (what happened, what it means, whether the
+operator needs to act) and since when, in the operator's time zone. No key, id, commit, command or markup:
+those stay in the controller's `conditions` and in this module's history. A clearance is one line, the
+condition's resolved line and how long it was open: "Resolved: openrazer works again on g14, after 26 min".
+A condition from a controller older than plain words, or a module's notice without a headline, is said from
+its summary, with code spans taken out (`cmd/messenger/words.go`).
+
 | When | What |
 |---|---|
 | `condition-raised` | one message, deduplicated by the condition's key |
@@ -76,6 +85,9 @@ Nothing is sent until these are given; `messenger_status` says which is missing.
 2. **The chat id**, as a setting: `settings` for `messenger` with `{"telegram-chat-id": "<id>"}`.
 3. **The desktop machines**, as a setting: `{"desktop-machines": ["<the machine the operator sits at>", …]}`.
    Without it, warnings go to Telegram.
+4. **The time zone**, as a setting: `{"time-zone": "<an IANA zone name>"}`. Every time a message says is
+   said in it; not given, the zone of the machine this runs on. A name this machine does not know is
+   logged and that zone used instead.
 
 ## Tools
 
@@ -83,7 +95,7 @@ Nothing is sent until these are given; `messenger_status` says which is missing.
 |---|---|
 | `operator-channel.open` | what is open now, urgent first, with where it went, silenced, reminded, held, refused, unsent |
 | `operator-channel.history` | what was said lately, and the refusals |
-| `operator-channel.notify` | a message from a module using the seat: key, severity, summary; `clear` to end it |
+| `operator-channel.notify` | a message from a module using the seat: key, severity, summary, and best a plain `headline`, `explanation` and `resolved` line; `clear` to end it |
 | `messenger_status` | whether the operator can be reached and why not; `check` asks Telegram whether the token works |
 | `messenger_recent` | the recent sends, edits, digests and failures |
 | `messenger_test` | a test message now, to telegram, desktop or both |

modules/messenger/cmd/messenger/condition.go

@@ -17,6 +17,8 @@ package main
 //   - `severity` is `urgent` or `warning`. Anything else is not guessed: the event is unreadable.
 //   - `silenced` is absent, null, or an object {until, by, why}; `until` in the past is not silenced.
 //   - Times are RFC 3339.
+//   - `headline`, `explanation` and `resolved` are the plain words the operator reads (novox/hq ADR
+//     0253): a condition from a controller older than them has none, and is said from its summary.
 //   - `key` is `<scope>.<id>.<kind>`. When it is absent it is made from subject and kind; when
 //     neither gives one the event is unreadable.
 //   - A cleared event carries the condition as last held, and may add `cleared` (its time).
@@ -60,6 +62,9 @@ type Condition struct {
 	Machine      string
 	Severity     string
 	Summary      string
+	Headline     string
+	Explanation  string
+	Resolved     string
 	Source       string
 	Resolver     string
 	Raised       time.Time
@@ -164,6 +169,9 @@ func DecodeCondition(event string, body []byte) (Condition, error) {
 	c.Kind = str("kind")
 	c.Severity = str("severity")
 	c.Summary = str("summary")
+	c.Headline = str("headline")
+	c.Explanation = str("explanation")
+	c.Resolved = str("resolved")
 	c.Resolver = str("resolver")
 	c.Raised = when("raised")
 	c.LastObserved = when("last-observed", "last_observed", "lastObserved")

modules/messenger/cmd/messenger/history_test.go

@@ -205,7 +205,7 @@ func TestTodaysBacklogWithAnUrgentStillOpenIsOneMessage(t *testing.T) {
 	if len(tg.sends) != 1 || len(dt.sends) != 1 || len(tg.edits)+len(dt.edits) != 0 {
 		t.Fatalf("telegram %d desktop %d", len(tg.sends), len(dt.sends))
 	}
-	if !strings.HasPrefix(tg.sends[0].Title, "URGENT: ") || !strings.Contains(tg.sends[0].Text(), "merge.mesh-catalog.f2b51686.not-acted") {
+	if !strings.HasPrefix(tg.sends[0].Title, "Urgent: ") || !strings.Contains(tg.sends[0].Text(), "Merge not acted") {
 		t.Fatalf("message: %q", tg.sends[0].Text())
 	}
 	if got := len(h.Open()); got != 4 {
@@ -280,11 +280,11 @@ func TestABurstIsOneMessage(t *testing.T) {
 		t.Fatalf("sent inside the window: %d", len(tg.sends))
 	}
 	runFor(h, c, time.Minute)
-	if len(tg.sends) != 1 || !strings.HasPrefix(tg.sends[0].Title, "WARNING: 5 new warnings") {
+	if len(tg.sends) != 1 || !strings.HasPrefix(tg.sends[0].Title, "Mesh: 5 new problems") {
 		t.Fatalf("sends %d: %+v", len(tg.sends), tg.sends)
 	}
 	for i := 0; i < 5; i++ {
-		if !strings.Contains(tg.sends[0].Body, fmt.Sprintf("seat.s%d.silent", i)) {
+		if !strings.Contains(tg.sends[0].Body, fmt.Sprintf("seat s%d silent", i)) {
 			t.Fatalf("the digest does not name s%d: %q", i, tg.sends[0].Body)
 		}
 	}
@@ -293,7 +293,7 @@ func TestABurstIsOneMessage(t *testing.T) {
 		h.Condition(EventCleared, Condition{Key: fmt.Sprintf("seat.s%d.silent", i)})
 	}
 	runFor(h, c, time.Minute)
-	if len(tg.sends) != 2 || len(tg.edits) != 0 || !strings.HasPrefix(tg.sends[1].Title, "CLEARED: 3 cleared") {
+	if len(tg.sends) != 2 || len(tg.edits) != 0 || !strings.HasPrefix(tg.sends[1].Title, "Mesh: 3 resolved") {
 		t.Fatalf("sends %d edits %d: %q", len(tg.sends), len(tg.edits), tg.sends[len(tg.sends)-1].Title)
 	}
 	// A burst of urgent ones: the first at once, the rest as one.
@@ -303,7 +303,7 @@ func TestABurstIsOneMessage(t *testing.T) {
 		c.pass(time.Second)
 	}
 	runFor(h, c, time.Minute)
-	if len(tg.sends) != 4 || !strings.HasPrefix(tg.sends[3].Title, "URGENT: 5 new urgent") {
+	if len(tg.sends) != 4 || !strings.HasPrefix(tg.sends[3].Title, "Urgent: 5 urgent problems") {
 		t.Fatalf("sends %d: %q", len(tg.sends), tg.sends[len(tg.sends)-1].Title)
 	}
 }
@@ -322,7 +322,7 @@ func TestTheDesktopIsGentle(t *testing.T) {
 	// Urgent is not held to the desktop's rhythm.
 	h.Condition(EventRaised, cond("machine.ace.silent", Urgent, "the home server is silent"))
 	h.Flush()
-	if len(dt.sends) != 2 || !strings.HasPrefix(dt.sends[1].Title, "URGENT: ") || len(tg.sends) != 1 {
+	if len(dt.sends) != 2 || !strings.HasPrefix(dt.sends[1].Title, "Urgent: ") || len(tg.sends) != 1 {
 		t.Fatalf("urgent: desktop %d telegram %d", len(dt.sends), len(tg.sends))
 	}
 	// The urgent message took the held warnings along — one notification, read in one go. What
@@ -358,7 +358,7 @@ func TestNothingIsSentInTheFirstMinuteButTheUrgentOpenAsOne(t *testing.T) {
 	if len(res.Said) != 2 || len(res.State) != 1 || len(res.News) != 1 {
 		t.Fatalf("sync: %+v", res)
 	}
-	if len(tg.sends) != 1 || len(dt.sends) != 1 || !strings.HasPrefix(tg.sends[0].Title, "URGENT: 2 new urgent") {
+	if len(tg.sends) != 1 || len(dt.sends) != 1 || !strings.HasPrefix(tg.sends[0].Title, "Urgent: 2 urgent problems") {
 		t.Fatalf("telegram %d desktop %d: %+v", len(tg.sends), len(dt.sends), tg.sends)
 	}
 	c.pass(10 * time.Second)
@@ -377,8 +377,8 @@ func TestNothingIsSentInTheFirstMinuteButTheUrgentOpenAsOne(t *testing.T) {
 	if len(dt.sends) != 2 || len(tg.sends) != 2 {
 		t.Fatalf("after the grace: telegram %d desktop %d", len(tg.sends), len(dt.sends))
 	}
-	if d := dt.sends[1]; !strings.Contains(d.Body, "plan.42.stalled") || !strings.Contains(d.Body, "plan.43.stalled") ||
-		!strings.Contains(d.Body, "machine.shanks.silent") || strings.Contains(d.Body, "plan.41.stalled") {
+	if d := dt.sends[1]; !strings.Contains(d.Body, "plan 42 stalled") || !strings.Contains(d.Body, "plan 43 stalled") ||
+		!strings.Contains(d.Body, "machine shanks silent") || strings.Contains(d.Body, "plan 41 stalled") {
 		t.Fatalf("desktop digest: %q", d.Text())
 	}
 }

modules/messenger/cmd/messenger/holder.go

@@ -115,11 +115,16 @@ func editsSilently(ch Channel) bool {
 
 // Record is one open message, kept in the module's own state so a restart forgets nothing.
 type Record struct {
-	Key          string            `json:"key"`
-	Kind         string            `json:"kind"`
-	Subject      string            `json:"subject"`
-	Severity     string            `json:"severity"`
-	Summary      string            `json:"summary"`
+	Key      string `json:"key"`
+	Kind     string `json:"kind"`
+	Subject  string `json:"subject"`
+	Severity string `json:"severity"`
+	Summary  string `json:"summary"`
+	// Headline, Explanation and Resolved are the plain words the operator reads (novox/hq ADR 0253):
+	// the controller's, or a module's through notify; empty, the message is said from the summary.
+	Headline     string            `json:"headline,omitempty"`
+	Explanation  string            `json:"explanation,omitempty"`
+	Resolved     string            `json:"resolved,omitempty"`
 	Origin       string            `json:"origin"`
 	More         string            `json:"more"`
 	Raised       time.Time         `json:"raised"`
@@ -138,6 +143,18 @@ type Record struct {
 	Seen time.Time `json:"seen,omitempty"`
 }
 
+// recordOf is a condition as this holder keeps it.
+func recordOf(c Condition) Record {
+	return Record{Key: c.Key, Kind: c.Kind, Subject: c.SubjectWords(), Severity: c.Severity, Summary: c.Summary,
+		Headline: c.Headline, Explanation: c.Explanation, Resolved: c.Resolved, Origin: "condition",
+		More: "conditions show " + c.Key, Raised: c.Raised, SilencedTill: c.SilencedTill}
+}
+
+// takeWords keeps the plain words current, as the summary is: a condition's words follow what is seen.
+func (r *Record) takeWords(from Record) {
+	r.Headline, r.Explanation, r.Resolved = from.Headline, from.Explanation, from.Resolved
+}
+
 func (r *Record) silenced(now time.Time) bool {
 	return !r.SilencedTill.IsZero() && now.Before(r.SilencedTill)
 }
@@ -179,6 +196,8 @@ type Holder struct {
 	Logf     func(string, ...any)
 	// Emit states a fact as this module (refused); nil states nothing.
 	Emit func(event string, body any) error
+	// Zone is the operator's time zone, which every time in a message is said in; nil is this machine's.
+	Zone func() *time.Location
 
 	work sync.Mutex // one event, call or tick at a time
 	mu   sync.Mutex // what the status reads
@@ -289,10 +308,7 @@ func (h *Holder) Condition(event string, c Condition) {
 	h.lastHeard = now
 	synced := h.syncedAt
 	h.mu.Unlock()
-	rec := Record{
-		Key: c.Key, Kind: c.Kind, Subject: c.SubjectWords(), Severity: c.Severity, Summary: c.Summary,
-		Origin: "condition", More: "conditions show " + c.Key, Raised: c.Raised, SilencedTill: c.SilencedTill,
-	}
+	rec := recordOf(c)
 	when := c.When(event)
 	quiet := false
 	switch {
@@ -339,9 +355,9 @@ func (h *Holder) Unreadable(key string, err error) {
 	h.mu.Unlock()
 	h.Logf("[messenger] refused %s: %v (unreadable events since start: %d)", key, err, n)
 	h.sayOnce("messenger.unreadable-event", time.Hour, Message{
-		Title: "WARNING: a condition event could not be read",
-		Body: fmt.Sprintf("the operator-channel's holder could not read %d condition event(s) from the controller; "+
-			"what was wrong is in messenger_status. A condition may be open that was not said.", n),
+		Title: "A mesh message could not be read",
+		Body: fmt.Sprintf("The messenger could not read %d update(s) from the controller, so a problem may be open "+
+			"that was not said. An agent can find out why in the messenger's status.", n),
 	})
 }
 
@@ -354,6 +370,7 @@ func (h *Holder) raised(rec Record, quiet bool) {
 		// Said again while open: the same message. Its words are kept current; nothing is sent.
 		h.mu.Lock()
 		old.Summary, old.Subject, old.Kind, old.SilencedTill = rec.Summary, rec.Subject, rec.Kind, rec.SilencedTill
+		old.takeWords(rec)
 		if rec.Severity != "" {
 			old.Severity = rec.Severity
 		}
@@ -368,6 +385,7 @@ func (h *Holder) raised(rec Record, quiet bool) {
 		old.Cleared = time.Time{}
 		old.Count++
 		old.Summary, old.Severity, old.SilencedTill = rec.Summary, rec.Severity, rec.SilencedTill
+		old.takeWords(rec)
 		old.Seen = now
 		h.mu.Unlock()
 		if !quiet && !old.silenced(now) && old.told() {
@@ -411,6 +429,7 @@ func (h *Holder) changed(rec Record, quiet bool) {
 	h.mu.Lock()
 	escalated := old.Severity == Warning && rec.Severity == Urgent
 	old.Summary, old.Subject, old.SilencedTill = rec.Summary, rec.Subject, rec.SilencedTill
+	old.takeWords(rec)
 	if rec.Severity != "" {
 		old.Severity = rec.Severity
 	}
@@ -521,52 +540,6 @@ func remindAfter(severity string) time.Duration {
 	return RemindWarning
 }
 
-// compose is the message for a record. withhold names what the content rule refused, so the words
-// that carried it are not sent.
-func compose(r *Record, what string, now time.Time, withhold int) Message {
-	sev := strings.ToUpper(r.Severity)
-	if sev == "" {
-		sev = "WARNING"
-	}
-	summary := r.Summary
-	if withhold > 0 {
-		summary = "channel-refused: this message carried " + r.Refused + ", so its words are withheld"
-	}
-	var title string
-	switch what {
-	case "raised":
-		title = sev + ": " + summary
-	case "reminder":
-		title = "STILL OPEN after " + roughly(now.Sub(r.Raised)) + ": " + summary
-	case "escalated":
-		title = "NOW URGENT: " + summary
-	case "reopened":
-		title = sev + " (open again, " + fmt.Sprint(r.Count) + " times): " + summary
-	case "cleared":
-		title = "CLEARED after " + roughly(r.Cleared.Sub(r.Raised)) + ": " + summary
-	default:
-		title = sev + ": " + summary
-	}
-	lines := []string{}
-	if withhold < 3 && r.Subject != "" {
-		about := "about: " + r.Subject
-		if r.Kind != "" {
-			about += " (" + r.Kind + ")"
-		}
-		lines = append(lines, about)
-	}
-	lines = append(lines, "since: "+r.Raised.UTC().Format("2006-01-02 15:04")+" UTC")
-	if withhold < 2 {
-		lines = append(lines, "key: "+r.Key)
-		if r.More != "" {
-			lines = append(lines, "more: "+r.More)
-		}
-	} else {
-		lines = append(lines, "more: conditions (the open ones, through the mesh)")
-	}
-	return Message{Title: title, Body: strings.Join(lines, "\n"), Urgent: r.Severity == Urgent, Quiet: what == "cleared"}
-}
-
 // say composes a record's message under the content rule: refused, it is composed again with less of
 // it, until what remains may leave. The refusal is recorded and stated once per record.
 func (h *Holder) say(r *Record, what string) Message {
@@ -574,13 +547,13 @@ func (h *Holder) say(r *Record, what string) Message {
 	if r.Refused != "" {
 		// Refused before: its words stay withheld in every later message too.
 		for w := 1; w <= 3; w++ {
-			m := compose(r, what, now, w)
+			m := compose(r, what, now, h.zone(), w)
 			if _, ok := Check(m.Text()); ok {
 				return m
 			}
 		}
 	}
-	m := compose(r, what, now, 0)
+	m := compose(r, what, now, h.zone(), 0)
 	refusal, ok := Check(m.Text())
 	if ok {
 		return m
@@ -605,13 +578,12 @@ func (h *Holder) say(r *Record, what string) Message {
 		}
 	}
 	for w := 1; w <= 3; w++ {
-		m := compose(r, what, now, w)
+		m := compose(r, what, now, h.zone(), w)
 		if _, ok := Check(m.Text()); ok {
 			return m
 		}
 	}
-	return Message{Title: "WARNING: channel-refused: a message carried " + refusal.What + " and was withheld",
-		Body: "more: conditions (the open ones, through the mesh)", Urgent: r.Severity == Urgent}
+	return withheld(refusal.What, r.Severity == Urgent)
 }
 
 // deliver sends a record's message where its severity routes it.

modules/messenger/cmd/messenger/holder_test.go

@@ -72,7 +72,24 @@ func (c *clock) pass(d time.Duration) { c.t = c.t.Add(d) }
 func start() *clock                   { return &clock{t: time.Date(2026, 10, 6, 12, 0, 0, 0, time.UTC)} }
 func cond(key, sev, summary string) Condition {
 	parts := strings.Split(key, ".")
-	return Condition{Key: key, Scope: parts[0], ID: parts[1], Kind: parts[len(parts)-1], Severity: sev, Summary: summary}
+	return Condition{Key: key, Scope: parts[0], ID: parts[1], Kind: parts[len(parts)-1], Severity: sev, Summary: summary,
+		Headline: headlineOf(key), Explanation: "What it means: " + summary + "."}
+}
+
+// headlineOf is the headline a test condition carries: its key in words, so a message can be told by it
+// and never carries the key itself (novox/hq ADR 0253).
+func headlineOf(key string) string { return strings.ReplaceAll(key, ".", " ") }
+
+// keyless fails a message that carries a condition's key: the operator reads words, never keys.
+func keyless(t *testing.T, ms ...Message) {
+	t.Helper()
+	for _, m := range ms {
+		for _, w := range strings.Fields(m.Text()) {
+			if strings.Count(w, ".") >= 2 && !strings.HasSuffix(w, ".") {
+				t.Errorf("a message carries a key %q: %q", w, m.Text())
+			}
+		}
+	}
 }
 
 // settle lets a burst window pass and sends what is due.
@@ -104,7 +121,9 @@ func TestARaisedConditionIsSentOnceByItsKey(t *testing.T) {
 	if len(tg.sends) != 1 || len(dt.sends) != 1 {
 		t.Fatalf("urgent: telegram %d, desktop %d; want one each", len(tg.sends), len(dt.sends))
 	}
-	if !strings.Contains(tg.sends[0].Text(), "machine.ace.silent") || !strings.HasPrefix(tg.sends[0].Title, "URGENT: ") {
+	keyless(t, tg.sends...)
+	if tg.sends[0].Title != "Urgent: machine ace silent" || !strings.HasPrefix(tg.sends[0].Body, "What it means: ") ||
+		!strings.Contains(tg.sends[0].Body, "\nSince ") {
 		t.Fatalf("message: %q", tg.sends[0].Text())
 	}
 	if open := h.Open(); len(open) != 1 || open[0].Count != 1 {
@@ -151,7 +170,7 @@ func TestTheCapIsALastLineAndIsSaidOnce(t *testing.T) {
 	if len(tg.sends) != CapPerHour+1 {
 		t.Fatalf("sent %d, want the cap of %d and one saying so", len(tg.sends), CapPerHour)
 	}
-	if last := tg.sends[CapPerHour]; !strings.HasPrefix(last.Title, "HELD BACK: telegram is at its cap") {
+	if last := tg.sends[CapPerHour]; !strings.HasPrefix(last.Title, "Mesh messages paused for this hour") {
 		t.Fatalf("the cap was not said: %q", last.Title)
 	}
 	st := h.Status("listening")
@@ -172,11 +191,11 @@ func TestTheCapIsALastLineAndIsSaidOnce(t *testing.T) {
 		t.Fatalf("sends %d", len(tg.sends))
 	}
 	d := tg.sends[len(tg.sends)-1]
-	if !strings.HasPrefix(d.Title, "URGENT: 5 new urgent") {
+	if !strings.HasPrefix(d.Title, "Urgent: 5 urgent problems") {
 		t.Fatalf("digest: %q", d.Title)
 	}
 	for i := 20; i < 25; i++ {
-		if !strings.Contains(d.Body, fmt.Sprintf("machine.m%d.silent", i)) {
+		if !strings.Contains(d.Body, fmt.Sprintf("machine m%d silent", i)) {
 			t.Fatalf("the digest does not name m%d: %q", i, d.Body)
 		}
 	}
@@ -194,7 +213,7 @@ func TestAMessageCarryingAnAddressIsRefusedAndSaidWithItsWordsWithheld(t *testin
 	if strings.Contains(text, "192.168") || strings.Contains(text, "token=") {
 		t.Fatalf("the address left: %q", text)
 	}
-	if !strings.Contains(text, "channel-refused") || !strings.Contains(text, "provider.keycloak.ace.failing") {
+	if !strings.Contains(text, "withheld, because it carried an IPv4 address") || !strings.Contains(text, "provider keycloak ace failing") {
 		t.Fatalf("not said as refused, by key: %q", text)
 	}
 	hist := h.History(10)["refusals"].([]RefusalNote)
@@ -242,7 +261,7 @@ func TestStillOpenPastItsBoundItIsSaidOnceMore(t *testing.T) {
 	}
 	c.pass(2 * time.Minute)
 	h.Tick()
-	if len(tg.sends) != 3 || !strings.HasPrefix(tg.sends[2].Title, "STILL OPEN after 61 min") {
+	if len(tg.sends) != 3 || (tg.sends[2].Title != "Still open: bus controller slow-consumer" || !strings.Contains(tg.sends[2].Body, "for 61 min")) {
 		t.Fatalf("urgent reminder: %d %q", len(tg.sends), tg.sends[len(tg.sends)-1].Title)
 	}
 	c.pass(3 * time.Hour)
@@ -253,7 +272,7 @@ func TestStillOpenPastItsBoundItIsSaidOnceMore(t *testing.T) {
 	c.pass(9 * time.Hour) // the warning is now 13 h old
 	h.Tick()
 	settle(h, c)
-	if len(tg.sends) != 4 || !strings.Contains(tg.sends[3].Text(), "plan.41.stalled") {
+	if len(tg.sends) != 4 || tg.sends[3].Title != "Still open: plan 41 stalled" {
 		t.Fatalf("warning reminder: %d", len(tg.sends))
 	}
 }
@@ -268,7 +287,7 @@ func TestClearedEditsTheFirstMessageAndReopenedWithinTenMinutesIsNotNew(t *testi
 	if len(tg.sends) != 1 || len(tg.edits) != 1 || len(dt.edits) != 1 {
 		t.Fatalf("telegram sends %d edits %d, desktop edits %d", len(tg.sends), len(tg.edits), len(dt.edits))
 	}
-	if m := tg.edits["1"]; !strings.HasPrefix(m.Title, "CLEARED after 14 min") {
+	if m := tg.edits["1"]; m.Title != "Resolved: machine ace silent, after 14 min" || m.Body != "" {
 		t.Fatalf("edit: %q", m.Title)
 	}
 	if len(h.Open()) != 0 {
@@ -277,7 +296,7 @@ func TestClearedEditsTheFirstMessageAndReopenedWithinTenMinutesIsNotNew(t *testi
 	c.pass(5 * time.Minute)
 	k.At = c.now() // a reopening keeps its first raising time; the event says when it happened
 	h.Condition(EventRaised, k)
-	if len(tg.sends) != 1 || !strings.Contains(tg.edits["1"].Title, "open again, 2 times") {
+	if len(tg.sends) != 1 || !strings.Contains(tg.edits["1"].Title, "(again, 2nd time)") {
 		t.Fatalf("reopened as new: sends %d, edit %q", len(tg.sends), tg.edits["1"].Title)
 	}
 	h.Condition(EventCleared, Condition{Key: k.Key})
@@ -326,7 +345,7 @@ func TestEscalationIsSaidOnce(t *testing.T) {
 	h.Condition(EventChanged, k)
 	h.Condition(EventChanged, k)
 	settle(h, c)
-	if len(dt.sends) != 2 || len(tg.sends) != 1 || !strings.HasPrefix(tg.sends[0].Title, "NOW URGENT") {
+	if len(dt.sends) != 2 || len(tg.sends) != 1 || !strings.HasPrefix(tg.sends[0].Title, "Now urgent: ") {
 		t.Fatalf("desktop %d telegram %d", len(dt.sends), len(tg.sends))
 	}
 	// Escalated while the warning still waited its window: one message, the urgent one.
@@ -335,7 +354,7 @@ func TestEscalationIsSaidOnce(t *testing.T) {
 	k2.Severity = Urgent
 	h.Condition(EventChanged, k2)
 	settle(h, c)
-	if len(dt.sends) != 3 || !strings.HasPrefix(dt.sends[2].Title, "NOW URGENT") {
+	if len(dt.sends) != 3 || !strings.HasPrefix(dt.sends[2].Title, "Now urgent: ") {
 		t.Fatalf("desktop %d: %q", len(dt.sends), dt.sends[len(dt.sends)-1].Title)
 	}
 }

modules/messenger/cmd/messenger/main.go

@@ -25,6 +25,22 @@ func logf(format string, a ...any) { fmt.Fprintf(os.Stderr, format+"\n", a...) }
 type Settings struct {
 	TelegramChatID  string   `json:"telegram-chat-id"`
 	DesktopMachines []string `json:"desktop-machines"`
+	// TimeZone is the operator's, an IANA name such as Europe/Brussels: every time a message says is said
+	// in it. Empty is this machine's own zone.
+	TimeZone string `json:"time-zone"`
+}
+
+// zoneOf is the location a time-zone setting names, or this machine's own when it names none or one
+// that does not exist (said, never guessed silently).
+func zoneOf(name string) (*time.Location, error) {
+	if name == "" {
+		return time.Local, nil
+	}
+	loc, err := time.LoadLocation(name)
+	if err != nil {
+		return time.Local, fmt.Errorf("the time-zone %q is not one this machine knows; times are said in its own zone", name)
+	}
+	return loc, nil
 }
 
 func readSettings(path string) (Settings, error) {
@@ -47,6 +63,9 @@ func readSettings(path string) (Settings, error) {
 	case float64:
 		s.TelegramChatID = fmt.Sprintf("%.0f", v)
 	}
+	if tz, ok := loose["time-zone"].(string); ok {
+		s.TimeZone = strings.TrimSpace(tz)
+	}
 	if list, ok := loose["desktop-machines"].([]any); ok {
 		for _, m := range list {
 			if name, ok := m.(string); ok && strings.TrimSpace(name) != "" {
@@ -128,7 +147,7 @@ func (l *listening) get() string  { l.mu.Lock(); defer l.mu.Unlock(); return l.n
 func main() {
 	settingsFile := os.Getenv("MESH_MESSENGER_SETTINGS")
 	var said sync.Mutex
-	lastSaid := ""
+	lastSaid, zoneSaid := "", ""
 	settings := func() Settings {
 		s, err := readSettings(settingsFile)
 		said.Lock()
@@ -153,7 +172,20 @@ func main() {
 		},
 		Store: stateStore{},
 		Logf:  logf,
-		Emit:  func(event string, body any) error { return stdio.Emit(event, body) },
+		Zone: func() *time.Location {
+			loc, err := zoneOf(settings().TimeZone)
+			said.Lock()
+			defer said.Unlock()
+			if err != nil && err.Error() != zoneSaid {
+				logf("[messenger] %v", err)
+			}
+			zoneSaid = ""
+			if err != nil {
+				zoneSaid = err.Error()
+			}
+			return loc
+		},
+		Emit: func(event string, body any) error { return stdio.Emit(event, body) },
 	}
 	h.init()
 	l := &listening{now: "not yet: starting"}
@@ -286,7 +318,8 @@ func tools(h *Holder, l *listening) []stdio.Tool {
 			Run:   func(a map[string]any) (any, error) { return h.History(limitArg(a, 50)), nil }},
 		{Name: "operator-channel.notify",
 			Description: "Tell the operator something, as a module that uses the seat: a key (the same key is the same " +
-				"message), urgent or warning, one line in the mesh's words, and what it is about. clear says it is over. " +
+				"message), urgent or warning, one line in the mesh's words, and what it is about; and best, in plain " +
+				"words, a headline, an explanation and the line said when it is over. clear says it is over. " +
 				"Roles and words only: an address, a path or a secret is refused. Deduplicated, capped and routed " +
 				"like the controller's conditions.",
 			Input: map[string]any{
@@ -294,11 +327,16 @@ func tools(h *Holder, l *listening) []stdio.Tool {
 				"severity": map[string]any{"type": "string", "enum": []string{Urgent, Warning}},
 				"summary":  str("one line in the mesh's words"),
 				"subject":  str("what it is about: a machine's role, a module, a plan"),
+				"headline": str("a few plain words the operator reads as the title, e.g. backup failed on ace: no ids, keys or commands"),
+				"explanation": str("one or two plain sentences: what happened, what it means for the operator, and whether " +
+					"they need to act"),
+				"resolved": str("the one short line said when it is over, e.g. backups run again on ace"),
 				"clear":    map[string]any{"type": "boolean", "description": "it is over: the message is edited to say so"},
 			},
 			Run: func(a map[string]any) (any, error) {
 				clear, _ := a["clear"].(bool)
-				return h.Notify(strArg(a, "key"), strArg(a, "severity"), strArg(a, "summary"), strArg(a, "subject"), clear)
+				return h.Notify(strArg(a, "key"), strArg(a, "severity"), strArg(a, "summary"), strArg(a, "subject"), clear,
+					strArg(a, "headline"), strArg(a, "explanation"), strArg(a, "resolved"))
 			}},
 		{Name: "messenger_status",
 			Description: "Whether the operator can be reached, and why not: each channel — can it send, what it lacks " +

modules/messenger/cmd/messenger/outbox.go

@@ -265,9 +265,9 @@ func (h *Holder) flushChannel(ch Channel, now time.Time, force bool) {
 		said := h.capSaid[name]
 		h.mu.Unlock()
 		if said.IsZero() || now.Sub(said) >= time.Hour {
-			m := Message{Title: fmt.Sprintf("HELD BACK: %s is at its cap of %d messages an hour", name, CapPerHour),
-				Body: fmt.Sprintf("%d message(s) are held and go out as one when the hour allows.\n"+
-					"more: conditions (through the mesh)", len(entries)), Urgent: true}
+			m := Message{Title: "Mesh messages paused for this hour",
+				Body: fmt.Sprintf("The mesh sent %d messages here this hour, its limit. %d more are held and come as "+
+					"one message when the hour allows.", CapPerHour, len(entries)), Urgent: true}
 			_, err := ch.Send(m)
 			h.noteChannel(name, err)
 			if err == nil {
@@ -414,32 +414,24 @@ func digest(items []item, msgs []Message) Message {
 			parts = append(parts, fmt.Sprintf("%d %s", n, many))
 		}
 	}
-	add(newU, "new urgent", "new urgent")
-	add(newW, "new warning", "new warnings")
+	add(newU, "urgent problem", "urgent problems")
+	add(newW, "new problem", "new problems")
 	add(still, "still open", "still open")
-	add(cleared, "cleared", "cleared")
+	add(cleared, "resolved", "resolved")
 	add(notices, "notice", "notices")
-	prefix := "WARNING"
+	prefix := "Mesh"
 	if urgent {
-		prefix = "URGENT"
-	} else if quiet {
-		prefix = "CLEARED"
+		prefix = "Urgent"
 	}
+	// Each line is one message's title: a headline, or a resolved line — plain words, no key (ADR 0253).
 	var lines []string
 	for i, m := range msgs {
 		if i == DigestLines {
 			lines = append(lines, fmt.Sprintf("and %d more", len(msgs)-DigestLines))
 			break
 		}
-		line := m.Title
-		if key := items[i].Key; items[i].Msg == nil {
-			if _, ok := Check(key); ok {
-				line += " [" + key + "]"
-			}
-		}
-		lines = append(lines, "- "+line)
+		lines = append(lines, "- "+m.Title)
 	}
-	lines = append(lines, "more: conditions (through the mesh)")
 	return Message{Title: prefix + ": " + strings.Join(parts, ", "), Body: strings.Join(lines, "\n"), Urgent: urgent, Quiet: quiet}
 }
 

modules/messenger/cmd/messenger/status.go

@@ -36,6 +36,7 @@ type Status struct {
 	Stale        int             `json:"events_taken_as_state"`      // older than the freshness bound: recorded, never said
 	Grace        bool            `json:"in_start_grace,omitempty"`
 	StateProblem string          `json:"state_problem,omitempty"`
+	TimeZone     string          `json:"time_zone"` // the zone every time in a message is said in
 	Rules        []string        `json:"rules"`
 }
 
@@ -95,7 +96,10 @@ func (h *Holder) Status(listening string) Status {
 	h.mu.Unlock()
 	sort.Strings(st.Unsent)
 	st.Listening = listening
+	st.TimeZone = h.zone().String()
 	st.Rules = []string{
+		"a message reads in one glance: the condition's headline as its title, its explanation, and since when in the operator's time zone; no key, id, commit or command — those stay in the controller's conditions and in this holder's history (novox/hq ADR 0253)",
+		"a clearance is one line: the condition's resolved line and how long it was open",
 		"history is never news: what is open is read from the controller on start, every 10 min and when an old event arrives; an event older than that reading is not acted on, one older than 10 min by its own time is state, never a message",
 		"a clearing of something never said says nothing; an urgent condition open and never said is said, all of them in one message",
 		"nothing is sent in the first minute after start but that one message",
@@ -213,7 +217,7 @@ func (h *Holder) Test(channel, text string) map[string]string {
 		out["refused"] = "it carried " + refusal.String() + "; nothing was sent"
 		return out
 	}
-	m := Message{Title: "TEST: " + text, Body: "nothing is wrong; this was asked for"}
+	m := Message{Title: "Test message: " + text, Body: "Nothing is wrong; this was asked for."}
 	for _, ch := range h.channels() {
 		if channel != "" && channel != "both" && channel != ch.Name() {
 			continue
@@ -240,7 +244,7 @@ func (h *Holder) Test(channel, text string) map[string]string {
 // Notify takes a message from a module that uses the seat (research 028 Q5, modules as sources):
 // the same shape, rule, cap and deduplication as a condition. Its key is put under `notify.` so it
 // can never be taken for one of the controller's conditions.
-func (h *Holder) Notify(key, severity, summary, subject string, clear bool) (map[string]any, error) {
+func (h *Holder) Notify(key, severity, summary, subject string, clear bool, plain ...string) (map[string]any, error) {
 	if key == "" {
 		return nil, errorf("key is required: the same key is the same message")
 	}
@@ -266,8 +270,20 @@ func (h *Holder) Notify(key, severity, summary, subject string, clear bool) (map
 	if summary == "" {
 		return nil, errorf("summary is required: one line in the mesh's words")
 	}
-	h.raised(Record{Key: key, Kind: "notice", Subject: subject, Severity: severity, Summary: summary,
-		Origin: "notify", More: "operator-channel.open"}, false)
+	rec := Record{Key: key, Kind: "notice", Subject: subject, Severity: severity, Summary: summary,
+		Origin: "notify", More: "operator-channel.open"}
+	// The plain words a module may give (novox/hq ADR 0253): a headline, an explanation, a resolved line.
+	for i, w := range plain {
+		switch i {
+		case 0:
+			rec.Headline = w
+		case 1:
+			rec.Explanation = w
+		case 2:
+			rec.Resolved = w
+		}
+	}
+	h.raised(rec, false)
 	h.mu.Lock()
 	r := h.open[key]
 	var sent []string

modules/messenger/cmd/messenger/sync.go

@@ -52,10 +52,7 @@ func (h *Holder) Sync(open []Condition, asked time.Time) SyncResult {
 	var urgent []*Record
 	var fresh []*Record
 	for _, c := range open {
-		rec := Record{
-			Key: c.Key, Kind: c.Kind, Subject: c.SubjectWords(), Severity: c.Severity, Summary: c.Summary,
-			Origin: "condition", More: "conditions show " + c.Key, Raised: c.Raised, SilencedTill: c.SilencedTill,
-		}
+		rec := recordOf(c)
 		h.mu.Lock()
 		old := h.open[c.Key]
 		var r *Record
@@ -72,6 +69,7 @@ func (h *Holder) Sync(open []Condition, asked time.Time) SyncResult {
 				old.Count++
 			}
 			old.Summary, old.Subject, old.Kind, old.SilencedTill = rec.Summary, rec.Subject, rec.Kind, rec.SilencedTill
+			old.takeWords(rec)
 			if rec.Severity != "" {
 				old.Severity = rec.Severity
 			}

modules/messenger/cmd/messenger/words.go

@@ -0,0 +1,211 @@
+package main
+
+// What a message says (novox/hq ADR 0253): **it reads in one glance.** A title in plain words, one or two
+// plain sentences on what happened, what it means and whether to act, and when it began in the
+// operator's own time. No key, id, commit, verb or markup: the condition's key and summary stay in the
+// controller (`conditions`) and in this holder's history, for whoever looks closer.
+//
+//   - The words are the condition's own: its headline, explanation and resolved line, made by the
+//     controller where the condition is made, so every channel says the same thing. A condition from a
+//     controller older than them, or a module's notice without a headline, is said from its summary,
+//     with what the operator cannot read taken out (plainSummary).
+//   - A clearance is one short line: "Resolved: openrazer works again on g14, after 26 min".
+//   - A reminder, an escalation and a reopening say so in the title, before the same headline.
+//   - Times are the operator's (the setting time-zone; this machine's zone when not given), and said as a
+//     clock time today, a weekday this week, a date before that.
+
+import (
+	"fmt"
+	"regexp"
+	"strings"
+	"time"
+)
+
+func (h *Holder) zone() *time.Location {
+	if h.Zone != nil {
+		if loc := h.Zone(); loc != nil {
+			return loc
+		}
+	}
+	return time.Local
+}
+
+// compose is the message for a record. withhold > 0 when the content rule refused what it said: 1 says
+// the headline alone, more says only that something was withheld.
+func compose(r *Record, what string, now time.Time, loc *time.Location, withhold int) Message {
+	headline, explanation := wordsOf(r)
+	urgent := r.Severity == Urgent
+	if withhold >= 2 {
+		return withheld(r.Refused, urgent)
+	}
+	if withhold == 1 {
+		explanation = "Part of this message was withheld, because it carried " + r.Refused + "."
+	}
+	var title string
+	switch what {
+	case "cleared":
+		return Message{Title: resolvedLine(r) + ", after " + roughly(r.Cleared.Sub(r.Raised)), Quiet: true}
+	case "reminder":
+		title = "Still open: " + headline
+	case "escalated":
+		title = "Now urgent: " + headline
+	case "reopened":
+		title = headline + " (again" + times(r.Count) + ")"
+		if urgent {
+			title = "Urgent: " + title
+		}
+	default:
+		title = headline
+		if urgent {
+			title = "Urgent: " + headline
+		}
+	}
+	since := "Since " + when(r.Raised, now, loc)
+	if what == "reminder" {
+		since = fmt.Sprintf("Open since %s, for %s.", when(r.Raised, now, loc), roughly(now.Sub(r.Raised)))
+	} else {
+		since += "."
+	}
+	body := since
+	if explanation != "" {
+		body = explanation + "\n" + since
+	}
+	return Message{Title: title, Body: body, Urgent: urgent}
+}
+
+// withheld is what is sent in place of a message the content rule refused.
+func withheld(carried string, urgent bool) Message {
+	return Message{Title: "A mesh message was withheld",
+		Body: "It carried " + carried + ", which may not leave the mesh. An agent can read it among the mesh's " +
+			"open conditions.", Urgent: urgent}
+}
+
+// times is " 2nd time" for a count of 2, "" for 1.
+func times(n int) string {
+	if n < 2 {
+		return ""
+	}
+	suffix := "th"
+	switch {
+	case n%100 >= 11 && n%100 <= 13:
+	case n%10 == 1:
+		suffix = "st"
+	case n%10 == 2:
+		suffix = "nd"
+	case n%10 == 3:
+		suffix = "rd"
+	}
+	return fmt.Sprintf(", %d%s time", n, suffix)
+}
+
+// wordsOf is a record's headline and explanation: its own, or made from its summary.
+func wordsOf(r *Record) (string, string) {
+	if r.Headline != "" {
+		return r.Headline, r.Explanation
+	}
+	summary := plainSummary(r.Summary)
+	if r.Origin == "notify" && len(summary) <= 80 {
+		return capital(summary), ""
+	}
+	return fallbackHeadline(r), capital(summary)
+}
+
+// resolvedLine is the line a clearance says: the condition's own, or made from its headline.
+func resolvedLine(r *Record) string {
+	line := r.Resolved
+	if line == "" {
+		headline, _ := wordsOf(r)
+		line = "Resolved: " + lowerFirst(headline)
+	}
+	if !strings.HasPrefix(line, "Resolved") {
+		line = "Resolved: " + lowerFirst(line)
+	}
+	return line
+}
+
+// fallbackHeadline is a title for something with no headline: what it is about and its kind, in words.
+func fallbackHeadline(r *Record) string {
+	what := strings.ReplaceAll(r.Kind, "-", " ")
+	if what == "" || what == "notice" {
+		what = "a notice"
+	}
+	about := ""
+	if r.Origin == "notify" {
+		about = r.Subject
+	} else if machine := machineOf(r.Subject); machine != "" {
+		about = machine
+	} else {
+		// A seat, a provider or a module is named by a name; a plan, a delivery or a call by an id, never said.
+		for _, scope := range []string{"seat ", "provider ", "module "} {
+			if name, ok := strings.CutPrefix(r.Subject, scope); ok {
+				about = name
+			}
+		}
+	}
+	if about == "" {
+		return capital(what)
+	}
+	return capital(what) + " on " + about
+}
+
+// machineOf is the machine a record's subject words name: "machine ace" or "x on ace".
+func machineOf(subject string) string {
+	if _, on, ok := strings.Cut(subject, " on "); ok {
+		return on
+	}
+	if m, ok := strings.CutPrefix(subject, "machine "); ok {
+		return m
+	}
+	return ""
+}
+
+var (
+	codeSpan = regexp.MustCompile("`([^`]*)`")
+	noise    = regexp.MustCompile(`\s+`)
+)
+
+// plainSummary is a summary with what the operator cannot read taken out: markup and the verbs in code
+// spans. Used only where the condition says no plain words of its own.
+func plainSummary(s string) string {
+	s = codeSpan.ReplaceAllStringFunc(s, func(m string) string {
+		inner := strings.Trim(m, "`")
+		if strings.ContainsAny(inner, ". ") {
+			return "a command"
+		}
+		return inner
+	})
+	s = strings.NewReplacer("**", "", "`", "").Replace(s)
+	return strings.TrimSpace(noise.ReplaceAllString(s, " "))
+}
+
+// when is a moment as the operator reads it, in their zone: "10:40" today, "Tue 10:40" this week,
+// "1 Oct 10:40" before.
+func when(t, now time.Time, loc *time.Location) string {
+	if t.IsZero() {
+		return "now"
+	}
+	lt, ln := t.In(loc), now.In(loc)
+	y1, m1, d1 := lt.Date()
+	y2, m2, d2 := ln.Date()
+	switch {
+	case y1 == y2 && m1 == m2 && d1 == d2:
+		return lt.Format("15:04")
+	case ln.Sub(lt) < 6*24*time.Hour:
+		return lt.Format("Mon 15:04")
+	}
+	return lt.Format("2 Jan 15:04")
+}
+
+func capital(s string) string {
+	if s == "" {
+		return s
+	}
+	return strings.ToUpper(s[:1]) + s[1:]
+}
+
+func lowerFirst(s string) string {
+	if s == "" || (len(s) > 1 && strings.ToUpper(s[:2]) == s[:2]) {
+		return s
+	}
+	return strings.ToLower(s[:1]) + s[1:]
+}

modules/messenger/cmd/messenger/words_test.go

@@ -0,0 +1,191 @@
+package main
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+	"time"
+	_ "time/tzdata"
+)
+
+// The notifications the operator could not read on 2026-10-08, said again from the events a controller
+// with plain words sends (novox/hq ADR 0253). BEFORE is the popup as it appeared; AFTER is what the desktop
+// shows now: a title in plain words, an explanation, since when in the operator's time — no key, id,
+// commit, verb or markup — and a clearance in one line.
+
+type example struct {
+	name, before                    string
+	key, kind, severity, summary    string
+	subject                         map[string]string
+	headline, explanation, resolved string
+	title, body                     string // what the desktop shows
+	cleared                         string // the clearance's one line
+	openFor                         time.Duration
+}
+
+var examples = []example{{
+	name: "a delivery waiting",
+	before: "CLEARED after 26 min: 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\nabout: plan plan-1791454185265004861 (waiting)\n" +
+		"since: 2026-10-08 10:40 UTC\nkey: plan.plan-1791454185265004861.waiting\nmore: conditions show " +
+		"plan.plan-1791454... 65004861.waiting",
+	key: "plan.plan-1791454185265004861.waiting", kind: "waiting", severity: Warning,
+	subject: map[string]string{"scope": "plan", "id": "plan-1791454185265004861"},
+	summary: "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",
+	headline: "openrazer delivery waiting to start",
+	explanation: "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. Nothing to do yet; it becomes urgent after " +
+		"4 hours. To start it now, have an agent start it by hand.",
+	resolved: "openrazer delivery no longer waiting",
+	title:    "openrazer delivery waiting to start",
+	body: "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. Nothing to do yet; it becomes urgent after 4 hours. " +
+		"To start it now, have an agent start it by hand.\nSince 12:40.",
+	cleared: "Resolved: openrazer delivery no longer waiting, after 26 min", openFor: 26 * time.Minute,
+}, {
+	name: "a module unhealthy",
+	before: "WARNING: openrazer on g14 is not healthy: its unit openrazer-daemon.service failed in the account's own " +
+		"service manager (exit-code)\nabout: module openrazer.g14 on g14 (module-unhealthy)\nsince: 2026-10-08 " +
+		"10:40 UTC\nkey: module.openrazer.g14.unhealthy\nmore: conditions show module.openrazer.g14.unhealthy",
+	key: "module.openrazer.g14.unhealthy", kind: "module-unhealthy", severity: Warning,
+	subject: map[string]string{"scope": "module", "id": "openrazer.g14", "machine": "g14"},
+	summary: "openrazer on g14 is not healthy: its unit openrazer-daemon.service failed in the account's own " +
+		"service manager (exit-code)",
+	headline: "openrazer not working on g14",
+	explanation: "openrazer on g14 is not healthy: its service openrazer-daemon stopped with an error. It clears as " +
+		"soon as it runs again; if it stays, it needs a look at why it fails.",
+	resolved: "openrazer works again on g14",
+	title:    "openrazer not working on g14",
+	body: "openrazer on g14 is not healthy: its service openrazer-daemon stopped with an error. It clears as soon " +
+		"as it runs again; if it stays, it needs a look at why it fails.\nSince 12:40.",
+	cleared: "Resolved: openrazer works again on g14, after 2.0 h", openFor: 2 * time.Hour,
+}, {
+	name: "failed units on a machine",
+	before: "WARNING: 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\nabout: machine shanks on shanks (machine-units)\nsince: " +
+		"2026-10-08 10:40 UTC\nkey: machine.shanks.units\nmore: conditions show machine.shanks.units",
+	key: "machine.shanks.units", kind: "machine-units", severity: Warning,
+	subject: map[string]string{"scope": "machine", "id": "shanks", "machine": "shanks"},
+	summary: "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",
+	headline: "3 failed services on shanks",
+	explanation: "On shanks, mnt-recalbox (a mount), storage-media (a mount) and greenclip failed. No module " +
+		"manages them, so the mesh does not repair them: mend or remove them on shanks.",
+	resolved: "No failed services on shanks any more",
+	title:    "3 failed services on shanks",
+	body: "On shanks, mnt-recalbox (a mount), storage-media (a mount) and greenclip failed. No module manages them, " +
+		"so the mesh does not repair them: mend or remove them on shanks.\nSince 12:40.",
+	cleared: "Resolved: no failed services on shanks any more, after 45 min", openFor: 45 * time.Minute,
+}, {
+	name: "a healer wanted",
+	before: "WARNING: \"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\nabout: mesh hand-acts.push (healer-wanted)\nsince: " +
+		"2026-10-08 10:40 UTC\nkey: mesh.hand-acts.push.healer-wanted\nmore: conditions show " +
+		"mesh.hand-acts.push.healer-wanted",
+	key: "mesh.hand-acts.push.healer-wanted", kind: "healer-wanted", severity: Warning,
+	subject: map[string]string{"scope": "mesh", "id": "hand-acts.push"},
+	summary: "\"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",
+	headline: "Push keeps being fixed by hand",
+	explanation: "A person repaired push by hand 35 times in 14 days. A healer (an automatic repair) is wanted for " +
+		"it; nothing is broken now.",
+	resolved: "Resolved: no more hand repairs of push",
+	title:    "Push keeps being fixed by hand",
+	body: "A person repaired push by hand 35 times in 14 days. A healer (an automatic repair) is wanted for it; " +
+		"nothing is broken now.\nSince 12:40.",
+	cleared: "Resolved: no more hand repairs of push, after 3 days", openFor: 3 * 24 * time.Hour,
+}}
+
+// event is the body a controller with plain words sends for a condition.
+func (e example) event(at time.Time, cleared bool) []byte {
+	body := map[string]any{"key": e.key, "kind": e.kind, "subject": e.subject, "severity": e.severity,
+		"summary": e.summary, "headline": e.headline, "explanation": e.explanation, "resolved": e.resolved,
+		"raised": "2026-10-08T10:40:00Z", "at": at.Format(time.RFC3339), "silenced": nil}
+	if cleared {
+		body["cleared"] = at.Format(time.RFC3339)
+	}
+	raw, _ := json.Marshal(body)
+	return raw
+}
+
+func TestRealNotificationsReadInOneGlance(t *testing.T) {
+	brussels, err := time.LoadLocation("Europe/Brussels")
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, e := range examples {
+		t.Run(e.name, func(t *testing.T) {
+			h, _, dt, c, _ := newHolder(t)
+			h.Telegram = nil
+			h.Zone = func() *time.Location { return brussels }
+			c.t = time.Date(2026, 10, 8, 10, 40, 0, 0, time.UTC)
+			raised, err := DecodeCondition(EventRaised, e.event(c.now(), false))
+			if err != nil {
+				t.Fatal(err)
+			}
+			h.Condition(EventRaised, raised)
+			settle(h, c)
+			if len(dt.sends) != 1 {
+				t.Fatalf("desktop sends %d", len(dt.sends))
+			}
+			m := dt.sends[0]
+			keyless(t, m)
+			if m.Title != e.title || m.Body != e.body {
+				t.Errorf("shows\n  %q\n  %q\nwant\n  %q\n  %q", m.Title, m.Body, e.title, e.body)
+			}
+			for _, w := range []string{"`", "UTC", "key:", "more:", "about:", "plan-", "a6385479"} {
+				if strings.Contains(m.Text(), w) {
+					t.Errorf("it still says %q: %q", w, m.Text())
+				}
+			}
+			c.pass(e.openFor - BurstWindow)
+			cleared, err := DecodeCondition(EventCleared, e.event(c.now(), true))
+			if err != nil {
+				t.Fatal(err)
+			}
+			h.Condition(EventCleared, cleared)
+			done := dt.edits["1"]
+			if done.Title != e.cleared || done.Body != "" {
+				t.Errorf("clearance %q / %q, want one line %q", done.Title, done.Body, e.cleared)
+			}
+			t.Logf("\nBEFORE:\n%s\n\nAFTER:\n%s\n%s\n\nCLEARED:\n%s", e.before, m.Title, m.Body, done.Title)
+		})
+	}
+}
+
+// **A condition from a controller without plain words is said from its summary**, its markup taken out.
+func TestAConditionWithoutPlainWordsIsSaidFromItsSummary(t *testing.T) {
+	h, tg, _, c, _ := newHolder(t)
+	h.Zone = func() *time.Location { return time.UTC }
+	k := Condition{Key: "machine.ace.silent", Scope: "machine", ID: "ace", Kind: "silent", Severity: Urgent,
+		Summary: "ace has not been heard from: `push ace` sends it again", Raised: c.now()}
+	h.Condition(EventRaised, k)
+	m := tg.sends[0]
+	if m.Title != "Urgent: Silent on ace" || m.Body != "Ace has not been heard from: a command sends it again\nSince 12:00." {
+		t.Errorf("%q / %q", m.Title, m.Body)
+	}
+	keyless(t, m)
+}
+
+// **Times are the operator's**: today a clock time, this week a weekday, before that a date.
+func TestTimesAreSaidInTheOperatorsZone(t *testing.T) {
+	brussels, _ := time.LoadLocation("Europe/Brussels")
+	now := time.Date(2026, 10, 8, 10, 40, 0, 0, time.UTC)
+	for at, want := range map[time.Time]string{
+		now.Add(-56 * time.Minute):    "11:44",
+		now.Add(-26 * time.Hour):      "Wed 10:40",
+		now.Add(-10 * 24 * time.Hour): "28 Sep 12:40",
+	} {
+		if got := when(at, now, brussels); got != want {
+			t.Errorf("%s: %q, want %q", at, got, want)
+		}
+	}
+	if loc, err := zoneOf("Nowhere/Atlantis"); err == nil || loc != time.Local {
+		t.Errorf("a zone that does not exist was not said: %v", err)
+	}
+}

modules/messenger/module.json

@@ -62,7 +62,7 @@
       "path": "${dir:state}/settings.json",
       "mode": "0600",
       "merge": "json",
-      "content": "{\n  \"telegram-chat-id\": \"\",\n  \"desktop-machines\": []\n}\n"
+      "content": "{\n  \"telegram-chat-id\": \"\",\n  \"desktop-machines\": [],\n  \"time-zone\": \"\"\n}\n"
     }
   ],
   "build": {