gnome-keyring: the secret service as a module, claiming node-secret-service (hq ADR 0208, ADR 0102)

PAM lines written into login and passwd as blocks, so login unlocks the keyring
on both workstations; no daemon of its own; gcr's ssh agent named for the session
until the environment can say a runtime-directory path. Go tools unlocked, lock,
collections and ssh-keys, never reading a secret.

modules/clipmenu/README.md

@@ -0,0 +1,69 @@
+# clipmenu
+
+The clipboard manager as a module (novox/hq ADR 0208, research 026/04).
+
+- Installs `clipmenu` from the official repositories. It brings `clipnotify`, `xsel`, `xdotool` and
+  `dmenu` as its own dependencies.
+- Claims the mesh's `node-clipboard` seat and serves its verbs `history` and `copy`. Requires
+  `x11-display` on its own machine.
+- **Declares `rofi-greenclip` absent** (ADR 0180). This module replaces it.
+- Starts `clipmenud` **once per session**, from the session's start (the `xinitrc` slot `normal`).
+  It is not a user unit as well. Its packaged unit needs user-scoped units (mesh-host #72, not
+  merged), and the session start alone is one starter.
+- Binds `$mod+period` to `clipmenu`, as its own i3 drop-in (`50-clipmenu.conf`). clipmenu shows the
+  history through `dmenu`, the seat command of `node-launcher`, so it looks like every other menu.
+- Its settings are environment contributions (ADR 0203), read by the daemon, the menu and the tools
+  alike:
+  - `CM_SELECTIONS=clipboard`: what was copied, not every highlighted word. The found greenclip did
+    the same.
+  - `CM_MAX_CLIPS=500`: how many clips are kept.
+  - `CM_HISTLENGTH=15`: how many lines the menu shows.
+
+## Tools
+
+| tool | does |
+|---|---|
+| `node-clipboard.history` | the history, newest first, each entry once with its id, first line, time, size and text (cut) |
+| `node-clipboard.copy` | put text on the clipboard; it enters the history like any copy |
+| `clipmenu_paste` | what the clipboard holds now |
+| `clipmenu_clear` | forget the history; the daemon's locks stay |
+| `clipmenu_delete` | forget one entry, by id or first line |
+
+The history is read from clipmenu's own store, in the account's runtime directory, under clipmenu's
+own lock, so a copy arriving meanwhile is neither lost nor half-written. `copy` hands the text to an
+owner (`xsel`) under the account's service manager. As a child of the tools runtime, the clipboard
+would empty whenever the runtime restarted.
+
+## What it improves on what was found
+
+- **No AUR package.** greenclip came from the user repository. clipmenu is in the official one.
+- **Started once.** greenclip was started by the window manager on both workstations, and on the
+  desktop by an enabled user unit as well.
+- **No absolute home path** in any configuration. greenclip's named one.
+- **The history does not outlive a reboot.** greenclip kept it in `~/.cache`, so every password ever
+  copied stayed on disk. clipmenu keeps it in the runtime directory, which is memory.
+- **One menu.** The history appears in the launcher's own menu, through the seat's `dmenu` command,
+  instead of a theme from a cloned theme repository.
+
+## What it leaves as found
+
+- `~/.config/greenclip.toml` and greenclip's history, `~/.cache/greenclip.history`.
+- On the desktop: greenclip's enabled user unit link
+  (`~/.config/systemd/user/default.target.wants/greenclip.service`). It dangles once the package is
+  gone.
+
+## Migration (ADR 0182)
+
+1. After the first push, delete `~/.config/greenclip.toml` and `~/.cache/greenclip.history`.
+2. On the desktop: `systemctl --user disable greenclip.service`, before the push if you can. The
+   package's removal takes the unit file with it.
+3. Until the `i3` module carries the main configuration, the found `exec --no-startup-id greenclip
+   daemon` and `$mod+period` lines stay in `~/.config/i3/config`. i3 reports `$mod+period` as bound
+   twice. The `i3` module's configuration carries neither.
+
+## Blockers
+
+- `node-clipboard`, `x11-display` and the `xinitrc` slot are ADR 0208's. Until the controller knows
+  them, `mctl` reads them as unknown.
+- `CM_*` reach the session through `node-env` (ADR 0203), so the account's environment module must
+  be assigned too. Without it clipmenu runs on its defaults: both selections, 1000 clips, 8 lines.

modules/clipmenu/cmd/clipmenu-tools/args.go

@@ -0,0 +1,97 @@
+// Reading a tool's arguments: JSON numbers arrive as float64, and a missing argument is its default.
+// The same in every desktop module that carries it.
+package main
+
+import (
+	"fmt"
+	"math"
+	"strings"
+	"time"
+)
+
+// text is a string argument, trimmed; required says an empty one is refused.
+func text(args map[string]any, key string, required bool) (string, error) {
+	v, present := args[key]
+	if !present || v == nil {
+		if required {
+			return "", fmt.Errorf("%s is required", key)
+		}
+		return "", nil
+	}
+	s, ok := v.(string)
+	if !ok {
+		return "", fmt.Errorf("%s is a string, not %T", key, v)
+	}
+	s = strings.TrimSpace(s)
+	if s == "" && required {
+		return "", fmt.Errorf("%s is required", key)
+	}
+	return s, nil
+}
+
+// whole is a whole-number argument within [least, most], or def when absent.
+func whole(args map[string]any, key string, def, least, most int) (int, error) {
+	v, present := args[key]
+	if !present || v == nil {
+		return def, nil
+	}
+	f, ok := v.(float64)
+	if !ok {
+		if i, isInt := v.(int); isInt {
+			f = float64(i)
+		} else {
+			return 0, fmt.Errorf("%s is a number, not %T", key, v)
+		}
+	}
+	if f != math.Trunc(f) {
+		return 0, fmt.Errorf("%s is a whole number, not %v", key, f)
+	}
+	n := int(f)
+	if n < least || n > most {
+		return 0, fmt.Errorf("%s is %d; it is between %d and %d", key, n, least, most)
+	}
+	return n, nil
+}
+
+// flag is a boolean argument, or def when absent.
+func flag(args map[string]any, key string, def bool) (bool, error) {
+	v, present := args[key]
+	if !present || v == nil {
+		return def, nil
+	}
+	b, ok := v.(bool)
+	if !ok {
+		return false, fmt.Errorf("%s is true or false, not %T", key, v)
+	}
+	return b, nil
+}
+
+// texts is a list-of-strings argument.
+func texts(args map[string]any, key string) ([]string, error) {
+	v, present := args[key]
+	if !present || v == nil {
+		return nil, nil
+	}
+	list, ok := v.([]any)
+	if !ok {
+		if ss, isStrings := v.([]string); isStrings {
+			return ss, nil
+		}
+		return nil, fmt.Errorf("%s is a list of strings, not %T", key, v)
+	}
+	out := make([]string, 0, len(list))
+	for i, item := range list {
+		s, ok := item.(string)
+		if !ok {
+			return nil, fmt.Errorf("%s[%d] is a string, not %T", key, i, item)
+		}
+		out = append(out, s)
+	}
+	return out, nil
+}
+
+// seconds is a timeout argument in seconds, defaulted and bounded below the runtime's call limit.
+func seconds(args map[string]any, key string, def, most int) (time.Duration, error) {
+	n, err := whole(args, key, def, 1, most)
+	return time.Duration(n) * time.Second, err
+}

modules/clipmenu/cmd/clipmenu-tools/clipboard.go

@@ -0,0 +1,348 @@
+package main
+
+import (
+	"bufio"
+	"errors"
+	"fmt"
+	"os"
+	"os/user"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"syscall"
+	"time"
+)
+
+const (
+	mostCopy  = 1 << 20
+	mostPaste = 64 << 10
+	// majorVersion is clipmenu's store layout: <dir>/clipmenu.<major>.<user>/.
+	majorVersion = 6
+)
+
+// account is the user clipmenu's store is named for.
+func account() string {
+	for _, k := range []string{"USER", "MESH_OPERATOR_ACCOUNT", "LOGNAME"} {
+		if v := strings.TrimSpace(os.Getenv(k)); v != "" {
+			return v
+		}
+	}
+	if u, err := user.Current(); err == nil {
+		return u.Username
+	}
+	return ""
+}
+
+// storeDir is where clipmenud keeps the history: CM_DIR, else the account's runtime directory.
+func storeDir(s Session) (string, error) {
+	base := os.Getenv("CM_DIR")
+	if base == "" {
+		base = s.RuntimeDir
+	}
+	if base == "" {
+		return "", fmt.Errorf("%w: the account's runtime directory, where the clipboard history lives, is missing (the account is not logged in)", ErrNoBus)
+	}
+	return filepath.Join(base, fmt.Sprintf("clipmenu.%d.%s", majorVersion, account())), nil
+}
+
+// cksum is POSIX cksum(1) of data: clipmenu names each entry's file by the cksum of its first line
+// followed by a newline, as "<crc> <length>".
+func cksum(data []byte) string {
+	var crc uint32
+	step := func(b byte) {
+		crc ^= uint32(b) << 24
+		for i := 0; i < 8; i++ {
+			if crc&0x80000000 != 0 {
+				crc = crc<<1 ^ 0x04C11DB7
+			} else {
+				crc <<= 1
+			}
+		}
+	}
+	for _, b := range data {
+		step(b)
+	}
+	for n := len(data); n != 0; n >>= 8 {
+		step(byte(n))
+	}
+	return fmt.Sprintf("%d %d", ^crc, len(data))
+}
+
+func entryID(line string) string { return cksum([]byte(line + "\n")) }
+
+// Entry is one clip in the history.
+type Entry struct {
+	ID        string `json:"id"`
+	Line      string `json:"line"`
+	At        string `json:"at"`
+	Bytes     int    `json:"bytes"`
+	Text      string `json:"text,omitempty"`
+	Truncated bool   `json:"truncated,omitempty"`
+	at        int64
+}
+
+// HistoryResult is what node-clipboard.history answers.
+type HistoryResult struct {
+	Collecting bool    `json:"collecting"`
+	Store      string  `json:"store"`
+	Total      int     `json:"total"`
+	Entries    []Entry `json:"entries"`
+}
+
+// readStore reads clipmenu's line cache: one "<nanoseconds> <first line>" per copy, oldest first, a
+// line repeated when the same thing was copied again. The newest copy of each line wins.
+func readStore(dir string) ([]Entry, error) {
+	f, err := os.Open(filepath.Join(dir, "line_cache"))
+	if errors.Is(err, os.ErrNotExist) {
+		return []Entry{}, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	defer f.Close()
+	latest := map[string]int64{}
+	scan := bufio.NewScanner(f)
+	scan.Buffer(make([]byte, 64<<10), 1<<20)
+	for scan.Scan() {
+		stamp, line, ok := strings.Cut(scan.Text(), " ")
+		if !ok {
+			continue
+		}
+		ns, err := strconv.ParseInt(stamp, 10, 64)
+		if err != nil {
+			continue
+		}
+		if ns >= latest[line] {
+			latest[line] = ns
+		}
+	}
+	out := make([]Entry, 0, len(latest))
+	for line, ns := range latest {
+		out = append(out, Entry{ID: entryID(line), Line: line, at: ns, At: time.Unix(0, ns).Format(time.RFC3339)})
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].at > out[j].at })
+	return out, scan.Err()
+}
+
+// History is the clipboard's history, newest first.
+func History(limit, maxBytes int) (HistoryResult, error) {
+	dir, err := storeDir(findEnvironment())
+	if err != nil {
+		return HistoryResult{}, err
+	}
+	entries, err := readStore(dir)
+	if err != nil {
+		return HistoryResult{}, err
+	}
+	out := HistoryResult{Collecting: len(processesOf("clipmenud")) > 0, Store: dir, Total: len(entries), Entries: []Entry{}}
+	for i, e := range entries {
+		if i == limit {
+			break
+		}
+		if info, err := os.Stat(filepath.Join(dir, e.ID)); err == nil {
+			e.Bytes = int(info.Size())
+			if maxBytes > 0 {
+				raw, _ := os.ReadFile(filepath.Join(dir, e.ID))
+				if len(raw) > maxBytes {
+					raw, e.Truncated = raw[:maxBytes], true
+				}
+				e.Text = string(raw)
+			}
+		}
+		out.Entries = append(out.Entries, e)
+	}
+	return out, nil
+}
+
+// CopyResult is what node-clipboard.copy answers.
+type CopyResult struct {
+	Bytes int    `json:"bytes"`
+	Unit  string `json:"unit"`
+}
+
+// Copy puts text on the clipboard. The clipboard is owned by a process until another copies, so the
+// owner (xsel) runs under the account's service manager, not as a child of this tool.
+func Copy(text string) (CopyResult, error) {
+	if len(text) == 0 {
+		return CopyResult{}, errors.New("text is empty; to empty the clipboard's history, clipmenu_clear")
+	}
+	if len(text) > mostCopy {
+		return CopyResult{}, fmt.Errorf("%d bytes; the clipboard takes at most %d here", len(text), mostCopy)
+	}
+	s, err := findSession()
+	if err != nil {
+		return CopyResult{}, err
+	}
+	if s.RuntimeDir == "" {
+		return CopyResult{}, fmt.Errorf("%w: no runtime directory to hand the text over in", ErrNoBus)
+	}
+	// Handed over in a file only the account can read, which the owner reads and removes.
+	f, err := os.CreateTemp(s.RuntimeDir, "clipmenu-copy-")
+	if err != nil {
+		return CopyResult{}, err
+	}
+	if _, err := f.WriteString(text); err != nil {
+		f.Close()
+		os.Remove(f.Name())
+		return CopyResult{}, err
+	}
+	f.Close()
+	unit := uniqueUnit("clipmenu-copy")
+	script := `xsel --nodetach --input --clipboard < "$0" & sleep 1; rm -f "$0"; wait`
+	if err := s.detach(unit, "/bin/sh", "-c", script, f.Name()); err != nil {
+		os.Remove(f.Name())
+		return CopyResult{}, err
+	}
+	return CopyResult{Bytes: len(text), Unit: unit + ".service"}, nil
+}
+
+// PasteResult is what clipmenu_paste answers.
+type PasteResult struct {
+	Text      string `json:"text"`
+	Bytes     int    `json:"bytes"`
+	Truncated bool   `json:"truncated,omitempty"`
+}
+
+// Paste reads the clipboard now.
+func Paste() (PasteResult, error) {
+	s, err := findSession()
+	if err != nil {
+		return PasteResult{}, err
+	}
+	r, err := s.run(5*time.Second, "", "xsel", "--output", "--clipboard")
+	if err != nil {
+		return PasteResult{}, err
+	}
+	if r.Code != 0 {
+		return PasteResult{}, fmt.Errorf("xsel: %s", strings.TrimSpace(r.Stderr))
+	}
+	out := PasteResult{Text: r.Stdout, Bytes: len(r.Stdout), Truncated: r.Truncated}
+	if len(out.Text) > mostPaste {
+		out.Text, out.Truncated = out.Text[:mostPaste], true
+	}
+	return out, nil
+}
+
+// ChangeResult is what clear and delete answer.
+type ChangeResult struct {
+	Removed   int `json:"removed"`
+	Remaining int `json:"remaining"`
+}
+
+// withStoreLock holds clipmenu's own lock on its store, the one clipmenud and clipdel take, while
+// change runs, so a copy arriving meanwhile is neither lost nor half-written.
+func withStoreLock(dir string, change func() error) error {
+	lock, err := os.OpenFile(filepath.Join(dir, "lock"), os.O_CREATE|os.O_WRONLY, 0o600)
+	if err != nil {
+		return err
+	}
+	defer lock.Close()
+	deadline := time.Now().Add(2 * time.Second)
+	for {
+		err := syscall.Flock(int(lock.Fd()), syscall.LOCK_EX|syscall.LOCK_NB)
+		if err == nil {
+			break
+		}
+		if time.Now().After(deadline) {
+			return fmt.Errorf("the clipboard store is locked by clipmenud and did not come free within 2s")
+		}
+		time.Sleep(50 * time.Millisecond)
+	}
+	defer syscall.Flock(int(lock.Fd()), syscall.LOCK_UN)
+	return change()
+}
+
+func storeOf() (string, error) {
+	dir, err := storeDir(findEnvironment())
+	if err != nil {
+		return "", err
+	}
+	if _, err := os.Stat(dir); errors.Is(err, os.ErrNotExist) {
+		return "", fmt.Errorf("there is no clipboard history at %s: clipmenud has not run in this login", dir)
+	}
+	return dir, nil
+}
+
+// Clear forgets every entry and its text, keeping the store and its locks (clipdel's own clear
+// removes the directory, the daemon's lock with it).
+func Clear() (ChangeResult, error) {
+	dir, err := storeOf()
+	if err != nil {
+		return ChangeResult{}, err
+	}
+	var out ChangeResult
+	err = withStoreLock(dir, func() error {
+		entries, err := readStore(dir)
+		if err != nil {
+			return err
+		}
+		out.Removed = len(entries)
+		files, err := os.ReadDir(dir)
+		if err != nil {
+			return err
+		}
+		for _, f := range files {
+			switch f.Name() {
+			case "lock", "session_lock", "line_cache":
+				continue
+			}
+			if f.Type().IsRegular() {
+				if err := os.Remove(filepath.Join(dir, f.Name())); err != nil {
+					return err
+				}
+			}
+		}
+		return os.WriteFile(filepath.Join(dir, "line_cache"), nil, 0o600)
+	})
+	return out, err
+}
+
+// Delete forgets one entry, by id or by its first line.
+func Delete(id, line string) (ChangeResult, error) {
+	if (id == "") == (line == "") {
+		return ChangeResult{}, errors.New("give the entry's id or its line, one of the two")
+	}
+	dir, err := storeOf()
+	if err != nil {
+		return ChangeResult{}, err
+	}
+	var out ChangeResult
+	err = withStoreLock(dir, func() error {
+		raw, err := os.ReadFile(filepath.Join(dir, "line_cache"))
+		if err != nil && !errors.Is(err, os.ErrNotExist) {
+			return err
+		}
+		var kept []string
+		for _, l := range strings.Split(strings.TrimRight(string(raw), "\n"), "\n") {
+			if l == "" {
+				continue
+			}
+			_, text, _ := strings.Cut(l, " ")
+			if text == line || (id != "" && entryID(text) == id) {
+				out.Removed++
+				_ = os.Remove(filepath.Join(dir, entryID(text)))
+				continue
+			}
+			kept = append(kept, l)
+		}
+		if out.Removed == 0 {
+			return fmt.Errorf("no entry %s%s in the clipboard history", id, line)
+		}
+		content := strings.Join(kept, "\n")
+		if content != "" {
+			content += "\n"
+		}
+		tmp := filepath.Join(dir, ".line_cache.mesh")
+		if err := os.WriteFile(tmp, []byte(content), 0o600); err != nil {
+			return err
+		}
+		return os.Rename(tmp, filepath.Join(dir, "line_cache"))
+	})
+	if err != nil {
+		return ChangeResult{}, err
+	}
+	entries, _ := readStore(dir)
+	out.Remaining = len(entries)
+	return out, nil
+}

modules/clipmenu/cmd/clipmenu-tools/clipboard_test.go

@@ -0,0 +1,163 @@
+package main
+
+import (
+	"errors"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+)
+
+const nobody = 4194400
+
+func TestEntryIdsAreWhatClipmenuNamesItsFiles(t *testing.T) {
+	for _, line := range []string{"hello", "", "two words (3 lines)", "ünïcode ✓", strings.Repeat("x", 300)} {
+		out, err := exec.Command("bash", "-c", `cksum <<< "$1"`, "_", line).Output()
+		if err != nil {
+			t.Skip("bash or cksum is missing here")
+		}
+		if got, want := entryID(line), strings.TrimSpace(string(out)); got != want {
+			t.Errorf("%q: %s, cksum says %s", line, got, want)
+		}
+	}
+}
+
+// store makes clipmenu's store as clipmenud leaves it, for the account the tools run as.
+func store(t *testing.T, clips map[string]string, order ...string) string {
+	t.Helper()
+	fakeMachine(t)
+	runtime := filepath.Join(runUserDir, strconv.Itoa(os.Getuid()))
+	t.Setenv("USER", "op")
+	t.Setenv("CM_DIR", "")
+	dir := filepath.Join(runtime, "clipmenu.6.op")
+	if err := os.MkdirAll(dir, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(runtime, "bus"), nil, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	var cache strings.Builder
+	for i, line := range order {
+		cache.WriteString(strconv.FormatInt(1_700_000_000_000_000_000+int64(i)*1_000_000_000, 10) + " " + line + "\n")
+		if err := os.WriteFile(filepath.Join(dir, entryID(line)), []byte(clips[line]), 0o600); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := os.WriteFile(filepath.Join(dir, "line_cache"), []byte(cache.String()), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	return dir
+}
+
+func TestTheHistoryIsNewestFirstOnceEachWithItsText(t *testing.T) {
+	store(t, map[string]string{"first": "first", "second (2 lines)": "second\nline two"}, "first", "second (2 lines)", "first")
+	fakeProcess(t, nobody, "clipmenud")
+	h, err := History(10, 4096)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !h.Collecting || h.Total != 2 || h.Entries[0].Line != "first" || h.Entries[1].Text != "second\nline two" || h.Entries[1].Bytes != 15 {
+		t.Fatalf("%+v", h)
+	}
+	if h, _ := History(1, 3); len(h.Entries) != 1 || h.Entries[0].Text != "fir" || !h.Entries[0].Truncated {
+		t.Fatalf("limited and cut: %+v", h)
+	}
+	if h, _ := History(10, 0); h.Entries[0].Text != "" || h.Entries[0].Bytes != 5 {
+		t.Fatalf("without text: %+v", h)
+	}
+}
+
+func TestAnEntryIsDeletedByIdOrLineWithItsText(t *testing.T) {
+	dir := store(t, map[string]string{"a": "a", "b": "b", "c": "c"}, "a", "b", "c", "a")
+	r, err := Delete(entryID("a"), "")
+	if err != nil || r.Removed != 2 || r.Remaining != 2 {
+		t.Fatalf("by id, both copies: %+v, %v", r, err)
+	}
+	if _, err := os.Stat(filepath.Join(dir, entryID("a"))); !errors.Is(err, os.ErrNotExist) {
+		t.Fatal("the text stayed")
+	}
+	if r, err := Delete("", "b"); err != nil || r.Removed != 1 || r.Remaining != 1 {
+		t.Fatalf("by line: %+v, %v", r, err)
+	}
+	if _, err := Delete("", "zzz"); err == nil {
+		t.Fatal("a missing entry was reported deleted")
+	}
+	if _, err := Delete("x", "y"); err == nil {
+		t.Fatal("both an id and a line were accepted")
+	}
+	cache, _ := os.ReadFile(filepath.Join(dir, "line_cache"))
+	if !strings.HasSuffix(string(cache), " c\n") || strings.Count(string(cache), "\n") != 1 {
+		t.Fatalf("line cache: %q", cache)
+	}
+}
+
+func TestClearForgetsEverythingButKeepsTheDaemonsLocks(t *testing.T) {
+	dir := store(t, map[string]string{"a": "a", "b": "b"}, "a", "b")
+	if err := os.WriteFile(filepath.Join(dir, "session_lock"), nil, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	r, err := Clear()
+	if err != nil || r.Removed != 2 {
+		t.Fatalf("%+v, %v", r, err)
+	}
+	left, _ := os.ReadDir(dir)
+	var names []string
+	for _, f := range left {
+		names = append(names, f.Name())
+	}
+	if strings.Join(names, ",") != "line_cache,lock,session_lock" {
+		t.Fatalf("left: %v", names)
+	}
+}
+
+func TestCopyHandsTheTextToAnOwnerUnderTheAccountsServiceManager(t *testing.T) {
+	store(t, nil)
+	fakeProcess(t, nobody, "i3", "DISPLAY=:1")
+	bin := fakeBinaries(t, map[string]string{"systemctl": "true", "systemd-run": `echo "$*" > "$LOG"; for last; do :; done; cat "$last" > "$LOG.text"`})
+	t.Setenv("LOG", filepath.Join(bin, "log"))
+	r, err := Copy("secret-free text")
+	if err != nil || r.Bytes != 16 || !strings.HasPrefix(r.Unit, "clipmenu-copy-") {
+		t.Fatalf("%+v, %v", r, err)
+	}
+	asked, _ := os.ReadFile(filepath.Join(bin, "log"))
+	if !strings.Contains(string(asked), "--setenv=DISPLAY=:1 -- /bin/sh -c xsel --nodetach --input --clipboard") {
+		t.Fatalf("asked: %s", asked)
+	}
+	handed, _ := os.ReadFile(filepath.Join(bin, "log.text"))
+	if string(handed) != "secret-free text" {
+		t.Fatalf("handed over: %q", handed)
+	}
+	if _, err := Copy(""); err == nil {
+		t.Fatal("empty text was accepted")
+	}
+}
+
+func TestPasteReadsTheClipboardOrSaysThereIsNoSession(t *testing.T) {
+	fakeMachine(t)
+	if _, err := Paste(); !errors.Is(err, ErrNoSession) {
+		t.Fatal(err)
+	}
+	fakeProcess(t, nobody, "i3", "DISPLAY=:1")
+	fakeBinaries(t, map[string]string{"xsel": `[ "$*" = "--output --clipboard" ] && printf 'on the clipboard'`})
+	p, err := Paste()
+	if err != nil || p.Text != "on the clipboard" || p.Bytes != 16 {
+		t.Fatalf("%+v, %v", p, err)
+	}
+}
+
+func TestWithoutAStoreTheChangesSayWhy(t *testing.T) {
+	fakeMachine(t)
+	runtime := filepath.Join(runUserDir, strconv.Itoa(os.Getuid()))
+	if err := os.MkdirAll(runtime, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("USER", "op")
+	if _, err := Clear(); err == nil || !strings.Contains(err.Error(), "clipmenud has not run") {
+		t.Fatal(err)
+	}
+	if h, err := History(5, 0); err != nil || h.Total != 0 || h.Collecting {
+		t.Fatalf("an empty history: %+v, %v", h, err)
+	}
+}

modules/clipmenu/cmd/clipmenu-tools/main.go

@@ -0,0 +1,90 @@
+// clipmenu's Go tools bundle (novox/hq ADR 0188, ADR 0193, ADR 0208): its implementation of
+// node-clipboard's verbs `history` and `copy`, and its own tools, served by the node's runtime as the
+// operator account. The history is read from clipmenu's own store in the account's runtime directory;
+// the clipboard itself is the X session's.
+package main
+
+import (
+	"fmt"
+	"os"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+func main() {
+	if err := stdio.Serve("", tools()); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+func tools() []stdio.Tool {
+	return []stdio.Tool{
+		{
+			Name: "node-clipboard.history",
+			Description: "What the operator copied, newest first: each entry's id, its first line, when, its size " +
+				"and its text (each cut at max_bytes). Whether the clipboard daemon is collecting.",
+			Input: map[string]any{
+				"limit":     map[string]any{"type": "integer", "description": "at most this many entries (default 20, at most 500)"},
+				"max_bytes": map[string]any{"type": "integer", "description": "cut each entry's text at this many bytes; 0 leaves the text out (default 4096, at most 65536)"},
+			},
+			Run: func(args map[string]any) (any, error) {
+				limit, err := whole(args, "limit", 20, 1, 500)
+				if err != nil {
+					return nil, err
+				}
+				most, err := whole(args, "max_bytes", 4096, 0, 65536)
+				if err != nil {
+					return nil, err
+				}
+				return History(limit, most)
+			},
+		},
+		{
+			Name: "node-clipboard.copy",
+			Description: "Put text on the operator's clipboard, as if they had copied it; it enters the history " +
+				"like any copy. Answers how many bytes.",
+			Input: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"text": map[string]any{"type": "string", "description": fmt.Sprintf("the text (at most %d bytes)", mostCopy)},
+				},
+				"required": []string{"text"},
+			},
+			Run: func(args map[string]any) (any, error) {
+				t, ok := args["text"].(string)
+				if !ok {
+					return nil, fmt.Errorf("text is required, as a string")
+				}
+				return Copy(t)
+			},
+		},
+		{
+			Name:        "clipmenu_paste",
+			Description: "What the operator's clipboard holds right now, as text (cut at 64 KiB, said in truncated).",
+			Run:         func(map[string]any) (any, error) { return Paste() },
+		},
+		{
+			Name:        "clipmenu_clear",
+			Description: "Forget the whole clipboard history. What is on the clipboard now stays there.",
+			Run:         func(map[string]any) (any, error) { return Clear() },
+		},
+		{
+			Name: "clipmenu_delete",
+			Description: "Forget one entry of the clipboard history, by its id as the history answers it, or by " +
+				"its first line exactly.",
+			Input: map[string]any{
+				"id":   map[string]any{"type": "string", "description": "the entry's id"},
+				"line": map[string]any{"type": "string", "description": "the entry's first line, exactly"},
+			},
+			Run: func(args map[string]any) (any, error) {
+				id, err := text(args, "id", false)
+				if err != nil {
+					return nil, err
+				}
+				line, _ := args["line"].(string)
+				return Delete(id, line)
+			},
+		},
+	}
+}

modules/clipmenu/cmd/clipmenu-tools/manifest_helpers_test.go

@@ -0,0 +1,175 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// The module's manifest, read the way the catalogue reads it, for the manifest tests. The same in
+// every desktop module that carries it.
+
+type manifest struct {
+	Module       string           `json:"module"`
+	Version      string           `json:"version"`
+	Capabilities []string         `json:"capabilities"`
+	Requires     []string         `json:"requires"`
+	Claims       []claim          `json:"claims"`
+	Seats        []any            `json:"seats"`
+	Tools        []string         `json:"tools"`
+	Environment  *environment     `json:"environment"`
+	Shell        []shellCode      `json:"shell"`
+	Resources    []map[string]any `json:"resources"`
+	Build        struct {
+		Artifacts []map[string]any `json:"artifacts"`
+	} `json:"build"`
+}
+
+type claim struct {
+	Name   string   `json:"name"`
+	Scope  string   `json:"scope"`
+	Serves []string `json:"serves"`
+}
+
+type environment struct {
+	Variables map[string]string `json:"variables"`
+	Path      []map[string]any  `json:"path"`
+}
+
+type shellCode struct {
+	For  string `json:"for"`
+	Slot string `json:"slot"`
+	Code string `json:"code"`
+}
+
+func readManifest(t *testing.T) manifest {
+	t.Helper()
+	raw, err := os.ReadFile(filepath.Join("..", "..", "module.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	dec := json.NewDecoder(strings.NewReader(string(raw)))
+	dec.DisallowUnknownFields()
+	var m manifest
+	if err := dec.Decode(&m); err != nil {
+		t.Fatalf("module.json: %v", err)
+	}
+	return m
+}
+
+func (m manifest) resource(t *testing.T, id string) map[string]any {
+	t.Helper()
+	for _, r := range m.Resources {
+		if r["id"] == id {
+			return r
+		}
+	}
+	t.Fatalf("no resource %q", id)
+	return nil
+}
+
+func (m manifest) packages() (present, absent []string) {
+	for _, r := range m.Resources {
+		if r["type"] == "package" {
+			if r["absent"] == true {
+				absent = append(absent, r["package"].(string))
+			} else {
+				present = append(present, r["package"].(string))
+			}
+		}
+	}
+	return present, absent
+}
+
+// sameAsSource checks that a file resource's content is byte for byte the module's source file, so
+// the readable file in the repository is what the machine gets.
+func (m manifest) sameAsSource(t *testing.T, id, source string) {
+	t.Helper()
+	want, err := os.ReadFile(filepath.Join("..", "..", source))
+	if err != nil {
+		t.Fatal(err)
+	}
+	r := m.resource(t, id)
+	if r["type"] != "file" {
+		t.Fatalf("%s is a %v, not a file", id, r["type"])
+	}
+	if got, _ := r["content"].(string); got != string(want) {
+		t.Fatalf("resource %s's content is not %s: edit the source and copy it into module.json", id, source)
+	}
+	if r["owner"] != "${machine:account}" && !strings.HasPrefix(r["path"].(string), "/etc/") {
+		t.Fatalf("%s under the home is the account's", id)
+	}
+}
+
+// checkTheToolsAgree checks that the manifest lists the module's own tools exactly, that the bundle
+// serves each seat verb the claims promise as <seat>.<verb>, and that the Go bundle is declared.
+func checkTheToolsAgree(t *testing.T, m manifest) {
+	t.Helper()
+	own, seat := map[string]bool{}, map[string]bool{}
+	for _, tool := range tools() {
+		if strings.Contains(tool.Name, ".") {
+			seat[tool.Name] = true
+		} else {
+			own[tool.Name] = true
+		}
+		if strings.TrimSpace(tool.Description) == "" {
+			t.Errorf("%s has no description", tool.Name)
+		}
+	}
+	listed := map[string]bool{}
+	for _, name := range m.Tools {
+		listed[name] = true
+		if !own[name] {
+			t.Errorf("module.json lists %s, which the bundle does not serve", name)
+		}
+	}
+	for name := range own {
+		if !listed[name] {
+			t.Errorf("the bundle serves %s, which module.json does not list", name)
+		}
+		if !strings.HasPrefix(name, strings.ReplaceAll(m.Module, "-", "_")+"_") {
+			t.Errorf("%s is not prefixed with the module's name", name)
+		}
+	}
+	promised := map[string]bool{}
+	for _, c := range m.Claims {
+		for _, verb := range c.Serves {
+			promised[c.Name+"."+verb] = true
+			if !seat[c.Name+"."+verb] {
+				t.Errorf("the claim on %s promises %s, which the bundle does not serve", c.Name, verb)
+			}
+		}
+	}
+	for name := range seat {
+		if !promised[name] {
+			t.Errorf("the bundle serves %s, which no claim promises", name)
+		}
+	}
+	var bundle map[string]any
+	for _, a := range m.Build.Artifacts {
+		if a["kind"] == "bundle" {
+			bundle = a
+		}
+	}
+	if bundle == nil || bundle["language"] != "go" || bundle["system"] != "arch" ||
+		bundle["from"] != "cmd/"+m.Module+"-tools" || bundle["binary"] != m.Module+"-tools" {
+		t.Errorf("the Go tools bundle: %v", bundle)
+	}
+}
+
+// checkNoSecretsOrInstallationNames refuses what a catalogue manifest must never carry.
+func checkNoSecretsOrInstallationNames(t *testing.T) {
+	t.Helper()
+	raw, err := os.ReadFile(filepath.Join("..", "..", "module.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := strings.ToLower(string(raw))
+	for _, never := range []string{"/home/", "jochen", "g14", "shanks", "novox.be", "api_key", ".hal/", "greenclip daemon"} {
+		if strings.Contains(s, never) {
+			t.Errorf("module.json names %q", never)
+		}
+	}
+}

modules/clipmenu/cmd/clipmenu-tools/manifest_test.go

@@ -0,0 +1,64 @@
+package main
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+)
+
+// clipmenu's shape (novox/hq ADR 0208, research 026/04): it claims node-clipboard serving history
+// and copy, requires the X display on its own machine, replaces greenclip, starts its daemon once
+// from the session's start, and binds its menu as an i3 drop-in through the launcher's dmenu command.
+
+func TestItClaimsTheClipboardSeatServingHistoryAndCopy(t *testing.T) {
+	m := readManifest(t)
+	if m.Module != "clipmenu" || m.Seats != nil {
+		t.Fatalf("module %q declares seats %v", m.Module, m.Seats)
+	}
+	if !reflect.DeepEqual(m.Claims, []claim{{Name: "node-clipboard", Scope: "node", Serves: []string{"history", "copy"}}}) {
+		t.Fatalf("claims: %+v", m.Claims)
+	}
+	if !reflect.DeepEqual(m.Requires, []string{"x11-display"}) {
+		t.Fatalf("requires: %v", m.Requires)
+	}
+	present, absent := m.packages()
+	if !reflect.DeepEqual(present, []string{"clipmenu"}) || !reflect.DeepEqual(absent, []string{"rofi-greenclip"}) {
+		t.Fatalf("packages: %v, absent %v", present, absent)
+	}
+}
+
+func TestTheDaemonStartsOnceFromTheSessionsStart(t *testing.T) {
+	m := readManifest(t)
+	if len(m.Shell) != 1 || m.Shell[0].For != "xinitrc" || m.Shell[0].Slot != "normal" {
+		t.Fatalf("%+v", m.Shell)
+	}
+	code := m.Shell[0].Code
+	if strings.Count(code, "\nclipmenud &\n") != 1 || strings.Contains(code, "greenclip") {
+		t.Fatalf("%q", code)
+	}
+	for _, r := range m.Resources {
+		if r["type"] == "service" || r["type"] == "process" {
+			t.Fatalf("a second start: %v", r)
+		}
+	}
+}
+
+func TestItsSettingsAreEnvironmentAndItsMenuIsTheLaunchersDmenu(t *testing.T) {
+	m := readManifest(t)
+	if !reflect.DeepEqual(m.Environment.Variables, map[string]string{"CM_SELECTIONS": "clipboard", "CM_MAX_CLIPS": "500", "CM_HISTLENGTH": "15"}) {
+		t.Fatalf("%v", m.Environment.Variables)
+	}
+	if _, set := m.Environment.Variables["CM_LAUNCHER"]; set {
+		t.Fatal("the launcher is clipmenu's default, dmenu: the seat's command")
+	}
+	m.sameAsSource(t, "i3-bindings", "files/i3/50-clipmenu.conf")
+	if c := m.resource(t, "i3-bindings")["content"].(string); !strings.Contains(c, "bindsym $mod+period exec --no-startup-id clipmenu") {
+		t.Fatalf("%s", c)
+	}
+}
+
+func TestTheToolsAgreeWithTheManifest(t *testing.T) {
+	m := readManifest(t)
+	checkTheToolsAgree(t, m)
+	checkNoSecretsOrInstallationNames(t)
+}

modules/clipmenu/cmd/clipmenu-tools/session.go

@@ -0,0 +1,423 @@
+// The operator's graphical session, as a tool the node's runtime runs finds it (novox/hq ADR 0208).
+//
+// The runtime is a system service running as the operator account (ADR 0175): it has the account's
+// uid and none of the session's environment — no DISPLAY, no XAUTHORITY, no session bus. A tool that
+// draws on the screen or talks to the desktop's D-Bus must find them. It reads them from a process of
+// the account that is part of the session (the window manager first), the same thing `loginctl` and
+// a person's own shell would point at, and says where it found them.
+//
+// Long-lived programs a tool starts go to the account's own service manager through `systemd-run
+// --user`, never as children of the tool: the runtime's unit is a cgroup the service manager empties
+// whenever the runtime restarts, and a compositor or a clipboard owner started from inside it would
+// die with it.
+//
+// This file is the same in every desktop module that carries it; it moves into the Go SDK once a
+// second consumer outside the desktop wants it.
+package main
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"syscall"
+	"time"
+)
+
+// Where the session is looked for. Variables so a test can point them at a fake tree.
+var (
+	procRoot   = "/proc"
+	runUserDir = "/run/user"
+	x11Sockets = "/tmp/.X11-unix"
+)
+
+// sessionHolders are the processes whose environment is the session's, best first: the window
+// manager is the session, the rest are its children. Anything else carrying DISPLAY ranks after them.
+var sessionHolders = []string{"i3", "sway", "i3bar", "picom", "xss-lock", "dunst", "clipmenud", "xterm"}
+
+// sessionKeys are the variables a session carries that a tool hands on to what it runs.
+var sessionKeys = []string{"DISPLAY", "XAUTHORITY", "WAYLAND_DISPLAY", "DBUS_SESSION_BUS_ADDRESS",
+	"XDG_RUNTIME_DIR", "XDG_SESSION_ID", "I3SOCK"}
+
+// Session is what a tool needs to reach the operator's desktop.
+type Session struct {
+	UID        int    `json:"uid"`
+	Display    string `json:"display,omitempty"`
+	XAuthority string `json:"xauthority,omitempty"`
+	Wayland    string `json:"wayland_display,omitempty"`
+	Bus        string `json:"bus,omitempty"`
+	RuntimeDir string `json:"runtime_dir,omitempty"`
+	SessionID  string `json:"session_id,omitempty"`
+	I3Sock     string `json:"i3sock,omitempty"`
+	// From says where the values were found: the tool's own environment, a process, or the socket.
+	From string `json:"from"`
+}
+
+// ErrNoSession is answered by a tool that needs the desktop when nobody is logged in to it.
+var ErrNoSession = errors.New("no graphical session")
+
+// ErrTimedOut is what run answers for a command ended because it ran past its time.
+var ErrTimedOut = errors.New("timed out")
+
+// ErrNoBus is answered by a tool that needs the session bus when the account has none.
+var ErrNoBus = errors.New("no session bus")
+
+// operatorHome is the account's home: what the runtime was told, else the process's own.
+func operatorHome() string {
+	if h := strings.TrimSpace(os.Getenv("MESH_OPERATOR_HOME")); h != "" {
+		return h
+	}
+	h, _ := os.UserHomeDir()
+	return h
+}
+
+// findSession finds the graphical session of the account this tool runs as, or answers
+// ErrNoSession with what it looked at.
+func findSession() (Session, error) {
+	s := findEnvironment()
+	if s.Display == "" && s.Wayland == "" {
+		return s, fmt.Errorf("%w for uid %d on this machine: no process of the account carries DISPLAY "+
+			"or WAYLAND_DISPLAY, and no X server socket in %s has an authority file to go with it. "+
+			"Is anyone logged in to the desktop?", ErrNoSession, s.UID, x11Sockets)
+	}
+	return s, nil
+}
+
+// findBus finds the account's session bus, which a logged-in account has whether or not a desktop
+// is running.
+func findBus() (Session, error) {
+	s := findEnvironment()
+	if s.Bus == "" {
+		return s, fmt.Errorf("%w for uid %d: DBUS_SESSION_BUS_ADDRESS is not set and %s does not exist "+
+			"(the account is not logged in)", ErrNoBus, s.UID, filepath.Join(runUserDir, strconv.Itoa(s.UID), "bus"))
+	}
+	return s, nil
+}
+
+func findEnvironment() Session {
+	uid := os.Getuid()
+	s := Session{UID: uid}
+	own := map[string]string{}
+	for _, k := range sessionKeys {
+		own[k] = os.Getenv(k)
+	}
+	if own["DISPLAY"] != "" || own["WAYLAND_DISPLAY"] != "" {
+		s.fill(own)
+		s.From = "the tool's own environment"
+	} else if pid, comm, env, ok := sessionProcess(uid); ok {
+		s.fill(env)
+		s.From = fmt.Sprintf("process %s (pid %d)", comm, pid)
+	} else if display, ok := lonelyX11Socket(); ok {
+		if a := filepath.Join(operatorHome(), ".Xauthority"); exists(a) {
+			s.Display, s.XAuthority = display, a
+			s.From = "the X server socket and the account's ~/.Xauthority"
+		}
+		s.fill(own)
+	} else {
+		s.fill(own)
+		s.From = "nothing: no session found"
+	}
+	// The bus and the runtime directory are the account's, whether or not the process named them.
+	runtime := filepath.Join(runUserDir, strconv.Itoa(uid))
+	if s.RuntimeDir == "" && exists(runtime) {
+		s.RuntimeDir = runtime
+	}
+	if s.Bus == "" && s.RuntimeDir != "" && exists(filepath.Join(s.RuntimeDir, "bus")) {
+		s.Bus = "unix:path=" + filepath.Join(s.RuntimeDir, "bus")
+	}
+	return s
+}
+
+func (s *Session) fill(env map[string]string) {
+	set := func(dst *string, key string) {
+		if *dst == "" {
+			*dst = env[key]
+		}
+	}
+	set(&s.Display, "DISPLAY")
+	set(&s.XAuthority, "XAUTHORITY")
+	set(&s.Wayland, "WAYLAND_DISPLAY")
+	set(&s.Bus, "DBUS_SESSION_BUS_ADDRESS")
+	set(&s.RuntimeDir, "XDG_RUNTIME_DIR")
+	set(&s.SessionID, "XDG_SESSION_ID")
+	set(&s.I3Sock, "I3SOCK")
+}
+
+// sessionProcess is the best process of this uid whose environment names a display.
+func sessionProcess(uid int) (int, string, map[string]string, bool) {
+	entries, err := os.ReadDir(procRoot)
+	if err != nil {
+		return 0, "", nil, false
+	}
+	type candidate struct {
+		pid  int
+		comm string
+		env  map[string]string
+		rank int
+	}
+	var found []candidate
+	for _, e := range entries {
+		pid, err := strconv.Atoi(e.Name())
+		if err != nil {
+			continue
+		}
+		dir := filepath.Join(procRoot, e.Name())
+		if owner, ok := ownerOf(dir); !ok || owner != uid {
+			continue
+		}
+		raw, err := os.ReadFile(filepath.Join(dir, "environ"))
+		if err != nil {
+			continue
+		}
+		env := parseEnviron(raw)
+		if env["DISPLAY"] == "" && env["WAYLAND_DISPLAY"] == "" {
+			continue
+		}
+		comm := readTrimmed(filepath.Join(dir, "comm"))
+		rank := len(sessionHolders)
+		for i, h := range sessionHolders {
+			if h == comm {
+				rank = i
+				break
+			}
+		}
+		found = append(found, candidate{pid, comm, env, rank})
+	}
+	if len(found) == 0 {
+		return 0, "", nil, false
+	}
+	sort.Slice(found, func(i, j int) bool {
+		if found[i].rank != found[j].rank {
+			return found[i].rank < found[j].rank
+		}
+		return found[i].pid > found[j].pid // the newer of two equals
+	})
+	best := found[0]
+	return best.pid, best.comm, best.env, true
+}
+
+func parseEnviron(raw []byte) map[string]string {
+	env := map[string]string{}
+	for _, kv := range bytes.Split(raw, []byte{0}) {
+		if i := bytes.IndexByte(kv, '='); i > 0 {
+			env[string(kv[:i])] = string(kv[i+1:])
+		}
+	}
+	return env
+}
+
+func ownerOf(path string) (int, bool) {
+	info, err := os.Stat(path)
+	if err != nil {
+		return 0, false
+	}
+	st, ok := info.Sys().(*syscall.Stat_t)
+	if !ok {
+		return 0, false
+	}
+	return int(st.Uid), true
+}
+
+// lonelyX11Socket is the display of the one X server socket there is, when there is exactly one.
+func lonelyX11Socket() (string, bool) {
+	entries, err := os.ReadDir(x11Sockets)
+	if err != nil {
+		return "", false
+	}
+	var displays []string
+	for _, e := range entries {
+		if n := strings.TrimPrefix(e.Name(), "X"); n != e.Name() {
+			if _, err := strconv.Atoi(n); err == nil {
+				displays = append(displays, ":"+n)
+			}
+		}
+	}
+	if len(displays) != 1 {
+		return "", false
+	}
+	return displays[0], true
+}
+
+func readTrimmed(path string) string {
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(string(b))
+}
+
+func exists(path string) bool {
+	_, err := os.Stat(path)
+	return err == nil
+}
+
+// Env is this process's environment with the session's variables in place of its own.
+func (s Session) Env() []string {
+	drop := map[string]bool{}
+	for _, k := range sessionKeys {
+		drop[k] = true
+	}
+	var env []string
+	for _, kv := range os.Environ() {
+		if i := strings.IndexByte(kv, '='); i > 0 && drop[kv[:i]] {
+			continue
+		}
+		env = append(env, kv)
+	}
+	add := func(k, v string) {
+		if v != "" {
+			env = append(env, k+"="+v)
+		}
+	}
+	add("DISPLAY", s.Display)
+	add("XAUTHORITY", s.XAuthority)
+	add("WAYLAND_DISPLAY", s.Wayland)
+	add("DBUS_SESSION_BUS_ADDRESS", s.Bus)
+	add("XDG_RUNTIME_DIR", s.RuntimeDir)
+	add("XDG_SESSION_ID", s.SessionID)
+	add("I3SOCK", s.I3Sock)
+	return env
+}
+
+// mostOutput bounds what a command may answer with, per stream.
+const mostOutput = 256 << 10
+
+// Result is what a command did.
+type Result struct {
+	Stdout    string `json:"stdout"`
+	Stderr    string `json:"stderr,omitempty"`
+	Code      int    `json:"code"`
+	Truncated bool   `json:"truncated,omitempty"`
+}
+
+// run runs a command in the session's environment, its input given, ended with everything it
+// started after timeout. A command that is not installed is an error naming it; one that exits
+// non-zero is a Result with its code, for the caller to judge.
+func (s Session) run(timeout time.Duration, stdin string, name string, args ...string) (Result, error) {
+	path, err := exec.LookPath(name)
+	if err != nil {
+		return Result{}, fmt.Errorf("%s is not installed on this machine", name)
+	}
+	cmd := exec.Command(path, args...)
+	cmd.Env = s.Env()
+	if home := operatorHome(); exists(home) {
+		cmd.Dir = home
+	}
+	if stdin != "" {
+		cmd.Stdin = strings.NewReader(stdin)
+	}
+	var out, errOut capped
+	cmd.Stdout, cmd.Stderr = &out, &errOut
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+	if err := cmd.Start(); err != nil {
+		return Result{}, fmt.Errorf("%s: %w", name, err)
+	}
+	done := make(chan error, 1)
+	go func() { done <- cmd.Wait() }()
+	select {
+	case err = <-done:
+	case <-time.After(timeout):
+		_ = syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)
+		<-done
+		return Result{Stdout: out.String(), Stderr: errOut.String()},
+			fmt.Errorf("%s did not finish within %s and was ended: %w", name, timeout, ErrTimedOut)
+	}
+	r := Result{Stdout: out.String(), Stderr: errOut.String(), Truncated: out.cut || errOut.cut}
+	var exit *exec.ExitError
+	if errors.As(err, &exit) {
+		r.Code = exit.ExitCode()
+	} else if err != nil {
+		return r, fmt.Errorf("%s: %w", name, err)
+	}
+	return r, nil
+}
+
+// detach starts a long-lived program under the account's own service manager, as a transient unit
+// that carries the session's display, so it outlives the runtime that asked for it. A unit already
+// running under the same name is stopped first, so a fixed name means "at most one".
+func (s Session) detach(unit string, args ...string) error {
+	if s.RuntimeDir == "" {
+		return fmt.Errorf("%w: the account's runtime directory is missing, so its service manager "+
+			"cannot be reached", ErrNoBus)
+	}
+	_, _ = s.run(5*time.Second, "", "systemctl", "--user", "stop", unit+".service")
+	call := []string{"--user", "--collect", "--quiet", "--unit=" + unit}
+	for _, kv := range [][2]string{{"DISPLAY", s.Display}, {"XAUTHORITY", s.XAuthority},
+		{"WAYLAND_DISPLAY", s.Wayland}, {"XDG_SESSION_ID", s.SessionID}, {"I3SOCK", s.I3Sock}} {
+		if kv[1] != "" {
+			call = append(call, "--setenv="+kv[0]+"="+kv[1])
+		}
+	}
+	call = append(call, "--")
+	call = append(call, args...)
+	r, err := s.run(10*time.Second, "", "systemd-run", call...)
+	if err != nil {
+		return err
+	}
+	if r.Code != 0 {
+		return fmt.Errorf("systemd-run %s: %s", unit, strings.TrimSpace(r.Stderr))
+	}
+	return nil
+}
+
+// uniqueUnit is a transient unit name that will not collide with an earlier one.
+func uniqueUnit(prefix string) string {
+	return fmt.Sprintf("%s-%d", prefix, time.Now().UnixNano())
+}
+
+type capped struct {
+	bytes.Buffer
+	cut bool
+}
+
+func (c *capped) Write(p []byte) (int, error) {
+	if room := mostOutput - c.Len(); room < len(p) {
+		if room > 0 {
+			c.Buffer.Write(p[:room])
+		}
+		c.cut = true
+		return len(p), nil
+	}
+	return c.Buffer.Write(p)
+}
+
+// processesOf are the pids of this uid's processes whose command name is comm, oldest first.
+func processesOf(comm string) []int {
+	entries, err := os.ReadDir(procRoot)
+	if err != nil {
+		return nil
+	}
+	uid := os.Getuid()
+	var pids []int
+	for _, e := range entries {
+		pid, err := strconv.Atoi(e.Name())
+		if err != nil {
+			continue
+		}
+		dir := filepath.Join(procRoot, e.Name())
+		if owner, ok := ownerOf(dir); !ok || owner != uid {
+			continue
+		}
+		if readTrimmed(filepath.Join(dir, "comm")) == comm {
+			pids = append(pids, pid)
+		}
+	}
+	sort.Ints(pids)
+	return pids
+}
+
+// signalAll sends sig to every process of this uid named comm, and answers the pids it reached.
+func signalAll(comm string, sig syscall.Signal) []int {
+	var reached []int
+	for _, pid := range processesOf(comm) {
+		if syscall.Kill(pid, sig) == nil {
+			reached = append(reached, pid)
+		}
+	}
+	return reached
+}

modules/clipmenu/cmd/clipmenu-tools/session_test.go

@@ -0,0 +1,174 @@
+package main
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+)
+
+// fakeMachine points the session finder at a temporary /proc, /run/user and X socket directory, with
+// none of the test process's own session variables, and gives back the root.
+func fakeMachine(t *testing.T) string {
+	t.Helper()
+	root := t.TempDir()
+	procRoot, runUserDir, x11Sockets = filepath.Join(root, "proc"), filepath.Join(root, "run-user"), filepath.Join(root, "x11")
+	for _, d := range []string{procRoot, runUserDir, x11Sockets} {
+		if err := os.MkdirAll(d, 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	for _, k := range sessionKeys {
+		t.Setenv(k, "")
+	}
+	t.Setenv("MESH_OPERATOR_HOME", filepath.Join(root, "home"))
+	t.Cleanup(func() { procRoot, runUserDir, x11Sockets = "/proc", "/run/user", "/tmp/.X11-unix" })
+	return root
+}
+
+func fakeProcess(t *testing.T, pid int, comm string, env ...string) {
+	t.Helper()
+	dir := filepath.Join(procRoot, strconv.Itoa(pid))
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "comm"), []byte(comm+"\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "environ"), []byte(strings.Join(env, "\x00")+"\x00"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestTheSessionIsReadFromTheWindowManagerBeforeAnyOtherProcess(t *testing.T) {
+	fakeMachine(t)
+	fakeProcess(t, 900, "xterm", "DISPLAY=:9", "XAUTHORITY=/elsewhere")
+	fakeProcess(t, 100, "i3", "DISPLAY=:1", "XAUTHORITY=/home/op/.Xauthority",
+		"DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus", "XDG_SESSION_ID=3", "SECRET_TOKEN=never-copied")
+	fakeProcess(t, 50, "bash", "PATH=/usr/bin")
+	s, err := findSession()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if s.Display != ":1" || s.XAuthority != "/home/op/.Xauthority" || s.SessionID != "3" || !strings.Contains(s.From, "i3 (pid 100)") {
+		t.Fatalf("the window manager's environment: %+v", s)
+	}
+	for _, kv := range s.Env() {
+		if strings.HasPrefix(kv, "SECRET_TOKEN=") {
+			t.Fatal("a variable of the session process that is not a session variable was handed on")
+		}
+	}
+}
+
+func TestAnyProcessCarryingADisplayServesWhenTheWindowManagerIsNotFound(t *testing.T) {
+	fakeMachine(t)
+	fakeProcess(t, 10, "firefox", "DISPLAY=:0")
+	fakeProcess(t, 20, "firefox", "DISPLAY=:2")
+	s, err := findSession()
+	if err != nil || s.Display != ":2" {
+		t.Fatalf("the newest of two equals: %+v, %v", s, err)
+	}
+}
+
+func TestNoSessionIsAClearAnswerNotAGuess(t *testing.T) {
+	fakeMachine(t)
+	fakeProcess(t, 10, "sshd", "PATH=/usr/bin")
+	_, err := findSession()
+	if !errors.Is(err, ErrNoSession) || !strings.Contains(err.Error(), "logged in to the desktop") {
+		t.Fatalf("no session: %v", err)
+	}
+}
+
+func TestOneXSocketAndTheAccountsAuthorityFileAreASession(t *testing.T) {
+	root := fakeMachine(t)
+	if err := os.WriteFile(filepath.Join(x11Sockets, "X0"), nil, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Join(root, "home"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(root, "home", ".Xauthority"), nil, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	s, err := findSession()
+	if err != nil || s.Display != ":0" || !strings.HasSuffix(s.XAuthority, "/home/.Xauthority") {
+		t.Fatalf("socket and authority: %+v, %v", s, err)
+	}
+}
+
+func TestTheBusIsTheAccountsRuntimeDirectoryWhenNoProcessNamesIt(t *testing.T) {
+	fakeMachine(t)
+	runtime := filepath.Join(runUserDir, strconv.Itoa(os.Getuid()))
+	if _, err := findBus(); !errors.Is(err, ErrNoBus) {
+		t.Fatalf("no runtime directory is no bus: %v", err)
+	}
+	if err := os.MkdirAll(runtime, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(runtime, "bus"), nil, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	s, err := findBus()
+	if err != nil || s.Bus != "unix:path="+filepath.Join(runtime, "bus") || s.RuntimeDir != runtime {
+		t.Fatalf("bus: %+v, %v", s, err)
+	}
+	env := strings.Join(s.Env(), "\n")
+	if !strings.Contains(env, "XDG_RUNTIME_DIR="+runtime) || !strings.Contains(env, "DBUS_SESSION_BUS_ADDRESS=unix:path=") {
+		t.Fatalf("the bus is handed on: %s", env)
+	}
+}
+
+func TestACommandIsBoundedAndANonZeroExitIsAResult(t *testing.T) {
+	fakeMachine(t)
+	s := Session{}
+	r, err := s.run(5*time.Second, "in", "sh", "-c", "cat; echo err >&2; exit 3")
+	if err != nil || r.Stdout != "in" || r.Code != 3 || strings.TrimSpace(r.Stderr) != "err" {
+		t.Fatalf("result: %+v, %v", r, err)
+	}
+	start := time.Now()
+	if _, err := s.run(200*time.Millisecond, "", "sh", "-c", "sleep 30 & sleep 30"); err == nil || time.Since(start) > 5*time.Second {
+		t.Fatalf("a command past its time is ended with what it started: %v after %s", err, time.Since(start))
+	}
+	if _, err := s.run(time.Second, "", "no-such-program-here"); err == nil || !strings.Contains(err.Error(), "not installed") {
+		t.Fatalf("a missing program: %v", err)
+	}
+}
+
+func TestDetachAsksTheAccountsServiceManagerWithTheSessionsDisplay(t *testing.T) {
+	fakeMachine(t)
+	bin := fakeBinaries(t, map[string]string{
+		"systemctl":   `echo "systemctl $*" >> "$LOG"`,
+		"systemd-run": `echo "systemd-run $*" >> "$LOG"`,
+	})
+	log := filepath.Join(bin, "log")
+	t.Setenv("LOG", log)
+	s := Session{Display: ":1", XAuthority: "/x", RuntimeDir: "/run/user/1"}
+	if err := s.detach("picom-session", "picom", "--config", "/c"); err != nil {
+		t.Fatal(err)
+	}
+	got, _ := os.ReadFile(log)
+	want := "systemctl --user stop picom-session.service\n" +
+		"systemd-run --user --collect --quiet --unit=picom-session --setenv=DISPLAY=:1 --setenv=XAUTHORITY=/x -- picom --config /c\n"
+	if string(got) != want {
+		t.Fatalf("detach ran:\n%s\nwant:\n%s", got, want)
+	}
+	if err := (Session{}).detach("x", "y"); !errors.Is(err, ErrNoBus) {
+		t.Fatalf("no runtime directory: %v", err)
+	}
+}
+
+// fakeBinaries puts shell scripts named for programs first on PATH, and answers their directory.
+func fakeBinaries(t *testing.T, scripts map[string]string) string {
+	t.Helper()
+	dir := t.TempDir()
+	for name, body := range scripts {
+		if err := os.WriteFile(filepath.Join(dir, name), []byte("#!/bin/sh\n"+body+"\n"), 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	t.Setenv("PATH", dir+string(os.PathListSeparator)+os.Getenv("PATH"))
+	return dir
+}

modules/clipmenu/files/i3/50-clipmenu.conf

@@ -0,0 +1,5 @@
+# The clipboard's history key (module clipmenu, novox/hq ADR 0208). Owned by the mesh: replaced at
+# every push. clipmenu shows the history through `dmenu`, the node's dmenu-compatible command, which
+# the holder of node-launcher answers (rofi on the workstations); the chosen entry is put back on the
+# clipboard.
+bindsym $mod+period exec --no-startup-id clipmenu -p Clipboard

modules/clipmenu/go.mod

@@ -0,0 +1,5 @@
+module clipmenu
+
+go 1.22
+
+require git.novox.be/novox/mesh-sdk/go v0.1.7

modules/clipmenu/go.sum

@@ -0,0 +1,2 @@
+git.novox.be/novox/mesh-sdk/go v0.1.7 h1:C0sTQmtTiyYH7bnqZb7PusXnqA37gKuT7Nqjn9gG47w=
+git.novox.be/novox/mesh-sdk/go v0.1.7/go.mod h1:GFuZUElBZ9A++mxgIKo97aXXo+kV0uJ/UkbhQPPIbrY=

modules/clipmenu/module.json

@@ -0,0 +1,75 @@
+{
+  "module": "clipmenu",
+  "version": "1",
+  "capabilities": [
+    "package-manager"
+  ],
+  "requires": [
+    "x11-display"
+  ],
+  "claims": [
+    {
+      "name": "node-clipboard",
+      "scope": "node",
+      "serves": [
+        "history",
+        "copy"
+      ]
+    }
+  ],
+  "tools": [
+    "clipmenu_paste",
+    "clipmenu_clear",
+    "clipmenu_delete"
+  ],
+  "environment": {
+    "variables": {
+      "CM_SELECTIONS": "clipboard",
+      "CM_MAX_CLIPS": "500",
+      "CM_HISTLENGTH": "15"
+    }
+  },
+  "shell": [
+    {
+      "for": "xinitrc",
+      "slot": "normal",
+      "code": "# The clipboard's history (module clipmenu, novox/hq ADR 0208): clipmenud collects every copy from\n# here on, once per session. It keeps the history in the account's runtime directory, so a reboot\n# forgets it, and with it every password that was ever copied.\nclipmenud &\n"
+    }
+  ],
+  "resources": [
+    {
+      "id": "package",
+      "type": "package",
+      "package": "clipmenu"
+    },
+    {
+      "id": "greenclip",
+      "type": "package",
+      "package": "rofi-greenclip",
+      "absent": true
+    },
+    {
+      "id": "i3-bindings",
+      "type": "file",
+      "path": "${machine:account-home}/.config/i3/config.d/50-clipmenu.conf",
+      "owner": "${machine:account}",
+      "mode": "0644",
+      "content": "# The clipboard's history key (module clipmenu, novox/hq ADR 0208). Owned by the mesh: replaced at\n# every push. clipmenu shows the history through `dmenu`, the node's dmenu-compatible command, which\n# the holder of node-launcher answers (rofi on the workstations); the chosen entry is put back on the\n# clipboard.\nbindsym $mod+period exec --no-startup-id clipmenu -p Clipboard\n"
+    }
+  ],
+  "build": {
+    "artifacts": [
+      {
+        "name": "tools",
+        "kind": "bundle",
+        "language": "go",
+        "system": "arch",
+        "from": "cmd/clipmenu-tools",
+        "binary": "clipmenu-tools",
+        "loads": [
+          "clipmenu-tools"
+        ]
+      }
+    ]
+  }
+}

modules/dunst/README.md

@@ -0,0 +1,60 @@
+# dunst
+
+The notifier as a module (novox/hq ADR 0208, research 026/05).
+
+- Installs `dunst`, and `libnotify` for `notify-send`, the client every program and these tools use.
+- Claims the mesh's `node-notifier` seat and serves its verbs `send` and `history`.
+- Owns `~/.config/dunst/dunstrc` and the directory `~/.config/dunst/dunstrc.d/`. Another module's
+  rule is that module's own file in the directory (ADR 0208 §4). dunst reads the directory after
+  `dunstrc`, so a drop-in outranks it.
+- **Starts nothing.** The package registers dunst with D-Bus, which starts it on the first
+  notification, inside the account's service manager. There is no autostart line, no unit and no
+  session-start contribution.
+- **Requires no display of its own.** dunst speaks both X11 and Wayland and picks the one the session
+  has, so it serves an X session and a later sway one alike.
+
+## Tools
+
+Every tool goes over the account's session bus. None needs the screen, and each answers clearly when
+the account is not logged in.
+
+| tool | does |
+|---|---|
+| `node-notifier.send` | a notification: title, body, urgency, sender, icon, how long; answers its id |
+| `node-notifier.history` | what was shown, newest first, with how long ago |
+| `dunst_pause` / `dunst_resume` | do not disturb: notifications are held back, not lost |
+| `dunst_close_all` | clear the screen; the history keeps them |
+| `dunst_rules` | the rules the running notifier holds, and the files they come from |
+| `dunst_count` | shown, waiting, in history, and whether paused |
+
+## What it chose, and what it improves
+
+The workstations' files differed: one had the notifications bottom-right, 15 % transparent and with
+rounded corners; the other top-right, opaque and square. This module takes the second, because the
+rest of the desktop is square and opaque, and the top-right corner sits under the bar that shows the
+count. The file keeps only the settings that differ from dunst's defaults.
+
+- **The context menu works.** It called `/usr/bin/dmenu`, installed on neither machine. It now calls
+  `dmenu`, the seat command of whichever module holds `node-launcher` (`rofi` on the workstations).
+- **The face is the interface one,** Inter (research 026/04), instead of a monospace Nerd font.
+- `icon_path`, which named two directories of an icon theme that is not installed, is gone. The icon
+  theme is looked up recursively.
+
+## What it leaves as found
+
+- `~/.config/dunst/dunstrc.d/50-slack.conf`, the Slack rule. It becomes the Slack module's own drop-in
+  when there is one, and until then it is the operator's file in a directory this module owns.
+
+## Migration (ADR 0182)
+
+- The first push keeps the found `dunstrc` once, then writes the module's.
+- **The desktop runs two notification daemons** because its session began before the session bus
+  fix (research 026/01). That ends at the next login, and nothing here starts a second one.
+  `dunst_count` after logging in again shows the one daemon's counts.
+
+## Blockers
+
+- `node-notifier` is ADR 0208's seat. Until the controller knows it, `mctl` reads the claim as
+  unknown.
+- `dunst_rules` and the counts ask the running notifier. When none runs, the bus starts one, which
+  needs a session to draw on.

modules/dunst/cmd/dunst-tools/args.go

@@ -0,0 +1,97 @@
+// Reading a tool's arguments: JSON numbers arrive as float64, and a missing argument is its default.
+// The same in every desktop module that carries it.
+package main
+
+import (
+	"fmt"
+	"math"
+	"strings"
+	"time"
+)
+
+// text is a string argument, trimmed; required says an empty one is refused.
+func text(args map[string]any, key string, required bool) (string, error) {
+	v, present := args[key]
+	if !present || v == nil {
+		if required {
+			return "", fmt.Errorf("%s is required", key)
+		}
+		return "", nil
+	}
+	s, ok := v.(string)
+	if !ok {
+		return "", fmt.Errorf("%s is a string, not %T", key, v)
+	}
+	s = strings.TrimSpace(s)
+	if s == "" && required {
+		return "", fmt.Errorf("%s is required", key)
+	}
+	return s, nil
+}
+
+// whole is a whole-number argument within [least, most], or def when absent.
+func whole(args map[string]any, key string, def, least, most int) (int, error) {
+	v, present := args[key]
+	if !present || v == nil {
+		return def, nil
+	}
+	f, ok := v.(float64)
+	if !ok {
+		if i, isInt := v.(int); isInt {
+			f = float64(i)
+		} else {
+			return 0, fmt.Errorf("%s is a number, not %T", key, v)
+		}
+	}
+	if f != math.Trunc(f) {
+		return 0, fmt.Errorf("%s is a whole number, not %v", key, f)
+	}
+	n := int(f)
+	if n < least || n > most {
+		return 0, fmt.Errorf("%s is %d; it is between %d and %d", key, n, least, most)
+	}
+	return n, nil
+}
+
+// flag is a boolean argument, or def when absent.
+func flag(args map[string]any, key string, def bool) (bool, error) {
+	v, present := args[key]
+	if !present || v == nil {
+		return def, nil
+	}
+	b, ok := v.(bool)
+	if !ok {
+		return false, fmt.Errorf("%s is true or false, not %T", key, v)
+	}
+	return b, nil
+}
+
+// texts is a list-of-strings argument.
+func texts(args map[string]any, key string) ([]string, error) {
+	v, present := args[key]
+	if !present || v == nil {
+		return nil, nil
+	}
+	list, ok := v.([]any)
+	if !ok {
+		if ss, isStrings := v.([]string); isStrings {
+			return ss, nil
+		}
+		return nil, fmt.Errorf("%s is a list of strings, not %T", key, v)
+	}
+	out := make([]string, 0, len(list))
+	for i, item := range list {
+		s, ok := item.(string)
+		if !ok {
+			return nil, fmt.Errorf("%s[%d] is a string, not %T", key, i, item)
+		}
+		out = append(out, s)
+	}
+	return out, nil
+}
+
+// seconds is a timeout argument in seconds, defaulted and bounded below the runtime's call limit.
+func seconds(args map[string]any, key string, def, most int) (time.Duration, error) {
+	n, err := whole(args, key, def, 1, most)
+	return time.Duration(n) * time.Second, err
+}

modules/dunst/cmd/dunst-tools/dunst.go

@@ -0,0 +1,355 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"syscall"
+	"time"
+	"unsafe"
+)
+
+var urgencies = []string{"low", "normal", "critical"}
+
+const busTimeout = 10 * time.Second
+
+// Notification is what node-notifier.send shows.
+type Notification struct {
+	Summary   string
+	Body      string
+	Urgency   string
+	AppName   string
+	Icon      string
+	ExpireMS  int
+	Category  string
+	ReplaceID int
+}
+
+func notificationOf(args map[string]any) (Notification, error) {
+	var n Notification
+	var err error
+	if n.Summary, err = text(args, "summary", true); err != nil {
+		return n, err
+	}
+	if n.Body, err = text(args, "body", false); err != nil {
+		return n, err
+	}
+	if n.Urgency, err = text(args, "urgency", false); err != nil {
+		return n, err
+	}
+	if n.Urgency == "" {
+		n.Urgency = "normal"
+	}
+	known := false
+	for _, u := range urgencies {
+		known = known || u == n.Urgency
+	}
+	if !known {
+		return n, fmt.Errorf("urgency %q is low, normal or critical", n.Urgency)
+	}
+	if n.AppName, err = text(args, "app_name", false); err != nil {
+		return n, err
+	}
+	if n.AppName == "" {
+		n.AppName = "mesh"
+	}
+	if n.Icon, err = text(args, "icon", false); err != nil {
+		return n, err
+	}
+	if n.ExpireMS, err = whole(args, "expire_ms", -1, 0, 24*3600*1000); err != nil {
+		return n, err
+	}
+	if n.Category, err = text(args, "category", false); err != nil {
+		return n, err
+	}
+	n.ReplaceID, err = whole(args, "replace_id", 0, 0, 1<<31-1)
+	return n, err
+}
+
+// SendResult is what node-notifier.send answers.
+type SendResult struct {
+	ID int `json:"id"`
+}
+
+// Send shows a notification through the desktop's notification service, whichever runs it.
+func Send(n Notification) (SendResult, error) {
+	s, err := findBus()
+	if err != nil {
+		return SendResult{}, err
+	}
+	args := []string{"--print-id", "--urgency=" + n.Urgency, "--app-name=" + n.AppName}
+	if n.Icon != "" {
+		args = append(args, "--icon="+n.Icon)
+	}
+	if n.ExpireMS >= 0 {
+		args = append(args, "--expire-time="+strconv.Itoa(n.ExpireMS))
+	}
+	if n.Category != "" {
+		args = append(args, "--category="+n.Category)
+	}
+	if n.ReplaceID > 0 {
+		args = append(args, "--replace-id="+strconv.Itoa(n.ReplaceID))
+	}
+	// "--" so a title that starts with a dash is a title.
+	args = append(args, "--", n.Summary)
+	if n.Body != "" {
+		args = append(args, n.Body)
+	}
+	r, err := s.run(busTimeout, "", "notify-send", args...)
+	if err != nil {
+		return SendResult{}, err
+	}
+	if r.Code != 0 {
+		return SendResult{}, fmt.Errorf("notify-send: %s", strings.TrimSpace(r.Stderr))
+	}
+	id, err := strconv.Atoi(strings.TrimSpace(r.Stdout))
+	if err != nil {
+		return SendResult{}, fmt.Errorf("notify-send answered no id: %q", r.Stdout)
+	}
+	return SendResult{ID: id}, nil
+}
+
+// dunstctl runs one dunstctl command over the session bus and answers what it printed.
+func dunstctl(args ...string) (string, error) {
+	s, err := findBus()
+	if err != nil {
+		return "", err
+	}
+	r, err := s.run(busTimeout, "", "dunstctl", args...)
+	if err != nil {
+		return "", err
+	}
+	if r.Code != 0 {
+		return "", fmt.Errorf("dunstctl %s: %s", strings.Join(args, " "), strings.TrimSpace(r.Stderr+r.Stdout))
+	}
+	return r.Stdout, nil
+}
+
+// variantMaps reads busctl's JSON form of an array of dictionaries (aa{sv}), which is how dunstctl
+// answers history and rules, into plain maps.
+func variantMaps(raw string) ([]map[string]any, error) {
+	var doc struct {
+		Type string `json:"type"`
+		Data [][]map[string]struct {
+			Data any `json:"data"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal([]byte(raw), &doc); err != nil {
+		return nil, fmt.Errorf("dunstctl's answer is not the bus's JSON: %w", err)
+	}
+	if doc.Type != "aa{sv}" {
+		return nil, fmt.Errorf("dunstctl answered %s, not aa{sv}", doc.Type)
+	}
+	out := []map[string]any{}
+	for _, group := range doc.Data {
+		for _, entry := range group {
+			m := map[string]any{}
+			for k, v := range entry {
+				m[k] = v.Data
+			}
+			out = append(out, m)
+		}
+	}
+	return out, nil
+}
+
+// Shown is one notification in the history.
+type Shown struct {
+	ID         int    `json:"id"`
+	AppName    string `json:"app_name"`
+	Summary    string `json:"summary"`
+	Body       string `json:"body,omitempty"`
+	Urgency    string `json:"urgency"`
+	Category   string `json:"category,omitempty"`
+	AgeSeconds int64  `json:"age_seconds"`
+}
+
+// HistoryResult is what node-notifier.history answers.
+type HistoryResult struct {
+	Total         int     `json:"total"`
+	Notifications []Shown `json:"notifications"`
+}
+
+// History is dunst's history, newest first.
+func History(limit int) (HistoryResult, error) {
+	raw, err := dunstctl("history")
+	if err != nil {
+		return HistoryResult{}, err
+	}
+	return parseHistory(raw, monotonicMicros(), limit)
+}
+
+func parseHistory(raw string, nowMicros int64, limit int) (HistoryResult, error) {
+	entries, err := variantMaps(raw)
+	if err != nil {
+		return HistoryResult{}, err
+	}
+	out := HistoryResult{Total: len(entries), Notifications: []Shown{}}
+	type stamped struct {
+		Shown
+		at int64
+	}
+	var all []stamped
+	for _, e := range entries {
+		at := number(e["timestamp"])
+		all = append(all, stamped{Shown{
+			ID: int(number(e["id"])), AppName: str(e["appname"]), Summary: str(e["summary"]), Body: str(e["body"]),
+			Urgency: strings.ToLower(str(e["urgency"])), Category: str(e["category"]),
+			AgeSeconds: max(0, (nowMicros-at)/1_000_000),
+		}, at})
+	}
+	sort.SliceStable(all, func(i, j int) bool { return all[i].at > all[j].at })
+	for i, s := range all {
+		if i == limit {
+			break
+		}
+		out.Notifications = append(out.Notifications, s.Shown)
+	}
+	return out, nil
+}
+
+func number(v any) int64 {
+	switch n := v.(type) {
+	case float64:
+		return int64(n)
+	case json.Number:
+		i, _ := n.Int64()
+		return i
+	}
+	return 0
+}
+
+func str(v any) string {
+	s, _ := v.(string)
+	return s
+}
+
+// monotonicMicros is the clock dunst stamps its notifications with (CLOCK_MONOTONIC, microseconds).
+func monotonicMicros() int64 {
+	var ts syscall.Timespec
+	const clockMonotonic = 1
+	if _, _, errno := syscall.Syscall(syscall.SYS_CLOCK_GETTIME, clockMonotonic, uintptr(unsafe.Pointer(&ts)), 0); errno != 0 {
+		return 0
+	}
+	return ts.Sec*1_000_000 + ts.Nsec/1000
+}
+
+// PauseResult is what dunst_pause and dunst_resume answer.
+type PauseResult struct {
+	Paused bool   `json:"paused"`
+	Note   string `json:"note"`
+}
+
+// SetPaused turns do-not-disturb on or off.
+func SetPaused(on bool) (PauseResult, error) {
+	if _, err := dunstctl("set-paused", strconv.FormatBool(on)); err != nil {
+		return PauseResult{}, err
+	}
+	out, err := dunstctl("is-paused")
+	if err != nil {
+		return PauseResult{}, err
+	}
+	paused := strings.TrimSpace(out) == "true"
+	note := "notifications are shown"
+	if paused {
+		note = "notifications are held back until dunst_resume; the next login starts unpaused"
+	}
+	return PauseResult{Paused: paused, Note: note}, nil
+}
+
+// CloseAll closes what is on screen.
+func CloseAll() (CountResult, error) {
+	if _, err := dunstctl("close-all"); err != nil {
+		return CountResult{}, err
+	}
+	return Count()
+}
+
+// CountResult is what dunst_count answers.
+type CountResult struct {
+	Displayed int  `json:"displayed"`
+	Waiting   int  `json:"waiting"`
+	History   int  `json:"history"`
+	Paused    bool `json:"paused"`
+}
+
+// Count is how many notifications are where.
+func Count() (CountResult, error) {
+	var c CountResult
+	for _, part := range []struct {
+		which string
+		into  *int
+	}{{"displayed", &c.Displayed}, {"waiting", &c.Waiting}, {"history", &c.History}} {
+		out, err := dunstctl("count", part.which)
+		if err != nil {
+			return c, err
+		}
+		n, err := strconv.Atoi(strings.TrimSpace(out))
+		if err != nil {
+			return c, fmt.Errorf("dunstctl count %s answered %q", part.which, out)
+		}
+		*part.into = n
+	}
+	out, err := dunstctl("is-paused")
+	if err != nil {
+		return c, err
+	}
+	c.Paused = strings.TrimSpace(out) == "true"
+	return c, nil
+}
+
+// Rule is one notifier rule in force.
+type Rule struct {
+	Name    string         `json:"name"`
+	Enabled bool           `json:"enabled"`
+	Sets    map[string]any `json:"sets"`
+}
+
+// RulesResult is what dunst_rules answers.
+type RulesResult struct {
+	Files []string `json:"files"`
+	Rules []Rule   `json:"rules"`
+}
+
+// Rules are the rules the running notifier holds, and the files it reads them from.
+func Rules() (RulesResult, error) {
+	raw, err := dunstctl("rules", "--json")
+	if err != nil {
+		return RulesResult{}, err
+	}
+	return parseRules(raw, configFiles(filepath.Join(operatorHome(), ".config", "dunst")))
+}
+
+func parseRules(raw string, files []string) (RulesResult, error) {
+	entries, err := variantMaps(raw)
+	if err != nil {
+		return RulesResult{}, err
+	}
+	out := RulesResult{Files: files, Rules: []Rule{}}
+	for _, e := range entries {
+		r := Rule{Name: str(e["name"]), Enabled: e["enabled"] == true, Sets: map[string]any{}}
+		for k, v := range e {
+			if k != "name" && k != "enabled" {
+				r.Sets[k] = v
+			}
+		}
+		out.Rules = append(out.Rules, r)
+	}
+	sort.SliceStable(out.Rules, func(i, j int) bool { return out.Rules[i].Name < out.Rules[j].Name })
+	return out, nil
+}
+
+// configFiles are dunstrc and its drop-ins in the order dunst reads them.
+func configFiles(dir string) []string {
+	files := []string{}
+	if _, err := os.Stat(filepath.Join(dir, "dunstrc")); err == nil {
+		files = append(files, filepath.Join(dir, "dunstrc"))
+	}
+	dropins, _ := filepath.Glob(filepath.Join(dir, "dunstrc.d", "*.conf"))
+	sort.Strings(dropins)
+	return append(files, dropins...)
+}

modules/dunst/cmd/dunst-tools/dunst_test.go

@@ -0,0 +1,160 @@
+package main
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strconv"
+	"strings"
+	"testing"
+)
+
+// withBus gives the fake machine the account's runtime directory and bus socket.
+func withBus(t *testing.T) string {
+	t.Helper()
+	root := fakeMachine(t)
+	runtime := filepath.Join(runUserDir, strconv.Itoa(os.Getuid()))
+	if err := os.MkdirAll(runtime, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(runtime, "bus"), nil, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	return root
+}
+
+// A history as dunstctl answers it (busctl's JSON), two entries out of order.
+const history = `{"type":"aa{sv}","data":[[
+ {"body":{"type":"s","data":"the build is green"},"summary":{"type":"s","data":"CI"},"appname":{"type":"s","data":"mesh"},
+  "category":{"type":"s","data":""},"id":{"type":"i","data":7},"timestamp":{"type":"x","data":100000000},"urgency":{"type":"s","data":"NORMAL"}},
+ {"body":{"type":"s","data":""},"summary":{"type":"s","data":"Battery low"},"appname":{"type":"s","data":"upower"},
+  "category":{"type":"s","data":"device"},"id":{"type":"i","data":9},"timestamp":{"type":"x","data":160000000},"urgency":{"type":"s","data":"CRITICAL"}}
+]]}`
+
+func TestTheHistoryIsNewestFirstWithAgesFromDunstsOwnClock(t *testing.T) {
+	got, err := parseHistory(history, 200_000_000, 20)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := []Shown{
+		{ID: 9, AppName: "upower", Summary: "Battery low", Urgency: "critical", Category: "device", AgeSeconds: 40},
+		{ID: 7, AppName: "mesh", Summary: "CI", Body: "the build is green", Urgency: "normal", AgeSeconds: 100},
+	}
+	if got.Total != 2 || !reflect.DeepEqual(got.Notifications, want) {
+		t.Fatalf("%+v", got)
+	}
+	if got, _ := parseHistory(history, 200_000_000, 1); len(got.Notifications) != 1 || got.Total != 2 {
+		t.Fatalf("limited: %+v", got)
+	}
+	if _, err := parseHistory(`{"type":"as","data":[]}`, 0, 1); err == nil {
+		t.Fatal("an answer of another type was accepted")
+	}
+	if monotonicMicros() <= 0 {
+		t.Fatal("the monotonic clock")
+	}
+}
+
+func TestSendAsksNotifySendOverTheAccountsBusAndAnswersTheId(t *testing.T) {
+	withBus(t)
+	bin := fakeBinaries(t, map[string]string{"notify-send": `for a in "$@"; do printf '[%s]' "$a"; done > "$LOG"; echo >> "$LOG"; echo "bus=$DBUS_SESSION_BUS_ADDRESS" >> "$LOG"; echo 42`})
+	t.Setenv("LOG", filepath.Join(bin, "log"))
+	n, err := notificationOf(map[string]any{"summary": "-dash title", "body": "hello", "urgency": "critical", "expire_ms": float64(0)})
+	if err != nil {
+		t.Fatal(err)
+	}
+	got, err := Send(n)
+	if err != nil || got.ID != 42 {
+		t.Fatalf("%+v, %v", got, err)
+	}
+	asked, _ := os.ReadFile(filepath.Join(bin, "log"))
+	want := "[--print-id][--urgency=critical][--app-name=mesh][--expire-time=0][--][-dash title][hello]\nbus=unix:path=" +
+		filepath.Join(runUserDir, strconv.Itoa(os.Getuid()), "bus") + "\n"
+	if string(asked) != want {
+		t.Fatalf("notify-send was asked:\n%s\nwant:\n%s", asked, want)
+	}
+}
+
+func TestANotificationIsRefusedForWhatItCannotBe(t *testing.T) {
+	for _, bad := range []map[string]any{{}, {"summary": " "}, {"summary": "x", "urgency": "urgent"}, {"summary": "x", "expire_ms": float64(-5)}} {
+		if _, err := notificationOf(bad); err == nil {
+			t.Errorf("accepted %v", bad)
+		}
+	}
+	n, _ := notificationOf(map[string]any{"summary": "x"})
+	if n.Urgency != "normal" || n.AppName != "mesh" || n.ExpireMS != -1 {
+		t.Fatalf("defaults: %+v", n)
+	}
+}
+
+func TestWithoutABusTheToolsSaySo(t *testing.T) {
+	fakeMachine(t)
+	if _, err := Send(Notification{Summary: "x"}); !errors.Is(err, ErrNoBus) {
+		t.Fatal(err)
+	}
+	if _, err := Count(); !errors.Is(err, ErrNoBus) {
+		t.Fatal(err)
+	}
+}
+
+func TestCountPauseAndCloseAllAreDunstctlsAnswers(t *testing.T) {
+	withBus(t)
+	bin := fakeBinaries(t, map[string]string{"dunstctl": `echo "$*" >> "$LOG"
+case "$*" in
+  "count displayed") echo 1 ;;
+  "count waiting") echo 0 ;;
+  "count history") echo 12 ;;
+  is-paused) cat "$STATE" 2>/dev/null || echo false ;;
+  "set-paused true") echo true > "$STATE" ;;
+  "set-paused false") echo false > "$STATE" ;;
+esac`})
+	t.Setenv("LOG", filepath.Join(bin, "log"))
+	t.Setenv("STATE", filepath.Join(bin, "paused"))
+	c, err := Count()
+	if err != nil || c != (CountResult{Displayed: 1, History: 12}) {
+		t.Fatalf("%+v, %v", c, err)
+	}
+	p, err := SetPaused(true)
+	if err != nil || !p.Paused || !strings.Contains(p.Note, "held back") {
+		t.Fatalf("%+v, %v", p, err)
+	}
+	if c, _ := CloseAll(); !c.Paused {
+		t.Fatalf("close-all answers the counts: %+v", c)
+	}
+	if p, _ := SetPaused(false); p.Paused {
+		t.Fatalf("resumed: %+v", p)
+	}
+	log, _ := os.ReadFile(filepath.Join(bin, "log"))
+	if !strings.Contains(string(log), "close-all\n") {
+		t.Fatalf("dunstctl was asked:\n%s", log)
+	}
+}
+
+func TestRulesAreTheRunningNotifiersWithTheFilesTheyComeFrom(t *testing.T) {
+	root := t.TempDir()
+	for _, f := range []string{"dunstrc", "dunstrc.d/50-slack.conf", "dunstrc.d/10-mail.conf", "dunstrc.d/notes.txt"} {
+		if err := os.MkdirAll(filepath.Dir(filepath.Join(root, f)), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(root, f), nil, 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	raw := `{"type":"aa{sv}","data":[[{"enabled":{"type":"b","data":true},"appname":{"type":"s","data":"Slack"},
+	  "fc":{"type":"s","data":"#6715ebff"},"name":{"type":"s","data":"slack"},"timeout":{"type":"x","data":10000000}}]]}`
+	got, err := parseRules(raw, configFiles(root))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got.Rules) != 1 || got.Rules[0].Name != "slack" || !got.Rules[0].Enabled || got.Rules[0].Sets["appname"] != "Slack" {
+		t.Fatalf("%+v", got)
+	}
+	var names []string
+	for _, f := range got.Files {
+		rel, _ := filepath.Rel(root, f)
+		names = append(names, rel)
+	}
+	if !reflect.DeepEqual(names, []string{"dunstrc", "dunstrc.d/10-mail.conf", "dunstrc.d/50-slack.conf"}) {
+		t.Fatalf("files: %v", names)
+	}
+}

modules/dunst/cmd/dunst-tools/main.go

@@ -0,0 +1,91 @@
+// dunst's Go tools bundle (novox/hq ADR 0188, ADR 0193, ADR 0208): its implementation of
+// node-notifier's verbs `send` and `history`, and its own tools, served by the node's runtime as the
+// operator account. Everything here goes over the account's session bus; none of it needs the screen.
+package main
+
+import (
+	"fmt"
+	"os"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+func main() {
+	if err := stdio.Serve("", tools()); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+func tools() []stdio.Tool {
+	return []stdio.Tool{
+		{
+			Name: "node-notifier.send",
+			Description: "Show a notification on the operator's desktop: a title, a body, an urgency (low, " +
+				"normal, critical), and optionally the sending application's name, an icon and how long it stays. " +
+				"Answers the notification's id.",
+			Input: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"summary":    map[string]any{"type": "string", "description": "the title"},
+					"body":       map[string]any{"type": "string", "description": "the text; simple markup (<b>, <i>, <u>, <a href>) is shown"},
+					"urgency":    map[string]any{"type": "string", "enum": urgencies, "description": "default normal"},
+					"app_name":   map[string]any{"type": "string", "description": "who it is from (default: mesh); a notifier rule can match it"},
+					"icon":       map[string]any{"type": "string", "description": "an icon name from the icon theme, or a file"},
+					"expire_ms":  map[string]any{"type": "integer", "description": "how long it stays; 0 until dismissed (default: the urgency's own)"},
+					"category":   map[string]any{"type": "string", "description": "a notification category, e.g. email.arrived"},
+					"replace_id": map[string]any{"type": "integer", "description": "replace the notification with this id instead of adding one"},
+				},
+				"required": []string{"summary"},
+			},
+			Run: func(args map[string]any) (any, error) {
+				n, err := notificationOf(args)
+				if err != nil {
+					return nil, err
+				}
+				return Send(n)
+			},
+		},
+		{
+			Name: "node-notifier.history",
+			Description: "The notifications the operator was shown, newest first: id, application, title, " +
+				"body, urgency and how long ago.",
+			Input: map[string]any{
+				"limit": map[string]any{"type": "integer", "description": "at most this many (default 20, at most 200)"},
+			},
+			Run: func(args map[string]any) (any, error) {
+				limit, err := whole(args, "limit", 20, 1, 200)
+				if err != nil {
+					return nil, err
+				}
+				return History(limit)
+			},
+		},
+		{
+			Name:        "dunst_pause",
+			Description: "Do not disturb: hold every new notification back until resumed. They are shown then, not lost.",
+			Run:         func(map[string]any) (any, error) { return SetPaused(true) },
+		},
+		{
+			Name:        "dunst_resume",
+			Description: "End do-not-disturb: notifications held back are shown.",
+			Run:         func(map[string]any) (any, error) { return SetPaused(false) },
+		},
+		{
+			Name:        "dunst_close_all",
+			Description: "Close every notification on screen. They stay in the history.",
+			Run:         func(map[string]any) (any, error) { return CloseAll() },
+		},
+		{
+			Name: "dunst_rules",
+			Description: "The notifier's rules in force — each rule's name, whether it is enabled, what it " +
+				"matches and what it sets — and the files they come from (the mesh's dunstrc, then dunstrc.d).",
+			Run: func(map[string]any) (any, error) { return Rules() },
+		},
+		{
+			Name:        "dunst_count",
+			Description: "How many notifications are shown, waiting and in the history, and whether do-not-disturb is on.",
+			Run:         func(map[string]any) (any, error) { return Count() },
+		},
+	}
+}

modules/dunst/cmd/dunst-tools/manifest_helpers_test.go

@@ -0,0 +1,175 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// The module's manifest, read the way the catalogue reads it, for the manifest tests. The same in
+// every desktop module that carries it.
+
+type manifest struct {
+	Module       string           `json:"module"`
+	Version      string           `json:"version"`
+	Capabilities []string         `json:"capabilities"`
+	Requires     []string         `json:"requires"`
+	Claims       []claim          `json:"claims"`
+	Seats        []any            `json:"seats"`
+	Tools        []string         `json:"tools"`
+	Environment  *environment     `json:"environment"`
+	Shell        []shellCode      `json:"shell"`
+	Resources    []map[string]any `json:"resources"`
+	Build        struct {
+		Artifacts []map[string]any `json:"artifacts"`
+	} `json:"build"`
+}
+
+type claim struct {
+	Name   string   `json:"name"`
+	Scope  string   `json:"scope"`
+	Serves []string `json:"serves"`
+}
+
+type environment struct {
+	Variables map[string]string `json:"variables"`
+	Path      []map[string]any  `json:"path"`
+}
+
+type shellCode struct {
+	For  string `json:"for"`
+	Slot string `json:"slot"`
+	Code string `json:"code"`
+}
+
+func readManifest(t *testing.T) manifest {
+	t.Helper()
+	raw, err := os.ReadFile(filepath.Join("..", "..", "module.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	dec := json.NewDecoder(strings.NewReader(string(raw)))
+	dec.DisallowUnknownFields()
+	var m manifest
+	if err := dec.Decode(&m); err != nil {
+		t.Fatalf("module.json: %v", err)
+	}
+	return m
+}
+
+func (m manifest) resource(t *testing.T, id string) map[string]any {
+	t.Helper()
+	for _, r := range m.Resources {
+		if r["id"] == id {
+			return r
+		}
+	}
+	t.Fatalf("no resource %q", id)
+	return nil
+}
+
+func (m manifest) packages() (present, absent []string) {
+	for _, r := range m.Resources {
+		if r["type"] == "package" {
+			if r["absent"] == true {
+				absent = append(absent, r["package"].(string))
+			} else {
+				present = append(present, r["package"].(string))
+			}
+		}
+	}
+	return present, absent
+}
+
+// sameAsSource checks that a file resource's content is byte for byte the module's source file, so
+// the readable file in the repository is what the machine gets.
+func (m manifest) sameAsSource(t *testing.T, id, source string) {
+	t.Helper()
+	want, err := os.ReadFile(filepath.Join("..", "..", source))
+	if err != nil {
+		t.Fatal(err)
+	}
+	r := m.resource(t, id)
+	if r["type"] != "file" {
+		t.Fatalf("%s is a %v, not a file", id, r["type"])
+	}
+	if got, _ := r["content"].(string); got != string(want) {
+		t.Fatalf("resource %s's content is not %s: edit the source and copy it into module.json", id, source)
+	}
+	if r["owner"] != "${machine:account}" && !strings.HasPrefix(r["path"].(string), "/etc/") {
+		t.Fatalf("%s under the home is the account's", id)
+	}
+}
+
+// checkTheToolsAgree checks that the manifest lists the module's own tools exactly, that the bundle
+// serves each seat verb the claims promise as <seat>.<verb>, and that the Go bundle is declared.
+func checkTheToolsAgree(t *testing.T, m manifest) {
+	t.Helper()
+	own, seat := map[string]bool{}, map[string]bool{}
+	for _, tool := range tools() {
+		if strings.Contains(tool.Name, ".") {
+			seat[tool.Name] = true
+		} else {
+			own[tool.Name] = true
+		}
+		if strings.TrimSpace(tool.Description) == "" {
+			t.Errorf("%s has no description", tool.Name)
+		}
+	}
+	listed := map[string]bool{}
+	for _, name := range m.Tools {
+		listed[name] = true
+		if !own[name] {
+			t.Errorf("module.json lists %s, which the bundle does not serve", name)
+		}
+	}
+	for name := range own {
+		if !listed[name] {
+			t.Errorf("the bundle serves %s, which module.json does not list", name)
+		}
+		if !strings.HasPrefix(name, strings.ReplaceAll(m.Module, "-", "_")+"_") {
+			t.Errorf("%s is not prefixed with the module's name", name)
+		}
+	}
+	promised := map[string]bool{}
+	for _, c := range m.Claims {
+		for _, verb := range c.Serves {
+			promised[c.Name+"."+verb] = true
+			if !seat[c.Name+"."+verb] {
+				t.Errorf("the claim on %s promises %s, which the bundle does not serve", c.Name, verb)
+			}
+		}
+	}
+	for name := range seat {
+		if !promised[name] {
+			t.Errorf("the bundle serves %s, which no claim promises", name)
+		}
+	}
+	var bundle map[string]any
+	for _, a := range m.Build.Artifacts {
+		if a["kind"] == "bundle" {
+			bundle = a
+		}
+	}
+	if bundle == nil || bundle["language"] != "go" || bundle["system"] != "arch" ||
+		bundle["from"] != "cmd/"+m.Module+"-tools" || bundle["binary"] != m.Module+"-tools" {
+		t.Errorf("the Go tools bundle: %v", bundle)
+	}
+}
+
+// checkNoSecretsOrInstallationNames refuses what a catalogue manifest must never carry.
+func checkNoSecretsOrInstallationNames(t *testing.T) {
+	t.Helper()
+	raw, err := os.ReadFile(filepath.Join("..", "..", "module.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := strings.ToLower(string(raw))
+	for _, never := range []string{"/home/", "jochen", "g14", "shanks", "novox.be", "api_key", ".hal/", "greenclip daemon"} {
+		if strings.Contains(s, never) {
+			t.Errorf("module.json names %q", never)
+		}
+	}
+}

modules/dunst/cmd/dunst-tools/manifest_test.go

@@ -0,0 +1,77 @@
+package main
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+)
+
+// dunst's shape (novox/hq ADR 0208): it claims node-notifier serving send and history, owns its
+// dunstrc and the drop-in directory other modules' rules go in, and starts nothing — D-Bus starts it
+// on the first notification. It draws only once a notification arrives, through the bus's
+// activation, so it requires no display of its own.
+
+func TestItClaimsTheNotifierSeatServingSendAndHistory(t *testing.T) {
+	m := readManifest(t)
+	if m.Module != "dunst" || m.Seats != nil {
+		t.Fatalf("module %q declares seats %v", m.Module, m.Seats)
+	}
+	if !reflect.DeepEqual(m.Claims, []claim{{Name: "node-notifier", Scope: "node", Serves: []string{"send", "history"}}}) {
+		t.Fatalf("claims: %+v", m.Claims)
+	}
+	if present, absent := m.packages(); !reflect.DeepEqual(present, []string{"dunst", "libnotify"}) || absent != nil {
+		t.Fatalf("packages: %v, absent %v", present, absent)
+	}
+}
+
+func TestItOwnsItsFileAndTheDropInDirectory(t *testing.T) {
+	m := readManifest(t)
+	m.sameAsSource(t, "configuration", "files/dunstrc")
+	if p := m.resource(t, "configuration")["path"]; p != "${machine:account-home}/.config/dunst/dunstrc" {
+		t.Fatalf("path: %v", p)
+	}
+	if d := m.resource(t, "dropins"); d["type"] != "directory" || d["path"] != "${machine:account-home}/.config/dunst/dunstrc.d" {
+		t.Fatalf("drop-ins: %v", d)
+	}
+	for _, r := range m.Resources {
+		if p, _ := r["path"].(string); strings.Contains(p, "dunstrc.d/") {
+			t.Fatalf("a rule of another module's: %v", r)
+		}
+	}
+}
+
+func TestTheFileIsTheDecidedOneAndCallsTheSeatsMenu(t *testing.T) {
+	m := readManifest(t)
+	c := m.resource(t, "configuration")["content"].(string)
+	for _, want := range []string{"origin = top-right", "transparency = 0", "corner_radius = 0", "font = Inter 10", "dmenu = dmenu -p dunst"} {
+		if !strings.Contains(c, "    "+want+"\n") {
+			t.Errorf("lacks %q", want)
+		}
+	}
+	for _, never := range []string{"/usr/bin/dmenu", "Hack", "icon_path", "/home/"} {
+		if strings.Contains(c, never) {
+			t.Errorf("names %q", never)
+		}
+	}
+}
+
+func TestNothingStartsItButTheBus(t *testing.T) {
+	m := readManifest(t)
+	if m.Shell != nil {
+		t.Fatalf("a session start: %+v", m.Shell)
+	}
+	for _, r := range m.Resources {
+		if r["type"] == "service" || r["type"] == "process" {
+			t.Fatalf("a unit: %v", r)
+		}
+		if p, _ := r["path"].(string); strings.Contains(p, "autostart") || strings.Contains(p, "i3/config.d") {
+			t.Fatalf("a start: %v", r)
+		}
+	}
+}
+
+func TestTheToolsAgreeWithTheManifest(t *testing.T) {
+	m := readManifest(t)
+	checkTheToolsAgree(t, m)
+	checkNoSecretsOrInstallationNames(t)
+}

modules/dunst/cmd/dunst-tools/session.go

@@ -0,0 +1,423 @@
+// The operator's graphical session, as a tool the node's runtime runs finds it (novox/hq ADR 0208).
+//
+// The runtime is a system service running as the operator account (ADR 0175): it has the account's
+// uid and none of the session's environment — no DISPLAY, no XAUTHORITY, no session bus. A tool that
+// draws on the screen or talks to the desktop's D-Bus must find them. It reads them from a process of
+// the account that is part of the session (the window manager first), the same thing `loginctl` and
+// a person's own shell would point at, and says where it found them.
+//
+// Long-lived programs a tool starts go to the account's own service manager through `systemd-run
+// --user`, never as children of the tool: the runtime's unit is a cgroup the service manager empties
+// whenever the runtime restarts, and a compositor or a clipboard owner started from inside it would
+// die with it.
+//
+// This file is the same in every desktop module that carries it; it moves into the Go SDK once a
+// second consumer outside the desktop wants it.
+package main
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"syscall"
+	"time"
+)
+
+// Where the session is looked for. Variables so a test can point them at a fake tree.
+var (
+	procRoot   = "/proc"
+	runUserDir = "/run/user"
+	x11Sockets = "/tmp/.X11-unix"
+)
+
+// sessionHolders are the processes whose environment is the session's, best first: the window
+// manager is the session, the rest are its children. Anything else carrying DISPLAY ranks after them.
+var sessionHolders = []string{"i3", "sway", "i3bar", "picom", "xss-lock", "dunst", "clipmenud", "xterm"}
+
+// sessionKeys are the variables a session carries that a tool hands on to what it runs.
+var sessionKeys = []string{"DISPLAY", "XAUTHORITY", "WAYLAND_DISPLAY", "DBUS_SESSION_BUS_ADDRESS",
+	"XDG_RUNTIME_DIR", "XDG_SESSION_ID", "I3SOCK"}
+
+// Session is what a tool needs to reach the operator's desktop.
+type Session struct {
+	UID        int    `json:"uid"`
+	Display    string `json:"display,omitempty"`
+	XAuthority string `json:"xauthority,omitempty"`
+	Wayland    string `json:"wayland_display,omitempty"`
+	Bus        string `json:"bus,omitempty"`
+	RuntimeDir string `json:"runtime_dir,omitempty"`
+	SessionID  string `json:"session_id,omitempty"`
+	I3Sock     string `json:"i3sock,omitempty"`
+	// From says where the values were found: the tool's own environment, a process, or the socket.
+	From string `json:"from"`
+}
+
+// ErrNoSession is answered by a tool that needs the desktop when nobody is logged in to it.
+var ErrNoSession = errors.New("no graphical session")
+
+// ErrTimedOut is what run answers for a command ended because it ran past its time.
+var ErrTimedOut = errors.New("timed out")
+
+// ErrNoBus is answered by a tool that needs the session bus when the account has none.
+var ErrNoBus = errors.New("no session bus")
+
+// operatorHome is the account's home: what the runtime was told, else the process's own.
+func operatorHome() string {
+	if h := strings.TrimSpace(os.Getenv("MESH_OPERATOR_HOME")); h != "" {
+		return h
+	}
+	h, _ := os.UserHomeDir()
+	return h
+}
+
+// findSession finds the graphical session of the account this tool runs as, or answers
+// ErrNoSession with what it looked at.
+func findSession() (Session, error) {
+	s := findEnvironment()
+	if s.Display == "" && s.Wayland == "" {
+		return s, fmt.Errorf("%w for uid %d on this machine: no process of the account carries DISPLAY "+
+			"or WAYLAND_DISPLAY, and no X server socket in %s has an authority file to go with it. "+
+			"Is anyone logged in to the desktop?", ErrNoSession, s.UID, x11Sockets)
+	}
+	return s, nil
+}
+
+// findBus finds the account's session bus, which a logged-in account has whether or not a desktop
+// is running.
+func findBus() (Session, error) {
+	s := findEnvironment()
+	if s.Bus == "" {
+		return s, fmt.Errorf("%w for uid %d: DBUS_SESSION_BUS_ADDRESS is not set and %s does not exist "+
+			"(the account is not logged in)", ErrNoBus, s.UID, filepath.Join(runUserDir, strconv.Itoa(s.UID), "bus"))
+	}
+	return s, nil
+}
+
+func findEnvironment() Session {
+	uid := os.Getuid()
+	s := Session{UID: uid}
+	own := map[string]string{}
+	for _, k := range sessionKeys {
+		own[k] = os.Getenv(k)
+	}
+	if own["DISPLAY"] != "" || own["WAYLAND_DISPLAY"] != "" {
+		s.fill(own)
+		s.From = "the tool's own environment"
+	} else if pid, comm, env, ok := sessionProcess(uid); ok {
+		s.fill(env)
+		s.From = fmt.Sprintf("process %s (pid %d)", comm, pid)
+	} else if display, ok := lonelyX11Socket(); ok {
+		if a := filepath.Join(operatorHome(), ".Xauthority"); exists(a) {
+			s.Display, s.XAuthority = display, a
+			s.From = "the X server socket and the account's ~/.Xauthority"
+		}
+		s.fill(own)
+	} else {
+		s.fill(own)
+		s.From = "nothing: no session found"
+	}
+	// The bus and the runtime directory are the account's, whether or not the process named them.
+	runtime := filepath.Join(runUserDir, strconv.Itoa(uid))
+	if s.RuntimeDir == "" && exists(runtime) {
+		s.RuntimeDir = runtime
+	}
+	if s.Bus == "" && s.RuntimeDir != "" && exists(filepath.Join(s.RuntimeDir, "bus")) {
+		s.Bus = "unix:path=" + filepath.Join(s.RuntimeDir, "bus")
+	}
+	return s
+}
+
+func (s *Session) fill(env map[string]string) {
+	set := func(dst *string, key string) {
+		if *dst == "" {
+			*dst = env[key]
+		}
+	}
+	set(&s.Display, "DISPLAY")
+	set(&s.XAuthority, "XAUTHORITY")
+	set(&s.Wayland, "WAYLAND_DISPLAY")
+	set(&s.Bus, "DBUS_SESSION_BUS_ADDRESS")
+	set(&s.RuntimeDir, "XDG_RUNTIME_DIR")
+	set(&s.SessionID, "XDG_SESSION_ID")
+	set(&s.I3Sock, "I3SOCK")
+}
+
+// sessionProcess is the best process of this uid whose environment names a display.
+func sessionProcess(uid int) (int, string, map[string]string, bool) {
+	entries, err := os.ReadDir(procRoot)
+	if err != nil {
+		return 0, "", nil, false
+	}
+	type candidate struct {
+		pid  int
+		comm string
+		env  map[string]string
+		rank int
+	}
+	var found []candidate
+	for _, e := range entries {
+		pid, err := strconv.Atoi(e.Name())
+		if err != nil {
+			continue
+		}
+		dir := filepath.Join(procRoot, e.Name())
+		if owner, ok := ownerOf(dir); !ok || owner != uid {
+			continue
+		}
+		raw, err := os.ReadFile(filepath.Join(dir, "environ"))
+		if err != nil {
+			continue
+		}
+		env := parseEnviron(raw)
+		if env["DISPLAY"] == "" && env["WAYLAND_DISPLAY"] == "" {
+			continue
+		}
+		comm := readTrimmed(filepath.Join(dir, "comm"))
+		rank := len(sessionHolders)
+		for i, h := range sessionHolders {
+			if h == comm {
+				rank = i
+				break
+			}
+		}
+		found = append(found, candidate{pid, comm, env, rank})
+	}
+	if len(found) == 0 {
+		return 0, "", nil, false
+	}
+	sort.Slice(found, func(i, j int) bool {
+		if found[i].rank != found[j].rank {
+			return found[i].rank < found[j].rank
+		}
+		return found[i].pid > found[j].pid // the newer of two equals
+	})
+	best := found[0]
+	return best.pid, best.comm, best.env, true
+}
+
+func parseEnviron(raw []byte) map[string]string {
+	env := map[string]string{}
+	for _, kv := range bytes.Split(raw, []byte{0}) {
+		if i := bytes.IndexByte(kv, '='); i > 0 {
+			env[string(kv[:i])] = string(kv[i+1:])
+		}
+	}
+	return env
+}
+
+func ownerOf(path string) (int, bool) {
+	info, err := os.Stat(path)
+	if err != nil {
+		return 0, false
+	}
+	st, ok := info.Sys().(*syscall.Stat_t)
+	if !ok {
+		return 0, false
+	}
+	return int(st.Uid), true
+}
+
+// lonelyX11Socket is the display of the one X server socket there is, when there is exactly one.
+func lonelyX11Socket() (string, bool) {
+	entries, err := os.ReadDir(x11Sockets)
+	if err != nil {
+		return "", false
+	}
+	var displays []string
+	for _, e := range entries {
+		if n := strings.TrimPrefix(e.Name(), "X"); n != e.Name() {
+			if _, err := strconv.Atoi(n); err == nil {
+				displays = append(displays, ":"+n)
+			}
+		}
+	}
+	if len(displays) != 1 {
+		return "", false
+	}
+	return displays[0], true
+}
+
+func readTrimmed(path string) string {
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(string(b))
+}
+
+func exists(path string) bool {
+	_, err := os.Stat(path)
+	return err == nil
+}
+
+// Env is this process's environment with the session's variables in place of its own.
+func (s Session) Env() []string {
+	drop := map[string]bool{}
+	for _, k := range sessionKeys {
+		drop[k] = true
+	}
+	var env []string
+	for _, kv := range os.Environ() {
+		if i := strings.IndexByte(kv, '='); i > 0 && drop[kv[:i]] {
+			continue
+		}
+		env = append(env, kv)
+	}
+	add := func(k, v string) {
+		if v != "" {
+			env = append(env, k+"="+v)
+		}
+	}
+	add("DISPLAY", s.Display)
+	add("XAUTHORITY", s.XAuthority)
+	add("WAYLAND_DISPLAY", s.Wayland)
+	add("DBUS_SESSION_BUS_ADDRESS", s.Bus)
+	add("XDG_RUNTIME_DIR", s.RuntimeDir)
+	add("XDG_SESSION_ID", s.SessionID)
+	add("I3SOCK", s.I3Sock)
+	return env
+}
+
+// mostOutput bounds what a command may answer with, per stream.
+const mostOutput = 256 << 10
+
+// Result is what a command did.
+type Result struct {
+	Stdout    string `json:"stdout"`
+	Stderr    string `json:"stderr,omitempty"`
+	Code      int    `json:"code"`
+	Truncated bool   `json:"truncated,omitempty"`
+}
+
+// run runs a command in the session's environment, its input given, ended with everything it
+// started after timeout. A command that is not installed is an error naming it; one that exits
+// non-zero is a Result with its code, for the caller to judge.
+func (s Session) run(timeout time.Duration, stdin string, name string, args ...string) (Result, error) {
+	path, err := exec.LookPath(name)
+	if err != nil {
+		return Result{}, fmt.Errorf("%s is not installed on this machine", name)
+	}
+	cmd := exec.Command(path, args...)
+	cmd.Env = s.Env()
+	if home := operatorHome(); exists(home) {
+		cmd.Dir = home
+	}
+	if stdin != "" {
+		cmd.Stdin = strings.NewReader(stdin)
+	}
+	var out, errOut capped
+	cmd.Stdout, cmd.Stderr = &out, &errOut
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+	if err := cmd.Start(); err != nil {
+		return Result{}, fmt.Errorf("%s: %w", name, err)
+	}
+	done := make(chan error, 1)
+	go func() { done <- cmd.Wait() }()
+	select {
+	case err = <-done:
+	case <-time.After(timeout):
+		_ = syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)
+		<-done
+		return Result{Stdout: out.String(), Stderr: errOut.String()},
+			fmt.Errorf("%s did not finish within %s and was ended: %w", name, timeout, ErrTimedOut)
+	}
+	r := Result{Stdout: out.String(), Stderr: errOut.String(), Truncated: out.cut || errOut.cut}
+	var exit *exec.ExitError
+	if errors.As(err, &exit) {
+		r.Code = exit.ExitCode()
+	} else if err != nil {
+		return r, fmt.Errorf("%s: %w", name, err)
+	}
+	return r, nil
+}
+
+// detach starts a long-lived program under the account's own service manager, as a transient unit
+// that carries the session's display, so it outlives the runtime that asked for it. A unit already
+// running under the same name is stopped first, so a fixed name means "at most one".
+func (s Session) detach(unit string, args ...string) error {
+	if s.RuntimeDir == "" {
+		return fmt.Errorf("%w: the account's runtime directory is missing, so its service manager "+
+			"cannot be reached", ErrNoBus)
+	}
+	_, _ = s.run(5*time.Second, "", "systemctl", "--user", "stop", unit+".service")
+	call := []string{"--user", "--collect", "--quiet", "--unit=" + unit}
+	for _, kv := range [][2]string{{"DISPLAY", s.Display}, {"XAUTHORITY", s.XAuthority},
+		{"WAYLAND_DISPLAY", s.Wayland}, {"XDG_SESSION_ID", s.SessionID}, {"I3SOCK", s.I3Sock}} {
+		if kv[1] != "" {
+			call = append(call, "--setenv="+kv[0]+"="+kv[1])
+		}
+	}
+	call = append(call, "--")
+	call = append(call, args...)
+	r, err := s.run(10*time.Second, "", "systemd-run", call...)
+	if err != nil {
+		return err
+	}
+	if r.Code != 0 {
+		return fmt.Errorf("systemd-run %s: %s", unit, strings.TrimSpace(r.Stderr))
+	}
+	return nil
+}
+
+// uniqueUnit is a transient unit name that will not collide with an earlier one.
+func uniqueUnit(prefix string) string {
+	return fmt.Sprintf("%s-%d", prefix, time.Now().UnixNano())
+}
+
+type capped struct {
+	bytes.Buffer
+	cut bool
+}
+
+func (c *capped) Write(p []byte) (int, error) {
+	if room := mostOutput - c.Len(); room < len(p) {
+		if room > 0 {
+			c.Buffer.Write(p[:room])
+		}
+		c.cut = true
+		return len(p), nil
+	}
+	return c.Buffer.Write(p)
+}
+
+// processesOf are the pids of this uid's processes whose command name is comm, oldest first.
+func processesOf(comm string) []int {
+	entries, err := os.ReadDir(procRoot)
+	if err != nil {
+		return nil
+	}
+	uid := os.Getuid()
+	var pids []int
+	for _, e := range entries {
+		pid, err := strconv.Atoi(e.Name())
+		if err != nil {
+			continue
+		}
+		dir := filepath.Join(procRoot, e.Name())
+		if owner, ok := ownerOf(dir); !ok || owner != uid {
+			continue
+		}
+		if readTrimmed(filepath.Join(dir, "comm")) == comm {
+			pids = append(pids, pid)
+		}
+	}
+	sort.Ints(pids)
+	return pids
+}
+
+// signalAll sends sig to every process of this uid named comm, and answers the pids it reached.
+func signalAll(comm string, sig syscall.Signal) []int {
+	var reached []int
+	for _, pid := range processesOf(comm) {
+		if syscall.Kill(pid, sig) == nil {
+			reached = append(reached, pid)
+		}
+	}
+	return reached
+}

modules/dunst/cmd/dunst-tools/session_test.go

@@ -0,0 +1,174 @@
+package main
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+)
+
+// fakeMachine points the session finder at a temporary /proc, /run/user and X socket directory, with
+// none of the test process's own session variables, and gives back the root.
+func fakeMachine(t *testing.T) string {
+	t.Helper()
+	root := t.TempDir()
+	procRoot, runUserDir, x11Sockets = filepath.Join(root, "proc"), filepath.Join(root, "run-user"), filepath.Join(root, "x11")
+	for _, d := range []string{procRoot, runUserDir, x11Sockets} {
+		if err := os.MkdirAll(d, 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	for _, k := range sessionKeys {
+		t.Setenv(k, "")
+	}
+	t.Setenv("MESH_OPERATOR_HOME", filepath.Join(root, "home"))
+	t.Cleanup(func() { procRoot, runUserDir, x11Sockets = "/proc", "/run/user", "/tmp/.X11-unix" })
+	return root
+}
+
+func fakeProcess(t *testing.T, pid int, comm string, env ...string) {
+	t.Helper()
+	dir := filepath.Join(procRoot, strconv.Itoa(pid))
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "comm"), []byte(comm+"\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "environ"), []byte(strings.Join(env, "\x00")+"\x00"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestTheSessionIsReadFromTheWindowManagerBeforeAnyOtherProcess(t *testing.T) {
+	fakeMachine(t)
+	fakeProcess(t, 900, "xterm", "DISPLAY=:9", "XAUTHORITY=/elsewhere")
+	fakeProcess(t, 100, "i3", "DISPLAY=:1", "XAUTHORITY=/home/op/.Xauthority",
+		"DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus", "XDG_SESSION_ID=3", "SECRET_TOKEN=never-copied")
+	fakeProcess(t, 50, "bash", "PATH=/usr/bin")
+	s, err := findSession()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if s.Display != ":1" || s.XAuthority != "/home/op/.Xauthority" || s.SessionID != "3" || !strings.Contains(s.From, "i3 (pid 100)") {
+		t.Fatalf("the window manager's environment: %+v", s)
+	}
+	for _, kv := range s.Env() {
+		if strings.HasPrefix(kv, "SECRET_TOKEN=") {
+			t.Fatal("a variable of the session process that is not a session variable was handed on")
+		}
+	}
+}
+
+func TestAnyProcessCarryingADisplayServesWhenTheWindowManagerIsNotFound(t *testing.T) {
+	fakeMachine(t)
+	fakeProcess(t, 10, "firefox", "DISPLAY=:0")
+	fakeProcess(t, 20, "firefox", "DISPLAY=:2")
+	s, err := findSession()
+	if err != nil || s.Display != ":2" {
+		t.Fatalf("the newest of two equals: %+v, %v", s, err)
+	}
+}
+
+func TestNoSessionIsAClearAnswerNotAGuess(t *testing.T) {
+	fakeMachine(t)
+	fakeProcess(t, 10, "sshd", "PATH=/usr/bin")
+	_, err := findSession()
+	if !errors.Is(err, ErrNoSession) || !strings.Contains(err.Error(), "logged in to the desktop") {
+		t.Fatalf("no session: %v", err)
+	}
+}
+
+func TestOneXSocketAndTheAccountsAuthorityFileAreASession(t *testing.T) {
+	root := fakeMachine(t)
+	if err := os.WriteFile(filepath.Join(x11Sockets, "X0"), nil, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Join(root, "home"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(root, "home", ".Xauthority"), nil, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	s, err := findSession()
+	if err != nil || s.Display != ":0" || !strings.HasSuffix(s.XAuthority, "/home/.Xauthority") {
+		t.Fatalf("socket and authority: %+v, %v", s, err)
+	}
+}
+
+func TestTheBusIsTheAccountsRuntimeDirectoryWhenNoProcessNamesIt(t *testing.T) {
+	fakeMachine(t)
+	runtime := filepath.Join(runUserDir, strconv.Itoa(os.Getuid()))
+	if _, err := findBus(); !errors.Is(err, ErrNoBus) {
+		t.Fatalf("no runtime directory is no bus: %v", err)
+	}
+	if err := os.MkdirAll(runtime, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(runtime, "bus"), nil, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	s, err := findBus()
+	if err != nil || s.Bus != "unix:path="+filepath.Join(runtime, "bus") || s.RuntimeDir != runtime {
+		t.Fatalf("bus: %+v, %v", s, err)
+	}
+	env := strings.Join(s.Env(), "\n")
+	if !strings.Contains(env, "XDG_RUNTIME_DIR="+runtime) || !strings.Contains(env, "DBUS_SESSION_BUS_ADDRESS=unix:path=") {
+		t.Fatalf("the bus is handed on: %s", env)
+	}
+}
+
+func TestACommandIsBoundedAndANonZeroExitIsAResult(t *testing.T) {
+	fakeMachine(t)
+	s := Session{}
+	r, err := s.run(5*time.Second, "in", "sh", "-c", "cat; echo err >&2; exit 3")
+	if err != nil || r.Stdout != "in" || r.Code != 3 || strings.TrimSpace(r.Stderr) != "err" {
+		t.Fatalf("result: %+v, %v", r, err)
+	}
+	start := time.Now()
+	if _, err := s.run(200*time.Millisecond, "", "sh", "-c", "sleep 30 & sleep 30"); err == nil || time.Since(start) > 5*time.Second {
+		t.Fatalf("a command past its time is ended with what it started: %v after %s", err, time.Since(start))
+	}
+	if _, err := s.run(time.Second, "", "no-such-program-here"); err == nil || !strings.Contains(err.Error(), "not installed") {
+		t.Fatalf("a missing program: %v", err)
+	}
+}
+
+func TestDetachAsksTheAccountsServiceManagerWithTheSessionsDisplay(t *testing.T) {
+	fakeMachine(t)
+	bin := fakeBinaries(t, map[string]string{
+		"systemctl":   `echo "systemctl $*" >> "$LOG"`,
+		"systemd-run": `echo "systemd-run $*" >> "$LOG"`,
+	})
+	log := filepath.Join(bin, "log")
+	t.Setenv("LOG", log)
+	s := Session{Display: ":1", XAuthority: "/x", RuntimeDir: "/run/user/1"}
+	if err := s.detach("picom-session", "picom", "--config", "/c"); err != nil {
+		t.Fatal(err)
+	}
+	got, _ := os.ReadFile(log)
+	want := "systemctl --user stop picom-session.service\n" +
+		"systemd-run --user --collect --quiet --unit=picom-session --setenv=DISPLAY=:1 --setenv=XAUTHORITY=/x -- picom --config /c\n"
+	if string(got) != want {
+		t.Fatalf("detach ran:\n%s\nwant:\n%s", got, want)
+	}
+	if err := (Session{}).detach("x", "y"); !errors.Is(err, ErrNoBus) {
+		t.Fatalf("no runtime directory: %v", err)
+	}
+}
+
+// fakeBinaries puts shell scripts named for programs first on PATH, and answers their directory.
+func fakeBinaries(t *testing.T, scripts map[string]string) string {
+	t.Helper()
+	dir := t.TempDir()
+	for name, body := range scripts {
+		if err := os.WriteFile(filepath.Join(dir, name), []byte("#!/bin/sh\n"+body+"\n"), 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	t.Setenv("PATH", dir+string(os.PathListSeparator)+os.Getenv("PATH"))
+	return dir
+}

modules/dunst/files/dunstrc

@@ -0,0 +1,92 @@
+# dunst, the notifier (module dunst, novox/hq ADR 0208). Owned by the mesh: this file is replaced
+# at every push. Adopted from the laptop's file of 2026-10-04 (the two workstations differed in
+# position, transparency and corner radius; the laptop's square, opaque, top-right one matches the
+# rest of the desktop). Only what differs from dunst's defaults, and what the desktop relies on.
+#
+# Other modules' rules go in ~/.config/dunst/dunstrc.d/*.conf, which dunst reads after this file,
+# so a drop-in outranks it. dunst is started by D-Bus on the first notification: nothing starts it.
+
+[global]
+    monitor = 0
+    follow = none
+
+    # Geometry
+    width = 250
+    height = (0, 300)
+    origin = top-right
+    offset = (10, 50)
+    notification_limit = 20
+
+    progress_bar = true
+    progress_bar_height = 10
+    progress_bar_frame_width = 1
+    progress_bar_min_width = 150
+    progress_bar_max_width = 300
+
+    indicate_hidden = yes
+    transparency = 0
+    separator_height = 2
+    padding = 8
+    horizontal_padding = 8
+    text_icon_padding = 0
+    frame_width = 3
+    frame_color = "#de5200"
+    gap_size = 0
+    separator_color = frame
+    sort = yes
+    corner_radius = 0
+
+    # Text: the interface face (research 026/04)
+    font = Inter 10
+    line_height = 0
+    markup = full
+    format = "<b>%s</b>\n%b"
+    alignment = left
+    vertical_alignment = center
+    show_age_threshold = 60
+    ellipsize = middle
+    ignore_newline = no
+    stack_duplicates = true
+    hide_duplicate_count = false
+    show_indicators = yes
+
+    # Icons, from the desktop's icon theme
+    enable_recursive_icon_lookup = true
+    icon_theme = Adwaita
+    icon_position = left
+    min_icon_size = 32
+    max_icon_size = 128
+
+    # History
+    sticky_history = yes
+    history_length = 20
+
+    # The context menu is the node's dmenu-compatible command, which the holder of node-launcher
+    # answers (rofi on the workstations). Links open in the desktop's default browser.
+    dmenu = dmenu -p dunst
+    browser = /usr/bin/xdg-open
+    always_run_script = true
+
+    title = Dunst
+    class = Dunst
+    ignore_dbusclose = false
+
+    mouse_left_click = close_current
+    mouse_middle_click = do_action, close_current
+    mouse_right_click = close_all
+
+[urgency_low]
+    background = "#000000"
+    foreground = "#ffffff"
+    timeout = 10
+
+[urgency_normal]
+    background = "#000000"
+    foreground = "#ffffff"
+    timeout = 10
+
+[urgency_critical]
+    background = "#000000"
+    foreground = "#ffffff"
+    frame_color = "#ff0000"
+    timeout = 0

modules/dunst/go.mod

@@ -0,0 +1,5 @@
+module dunst
+
+go 1.22
+
+require git.novox.be/novox/mesh-sdk/go v0.1.7

modules/dunst/go.sum

@@ -0,0 +1,2 @@
+git.novox.be/novox/mesh-sdk/go v0.1.7 h1:C0sTQmtTiyYH7bnqZb7PusXnqA37gKuT7Nqjn9gG47w=
+git.novox.be/novox/mesh-sdk/go v0.1.7/go.mod h1:GFuZUElBZ9A++mxgIKo97aXXo+kV0uJ/UkbhQPPIbrY=

modules/dunst/module.json

@@ -0,0 +1,73 @@
+{
+  "module": "dunst",
+  "version": "1",
+  "capabilities": [
+    "package-manager"
+  ],
+  "claims": [
+    {
+      "name": "node-notifier",
+      "scope": "node",
+      "serves": [
+        "send",
+        "history"
+      ]
+    }
+  ],
+  "tools": [
+    "dunst_pause",
+    "dunst_resume",
+    "dunst_close_all",
+    "dunst_rules",
+    "dunst_count"
+  ],
+  "resources": [
+    {
+      "id": "package",
+      "type": "package",
+      "package": "dunst"
+    },
+    {
+      "id": "client",
+      "type": "package",
+      "package": "libnotify"
+    },
+    {
+      "id": "configuration-dir",
+      "type": "directory",
+      "path": "${machine:account-home}/.config/dunst",
+      "owner": "${machine:account}",
+      "mode": "0755"
+    },
+    {
+      "id": "dropins",
+      "type": "directory",
+      "path": "${machine:account-home}/.config/dunst/dunstrc.d",
+      "owner": "${machine:account}",
+      "mode": "0755"
+    },
+    {
+      "id": "configuration",
+      "type": "file",
+      "path": "${machine:account-home}/.config/dunst/dunstrc",
+      "owner": "${machine:account}",
+      "mode": "0644",
+      "content": "# dunst, the notifier (module dunst, novox/hq ADR 0208). Owned by the mesh: this file is replaced\n# at every push. Adopted from the laptop's file of 2026-10-04 (the two workstations differed in\n# position, transparency and corner radius; the laptop's square, opaque, top-right one matches the\n# rest of the desktop). Only what differs from dunst's defaults, and what the desktop relies on.\n#\n# Other modules' rules go in ~/.config/dunst/dunstrc.d/*.conf, which dunst reads after this file,\n# so a drop-in outranks it. dunst is started by D-Bus on the first notification: nothing starts it.\n\n[global]\n    monitor = 0\n    follow = none\n\n    # Geometry\n    width = 250\n    height = (0, 300)\n    origin = top-right\n    offset = (10, 50)\n    notification_limit = 20\n\n    progress_bar = true\n    progress_bar_height = 10\n    progress_bar_frame_width = 1\n    progress_bar_min_width = 150\n    progress_bar_max_width = 300\n\n    indicate_hidden = yes\n    transparency = 0\n    separator_height = 2\n    padding = 8\n    horizontal_padding = 8\n    text_icon_padding = 0\n    frame_width = 3\n    frame_color = \"#de5200\"\n    gap_size = 0\n    separator_color = frame\n    sort = yes\n    corner_radius = 0\n\n    # Text: the interface face (research 026/04)\n    font = Inter 10\n    line_height = 0\n    markup = full\n    format = \"<b>%s</b>\\n%b\"\n    alignment = left\n    vertical_alignment = center\n    show_age_threshold = 60\n    ellipsize = middle\n    ignore_newline = no\n    stack_duplicates = true\n    hide_duplicate_count = false\n    show_indicators = yes\n\n    # Icons, from the desktop's icon theme\n    enable_recursive_icon_lookup = true\n    icon_theme = Adwaita\n    icon_position = left\n    min_icon_size = 32\n    max_icon_size = 128\n\n    # History\n    sticky_history = yes\n    history_length = 20\n\n    # The context menu is the node's dmenu-compatible command, which the holder of node-launcher\n    # answers (rofi on the workstations). Links open in the desktop's default browser.\n    dmenu = dmenu -p dunst\n    browser = /usr/bin/xdg-open\n    always_run_script = true\n\n    title = Dunst\n    class = Dunst\n    ignore_dbusclose = false\n\n    mouse_left_click = close_current\n    mouse_middle_click = do_action, close_current\n    mouse_right_click = close_all\n\n[urgency_low]\n    background = \"#000000\"\n    foreground = \"#ffffff\"\n    timeout = 10\n\n[urgency_normal]\n    background = \"#000000\"\n    foreground = \"#ffffff\"\n    timeout = 10\n\n[urgency_critical]\n    background = \"#000000\"\n    foreground = \"#ffffff\"\n    frame_color = \"#ff0000\"\n    timeout = 0\n"
+    }
+  ],
+  "build": {
+    "artifacts": [
+      {
+        "name": "tools",
+        "kind": "bundle",
+        "language": "go",
+        "system": "arch",
+        "from": "cmd/dunst-tools",
+        "binary": "dunst-tools",
+        "loads": [
+          "dunst-tools"
+        ]
+      }
+    ]
+  }
+}

modules/feh/README.md

@@ -0,0 +1,47 @@
+# feh
+
+The wallpaper as a module (novox/hq ADR 0208, research 026/05).
+
+- Installs `feh` and requires `x11-display` on its own machine. It holds no seat: a wallpaper is not a
+  role anything else calls.
+- **Carries the wallpaper itself.** `wallpaper/default.jpg` is built into an archive of the module
+  (ADR 0205) and unpacked into `~/.local/share/feh/wallpapers/`, which the module owns.
+- Owns `~/.fehbg`, which sets that image, filled, on every monitor, without rewriting itself
+  (`--no-fehbg`).
+- Runs `~/.fehbg` once per session, from the session's start (the `xinitrc` slot `normal`).
+- Binds `$mod+Shift+b` to the same file, as its own i3 drop-in (`50-feh.conf`): the declared wallpaper
+  back, after a monitor change.
+
+## Tools
+
+| tool | does |
+|---|---|
+| `feh_set` | set images (one for all monitors, or one each) in a mode: fill, center, max, scale, tile. For this session; the declared wallpaper returns at the next login |
+| `feh_current` | the declared wallpaper (from `~/.fehbg`) and the one `feh_set` put up in this session |
+
+`feh_set` never writes `~/.fehbg`. A wallpaper that should stay is a change to this module, or a
+setting once issue 168 closes, not a file the next push would overwrite.
+
+## What it improves on what was found
+
+- **The wallpaper no longer lives in the predecessor's tree.** `~/.fehbg` pointed into a directory
+  of the retired predecessor's. Deleting that directory would have left the desktop black, silently.
+- **One image file, the same on both workstations.** The image was byte-identical on both. It is now
+  the module's own.
+
+## What it leaves as found
+
+- The predecessor's wallpaper directory. It is part of the predecessor's tree, which goes as a whole.
+
+## Migration (ADR 0182)
+
+- The first push keeps the found `~/.fehbg` once, then writes the module's.
+- Once the `xorg` module writes the session's start, delete the `~/.fehbg &` line from your own part
+  of `~/.xinitrc`.
+- The image's origin is the predecessor's desktop module. Check that it may be redistributed before
+  this catalogue is published anywhere public.
+
+## Blockers
+
+- `x11-display` and the `xinitrc` slot are ADR 0208's. Until the controller knows them, `mctl` reads
+  them as unknown.

modules/feh/cmd/feh-tools/args.go

@@ -0,0 +1,97 @@
+// Reading a tool's arguments: JSON numbers arrive as float64, and a missing argument is its default.
+// The same in every desktop module that carries it.
+package main
+
+import (
+	"fmt"
+	"math"
+	"strings"
+	"time"
+)
+
+// text is a string argument, trimmed; required says an empty one is refused.
+func text(args map[string]any, key string, required bool) (string, error) {
+	v, present := args[key]
+	if !present || v == nil {
+		if required {
+			return "", fmt.Errorf("%s is required", key)
+		}
+		return "", nil
+	}
+	s, ok := v.(string)
+	if !ok {
+		return "", fmt.Errorf("%s is a string, not %T", key, v)
+	}
+	s = strings.TrimSpace(s)
+	if s == "" && required {
+		return "", fmt.Errorf("%s is required", key)
+	}
+	return s, nil
+}
+
+// whole is a whole-number argument within [least, most], or def when absent.
+func whole(args map[string]any, key string, def, least, most int) (int, error) {
+	v, present := args[key]
+	if !present || v == nil {
+		return def, nil
+	}
+	f, ok := v.(float64)
+	if !ok {
+		if i, isInt := v.(int); isInt {
+			f = float64(i)
+		} else {
+			return 0, fmt.Errorf("%s is a number, not %T", key, v)
+		}
+	}
+	if f != math.Trunc(f) {
+		return 0, fmt.Errorf("%s is a whole number, not %v", key, f)
+	}
+	n := int(f)
+	if n < least || n > most {
+		return 0, fmt.Errorf("%s is %d; it is between %d and %d", key, n, least, most)
+	}
+	return n, nil
+}
+
+// flag is a boolean argument, or def when absent.
+func flag(args map[string]any, key string, def bool) (bool, error) {
+	v, present := args[key]
+	if !present || v == nil {
+		return def, nil
+	}
+	b, ok := v.(bool)
+	if !ok {
+		return false, fmt.Errorf("%s is true or false, not %T", key, v)
+	}
+	return b, nil
+}
+
+// texts is a list-of-strings argument.
+func texts(args map[string]any, key string) ([]string, error) {
+	v, present := args[key]
+	if !present || v == nil {
+		return nil, nil
+	}
+	list, ok := v.([]any)
+	if !ok {
+		if ss, isStrings := v.([]string); isStrings {
+			return ss, nil
+		}
+		return nil, fmt.Errorf("%s is a list of strings, not %T", key, v)
+	}
+	out := make([]string, 0, len(list))
+	for i, item := range list {
+		s, ok := item.(string)
+		if !ok {
+			return nil, fmt.Errorf("%s[%d] is a string, not %T", key, i, item)
+		}
+		out = append(out, s)
+	}
+	return out, nil
+}
+
+// seconds is a timeout argument in seconds, defaulted and bounded below the runtime's call limit.
+func seconds(args map[string]any, key string, def, most int) (time.Duration, error) {
+	n, err := whole(args, key, def, 1, most)
+	return time.Duration(n) * time.Second, err
+}

modules/feh/cmd/feh-tools/main.go

@@ -0,0 +1,53 @@
+// feh's Go tools bundle (novox/hq ADR 0188, ADR 0193, ADR 0208): the wallpaper's tools, served by the
+// node's runtime as the operator account.
+package main
+
+import (
+	"fmt"
+	"os"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+func main() {
+	if err := stdio.Serve("", tools()); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+func tools() []stdio.Tool {
+	return []stdio.Tool{
+		{
+			Name: "feh_set",
+			Description: "Set the wallpaper in the operator's session: one image for every monitor, or one per " +
+				"monitor in the X screen order, filled, centred, scaled to fit, stretched or tiled. Lasts until the " +
+				"next session start, when the declared wallpaper returns; the declared one is untouched.",
+			Input: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"images": map[string]any{"type": "array", "items": map[string]any{"type": "string"}, "description": "image files on this machine, absolute or under the account's home; one per monitor, or one for all"},
+					"mode":   map[string]any{"type": "string", "enum": modes, "description": "default fill"},
+				},
+				"required": []string{"images"},
+			},
+			Run: func(args map[string]any) (any, error) {
+				images, err := texts(args, "images")
+				if err != nil {
+					return nil, err
+				}
+				mode, err := text(args, "mode", false)
+				if err != nil {
+					return nil, err
+				}
+				return Set(images, mode)
+			},
+		},
+		{
+			Name: "feh_current",
+			Description: "The wallpaper: the declared one the session start sets (images and mode, read from " +
+				"~/.fehbg), and the one feh_set put up in this session, if any.",
+			Run: func(map[string]any) (any, error) { return Current() },
+		},
+	}
+}

modules/feh/cmd/feh-tools/manifest_helpers_test.go

@@ -0,0 +1,175 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// The module's manifest, read the way the catalogue reads it, for the manifest tests. The same in
+// every desktop module that carries it.
+
+type manifest struct {
+	Module       string           `json:"module"`
+	Version      string           `json:"version"`
+	Capabilities []string         `json:"capabilities"`
+	Requires     []string         `json:"requires"`
+	Claims       []claim          `json:"claims"`
+	Seats        []any            `json:"seats"`
+	Tools        []string         `json:"tools"`
+	Environment  *environment     `json:"environment"`
+	Shell        []shellCode      `json:"shell"`
+	Resources    []map[string]any `json:"resources"`
+	Build        struct {
+		Artifacts []map[string]any `json:"artifacts"`
+	} `json:"build"`
+}
+
+type claim struct {
+	Name   string   `json:"name"`
+	Scope  string   `json:"scope"`
+	Serves []string `json:"serves"`
+}
+
+type environment struct {
+	Variables map[string]string `json:"variables"`
+	Path      []map[string]any  `json:"path"`
+}
+
+type shellCode struct {
+	For  string `json:"for"`
+	Slot string `json:"slot"`
+	Code string `json:"code"`
+}
+
+func readManifest(t *testing.T) manifest {
+	t.Helper()
+	raw, err := os.ReadFile(filepath.Join("..", "..", "module.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	dec := json.NewDecoder(strings.NewReader(string(raw)))
+	dec.DisallowUnknownFields()
+	var m manifest
+	if err := dec.Decode(&m); err != nil {
+		t.Fatalf("module.json: %v", err)
+	}
+	return m
+}
+
+func (m manifest) resource(t *testing.T, id string) map[string]any {
+	t.Helper()
+	for _, r := range m.Resources {
+		if r["id"] == id {
+			return r
+		}
+	}
+	t.Fatalf("no resource %q", id)
+	return nil
+}
+
+func (m manifest) packages() (present, absent []string) {
+	for _, r := range m.Resources {
+		if r["type"] == "package" {
+			if r["absent"] == true {
+				absent = append(absent, r["package"].(string))
+			} else {
+				present = append(present, r["package"].(string))
+			}
+		}
+	}
+	return present, absent
+}
+
+// sameAsSource checks that a file resource's content is byte for byte the module's source file, so
+// the readable file in the repository is what the machine gets.
+func (m manifest) sameAsSource(t *testing.T, id, source string) {
+	t.Helper()
+	want, err := os.ReadFile(filepath.Join("..", "..", source))
+	if err != nil {
+		t.Fatal(err)
+	}
+	r := m.resource(t, id)
+	if r["type"] != "file" {
+		t.Fatalf("%s is a %v, not a file", id, r["type"])
+	}
+	if got, _ := r["content"].(string); got != string(want) {
+		t.Fatalf("resource %s's content is not %s: edit the source and copy it into module.json", id, source)
+	}
+	if r["owner"] != "${machine:account}" && !strings.HasPrefix(r["path"].(string), "/etc/") {
+		t.Fatalf("%s under the home is the account's", id)
+	}
+}
+
+// checkTheToolsAgree checks that the manifest lists the module's own tools exactly, that the bundle
+// serves each seat verb the claims promise as <seat>.<verb>, and that the Go bundle is declared.
+func checkTheToolsAgree(t *testing.T, m manifest) {
+	t.Helper()
+	own, seat := map[string]bool{}, map[string]bool{}
+	for _, tool := range tools() {
+		if strings.Contains(tool.Name, ".") {
+			seat[tool.Name] = true
+		} else {
+			own[tool.Name] = true
+		}
+		if strings.TrimSpace(tool.Description) == "" {
+			t.Errorf("%s has no description", tool.Name)
+		}
+	}
+	listed := map[string]bool{}
+	for _, name := range m.Tools {
+		listed[name] = true
+		if !own[name] {
+			t.Errorf("module.json lists %s, which the bundle does not serve", name)
+		}
+	}
+	for name := range own {
+		if !listed[name] {
+			t.Errorf("the bundle serves %s, which module.json does not list", name)
+		}
+		if !strings.HasPrefix(name, strings.ReplaceAll(m.Module, "-", "_")+"_") {
+			t.Errorf("%s is not prefixed with the module's name", name)
+		}
+	}
+	promised := map[string]bool{}
+	for _, c := range m.Claims {
+		for _, verb := range c.Serves {
+			promised[c.Name+"."+verb] = true
+			if !seat[c.Name+"."+verb] {
+				t.Errorf("the claim on %s promises %s, which the bundle does not serve", c.Name, verb)
+			}
+		}
+	}
+	for name := range seat {
+		if !promised[name] {
+			t.Errorf("the bundle serves %s, which no claim promises", name)
+		}
+	}
+	var bundle map[string]any
+	for _, a := range m.Build.Artifacts {
+		if a["kind"] == "bundle" {
+			bundle = a
+		}
+	}
+	if bundle == nil || bundle["language"] != "go" || bundle["system"] != "arch" ||
+		bundle["from"] != "cmd/"+m.Module+"-tools" || bundle["binary"] != m.Module+"-tools" {
+		t.Errorf("the Go tools bundle: %v", bundle)
+	}
+}
+
+// checkNoSecretsOrInstallationNames refuses what a catalogue manifest must never carry.
+func checkNoSecretsOrInstallationNames(t *testing.T) {
+	t.Helper()
+	raw, err := os.ReadFile(filepath.Join("..", "..", "module.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := strings.ToLower(string(raw))
+	for _, never := range []string{"/home/", "jochen", "g14", "shanks", "novox.be", "api_key", ".hal/", "greenclip daemon"} {
+		if strings.Contains(s, never) {
+			t.Errorf("module.json names %q", never)
+		}
+	}
+}

modules/feh/cmd/feh-tools/manifest_test.go

@@ -0,0 +1,79 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+// feh's shape (novox/hq ADR 0208): no seat; it requires the X display on its own machine, carries
+// the wallpaper as its own archive (ADR 0205), owns ~/.fehbg pointing at it, and sets it once from
+// the session's start.
+
+func TestItRequiresTheXDisplayAndClaimsNothing(t *testing.T) {
+	m := readManifest(t)
+	if m.Module != "feh" || m.Seats != nil || m.Claims != nil {
+		t.Fatalf("module %q, seats %v, claims %v", m.Module, m.Seats, m.Claims)
+	}
+	if !reflect.DeepEqual(m.Requires, []string{"x11-display"}) {
+		t.Fatalf("requires: %v", m.Requires)
+	}
+	if present, absent := m.packages(); !reflect.DeepEqual(present, []string{"feh"}) || absent != nil {
+		t.Fatalf("packages: %v, absent %v", present, absent)
+	}
+}
+
+func TestTheWallpaperIsTheModulesOwnArchive(t *testing.T) {
+	m := readManifest(t)
+	a := m.resource(t, "wallpapers")
+	if a["type"] != "archive" || a["artifact"] != "wallpapers" || a["path"] != "${machine:account-home}/.local/share/feh/wallpapers" || a["owner"] != "${machine:account}" {
+		t.Fatalf("%v", a)
+	}
+	found := false
+	for _, art := range m.Build.Artifacts {
+		if art["name"] == "wallpapers" && art["kind"] == "archive" && art["from"] == "wallpaper" {
+			found = true
+		}
+	}
+	if !found {
+		t.Fatal("no archive artifact built from wallpaper/")
+	}
+	info, err := os.Stat(filepath.Join("..", "..", "wallpaper", "default.jpg"))
+	if err != nil || info.Size() == 0 {
+		t.Fatalf("the image: %v", err)
+	}
+}
+
+func TestFehbgIsOwnedAndTheSessionStartRunsItOnce(t *testing.T) {
+	m := readManifest(t)
+	m.sameAsSource(t, "fehbg", "files/fehbg")
+	f := m.resource(t, "fehbg")
+	if f["path"] != "${machine:account-home}/.fehbg" || f["mode"] != "0755" {
+		t.Fatalf("%v", f)
+	}
+	if c := f["content"].(string); !strings.Contains(c, "$HOME/.local/share/feh/wallpapers/default.jpg") || strings.Contains(c, ".hal") {
+		t.Fatalf("%s", c)
+	}
+	if len(m.Shell) != 1 || m.Shell[0].For != "xinitrc" || m.Shell[0].Slot != "normal" || strings.Count(m.Shell[0].Code, `"$HOME/.fehbg"`) != 1 {
+		t.Fatalf("%+v", m.Shell)
+	}
+}
+
+func TestTheKeyThatRestoresTheWallpaperIsAnI3DropIn(t *testing.T) {
+	m := readManifest(t)
+	m.sameAsSource(t, "i3-bindings", "files/i3/50-feh.conf")
+	if p := m.resource(t, "i3-bindings")["path"]; p != "${machine:account-home}/.config/i3/config.d/50-feh.conf" {
+		t.Fatalf("path: %v", p)
+	}
+	if c := m.resource(t, "i3-bindings")["content"].(string); !strings.Contains(c, "bindsym $mod+Shift+b exec --no-startup-id ~/.fehbg\n") {
+		t.Fatalf("%s", c)
+	}
+}
+
+func TestTheToolsAgreeWithTheManifest(t *testing.T) {
+	m := readManifest(t)
+	checkTheToolsAgree(t, m)
+	checkNoSecretsOrInstallationNames(t)
+}

modules/feh/cmd/feh-tools/session.go

@@ -0,0 +1,423 @@
+// The operator's graphical session, as a tool the node's runtime runs finds it (novox/hq ADR 0208).
+//
+// The runtime is a system service running as the operator account (ADR 0175): it has the account's
+// uid and none of the session's environment — no DISPLAY, no XAUTHORITY, no session bus. A tool that
+// draws on the screen or talks to the desktop's D-Bus must find them. It reads them from a process of
+// the account that is part of the session (the window manager first), the same thing `loginctl` and
+// a person's own shell would point at, and says where it found them.
+//
+// Long-lived programs a tool starts go to the account's own service manager through `systemd-run
+// --user`, never as children of the tool: the runtime's unit is a cgroup the service manager empties
+// whenever the runtime restarts, and a compositor or a clipboard owner started from inside it would
+// die with it.
+//
+// This file is the same in every desktop module that carries it; it moves into the Go SDK once a
+// second consumer outside the desktop wants it.
+package main
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"syscall"
+	"time"
+)
+
+// Where the session is looked for. Variables so a test can point them at a fake tree.
+var (
+	procRoot   = "/proc"
+	runUserDir = "/run/user"
+	x11Sockets = "/tmp/.X11-unix"
+)
+
+// sessionHolders are the processes whose environment is the session's, best first: the window
+// manager is the session, the rest are its children. Anything else carrying DISPLAY ranks after them.
+var sessionHolders = []string{"i3", "sway", "i3bar", "picom", "xss-lock", "dunst", "clipmenud", "xterm"}
+
+// sessionKeys are the variables a session carries that a tool hands on to what it runs.
+var sessionKeys = []string{"DISPLAY", "XAUTHORITY", "WAYLAND_DISPLAY", "DBUS_SESSION_BUS_ADDRESS",
+	"XDG_RUNTIME_DIR", "XDG_SESSION_ID", "I3SOCK"}
+
+// Session is what a tool needs to reach the operator's desktop.
+type Session struct {
+	UID        int    `json:"uid"`
+	Display    string `json:"display,omitempty"`
+	XAuthority string `json:"xauthority,omitempty"`
+	Wayland    string `json:"wayland_display,omitempty"`
+	Bus        string `json:"bus,omitempty"`
+	RuntimeDir string `json:"runtime_dir,omitempty"`
+	SessionID  string `json:"session_id,omitempty"`
+	I3Sock     string `json:"i3sock,omitempty"`
+	// From says where the values were found: the tool's own environment, a process, or the socket.
+	From string `json:"from"`
+}
+
+// ErrNoSession is answered by a tool that needs the desktop when nobody is logged in to it.
+var ErrNoSession = errors.New("no graphical session")
+
+// ErrTimedOut is what run answers for a command ended because it ran past its time.
+var ErrTimedOut = errors.New("timed out")
+
+// ErrNoBus is answered by a tool that needs the session bus when the account has none.
+var ErrNoBus = errors.New("no session bus")
+
+// operatorHome is the account's home: what the runtime was told, else the process's own.
+func operatorHome() string {
+	if h := strings.TrimSpace(os.Getenv("MESH_OPERATOR_HOME")); h != "" {
+		return h
+	}
+	h, _ := os.UserHomeDir()
+	return h
+}
+
+// findSession finds the graphical session of the account this tool runs as, or answers
+// ErrNoSession with what it looked at.
+func findSession() (Session, error) {
+	s := findEnvironment()
+	if s.Display == "" && s.Wayland == "" {
+		return s, fmt.Errorf("%w for uid %d on this machine: no process of the account carries DISPLAY "+
+			"or WAYLAND_DISPLAY, and no X server socket in %s has an authority file to go with it. "+
+			"Is anyone logged in to the desktop?", ErrNoSession, s.UID, x11Sockets)
+	}
+	return s, nil
+}
+
+// findBus finds the account's session bus, which a logged-in account has whether or not a desktop
+// is running.
+func findBus() (Session, error) {
+	s := findEnvironment()
+	if s.Bus == "" {
+		return s, fmt.Errorf("%w for uid %d: DBUS_SESSION_BUS_ADDRESS is not set and %s does not exist "+
+			"(the account is not logged in)", ErrNoBus, s.UID, filepath.Join(runUserDir, strconv.Itoa(s.UID), "bus"))
+	}
+	return s, nil
+}
+
+func findEnvironment() Session {
+	uid := os.Getuid()
+	s := Session{UID: uid}
+	own := map[string]string{}
+	for _, k := range sessionKeys {
+		own[k] = os.Getenv(k)
+	}
+	if own["DISPLAY"] != "" || own["WAYLAND_DISPLAY"] != "" {
+		s.fill(own)
+		s.From = "the tool's own environment"
+	} else if pid, comm, env, ok := sessionProcess(uid); ok {
+		s.fill(env)
+		s.From = fmt.Sprintf("process %s (pid %d)", comm, pid)
+	} else if display, ok := lonelyX11Socket(); ok {
+		if a := filepath.Join(operatorHome(), ".Xauthority"); exists(a) {
+			s.Display, s.XAuthority = display, a
+			s.From = "the X server socket and the account's ~/.Xauthority"
+		}
+		s.fill(own)
+	} else {
+		s.fill(own)
+		s.From = "nothing: no session found"
+	}
+	// The bus and the runtime directory are the account's, whether or not the process named them.
+	runtime := filepath.Join(runUserDir, strconv.Itoa(uid))
+	if s.RuntimeDir == "" && exists(runtime) {
+		s.RuntimeDir = runtime
+	}
+	if s.Bus == "" && s.RuntimeDir != "" && exists(filepath.Join(s.RuntimeDir, "bus")) {
+		s.Bus = "unix:path=" + filepath.Join(s.RuntimeDir, "bus")
+	}
+	return s
+}
+
+func (s *Session) fill(env map[string]string) {
+	set := func(dst *string, key string) {
+		if *dst == "" {
+			*dst = env[key]
+		}
+	}
+	set(&s.Display, "DISPLAY")
+	set(&s.XAuthority, "XAUTHORITY")
+	set(&s.Wayland, "WAYLAND_DISPLAY")
+	set(&s.Bus, "DBUS_SESSION_BUS_ADDRESS")
+	set(&s.RuntimeDir, "XDG_RUNTIME_DIR")
+	set(&s.SessionID, "XDG_SESSION_ID")
+	set(&s.I3Sock, "I3SOCK")
+}
+
+// sessionProcess is the best process of this uid whose environment names a display.
+func sessionProcess(uid int) (int, string, map[string]string, bool) {
+	entries, err := os.ReadDir(procRoot)
+	if err != nil {
+		return 0, "", nil, false
+	}
+	type candidate struct {
+		pid  int
+		comm string
+		env  map[string]string
+		rank int
+	}
+	var found []candidate
+	for _, e := range entries {
+		pid, err := strconv.Atoi(e.Name())
+		if err != nil {
+			continue
+		}
+		dir := filepath.Join(procRoot, e.Name())
+		if owner, ok := ownerOf(dir); !ok || owner != uid {
+			continue
+		}
+		raw, err := os.ReadFile(filepath.Join(dir, "environ"))
+		if err != nil {
+			continue
+		}
+		env := parseEnviron(raw)
+		if env["DISPLAY"] == "" && env["WAYLAND_DISPLAY"] == "" {
+			continue
+		}
+		comm := readTrimmed(filepath.Join(dir, "comm"))
+		rank := len(sessionHolders)
+		for i, h := range sessionHolders {
+			if h == comm {
+				rank = i
+				break
+			}
+		}
+		found = append(found, candidate{pid, comm, env, rank})
+	}
+	if len(found) == 0 {
+		return 0, "", nil, false
+	}
+	sort.Slice(found, func(i, j int) bool {
+		if found[i].rank != found[j].rank {
+			return found[i].rank < found[j].rank
+		}
+		return found[i].pid > found[j].pid // the newer of two equals
+	})
+	best := found[0]
+	return best.pid, best.comm, best.env, true
+}
+
+func parseEnviron(raw []byte) map[string]string {
+	env := map[string]string{}
+	for _, kv := range bytes.Split(raw, []byte{0}) {
+		if i := bytes.IndexByte(kv, '='); i > 0 {
+			env[string(kv[:i])] = string(kv[i+1:])
+		}
+	}
+	return env
+}
+
+func ownerOf(path string) (int, bool) {
+	info, err := os.Stat(path)
+	if err != nil {
+		return 0, false
+	}
+	st, ok := info.Sys().(*syscall.Stat_t)
+	if !ok {
+		return 0, false
+	}
+	return int(st.Uid), true
+}
+
+// lonelyX11Socket is the display of the one X server socket there is, when there is exactly one.
+func lonelyX11Socket() (string, bool) {
+	entries, err := os.ReadDir(x11Sockets)
+	if err != nil {
+		return "", false
+	}
+	var displays []string
+	for _, e := range entries {
+		if n := strings.TrimPrefix(e.Name(), "X"); n != e.Name() {
+			if _, err := strconv.Atoi(n); err == nil {
+				displays = append(displays, ":"+n)
+			}
+		}
+	}
+	if len(displays) != 1 {
+		return "", false
+	}
+	return displays[0], true
+}
+
+func readTrimmed(path string) string {
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(string(b))
+}
+
+func exists(path string) bool {
+	_, err := os.Stat(path)
+	return err == nil
+}
+
+// Env is this process's environment with the session's variables in place of its own.
+func (s Session) Env() []string {
+	drop := map[string]bool{}
+	for _, k := range sessionKeys {
+		drop[k] = true
+	}
+	var env []string
+	for _, kv := range os.Environ() {
+		if i := strings.IndexByte(kv, '='); i > 0 && drop[kv[:i]] {
+			continue
+		}
+		env = append(env, kv)
+	}
+	add := func(k, v string) {
+		if v != "" {
+			env = append(env, k+"="+v)
+		}
+	}
+	add("DISPLAY", s.Display)
+	add("XAUTHORITY", s.XAuthority)
+	add("WAYLAND_DISPLAY", s.Wayland)
+	add("DBUS_SESSION_BUS_ADDRESS", s.Bus)
+	add("XDG_RUNTIME_DIR", s.RuntimeDir)
+	add("XDG_SESSION_ID", s.SessionID)
+	add("I3SOCK", s.I3Sock)
+	return env
+}
+
+// mostOutput bounds what a command may answer with, per stream.
+const mostOutput = 256 << 10
+
+// Result is what a command did.
+type Result struct {
+	Stdout    string `json:"stdout"`
+	Stderr    string `json:"stderr,omitempty"`
+	Code      int    `json:"code"`
+	Truncated bool   `json:"truncated,omitempty"`
+}
+
+// run runs a command in the session's environment, its input given, ended with everything it
+// started after timeout. A command that is not installed is an error naming it; one that exits
+// non-zero is a Result with its code, for the caller to judge.
+func (s Session) run(timeout time.Duration, stdin string, name string, args ...string) (Result, error) {
+	path, err := exec.LookPath(name)
+	if err != nil {
+		return Result{}, fmt.Errorf("%s is not installed on this machine", name)
+	}
+	cmd := exec.Command(path, args...)
+	cmd.Env = s.Env()
+	if home := operatorHome(); exists(home) {
+		cmd.Dir = home
+	}
+	if stdin != "" {
+		cmd.Stdin = strings.NewReader(stdin)
+	}
+	var out, errOut capped
+	cmd.Stdout, cmd.Stderr = &out, &errOut
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+	if err := cmd.Start(); err != nil {
+		return Result{}, fmt.Errorf("%s: %w", name, err)
+	}
+	done := make(chan error, 1)
+	go func() { done <- cmd.Wait() }()
+	select {
+	case err = <-done:
+	case <-time.After(timeout):
+		_ = syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)
+		<-done
+		return Result{Stdout: out.String(), Stderr: errOut.String()},
+			fmt.Errorf("%s did not finish within %s and was ended: %w", name, timeout, ErrTimedOut)
+	}
+	r := Result{Stdout: out.String(), Stderr: errOut.String(), Truncated: out.cut || errOut.cut}
+	var exit *exec.ExitError
+	if errors.As(err, &exit) {
+		r.Code = exit.ExitCode()
+	} else if err != nil {
+		return r, fmt.Errorf("%s: %w", name, err)
+	}
+	return r, nil
+}
+
+// detach starts a long-lived program under the account's own service manager, as a transient unit
+// that carries the session's display, so it outlives the runtime that asked for it. A unit already
+// running under the same name is stopped first, so a fixed name means "at most one".
+func (s Session) detach(unit string, args ...string) error {
+	if s.RuntimeDir == "" {
+		return fmt.Errorf("%w: the account's runtime directory is missing, so its service manager "+
+			"cannot be reached", ErrNoBus)
+	}
+	_, _ = s.run(5*time.Second, "", "systemctl", "--user", "stop", unit+".service")
+	call := []string{"--user", "--collect", "--quiet", "--unit=" + unit}
+	for _, kv := range [][2]string{{"DISPLAY", s.Display}, {"XAUTHORITY", s.XAuthority},
+		{"WAYLAND_DISPLAY", s.Wayland}, {"XDG_SESSION_ID", s.SessionID}, {"I3SOCK", s.I3Sock}} {
+		if kv[1] != "" {
+			call = append(call, "--setenv="+kv[0]+"="+kv[1])
+		}
+	}
+	call = append(call, "--")
+	call = append(call, args...)
+	r, err := s.run(10*time.Second, "", "systemd-run", call...)
+	if err != nil {
+		return err
+	}
+	if r.Code != 0 {
+		return fmt.Errorf("systemd-run %s: %s", unit, strings.TrimSpace(r.Stderr))
+	}
+	return nil
+}
+
+// uniqueUnit is a transient unit name that will not collide with an earlier one.
+func uniqueUnit(prefix string) string {
+	return fmt.Sprintf("%s-%d", prefix, time.Now().UnixNano())
+}
+
+type capped struct {
+	bytes.Buffer
+	cut bool
+}
+
+func (c *capped) Write(p []byte) (int, error) {
+	if room := mostOutput - c.Len(); room < len(p) {
+		if room > 0 {
+			c.Buffer.Write(p[:room])
+		}
+		c.cut = true
+		return len(p), nil
+	}
+	return c.Buffer.Write(p)
+}
+
+// processesOf are the pids of this uid's processes whose command name is comm, oldest first.
+func processesOf(comm string) []int {
+	entries, err := os.ReadDir(procRoot)
+	if err != nil {
+		return nil
+	}
+	uid := os.Getuid()
+	var pids []int
+	for _, e := range entries {
+		pid, err := strconv.Atoi(e.Name())
+		if err != nil {
+			continue
+		}
+		dir := filepath.Join(procRoot, e.Name())
+		if owner, ok := ownerOf(dir); !ok || owner != uid {
+			continue
+		}
+		if readTrimmed(filepath.Join(dir, "comm")) == comm {
+			pids = append(pids, pid)
+		}
+	}
+	sort.Ints(pids)
+	return pids
+}
+
+// signalAll sends sig to every process of this uid named comm, and answers the pids it reached.
+func signalAll(comm string, sig syscall.Signal) []int {
+	var reached []int
+	for _, pid := range processesOf(comm) {
+		if syscall.Kill(pid, sig) == nil {
+			reached = append(reached, pid)
+		}
+	}
+	return reached
+}

modules/feh/cmd/feh-tools/session_test.go

@@ -0,0 +1,174 @@
+package main
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+)
+
+// fakeMachine points the session finder at a temporary /proc, /run/user and X socket directory, with
+// none of the test process's own session variables, and gives back the root.
+func fakeMachine(t *testing.T) string {
+	t.Helper()
+	root := t.TempDir()
+	procRoot, runUserDir, x11Sockets = filepath.Join(root, "proc"), filepath.Join(root, "run-user"), filepath.Join(root, "x11")
+	for _, d := range []string{procRoot, runUserDir, x11Sockets} {
+		if err := os.MkdirAll(d, 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	for _, k := range sessionKeys {
+		t.Setenv(k, "")
+	}
+	t.Setenv("MESH_OPERATOR_HOME", filepath.Join(root, "home"))
+	t.Cleanup(func() { procRoot, runUserDir, x11Sockets = "/proc", "/run/user", "/tmp/.X11-unix" })
+	return root
+}
+
+func fakeProcess(t *testing.T, pid int, comm string, env ...string) {
+	t.Helper()
+	dir := filepath.Join(procRoot, strconv.Itoa(pid))
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "comm"), []byte(comm+"\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "environ"), []byte(strings.Join(env, "\x00")+"\x00"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestTheSessionIsReadFromTheWindowManagerBeforeAnyOtherProcess(t *testing.T) {
+	fakeMachine(t)
+	fakeProcess(t, 900, "xterm", "DISPLAY=:9", "XAUTHORITY=/elsewhere")
+	fakeProcess(t, 100, "i3", "DISPLAY=:1", "XAUTHORITY=/home/op/.Xauthority",
+		"DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus", "XDG_SESSION_ID=3", "SECRET_TOKEN=never-copied")
+	fakeProcess(t, 50, "bash", "PATH=/usr/bin")
+	s, err := findSession()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if s.Display != ":1" || s.XAuthority != "/home/op/.Xauthority" || s.SessionID != "3" || !strings.Contains(s.From, "i3 (pid 100)") {
+		t.Fatalf("the window manager's environment: %+v", s)
+	}
+	for _, kv := range s.Env() {
+		if strings.HasPrefix(kv, "SECRET_TOKEN=") {
+			t.Fatal("a variable of the session process that is not a session variable was handed on")
+		}
+	}
+}
+
+func TestAnyProcessCarryingADisplayServesWhenTheWindowManagerIsNotFound(t *testing.T) {
+	fakeMachine(t)
+	fakeProcess(t, 10, "firefox", "DISPLAY=:0")
+	fakeProcess(t, 20, "firefox", "DISPLAY=:2")
+	s, err := findSession()
+	if err != nil || s.Display != ":2" {
+		t.Fatalf("the newest of two equals: %+v, %v", s, err)
+	}
+}
+
+func TestNoSessionIsAClearAnswerNotAGuess(t *testing.T) {
+	fakeMachine(t)
+	fakeProcess(t, 10, "sshd", "PATH=/usr/bin")
+	_, err := findSession()
+	if !errors.Is(err, ErrNoSession) || !strings.Contains(err.Error(), "logged in to the desktop") {
+		t.Fatalf("no session: %v", err)
+	}
+}
+
+func TestOneXSocketAndTheAccountsAuthorityFileAreASession(t *testing.T) {
+	root := fakeMachine(t)
+	if err := os.WriteFile(filepath.Join(x11Sockets, "X0"), nil, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Join(root, "home"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(root, "home", ".Xauthority"), nil, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	s, err := findSession()
+	if err != nil || s.Display != ":0" || !strings.HasSuffix(s.XAuthority, "/home/.Xauthority") {
+		t.Fatalf("socket and authority: %+v, %v", s, err)
+	}
+}
+
+func TestTheBusIsTheAccountsRuntimeDirectoryWhenNoProcessNamesIt(t *testing.T) {
+	fakeMachine(t)
+	runtime := filepath.Join(runUserDir, strconv.Itoa(os.Getuid()))
+	if _, err := findBus(); !errors.Is(err, ErrNoBus) {
+		t.Fatalf("no runtime directory is no bus: %v", err)
+	}
+	if err := os.MkdirAll(runtime, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(runtime, "bus"), nil, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	s, err := findBus()
+	if err != nil || s.Bus != "unix:path="+filepath.Join(runtime, "bus") || s.RuntimeDir != runtime {
+		t.Fatalf("bus: %+v, %v", s, err)
+	}
+	env := strings.Join(s.Env(), "\n")
+	if !strings.Contains(env, "XDG_RUNTIME_DIR="+runtime) || !strings.Contains(env, "DBUS_SESSION_BUS_ADDRESS=unix:path=") {
+		t.Fatalf("the bus is handed on: %s", env)
+	}
+}
+
+func TestACommandIsBoundedAndANonZeroExitIsAResult(t *testing.T) {
+	fakeMachine(t)
+	s := Session{}
+	r, err := s.run(5*time.Second, "in", "sh", "-c", "cat; echo err >&2; exit 3")
+	if err != nil || r.Stdout != "in" || r.Code != 3 || strings.TrimSpace(r.Stderr) != "err" {
+		t.Fatalf("result: %+v, %v", r, err)
+	}
+	start := time.Now()
+	if _, err := s.run(200*time.Millisecond, "", "sh", "-c", "sleep 30 & sleep 30"); err == nil || time.Since(start) > 5*time.Second {
+		t.Fatalf("a command past its time is ended with what it started: %v after %s", err, time.Since(start))
+	}
+	if _, err := s.run(time.Second, "", "no-such-program-here"); err == nil || !strings.Contains(err.Error(), "not installed") {
+		t.Fatalf("a missing program: %v", err)
+	}
+}
+
+func TestDetachAsksTheAccountsServiceManagerWithTheSessionsDisplay(t *testing.T) {
+	fakeMachine(t)
+	bin := fakeBinaries(t, map[string]string{
+		"systemctl":   `echo "systemctl $*" >> "$LOG"`,
+		"systemd-run": `echo "systemd-run $*" >> "$LOG"`,
+	})
+	log := filepath.Join(bin, "log")
+	t.Setenv("LOG", log)
+	s := Session{Display: ":1", XAuthority: "/x", RuntimeDir: "/run/user/1"}
+	if err := s.detach("picom-session", "picom", "--config", "/c"); err != nil {
+		t.Fatal(err)
+	}
+	got, _ := os.ReadFile(log)
+	want := "systemctl --user stop picom-session.service\n" +
+		"systemd-run --user --collect --quiet --unit=picom-session --setenv=DISPLAY=:1 --setenv=XAUTHORITY=/x -- picom --config /c\n"
+	if string(got) != want {
+		t.Fatalf("detach ran:\n%s\nwant:\n%s", got, want)
+	}
+	if err := (Session{}).detach("x", "y"); !errors.Is(err, ErrNoBus) {
+		t.Fatalf("no runtime directory: %v", err)
+	}
+}
+
+// fakeBinaries puts shell scripts named for programs first on PATH, and answers their directory.
+func fakeBinaries(t *testing.T, scripts map[string]string) string {
+	t.Helper()
+	dir := t.TempDir()
+	for name, body := range scripts {
+		if err := os.WriteFile(filepath.Join(dir, name), []byte("#!/bin/sh\n"+body+"\n"), 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	t.Setenv("PATH", dir+string(os.PathListSeparator)+os.Getenv("PATH"))
+	return dir
+}

modules/feh/cmd/feh-tools/wallpaper.go

@@ -0,0 +1,174 @@
+package main
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"time"
+)
+
+// modes are feh's background modes, by the word feh_set takes.
+var modes = []string{"fill", "center", "max", "scale", "tile"}
+
+// Wallpaper is images and how they are laid on the screens.
+type Wallpaper struct {
+	Images []string `json:"images"`
+	Mode   string   `json:"mode"`
+	At     string   `json:"at,omitempty"`
+}
+
+func fehbg() string { return filepath.Join(operatorHome(), ".fehbg") }
+
+// sessionRecord is where feh_set notes what it put up, for feh_current: in the runtime directory,
+// so it lasts exactly as long as the login, like the wallpaper itself.
+func sessionRecord(s Session) string {
+	if s.RuntimeDir == "" {
+		return ""
+	}
+	return filepath.Join(s.RuntimeDir, "feh", "current.json")
+}
+
+// SetResult is what feh_set answers.
+type SetResult struct {
+	Wallpaper
+	Note string `json:"note"`
+}
+
+// Set puts images up as the wallpaper for this session.
+func Set(images []string, mode string) (SetResult, error) {
+	if mode == "" {
+		mode = "fill"
+	}
+	known := false
+	for _, m := range modes {
+		known = known || m == mode
+	}
+	if !known {
+		return SetResult{}, fmt.Errorf("mode %q is one of %s", mode, strings.Join(modes, ", "))
+	}
+	if len(images) == 0 {
+		return SetResult{}, errors.New("images is required: at least one image")
+	}
+	var paths []string
+	for _, img := range images {
+		p := img
+		if strings.HasPrefix(p, "~/") {
+			p = filepath.Join(operatorHome(), p[2:])
+		}
+		if !filepath.IsAbs(p) {
+			p = filepath.Join(operatorHome(), p)
+		}
+		info, err := os.Stat(p)
+		if err != nil {
+			return SetResult{}, fmt.Errorf("image %s: %w", img, err)
+		}
+		if info.IsDir() {
+			return SetResult{}, fmt.Errorf("image %s is a directory", img)
+		}
+		paths = append(paths, p)
+	}
+	s, err := findSession()
+	if err != nil {
+		return SetResult{}, err
+	}
+	args := append([]string{"--no-fehbg", "--bg-" + mode}, paths...)
+	r, err := s.run(15*time.Second, "", "feh", args...)
+	if err != nil {
+		return SetResult{}, err
+	}
+	if r.Code != 0 {
+		return SetResult{}, fmt.Errorf("feh: %s", strings.TrimSpace(r.Stderr))
+	}
+	w := Wallpaper{Images: paths, Mode: mode, At: time.Now().Format(time.RFC3339)}
+	if rec := sessionRecord(s); rec != "" {
+		if err := os.MkdirAll(filepath.Dir(rec), 0o700); err == nil {
+			raw, _ := json.Marshal(w)
+			_ = os.WriteFile(rec, raw, 0o600)
+		}
+	}
+	return SetResult{Wallpaper: w, Note: "for this session; the declared wallpaper returns at the next login"}, nil
+}
+
+// CurrentResult is what feh_current answers.
+type CurrentResult struct {
+	Declared *Wallpaper `json:"declared"`
+	Session  *Wallpaper `json:"session,omitempty"`
+}
+
+var bgMode = regexp.MustCompile(`--bg-(fill|center|max|scale|tile)\b`)
+
+// Current is the declared wallpaper and the one set in this session.
+func Current() (CurrentResult, error) {
+	var out CurrentResult
+	if raw, err := os.ReadFile(fehbg()); err == nil {
+		out.Declared = parseFehbg(string(raw), operatorHome())
+	}
+	if rec := sessionRecord(findEnvironment()); rec != "" {
+		if raw, err := os.ReadFile(rec); err == nil {
+			var w Wallpaper
+			if json.Unmarshal(raw, &w) == nil {
+				out.Session = &w
+			}
+		}
+	}
+	return out, nil
+}
+
+// parseFehbg reads the feh line of a ~/.fehbg: its mode and its images, with $HOME expanded.
+func parseFehbg(script, home string) *Wallpaper {
+	for _, line := range strings.Split(script, "\n") {
+		line = strings.TrimSpace(line)
+		if !strings.HasPrefix(line, "feh ") {
+			continue
+		}
+		w := &Wallpaper{Images: []string{}}
+		if m := bgMode.FindStringSubmatch(line); m != nil {
+			w.Mode = m[1]
+		}
+		for _, word := range shellWords(line)[1:] {
+			if strings.HasPrefix(word, "-") {
+				continue
+			}
+			word = strings.ReplaceAll(strings.ReplaceAll(word, "${HOME}", home), "$HOME", home)
+			w.Images = append(w.Images, word)
+		}
+		return w
+	}
+	return nil
+}
+
+// shellWords splits a simple command line on blanks, honouring single and double quotes.
+func shellWords(line string) []string {
+	var words []string
+	var cur strings.Builder
+	var quote byte
+	in := false
+	for i := 0; i < len(line); i++ {
+		c := line[i]
+		switch {
+		case quote != 0 && c == quote:
+			quote = 0
+		case quote != 0:
+			cur.WriteByte(c)
+		case c == '\'' || c == '"':
+			quote, in = c, true
+		case c == ' ' || c == '\t':
+			if in {
+				words = append(words, cur.String())
+				cur.Reset()
+				in = false
+			}
+		default:
+			cur.WriteByte(c)
+			in = true
+		}
+	}
+	if in {
+		words = append(words, cur.String())
+	}
+	return words
+}

modules/feh/cmd/feh-tools/wallpaper_test.go

@@ -0,0 +1,92 @@
+package main
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strconv"
+	"strings"
+	"testing"
+)
+
+const nobody = 4194400
+
+func TestTheDeclaredWallpaperIsReadFromTheModulesFehbg(t *testing.T) {
+	raw, err := os.ReadFile(filepath.Join("..", "..", "files", "fehbg"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	w := parseFehbg(string(raw), "/home/op")
+	if w == nil || w.Mode != "fill" || !reflect.DeepEqual(w.Images, []string{"/home/op/.local/share/feh/wallpapers/default.jpg"}) {
+		t.Fatalf("%+v", w)
+	}
+	// The form feh writes itself, single-quoted, two monitors.
+	w = parseFehbg("#!/bin/sh\nfeh --no-fehbg --bg-center '/a b/one.png' '/two.png' \n", "/home/op")
+	if w.Mode != "center" || !reflect.DeepEqual(w.Images, []string{"/a b/one.png", "/two.png"}) {
+		t.Fatalf("%+v", w)
+	}
+	if parseFehbg("#!/bin/sh\n", "/h") != nil {
+		t.Fatal("a file without feh declares a wallpaper")
+	}
+}
+
+func TestSetPutsTheImagesUpForThisSessionAndCurrentSaysSo(t *testing.T) {
+	root := fakeMachine(t)
+	fakeProcess(t, nobody, "i3", "DISPLAY=:1")
+	if err := os.MkdirAll(filepath.Join(runUserDir, strconv.Itoa(os.Getuid())), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	home := filepath.Join(root, "home")
+	for _, f := range []string{"Pictures/a.jpg", "Pictures/b.jpg"} {
+		if err := os.MkdirAll(filepath.Dir(filepath.Join(home, f)), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(home, f), []byte("jpg"), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	src, _ := os.ReadFile(filepath.Join("..", "..", "files", "fehbg"))
+	if err := os.WriteFile(filepath.Join(home, ".fehbg"), src, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	bin := fakeBinaries(t, map[string]string{"feh": `echo "$* DISPLAY=$DISPLAY" > "$LOG"`})
+	t.Setenv("LOG", filepath.Join(bin, "log"))
+	got, err := Set([]string{"~/Pictures/a.jpg", "Pictures/b.jpg"}, "scale")
+	if err != nil || !strings.Contains(got.Note, "next login") {
+		t.Fatalf("%+v, %v", got, err)
+	}
+	asked, _ := os.ReadFile(filepath.Join(bin, "log"))
+	want := "--no-fehbg --bg-scale " + filepath.Join(home, "Pictures/a.jpg") + " " + filepath.Join(home, "Pictures/b.jpg") + " DISPLAY=:1\n"
+	if string(asked) != want {
+		t.Fatalf("feh was asked %q, want %q", asked, want)
+	}
+	cur, err := Current()
+	if err != nil || cur.Declared == nil || cur.Session == nil || cur.Session.Mode != "scale" || len(cur.Session.Images) != 2 ||
+		cur.Declared.Images[0] != filepath.Join(home, ".local/share/feh/wallpapers/default.jpg") {
+		t.Fatalf("%+v, %v", cur, err)
+	}
+}
+
+func TestSetRefusesWhatFehCannotShow(t *testing.T) {
+	fakeMachine(t)
+	if _, err := Set([]string{"/nowhere.jpg"}, ""); err == nil {
+		t.Fatal("a missing image was accepted")
+	}
+	if _, err := Set([]string{"/"}, ""); err == nil {
+		t.Fatal("a directory was accepted")
+	}
+	if _, err := Set([]string{"/etc/hostname"}, "stretch"); err == nil {
+		t.Fatal("an unknown mode was accepted")
+	}
+	if _, err := Set(nil, ""); err == nil {
+		t.Fatal("no image was accepted")
+	}
+	f := filepath.Join(t.TempDir(), "x.jpg")
+	if err := os.WriteFile(f, nil, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := Set([]string{f}, ""); !errors.Is(err, ErrNoSession) {
+		t.Fatalf("without a session: %v", err)
+	}
+}

modules/feh/files/fehbg

@@ -0,0 +1,6 @@
+#!/bin/sh
+# The wallpaper (module feh, novox/hq ADR 0208). Owned by the mesh: replaced at every push. The
+# session's start runs it, and so may anything that wants the declared wallpaper back. The image is
+# the module's own, in ~/.local/share/feh/wallpapers. feh_set changes the wallpaper for a session
+# without touching this file.
+feh --no-fehbg --bg-fill "$HOME/.local/share/feh/wallpapers/default.jpg"

modules/feh/files/i3/50-feh.conf

@@ -0,0 +1,3 @@
+# The wallpaper's key (module feh, novox/hq ADR 0208). Owned by the mesh: replaced at every push.
+# It puts the declared wallpaper back, after a monitor change or a wallpaper set for the session.
+bindsym $mod+Shift+b exec --no-startup-id ~/.fehbg

modules/feh/go.mod

@@ -0,0 +1,5 @@
+module feh
+
+go 1.22
+
+require git.novox.be/novox/mesh-sdk/go v0.1.7

modules/feh/go.sum

@@ -0,0 +1,2 @@
+git.novox.be/novox/mesh-sdk/go v0.1.7 h1:C0sTQmtTiyYH7bnqZb7PusXnqA37gKuT7Nqjn9gG47w=
+git.novox.be/novox/mesh-sdk/go v0.1.7/go.mod h1:GFuZUElBZ9A++mxgIKo97aXXo+kV0uJ/UkbhQPPIbrY=

modules/feh/module.json

@@ -0,0 +1,71 @@
+{
+  "module": "feh",
+  "version": "1",
+  "capabilities": [
+    "package-manager"
+  ],
+  "requires": [
+    "x11-display"
+  ],
+  "tools": [
+    "feh_set",
+    "feh_current"
+  ],
+  "shell": [
+    {
+      "for": "xinitrc",
+      "slot": "normal",
+      "code": "# The wallpaper (module feh, novox/hq ADR 0208): the declared one, set once per session.\n\"$HOME/.fehbg\"\n"
+    }
+  ],
+  "resources": [
+    {
+      "id": "package",
+      "type": "package",
+      "package": "feh"
+    },
+    {
+      "id": "wallpapers",
+      "type": "archive",
+      "path": "${machine:account-home}/.local/share/feh/wallpapers",
+      "owner": "${machine:account}",
+      "artifact": "wallpapers"
+    },
+    {
+      "id": "fehbg",
+      "type": "file",
+      "path": "${machine:account-home}/.fehbg",
+      "owner": "${machine:account}",
+      "mode": "0755",
+      "content": "#!/bin/sh\n# The wallpaper (module feh, novox/hq ADR 0208). Owned by the mesh: replaced at every push. The\n# session's start runs it, and so may anything that wants the declared wallpaper back. The image is\n# the module's own, in ~/.local/share/feh/wallpapers. feh_set changes the wallpaper for a session\n# without touching this file.\nfeh --no-fehbg --bg-fill \"$HOME/.local/share/feh/wallpapers/default.jpg\"\n"
+    },
+    {
+      "id": "i3-bindings",
+      "type": "file",
+      "path": "${machine:account-home}/.config/i3/config.d/50-feh.conf",
+      "owner": "${machine:account}",
+      "mode": "0644",
+      "content": "# The wallpaper's key (module feh, novox/hq ADR 0208). Owned by the mesh: replaced at every push.\n# It puts the declared wallpaper back, after a monitor change or a wallpaper set for the session.\nbindsym $mod+Shift+b exec --no-startup-id ~/.fehbg\n"
+    }
+  ],
+  "build": {
+    "artifacts": [
+      {
+        "name": "wallpapers",
+        "kind": "archive",
+        "from": "wallpaper"
+      },
+      {
+        "name": "tools",
+        "kind": "bundle",
+        "language": "go",
+        "system": "arch",
+        "from": "cmd/feh-tools",
+        "binary": "feh-tools",
+        "loads": [
+          "feh-tools"
+        ]
+      }
+    ]
+  }
+}

modules/gnome-keyring/README.md

@@ -0,0 +1,101 @@
+# gnome-keyring
+
+The secret service as a module (novox/hq ADR 0208, ADR 0102).
+
+- Installs `gnome-keyring` (it brings `gcr-4`, whose ssh agent this uses), `libsecret` (the client
+  library and `secret-tool`) and `seahorse` (the keyrings' manager, for the operator).
+- Claims the mesh's `node-secret-service` seat (no verbs yet, ADR 0208 §2). It requires no display:
+  the secret service is a D-Bus service, and a Wayland session uses the same module.
+- **Writes the PAM lines into the stacks, never over them** (ADR 0102). Each is a marked block at the
+  end of the file; every other line stays the distribution's.
+  - `/etc/pam.d/login`: `auth optional pam_gnome_keyring.so` and
+    `session optional pam_gnome_keyring.so auto_start`. The login manager's stack includes `login`,
+    so the password typed at the login screen unlocks the login keyring, and the login session starts
+    the daemon.
+  - `/etc/pam.d/passwd`: `password optional pam_gnome_keyring.so`, so changing the account's password
+    changes the keyring's, and the next login still unlocks it.
+- **Starts no daemon.** PAM starts it at login, and D-Bus would if PAM had not.
+- Names gcr's ssh agent socket for the session, in the `xinitrc` slot `first`: `SSH_AUTH_SOCK` is
+  `$XDG_RUNTIME_DIR/gcr/ssh`. The agent itself is `gcr-ssh-agent.socket`, a user unit the package
+  enables by preset.
+
+## Tools
+
+None reads a secret. They ask the Secret Service for names, counts and lock states, and the agent for
+fingerprints.
+
+| tool | does |
+|---|---|
+| `gnome_keyring_unlocked` | the login and default keyrings, locked or not; whether the daemon runs |
+| `gnome_keyring_lock` | lock a keyring now (login by default); unlocking stays the operator's |
+| `gnome_keyring_collections` | every keyring: id, label, locked, item count, created, changed, default |
+| `gnome_keyring_ssh_keys` | the agent's keys by fingerprint, size, type and comment |
+
+## What it improves on what was found
+
+- **The desktop's login unlocks the keyring.** Its `/etc/pam.d/login` had no keyring lines, so the
+  keyring stayed locked after every login, and a script prompted for the password to unlock it. Both
+  workstations now get the same lines.
+- **One daemon.** The session's start ran `gnome-keyring-daemon --start` a second time, asking for an
+  ssh component that gnome-keyring no longer has, and the window manager ran an unlock-prompt script.
+  Both go.
+- **The session has an ssh agent.** The found `export SSH_AUTH_SOCK` exported nothing: the second
+  daemon printed no socket. The session's processes had no agent, although gcr's was listening.
+
+## The default keyring is not the login keyring
+
+On both workstations, measured on 2026-10-04, the default keyring, where programs store new secrets,
+is a second keyring, `Default_keyring`. The login keyring holds one item at most. PAM unlocks only the
+login keyring. Another keyring opens with it only if its password is stored in the login keyring
+("unlock automatically"). On the desktop the login keyring was locked and the default one unlocked,
+which the unlock-prompt script did.
+
+After the first login with this module: `gnome_keyring_unlocked` shows both. If the default keyring
+is still locked, choose one, once, in `seahorse`:
+
+- tick its *unlock automatically* when prompted;
+- or move its items into the login keyring and make that the default.
+
+Which keyring is the default is the operator's data, never the module's.
+
+## Blockers and a proposal
+
+**`SSH_AUTH_SOCK` belongs in the account's environment, and ADR 0203 cannot say it yet.** The value
+is a path under the account's runtime directory (`/run/user/<uid>`). ADR 0203 forbids `$` in a
+contributed value, and no `${machine:…}` fact names that directory. So today the variable reaches
+only the X session and what it starts, through the `xinitrc` slot. An ssh login, the login shell's
+`execute` and the user manager's services do not get it.
+
+**Proposed:** a machine fact `${machine:account-runtime-dir}`, resolved like `${machine:account-home}`
+from the account's uid. The variable then becomes an environment contribution:
+
+> `environment.variables.SSH_AUTH_SOCK` = `${machine:account-runtime-dir}/gcr/ssh`
+
+The slot contribution then goes. That is a progressive insight on ADR 0203, or a small record of its
+own. It changes the controller's machine facts, not this module's shape.
+
+**User-scoped units (mesh-host #72).** `gcr-ssh-agent.socket` and `gnome-keyring-daemon.socket` are
+enabled by the package's presets on both workstations, and nothing in the mesh asserts it. Once user
+units ship, this module should declare both enabled.
+
+## What it leaves as found
+
+- The keyrings themselves (`~/.local/share/keyrings/`): the operator's data, never touched.
+- `~/.config/i3/unlock-keyring.sh`, the unlock-prompt script.
+
+## Migration (ADR 0182)
+
+1. **On the laptop,** `/etc/pam.d/login` already has the two lines outside any block. After the first
+   push they are there twice. Delete the two hand-written ones, outside the `# BEGIN mesh` block.
+2. Once the `xorg` module writes the session's start, delete from your own part of `~/.xinitrc` the
+   `eval $(/usr/bin/gnome-keyring-daemon --start …)` line and the `export SSH_AUTH_SOCK` after it.
+3. Once the `i3` module carries the main configuration, its `exec … unlock-keyring.sh` line is gone.
+   Delete `~/.config/i3/unlock-keyring.sh`.
+4. **On the desktop,** log in again after the first push. The keyring is unlocked by the login from
+   then on.
+
+## Blockers
+
+- `node-secret-service` and the `xinitrc` slot are ADR 0208's. Until the controller knows them,
+  `mctl` reads them as unknown.
+- The environment fact above, and user-scoped units (mesh-host #72).

modules/gnome-keyring/cmd/gnome-keyring-tools/args.go

@@ -0,0 +1,97 @@
+// Reading a tool's arguments: JSON numbers arrive as float64, and a missing argument is its default.
+// The same in every desktop module that carries it.
+package main
+
+import (
+	"fmt"
+	"math"
+	"strings"
+	"time"
+)
+
+// text is a string argument, trimmed; required says an empty one is refused.
+func text(args map[string]any, key string, required bool) (string, error) {
+	v, present := args[key]
+	if !present || v == nil {
+		if required {
+			return "", fmt.Errorf("%s is required", key)
+		}
+		return "", nil
+	}
+	s, ok := v.(string)
+	if !ok {
+		return "", fmt.Errorf("%s is a string, not %T", key, v)
+	}
+	s = strings.TrimSpace(s)
+	if s == "" && required {
+		return "", fmt.Errorf("%s is required", key)
+	}
+	return s, nil
+}
+
+// whole is a whole-number argument within [least, most], or def when absent.
+func whole(args map[string]any, key string, def, least, most int) (int, error) {
+	v, present := args[key]
+	if !present || v == nil {
+		return def, nil
+	}
+	f, ok := v.(float64)
+	if !ok {
+		if i, isInt := v.(int); isInt {
+			f = float64(i)
+		} else {
+			return 0, fmt.Errorf("%s is a number, not %T", key, v)
+		}
+	}
+	if f != math.Trunc(f) {
+		return 0, fmt.Errorf("%s is a whole number, not %v", key, f)
+	}
+	n := int(f)
+	if n < least || n > most {
+		return 0, fmt.Errorf("%s is %d; it is between %d and %d", key, n, least, most)
+	}
+	return n, nil
+}
+
+// flag is a boolean argument, or def when absent.
+func flag(args map[string]any, key string, def bool) (bool, error) {
+	v, present := args[key]
+	if !present || v == nil {
+		return def, nil
+	}
+	b, ok := v.(bool)
+	if !ok {
+		return false, fmt.Errorf("%s is true or false, not %T", key, v)
+	}
+	return b, nil
+}
+
+// texts is a list-of-strings argument.
+func texts(args map[string]any, key string) ([]string, error) {
+	v, present := args[key]
+	if !present || v == nil {
+		return nil, nil
+	}
+	list, ok := v.([]any)
+	if !ok {
+		if ss, isStrings := v.([]string); isStrings {
+			return ss, nil
+		}
+		return nil, fmt.Errorf("%s is a list of strings, not %T", key, v)
+	}
+	out := make([]string, 0, len(list))
+	for i, item := range list {
+		s, ok := item.(string)
+		if !ok {
+			return nil, fmt.Errorf("%s[%d] is a string, not %T", key, i, item)
+		}
+		out = append(out, s)
+	}
+	return out, nil
+}
+
+// seconds is a timeout argument in seconds, defaulted and bounded below the runtime's call limit.
+func seconds(args map[string]any, key string, def, most int) (time.Duration, error) {
+	n, err := whole(args, key, def, 1, most)
+	return time.Duration(n) * time.Second, err
+}

modules/gnome-keyring/cmd/gnome-keyring-tools/keyring.go

@@ -0,0 +1,260 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+)
+
+const (
+	service       = "org.freedesktop.secrets"
+	servicePath   = "/org/freedesktop/secrets"
+	collectionDir = "/org/freedesktop/secrets/collection/"
+	busTimeout    = 10 * time.Second
+)
+
+// busctl runs one busctl call on the account's session bus and answers its JSON.
+func busctl(s Session, args ...string) (json.RawMessage, error) {
+	r, err := s.run(busTimeout, "", "busctl", append([]string{"--user", "--json=short"}, args...)...)
+	if err != nil {
+		return nil, err
+	}
+	if r.Code != 0 {
+		return nil, fmt.Errorf("the secret service: %s", strings.TrimSpace(r.Stderr))
+	}
+	var v struct {
+		Data json.RawMessage `json:"data"`
+	}
+	if err := json.Unmarshal([]byte(r.Stdout), &v); err != nil {
+		return nil, fmt.Errorf("busctl answered no JSON: %w", err)
+	}
+	return v.Data, nil
+}
+
+// collectionID is the part of a collection's object path after .../collection/, unescaped the way
+// the Secret Service escapes it ("_5f" is "_").
+func collectionID(path string) string { return strings.TrimPrefix(path, collectionDir) }
+
+func collectionPath(id string) string { return collectionDir + id }
+
+var validID = regexp.MustCompile(`^[A-Za-z0-9_]+$`)
+
+// Collection is one keyring.
+type Collection struct {
+	ID       string `json:"id"`
+	Label    string `json:"label"`
+	Locked   bool   `json:"locked"`
+	Items    int    `json:"items"`
+	Created  string `json:"created,omitempty"`
+	Modified string `json:"modified,omitempty"`
+	Default  bool   `json:"default,omitempty"`
+}
+
+// CollectionsResult is what gnome_keyring_collections answers.
+type CollectionsResult struct {
+	Collections []Collection `json:"collections"`
+}
+
+func paths(s Session) ([]string, error) {
+	raw, err := busctl(s, "get-property", service, servicePath, "org.freedesktop.Secret.Service", "Collections")
+	if err != nil {
+		return nil, err
+	}
+	var out []string
+	if err := json.Unmarshal(raw, &out); err != nil {
+		return nil, fmt.Errorf("the collections: %w", err)
+	}
+	return out, nil
+}
+
+func defaultCollection(s Session) string {
+	raw, err := busctl(s, "call", service, servicePath, "org.freedesktop.Secret.Service", "ReadAlias", "s", "default")
+	if err != nil {
+		return ""
+	}
+	var out []string
+	if json.Unmarshal(raw, &out) != nil || len(out) == 0 || out[0] == "/" {
+		return ""
+	}
+	return collectionID(out[0])
+}
+
+// describe reads a collection's properties: label, lock, the number of items (never the items), times.
+func describe(s Session, path string) (Collection, error) {
+	raw, err := busctl(s, "call", service, path, "org.freedesktop.DBus.Properties", "GetAll", "s", "org.freedesktop.Secret.Collection")
+	if err != nil {
+		return Collection{}, err
+	}
+	return parseCollection(path, raw)
+}
+
+func parseCollection(path string, raw json.RawMessage) (Collection, error) {
+	var answer []map[string]struct {
+		Data json.RawMessage `json:"data"`
+	}
+	if err := json.Unmarshal(raw, &answer); err != nil || len(answer) != 1 {
+		return Collection{}, fmt.Errorf("collection %s: not a property map", path)
+	}
+	p := answer[0]
+	c := Collection{ID: collectionID(path)}
+	_ = json.Unmarshal(p["Label"].Data, &c.Label)
+	_ = json.Unmarshal(p["Locked"].Data, &c.Locked)
+	var items []string
+	_ = json.Unmarshal(p["Items"].Data, &items)
+	c.Items = len(items)
+	for key, into := range map[string]*string{"Created": &c.Created, "Modified": &c.Modified} {
+		var t int64
+		if json.Unmarshal(p[key].Data, &t) == nil && t > 0 {
+			*into = time.Unix(t, 0).Format(time.RFC3339)
+		}
+	}
+	return c, nil
+}
+
+// Collections are the operator's keyrings.
+func Collections() (CollectionsResult, error) {
+	s, err := findBus()
+	if err != nil {
+		return CollectionsResult{}, err
+	}
+	ps, err := paths(s)
+	if err != nil {
+		return CollectionsResult{}, err
+	}
+	def := defaultCollection(s)
+	out := CollectionsResult{Collections: []Collection{}}
+	for _, p := range ps {
+		c, err := describe(s, p)
+		if err != nil {
+			return CollectionsResult{}, err
+		}
+		c.Default = c.ID == def
+		out.Collections = append(out.Collections, c)
+	}
+	sort.Slice(out.Collections, func(i, j int) bool { return out.Collections[i].ID < out.Collections[j].ID })
+	return out, nil
+}
+
+// UnlockedResult is what gnome_keyring_unlocked answers.
+type UnlockedResult struct {
+	Daemon  bool        `json:"daemon_running"`
+	Login   *Collection `json:"login,omitempty"`
+	Default *Collection `json:"default,omitempty"`
+	Note    string      `json:"note,omitempty"`
+}
+
+// Unlocked is whether the login and default keyrings are unlocked.
+func Unlocked() (UnlockedResult, error) {
+	s, err := findBus()
+	if err != nil {
+		return UnlockedResult{}, err
+	}
+	// gnome-keyring-daemon, as the kernel shortens a command's name to 15 characters.
+	out := UnlockedResult{Daemon: len(processesOf("gnome-keyring-d")) > 0}
+	if c, err := describe(s, collectionPath("login")); err == nil {
+		out.Login = &c
+	} else {
+		out.Note = "no login keyring: " + err.Error()
+	}
+	if def := defaultCollection(s); def != "" && def != "login" {
+		if c, err := describe(s, collectionPath(def)); err == nil {
+			c.Default = true
+			out.Default = &c
+		}
+	} else if out.Login != nil {
+		out.Login.Default = def == "login"
+	}
+	return out, nil
+}
+
+// LockResult is what gnome_keyring_lock answers.
+type LockResult struct {
+	Collection string `json:"collection"`
+	Locked     bool   `json:"locked"`
+}
+
+// Lock locks one keyring.
+func Lock(id string) (LockResult, error) {
+	if id == "" {
+		id = "login"
+	}
+	if !validID.MatchString(id) {
+		return LockResult{}, fmt.Errorf("collection %q is not a keyring id", id)
+	}
+	s, err := findBus()
+	if err != nil {
+		return LockResult{}, err
+	}
+	if _, err := busctl(s, "call", service, servicePath, "org.freedesktop.Secret.Service", "Lock", "ao", "1", collectionPath(id)); err != nil {
+		return LockResult{}, err
+	}
+	c, err := describe(s, collectionPath(id))
+	if err != nil {
+		return LockResult{}, err
+	}
+	return LockResult{Collection: id, Locked: c.Locked}, nil
+}
+
+// Key is one key the ssh agent holds.
+type Key struct {
+	Bits        int    `json:"bits"`
+	Fingerprint string `json:"fingerprint"`
+	Comment     string `json:"comment"`
+	Type        string `json:"type"`
+}
+
+// SSHKeysResult is what gnome_keyring_ssh_keys answers.
+type SSHKeysResult struct {
+	Agent string `json:"agent"`
+	Keys  []Key  `json:"keys"`
+	Note  string `json:"note,omitempty"`
+}
+
+// agentSocket is gcr's ssh agent socket, which its user socket unit listens on.
+func agentSocket(s Session) string { return filepath.Join(s.RuntimeDir, "gcr", "ssh") }
+
+var keyLine = regexp.MustCompile(`^(\d+)\s+(\S+)\s+(.*?)\s*\(([A-Z0-9-]+)\)$`)
+
+func parseKeys(out string) []Key {
+	keys := []Key{}
+	for _, line := range strings.Split(out, "\n") {
+		m := keyLine.FindStringSubmatch(strings.TrimSpace(line))
+		if m == nil {
+			continue
+		}
+		bits, _ := strconv.Atoi(m[1])
+		keys = append(keys, Key{Bits: bits, Fingerprint: m[2], Comment: m[3], Type: m[4]})
+	}
+	return keys
+}
+
+// SSHKeys lists what gcr's ssh agent holds, by fingerprint.
+func SSHKeys() (SSHKeysResult, error) {
+	s, err := findBus()
+	if err != nil {
+		return SSHKeysResult{}, err
+	}
+	sock := agentSocket(s)
+	// The agent is named for this one command only; nothing else of the tool's environment changes.
+	r, err := s.run(busTimeout, "", "env", "SSH_AUTH_SOCK="+sock, "ssh-add", "-l", "-E", "sha256")
+	if err != nil {
+		return SSHKeysResult{}, err
+	}
+	out := SSHKeysResult{Agent: sock, Keys: parseKeys(r.Stdout)}
+	switch r.Code {
+	case 0:
+	case 1:
+		out.Note = "the agent holds no keys"
+	case 127:
+		return SSHKeysResult{}, fmt.Errorf("ssh-add is not installed on this machine")
+	default:
+		return SSHKeysResult{}, fmt.Errorf("the ssh agent at %s does not answer: %s (is gcr-ssh-agent.socket enabled?)",
+			sock, strings.TrimSpace(r.Stderr))
+	}
+	return out, nil
+}

modules/gnome-keyring/cmd/gnome-keyring-tools/keyring_test.go

@@ -0,0 +1,131 @@
+package main
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+)
+
+const nobody = 4194400
+
+// secretService fakes busctl answering as gnome-keyring did on 2026-10-04: a session, a login and a
+// default keyring, the login one unlocked; Lock locks it.
+func secretService(t *testing.T) string {
+	t.Helper()
+	fakeMachine(t)
+	runtime := filepath.Join(runUserDir, strconv.Itoa(os.Getuid()))
+	if err := os.MkdirAll(runtime, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(runtime, "bus"), nil, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	bin := fakeBinaries(t, map[string]string{"busctl": `echo "$*" >> "$LOG"
+locked=false; [ -f "$LOG.locked" ] && locked=true
+case "$*" in
+  *"get-property org.freedesktop.secrets /org/freedesktop/secrets org.freedesktop.Secret.Service Collections")
+    echo '{"type":"ao","data":["/org/freedesktop/secrets/collection/session","/org/freedesktop/secrets/collection/login","/org/freedesktop/secrets/collection/Default_5fkeyring"]}' ;;
+  *"ReadAlias s default") echo '{"type":"o","data":["/org/freedesktop/secrets/collection/Default_5fkeyring"]}' ;;
+  *"/collection/login org.freedesktop.DBus.Properties GetAll"*)
+    echo '{"type":"a{sv}","data":[{"Items":{"type":"ao","data":["/x/1","/x/2"]},"Label":{"type":"s","data":"Login"},"Locked":{"type":"b","data":'$locked'},"Created":{"type":"t","data":1752488320},"Modified":{"type":"t","data":0}}]}' ;;
+  *"/collection/"*"GetAll"*)
+    echo '{"type":"a{sv}","data":[{"Items":{"type":"ao","data":[]},"Label":{"type":"s","data":"Other"},"Locked":{"type":"b","data":true},"Created":{"type":"t","data":0},"Modified":{"type":"t","data":0}}]}' ;;
+  *"Lock ao 1 /org/freedesktop/secrets/collection/login") touch "$LOG.locked"; echo '{"type":"aoo","data":[["/org/freedesktop/secrets/collection/login"],"/"]}' ;;
+  *) echo "no such call: $*" >&2; exit 1 ;;
+esac`})
+	t.Setenv("LOG", filepath.Join(bin, "log"))
+	return bin
+}
+
+func TestCollectionsAreNamesCountsAndLocksNeverItems(t *testing.T) {
+	bin := secretService(t)
+	got, err := Collections()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got.Collections) != 3 {
+		t.Fatalf("%+v", got)
+	}
+	var login, def Collection
+	for _, c := range got.Collections {
+		switch c.ID {
+		case "login":
+			login = c
+		case "Default_5fkeyring":
+			def = c
+		}
+	}
+	if login.Label != "Login" || login.Locked || login.Items != 2 || login.Created == "" || login.Modified != "" || login.Default {
+		t.Fatalf("login: %+v", login)
+	}
+	if !def.Default || !def.Locked {
+		t.Fatalf("default: %+v", def)
+	}
+	asked, _ := os.ReadFile(filepath.Join(bin, "log"))
+	if strings.Contains(string(asked), "GetSecret") || strings.Contains(string(asked), "Item") && strings.Contains(string(asked), "Secret.Item") {
+		t.Fatalf("a secret was asked for:\n%s", asked)
+	}
+}
+
+func TestUnlockedAnswersTheLoginAndTheDefaultKeyring(t *testing.T) {
+	secretService(t)
+	fakeProcess(t, nobody, "gnome-keyring-d")
+	got, err := Unlocked()
+	if err != nil || !got.Daemon || got.Login == nil || got.Login.Locked || got.Default == nil || !got.Default.Default {
+		t.Fatalf("%+v, %v", got, err)
+	}
+}
+
+func TestLockLocksTheLoginKeyringAndRefusesAPathForAnId(t *testing.T) {
+	secretService(t)
+	got, err := Lock("")
+	if err != nil || got.Collection != "login" || !got.Locked {
+		t.Fatalf("%+v, %v", got, err)
+	}
+	for _, bad := range []string{"../service", "login /org/x", "a b"} {
+		if _, err := Lock(bad); err == nil {
+			t.Errorf("%q was accepted", bad)
+		}
+	}
+}
+
+func TestTheAgentsKeysAreFingerprints(t *testing.T) {
+	keys := parseKeys("256 SHA256:x+LmFabc op@laptop (ED25519)\n3072 SHA256:yyy a comment with spaces (RSA)\nThe agent has no identities.\n")
+	if len(keys) != 2 || keys[0] != (Key{Bits: 256, Fingerprint: "SHA256:x+LmFabc", Comment: "op@laptop", Type: "ED25519"}) ||
+		keys[1].Comment != "a comment with spaces" || keys[1].Type != "RSA" {
+		t.Fatalf("%+v", keys)
+	}
+}
+
+func TestSSHKeysAsksGcrsAgentAndSaysWhenItDoesNotAnswer(t *testing.T) {
+	secretService(t)
+	bin := fakeBinaries(t, map[string]string{"ssh-add": `echo "$SSH_AUTH_SOCK $*" > "$LOG.ssh"; [ -f "$NOAGENT" ] && { echo "Could not open a connection" >&2; exit 2; }; echo "256 SHA256:abc op (ED25519)"`})
+	t.Setenv("NOAGENT", filepath.Join(bin, "noagent"))
+	got, err := SSHKeys()
+	if err != nil || len(got.Keys) != 1 || !strings.HasSuffix(got.Agent, "/gcr/ssh") {
+		t.Fatalf("%+v, %v", got, err)
+	}
+	asked, _ := os.ReadFile(os.Getenv("LOG") + ".ssh")
+	if !strings.HasSuffix(strings.TrimSpace(string(asked)), "/gcr/ssh -l -E sha256") {
+		t.Fatalf("asked: %s", asked)
+	}
+	if err := os.WriteFile(filepath.Join(bin, "noagent"), nil, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := SSHKeys(); err == nil || !strings.Contains(err.Error(), "gcr-ssh-agent.socket") {
+		t.Fatalf("no agent: %v", err)
+	}
+}
+
+func TestWithoutABusTheToolsSaySo(t *testing.T) {
+	fakeMachine(t)
+	if _, err := Collections(); !errors.Is(err, ErrNoBus) {
+		t.Fatal(err)
+	}
+	if _, err := SSHKeys(); !errors.Is(err, ErrNoBus) {
+		t.Fatal(err)
+	}
+}

modules/gnome-keyring/cmd/gnome-keyring-tools/main.go

@@ -0,0 +1,57 @@
+// gnome-keyring's Go tools bundle (novox/hq ADR 0188, ADR 0193, ADR 0208): the secret service's
+// tools, served by the node's runtime as the operator account. node-secret-service has no verbs yet
+// (ADR 0208 §2), so every tool here is the module's own. None of them ever reads a secret: they ask the
+// Secret Service for names, counts and lock states, and the ssh agent for fingerprints.
+package main
+
+import (
+	"fmt"
+	"os"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+func main() {
+	if err := stdio.Serve("", tools()); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+func tools() []stdio.Tool {
+	return []stdio.Tool{
+		{
+			Name: "gnome_keyring_unlocked",
+			Description: "Is the operator's keyring unlocked: the login keyring and the default one, each locked " +
+				"or not, and whether the keyring daemon runs.",
+			Run: func(map[string]any) (any, error) { return Unlocked() },
+		},
+		{
+			Name: "gnome_keyring_lock",
+			Description: "Lock a keyring now (the login keyring unless another is named): programs must ask " +
+				"for its password again. Unlocking is the operator's, at their desktop.",
+			Input: map[string]any{
+				"collection": map[string]any{"type": "string", "description": "the keyring's id, as gnome_keyring_collections answers it (default login)"},
+			},
+			Run: func(args map[string]any) (any, error) {
+				c, err := text(args, "collection", false)
+				if err != nil {
+					return nil, err
+				}
+				return Lock(c)
+			},
+		},
+		{
+			Name: "gnome_keyring_collections",
+			Description: "The operator's keyrings: each one's id, label, whether it is locked, how many items it " +
+				"holds, when it was created and changed, and which is the default. Never an item, never a secret.",
+			Run: func(map[string]any) (any, error) { return Collections() },
+		},
+		{
+			Name: "gnome_keyring_ssh_keys",
+			Description: "The keys the session's ssh agent (gcr's) holds, by fingerprint, size, type and comment. " +
+				"Never a key.",
+			Run: func(map[string]any) (any, error) { return SSHKeys() },
+		},
+	}
+}

modules/gnome-keyring/cmd/gnome-keyring-tools/manifest_helpers_test.go

@@ -0,0 +1,175 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// The module's manifest, read the way the catalogue reads it, for the manifest tests. The same in
+// every desktop module that carries it.
+
+type manifest struct {
+	Module       string           `json:"module"`
+	Version      string           `json:"version"`
+	Capabilities []string         `json:"capabilities"`
+	Requires     []string         `json:"requires"`
+	Claims       []claim          `json:"claims"`
+	Seats        []any            `json:"seats"`
+	Tools        []string         `json:"tools"`
+	Environment  *environment     `json:"environment"`
+	Shell        []shellCode      `json:"shell"`
+	Resources    []map[string]any `json:"resources"`
+	Build        struct {
+		Artifacts []map[string]any `json:"artifacts"`
+	} `json:"build"`
+}
+
+type claim struct {
+	Name   string   `json:"name"`
+	Scope  string   `json:"scope"`
+	Serves []string `json:"serves"`
+}
+
+type environment struct {
+	Variables map[string]string `json:"variables"`
+	Path      []map[string]any  `json:"path"`
+}
+
+type shellCode struct {
+	For  string `json:"for"`
+	Slot string `json:"slot"`
+	Code string `json:"code"`
+}
+
+func readManifest(t *testing.T) manifest {
+	t.Helper()
+	raw, err := os.ReadFile(filepath.Join("..", "..", "module.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	dec := json.NewDecoder(strings.NewReader(string(raw)))
+	dec.DisallowUnknownFields()
+	var m manifest
+	if err := dec.Decode(&m); err != nil {
+		t.Fatalf("module.json: %v", err)
+	}
+	return m
+}
+
+func (m manifest) resource(t *testing.T, id string) map[string]any {
+	t.Helper()
+	for _, r := range m.Resources {
+		if r["id"] == id {
+			return r
+		}
+	}
+	t.Fatalf("no resource %q", id)
+	return nil
+}
+
+func (m manifest) packages() (present, absent []string) {
+	for _, r := range m.Resources {
+		if r["type"] == "package" {
+			if r["absent"] == true {
+				absent = append(absent, r["package"].(string))
+			} else {
+				present = append(present, r["package"].(string))
+			}
+		}
+	}
+	return present, absent
+}
+
+// sameAsSource checks that a file resource's content is byte for byte the module's source file, so
+// the readable file in the repository is what the machine gets.
+func (m manifest) sameAsSource(t *testing.T, id, source string) {
+	t.Helper()
+	want, err := os.ReadFile(filepath.Join("..", "..", source))
+	if err != nil {
+		t.Fatal(err)
+	}
+	r := m.resource(t, id)
+	if r["type"] != "file" {
+		t.Fatalf("%s is a %v, not a file", id, r["type"])
+	}
+	if got, _ := r["content"].(string); got != string(want) {
+		t.Fatalf("resource %s's content is not %s: edit the source and copy it into module.json", id, source)
+	}
+	if r["owner"] != "${machine:account}" && !strings.HasPrefix(r["path"].(string), "/etc/") {
+		t.Fatalf("%s under the home is the account's", id)
+	}
+}
+
+// checkTheToolsAgree checks that the manifest lists the module's own tools exactly, that the bundle
+// serves each seat verb the claims promise as <seat>.<verb>, and that the Go bundle is declared.
+func checkTheToolsAgree(t *testing.T, m manifest) {
+	t.Helper()
+	own, seat := map[string]bool{}, map[string]bool{}
+	for _, tool := range tools() {
+		if strings.Contains(tool.Name, ".") {
+			seat[tool.Name] = true
+		} else {
+			own[tool.Name] = true
+		}
+		if strings.TrimSpace(tool.Description) == "" {
+			t.Errorf("%s has no description", tool.Name)
+		}
+	}
+	listed := map[string]bool{}
+	for _, name := range m.Tools {
+		listed[name] = true
+		if !own[name] {
+			t.Errorf("module.json lists %s, which the bundle does not serve", name)
+		}
+	}
+	for name := range own {
+		if !listed[name] {
+			t.Errorf("the bundle serves %s, which module.json does not list", name)
+		}
+		if !strings.HasPrefix(name, strings.ReplaceAll(m.Module, "-", "_")+"_") {
+			t.Errorf("%s is not prefixed with the module's name", name)
+		}
+	}
+	promised := map[string]bool{}
+	for _, c := range m.Claims {
+		for _, verb := range c.Serves {
+			promised[c.Name+"."+verb] = true
+			if !seat[c.Name+"."+verb] {
+				t.Errorf("the claim on %s promises %s, which the bundle does not serve", c.Name, verb)
+			}
+		}
+	}
+	for name := range seat {
+		if !promised[name] {
+			t.Errorf("the bundle serves %s, which no claim promises", name)
+		}
+	}
+	var bundle map[string]any
+	for _, a := range m.Build.Artifacts {
+		if a["kind"] == "bundle" {
+			bundle = a
+		}
+	}
+	if bundle == nil || bundle["language"] != "go" || bundle["system"] != "arch" ||
+		bundle["from"] != "cmd/"+m.Module+"-tools" || bundle["binary"] != m.Module+"-tools" {
+		t.Errorf("the Go tools bundle: %v", bundle)
+	}
+}
+
+// checkNoSecretsOrInstallationNames refuses what a catalogue manifest must never carry.
+func checkNoSecretsOrInstallationNames(t *testing.T) {
+	t.Helper()
+	raw, err := os.ReadFile(filepath.Join("..", "..", "module.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := strings.ToLower(string(raw))
+	for _, never := range []string{"/home/", "jochen", "g14", "shanks", "novox.be", "api_key", ".hal/", "greenclip daemon"} {
+		if strings.Contains(s, never) {
+			t.Errorf("module.json names %q", never)
+		}
+	}
+}

modules/gnome-keyring/cmd/gnome-keyring-tools/manifest_test.go

@@ -0,0 +1,64 @@
+package main
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+)
+
+// gnome-keyring's shape (novox/hq ADR 0208, ADR 0102): it claims node-secret-service, writes its PAM
+// lines into the login and passwd stacks as marked blocks (never over the files), and starts no daemon
+// of its own: PAM and D-Bus do.
+
+func TestItClaimsTheSecretServiceSeat(t *testing.T) {
+	m := readManifest(t)
+	if m.Module != "gnome-keyring" || m.Seats != nil || m.Requires != nil {
+		t.Fatalf("module %q, seats %v, requires %v", m.Module, m.Seats, m.Requires)
+	}
+	if !reflect.DeepEqual(m.Claims, []claim{{Name: "node-secret-service", Scope: "node"}}) {
+		t.Fatalf("claims: %+v", m.Claims)
+	}
+	if present, absent := m.packages(); !reflect.DeepEqual(present, []string{"gnome-keyring", "libsecret", "seahorse"}) || absent != nil {
+		t.Fatalf("packages: %v, absent %v", present, absent)
+	}
+}
+
+func TestThePAMLinesAreBlocksWrittenIntoTheStacks(t *testing.T) {
+	m := readManifest(t)
+	for id, want := range map[string]struct{ path, source string }{
+		"pam-login":  {"/etc/pam.d/login", "files/pam/login"},
+		"pam-passwd": {"/etc/pam.d/passwd", "files/pam/passwd"},
+	} {
+		m.sameAsSource(t, id, want.source)
+		r := m.resource(t, id)
+		if r["path"] != want.path || r["into"] != "block" || r["at"] != "end" || r["owner"] != nil {
+			t.Errorf("%s: %v", id, r)
+		}
+	}
+	login := m.resource(t, "pam-login")["content"].(string)
+	if !strings.Contains(login, "\nauth       optional     pam_gnome_keyring.so\n") ||
+		!strings.Contains(login, "\nsession    optional     pam_gnome_keyring.so auto_start\n") {
+		t.Fatalf("%s", login)
+	}
+}
+
+func TestItStartsNoDaemonAndOnlyNamesTheAgentsSocket(t *testing.T) {
+	m := readManifest(t)
+	if len(m.Shell) != 1 || m.Shell[0].For != "xinitrc" || m.Shell[0].Slot != "first" {
+		t.Fatalf("%+v", m.Shell)
+	}
+	code := m.Shell[0].Code
+	if strings.Contains(code, "gnome-keyring-daemon") || strings.Contains(code, "--unlock") ||
+		!strings.Contains(code, `SSH_AUTH_SOCK="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/gcr/ssh"`) {
+		t.Fatalf("%q", code)
+	}
+	if m.Environment != nil {
+		t.Fatal("SSH_AUTH_SOCK needs the runtime directory, which ADR 0203 forbids in a value; it is not an environment contribution yet")
+	}
+}
+
+func TestTheToolsAgreeWithTheManifest(t *testing.T) {
+	m := readManifest(t)
+	checkTheToolsAgree(t, m)
+	checkNoSecretsOrInstallationNames(t)
+}

modules/gnome-keyring/cmd/gnome-keyring-tools/session.go

@@ -0,0 +1,423 @@
+// The operator's graphical session, as a tool the node's runtime runs finds it (novox/hq ADR 0208).
+//
+// The runtime is a system service running as the operator account (ADR 0175): it has the account's
+// uid and none of the session's environment — no DISPLAY, no XAUTHORITY, no session bus. A tool that
+// draws on the screen or talks to the desktop's D-Bus must find them. It reads them from a process of
+// the account that is part of the session (the window manager first), the same thing `loginctl` and
+// a person's own shell would point at, and says where it found them.
+//
+// Long-lived programs a tool starts go to the account's own service manager through `systemd-run
+// --user`, never as children of the tool: the runtime's unit is a cgroup the service manager empties
+// whenever the runtime restarts, and a compositor or a clipboard owner started from inside it would
+// die with it.
+//
+// This file is the same in every desktop module that carries it; it moves into the Go SDK once a
+// second consumer outside the desktop wants it.
+package main
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"syscall"
+	"time"
+)
+
+// Where the session is looked for. Variables so a test can point them at a fake tree.
+var (
+	procRoot   = "/proc"
+	runUserDir = "/run/user"
+	x11Sockets = "/tmp/.X11-unix"
+)
+
+// sessionHolders are the processes whose environment is the session's, best first: the window
+// manager is the session, the rest are its children. Anything else carrying DISPLAY ranks after them.
+var sessionHolders = []string{"i3", "sway", "i3bar", "picom", "xss-lock", "dunst", "clipmenud", "xterm"}
+
+// sessionKeys are the variables a session carries that a tool hands on to what it runs.
+var sessionKeys = []string{"DISPLAY", "XAUTHORITY", "WAYLAND_DISPLAY", "DBUS_SESSION_BUS_ADDRESS",
+	"XDG_RUNTIME_DIR", "XDG_SESSION_ID", "I3SOCK"}
+
+// Session is what a tool needs to reach the operator's desktop.
+type Session struct {
+	UID        int    `json:"uid"`
+	Display    string `json:"display,omitempty"`
+	XAuthority string `json:"xauthority,omitempty"`
+	Wayland    string `json:"wayland_display,omitempty"`
+	Bus        string `json:"bus,omitempty"`
+	RuntimeDir string `json:"runtime_dir,omitempty"`
+	SessionID  string `json:"session_id,omitempty"`
+	I3Sock     string `json:"i3sock,omitempty"`
+	// From says where the values were found: the tool's own environment, a process, or the socket.
+	From string `json:"from"`
+}
+
+// ErrNoSession is answered by a tool that needs the desktop when nobody is logged in to it.
+var ErrNoSession = errors.New("no graphical session")
+
+// ErrTimedOut is what run answers for a command ended because it ran past its time.
+var ErrTimedOut = errors.New("timed out")
+
+// ErrNoBus is answered by a tool that needs the session bus when the account has none.
+var ErrNoBus = errors.New("no session bus")
+
+// operatorHome is the account's home: what the runtime was told, else the process's own.
+func operatorHome() string {
+	if h := strings.TrimSpace(os.Getenv("MESH_OPERATOR_HOME")); h != "" {
+		return h
+	}
+	h, _ := os.UserHomeDir()
+	return h
+}
+
+// findSession finds the graphical session of the account this tool runs as, or answers
+// ErrNoSession with what it looked at.
+func findSession() (Session, error) {
+	s := findEnvironment()
+	if s.Display == "" && s.Wayland == "" {
+		return s, fmt.Errorf("%w for uid %d on this machine: no process of the account carries DISPLAY "+
+			"or WAYLAND_DISPLAY, and no X server socket in %s has an authority file to go with it. "+
+			"Is anyone logged in to the desktop?", ErrNoSession, s.UID, x11Sockets)
+	}
+	return s, nil
+}
+
+// findBus finds the account's session bus, which a logged-in account has whether or not a desktop
+// is running.
+func findBus() (Session, error) {
+	s := findEnvironment()
+	if s.Bus == "" {
+		return s, fmt.Errorf("%w for uid %d: DBUS_SESSION_BUS_ADDRESS is not set and %s does not exist "+
+			"(the account is not logged in)", ErrNoBus, s.UID, filepath.Join(runUserDir, strconv.Itoa(s.UID), "bus"))
+	}
+	return s, nil
+}
+
+func findEnvironment() Session {
+	uid := os.Getuid()
+	s := Session{UID: uid}
+	own := map[string]string{}
+	for _, k := range sessionKeys {
+		own[k] = os.Getenv(k)
+	}
+	if own["DISPLAY"] != "" || own["WAYLAND_DISPLAY"] != "" {
+		s.fill(own)
+		s.From = "the tool's own environment"
+	} else if pid, comm, env, ok := sessionProcess(uid); ok {
+		s.fill(env)
+		s.From = fmt.Sprintf("process %s (pid %d)", comm, pid)
+	} else if display, ok := lonelyX11Socket(); ok {
+		if a := filepath.Join(operatorHome(), ".Xauthority"); exists(a) {
+			s.Display, s.XAuthority = display, a
+			s.From = "the X server socket and the account's ~/.Xauthority"
+		}
+		s.fill(own)
+	} else {
+		s.fill(own)
+		s.From = "nothing: no session found"
+	}
+	// The bus and the runtime directory are the account's, whether or not the process named them.
+	runtime := filepath.Join(runUserDir, strconv.Itoa(uid))
+	if s.RuntimeDir == "" && exists(runtime) {
+		s.RuntimeDir = runtime
+	}
+	if s.Bus == "" && s.RuntimeDir != "" && exists(filepath.Join(s.RuntimeDir, "bus")) {
+		s.Bus = "unix:path=" + filepath.Join(s.RuntimeDir, "bus")
+	}
+	return s
+}
+
+func (s *Session) fill(env map[string]string) {
+	set := func(dst *string, key string) {
+		if *dst == "" {
+			*dst = env[key]
+		}
+	}
+	set(&s.Display, "DISPLAY")
+	set(&s.XAuthority, "XAUTHORITY")
+	set(&s.Wayland, "WAYLAND_DISPLAY")
+	set(&s.Bus, "DBUS_SESSION_BUS_ADDRESS")
+	set(&s.RuntimeDir, "XDG_RUNTIME_DIR")
+	set(&s.SessionID, "XDG_SESSION_ID")
+	set(&s.I3Sock, "I3SOCK")
+}
+
+// sessionProcess is the best process of this uid whose environment names a display.
+func sessionProcess(uid int) (int, string, map[string]string, bool) {
+	entries, err := os.ReadDir(procRoot)
+	if err != nil {
+		return 0, "", nil, false
+	}
+	type candidate struct {
+		pid  int
+		comm string
+		env  map[string]string
+		rank int
+	}
+	var found []candidate
+	for _, e := range entries {
+		pid, err := strconv.Atoi(e.Name())
+		if err != nil {
+			continue
+		}
+		dir := filepath.Join(procRoot, e.Name())
+		if owner, ok := ownerOf(dir); !ok || owner != uid {
+			continue
+		}
+		raw, err := os.ReadFile(filepath.Join(dir, "environ"))
+		if err != nil {
+			continue
+		}
+		env := parseEnviron(raw)
+		if env["DISPLAY"] == "" && env["WAYLAND_DISPLAY"] == "" {
+			continue
+		}
+		comm := readTrimmed(filepath.Join(dir, "comm"))
+		rank := len(sessionHolders)
+		for i, h := range sessionHolders {
+			if h == comm {
+				rank = i
+				break
+			}
+		}
+		found = append(found, candidate{pid, comm, env, rank})
+	}
+	if len(found) == 0 {
+		return 0, "", nil, false
+	}
+	sort.Slice(found, func(i, j int) bool {
+		if found[i].rank != found[j].rank {
+			return found[i].rank < found[j].rank
+		}
+		return found[i].pid > found[j].pid // the newer of two equals
+	})
+	best := found[0]
+	return best.pid, best.comm, best.env, true
+}
+
+func parseEnviron(raw []byte) map[string]string {
+	env := map[string]string{}
+	for _, kv := range bytes.Split(raw, []byte{0}) {
+		if i := bytes.IndexByte(kv, '='); i > 0 {
+			env[string(kv[:i])] = string(kv[i+1:])
+		}
+	}
+	return env
+}
+
+func ownerOf(path string) (int, bool) {
+	info, err := os.Stat(path)
+	if err != nil {
+		return 0, false
+	}
+	st, ok := info.Sys().(*syscall.Stat_t)
+	if !ok {
+		return 0, false
+	}
+	return int(st.Uid), true
+}
+
+// lonelyX11Socket is the display of the one X server socket there is, when there is exactly one.
+func lonelyX11Socket() (string, bool) {
+	entries, err := os.ReadDir(x11Sockets)
+	if err != nil {
+		return "", false
+	}
+	var displays []string
+	for _, e := range entries {
+		if n := strings.TrimPrefix(e.Name(), "X"); n != e.Name() {
+			if _, err := strconv.Atoi(n); err == nil {
+				displays = append(displays, ":"+n)
+			}
+		}
+	}
+	if len(displays) != 1 {
+		return "", false
+	}
+	return displays[0], true
+}
+
+func readTrimmed(path string) string {
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(string(b))
+}
+
+func exists(path string) bool {
+	_, err := os.Stat(path)
+	return err == nil
+}
+
+// Env is this process's environment with the session's variables in place of its own.
+func (s Session) Env() []string {
+	drop := map[string]bool{}
+	for _, k := range sessionKeys {
+		drop[k] = true
+	}
+	var env []string
+	for _, kv := range os.Environ() {
+		if i := strings.IndexByte(kv, '='); i > 0 && drop[kv[:i]] {
+			continue
+		}
+		env = append(env, kv)
+	}
+	add := func(k, v string) {
+		if v != "" {
+			env = append(env, k+"="+v)
+		}
+	}
+	add("DISPLAY", s.Display)
+	add("XAUTHORITY", s.XAuthority)
+	add("WAYLAND_DISPLAY", s.Wayland)
+	add("DBUS_SESSION_BUS_ADDRESS", s.Bus)
+	add("XDG_RUNTIME_DIR", s.RuntimeDir)
+	add("XDG_SESSION_ID", s.SessionID)
+	add("I3SOCK", s.I3Sock)
+	return env
+}
+
+// mostOutput bounds what a command may answer with, per stream.
+const mostOutput = 256 << 10
+
+// Result is what a command did.
+type Result struct {
+	Stdout    string `json:"stdout"`
+	Stderr    string `json:"stderr,omitempty"`
+	Code      int    `json:"code"`
+	Truncated bool   `json:"truncated,omitempty"`
+}
+
+// run runs a command in the session's environment, its input given, ended with everything it
+// started after timeout. A command that is not installed is an error naming it; one that exits
+// non-zero is a Result with its code, for the caller to judge.
+func (s Session) run(timeout time.Duration, stdin string, name string, args ...string) (Result, error) {
+	path, err := exec.LookPath(name)
+	if err != nil {
+		return Result{}, fmt.Errorf("%s is not installed on this machine", name)
+	}
+	cmd := exec.Command(path, args...)
+	cmd.Env = s.Env()
+	if home := operatorHome(); exists(home) {
+		cmd.Dir = home
+	}
+	if stdin != "" {
+		cmd.Stdin = strings.NewReader(stdin)
+	}
+	var out, errOut capped
+	cmd.Stdout, cmd.Stderr = &out, &errOut
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+	if err := cmd.Start(); err != nil {
+		return Result{}, fmt.Errorf("%s: %w", name, err)
+	}
+	done := make(chan error, 1)
+	go func() { done <- cmd.Wait() }()
+	select {
+	case err = <-done:
+	case <-time.After(timeout):
+		_ = syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)
+		<-done
+		return Result{Stdout: out.String(), Stderr: errOut.String()},
+			fmt.Errorf("%s did not finish within %s and was ended: %w", name, timeout, ErrTimedOut)
+	}
+	r := Result{Stdout: out.String(), Stderr: errOut.String(), Truncated: out.cut || errOut.cut}
+	var exit *exec.ExitError
+	if errors.As(err, &exit) {
+		r.Code = exit.ExitCode()
+	} else if err != nil {
+		return r, fmt.Errorf("%s: %w", name, err)
+	}
+	return r, nil
+}
+
+// detach starts a long-lived program under the account's own service manager, as a transient unit
+// that carries the session's display, so it outlives the runtime that asked for it. A unit already
+// running under the same name is stopped first, so a fixed name means "at most one".
+func (s Session) detach(unit string, args ...string) error {
+	if s.RuntimeDir == "" {
+		return fmt.Errorf("%w: the account's runtime directory is missing, so its service manager "+
+			"cannot be reached", ErrNoBus)
+	}
+	_, _ = s.run(5*time.Second, "", "systemctl", "--user", "stop", unit+".service")
+	call := []string{"--user", "--collect", "--quiet", "--unit=" + unit}
+	for _, kv := range [][2]string{{"DISPLAY", s.Display}, {"XAUTHORITY", s.XAuthority},
+		{"WAYLAND_DISPLAY", s.Wayland}, {"XDG_SESSION_ID", s.SessionID}, {"I3SOCK", s.I3Sock}} {
+		if kv[1] != "" {
+			call = append(call, "--setenv="+kv[0]+"="+kv[1])
+		}
+	}
+	call = append(call, "--")
+	call = append(call, args...)
+	r, err := s.run(10*time.Second, "", "systemd-run", call...)
+	if err != nil {
+		return err
+	}
+	if r.Code != 0 {
+		return fmt.Errorf("systemd-run %s: %s", unit, strings.TrimSpace(r.Stderr))
+	}
+	return nil
+}
+
+// uniqueUnit is a transient unit name that will not collide with an earlier one.
+func uniqueUnit(prefix string) string {
+	return fmt.Sprintf("%s-%d", prefix, time.Now().UnixNano())
+}
+
+type capped struct {
+	bytes.Buffer
+	cut bool
+}
+
+func (c *capped) Write(p []byte) (int, error) {
+	if room := mostOutput - c.Len(); room < len(p) {
+		if room > 0 {
+			c.Buffer.Write(p[:room])
+		}
+		c.cut = true
+		return len(p), nil
+	}
+	return c.Buffer.Write(p)
+}
+
+// processesOf are the pids of this uid's processes whose command name is comm, oldest first.
+func processesOf(comm string) []int {
+	entries, err := os.ReadDir(procRoot)
+	if err != nil {
+		return nil
+	}
+	uid := os.Getuid()
+	var pids []int
+	for _, e := range entries {
+		pid, err := strconv.Atoi(e.Name())
+		if err != nil {
+			continue
+		}
+		dir := filepath.Join(procRoot, e.Name())
+		if owner, ok := ownerOf(dir); !ok || owner != uid {
+			continue
+		}
+		if readTrimmed(filepath.Join(dir, "comm")) == comm {
+			pids = append(pids, pid)
+		}
+	}
+	sort.Ints(pids)
+	return pids
+}
+
+// signalAll sends sig to every process of this uid named comm, and answers the pids it reached.
+func signalAll(comm string, sig syscall.Signal) []int {
+	var reached []int
+	for _, pid := range processesOf(comm) {
+		if syscall.Kill(pid, sig) == nil {
+			reached = append(reached, pid)
+		}
+	}
+	return reached
+}

modules/gnome-keyring/cmd/gnome-keyring-tools/session_test.go

@@ -0,0 +1,174 @@
+package main
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+)
+
+// fakeMachine points the session finder at a temporary /proc, /run/user and X socket directory, with
+// none of the test process's own session variables, and gives back the root.
+func fakeMachine(t *testing.T) string {
+	t.Helper()
+	root := t.TempDir()
+	procRoot, runUserDir, x11Sockets = filepath.Join(root, "proc"), filepath.Join(root, "run-user"), filepath.Join(root, "x11")
+	for _, d := range []string{procRoot, runUserDir, x11Sockets} {
+		if err := os.MkdirAll(d, 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	for _, k := range sessionKeys {
+		t.Setenv(k, "")
+	}
+	t.Setenv("MESH_OPERATOR_HOME", filepath.Join(root, "home"))
+	t.Cleanup(func() { procRoot, runUserDir, x11Sockets = "/proc", "/run/user", "/tmp/.X11-unix" })
+	return root
+}
+
+func fakeProcess(t *testing.T, pid int, comm string, env ...string) {
+	t.Helper()
+	dir := filepath.Join(procRoot, strconv.Itoa(pid))
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "comm"), []byte(comm+"\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "environ"), []byte(strings.Join(env, "\x00")+"\x00"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestTheSessionIsReadFromTheWindowManagerBeforeAnyOtherProcess(t *testing.T) {
+	fakeMachine(t)
+	fakeProcess(t, 900, "xterm", "DISPLAY=:9", "XAUTHORITY=/elsewhere")
+	fakeProcess(t, 100, "i3", "DISPLAY=:1", "XAUTHORITY=/home/op/.Xauthority",
+		"DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus", "XDG_SESSION_ID=3", "SECRET_TOKEN=never-copied")
+	fakeProcess(t, 50, "bash", "PATH=/usr/bin")
+	s, err := findSession()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if s.Display != ":1" || s.XAuthority != "/home/op/.Xauthority" || s.SessionID != "3" || !strings.Contains(s.From, "i3 (pid 100)") {
+		t.Fatalf("the window manager's environment: %+v", s)
+	}
+	for _, kv := range s.Env() {
+		if strings.HasPrefix(kv, "SECRET_TOKEN=") {
+			t.Fatal("a variable of the session process that is not a session variable was handed on")
+		}
+	}
+}
+
+func TestAnyProcessCarryingADisplayServesWhenTheWindowManagerIsNotFound(t *testing.T) {
+	fakeMachine(t)
+	fakeProcess(t, 10, "firefox", "DISPLAY=:0")
+	fakeProcess(t, 20, "firefox", "DISPLAY=:2")
+	s, err := findSession()
+	if err != nil || s.Display != ":2" {
+		t.Fatalf("the newest of two equals: %+v, %v", s, err)
+	}
+}
+
+func TestNoSessionIsAClearAnswerNotAGuess(t *testing.T) {
+	fakeMachine(t)
+	fakeProcess(t, 10, "sshd", "PATH=/usr/bin")
+	_, err := findSession()
+	if !errors.Is(err, ErrNoSession) || !strings.Contains(err.Error(), "logged in to the desktop") {
+		t.Fatalf("no session: %v", err)
+	}
+}
+
+func TestOneXSocketAndTheAccountsAuthorityFileAreASession(t *testing.T) {
+	root := fakeMachine(t)
+	if err := os.WriteFile(filepath.Join(x11Sockets, "X0"), nil, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Join(root, "home"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(root, "home", ".Xauthority"), nil, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	s, err := findSession()
+	if err != nil || s.Display != ":0" || !strings.HasSuffix(s.XAuthority, "/home/.Xauthority") {
+		t.Fatalf("socket and authority: %+v, %v", s, err)
+	}
+}
+
+func TestTheBusIsTheAccountsRuntimeDirectoryWhenNoProcessNamesIt(t *testing.T) {
+	fakeMachine(t)
+	runtime := filepath.Join(runUserDir, strconv.Itoa(os.Getuid()))
+	if _, err := findBus(); !errors.Is(err, ErrNoBus) {
+		t.Fatalf("no runtime directory is no bus: %v", err)
+	}
+	if err := os.MkdirAll(runtime, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(runtime, "bus"), nil, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	s, err := findBus()
+	if err != nil || s.Bus != "unix:path="+filepath.Join(runtime, "bus") || s.RuntimeDir != runtime {
+		t.Fatalf("bus: %+v, %v", s, err)
+	}
+	env := strings.Join(s.Env(), "\n")
+	if !strings.Contains(env, "XDG_RUNTIME_DIR="+runtime) || !strings.Contains(env, "DBUS_SESSION_BUS_ADDRESS=unix:path=") {
+		t.Fatalf("the bus is handed on: %s", env)
+	}
+}
+
+func TestACommandIsBoundedAndANonZeroExitIsAResult(t *testing.T) {
+	fakeMachine(t)
+	s := Session{}
+	r, err := s.run(5*time.Second, "in", "sh", "-c", "cat; echo err >&2; exit 3")
+	if err != nil || r.Stdout != "in" || r.Code != 3 || strings.TrimSpace(r.Stderr) != "err" {
+		t.Fatalf("result: %+v, %v", r, err)
+	}
+	start := time.Now()
+	if _, err := s.run(200*time.Millisecond, "", "sh", "-c", "sleep 30 & sleep 30"); err == nil || time.Since(start) > 5*time.Second {
+		t.Fatalf("a command past its time is ended with what it started: %v after %s", err, time.Since(start))
+	}
+	if _, err := s.run(time.Second, "", "no-such-program-here"); err == nil || !strings.Contains(err.Error(), "not installed") {
+		t.Fatalf("a missing program: %v", err)
+	}
+}
+
+func TestDetachAsksTheAccountsServiceManagerWithTheSessionsDisplay(t *testing.T) {
+	fakeMachine(t)
+	bin := fakeBinaries(t, map[string]string{
+		"systemctl":   `echo "systemctl $*" >> "$LOG"`,
+		"systemd-run": `echo "systemd-run $*" >> "$LOG"`,
+	})
+	log := filepath.Join(bin, "log")
+	t.Setenv("LOG", log)
+	s := Session{Display: ":1", XAuthority: "/x", RuntimeDir: "/run/user/1"}
+	if err := s.detach("picom-session", "picom", "--config", "/c"); err != nil {
+		t.Fatal(err)
+	}
+	got, _ := os.ReadFile(log)
+	want := "systemctl --user stop picom-session.service\n" +
+		"systemd-run --user --collect --quiet --unit=picom-session --setenv=DISPLAY=:1 --setenv=XAUTHORITY=/x -- picom --config /c\n"
+	if string(got) != want {
+		t.Fatalf("detach ran:\n%s\nwant:\n%s", got, want)
+	}
+	if err := (Session{}).detach("x", "y"); !errors.Is(err, ErrNoBus) {
+		t.Fatalf("no runtime directory: %v", err)
+	}
+}
+
+// fakeBinaries puts shell scripts named for programs first on PATH, and answers their directory.
+func fakeBinaries(t *testing.T, scripts map[string]string) string {
+	t.Helper()
+	dir := t.TempDir()
+	for name, body := range scripts {
+		if err := os.WriteFile(filepath.Join(dir, name), []byte("#!/bin/sh\n"+body+"\n"), 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	t.Setenv("PATH", dir+string(os.PathListSeparator)+os.Getenv("PATH"))
+	return dir
+}

modules/gnome-keyring/files/pam/login

@@ -0,0 +1,4 @@
+# The login keyring (module gnome-keyring, novox/hq ADR 0208, ADR 0102): the password typed at the
+# login screen unlocks the keyring, and the login session starts the keyring daemon with it.
+auth       optional     pam_gnome_keyring.so
+session    optional     pam_gnome_keyring.so auto_start

modules/gnome-keyring/files/pam/passwd

@@ -0,0 +1,3 @@
+# The login keyring (module gnome-keyring, novox/hq ADR 0208, ADR 0102): changing the account's
+# password changes the login keyring's with it, so the next login still unlocks it.
+password   optional     pam_gnome_keyring.so

modules/gnome-keyring/go.mod

@@ -0,0 +1,5 @@
+module gnomekeyring
+
+go 1.22
+
+require git.novox.be/novox/mesh-sdk/go v0.1.7

modules/gnome-keyring/go.sum

@@ -0,0 +1,2 @@
+git.novox.be/novox/mesh-sdk/go v0.1.7 h1:C0sTQmtTiyYH7bnqZb7PusXnqA37gKuT7Nqjn9gG47w=
+git.novox.be/novox/mesh-sdk/go v0.1.7/go.mod h1:GFuZUElBZ9A++mxgIKo97aXXo+kV0uJ/UkbhQPPIbrY=

modules/gnome-keyring/module.json

@@ -0,0 +1,76 @@
+{
+  "module": "gnome-keyring",
+  "version": "1",
+  "capabilities": [
+    "package-manager"
+  ],
+  "claims": [
+    {
+      "name": "node-secret-service",
+      "scope": "node"
+    }
+  ],
+  "tools": [
+    "gnome_keyring_unlocked",
+    "gnome_keyring_lock",
+    "gnome_keyring_collections",
+    "gnome_keyring_ssh_keys"
+  ],
+  "shell": [
+    {
+      "for": "xinitrc",
+      "slot": "first",
+      "code": "# The ssh agent (module gnome-keyring, novox/hq ADR 0208): gcr's, which the account's service manager\n# starts on first use from its socket. Named here, for the session and every terminal it starts, until\n# the account's environment can say a path under the runtime directory (see the module's README).\nSSH_AUTH_SOCK=\"${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/gcr/ssh\"\nexport SSH_AUTH_SOCK\n"
+    }
+  ],
+  "resources": [
+    {
+      "id": "package",
+      "type": "package",
+      "package": "gnome-keyring"
+    },
+    {
+      "id": "library",
+      "type": "package",
+      "package": "libsecret"
+    },
+    {
+      "id": "manager",
+      "type": "package",
+      "package": "seahorse"
+    },
+    {
+      "id": "pam-login",
+      "type": "file",
+      "path": "/etc/pam.d/login",
+      "mode": "0644",
+      "into": "block",
+      "at": "end",
+      "content": "# The login keyring (module gnome-keyring, novox/hq ADR 0208, ADR 0102): the password typed at the\n# login screen unlocks the keyring, and the login session starts the keyring daemon with it.\nauth       optional     pam_gnome_keyring.so\nsession    optional     pam_gnome_keyring.so auto_start\n"
+    },
+    {
+      "id": "pam-passwd",
+      "type": "file",
+      "path": "/etc/pam.d/passwd",
+      "mode": "0644",
+      "into": "block",
+      "at": "end",
+      "content": "# The login keyring (module gnome-keyring, novox/hq ADR 0208, ADR 0102): changing the account's\n# password changes the login keyring's with it, so the next login still unlocks it.\npassword   optional     pam_gnome_keyring.so\n"
+    }
+  ],
+  "build": {
+    "artifacts": [
+      {
+        "name": "tools",
+        "kind": "bundle",
+        "language": "go",
+        "system": "arch",
+        "from": "cmd/gnome-keyring-tools",
+        "binary": "gnome-keyring-tools",
+        "loads": [
+          "gnome-keyring-tools"
+        ]
+      }
+    ]
+  }
+}

modules/i3status-rust/README.md

@@ -0,0 +1,86 @@
+# i3status-rust
+
+The bars as a module (novox/hq ADR 0208, research 026/05).
+
+- Installs `i3status-rust`, and `pacman-contrib` for `checkupdates`, which the update block uses.
+  Claims the mesh's `node-bar` seat (no verbs yet, ADR 0208 §2). Requires `x11-display` on its own
+  machine: its bars are i3bar's.
+- Owns `~/.config/i3status-rust/`, both bars (`top-bar.toml`, `bottom-bar.toml`) and their icon set
+  (`icons/custom-icons.toml`).
+- Places the two `bar { }` blocks as its own i3 drop-in, `~/.config/i3/config.d/60-i3status-rust.conf`:
+  - the bottom bar shows the machine;
+  - the top bar shows the focused window and the tray, on the primary output.
+- Places two programs in `~/.local/bin`:
+  - `i3status-updates`, the pending-updates block;
+  - `i3bar-watchdog`, which brings back a bar that died.
+- Starts the watchdog once per session, from the session's start (the `xinitrc` slot `normal`). It ends
+  with the session's own process.
+
+## Tools
+
+| tool | does |
+|---|---|
+| `i3status_rust_reload` | the running bars re-read their files (i3status-rs restarts in place) |
+| `i3status_rust_blocks` | each bar's blocks in order, kind and settings, and what each shows now (one run of the bar) |
+| `i3status_rust_block_run` | one block alone, with the bar's theme and icons, to see what it shows or why it errors |
+| `i3status_rust_themes` | the themes on the machine and the one each bar uses |
+
+## The battery, and what else was left out
+
+A bar block that follows one machine's hardware is that machine model's hardware module's (ADR 0208
+§1), so the bottom bar here has none:
+
+- **the battery,** which only the laptop has;
+- **the GPU,** which was the laptop's AMD block, commented out for NVIDIA on the desktop;
+- **three Bluetooth headsets** by hardware address: one person's devices, not the bar's.
+
+i3status-rust reads no drop-in directory, and ADR 0208's slots cover `xinitrc` and `xresources` only,
+so a hardware module has no way into this file yet. Two ways forward, for the operator to choose:
+
+1. **Give the bar a slot.** A `shell`-style contribution `for: i3status-rust` would let the laptop's
+   hardware module add its battery block. That is a decision record of its own, extending ADR 0208 §4.
+2. **Blocks that show only where they apply.** i3status-rust's common `if_command` option (for
+   example `test -d /sys/class/power_supply/BAT0`) hides a block on a machine without the hardware.
+   That is "say it by what is there" (ADR 0112), but the knowledge stays in the bar.
+
+Until one of them is chosen, **the laptop's bar shows no battery** once this module is assigned.
+
+## What it improves on what was found
+
+- **The weather needs no key.** The found block used a weather service with an API key written in
+  plain text in the file, and a fixed city. It now uses the Norwegian Meteorological Institute, which
+  needs no key, located automatically.
+- **The update count is the module's own,** adopted from the operator's `~/scripts/pkg-updates`. It
+  counts AUR updates only where an AUR helper is installed. Clicking it lists the updates in the
+  launcher's menu, instead of a theme from a cloned theme repository.
+- **The faces** are JetBrains Mono Nerd Font, not Hack.
+- **The watchdog is no longer a hand-enabled user unit** that ran on one workstation and not the
+  other. It runs on both, once per session, and ends with the session.
+- The docker block's click, which ran a program installed on neither machine, is gone.
+
+## What it leaves as found
+
+- `~/.config/i3status-rust/scripts/` (a mouse battery script for one device).
+- `~/scripts/pkg-updates` and `~/scripts/i3-bar-watchdog`, replaced here.
+- The user unit `~/.config/systemd/user/i3-bar-watchdog.service` and its enablement link.
+
+## Migration (ADR 0182)
+
+1. **Revoke the weather API key** that was in the found `bottom-bar.toml`. It sat in plain text on
+   both workstations. The first push keeps the found file once and then writes the module's, which
+   has no key.
+2. Before the first push, on the laptop: `systemctl --user disable --now i3-bar-watchdog.service`.
+   Otherwise two watchdogs run. Then delete the unit file, `~/scripts/i3-bar-watchdog` and
+   `~/scripts/pkg-updates`.
+3. Until the `i3` module carries the main configuration, the found `~/.config/i3/config` still has its
+   own two `bar { }` blocks, and i3 shows four bars. The `i3` module's configuration has none.
+
+## Blockers
+
+- `node-bar`, `x11-display` and the `xinitrc` slot are ADR 0208's. Until the controller knows them,
+  `mctl` reads them as unknown.
+- The battery block waits for one of the two ways above.
+- The watchdog would be a user unit once user-scoped units ship (mesh-host #72). It is not, because it
+  runs per session and ends with the session, as a session-start line already does.
+- `pacman-contrib` is declared here. A future `pacman` module that wants `checkupdates` or `paccache`
+  takes it over, since a package is declared once per node.

modules/i3status-rust/cmd/i3status-rust-tools/args.go

@@ -0,0 +1,97 @@
+// Reading a tool's arguments: JSON numbers arrive as float64, and a missing argument is its default.
+// The same in every desktop module that carries it.
+package main
+
+import (
+	"fmt"
+	"math"
+	"strings"
+	"time"
+)
+
+// text is a string argument, trimmed; required says an empty one is refused.
+func text(args map[string]any, key string, required bool) (string, error) {
+	v, present := args[key]
+	if !present || v == nil {
+		if required {
+			return "", fmt.Errorf("%s is required", key)
+		}
+		return "", nil
+	}
+	s, ok := v.(string)
+	if !ok {
+		return "", fmt.Errorf("%s is a string, not %T", key, v)
+	}
+	s = strings.TrimSpace(s)
+	if s == "" && required {
+		return "", fmt.Errorf("%s is required", key)
+	}
+	return s, nil
+}
+
+// whole is a whole-number argument within [least, most], or def when absent.
+func whole(args map[string]any, key string, def, least, most int) (int, error) {
+	v, present := args[key]
+	if !present || v == nil {
+		return def, nil
+	}
+	f, ok := v.(float64)
+	if !ok {
+		if i, isInt := v.(int); isInt {
+			f = float64(i)
+		} else {
+			return 0, fmt.Errorf("%s is a number, not %T", key, v)
+		}
+	}
+	if f != math.Trunc(f) {
+		return 0, fmt.Errorf("%s is a whole number, not %v", key, f)
+	}
+	n := int(f)
+	if n < least || n > most {
+		return 0, fmt.Errorf("%s is %d; it is between %d and %d", key, n, least, most)
+	}
+	return n, nil
+}
+
+// flag is a boolean argument, or def when absent.
+func flag(args map[string]any, key string, def bool) (bool, error) {
+	v, present := args[key]
+	if !present || v == nil {
+		return def, nil
+	}
+	b, ok := v.(bool)
+	if !ok {
+		return false, fmt.Errorf("%s is true or false, not %T", key, v)
+	}
+	return b, nil
+}
+
+// texts is a list-of-strings argument.
+func texts(args map[string]any, key string) ([]string, error) {
+	v, present := args[key]
+	if !present || v == nil {
+		return nil, nil
+	}
+	list, ok := v.([]any)
+	if !ok {
+		if ss, isStrings := v.([]string); isStrings {
+			return ss, nil
+		}
+		return nil, fmt.Errorf("%s is a list of strings, not %T", key, v)
+	}
+	out := make([]string, 0, len(list))
+	for i, item := range list {
+		s, ok := item.(string)
+		if !ok {
+			return nil, fmt.Errorf("%s[%d] is a string, not %T", key, i, item)
+		}
+		out = append(out, s)
+	}
+	return out, nil
+}
+
+// seconds is a timeout argument in seconds, defaulted and bounded below the runtime's call limit.
+func seconds(args map[string]any, key string, def, most int) (time.Duration, error) {
+	n, err := whole(args, key, def, 1, most)
+	return time.Duration(n) * time.Second, err
+}

modules/i3status-rust/cmd/i3status-rust-tools/bar.go

@@ -0,0 +1,306 @@
+package main
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+	"syscall"
+	"time"
+)
+
+var bars = []string{"top", "bottom"}
+
+// A bar runs this long when a tool reads its values: long enough for every block's first update.
+const runFor = 4 * time.Second
+
+func configDir() string { return filepath.Join(operatorHome(), ".config", "i3status-rust") }
+
+func barFile(bar string) string { return filepath.Join(configDir(), bar+"-bar.toml") }
+
+func barsOf(bar string) ([]string, error) {
+	if bar == "" {
+		return bars, nil
+	}
+	for _, b := range bars {
+		if b == bar {
+			return []string{bar}, nil
+		}
+	}
+	return nil, fmt.Errorf("bar %q is top or bottom", bar)
+}
+
+// ReloadResult is what i3status_rust_reload answers.
+type ReloadResult struct {
+	Reached []int  `json:"reached"`
+	Note    string `json:"note"`
+}
+
+// Reload restarts every running i3status-rs in place, which re-reads its file (SIGUSR2).
+func Reload() ReloadResult {
+	reached := signalAll("i3status-rs", syscall.SIGUSR2)
+	if reached == nil {
+		return ReloadResult{Reached: []int{}, Note: "no bar is running: i3 starts them with the session"}
+	}
+	return ReloadResult{Reached: reached, Note: "each bar re-read its configuration"}
+}
+
+// Config is a bar's file cut into the part before its blocks and each block's own text.
+type Config struct {
+	Header string
+	Blocks []string
+}
+
+var blockStart = regexp.MustCompile(`(?m)^\[\[block\]\]\s*$`)
+
+func splitConfig(raw string) Config {
+	idx := blockStart.FindAllStringIndex(raw, -1)
+	if len(idx) == 0 {
+		return Config{Header: raw}
+	}
+	c := Config{Header: raw[:idx[0][0]]}
+	for i, at := range idx {
+		end := len(raw)
+		if i+1 < len(idx) {
+			end = idx[i+1][0]
+		}
+		c.Blocks = append(c.Blocks, raw[at[0]:end])
+	}
+	return c
+}
+
+// Block is one block of a bar.
+type Block struct {
+	Index    int               `json:"index"`
+	Kind     string            `json:"block"`
+	Settings map[string]string `json:"settings"`
+	Text     *string           `json:"text,omitempty"`
+	State    string            `json:"state,omitempty"`
+}
+
+var keyValue = regexp.MustCompile(`^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.+?)\s*$`)
+
+// describe reads a block's own top-level settings (not its sub-tables, such as clicks), as written.
+func describe(index int, raw string) Block {
+	b := Block{Index: index, Settings: map[string]string{}}
+	for _, line := range strings.Split(raw, "\n")[1:] {
+		line = strings.TrimSpace(line)
+		if strings.HasPrefix(line, "[") {
+			break
+		}
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		if m := keyValue.FindStringSubmatch(line); m != nil {
+			v := strings.Trim(m[2], `"`)
+			if m[1] == "block" {
+				b.Kind = v
+			} else {
+				b.Settings[m[1]] = v
+			}
+		}
+	}
+	return b
+}
+
+// BarBlocks is one bar's blocks.
+type BarBlocks struct {
+	Bar    string  `json:"bar"`
+	File   string  `json:"file"`
+	Blocks []Block `json:"blocks"`
+	Error  string  `json:"error,omitempty"`
+}
+
+// Blocks describes each bar's blocks, and with values what each shows now.
+func Blocks(bar string, values bool) ([]BarBlocks, error) {
+	which, err := barsOf(bar)
+	if err != nil {
+		return nil, err
+	}
+	var out []BarBlocks
+	for _, b := range which {
+		file := barFile(b)
+		raw, err := os.ReadFile(file)
+		if err != nil {
+			out = append(out, BarBlocks{Bar: b, File: file, Blocks: []Block{}, Error: err.Error()})
+			continue
+		}
+		c := splitConfig(string(raw))
+		bb := BarBlocks{Bar: b, File: file, Blocks: []Block{}}
+		for i, text := range c.Blocks {
+			bb.Blocks = append(bb.Blocks, describe(i, text))
+		}
+		if values {
+			shown, err := runBar(file)
+			if err != nil {
+				bb.Error = err.Error()
+			}
+			for i := range bb.Blocks {
+				if w, ok := shown[i]; ok {
+					text := w.text
+					bb.Blocks[i].Text, bb.Blocks[i].State = &text, w.state
+				}
+			}
+		}
+		out = append(out, bb)
+	}
+	return out, nil
+}
+
+type widgetText struct{ text, state string }
+
+// runBar runs i3status-rs on a file for a moment and answers each block's latest text, by index.
+// i3status-rs names each block's widgets by an instance "<index>:…", which is how they are told apart.
+func runBar(file string) (map[int]widgetText, error) {
+	s := findEnvironment() // the session when there is one; blocks that need none run without
+	r, err := s.run(runFor, "", "i3status-rs", file)
+	if err != nil && !errors.Is(err, ErrTimedOut) {
+		return nil, err
+	}
+	shown := parseStatus(r.Stdout)
+	if len(shown) == 0 {
+		msg := strings.TrimSpace(r.Stderr)
+		if msg == "" {
+			msg = "the bar showed nothing within " + runFor.String()
+		}
+		return shown, errors.New(msg)
+	}
+	return shown, nil
+}
+
+// parseStatus reads i3bar's protocol — a header, "[", then one JSON array per update — and answers
+// the last complete update's text per block index.
+func parseStatus(stream string) map[int]widgetText {
+	var last []map[string]any
+	for _, line := range strings.Split(stream, "\n") {
+		line = strings.TrimSuffix(strings.TrimPrefix(strings.TrimSpace(line), ","), ",")
+		if !strings.HasPrefix(line, "[{") && line != "[]" {
+			continue
+		}
+		var update []map[string]any
+		if json.Unmarshal([]byte(line), &update) == nil {
+			last = update
+		}
+	}
+	out := map[int]widgetText{}
+	for _, w := range last {
+		instance, _ := w["instance"].(string)
+		head, _, ok := strings.Cut(instance, ":")
+		if !ok {
+			continue // a separator
+		}
+		i, err := strconv.Atoi(head)
+		if err != nil {
+			continue
+		}
+		text, _ := w["full_text"].(string)
+		cur := out[i]
+		cur.text = strings.TrimSpace(strings.TrimSpace(cur.text) + " " + strings.TrimSpace(text))
+		if colour, _ := w["color"].(string); strings.EqualFold(colour, "#FF0000FF") {
+			cur.state = "critical"
+		}
+		out[i] = cur
+	}
+	return out
+}
+
+// RunResult is what i3status_rust_block_run answers.
+type RunResult struct {
+	Bar   string `json:"bar"`
+	Block Block  `json:"block"`
+	Error string `json:"error,omitempty"`
+}
+
+// BlockRun runs one block of a bar alone, with the bar's theme and icons.
+func BlockRun(bar string, index int) (RunResult, error) {
+	if _, err := barsOf(bar); err != nil || bar == "" {
+		return RunResult{}, fmt.Errorf("bar %q is top or bottom", bar)
+	}
+	raw, err := os.ReadFile(barFile(bar))
+	if err != nil {
+		return RunResult{}, err
+	}
+	c := splitConfig(string(raw))
+	if index >= len(c.Blocks) {
+		return RunResult{}, fmt.Errorf("the %s bar has %d blocks, numbered from 0", bar, len(c.Blocks))
+	}
+	tmp, err := os.CreateTemp("", "i3status-rust-block-*.toml")
+	if err != nil {
+		return RunResult{}, err
+	}
+	defer os.Remove(tmp.Name())
+	if _, err := tmp.WriteString(c.Header + c.Blocks[index]); err != nil {
+		tmp.Close()
+		return RunResult{}, err
+	}
+	tmp.Close()
+	out := RunResult{Bar: bar, Block: describe(index, c.Blocks[index])}
+	shown, err := runBar(tmp.Name())
+	if err != nil {
+		out.Error = err.Error()
+	}
+	if w, ok := shown[0]; ok {
+		text := w.text
+		out.Block.Text, out.Block.State = &text, w.state
+	}
+	return out, nil
+}
+
+// Theme is one bar theme.
+type Theme struct {
+	Name   string `json:"name"`
+	File   string `json:"file"`
+	Source string `json:"source"`
+}
+
+// ThemesResult is what i3status_rust_themes answers.
+type ThemesResult struct {
+	InUse  map[string]string `json:"in_use"`
+	Themes []Theme           `json:"themes"`
+}
+
+type themeDir struct{ path, source string }
+
+func themeDirs() []themeDir {
+	return []themeDir{
+		{filepath.Join(configDir(), "themes"), "the account's"},
+		{filepath.Join(operatorHome(), ".local", "share", "i3status-rust", "themes"), "the account's"},
+		{"/usr/share/i3status-rust/themes", "the distribution's"},
+	}
+}
+
+var themeName = regexp.MustCompile(`(?ms)^\[theme\]\s*$.*?^theme\s*=\s*"([^"]+)"`)
+
+// Themes lists the themes, the first directory winning a name, and the one each bar names.
+func Themes(dirs []themeDir) ThemesResult {
+	out := ThemesResult{InUse: map[string]string{}, Themes: []Theme{}}
+	for _, b := range bars {
+		if raw, err := os.ReadFile(barFile(b)); err == nil {
+			if m := themeName.FindStringSubmatch(string(raw)); m != nil {
+				out.InUse[b] = m[1]
+			}
+		}
+	}
+	seen := map[string]bool{}
+	for _, d := range dirs {
+		entries, err := os.ReadDir(d.path)
+		if err != nil {
+			continue
+		}
+		for _, e := range entries {
+			name, ok := strings.CutSuffix(e.Name(), ".toml")
+			if !ok || seen[name] {
+				continue
+			}
+			seen[name] = true
+			out.Themes = append(out.Themes, Theme{Name: name, File: filepath.Join(d.path, e.Name()), Source: d.source})
+		}
+	}
+	sort.Slice(out.Themes, func(i, j int) bool { return out.Themes[i].Name < out.Themes[j].Name })
+	return out
+}

modules/i3status-rust/cmd/i3status-rust-tools/bar_test.go

@@ -0,0 +1,141 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func source(t *testing.T, name string) string {
+	t.Helper()
+	raw, err := os.ReadFile(filepath.Join("..", "..", "files", name))
+	if err != nil {
+		t.Fatal(err)
+	}
+	return string(raw)
+}
+
+func TestTheModulesBarsSplitIntoTheirBlocksInOrder(t *testing.T) {
+	c := splitConfig(source(t, "bottom-bar.toml"))
+	var kinds []string
+	for i, b := range c.Blocks {
+		kinds = append(kinds, describe(i, b).Kind)
+	}
+	want := []string{"tea_timer", "custom", "cpu", "disk_space", "disk_space", "memory", "docker", "sound", "weather", "notify", "time"}
+	if !reflect.DeepEqual(kinds, want) {
+		t.Fatalf("%v", kinds)
+	}
+	if !strings.Contains(c.Header, `theme = "plain"`) || strings.Contains(c.Header, "[[block]]") {
+		t.Fatalf("header: %s", c.Header)
+	}
+	custom := describe(1, c.Blocks[1])
+	if custom.Settings["command"] != "~/.local/bin/i3status-updates 10" || custom.Settings["interval"] != "1800" {
+		t.Fatalf("a block's own settings, not its click's: %+v", custom)
+	}
+	if _, leaked := custom.Settings["cmd"]; leaked {
+		t.Fatal("the click's cmd was read as the block's")
+	}
+	top := splitConfig(source(t, "top-bar.toml"))
+	if len(top.Blocks) != 2 || describe(0, top.Blocks[0]).Kind != "focused_window" {
+		t.Fatalf("top: %+v", top.Blocks)
+	}
+}
+
+// Two updates of i3bar's protocol, as i3status-rs wrote them for the top bar on 2026-10-04.
+const stream = `{"version": 1, "click_events": true}
+[
+[{"full_text":" | ","color":"#FFFFFFFF","separator":false},{"full_text":" up 1d ","color":"#F1F1F1FF","name":"0","instance":"1:"}],
+[{"full_text":" | ","color":"#FFFFFFFF","separator":false},{"full_text":" ","color":"#FF0000FF","name":"0","instance":"0:"},{"full_text":"failed to connect to wayland ","color":"#FF0000FF","name":"0","instance":"0:"},{"full_text":" | "},{"full_text":" up 2d ","color":"#F1F1F1FF","name":"0","instance":"1:"}],
+`
+
+func TestTheLatestUpdateIsReadPerBlockIndex(t *testing.T) {
+	got := parseStatus(stream)
+	if got[1].text != "up 2d" || got[1].state != "" || got[0].text != "failed to connect to wayland" || got[0].state != "critical" || len(got) != 2 {
+		t.Fatalf("%+v", got)
+	}
+	if len(parseStatus("garbage\n[\n")) != 0 {
+		t.Fatal("no update is no blocks")
+	}
+}
+
+// installBars puts the module's bars where i3status-rs would read them, and a fake i3status-rs.
+func installBars(t *testing.T) string {
+	t.Helper()
+	root := fakeMachine(t)
+	dir := filepath.Join(root, "home", ".config", "i3status-rust")
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	for _, f := range []string{"top-bar.toml", "bottom-bar.toml"} {
+		if err := os.WriteFile(filepath.Join(dir, f), []byte(source(t, f)), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	bin := fakeBinaries(t, map[string]string{"i3status-rs": `cp "$1" "$LOG.config"
+printf '%s\n' '{"version": 1}' '[' '[{"full_text":"first","instance":"0:"},{"full_text":"second","instance":"1:"}],'`})
+	t.Setenv("LOG", filepath.Join(bin, "log"))
+	return bin
+}
+
+func TestBlocksPairEachBlockWithWhatItShows(t *testing.T) {
+	installBars(t)
+	got, err := Blocks("top", true)
+	if err != nil || len(got) != 1 {
+		t.Fatalf("%+v, %v", got, err)
+	}
+	b := got[0].Blocks
+	if len(b) != 2 || b[0].Kind != "focused_window" || b[0].Text == nil || *b[0].Text != "first" || *b[1].Text != "second" {
+		t.Fatalf("%+v", got)
+	}
+	if all, _ := Blocks("", false); len(all) != 2 || all[1].Blocks[0].Text != nil {
+		t.Fatalf("both bars, without values: %+v", all)
+	}
+	if _, err := Blocks("side", false); err == nil {
+		t.Fatal("an unknown bar was accepted")
+	}
+}
+
+func TestOneBlockRunsAloneWithTheBarsThemeAndIcons(t *testing.T) {
+	bin := installBars(t)
+	got, err := BlockRun("bottom", 8)
+	if err != nil || got.Block.Kind != "weather" || got.Block.Text == nil || *got.Block.Text != "first" {
+		t.Fatalf("%+v, %v", got, err)
+	}
+	ran, _ := os.ReadFile(filepath.Join(bin, "log.config"))
+	if strings.Count(string(ran), "[[block]]") != 1 || !strings.Contains(string(ran), `name = "metno"`) ||
+		!strings.Contains(string(ran), `icons = "custom-icons"`) {
+		t.Fatalf("the config it ran:\n%s", ran)
+	}
+	if _, err := BlockRun("bottom", 11); err == nil {
+		t.Fatal("a block past the end was accepted")
+	}
+	if _, err := BlockRun("", 0); err == nil {
+		t.Fatal("no bar was accepted")
+	}
+}
+
+func TestThemesListEachOnceWithTheOnesInUse(t *testing.T) {
+	installBars(t)
+	root := t.TempDir()
+	for _, f := range []string{"mine/plain.toml", "system/plain.toml", "system/nord-dark.toml", "system/README"} {
+		if err := os.MkdirAll(filepath.Dir(filepath.Join(root, f)), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(root, f), nil, 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	got := Themes([]themeDir{{filepath.Join(root, "mine"), "mine"}, {filepath.Join(root, "system"), "system"}})
+	if got.InUse["top"] != "plain" || got.InUse["bottom"] != "plain" || len(got.Themes) != 2 || got.Themes[1].Source != "mine" {
+		t.Fatalf("%+v", got)
+	}
+}
+
+func TestReloadWithNoBarRunningSaysSo(t *testing.T) {
+	fakeMachine(t)
+	if r := Reload(); len(r.Reached) != 0 || !strings.Contains(r.Note, "no bar") {
+		t.Fatalf("%+v", r)
+	}
+}

modules/i3status-rust/cmd/i3status-rust-tools/main.go

@@ -0,0 +1,81 @@
+// i3status-rust's Go tools bundle (novox/hq ADR 0188, ADR 0193, ADR 0208): the bars' tools, served by
+// the node's runtime as the operator account. node-bar has no verbs yet (ADR 0208 §2), so every tool
+// here is the module's own.
+package main
+
+import (
+	"fmt"
+	"os"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+func main() {
+	if err := stdio.Serve("", tools()); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+var barInput = map[string]any{"type": "string", "enum": bars, "description": "which bar (default: both)"}
+
+func tools() []stdio.Tool {
+	return []stdio.Tool{
+		{
+			Name: "i3status_rust_reload",
+			Description: "Make the running bars re-read their configuration (i3status-rs restarts in place). " +
+				"Answers the processes reached.",
+			Run: func(map[string]any) (any, error) { return Reload(), nil },
+		},
+		{
+			Name: "i3status_rust_blocks",
+			Description: "What each bar shows: every block in order, its kind and settings, and with values " +
+				"(the default) what it shows right now, from one run of the bar's configuration.",
+			Input: map[string]any{
+				"bar":    barInput,
+				"values": map[string]any{"type": "boolean", "description": "run the bar once to read each block's current text (default true; a few seconds)"},
+			},
+			Run: func(args map[string]any) (any, error) {
+				bar, err := text(args, "bar", false)
+				if err != nil {
+					return nil, err
+				}
+				values, err := flag(args, "values", true)
+				if err != nil {
+					return nil, err
+				}
+				return Blocks(bar, values)
+			},
+		},
+		{
+			Name: "i3status_rust_block_run",
+			Description: "Run one block of a bar once, alone, and answer what it shows — to see a block that " +
+				"errors, or what a click would act on.",
+			Input: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"bar":   map[string]any{"type": "string", "enum": bars},
+					"index": map[string]any{"type": "integer", "description": "the block's position in the bar, from 0, as i3status_rust_blocks answers it"},
+				},
+				"required": []string{"bar", "index"},
+			},
+			Run: func(args map[string]any) (any, error) {
+				bar, err := text(args, "bar", true)
+				if err != nil {
+					return nil, err
+				}
+				index, err := whole(args, "index", 0, 0, 200)
+				if err != nil {
+					return nil, err
+				}
+				return BlockRun(bar, index)
+			},
+		},
+		{
+			Name: "i3status_rust_themes",
+			Description: "The bar themes on this machine (the distribution's and the account's own) and the " +
+				"one each bar uses.",
+			Run: func(map[string]any) (any, error) { return Themes(themeDirs()), nil },
+		},
+	}
+}

modules/i3status-rust/cmd/i3status-rust-tools/manifest_helpers_test.go

@@ -0,0 +1,175 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// The module's manifest, read the way the catalogue reads it, for the manifest tests. The same in
+// every desktop module that carries it.
+
+type manifest struct {
+	Module       string           `json:"module"`
+	Version      string           `json:"version"`
+	Capabilities []string         `json:"capabilities"`
+	Requires     []string         `json:"requires"`
+	Claims       []claim          `json:"claims"`
+	Seats        []any            `json:"seats"`
+	Tools        []string         `json:"tools"`
+	Environment  *environment     `json:"environment"`
+	Shell        []shellCode      `json:"shell"`
+	Resources    []map[string]any `json:"resources"`
+	Build        struct {
+		Artifacts []map[string]any `json:"artifacts"`
+	} `json:"build"`
+}
+
+type claim struct {
+	Name   string   `json:"name"`
+	Scope  string   `json:"scope"`
+	Serves []string `json:"serves"`
+}
+
+type environment struct {
+	Variables map[string]string `json:"variables"`
+	Path      []map[string]any  `json:"path"`
+}
+
+type shellCode struct {
+	For  string `json:"for"`
+	Slot string `json:"slot"`
+	Code string `json:"code"`
+}
+
+func readManifest(t *testing.T) manifest {
+	t.Helper()
+	raw, err := os.ReadFile(filepath.Join("..", "..", "module.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	dec := json.NewDecoder(strings.NewReader(string(raw)))
+	dec.DisallowUnknownFields()
+	var m manifest
+	if err := dec.Decode(&m); err != nil {
+		t.Fatalf("module.json: %v", err)
+	}
+	return m
+}
+
+func (m manifest) resource(t *testing.T, id string) map[string]any {
+	t.Helper()
+	for _, r := range m.Resources {
+		if r["id"] == id {
+			return r
+		}
+	}
+	t.Fatalf("no resource %q", id)
+	return nil
+}
+
+func (m manifest) packages() (present, absent []string) {
+	for _, r := range m.Resources {
+		if r["type"] == "package" {
+			if r["absent"] == true {
+				absent = append(absent, r["package"].(string))
+			} else {
+				present = append(present, r["package"].(string))
+			}
+		}
+	}
+	return present, absent
+}
+
+// sameAsSource checks that a file resource's content is byte for byte the module's source file, so
+// the readable file in the repository is what the machine gets.
+func (m manifest) sameAsSource(t *testing.T, id, source string) {
+	t.Helper()
+	want, err := os.ReadFile(filepath.Join("..", "..", source))
+	if err != nil {
+		t.Fatal(err)
+	}
+	r := m.resource(t, id)
+	if r["type"] != "file" {
+		t.Fatalf("%s is a %v, not a file", id, r["type"])
+	}
+	if got, _ := r["content"].(string); got != string(want) {
+		t.Fatalf("resource %s's content is not %s: edit the source and copy it into module.json", id, source)
+	}
+	if r["owner"] != "${machine:account}" && !strings.HasPrefix(r["path"].(string), "/etc/") {
+		t.Fatalf("%s under the home is the account's", id)
+	}
+}
+
+// checkTheToolsAgree checks that the manifest lists the module's own tools exactly, that the bundle
+// serves each seat verb the claims promise as <seat>.<verb>, and that the Go bundle is declared.
+func checkTheToolsAgree(t *testing.T, m manifest) {
+	t.Helper()
+	own, seat := map[string]bool{}, map[string]bool{}
+	for _, tool := range tools() {
+		if strings.Contains(tool.Name, ".") {
+			seat[tool.Name] = true
+		} else {
+			own[tool.Name] = true
+		}
+		if strings.TrimSpace(tool.Description) == "" {
+			t.Errorf("%s has no description", tool.Name)
+		}
+	}
+	listed := map[string]bool{}
+	for _, name := range m.Tools {
+		listed[name] = true
+		if !own[name] {
+			t.Errorf("module.json lists %s, which the bundle does not serve", name)
+		}
+	}
+	for name := range own {
+		if !listed[name] {
+			t.Errorf("the bundle serves %s, which module.json does not list", name)
+		}
+		if !strings.HasPrefix(name, strings.ReplaceAll(m.Module, "-", "_")+"_") {
+			t.Errorf("%s is not prefixed with the module's name", name)
+		}
+	}
+	promised := map[string]bool{}
+	for _, c := range m.Claims {
+		for _, verb := range c.Serves {
+			promised[c.Name+"."+verb] = true
+			if !seat[c.Name+"."+verb] {
+				t.Errorf("the claim on %s promises %s, which the bundle does not serve", c.Name, verb)
+			}
+		}
+	}
+	for name := range seat {
+		if !promised[name] {
+			t.Errorf("the bundle serves %s, which no claim promises", name)
+		}
+	}
+	var bundle map[string]any
+	for _, a := range m.Build.Artifacts {
+		if a["kind"] == "bundle" {
+			bundle = a
+		}
+	}
+	if bundle == nil || bundle["language"] != "go" || bundle["system"] != "arch" ||
+		bundle["from"] != "cmd/"+m.Module+"-tools" || bundle["binary"] != m.Module+"-tools" {
+		t.Errorf("the Go tools bundle: %v", bundle)
+	}
+}
+
+// checkNoSecretsOrInstallationNames refuses what a catalogue manifest must never carry.
+func checkNoSecretsOrInstallationNames(t *testing.T) {
+	t.Helper()
+	raw, err := os.ReadFile(filepath.Join("..", "..", "module.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := strings.ToLower(string(raw))
+	for _, never := range []string{"/home/", "jochen", "g14", "shanks", "novox.be", "api_key", ".hal/", "greenclip daemon"} {
+		if strings.Contains(s, never) {
+			t.Errorf("module.json names %q", never)
+		}
+	}
+}

modules/i3status-rust/cmd/i3status-rust-tools/manifest_test.go

@@ -0,0 +1,71 @@
+package main
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+)
+
+// i3status-rust's shape (novox/hq ADR 0208): it claims node-bar, requires the X display on its own
+// machine (its bars are i3bar's), owns its two bars and their icons, places the bars as an i3 drop-in,
+// and runs the bar watchdog once per session. No block follows one machine's hardware or one person's
+// devices.
+
+func TestItClaimsTheBarSeatAndRequiresTheXDisplay(t *testing.T) {
+	m := readManifest(t)
+	if m.Module != "i3status-rust" || m.Seats != nil {
+		t.Fatalf("module %q declares seats %v", m.Module, m.Seats)
+	}
+	if !reflect.DeepEqual(m.Claims, []claim{{Name: "node-bar", Scope: "node"}}) {
+		t.Fatalf("claims: %+v", m.Claims)
+	}
+	if !reflect.DeepEqual(m.Requires, []string{"x11-display"}) {
+		t.Fatalf("requires: %v", m.Requires)
+	}
+	if present, absent := m.packages(); !reflect.DeepEqual(present, []string{"i3status-rust", "pacman-contrib"}) || absent != nil {
+		t.Fatalf("packages: %v, absent %v", present, absent)
+	}
+}
+
+func TestItOwnsItsFilesAsWrittenInTheModule(t *testing.T) {
+	m := readManifest(t)
+	for id, src := range map[string]string{
+		"top-bar": "files/top-bar.toml", "bottom-bar": "files/bottom-bar.toml", "icons": "files/icons/custom-icons.toml",
+		"updates": "files/bin/i3status-updates", "watchdog": "files/bin/i3bar-watchdog", "i3-bars": "files/i3/60-i3status-rust.conf",
+	} {
+		m.sameAsSource(t, id, src)
+	}
+}
+
+func TestNoBlockFollowsAMachinesHardwareOrAPersonsDevicesOrCarriesAKey(t *testing.T) {
+	m := readManifest(t)
+	bottom := m.resource(t, "bottom-bar")["content"].(string)
+	for _, never := range []string{`block = "battery"`, `block = "amd_gpu"`, `block = "nvidia_gpu"`, "mac = ", "api_key", "city_id", "openweathermap", "~/scripts/"} {
+		if strings.Contains(bottom, never) {
+			t.Errorf("the bottom bar has %s", never)
+		}
+	}
+}
+
+func TestTheBarsAreAnI3DropInAndTheWatchdogRunsOncePerSession(t *testing.T) {
+	m := readManifest(t)
+	bars := m.resource(t, "i3-bars")
+	if bars["path"] != "${machine:account-home}/.config/i3/config.d/60-i3status-rust.conf" {
+		t.Fatalf("%v", bars["path"])
+	}
+	c := bars["content"].(string)
+	if strings.Count(c, "bar {") != 2 || !strings.Contains(c, "status_command i3status-rs ~/.config/i3status-rust/bottom-bar.toml") ||
+		!strings.Contains(c, "font pango:JetBrainsMono Nerd Font 11") {
+		t.Fatalf("%s", c)
+	}
+	if len(m.Shell) != 1 || m.Shell[0].For != "xinitrc" || m.Shell[0].Slot != "normal" ||
+		!strings.Contains(m.Shell[0].Code, `"$HOME/.local/bin/i3bar-watchdog" "$$" &`) {
+		t.Fatalf("%+v", m.Shell)
+	}
+}
+
+func TestTheToolsAgreeWithTheManifest(t *testing.T) {
+	m := readManifest(t)
+	checkTheToolsAgree(t, m)
+	checkNoSecretsOrInstallationNames(t)
+}

modules/i3status-rust/cmd/i3status-rust-tools/session.go

@@ -0,0 +1,423 @@
+// The operator's graphical session, as a tool the node's runtime runs finds it (novox/hq ADR 0208).
+//
+// The runtime is a system service running as the operator account (ADR 0175): it has the account's
+// uid and none of the session's environment — no DISPLAY, no XAUTHORITY, no session bus. A tool that
+// draws on the screen or talks to the desktop's D-Bus must find them. It reads them from a process of
+// the account that is part of the session (the window manager first), the same thing `loginctl` and
+// a person's own shell would point at, and says where it found them.
+//
+// Long-lived programs a tool starts go to the account's own service manager through `systemd-run
+// --user`, never as children of the tool: the runtime's unit is a cgroup the service manager empties
+// whenever the runtime restarts, and a compositor or a clipboard owner started from inside it would
+// die with it.
+//
+// This file is the same in every desktop module that carries it; it moves into the Go SDK once a
+// second consumer outside the desktop wants it.
+package main
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"syscall"
+	"time"
+)
+
+// Where the session is looked for. Variables so a test can point them at a fake tree.
+var (
+	procRoot   = "/proc"
+	runUserDir = "/run/user"
+	x11Sockets = "/tmp/.X11-unix"
+)
+
+// sessionHolders are the processes whose environment is the session's, best first: the window
+// manager is the session, the rest are its children. Anything else carrying DISPLAY ranks after them.
+var sessionHolders = []string{"i3", "sway", "i3bar", "picom", "xss-lock", "dunst", "clipmenud", "xterm"}
+
+// sessionKeys are the variables a session carries that a tool hands on to what it runs.
+var sessionKeys = []string{"DISPLAY", "XAUTHORITY", "WAYLAND_DISPLAY", "DBUS_SESSION_BUS_ADDRESS",
+	"XDG_RUNTIME_DIR", "XDG_SESSION_ID", "I3SOCK"}
+
+// Session is what a tool needs to reach the operator's desktop.
+type Session struct {
+	UID        int    `json:"uid"`
+	Display    string `json:"display,omitempty"`
+	XAuthority string `json:"xauthority,omitempty"`
+	Wayland    string `json:"wayland_display,omitempty"`
+	Bus        string `json:"bus,omitempty"`
+	RuntimeDir string `json:"runtime_dir,omitempty"`
+	SessionID  string `json:"session_id,omitempty"`
+	I3Sock     string `json:"i3sock,omitempty"`
+	// From says where the values were found: the tool's own environment, a process, or the socket.
+	From string `json:"from"`
+}
+
+// ErrNoSession is answered by a tool that needs the desktop when nobody is logged in to it.
+var ErrNoSession = errors.New("no graphical session")
+
+// ErrTimedOut is what run answers for a command ended because it ran past its time.
+var ErrTimedOut = errors.New("timed out")
+
+// ErrNoBus is answered by a tool that needs the session bus when the account has none.
+var ErrNoBus = errors.New("no session bus")
+
+// operatorHome is the account's home: what the runtime was told, else the process's own.
+func operatorHome() string {
+	if h := strings.TrimSpace(os.Getenv("MESH_OPERATOR_HOME")); h != "" {
+		return h
+	}
+	h, _ := os.UserHomeDir()
+	return h
+}
+
+// findSession finds the graphical session of the account this tool runs as, or answers
+// ErrNoSession with what it looked at.
+func findSession() (Session, error) {
+	s := findEnvironment()
+	if s.Display == "" && s.Wayland == "" {
+		return s, fmt.Errorf("%w for uid %d on this machine: no process of the account carries DISPLAY "+
+			"or WAYLAND_DISPLAY, and no X server socket in %s has an authority file to go with it. "+
+			"Is anyone logged in to the desktop?", ErrNoSession, s.UID, x11Sockets)
+	}
+	return s, nil
+}
+
+// findBus finds the account's session bus, which a logged-in account has whether or not a desktop
+// is running.
+func findBus() (Session, error) {
+	s := findEnvironment()
+	if s.Bus == "" {
+		return s, fmt.Errorf("%w for uid %d: DBUS_SESSION_BUS_ADDRESS is not set and %s does not exist "+
+			"(the account is not logged in)", ErrNoBus, s.UID, filepath.Join(runUserDir, strconv.Itoa(s.UID), "bus"))
+	}
+	return s, nil
+}
+
+func findEnvironment() Session {
+	uid := os.Getuid()
+	s := Session{UID: uid}
+	own := map[string]string{}
+	for _, k := range sessionKeys {
+		own[k] = os.Getenv(k)
+	}
+	if own["DISPLAY"] != "" || own["WAYLAND_DISPLAY"] != "" {
+		s.fill(own)
+		s.From = "the tool's own environment"
+	} else if pid, comm, env, ok := sessionProcess(uid); ok {
+		s.fill(env)
+		s.From = fmt.Sprintf("process %s (pid %d)", comm, pid)
+	} else if display, ok := lonelyX11Socket(); ok {
+		if a := filepath.Join(operatorHome(), ".Xauthority"); exists(a) {
+			s.Display, s.XAuthority = display, a
+			s.From = "the X server socket and the account's ~/.Xauthority"
+		}
+		s.fill(own)
+	} else {
+		s.fill(own)
+		s.From = "nothing: no session found"
+	}
+	// The bus and the runtime directory are the account's, whether or not the process named them.
+	runtime := filepath.Join(runUserDir, strconv.Itoa(uid))
+	if s.RuntimeDir == "" && exists(runtime) {
+		s.RuntimeDir = runtime
+	}
+	if s.Bus == "" && s.RuntimeDir != "" && exists(filepath.Join(s.RuntimeDir, "bus")) {
+		s.Bus = "unix:path=" + filepath.Join(s.RuntimeDir, "bus")
+	}
+	return s
+}
+
+func (s *Session) fill(env map[string]string) {
+	set := func(dst *string, key string) {
+		if *dst == "" {
+			*dst = env[key]
+		}
+	}
+	set(&s.Display, "DISPLAY")
+	set(&s.XAuthority, "XAUTHORITY")
+	set(&s.Wayland, "WAYLAND_DISPLAY")
+	set(&s.Bus, "DBUS_SESSION_BUS_ADDRESS")
+	set(&s.RuntimeDir, "XDG_RUNTIME_DIR")
+	set(&s.SessionID, "XDG_SESSION_ID")
+	set(&s.I3Sock, "I3SOCK")
+}
+
+// sessionProcess is the best process of this uid whose environment names a display.
+func sessionProcess(uid int) (int, string, map[string]string, bool) {
+	entries, err := os.ReadDir(procRoot)
+	if err != nil {
+		return 0, "", nil, false
+	}
+	type candidate struct {
+		pid  int
+		comm string
+		env  map[string]string
+		rank int
+	}
+	var found []candidate
+	for _, e := range entries {
+		pid, err := strconv.Atoi(e.Name())
+		if err != nil {
+			continue
+		}
+		dir := filepath.Join(procRoot, e.Name())
+		if owner, ok := ownerOf(dir); !ok || owner != uid {
+			continue
+		}
+		raw, err := os.ReadFile(filepath.Join(dir, "environ"))
+		if err != nil {
+			continue
+		}
+		env := parseEnviron(raw)
+		if env["DISPLAY"] == "" && env["WAYLAND_DISPLAY"] == "" {
+			continue
+		}
+		comm := readTrimmed(filepath.Join(dir, "comm"))
+		rank := len(sessionHolders)
+		for i, h := range sessionHolders {
+			if h == comm {
+				rank = i
+				break
+			}
+		}
+		found = append(found, candidate{pid, comm, env, rank})
+	}
+	if len(found) == 0 {
+		return 0, "", nil, false
+	}
+	sort.Slice(found, func(i, j int) bool {
+		if found[i].rank != found[j].rank {
+			return found[i].rank < found[j].rank
+		}
+		return found[i].pid > found[j].pid // the newer of two equals
+	})
+	best := found[0]
+	return best.pid, best.comm, best.env, true
+}
+
+func parseEnviron(raw []byte) map[string]string {
+	env := map[string]string{}
+	for _, kv := range bytes.Split(raw, []byte{0}) {
+		if i := bytes.IndexByte(kv, '='); i > 0 {
+			env[string(kv[:i])] = string(kv[i+1:])
+		}
+	}
+	return env
+}
+
+func ownerOf(path string) (int, bool) {
+	info, err := os.Stat(path)
+	if err != nil {
+		return 0, false
+	}
+	st, ok := info.Sys().(*syscall.Stat_t)
+	if !ok {
+		return 0, false
+	}
+	return int(st.Uid), true
+}
+
+// lonelyX11Socket is the display of the one X server socket there is, when there is exactly one.
+func lonelyX11Socket() (string, bool) {
+	entries, err := os.ReadDir(x11Sockets)
+	if err != nil {
+		return "", false
+	}
+	var displays []string
+	for _, e := range entries {
+		if n := strings.TrimPrefix(e.Name(), "X"); n != e.Name() {
+			if _, err := strconv.Atoi(n); err == nil {
+				displays = append(displays, ":"+n)
+			}
+		}
+	}
+	if len(displays) != 1 {
+		return "", false
+	}
+	return displays[0], true
+}
+
+func readTrimmed(path string) string {
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(string(b))
+}
+
+func exists(path string) bool {
+	_, err := os.Stat(path)
+	return err == nil
+}
+
+// Env is this process's environment with the session's variables in place of its own.
+func (s Session) Env() []string {
+	drop := map[string]bool{}
+	for _, k := range sessionKeys {
+		drop[k] = true
+	}
+	var env []string
+	for _, kv := range os.Environ() {
+		if i := strings.IndexByte(kv, '='); i > 0 && drop[kv[:i]] {
+			continue
+		}
+		env = append(env, kv)
+	}
+	add := func(k, v string) {
+		if v != "" {
+			env = append(env, k+"="+v)
+		}
+	}
+	add("DISPLAY", s.Display)
+	add("XAUTHORITY", s.XAuthority)
+	add("WAYLAND_DISPLAY", s.Wayland)
+	add("DBUS_SESSION_BUS_ADDRESS", s.Bus)
+	add("XDG_RUNTIME_DIR", s.RuntimeDir)
+	add("XDG_SESSION_ID", s.SessionID)
+	add("I3SOCK", s.I3Sock)
+	return env
+}
+
+// mostOutput bounds what a command may answer with, per stream.
+const mostOutput = 256 << 10
+
+// Result is what a command did.
+type Result struct {
+	Stdout    string `json:"stdout"`
+	Stderr    string `json:"stderr,omitempty"`
+	Code      int    `json:"code"`
+	Truncated bool   `json:"truncated,omitempty"`
+}
+
+// run runs a command in the session's environment, its input given, ended with everything it
+// started after timeout. A command that is not installed is an error naming it; one that exits
+// non-zero is a Result with its code, for the caller to judge.
+func (s Session) run(timeout time.Duration, stdin string, name string, args ...string) (Result, error) {
+	path, err := exec.LookPath(name)
+	if err != nil {
+		return Result{}, fmt.Errorf("%s is not installed on this machine", name)
+	}
+	cmd := exec.Command(path, args...)
+	cmd.Env = s.Env()
+	if home := operatorHome(); exists(home) {
+		cmd.Dir = home
+	}
+	if stdin != "" {
+		cmd.Stdin = strings.NewReader(stdin)
+	}
+	var out, errOut capped
+	cmd.Stdout, cmd.Stderr = &out, &errOut
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+	if err := cmd.Start(); err != nil {
+		return Result{}, fmt.Errorf("%s: %w", name, err)
+	}
+	done := make(chan error, 1)
+	go func() { done <- cmd.Wait() }()
+	select {
+	case err = <-done:
+	case <-time.After(timeout):
+		_ = syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)
+		<-done
+		return Result{Stdout: out.String(), Stderr: errOut.String()},
+			fmt.Errorf("%s did not finish within %s and was ended: %w", name, timeout, ErrTimedOut)
+	}
+	r := Result{Stdout: out.String(), Stderr: errOut.String(), Truncated: out.cut || errOut.cut}
+	var exit *exec.ExitError
+	if errors.As(err, &exit) {
+		r.Code = exit.ExitCode()
+	} else if err != nil {
+		return r, fmt.Errorf("%s: %w", name, err)
+	}
+	return r, nil
+}
+
+// detach starts a long-lived program under the account's own service manager, as a transient unit
+// that carries the session's display, so it outlives the runtime that asked for it. A unit already
+// running under the same name is stopped first, so a fixed name means "at most one".
+func (s Session) detach(unit string, args ...string) error {
+	if s.RuntimeDir == "" {
+		return fmt.Errorf("%w: the account's runtime directory is missing, so its service manager "+
+			"cannot be reached", ErrNoBus)
+	}
+	_, _ = s.run(5*time.Second, "", "systemctl", "--user", "stop", unit+".service")
+	call := []string{"--user", "--collect", "--quiet", "--unit=" + unit}
+	for _, kv := range [][2]string{{"DISPLAY", s.Display}, {"XAUTHORITY", s.XAuthority},
+		{"WAYLAND_DISPLAY", s.Wayland}, {"XDG_SESSION_ID", s.SessionID}, {"I3SOCK", s.I3Sock}} {
+		if kv[1] != "" {
+			call = append(call, "--setenv="+kv[0]+"="+kv[1])
+		}
+	}
+	call = append(call, "--")
+	call = append(call, args...)
+	r, err := s.run(10*time.Second, "", "systemd-run", call...)
+	if err != nil {
+		return err
+	}
+	if r.Code != 0 {
+		return fmt.Errorf("systemd-run %s: %s", unit, strings.TrimSpace(r.Stderr))
+	}
+	return nil
+}
+
+// uniqueUnit is a transient unit name that will not collide with an earlier one.
+func uniqueUnit(prefix string) string {
+	return fmt.Sprintf("%s-%d", prefix, time.Now().UnixNano())
+}
+
+type capped struct {
+	bytes.Buffer
+	cut bool
+}
+
+func (c *capped) Write(p []byte) (int, error) {
+	if room := mostOutput - c.Len(); room < len(p) {
+		if room > 0 {
+			c.Buffer.Write(p[:room])
+		}
+		c.cut = true
+		return len(p), nil
+	}
+	return c.Buffer.Write(p)
+}
+
+// processesOf are the pids of this uid's processes whose command name is comm, oldest first.
+func processesOf(comm string) []int {
+	entries, err := os.ReadDir(procRoot)
+	if err != nil {
+		return nil
+	}
+	uid := os.Getuid()
+	var pids []int
+	for _, e := range entries {
+		pid, err := strconv.Atoi(e.Name())
+		if err != nil {
+			continue
+		}
+		dir := filepath.Join(procRoot, e.Name())
+		if owner, ok := ownerOf(dir); !ok || owner != uid {
+			continue
+		}
+		if readTrimmed(filepath.Join(dir, "comm")) == comm {
+			pids = append(pids, pid)
+		}
+	}
+	sort.Ints(pids)
+	return pids
+}
+
+// signalAll sends sig to every process of this uid named comm, and answers the pids it reached.
+func signalAll(comm string, sig syscall.Signal) []int {
+	var reached []int
+	for _, pid := range processesOf(comm) {
+		if syscall.Kill(pid, sig) == nil {
+			reached = append(reached, pid)
+		}
+	}
+	return reached
+}

modules/i3status-rust/cmd/i3status-rust-tools/session_test.go

@@ -0,0 +1,174 @@
+package main
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+)
+
+// fakeMachine points the session finder at a temporary /proc, /run/user and X socket directory, with
+// none of the test process's own session variables, and gives back the root.
+func fakeMachine(t *testing.T) string {
+	t.Helper()
+	root := t.TempDir()
+	procRoot, runUserDir, x11Sockets = filepath.Join(root, "proc"), filepath.Join(root, "run-user"), filepath.Join(root, "x11")
+	for _, d := range []string{procRoot, runUserDir, x11Sockets} {
+		if err := os.MkdirAll(d, 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	for _, k := range sessionKeys {
+		t.Setenv(k, "")
+	}
+	t.Setenv("MESH_OPERATOR_HOME", filepath.Join(root, "home"))
+	t.Cleanup(func() { procRoot, runUserDir, x11Sockets = "/proc", "/run/user", "/tmp/.X11-unix" })
+	return root
+}
+
+func fakeProcess(t *testing.T, pid int, comm string, env ...string) {
+	t.Helper()
+	dir := filepath.Join(procRoot, strconv.Itoa(pid))
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "comm"), []byte(comm+"\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "environ"), []byte(strings.Join(env, "\x00")+"\x00"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestTheSessionIsReadFromTheWindowManagerBeforeAnyOtherProcess(t *testing.T) {
+	fakeMachine(t)
+	fakeProcess(t, 900, "xterm", "DISPLAY=:9", "XAUTHORITY=/elsewhere")
+	fakeProcess(t, 100, "i3", "DISPLAY=:1", "XAUTHORITY=/home/op/.Xauthority",
+		"DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus", "XDG_SESSION_ID=3", "SECRET_TOKEN=never-copied")
+	fakeProcess(t, 50, "bash", "PATH=/usr/bin")
+	s, err := findSession()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if s.Display != ":1" || s.XAuthority != "/home/op/.Xauthority" || s.SessionID != "3" || !strings.Contains(s.From, "i3 (pid 100)") {
+		t.Fatalf("the window manager's environment: %+v", s)
+	}
+	for _, kv := range s.Env() {
+		if strings.HasPrefix(kv, "SECRET_TOKEN=") {
+			t.Fatal("a variable of the session process that is not a session variable was handed on")
+		}
+	}
+}
+
+func TestAnyProcessCarryingADisplayServesWhenTheWindowManagerIsNotFound(t *testing.T) {
+	fakeMachine(t)
+	fakeProcess(t, 10, "firefox", "DISPLAY=:0")
+	fakeProcess(t, 20, "firefox", "DISPLAY=:2")
+	s, err := findSession()
+	if err != nil || s.Display != ":2" {
+		t.Fatalf("the newest of two equals: %+v, %v", s, err)
+	}
+}
+
+func TestNoSessionIsAClearAnswerNotAGuess(t *testing.T) {
+	fakeMachine(t)
+	fakeProcess(t, 10, "sshd", "PATH=/usr/bin")
+	_, err := findSession()
+	if !errors.Is(err, ErrNoSession) || !strings.Contains(err.Error(), "logged in to the desktop") {
+		t.Fatalf("no session: %v", err)
+	}
+}
+
+func TestOneXSocketAndTheAccountsAuthorityFileAreASession(t *testing.T) {
+	root := fakeMachine(t)
+	if err := os.WriteFile(filepath.Join(x11Sockets, "X0"), nil, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Join(root, "home"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(root, "home", ".Xauthority"), nil, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	s, err := findSession()
+	if err != nil || s.Display != ":0" || !strings.HasSuffix(s.XAuthority, "/home/.Xauthority") {
+		t.Fatalf("socket and authority: %+v, %v", s, err)
+	}
+}
+
+func TestTheBusIsTheAccountsRuntimeDirectoryWhenNoProcessNamesIt(t *testing.T) {
+	fakeMachine(t)
+	runtime := filepath.Join(runUserDir, strconv.Itoa(os.Getuid()))
+	if _, err := findBus(); !errors.Is(err, ErrNoBus) {
+		t.Fatalf("no runtime directory is no bus: %v", err)
+	}
+	if err := os.MkdirAll(runtime, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(runtime, "bus"), nil, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	s, err := findBus()
+	if err != nil || s.Bus != "unix:path="+filepath.Join(runtime, "bus") || s.RuntimeDir != runtime {
+		t.Fatalf("bus: %+v, %v", s, err)
+	}
+	env := strings.Join(s.Env(), "\n")
+	if !strings.Contains(env, "XDG_RUNTIME_DIR="+runtime) || !strings.Contains(env, "DBUS_SESSION_BUS_ADDRESS=unix:path=") {
+		t.Fatalf("the bus is handed on: %s", env)
+	}
+}
+
+func TestACommandIsBoundedAndANonZeroExitIsAResult(t *testing.T) {
+	fakeMachine(t)
+	s := Session{}
+	r, err := s.run(5*time.Second, "in", "sh", "-c", "cat; echo err >&2; exit 3")
+	if err != nil || r.Stdout != "in" || r.Code != 3 || strings.TrimSpace(r.Stderr) != "err" {
+		t.Fatalf("result: %+v, %v", r, err)
+	}
+	start := time.Now()
+	if _, err := s.run(200*time.Millisecond, "", "sh", "-c", "sleep 30 & sleep 30"); err == nil || time.Since(start) > 5*time.Second {
+		t.Fatalf("a command past its time is ended with what it started: %v after %s", err, time.Since(start))
+	}
+	if _, err := s.run(time.Second, "", "no-such-program-here"); err == nil || !strings.Contains(err.Error(), "not installed") {
+		t.Fatalf("a missing program: %v", err)
+	}
+}
+
+func TestDetachAsksTheAccountsServiceManagerWithTheSessionsDisplay(t *testing.T) {
+	fakeMachine(t)
+	bin := fakeBinaries(t, map[string]string{
+		"systemctl":   `echo "systemctl $*" >> "$LOG"`,
+		"systemd-run": `echo "systemd-run $*" >> "$LOG"`,
+	})
+	log := filepath.Join(bin, "log")
+	t.Setenv("LOG", log)
+	s := Session{Display: ":1", XAuthority: "/x", RuntimeDir: "/run/user/1"}
+	if err := s.detach("picom-session", "picom", "--config", "/c"); err != nil {
+		t.Fatal(err)
+	}
+	got, _ := os.ReadFile(log)
+	want := "systemctl --user stop picom-session.service\n" +
+		"systemd-run --user --collect --quiet --unit=picom-session --setenv=DISPLAY=:1 --setenv=XAUTHORITY=/x -- picom --config /c\n"
+	if string(got) != want {
+		t.Fatalf("detach ran:\n%s\nwant:\n%s", got, want)
+	}
+	if err := (Session{}).detach("x", "y"); !errors.Is(err, ErrNoBus) {
+		t.Fatalf("no runtime directory: %v", err)
+	}
+}
+
+// fakeBinaries puts shell scripts named for programs first on PATH, and answers their directory.
+func fakeBinaries(t *testing.T, scripts map[string]string) string {
+	t.Helper()
+	dir := t.TempDir()
+	for name, body := range scripts {
+		if err := os.WriteFile(filepath.Join(dir, name), []byte("#!/bin/sh\n"+body+"\n"), 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	t.Setenv("PATH", dir+string(os.PathListSeparator)+os.Getenv("PATH"))
+	return dir
+}

modules/i3status-rust/files/bin/i3bar-watchdog

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# i3bar-watchdog [session-pid] (module i3status-rust, novox/hq ADR 0208): respawns a bar that died.
+#
+# i3 starts one i3bar per `bar { }` block and never restarts one that exits, and a reload does not
+# either. Changing the monitor setup reliably kills the bar that owns the tray. This brings back the
+# one missing i3bar, without restarting i3, and logs the outputs at that moment: the evidence for the
+# cause, which is i3bar's.
+#
+# Started once per session from the session's start, with the session's own pid; it ends when that
+# process does. Adopted from the predecessor's i3-bar-watchdog user unit of 2026-10-04.
+set -uo pipefail
+
+session_pid="${1:-}"
+interval="${I3_BAR_WATCHDOG_INTERVAL:-5}"
+# Two misses in a row before acting: an i3 restart tears every bar down and starts them again.
+confirm="${I3_BAR_WATCHDOG_CONFIRM:-2}"
+# Never respawn the same bar more often than this, so a bar that dies at once is not a tight loop.
+cooldown="${I3_BAR_WATCHDOG_COOLDOWN:-30}"
+
+log() { printf 'i3bar-watchdog: %s\n' "$*" >&2; }
+
+for tool in i3-msg i3bar pgrep; do
+	command -v "$tool" >/dev/null 2>&1 || {
+		log "$tool is missing; not watching"
+		exit 1
+	}
+done
+
+declare -A missed=() fixed=()
+
+bar_ids() { i3-msg -t get_bar_config 2>/dev/null | grep -oE '"[^"]+"' | tr -d '"'; }
+outputs() { xrandr --listmonitors 2>/dev/null | tail -n +2 | awk '{print $2" "$3}' | tr '\n' ' '; }
+session_alive() { [ -z "$session_pid" ] || kill -0 "$session_pid" 2>/dev/null; }
+
+while session_alive; do
+	sleep "$interval"
+	socket="$(i3 --get-socketpath 2>/dev/null)"
+	[ -n "$socket" ] && [ -S "$socket" ] || continue
+	ids="$(bar_ids)"
+	[ -n "$ids" ] || continue
+	while read -r id; do
+		[ -n "$id" ] || continue
+		if pgrep -u "$EUID" -f -- "i3bar --bar_id=$id" >/dev/null 2>&1; then
+			missed[$id]=0
+			continue
+		fi
+		missed[$id]=$((${missed[$id]:-0} + 1))
+		[ "${missed[$id]}" -ge "$confirm" ] || continue
+		now="$(date +%s)"
+		if [ $((now - ${fixed[$id]:-0})) -lt "$cooldown" ]; then
+			continue
+		fi
+		log "$id is gone; respawning it. Outputs now: $(outputs)"
+		nohup i3bar --bar_id="$id" --socket="$socket" >/dev/null 2>&1 &
+		disown 2>/dev/null || true
+		fixed[$id]="$now"
+		sleep 2
+		if pgrep -u "$EUID" -f -- "i3bar --bar_id=$id" >/dev/null 2>&1; then
+			missed[$id]=0
+		else
+			log "$id exited within 2s of respawning; check its status_command"
+		fi
+	done <<<"$ids"
+done

modules/i3status-rust/files/bin/i3status-updates

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# i3status-updates [threshold] (module i3status-rust, novox/hq ADR 0208): the pending updates, for
+# the bottom bar's custom block (json = true). Emits one JSON line.
+#
+# Adopted from the operator's pkg-updates of 2026-10-04. The native `packages` block showed a raw
+# red error on every transient network failure, which on a roaming laptop is often. This keeps the
+# last good result through a failure and shows an error only after `threshold` failures in a row
+# (default 10). Official packages through checkupdates (pacman-contrib, a temporary database, no
+# root); AUR packages through paru when it is installed, and none counted when it is not.
+set -uo pipefail
+
+threshold="${1:-10}"
+icon="update"
+state_dir="${XDG_RUNTIME_DIR:-/tmp}/i3status-updates"
+mkdir -p "$state_dir"
+last="$state_dir/last_good.json"
+failures="$state_dir/failures"
+
+json() { printf '{"icon":"%s","state":"%s","text":"%s","short_text":"%s"}' "$icon" "$1" "$2" "$3"; }
+count() { [ -n "$1" ] && printf '%s\n' "$1" | grep -c . || echo 0; }
+
+official="$(checkupdates 2>/dev/null)"
+official_rc=$?
+aur="" aur_rc=0
+if command -v paru >/dev/null 2>&1; then
+	aur="$(paru -Qua 2>/dev/null)"
+	aur_rc=$?
+fi
+
+# checkupdates: 0 updates listed, 2 none pending; anything else is a failure.
+if { [ "$official_rc" -eq 0 ] || [ "$official_rc" -eq 2 ]; } && [ "$aur_rc" -eq 0 ]; then
+	o="$(count "$official")"
+	a="$(count "$aur")"
+	total=$((o + a))
+	if [ "$total" -eq 0 ]; then
+		payload="$(json Good "up to date" "")"
+	else
+		# A kernel update wants a reboot: the one worth not putting off.
+		state=Info
+		printf '%s\n' "$official" | grep -qE '^(linux|linux-lts|linux-zen) ' && state=Warning
+		label="$o + $a = $total updates"
+		[ "$a" -eq 0 ] && label="$total updates"
+		[ "$total" -eq 1 ] && label="1 update"
+		payload="$(json "$state" "$label" "$total")"
+	fi
+	printf '%s' "$payload" >"$last"
+	printf '0' >"$failures"
+	printf '%s\n' "$payload"
+	exit 0
+fi
+
+n=$(($(cat "$failures" 2>/dev/null || echo 0) + 1))
+printf '%s' "$n" >"$failures"
+if [ "$n" -ge "$threshold" ]; then
+	json Critical "update check failing (${n}x)" "!"
+	echo
+elif [ -s "$last" ]; then
+	cat "$last"
+	echo
+else
+	json Idle "" ""
+	echo
+fi

modules/i3status-rust/files/bottom-bar.toml

@@ -0,0 +1,100 @@
+# The bottom bar (module i3status-rust, novox/hq ADR 0208). Owned by the mesh: replaced at every
+# push. Adopted from the workstations of 2026-10-04 with what follows a machine's hardware or one
+# person's devices left out: the battery and the GPU belong to a machine model's hardware module,
+# and a headset's address is not the bar's to know. Every block here works the same on any machine.
+icons_format = "{icon}"
+
+[theme]
+theme = "plain"
+[theme.overrides]
+idle_bg = "#000000"
+idle_fg = "#f1f1f1"
+info_bg = "#000000"
+info_fg = "#f1f1f1"
+good_bg = "#000000"
+good_fg = "#859900"
+warning_bg = "#000000"
+warning_fg = "#de5200"
+critical_bg = "#000000"
+critical_fg = "#ff0000"
+separator = " | "
+separator_fg = "#ffffff"
+separator_bg = "#000000"
+
+[icons]
+icons = "custom-icons"
+
+[[block]]
+block = "tea_timer"
+format = "$icon{ $minutes:$seconds|}"
+done_cmd = "notify-send 'Timer finished'"
+
+# Pending updates: official and, where an AUR helper is installed, AUR. The script keeps the last good
+# count through a network gap and shows an error only after ten failed checks in a row. Click: the
+# list, in the launcher's menu.
+[[block]]
+block = "custom"
+command = "~/.local/bin/i3status-updates 10"
+json = true
+interval = 1800
+[[block.click]]
+button = "left"
+cmd = "checkupdates | dmenu -l 20 -p Updates"
+
+[[block]]
+block = "cpu"
+
+[[block]]
+block = "disk_space"
+path = "/"
+info_type = "used"
+alert_unit = "GB"
+interval = 20
+warning = 850
+alert = 920
+format = "$icon / $used.eng(w:2) ($percentage.eng(w:2))"
+
+[[block]]
+block = "disk_space"
+path = "/home"
+info_type = "used"
+alert_unit = "GB"
+interval = 20
+warning = 850
+alert = 920
+format = "$icon /home $used.eng(w:2) ($percentage.eng(w:2))"
+
+[[block]]
+block = "memory"
+format = "$icon $mem_total_used.eng(w:2) ($mem_total_used_percents.eng(w:2))"
+format_alt = "$icon_swap $swap_used.eng(w:2) ($swap_used_percents.eng(w:2))"
+
+[[block]]
+block = "docker"
+interval = 2
+format = "$icon $running/$total"
+
+[[block]]
+block = "sound"
+[[block.click]]
+button = "left"
+cmd = "pavucontrol"
+
+# The weather from the Norwegian Meteorological Institute, which needs no key, where the machine is.
+[[block]]
+block = "weather"
+format = "$icon  $weather_verbose ($location) $temp"
+autolocate = true
+autolocate_interval = 600
+[block.service]
+name = "metno"
+
+[[block]]
+block = "notify"
+driver = "dunst"
+format = " $icon {($notification_count.eng(w:1))|}"
+
+[[block]]
+block = "time"
+interval = 1
+format = "$timestamp.datetime(f:'%a %d/%m %H:%M:%S')"

modules/i3status-rust/files/i3/60-i3status-rust.conf

@@ -0,0 +1,34 @@
+# The bars (module i3status-rust, novox/hq ADR 0208). Owned by the mesh: replaced at every push.
+# i3 reads this file through its configuration's `include ~/.config/i3/config.d/*.conf`. The bottom
+# bar shows the machine; the top bar the focused window and the tray, on the primary output. The
+# face is the monospace one every desktop module names.
+bar {
+        font pango:JetBrainsMono Nerd Font 11
+        position bottom
+        status_command i3status-rs ~/.config/i3status-rust/bottom-bar.toml
+        tray_output none
+        colors {
+                separator #ffffff
+                background #000000
+                statusline #ffffff
+                # The text on an accent-coloured button is dark: light text on the accent was barely
+                # legible.
+                focused_workspace #de5200 #de5200 #000000
+                active_workspace #de5200 #de5200 #000000
+                inactive_workspace #000000 #000000 #ffffff
+                urgent_workspace #2f343a #900000 #ffffff
+        }
+}
+
+bar {
+        font pango:JetBrainsMono Nerd Font 11
+        position top
+        status_command i3status-rs ~/.config/i3status-rust/top-bar.toml
+        workspace_buttons no
+        tray_output primary
+        colors {
+                separator #ffffff
+                background #000000
+                statusline #ffffff
+        }
+}

modules/i3status-rust/files/icons/custom-icons.toml

@@ -0,0 +1,135 @@
+# Icons for the bars (module i3status-rust, novox/hq ADR 0208), from the JetBrains Mono Nerd Font.
+# Owned by the mesh: replaced at every push. Adopted unchanged from the workstations of 2026-10-04.
+# Material from NerdFont
+# https://www.nerdfonts.com/cheat-sheet
+backlight = [
+    "\ue38d", # nf-weather-moon_new
+    "\ue3d4", # nf-weather-moon_alt_waxing_gibbous_6
+    "\ue3d3", # nf-weather-moon_alt_waxing_gibbous_5
+    "\ue3d2", # nf-weather-moon_alt_waxing_gibbous_4
+    "\ue3d1", # nf-weather-moon_alt_waxing_gibbous_3
+    "\ue3d0", # nf-weather-moon_alt_waxing_gibbous_2
+    "\ue3cf", # nf-weather-moon_alt_waxing_gibbous_1
+    "\ue3ce", # nf-weather-moon_alt_first_quarter
+    "\ue3cd", # nf-weather-moon_alt_waxing_crescent_6
+    "\ue3cc", # nf-weather-moon_alt_waxing_crescent_5
+    "\ue3cb", # nf-weather-moon_alt_waxing_crescent_4
+    "\ue3ca", # nf-weather-moon_alt_waxing_crescent_3
+    "\ue3c9", # nf-weather-moon_alt_waxing_crescent_2
+    "\ue3c8", # nf-weather-moon_alt_waxing_crescent_1
+    "\ue39b", # nf-weather-moon_full
+]
+bat_charging = "\U000f0084" # nf-md-battery_charging
+bat_not_available = "\U000f0091" # nf-md-battery_unknown
+bat = [
+    "\U000f007a", # nf-md-battery_10
+    "\U000f007b", # nf-md-battery_20
+    "\U000f007c", # nf-md-battery_30
+    "\U000f007d", # nf-md-battery_40
+    "\U000f007e", # nf-md-battery_50
+    "\U000f007f", # nf-md-battery_60
+    "\U000f0080", # nf-md-battery_70
+    "\U000f0081", # nf-md-battery_80
+    "\U000f0082", # nf-md-battery_90
+    "\U000f0079", # nf-md-battery
+]
+bell = "\U000f009c" # nf-md-bell_outline
+bell-slash = "\U000f009b" # nf-md-bell_off
+blackberry = "\uf307" # nf-md-blackberry
+bluetooth = "\U000f00af" # nf-md-bluetooth
+calendar = "\U000f00ed" # nf-md-calendar
+cogs = "\U000f0493" # nf-md-cog
+cpu = [
+	"\U000F0F86", # nf-md-speedometer_slow
+	"\U000F0F85", # nf-md-speedometer_medium
+	"\U000F04C5", # nf-md-speedometer
+]
+cpu_boost_on = "\U000f0521" # nf-md-toggle_switch
+cpu_boost_off = "\U000f0a19" # nf-md-toggle_switch_off_outline
+disk_drive = "\U000f02ca" # nf-md-harddisk
+docker = "\uf308" # nf-linux-docker
+github = "\U000f02a4" # nf-md-github
+gpu = "\U000f0379" # nf-md-monitor
+headphones = "\U000f02cb" # nf-md-headphones
+joystick = "\U000f0297" # nf-md-gamepad_variant
+keyboard = "\U000f030c" # nf-md-keyboard
+mail = "\U000f01ee" # nf-md-email
+memory_mem = "\U000f035b" # nf-md-memory
+memory_swap = "\U000f02ca" # nf-md-harddisk
+mouse = "\U000f037d" # nf-md-mouse
+music = "\U000f075a" # nf-md-music
+music_next = "\U000f04ad" # nf-md-skip_next
+music_pause = "\U000f03e4" # nf-md-pause
+music_play = "\U000f040a" # nf-md-play
+music_prev = "\U000f04ae" # nf-md-skip_previous
+net_bridge = "\U000f04aa" # nf-md-sitemap
+net_down = "\U000f01da" # nf-md-download
+net_loopback = "\U000f006f" # nf-md-backup_restore
+net_modem = "\U000f03f2" # nf-md-phone
+net_cellular = [
+        "\U000F08FD", # nf-md-network_strength_off_outline
+        "\U000F08FE", # nf-md-network_strength_outline
+        "\U000F08F4", # nf-md-network_strength_1
+        "\U000F08F6", # nf-md-network_strength_2
+        "\U000F08F8", # nf-md-network_strength_3
+        "\U000F08FA", # nf-md-network_strength_4
+]
+net_up = "\U000f0552" # nf-md-upload
+net_vpn = "\U000f0582" # nf-md-vpn
+net_wired = "\U000f0200" # nf-md-ethernet
+net_wireless = [
+	"\U000F092F", # nf-md-wifi_strength_outline
+	"\U000F091F", # nf-md-wifi_strength_1
+	"\U000F0922", # nf-md-wifi_strength_2
+	"\U000F0925", # nf-md-wifi_strength_3
+	"\U000F0928", # nf-md-wifi_strength_4
+]
+notification = "\U000f009c" # nf-md-bell_outline
+phone = "\U000f03f2" # nf-md-phone
+phone_disconnected = "\U000f0658" # nf-md-phone_minus
+ping = "\U000f051f" # nf-md-timer_sand
+pomodoro = "\ue001" # nf-pom-pomodoro_done
+pomodoro_break = "\U000f0176" # nf-md-coffee
+pomodoro_paused = "\U000f03e4" # nf-md-pause
+pomodoro_started = "\U000f040a" # nf-md-play
+pomodoro_stopped = "\U000f04db" # nf-md-stop
+resolution = "\U000f0293" # nf-md-fullscreen
+tasks = "\U000f05c7" # nf-md-playlist_check
+tea = "\U000f0d9e" # nf-md-tea
+thermometer = [
+    "\U000f10c3", # nf-md-thermometer_low
+    "\U000f050f", # nf-md-thermometer
+    "\U000f10c2", # nf-md-thermometer_high
+]
+time = "\U000f0150" # nf-md-clock_outline
+toggle_off = "\U000f0a19" # nf-md-toggle_switch_off_outline
+toggle_on = "\U000f0521" # nf-md-toggle_switch
+unknown = "\U000f0186" # nf-md-comment_question_outline | TODO: Make default?
+update = "\U000f03d5" # nf-md-package_up
+uptime = "\U000f0153" # nf-md-clock_in
+volume_muted = "\U000f075f" # nf-md-volume_mute
+volume = [
+    "\U000f057f", # nf-md-volume_low
+    "\U000f0580", # nf-md-volume_medium
+    "\U000f057e", # nf-md-volume_high
+]
+microphone_muted = "\U000f036d" # nf-md-microphone_off
+microphone = [
+	"\U000f036e", # nf-md-microphone_outline
+    "\U000f036c", # nf-md-microphone
+    "\U000f036c", # nf-md-microphone
+]
+xrandr = "\U000f037a" # nf-md-monitor_multiple
+
+# Weather icons (https://greshake.github.io/i3status-rust/i3status_rs/blocks/weather/index.html)
+weather_sun = "\ue30d" # nf-weather-day_sunny (when weather is reported as “Clear” during the day)
+weather_moon = "\ue32b" # nf-weather-night_clear (when weather is reported as “Clear” at night)
+weather_clouds = "\ue312" # nf-weather-cloudy (when weather is reported as “Clouds” during the day)
+weather_clouds_night = "\ue37e" # nf-weather-night_alt_cloudy (when weather is reported as “Clouds” at night)
+weather_fog = "\ue313" # nf-weather-fog (when weather is reported as “Fog” or “Mist” during the day)
+weather_fog_night = "\ue346" # nf-weather-night_fog (when weather is reported as “Fog” or “Mist” at night)
+weather_rain = "\ue318" # nf-weather-rain (when weather is reported as “Rain” or “Drizzle” during the day)
+weather_rain_night = "\ue325" # nf-weather-night_alt_rain (when weather is reported as “Rain” or “Drizzle” at night)
+weather_snow = "\ue31a" # nf-weather-snow (when weather is reported as “Snow”)
+weather_thunder = "\ue31d" # nf-weather-thunderstorm (when weather is reported as “Thunderstorm” during the day)
+weather_thunder_night = "\ue32a" # nf-weather-night_alt_thunderstorm (when weather is reported as “Thunderstorm” at night)

modules/i3status-rust/files/top-bar.toml

@@ -0,0 +1,33 @@
+# The top bar (module i3status-rust, novox/hq ADR 0208): the focused window's title and the uptime.
+# Owned by the mesh: replaced at every push. Adopted unchanged from the workstations of 2026-10-04.
+icons_format = "{icon}"
+
+[theme]
+theme = "plain"
+[theme.overrides]
+idle_bg = "#000000"
+idle_fg = "#f1f1f1"
+info_bg = "#000000"
+info_fg = "#f1f1f1"
+good_bg = "#000000"
+good_fg = "#859900"
+warning_bg = "#000000"
+warning_fg = "#de5200"
+critical_bg = "#000000"
+critical_fg = "#ff0000"
+separator = " | "
+separator_fg = "#ffffff"
+separator_bg = "#000000"
+
+[icons]
+icons = "custom-icons"
+
+[[block]]
+block = "focused_window"
+[block.format]
+full = " $title.str(max_w:50) |"
+short = " $title.str(max_w:100) |"
+
+[[block]]
+block = "uptime"
+interval = 60

modules/i3status-rust/go.mod

@@ -0,0 +1,5 @@
+module i3statusrust
+
+go 1.22
+
+require git.novox.be/novox/mesh-sdk/go v0.1.7

modules/i3status-rust/go.sum

@@ -0,0 +1,2 @@
+git.novox.be/novox/mesh-sdk/go v0.1.7 h1:C0sTQmtTiyYH7bnqZb7PusXnqA37gKuT7Nqjn9gG47w=
+git.novox.be/novox/mesh-sdk/go v0.1.7/go.mod h1:GFuZUElBZ9A++mxgIKo97aXXo+kV0uJ/UkbhQPPIbrY=

modules/photos-eef/module.json

@@ -45,7 +45,7 @@
       "image": "registry-api.novox.be/novox/photos-client@sha256:f87d63ee7bfb44c9f9748b99be6ba6dc0daf955a1d463699e9e7e3009693c0ab",
       "network": "photos-eef",
       "ports": [
-        "80"
+        "4012:80"
       ],
       "names-on-purpose": {
         "registry-api.novox.be": "built outside the mesh, from the application's own repository, and pulled from the registry that built it; moves when that repository is a build source on the git seat (novox/hq ADR 0155, issue 122)"

modules/photos-filip/module.json

@@ -45,7 +45,7 @@
       "image": "registry-api.novox.be/novox/photos-client@sha256:f87d63ee7bfb44c9f9748b99be6ba6dc0daf955a1d463699e9e7e3009693c0ab",
       "network": "photos-filip",
       "ports": [
-        "80"
+        "4013:80"
       ],
       "names-on-purpose": {
         "registry-api.novox.be": "built outside the mesh, from the application's own repository, and pulled from the registry that built it; moves when that repository is a build source on the git seat (novox/hq ADR 0155, issue 122)"

modules/photos/module.json

@@ -89,7 +89,7 @@
       "image": "registry-api.novox.be/novox/photos-admin-client@sha256:f437fa9ed28b29a012f715fb8d9b809a15cff4a672794c620d5d400f57695580",
       "network": "photos",
       "ports": [
-        "80"
+        "4001:80"
       ],
       "names-on-purpose": {
         "registry-api.novox.be": "built outside the mesh, from the application's own repository, and pulled from the registry that built it; moves when that repository is a build source on the git seat (novox/hq ADR 0155, issue 122)"

modules/picom/README.md

@@ -0,0 +1,62 @@
+# picom
+
+The X compositor as a module (novox/hq ADR 0208, research 026).
+
+- Installs `picom`, and `xorg-xprop` for setting a window's own opacity.
+- Claims the mesh's `node-compositor` seat (no verbs yet, ADR 0208 §2) and requires `x11-display`.
+  That requirement has the machine's reach: the display server must be held on this module's own
+  machine, or assignment is refused, naming the seat's holders.
+- Owns `~/.config/picom/` and `~/.config/picom/picom.conf`, which it writes whole at every push.
+- **Adds no start of its own.** picom's package ships an XDG autostart entry
+  (`/etc/xdg/autostart/picom.desktop`), which the session runs: the `i3` module's `dex --autostart`.
+  That is the tool's own grain (ADR 0208 §4) and its one start. The desktop modules follow one rule:
+  a process has one starter. Its package's autostart entry is that starter where there is one, and
+  the `xinitrc` slot where there is none.
+
+## Tools
+
+Served by the node's runtime as the operator account (ADR 0175). The tools find the operator's X
+session from the window manager's own environment, and say so plainly when nobody is logged in.
+
+| tool | does |
+|---|---|
+| `picom_restart` | a running picom re-reads its file (`SIGUSR1`); `hard`, or none running, starts a fresh one |
+| `picom_rules` | the global options and the window rules in force, in picom's order, and whether it runs |
+| `picom_window_opacity` | read or set one window's own opacity, the focused window by default |
+| `picom_toggle` | compositing off or on, for a game or a test; the next login starts it again |
+
+A picom a tool starts runs under the account's own service manager (`systemd-run --user`, unit
+`picom`). As a child of the runtime it would die whenever the runtime restarts.
+
+## What it improves on what was found
+
+- **Window rules** replace `opacity-rule`, `inactive-opacity` and `inactive-dim`, which picom 12 and
+  later supersede. The behaviour is the same: only terminals are translucent (95 % focused, 75 %
+  unfocused). The browser and video "pin to 100 %" rule went, because nothing else is made
+  translucent any more.
+- **Full-screen windows are opaque,** a terminal included.
+- **One start.** Today both the window manager's configuration and the autostart entry start picom,
+  and the second one exits.
+- On the desktop, picom was not running at all on the day it was measured, although both starts were
+  in place. It probably fails to start on that machine's GPU. `picom_restart` with `hard` after
+  assignment answers with what happened. The next step is the `picom` user unit's journal.
+
+## What it leaves as found
+
+The window manager's own `exec --no-startup-id picom` line belongs to the `i3` module's configuration,
+which no longer carries it. Nothing else of picom's lies outside the directory this module owns.
+
+## Migration (ADR 0182)
+
+- The first push keeps the found `picom.conf` once, then writes the module's.
+- Until the `i3` module replaces the hand-kept `~/.config/i3/config`, its `exec picom` line starts a
+  second picom. The second one exits at once, because a compositor is already running. Nothing to
+  do, unless the line is still there after `i3` is assigned.
+
+## Blockers
+
+- The seat `node-compositor` and the provision `x11-display` are ADR 0208's.
+  Until the controller knows them, `mctl` reads the claim and the requirement as unknown, and refuses
+  the module.
+- `xorg-xprop` is declared here because the `xorg` module does not install it. If `xorg` comes to
+  declare it, it leaves this module, since a package is declared once per node.

modules/picom/cmd/picom-tools/args.go

@@ -0,0 +1,97 @@
+// Reading a tool's arguments: JSON numbers arrive as float64, and a missing argument is its default.
+// The same in every desktop module that carries it.
+package main
+
+import (
+	"fmt"
+	"math"
+	"strings"
+	"time"
+)
+
+// text is a string argument, trimmed; required says an empty one is refused.
+func text(args map[string]any, key string, required bool) (string, error) {
+	v, present := args[key]
+	if !present || v == nil {
+		if required {
+			return "", fmt.Errorf("%s is required", key)
+		}
+		return "", nil
+	}
+	s, ok := v.(string)
+	if !ok {
+		return "", fmt.Errorf("%s is a string, not %T", key, v)
+	}
+	s = strings.TrimSpace(s)
+	if s == "" && required {
+		return "", fmt.Errorf("%s is required", key)
+	}
+	return s, nil
+}
+
+// whole is a whole-number argument within [least, most], or def when absent.
+func whole(args map[string]any, key string, def, least, most int) (int, error) {
+	v, present := args[key]
+	if !present || v == nil {
+		return def, nil
+	}
+	f, ok := v.(float64)
+	if !ok {
+		if i, isInt := v.(int); isInt {
+			f = float64(i)
+		} else {
+			return 0, fmt.Errorf("%s is a number, not %T", key, v)
+		}
+	}
+	if f != math.Trunc(f) {
+		return 0, fmt.Errorf("%s is a whole number, not %v", key, f)
+	}
+	n := int(f)
+	if n < least || n > most {
+		return 0, fmt.Errorf("%s is %d; it is between %d and %d", key, n, least, most)
+	}
+	return n, nil
+}
+
+// flag is a boolean argument, or def when absent.
+func flag(args map[string]any, key string, def bool) (bool, error) {
+	v, present := args[key]
+	if !present || v == nil {
+		return def, nil
+	}
+	b, ok := v.(bool)
+	if !ok {
+		return false, fmt.Errorf("%s is true or false, not %T", key, v)
+	}
+	return b, nil
+}
+
+// texts is a list-of-strings argument.
+func texts(args map[string]any, key string) ([]string, error) {
+	v, present := args[key]
+	if !present || v == nil {
+		return nil, nil
+	}
+	list, ok := v.([]any)
+	if !ok {
+		if ss, isStrings := v.([]string); isStrings {
+			return ss, nil
+		}
+		return nil, fmt.Errorf("%s is a list of strings, not %T", key, v)
+	}
+	out := make([]string, 0, len(list))
+	for i, item := range list {
+		s, ok := item.(string)
+		if !ok {
+			return nil, fmt.Errorf("%s[%d] is a string, not %T", key, i, item)
+		}
+		out = append(out, s)
+	}
+	return out, nil
+}
+
+// seconds is a timeout argument in seconds, defaulted and bounded below the runtime's call limit.
+func seconds(args map[string]any, key string, def, most int) (time.Duration, error) {
+	n, err := whole(args, key, def, 1, most)
+	return time.Duration(n) * time.Second, err
+}

modules/picom/cmd/picom-tools/main.go

@@ -0,0 +1,89 @@
+// picom's Go tools bundle (novox/hq ADR 0188, ADR 0193, ADR 0208): the compositor's own tools, served
+// by the node's runtime as the operator account. node-compositor has no verbs yet (ADR 0208 §2), so
+// every tool here is the module's own.
+package main
+
+import (
+	"fmt"
+	"os"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+func main() {
+	if err := stdio.Serve("", tools()); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+func tools() []stdio.Tool {
+	return []stdio.Tool{
+		{
+			Name: "picom_restart",
+			Description: "Make the compositor re-read its configuration: a running picom is told to reinitialise " +
+				"(SIGUSR1); with hard, or when none runs, a fresh one is started in the operator's session under " +
+				"their service manager. Answers what was done and the pids.",
+			Input: map[string]any{
+				"hard": map[string]any{"type": "boolean", "description": "end the running picom and start a new one (default false)"},
+			},
+			Run: func(args map[string]any) (any, error) {
+				hard, err := flag(args, "hard", false)
+				if err != nil {
+					return nil, err
+				}
+				return Restart(hard)
+			},
+		},
+		{
+			Name: "picom_rules",
+			Description: "The compositor's configuration in force: its global options and each window rule " +
+				"(match, opacity, shadow, fade…) in the order picom applies them, from the file the mesh placed, " +
+				"and whether picom is running.",
+			Run: func(map[string]any) (any, error) { return Rules(configPath()) },
+		},
+		{
+			Name: "picom_window_opacity",
+			Description: "Read or set one window's own opacity (_NET_WM_WINDOW_OPACITY), the focused window " +
+				"unless one is named. A window rule that sets opacity (terminals) outranks it. Lasts as long as " +
+				"the window; the declared rules are untouched.",
+			Input: map[string]any{
+				"window":  map[string]any{"type": "string", "description": "X window id, 0x… or decimal (default: the focused window)"},
+				"opacity": map[string]any{"type": "integer", "description": "0-100 to set; 100 removes the window's own value; omit to read"},
+			},
+			Run: func(args map[string]any) (any, error) {
+				window, err := text(args, "window", false)
+				if err != nil {
+					return nil, err
+				}
+				if _, set := args["opacity"]; !set {
+					return WindowOpacity(window, -1)
+				}
+				opacity, err := whole(args, "opacity", 100, 0, 100)
+				if err != nil {
+					return nil, err
+				}
+				return WindowOpacity(window, opacity)
+			},
+		},
+		{
+			Name: "picom_toggle",
+			Description: "Turn compositing off or on in the operator's session, for a game or a test: off ends " +
+				"picom, on starts it. Without `on`, flips it. The session start brings it back at the next login.",
+			Input: map[string]any{
+				"on": map[string]any{"type": "boolean", "description": "true to start, false to stop (default: the opposite of now)"},
+			},
+			Run: func(args map[string]any) (any, error) {
+				var want *bool
+				if _, given := args["on"]; given {
+					on, err := flag(args, "on", false)
+					if err != nil {
+						return nil, err
+					}
+					want = &on
+				}
+				return Toggle(want)
+			},
+		},
+	}
+}

modules/picom/cmd/picom-tools/manifest_helpers_test.go

@@ -0,0 +1,175 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// The module's manifest, read the way the catalogue reads it, for the manifest tests. The same in
+// every desktop module that carries it.
+
+type manifest struct {
+	Module       string           `json:"module"`
+	Version      string           `json:"version"`
+	Capabilities []string         `json:"capabilities"`
+	Requires     []string         `json:"requires"`
+	Claims       []claim          `json:"claims"`
+	Seats        []any            `json:"seats"`
+	Tools        []string         `json:"tools"`
+	Environment  *environment     `json:"environment"`
+	Shell        []shellCode      `json:"shell"`
+	Resources    []map[string]any `json:"resources"`
+	Build        struct {
+		Artifacts []map[string]any `json:"artifacts"`
+	} `json:"build"`
+}
+
+type claim struct {
+	Name   string   `json:"name"`
+	Scope  string   `json:"scope"`
+	Serves []string `json:"serves"`
+}
+
+type environment struct {
+	Variables map[string]string `json:"variables"`
+	Path      []map[string]any  `json:"path"`
+}
+
+type shellCode struct {
+	For  string `json:"for"`
+	Slot string `json:"slot"`
+	Code string `json:"code"`
+}
+
+func readManifest(t *testing.T) manifest {
+	t.Helper()
+	raw, err := os.ReadFile(filepath.Join("..", "..", "module.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	dec := json.NewDecoder(strings.NewReader(string(raw)))
+	dec.DisallowUnknownFields()
+	var m manifest
+	if err := dec.Decode(&m); err != nil {
+		t.Fatalf("module.json: %v", err)
+	}
+	return m
+}
+
+func (m manifest) resource(t *testing.T, id string) map[string]any {
+	t.Helper()
+	for _, r := range m.Resources {
+		if r["id"] == id {
+			return r
+		}
+	}
+	t.Fatalf("no resource %q", id)
+	return nil
+}
+
+func (m manifest) packages() (present, absent []string) {
+	for _, r := range m.Resources {
+		if r["type"] == "package" {
+			if r["absent"] == true {
+				absent = append(absent, r["package"].(string))
+			} else {
+				present = append(present, r["package"].(string))
+			}
+		}
+	}
+	return present, absent
+}
+
+// sameAsSource checks that a file resource's content is byte for byte the module's source file, so
+// the readable file in the repository is what the machine gets.
+func (m manifest) sameAsSource(t *testing.T, id, source string) {
+	t.Helper()
+	want, err := os.ReadFile(filepath.Join("..", "..", source))
+	if err != nil {
+		t.Fatal(err)
+	}
+	r := m.resource(t, id)
+	if r["type"] != "file" {
+		t.Fatalf("%s is a %v, not a file", id, r["type"])
+	}
+	if got, _ := r["content"].(string); got != string(want) {
+		t.Fatalf("resource %s's content is not %s: edit the source and copy it into module.json", id, source)
+	}
+	if r["owner"] != "${machine:account}" && !strings.HasPrefix(r["path"].(string), "/etc/") {
+		t.Fatalf("%s under the home is the account's", id)
+	}
+}
+
+// checkTheToolsAgree checks that the manifest lists the module's own tools exactly, that the bundle
+// serves each seat verb the claims promise as <seat>.<verb>, and that the Go bundle is declared.
+func checkTheToolsAgree(t *testing.T, m manifest) {
+	t.Helper()
+	own, seat := map[string]bool{}, map[string]bool{}
+	for _, tool := range tools() {
+		if strings.Contains(tool.Name, ".") {
+			seat[tool.Name] = true
+		} else {
+			own[tool.Name] = true
+		}
+		if strings.TrimSpace(tool.Description) == "" {
+			t.Errorf("%s has no description", tool.Name)
+		}
+	}
+	listed := map[string]bool{}
+	for _, name := range m.Tools {
+		listed[name] = true
+		if !own[name] {
+			t.Errorf("module.json lists %s, which the bundle does not serve", name)
+		}
+	}
+	for name := range own {
+		if !listed[name] {
+			t.Errorf("the bundle serves %s, which module.json does not list", name)
+		}
+		if !strings.HasPrefix(name, strings.ReplaceAll(m.Module, "-", "_")+"_") {
+			t.Errorf("%s is not prefixed with the module's name", name)
+		}
+	}
+	promised := map[string]bool{}
+	for _, c := range m.Claims {
+		for _, verb := range c.Serves {
+			promised[c.Name+"."+verb] = true
+			if !seat[c.Name+"."+verb] {
+				t.Errorf("the claim on %s promises %s, which the bundle does not serve", c.Name, verb)
+			}
+		}
+	}
+	for name := range seat {
+		if !promised[name] {
+			t.Errorf("the bundle serves %s, which no claim promises", name)
+		}
+	}
+	var bundle map[string]any
+	for _, a := range m.Build.Artifacts {
+		if a["kind"] == "bundle" {
+			bundle = a
+		}
+	}
+	if bundle == nil || bundle["language"] != "go" || bundle["system"] != "arch" ||
+		bundle["from"] != "cmd/"+m.Module+"-tools" || bundle["binary"] != m.Module+"-tools" {
+		t.Errorf("the Go tools bundle: %v", bundle)
+	}
+}
+
+// checkNoSecretsOrInstallationNames refuses what a catalogue manifest must never carry.
+func checkNoSecretsOrInstallationNames(t *testing.T) {
+	t.Helper()
+	raw, err := os.ReadFile(filepath.Join("..", "..", "module.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := strings.ToLower(string(raw))
+	for _, never := range []string{"/home/", "jochen", "g14", "shanks", "novox.be", "api_key", ".hal/", "greenclip daemon"} {
+		if strings.Contains(s, never) {
+			t.Errorf("module.json names %q", never)
+		}
+	}
+}

modules/picom/cmd/picom-tools/manifest_test.go

@@ -0,0 +1,61 @@
+package main
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+)
+
+// picom's shape (novox/hq ADR 0208): it claims node-compositor and serves no verb of it, requires the
+// X display on its own machine, owns its configuration file, and is started once, by its package's
+// XDG autostart entry, never by the window manager or the session's start as well.
+
+func TestItClaimsTheCompositorSeatAndRequiresTheXDisplay(t *testing.T) {
+	m := readManifest(t)
+	if m.Module != "picom" || m.Seats != nil {
+		t.Fatalf("module %q declares seats %v", m.Module, m.Seats)
+	}
+	if !reflect.DeepEqual(m.Claims, []claim{{Name: "node-compositor", Scope: "node"}}) {
+		t.Fatalf("claims: %+v", m.Claims)
+	}
+	if !reflect.DeepEqual(m.Requires, []string{"x11-display"}) {
+		t.Fatalf("requires: %v", m.Requires)
+	}
+	if present, absent := m.packages(); !reflect.DeepEqual(present, []string{"picom", "xorg-xprop"}) || absent != nil {
+		t.Fatalf("packages: %v, absent %v", present, absent)
+	}
+}
+
+func TestItOwnsItsConfigurationAsWrittenInTheModule(t *testing.T) {
+	m := readManifest(t)
+	m.sameAsSource(t, "configuration", "files/picom.conf")
+	if p := m.resource(t, "configuration")["path"]; p != "${machine:account-home}/.config/picom/picom.conf" {
+		t.Fatalf("path: %v", p)
+	}
+	if d := m.resource(t, "configuration-dir"); d["type"] != "directory" || d["path"] != "${machine:account-home}/.config/picom" {
+		t.Fatalf("the directory: %v", d)
+	}
+}
+
+func TestThePackagesAutostartEntryIsItsOnlyStart(t *testing.T) {
+	m := readManifest(t)
+	// picom's package ships /etc/xdg/autostart/picom.desktop, which the session's dex runs. A second
+	// start from here would be a second compositor, refused by the first.
+	if m.Shell != nil {
+		t.Fatalf("a session-start line as well as the package's autostart entry: %+v", m.Shell)
+	}
+	for _, r := range m.Resources {
+		if p, _ := r["path"].(string); strings.Contains(p, "i3/config.d") || strings.Contains(p, "autostart") {
+			t.Fatalf("a second start: %v", r)
+		}
+		if r["type"] == "service" || r["type"] == "process" {
+			t.Fatalf("a unit: %v", r)
+		}
+	}
+}
+
+func TestTheToolsAgreeWithTheManifest(t *testing.T) {
+	m := readManifest(t)
+	checkTheToolsAgree(t, m)
+	checkNoSecretsOrInstallationNames(t)
+}

modules/picom/cmd/picom-tools/picom.go

@@ -0,0 +1,293 @@
+package main
+
+import (
+	"errors"
+	"fmt"
+	"math"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strconv"
+	"strings"
+	"syscall"
+	"time"
+)
+
+// unit is the name picom runs under in the account's service manager when a tool starts it. The
+// session start runs its own, and a tool that starts one first ends any other (Toggle, Restart).
+const unit = "picom"
+
+func configPath() string { return filepath.Join(operatorHome(), ".config", "picom", "picom.conf") }
+
+// Running is picom's processes of this account.
+func running() []int { return processesOf("picom") }
+
+// RestartResult is what picom_restart answers.
+type RestartResult struct {
+	Action string `json:"action"`
+	PIDs   []int  `json:"pids"`
+	Note   string `json:"note,omitempty"`
+}
+
+// Restart tells a running picom to reinitialise, or starts one.
+func Restart(hard bool) (RestartResult, error) {
+	if pids := running(); len(pids) > 0 && !hard {
+		return RestartResult{Action: "reinitialised", PIDs: signalAll("picom", syscall.SIGUSR1),
+			Note: "picom re-read " + configPath()}, nil
+	}
+	s, err := findSession()
+	if err != nil {
+		return RestartResult{}, err
+	}
+	if err := stopAll(); err != nil {
+		return RestartResult{}, err
+	}
+	if err := s.detach(unit, "picom", "--config", configPath()); err != nil {
+		return RestartResult{}, err
+	}
+	pids := waitFor(func() []int { return running() }, 3*time.Second)
+	return RestartResult{Action: "started", PIDs: pids,
+		Note: "started under the account's service manager as " + unit + ".service"}, nil
+}
+
+// stopAll ends every picom of this account and waits for them to go.
+func stopAll() error {
+	signalAll("picom", syscall.SIGTERM)
+	deadline := time.Now().Add(3 * time.Second)
+	for time.Now().Before(deadline) {
+		if len(running()) == 0 {
+			return nil
+		}
+		time.Sleep(100 * time.Millisecond)
+	}
+	if left := running(); len(left) > 0 {
+		return fmt.Errorf("picom %v did not end within 3s", left)
+	}
+	return nil
+}
+
+func waitFor(get func() []int, within time.Duration) []int {
+	deadline := time.Now().Add(within)
+	for {
+		if got := get(); len(got) > 0 || time.Now().After(deadline) {
+			return got
+		}
+		time.Sleep(100 * time.Millisecond)
+	}
+}
+
+// ToggleResult is what picom_toggle answers.
+type ToggleResult struct {
+	Compositing bool   `json:"compositing"`
+	PIDs        []int  `json:"pids"`
+	Note        string `json:"note"`
+}
+
+// Toggle stops or starts compositing; want nil flips it.
+func Toggle(want *bool) (ToggleResult, error) {
+	on := len(running()) == 0
+	if want != nil {
+		on = *want
+	}
+	if !on {
+		if err := stopAll(); err != nil {
+			return ToggleResult{}, err
+		}
+		return ToggleResult{Compositing: false, PIDs: []int{},
+			Note: "picom ended; the session start runs it again at the next login, or call picom_toggle with on"}, nil
+	}
+	if pids := running(); len(pids) > 0 {
+		return ToggleResult{Compositing: true, PIDs: pids, Note: "picom was already running"}, nil
+	}
+	r, err := Restart(true)
+	if err != nil {
+		return ToggleResult{}, err
+	}
+	return ToggleResult{Compositing: len(r.PIDs) > 0, PIDs: r.PIDs, Note: r.Note}, nil
+}
+
+// Rule is one window rule, its options as written.
+type Rule struct {
+	Match   string            `json:"match"`
+	Options map[string]string `json:"options"`
+}
+
+// RulesResult is what picom_rules answers.
+type RulesResult struct {
+	File    string            `json:"file"`
+	Running []int             `json:"running"`
+	Global  map[string]string `json:"global"`
+	Rules   []Rule            `json:"rules"`
+	// Legacy names options that window rules supersede, which picom ignores when rules are set.
+	Legacy []string `json:"legacy,omitempty"`
+}
+
+var (
+	commentLine = regexp.MustCompile(`(?m)^\s*#.*$`)
+	rulesBlock  = regexp.MustCompile(`(?s)\brules\s*[=:]\s*\((.*?)\)\s*;`)
+	ruleGroup   = regexp.MustCompile(`(?s)\{(.*?)\}`)
+	assignment  = regexp.MustCompile(`(?m)^\s*([A-Za-z][A-Za-z0-9-]*)\s*[=:]\s*(.+?)\s*;?\s*$`)
+)
+
+// superseded are the options picom's window rules replace (picom(1), WINDOW RULES).
+var superseded = []string{"opacity-rule", "inactive-opacity", "active-opacity", "inactive-dim",
+	"shadow-exclude", "fade-exclude", "focus-exclude", "rounded-corners-exclude", "blur-background-exclude",
+	"corner-radius-rules", "wintypes", "inactive-opacity-override", "mark-wmwin-focused"}
+
+// Rules reads picom's configuration file into its global options and its window rules.
+func Rules(path string) (RulesResult, error) {
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return RulesResult{}, fmt.Errorf("picom's configuration: %w", err)
+	}
+	return parseRules(path, string(raw), running()), nil
+}
+
+func parseRules(path, conf string, pids []int) RulesResult {
+	out := RulesResult{File: path, Running: pids, Global: map[string]string{}, Rules: []Rule{}}
+	conf = commentLine.ReplaceAllString(conf, "")
+	rest := conf
+	if m := rulesBlock.FindStringSubmatchIndex(conf); m != nil {
+		body := conf[m[2]:m[3]]
+		rest = conf[:m[0]] + conf[m[1]:]
+		for _, g := range ruleGroup.FindAllStringSubmatch(body, -1) {
+			r := Rule{Options: map[string]string{}}
+			for _, part := range strings.Split(g[1], ";") {
+				k, v, ok := strings.Cut(part, "=")
+				if !ok {
+					continue
+				}
+				k, v = strings.TrimSpace(k), strings.TrimSpace(v)
+				if k == "match" {
+					r.Match = unquote(v)
+				} else {
+					r.Options[k] = unquote(v)
+				}
+			}
+			out.Rules = append(out.Rules, r)
+		}
+	}
+	for _, m := range assignment.FindAllStringSubmatch(rest, -1) {
+		out.Global[m[1]] = unquote(strings.TrimSuffix(m[2], ";"))
+	}
+	if len(out.Rules) > 0 {
+		for _, name := range superseded {
+			if _, set := out.Global[name]; set {
+				out.Legacy = append(out.Legacy, name)
+			}
+		}
+	}
+	return out
+}
+
+func unquote(v string) string {
+	v = strings.TrimSpace(v)
+	if len(v) >= 2 && v[0] == '"' && v[len(v)-1] == '"' {
+		return v[1 : len(v)-1]
+	}
+	return v
+}
+
+// OpacityResult is what picom_window_opacity answers.
+type OpacityResult struct {
+	Window string `json:"window"`
+	Class  string `json:"class,omitempty"`
+	Title  string `json:"title,omitempty"`
+	// Opacity is the window's own value in percent; nil when it has none.
+	Opacity *int   `json:"opacity"`
+	Note    string `json:"note,omitempty"`
+}
+
+var (
+	activeWindow = regexp.MustCompile(`window id # (0x[0-9a-fA-F]+)`)
+	cardinal     = regexp.MustCompile(`_NET_WM_WINDOW_OPACITY\(CARDINAL\) = (\d+)`)
+	wmClass      = regexp.MustCompile(`WM_CLASS\(STRING\) = "[^"]*", "([^"]*)"`)
+	wmName       = regexp.MustCompile(`_NET_WM_NAME\(UTF8_STRING\) = "(.*)"`)
+)
+
+// WindowOpacity reads a window's own opacity, and sets it when percent is 0-100.
+func WindowOpacity(window string, percent int) (OpacityResult, error) {
+	s, err := findSession()
+	if err != nil {
+		return OpacityResult{}, err
+	}
+	if window == "" {
+		r, err := s.run(5*time.Second, "", "xprop", "-root", "_NET_ACTIVE_WINDOW")
+		if err != nil {
+			return OpacityResult{}, err
+		}
+		m := activeWindow.FindStringSubmatch(r.Stdout)
+		if m == nil || m[1] == "0x0" {
+			return OpacityResult{}, errors.New("no window is focused")
+		}
+		window = m[1]
+	}
+	id, err := windowID(window)
+	if err != nil {
+		return OpacityResult{}, err
+	}
+	if percent >= 0 {
+		var r Result
+		if percent == 100 {
+			r, err = s.run(5*time.Second, "", "xprop", "-id", id, "-remove", "_NET_WM_WINDOW_OPACITY")
+		} else {
+			r, err = s.run(5*time.Second, "", "xprop", "-id", id, "-f", "_NET_WM_WINDOW_OPACITY", "32c",
+				"-set", "_NET_WM_WINDOW_OPACITY", strconv.FormatUint(opacityCardinal(percent), 10))
+		}
+		if err != nil {
+			return OpacityResult{}, err
+		}
+		if r.Code != 0 {
+			return OpacityResult{}, fmt.Errorf("xprop: %s", strings.TrimSpace(r.Stderr))
+		}
+	}
+	r, err := s.run(5*time.Second, "", "xprop", "-id", id, "_NET_WM_WINDOW_OPACITY", "WM_CLASS", "_NET_WM_NAME")
+	if err != nil {
+		return OpacityResult{}, err
+	}
+	if r.Code != 0 {
+		return OpacityResult{}, fmt.Errorf("window %s: %s", id, strings.TrimSpace(r.Stderr))
+	}
+	out := parseWindow(id, r.Stdout)
+	if rules, err := Rules(configPath()); err == nil && out.Class != "" {
+		for _, rule := range rules.Rules {
+			if _, sets := rule.Options["opacity"]; sets && strings.Contains(rule.Match, "class_g = '"+out.Class+"'") {
+				out.Note = "a window rule sets the opacity of class " + out.Class + " and outranks the window's own value"
+			}
+		}
+	}
+	return out, nil
+}
+
+func windowID(w string) (string, error) {
+	w = strings.TrimSpace(strings.ToLower(w))
+	base := 10
+	if strings.HasPrefix(w, "0x") {
+		w, base = w[2:], 16
+	}
+	n, err := strconv.ParseUint(w, base, 32)
+	if err != nil || n == 0 {
+		return "", fmt.Errorf("window %q is not an X window id", w)
+	}
+	return fmt.Sprintf("0x%x", n), nil
+}
+
+func opacityCardinal(percent int) uint64 {
+	return uint64(math.Round(float64(percent) / 100 * float64(math.MaxUint32)))
+}
+
+func parseWindow(id, out string) OpacityResult {
+	r := OpacityResult{Window: id}
+	if m := cardinal.FindStringSubmatch(out); m != nil {
+		n, _ := strconv.ParseUint(m[1], 10, 64)
+		p := int(math.Round(float64(n) / float64(math.MaxUint32) * 100))
+		r.Opacity = &p
+	}
+	if m := wmClass.FindStringSubmatch(out); m != nil {
+		r.Class = m[1]
+	}
+	if m := wmName.FindStringSubmatch(out); m != nil {
+		r.Title = m[1]
+	}
+	return r
+}

modules/picom/cmd/picom-tools/picom_test.go

@@ -0,0 +1,131 @@
+package main
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// A pid above the kernel's largest, so a signal a test sends reaches nothing.
+const nobody = 4194400
+
+func TestTheModulesOwnConfigurationReadsAsRulesInOrder(t *testing.T) {
+	raw, err := os.ReadFile(filepath.Join("..", "..", "files", "picom.conf"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	r := parseRules("picom.conf", string(raw), nil)
+	if r.Global["backend"] != "glx" || r.Global["vsync"] != "true" || r.Global["shadow"] != "false" {
+		t.Fatalf("global options: %v", r.Global)
+	}
+	if len(r.Rules) != 5 {
+		t.Fatalf("five rules: %+v", r.Rules)
+	}
+	focused, unfocused := r.Rules[2], r.Rules[3]
+	if focused.Match != "class_g = 'XTerm' && focused" || focused.Options["opacity"] != "0.95" ||
+		unfocused.Match != "class_g = 'XTerm' && !focused" || unfocused.Options["opacity"] != "0.75" {
+		t.Fatalf("the terminal rules: %+v %+v", focused, unfocused)
+	}
+	if last := r.Rules[4]; last.Match != "fullscreen" || last.Options["opacity"] != "1" {
+		t.Fatalf("full screen is opaque, and last so it wins: %+v", last)
+	}
+	if len(r.Legacy) != 0 {
+		t.Fatalf("the module's file sets no option the rules supersede: %v", r.Legacy)
+	}
+	if _, inGlobal := r.Global["match"]; inGlobal {
+		t.Fatal("a rule's key leaked into the global options")
+	}
+}
+
+func TestTodaysFileIsReportedForTheOptionsItsRulesWouldIgnore(t *testing.T) {
+	conf := "inactive-opacity = 1.0;\nopacity-rule = [ \"95:class_g = 'XTerm'\" ];\nrules = (\n  { match = \"focused\"; opacity = 1; }\n);\n"
+	r := parseRules("x", conf, []int{7})
+	if len(r.Rules) != 1 || r.Rules[0].Match != "focused" || len(r.Running) != 1 {
+		t.Fatalf("%+v", r)
+	}
+	if strings.Join(r.Legacy, ",") != "opacity-rule,inactive-opacity" {
+		t.Fatalf("legacy: %v", r.Legacy)
+	}
+}
+
+func TestAWindowIdIsHexOrDecimalAndNeverZero(t *testing.T) {
+	for in, want := range map[string]string{"0x3C00012": "0x3c00012", "62914578": "0x3c00012"} {
+		if got, err := windowID(in); err != nil || got != want {
+			t.Errorf("%s: %s, %v", in, got, err)
+		}
+	}
+	for _, bad := range []string{"0", "0x0", "window", "-1", "0x1ffffffff"} {
+		if _, err := windowID(bad); err == nil {
+			t.Errorf("%s was accepted", bad)
+		}
+	}
+}
+
+func TestOpacityIsAPercentOfTheFullCardinal(t *testing.T) {
+	if opacityCardinal(0) != 0 || opacityCardinal(100) != 0xffffffff || opacityCardinal(75) != 3221225471 {
+		t.Fatalf("%d %d %d", opacityCardinal(0), opacityCardinal(100), opacityCardinal(75))
+	}
+	r := parseWindow("0x1", "_NET_WM_WINDOW_OPACITY(CARDINAL) = 3221225471\nWM_CLASS(STRING) = \"xterm\", \"XTerm\"\n_NET_WM_NAME(UTF8_STRING) = \"op@host: ~\"\n")
+	if r.Opacity == nil || *r.Opacity != 75 || r.Class != "XTerm" || r.Title != "op@host: ~" {
+		t.Fatalf("%+v", r)
+	}
+	if r := parseWindow("0x1", "_NET_WM_WINDOW_OPACITY:  not found.\n"); r.Opacity != nil {
+		t.Fatalf("no value of its own: %+v", r)
+	}
+}
+
+func TestSettingTheFocusedWindowsOpacityAsksXpropAndNamesTheRuleThatOutranksIt(t *testing.T) {
+	root := fakeMachine(t)
+	fakeProcess(t, nobody, "i3", "DISPLAY=:1")
+	conf := filepath.Join(root, "home", ".config", "picom")
+	if err := os.MkdirAll(conf, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	src, _ := os.ReadFile(filepath.Join("..", "..", "files", "picom.conf"))
+	if err := os.WriteFile(filepath.Join(conf, "picom.conf"), src, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	bin := fakeBinaries(t, map[string]string{"xprop": `echo "xprop $* DISPLAY=$DISPLAY" >> "$LOG"
+case "$*" in
+  "-root _NET_ACTIVE_WINDOW") echo "_NET_ACTIVE_WINDOW(WINDOW): window id # 0x3c00012" ;;
+  *WM_CLASS*) printf '_NET_WM_WINDOW_OPACITY(CARDINAL) = 2147483648\nWM_CLASS(STRING) = "xterm", "XTerm"\n' ;;
+esac`})
+	t.Setenv("LOG", filepath.Join(bin, "log"))
+	r, err := WindowOpacity("", 50)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if r.Window != "0x3c00012" || r.Opacity == nil || *r.Opacity != 50 || !strings.Contains(r.Note, "XTerm") {
+		t.Fatalf("%+v", r)
+	}
+	log, _ := os.ReadFile(filepath.Join(bin, "log"))
+	if !strings.Contains(string(log), "xprop -id 0x3c00012 -f _NET_WM_WINDOW_OPACITY 32c -set _NET_WM_WINDOW_OPACITY 2147483648 DISPLAY=:1") {
+		t.Fatalf("xprop was asked:\n%s", log)
+	}
+}
+
+func TestWithoutASessionTheToolsThatDrawSaySo(t *testing.T) {
+	fakeMachine(t)
+	if _, err := WindowOpacity("", -1); !errors.Is(err, ErrNoSession) {
+		t.Fatalf("window opacity: %v", err)
+	}
+	on := true
+	if _, err := Toggle(&on); !errors.Is(err, ErrNoSession) {
+		t.Fatalf("toggle on: %v", err)
+	}
+}
+
+func TestARunningPicomIsToldToReinitialiseNotRestarted(t *testing.T) {
+	fakeMachine(t)
+	fakeProcess(t, nobody, "picom", "DISPLAY=:1")
+	r, err := Restart(false)
+	if err != nil || r.Action != "reinitialised" {
+		t.Fatalf("%+v, %v", r, err)
+	}
+	on := true
+	if r, err := Toggle(&on); err != nil || !r.Compositing || r.PIDs[0] != nobody {
+		t.Fatalf("on while running: %+v, %v", r, err)
+	}
+}

modules/picom/cmd/picom-tools/session.go

@@ -0,0 +1,423 @@
+// The operator's graphical session, as a tool the node's runtime runs finds it (novox/hq ADR 0208).
+//
+// The runtime is a system service running as the operator account (ADR 0175): it has the account's
+// uid and none of the session's environment — no DISPLAY, no XAUTHORITY, no session bus. A tool that
+// draws on the screen or talks to the desktop's D-Bus must find them. It reads them from a process of
+// the account that is part of the session (the window manager first), the same thing `loginctl` and
+// a person's own shell would point at, and says where it found them.
+//
+// Long-lived programs a tool starts go to the account's own service manager through `systemd-run
+// --user`, never as children of the tool: the runtime's unit is a cgroup the service manager empties
+// whenever the runtime restarts, and a compositor or a clipboard owner started from inside it would
+// die with it.
+//
+// This file is the same in every desktop module that carries it; it moves into the Go SDK once a
+// second consumer outside the desktop wants it.
+package main
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"syscall"
+	"time"
+)
+
+// Where the session is looked for. Variables so a test can point them at a fake tree.
+var (
+	procRoot   = "/proc"
+	runUserDir = "/run/user"
+	x11Sockets = "/tmp/.X11-unix"
+)
+
+// sessionHolders are the processes whose environment is the session's, best first: the window
+// manager is the session, the rest are its children. Anything else carrying DISPLAY ranks after them.
+var sessionHolders = []string{"i3", "sway", "i3bar", "picom", "xss-lock", "dunst", "clipmenud", "xterm"}
+
+// sessionKeys are the variables a session carries that a tool hands on to what it runs.
+var sessionKeys = []string{"DISPLAY", "XAUTHORITY", "WAYLAND_DISPLAY", "DBUS_SESSION_BUS_ADDRESS",
+	"XDG_RUNTIME_DIR", "XDG_SESSION_ID", "I3SOCK"}
+
+// Session is what a tool needs to reach the operator's desktop.
+type Session struct {
+	UID        int    `json:"uid"`
+	Display    string `json:"display,omitempty"`
+	XAuthority string `json:"xauthority,omitempty"`
+	Wayland    string `json:"wayland_display,omitempty"`
+	Bus        string `json:"bus,omitempty"`
+	RuntimeDir string `json:"runtime_dir,omitempty"`
+	SessionID  string `json:"session_id,omitempty"`
+	I3Sock     string `json:"i3sock,omitempty"`
+	// From says where the values were found: the tool's own environment, a process, or the socket.
+	From string `json:"from"`
+}
+
+// ErrNoSession is answered by a tool that needs the desktop when nobody is logged in to it.
+var ErrNoSession = errors.New("no graphical session")
+
+// ErrTimedOut is what run answers for a command ended because it ran past its time.
+var ErrTimedOut = errors.New("timed out")
+
+// ErrNoBus is answered by a tool that needs the session bus when the account has none.
+var ErrNoBus = errors.New("no session bus")
+
+// operatorHome is the account's home: what the runtime was told, else the process's own.
+func operatorHome() string {
+	if h := strings.TrimSpace(os.Getenv("MESH_OPERATOR_HOME")); h != "" {
+		return h
+	}
+	h, _ := os.UserHomeDir()
+	return h
+}
+
+// findSession finds the graphical session of the account this tool runs as, or answers
+// ErrNoSession with what it looked at.
+func findSession() (Session, error) {
+	s := findEnvironment()
+	if s.Display == "" && s.Wayland == "" {
+		return s, fmt.Errorf("%w for uid %d on this machine: no process of the account carries DISPLAY "+
+			"or WAYLAND_DISPLAY, and no X server socket in %s has an authority file to go with it. "+
+			"Is anyone logged in to the desktop?", ErrNoSession, s.UID, x11Sockets)
+	}
+	return s, nil
+}
+
+// findBus finds the account's session bus, which a logged-in account has whether or not a desktop
+// is running.
+func findBus() (Session, error) {
+	s := findEnvironment()
+	if s.Bus == "" {
+		return s, fmt.Errorf("%w for uid %d: DBUS_SESSION_BUS_ADDRESS is not set and %s does not exist "+
+			"(the account is not logged in)", ErrNoBus, s.UID, filepath.Join(runUserDir, strconv.Itoa(s.UID), "bus"))
+	}
+	return s, nil
+}
+
+func findEnvironment() Session {
+	uid := os.Getuid()
+	s := Session{UID: uid}
+	own := map[string]string{}
+	for _, k := range sessionKeys {
+		own[k] = os.Getenv(k)
+	}
+	if own["DISPLAY"] != "" || own["WAYLAND_DISPLAY"] != "" {
+		s.fill(own)
+		s.From = "the tool's own environment"
+	} else if pid, comm, env, ok := sessionProcess(uid); ok {
+		s.fill(env)
+		s.From = fmt.Sprintf("process %s (pid %d)", comm, pid)
+	} else if display, ok := lonelyX11Socket(); ok {
+		if a := filepath.Join(operatorHome(), ".Xauthority"); exists(a) {
+			s.Display, s.XAuthority = display, a
+			s.From = "the X server socket and the account's ~/.Xauthority"
+		}
+		s.fill(own)
+	} else {
+		s.fill(own)
+		s.From = "nothing: no session found"
+	}
+	// The bus and the runtime directory are the account's, whether or not the process named them.
+	runtime := filepath.Join(runUserDir, strconv.Itoa(uid))
+	if s.RuntimeDir == "" && exists(runtime) {
+		s.RuntimeDir = runtime
+	}
+	if s.Bus == "" && s.RuntimeDir != "" && exists(filepath.Join(s.RuntimeDir, "bus")) {
+		s.Bus = "unix:path=" + filepath.Join(s.RuntimeDir, "bus")
+	}
+	return s
+}
+
+func (s *Session) fill(env map[string]string) {
+	set := func(dst *string, key string) {
+		if *dst == "" {
+			*dst = env[key]
+		}
+	}
+	set(&s.Display, "DISPLAY")
+	set(&s.XAuthority, "XAUTHORITY")
+	set(&s.Wayland, "WAYLAND_DISPLAY")
+	set(&s.Bus, "DBUS_SESSION_BUS_ADDRESS")
+	set(&s.RuntimeDir, "XDG_RUNTIME_DIR")
+	set(&s.SessionID, "XDG_SESSION_ID")
+	set(&s.I3Sock, "I3SOCK")
+}
+
+// sessionProcess is the best process of this uid whose environment names a display.
+func sessionProcess(uid int) (int, string, map[string]string, bool) {
+	entries, err := os.ReadDir(procRoot)
+	if err != nil {
+		return 0, "", nil, false
+	}
+	type candidate struct {
+		pid  int
+		comm string
+		env  map[string]string
+		rank int
+	}
+	var found []candidate
+	for _, e := range entries {
+		pid, err := strconv.Atoi(e.Name())
+		if err != nil {
+			continue
+		}
+		dir := filepath.Join(procRoot, e.Name())
+		if owner, ok := ownerOf(dir); !ok || owner != uid {
+			continue
+		}
+		raw, err := os.ReadFile(filepath.Join(dir, "environ"))
+		if err != nil {
+			continue
+		}
+		env := parseEnviron(raw)
+		if env["DISPLAY"] == "" && env["WAYLAND_DISPLAY"] == "" {
+			continue
+		}
+		comm := readTrimmed(filepath.Join(dir, "comm"))
+		rank := len(sessionHolders)
+		for i, h := range sessionHolders {
+			if h == comm {
+				rank = i
+				break
+			}
+		}
+		found = append(found, candidate{pid, comm, env, rank})
+	}
+	if len(found) == 0 {
+		return 0, "", nil, false
+	}
+	sort.Slice(found, func(i, j int) bool {
+		if found[i].rank != found[j].rank {
+			return found[i].rank < found[j].rank
+		}
+		return found[i].pid > found[j].pid // the newer of two equals
+	})
+	best := found[0]
+	return best.pid, best.comm, best.env, true
+}
+
+func parseEnviron(raw []byte) map[string]string {
+	env := map[string]string{}
+	for _, kv := range bytes.Split(raw, []byte{0}) {
+		if i := bytes.IndexByte(kv, '='); i > 0 {
+			env[string(kv[:i])] = string(kv[i+1:])
+		}
+	}
+	return env
+}
+
+func ownerOf(path string) (int, bool) {
+	info, err := os.Stat(path)
+	if err != nil {
+		return 0, false
+	}
+	st, ok := info.Sys().(*syscall.Stat_t)
+	if !ok {
+		return 0, false
+	}
+	return int(st.Uid), true
+}
+
+// lonelyX11Socket is the display of the one X server socket there is, when there is exactly one.
+func lonelyX11Socket() (string, bool) {
+	entries, err := os.ReadDir(x11Sockets)
+	if err != nil {
+		return "", false
+	}
+	var displays []string
+	for _, e := range entries {
+		if n := strings.TrimPrefix(e.Name(), "X"); n != e.Name() {
+			if _, err := strconv.Atoi(n); err == nil {
+				displays = append(displays, ":"+n)
+			}
+		}
+	}
+	if len(displays) != 1 {
+		return "", false
+	}
+	return displays[0], true
+}
+
+func readTrimmed(path string) string {
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(string(b))
+}
+
+func exists(path string) bool {
+	_, err := os.Stat(path)
+	return err == nil
+}
+
+// Env is this process's environment with the session's variables in place of its own.
+func (s Session) Env() []string {
+	drop := map[string]bool{}
+	for _, k := range sessionKeys {
+		drop[k] = true
+	}
+	var env []string
+	for _, kv := range os.Environ() {
+		if i := strings.IndexByte(kv, '='); i > 0 && drop[kv[:i]] {
+			continue
+		}
+		env = append(env, kv)
+	}
+	add := func(k, v string) {
+		if v != "" {
+			env = append(env, k+"="+v)
+		}
+	}
+	add("DISPLAY", s.Display)
+	add("XAUTHORITY", s.XAuthority)
+	add("WAYLAND_DISPLAY", s.Wayland)
+	add("DBUS_SESSION_BUS_ADDRESS", s.Bus)
+	add("XDG_RUNTIME_DIR", s.RuntimeDir)
+	add("XDG_SESSION_ID", s.SessionID)
+	add("I3SOCK", s.I3Sock)
+	return env
+}
+
+// mostOutput bounds what a command may answer with, per stream.
+const mostOutput = 256 << 10
+
+// Result is what a command did.
+type Result struct {
+	Stdout    string `json:"stdout"`
+	Stderr    string `json:"stderr,omitempty"`
+	Code      int    `json:"code"`
+	Truncated bool   `json:"truncated,omitempty"`
+}
+
+// run runs a command in the session's environment, its input given, ended with everything it
+// started after timeout. A command that is not installed is an error naming it; one that exits
+// non-zero is a Result with its code, for the caller to judge.
+func (s Session) run(timeout time.Duration, stdin string, name string, args ...string) (Result, error) {
+	path, err := exec.LookPath(name)
+	if err != nil {
+		return Result{}, fmt.Errorf("%s is not installed on this machine", name)
+	}
+	cmd := exec.Command(path, args...)
+	cmd.Env = s.Env()
+	if home := operatorHome(); exists(home) {
+		cmd.Dir = home
+	}
+	if stdin != "" {
+		cmd.Stdin = strings.NewReader(stdin)
+	}
+	var out, errOut capped
+	cmd.Stdout, cmd.Stderr = &out, &errOut
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+	if err := cmd.Start(); err != nil {
+		return Result{}, fmt.Errorf("%s: %w", name, err)
+	}
+	done := make(chan error, 1)
+	go func() { done <- cmd.Wait() }()
+	select {
+	case err = <-done:
+	case <-time.After(timeout):
+		_ = syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)
+		<-done
+		return Result{Stdout: out.String(), Stderr: errOut.String()},
+			fmt.Errorf("%s did not finish within %s and was ended: %w", name, timeout, ErrTimedOut)
+	}
+	r := Result{Stdout: out.String(), Stderr: errOut.String(), Truncated: out.cut || errOut.cut}
+	var exit *exec.ExitError
+	if errors.As(err, &exit) {
+		r.Code = exit.ExitCode()
+	} else if err != nil {
+		return r, fmt.Errorf("%s: %w", name, err)
+	}
+	return r, nil
+}
+
+// detach starts a long-lived program under the account's own service manager, as a transient unit
+// that carries the session's display, so it outlives the runtime that asked for it. A unit already
+// running under the same name is stopped first, so a fixed name means "at most one".
+func (s Session) detach(unit string, args ...string) error {
+	if s.RuntimeDir == "" {
+		return fmt.Errorf("%w: the account's runtime directory is missing, so its service manager "+
+			"cannot be reached", ErrNoBus)
+	}
+	_, _ = s.run(5*time.Second, "", "systemctl", "--user", "stop", unit+".service")
+	call := []string{"--user", "--collect", "--quiet", "--unit=" + unit}
+	for _, kv := range [][2]string{{"DISPLAY", s.Display}, {"XAUTHORITY", s.XAuthority},
+		{"WAYLAND_DISPLAY", s.Wayland}, {"XDG_SESSION_ID", s.SessionID}, {"I3SOCK", s.I3Sock}} {
+		if kv[1] != "" {
+			call = append(call, "--setenv="+kv[0]+"="+kv[1])
+		}
+	}
+	call = append(call, "--")
+	call = append(call, args...)
+	r, err := s.run(10*time.Second, "", "systemd-run", call...)
+	if err != nil {
+		return err
+	}
+	if r.Code != 0 {
+		return fmt.Errorf("systemd-run %s: %s", unit, strings.TrimSpace(r.Stderr))
+	}
+	return nil
+}
+
+// uniqueUnit is a transient unit name that will not collide with an earlier one.
+func uniqueUnit(prefix string) string {
+	return fmt.Sprintf("%s-%d", prefix, time.Now().UnixNano())
+}
+
+type capped struct {
+	bytes.Buffer
+	cut bool
+}
+
+func (c *capped) Write(p []byte) (int, error) {
+	if room := mostOutput - c.Len(); room < len(p) {
+		if room > 0 {
+			c.Buffer.Write(p[:room])
+		}
+		c.cut = true
+		return len(p), nil
+	}
+	return c.Buffer.Write(p)
+}
+
+// processesOf are the pids of this uid's processes whose command name is comm, oldest first.
+func processesOf(comm string) []int {
+	entries, err := os.ReadDir(procRoot)
+	if err != nil {
+		return nil
+	}
+	uid := os.Getuid()
+	var pids []int
+	for _, e := range entries {
+		pid, err := strconv.Atoi(e.Name())
+		if err != nil {
+			continue
+		}
+		dir := filepath.Join(procRoot, e.Name())
+		if owner, ok := ownerOf(dir); !ok || owner != uid {
+			continue
+		}
+		if readTrimmed(filepath.Join(dir, "comm")) == comm {
+			pids = append(pids, pid)
+		}
+	}
+	sort.Ints(pids)
+	return pids
+}
+
+// signalAll sends sig to every process of this uid named comm, and answers the pids it reached.
+func signalAll(comm string, sig syscall.Signal) []int {
+	var reached []int
+	for _, pid := range processesOf(comm) {
+		if syscall.Kill(pid, sig) == nil {
+			reached = append(reached, pid)
+		}
+	}
+	return reached
+}

modules/picom/cmd/picom-tools/session_test.go

@@ -0,0 +1,174 @@
+package main
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+)
+
+// fakeMachine points the session finder at a temporary /proc, /run/user and X socket directory, with
+// none of the test process's own session variables, and gives back the root.
+func fakeMachine(t *testing.T) string {
+	t.Helper()
+	root := t.TempDir()
+	procRoot, runUserDir, x11Sockets = filepath.Join(root, "proc"), filepath.Join(root, "run-user"), filepath.Join(root, "x11")
+	for _, d := range []string{procRoot, runUserDir, x11Sockets} {
+		if err := os.MkdirAll(d, 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	for _, k := range sessionKeys {
+		t.Setenv(k, "")
+	}
+	t.Setenv("MESH_OPERATOR_HOME", filepath.Join(root, "home"))
+	t.Cleanup(func() { procRoot, runUserDir, x11Sockets = "/proc", "/run/user", "/tmp/.X11-unix" })
+	return root
+}
+
+func fakeProcess(t *testing.T, pid int, comm string, env ...string) {
+	t.Helper()
+	dir := filepath.Join(procRoot, strconv.Itoa(pid))
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "comm"), []byte(comm+"\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "environ"), []byte(strings.Join(env, "\x00")+"\x00"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestTheSessionIsReadFromTheWindowManagerBeforeAnyOtherProcess(t *testing.T) {
+	fakeMachine(t)
+	fakeProcess(t, 900, "xterm", "DISPLAY=:9", "XAUTHORITY=/elsewhere")
+	fakeProcess(t, 100, "i3", "DISPLAY=:1", "XAUTHORITY=/home/op/.Xauthority",
+		"DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus", "XDG_SESSION_ID=3", "SECRET_TOKEN=never-copied")
+	fakeProcess(t, 50, "bash", "PATH=/usr/bin")
+	s, err := findSession()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if s.Display != ":1" || s.XAuthority != "/home/op/.Xauthority" || s.SessionID != "3" || !strings.Contains(s.From, "i3 (pid 100)") {
+		t.Fatalf("the window manager's environment: %+v", s)
+	}
+	for _, kv := range s.Env() {
+		if strings.HasPrefix(kv, "SECRET_TOKEN=") {
+			t.Fatal("a variable of the session process that is not a session variable was handed on")
+		}
+	}
+}
+
+func TestAnyProcessCarryingADisplayServesWhenTheWindowManagerIsNotFound(t *testing.T) {
+	fakeMachine(t)
+	fakeProcess(t, 10, "firefox", "DISPLAY=:0")
+	fakeProcess(t, 20, "firefox", "DISPLAY=:2")
+	s, err := findSession()
+	if err != nil || s.Display != ":2" {
+		t.Fatalf("the newest of two equals: %+v, %v", s, err)
+	}
+}
+
+func TestNoSessionIsAClearAnswerNotAGuess(t *testing.T) {
+	fakeMachine(t)
+	fakeProcess(t, 10, "sshd", "PATH=/usr/bin")
+	_, err := findSession()
+	if !errors.Is(err, ErrNoSession) || !strings.Contains(err.Error(), "logged in to the desktop") {
+		t.Fatalf("no session: %v", err)
+	}
+}
+
+func TestOneXSocketAndTheAccountsAuthorityFileAreASession(t *testing.T) {
+	root := fakeMachine(t)
+	if err := os.WriteFile(filepath.Join(x11Sockets, "X0"), nil, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Join(root, "home"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(root, "home", ".Xauthority"), nil, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	s, err := findSession()
+	if err != nil || s.Display != ":0" || !strings.HasSuffix(s.XAuthority, "/home/.Xauthority") {
+		t.Fatalf("socket and authority: %+v, %v", s, err)
+	}
+}
+
+func TestTheBusIsTheAccountsRuntimeDirectoryWhenNoProcessNamesIt(t *testing.T) {
+	fakeMachine(t)
+	runtime := filepath.Join(runUserDir, strconv.Itoa(os.Getuid()))
+	if _, err := findBus(); !errors.Is(err, ErrNoBus) {
+		t.Fatalf("no runtime directory is no bus: %v", err)
+	}
+	if err := os.MkdirAll(runtime, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(runtime, "bus"), nil, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	s, err := findBus()
+	if err != nil || s.Bus != "unix:path="+filepath.Join(runtime, "bus") || s.RuntimeDir != runtime {
+		t.Fatalf("bus: %+v, %v", s, err)
+	}
+	env := strings.Join(s.Env(), "\n")
+	if !strings.Contains(env, "XDG_RUNTIME_DIR="+runtime) || !strings.Contains(env, "DBUS_SESSION_BUS_ADDRESS=unix:path=") {
+		t.Fatalf("the bus is handed on: %s", env)
+	}
+}
+
+func TestACommandIsBoundedAndANonZeroExitIsAResult(t *testing.T) {
+	fakeMachine(t)
+	s := Session{}
+	r, err := s.run(5*time.Second, "in", "sh", "-c", "cat; echo err >&2; exit 3")
+	if err != nil || r.Stdout != "in" || r.Code != 3 || strings.TrimSpace(r.Stderr) != "err" {
+		t.Fatalf("result: %+v, %v", r, err)
+	}
+	start := time.Now()
+	if _, err := s.run(200*time.Millisecond, "", "sh", "-c", "sleep 30 & sleep 30"); err == nil || time.Since(start) > 5*time.Second {
+		t.Fatalf("a command past its time is ended with what it started: %v after %s", err, time.Since(start))
+	}
+	if _, err := s.run(time.Second, "", "no-such-program-here"); err == nil || !strings.Contains(err.Error(), "not installed") {
+		t.Fatalf("a missing program: %v", err)
+	}
+}
+
+func TestDetachAsksTheAccountsServiceManagerWithTheSessionsDisplay(t *testing.T) {
+	fakeMachine(t)
+	bin := fakeBinaries(t, map[string]string{
+		"systemctl":   `echo "systemctl $*" >> "$LOG"`,
+		"systemd-run": `echo "systemd-run $*" >> "$LOG"`,
+	})
+	log := filepath.Join(bin, "log")
+	t.Setenv("LOG", log)
+	s := Session{Display: ":1", XAuthority: "/x", RuntimeDir: "/run/user/1"}
+	if err := s.detach("picom-session", "picom", "--config", "/c"); err != nil {
+		t.Fatal(err)
+	}
+	got, _ := os.ReadFile(log)
+	want := "systemctl --user stop picom-session.service\n" +
+		"systemd-run --user --collect --quiet --unit=picom-session --setenv=DISPLAY=:1 --setenv=XAUTHORITY=/x -- picom --config /c\n"
+	if string(got) != want {
+		t.Fatalf("detach ran:\n%s\nwant:\n%s", got, want)
+	}
+	if err := (Session{}).detach("x", "y"); !errors.Is(err, ErrNoBus) {
+		t.Fatalf("no runtime directory: %v", err)
+	}
+}
+
+// fakeBinaries puts shell scripts named for programs first on PATH, and answers their directory.
+func fakeBinaries(t *testing.T, scripts map[string]string) string {
+	t.Helper()
+	dir := t.TempDir()
+	for name, body := range scripts {
+		if err := os.WriteFile(filepath.Join(dir, name), []byte("#!/bin/sh\n"+body+"\n"), 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	t.Setenv("PATH", dir+string(os.PathListSeparator)+os.Getenv("PATH"))
+	return dir
+}

modules/picom/files/picom.conf

@@ -0,0 +1,32 @@
+# picom, the X compositor (module picom, novox/hq ADR 0208). Owned by the mesh: this file is
+# replaced at every push. Adopted from the two workstations' file of 2026-10-04 and moved to
+# picom's window rules, which supersede opacity-rule, inactive-opacity and inactive-dim.
+
+backend = "glx";
+vsync = true;
+
+fading = true;
+fade-in-step = 0.05;
+fade-out-step = 0.05;
+
+# Tiled windows hide their shadows and corners, so neither is drawn.
+shadow = false;
+corner-radius = 0;
+blur-method = "none";
+
+# "Focused" is i3's _NET_ACTIVE_WINDOW, not X focus events: under i3 those do not reliably reach
+# the toplevel picom tracks, and a terminal then never lifts to its focused opacity.
+use-ewmh-active-win = true;
+
+# Window rules are applied in order, and a later match wins. Only terminals are translucent:
+# nothing else on screen (browsers, video, games) is touched. A terminal is matched by its class;
+# the node's terminal emulator today is xterm (class XTerm). A window's own opacity property is
+# used wherever no rule sets one, which is what the window-opacity tool sets.
+rules = (
+  { match = "window_type = 'tooltip'"; fade = false; opacity = 0.95; },
+  { match = "window_type = 'dock' || window_type = 'desktop'"; fade = false; },
+  { match = "class_g = 'XTerm' && focused"; opacity = 0.95; },
+  { match = "class_g = 'XTerm' && !focused"; opacity = 0.75; },
+  # A full-screen window is opaque, a terminal included: a video or a game is never see-through.
+  { match = "fullscreen"; opacity = 1; }
+);

modules/picom/go.mod

@@ -0,0 +1,5 @@
+module picom
+
+go 1.22
+
+require git.novox.be/novox/mesh-sdk/go v0.1.7

modules/picom/go.sum

@@ -0,0 +1,2 @@
+git.novox.be/novox/mesh-sdk/go v0.1.7 h1:C0sTQmtTiyYH7bnqZb7PusXnqA37gKuT7Nqjn9gG47w=
+git.novox.be/novox/mesh-sdk/go v0.1.7/go.mod h1:GFuZUElBZ9A++mxgIKo97aXXo+kV0uJ/UkbhQPPIbrY=

modules/picom/module.json

@@ -0,0 +1,64 @@
+{
+  "module": "picom",
+  "version": "1",
+  "capabilities": [
+    "package-manager"
+  ],
+  "requires": [
+    "x11-display"
+  ],
+  "claims": [
+    {
+      "name": "node-compositor",
+      "scope": "node"
+    }
+  ],
+  "tools": [
+    "picom_restart",
+    "picom_rules",
+    "picom_window_opacity",
+    "picom_toggle"
+  ],
+  "resources": [
+    {
+      "id": "package",
+      "type": "package",
+      "package": "picom"
+    },
+    {
+      "id": "window-properties",
+      "type": "package",
+      "package": "xorg-xprop"
+    },
+    {
+      "id": "configuration-dir",
+      "type": "directory",
+      "path": "${machine:account-home}/.config/picom",
+      "owner": "${machine:account}",
+      "mode": "0755"
+    },
+    {
+      "id": "configuration",
+      "type": "file",
+      "path": "${machine:account-home}/.config/picom/picom.conf",
+      "owner": "${machine:account}",
+      "mode": "0644",
+      "content": "# picom, the X compositor (module picom, novox/hq ADR 0208). Owned by the mesh: this file is\n# replaced at every push. Adopted from the two workstations' file of 2026-10-04 and moved to\n# picom's window rules, which supersede opacity-rule, inactive-opacity and inactive-dim.\n\nbackend = \"glx\";\nvsync = true;\n\nfading = true;\nfade-in-step = 0.05;\nfade-out-step = 0.05;\n\n# Tiled windows hide their shadows and corners, so neither is drawn.\nshadow = false;\ncorner-radius = 0;\nblur-method = \"none\";\n\n# \"Focused\" is i3's _NET_ACTIVE_WINDOW, not X focus events: under i3 those do not reliably reach\n# the toplevel picom tracks, and a terminal then never lifts to its focused opacity.\nuse-ewmh-active-win = true;\n\n# Window rules are applied in order, and a later match wins. Only terminals are translucent:\n# nothing else on screen (browsers, video, games) is touched. A terminal is matched by its class;\n# the node's terminal emulator today is xterm (class XTerm). A window's own opacity property is\n# used wherever no rule sets one, which is what the window-opacity tool sets.\nrules = (\n  { match = \"window_type = 'tooltip'\"; fade = false; opacity = 0.95; },\n  { match = \"window_type = 'dock' || window_type = 'desktop'\"; fade = false; },\n  { match = \"class_g = 'XTerm' && focused\"; opacity = 0.95; },\n  { match = \"class_g = 'XTerm' && !focused\"; opacity = 0.75; },\n  # A full-screen window is opaque, a terminal included: a video or a game is never see-through.\n  { match = \"fullscreen\"; opacity = 1; }\n);\n"
+    }
+  ],
+  "build": {
+    "artifacts": [
+      {
+        "name": "tools",
+        "kind": "bundle",
+        "language": "go",
+        "system": "arch",
+        "from": "cmd/picom-tools",
+        "binary": "picom-tools",
+        "loads": [
+          "picom-tools"
+        ]
+      }
+    ]
+  }
+}

modules/rofi/README.md

@@ -0,0 +1,88 @@
+# rofi
+
+The launcher as a module (novox/hq ADR 0208, research 026/04 and 05).
+
+- Installs `rofi`, claims the mesh's `node-launcher` seat and serves its verb `menu`. Requires
+  `x11-display` on its own machine.
+- **The seat's dmenu-compatible command.** It places `~/.local/bin/dmenu`: choices on standard input,
+  the chosen one on standard output, exit 1 when nothing was chosen. It runs `rofi -dmenu`, passing
+  on dmenu's `-p`, `-l` and `-i` and dropping its look options. A script, a notifier or a clipboard
+  manager calls `dmenu` and works whichever module holds the seat. On a node where the `dmenu` module
+  holds `node-launcher` instead, the real dmenu answers the same calls.
+- Owns `~/.config/rofi/config.rasi` and the themes `mesh` and `mesh-powermenu` in
+  `~/.config/rofi/themes/`. The faces are JetBrains Mono Nerd Font for the list and the input, and
+  Inter for messages. Both are packages of the `fonts` module.
+- Places its key bindings as its own i3 drop-in, `~/.config/i3/config.d/50-rofi.conf`. The `i3`
+  module's configuration includes that directory after it sets `$mod`.
+- Starts nothing. rofi runs when a key is pressed.
+
+| key | runs |
+|---|---|
+| `$mod+d` | applications (`rofi-launch drun`) |
+| `$mod+t` | a command (`rofi-launch run`) |
+| `$mod+Shift+t` | a command with sudo, in the terminal (`rofi-launch sudo`) |
+| `$mod+Shift+w` | the window switcher (`rofi-launch window`) |
+| `$mod+Escape` | the power menu (`rofi-powermenu`) |
+
+## The power menu is here
+
+The power menu belongs to the session. It is still the launcher's, because all of it is rofi: its
+theme, its buttons and its confirmation. Every action it takes is a verb of logind or the service
+manager, so it names no window manager and no locker:
+
+- **lock** is `loginctl lock-session`, which the holder of `node-lock-screen` answers;
+- **log out** is `loginctl terminate-session`;
+- **suspend, reboot and shut down** are `systemctl`'s.
+
+A Wayland session gets the same menu from whichever launcher holds the seat there.
+
+## Tools
+
+| tool | does |
+|---|---|
+| `node-launcher.menu` | show a list in the operator's session and answer the chosen line and its index, or `cancelled` (also when nobody answers within the timeout, 20 s by default, 25 s at most) |
+| `rofi_applications` | the desktop entries the launcher offers, the account's own winning an id; filter by words, hidden ones on request |
+| `rofi_themes` | every theme (the mesh's, the account's, the distribution's) and the one configured |
+| `rofi_run` | start a desktop entry or a command in the session, under the account's service manager |
+
+## What it improves on what was found
+
+- **Plain `dmenu` calls work again.** The one found on 2026-10-04 is the notifier's context menu: on
+  both workstations it called `/usr/bin/dmenu`, which neither had installed. The `dunst` module now
+  calls `dmenu`, and this module answers it. The operator's own scripts all call `rofi -dmenu`, which
+  keeps working.
+- **The theme is one file per face.** There is no colour file imported from a cloned theme
+  repository. The faces are the decided ones (research 026/04): Iosevka and Hack are gone.
+- **The retry after resume no longer reopens a closed menu.** The found launchers retried
+  `rofi -dmenu` on any failure, so pressing Escape in the sudo prompt reopened it four times.
+  `rofi-launch` retries only a failure within half a second, which is a failed keyboard grab.
+- **The power menu locks through logind,** so it goes through the one locker. The found one ran
+  `i3lock` directly and bypassed it. Log out no longer names four window managers.
+- `icon-theme` and `window-command` are gone. They named an icon theme and a program (`wmctrl`) that
+  nothing installs. rofi's defaults serve.
+
+## What it leaves as found
+
+- `~/.config/rofi/themes-repo/` (a cloned theme repository), the five symbolic links into it
+  (`applets`, `images`, `launchers`, `powermenu`, `scripts`), `colors/`, `theme.rasi` and
+  `powermenu.rasi`.
+- The predecessor's scripts in `~/scripts`: `rofi-launcher-normal`, `rofi-launcher-terminal`,
+  `rofi-launcher-terminal-sudo` and `powermenu` (replaced here), and `theme-picker` with its modes
+  (settings, once issue 168 closes).
+
+## Migration (ADR 0182)
+
+Once the `i3` module carries the main i3 configuration:
+
+1. Delete `~/.config/rofi/theme.rasi`, `powermenu.rasi`, `colors/`, the five links and `themes-repo/`.
+   Nothing reads them any more.
+2. Delete the four scripts above from `~/scripts`.
+3. Your scripts that call `rofi -dmenu` keep working. Calling `dmenu` instead lets them follow the
+   seat, for example to a Wayland launcher later.
+
+## Blockers
+
+- `node-launcher`, `x11-display` and the `i3` drop-in directory are ADR 0208's and the `i3`
+  module's. Until the controller knows the seat, `mctl` reads the claim as unknown.
+- `~/.local/bin` is on `PATH` through the `zsh` module's environment contribution (ADR 0203). The
+  key bindings name `~/.local/bin/…` in full, so they do not depend on it. Callers of `dmenu` do.

modules/rofi/cmd/rofi-tools/args.go

@@ -0,0 +1,97 @@
+// Reading a tool's arguments: JSON numbers arrive as float64, and a missing argument is its default.
+// The same in every desktop module that carries it.
+package main
+
+import (
+	"fmt"
+	"math"
+	"strings"
+	"time"
+)
+
+// text is a string argument, trimmed; required says an empty one is refused.
+func text(args map[string]any, key string, required bool) (string, error) {
+	v, present := args[key]
+	if !present || v == nil {
+		if required {
+			return "", fmt.Errorf("%s is required", key)
+		}
+		return "", nil
+	}
+	s, ok := v.(string)
+	if !ok {
+		return "", fmt.Errorf("%s is a string, not %T", key, v)
+	}
+	s = strings.TrimSpace(s)
+	if s == "" && required {
+		return "", fmt.Errorf("%s is required", key)
+	}
+	return s, nil
+}
+
+// whole is a whole-number argument within [least, most], or def when absent.
+func whole(args map[string]any, key string, def, least, most int) (int, error) {
+	v, present := args[key]
+	if !present || v == nil {
+		return def, nil
+	}
+	f, ok := v.(float64)
+	if !ok {
+		if i, isInt := v.(int); isInt {
+			f = float64(i)
+		} else {
+			return 0, fmt.Errorf("%s is a number, not %T", key, v)
+		}
+	}
+	if f != math.Trunc(f) {
+		return 0, fmt.Errorf("%s is a whole number, not %v", key, f)
+	}
+	n := int(f)
+	if n < least || n > most {
+		return 0, fmt.Errorf("%s is %d; it is between %d and %d", key, n, least, most)
+	}
+	return n, nil
+}
+
+// flag is a boolean argument, or def when absent.
+func flag(args map[string]any, key string, def bool) (bool, error) {
+	v, present := args[key]
+	if !present || v == nil {
+		return def, nil
+	}
+	b, ok := v.(bool)
+	if !ok {
+		return false, fmt.Errorf("%s is true or false, not %T", key, v)
+	}
+	return b, nil
+}
+
+// texts is a list-of-strings argument.
+func texts(args map[string]any, key string) ([]string, error) {
+	v, present := args[key]
+	if !present || v == nil {
+		return nil, nil
+	}
+	list, ok := v.([]any)
+	if !ok {
+		if ss, isStrings := v.([]string); isStrings {
+			return ss, nil
+		}
+		return nil, fmt.Errorf("%s is a list of strings, not %T", key, v)
+	}
+	out := make([]string, 0, len(list))
+	for i, item := range list {
+		s, ok := item.(string)
+		if !ok {
+			return nil, fmt.Errorf("%s[%d] is a string, not %T", key, i, item)
+		}
+		out = append(out, s)
+	}
+	return out, nil
+}
+
+// seconds is a timeout argument in seconds, defaulted and bounded below the runtime's call limit.
+func seconds(args map[string]any, key string, def, most int) (time.Duration, error) {
+	n, err := whole(args, key, def, 1, most)
+	return time.Duration(n) * time.Second, err
+}

modules/rofi/cmd/rofi-tools/main.go

@@ -0,0 +1,100 @@
+// rofi's Go tools bundle (novox/hq ADR 0188, ADR 0193, ADR 0208): its implementation of
+// node-launcher's verb `menu` — the dmenu-compatible command as a tool — and its own tools, served by
+// the node's runtime as the operator account.
+package main
+
+import (
+	"fmt"
+	"os"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+func main() {
+	if err := stdio.Serve("", tools()); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+func tools() []stdio.Tool {
+	return []stdio.Tool{
+		{
+			Name: "node-launcher.menu",
+			Description: fmt.Sprintf("Show a list in the operator's session and answer the line they choose: "+
+				"the launcher's dmenu-compatible command as a tool. Answers chosen and its index, or cancelled "+
+				"when they closed it or did not answer within timeout_seconds (default %d, at most %d).", menuDefault, menuMost),
+			Input: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"items":           map[string]any{"type": "array", "items": map[string]any{"type": "string"}, "description": "the choices, one line each"},
+					"prompt":          map[string]any{"type": "string", "description": "the prompt (default: Choose)"},
+					"message":         map[string]any{"type": "string", "description": "a line of explanation above the list"},
+					"allow_custom":    map[string]any{"type": "boolean", "description": "accept a typed answer that is not in the list (default false)"},
+					"timeout_seconds": map[string]any{"type": "integer", "description": fmt.Sprintf("give up after this long (default %d, at most %d)", menuDefault, menuMost)},
+				},
+				"required": []string{"items"},
+			},
+			Run: func(args map[string]any) (any, error) {
+				q, err := menuQuestion(args)
+				if err != nil {
+					return nil, err
+				}
+				return Menu(q)
+			},
+		},
+		{
+			Name: "rofi_applications",
+			Description: "The desktop applications the launcher offers on this machine, from every desktop entry " +
+				"directory in the order the launcher reads them (the account's first): id, name, what it runs, " +
+				"categories and the file. Hidden entries are left out unless asked for.",
+			Input: map[string]any{
+				"query":       map[string]any{"type": "string", "description": "only entries whose name, generic name, keywords or command contain this (any case)"},
+				"show_hidden": map[string]any{"type": "boolean", "description": "include entries marked NoDisplay or Hidden (default false)"},
+				"limit":       map[string]any{"type": "integer", "description": "at most this many (default 200, at most 2000)"},
+			},
+			Run: func(args map[string]any) (any, error) {
+				query, err := text(args, "query", false)
+				if err != nil {
+					return nil, err
+				}
+				hidden, err := flag(args, "show_hidden", false)
+				if err != nil {
+					return nil, err
+				}
+				limit, err := whole(args, "limit", 200, 1, 2000)
+				if err != nil {
+					return nil, err
+				}
+				return Applications(applicationDirs(), query, hidden, limit), nil
+			},
+		},
+		{
+			Name: "rofi_themes",
+			Description: "The launcher's themes on this machine — the mesh's, the operator's own and the " +
+				"distribution's — each with its file, and which one the configuration uses.",
+			Run: func(map[string]any) (any, error) { return Themes(themeDirs(), configFile()), nil },
+		},
+		{
+			Name: "rofi_run",
+			Description: "Start a program in the operator's session, as the launcher would: a desktop entry by " +
+				"its id (firefox.desktop), or a command as its words. It runs under the account's own service " +
+				"manager, so it outlives this call; answers the unit it runs as and what it ran.",
+			Input: map[string]any{
+				"application": map[string]any{"type": "string", "description": "a desktop entry id, as rofi_applications answers it"},
+				"command":     map[string]any{"type": "array", "items": map[string]any{"type": "string"}, "description": "a program and its arguments, one word each"},
+			},
+			Run: func(args map[string]any) (any, error) {
+				app, err := text(args, "application", false)
+				if err != nil {
+					return nil, err
+				}
+				command, err := texts(args, "command")
+				if err != nil {
+					return nil, err
+				}
+				return Run(app, command)
+			},
+		},
+	}
+}

modules/rofi/cmd/rofi-tools/manifest_helpers_test.go

@@ -0,0 +1,175 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// The module's manifest, read the way the catalogue reads it, for the manifest tests. The same in
+// every desktop module that carries it.
+
+type manifest struct {
+	Module       string           `json:"module"`
+	Version      string           `json:"version"`
+	Capabilities []string         `json:"capabilities"`
+	Requires     []string         `json:"requires"`
+	Claims       []claim          `json:"claims"`
+	Seats        []any            `json:"seats"`
+	Tools        []string         `json:"tools"`
+	Environment  *environment     `json:"environment"`
+	Shell        []shellCode      `json:"shell"`
+	Resources    []map[string]any `json:"resources"`
+	Build        struct {
+		Artifacts []map[string]any `json:"artifacts"`
+	} `json:"build"`
+}
+
+type claim struct {
+	Name   string   `json:"name"`
+	Scope  string   `json:"scope"`
+	Serves []string `json:"serves"`
+}
+
+type environment struct {
+	Variables map[string]string `json:"variables"`
+	Path      []map[string]any  `json:"path"`
+}
+
+type shellCode struct {
+	For  string `json:"for"`
+	Slot string `json:"slot"`
+	Code string `json:"code"`
+}
+
+func readManifest(t *testing.T) manifest {
+	t.Helper()
+	raw, err := os.ReadFile(filepath.Join("..", "..", "module.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	dec := json.NewDecoder(strings.NewReader(string(raw)))
+	dec.DisallowUnknownFields()
+	var m manifest
+	if err := dec.Decode(&m); err != nil {
+		t.Fatalf("module.json: %v", err)
+	}
+	return m
+}
+
+func (m manifest) resource(t *testing.T, id string) map[string]any {
+	t.Helper()
+	for _, r := range m.Resources {
+		if r["id"] == id {
+			return r
+		}
+	}
+	t.Fatalf("no resource %q", id)
+	return nil
+}
+
+func (m manifest) packages() (present, absent []string) {
+	for _, r := range m.Resources {
+		if r["type"] == "package" {
+			if r["absent"] == true {
+				absent = append(absent, r["package"].(string))
+			} else {
+				present = append(present, r["package"].(string))
+			}
+		}
+	}
+	return present, absent
+}
+
+// sameAsSource checks that a file resource's content is byte for byte the module's source file, so
+// the readable file in the repository is what the machine gets.
+func (m manifest) sameAsSource(t *testing.T, id, source string) {
+	t.Helper()
+	want, err := os.ReadFile(filepath.Join("..", "..", source))
+	if err != nil {
+		t.Fatal(err)
+	}
+	r := m.resource(t, id)
+	if r["type"] != "file" {
+		t.Fatalf("%s is a %v, not a file", id, r["type"])
+	}
+	if got, _ := r["content"].(string); got != string(want) {
+		t.Fatalf("resource %s's content is not %s: edit the source and copy it into module.json", id, source)
+	}
+	if r["owner"] != "${machine:account}" && !strings.HasPrefix(r["path"].(string), "/etc/") {
+		t.Fatalf("%s under the home is the account's", id)
+	}
+}
+
+// checkTheToolsAgree checks that the manifest lists the module's own tools exactly, that the bundle
+// serves each seat verb the claims promise as <seat>.<verb>, and that the Go bundle is declared.
+func checkTheToolsAgree(t *testing.T, m manifest) {
+	t.Helper()
+	own, seat := map[string]bool{}, map[string]bool{}
+	for _, tool := range tools() {
+		if strings.Contains(tool.Name, ".") {
+			seat[tool.Name] = true
+		} else {
+			own[tool.Name] = true
+		}
+		if strings.TrimSpace(tool.Description) == "" {
+			t.Errorf("%s has no description", tool.Name)
+		}
+	}
+	listed := map[string]bool{}
+	for _, name := range m.Tools {
+		listed[name] = true
+		if !own[name] {
+			t.Errorf("module.json lists %s, which the bundle does not serve", name)
+		}
+	}
+	for name := range own {
+		if !listed[name] {
+			t.Errorf("the bundle serves %s, which module.json does not list", name)
+		}
+		if !strings.HasPrefix(name, strings.ReplaceAll(m.Module, "-", "_")+"_") {
+			t.Errorf("%s is not prefixed with the module's name", name)
+		}
+	}
+	promised := map[string]bool{}
+	for _, c := range m.Claims {
+		for _, verb := range c.Serves {
+			promised[c.Name+"."+verb] = true
+			if !seat[c.Name+"."+verb] {
+				t.Errorf("the claim on %s promises %s, which the bundle does not serve", c.Name, verb)
+			}
+		}
+	}
+	for name := range seat {
+		if !promised[name] {
+			t.Errorf("the bundle serves %s, which no claim promises", name)
+		}
+	}
+	var bundle map[string]any
+	for _, a := range m.Build.Artifacts {
+		if a["kind"] == "bundle" {
+			bundle = a
+		}
+	}
+	if bundle == nil || bundle["language"] != "go" || bundle["system"] != "arch" ||
+		bundle["from"] != "cmd/"+m.Module+"-tools" || bundle["binary"] != m.Module+"-tools" {
+		t.Errorf("the Go tools bundle: %v", bundle)
+	}
+}
+
+// checkNoSecretsOrInstallationNames refuses what a catalogue manifest must never carry.
+func checkNoSecretsOrInstallationNames(t *testing.T) {
+	t.Helper()
+	raw, err := os.ReadFile(filepath.Join("..", "..", "module.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := strings.ToLower(string(raw))
+	for _, never := range []string{"/home/", "jochen", "g14", "shanks", "novox.be", "api_key", ".hal/", "greenclip daemon"} {
+		if strings.Contains(s, never) {
+			t.Errorf("module.json names %q", never)
+		}
+	}
+}

modules/rofi/cmd/rofi-tools/manifest_test.go

@@ -0,0 +1,111 @@
+package main
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+)
+
+// rofi's shape (novox/hq ADR 0208, research 026/04): it claims node-launcher and serves its verb
+// `menu`, requires the X display on its own machine, owns its configuration and its two themes, and
+// places the seat's dmenu-compatible command, its launcher and power menu, and its key bindings as
+// its own i3 drop-in.
+
+func TestItClaimsTheLauncherSeatServingMenuAndRequiresTheXDisplay(t *testing.T) {
+	m := readManifest(t)
+	if m.Module != "rofi" || m.Seats != nil {
+		t.Fatalf("module %q declares seats %v", m.Module, m.Seats)
+	}
+	if !reflect.DeepEqual(m.Claims, []claim{{Name: "node-launcher", Scope: "node", Serves: []string{"menu"}}}) {
+		t.Fatalf("claims: %+v", m.Claims)
+	}
+	if !reflect.DeepEqual(m.Requires, []string{"x11-display"}) {
+		t.Fatalf("requires: %v", m.Requires)
+	}
+	if present, absent := m.packages(); !reflect.DeepEqual(present, []string{"rofi"}) || absent != nil {
+		t.Fatalf("packages: %v, absent %v", present, absent)
+	}
+}
+
+func TestItOwnsItsFilesAsWrittenInTheModule(t *testing.T) {
+	m := readManifest(t)
+	for id, source := range map[string]string{
+		"configuration":   "files/config.rasi",
+		"theme":           "files/themes/mesh.rasi",
+		"theme-powermenu": "files/themes/mesh-powermenu.rasi",
+		"dmenu":           "files/bin/dmenu",
+		"launch":          "files/bin/rofi-launch",
+		"powermenu":       "files/bin/rofi-powermenu",
+		"i3-bindings":     "files/i3/50-rofi.conf",
+	} {
+		m.sameAsSource(t, id, source)
+	}
+	for _, id := range []string{"dmenu", "launch", "powermenu"} {
+		if m.resource(t, id)["mode"] != "0755" {
+			t.Errorf("%s is executable", id)
+		}
+	}
+	if p := m.resource(t, "dmenu")["path"]; p != "${machine:account-home}/.local/bin/dmenu" {
+		t.Fatalf("the seat's command is dmenu on the account's PATH: %v", p)
+	}
+}
+
+func TestTheThemesAreTheMeshsFacesAndTheConfigurationNamesOne(t *testing.T) {
+	m := readManifest(t)
+	conf := m.resource(t, "configuration")["content"].(string)
+	if !strings.Contains(conf, `@theme "mesh"`) || strings.Contains(conf, "@import") {
+		t.Fatal("the configuration names the theme mesh and imports nothing")
+	}
+	for _, id := range []string{"theme", "theme-powermenu"} {
+		c := m.resource(t, id)["content"].(string)
+		if !strings.Contains(c, `"JetBrainsMono Nerd Font`) || strings.Contains(c, "@import") ||
+			strings.Contains(c, "Hack") || strings.Contains(c, "Iosevka") {
+			t.Errorf("%s: the monospace face, and no imported file", id)
+		}
+	}
+	if !strings.Contains(m.resource(t, "theme")["content"].(string), `"Inter 11"`) {
+		t.Error("the theme's prose is in the interface face")
+	}
+}
+
+func TestThePowerMenuNamesNoWindowManagerAndNoLocker(t *testing.T) {
+	m := readManifest(t)
+	menu := m.resource(t, "powermenu")["content"].(string)
+	for _, never := range []string{"i3-msg", "i3lock", "betterlockscreen", "openbox", "bspc", "qdbus", "mpc"} {
+		if strings.Contains(menu, never) {
+			t.Errorf("the power menu names %s", never)
+		}
+	}
+	for _, want := range []string{"loginctl lock-session", "loginctl terminate-session", "systemctl suspend", "systemctl reboot", "systemctl poweroff"} {
+		if !strings.Contains(menu, want) {
+			t.Errorf("the power menu lacks %s", want)
+		}
+	}
+}
+
+func TestTheKeyBindingsAreAnI3DropInRunningTheModulesOwnCommands(t *testing.T) {
+	m := readManifest(t)
+	bindings := m.resource(t, "i3-bindings")["content"].(string)
+	for _, line := range strings.Split(bindings, "\n") {
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		if !strings.HasPrefix(line, "bindsym $mod+") || !strings.Contains(line, "exec --no-startup-id ~/.local/bin/rofi-") {
+			t.Errorf("a binding that is not the launcher's: %s", line)
+		}
+	}
+	for _, key := range []string{"$mod+d ", "$mod+Escape "} {
+		if !strings.Contains(bindings, "bindsym "+key) {
+			t.Errorf("no %s", key)
+		}
+	}
+	if m.Shell != nil {
+		t.Fatalf("the launcher starts nothing at session start: %+v", m.Shell)
+	}
+}
+
+func TestTheToolsAgreeWithTheManifest(t *testing.T) {
+	m := readManifest(t)
+	checkTheToolsAgree(t, m)
+	checkNoSecretsOrInstallationNames(t)
+}

modules/rofi/cmd/rofi-tools/rofi.go

@@ -0,0 +1,410 @@
+package main
+
+import (
+	"bufio"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+	"time"
+)
+
+// The menu waits for a person, bounded below the runtime's call limit.
+const (
+	menuDefault = 20
+	menuMost    = 25
+	mostItems   = 1000
+)
+
+// MenuQuestion is what node-launcher.menu asks.
+type MenuQuestion struct {
+	Items       []string
+	Prompt      string
+	Message     string
+	AllowCustom bool
+	Timeout     time.Duration
+}
+
+func menuQuestion(args map[string]any) (MenuQuestion, error) {
+	var q MenuQuestion
+	var err error
+	if q.Items, err = texts(args, "items"); err != nil {
+		return q, err
+	}
+	if len(q.Items) == 0 {
+		return q, errors.New("items is required: at least one choice")
+	}
+	if len(q.Items) > mostItems {
+		return q, fmt.Errorf("%d items; a menu shows at most %d", len(q.Items), mostItems)
+	}
+	for i, item := range q.Items {
+		if strings.ContainsAny(item, "\n\r") {
+			return q, fmt.Errorf("items[%d] spans lines; a choice is one line", i)
+		}
+	}
+	if q.Prompt, err = text(args, "prompt", false); err != nil {
+		return q, err
+	}
+	if q.Prompt == "" {
+		q.Prompt = "Choose"
+	}
+	if q.Message, err = text(args, "message", false); err != nil {
+		return q, err
+	}
+	if q.AllowCustom, err = flag(args, "allow_custom", false); err != nil {
+		return q, err
+	}
+	q.Timeout, err = seconds(args, "timeout_seconds", menuDefault, menuMost)
+	return q, err
+}
+
+// MenuAnswer is what node-launcher.menu answers.
+type MenuAnswer struct {
+	Chosen    string `json:"chosen,omitempty"`
+	Index     int    `json:"index"`
+	Custom    bool   `json:"custom,omitempty"`
+	Cancelled bool   `json:"cancelled"`
+	TimedOut  bool   `json:"timed_out,omitempty"`
+}
+
+// Menu shows the list with `rofi -dmenu` in the operator's session and answers the choice.
+func Menu(q MenuQuestion) (MenuAnswer, error) {
+	s, err := findSession()
+	if err != nil {
+		return MenuAnswer{}, err
+	}
+	args := []string{"-dmenu", "-i", "-p", q.Prompt, "-format", "s"}
+	if q.Message != "" {
+		args = append(args, "-mesg", q.Message)
+	}
+	if !q.AllowCustom {
+		args = append(args, "-no-custom")
+	}
+	r, err := s.run(q.Timeout, strings.Join(q.Items, "\n")+"\n", "rofi", args...)
+	if errors.Is(err, ErrTimedOut) {
+		return MenuAnswer{Index: -1, Cancelled: true, TimedOut: true}, nil
+	}
+	if err != nil {
+		return MenuAnswer{}, err
+	}
+	switch r.Code {
+	case 0:
+	case 1:
+		return MenuAnswer{Index: -1, Cancelled: true}, nil
+	default:
+		return MenuAnswer{}, fmt.Errorf("rofi exited %d: %s", r.Code, strings.TrimSpace(r.Stderr))
+	}
+	chosen := strings.TrimRight(r.Stdout, "\n")
+	for i, item := range q.Items {
+		if item == chosen {
+			return MenuAnswer{Chosen: chosen, Index: i}, nil
+		}
+	}
+	return MenuAnswer{Chosen: chosen, Index: -1, Custom: true}, nil
+}
+
+// Application is one desktop entry the launcher offers.
+type Application struct {
+	ID          string   `json:"id"`
+	Name        string   `json:"name"`
+	GenericName string   `json:"generic_name,omitempty"`
+	Comment     string   `json:"comment,omitempty"`
+	Exec        string   `json:"exec"`
+	Terminal    bool     `json:"terminal,omitempty"`
+	Categories  []string `json:"categories,omitempty"`
+	Hidden      bool     `json:"hidden,omitempty"`
+	File        string   `json:"file"`
+	keywords    string
+}
+
+// ApplicationsResult is what rofi_applications answers.
+type ApplicationsResult struct {
+	Directories  []string      `json:"directories"`
+	Count        int           `json:"count"`
+	Truncated    bool          `json:"truncated,omitempty"`
+	Applications []Application `json:"applications"`
+}
+
+// applicationDirs are the directories desktop entries are read from, the first winning an id: the
+// account's own, then XDG_DATA_DIRS (as the session has it), then flatpak's exports.
+func applicationDirs() []string {
+	home := operatorHome()
+	dirs := []string{filepath.Join(home, ".local", "share", "applications")}
+	data := os.Getenv("XDG_DATA_DIRS")
+	if data == "" {
+		data = "/usr/local/share:/usr/share"
+	}
+	for _, d := range strings.Split(data, ":") {
+		if d != "" {
+			dirs = append(dirs, filepath.Join(d, "applications"))
+		}
+	}
+	dirs = append(dirs, filepath.Join(home, ".local", "share", "flatpak", "exports", "share", "applications"),
+		"/var/lib/flatpak/exports/share/applications")
+	return unique(dirs)
+}
+
+func unique(in []string) []string {
+	seen := map[string]bool{}
+	var out []string
+	for _, s := range in {
+		if !seen[s] {
+			seen[s] = true
+			out = append(out, s)
+		}
+	}
+	return out
+}
+
+// Applications reads every desktop entry in dirs, the first directory winning an id.
+func Applications(dirs []string, query string, showHidden bool, limit int) ApplicationsResult {
+	byID := map[string]Application{}
+	for _, dir := range dirs {
+		_ = filepath.WalkDir(dir, func(path string, d os.DirEntry, err error) error {
+			if err != nil || d.IsDir() || !strings.HasSuffix(path, ".desktop") {
+				return nil
+			}
+			rel, _ := filepath.Rel(dir, path)
+			id := strings.ReplaceAll(rel, string(filepath.Separator), "-")
+			if _, taken := byID[id]; taken {
+				return nil
+			}
+			if app, ok := readDesktopEntry(path); ok {
+				app.ID = id
+				byID[id] = app
+			}
+			return nil
+		})
+	}
+	q := strings.ToLower(query)
+	out := ApplicationsResult{Directories: dirs, Applications: []Application{}}
+	ids := make([]string, 0, len(byID))
+	for id := range byID {
+		ids = append(ids, id)
+	}
+	sort.Slice(ids, func(i, j int) bool {
+		a, b := byID[ids[i]], byID[ids[j]]
+		if strings.ToLower(a.Name) != strings.ToLower(b.Name) {
+			return strings.ToLower(a.Name) < strings.ToLower(b.Name)
+		}
+		return a.ID < b.ID
+	})
+	for _, id := range ids {
+		app := byID[id]
+		if app.Hidden && !showHidden {
+			continue
+		}
+		if q != "" && !strings.Contains(strings.ToLower(app.Name+"\x00"+app.GenericName+"\x00"+app.keywords+"\x00"+app.Exec), q) {
+			continue
+		}
+		out.Count++
+		if len(out.Applications) < limit {
+			out.Applications = append(out.Applications, app)
+		} else {
+			out.Truncated = true
+		}
+	}
+	return out
+}
+
+// readDesktopEntry reads the [Desktop Entry] group of an application's file, unlocalised.
+func readDesktopEntry(path string) (Application, bool) {
+	f, err := os.Open(path)
+	if err != nil {
+		return Application{}, false
+	}
+	defer f.Close()
+	app := Application{File: path}
+	kind := ""
+	in := false
+	scan := bufio.NewScanner(f)
+	for scan.Scan() {
+		line := strings.TrimSpace(scan.Text())
+		if strings.HasPrefix(line, "[") {
+			in = line == "[Desktop Entry]"
+			continue
+		}
+		if !in || line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		k, v, ok := strings.Cut(line, "=")
+		if !ok {
+			continue
+		}
+		k, v = strings.TrimSpace(k), strings.TrimSpace(v)
+		switch k {
+		case "Type":
+			kind = v
+		case "Name":
+			app.Name = v
+		case "GenericName":
+			app.GenericName = v
+		case "Comment":
+			app.Comment = v
+		case "Exec":
+			app.Exec = v
+		case "Keywords":
+			app.keywords = v
+		case "Terminal":
+			app.Terminal = v == "true"
+		case "Categories":
+			for _, c := range strings.Split(v, ";") {
+				if c != "" {
+					app.Categories = append(app.Categories, c)
+				}
+			}
+		case "NoDisplay", "Hidden":
+			app.Hidden = app.Hidden || v == "true"
+		}
+	}
+	if kind != "Application" || app.Name == "" {
+		return Application{}, false
+	}
+	return app, true
+}
+
+// Theme is one launcher theme.
+type Theme struct {
+	Name   string `json:"name"`
+	File   string `json:"file"`
+	Source string `json:"source"`
+}
+
+// ThemesResult is what rofi_themes answers.
+type ThemesResult struct {
+	Current string  `json:"current"`
+	Themes  []Theme `json:"themes"`
+}
+
+type themeDir struct{ path, source string }
+
+func configFile() string { return filepath.Join(operatorHome(), ".config", "rofi", "config.rasi") }
+
+func themeDirs() []themeDir {
+	home := operatorHome()
+	return []themeDir{
+		{filepath.Join(home, ".config", "rofi", "themes"), "the account's (the mesh places mesh and mesh-powermenu here)"},
+		{filepath.Join(home, ".local", "share", "rofi", "themes"), "the account's"},
+		{"/usr/share/rofi/themes", "the distribution's"},
+	}
+}
+
+var themeLine = regexp.MustCompile(`(?m)^\s*@theme\s+"([^"]+)"`)
+
+// Themes lists every .rasi theme, the first directory winning a name, and the configured one.
+func Themes(dirs []themeDir, config string) ThemesResult {
+	out := ThemesResult{Themes: []Theme{}}
+	if raw, err := os.ReadFile(config); err == nil {
+		if m := themeLine.FindSubmatch(raw); m != nil {
+			out.Current = string(m[1])
+		}
+	}
+	seen := map[string]bool{}
+	for _, d := range dirs {
+		entries, err := os.ReadDir(d.path)
+		if err != nil {
+			continue
+		}
+		for _, e := range entries {
+			name, ok := strings.CutSuffix(e.Name(), ".rasi")
+			if !ok || e.IsDir() || seen[name] {
+				continue
+			}
+			seen[name] = true
+			out.Themes = append(out.Themes, Theme{Name: name, File: filepath.Join(d.path, e.Name()), Source: d.source})
+		}
+	}
+	sort.Slice(out.Themes, func(i, j int) bool { return out.Themes[i].Name < out.Themes[j].Name })
+	return out
+}
+
+// RunResult is what rofi_run answers.
+type RunResult struct {
+	Unit string   `json:"unit"`
+	Argv []string `json:"argv"`
+}
+
+// Run starts an application or a command in the session under the account's service manager.
+func Run(application string, command []string) (RunResult, error) {
+	if (application == "") == (len(command) == 0) {
+		return RunResult{}, errors.New("name an application or give a command, one of the two")
+	}
+	argv := command
+	if application != "" {
+		var app *Application
+		for _, a := range Applications(applicationDirs(), "", true, 1<<20).Applications {
+			if a.ID == application {
+				a := a
+				app = &a
+				break
+			}
+		}
+		if app == nil {
+			return RunResult{}, fmt.Errorf("no desktop entry %s on this machine", application)
+		}
+		var err error
+		if argv, err = execWords(app.Exec); err != nil {
+			return RunResult{}, fmt.Errorf("%s: %w", application, err)
+		}
+		if app.Terminal {
+			argv = append([]string{"rofi-sensible-terminal", "-e"}, argv...)
+		}
+	}
+	s, err := findSession()
+	if err != nil {
+		return RunResult{}, err
+	}
+	unit := uniqueUnit("rofi-run")
+	if err := s.detach(unit, argv...); err != nil {
+		return RunResult{}, err
+	}
+	return RunResult{Unit: unit + ".service", Argv: argv}, nil
+}
+
+// execWords splits a desktop entry's Exec into words (its quoting rules), dropping the field codes a
+// launcher fills with files or URLs, since none are given.
+func execWords(exec string) ([]string, error) {
+	var words []string
+	var cur strings.Builder
+	inWord, quoted := false, false
+	for i := 0; i < len(exec); i++ {
+		c := exec[i]
+		switch {
+		case quoted && c == '\\' && i+1 < len(exec):
+			i++
+			cur.WriteByte(exec[i])
+		case c == '"':
+			quoted = !quoted
+			inWord = true
+		case !quoted && (c == ' ' || c == '\t'):
+			if inWord {
+				words = append(words, cur.String())
+				cur.Reset()
+				inWord = false
+			}
+		default:
+			cur.WriteByte(c)
+			inWord = true
+		}
+	}
+	if quoted {
+		return nil, fmt.Errorf("unbalanced quote in Exec %q", exec)
+	}
+	if inWord {
+		words = append(words, cur.String())
+	}
+	var out []string
+	for _, w := range words {
+		if len(w) == 2 && w[0] == '%' {
+			continue // %f %F %u %U %i %c %k %d %D %n %N %v %m
+		}
+		out = append(out, strings.ReplaceAll(w, "%%", "%"))
+	}
+	if len(out) == 0 {
+		return nil, fmt.Errorf("Exec %q names no program", exec)
+	}
+	return out, nil
+}

modules/rofi/cmd/rofi-tools/rofi_test.go

@@ -0,0 +1,196 @@
+package main
+
+import (
+	"errors"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"reflect"
+	"strconv"
+	"strings"
+	"testing"
+)
+
+const nobody = 4194400
+
+func withSession(t *testing.T) string {
+	t.Helper()
+	root := fakeMachine(t)
+	fakeProcess(t, nobody, "i3", "DISPLAY=:1", "XDG_SESSION_ID=2")
+	return root
+}
+
+func TestTheMenuAnswersTheChosenLineAndItsIndex(t *testing.T) {
+	withSession(t)
+	bin := fakeBinaries(t, map[string]string{"rofi": `echo "$* DISPLAY=$DISPLAY" > "$LOG"; cat > "$LOG.in"; echo "second"`})
+	t.Setenv("LOG", filepath.Join(bin, "log"))
+	q, err := menuQuestion(map[string]any{"items": []any{"first", "second"}, "prompt": "Pick", "message": "why"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	got, err := Menu(q)
+	if err != nil || got.Chosen != "second" || got.Index != 1 || got.Cancelled || got.Custom {
+		t.Fatalf("%+v, %v", got, err)
+	}
+	asked, _ := os.ReadFile(filepath.Join(bin, "log"))
+	if strings.TrimSpace(string(asked)) != "-dmenu -i -p Pick -format s -mesg why -no-custom DISPLAY=:1" {
+		t.Fatalf("rofi was asked: %s", asked)
+	}
+	in, _ := os.ReadFile(filepath.Join(bin, "log.in"))
+	if string(in) != "first\nsecond\n" {
+		t.Fatalf("the choices, one per line: %q", in)
+	}
+}
+
+func TestClosingTheMenuOrNotAnsweringIsACancelNotAnError(t *testing.T) {
+	withSession(t)
+	fakeBinaries(t, map[string]string{"rofi": `exit 1`})
+	got, err := Menu(MenuQuestion{Items: []string{"a"}, Prompt: "p", Timeout: 5e9})
+	if err != nil || !got.Cancelled || got.Index != -1 {
+		t.Fatalf("closed: %+v, %v", got, err)
+	}
+	fakeBinaries(t, map[string]string{"rofi": `sleep 30`})
+	got, err = Menu(MenuQuestion{Items: []string{"a"}, Prompt: "p", Timeout: 2e8})
+	if err != nil || !got.Cancelled || !got.TimedOut {
+		t.Fatalf("not answered: %+v, %v", got, err)
+	}
+	fakeBinaries(t, map[string]string{"rofi": `echo typed`})
+	got, err = Menu(MenuQuestion{Items: []string{"a"}, Prompt: "p", AllowCustom: true, Timeout: 5e9})
+	if err != nil || got.Chosen != "typed" || !got.Custom || got.Index != -1 {
+		t.Fatalf("typed: %+v, %v", got, err)
+	}
+}
+
+func TestAMenuQuestionIsBoundedAndOneLinePerChoice(t *testing.T) {
+	for _, bad := range []map[string]any{
+		{},
+		{"items": []any{}},
+		{"items": []any{"two\nlines"}},
+		{"items": []any{"a"}, "timeout_seconds": float64(60)},
+		{"items": []any{3.0}},
+	} {
+		if _, err := menuQuestion(bad); err == nil {
+			t.Errorf("accepted %v", bad)
+		}
+	}
+	q, err := menuQuestion(map[string]any{"items": []any{"a"}})
+	if err != nil || q.Prompt != "Choose" || q.Timeout.Seconds() != menuDefault {
+		t.Fatalf("defaults: %+v, %v", q, err)
+	}
+}
+
+func TestWithoutASessionTheMenuSaysSo(t *testing.T) {
+	fakeMachine(t)
+	if _, err := Menu(MenuQuestion{Items: []string{"a"}, Timeout: 1e9}); !errors.Is(err, ErrNoSession) {
+		t.Fatal(err)
+	}
+}
+
+func writeFile(t *testing.T, path, content string) {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestApplicationsAreTheDesktopEntriesTheAccountsWinning(t *testing.T) {
+	root := t.TempDir()
+	own, system := filepath.Join(root, "own"), filepath.Join(root, "system")
+	writeFile(t, filepath.Join(system, "firefox.desktop"), "[Desktop Entry]\nType=Application\nName=Firefox\nExec=firefox %u\nCategories=Network;WebBrowser;\n[Desktop Action new]\nName=New Window\nExec=firefox --new-window\n")
+	writeFile(t, filepath.Join(own, "firefox.desktop"), "[Desktop Entry]\nType=Application\nName=Firefox (mine)\nExec=firefox -P work %u\n")
+	writeFile(t, filepath.Join(system, "kde", "konsole.desktop"), "[Desktop Entry]\nType=Application\nName=Konsole\nExec=konsole\nTerminal=false\nKeywords=terminal;shell;\n")
+	writeFile(t, filepath.Join(system, "hidden.desktop"), "[Desktop Entry]\nType=Application\nName=Helper\nExec=helper\nNoDisplay=true\n")
+	writeFile(t, filepath.Join(system, "link.desktop"), "[Desktop Entry]\nType=Link\nName=A link\nURL=https://example.org\n")
+	got := Applications([]string{own, system}, "", false, 10)
+	var names []string
+	for _, a := range got.Applications {
+		names = append(names, a.ID+"="+a.Name)
+	}
+	if !reflect.DeepEqual(names, []string{"firefox.desktop=Firefox (mine)", "kde-konsole.desktop=Konsole"}) {
+		t.Fatalf("%v", names)
+	}
+	if got := Applications([]string{own, system}, "SHELL", false, 10); got.Count != 1 || got.Applications[0].Name != "Konsole" {
+		t.Fatalf("by keyword: %+v", got)
+	}
+	if got := Applications([]string{own, system}, "", true, 1); got.Count != 3 || !got.Truncated || len(got.Applications) != 1 {
+		t.Fatalf("hidden and limited: %+v", got)
+	}
+}
+
+func TestThemesAreListedOnceWithTheConfiguredOne(t *testing.T) {
+	root := t.TempDir()
+	mine, system := filepath.Join(root, "mine"), filepath.Join(root, "system")
+	writeFile(t, filepath.Join(mine, "mesh.rasi"), "*{}")
+	writeFile(t, filepath.Join(system, "mesh.rasi"), "*{}")
+	writeFile(t, filepath.Join(system, "Arc.rasi"), "*{}")
+	conf, _ := os.ReadFile(filepath.Join("..", "..", "files", "config.rasi"))
+	writeFile(t, filepath.Join(root, "config.rasi"), string(conf))
+	got := Themes([]themeDir{{mine, "mine"}, {system, "system"}}, filepath.Join(root, "config.rasi"))
+	if got.Current != "mesh" || len(got.Themes) != 2 || got.Themes[1].Source != "mine" {
+		t.Fatalf("%+v", got)
+	}
+}
+
+func TestExecIsSplitAsTheDesktopEntrySpecQuotesIt(t *testing.T) {
+	for in, want := range map[string][]string{
+		"firefox %u":              {"firefox"},
+		`sh -c "echo \"a b\"" %F`: {"sh", "-c", `echo "a b"`},
+		"printf 100%% --flag":     {"printf", "100%", "--flag"},
+		`"/opt/My App/run" --x`:   {"/opt/My App/run", "--x"},
+	} {
+		got, err := execWords(in)
+		if err != nil || !reflect.DeepEqual(got, want) {
+			t.Errorf("%s: %q, %v", in, got, err)
+		}
+	}
+	for _, bad := range []string{`"open`, "%u"} {
+		if _, err := execWords(bad); err == nil {
+			t.Errorf("%s was accepted", bad)
+		}
+	}
+}
+
+func TestRunStartsAnApplicationUnderTheAccountsServiceManager(t *testing.T) {
+	root := withSession(t)
+	writeFile(t, filepath.Join(root, "home", ".local", "share", "applications", "htop.desktop"),
+		"[Desktop Entry]\nType=Application\nName=htop\nExec=htop\nTerminal=true\n")
+	t.Setenv("XDG_DATA_DIRS", filepath.Join(root, "none"))
+	// The account's runtime directory, through which its service manager is reached.
+	if err := os.MkdirAll(filepath.Join(runUserDir, strconv.Itoa(os.Getuid())), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	bin := fakeBinaries(t, map[string]string{"systemd-run": `echo "$*" > "$LOG"`, "systemctl": `true`})
+	t.Setenv("LOG", filepath.Join(bin, "log"))
+	got, err := Run("htop.desktop", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !reflect.DeepEqual(got.Argv, []string{"rofi-sensible-terminal", "-e", "htop"}) || !strings.HasPrefix(got.Unit, "rofi-run-") {
+		t.Fatalf("%+v", got)
+	}
+	asked, _ := os.ReadFile(filepath.Join(bin, "log"))
+	if !strings.Contains(string(asked), "--setenv=DISPLAY=:1 --setenv=XDG_SESSION_ID=2 -- rofi-sensible-terminal -e htop") {
+		t.Fatalf("systemd-run was asked: %s", asked)
+	}
+	if _, err := Run("", nil); err == nil {
+		t.Fatal("nothing to run was accepted")
+	}
+	if _, err := Run("nope.desktop", nil); err == nil {
+		t.Fatal("a missing entry was accepted")
+	}
+}
+
+func TestTheDmenuCommandHandsRofiWhatItUnderstands(t *testing.T) {
+	fakeBinaries(t, map[string]string{"rofi": `for a in "$@"; do printf '[%s]' "$a"; done`})
+	shim, _ := filepath.Abs(filepath.Join("..", "..", "files", "bin", "dmenu"))
+	out, err := exec.Command(shim, "-b", "-fn", "Mono 10", "-l", "8", "-p", "pick one", "-nb", "#000", "-i").Output()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(out) != "[-dmenu][-l][8][-p][pick one][-i]" {
+		t.Fatalf("rofi was handed %s", out)
+	}
+}

modules/rofi/cmd/rofi-tools/session.go

@@ -0,0 +1,423 @@
+// The operator's graphical session, as a tool the node's runtime runs finds it (novox/hq ADR 0208).
+//
+// The runtime is a system service running as the operator account (ADR 0175): it has the account's
+// uid and none of the session's environment — no DISPLAY, no XAUTHORITY, no session bus. A tool that
+// draws on the screen or talks to the desktop's D-Bus must find them. It reads them from a process of
+// the account that is part of the session (the window manager first), the same thing `loginctl` and
+// a person's own shell would point at, and says where it found them.
+//
+// Long-lived programs a tool starts go to the account's own service manager through `systemd-run
+// --user`, never as children of the tool: the runtime's unit is a cgroup the service manager empties
+// whenever the runtime restarts, and a compositor or a clipboard owner started from inside it would
+// die with it.
+//
+// This file is the same in every desktop module that carries it; it moves into the Go SDK once a
+// second consumer outside the desktop wants it.
+package main
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"syscall"
+	"time"
+)
+
+// Where the session is looked for. Variables so a test can point them at a fake tree.
+var (
+	procRoot   = "/proc"
+	runUserDir = "/run/user"
+	x11Sockets = "/tmp/.X11-unix"
+)
+
+// sessionHolders are the processes whose environment is the session's, best first: the window
+// manager is the session, the rest are its children. Anything else carrying DISPLAY ranks after them.
+var sessionHolders = []string{"i3", "sway", "i3bar", "picom", "xss-lock", "dunst", "clipmenud", "xterm"}
+
+// sessionKeys are the variables a session carries that a tool hands on to what it runs.
+var sessionKeys = []string{"DISPLAY", "XAUTHORITY", "WAYLAND_DISPLAY", "DBUS_SESSION_BUS_ADDRESS",
+	"XDG_RUNTIME_DIR", "XDG_SESSION_ID", "I3SOCK"}
+
+// Session is what a tool needs to reach the operator's desktop.
+type Session struct {
+	UID        int    `json:"uid"`
+	Display    string `json:"display,omitempty"`
+	XAuthority string `json:"xauthority,omitempty"`
+	Wayland    string `json:"wayland_display,omitempty"`
+	Bus        string `json:"bus,omitempty"`
+	RuntimeDir string `json:"runtime_dir,omitempty"`
+	SessionID  string `json:"session_id,omitempty"`
+	I3Sock     string `json:"i3sock,omitempty"`
+	// From says where the values were found: the tool's own environment, a process, or the socket.
+	From string `json:"from"`
+}
+
+// ErrNoSession is answered by a tool that needs the desktop when nobody is logged in to it.
+var ErrNoSession = errors.New("no graphical session")
+
+// ErrTimedOut is what run answers for a command ended because it ran past its time.
+var ErrTimedOut = errors.New("timed out")
+
+// ErrNoBus is answered by a tool that needs the session bus when the account has none.
+var ErrNoBus = errors.New("no session bus")
+
+// operatorHome is the account's home: what the runtime was told, else the process's own.
+func operatorHome() string {
+	if h := strings.TrimSpace(os.Getenv("MESH_OPERATOR_HOME")); h != "" {
+		return h
+	}
+	h, _ := os.UserHomeDir()
+	return h
+}
+
+// findSession finds the graphical session of the account this tool runs as, or answers
+// ErrNoSession with what it looked at.
+func findSession() (Session, error) {
+	s := findEnvironment()
+	if s.Display == "" && s.Wayland == "" {
+		return s, fmt.Errorf("%w for uid %d on this machine: no process of the account carries DISPLAY "+
+			"or WAYLAND_DISPLAY, and no X server socket in %s has an authority file to go with it. "+
+			"Is anyone logged in to the desktop?", ErrNoSession, s.UID, x11Sockets)
+	}
+	return s, nil
+}
+
+// findBus finds the account's session bus, which a logged-in account has whether or not a desktop
+// is running.
+func findBus() (Session, error) {
+	s := findEnvironment()
+	if s.Bus == "" {
+		return s, fmt.Errorf("%w for uid %d: DBUS_SESSION_BUS_ADDRESS is not set and %s does not exist "+
+			"(the account is not logged in)", ErrNoBus, s.UID, filepath.Join(runUserDir, strconv.Itoa(s.UID), "bus"))
+	}
+	return s, nil
+}
+
+func findEnvironment() Session {
+	uid := os.Getuid()
+	s := Session{UID: uid}
+	own := map[string]string{}
+	for _, k := range sessionKeys {
+		own[k] = os.Getenv(k)
+	}
+	if own["DISPLAY"] != "" || own["WAYLAND_DISPLAY"] != "" {
+		s.fill(own)
+		s.From = "the tool's own environment"
+	} else if pid, comm, env, ok := sessionProcess(uid); ok {
+		s.fill(env)
+		s.From = fmt.Sprintf("process %s (pid %d)", comm, pid)
+	} else if display, ok := lonelyX11Socket(); ok {
+		if a := filepath.Join(operatorHome(), ".Xauthority"); exists(a) {
+			s.Display, s.XAuthority = display, a
+			s.From = "the X server socket and the account's ~/.Xauthority"
+		}
+		s.fill(own)
+	} else {
+		s.fill(own)
+		s.From = "nothing: no session found"
+	}
+	// The bus and the runtime directory are the account's, whether or not the process named them.
+	runtime := filepath.Join(runUserDir, strconv.Itoa(uid))
+	if s.RuntimeDir == "" && exists(runtime) {
+		s.RuntimeDir = runtime
+	}
+	if s.Bus == "" && s.RuntimeDir != "" && exists(filepath.Join(s.RuntimeDir, "bus")) {
+		s.Bus = "unix:path=" + filepath.Join(s.RuntimeDir, "bus")
+	}
+	return s
+}
+
+func (s *Session) fill(env map[string]string) {
+	set := func(dst *string, key string) {
+		if *dst == "" {
+			*dst = env[key]
+		}
+	}
+	set(&s.Display, "DISPLAY")
+	set(&s.XAuthority, "XAUTHORITY")
+	set(&s.Wayland, "WAYLAND_DISPLAY")
+	set(&s.Bus, "DBUS_SESSION_BUS_ADDRESS")
+	set(&s.RuntimeDir, "XDG_RUNTIME_DIR")
+	set(&s.SessionID, "XDG_SESSION_ID")
+	set(&s.I3Sock, "I3SOCK")
+}
+
+// sessionProcess is the best process of this uid whose environment names a display.
+func sessionProcess(uid int) (int, string, map[string]string, bool) {
+	entries, err := os.ReadDir(procRoot)
+	if err != nil {
+		return 0, "", nil, false
+	}
+	type candidate struct {
+		pid  int
+		comm string
+		env  map[string]string
+		rank int
+	}
+	var found []candidate
+	for _, e := range entries {
+		pid, err := strconv.Atoi(e.Name())
+		if err != nil {
+			continue
+		}
+		dir := filepath.Join(procRoot, e.Name())
+		if owner, ok := ownerOf(dir); !ok || owner != uid {
+			continue
+		}
+		raw, err := os.ReadFile(filepath.Join(dir, "environ"))
+		if err != nil {
+			continue
+		}
+		env := parseEnviron(raw)
+		if env["DISPLAY"] == "" && env["WAYLAND_DISPLAY"] == "" {
+			continue
+		}
+		comm := readTrimmed(filepath.Join(dir, "comm"))
+		rank := len(sessionHolders)
+		for i, h := range sessionHolders {
+			if h == comm {
+				rank = i
+				break
+			}
+		}
+		found = append(found, candidate{pid, comm, env, rank})
+	}
+	if len(found) == 0 {
+		return 0, "", nil, false
+	}
+	sort.Slice(found, func(i, j int) bool {
+		if found[i].rank != found[j].rank {
+			return found[i].rank < found[j].rank
+		}
+		return found[i].pid > found[j].pid // the newer of two equals
+	})
+	best := found[0]
+	return best.pid, best.comm, best.env, true
+}
+
+func parseEnviron(raw []byte) map[string]string {
+	env := map[string]string{}
+	for _, kv := range bytes.Split(raw, []byte{0}) {
+		if i := bytes.IndexByte(kv, '='); i > 0 {
+			env[string(kv[:i])] = string(kv[i+1:])
+		}
+	}
+	return env
+}
+
+func ownerOf(path string) (int, bool) {
+	info, err := os.Stat(path)
+	if err != nil {
+		return 0, false
+	}
+	st, ok := info.Sys().(*syscall.Stat_t)
+	if !ok {
+		return 0, false
+	}
+	return int(st.Uid), true
+}
+
+// lonelyX11Socket is the display of the one X server socket there is, when there is exactly one.
+func lonelyX11Socket() (string, bool) {
+	entries, err := os.ReadDir(x11Sockets)
+	if err != nil {
+		return "", false
+	}
+	var displays []string
+	for _, e := range entries {
+		if n := strings.TrimPrefix(e.Name(), "X"); n != e.Name() {
+			if _, err := strconv.Atoi(n); err == nil {
+				displays = append(displays, ":"+n)
+			}
+		}
+	}
+	if len(displays) != 1 {
+		return "", false
+	}
+	return displays[0], true
+}
+
+func readTrimmed(path string) string {
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(string(b))
+}
+
+func exists(path string) bool {
+	_, err := os.Stat(path)
+	return err == nil
+}
+
+// Env is this process's environment with the session's variables in place of its own.
+func (s Session) Env() []string {
+	drop := map[string]bool{}
+	for _, k := range sessionKeys {
+		drop[k] = true
+	}
+	var env []string
+	for _, kv := range os.Environ() {
+		if i := strings.IndexByte(kv, '='); i > 0 && drop[kv[:i]] {
+			continue
+		}
+		env = append(env, kv)
+	}
+	add := func(k, v string) {
+		if v != "" {
+			env = append(env, k+"="+v)
+		}
+	}
+	add("DISPLAY", s.Display)
+	add("XAUTHORITY", s.XAuthority)
+	add("WAYLAND_DISPLAY", s.Wayland)
+	add("DBUS_SESSION_BUS_ADDRESS", s.Bus)
+	add("XDG_RUNTIME_DIR", s.RuntimeDir)
+	add("XDG_SESSION_ID", s.SessionID)
+	add("I3SOCK", s.I3Sock)
+	return env
+}
+
+// mostOutput bounds what a command may answer with, per stream.
+const mostOutput = 256 << 10
+
+// Result is what a command did.
+type Result struct {
+	Stdout    string `json:"stdout"`
+	Stderr    string `json:"stderr,omitempty"`
+	Code      int    `json:"code"`
+	Truncated bool   `json:"truncated,omitempty"`
+}
+
+// run runs a command in the session's environment, its input given, ended with everything it
+// started after timeout. A command that is not installed is an error naming it; one that exits
+// non-zero is a Result with its code, for the caller to judge.
+func (s Session) run(timeout time.Duration, stdin string, name string, args ...string) (Result, error) {
+	path, err := exec.LookPath(name)
+	if err != nil {
+		return Result{}, fmt.Errorf("%s is not installed on this machine", name)
+	}
+	cmd := exec.Command(path, args...)
+	cmd.Env = s.Env()
+	if home := operatorHome(); exists(home) {
+		cmd.Dir = home
+	}
+	if stdin != "" {
+		cmd.Stdin = strings.NewReader(stdin)
+	}
+	var out, errOut capped
+	cmd.Stdout, cmd.Stderr = &out, &errOut
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+	if err := cmd.Start(); err != nil {
+		return Result{}, fmt.Errorf("%s: %w", name, err)
+	}
+	done := make(chan error, 1)
+	go func() { done <- cmd.Wait() }()
+	select {
+	case err = <-done:
+	case <-time.After(timeout):
+		_ = syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)
+		<-done
+		return Result{Stdout: out.String(), Stderr: errOut.String()},
+			fmt.Errorf("%s did not finish within %s and was ended: %w", name, timeout, ErrTimedOut)
+	}
+	r := Result{Stdout: out.String(), Stderr: errOut.String(), Truncated: out.cut || errOut.cut}
+	var exit *exec.ExitError
+	if errors.As(err, &exit) {
+		r.Code = exit.ExitCode()
+	} else if err != nil {
+		return r, fmt.Errorf("%s: %w", name, err)
+	}
+	return r, nil
+}
+
+// detach starts a long-lived program under the account's own service manager, as a transient unit
+// that carries the session's display, so it outlives the runtime that asked for it. A unit already
+// running under the same name is stopped first, so a fixed name means "at most one".
+func (s Session) detach(unit string, args ...string) error {
+	if s.RuntimeDir == "" {
+		return fmt.Errorf("%w: the account's runtime directory is missing, so its service manager "+
+			"cannot be reached", ErrNoBus)
+	}
+	_, _ = s.run(5*time.Second, "", "systemctl", "--user", "stop", unit+".service")
+	call := []string{"--user", "--collect", "--quiet", "--unit=" + unit}
+	for _, kv := range [][2]string{{"DISPLAY", s.Display}, {"XAUTHORITY", s.XAuthority},
+		{"WAYLAND_DISPLAY", s.Wayland}, {"XDG_SESSION_ID", s.SessionID}, {"I3SOCK", s.I3Sock}} {
+		if kv[1] != "" {
+			call = append(call, "--setenv="+kv[0]+"="+kv[1])
+		}
+	}
+	call = append(call, "--")
+	call = append(call, args...)
+	r, err := s.run(10*time.Second, "", "systemd-run", call...)
+	if err != nil {
+		return err
+	}
+	if r.Code != 0 {
+		return fmt.Errorf("systemd-run %s: %s", unit, strings.TrimSpace(r.Stderr))
+	}
+	return nil
+}
+
+// uniqueUnit is a transient unit name that will not collide with an earlier one.
+func uniqueUnit(prefix string) string {
+	return fmt.Sprintf("%s-%d", prefix, time.Now().UnixNano())
+}
+
+type capped struct {
+	bytes.Buffer
+	cut bool
+}
+
+func (c *capped) Write(p []byte) (int, error) {
+	if room := mostOutput - c.Len(); room < len(p) {
+		if room > 0 {
+			c.Buffer.Write(p[:room])
+		}
+		c.cut = true
+		return len(p), nil
+	}
+	return c.Buffer.Write(p)
+}
+
+// processesOf are the pids of this uid's processes whose command name is comm, oldest first.
+func processesOf(comm string) []int {
+	entries, err := os.ReadDir(procRoot)
+	if err != nil {
+		return nil
+	}
+	uid := os.Getuid()
+	var pids []int
+	for _, e := range entries {
+		pid, err := strconv.Atoi(e.Name())
+		if err != nil {
+			continue
+		}
+		dir := filepath.Join(procRoot, e.Name())
+		if owner, ok := ownerOf(dir); !ok || owner != uid {
+			continue
+		}
+		if readTrimmed(filepath.Join(dir, "comm")) == comm {
+			pids = append(pids, pid)
+		}
+	}
+	sort.Ints(pids)
+	return pids
+}
+
+// signalAll sends sig to every process of this uid named comm, and answers the pids it reached.
+func signalAll(comm string, sig syscall.Signal) []int {
+	var reached []int
+	for _, pid := range processesOf(comm) {
+		if syscall.Kill(pid, sig) == nil {
+			reached = append(reached, pid)
+		}
+	}
+	return reached
+}

modules/rofi/cmd/rofi-tools/session_test.go

@@ -0,0 +1,174 @@
+package main
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+)
+
+// fakeMachine points the session finder at a temporary /proc, /run/user and X socket directory, with
+// none of the test process's own session variables, and gives back the root.
+func fakeMachine(t *testing.T) string {
+	t.Helper()
+	root := t.TempDir()
+	procRoot, runUserDir, x11Sockets = filepath.Join(root, "proc"), filepath.Join(root, "run-user"), filepath.Join(root, "x11")
+	for _, d := range []string{procRoot, runUserDir, x11Sockets} {
+		if err := os.MkdirAll(d, 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	for _, k := range sessionKeys {
+		t.Setenv(k, "")
+	}
+	t.Setenv("MESH_OPERATOR_HOME", filepath.Join(root, "home"))
+	t.Cleanup(func() { procRoot, runUserDir, x11Sockets = "/proc", "/run/user", "/tmp/.X11-unix" })
+	return root
+}
+
+func fakeProcess(t *testing.T, pid int, comm string, env ...string) {
+	t.Helper()
+	dir := filepath.Join(procRoot, strconv.Itoa(pid))
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "comm"), []byte(comm+"\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "environ"), []byte(strings.Join(env, "\x00")+"\x00"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestTheSessionIsReadFromTheWindowManagerBeforeAnyOtherProcess(t *testing.T) {
+	fakeMachine(t)
+	fakeProcess(t, 900, "xterm", "DISPLAY=:9", "XAUTHORITY=/elsewhere")
+	fakeProcess(t, 100, "i3", "DISPLAY=:1", "XAUTHORITY=/home/op/.Xauthority",
+		"DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus", "XDG_SESSION_ID=3", "SECRET_TOKEN=never-copied")
+	fakeProcess(t, 50, "bash", "PATH=/usr/bin")
+	s, err := findSession()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if s.Display != ":1" || s.XAuthority != "/home/op/.Xauthority" || s.SessionID != "3" || !strings.Contains(s.From, "i3 (pid 100)") {
+		t.Fatalf("the window manager's environment: %+v", s)
+	}
+	for _, kv := range s.Env() {
+		if strings.HasPrefix(kv, "SECRET_TOKEN=") {
+			t.Fatal("a variable of the session process that is not a session variable was handed on")
+		}
+	}
+}
+
+func TestAnyProcessCarryingADisplayServesWhenTheWindowManagerIsNotFound(t *testing.T) {
+	fakeMachine(t)
+	fakeProcess(t, 10, "firefox", "DISPLAY=:0")
+	fakeProcess(t, 20, "firefox", "DISPLAY=:2")
+	s, err := findSession()
+	if err != nil || s.Display != ":2" {
+		t.Fatalf("the newest of two equals: %+v, %v", s, err)
+	}
+}
+
+func TestNoSessionIsAClearAnswerNotAGuess(t *testing.T) {
+	fakeMachine(t)
+	fakeProcess(t, 10, "sshd", "PATH=/usr/bin")
+	_, err := findSession()
+	if !errors.Is(err, ErrNoSession) || !strings.Contains(err.Error(), "logged in to the desktop") {
+		t.Fatalf("no session: %v", err)
+	}
+}
+
+func TestOneXSocketAndTheAccountsAuthorityFileAreASession(t *testing.T) {
+	root := fakeMachine(t)
+	if err := os.WriteFile(filepath.Join(x11Sockets, "X0"), nil, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Join(root, "home"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(root, "home", ".Xauthority"), nil, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	s, err := findSession()
+	if err != nil || s.Display != ":0" || !strings.HasSuffix(s.XAuthority, "/home/.Xauthority") {
+		t.Fatalf("socket and authority: %+v, %v", s, err)
+	}
+}
+
+func TestTheBusIsTheAccountsRuntimeDirectoryWhenNoProcessNamesIt(t *testing.T) {
+	fakeMachine(t)
+	runtime := filepath.Join(runUserDir, strconv.Itoa(os.Getuid()))
+	if _, err := findBus(); !errors.Is(err, ErrNoBus) {
+		t.Fatalf("no runtime directory is no bus: %v", err)
+	}
+	if err := os.MkdirAll(runtime, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(runtime, "bus"), nil, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	s, err := findBus()
+	if err != nil || s.Bus != "unix:path="+filepath.Join(runtime, "bus") || s.RuntimeDir != runtime {
+		t.Fatalf("bus: %+v, %v", s, err)
+	}
+	env := strings.Join(s.Env(), "\n")
+	if !strings.Contains(env, "XDG_RUNTIME_DIR="+runtime) || !strings.Contains(env, "DBUS_SESSION_BUS_ADDRESS=unix:path=") {
+		t.Fatalf("the bus is handed on: %s", env)
+	}
+}
+
+func TestACommandIsBoundedAndANonZeroExitIsAResult(t *testing.T) {
+	fakeMachine(t)
+	s := Session{}
+	r, err := s.run(5*time.Second, "in", "sh", "-c", "cat; echo err >&2; exit 3")
+	if err != nil || r.Stdout != "in" || r.Code != 3 || strings.TrimSpace(r.Stderr) != "err" {
+		t.Fatalf("result: %+v, %v", r, err)
+	}
+	start := time.Now()
+	if _, err := s.run(200*time.Millisecond, "", "sh", "-c", "sleep 30 & sleep 30"); err == nil || time.Since(start) > 5*time.Second {
+		t.Fatalf("a command past its time is ended with what it started: %v after %s", err, time.Since(start))
+	}
+	if _, err := s.run(time.Second, "", "no-such-program-here"); err == nil || !strings.Contains(err.Error(), "not installed") {
+		t.Fatalf("a missing program: %v", err)
+	}
+}
+
+func TestDetachAsksTheAccountsServiceManagerWithTheSessionsDisplay(t *testing.T) {
+	fakeMachine(t)
+	bin := fakeBinaries(t, map[string]string{
+		"systemctl":   `echo "systemctl $*" >> "$LOG"`,
+		"systemd-run": `echo "systemd-run $*" >> "$LOG"`,
+	})
+	log := filepath.Join(bin, "log")
+	t.Setenv("LOG", log)
+	s := Session{Display: ":1", XAuthority: "/x", RuntimeDir: "/run/user/1"}
+	if err := s.detach("picom-session", "picom", "--config", "/c"); err != nil {
+		t.Fatal(err)
+	}
+	got, _ := os.ReadFile(log)
+	want := "systemctl --user stop picom-session.service\n" +
+		"systemd-run --user --collect --quiet --unit=picom-session --setenv=DISPLAY=:1 --setenv=XAUTHORITY=/x -- picom --config /c\n"
+	if string(got) != want {
+		t.Fatalf("detach ran:\n%s\nwant:\n%s", got, want)
+	}
+	if err := (Session{}).detach("x", "y"); !errors.Is(err, ErrNoBus) {
+		t.Fatalf("no runtime directory: %v", err)
+	}
+}
+
+// fakeBinaries puts shell scripts named for programs first on PATH, and answers their directory.
+func fakeBinaries(t *testing.T, scripts map[string]string) string {
+	t.Helper()
+	dir := t.TempDir()
+	for name, body := range scripts {
+		if err := os.WriteFile(filepath.Join(dir, name), []byte("#!/bin/sh\n"+body+"\n"), 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	t.Setenv("PATH", dir+string(os.PathListSeparator)+os.Getenv("PATH"))
+	return dir
+}

modules/rofi/files/bin/dmenu

@@ -0,0 +1,26 @@
+#!/bin/sh
+# dmenu, as this node's launcher answers it (module rofi, novox/hq ADR 0208). The node-launcher
+# seat's dmenu-compatible command: choices on standard input, the chosen one on standard output,
+# exit 1 when nothing was chosen. A script calls `dmenu` and works whichever module holds the seat.
+#
+# rofi understands dmenu's -p, -l and -i. dmenu's look options (-fn, -nb, -nf, -sb, -sf, -m, -w)
+# take a value rofi would misread, so they are dropped with it; -b and -f are dropped alone. The
+# look is the launcher's theme.
+set -u
+n=$#
+while [ "$n" -gt 0 ]; do
+	arg=$1
+	shift
+	n=$((n - 1))
+	case $arg in
+	-fn | -nb | -nf | -sb | -sf | -m | -w)
+		if [ "$n" -gt 0 ]; then
+			shift
+			n=$((n - 1))
+		fi
+		;;
+	-b | -f) ;;
+	*) set -- "$@" "$arg" ;;
+	esac
+done
+exec rofi -dmenu "$@"

modules/rofi/files/bin/rofi-launch

@@ -0,0 +1,39 @@
+#!/bin/sh
+# rofi-launch drun|run|window|filebrowser|sudo (module rofi, novox/hq ADR 0208): what the launcher's
+# key bindings run.
+#
+# After a resume the keyboard grab can fail for a moment, and rofi then exits at once: a key press
+# that opens nothing. So a failure within half a second is tried again, up to five times. A person
+# closing the menu takes longer than that, and is never shown it a second time.
+set -u
+mode=${1:-drun}
+
+now_ms() { date +%s%3N; }
+
+attempt() {
+	i=0
+	while [ "$i" -lt 5 ]; do
+		start=$(now_ms)
+		"$@" && return 0
+		[ $(($(now_ms) - start)) -ge 500 ] && return 1
+		i=$((i + 1))
+		sleep 0.1
+	done
+	return 1
+}
+
+case $mode in
+drun | run | window | filebrowser)
+	attempt rofi -show "$mode"
+	;;
+sudo)
+	# A command line, run with sudo in the node's terminal.
+	command=$(attempt rofi -dmenu -p sudo </dev/null) || exit 0
+	[ -n "$command" ] || exit 0
+	exec rofi-sensible-terminal -e sudo sh -c "$command"
+	;;
+*)
+	echo "rofi-launch: no mode $mode (drun, run, window, filebrowser, sudo)" >&2
+	exit 2
+	;;
+esac