WIP: power module (in progress)

The i3 and laptop READMEs each pointed at the other for 10-asus.conf and 20-g14.conf,
so nobody owned them. The module now writes both (adopted paths, so no duplicate
binding breaks i3's config check), ships the scripts they call, runs the media keys
with notifications again, and brings back the touchpad reset after resume as a unit
the sleep services want. zephyrus_keys answers what each custom key runs; the check
flags as-user, thd's account and the resume unit. xorg-xinput is the xorg module's.

modules/adwaita/README.md

@@ -0,0 +1,103 @@
+# adwaita
+
+The desktop's theme as a module (novox/hq ADR 0208, research 026, to-be 42 phase 2, step 6): Adwaita
+for GTK, Qt, the portal and the cursor, dark by default. It claims no seat, because themes coexist.
+
+- **Packages:** `gnome-themes-extra` (Adwaita-dark for GTK 2 and 3), `adwaita-icon-theme`,
+  `adwaita-cursors`, `qt6ct`, `xdg-desktop-portal-gtk`.
+- **Environment** (ADR 0203), the five words today's `~/.xinitrc` exported plus the cursor:
+  - `GTK_THEME=Adwaita:dark`;
+  - `GTK2_RC_FILES=/usr/share/themes/Adwaita-dark/gtk-2.0/gtkrc`;
+  - `QT_QPA_PLATFORMTHEME=qt6ct`;
+  - `QT_STYLE_OVERRIDE=Fusion`;
+  - `QT_SELECT=6`;
+  - `XCURSOR_THEME=Adwaita`, `XCURSOR_SIZE=24`.
+- **Session code** (ADR 0208 §4):
+  - in the `xinitrc` slot `normal`, the GSettings keys the portal serves (dark, the GTK and icon theme,
+    the cursor, the UI and monospace fonts), set at every session start. This replaces the
+    predecessor's `~/scripts/xdg-appearance`;
+  - in the `xresources` slot `normal`, `Xcursor.theme` and `Xcursor.size`.
+
+## What it owns
+
+| path | class | from |
+|---|---|---|
+| `~/.config/gtk-3.0/settings.ini` | owned (the found file kept once) | [`config/gtk-settings.ini`](config/gtk-settings.ini) |
+| `~/.config/gtk-4.0/settings.ini` | owned | the same file |
+| `~/.config/qt6ct/qt6ct.conf` | owned | [`config/qt6ct.conf`](config/qt6ct.conf) |
+| `~/.config/xdg-desktop-portal/portals.conf` | owned | [`config/portals.conf`](config/portals.conf) |
+| `~/.icons/default/index.theme` | owned | [`config/cursor-index.theme`](config/cursor-index.theme): the cursor for programs that read neither `XCURSOR_THEME` nor the resources |
+
+**`qt6ct.conf` is the mesh's now.** A change made in qt6ct's own window is replaced at the next push,
+and the window's saved geometry goes with it. The theme is this module's to say. Settings will make it
+the operator's (issue 168).
+
+## What it improves
+
+- **No package from the user repository.** Today's Qt style, `adwaita-dark` (`QT_STYLE_OVERRIDE` and
+  qt6ct's `Adwaita-Dark`), comes from the user repository's `adwaita-qt5`/`adwaita-qt6-git`, a
+  project that is no longer developed. The module uses Qt's own **Fusion** style with qt6ct's
+  **`darker`** palette, both shipped with Qt and qt6ct. **This is the one visible change:** Qt
+  programs keep a dark palette, drawn by Fusion instead of Adwaita-Qt.
+- **One Qt tool.** `qt5ct` is gone (installed on the desktop only, with a configuration on both).
+  `QT_SELECT=6` and `qt6ct` cover the Qt 6 programs. A Qt 5 program gets Fusion through
+  `QT_STYLE_OVERRIDE`, but not the palette.
+- **The fonts research 026/04 chose:** Inter 11 for GTK, Qt and GSettings' interface font, and
+  JetBrains Mono Nerd Font for Qt's fixed font and GSettings' monospace. Today these are Noto Sans 12,
+  Adwaita Sans 11 and nothing.
+- **The cursor said everywhere**: GTK's settings, GSettings, `XCURSOR_*`, the X resources and the
+  default theme. Today only the resources and GSettings said it.
+- **The portal answers secrets.** `portals.conf` routes `org.freedesktop.impl.portal.Secret` to
+  gnome-keyring. Today `adwaita_portal_check` shows no backend answering it: gtk does not implement
+  it, and gnome-keyring's backend names only GNOME.
+
+## Tools
+
+| tool | | what |
+|---|---|---|
+| `adwaita_appearance` | r/a | dark or light as each audience sees it (GSettings, the portal's own answer, the GTK files, Qt's style and palette, the theme words in the user manager). `mode` switches GSettings for the session, and the answer says what follows live (programs asking the portal) and what stays dark (GTK 3 under `GTK_THEME`, the declared files) |
+| `adwaita_cursor` | r/a | the cursor in GSettings, the resources and the environment, and the cursor themes installed; set theme or size for new windows (GSettings, and the resources when a session runs) |
+| `adwaita_icons` | r | icon themes installed (where, what each inherits, whether it has cursors), and the one GSettings, GTK and Qt use |
+| `adwaita_portal_check` | r | the backends installed and what each implements, which `portals.conf` decides (the first that exists, in xdg-desktop-portal's order), the backend answering each interface, what runs on the bus, and the colour scheme the portal answers |
+
+Each reaches GSettings, the portal and the user manager on the account's bus. Only the cursor's X
+resources need the session. From the user manager it reads only the theme's own words.
+
+**The appearance is a session's choice.** A persistent dark or light, for the files too, is a setting
+and waits for issue 168. Until then the module's default is dark, and `mode` lasts until the next
+login.
+
+## What it leaves found
+
+`~/.config/qt5ct/`, `~/.config/gtk-3.0/bookmarks` and everything else in those directories,
+`~/scripts/xdg-appearance`, and the user repository's `adwaita-qt*` packages.
+
+## The one-off migration (ADR 0182)
+
+**Once `adwaita` is assigned:**
+
+1. In `~/.xinitrc`, the theme exports and `~/scripts/xdg-appearance || true` go (see `xorg`'s list).
+2. Delete `~/scripts/xdg-appearance`.
+3. In `~/.Xresources`, delete the two `Xcursor` lines.
+4. Delete `~/.config/qt5ct/`.
+5. Remove the user repository's packages: `sudo pacman -Rns adwaita-qt5-git adwaita-qt6-git`
+   (laptop), `sudo pacman -Rns adwaita-qt5 adwaita-qt6-git adwaita-dark qt5ct` (desktop). Check first
+   that nothing else needs them (`pacman -Qi`).
+
+## What changes when it is assigned
+
+| | g14 | shanks |
+|---|---|---|
+| packages | none (all present) | the same |
+| GTK settings, `portals.conf` | the found files kept once, then the module's: adds the cursor and Inter, keeps Adwaita dark; `portals.conf` adds the Secret line | the same |
+| `qt6ct.conf` | Fusion with the `darker` palette, Inter and JetBrains Mono, instead of Adwaita-Dark with Noto Sans | the same |
+| `~/.icons/default/index.theme` | new | new |
+| environment | `QT_STYLE_OVERRIDE` becomes `Fusion`; `XCURSOR_*` added; the rest as `~/.xinitrc` exported them | the same |
+| running programs | **nothing**: settings are read at a program's start, and GSettings is set at the next login | the same |
+| next login | GSettings' fonts become Inter and JetBrains Mono. A secret request through the portal finds gnome-keyring | the same |
+
+## Blockers
+
+- **`fonts` first**, for Inter and JetBrains Mono. Without them, GTK and Qt fall back to the nearest
+  installed face.
+- **Light is a session's choice only**, until settings (issue 168).

modules/adwaita/cmd/adwaita-tools/adwaita_test.go

@@ -0,0 +1,246 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"adwaita/internal/desktop"
+)
+
+type manifest struct {
+	Capabilities []string `json:"capabilities"`
+	Claims       []any    `json:"claims"`
+	Tools        []string `json:"tools"`
+	Environment  struct {
+		Variables map[string]string `json:"variables"`
+	} `json:"environment"`
+	Shell []struct {
+		For, Slot, Code string
+	} `json:"shell"`
+	Resources []map[string]any `json:"resources"`
+}
+
+func readManifest(t *testing.T) manifest {
+	raw, err := os.ReadFile(filepath.Join("..", "..", "module.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var m manifest
+	if err := json.Unmarshal(raw, &m); err != nil {
+		t.Fatal(err)
+	}
+	return m
+}
+
+func TestItContributesTheThemesWordsAndClaimsNoSeat(t *testing.T) {
+	m := readManifest(t)
+	if m.Claims != nil {
+		t.Fatal("a theme is not a seat: several coexist")
+	}
+	want := map[string]string{"GTK_THEME": "Adwaita:dark", "GTK2_RC_FILES": "/usr/share/themes/Adwaita-dark/gtk-2.0/gtkrc",
+		"QT_QPA_PLATFORMTHEME": "qt6ct", "QT_STYLE_OVERRIDE": "Fusion", "QT_SELECT": "6", "XCURSOR_THEME": "Adwaita", "XCURSOR_SIZE": "24"}
+	if len(m.Environment.Variables) != len(want) {
+		t.Fatalf("%v", m.Environment.Variables)
+	}
+	for k, v := range want {
+		if m.Environment.Variables[k] != v {
+			t.Errorf("%s=%q", k, m.Environment.Variables[k])
+		}
+	}
+	served := map[string]bool{}
+	for _, tool := range tools(adwaita{}) {
+		served[tool.Name] = true
+	}
+	if len(served) != len(m.Tools) {
+		t.Fatalf("%v %v", served, m.Tools)
+	}
+	for _, n := range m.Tools {
+		if !served[n] {
+			t.Errorf("%s", n)
+		}
+	}
+}
+
+func TestTheSessionLinesSetGSettingsAndTheResourcesTheCursor(t *testing.T) {
+	m := readManifest(t)
+	if len(m.Shell) != 2 || m.Shell[0].For != "xresources" || m.Shell[1].For != "xinitrc" || m.Shell[0].Slot != "normal" || m.Shell[1].Slot != "normal" {
+		t.Fatalf("%+v", m.Shell)
+	}
+	if m.Shell[0].Code != "! adwaita: the cursor, for X programs that take it from the resources.\nXcursor.theme: Adwaita\nXcursor.size: 24\n" {
+		t.Fatalf("%q", m.Shell[0].Code)
+	}
+	x := m.Shell[1].Code
+	for _, want := range []string{"color-scheme 'prefer-dark'", "gtk-theme 'Adwaita'", "icon-theme 'Adwaita'", "cursor-theme 'Adwaita'", "font-name 'Inter 11'", "monospace-font-name 'JetBrainsMono Nerd Font 11'"} {
+		if !strings.Contains(x, want) {
+			t.Errorf("lacks %s", want)
+		}
+	}
+	for _, l := range strings.Split(strings.TrimSpace(x), "\n") {
+		if !strings.HasPrefix(l, "#") && !strings.HasSuffix(l, "|| true") {
+			t.Errorf("a session line that can stop the session's start: %q", l)
+		}
+	}
+}
+
+func TestItOwnsTheFilesItsSourcesHoldAndNoQt5Duplicate(t *testing.T) {
+	m := readManifest(t)
+	sources := map[string]string{"gtk3": "gtk-settings.ini", "gtk4": "gtk-settings.ini", "qt6ct": "qt6ct.conf", "portals": "portals.conf", "cursor": "cursor-index.theme"}
+	pkgs := []string{}
+	for _, r := range m.Resources {
+		id := r["id"].(string)
+		if r["type"] == "package" {
+			pkgs = append(pkgs, r["package"].(string))
+			continue
+		}
+		raw, _ := os.ReadFile(filepath.Join("..", "..", "config", sources[id]))
+		if r["content"] != string(raw) || r["into"] != nil || r["owner"] != "${machine:account}" {
+			t.Errorf("%s is not config/%s, whole and the account's", id, sources[id])
+		}
+		if strings.Contains(r["path"].(string), "qt5ct") {
+			t.Error("qt5ct: both workstations run Qt 6 programs through qt6ct; a second tool is a duplicate")
+		}
+	}
+	if strings.Join(pkgs, ",") != "gnome-themes-extra,adwaita-icon-theme,adwaita-cursors,qt6ct,xdg-desktop-portal-gtk" {
+		t.Fatalf("%v", pkgs)
+	}
+	qt := readINI(filepath.Join("..", "..", "config", "qt6ct.conf"))
+	if qt["Appearance"]["style"] != "Fusion" || qt["Appearance"]["custom_palette"] != "true" || !strings.Contains(qt["Fonts"]["general"], "Inter,11") {
+		t.Fatalf("%v", qt)
+	}
+	if _, err := os.Stat("/usr/share/qt6ct/colors"); err == nil {
+		if _, err := os.Stat(qt["Appearance"]["color_scheme_path"]); err != nil {
+			t.Fatalf("qt6ct ships no %s", qt["Appearance"]["color_scheme_path"])
+		}
+	}
+	gtk := readINI(filepath.Join("..", "..", "config", "gtk-settings.ini"))["Settings"]
+	if gtk["gtk-theme-name"] != "Adwaita" || gtk["gtk-application-prefer-dark-theme"] != "1" || gtk["gtk-font-name"] != "Inter 11" {
+		t.Fatalf("%v", gtk)
+	}
+}
+
+func TestKeyFilesAreReadWithTheirComments(t *testing.T) {
+	ini := ParseINI("# c\n[A]\nk = v\n; also a comment\n[B]\nx=1=2\n")
+	if ini["A"]["k"] != "v" || ini["B"]["x"] != "1=2" || len(ini) != 2 {
+		t.Fatalf("%v", ini)
+	}
+}
+
+func TestThePortalsAnswerIsResolvedAsXdgDesktopPortalDoes(t *testing.T) {
+	dir := t.TempDir()
+	os.WriteFile(filepath.Join(dir, "gtk.portal"), []byte("[portal]\nDBusName=org.freedesktop.impl.portal.desktop.gtk\nInterfaces=org.freedesktop.impl.portal.FileChooser;org.freedesktop.impl.portal.Settings;\nUseIn=gnome\n"), 0o644)
+	os.WriteFile(filepath.Join(dir, "gnome-keyring.portal"), []byte("[portal]\nDBusName=org.freedesktop.secrets\nInterfaces=org.freedesktop.impl.portal.Secret;\nUseIn=gnome\n"), 0o644)
+	os.WriteFile(filepath.Join(dir, "kde.portal"), []byte("[portal]\nDBusName=org.freedesktop.impl.portal.desktop.kde\nInterfaces=org.freedesktop.impl.portal.FileChooser;\nUseIn=KDE\n"), 0o644)
+	b := Backends([]string{dir})
+	if len(b) != 3 || b[0].Name != "gnome-keyring" || len(b[1].Interfaces) != 2 {
+		t.Fatalf("%+v", b)
+	}
+	got := Resolve(b, map[string]string{"default": "gtk", "org.freedesktop.impl.portal.Secret": "gnome-keyring"}, []string{"i3"})
+	if got["org.freedesktop.impl.portal.FileChooser"] != "gtk" || got["org.freedesktop.impl.portal.Secret"] != "gnome-keyring" || got["org.freedesktop.impl.portal.Settings"] != "gtk" {
+		t.Fatalf("%v", got)
+	}
+	got = Resolve(b, map[string]string{"default": "gtk"}, []string{"i3"})
+	if got["org.freedesktop.impl.portal.Secret"] != "(none)" {
+		t.Fatalf("gtk does not implement secrets: %v", got)
+	}
+	got = Resolve(b, map[string]string{"default": "none;gtk"}, nil)
+	if got["org.freedesktop.impl.portal.FileChooser"] != "(none)" {
+		t.Fatalf("none stops the list: %v", got)
+	}
+	got = Resolve(b, nil, []string{"KDE"})
+	if got["org.freedesktop.impl.portal.FileChooser"] != "kde" || got["org.freedesktop.impl.portal.Settings"] != "(none)" {
+		t.Fatalf("with no configuration, UseIn decides: %v", got)
+	}
+	c := PortalConfigs("/h", []string{"i3", "GNOME"})
+	if c[0] != "/h/.config/xdg-desktop-portal/i3-portals.conf" || c[1] != "/h/.config/xdg-desktop-portal/gnome-portals.conf" || c[2] != "/h/.config/xdg-desktop-portal/portals.conf" {
+		t.Fatalf("%v", c[:3])
+	}
+}
+
+func TestThemesAreFoundOnceEachWithCursorsAndIcons(t *testing.T) {
+	a, b := t.TempDir(), t.TempDir()
+	os.MkdirAll(filepath.Join(a, "Adwaita", "cursors"), 0o755)
+	os.MkdirAll(filepath.Join(b, "Adwaita"), 0o755)
+	os.WriteFile(filepath.Join(b, "Adwaita", "index.theme"), []byte("[Icon Theme]\nName=Adwaita\nInherits=hicolor\nDirectories=16x16\n"), 0o644)
+	os.MkdirAll(filepath.Join(b, "hicolor"), 0o755)
+	os.WriteFile(filepath.Join(b, "hicolor", "index.theme"), []byte("[Icon Theme]\nName=Hicolor\nDirectories=16x16\n"), 0o644)
+	os.MkdirAll(filepath.Join(b, "empty"), 0o755)
+	got := Themes([]string{a, b})
+	if len(got) != 2 || got[0].Name != "Adwaita" || !got[0].Cursors || got[0].Icons || got[0].Dir != filepath.Join(a, "Adwaita") || got[1].Name != "hicolor" {
+		t.Fatalf("the first directory's Adwaita hides the second's: %+v", got)
+	}
+}
+
+type fake struct {
+	ran []string
+	get map[string]string
+}
+
+func (f *fake) desk() desktop.Desk {
+	return desktop.Desk{
+		Find: func() (*desktop.Session, error) { return nil, &desktop.NoSession{Reason: "none"} },
+		Run: func(_ context.Context, env []string, _ []byte, name string, args ...string) desktop.Result {
+			line := strings.Join(append([]string{name}, args...), " ")
+			f.ran = append(f.ran, line)
+			switch {
+			case name == "gsettings" && args[0] == "get":
+				return desktop.Result{Stdout: "'" + f.get[args[2]] + "'\n"}
+			case name == "gsettings" && args[0] == "set":
+				f.get[args[2]] = args[3]
+			case name == "systemctl":
+				return desktop.Result{Stdout: "GTK_THEME=Adwaita:dark\nNPM_TOKEN=secret\nXDG_CURRENT_DESKTOP=i3\n"}
+			case name == "busctl" && args[1] == "call":
+				return desktop.Result{Stdout: "v u 1\n"}
+			}
+			return desktop.Result{}
+		},
+	}
+}
+
+func TestAppearanceSwitchesGSettingsAndSaysWhatFollowsAndWhatStays(t *testing.T) {
+	f := &fake{get: map[string]string{"color-scheme": "prefer-dark", "gtk-theme": "Adwaita"}}
+	a := adwaita{d: f.desk(), home: t.TempDir()}
+	got, err := a.appearance(context.Background(), desktop.Args{"mode": "light"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	j := asJSON(got)
+	if f.get["color-scheme"] != "prefer-light" || !strings.Contains(j, `"switched":"light"`) || !strings.Contains(j, "GTK_THEME=Adwaita:dark") || !strings.Contains(j, `"lasts"`) {
+		t.Fatalf("%s", j)
+	}
+	if strings.Contains(j, "secret") || strings.Contains(j, "NPM_TOKEN") {
+		t.Fatal("only the theme's words are read back from the user manager")
+	}
+	if _, err := a.appearance(context.Background(), desktop.Args{"mode": "blue"}); err == nil {
+		t.Fatal("mode is dark or light")
+	}
+	got, _ = a.appearance(context.Background(), desktop.Args{})
+	if strings.Contains(asJSON(got), "switched") {
+		t.Fatal("reading changes nothing")
+	}
+}
+
+func TestACursorThemeMustBeInstalledAndWithoutASessionOnlyGSettingsChanges(t *testing.T) {
+	dir := t.TempDir()
+	os.MkdirAll(filepath.Join(dir, "Adwaita", "cursors"), 0o755)
+	f := &fake{get: map[string]string{}}
+	a := adwaita{d: f.desk(), home: t.TempDir(), iconDirs: []string{dir}}
+	if _, err := a.cursor(context.Background(), desktop.Args{"theme": "Bibata"}); err == nil {
+		t.Fatal("a theme that is not installed")
+	}
+	got, err := a.cursor(context.Background(), desktop.Args{"theme": "Adwaita", "size": float64(32)})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if f.get["cursor-theme"] != "Adwaita" || f.get["cursor-size"] != "32" || !strings.Contains(asJSON(got), "no graphical session") {
+		t.Fatalf("%v %s", f.get, asJSON(got))
+	}
+}
+
+func asJSON(v any) string {
+	b, _ := json.Marshal(v)
+	return string(b)
+}

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

@@ -0,0 +1,84 @@
+// adwaita's tools (novox/hq ADR 0208, research 026/05): appearance (dark or light for GTK, Qt and the
+// portal at once), cursor, icons and portal-check. The predecessor's appearance script is folded into
+// the first, and into the module's session line.
+//
+// None needs the display except setting the cursor's X resources: GSettings, the portal and the user
+// manager are reached on the account's own bus, which exists whenever the operator's user manager
+// runs.
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"time"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+
+	"adwaita/internal/desktop"
+)
+
+func main() {
+	home := desktop.Home()
+	a := adwaita{
+		d: desktop.Machine("i3", "sway"), home: home,
+		iconDirs:   []string{filepath.Join(home, ".local", "share", "icons"), filepath.Join(home, ".icons"), "/usr/local/share/icons", "/usr/share/icons"},
+		portalDirs: []string{"/usr/share/xdg-desktop-portal/portals"},
+		uid:        os.Getuid(),
+	}
+	if err := stdio.Serve("", tools(a)); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+func call(run func(ctx context.Context, a desktop.Args) (any, error)) func(map[string]any) (any, error) {
+	return func(args map[string]any) (any, error) {
+		ctx, cancel := context.WithTimeout(context.Background(), 25*time.Second)
+		defer cancel()
+		return run(ctx, desktop.Args(args))
+	}
+}
+
+func tools(a adwaita) []stdio.Tool {
+	return []stdio.Tool{
+		{
+			Name: "adwaita_appearance",
+			Description: "Dark or light, as each audience sees it now: GSettings (which the portal serves to " +
+				"Electron, Firefox and flatpaks), the portal's own answer, the GTK settings files, Qt's palette " +
+				"and the theme words in the user manager's environment. With mode, switch GSettings for the " +
+				"running session and answer which audiences follow live and which keep the module's dark " +
+				"default until it is a setting.",
+			Input: desktop.Schema(map[string]any{"mode": desktop.Enum("switch to (optional)", "dark", "light")}),
+			Run:   call(a.appearance),
+		},
+		{
+			Name: "adwaita_cursor",
+			Description: "The cursor theme and size in force (GSettings, the X resources, XCURSOR_* in the user " +
+				"manager) and the cursor themes installed. With theme and/or size, set them for windows opened " +
+				"from now on; the module's defaults return at the next login.",
+			Input: desktop.Schema(map[string]any{
+				"theme": desktop.Str("an installed cursor theme"),
+				"size":  desktop.Int("pixels, 8 to 256"),
+			}),
+			Run: call(a.cursor),
+		},
+		{
+			Name: "adwaita_icons",
+			Description: "The icon themes installed (name, where, what each inherits, whether it carries cursors) " +
+				"and the one GTK and Qt are set to use.",
+			Input: desktop.Schema(map[string]any{}),
+			Run:   call(a.icons),
+		},
+		{
+			Name: "adwaita_portal_check",
+			Description: "Which xdg-desktop-portal backend answers which interface for this desktop: the backends " +
+				"installed and what they implement, the portals.conf that decides (and which one won), the " +
+				"resulting backend per interface, whether the portal and each backend are running on the " +
+				"account's bus, and the colour scheme the portal answers.",
+			Input: desktop.Schema(map[string]any{}),
+			Run:   call(a.portalCheck),
+		},
+	}
+}

modules/adwaita/cmd/adwaita-tools/tools.go

@@ -0,0 +1,434 @@
+package main
+
+import (
+	"bufio"
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+
+	"adwaita/internal/desktop"
+)
+
+type adwaita struct {
+	d          desktop.Desk
+	home       string
+	iconDirs   []string
+	portalDirs []string
+	uid        int
+}
+
+const iface = "org.gnome.desktop.interface"
+
+// ParseINI reads a key file (GTK's settings.ini, qt6ct.conf, a .portal, index.theme): sections of
+// key=value, `#` and `;` comments.
+func ParseINI(text string) map[string]map[string]string {
+	out := map[string]map[string]string{}
+	section := ""
+	sc := bufio.NewScanner(strings.NewReader(text))
+	for sc.Scan() {
+		l := strings.TrimSpace(sc.Text())
+		if l == "" || strings.HasPrefix(l, "#") || strings.HasPrefix(l, ";") {
+			continue
+		}
+		if strings.HasPrefix(l, "[") && strings.HasSuffix(l, "]") {
+			section = l[1 : len(l)-1]
+			continue
+		}
+		if k, v, ok := strings.Cut(l, "="); ok {
+			if out[section] == nil {
+				out[section] = map[string]string{}
+			}
+			out[section][strings.TrimSpace(k)] = strings.TrimSpace(v)
+		}
+	}
+	return out
+}
+
+func readINI(path string) map[string]map[string]string {
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return nil
+	}
+	return ParseINI(string(b))
+}
+
+// gsetting is one GSettings value, unquoted.
+func (a adwaita) gsetting(ctx context.Context, schema, key string) (string, error) {
+	r := a.d.AsUser(ctx, "gsettings", "get", schema, key)
+	if !r.OK() {
+		return "", r.Err()
+	}
+	return strings.Trim(strings.TrimSpace(r.Stdout), "'"), nil
+}
+
+// themeWords are the words of the user manager's environment the theme is about; nothing else of it
+// is read back.
+var themeWords = []string{"GTK_THEME", "GTK2_RC_FILES", "QT_QPA_PLATFORMTHEME", "QT_STYLE_OVERRIDE", "QT_SELECT",
+	"XCURSOR_THEME", "XCURSOR_SIZE", "XDG_CURRENT_DESKTOP"}
+
+func (a adwaita) userEnvironment(ctx context.Context) map[string]string {
+	r := a.d.AsUser(ctx, "systemctl", "--user", "show-environment")
+	all := desktop.ParseProperties(r.Stdout)
+	out := map[string]string{}
+	for _, w := range themeWords {
+		if v, ok := all[w]; ok {
+			out[w] = v
+		}
+	}
+	return out
+}
+
+var portalScheme = regexp.MustCompile(`^v u (\d)`)
+
+// portalColourScheme asks the portal what it tells applications: 0 no preference, 1 dark, 2 light.
+func (a adwaita) portalColourScheme(ctx context.Context) string {
+	r := a.d.AsUser(ctx, "busctl", "--user", "call", "org.freedesktop.portal.Desktop", "/org/freedesktop/portal/desktop",
+		"org.freedesktop.portal.Settings", "ReadOne", "ss", "org.freedesktop.appearance", "color-scheme")
+	m := portalScheme.FindStringSubmatch(strings.TrimSpace(r.Stdout))
+	if !r.OK() || m == nil {
+		return "unanswered"
+	}
+	return map[string]string{"0": "no-preference", "1": "dark", "2": "light"}[m[1]]
+}
+
+func (a adwaita) appearance(ctx context.Context, args desktop.Args) (any, error) {
+	mode := args.Opt("mode", "")
+	if mode != "" && mode != "dark" && mode != "light" {
+		return nil, fmt.Errorf("mode is dark or light")
+	}
+	if mode != "" {
+		scheme := map[string]string{"dark": "prefer-dark", "light": "prefer-light"}[mode]
+		if r := a.d.AsUser(ctx, "gsettings", "set", iface, "color-scheme", scheme); !r.OK() {
+			return nil, r.Err()
+		}
+	}
+	scheme, err := a.gsetting(ctx, iface, "color-scheme")
+	if err != nil {
+		return nil, fmt.Errorf("GSettings does not answer on the account's bus: %w", err)
+	}
+	gtkTheme, _ := a.gsetting(ctx, iface, "gtk-theme")
+	gtk3 := readINI(filepath.Join(a.home, ".config", "gtk-3.0", "settings.ini"))["Settings"]
+	gtk4 := readINI(filepath.Join(a.home, ".config", "gtk-4.0", "settings.ini"))["Settings"]
+	qt := readINI(filepath.Join(a.home, ".config", "qt6ct", "qt6ct.conf"))["Appearance"]
+	env := a.userEnvironment(ctx)
+	answer := map[string]any{
+		"gsettings":   map[string]string{"color-scheme": scheme, "gtk-theme": gtkTheme},
+		"portal":      a.portalColourScheme(ctx),
+		"gtk3":        map[string]string{"theme": gtk3["gtk-theme-name"], "prefer-dark": gtk3["gtk-application-prefer-dark-theme"]},
+		"gtk4":        map[string]string{"theme": gtk4["gtk-theme-name"], "prefer-dark": gtk4["gtk-application-prefer-dark-theme"]},
+		"qt":          map[string]string{"style": qt["style"], "palette": filepath.Base(qt["color_scheme_path"])},
+		"environment": env,
+	}
+	if mode != "" {
+		var stays []string
+		if strings.HasSuffix(env["GTK_THEME"], ":dark") && mode == "light" {
+			stays = append(stays, "GTK 3 programs: GTK_THEME="+env["GTK_THEME"]+" in the environment pins them dark")
+		}
+		if mode == "light" {
+			stays = append(stays, "the GTK settings files and Qt's palette, which the module declares dark")
+		}
+		answer["switched"] = mode
+		answer["follows_live"] = "programs asking the portal: Electron, Chromium, Firefox, libadwaita and flatpaks"
+		if len(stays) > 0 {
+			answer["stays"] = stays
+		}
+		answer["lasts"] = "until the next login, which sets the module's default (dark) again; a persistent choice waits for settings (hq issue 168)"
+	}
+	return answer, nil
+}
+
+// Theme is one installed icon or cursor theme.
+type Theme struct {
+	Name     string   `json:"name"`
+	Dir      string   `json:"dir"`
+	Title    string   `json:"title,omitempty"`
+	Inherits []string `json:"inherits,omitempty"`
+	Cursors  bool     `json:"cursors"`
+	Icons    bool     `json:"icons"`
+}
+
+// Themes lists the themes in dirs; a name found earlier hides the same name later, as lookups do.
+func Themes(dirs []string) []Theme {
+	seen := map[string]bool{}
+	var out []Theme
+	for _, d := range dirs {
+		entries, _ := os.ReadDir(d)
+		for _, e := range entries {
+			if !e.IsDir() && e.Type()&os.ModeSymlink == 0 || seen[e.Name()] {
+				continue
+			}
+			dir := filepath.Join(d, e.Name())
+			t := Theme{Name: e.Name(), Dir: dir}
+			if info, err := os.Stat(filepath.Join(dir, "cursors")); err == nil && info.IsDir() {
+				t.Cursors = true
+			}
+			if ini := readINI(filepath.Join(dir, "index.theme")); ini != nil {
+				th := ini["Icon Theme"]
+				t.Title = th["Name"]
+				if th["Directories"] != "" {
+					t.Icons = true
+				}
+				for _, i := range strings.Split(th["Inherits"], ",") {
+					if i = strings.TrimSpace(i); i != "" {
+						t.Inherits = append(t.Inherits, i)
+					}
+				}
+			}
+			if !t.Cursors && !t.Icons && t.Title == "" {
+				continue
+			}
+			seen[e.Name()] = true
+			out = append(out, t)
+		}
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
+	return out
+}
+
+var cursorName = regexp.MustCompile(`^[A-Za-z0-9._ -]{1,64}$`)
+
+func (a adwaita) cursor(ctx context.Context, args desktop.Args) (any, error) {
+	theme := args.Opt("theme", "")
+	size, err := args.Whole("size", 0, 8, 256)
+	if err != nil {
+		return nil, err
+	}
+	var cursors []string
+	installed := map[string]bool{}
+	for _, t := range Themes(a.iconDirs) {
+		if t.Cursors {
+			cursors = append(cursors, t.Name)
+			installed[t.Name] = true
+		}
+	}
+	changed := theme != "" || size != 0
+	if theme != "" && (!cursorName.MatchString(theme) || !installed[theme]) {
+		return nil, fmt.Errorf("%q is not an installed cursor theme; installed: %s", theme, strings.Join(cursors, ", "))
+	}
+	var resources []string
+	if theme != "" {
+		if r := a.d.AsUser(ctx, "gsettings", "set", iface, "cursor-theme", theme); !r.OK() {
+			return nil, r.Err()
+		}
+		resources = append(resources, "Xcursor.theme: "+theme)
+	}
+	if size != 0 {
+		if r := a.d.AsUser(ctx, "gsettings", "set", iface, "cursor-size", strconv.Itoa(size)); !r.OK() {
+			return nil, r.Err()
+		}
+		resources = append(resources, "Xcursor.size: "+strconv.Itoa(size))
+	}
+	answer := map[string]any{"installed": cursors}
+	gTheme, _ := a.gsetting(ctx, iface, "cursor-theme")
+	gSize, _ := a.gsetting(ctx, iface, "cursor-size")
+	answer["gsettings"] = map[string]string{"cursor-theme": gTheme, "cursor-size": gSize}
+	env := a.userEnvironment(ctx)
+	answer["environment"] = map[string]string{"XCURSOR_THEME": env["XCURSOR_THEME"], "XCURSOR_SIZE": env["XCURSOR_SIZE"]}
+	if s, err := a.d.Find(); err == nil {
+		senv := s.Env(a.d.Base)
+		if len(resources) > 0 {
+			if r := a.d.Run(ctx, senv, []byte(strings.Join(resources, "\n")+"\n"), "xrdb", "-nocpp", "-merge", "-"); !r.OK() {
+				return nil, r.Err()
+			}
+		}
+		q := a.d.Run(ctx, senv, nil, "xrdb", "-query")
+		x := map[string]string{}
+		for _, l := range strings.Split(q.Stdout, "\n") {
+			if k, v, ok := strings.Cut(l, ":"); ok && strings.HasPrefix(k, "Xcursor.") {
+				x[k] = strings.TrimSpace(v)
+			}
+		}
+		answer["x_resources"] = x
+	} else {
+		answer["x_resources"] = nil
+		if changed {
+			answer["note"] = "no graphical session: GSettings changed, the X resources not"
+		}
+	}
+	if changed {
+		answer["lasts"] = "for windows opened from now on, until the next login"
+	}
+	return answer, nil
+}
+
+func (a adwaita) icons(ctx context.Context, args desktop.Args) (any, error) {
+	var themes []Theme
+	for _, t := range Themes(a.iconDirs) {
+		if t.Icons {
+			themes = append(themes, t)
+		}
+	}
+	gtk3 := readINI(filepath.Join(a.home, ".config", "gtk-3.0", "settings.ini"))["Settings"]
+	qt := readINI(filepath.Join(a.home, ".config", "qt6ct", "qt6ct.conf"))["Appearance"]
+	g, _ := a.gsetting(ctx, iface, "icon-theme")
+	return map[string]any{
+		"installed": themes,
+		"in_use":    map[string]string{"gsettings": g, "gtk": gtk3["gtk-icon-theme-name"], "qt": qt["icon_theme"]},
+	}, nil
+}
+
+// Backend is one installed portal backend.
+type Backend struct {
+	Name       string   `json:"name"`
+	DBusName   string   `json:"dbus_name"`
+	Interfaces []string `json:"interfaces"`
+	UseIn      []string `json:"use_in,omitempty"`
+	Running    bool     `json:"running"`
+}
+
+func splitList(v string) []string {
+	var out []string
+	for _, x := range strings.Split(v, ";") {
+		if x = strings.TrimSpace(x); x != "" {
+			out = append(out, x)
+		}
+	}
+	return out
+}
+
+// Backends reads the installed `.portal` files.
+func Backends(dirs []string) []Backend {
+	var out []Backend
+	for _, d := range dirs {
+		files, _ := filepath.Glob(filepath.Join(d, "*.portal"))
+		sort.Strings(files)
+		for _, f := range files {
+			p := readINI(f)["portal"]
+			out = append(out, Backend{Name: strings.TrimSuffix(filepath.Base(f), ".portal"), DBusName: p["DBusName"],
+				Interfaces: splitList(p["Interfaces"]), UseIn: splitList(p["UseIn"])})
+		}
+	}
+	return out
+}
+
+// PortalConfigs are the files xdg-desktop-portal looks for, in its order (portals.conf(5)): for each
+// directory, `<desktop>-portals.conf` for each of the desktops named, then `portals.conf`. The first
+// that exists decides everything.
+func PortalConfigs(home string, desktops []string) []string {
+	dirs := []string{
+		filepath.Join(home, ".config", "xdg-desktop-portal"), "/etc/xdg/xdg-desktop-portal", "/etc/xdg-desktop-portal",
+		filepath.Join(home, ".local", "share", "xdg-desktop-portal"), "/usr/local/share/xdg-desktop-portal", "/usr/share/xdg-desktop-portal",
+	}
+	var out []string
+	for _, d := range dirs {
+		for _, desk := range desktops {
+			out = append(out, filepath.Join(d, strings.ToLower(desk)+"-portals.conf"))
+		}
+		out = append(out, filepath.Join(d, "portals.conf"))
+	}
+	return out
+}
+
+// Resolve says which backend answers each interface the backends implement, given the deciding
+// file's [preferred] section: an interface's own key first, else `default`; each a list of backend
+// names, the first one that implements the interface wins; `none` answers nothing, `*` any.
+// With no file, a backend whose UseIn names the desktop answers.
+func Resolve(backends []Backend, preferred map[string]string, desktops []string) map[string]string {
+	out := map[string]string{}
+	implements := func(b Backend, i string) bool {
+		for _, x := range b.Interfaces {
+			if x == i {
+				return true
+			}
+		}
+		return false
+	}
+	var all []string
+	seen := map[string]bool{}
+	for _, b := range backends {
+		for _, i := range b.Interfaces {
+			if !seen[i] {
+				seen[i] = true
+				all = append(all, i)
+			}
+		}
+	}
+	sort.Strings(all)
+	for _, i := range all {
+		var want []string
+		if preferred != nil {
+			if v, ok := preferred[i]; ok {
+				want = splitList(v)
+			} else {
+				want = splitList(preferred["default"])
+			}
+		} else {
+			for _, b := range backends {
+				for _, u := range b.UseIn {
+					for _, d := range desktops {
+						if strings.EqualFold(u, d) {
+							want = append(want, b.Name)
+						}
+					}
+				}
+			}
+		}
+		out[i] = "(none)"
+	pick:
+		for _, w := range want {
+			if w == "none" {
+				break
+			}
+			for _, b := range backends {
+				if (w == "*" || w == b.Name) && implements(b, i) {
+					out[i] = b.Name
+					break pick
+				}
+			}
+		}
+	}
+	return out
+}
+
+func (a adwaita) portalCheck(ctx context.Context, args desktop.Args) (any, error) {
+	env := a.userEnvironment(ctx)
+	desktops := splitColon(env["XDG_CURRENT_DESKTOP"])
+	backends := Backends(a.portalDirs)
+	names := map[string]bool{}
+	if r := a.d.AsUser(ctx, "busctl", "--user", "list", "--no-legend", "--no-pager"); r.OK() {
+		for _, l := range strings.Split(r.Stdout, "\n") {
+			if f := strings.Fields(l); len(f) > 1 && f[1] != "-" {
+				names[f[0]] = true
+			}
+		}
+	}
+	for i := range backends {
+		backends[i].Running = names[backends[i].DBusName]
+	}
+	var decided string
+	var preferred map[string]string
+	looked := PortalConfigs(a.home, desktops)
+	for _, f := range looked {
+		if ini := readINI(f); ini != nil {
+			decided, preferred = f, ini["preferred"]
+			if preferred == nil {
+				preferred = map[string]string{}
+			}
+			break
+		}
+	}
+	return map[string]any{
+		"desktop":       env["XDG_CURRENT_DESKTOP"],
+		"portal":        map[string]bool{"running": names["org.freedesktop.portal.Desktop"]},
+		"backends":      backends,
+		"decided_by":    decided,
+		"preferred":     preferred,
+		"answers":       Resolve(backends, preferred, desktops),
+		"colour_scheme": a.portalColourScheme(ctx),
+	}, nil
+}
+
+func splitColon(v string) []string {
+	var out []string
+	for _, x := range strings.Split(v, ":") {
+		if x = strings.TrimSpace(x); x != "" {
+			out = append(out, x)
+		}
+	}
+	return out
+}

modules/adwaita/config/cursor-index.theme

@@ -0,0 +1,5 @@
+# Written by the mesh (module adwaita, novox/hq ADR 0208): the default cursor theme, for programs that
+# read neither XCURSOR_THEME nor the X resources.
+[Icon Theme]
+Name=Default
+Inherits=Adwaita

modules/adwaita/config/gtk-settings.ini

@@ -0,0 +1,9 @@
+# Written by the mesh (module adwaita, novox/hq ADR 0208), for GTK 3 and GTK 4 alike. Replaced at
+# every push; adwaita_appearance switches dark and light for the running session.
+[Settings]
+gtk-theme-name=Adwaita
+gtk-icon-theme-name=Adwaita
+gtk-cursor-theme-name=Adwaita
+gtk-cursor-theme-size=24
+gtk-font-name=Inter 11
+gtk-application-prefer-dark-theme=1

modules/adwaita/config/portals.conf

@@ -0,0 +1,11 @@
+# Written by the mesh (module adwaita, novox/hq ADR 0208). Replaced at every push.
+#
+# Which portal backend answers each interface. i3 is not a desktop xdg-desktop-portal knows, so with
+# no preference it uses whichever backend happens to be installed: fine while gtk is the only one,
+# wrong the day another arrives as somebody else's dependency. Named instead. gtk also serves
+# org.freedesktop.appearance (dark or light) from GSettings, which the session's start sets.
+[preferred]
+default=gtk
+# Secrets for sandboxed programs come from the keyring's backend. Without this line no backend answers
+# the interface: gtk does not implement it, and gnome-keyring's names only GNOME as its desktop.
+org.freedesktop.impl.portal.Secret=gnome-keyring

modules/adwaita/config/qt6ct.conf

@@ -0,0 +1,29 @@
+[Appearance]
+color_scheme_path=/usr/share/qt6ct/colors/darker.conf
+custom_palette=true
+icon_theme=Adwaita
+standard_dialogs=default
+style=Fusion
+
+[Fonts]
+fixed="JetBrainsMono Nerd Font,11,-1,5,50,0,0,0,0,0"
+general="Inter,11,-1,5,50,0,0,0,0,0"
+
+[Interface]
+activate_item_on_single_click=1
+buttonbox_layout=0
+cursor_flash_time=1000
+dialog_buttons_have_icons=1
+double_click_interval=400
+gui_effects=@Invalid()
+keyboard_scheme=2
+menus_have_icons=true
+show_shortcuts_in_context_menus=true
+stylesheets=@Invalid()
+toolbutton_style=4
+underline_shortcut=1
+wheel_scroll_lines=3
+
+[Troubleshooting]
+force_raster_widgets=1
+ignored_applications=@Invalid()

modules/adwaita/go.mod

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

modules/adwaita/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/adwaita/internal/desktop/args.go

@@ -0,0 +1,160 @@
+package desktop
+
+import (
+	"fmt"
+	"math"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// Args reads a tool's arguments as JSON decoded them: strings, float64 numbers, booleans.
+type Args map[string]any
+
+// Text is a required string, trimmed.
+func (a Args) Text(name string) (string, error) {
+	v, ok := a[name].(string)
+	if !ok || strings.TrimSpace(v) == "" {
+		return "", fmt.Errorf("%s is required, as text", name)
+	}
+	return strings.TrimSpace(v), nil
+}
+
+// Opt is an optional string, trimmed, or def.
+func (a Args) Opt(name, def string) string {
+	if v, ok := a[name].(string); ok && strings.TrimSpace(v) != "" {
+		return strings.TrimSpace(v)
+	}
+	return def
+}
+
+// Has is whether the caller gave the argument at all.
+func (a Args) Has(name string) bool {
+	v, ok := a[name]
+	return ok && v != nil
+}
+
+// Bool is an optional boolean: its value, and whether it was given.
+func (a Args) Bool(name string) (bool, bool, error) {
+	v, ok := a[name]
+	if !ok || v == nil {
+		return false, false, nil
+	}
+	b, isBool := v.(bool)
+	if !isBool {
+		return false, false, fmt.Errorf("%s is true or false", name)
+	}
+	return b, true, nil
+}
+
+// Number is an optional number: its value, and whether it was given.
+func (a Args) Number(name string) (float64, bool, error) {
+	v, ok := a[name]
+	if !ok || v == nil {
+		return 0, false, nil
+	}
+	f, isNum := v.(float64)
+	if !isNum || math.IsNaN(f) || math.IsInf(f, 0) {
+		return 0, false, fmt.Errorf("%s is a number", name)
+	}
+	return f, true, nil
+}
+
+// Whole is an optional whole number within [lo, hi], or def.
+func (a Args) Whole(name string, def, lo, hi int) (int, error) {
+	f, given, err := a.Number(name)
+	if err != nil {
+		return 0, err
+	}
+	if !given {
+		return def, nil
+	}
+	if f != math.Trunc(f) || f < float64(lo) || f > float64(hi) {
+		return 0, fmt.Errorf("%s is a whole number from %d to %d", name, lo, hi)
+	}
+	return int(f), nil
+}
+
+// OneOf is an optional string that must be one of choices, or def.
+func (a Args) OneOf(name, def string, choices ...string) (string, error) {
+	v := a.Opt(name, def)
+	for _, c := range choices {
+		if v == c {
+			return v, nil
+		}
+	}
+	return "", fmt.Errorf("%s is one of %s", name, strings.Join(choices, ", "))
+}
+
+// Strings is an optional list of strings.
+func (a Args) Strings(name string) ([]string, error) {
+	v, ok := a[name]
+	if !ok || v == nil {
+		return nil, nil
+	}
+	list, isList := v.([]any)
+	if !isList {
+		return nil, fmt.Errorf("%s is a list of text", name)
+	}
+	out := make([]string, 0, len(list))
+	for _, x := range list {
+		s, isText := x.(string)
+		if !isText {
+			return nil, fmt.Errorf("%s is a list of text", name)
+		}
+		out = append(out, s)
+	}
+	return out, nil
+}
+
+// Home is the operator account's home: the runtime's word for it, else this process's.
+func Home() string {
+	if h := os.Getenv("MESH_OPERATOR_HOME"); h != "" {
+		return h
+	}
+	if h, err := os.UserHomeDir(); err == nil {
+		return h
+	}
+	return "/"
+}
+
+// InHome resolves a path the caller gave: `~/x` and a relative path are under the home. A path
+// that leaves the home through `..` is refused, so a tool that writes never writes outside it.
+func InHome(path string) (string, error) {
+	home := Home()
+	switch {
+	case path == "~":
+		path = home
+	case strings.HasPrefix(path, "~/"):
+		path = filepath.Join(home, path[2:])
+	case !filepath.IsAbs(path):
+		path = filepath.Join(home, path)
+	}
+	path = filepath.Clean(path)
+	if path != home && !strings.HasPrefix(path, home+string(filepath.Separator)) {
+		return "", fmt.Errorf("%s is outside the account's home", path)
+	}
+	return path, nil
+}
+
+// Schema builds a tool's input schema from property descriptions; required names those that must
+// be given. A property is a string unless its description object says otherwise.
+func Schema(props map[string]any, required ...string) map[string]any {
+	s := map[string]any{"type": "object", "properties": props}
+	if len(required) > 0 {
+		s["required"] = required
+	}
+	return s
+}
+
+// Str, Num, Flag, List and Enum describe one property.
+func Str(desc string) map[string]any  { return map[string]any{"type": "string", "description": desc} }
+func Num(desc string) map[string]any  { return map[string]any{"type": "number", "description": desc} }
+func Int(desc string) map[string]any  { return map[string]any{"type": "integer", "description": desc} }
+func Flag(desc string) map[string]any { return map[string]any{"type": "boolean", "description": desc} }
+func List(desc string) map[string]any {
+	return map[string]any{"type": "array", "items": map[string]any{"type": "string"}, "description": desc}
+}
+func Enum(desc string, values ...string) map[string]any {
+	return map[string]any{"type": "string", "enum": values, "description": desc}
+}

modules/adwaita/internal/desktop/copies_test.go

@@ -0,0 +1,42 @@
+package desktop
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// The desktop modules that carry this package. Each builds alone, so each has its own copy; this
+// test, itself one of the copied files, holds them to one text wherever the siblings are present.
+var carriers = []string{"xorg", "lemurs", "i3", "xterm", "adwaita"}
+
+func TestEveryDesktopModuleCarriesTheSameCopy(t *testing.T) {
+	mine, err := filepath.Glob("*.go")
+	if err != nil || len(mine) == 0 {
+		t.Fatal("no files of this package found", err)
+	}
+	compared := 0
+	for _, module := range carriers {
+		dir := filepath.Join("..", "..", "..", module, "internal", "desktop")
+		if _, err := os.Stat(dir); err != nil {
+			continue
+		}
+		theirs, _ := filepath.Glob(filepath.Join(dir, "*.go"))
+		if len(theirs) != len(mine) {
+			t.Errorf("%s carries %d files of this package, this copy %d", module, len(theirs), len(mine))
+			continue
+		}
+		for _, f := range mine {
+			a, _ := os.ReadFile(f)
+			b, err := os.ReadFile(filepath.Join(dir, f))
+			if err != nil || !bytes.Equal(a, b) {
+				t.Errorf("%s's copy of %s differs from this one: change every copy together", module, f)
+			}
+		}
+		compared++
+	}
+	if compared == 0 {
+		t.Log("no sibling copies beside this module")
+	}
+}

modules/adwaita/internal/desktop/run.go

@@ -0,0 +1,232 @@
+package desktop
+
+import (
+	"bytes"
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"strings"
+	"syscall"
+	"time"
+)
+
+// Bounds on a command a tool runs: well below the runtime's 30 s call limit, and an answer that
+// fits in a tool's reply.
+const (
+	DefaultTimeout = 10 * time.Second
+	MostOutput     = 256 << 10
+)
+
+// Result is what one command did.
+type Result struct {
+	Command   []string `json:"command"`
+	Code      int      `json:"exit_code"`
+	Stdout    string   `json:"stdout,omitempty"`
+	Stderr    string   `json:"stderr,omitempty"`
+	Truncated bool     `json:"truncated,omitempty"`
+	TimedOut  bool     `json:"timed_out,omitempty"`
+}
+
+// OK is whether the command ran and exited 0.
+func (r Result) OK() bool { return r.Code == 0 && !r.TimedOut }
+
+// Err is the command's failure as an error naming it and what it said, or nil.
+func (r Result) Err() error {
+	if r.OK() {
+		return nil
+	}
+	said := strings.TrimSpace(r.Stderr)
+	if said == "" {
+		said = strings.TrimSpace(r.Stdout)
+	}
+	if r.TimedOut {
+		return fmt.Errorf("%s did not finish in time", strings.Join(r.Command, " "))
+	}
+	return fmt.Errorf("%s exited %d: %s", strings.Join(r.Command, " "), r.Code, said)
+}
+
+// Runner runs a command with an environment and answers what it did. Tools take one, so their
+// tests replace the machine with a table of answers.
+type Runner func(ctx context.Context, env []string, stdin []byte, name string, args ...string) Result
+
+// Exec is the machine's Runner: the command in its own process group, ended with everything it
+// started at the deadline, each stream cut at MostOutput.
+func Exec(ctx context.Context, env []string, stdin []byte, name string, args ...string) Result {
+	if _, ok := ctx.Deadline(); !ok {
+		var cancel context.CancelFunc
+		ctx, cancel = context.WithTimeout(ctx, DefaultTimeout)
+		defer cancel()
+	}
+	res := Result{Command: append([]string{name}, args...)}
+	cmd := exec.Command(name, args...)
+	cmd.Env = env
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+	if stdin != nil {
+		cmd.Stdin = bytes.NewReader(stdin)
+	}
+	out, errb := &capped{}, &capped{}
+	cmd.Stdout, cmd.Stderr = out, errb
+	if err := cmd.Start(); err != nil {
+		res.Code = 127
+		res.Stderr = err.Error()
+		return res
+	}
+	done := make(chan error, 1)
+	go func() { done <- cmd.Wait() }()
+	var err error
+	select {
+	case err = <-done:
+	case <-ctx.Done():
+		_ = syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)
+		err = <-done
+		res.TimedOut = true
+	}
+	res.Stdout, res.Stderr = out.String(), errb.String()
+	res.Truncated = out.cut || errb.cut
+	var exit *exec.ExitError
+	switch {
+	case err == nil:
+	case errors.As(err, &exit):
+		res.Code = exit.ExitCode()
+		if res.Code < 0 {
+			res.Code = 128
+		}
+	default:
+		res.Code = 1
+		if res.Stderr == "" {
+			res.Stderr = err.Error()
+		}
+	}
+	return res
+}
+
+// capped keeps the first MostOutput bytes written to it. Its buffer is a field, not embedded: an
+// embedded bytes.Buffer brings ReadFrom along, and io.Copy would use it and never call Write.
+type capped struct {
+	buf bytes.Buffer
+	cut bool
+}
+
+func (c *capped) Write(p []byte) (int, error) {
+	if room := MostOutput - c.buf.Len(); room < len(p) {
+		if room > 0 {
+			c.buf.Write(p[:room])
+		}
+		c.cut = true
+		return len(p), nil
+	}
+	return c.buf.Write(p)
+}
+
+func (c *capped) String() string { return c.buf.String() }
+
+// Desk is what a desktop tool needs: how to find the session, and how to run a command.
+type Desk struct {
+	Find func() (*Session, error)
+	Run  Runner
+	// Base is the environment a command starts from, before the session's words.
+	Base []string
+}
+
+// Machine is the real Desk, preferring the named processes as the session's.
+func Machine(prefer ...string) Desk {
+	return Desk{
+		Find: func() (*Session, error) { return Find(prefer...) },
+		Run:  Exec,
+		Base: os.Environ(),
+	}
+}
+
+// InSession runs a command in the operator's session, or answers NoSession.
+func (d Desk) InSession(ctx context.Context, name string, args ...string) (Result, *Session, error) {
+	s, err := d.Find()
+	if err != nil {
+		return Result{}, nil, err
+	}
+	return d.Run(ctx, s.Env(d.Base), nil, name, args...), s, nil
+}
+
+// InSessionWith is InSession with standard input.
+func (d Desk) InSessionWith(ctx context.Context, stdin []byte, name string, args ...string) (Result, *Session, error) {
+	s, err := d.Find()
+	if err != nil {
+		return Result{}, nil, err
+	}
+	return d.Run(ctx, s.Env(d.Base), stdin, name, args...), s, nil
+}
+
+// Plain runs a command with the base environment: for what needs no session.
+func (d Desk) Plain(ctx context.Context, name string, args ...string) Result {
+	return d.Run(ctx, d.Base, nil, name, args...)
+}
+
+// AsUser runs a command with the account's own runtime directory and bus, and no display.
+func (d Desk) AsUser(ctx context.Context, name string, args ...string) Result {
+	return d.Run(ctx, UserEnv(d.Base, os.Getuid()), nil, name, args...)
+}
+
+// Launched is how a program was started in the session.
+type Launched struct {
+	Unit string `json:"unit,omitempty"`
+	PID  int    `json:"pid,omitempty"`
+	How  string `json:"how"`
+}
+
+// Launch starts a program in the operator's session that outlives the call and the runtime.
+//
+// **Not as a child of this process.** The runtime is a system service; everything it starts is in
+// its control group, and the service manager ends that group whenever the runtime restarts — which
+// is every push that changes it. So the program is handed to the account's own service manager as a
+// transient unit (`systemd-run --user`), with the session's words set on it, and lives as long as the
+// operator's user manager does. Without a user manager it is started detached as a last resort, and
+// the answer says it will end with the runtime.
+func (d Desk) Launch(ctx context.Context, s *Session, name string, argv ...string) (Launched, error) {
+	if len(argv) == 0 {
+		return Launched{}, errors.New("nothing to launch")
+	}
+	env := s.Env(d.Base)
+	unit := "mesh-" + name + "-" + token()
+	args := []string{"--user", "--collect", "--quiet", "--unit=" + unit}
+	for _, w := range []string{"DISPLAY", "WAYLAND_DISPLAY", "XAUTHORITY", "XDG_SESSION_TYPE", "XDG_CURRENT_DESKTOP", "XDG_SESSION_DESKTOP", "I3SOCK", "SWAYSOCK"} {
+		if v := lookup(env, w); v != "" {
+			args = append(args, "--setenv="+w+"="+v)
+		}
+	}
+	args = append(args, "--")
+	args = append(args, argv...)
+	res := d.Run(ctx, env, nil, "systemd-run", args...)
+	if res.OK() {
+		return Launched{Unit: unit, How: "a transient unit of the account's service manager; ends when it exits or when the operator logs out"}, nil
+	}
+	if s.Bus != "" {
+		return Launched{}, res.Err()
+	}
+	cmd := exec.Command(argv[0], argv[1:]...)
+	cmd.Env = env
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setsid: true}
+	if err := cmd.Start(); err != nil {
+		return Launched{}, err
+	}
+	pid := cmd.Process.Pid
+	go func() { _ = cmd.Wait() }()
+	return Launched{PID: pid, How: "detached from the runtime with no user manager to hand it to; it ends when the runtime restarts"}, nil
+}
+
+func lookup(env []string, name string) string {
+	for i := len(env) - 1; i >= 0; i-- {
+		if k, v, ok := strings.Cut(env[i], "="); ok && k == name {
+			return v
+		}
+	}
+	return ""
+}
+
+func token() string {
+	b := make([]byte, 4)
+	_, _ = rand.Read(b)
+	return hex.EncodeToString(b)
+}

modules/adwaita/internal/desktop/session.go

@@ -0,0 +1,445 @@
+// Package desktop is how a desktop module's tools act in the operator's graphical session
+// (novox/hq ADR 0208, research 026/05).
+//
+// **One question, answered once for every desktop tool.** A tool runs inside the node's runtime: a
+// process of node-tools.service, started by the system's service manager as the operator account,
+// with no session around it — no DISPLAY, no XAUTHORITY, no session bus. The session it must act in
+// was started elsewhere, by the login manager, and the only place its values are written down is
+// the environment of the processes it started. So this package finds the session the way a person
+// would: it looks at the operator account's own processes, takes the one that is plainly the
+// session's (the window manager, or the oldest process carrying a display), confirms with logind
+// that its session is a live local one, and checks that the display's socket is really there.
+//
+// **Only the session's own words are read.** A session's processes also carry whatever its start
+// script exported — on the workstations that was a file of secrets — so the environment is filtered
+// to a fixed list of names while it is read, and nothing else ever leaves /proc.
+//
+// The D-Bus address handed on is the user manager's socket, `unix:path=$XDG_RUNTIME_DIR/bus`,
+// whenever it exists, because that is where the portal, the notifier and every user service
+// listen. A session started on a private bus (a stale session, measured on one workstation) is
+// reported as `session_bus` beside it, so the difference is visible rather than guessed at.
+//
+// The same copy of this package is vendored into every desktop module (xorg, lemurs, i3, xterm,
+// adwaita); the catalogue builds each module alone, so it cannot be imported across them. Change
+// every copy together — the modules' tests compare them.
+package desktop
+
+import (
+	"bufio"
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"os/user"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"syscall"
+	"time"
+)
+
+// SessionWords are the only environment words read from a session's process: the ones that say
+// where the session is. Everything else in that environment is the operator's, and is never read.
+var SessionWords = []string{
+	"DISPLAY", "WAYLAND_DISPLAY", "XAUTHORITY",
+	"XDG_SESSION_ID", "XDG_SESSION_TYPE", "XDG_SESSION_DESKTOP", "XDG_CURRENT_DESKTOP",
+	"XDG_RUNTIME_DIR", "DBUS_SESSION_BUS_ADDRESS", "XDG_SEAT", "XDG_VTNR",
+	"I3SOCK", "SWAYSOCK",
+}
+
+// Session is the operator's running graphical session, as a tool needs it.
+type Session struct {
+	UID            int    `json:"uid"`
+	ID             string `json:"session_id,omitempty"`
+	Type           string `json:"type"`
+	Display        string `json:"display,omitempty"`
+	WaylandDisplay string `json:"wayland_display,omitempty"`
+	XAuthority     string `json:"xauthority,omitempty"`
+	RuntimeDir     string `json:"runtime_dir"`
+	Bus            string `json:"bus,omitempty"`
+	SessionBus     string `json:"session_bus,omitempty"`
+	Desktop        string `json:"desktop,omitempty"`
+	// FoundIn is the process whose environment named the session.
+	FoundIn Process `json:"found_in"`
+	// Active is logind's word on the session, when logind answered.
+	Active *bool `json:"active,omitempty"`
+
+	words map[string]string
+}
+
+// Process is one process the search looked at.
+type Process struct {
+	PID     int    `json:"pid"`
+	Command string `json:"command"`
+	start   uint64
+}
+
+// NoSession is the answer when there is no graphical session to act in. Its text is JSON, so a tool
+// that returns it as its error still answers structured data.
+type NoSession struct {
+	Reason string   `json:"reason"`
+	Looked []string `json:"looked"`
+}
+
+func (e *NoSession) Error() string {
+	b, _ := json.Marshal(map[string]any{"error": "no-graphical-session", "reason": e.Reason, "looked": e.Looked})
+	return string(b)
+}
+
+// IsNoSession is whether err says there is no session.
+func IsNoSession(err error) bool {
+	var n *NoSession
+	return errors.As(err, &n)
+}
+
+// Finder holds where the search looks, so a test can point it at a tree of its own.
+type Finder struct {
+	Proc        string // the process table: /proc
+	X11Sockets  string // where X servers listen: /tmp/.X11-unix
+	RuntimeBase string // the parent of every XDG_RUNTIME_DIR: /run/user
+	UID         int    // whose session
+	// Prefer names the processes that are the session's own, best first: the session's holder.
+	Prefer []string
+	// Logind answers `loginctl show-session` for one id; nil skips the check.
+	Logind func(id string) (map[string]string, error)
+}
+
+// DefaultFinder is the machine's: the account this process runs as, or — when it runs as root — the
+// operator account the runtime names (MESH_OPERATOR_ACCOUNT).
+func DefaultFinder(prefer ...string) Finder {
+	uid := os.Getuid()
+	if uid == 0 {
+		if name := os.Getenv("MESH_OPERATOR_ACCOUNT"); name != "" {
+			if u, err := user.Lookup(name); err == nil {
+				if n, err := strconv.Atoi(u.Uid); err == nil {
+					uid = n
+				}
+			}
+		}
+	}
+	return Finder{
+		Proc: "/proc", X11Sockets: "/tmp/.X11-unix", RuntimeBase: "/run/user",
+		UID: uid, Prefer: prefer, Logind: loginctl,
+	}
+}
+
+// Find is the operator's session on this machine, preferring a process named in prefer.
+func Find(prefer ...string) (*Session, error) {
+	return DefaultFinder(prefer...).Find()
+}
+
+type candidate struct {
+	proc   Process
+	words  map[string]string
+	rank   int
+	logind map[string]string
+}
+
+// Find looks for the session.
+func (f Finder) Find() (*Session, error) {
+	entries, err := os.ReadDir(f.Proc)
+	if err != nil {
+		return nil, &NoSession{Reason: "the process table cannot be read: " + err.Error(), Looked: []string{f.Proc}}
+	}
+	looked := []string{fmt.Sprintf("the processes of uid %d in %s", f.UID, f.Proc)}
+	var found []candidate
+	stale := 0
+	for _, e := range entries {
+		pid, err := strconv.Atoi(e.Name())
+		if err != nil {
+			continue
+		}
+		dir := filepath.Join(f.Proc, e.Name())
+		info, err := os.Stat(dir)
+		if err != nil {
+			continue
+		}
+		if st, ok := info.Sys().(*syscall.Stat_t); !ok || int(st.Uid) != f.UID {
+			continue
+		}
+		words := readWords(filepath.Join(dir, "environ"))
+		if words["DISPLAY"] == "" && words["WAYLAND_DISPLAY"] == "" {
+			continue
+		}
+		if !f.reachable(words) {
+			stale++
+			continue
+		}
+		found = append(found, candidate{proc: Process{PID: pid, Command: comm(dir), start: startTime(dir)}, words: words})
+	}
+	if len(found) == 0 {
+		reason := fmt.Sprintf("no process of uid %d carries a display", f.UID)
+		if stale > 0 {
+			reason = fmt.Sprintf("%d process(es) of uid %d name a display whose socket is gone: the session they belonged to has ended", stale, f.UID)
+		}
+		return nil, &NoSession{Reason: reason, Looked: append(looked, f.X11Sockets, f.RuntimeBase)}
+	}
+
+	// logind's word on each session the candidates name, asked once per session.
+	asked := map[string]map[string]string{}
+	for i := range found {
+		id := found[i].words["XDG_SESSION_ID"]
+		if f.Logind == nil || id == "" {
+			found[i].rank = 1
+			continue
+		}
+		props, done := asked[id]
+		if !done {
+			props, _ = f.Logind(id)
+			asked[id] = props
+		}
+		found[i].logind = props
+		switch {
+		case props == nil:
+			found[i].rank = 1
+		case props["Remote"] == "yes":
+			found[i].rank = 3
+		case props["Active"] == "yes" && props["State"] != "closing":
+			found[i].rank = 0
+		case props["State"] == "closing":
+			found[i].rank = 3
+		default:
+			found[i].rank = 2
+		}
+	}
+	if f.Logind != nil {
+		looked = append(looked, "logind's sessions")
+	}
+	preferred := func(c candidate) int {
+		for i, p := range f.Prefer {
+			if c.proc.Command == p {
+				return i
+			}
+		}
+		return len(f.Prefer)
+	}
+	sort.SliceStable(found, func(i, j int) bool {
+		a, b := found[i], found[j]
+		if a.rank != b.rank {
+			return a.rank < b.rank
+		}
+		if pa, pb := preferred(a), preferred(b); pa != pb {
+			return pa < pb
+		}
+		if a.proc.start != b.proc.start {
+			return a.proc.start < b.proc.start
+		}
+		return a.proc.PID < b.proc.PID
+	})
+	best := found[0]
+	if best.rank == 3 {
+		return nil, &NoSession{Reason: "the only sessions found are remote or closing", Looked: looked}
+	}
+	return f.session(best), nil
+}
+
+func (f Finder) session(c candidate) *Session {
+	w := c.words
+	s := &Session{
+		UID: f.UID, ID: w["XDG_SESSION_ID"], Display: w["DISPLAY"], WaylandDisplay: w["WAYLAND_DISPLAY"],
+		XAuthority: w["XAUTHORITY"], RuntimeDir: w["XDG_RUNTIME_DIR"], FoundIn: c.proc, words: w,
+	}
+	s.Desktop = w["XDG_CURRENT_DESKTOP"]
+	if s.Desktop == "" {
+		s.Desktop = w["XDG_SESSION_DESKTOP"]
+	}
+	switch {
+	case w["XDG_SESSION_TYPE"] != "":
+		s.Type = w["XDG_SESSION_TYPE"]
+	case s.WaylandDisplay != "":
+		s.Type = "wayland"
+	default:
+		s.Type = "x11"
+	}
+	if s.RuntimeDir == "" {
+		s.RuntimeDir = filepath.Join(f.RuntimeBase, strconv.Itoa(f.UID))
+	}
+	if isSocket(filepath.Join(s.RuntimeDir, "bus")) {
+		s.Bus = "unix:path=" + filepath.Join(s.RuntimeDir, "bus")
+	}
+	if own := w["DBUS_SESSION_BUS_ADDRESS"]; own != "" && own != s.Bus {
+		s.SessionBus = own
+	}
+	if c.logind != nil {
+		active := c.logind["Active"] == "yes"
+		s.Active = &active
+	}
+	return s
+}
+
+// reachable is whether the display a process names is still served: the X server's socket, or the
+// Wayland compositor's. A process outliving its session still carries the session's words.
+func (f Finder) reachable(w map[string]string) bool {
+	if d := w["WAYLAND_DISPLAY"]; d != "" {
+		path := d
+		if !filepath.IsAbs(d) {
+			dir := w["XDG_RUNTIME_DIR"]
+			if dir == "" {
+				dir = filepath.Join(f.RuntimeBase, strconv.Itoa(f.UID))
+			}
+			path = filepath.Join(dir, d)
+		}
+		if isSocket(path) {
+			return true
+		}
+	}
+	n, ok := DisplayNumber(w["DISPLAY"])
+	return ok && isSocket(filepath.Join(f.X11Sockets, "X"+strconv.Itoa(n)))
+}
+
+// DisplayNumber is the server number of a local X display (":1", ":1.0", "unix:1"); a display on
+// another host — an ssh session's forwarded one — is not the local session and answers false.
+func DisplayNumber(display string) (int, bool) {
+	host, rest, ok := strings.Cut(display, ":")
+	if !ok || (host != "" && host != "unix") {
+		return 0, false
+	}
+	num, _, _ := strings.Cut(rest, ".")
+	n, err := strconv.Atoi(num)
+	if err != nil || n < 0 {
+		return 0, false
+	}
+	return n, true
+}
+
+// Word is one of the session's words as its process had it ("" when it had none).
+func (s *Session) Word(name string) string { return s.words[name] }
+
+// Env is base with the session's words in place of whatever base said for them.
+func (s *Session) Env(base []string) []string {
+	drop := map[string]bool{}
+	for _, w := range SessionWords {
+		drop[w] = true
+	}
+	out := make([]string, 0, len(base)+8)
+	for _, kv := range base {
+		k, _, _ := strings.Cut(kv, "=")
+		if !drop[k] {
+			out = append(out, kv)
+		}
+	}
+	bus := s.Bus
+	if bus == "" {
+		bus = s.SessionBus
+	}
+	for _, kv := range [][2]string{
+		{"DISPLAY", s.Display}, {"WAYLAND_DISPLAY", s.WaylandDisplay}, {"XAUTHORITY", s.XAuthority},
+		{"XDG_RUNTIME_DIR", s.RuntimeDir}, {"DBUS_SESSION_BUS_ADDRESS", bus},
+		{"XDG_SESSION_TYPE", s.Type}, {"XDG_SESSION_ID", s.ID},
+		{"XDG_CURRENT_DESKTOP", s.words["XDG_CURRENT_DESKTOP"]},
+		{"XDG_SESSION_DESKTOP", s.words["XDG_SESSION_DESKTOP"]},
+		{"I3SOCK", s.words["I3SOCK"]}, {"SWAYSOCK", s.words["SWAYSOCK"]},
+	} {
+		if kv[1] != "" {
+			out = append(out, kv[0]+"="+kv[1])
+		}
+	}
+	return out
+}
+
+// UserEnv is base with the account's own runtime directory and bus, for a tool that talks to the
+// user manager or the session bus and needs no display — it works with no session at all.
+func UserEnv(base []string, uid int) []string {
+	dir := filepath.Join("/run/user", strconv.Itoa(uid))
+	out := make([]string, 0, len(base)+2)
+	for _, kv := range base {
+		k, _, _ := strings.Cut(kv, "=")
+		if k != "XDG_RUNTIME_DIR" && k != "DBUS_SESSION_BUS_ADDRESS" {
+			out = append(out, kv)
+		}
+	}
+	return append(out, "XDG_RUNTIME_DIR="+dir, "DBUS_SESSION_BUS_ADDRESS=unix:path="+filepath.Join(dir, "bus"))
+}
+
+// readWords reads a process's environment and keeps only SessionWords.
+func readWords(path string) map[string]string {
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return nil
+	}
+	keep := map[string]bool{}
+	for _, w := range SessionWords {
+		keep[w] = true
+	}
+	out := map[string]string{}
+	for _, kv := range bytes.Split(raw, []byte{0}) {
+		k, v, ok := bytes.Cut(kv, []byte{'='})
+		if ok && keep[string(k)] {
+			out[string(k)] = string(v)
+		}
+	}
+	return out
+}
+
+func comm(dir string) string {
+	b, err := os.ReadFile(filepath.Join(dir, "comm"))
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(string(b))
+}
+
+// startTime is field 22 of /proc/<pid>/stat: when the process started, in clock ticks since boot.
+// Read after the command's closing parenthesis, because the command may hold spaces.
+func startTime(dir string) uint64 {
+	b, err := os.ReadFile(filepath.Join(dir, "stat"))
+	if err != nil {
+		return ^uint64(0)
+	}
+	i := bytes.LastIndexByte(b, ')')
+	if i < 0 {
+		return ^uint64(0)
+	}
+	fields := strings.Fields(string(b[i+1:]))
+	// fields[0] is the state, field 3 of the line; start time is field 22.
+	if len(fields) < 20 {
+		return ^uint64(0)
+	}
+	n, err := strconv.ParseUint(fields[19], 10, 64)
+	if err != nil {
+		return ^uint64(0)
+	}
+	return n
+}
+
+func isSocket(path string) bool {
+	info, err := os.Stat(path)
+	return err == nil && info.Mode()&os.ModeSocket != 0
+}
+
+// loginctl asks logind about one session, by its property lines.
+func loginctl(id string) (map[string]string, error) {
+	cmd := exec.Command("loginctl", "show-session", id, "-p", "Active", "-p", "State", "-p", "Remote", "-p", "Type", "-p", "Class")
+	var out bytes.Buffer
+	cmd.Stdout = &out
+	done := make(chan error, 1)
+	if err := cmd.Start(); err != nil {
+		return nil, err
+	}
+	go func() { done <- cmd.Wait() }()
+	select {
+	case err := <-done:
+		if err != nil {
+			return nil, err
+		}
+	case <-time.After(3 * time.Second):
+		_ = cmd.Process.Kill()
+		return nil, errors.New("loginctl did not answer in 3s")
+	}
+	return ParseProperties(out.String()), nil
+}
+
+// ParseProperties reads `Key=Value` lines, as loginctl and systemctl show print them.
+func ParseProperties(text string) map[string]string {
+	out := map[string]string{}
+	sc := bufio.NewScanner(strings.NewReader(text))
+	for sc.Scan() {
+		if k, v, ok := strings.Cut(sc.Text(), "="); ok {
+			out[k] = v
+		}
+	}
+	return out
+}

modules/adwaita/internal/desktop/session_test.go

@@ -0,0 +1,255 @@
+package desktop
+
+import (
+	"context"
+	"encoding/json"
+	"net"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+)
+
+// A machine in a directory: a process table, the X servers' socket directory and a runtime base.
+type fakeMachine struct {
+	t                  *testing.T
+	proc, x11, runtime string
+	uid                int
+}
+
+func newMachine(t *testing.T) *fakeMachine {
+	root, err := os.MkdirTemp("", "desk")
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { os.RemoveAll(root) })
+	m := &fakeMachine{t: t, proc: filepath.Join(root, "p"), x11: filepath.Join(root, "x"), runtime: filepath.Join(root, "r"), uid: os.Getuid()}
+	for _, d := range []string{m.proc, m.x11, filepath.Join(m.runtime, strconv.Itoa(m.uid))} {
+		if err := os.MkdirAll(d, 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return m
+}
+
+func (m *fakeMachine) socket(path string) {
+	l, err := net.Listen("unix", path)
+	if err != nil {
+		m.t.Fatal(err)
+	}
+	m.t.Cleanup(func() { l.Close() })
+}
+
+func (m *fakeMachine) process(pid int, comm string, start int, env ...string) {
+	dir := filepath.Join(m.proc, strconv.Itoa(pid))
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		m.t.Fatal(err)
+	}
+	os.WriteFile(filepath.Join(dir, "environ"), []byte(strings.Join(env, "\x00")+"\x00"), 0o600)
+	os.WriteFile(filepath.Join(dir, "comm"), []byte(comm+"\n"), 0o644)
+	// pid (comm) state ppid pgrp session tty tpgid flags minflt cminflt majflt cmajflt utime stime
+	// cutime cstime priority nice threads itrealvalue starttime ...
+	stat := strconv.Itoa(pid) + " (" + comm + ") S 1 1 1 0 -1 0 0 0 0 0 0 0 0 0 20 0 1 0 " + strconv.Itoa(start) + " 0 0"
+	os.WriteFile(filepath.Join(dir, "stat"), []byte(stat), 0o644)
+}
+
+func (m *fakeMachine) finder(logind func(string) (map[string]string, error), prefer ...string) Finder {
+	return Finder{Proc: m.proc, X11Sockets: m.x11, RuntimeBase: m.runtime, UID: m.uid, Prefer: prefer, Logind: logind}
+}
+
+func active(id string) (map[string]string, error) {
+	return map[string]string{"Active": "yes", "State": "active", "Remote": "no", "Type": "x11"}, nil
+}
+
+func TestTheSessionIsFoundInTheWindowManagersEnvironmentAndOnlyItsWordsAreRead(t *testing.T) {
+	m := newMachine(t)
+	m.socket(filepath.Join(m.x11, "X1"))
+	run := filepath.Join(m.runtime, strconv.Itoa(m.uid))
+	m.socket(filepath.Join(run, "bus"))
+	m.process(100, "lemurs-child", 5, "DISPLAY=:1", "XDG_SESSION_ID=1")
+	m.process(200, "i3", 10, "DISPLAY=:1", "XAUTHORITY=/home/op/.Xauthority", "XDG_SESSION_ID=1",
+		"XDG_SESSION_TYPE=x11", "XDG_CURRENT_DESKTOP=i3", "XDG_RUNTIME_DIR="+run,
+		"DBUS_SESSION_BUS_ADDRESS=unix:path=/tmp/dbus-private", "NPM_TOKEN=secret", "OPENAI_API_KEY=secret")
+	m.process(300, "zsh", 50, "TERM=xterm") // no display: not a candidate
+
+	s, err := m.finder(active, "i3").Find()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if s.FoundIn.PID != 200 || s.Display != ":1" || s.XAuthority != "/home/op/.Xauthority" || s.ID != "1" || s.Type != "x11" || s.Desktop != "i3" {
+		t.Fatalf("session: %+v", s)
+	}
+	if s.Bus != "unix:path="+filepath.Join(run, "bus") || s.SessionBus != "unix:path=/tmp/dbus-private" {
+		t.Fatalf("the user manager's bus first, the session's private one reported beside it: %q %q", s.Bus, s.SessionBus)
+	}
+	if s.Active == nil || !*s.Active {
+		t.Fatal("logind's word is carried")
+	}
+	env := strings.Join(s.Env([]string{"PATH=/usr/bin", "DISPLAY=:9", "HOME=/home/op"}), "\n")
+	for _, want := range []string{"PATH=/usr/bin", "HOME=/home/op", "DISPLAY=:1", "XAUTHORITY=/home/op/.Xauthority", "DBUS_SESSION_BUS_ADDRESS=unix:path=" + filepath.Join(run, "bus"), "XDG_RUNTIME_DIR=" + run} {
+		if !strings.Contains(env, want) {
+			t.Errorf("env lacks %s:\n%s", want, env)
+		}
+	}
+	if strings.Contains(env, ":9") || strings.Contains(env, "secret") || strings.Contains(env, "NPM_TOKEN") {
+		t.Fatalf("the base's display is replaced and no other word of the session's process passes:\n%s", env)
+	}
+	b, _ := json.Marshal(s)
+	if strings.Contains(string(b), "secret") {
+		t.Fatal("the answer carries a word outside the session's")
+	}
+}
+
+func TestWithoutAPreferenceTheOldestProcessOfTheLiveSessionWins(t *testing.T) {
+	m := newMachine(t)
+	m.socket(filepath.Join(m.x11, "X0"))
+	m.process(410, "xterm", 90, "DISPLAY=:0", "XDG_SESSION_ID=3")
+	m.process(400, "openbox", 20, "DISPLAY=:0", "XDG_SESSION_ID=3")
+	s, err := m.finder(nil).Find()
+	if err != nil || s.FoundIn.PID != 400 {
+		t.Fatalf("%+v %v", s, err)
+	}
+	if s.RuntimeDir != filepath.Join(m.runtime, strconv.Itoa(m.uid)) || s.Bus != "" {
+		t.Fatalf("an absent runtime directory word falls back to the account's, and no bus socket means no bus: %+v", s)
+	}
+}
+
+func TestALeftoverProcessOfAnEndedSessionIsNotTheSession(t *testing.T) {
+	m := newMachine(t)
+	m.process(500, "i3", 10, "DISPLAY=:2", "XDG_SESSION_ID=7") // no X2 socket
+	_, err := m.finder(active, "i3").Find()
+	if !IsNoSession(err) || !strings.Contains(err.Error(), "socket is gone") {
+		t.Fatalf("%v", err)
+	}
+	var answer map[string]any
+	if json.Unmarshal([]byte(err.Error()), &answer) != nil || answer["error"] != "no-graphical-session" {
+		t.Fatalf("the refusal is structured: %s", err)
+	}
+}
+
+func TestNoProcessWithADisplayIsAClearNoSession(t *testing.T) {
+	m := newMachine(t)
+	m.process(600, "sshd", 1, "SSH_CONNECTION=x")
+	_, err := m.finder(active).Find()
+	if !IsNoSession(err) || !strings.Contains(err.Error(), "no process of uid") {
+		t.Fatalf("%v", err)
+	}
+}
+
+func TestAnActiveLocalSessionBeatsAnInactiveOneAndARemoteOneIsRefused(t *testing.T) {
+	m := newMachine(t)
+	m.socket(filepath.Join(m.x11, "X0"))
+	m.socket(filepath.Join(m.x11, "X1"))
+	m.process(700, "i3", 5, "DISPLAY=:0", "XDG_SESSION_ID=a")
+	m.process(800, "i3", 9, "DISPLAY=:1", "XDG_SESSION_ID=b")
+	logind := func(id string) (map[string]string, error) {
+		if id == "a" {
+			return map[string]string{"Active": "no", "State": "online", "Remote": "no"}, nil
+		}
+		return map[string]string{"Active": "yes", "State": "active", "Remote": "no"}, nil
+	}
+	s, err := m.finder(logind, "i3").Find()
+	if err != nil || s.FoundIn.PID != 800 || s.Display != ":1" {
+		t.Fatalf("the active session: %+v %v", s, err)
+	}
+	remote := func(string) (map[string]string, error) {
+		return map[string]string{"Active": "yes", "Remote": "yes"}, nil
+	}
+	if _, err := m.finder(remote).Find(); !IsNoSession(err) {
+		t.Fatalf("a remote session is not the operator's desktop: %v", err)
+	}
+}
+
+func TestAWaylandSessionIsFoundByItsCompositorsSocket(t *testing.T) {
+	m := newMachine(t)
+	run := filepath.Join(m.runtime, strconv.Itoa(m.uid))
+	m.socket(filepath.Join(run, "wayland-1"))
+	m.process(900, "sway", 3, "WAYLAND_DISPLAY=wayland-1", "XDG_RUNTIME_DIR="+run, "SWAYSOCK=/run/x.sock")
+	s, err := m.finder(nil, "sway").Find()
+	if err != nil || s.Type != "wayland" || s.WaylandDisplay != "wayland-1" {
+		t.Fatalf("%+v %v", s, err)
+	}
+	if !strings.Contains(strings.Join(s.Env(nil), " "), "SWAYSOCK=/run/x.sock") {
+		t.Fatal("the compositor's socket word passes")
+	}
+}
+
+func TestADisplayOnAnotherHostIsNotTheLocalSession(t *testing.T) {
+	for d, want := range map[string]bool{":0": true, ":1.0": true, "unix:2": true, "localhost:10.0": false, "host:0": false, "": false, ":x": false} {
+		if _, ok := DisplayNumber(d); ok != want {
+			t.Errorf("%q: %v", d, ok)
+		}
+	}
+}
+
+func TestACommandIsBoundedAndItsFailureNamed(t *testing.T) {
+	r := Exec(context.Background(), os.Environ(), []byte("hello"), "cat")
+	if !r.OK() || r.Stdout != "hello" {
+		t.Fatalf("%+v", r)
+	}
+	r = Exec(context.Background(), os.Environ(), nil, "sh", "-c", "echo no >&2; exit 3")
+	if r.OK() || r.Code != 3 || !strings.Contains(r.Err().Error(), "exited 3: no") {
+		t.Fatalf("%+v", r)
+	}
+	r = Exec(context.Background(), os.Environ(), nil, "no-such-program-here")
+	if r.OK() || r.Code != 127 {
+		t.Fatalf("%+v", r)
+	}
+	r = Exec(context.Background(), os.Environ(), nil, "sh", "-c", "head -c 400000 /dev/zero")
+	if !r.Truncated || len(r.Stdout) != MostOutput {
+		t.Fatalf("cut at %d: %d %v", MostOutput, len(r.Stdout), r.Truncated)
+	}
+}
+
+func TestArgumentsAreReadStrictly(t *testing.T) {
+	a := Args{"name": " x ", "n": float64(3), "f": 1.5, "b": true, "l": []any{"a", "b"}}
+	if v, err := a.Text("name"); err != nil || v != "x" {
+		t.Fatal(v, err)
+	}
+	if _, err := a.Text("missing"); err == nil {
+		t.Fatal("a missing required text")
+	}
+	if n, err := a.Whole("n", 0, 1, 5); err != nil || n != 3 {
+		t.Fatal(n, err)
+	}
+	if _, err := a.Whole("f", 0, 0, 5); err == nil {
+		t.Fatal("1.5 is not whole")
+	}
+	if _, err := a.Whole("n", 0, 4, 5); err == nil {
+		t.Fatal("out of range")
+	}
+	if b, given, err := a.Bool("b"); !b || !given || err != nil {
+		t.Fatal("bool")
+	}
+	if _, _, err := a.Bool("name"); err == nil {
+		t.Fatal("text is not a bool")
+	}
+	if l, err := a.Strings("l"); err != nil || len(l) != 2 {
+		t.Fatal(l, err)
+	}
+	if _, err := a.OneOf("name", "", "y", "z"); err == nil {
+		t.Fatal("not one of")
+	}
+}
+
+func TestAPathIsKeptInsideTheHome(t *testing.T) {
+	t.Setenv("MESH_OPERATOR_HOME", "/home/op")
+	for in, want := range map[string]string{"~/a.png": "/home/op/a.png", "b/c": "/home/op/b/c", "/home/op/d": "/home/op/d", "~": "/home/op"} {
+		if got, err := InHome(in); err != nil || got != want {
+			t.Errorf("%s: %s %v", in, got, err)
+		}
+	}
+	for _, out := range []string{"/etc/passwd", "~/../other", "../x"} {
+		if _, err := InHome(out); err == nil {
+			t.Errorf("%s was accepted", out)
+		}
+	}
+}
+
+func TestPropertiesAreParsed(t *testing.T) {
+	p := ParseProperties("Active=yes\nState=active\nDisplay=\n")
+	if p["Active"] != "yes" || p["State"] != "active" || p["Display"] != "" {
+		t.Fatal(p)
+	}
+}

modules/adwaita/module.json

@@ -0,0 +1,118 @@
+{
+  "module": "adwaita",
+  "version": "1",
+  "capabilities": [
+    "package-manager"
+  ],
+  "tools": [
+    "adwaita_appearance",
+    "adwaita_cursor",
+    "adwaita_icons",
+    "adwaita_portal_check"
+  ],
+  "environment": {
+    "variables": {
+      "GTK_THEME": "Adwaita:dark",
+      "GTK2_RC_FILES": "/usr/share/themes/Adwaita-dark/gtk-2.0/gtkrc",
+      "QT_QPA_PLATFORMTHEME": "qt6ct",
+      "QT_STYLE_OVERRIDE": "Fusion",
+      "QT_SELECT": "6",
+      "XCURSOR_THEME": "Adwaita",
+      "XCURSOR_SIZE": "24"
+    }
+  },
+  "shell": [
+    {
+      "for": "xresources",
+      "slot": "normal",
+      "code": "! adwaita: the cursor, for X programs that take it from the resources.\nXcursor.theme: Adwaita\nXcursor.size: 24\n"
+    },
+    {
+      "for": "xinitrc",
+      "slot": "normal",
+      "code": "# The appearance (module adwaita): GSettings is where the portal reads dark or light, and the portal is\n# the only way it reaches Electron, Chromium, Firefox and flatpaks. Set at every session start to the\n# module's default; adwaita_appearance switches it for a session.\ngsettings set org.gnome.desktop.interface color-scheme 'prefer-dark' || true\ngsettings set org.gnome.desktop.interface gtk-theme 'Adwaita' || true\ngsettings set org.gnome.desktop.interface icon-theme 'Adwaita' || true\ngsettings set org.gnome.desktop.interface cursor-theme 'Adwaita' || true\ngsettings set org.gnome.desktop.interface cursor-size 24 || true\ngsettings set org.gnome.desktop.interface font-name 'Inter 11' || true\ngsettings set org.gnome.desktop.interface monospace-font-name 'JetBrainsMono Nerd Font 11' || true\n"
+    }
+  ],
+  "resources": [
+    {
+      "id": "package-gnome-themes-extra",
+      "type": "package",
+      "package": "gnome-themes-extra"
+    },
+    {
+      "id": "package-adwaita-icon-theme",
+      "type": "package",
+      "package": "adwaita-icon-theme"
+    },
+    {
+      "id": "package-adwaita-cursors",
+      "type": "package",
+      "package": "adwaita-cursors"
+    },
+    {
+      "id": "package-qt6ct",
+      "type": "package",
+      "package": "qt6ct"
+    },
+    {
+      "id": "package-xdg-desktop-portal-gtk",
+      "type": "package",
+      "package": "xdg-desktop-portal-gtk"
+    },
+    {
+      "id": "gtk3",
+      "type": "file",
+      "path": "${machine:account-home}/.config/gtk-3.0/settings.ini",
+      "owner": "${machine:account}",
+      "mode": "0644",
+      "content": "# Written by the mesh (module adwaita, novox/hq ADR 0208), for GTK 3 and GTK 4 alike. Replaced at\n# every push; adwaita_appearance switches dark and light for the running session.\n[Settings]\ngtk-theme-name=Adwaita\ngtk-icon-theme-name=Adwaita\ngtk-cursor-theme-name=Adwaita\ngtk-cursor-theme-size=24\ngtk-font-name=Inter 11\ngtk-application-prefer-dark-theme=1\n"
+    },
+    {
+      "id": "gtk4",
+      "type": "file",
+      "path": "${machine:account-home}/.config/gtk-4.0/settings.ini",
+      "owner": "${machine:account}",
+      "mode": "0644",
+      "content": "# Written by the mesh (module adwaita, novox/hq ADR 0208), for GTK 3 and GTK 4 alike. Replaced at\n# every push; adwaita_appearance switches dark and light for the running session.\n[Settings]\ngtk-theme-name=Adwaita\ngtk-icon-theme-name=Adwaita\ngtk-cursor-theme-name=Adwaita\ngtk-cursor-theme-size=24\ngtk-font-name=Inter 11\ngtk-application-prefer-dark-theme=1\n"
+    },
+    {
+      "id": "qt6ct",
+      "type": "file",
+      "path": "${machine:account-home}/.config/qt6ct/qt6ct.conf",
+      "owner": "${machine:account}",
+      "mode": "0644",
+      "content": "[Appearance]\ncolor_scheme_path=/usr/share/qt6ct/colors/darker.conf\ncustom_palette=true\nicon_theme=Adwaita\nstandard_dialogs=default\nstyle=Fusion\n\n[Fonts]\nfixed=\"JetBrainsMono Nerd Font,11,-1,5,50,0,0,0,0,0\"\ngeneral=\"Inter,11,-1,5,50,0,0,0,0,0\"\n\n[Interface]\nactivate_item_on_single_click=1\nbuttonbox_layout=0\ncursor_flash_time=1000\ndialog_buttons_have_icons=1\ndouble_click_interval=400\ngui_effects=@Invalid()\nkeyboard_scheme=2\nmenus_have_icons=true\nshow_shortcuts_in_context_menus=true\nstylesheets=@Invalid()\ntoolbutton_style=4\nunderline_shortcut=1\nwheel_scroll_lines=3\n\n[Troubleshooting]\nforce_raster_widgets=1\nignored_applications=@Invalid()\n"
+    },
+    {
+      "id": "portals",
+      "type": "file",
+      "path": "${machine:account-home}/.config/xdg-desktop-portal/portals.conf",
+      "owner": "${machine:account}",
+      "mode": "0644",
+      "content": "# Written by the mesh (module adwaita, novox/hq ADR 0208). Replaced at every push.\n#\n# Which portal backend answers each interface. i3 is not a desktop xdg-desktop-portal knows, so with\n# no preference it uses whichever backend happens to be installed: fine while gtk is the only one,\n# wrong the day another arrives as somebody else's dependency. Named instead. gtk also serves\n# org.freedesktop.appearance (dark or light) from GSettings, which the session's start sets.\n[preferred]\ndefault=gtk\n# Secrets for sandboxed programs come from the keyring's backend. Without this line no backend answers\n# the interface: gtk does not implement it, and gnome-keyring's names only GNOME as its desktop.\norg.freedesktop.impl.portal.Secret=gnome-keyring\n"
+    },
+    {
+      "id": "cursor",
+      "type": "file",
+      "path": "${machine:account-home}/.icons/default/index.theme",
+      "owner": "${machine:account}",
+      "mode": "0644",
+      "content": "# Written by the mesh (module adwaita, novox/hq ADR 0208): the default cursor theme, for programs that\n# read neither XCURSOR_THEME nor the X resources.\n[Icon Theme]\nName=Default\nInherits=Adwaita\n"
+    }
+  ],
+  "build": {
+    "artifacts": [
+      {
+        "name": "tools",
+        "kind": "bundle",
+        "language": "go",
+        "system": "arch",
+        "from": "cmd/adwaita-tools",
+        "binary": "adwaita-tools",
+        "loads": [
+          "adwaita-tools"
+        ]
+      }
+    ]
+  }
+}

modules/asus-zephyrus-g14/README.md

@@ -0,0 +1,362 @@
+# asus-zephyrus-g14
+
+The hardware module for the **ASUS ROG Zephyrus G14** laptop: its vendor daemon and platform
+profiles, the hybrid GPU's mode and driver options, suspend, the lid and power key, low battery,
+the backlights, the vendor keys and the touchpad (novox/hq research 027/03 *Power management on
+the laptop*, research 026/05, to-be 42 phase 3).
+
+## Why this name
+
+A module is named after the hardware model, never the node (novox/hq ADR 0112; research 026/03:
+no flavors, no machine names). `asus-zephyrus-g14` is the model family exactly as the firmware
+reports it (`/sys/class/dmi/id/product_family` = `ROG Zephyrus G14`). The module's code checks that
+value and its switcher does nothing on any other model, and `zephyrus_check` reports it.
+
+A wider name such as `asus-rog-laptop` would promise what this module cannot keep. Its contents
+belong to this family: the vendor-key scan codes, the eDP panel beside an NVIDIA dGPU, and the NVIDIA
+D3 workaround. A second G14 is assigned the same module. Another ROG model gets its own.
+
+Written against the GA403 (2024, Ryzen 8945HS, RTX 4070 Laptop, hybrid). Older G14 years have the same
+daemons and probably the same keys. Their GPU options are unverified.
+
+## What it owns
+
+| | what | how |
+|---|---|---|
+| package | `asusctl` (asusd + client) | the distribution's package (`extra`). The machine was found with a local build of 6.4.0. The host only asserts *present*, so the switch to 6.5.0 from `extra` happens at the next `pacman -Syu` (or `pacman -S asusctl`). `zephyrus_check` flags a local build |
+| package | `upower`, `playerctl` | what the low-battery drop-in and the media keys use. `xinput` is the `xorg` module's (one package, one module on a node) |
+| service | `asusd` running (static unit: no boot state to declare), `supergfxd` running and enabled | |
+| archive | `/usr/local/lib/asus-zephyrus-g14/bin/` | the module's scripts, from `files/bin` (below) |
+| file ×2 | `~/.config/i3/config.d/10-asus.conf`, `20-g14.conf` | the laptop's lines in i3: the keys the firmware sends as ordinary presses (Fn+F6, Fn+F9), the keyboard-backlight notifier, the panel as primary, the touchpad key. The paths are adopted, because a second file binding the same keys makes i3's configuration check fail, and the `i3` module's watcher then reloads nothing |
+| file ×4 | `asus-zephyrus-g14-touchpad-resume.service`, and a drop-in `asus-zephyrus-g14-touchpad.conf` on each sleep service | the touchpad's settings once more after a resume (below) |
+| file | `/etc/modprobe.d/g14-nvidia-power.conf` | `NVreg_DynamicPowerManagement=0x00` (runtime D3 off: the ACPI D-Notifier hang) and `NVreg_PreserveVideoMemoryAllocations=1`. The path is adopted (ADR 0182) |
+| file | `/etc/modprobe.d/video-brightness-switch.conf` | `video.brightness_switch_enabled=0`, so the ACPI video driver does not also move a backlight on the keys. The file was on the machine and owned by nothing |
+| file ×3 | `systemd-{suspend,hibernate,suspend-then-hibernate}.service.d/asus-zephyrus-g14-nvidia.conf` | `Wants=` the matching `nvidia-*` sleep units and `nvidia-resume` (see *suspend units* below) |
+| file | `nvidia-powerd.service.d/asus-zephyrus-g14.conf` | `ConditionKernelCommandLine=zephyrus.nvidia-powerd`: Dynamic Boost runs only when the operator opts in at boot |
+| file | `/etc/systemd/logind.conf.d/power.conf` | the power key and the lid suspend, on battery, on mains and docked. `systemd-logind` is reloaded, never restarted |
+| file | `/etc/udev/rules.d/90-backlight.rules` | backlights writable by the `video` group. `systemd-udevd` is reloaded |
+| file | `triggerhappy.service.d/asus-zephyrus-g14.conf` | `thd … --user ${machine:account}`: the triggers run as the operator's account (below) |
+| file | `/etc/triggerhappy/triggers.d/asus-g14.conf` | the vendor keys: media (`KEY_PROG1/3/4`), panel brightness, touchpad (`KEY_F21`). The path is adopted, because two trigger files would fire every key twice |
+| file | `/etc/UPower/UPower.conf.d/50-asus-zephyrus-g14.conf` | low battery at 15/10/7 %; at 7 % **suspend**, not power off. A drop-in over the package's own file |
+| file | `/etc/X11/xorg.conf.d/30-asus-zephyrus-g14-touchpad.conf` | tap to click, natural scrolling, acceleration 0.15, as an X input class |
+
+**What it does not own, on purpose:**
+
+- `/etc/asusd/*.ron` belong to asusd, which rewrites them whenever a setting changes. RON is not a
+  format the host writes into (ADR 0102 speaks JSON and marked blocks). Owning the file whole would
+  repeat the predecessor's freeze: the measured file already differs from the one the predecessor
+  shipped. The settings the module needs are set through asusd, by its code (below).
+- `/etc/supergfxd.conf` and `/etc/modprobe.d/supergfxd.conf` belong to supergfxd, which writes both.
+- The swap file, its unit and the swap partition are the machine's swap layout (research 027,
+  question 3). They are not this module's, nor `memory-pressure`'s.
+- **Places.** The screen layouts for named places (`$mod+Alt+1…7`, `~/.screenlayout/`,
+  `~/scripts/.screenlayouts/@*.sh`) name where the operator works, which no module may (ADR 0112).
+  They are the operator's own lines until autorandr profiles replace them (the `xorg` module).
+- **The monitor-hotplug wizard** (`/etc/udev/rules.d/91-monitor-hotplug.rules`,
+  `~/scripts/.screenlayouts/monitor-wizard.sh`) is any laptop's, not this model's. The predecessor said
+  so itself (its `laptop` flavor). It is the display server's to replace with autorandr's own hotplug
+  handling. Until then it stays as found, and it still calls the predecessor's `as-user`.
+- **The screenshot script** (`~/.config/i3/scripts/screenshot.sh`) is any machine's. The `i3` module
+  binds it too. This module only binds the key the firmware sends for it.
+- **The bar's battery block.** It belongs here (a block that follows this model's hardware), but the
+  bar has no way in yet (`i3status-rust` README). Once ADR 0210's contributions reach the bar seat,
+  this module contributes it.
+
+**Requires `x11-display`.** The i3 lines and the session scripts need a display, so the module is
+assigned where the display server is.
+
+## Software outside the distribution (ADR 0205, research 027 question 1)
+
+`supergfxctl` (5.2.7, from the asus-linux repository, which is no longer configured) and
+`triggerhappy` (AUR) are **kept as found, and depended on**. The module declares no package for
+either, because the host installs from the official repositories only. It declares their services
+(`supergfxd` running, `triggerhappy` running), so on a machine without them the host refuses the
+service by name: *does not exist on this machine*. The refusal is loud, never a silent pass.
+`zephyrus_check` names both as foreign.
+
+This module does not choose between the options of research 027 question 1. Under the starting
+position (P2: the build machine builds AUR packages into a repository the mesh serves), both become
+`package` resources here, and a fresh G14 installs them. **Until P2 exists, a fresh G14 is blocked
+on installing these two by hand.** ADR 0205's vendored archive (P1) does not fit: supergfxctl is a
+daemon with a system-bus policy and udev rules, and triggerhappy is C.
+
+A later option for the keys: the module's own Go code could read the vendor keys from evdev, which
+the operator's account may do through the `input` group. That would retire triggerhappy entirely.
+It is not done here, because it would put the keys behind the node's runtime, and the runtime
+restarts a bundle that dies only on its next call (below).
+
+## The long-running code: the profile switcher (ADR 0198)
+
+The module's Go bundle serves the tools and runs the platform-profile switcher in the same process.
+The node's runtime launches the bundle at the runtime's start. It replaces the predecessor's
+`auto-profile`, a user unit that woke every five seconds, on battery too.
+
+- **Policy** (constants until settings exist, issue 168): battery → `Quiet`; mains → `Balanced`;
+  mains with the CPU at or above 50 % for 3 samples of 10 s → `Performance`, back to `Balanced` after
+  3 samples at or below 20 %. Between the lines nothing moves (hysteresis). iowait counts as idle.
+- **Woken by events, not a poll.** The kernel's power-supply uevents (netlink, group 1) wake the
+  switcher. Any account may listen on that group, and it needs no daemon, bus client or dependency;
+  upower re-announces the same changes but would need a D-Bus client in the bundle. The CPU is
+  sampled only on mains, every 10 s, because only there does the answer depend on it. On battery,
+  a safety re-read every 5 minutes covers an event lost across a suspend. If the uevent socket
+  cannot be opened, the switcher polls every 10 s and says so in `zephyrus_profile_policy`.
+- **The battery decides the source.** A battery that is *discharging* means battery, whatever any
+  adapter says. The predecessor took any `online` file reading 1 as mains, and on this model the USB-C
+  ports report `online`. Batteries of `scope=Device` (a mouse, a headset) are ignored.
+- **It acts on a change of its decision, never to restore one.** A profile someone chose by hand (the
+  profile key, asusctl, `zephyrus_profile`) stays until the power source changes or the load crosses
+  a line. The predecessor re-asserted its choice every five seconds, which made the profile key
+  useless. **Starting is not a decision**: the runtime restarts the bundle on every push that changes
+  one, and a push must not reset the operator's profile.
+- **A hold.** `zephyrus_profile` holds the profile it sets for 60 min (`hold_minutes`). A change of
+  power source ends the hold.
+- **One assertion at start:** through asusctl, the charge limit (80 %) and asusd's own on-mains and
+  on-battery profiles (`Balanced`, `Quiet`), each read first and set only if it differs. asusd's own
+  switching on a change of power source then agrees with the switcher's. A limit set later with
+  `zephyrus_charge_limit` stands until the bundle next starts. For a one-off full charge, use its
+  `oneshot`.
+- **Events:** `profile.switched` (`profile`, `from`, `reason`, `source`), published through the
+  runtime.
+
+No root is involved. asusd's and supergfxd's bus policies admit the `users` and `wheel` groups, and the
+runtime runs as the operator's account. The one write that may escalate is the panel's backlight,
+when the udev rule has not run yet. It uses `sudo -n` and never prompts. Every command is bounded at
+20 s.
+
+**Known limit.** The runtime restarts a launched bundle that exits *on its next tool call*, not at
+once (mesh-tools `launch.ts`), so a crashed switcher stays down until a tool is called. ADR 0198 §1
+says *started again when it exits*. The switcher recovers from a panic and reports it in
+`zephyrus_profile_policy` and `zephyrus_check`, but a crash of the process is the runtime's to restart.
+
+## The vendor keys and the scripts
+
+triggerhappy opens the input devices as root, then **drops to the operator's account with its groups**
+(`initgroups`: `input`, `video`). The packaged unit already drops to `nobody`, and the module's drop-in
+names the account instead. The predecessor replaced the packaged unit with one that ran every trigger
+as root, then `su`-ed to a named person with a hard-coded uid and display, and sourced a file of
+secrets on the way (research 027 question 2). Now:
+
+- `zephyrus-session CMD…`: runs a command in the account's graphical session. It sets the account's
+  own bus (`/run/user/<uid>/bus`) and takes the display and its authority from the session's window
+  manager's own environment, as the desktop modules' session finder does. If i3 is not running, it
+  asks logind, and then any process of the account that has a display. Nothing is sourced.
+  triggerhappy's `--user` changes the user and its groups and nothing else: the triggers start with
+  the service's bare environment, which is why every key that needs the session goes through this.
+- `zephyrus-media play-pause | next | previous`: the media keys through MPRIS, with a notification of
+  what happened and a lock against the key's own repeat.
+- `zephyrus-display primary | order`: the internal panel as the primary output, and the display key's
+  workspace split (odd workspaces on the panel, even ones on the first external output). The panel is
+  found as the connected `eDP` output. The predecessor named `eDP-1` and used `jq`. This reads i3's
+  answer without it.
+- `zephyrus-kbd-notify`: the keyboard backlight's level, shown when UPower says it changed. One
+  instance per session, because i3 runs its `exec` lines again on an in-place restart.
+- `zephyrus-backlight + | - | N`: the panel in 5 % steps, never below 1 %. **The panel is the
+  backlight under the eDP connector**, because this model also registers `nvidia_0`, which moves
+  nothing. The predecessor named `amdgpu_bl1` literally.
+- `zephyrus-notify ID TEXT`: one replacing notification, through `busctl` (the service manager's
+  client, so no libnotify).
+- `zephyrus-touchpad reset | toggle`: bound to the touchpad key (`KEY_F21`).
+
+**Media keys** go to MPRIS through `playerctl`. The predecessor's fallback to a media server's local
+API needed a token from the secrets file, and is dropped until a module can be handed a secret
+(research 027 question 2). A player that does not speak MPRIS is told as "Media: no player".
+
+## The touchpad: an input class instead of a sleep hook
+
+The predecessor re-ran `xinput` from `/etc/systemd/system-sleep/` after every resume, as a named person
+on a guessed display, because settings made with `xinput` are lost when the device initialises again.
+An X input class is applied by X **every time the device appears**: at login, on hotplug and after a
+resume. So the cause is fixed. The class matches any touchpad on the machine, which is the model's, so it
+holds across G14 years whose touchpads differ. It takes effect at the next X start.
+`zephyrus-touchpad reset` stays as the manual form, on the touchpad key and `$mod+Shift+x`.
+
+**And a backstop after resume.** A resume that does not initialise the device again does not make X
+apply the class either, and the predecessor's i3 file says the touchpad "sometimes needs re-init after
+sleep". So `asus-zephyrus-g14-touchpad-resume.service` runs `zephyrus-touchpad reset` as the account,
+two seconds after the machine is awake. It is never enabled. Each sleep service `Wants=` it through a
+drop-in, and it is ordered `After=` them, which is how `nvidia-resume` is started too.
+`zephyrus_check` says whether the sleep wants it.
+
+## Suspend units without enabling them
+
+`nvidia-suspend`, `-hibernate`, `-suspend-then-hibernate` and `-resume` are enabled with links in the
+sleep services' `.wants` directories. The mesh makes no links (ADR 0012). The host's service shape
+cannot declare them either: it may only say *running* or *stopped*, and *running* on a one-shot that
+last failed would start `nvidia-sleep.sh suspend` with the machine awake. So the module asks for them
+from the other side: a drop-in on each sleep service that `Wants=` them. The units' own
+`Before=`/`After=` order them. The found links stay and are harmless.
+
+`suspend-then-hibernate` now also gets `nvidia-suspend-then-hibernate`, which the machine lacked.
+
+The drop-ins take effect at the service manager's next `daemon-reload`. In the same apply, the restart
+of `triggerhappy` (whose drop-in changes) performs one.
+
+## Tools
+
+| tool | r/a | what |
+|---|---|---|
+| `zephyrus_brightness` | r/a | panel (percent or ±step, floor 1 %) and keyboard (off/low/med/high, 0-3, ±) through asusd |
+| `zephyrus_battery` | r | charge, energy in Wh, health (full ÷ design), cycles (the firmware reports 0, and this is said), limit, watts, hours left |
+| `zephyrus_charge_limit` | r/a | 20-100 through asusd; `oneshot` |
+| `zephyrus_gpu_mode` | r/a | mode, supported modes, dGPU power, the pending mode and action; says that asusd switches the mode on every change of power source |
+| `zephyrus_profile` | r/a | active, on-mains and on-battery profile, kernel platform profile; set with a hold |
+| `zephyrus_thermals` | r | every hwmon temperature and fan, the hottest, the dGPU's temperature **only when it is awake** (nvidia-smi wakes a suspended GPU) |
+| `zephyrus_power_draw` | r | battery flow, APU package power (PPT), dGPU draw when awake, power source and why |
+| `zephyrus_profile_policy` | r | what the switcher would choose now and why: source, recent load against the thresholds, decision, hold, last switch, what woke it, what it asserted at start, and whether the predecessor's switcher still runs |
+| `zephyrus_fan_curves` | r | asusd's curves per profile and fan |
+| `zephyrus_keys` | r | every custom key: each triggerhappy trigger, the module's i3 lines and the keys the firmware handles; what runs and the file it is in. Warns when one key is in two trigger files, which fires it twice |
+| `zephyrus_check` | r | every expectation: model, packages (local or foreign), daemons, nvidia-powerd, sleep units, the NVIDIA options **in force** (`/proc/driver/nvidia/params`), charge limit, one authority each over the profile and the GPU mode, predecessor leftovers; the touchpad resume unit wanted by the sleep; triggerhappy running as the operator's account; any trigger, udev rule or sleep hook still naming `as-user`. It also lists what it did not check |
+
+`profile` is a candidate verb for a future `node-power-profile` seat (research 027/03). That seat has
+no record yet, so this is the module's own tool.
+
+## Found on the laptop, 2026-10-04 (read-only)
+
+- **Two authorities over the GPU mode.** `asusd.ron` has `ac_command: "supergfxctl -m Hybrid"` and
+  `bat_command: "supergfxctl -m Integrated"`, so asusd switches the GPU mode on every change of power
+  source. **supergfxd 5.2.7 cannot read logind's sessions** (`manager is an invalid variant`, every
+  boot), so a switch that needs a logout times out. `zephyrus_check` reports both. The fix is the
+  operator's, in asusd's file: clear both commands, or update supergfxctl once it can be packaged.
+- **`brightness.conf` did nothing.** `HandleBrightnessKey` is not a logind key, and logind logs
+  *Unknown key … ignoring* at every start. The module does not carry it. The brightness keys were
+  always triggerhappy's, with the ACPI video switch off.
+- **Two profile switchers** would run at once until `auto-profile` is stopped (below).
+- **asusctl is a local build** (6.4.0, *Unknown Packager*) beside a foreign `asusctl-debug`.
+
+## When assigned to the laptop: what changes
+
+1. `/usr/local/lib/asus-zephyrus-g14/` appears (seven scripts).
+2. Written over found files (each original kept once by the host): `g14-nvidia-power.conf` and
+   `video-brightness-switch.conf` (same options, so no change until the next boot either),
+   `logind.conf.d/power.conf` (same keys; logind reloaded), `90-backlight.rules` (same effect;
+   udevd reloaded), `triggers.d/asus-g14.conf` (now the module's scripts), and i3's `10-asus.conf` and
+   `20-g14.conf` (the module's lines; the `i3` module's watcher checks and reloads them).
+3. New: the three sleep drop-ins (behaviour gained: `nvidia-suspend-then-hibernate`), the
+   nvidia-powerd drop-in (no effect while it is masked), the triggerhappy drop-in, the UPower drop-in
+   (same values as today), the touchpad input class (at the next X start), and the resume unit with
+   its three drop-ins.
+4. `daemon-reload` and a `triggerhappy` restart. thd now runs as the account and the keys run the
+   module's scripts. `upower` restarts.
+5. Packages, asusd and supergfxd: already as declared, so nothing changes. asusctl stays the local
+   6.4.0 until the next upgrade.
+6. The node runtime restarts with the new bundle. The switcher asserts the limit (80, already) and
+   asusd's profiles (Balanced and Quiet, already), so it sets nothing. It takes the current decision
+   as applied and acts from the first event on.
+
+## Predecessor files this module makes redundant — the operator removes them once (ADR 0182)
+
+**On the laptop:**
+
+1. `systemctl --user disable --now auto-profile.service`, then delete
+   `~/.config/systemd/user/auto-profile.service` and `~/scripts/auto-profile`. **Do this right after
+   the push**, or two switchers run at once.
+2. **Before the push, keep the place layouts.** The module writes `20-g14.conf` over the found file,
+   and the found file carries the seven `$mod+Alt+1…7` layout bindings, which name places. Move them,
+   and the `exec … ~/.screenlayout/@default.sh` line, to a file of your own in the same directory,
+   e.g. `~/.config/i3/config.d/90-layouts.conf`. i3 reads it the same way, and it stays yours until
+   autorandr profiles replace it. The host keeps the found `20-g14.conf` once in any case.
+3. `~/scripts/asus-bright`, `~/scripts/asusctl-kbd-bright`, `~/scripts/xrandr-bright`,
+   `~/scripts/media-control`, `~/scripts/xinput-reset-touchpad`,
+   `~/scripts/.screenlayouts/orden-workspaces.sh` and `~/.config/i3/scripts/kbd-brightness-notify.sh`:
+   no trigger and no line of the module's uses them any more.
+   **Keep `~/scripts/as-user`** while `/etc/udev/rules.d/91-monitor-hotplug.rules` exists: that rule
+   still runs the monitor wizard through it. `zephyrus_check` names every place that still calls it.
+4. `/etc/systemd/system/triggerhappy.service`: the predecessor's replacement of the packaged unit. The
+   module's drop-in works over either, so delete it and `systemctl daemon-reload` to return to the
+   packaged unit (`Type=notify`, socket).
+5. `/etc/systemd/logind.conf.d/brightness.conf`: the unknown key, which does nothing.
+6. `/etc/systemd/system-sleep/xinput-reset-touchpad.sh`, if it is still there: replaced by the input
+   class and the resume unit. (It was already gone on 2026-10-04.)
+7. `/etc/UPower/UPower.conf`: the predecessor's replacement of the package's file. Its values are now
+   the module's drop-in. Restore the package's copy (`rm` it, then `pacman -S upower`).
+8. Optional: `systemctl disable nvidia-suspend nvidia-resume nvidia-hibernate` (the drop-ins carry them
+   now), `/etc/asusd/*.ron-old` and `fan_curves.ron.bak`, the foreign `asusctl-debug` package, and
+   `pacman -S asusctl` for the distribution's build.
+
+**Stays the machine's:** `/swapfile` and `/etc/systemd/system/swapfile.swap` (the swap layout),
+`/etc/udev/rules.d/91-monitor-hotplug.rules` (the display's, phase 2), and the place layouts.
+
+**On the desktop** (the predecessor's G14 flavor reached it; part was removed on 2026-10-04): none of
+this module applies there. Still present and to be deleted:
+`/etc/systemd/logind.conf.d/brightness.conf`, `/etc/systemd/system-sleep/xinput-reset-touchpad.sh`,
+`~/scripts/xinput-reset-touchpad`, `~/scripts/xrandr-bright` and
+`~/.config/i3/scripts/kbd-brightness-notify.sh`.
+
+## The predecessor, file by file
+
+The predecessor carried this model in its desktop module's `g14` and `laptop` flavors, and in a
+`g14-power` module. Every model-specific file of the desktop module, and where it is now:
+
+| predecessor file | now |
+|---|---|
+| `i3-asus.conf` → `config.d/10-asus.conf` | **this module**, the same path; the scripts it calls are the module's |
+| `i3-g14.conf` → `config.d/20-g14.conf` | **this module**, the same path. The place layouts in it are the operator's own file (migration, step 2) |
+| `g14-triggerhappy-asus-g14.conf` | **this module**, the same path; the triggers run the module's scripts |
+| `g14-triggerhappy.service` (a replacement of the packaged unit) | **retired**: a drop-in over the packaged unit (`--user`) |
+| `as-user` | **retired**: thd runs as the account, and `zephyrus-session` finds the session. Kept on the machine while the monitor wizard's udev rule calls it |
+| `asus-bright` | **this module**: `zephyrus-backlight`, the panel found by its connector |
+| `media-control` (bound by the `g14` triggers) | **this module**: `zephyrus-media`, without the fallback that needed a secret |
+| `xinput-reset-touchpad` | **this module**: the input class, `zephyrus-touchpad`, and the resume unit |
+| `g14-system-sleep-xinput-reset-touchpad.sh` | **this module**: the input class, and the resume unit that the sleep services want |
+| `kbd-brightness-notify.sh` | **this module**: `zephyrus-kbd-notify`, one instance per session |
+| `asusctl-kbd-bright` | **retired**: the keyboard keys are the firmware's, and `zephyrus_brightness` sets it by hand |
+| `xrandr-bright` | **retired**: a software dimming; the panel's backlight is `zephyrus-backlight` |
+| `screenlayout-orden-workspaces.sh` | **this module**: `zephyrus-display order`, on Fn+F9 |
+| `screenlayout-*.sh` (six named places) | **the operator's**, until autorandr profiles (the `xorg` module) replace them |
+| `g14-90-backlight.rules` | **this module**, the same path |
+| `g14-logind-brightness.conf` | **retired**: an unknown logind key that did nothing |
+| `laptop-monitor-wizard.sh`, `laptop-91-monitor-hotplug.rules` | **any laptop's, not this module's**: kept as found, for the `xorg` module's autorandr to replace |
+| `bottom-bar.g14.toml` (the battery block) | **waits**: this module's, once the bar takes contributions (ADR 0210) |
+| `razer-basilisk-battery-percentage` | **not this model's**: a mouse. No module carries it (`i3status-rust` README) |
+| `screenshot.sh` | **not this model's**: any machine's script, which the `i3` module binds too; this module binds Fn+F6 to it |
+| package `triggerhappy` | **depended on, kept as found** (outside the distribution, above) |
+
+`g14-power`'s pieces (the NVIDIA options, logind, UPower, the sleep units, `auto-profile`) are in
+*What it owns* and the switcher above. Its memory guard is the `memory-pressure` module's.
+
+## What the predecessor paid for, and what this module does about it
+
+- **One file for every machine overwrote what each machine needed** (the predecessor's split of its i3
+  configuration into a base, an ASUS and a G14 layer, 2026-03). Here the model's lines are this
+  module's files, and nothing else writes them.
+- **The layers silently stopped applying.** The predecessor's chain *laptop → g14* was stated in two
+  places, and the one its installer read lacked it. For weeks the G14 received only its 21
+  G14-tagged files, and the 49 base and laptop files were never seeded. Validation and the pipeline
+  both reported success (2026-08, found at a cutover). Here a module is one manifest. Its tests assert
+  that every trigger runs a script it ships, and `zephyrus_check` and `zephyrus_keys` read back what is
+  on the machine.
+- **A hook wrote asusd's own files with sudo,** because configuration sync might not run on install
+  (2026-04), and froze them. asusd rewrites those files whenever a setting changes. Here the module
+  sets asusd through its client and never writes the RON files.
+- **A profile daemon fought the profile key.** The predecessor turned asusd's own switching off and
+  re-asserted its choice every five seconds (2026-03). Here the switcher acts on a change of its
+  decision, never to restore one.
+- **The overnight freeze** was an ACPI power-source event hanging the NVIDIA GPU in runtime D3
+  (2026-06). It is fixed by the driver options, which `zephyrus_check` reads from the running driver
+  rather than from the file.
+- **A unit restarted about 73,000 times, unnoticed** (2026-06). Here every expectation is in
+  `zephyrus_check`, and so is a list of what it did not check.
+- **The vendor keys ran as root and `su`-ed to a named person** on a guessed display, sourcing a file
+  of secrets. Here thd drops to the account, and nothing is sourced.
+- **The touchpad lost its settings after a resume,** because `xinput` settings vanish when the device
+  initialises again. Here an input class re-applies them, with the resume unit as a backstop.
+
+## Tests
+
+`go test ./...` in this directory. Every tool runs against a tree standing in for `/sys`, `/proc` and
+`/etc`, and an injected runner answering with what asusctl 6.4 and supergfxctl 5.2 said on the laptop.
+The tests cover:
+
+- the power-source rule;
+- battery arithmetic from `charge_*`;
+- the eDP panel choice;
+- brightness bounds;
+- the policy's sustain, relax and hysteresis, with iowait counted as idle;
+- the switcher: no act at start, one switch per change of source, a published event, boost from
+  samples, holds, retry after failure, start-up assertions only where they differ, inert on another
+  model;
+- the uevent filter;
+- the manifest: tools listed equal tools served, no machine named, triggers exist, every key runs a
+  shipped executable script, every script passes `bash -n`;
+- `zephyrus_keys` over the module's own triggers and i3 lines, and a key in two trigger files;
+- the checks for `as-user`, triggerhappy's account and the resume unit.

modules/asus-zephyrus-g14/cmd/zephyrus/asus.go

@@ -0,0 +1,264 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"regexp"
+	"strconv"
+	"strings"
+)
+
+// The vendor daemons are reached through their own command-line clients, which speak to them on the
+// system bus. Their bus policy admits the `users` and `wheel` groups, so none of this needs root.
+
+// Profiles are the platform profiles asusd offers on this model, in its spelling.
+var Profiles = []string{"Quiet", "Balanced", "Performance"}
+
+// canonicalProfile accepts any case and answers asusd's spelling, or an error naming the choices.
+func canonicalProfile(s string) (string, error) {
+	for _, p := range Profiles {
+		if strings.EqualFold(strings.TrimSpace(s), p) {
+			return p, nil
+		}
+	}
+	return "", fmt.Errorf("profile %q is not one of %s", s, strings.Join(Profiles, ", "))
+}
+
+// ProfileState is what asusd says about the platform profile.
+type ProfileState struct {
+	Active   string `json:"active"`
+	OnAC     string `json:"on_ac,omitempty"`
+	Battery  string `json:"on_battery,omitempty"`
+	Platform string `json:"platform_profile,omitempty"`
+	Choices  string `json:"platform_profile_choices,omitempty"`
+}
+
+var (
+	activeProfile  = regexp.MustCompile(`(?m)^Active profile:\s*(\S+)`)
+	acProfile      = regexp.MustCompile(`(?m)^AC profile\s+(\S+)`)
+	batteryProfile = regexp.MustCompile(`(?m)^Battery profile\s+(\S+)`)
+)
+
+// ParseProfileGet reads `asusctl profile get`.
+func ParseProfileGet(out string) (ProfileState, error) {
+	var p ProfileState
+	if m := activeProfile.FindStringSubmatch(out); m != nil {
+		p.Active = m[1]
+	} else {
+		return p, fmt.Errorf("asusctl profile get said no active profile: %q", strings.TrimSpace(out))
+	}
+	if m := acProfile.FindStringSubmatch(out); m != nil {
+		p.OnAC = m[1]
+	}
+	if m := batteryProfile.FindStringSubmatch(out); m != nil {
+		p.Battery = m[1]
+	}
+	return p, nil
+}
+
+// Profile reads the platform profile from asusd and the kernel.
+func (m *Machine) Profile(ctx context.Context) (ProfileState, error) {
+	out, err := m.Run(ctx, "asusctl", "profile", "get")
+	if err != nil {
+		return ProfileState{}, vendor("asusctl", err)
+	}
+	p, err := ParseProfileGet(out)
+	if err != nil {
+		return p, err
+	}
+	p.Platform = m.read("/sys/firmware/acpi/platform_profile")
+	p.Choices = m.read("/sys/firmware/acpi/platform_profile_choices")
+	return p, nil
+}
+
+// SetProfile has asusd switch the active profile.
+func (m *Machine) SetProfile(ctx context.Context, profile string) error {
+	_, err := m.Run(ctx, "asusctl", "profile", "set", profile)
+	return vendor("asusctl", err)
+}
+
+var chargeLimit = regexp.MustCompile(`charge limit:\s*(\d+)\s*%`)
+
+// ChargeLimit is the battery's charge limit as asusd reports it.
+func (m *Machine) ChargeLimit(ctx context.Context) (int, error) {
+	out, err := m.Run(ctx, "asusctl", "battery", "info")
+	if err != nil {
+		return 0, vendor("asusctl", err)
+	}
+	g := chargeLimit.FindStringSubmatch(out)
+	if g == nil {
+		return 0, fmt.Errorf("asusctl battery info said no limit: %q", strings.TrimSpace(out))
+	}
+	n, _ := strconv.Atoi(g[1])
+	return n, nil
+}
+
+// Keyboard backlight levels in asusd's spelling, index = the kernel's brightness value.
+var KeyboardLevels = []string{"off", "low", "med", "high"}
+
+var ledLevel = regexp.MustCompile(`(?i)brightness:\s*(off|low|med|high)`)
+
+// ParseLeds reads `asusctl leds get`.
+func ParseLeds(out string) (string, error) {
+	g := ledLevel.FindStringSubmatch(out)
+	if g == nil {
+		return "", fmt.Errorf("asusctl leds get said no level: %q", strings.TrimSpace(out))
+	}
+	return strings.ToLower(g[1]), nil
+}
+
+// FanCurve is one fan's curve in one profile: eight points of temperature (°C) and duty (0-255).
+type FanCurve struct {
+	Fan     string `json:"fan"`
+	Enabled bool   `json:"enabled"`
+	Temp    []int  `json:"temp_c"`
+	PWM     []int  `json:"pwm"`
+}
+
+var (
+	fanBlock = regexp.MustCompile(`(?s)fan:\s*(\w+),\s*pwm:\s*\(([^)]*)\),\s*temp:\s*\(([^)]*)\),\s*enabled:\s*(true|false)`)
+)
+
+// ParseFanCurves reads `asusctl fan-curve --mod-profile <p>`.
+func ParseFanCurves(out string) []FanCurve {
+	var curves []FanCurve
+	for _, g := range fanBlock.FindAllStringSubmatch(out, -1) {
+		curves = append(curves, FanCurve{Fan: g[1], PWM: ints(g[2]), Temp: ints(g[3]), Enabled: g[4] == "true"})
+	}
+	return curves
+}
+
+func ints(list string) []int {
+	var out []int
+	for _, f := range strings.Split(list, ",") {
+		if n, err := strconv.Atoi(strings.TrimSpace(f)); err == nil {
+			out = append(out, n)
+		}
+	}
+	return out
+}
+
+// GPUState is what supergfxd says about the hybrid GPU.
+type GPUState struct {
+	Mode          string   `json:"mode"`
+	Supported     []string `json:"supported"`
+	Power         string   `json:"dgpu_power,omitempty"`
+	PendingAction string   `json:"pending_action,omitempty"`
+	PendingMode   string   `json:"pending_mode,omitempty"`
+	Vendor        string   `json:"dgpu_vendor,omitempty"`
+}
+
+// ParseSupported reads `supergfxctl -s`: `[Integrated, Hybrid, AsusMuxDgpu]`.
+func ParseSupported(out string) []string {
+	out = strings.Trim(strings.TrimSpace(out), "[]")
+	var modes []string
+	for _, f := range strings.Split(out, ",") {
+		if f = strings.TrimSpace(f); f != "" {
+			modes = append(modes, f)
+		}
+	}
+	return modes
+}
+
+// GPU reads supergfxd.
+func (m *Machine) GPU(ctx context.Context) (GPUState, error) {
+	var g GPUState
+	mode, err := m.Run(ctx, "supergfxctl", "-g")
+	if err != nil {
+		return g, vendor("supergfxctl", err)
+	}
+	g.Mode = strings.TrimSpace(mode)
+	if s, err := m.Run(ctx, "supergfxctl", "-s"); err == nil {
+		g.Supported = ParseSupported(s)
+	}
+	if s, err := m.Run(ctx, "supergfxctl", "-S"); err == nil {
+		g.Power = strings.TrimSpace(s)
+	}
+	if s, err := m.Run(ctx, "supergfxctl", "-p"); err == nil {
+		g.PendingAction = strings.TrimSpace(s)
+	}
+	if s, err := m.Run(ctx, "supergfxctl", "-P"); err == nil {
+		g.PendingMode = strings.TrimSpace(s)
+	}
+	if s, err := m.Run(ctx, "supergfxctl", "-V"); err == nil {
+		g.Vendor = strings.TrimSpace(s)
+	}
+	return g, nil
+}
+
+// vendor names a vendor client that is not installed, rather than passing on "executable file not
+// found". asusctl is in the distribution's repositories; supergfxctl is not, and the module keeps it as
+// it was found until the mesh can build packages from the user repository (research 027, question 1).
+func vendor(name string, err error) error {
+	if err == nil {
+		return nil
+	}
+	if notInstalled(err) {
+		switch name {
+		case "supergfxctl":
+			return fmt.Errorf("supergfxctl is not installed: it is not in the distribution's repositories, " +
+				"and this module keeps the copy it finds rather than install one (novox/hq research 027, question 1)")
+		default:
+			return fmt.Errorf("%s is not installed; the module's package resource installs it", name)
+		}
+	}
+	return err
+}
+
+// AsusdConfig is the few settings of asusd's own file that decide what this module's code does. The
+// file is asusd's: it rewrites it whenever a setting changes, so the module reads it and never writes
+// it.
+type AsusdConfig struct {
+	ChargeLimit          *int   `json:"charge_control_end_threshold,omitempty"`
+	ProfileOnAC          string `json:"platform_profile_on_ac,omitempty"`
+	ProfileOnBattery     string `json:"platform_profile_on_battery,omitempty"`
+	ChangesProfileOnAC   *bool  `json:"change_platform_profile_on_ac,omitempty"`
+	ChangesProfileOnBatt *bool  `json:"change_platform_profile_on_battery,omitempty"`
+	ACCommand            string `json:"ac_command,omitempty"`
+	BatteryCommand       string `json:"bat_command,omitempty"`
+	DisablesPowerdOnBatt *bool  `json:"disable_nvidia_powerd_on_battery,omitempty"`
+}
+
+var ronField = regexp.MustCompile(`(?m)^\s{4}([a-z_]+):\s*(.*?),?\s*$`)
+
+// ParseAsusdRon reads the top-level scalar fields of asusd.ron. RON is not a format the mesh
+// speaks; these are one line each, and nothing nested is read.
+func ParseAsusdRon(text string) AsusdConfig {
+	var c AsusdConfig
+	for _, g := range ronField.FindAllStringSubmatch(text, -1) {
+		key, value := g[1], strings.TrimSuffix(strings.TrimSpace(g[2]), ",")
+		unquoted := strings.Trim(value, `"`)
+		boolean := func() *bool { b := value == "true"; return &b }
+		switch key {
+		case "charge_control_end_threshold":
+			if n, err := strconv.Atoi(value); err == nil {
+				c.ChargeLimit = &n
+			}
+		case "platform_profile_on_ac":
+			c.ProfileOnAC = unquoted
+		case "platform_profile_on_battery":
+			c.ProfileOnBattery = unquoted
+		case "change_platform_profile_on_ac":
+			c.ChangesProfileOnAC = boolean()
+		case "change_platform_profile_on_battery":
+			c.ChangesProfileOnBatt = boolean()
+		case "ac_command":
+			c.ACCommand = unquoted
+		case "bat_command":
+			c.BatteryCommand = unquoted
+		case "disable_nvidia_powerd_on_battery":
+			c.DisablesPowerdOnBatt = boolean()
+		}
+	}
+	return c
+}
+
+// Asusd reads asusd's file; nil when it is not there.
+func (m *Machine) Asusd() *AsusdConfig {
+	text := m.read("/etc/asusd/asusd.ron")
+	if text == "" {
+		return nil
+	}
+	c := ParseAsusdRon(text)
+	return &c
+}

modules/asus-zephyrus-g14/cmd/zephyrus/asus_test.go

@@ -0,0 +1,146 @@
+package main
+
+import (
+	"context"
+	"strings"
+	"testing"
+)
+
+// What asusctl 6.4 and supergfxctl 5.2 said on the laptop on 2026-10-04.
+const fanCurveQuiet = `
+Fan curves for Quiet
+
+[
+    (
+        fan: CPU,
+        pwm: (2, 0, 10, 20, 35, 55, 80, 100),
+        temp: (35, 45, 50, 55, 60, 65, 70, 80),
+        enabled: true,
+    ),
+    (
+        fan: GPU,
+        pwm: (0, 0, 10, 20, 35, 65, 90, 115),
+        temp: (35, 45, 50, 55, 60, 65, 70, 80),
+        enabled: false,
+    ),
+]
+`
+
+const asusdRon = `(
+    charge_control_end_threshold: 80,
+    base_charge_control_end_threshold: 0,
+    disable_nvidia_powerd_on_battery: true,
+    ac_command: "supergfxctl -m Hybrid",
+    bat_command: "supergfxctl -m Integrated",
+    platform_profile_linked_epp: true,
+    platform_profile_on_battery: Quiet,
+    change_platform_profile_on_battery: true,
+    platform_profile_on_ac: Balanced,
+    change_platform_profile_on_ac: true,
+    ac_profile_tunings: {
+        Quiet: (
+            enabled: false,
+            group: {},
+        ),
+    },
+)`
+
+func TestAsusctlsAnswersAreRead(t *testing.T) {
+	p, err := ParseProfileGet(profileGetBalanced)
+	if err != nil || p.Active != "Balanced" || p.OnAC != "Balanced" || p.Battery != "Quiet" {
+		t.Fatalf("%+v %v", p, err)
+	}
+	if _, err := ParseProfileGet("something else"); err == nil {
+		t.Fatal("an answer with no profile was read as one")
+	}
+	if l, err := ParseLeds("Current keyboard led brightness: High\n"); err != nil || l != "high" {
+		t.Fatalf("%q %v", l, err)
+	}
+	curves := ParseFanCurves(fanCurveQuiet)
+	if len(curves) != 2 || curves[0].Fan != "CPU" || curves[0].PWM[7] != 100 || curves[0].Temp[0] != 35 || curves[1].Enabled {
+		t.Fatalf("%+v", curves)
+	}
+	if got := ParseSupported("[Integrated, Hybrid, AsusMuxDgpu]\n"); strings.Join(got, ",") != "Integrated,Hybrid,AsusMuxDgpu" {
+		t.Fatalf("%v", got)
+	}
+}
+
+func TestAsusdsFileIsReadForWhatDecidesTheModulesCodeAndNothingNested(t *testing.T) {
+	c := ParseAsusdRon(asusdRon)
+	if *c.ChargeLimit != 80 || c.ProfileOnAC != "Balanced" || c.ProfileOnBattery != "Quiet" ||
+		c.ACCommand != "supergfxctl -m Hybrid" || c.BatteryCommand != "supergfxctl -m Integrated" ||
+		!*c.ChangesProfileOnAC || !*c.DisablesPowerdOnBatt {
+		t.Fatalf("%+v", c)
+	}
+}
+
+func TestAMissingVendorClientIsNamedWithWhyItIsMissing(t *testing.T) {
+	f := newFake(t)
+	f.fails["supergfxctl"] = notFound
+	_, err := f.machine().GPU(context.Background())
+	if err == nil || !strings.Contains(err.Error(), "research 027") {
+		t.Fatalf("%v", err)
+	}
+	f.fails["asusctl"] = notFound
+	_, err = f.machine().Profile(context.Background())
+	if err == nil || !strings.Contains(err.Error(), "package resource installs it") {
+		t.Fatalf("%v", err)
+	}
+}
+
+func TestAGPUModeIsSetOnlyWhenTheMachineSupportsItAndAsusdsSwitchingIsSaid(t *testing.T) {
+	f := newFake(t)
+	f.answers["supergfxctl -g"] = "Hybrid\n"
+	f.answers["supergfxctl -s"] = "[Integrated, Hybrid, AsusMuxDgpu]\n"
+	f.file("/etc/asusd/asusd.ron", asusdRon)
+	m := f.machine()
+	if _, err := GPUModeTool(context.Background(), m, map[string]any{"mode": "Vfio"}); err == nil {
+		t.Fatal("an unsupported mode was accepted")
+	}
+	out, err := GPUModeTool(context.Background(), m, map[string]any{"mode": "integrated"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !f.called("supergfxctl -m Integrated") {
+		t.Fatalf("calls %v", f.calls)
+	}
+	if _, said := out.(map[string]any)["asusd_switches_it"]; !said {
+		t.Fatalf("asusd's own switching of the mode was not said: %+v", out)
+	}
+}
+
+func TestTheChargeLimitIsBoundedAndSetThroughAsusd(t *testing.T) {
+	f := newFake(t)
+	f.answers["asusctl battery info"] = "Current battery charge limit: 60%\n"
+	m := f.machine()
+	for _, bad := range []any{float64(10), float64(101), "x", 55.5} {
+		if _, err := ChargeLimitTool(context.Background(), m, map[string]any{"limit": bad}); err == nil {
+			t.Errorf("limit %v was accepted", bad)
+		}
+	}
+	out, err := ChargeLimitTool(context.Background(), m, map[string]any{"limit": float64(60)})
+	if err != nil || !f.called("asusctl battery limit 60") || out.(map[string]any)["asusd_limit_percent"] != 60 {
+		t.Fatalf("%+v %v %v", out, err, f.calls)
+	}
+}
+
+func TestAProfileSetByToolIsHeldAndAnUnknownOneRefused(t *testing.T) {
+	f := newFake(t)
+	f.onMains()
+	f.answers["asusctl profile get"] = profileGetBalanced
+	m := f.machine()
+	sw := NewSwitcher(m, nil)
+	if _, err := ProfileTool(context.Background(), m, sw, map[string]any{"profile": "Turbo"}); err == nil {
+		t.Fatal("an unknown profile was accepted")
+	}
+	out, err := ProfileTool(context.Background(), m, sw, map[string]any{"profile": "performance", "hold_minutes": float64(30)})
+	if err != nil || !f.called("asusctl profile set Performance") {
+		t.Fatalf("%v %v", err, f.calls)
+	}
+	if _, held := out.(map[string]any)["held_until"]; !held {
+		t.Fatalf("not held: %+v", out)
+	}
+	if r := sw.Report(); r.Held != "Performance" {
+		t.Fatalf("%+v", r)
+	}
+}

modules/asus-zephyrus-g14/cmd/zephyrus/check.go

@@ -0,0 +1,200 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+)
+
+// Check is one thing the module expects of the machine, and whether it holds.
+type Check struct {
+	Name   string `json:"name"`
+	OK     bool   `json:"ok"`
+	Detail string `json:"detail"`
+}
+
+// CheckReport is what zephyrus_check answers. NotChecked says what it did not look at, because a
+// check that reads as clean while skipping something is the predecessor's verifier again.
+type CheckReport struct {
+	Model      string   `json:"model"`
+	Checks     []Check  `json:"checks"`
+	Failing    int      `json:"failing"`
+	NotChecked []string `json:"not_checked"`
+}
+
+var (
+	pacmanVersion  = regexp.MustCompile(`(?m)^Version\s*:\s*(\S+)`)
+	pacmanPackager = regexp.MustCompile(`(?m)^Packager\s*:\s*(.+)$`)
+	nvidiaParam    = regexp.MustCompile(`(?m)^(\w+):\s*(\S+)`)
+)
+
+// ParseNvidiaParams reads /proc/driver/nvidia/params.
+func ParseNvidiaParams(text string) map[string]string {
+	out := map[string]string{}
+	for _, g := range nvidiaParam.FindAllStringSubmatch(text, -1) {
+		out[g[1]] = g[2]
+	}
+	return out
+}
+
+// predecessorProcess finds a running process whose command line names the predecessor's script.
+func (m *Machine) predecessorProcess(name string) (int, bool) {
+	for _, dir := range m.glob("/proc/[0-9]*") {
+		cmd := strings.ReplaceAll(m.read(dir+"/cmdline"), "\x00", " ")
+		if strings.Contains(cmd, "/"+name) && !strings.Contains(cmd, "zephyrus") {
+			var pid int
+			fmt.Sscanf(filepath.Base(dir), "%d", &pid)
+			return pid, true
+		}
+	}
+	return 0, false
+}
+
+func (m *Machine) unitIs(ctx context.Context, verb, unit string) string {
+	out, _ := m.Run(ctx, "systemctl", verb, unit)
+	return strings.TrimSpace(out)
+}
+
+// Check reads every expectation and reports each.
+func (m *Machine) Check(ctx context.Context, sw *Switcher) CheckReport {
+	r := CheckReport{Model: m.Model(), NotChecked: []string{
+		"the fan curves (asusd's own, read them with zephyrus_fan_curves)",
+		"whether the initramfs carries the NVIDIA options (they are read from the running driver instead)",
+		"the vendor keys themselves (press them)",
+	}}
+	add := func(name string, ok bool, format string, a ...any) {
+		r.Checks = append(r.Checks, Check{Name: name, OK: ok, Detail: fmt.Sprintf(format, a...)})
+		if !ok {
+			r.Failing++
+		}
+	}
+	add("model", m.ThisModel(), "the firmware reports %q; this module is for %q", r.Model, ModelFamily)
+
+	// asusctl: present, and from the distribution rather than a local build.
+	if info, err := m.Run(ctx, "pacman", "-Qi", "asusctl"); err != nil {
+		add("asusctl package", false, "not installed: %v", err)
+	} else {
+		v, p := "", ""
+		if g := pacmanVersion.FindStringSubmatch(info); g != nil {
+			v = g[1]
+		}
+		if g := pacmanPackager.FindStringSubmatch(info); g != nil {
+			p = strings.TrimSpace(g[1])
+		}
+		local := p == "Unknown Packager"
+		add("asusctl package", !local, "version %s, packager %s%s", v, p,
+			map[bool]string{true: "; a local build — the distribution's package replaces it at the next upgrade (pacman -S asusctl)", false: ""}[local])
+	}
+	for _, foreign := range []string{"supergfxctl", "triggerhappy"} {
+		_, err := m.Run(ctx, "pacman", "-Q", foreign)
+		add(foreign+" package", err == nil, "%s; not in the distribution's repositories, kept as found (novox/hq research 027, question 1)",
+			map[bool]string{true: "installed", false: "NOT installed"}[err == nil])
+	}
+	for _, unit := range []string{"asusd.service", "supergfxd.service", "triggerhappy.service"} {
+		state := m.unitIs(ctx, "is-active", unit)
+		add(unit, state == "active", "%s", state)
+	}
+	powerd := m.unitIs(ctx, "is-enabled", "nvidia-powerd.service")
+	add("nvidia-powerd.service", powerd == "masked" || powerd == "disabled" || powerd == "" || strings.Contains(powerd, "not-found"),
+		"%s; the module's drop-in keeps it from starting unless the kernel command line says zephyrus.nvidia-powerd", orNone(powerd))
+	wants, _ := m.Run(ctx, "systemctl", "show", "-p", "Wants", "systemd-suspend.service")
+	add("nvidia suspend and resume", strings.Contains(wants, "nvidia-suspend.service") && strings.Contains(wants, "nvidia-resume.service"),
+		"systemd-suspend.service %s", strings.TrimSpace(wants))
+
+	add("touchpad after resume", strings.Contains(wants, "asus-zephyrus-g14-touchpad-resume.service"),
+		"systemd-suspend.service wants asus-zephyrus-g14-touchpad-resume.service: %v (a daemon-reload makes a new drop-in count)",
+		strings.Contains(wants, "asus-zephyrus-g14-touchpad-resume.service"))
+	if uid := m.triggerhappyUID(); uid < 0 {
+		add("triggerhappy as the account", false, "no thd process runs: the vendor keys do nothing")
+	} else {
+		add("triggerhappy as the account", uid == operatorUID(), "thd runs as uid %d; the operator's account is %d (the module's drop-in passes --user)", uid, operatorUID())
+	}
+	refs := m.asUserReferences()
+	add("no as-user", len(refs) == 0, "%s", orNone(map[bool]string{true: "", false: "the predecessor's as-user is still named in " + strings.Join(refs, ", ") +
+		": it su-s to a named person on a guessed display and sources a file of secrets"}[len(refs) == 0]))
+
+	params := ParseNvidiaParams(m.read("/proc/driver/nvidia/params"))
+	if len(params) == 0 {
+		add("nvidia options", false, "the NVIDIA driver is not loaded (no /proc/driver/nvidia/params)")
+	} else {
+		add("nvidia options", params["PreserveVideoMemoryAllocations"] == "1" && params["DynamicPowerManagement"] == "0",
+			"PreserveVideoMemoryAllocations=%s DynamicPowerManagement=%s (want 1 and 0; a change applies when the driver loads again)",
+			params["PreserveVideoMemoryAllocations"], params["DynamicPowerManagement"])
+	}
+
+	for _, b := range m.Batteries() {
+		ok := b.LimitPercent != nil && *b.LimitPercent == ChargeLimitPercent
+		have := "unknown"
+		if b.LimitPercent != nil {
+			have = fmt.Sprintf("%d%%", *b.LimitPercent)
+		}
+		add("charge limit", ok, "%s is %s, the module's is %d%%", b.Name, have, ChargeLimitPercent)
+	}
+
+	if c := m.Asusd(); c != nil && (c.ACCommand != "" || c.BatteryCommand != "") {
+		add("one authority over the GPU mode", false,
+			"asusd runs %q on mains and %q on battery: it switches the GPU mode on every change of power source, "+
+				"so a mode set with zephyrus_gpu_mode lasts until the next one. Clear ac_command and bat_command in /etc/asusd/asusd.ron (asusd's file) to make it the operator's alone",
+			c.ACCommand, c.BatteryCommand)
+	}
+	if out, err := m.Run(ctx, "journalctl", "-b", "-u", "supergfxd.service", "-g", "invalid variant", "-n", "1", "-q", "-o", "cat"); err == nil && strings.TrimSpace(out) != "" {
+		add("supergfxd and logind", false, "supergfxd cannot read logind's sessions this boot (%s): a mode change that needs a logout times out", strings.TrimSpace(out))
+	}
+
+	if pid, ok := m.predecessorProcess("auto-profile"); ok {
+		add("one profile switcher", false, "the predecessor's auto-profile still runs (pid %d) and switches the profile every five seconds; "+
+			"stop it: systemctl --user disable --now auto-profile.service", pid)
+	} else {
+		add("one profile switcher", true, "no predecessor auto-profile is running")
+	}
+	if sw != nil {
+		rep := sw.Report()
+		add("profile switcher", rep.Running, "%s", orNone(firstNonEmpty(rep.Disabled, rep.LastError, "woken by "+rep.Watching)))
+	}
+	if home := os.Getenv("MESH_OPERATOR_HOME"); home != "" {
+		var left []string
+		for _, p := range PredecessorHomeFiles {
+			if _, err := os.Stat(filepath.Join(m.Root, home, p)); err == nil {
+				left = append(left, "~/"+p)
+			}
+		}
+		add("predecessor files in the home", len(left) == 0, "%s", orNone(strings.Join(left, ", ")))
+	} else {
+		r.NotChecked = append(r.NotChecked, "the predecessor's files in the operator's home (MESH_OPERATOR_HOME is not set)")
+	}
+	return r
+}
+
+// PredecessorHomeFiles are what the predecessor placed in the operator's home for this model and this
+// module replaces. The mesh removes nothing it did not make (novox/hq ADR 0182): the operator does,
+// once, and this list is how the check knows.
+var PredecessorHomeFiles = []string{
+	"scripts/auto-profile",
+	".config/systemd/user/auto-profile.service",
+	"scripts/asus-bright",
+	"scripts/asusctl-kbd-bright",
+	"scripts/xrandr-bright",
+	"scripts/media-control",
+	"scripts/xinput-reset-touchpad",
+	".config/i3/scripts/kbd-brightness-notify.sh",
+	"scripts/.screenlayouts/orden-workspaces.sh",
+}
+
+func orNone(s string) string {
+	if strings.TrimSpace(s) == "" {
+		return "none"
+	}
+	return s
+}
+
+func firstNonEmpty(ss ...string) string {
+	for _, s := range ss {
+		if s != "" {
+			return s
+		}
+	}
+	return ""
+}

modules/asus-zephyrus-g14/cmd/zephyrus/display.go

@@ -0,0 +1,202 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"math"
+	"os"
+	"path"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+// MinPanelPercent is the floor a brightness change never goes below: a panel at zero is a black
+// screen that looks like a dead machine, and the keys cannot be seen to bring it back.
+const MinPanelPercent = 1
+
+// Panel is the internal display's backlight.
+type Panel struct {
+	Device  string   `json:"device"`
+	Percent float64  `json:"percent"`
+	Raw     int64    `json:"raw"`
+	Max     int64    `json:"max"`
+	Others  []string `json:"other_backlights,omitempty"`
+}
+
+// panelDevice chooses the backlight that drives the internal panel.
+//
+// **This model registers two.** In hybrid mode the integrated GPU drives the panel (amdgpu_bl1,
+// beneath the eDP connector) and the discrete GPU's driver registers one of its own (nvidia_0) that
+// moves nothing. The predecessor's scripts named amdgpu_bl1 literally, which is right until the GPU
+// mode puts the panel on the other GPU. The one that sits under an eDP connector is the panel's; failing
+// that, the kernel's own preference: firmware, then platform, then raw.
+func (m *Machine) panelDevice() (string, []string, error) {
+	all := m.glob("/sys/class/backlight/*")
+	if len(all) == 0 {
+		return "", nil, fmt.Errorf("this machine has no backlight in /sys/class/backlight")
+	}
+	names := make([]string, 0, len(all))
+	for _, d := range all {
+		names = append(names, path.Base(d))
+	}
+	sort.Strings(names)
+	rank := func(name string) int {
+		dir := "/sys/class/backlight/" + name
+		if target, err := os.Readlink(m.path(dir)); err == nil && strings.Contains(target, "-eDP-") {
+			return 0
+		}
+		switch m.read(dir + "/type") {
+		case "firmware":
+			return 1
+		case "platform":
+			return 2
+		}
+		return 3
+	}
+	best := names[0]
+	for _, n := range names[1:] {
+		if rank(n) < rank(best) {
+			best = n
+		}
+	}
+	var others []string
+	for _, n := range names {
+		if n != best {
+			others = append(others, n)
+		}
+	}
+	return best, others, nil
+}
+
+// PanelBrightness reads the panel.
+func (m *Machine) PanelBrightness() (Panel, error) {
+	dev, others, err := m.panelDevice()
+	if err != nil {
+		return Panel{}, err
+	}
+	dir := "/sys/class/backlight/" + dev
+	raw, ok1 := m.readInt(dir + "/brightness")
+	max, ok2 := m.readInt(dir + "/max_brightness")
+	if !ok1 || !ok2 || max <= 0 {
+		return Panel{}, fmt.Errorf("%s does not say its brightness", dir)
+	}
+	return Panel{Device: dev, Raw: raw, Max: max, Percent: round1(float64(raw) / float64(max) * 100), Others: others}, nil
+}
+
+// PanelTarget turns a request — "40", "40%", "+5", "-10" — into the percentage to set, clamped to
+// [MinPanelPercent, 100].
+func PanelTarget(current float64, request string) (float64, error) {
+	r := strings.TrimSuffix(strings.TrimSpace(request), "%")
+	if r == "" {
+		return 0, fmt.Errorf("panel needs a percentage (40) or a step (+5, -5)")
+	}
+	n, err := strconv.ParseFloat(r, 64)
+	if err != nil || math.IsNaN(n) || math.IsInf(n, 0) {
+		return 0, fmt.Errorf("panel %q is not a percentage or a step", request)
+	}
+	target := n
+	if strings.HasPrefix(r, "+") || strings.HasPrefix(r, "-") {
+		target = current + n
+	}
+	return math.Max(MinPanelPercent, math.Min(100, target)), nil
+}
+
+// SetPanel sets the panel to a percentage.
+func (m *Machine) SetPanel(ctx context.Context, request string) (Panel, error) {
+	p, err := m.PanelBrightness()
+	if err != nil {
+		return p, err
+	}
+	target, err := PanelTarget(p.Percent, request)
+	if err != nil {
+		return p, err
+	}
+	raw := int64(math.Round(target / 100 * float64(p.Max)))
+	if raw < 1 {
+		raw = 1
+	}
+	if err := m.write(ctx, "/sys/class/backlight/"+p.Device+"/brightness", strconv.FormatInt(raw, 10)); err != nil {
+		return p, err
+	}
+	return m.PanelBrightness()
+}
+
+// Keyboard is the keyboard's backlight.
+type Keyboard struct {
+	Device string `json:"device"`
+	Level  string `json:"level"`
+	Value  int64  `json:"value"`
+	Max    int64  `json:"max"`
+}
+
+// KeyboardBrightness reads the keyboard backlight from the kernel.
+func (m *Machine) KeyboardBrightness() (Keyboard, error) {
+	found := m.glob("/sys/class/leds/*kbd_backlight*")
+	if len(found) == 0 {
+		return Keyboard{}, fmt.Errorf("this machine has no keyboard backlight in /sys/class/leds")
+	}
+	dir := found[0]
+	v, ok1 := m.readInt(dir + "/brightness")
+	max, ok2 := m.readInt(dir + "/max_brightness")
+	if !ok1 || !ok2 {
+		return Keyboard{}, fmt.Errorf("%s does not say its brightness", dir)
+	}
+	k := Keyboard{Device: path.Base(dir), Value: v, Max: max}
+	if max == int64(len(KeyboardLevels)-1) && v >= 0 && v <= max {
+		k.Level = KeyboardLevels[v]
+	}
+	return k, nil
+}
+
+// KeyboardTarget turns a request — off/low/med/high, 0-3, "+", "-" — into asusd's level name.
+func KeyboardTarget(current int64, request string) (string, error) {
+	r := strings.ToLower(strings.TrimSpace(request))
+	switch r {
+	case "medium":
+		r = "med"
+	case "+", "up":
+		r = strconv.FormatInt(min64(current+1, int64(len(KeyboardLevels)-1)), 10)
+	case "-", "down":
+		r = strconv.FormatInt(max64(current-1, 0), 10)
+	}
+	for _, l := range KeyboardLevels {
+		if r == l {
+			return l, nil
+		}
+	}
+	if n, err := strconv.Atoi(r); err == nil && n >= 0 && n < len(KeyboardLevels) {
+		return KeyboardLevels[n], nil
+	}
+	return "", fmt.Errorf("keyboard %q is not one of off, low, med, high, 0-3, + or -", request)
+}
+
+// SetKeyboard has asusd set the keyboard backlight, so its own record of the level stays true.
+func (m *Machine) SetKeyboard(ctx context.Context, request string) (Keyboard, error) {
+	k, err := m.KeyboardBrightness()
+	if err != nil {
+		return k, err
+	}
+	level, err := KeyboardTarget(k.Value, request)
+	if err != nil {
+		return k, err
+	}
+	if _, err := m.Run(ctx, "asusctl", "leds", "set", level); err != nil {
+		return k, vendor("asusctl", err)
+	}
+	return m.KeyboardBrightness()
+}
+
+func min64(a, b int64) int64 {
+	if a < b {
+		return a
+	}
+	return b
+}
+
+func max64(a, b int64) int64 {
+	if a > b {
+		return a
+	}
+	return b
+}

modules/asus-zephyrus-g14/cmd/zephyrus/display_test.go

@@ -0,0 +1,91 @@
+package main
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// backlight makes a backlight the way sysfs does: a link from /sys/class/backlight into the device
+// tree, which is where the eDP connector shows.
+func (f *fake) backlight(name, device string, raw, max string) {
+	dev := "/sys/devices/" + device + "/" + name
+	f.file(dev+"/brightness", raw)
+	f.file(dev+"/max_brightness", max)
+	f.file(dev+"/type", "raw")
+	link := filepath.Join(f.root, "/sys/class/backlight", name)
+	os.MkdirAll(filepath.Dir(link), 0o755)
+	if err := os.Symlink(filepath.Join(f.root, dev), link); err != nil {
+		f.t.Fatal(err)
+	}
+}
+
+func TestThePanelIsTheBacklightUnderTheEDPConnectorNotTheDiscreteGPUs(t *testing.T) {
+	f := newFake(t)
+	f.backlight("amdgpu_bl1", "pci0000:00/0000:65:00.0/drm/card1/card1-eDP-1", "199500", "399000")
+	f.backlight("nvidia_0", "pci0000:00/0000:01:00.0/backlight", "100", "100")
+	p, err := f.machine().PanelBrightness()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if p.Device != "amdgpu_bl1" || p.Percent != 50 || len(p.Others) != 1 || p.Others[0] != "nvidia_0" {
+		t.Fatalf("%+v", p)
+	}
+}
+
+func TestAPanelRequestIsAPercentageOrAStepAndNeverGoesDark(t *testing.T) {
+	for _, c := range []struct {
+		cur  float64
+		req  string
+		want float64
+	}{{50, "40", 40}, {50, "40%", 40}, {50, "+5", 55}, {50, "-10", 40}, {3, "-10", 1}, {98, "+5", 100}, {50, "0", 1}} {
+		got, err := PanelTarget(c.cur, c.req)
+		if err != nil || got != c.want {
+			t.Errorf("%v %q: %v %v, want %v", c.cur, c.req, got, err, c.want)
+		}
+	}
+	for _, bad := range []string{"", "bright", "NaN"} {
+		if _, err := PanelTarget(50, bad); err == nil {
+			t.Errorf("%q was accepted", bad)
+		}
+	}
+}
+
+func TestSettingThePanelWritesTheRawValue(t *testing.T) {
+	f := newFake(t)
+	f.backlight("amdgpu_bl1", "card1-eDP-1", "399000", "399000")
+	p, err := f.machine().SetPanel(context.Background(), "25")
+	if err != nil {
+		t.Fatal(err)
+	}
+	raw, _ := os.ReadFile(filepath.Join(f.root, "/sys/devices/card1-eDP-1/amdgpu_bl1/brightness"))
+	if strings.TrimSpace(string(raw)) != "99750" || p.Percent != 25 {
+		t.Fatalf("wrote %q, read back %+v", raw, p)
+	}
+}
+
+func TestTheKeyboardIsSetThroughAsusdByLevel(t *testing.T) {
+	f := newFake(t)
+	f.file("/sys/class/leds/asus::kbd_backlight/brightness", "1")
+	f.file("/sys/class/leds/asus::kbd_backlight/max_brightness", "3")
+	k, err := f.machine().KeyboardBrightness()
+	if err != nil || k.Level != "low" {
+		t.Fatalf("%+v %v", k, err)
+	}
+	if _, err := f.machine().SetKeyboard(context.Background(), "+"); err != nil {
+		t.Fatal(err)
+	}
+	if !f.called("asusctl leds set med") {
+		t.Fatalf("calls: %v", f.calls)
+	}
+	for req, want := range map[string]string{"high": "high", "0": "off", "medium": "med", "-": "off"} {
+		if got, err := KeyboardTarget(1, req); err != nil || got != want {
+			t.Errorf("%q: %q %v", req, got, err)
+		}
+	}
+	if _, err := KeyboardTarget(1, "7"); err == nil {
+		t.Error("level 7 was accepted")
+	}
+}

modules/asus-zephyrus-g14/cmd/zephyrus/helpers_test.go

@@ -0,0 +1,103 @@
+package main
+
+import (
+	"context"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+)
+
+// fake is a machine for a test: a tree standing in for /, and a runner answering from a table and
+// recording every command it was asked to run.
+type fake struct {
+	t       *testing.T
+	root    string
+	mu      sync.Mutex
+	answers map[string]string
+	fails   map[string]error
+	calls   []string
+}
+
+func newFake(t *testing.T) *fake {
+	t.Helper()
+	return &fake{t: t, root: t.TempDir(), answers: map[string]string{}, fails: map[string]error{}}
+}
+
+func (f *fake) machine() *Machine { return &Machine{Root: f.root, Run: f.run} }
+
+func (f *fake) run(_ context.Context, name string, args ...string) (string, error) {
+	line := strings.TrimSpace(name + " " + strings.Join(args, " "))
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.calls = append(f.calls, line)
+	if err, ok := f.fails[line]; ok {
+		return "", err
+	}
+	if out, ok := f.answers[line]; ok {
+		return out, nil
+	}
+	if err, ok := f.fails[name]; ok {
+		return "", err
+	}
+	return "", nil
+}
+
+func (f *fake) called(line string) bool {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	for _, c := range f.calls {
+		if c == line {
+			return true
+		}
+	}
+	return false
+}
+
+func (f *fake) callsLike(prefix string) []string {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	var out []string
+	for _, c := range f.calls {
+		if strings.HasPrefix(c, prefix) {
+			out = append(out, c)
+		}
+	}
+	return out
+}
+
+// file writes a file under the fake root.
+func (f *fake) file(path, content string) {
+	f.t.Helper()
+	full := filepath.Join(f.root, path)
+	if err := os.MkdirAll(filepath.Dir(full), 0o755); err != nil {
+		f.t.Fatal(err)
+	}
+	if err := os.WriteFile(full, []byte(content), 0o644); err != nil {
+		f.t.Fatal(err)
+	}
+}
+
+// supply writes one power supply's attributes.
+func (f *fake) supply(name string, attrs map[string]string) {
+	for k, v := range attrs {
+		f.file("/sys/class/power_supply/"+name+"/"+k, v+"\n")
+	}
+}
+
+// onMains and onBattery are this model's two states as measured on 2026-10-04.
+func (f *fake) onMains() {
+	f.supply("ACAD", map[string]string{"type": "Mains", "online": "1"})
+	f.supply("BAT1", map[string]string{"type": "Battery", "status": "Not charging", "capacity": "80"})
+}
+
+func (f *fake) onBattery() {
+	f.supply("ACAD", map[string]string{"type": "Mains", "online": "0"})
+	f.supply("BAT1", map[string]string{"type": "Battery", "status": "Discharging", "capacity": "79"})
+}
+
+var notFound = &exec.Error{Name: "x", Err: exec.ErrNotFound}
+
+const profileGetBalanced = "Active profile: Balanced\n\nAC profile Balanced\nBattery profile Quiet\n"

modules/asus-zephyrus-g14/cmd/zephyrus/keys.go

@@ -0,0 +1,156 @@
+package main
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+// Key is one custom key on the laptop: what it is, what runs, and where that is defined.
+type Key struct {
+	Key      string `json:"key"`
+	Physical string `json:"physical,omitempty"`
+	When     string `json:"when,omitempty"`
+	Runs     string `json:"runs"`
+	From     string `json:"from"`
+}
+
+// KeysReport is what zephyrus_keys answers.
+type KeysReport struct {
+	Keys     []Key    `json:"keys"`
+	Warnings []string `json:"warnings"`
+	NotRead  []string `json:"not_read"`
+}
+
+// TriggerDir is triggerhappy's directory of trigger files; the module owns one file in it.
+const TriggerDir = "/etc/triggerhappy/triggers.d"
+
+// I3Fragments are the module's own files in i3's include directory, relative to the account's home.
+var I3Fragments = []string{".config/i3/config.d/10-asus.conf", ".config/i3/config.d/20-g14.conf"}
+
+// physicalKeys names the key behind an evdev code, as far as it is known on this model. The media
+// codes are the M4 key and Fn+F4/F5 together; which code is which key was not recorded.
+var physicalKeys = map[string]string{
+	"KEY_PROG1":          "a media key (M4, Fn+F4 or Fn+F5)",
+	"KEY_PROG3":          "a media key (M4, Fn+F4 or Fn+F5)",
+	"KEY_PROG4":          "a media key (M4, Fn+F4 or Fn+F5)",
+	"KEY_BRIGHTNESSDOWN": "Fn+F7",
+	"KEY_BRIGHTNESSUP":   "Fn+F8",
+	"KEY_F21":            "Fn+F10 (touchpad)",
+	"$mod+Shift+s":       "Fn+F6 (screenshot; the firmware sends Super+Shift+S)",
+	"$mod+p":             "Fn+F9 (display; the firmware sends Super+P)",
+}
+
+// firmwareKeys are handled below any configuration file.
+var firmwareKeys = []Key{
+	{Key: "Fn+F2 / Fn+F3", Physical: "keyboard backlight", Runs: "the firmware and asusd; zephyrus-kbd-notify shows the level", From: "firmware"},
+}
+
+var (
+	triggerLine = regexp.MustCompile(`^(\S+)\s+([0-9]+)\s+(.+)$`)
+	i3Bind      = regexp.MustCompile(`^bindsym\s+((?:--\S+\s+)*)(\S+)\s+(.+)$`)
+	i3Exec      = regexp.MustCompile(`^exec(?:_always)?\s+(?:--no-startup-id\s+)?(.+)$`)
+)
+
+var triggerWhen = map[string]string{"0": "released", "1": "pressed", "2": "held (repeat)"}
+
+// Keys lists the laptop's custom keys: every triggerhappy trigger, the module's i3 lines and the keys
+// the firmware handles itself.
+func (m *Machine) Keys() KeysReport {
+	r := KeysReport{Keys: []Key{}, Warnings: []string{}, NotRead: []string{}}
+	seen := map[string][]string{}
+	files := m.glob(TriggerDir + "/*.conf")
+	sort.Strings(files)
+	if len(files) == 0 {
+		r.Warnings = append(r.Warnings, "no trigger file in "+TriggerDir+": the vendor keys do nothing")
+	}
+	for _, f := range files {
+		for _, line := range strings.Split(m.read(f), "\n") {
+			line = strings.TrimSpace(line)
+			if line == "" || strings.HasPrefix(line, "#") {
+				continue
+			}
+			g := triggerLine.FindStringSubmatch(line)
+			if g == nil {
+				continue
+			}
+			r.Keys = append(r.Keys, Key{Key: g[1], Physical: physicalKeys[g[1]], When: triggerWhen[g[2]], Runs: g[3], From: f})
+			id := g[1] + " " + g[2]
+			seen[id] = append(seen[id], f)
+		}
+	}
+	for id, fs := range seen {
+		if len(fs) > 1 {
+			r.Warnings = append(r.Warnings, fmt.Sprintf("%s is bound in %d places (%s): it fires every one", id, len(fs), strings.Join(fs, ", ")))
+		}
+	}
+	home := os.Getenv("MESH_OPERATOR_HOME")
+	if home == "" {
+		r.NotRead = append(r.NotRead, "the module's i3 lines (MESH_OPERATOR_HOME is not set)")
+	}
+	for _, rel := range I3Fragments {
+		if home == "" {
+			break
+		}
+		p := filepath.Join(home, rel)
+		text := m.read(p)
+		if text == "" {
+			r.Warnings = append(r.Warnings, "~/"+rel+" is missing or empty")
+			continue
+		}
+		for _, line := range strings.Split(text, "\n") {
+			line = strings.TrimSpace(line)
+			if g := i3Bind.FindStringSubmatch(line); g != nil {
+				when := "pressed"
+				if strings.Contains(g[1], "--release") {
+					when = "released"
+				}
+				r.Keys = append(r.Keys, Key{Key: g[2], Physical: physicalKeys[g[2]], When: when, Runs: strings.TrimPrefix(strings.TrimPrefix(g[3], "exec "), "--no-startup-id "), From: "~/" + rel})
+			} else if g := i3Exec.FindStringSubmatch(line); g != nil {
+				r.Keys = append(r.Keys, Key{Key: "(session start)", When: "at login", Runs: g[1], From: "~/" + rel})
+			}
+		}
+	}
+	r.Keys = append(r.Keys, firmwareKeys...)
+	sort.Strings(r.Warnings)
+	return r
+}
+
+// asUserReferences finds the predecessor's as-user wrapper still named in a trigger, a udev rule or
+// the module's i3 lines.
+func (m *Machine) asUserReferences() []string {
+	var at []string
+	for _, pattern := range []string{TriggerDir + "/*.conf", "/etc/udev/rules.d/*.rules", "/etc/systemd/system-sleep/*"} {
+		for _, f := range m.glob(pattern) {
+			if strings.Contains(m.read(f), "as-user") {
+				at = append(at, f)
+			}
+		}
+	}
+	sort.Strings(at)
+	return at
+}
+
+// triggerhappyUID is the real user id the running thd has, or -1 when none runs.
+func (m *Machine) triggerhappyUID() int {
+	for _, dir := range m.glob("/proc/[0-9]*") {
+		if strings.TrimSpace(m.read(dir+"/comm")) != "thd" {
+			continue
+		}
+		for _, line := range strings.Split(m.read(dir+"/status"), "\n") {
+			if f := strings.Fields(line); len(f) >= 2 && f[0] == "Uid:" {
+				var uid int
+				if _, err := fmt.Sscanf(f[1], "%d", &uid); err == nil {
+					return uid
+				}
+			}
+		}
+	}
+	return -1
+}
+
+// operatorUID is the account the module's code runs as: the runtime runs it as the operator's.
+var operatorUID = os.Getuid

modules/asus-zephyrus-g14/cmd/zephyrus/keys_test.go

@@ -0,0 +1,106 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func put(t *testing.T, root, p, content string) {
+	t.Helper()
+	full := filepath.Join(root, p)
+	if err := os.MkdirAll(filepath.Dir(full), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(full, []byte(content), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// The module's shipped triggers and i3 lines, read back as keys: what each runs and where.
+func TestKeysListsTriggersI3LinesAndFirmwareKeys(t *testing.T) {
+	f := newFake(t)
+	m := readManifest(t)
+	content := map[string]string{}
+	for _, r := range m.Resources {
+		if c, ok := r["content"].(string); ok {
+			content[r["id"].(string)] = c
+		}
+	}
+	put(t, f.root, TriggerDir+"/asus-g14.conf", content["vendor-keys"])
+	home := "/home/operator"
+	t.Setenv("MESH_OPERATOR_HOME", home)
+	put(t, f.root, home+"/"+I3Fragments[0], content["i3-vendor-keys"])
+	put(t, f.root, home+"/"+I3Fragments[1], content["i3-model"])
+
+	r := f.machine().Keys()
+	got := map[string]Key{}
+	for _, k := range r.Keys {
+		got[k.Key+"|"+k.When] = k
+	}
+	if k := got["KEY_F21|pressed"]; !strings.Contains(k.Runs, "zephyrus-touchpad reset") || k.Physical == "" {
+		t.Errorf("touchpad key: %+v", k)
+	}
+	if k := got["KEY_PROG1|pressed"]; !strings.Contains(k.Runs, "zephyrus-media play-pause") {
+		t.Errorf("media key: %+v", k)
+	}
+	if k := got["$mod+Shift+s|released"]; !strings.Contains(k.Runs, "screenshot") || !strings.Contains(k.Physical, "Fn+F6") {
+		t.Errorf("screenshot key: %+v", k)
+	}
+	if k := got["$mod+p|pressed"]; !strings.Contains(k.Runs, "zephyrus-display order") {
+		t.Errorf("display key: %+v", k)
+	}
+	if k := got["(session start)|at login"]; k.Runs == "" {
+		t.Errorf("no session-start line read")
+	}
+	if k := got["Fn+F2 / Fn+F3|"]; k.From != "firmware" {
+		t.Errorf("firmware keys missing: %+v", r.Keys)
+	}
+	if len(r.Warnings) != 0 || len(r.NotRead) != 0 {
+		t.Errorf("warnings %v, not read %v", r.Warnings, r.NotRead)
+	}
+	if _, err := json.Marshal(r); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// A key bound in two trigger files fires twice, which is said.
+func TestKeysWarnsAboutAKeyInTwoTriggerFiles(t *testing.T) {
+	f := newFake(t)
+	put(t, f.root, TriggerDir+"/asus-g14.conf", "KEY_F21\t1\t/x reset\n")
+	put(t, f.root, TriggerDir+"/old.conf", "KEY_F21\t1\t/y reset\n")
+	t.Setenv("MESH_OPERATOR_HOME", "")
+	r := f.machine().Keys()
+	if len(r.Warnings) != 1 || !strings.Contains(r.Warnings[0], "KEY_F21") || len(r.NotRead) != 1 {
+		t.Errorf("warnings %v, not read %v", r.Warnings, r.NotRead)
+	}
+}
+
+// The check names what still calls as-user, and whether triggerhappy runs as the account.
+func TestCheckFindsAsUserAndTriggerhappysAccount(t *testing.T) {
+	f := newFake(t)
+	put(t, f.root, "/etc/udev/rules.d/91-monitor-hotplug.rules", `RUN+="/x/scripts/as-user setsid wizard"`)
+	put(t, f.root, "/proc/4242/comm", "thd\n")
+	put(t, f.root, "/proc/4242/status", "Name:\tthd\nUid:\t0\t0\t0\t0\n")
+	was := operatorUID
+	operatorUID = func() int { return 1000 }
+	defer func() { operatorUID = was }()
+	t.Setenv("MESH_OPERATOR_HOME", "")
+	r := f.machine().Check(context.Background(), nil)
+	by := map[string]Check{}
+	for _, c := range r.Checks {
+		by[c.Name] = c
+	}
+	if c := by["no as-user"]; c.OK || !strings.Contains(c.Detail, "91-monitor-hotplug.rules") {
+		t.Errorf("as-user: %+v", c)
+	}
+	if c := by["triggerhappy as the account"]; c.OK || !strings.Contains(c.Detail, "uid 0") {
+		t.Errorf("triggerhappy: %+v", c)
+	}
+	if c := by["touchpad after resume"]; c.OK {
+		t.Errorf("resume: %+v", c)
+	}
+}

modules/asus-zephyrus-g14/cmd/zephyrus/machine.go

@@ -0,0 +1,124 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// CommandTimeout bounds every command a tool or the switcher runs: a vendor daemon that hangs on its
+// bus must cost a tool call twenty seconds, never the runtime's thirty.
+const CommandTimeout = 20 * time.Second
+
+// Runner runs one command and answers its standard output. It is injected so that every tool is
+// tested against recorded answers rather than this machine's daemons.
+type Runner func(ctx context.Context, name string, args ...string) (string, error)
+
+// ExecRunner runs a command on the machine, bounded by CommandTimeout. A failure carries what the
+// command said on stderr, because "exit status 1" names nothing.
+func ExecRunner(ctx context.Context, name string, args ...string) (string, error) {
+	ctx, cancel := context.WithTimeout(ctx, CommandTimeout)
+	defer cancel()
+	cmd := exec.CommandContext(ctx, name, args...)
+	var stdout, stderr bytes.Buffer
+	cmd.Stdout, cmd.Stderr = &stdout, &stderr
+	err := cmd.Run()
+	if ctx.Err() == context.DeadlineExceeded {
+		return stdout.String(), fmt.Errorf("%s did not answer within %s", name, CommandTimeout)
+	}
+	if err != nil {
+		said := strings.TrimSpace(stderr.String())
+		if said == "" {
+			said = strings.TrimSpace(stdout.String())
+		}
+		if said != "" {
+			return stdout.String(), fmt.Errorf("%s %s: %w: %s", name, strings.Join(args, " "), err, said)
+		}
+		return stdout.String(), fmt.Errorf("%s %s: %w", name, strings.Join(args, " "), err)
+	}
+	return stdout.String(), nil
+}
+
+// Machine is what the module reads and acts on: a filesystem root (the real one, or a test's tree of
+// /sys and /proc and /etc) and a way to run commands.
+type Machine struct {
+	Root string
+	Run  Runner
+}
+
+// Here is the machine this process runs on.
+func Here() *Machine { return &Machine{Root: "/", Run: ExecRunner} }
+
+func (m *Machine) path(p string) string { return filepath.Join(m.Root, p) }
+
+// read is a file's content, trimmed; "" when it cannot be read.
+func (m *Machine) read(p string) string {
+	b, err := os.ReadFile(m.path(p))
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(string(b))
+}
+
+// readInt is a file holding one integer; ok false when it is absent or not a number.
+func (m *Machine) readInt(p string) (int64, bool) {
+	s := m.read(p)
+	if s == "" {
+		return 0, false
+	}
+	n, err := strconv.ParseInt(s, 10, 64)
+	return n, err == nil
+}
+
+func (m *Machine) glob(pattern string) []string {
+	found, _ := filepath.Glob(m.path(pattern))
+	out := make([]string, 0, len(found))
+	for _, f := range found {
+		rel, err := filepath.Rel(m.Root, f)
+		if err != nil {
+			continue
+		}
+		out = append(out, "/"+filepath.ToSlash(rel))
+	}
+	return out
+}
+
+// write puts a value into a file of the kernel's (a backlight). Where the account may not write it
+// — the udev rule that gives the video group the panel has not run yet — it escalates with `sudo -n`,
+// which never prompts: the operator's account may escalate without one, and when it may not, the
+// tool says so in sudo's words.
+func (m *Machine) write(ctx context.Context, p, value string) error {
+	err := os.WriteFile(m.path(p), []byte(value), 0)
+	if err == nil {
+		return nil
+	}
+	if !errors.Is(err, os.ErrPermission) {
+		return err
+	}
+	if _, serr := m.Run(ctx, "sudo", "-n", "sh", "-c", `printf '%s' "$1" > "$2"`, "sh", value, m.path(p)); serr != nil {
+		return fmt.Errorf("%s is not writable by this account and sudo -n refused: %v", p, serr)
+	}
+	return nil
+}
+
+// notInstalled says a command failed because it is not on this machine at all.
+func notInstalled(err error) bool { return errors.Is(err, exec.ErrNotFound) }
+
+// round to one decimal, for watts and percentages a person reads.
+func round1(f float64) float64 {
+	return float64(int64(f*10+sign(f)*0.5)) / 10
+}
+
+func sign(f float64) float64 {
+	if f < 0 {
+		return -1
+	}
+	return 1
+}

modules/asus-zephyrus-g14/cmd/zephyrus/main.go

@@ -0,0 +1,25 @@
+// The asus-zephyrus-g14 module's Go bundle (novox/hq ADR 0188, ADR 0193, ADR 0198): one process the
+// node's runtime launches, serving the module's tools over MCP on stdio and running its long-running
+// code — the platform-profile switcher — beside them.
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+func main() {
+	m := Here()
+	sw := NewSwitcher(m, func(eventType string, body any) error { return stdio.Emit(eventType, body) })
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	go sw.Run(ctx)
+	// An empty name serves as the module the runtime names (MESH_SERVED_MODULE).
+	if err := stdio.Serve("", Tools(m, sw)); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}

modules/asus-zephyrus-g14/cmd/zephyrus/manifest_test.go

@@ -0,0 +1,110 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sort"
+	"strings"
+	"testing"
+)
+
+type manifest struct {
+	Module    string           `json:"module"`
+	Tools     []string         `json:"tools"`
+	Emits     []string         `json:"emits"`
+	Resources []map[string]any `json:"resources"`
+}
+
+func readManifest(t *testing.T) manifest {
+	t.Helper()
+	raw, err := os.ReadFile("../../module.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var m manifest
+	if err := json.Unmarshal(raw, &m); err != nil {
+		t.Fatal(err)
+	}
+	return m
+}
+
+func TestTheManifestNamesExactlyTheToolsTheBundleServes(t *testing.T) {
+	m := readManifest(t)
+	var served []string
+	for _, tool := range Tools(&Machine{Root: t.TempDir(), Run: newFake(t).run}, nil) {
+		served = append(served, tool.Name)
+	}
+	sort.Strings(served)
+	listed := append([]string(nil), m.Tools...)
+	sort.Strings(listed)
+	if strings.Join(served, ",") != strings.Join(listed, ",") {
+		t.Fatalf("served %v, listed %v", served, listed)
+	}
+	if len(m.Emits) != 1 || m.Emits[0] != "profile.switched" {
+		t.Fatalf("emits %v", m.Emits)
+	}
+}
+
+// The module names the model, never a node, a person or a user id (novox/hq ADR 0112), and every
+// trigger it names a service restart or reload on is one of its own resources.
+func TestTheManifestNamesNoMachineAndItsTriggersExist(t *testing.T) {
+	m := readManifest(t)
+	ids := map[string]bool{}
+	for _, r := range m.Resources {
+		ids[r["id"].(string)] = true
+	}
+	raw, _ := os.ReadFile("../../module.json")
+	for _, banned := range []string{"jochen", "/home/", "/run/user/1000", "\"g14\"", "shanks"} {
+		if strings.Contains(string(raw), banned) {
+			t.Errorf("the manifest says %q", banned)
+		}
+	}
+	for _, r := range m.Resources {
+		for _, key := range []string{"restart-on", "reload-on"} {
+			list, _ := r[key].([]any)
+			for _, id := range list {
+				if !ids[id.(string)] {
+					t.Errorf("%s %s names %v, which is not a resource", r["id"], key, id)
+				}
+			}
+		}
+	}
+}
+
+// Every trigger runs a script the module ships, and every script parses.
+func TestTheVendorKeysRunTheModulesOwnScriptsAndTheyParse(t *testing.T) {
+	m := readManifest(t)
+	var triggers string
+	for _, r := range m.Resources {
+		if r["id"] == "vendor-keys" {
+			triggers = r["content"].(string)
+		}
+	}
+	if triggers == "" {
+		t.Fatal("no vendor-keys resource")
+	}
+	for _, line := range strings.Split(triggers, "\n") {
+		f := strings.Split(line, "\t")
+		if strings.HasPrefix(line, "#") || len(f) < 3 {
+			continue
+		}
+		script := strings.Fields(f[2])[0]
+		local := filepath.Join("../../files/bin", filepath.Base(script))
+		if !strings.HasPrefix(script, "/usr/local/lib/asus-zephyrus-g14/bin/") {
+			t.Errorf("%s runs %s, which the module does not ship", f[0], script)
+		} else if st, err := os.Stat(local); err != nil || st.Mode()&0o111 == 0 {
+			t.Errorf("%s: %s is missing or not executable", f[0], local)
+		}
+	}
+	scripts, _ := filepath.Glob("../../files/bin/*")
+	if len(scripts) == 0 {
+		t.Fatal("no scripts")
+	}
+	for _, s := range scripts {
+		if out, err := exec.Command("bash", "-n", s).CombinedOutput(); err != nil {
+			t.Errorf("%s: %v %s", s, err, out)
+		}
+	}
+}

modules/asus-zephyrus-g14/cmd/zephyrus/policy.go

@@ -0,0 +1,137 @@
+package main
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// The policy, as constants until the mesh has settings a module can read (novox/hq issue 168). The
+// values are the predecessor's, made explicit, and two of its behaviours are changed on purpose:
+//
+//   - **Sustained, not momentary.** The predecessor boosted on one five-second sample above 50 %: a
+//     compile's first second, a browser's tab restore. Here the load must stay above the line for
+//     SustainSamples samples in a row, and below the lower line as long, before the profile moves.
+//   - **Waiting on a disk is not load.** iowait is counted as idle: a machine stalled on its SSD does
+//     not get faster with a higher power limit, only hotter.
+const (
+	ProfileOnBattery = "Quiet"
+	ProfileOnAC      = "Balanced"
+	ProfileUnderLoad = "Performance"
+
+	CPUHighPercent = 50.0 // on mains, sustained at or above this boosts to ProfileUnderLoad
+	CPULowPercent  = 20.0 // and sustained at or below this goes back to ProfileOnAC
+
+	SampleEvery    = 10 * time.Second // CPU is sampled only on mains; on battery nothing is sampled
+	SustainSamples = 3                // 30 s above CPUHighPercent to boost
+	RelaxSamples   = 3                // 30 s below CPULowPercent to relax
+
+	// SafetyRecheck is how often the power source is read when no event has said it changed: the
+	// kernel's event is the trigger, and this only covers one lost across a suspend.
+	SafetyRecheck = 5 * time.Minute
+
+	// DefaultHold is how long a profile chosen through the profile tool is kept before the switcher
+	// may move it again. A change of power source ends a hold at once.
+	DefaultHold = 60 * time.Minute
+
+	// ChargeLimitPercent is the battery charge limit the module asserts through asusd at start.
+	ChargeLimitPercent = 80
+)
+
+// Policy is the switcher's memory of recent load: how many samples in a row were above the upper line
+// or below the lower one, and whether it is boosted.
+type Policy struct {
+	Boosted      bool      `json:"boosted"`
+	Above        int       `json:"samples_above"`
+	Below        int       `json:"samples_below"`
+	Recent       []float64 `json:"recent_cpu_percent"`
+	BoostedSince time.Time `json:"boosted_since,omitempty"`
+}
+
+// Observe takes one CPU sample (busy percent since the previous one) taken on mains.
+func (p *Policy) Observe(cpu float64, at time.Time) {
+	p.Recent = append(p.Recent, round1(cpu))
+	if len(p.Recent) > 6 {
+		p.Recent = p.Recent[len(p.Recent)-6:]
+	}
+	switch {
+	case cpu >= CPUHighPercent:
+		p.Above++
+		p.Below = 0
+		if !p.Boosted && p.Above >= SustainSamples {
+			p.Boosted = true
+			p.BoostedSince = at
+		}
+	case cpu <= CPULowPercent:
+		p.Below++
+		p.Above = 0
+		if p.Boosted && p.Below >= RelaxSamples {
+			p.Boosted = false
+			p.BoostedSince = time.Time{}
+		}
+	default:
+		// Between the lines: no direction is sustained, and the profile stays where it is.
+		p.Above, p.Below = 0, 0
+	}
+}
+
+// Reset forgets the load, for a change of power source.
+func (p *Policy) Reset() { *p = Policy{} }
+
+// Decision is what the switcher would choose, and why.
+type Decision struct {
+	Profile string `json:"profile"`
+	Reason  string `json:"reason"`
+}
+
+// Decide is the policy: battery → ProfileOnBattery; mains → ProfileOnAC, or ProfileUnderLoad while
+// boosted.
+func (p *Policy) Decide(src Source) Decision {
+	if !src.OnAC {
+		return Decision{ProfileOnBattery, "on battery (" + src.Reason + ")"}
+	}
+	if p.Boosted {
+		return Decision{ProfileUnderLoad, fmt.Sprintf("on mains (%s) and CPU load sustained at or above %s%% for %d samples of %s",
+			src.Reason, strconv.FormatFloat(CPUHighPercent, 'f', -1, 64), SustainSamples, SampleEvery)}
+	}
+	return Decision{ProfileOnAC, fmt.Sprintf("on mains (%s), and CPU load not sustained at or above %s%%",
+		src.Reason, strconv.FormatFloat(CPUHighPercent, 'f', -1, 64))}
+}
+
+// CPUTimes is the first line of /proc/stat: total and idle jiffies (iowait counted as idle).
+type CPUTimes struct{ Total, Idle uint64 }
+
+// ParseProcStat reads the aggregate cpu line of /proc/stat.
+func ParseProcStat(text string) (CPUTimes, error) {
+	line := strings.SplitN(text, "\n", 2)[0]
+	f := strings.Fields(line)
+	if len(f) < 6 || f[0] != "cpu" {
+		return CPUTimes{}, fmt.Errorf("/proc/stat does not start with the cpu line")
+	}
+	var t CPUTimes
+	for i, s := range f[1:] {
+		if i >= 8 { // user nice system idle iowait irq softirq steal; guest is already in user
+			break
+		}
+		n, err := strconv.ParseUint(s, 10, 64)
+		if err != nil {
+			return CPUTimes{}, fmt.Errorf("/proc/stat: %v", err)
+		}
+		t.Total += n
+		if i == 3 || i == 4 {
+			t.Idle += n
+		}
+	}
+	return t, nil
+}
+
+// Busy is the percentage of time not idle between two readings.
+func Busy(before, after CPUTimes) (float64, bool) {
+	if after.Total <= before.Total {
+		return 0, false
+	}
+	total := float64(after.Total - before.Total)
+	idle := float64(after.Idle - before.Idle)
+	return (total - idle) / total * 100, true
+}

modules/asus-zephyrus-g14/cmd/zephyrus/power.go

@@ -0,0 +1,180 @@
+package main
+
+import (
+	"path"
+	"sort"
+	"strings"
+)
+
+// Supply is one entry of /sys/class/power_supply as the kernel reports it.
+type Supply struct {
+	Name   string `json:"name"`
+	Type   string `json:"type"`
+	Scope  string `json:"scope,omitempty"`
+	Status string `json:"status,omitempty"`
+	Online *bool  `json:"online,omitempty"`
+}
+
+// Supplies is every power supply the kernel knows, sorted by name.
+func (m *Machine) Supplies() []Supply {
+	var out []Supply
+	for _, dir := range m.glob("/sys/class/power_supply/*") {
+		s := Supply{
+			Name:   path.Base(dir),
+			Type:   m.read(dir + "/type"),
+			Scope:  m.read(dir + "/scope"),
+			Status: m.read(dir + "/status"),
+		}
+		if v, ok := m.readInt(dir + "/online"); ok {
+			on := v == 1
+			s.Online = &on
+		}
+		out = append(out, s)
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
+	return out
+}
+
+// system is a supply that powers this machine. A mouse's or a headset's battery reports scope
+// Device, and it says nothing about whether the laptop is on mains.
+func (s Supply) system() bool { return !strings.EqualFold(s.Scope, "Device") }
+
+// Source is where the machine draws its power from, and why that was concluded.
+type Source struct {
+	OnAC   bool   `json:"on_ac"`
+	Source string `json:"source"`
+	Reason string `json:"reason"`
+}
+
+// PowerSource decides mains or battery.
+//
+// **A battery that says it is discharging wins over any adapter that says it is online.** The
+// predecessor's script took any `online` file reading 1 as mains, and a USB-C port reports `online`
+// for things that do not power the machine. The battery's own status is the one fact that cannot be
+// misread: it discharges exactly when nothing outside is carrying the load. Only when no battery says
+// so are the adapters asked, and a machine with no system battery at all is on mains.
+func PowerSource(supplies []Supply) Source {
+	batteries := 0
+	for _, s := range supplies {
+		if s.Type == "Battery" && s.system() {
+			batteries++
+			if strings.EqualFold(s.Status, "Discharging") {
+				return Source{OnAC: false, Source: "battery", Reason: s.Name + " is discharging"}
+			}
+		}
+	}
+	for _, s := range supplies {
+		if (s.Type == "Mains" || strings.HasPrefix(s.Type, "USB")) && s.system() && s.Online != nil && *s.Online {
+			return Source{OnAC: true, Source: "ac", Reason: s.Name + " (" + s.Type + ") is online"}
+		}
+	}
+	if batteries == 0 {
+		return Source{OnAC: true, Source: "ac", Reason: "this machine has no system battery"}
+	}
+	return Source{OnAC: false, Source: "battery", Reason: "no mains or USB supply is online"}
+}
+
+// Battery is what the battery tool answers.
+type Battery struct {
+	Name           string   `json:"name"`
+	Status         string   `json:"status"`
+	ChargePercent  *int64   `json:"charge_percent,omitempty"`
+	EnergyWh       *float64 `json:"energy_wh,omitempty"`
+	FullWh         *float64 `json:"full_wh,omitempty"`
+	DesignWh       *float64 `json:"design_wh,omitempty"`
+	HealthPercent  *float64 `json:"health_percent,omitempty"`
+	Cycles         *int64   `json:"cycles"`
+	CyclesNote     string   `json:"cycles_note,omitempty"`
+	LimitPercent   *int64   `json:"charge_limit_percent,omitempty"`
+	PowerW         *float64 `json:"power_w,omitempty"`
+	HoursRemaining *float64 `json:"hours_remaining,omitempty"`
+	Technology     string   `json:"technology,omitempty"`
+	Model          string   `json:"model,omitempty"`
+	Manufacturer   string   `json:"manufacturer,omitempty"`
+}
+
+// Batteries reads every system battery.
+func (m *Machine) Batteries() []Battery {
+	var out []Battery
+	for _, s := range m.Supplies() {
+		if s.Type != "Battery" || !s.system() {
+			continue
+		}
+		out = append(out, m.battery(s))
+	}
+	return out
+}
+
+func (m *Machine) battery(s Supply) Battery {
+	dir := "/sys/class/power_supply/" + s.Name
+	b := Battery{
+		Name: s.Name, Status: s.Status,
+		Technology:   m.read(dir + "/technology"),
+		Model:        m.read(dir + "/model_name"),
+		Manufacturer: strings.TrimSpace(m.read(dir + "/manufacturer")),
+	}
+	if v, ok := m.readInt(dir + "/capacity"); ok {
+		b.ChargePercent = &v
+	}
+	// Energy in Wh: energy_* (µWh) where the firmware reports it, else charge_* (µAh) times the
+	// design minimum voltage, which is how upower converts it too.
+	wh := func(energy, charge string) *float64 {
+		if v, ok := m.readInt(dir + "/" + energy); ok {
+			f := round1(float64(v) / 1e6)
+			return &f
+		}
+		c, okc := m.readInt(dir + "/" + charge)
+		volts, okv := m.readInt(dir + "/voltage_min_design")
+		if okc && okv {
+			f := round1(float64(c) * float64(volts) / 1e12)
+			return &f
+		}
+		return nil
+	}
+	b.EnergyWh = wh("energy_now", "charge_now")
+	b.FullWh = wh("energy_full", "charge_full")
+	b.DesignWh = wh("energy_full_design", "charge_full_design")
+	if b.FullWh != nil && b.DesignWh != nil && *b.DesignWh > 0 {
+		h := round1(*b.FullWh / *b.DesignWh * 100)
+		b.HealthPercent = &h
+	}
+	if v, ok := m.readInt(dir + "/cycle_count"); ok && v > 0 {
+		b.Cycles = &v
+	} else {
+		b.CyclesNote = "the firmware does not report a cycle count (it reads 0)"
+	}
+	if v, ok := m.readInt(dir + "/charge_control_end_threshold"); ok {
+		b.LimitPercent = &v
+	}
+	if w := m.batteryWatts(dir); w != nil {
+		b.PowerW = w
+		if strings.EqualFold(s.Status, "Discharging") && b.EnergyWh != nil && *w > 0.5 {
+			h := round1(*b.EnergyWh / *w)
+			b.HoursRemaining = &h
+		}
+	}
+	return b
+}
+
+// batteryWatts is how much the battery is giving or taking, in watts, unsigned: power_now where the
+// firmware reports it, else current times voltage.
+func (m *Machine) batteryWatts(dir string) *float64 {
+	if v, ok := m.readInt(dir + "/power_now"); ok {
+		f := round1(abs(float64(v)) / 1e6)
+		return &f
+	}
+	i, oki := m.readInt(dir + "/current_now")
+	u, oku := m.readInt(dir + "/voltage_now")
+	if oki && oku {
+		f := round1(abs(float64(i)) * float64(u) / 1e12)
+		return &f
+	}
+	return nil
+}
+
+func abs(f float64) float64 {
+	if f < 0 {
+		return -f
+	}
+	return f
+}

modules/asus-zephyrus-g14/cmd/zephyrus/power_test.go

@@ -0,0 +1,73 @@
+package main
+
+import "testing"
+
+func on(b bool) *bool { return &b }
+
+func TestADischargingBatteryWinsOverAnAdapterThatSaysOnline(t *testing.T) {
+	got := PowerSource([]Supply{
+		{Name: "BAT1", Type: "Battery", Status: "Discharging"},
+		{Name: "ucsi-source-psy-USBC000:001", Type: "USB", Scope: "System", Online: on(true)},
+	})
+	if got.OnAC {
+		t.Fatalf("a USB-C port reporting online while the battery discharges was read as mains: %+v", got)
+	}
+}
+
+func TestMainsOnlineIsAC(t *testing.T) {
+	got := PowerSource([]Supply{
+		{Name: "ACAD", Type: "Mains", Online: on(true)},
+		{Name: "BAT1", Type: "Battery", Status: "Not charging"},
+	})
+	if !got.OnAC || got.Reason != "ACAD (Mains) is online" {
+		t.Fatalf("%+v", got)
+	}
+}
+
+func TestAPeripheralsBatteryDecidesNothing(t *testing.T) {
+	got := PowerSource([]Supply{
+		{Name: "hidpp_battery_0", Type: "Battery", Scope: "Device", Status: "Discharging"},
+		{Name: "ACAD", Type: "Mains", Online: on(true)},
+		{Name: "BAT1", Type: "Battery", Status: "Charging"},
+	})
+	if !got.OnAC {
+		t.Fatalf("a mouse's discharging battery put the laptop on battery: %+v", got)
+	}
+}
+
+func TestNoSupplyOnlineWithABatteryIsBatteryAndNoBatteryIsMains(t *testing.T) {
+	if got := PowerSource([]Supply{{Name: "ACAD", Type: "Mains", Online: on(false)}, {Name: "BAT1", Type: "Battery", Status: "Unknown"}}); got.OnAC {
+		t.Fatalf("%+v", got)
+	}
+	if got := PowerSource(nil); !got.OnAC {
+		t.Fatalf("a machine with no battery is on mains: %+v", got)
+	}
+}
+
+func TestTheBatteryIsReadInWattHoursFromChargeAndHealthAgainstDesign(t *testing.T) {
+	f := newFake(t)
+	// The laptop's own battery, as measured: charge_* in µAh, no energy_* and no power_now.
+	f.supply("BAT1", map[string]string{
+		"type": "Battery", "status": "Discharging", "capacity": "80",
+		"charge_now": "3073000", "charge_full": "3865000", "charge_full_design": "4580000",
+		"voltage_min_design": "15939000", "current_now": "1000000", "voltage_now": "16000000",
+		"cycle_count": "0", "charge_control_end_threshold": "80", "manufacturer": "ASUS ",
+	})
+	bs := f.machine().Batteries()
+	if len(bs) != 1 {
+		t.Fatalf("%+v", bs)
+	}
+	b := bs[0]
+	if *b.EnergyWh != 49 || *b.FullWh != 61.6 || *b.DesignWh != 73 || *b.HealthPercent != 84.4 {
+		t.Fatalf("energy %v full %v design %v health %v", *b.EnergyWh, *b.FullWh, *b.DesignWh, *b.HealthPercent)
+	}
+	if b.Cycles != nil || b.CyclesNote == "" {
+		t.Fatal("a cycle count of 0 is the firmware not reporting one, and said so")
+	}
+	if *b.LimitPercent != 80 || *b.PowerW != 16 || b.HoursRemaining == nil || *b.HoursRemaining != 3.1 {
+		t.Fatalf("limit %v power %v hours %v", *b.LimitPercent, *b.PowerW, b.HoursRemaining)
+	}
+	if b.Manufacturer != "ASUS" {
+		t.Fatalf("manufacturer %q", b.Manufacturer)
+	}
+}

modules/asus-zephyrus-g14/cmd/zephyrus/switcher.go

@@ -0,0 +1,303 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+)
+
+// The module's long-running code (novox/hq ADR 0198): the profile switcher, launched with the tools
+// by the node's runtime and running beside them in the same process.
+//
+// It replaces the predecessor's `auto-profile`, a user unit that woke every five seconds for ever —
+// read the adapters, read /proc/stat, maybe call asusctl — on battery too, where its only possible
+// answer was the one it had already given. Here the kernel's power-supply event is the trigger; the
+// CPU is sampled only on mains, where the answer depends on it; and on battery the process sleeps
+// until the adapter comes back.
+//
+// **It acts on a change of its decision, never to restore one.** A profile chosen by hand — the
+// vendor's profile key, asusctl in a terminal, the profile tool — stays until the power source
+// changes or the load crosses a line. The predecessor re-asserted its choice every five seconds and so
+// made the profile key useless on battery.
+
+// Emitter publishes an event as the module; nil when the process is not under the runtime.
+type Emitter func(eventType string, body any) error
+
+// Switcher is the switcher's state, shared with the tools that report it.
+type Switcher struct {
+	m    *Machine
+	now  func() time.Time
+	emit Emitter
+
+	mu        sync.Mutex
+	policy    Policy
+	source    *Source
+	decision  *Decision
+	applied   string
+	appliedAt time.Time
+	lastError string
+	holdUntil time.Time
+	holdOf    string
+	watching  string
+	cpuPrev   *CPUTimes
+	disabled  string
+	asserted  []string
+}
+
+func NewSwitcher(m *Machine, emit Emitter) *Switcher {
+	return &Switcher{m: m, now: time.Now, emit: emit}
+}
+
+// Model is the machine's product family as its firmware reports it.
+func (m *Machine) Model() string { return m.read("/sys/class/dmi/id/product_family") }
+
+// ModelFamily is the family this module is written for.
+const ModelFamily = "ROG Zephyrus G14"
+
+// ThisModel says whether the machine is the model this module is written for.
+func (m *Machine) ThisModel() bool { return strings.EqualFold(m.Model(), ModelFamily) }
+
+// sampleCPU reads /proc/stat and answers the busy percentage since the previous reading.
+func (s *Switcher) sampleCPU() (float64, bool) {
+	t, err := ParseProcStat(s.m.read("/proc/stat"))
+	if err != nil {
+		return 0, false
+	}
+	prev := s.cpuPrev
+	s.cpuPrev = &t
+	if prev == nil {
+		return 0, false
+	}
+	return Busy(*prev, t)
+}
+
+// Evaluate reads the power source, takes a CPU sample when asked and on mains, decides, and applies
+// the decision when it changed. It is the whole of one wake-up and what the tests drive.
+func (s *Switcher) Evaluate(ctx context.Context, sample bool) {
+	if body := s.evaluate(ctx, sample); body != nil && s.emit != nil {
+		// Outside the lock: publishing waits for the bus, and the tools that report the switcher
+		// must not wait with it.
+		if err := s.emit("profile.switched", body); err != nil {
+			fmt.Fprintf(os.Stderr, "profile.switched not published: %v\n", err)
+		}
+	}
+}
+
+// evaluate is Evaluate under the lock; it answers the event to publish when it switched.
+func (s *Switcher) evaluate(ctx context.Context, sample bool) map[string]any {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.disabled != "" {
+		return nil
+	}
+	src := PowerSource(s.m.Supplies())
+	now := s.now()
+	first := s.source == nil
+	if first || s.source.OnAC != src.OnAC {
+		// A new power source: what was learnt about load on the other one says nothing here, and a
+		// hold was for the source it was asked on.
+		s.policy.Reset()
+		s.cpuPrev = nil
+		s.holdUntil = time.Time{}
+		s.holdOf = ""
+		s.sampleCPU() // the first reading on this source, so the next sample is a difference
+	} else if sample && src.OnAC {
+		if busy, ok := s.sampleCPU(); ok {
+			s.policy.Observe(busy, now)
+		}
+	}
+	s.source = &src
+	d := s.policy.Decide(src)
+	s.decision = &d
+	// **Starting is not a reason to switch.** The runtime starts this process on every push that
+	// changes a bundle; at boot and at every change of power source asusd has already applied its own
+	// profile for the source, which AssertVendorSettings made the policy's. So the first decision is
+	// taken as applied, and a profile someone chose by hand survives a push.
+	if first {
+		s.applied = d.Profile
+		return nil
+	}
+	// Compared with what the switcher itself last applied, never with the profile in force: a profile
+	// someone chose by hand is not a reason to act, a new decision is.
+	if d.Profile == s.applied || now.Before(s.holdUntil) {
+		return nil
+	}
+	from := s.applied
+	if err := s.m.SetProfile(ctx, d.Profile); err != nil {
+		s.lastError = err.Error() // and tried again at the next wake-up, since applied did not move
+		return nil
+	}
+	s.lastError = ""
+	s.applied, s.appliedAt = d.Profile, now
+	body := map[string]any{"profile": d.Profile, "reason": d.Reason, "source": src.Source}
+	if from != "" {
+		body["from"] = from
+	}
+	return body
+}
+
+// Hold keeps a profile chosen through the tool for a while: the switcher does not move it until the
+// hold ends or the power source changes.
+func (s *Switcher) Hold(profile string, d time.Duration) time.Time {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if d <= 0 {
+		s.holdUntil, s.holdOf = time.Time{}, ""
+		return time.Time{}
+	}
+	s.holdUntil, s.holdOf = s.now().Add(d), profile
+	return s.holdUntil
+}
+
+// Run is the switcher's life: assert asusd's settings once, then wake on each power-supply event, on
+// each CPU sample while on mains, and at SafetyRecheck otherwise.
+func (s *Switcher) Run(ctx context.Context) {
+	defer func() {
+		if r := recover(); r != nil {
+			s.mu.Lock()
+			s.disabled = fmt.Sprintf("the switcher stopped on a fault: %v", r)
+			s.mu.Unlock()
+			fmt.Fprintln(os.Stderr, s.disabled)
+		}
+	}()
+	if !s.m.ThisModel() {
+		s.mu.Lock()
+		s.disabled = fmt.Sprintf("this machine reports %q, not %q: the switcher does not act on another model",
+			s.m.Model(), ModelFamily)
+		s.mu.Unlock()
+		fmt.Fprintln(os.Stderr, s.disabled)
+		return
+	}
+	s.AssertVendorSettings(ctx)
+
+	events, err := listenPowerSupply(ctx)
+	s.mu.Lock()
+	if err != nil {
+		s.watching = "polling every " + SampleEvery.String() + ": " + err.Error()
+	} else {
+		s.watching = "the kernel's power-supply events"
+	}
+	s.mu.Unlock()
+
+	s.Evaluate(ctx, false)
+	timer := time.NewTimer(s.interval(err != nil))
+	defer timer.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case _, open := <-events:
+			if !open {
+				events = nil
+				s.mu.Lock()
+				s.watching = "polling every " + SampleEvery.String() + ": the uevent socket closed"
+				s.mu.Unlock()
+				err = fmt.Errorf("closed")
+				continue
+			}
+			// Settle: an adapter change arrives as several events within a moment.
+			time.Sleep(time.Second)
+			s.Evaluate(ctx, false)
+		case <-timer.C:
+			s.Evaluate(ctx, true)
+			timer.Reset(s.interval(err != nil))
+		}
+	}
+}
+
+// interval is how long to sleep: a CPU sample's period on mains (or with no events to wake on), the
+// safety recheck on battery.
+func (s *Switcher) interval(polling bool) time.Duration {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if polling || s.source == nil || s.source.OnAC {
+		return SampleEvery
+	}
+	return SafetyRecheck
+}
+
+// AssertVendorSettings puts asusd's own settings where the module wants them, once at start: the
+// battery charge limit, and the profiles asusd itself switches to on mains and on battery, so that the
+// vendor daemon's own switching and this module's never disagree. Each is read first and set only if
+// it differs. A value changed later with a tool stands until the next start.
+func (s *Switcher) AssertVendorSettings(ctx context.Context) []string {
+	var said []string
+	if limit, err := s.m.ChargeLimit(ctx); err != nil {
+		said = append(said, "charge limit not read: "+err.Error())
+	} else if limit != ChargeLimitPercent {
+		if _, err := s.m.Run(ctx, "asusctl", "battery", "limit", strconv.Itoa(ChargeLimitPercent)); err != nil {
+			said = append(said, "charge limit not set: "+vendor("asusctl", err).Error())
+		} else {
+			said = append(said, fmt.Sprintf("charge limit %d%% → %d%%", limit, ChargeLimitPercent))
+		}
+	} else {
+		said = append(said, fmt.Sprintf("charge limit already %d%%", ChargeLimitPercent))
+	}
+	p, err := s.m.Profile(ctx)
+	if err != nil {
+		said = append(said, "asusd's profiles not read: "+err.Error())
+	} else {
+		for _, want := range []struct{ flag, have, want, what string }{
+			{"-a", p.OnAC, ProfileOnAC, "on mains"},
+			{"-b", p.Battery, ProfileOnBattery, "on battery"},
+		} {
+			if want.have == "" || strings.EqualFold(want.have, want.want) {
+				continue
+			}
+			if _, err := s.m.Run(ctx, "asusctl", "profile", "set", want.flag, want.want); err != nil {
+				said = append(said, "asusd's profile "+want.what+" not set: "+err.Error())
+			} else {
+				said = append(said, fmt.Sprintf("asusd's profile %s %s → %s", want.what, want.have, want.want))
+			}
+		}
+	}
+	s.mu.Lock()
+	s.asserted = said
+	s.mu.Unlock()
+	for _, line := range said {
+		fmt.Fprintln(os.Stderr, line)
+	}
+	return said
+}
+
+// SwitcherReport is the switcher's state as the profile-policy tool shows it.
+type SwitcherReport struct {
+	Running         bool       `json:"running"`
+	Disabled        string     `json:"disabled,omitempty"`
+	Watching        string     `json:"woken_by,omitempty"`
+	Source          *Source    `json:"source,omitempty"`
+	Decision        *Decision  `json:"decision,omitempty"`
+	Load            Policy     `json:"load"`
+	LastApplied     string     `json:"last_applied,omitempty"`
+	LastAppliedAt   *time.Time `json:"last_applied_at,omitempty"`
+	LastError       string     `json:"last_error,omitempty"`
+	HeldUntil       *time.Time `json:"held_until,omitempty"`
+	Held            string     `json:"held_profile,omitempty"`
+	AssertedAtStart []string   `json:"asserted_at_start,omitempty"`
+}
+
+func (s *Switcher) Report() SwitcherReport {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	r := SwitcherReport{
+		Running: s.watching != "" && s.disabled == "", Disabled: s.disabled, Watching: s.watching,
+		Source: s.source, Decision: s.decision, Load: s.policy, LastApplied: s.applied,
+		LastAppliedAt: when(s.appliedAt), LastError: s.lastError, AssertedAtStart: s.asserted,
+	}
+	if s.now().Before(s.holdUntil) {
+		r.HeldUntil, r.Held = when(s.holdUntil), s.holdOf
+	}
+	return r
+}
+
+// when is a time for a report: absent rather than the zero time.
+func when(t time.Time) *time.Time {
+	if t.IsZero() {
+		return nil
+	}
+	return &t
+}

modules/asus-zephyrus-g14/cmd/zephyrus/switcher_test.go

@@ -0,0 +1,190 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"strconv"
+	"testing"
+	"time"
+)
+
+func TestTheLoadMustBeSustainedToBoostAndToRelaxAndBetweenTheLinesNothingMoves(t *testing.T) {
+	var p Policy
+	at := time.Now()
+	mains := Source{OnAC: true, Reason: "ACAD (Mains) is online"}
+	for i := 0; i < SustainSamples-1; i++ {
+		p.Observe(90, at)
+	}
+	if p.Decide(mains).Profile != ProfileOnAC {
+		t.Fatal("boosted before the load was sustained")
+	}
+	p.Observe(35, at) // between the lines breaks the run
+	p.Observe(90, at)
+	if p.Boosted {
+		t.Fatal("a broken run still counted")
+	}
+	for i := 0; i < SustainSamples; i++ {
+		p.Observe(CPUHighPercent, at)
+	}
+	if d := p.Decide(mains); d.Profile != ProfileUnderLoad {
+		t.Fatalf("%+v", d)
+	}
+	p.Observe(35, at)
+	if !p.Boosted {
+		t.Fatal("load between the lines relaxed the boost")
+	}
+	for i := 0; i < RelaxSamples; i++ {
+		p.Observe(5, at)
+	}
+	if p.Decide(mains).Profile != ProfileOnAC {
+		t.Fatal("did not relax after a sustained low")
+	}
+	p.Boosted = true
+	if d := p.Decide(Source{OnAC: false, Reason: "BAT1 is discharging"}); d.Profile != ProfileOnBattery {
+		t.Fatalf("battery: %+v", d)
+	}
+}
+
+func TestIOWaitIsIdle(t *testing.T) {
+	a, err := ParseProcStat("cpu  100 0 100 700 100 0 0 0 0 0\ncpu0 1 2 3\n")
+	if err != nil {
+		t.Fatal(err)
+	}
+	b, _ := ParseProcStat("cpu  150 0 150 700 200 0 0 0 0 0\n")
+	busy, ok := Busy(a, b)
+	if !ok || busy != 50 {
+		t.Fatalf("%v %v", busy, ok)
+	}
+	if _, ok := Busy(b, b); ok {
+		t.Fatal("no time passed and a load was answered")
+	}
+	if _, err := ParseProcStat("intr 1 2"); err == nil {
+		t.Fatal("a file without the cpu line was read")
+	}
+}
+
+func switcherOn(t *testing.T) (*fake, *Switcher, *[]map[string]any) {
+	f := newFake(t)
+	f.onMains()
+	f.file("/proc/stat", "cpu  0 0 0 0 0 0 0 0\n")
+	var emitted []map[string]any
+	sw := NewSwitcher(f.machine(), func(_ string, body any) error {
+		emitted = append(emitted, body.(map[string]any))
+		return nil
+	})
+	return f, sw, &emitted
+}
+
+func TestStartingIsNotAReasonToSwitch(t *testing.T) {
+	f, sw, emitted := switcherOn(t)
+	sw.Evaluate(context.Background(), false)
+	if calls := f.callsLike("asusctl profile set"); len(calls) != 0 || len(*emitted) != 0 {
+		t.Fatalf("the first decision acted: %v %v", calls, *emitted)
+	}
+}
+
+func TestAChangeOfPowerSourceSwitchesOnceAndPublishesIt(t *testing.T) {
+	f, sw, emitted := switcherOn(t)
+	ctx := context.Background()
+	sw.Evaluate(ctx, false)
+	f.onBattery()
+	sw.Evaluate(ctx, false)
+	sw.Evaluate(ctx, true) // nothing changed: nothing done, and on battery nothing sampled
+	if calls := f.callsLike("asusctl profile set"); len(calls) != 1 || calls[0] != "asusctl profile set Quiet" {
+		t.Fatalf("%v", calls)
+	}
+	if len(*emitted) != 1 || (*emitted)[0]["profile"] != "Quiet" || (*emitted)[0]["from"] != "Balanced" {
+		t.Fatalf("%v", *emitted)
+	}
+	f.onMains()
+	sw.Evaluate(ctx, false)
+	if calls := f.callsLike("asusctl profile set"); len(calls) != 2 || calls[1] != "asusctl profile set Balanced" {
+		t.Fatalf("%v", calls)
+	}
+}
+
+func TestSustainedLoadOnMainsBoostsFromSamples(t *testing.T) {
+	f, sw, _ := switcherOn(t)
+	ctx := context.Background()
+	sw.Evaluate(ctx, false)
+	var user int
+	for i := 1; i <= SustainSamples; i++ {
+		user += 90
+		f.file("/proc/stat", "cpu  "+itoa(user)+" 0 0 "+itoa(i*10)+" 0 0 0 0\n")
+		sw.Evaluate(ctx, true)
+	}
+	if !f.called("asusctl profile set Performance") {
+		t.Fatalf("%v", f.calls)
+	}
+}
+
+func TestAHoldKeepsTheProfileUntilItEndsAndAFailureIsTriedAgain(t *testing.T) {
+	f, sw, _ := switcherOn(t)
+	ctx := context.Background()
+	now := time.Now()
+	sw.now = func() time.Time { return now }
+	sw.Evaluate(ctx, false)
+	f.onBattery()
+	sw.Evaluate(ctx, false) // source change ends any hold; switches to Quiet
+	sw.Hold("Performance", time.Hour)
+	f.fails["asusctl profile set Balanced"] = errors.New("asusd is restarting")
+	f.onMains()
+	sw.Evaluate(ctx, false) // a change of source: the hold ends, the switch is attempted and fails
+	if r := sw.Report(); r.LastError == "" || r.Held != "" {
+		t.Fatalf("%+v", r)
+	}
+	delete(f.fails, "asusctl profile set Balanced")
+	sw.Evaluate(ctx, false)
+	if r := sw.Report(); r.LastApplied != "Balanced" || r.LastError != "" {
+		t.Fatalf("not tried again: %+v", r)
+	}
+	// A hold on the same source keeps a new decision from acting until it ends.
+	sw.Hold("Quiet", time.Hour)
+	sw.policy.Boosted = true
+	sw.Evaluate(ctx, false)
+	if f.called("asusctl profile set Performance") {
+		t.Fatal("switched during a hold")
+	}
+	now = now.Add(2 * time.Hour)
+	sw.Evaluate(ctx, false)
+	if !f.called("asusctl profile set Performance") {
+		t.Fatal("did not act once the hold ended")
+	}
+}
+
+func TestAsusdsSettingsAreSetOnlyWhereTheyDiffer(t *testing.T) {
+	f := newFake(t)
+	f.answers["asusctl battery info"] = "Current battery charge limit: 100%\n"
+	f.answers["asusctl profile get"] = "Active profile: Balanced\nAC profile Performance\nBattery profile Quiet\n"
+	sw := NewSwitcher(f.machine(), nil)
+	sw.AssertVendorSettings(context.Background())
+	if !f.called("asusctl battery limit 80") || !f.called("asusctl profile set -a Balanced") || f.called("asusctl profile set -b Quiet") {
+		t.Fatalf("%v", f.calls)
+	}
+}
+
+func TestTheSwitcherDoesNotActOnAnotherModel(t *testing.T) {
+	f := newFake(t)
+	f.file("/sys/class/dmi/id/product_family", "ROG Strix\n")
+	sw := NewSwitcher(f.machine(), nil)
+	done := make(chan struct{})
+	go func() { sw.Run(context.Background()); close(done) }()
+	select {
+	case <-done:
+	case <-time.After(2 * time.Second):
+		t.Fatal("the switcher ran on another model")
+	}
+	if r := sw.Report(); r.Running || r.Disabled == "" || len(f.calls) != 0 {
+		t.Fatalf("%+v %v", r, f.calls)
+	}
+}
+
+func TestOnlyPowerSupplyUeventsWake(t *testing.T) {
+	yes := []byte("change@/devices/LNXSYSTM:00/ACPI0003:00/power_supply/ACAD\x00ACTION=change\x00SUBSYSTEM=power_supply\x00POWER_SUPPLY_ONLINE=0\x00")
+	no := []byte("change@/devices/virtual/net/wlan0\x00ACTION=change\x00SUBSYSTEM=net\x00")
+	if !powerSupplyEvent(yes) || powerSupplyEvent(no) {
+		t.Fatal("the uevent filter")
+	}
+}
+
+func itoa(n int) string { return strconv.Itoa(n) }

modules/asus-zephyrus-g14/cmd/zephyrus/thermals.go

@@ -0,0 +1,168 @@
+package main
+
+import (
+	"context"
+	"path"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+// Sensor is one temperature, fan or power reading from hwmon.
+type Sensor struct {
+	Chip  string  `json:"chip"`
+	Label string  `json:"label"`
+	Value float64 `json:"value"`
+}
+
+// DGPU is the discrete GPU as the PCI bus and its driver see it.
+type DGPU struct {
+	Address string   `json:"pci_address"`
+	Runtime string   `json:"runtime_status"`
+	Name    string   `json:"name,omitempty"`
+	TempC   *float64 `json:"temp_c,omitempty"`
+	PowerW  *float64 `json:"power_w,omitempty"`
+	PState  string   `json:"pstate,omitempty"`
+	Note    string   `json:"note,omitempty"`
+}
+
+// hwmon reads every hwmon reading of one kind: "temp" (°C), "fan" (RPM) or "power" (W).
+func (m *Machine) hwmon(kind string) []Sensor {
+	var out []Sensor
+	for _, dir := range m.glob("/sys/class/hwmon/hwmon*") {
+		chip := m.read(dir + "/name")
+		inputs := m.glob(dir + "/" + kind + "*_input")
+		if kind == "power" {
+			inputs = append(inputs, m.glob(dir+"/power*_average")...)
+		}
+		for _, in := range inputs {
+			v, ok := m.readInt(in)
+			if !ok {
+				continue
+			}
+			base := path.Base(in)
+			stem := base[:strings.LastIndex(base, "_")]
+			label := m.read(dir + "/" + stem + "_label")
+			if label == "" {
+				label = base
+			} else if strings.HasSuffix(base, "_average") {
+				label += " (average)"
+			}
+			value := float64(v)
+			switch kind {
+			case "temp":
+				value = round1(value / 1000)
+			case "power":
+				value = round1(value / 1e6)
+			}
+			out = append(out, Sensor{Chip: chip, Label: label, Value: value})
+		}
+	}
+	sort.Slice(out, func(i, j int) bool {
+		if out[i].Chip != out[j].Chip {
+			return out[i].Chip < out[j].Chip
+		}
+		return out[i].Label < out[j].Label
+	})
+	return out
+}
+
+// dgpu finds the NVIDIA display controller and, only when it is already awake, asks its driver for
+// its temperature and draw. **Asking wakes it**: nvidia-smi brings a suspended GPU out of D3, which
+// is the power a reading of power draw should not cost.
+func (m *Machine) dgpu(ctx context.Context) *DGPU {
+	for _, dir := range m.glob("/sys/bus/pci/devices/*") {
+		if m.read(dir+"/vendor") != "0x10de" || !strings.HasPrefix(m.read(dir+"/class"), "0x03") {
+			continue
+		}
+		g := &DGPU{Address: path.Base(dir), Runtime: m.read(dir + "/power/runtime_status")}
+		if g.Runtime != "active" {
+			g.Note = "the discrete GPU is " + g.Runtime + "; not woken to be read"
+			return g
+		}
+		out, err := m.Run(ctx, "nvidia-smi", "--query-gpu=name,temperature.gpu,power.draw,pstate", "--format=csv,noheader,nounits")
+		if err != nil {
+			g.Note = "nvidia-smi: " + err.Error()
+			return g
+		}
+		f := strings.Split(strings.TrimSpace(strings.SplitN(out, "\n", 2)[0]), ",")
+		if len(f) >= 4 {
+			g.Name = strings.TrimSpace(f[0])
+			if t, err := strconv.ParseFloat(strings.TrimSpace(f[1]), 64); err == nil {
+				g.TempC = &t
+			}
+			if w, err := strconv.ParseFloat(strings.TrimSpace(f[2]), 64); err == nil {
+				w = round1(w)
+				g.PowerW = &w
+			}
+			g.PState = strings.TrimSpace(f[3])
+		}
+		return g
+	}
+	return nil
+}
+
+// Thermals is what the thermals tool answers.
+type Thermals struct {
+	Temperatures []Sensor `json:"temperatures_c"`
+	Fans         []Sensor `json:"fans_rpm"`
+	DGPU         *DGPU    `json:"dgpu,omitempty"`
+	Profile      string   `json:"platform_profile,omitempty"`
+	Hottest      *Sensor  `json:"hottest,omitempty"`
+}
+
+func (m *Machine) Thermals(ctx context.Context) Thermals {
+	t := Thermals{Temperatures: m.hwmon("temp"), Fans: m.hwmon("fan"), DGPU: m.dgpu(ctx),
+		Profile: m.read("/sys/firmware/acpi/platform_profile")}
+	if t.Temperatures == nil {
+		t.Temperatures = []Sensor{}
+	}
+	if t.Fans == nil {
+		t.Fans = []Sensor{}
+	}
+	for i := range t.Temperatures {
+		if t.Hottest == nil || t.Temperatures[i].Value > t.Hottest.Value {
+			h := t.Temperatures[i]
+			t.Hottest = &h
+		}
+	}
+	return t
+}
+
+// PowerDraw is what the power-draw tool answers.
+type PowerDraw struct {
+	Source      Source   `json:"source"`
+	BatteryW    *float64 `json:"battery_w,omitempty"`
+	BatteryFlow string   `json:"battery_flow,omitempty"`
+	CPUPackageW *float64 `json:"apu_package_w,omitempty"`
+	DGPU        *DGPU    `json:"dgpu,omitempty"`
+	Note        string   `json:"note"`
+}
+
+func (m *Machine) PowerDraw(ctx context.Context) PowerDraw {
+	p := PowerDraw{Source: PowerSource(m.Supplies()), DGPU: m.dgpu(ctx),
+		Note: "on battery, battery_w is what the whole machine draws; on mains it is only what the battery takes or gives"}
+	for _, b := range m.Batteries() {
+		if b.PowerW != nil {
+			w := *b.PowerW
+			p.BatteryW = &w
+			switch strings.ToLower(b.Status) {
+			case "discharging":
+				p.BatteryFlow = "discharging"
+			case "charging":
+				p.BatteryFlow = "charging"
+			default:
+				p.BatteryFlow = strings.ToLower(b.Status)
+			}
+			break
+		}
+	}
+	// The integrated GPU's hwmon reports the whole APU's package power (PPT) on this model.
+	for _, s := range m.hwmon("power") {
+		if s.Chip == "amdgpu" && s.Label == "PPT" {
+			w := s.Value
+			p.CPUPackageW = &w
+		}
+	}
+	return p
+}

modules/asus-zephyrus-g14/cmd/zephyrus/tools.go

@@ -0,0 +1,315 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"math"
+	"strconv"
+	"strings"
+	"time"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+// Tools is the module's tools, over one machine and its switcher.
+func Tools(m *Machine, sw *Switcher) []stdio.Tool {
+	ctx := context.Background
+	return []stdio.Tool{
+		{
+			Name: "zephyrus_brightness",
+			Description: "Read or set the internal panel's and the keyboard's backlight. With no argument, reads both. " +
+				"panel is a percentage (40) or a step (+5, -10), never below 1 %; keyboard is off, low, med, high, 0-3, + or -.",
+			Input: map[string]any{
+				"panel":    map[string]any{"type": "string", "description": "percentage or step, e.g. 40, +5, -10"},
+				"keyboard": map[string]any{"type": "string", "description": "off, low, med, high, 0-3, + or -"},
+			},
+			Run: func(args map[string]any) (any, error) {
+				out := map[string]any{}
+				if p := str(args, "panel"); p != "" {
+					got, err := m.SetPanel(ctx(), p)
+					if err != nil {
+						return nil, err
+					}
+					out["panel"] = got
+				} else if got, err := m.PanelBrightness(); err == nil {
+					out["panel"] = got
+				} else {
+					out["panel_error"] = err.Error()
+				}
+				if k := str(args, "keyboard"); k != "" {
+					got, err := m.SetKeyboard(ctx(), k)
+					if err != nil {
+						return nil, err
+					}
+					out["keyboard"] = got
+				} else if got, err := m.KeyboardBrightness(); err == nil {
+					out["keyboard"] = got
+				} else {
+					out["keyboard_error"] = err.Error()
+				}
+				return out, nil
+			},
+		},
+		{
+			Name:        "zephyrus_battery",
+			Description: "The battery: charge, energy, health (full against design), cycles, the charge limit, the power it gives or takes, and time left when discharging.",
+			Run: func(map[string]any) (any, error) {
+				return map[string]any{"source": PowerSource(m.Supplies()), "batteries": orEmpty(m.Batteries())}, nil
+			},
+		},
+		{
+			Name: "zephyrus_charge_limit",
+			Description: fmt.Sprintf("Read or set the battery charge limit through asusd. limit is 20-100; oneshot charges to full once "+
+				"and goes back to the limit. The module asserts %d %% again when its process next starts.", ChargeLimitPercent),
+			Input: map[string]any{
+				"limit":   map[string]any{"type": "integer", "description": "20-100"},
+				"oneshot": map[string]any{"type": "boolean", "description": "charge to full once, keeping the limit"},
+			},
+			Run: func(args map[string]any) (any, error) { return ChargeLimitTool(ctx(), m, args) },
+		},
+		{
+			Name: "zephyrus_gpu_mode",
+			Description: "Read or set the hybrid GPU's mode through supergfxd: Integrated, Hybrid or AsusMuxDgpu as the machine supports. " +
+				"Answers the mode, the discrete GPU's power state, any pending mode and the action it waits for (a logout, a reboot), " +
+				"and whether asusd will switch it again on the next change of power source.",
+			Input: map[string]any{
+				"mode": map[string]any{"type": "string", "description": "a supported mode, e.g. Integrated or Hybrid"},
+			},
+			Run: func(args map[string]any) (any, error) { return GPUModeTool(ctx(), m, args) },
+		},
+		{
+			Name: "zephyrus_profile",
+			Description: "Read or set the platform profile (Quiet, Balanced, Performance) through asusd. A profile set here is held " +
+				fmt.Sprintf("for hold_minutes (default %d, 0 for none) before the module's switcher may move it; a change of power source ends the hold.", int(DefaultHold.Minutes())),
+			Input: map[string]any{
+				"profile":      map[string]any{"type": "string", "enum": Profiles},
+				"hold_minutes": map[string]any{"type": "integer", "description": "how long the switcher leaves it (default 60, at most 1440)"},
+			},
+			Run: func(args map[string]any) (any, error) { return ProfileTool(ctx(), m, sw, args) },
+		},
+		{
+			Name:        "zephyrus_thermals",
+			Description: "Every temperature and fan the hardware reports (°C, RPM), the hottest, the platform profile, and the discrete GPU's temperature when it is awake (it is not woken to be read).",
+			Run:         func(map[string]any) (any, error) { return m.Thermals(ctx()), nil },
+		},
+		{
+			Name:        "zephyrus_power_draw",
+			Description: "What the machine draws: the battery's flow in watts, the APU's package power, the discrete GPU's draw when awake, and the power source with the reason it was decided.",
+			Run:         func(map[string]any) (any, error) { return m.PowerDraw(ctx()), nil },
+		},
+		{
+			Name: "zephyrus_profile_policy",
+			Description: "What the module's profile switcher would choose now and why: the power source, recent CPU load against the thresholds, " +
+				"the decision, the profile in force, any hold, what woke it, and what it asserted in asusd at start.",
+			Run: func(map[string]any) (any, error) { return PolicyTool(ctx(), m, sw), nil },
+		},
+		{
+			Name:        "zephyrus_fan_curves",
+			Description: "The fan curves asusd holds for each profile (or one profile): per fan, eight points of temperature and duty.",
+			Input: map[string]any{
+				"profile": map[string]any{"type": "string", "enum": Profiles},
+			},
+			Run: func(args map[string]any) (any, error) { return FanCurvesTool(ctx(), m, args) },
+		},
+		{
+			Name: "zephyrus_keys",
+			Description: "Every custom key on the laptop: each triggerhappy trigger (the vendor keys that reach no X client), the module's own i3 lines " +
+				"(keys the firmware sends as ordinary presses, and what starts with the session), and the keys the firmware handles itself — " +
+				"what each runs and the file it is defined in. Warns when one key is bound in two trigger files, which fires it twice.",
+			Run: func(map[string]any) (any, error) { return m.Keys(), nil },
+		},
+		{
+			Name: "zephyrus_check",
+			Description: "Check what this module expects of the machine: the model, the vendor packages and daemons, the NVIDIA options in force, " +
+				"suspend and resume, the charge limit, one authority each over the profile and the GPU mode, and the predecessor's leftovers. Says what it did not check.",
+			Run: func(map[string]any) (any, error) { return m.Check(ctx(), sw), nil },
+		},
+	}
+}
+
+// ChargeLimitTool reads or sets the limit.
+func ChargeLimitTool(ctx context.Context, m *Machine, args map[string]any) (any, error) {
+	out := map[string]any{"module_limit_percent": ChargeLimitPercent}
+	if v, given := args["limit"]; given && v != nil {
+		n, err := whole(v, "limit")
+		if err != nil {
+			return nil, err
+		}
+		if n < 20 || n > 100 {
+			return nil, fmt.Errorf("limit %d is outside 20-100", n)
+		}
+		if _, err := m.Run(ctx, "asusctl", "battery", "limit", strconv.Itoa(n)); err != nil {
+			return nil, vendor("asusctl", err)
+		}
+		out["set"] = n
+	}
+	if b, _ := args["oneshot"].(bool); b {
+		if _, err := m.Run(ctx, "asusctl", "battery", "oneshot"); err != nil {
+			return nil, vendor("asusctl", err)
+		}
+		out["oneshot"] = "charging to full once; the limit returns after"
+	}
+	if n, err := m.ChargeLimit(ctx); err == nil {
+		out["asusd_limit_percent"] = n
+	} else {
+		out["asusd_error"] = err.Error()
+	}
+	for _, b := range m.Batteries() {
+		if b.LimitPercent != nil {
+			out["kernel_limit_percent"] = *b.LimitPercent
+		}
+	}
+	return out, nil
+}
+
+// GPUModeTool reads or sets the GPU mode.
+func GPUModeTool(ctx context.Context, m *Machine, args map[string]any) (any, error) {
+	g, err := m.GPU(ctx)
+	if err != nil {
+		return nil, err
+	}
+	out := map[string]any{}
+	if want := str(args, "mode"); want != "" {
+		mode := ""
+		for _, s := range g.Supported {
+			if strings.EqualFold(s, want) {
+				mode = s
+			}
+		}
+		if mode == "" {
+			return nil, fmt.Errorf("mode %q is not one this machine supports (%s)", want, strings.Join(g.Supported, ", "))
+		}
+		said, err := m.Run(ctx, "supergfxctl", "-m", mode)
+		if err != nil {
+			return nil, vendor("supergfxctl", err)
+		}
+		out["requested"] = mode
+		if s := strings.TrimSpace(said); s != "" {
+			out["supergfxctl_said"] = s
+		}
+		if g, err = m.GPU(ctx); err != nil {
+			return nil, err
+		}
+	}
+	out["gpu"] = g
+	if c := m.Asusd(); c != nil && (c.ACCommand != "" || c.BatteryCommand != "") {
+		out["asusd_switches_it"] = map[string]string{"on_ac": c.ACCommand, "on_battery": c.BatteryCommand,
+			"note": "asusd runs these on every change of power source, so a mode set here lasts until the next one"}
+	}
+	return out, nil
+}
+
+// ProfileTool reads or sets the profile.
+func ProfileTool(ctx context.Context, m *Machine, sw *Switcher, args map[string]any) (any, error) {
+	out := map[string]any{}
+	if want := str(args, "profile"); want != "" {
+		p, err := canonicalProfile(want)
+		if err != nil {
+			return nil, err
+		}
+		hold := DefaultHold
+		if v, given := args["hold_minutes"]; given && v != nil {
+			n, err := whole(v, "hold_minutes")
+			if err != nil {
+				return nil, err
+			}
+			if n < 0 {
+				return nil, fmt.Errorf("hold_minutes must not be negative")
+			}
+			hold = time.Duration(min(n, 1440)) * time.Minute
+		}
+		if err := m.SetProfile(ctx, p); err != nil {
+			return nil, err
+		}
+		out["set"] = p
+		if sw != nil {
+			if until := sw.Hold(p, hold); !until.IsZero() {
+				out["held_until"] = until
+			}
+		}
+	}
+	state, err := m.Profile(ctx)
+	if err != nil {
+		return nil, err
+	}
+	out["profile"] = state
+	return out, nil
+}
+
+// PolicyTool reports the switcher and, independently of it, what the policy says now.
+func PolicyTool(ctx context.Context, m *Machine, sw *Switcher) any {
+	out := map[string]any{
+		"thresholds": map[string]any{
+			"on_battery": ProfileOnBattery, "on_ac": ProfileOnAC, "under_load": ProfileUnderLoad,
+			"cpu_high_percent": CPUHighPercent, "cpu_low_percent": CPULowPercent,
+			"sample_every": SampleEvery.String(), "sustain_samples": SustainSamples, "relax_samples": RelaxSamples,
+			"set_by": "constants until settings exist (novox/hq issue 168)",
+		},
+	}
+	if sw != nil {
+		out["switcher"] = sw.Report()
+	} else {
+		var p Policy
+		out["decision_now"] = p.Decide(PowerSource(m.Supplies()))
+	}
+	if state, err := m.Profile(ctx); err == nil {
+		out["in_force"] = state
+	} else {
+		out["in_force_error"] = err.Error()
+	}
+	if pid, ok := m.predecessorProcess("auto-profile"); ok {
+		out["second_switcher"] = fmt.Sprintf("the predecessor's auto-profile still runs (pid %d) and overrides this every five seconds", pid)
+	}
+	return out
+}
+
+// FanCurvesTool reads asusd's fan curves.
+func FanCurvesTool(ctx context.Context, m *Machine, args map[string]any) (any, error) {
+	profiles := Profiles
+	if want := str(args, "profile"); want != "" {
+		p, err := canonicalProfile(want)
+		if err != nil {
+			return nil, err
+		}
+		profiles = []string{p}
+	}
+	out := map[string]any{}
+	for _, p := range profiles {
+		said, err := m.Run(ctx, "asusctl", "fan-curve", "--mod-profile", strings.ToLower(p))
+		if err != nil {
+			return nil, vendor("asusctl", err)
+		}
+		out[p] = orEmpty(ParseFanCurves(said))
+	}
+	return out, nil
+}
+
+func str(args map[string]any, key string) string {
+	s, _ := args[key].(string)
+	return strings.TrimSpace(s)
+}
+
+// whole is an integer argument given as a JSON number or a numeric string.
+func whole(v any, key string) (int, error) {
+	switch n := v.(type) {
+	case float64:
+		if n != math.Trunc(n) {
+			return 0, fmt.Errorf("%s must be a whole number, not %v", key, n)
+		}
+		return int(n), nil
+	case string:
+		i, err := strconv.Atoi(strings.TrimSpace(n))
+		if err != nil {
+			return 0, fmt.Errorf("%s must be a whole number, not %q", key, n)
+		}
+		return i, nil
+	}
+	return 0, fmt.Errorf("%s must be a whole number", key)
+}
+
+func orEmpty[T any](s []T) []T {
+	if s == nil {
+		return []T{}
+	}
+	return s
+}

modules/asus-zephyrus-g14/cmd/zephyrus/uevent.go

@@ -0,0 +1,72 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"syscall"
+)
+
+// The kernel announces every change of a power supply — an adapter plugged or pulled, a battery
+// starting or stopping to discharge — as a uevent on a netlink socket that any account may listen
+// on. That is the event the switcher reacts to: no daemon, no bus client, no polling.
+//
+// upower re-announces the same changes on the system bus, and listening there would need a D-Bus
+// client in the bundle; udev's re-broadcast (netlink group 2) carries a libudev header. The kernel's
+// own group (1) is the source both of them read.
+
+// powerSupplyEvent says whether a uevent is about a power supply.
+func powerSupplyEvent(msg []byte) bool {
+	for _, field := range bytes.Split(msg, []byte{0}) {
+		if bytes.Equal(field, []byte("SUBSYSTEM=power_supply")) {
+			return true
+		}
+	}
+	return false
+}
+
+// listenPowerSupply opens the kernel's uevent socket and sends on the channel for each power-supply
+// event, never blocking: a burst of events is one wake-up. It stops when ctx ends.
+func listenPowerSupply(ctx context.Context) (<-chan struct{}, error) {
+	fd, err := syscall.Socket(syscall.AF_NETLINK, syscall.SOCK_RAW|syscall.SOCK_CLOEXEC, syscall.NETLINK_KOBJECT_UEVENT)
+	if err != nil {
+		return nil, fmt.Errorf("opening the kernel's uevent socket: %w", err)
+	}
+	if err := syscall.Bind(fd, &syscall.SockaddrNetlink{Family: syscall.AF_NETLINK, Groups: 1}); err != nil {
+		syscall.Close(fd)
+		return nil, fmt.Errorf("joining the kernel's uevent group: %w", err)
+	}
+	events := make(chan struct{}, 1)
+	go func() {
+		<-ctx.Done()
+		syscall.Close(fd)
+	}()
+	go func() {
+		defer close(events)
+		buf := make([]byte, 64*1024)
+		for {
+			n, _, err := syscall.Recvfrom(fd, buf, 0)
+			if err != nil {
+				if err == syscall.EINTR || err == syscall.ENOBUFS {
+					// ENOBUFS: events were dropped. Treat it as one, since a dropped one may have
+					// been the adapter.
+					if err == syscall.ENOBUFS {
+						select {
+						case events <- struct{}{}:
+						default:
+						}
+					}
+					continue
+				}
+				return
+			}
+			if powerSupplyEvent(buf[:n]) {
+				select {
+				case events <- struct{}{}:
+				default:
+				}
+			}
+		}
+	}()
+	return events, nil
+}

modules/asus-zephyrus-g14/files/bin/zephyrus-backlight

@@ -0,0 +1,33 @@
+#!/bin/bash
+# zephyrus-backlight + | - | PERCENT — step or set the internal panel's backlight, never below 1 %.
+# Shipped by the mesh's asus-zephyrus-g14 module; edit the catalogue.
+#
+# The panel is the backlight beneath the eDP connector, not a name: in hybrid mode this model also
+# registers the discrete GPU's backlight (nvidia_0), which moves nothing. Writable by the video group
+# through the module's udev rule, so the vendor-key trigger needs no root.
+set -u
+STEP=5
+dev=""
+for d in /sys/class/backlight/*; do
+	[ -e "$d" ] || continue
+	case "$(readlink -f "$d")" in *-eDP-*) dev=$d; break ;; esac
+done
+if [ -z "$dev" ]; then
+	for d in /sys/class/backlight/*; do [ -e "$d" ] && { dev=$d; break; }; done
+fi
+[ -n "$dev" ] || { echo "zephyrus-backlight: no backlight" >&2; exit 1; }
+cur=$(cat "$dev/brightness")
+max=$(cat "$dev/max_brightness")
+pct=$(( cur * 100 / max ))
+case "${1:-}" in
+	+|up|Up) pct=$(( pct + STEP )) ;;
+	-|down|Down) pct=$(( pct - STEP )) ;;
+	''|*[!0-9]*) echo "usage: zephyrus-backlight + | - | PERCENT" >&2; exit 2 ;;
+	*) pct=$1 ;;
+esac
+(( pct < 1 )) && pct=1
+(( pct > 100 )) && pct=100
+new=$(( max * pct / 100 ))
+(( new < 1 )) && new=1
+printf '%s' "$new" >"$dev/brightness" || exit 1
+exec "$(dirname "$0")/zephyrus-notify" 5555 "Brightness: ${pct}%"

modules/asus-zephyrus-g14/files/bin/zephyrus-display

@@ -0,0 +1,41 @@
+#!/bin/bash
+# zephyrus-display primary | order — the laptop's internal panel among the outputs.
+# Shipped by the mesh's asus-zephyrus-g14 module; edit the catalogue.
+#
+#   primary  makes the internal panel X's primary output, where the bars' tray goes.
+#   order    the display key (Fn+F9, which the firmware sends as Super+P): odd workspaces to the
+#            internal panel, even ones to the first external output, or all to the panel when it
+#            is alone. The predecessor's orden-workspaces.
+#
+# The panel is found, not named: the connected output whose name starts with eDP. The predecessor
+# wrote eDP-1, which is what this model calls it today and not a promise.
+set -u
+here=$(dirname "$0")
+panel=$(xrandr --query 2>/dev/null | awk '$2 == "connected" && $1 ~ /^eDP/ { print $1; exit }')
+[ -n "$panel" ] || { echo "zephyrus-display: no internal panel connected" >&2; exit 1; }
+case "${1:-}" in
+primary)
+	exec xrandr --output "$panel" --primary
+	;;
+order)
+	external=$(xrandr --listmonitors 2>/dev/null | awk -v p="$panel" 'NR > 1 && $NF != p { print $NF; exit }')
+	[ -n "$external" ] || external=$panel
+	# i3's workspace list, one object per workspace; num and output read from each. No jq: the
+	# fields are flat strings and numbers, and rect, the only nested value, holds neither name.
+	i3-msg -t get_workspaces 2>/dev/null | sed 's/},{"id"/}\n{"id"/g' |
+		while read -r ws; do
+			num=$(printf '%s' "$ws" | grep -o '"num":-\?[0-9]*' | cut -d: -f2)
+			out=$(printf '%s' "$ws" | grep -o '"output":"[^"]*"' | cut -d'"' -f4)
+			[ -n "$num" ] && [ "$num" -ge 0 ] || continue
+			if [ $((num % 2)) -eq 0 ]; then dest=$external; else dest=$panel; fi
+			[ "$out" = "$dest" ] && continue
+			i3-msg "workspace number $num; move workspace to output $dest" >/dev/null
+		done
+	if [ "$external" = "$panel" ]; then
+		"$here/zephyrus-notify" 7780 "Workspaces: all on the panel"
+	else
+		"$here/zephyrus-notify" 7780 "Workspaces: odd on the panel, even on $external"
+	fi
+	;;
+*) echo "usage: zephyrus-display primary | order" >&2; exit 2 ;;
+esac

modules/asus-zephyrus-g14/files/bin/zephyrus-kbd-notify

@@ -0,0 +1,20 @@
+#!/bin/bash
+# zephyrus-kbd-notify — shows the keyboard backlight's level when it changes. The level itself is set
+# by the firmware and asusd (Fn+F2/F3), which tell UPower; this only listens and notifies. Started once
+# per session from the module's i3 fragment. Shipped by the mesh's asus-zephyrus-g14 module.
+#
+# One instance per session: i3 runs its `exec` lines again on an in-place restart, and the
+# predecessor's listener ran twice after one, showing every change twice.
+set -u
+here=$(dirname "$0")
+lock="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/zephyrus-kbd-notify.lock"
+exec 9>"$lock"
+flock -n 9 || exit 0
+levels=(Off Low Med High)
+dbus-monitor --system "type='signal',interface='org.freedesktop.UPower.KbdBacklight',member='BrightnessChanged'" 2>/dev/null |
+	while read -r line; do
+		if [[ $line =~ int32\ ([0-9]+) ]]; then
+			v=${BASH_REMATCH[1]}
+			"$here/zephyrus-notify" 5556 "Keyboard: ${levels[$v]:-$v}"
+		fi
+	done

modules/asus-zephyrus-g14/files/bin/zephyrus-media

@@ -0,0 +1,27 @@
+#!/bin/bash
+# zephyrus-media play-pause | next | previous — the media keys, through MPRIS (playerctl), with a short
+# notification of what happened. Shipped by the mesh's asus-zephyrus-g14 module; edit the catalogue.
+#
+# From the predecessor's media-control, kept: the lock against a double fire (the vendor keys can
+# repeat), and the notification. Dropped: its fallback to a media server's local API, which needed a
+# token from a file of secrets (novox/hq research 027 question 2). A player that speaks MPRIS is
+# reached; one that does not says so.
+set -u
+here=$(dirname "$0")
+action=${1:-play-pause}
+case "$action" in play-pause | next | previous) ;; *) echo "usage: zephyrus-media play-pause | next | previous" >&2; exit 2 ;; esac
+lock="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/zephyrus-media.lock"
+exec 9>"$lock"
+flock -n 9 || exit 0
+if ! playerctl status >/dev/null 2>&1; then
+	"$here/zephyrus-notify" 7777 "Media: no player"
+	exit 0
+fi
+playerctl "$action" 2>/dev/null
+if [ "$action" = play-pause ]; then
+	sleep 0.2
+	[ "$(playerctl status 2>/dev/null)" = Playing ] && label=Playing || label=Paused
+else
+	label=${action^}
+fi
+"$here/zephyrus-notify" 7777 "Media: $label"

modules/asus-zephyrus-g14/files/bin/zephyrus-notify

@@ -0,0 +1,12 @@
+#!/bin/bash
+# zephyrus-notify ID SUMMARY — a short desktop notification that replaces the previous one with the
+# same ID, through the session's notification service on its bus. busctl is the service manager's
+# own client, so nothing is installed for it. Shipped by the mesh's asus-zephyrus-g14 module.
+set -u
+id=${1:-0}
+summary=${2:-}
+uid=$(id -u)
+DBUS_SESSION_BUS_ADDRESS="unix:path=/run/user/${uid}/bus" \
+	busctl --user call org.freedesktop.Notifications /org/freedesktop/Notifications \
+	org.freedesktop.Notifications Notify susssasa{sv}i \
+	asus-zephyrus-g14 "$id" "" "$summary" "" 0 1 urgency y 0 1500 >/dev/null 2>&1 || true

modules/asus-zephyrus-g14/files/bin/zephyrus-session

@@ -0,0 +1,46 @@
+#!/bin/bash
+# zephyrus-session COMMAND [ARG...] — run a command in the operator's graphical session from outside
+# it: from a vendor-key trigger, which triggerhappy runs as the operator's account but with none of
+# the session's environment. Shipped by the mesh's asus-zephyrus-g14 module; edit the catalogue.
+#
+# What it replaces: the predecessor's `as-user`, which triggerhappy ran as root and which `su`-ed to
+# a named person with a hard-coded user id and display, and sourced a file of secrets on the way.
+# Here the account is whoever runs it, the bus is that account's, and the display is the one the
+# account's own session uses. Nothing is sourced.
+set -u
+uid=$(id -u)
+export XDG_RUNTIME_DIR="/run/user/${uid}"
+export DBUS_SESSION_BUS_ADDRESS="unix:path=${XDG_RUNTIME_DIR}/bus"
+home=$(getent passwd "$uid" | cut -d: -f6)
+[ -n "$home" ] && export HOME="$home"
+# The session's own window manager says best which display and authority the session uses: read
+# them from its environment, as the desktop modules' session finder does. Then logind, then any
+# process of this account that has a display.
+from_environ() {
+	env=$(tr '\0' '\n' <"/proc/$1/environ" 2>/dev/null) || return 1
+	d=$(printf '%s\n' "$env" | sed -n 's/^DISPLAY=//p' | head -n1)
+	[ -n "$d" ] || return 1
+	export DISPLAY="$d"
+	a=$(printf '%s\n' "$env" | sed -n 's/^XAUTHORITY=//p' | head -n1)
+	[ -n "$a" ] && export XAUTHORITY="$a"
+	return 0
+}
+if [ -z "${DISPLAY:-}" ]; then
+	for pid in $(pgrep -xu "$uid" i3 2>/dev/null); do
+		from_environ "$pid" && break
+	done
+fi
+if [ -z "${DISPLAY:-}" ]; then
+	for s in $(loginctl list-sessions --no-legend 2>/dev/null | awk -v u="$uid" '$2 == u { print $1 }'); do
+		d=$(loginctl show-session "$s" -p Display --value 2>/dev/null)
+		if [ -n "$d" ]; then export DISPLAY="$d"; break; fi
+	done
+fi
+if [ -z "${DISPLAY:-}" ]; then
+	for pid in $(pgrep -u "$uid" 2>/dev/null); do
+		from_environ "$pid" && break
+	done
+fi
+: "${XAUTHORITY:=${HOME}/.Xauthority}"
+export XAUTHORITY
+exec "$@"

modules/asus-zephyrus-g14/files/bin/zephyrus-touchpad

@@ -0,0 +1,29 @@
+#!/bin/bash
+# zephyrus-touchpad reset | toggle — apply the touchpad's settings again, or switch it on or off.
+# Shipped by the mesh's asus-zephyrus-g14 module; edit the catalogue.
+#
+# The settings themselves are an X input class (/etc/X11/xorg.conf.d/30-asus-zephyrus-g14-touchpad.conf),
+# which X applies every time the device appears — after a resume too, which is what the predecessor's
+# sleep hook existed for. This is the manual form, bound to the touchpad key.
+set -u
+here=$(dirname "$0")
+name=$("$here/zephyrus-session" xinput list --name-only 2>/dev/null | grep -m1 -i 'touchpad')
+[ -n "$name" ] || { echo "zephyrus-touchpad: no touchpad in this session" >&2; exit 1; }
+x() { "$here/zephyrus-session" xinput "$@"; }
+case "${1:-reset}" in
+	reset)
+		x set-prop "$name" "libinput Tapping Enabled" 1
+		x set-prop "$name" "libinput Natural Scrolling Enabled" 1
+		x set-prop "$name" "libinput Accel Speed" 0.15
+		x enable "$name"
+		"$here/zephyrus-session" "$here/zephyrus-notify" 7779 "Touchpad: reset"
+		;;
+	toggle)
+		if x list-props "$name" | grep -q 'Device Enabled ([0-9]*):[[:space:]]*1'; then
+			x disable "$name"; "$here/zephyrus-session" "$here/zephyrus-notify" 7779 "Touchpad: off"
+		else
+			x enable "$name"; "$here/zephyrus-session" "$here/zephyrus-notify" 7779 "Touchpad: on"
+		fi
+		;;
+	*) echo "usage: zephyrus-touchpad reset | toggle" >&2; exit 2 ;;
+esac

modules/asus-zephyrus-g14/go.mod

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

modules/asus-zephyrus-g14/go.sum

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

modules/asus-zephyrus-g14/module.json

@@ -0,0 +1,301 @@
+{
+  "module": "asus-zephyrus-g14",
+  "version": "1",
+  "capabilities": [
+    "package-manager",
+    "service-manager"
+  ],
+  "requires": [
+    "x11-display"
+  ],
+  "emits": [
+    "profile.switched"
+  ],
+  "tools": [
+    "zephyrus_brightness",
+    "zephyrus_battery",
+    "zephyrus_charge_limit",
+    "zephyrus_gpu_mode",
+    "zephyrus_profile",
+    "zephyrus_thermals",
+    "zephyrus_power_draw",
+    "zephyrus_profile_policy",
+    "zephyrus_fan_curves",
+    "zephyrus_keys",
+    "zephyrus_check"
+  ],
+  "resources": [
+    {
+      "id": "asusctl",
+      "type": "package",
+      "package": "asusctl"
+    },
+    {
+      "id": "playerctl",
+      "type": "package",
+      "package": "playerctl"
+    },
+    {
+      "id": "asusd",
+      "type": "service",
+      "unit": "asusd.service",
+      "state": "running"
+    },
+    {
+      "id": "supergfxd",
+      "type": "service",
+      "unit": "supergfxd.service",
+      "state": "running",
+      "boot": "enabled"
+    },
+    {
+      "id": "scripts",
+      "type": "archive",
+      "path": "/usr/local/lib/asus-zephyrus-g14",
+      "artifact": "scripts"
+    },
+    {
+      "id": "nvidia-options",
+      "type": "file",
+      "path": "/etc/modprobe.d/g14-nvidia-power.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The discrete GPU's driver options on the ROG Zephyrus G14 (GA403, RTX 40 series, hybrid graphics).\n#\n# NVreg_DynamicPowerManagement=0x00 turns runtime D3 off. With it on, a change of power source sends\n# the driver an ACPI notification it fails to handle on this model (\"RmHandleDNotifierEvent: Failed to\n# handle ACPI D-Notifier event, status=0x62\"), and the GPU stops making progress until the machine is\n# powered off. Off costs a few idle watts in hybrid mode and keeps the machine up.\n#\n# NVreg_PreserveVideoMemoryAllocations=1 saves video memory across suspend, so what used the GPU still\n# works after waking. It needs nvidia-suspend, -hibernate and -resume to run around a sleep, which this\n# module's drop-ins on the sleep services ask for.\n#\n# A change here applies when the driver next loads: at the next boot.\noptions nvidia NVreg_PreserveVideoMemoryAllocations=1\noptions nvidia NVreg_DynamicPowerManagement=0x00\n"
+    },
+    {
+      "id": "video-options",
+      "type": "file",
+      "path": "/etc/modprobe.d/video-brightness-switch.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The ACPI video driver does not change the backlight itself on the brightness keys: on this model it\n# moves the wrong one. The keys are triggerhappy's (see /etc/triggerhappy/triggers.d/asus-g14.conf).\n# Applies when the module next loads: at the next boot.\noptions video brightness_switch_enabled=0\n"
+    },
+    {
+      "id": "suspend-drop-ins",
+      "type": "directory",
+      "path": "/etc/systemd/system/systemd-suspend.service.d",
+      "mode": "0755"
+    },
+    {
+      "id": "nvidia-on-suspend",
+      "type": "file",
+      "path": "/etc/systemd/system/systemd-suspend.service.d/asus-zephyrus-g14-nvidia.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The NVIDIA driver's own sleep actions, asked for by the sleep itself rather than enabled as\n# links: the mesh declares files and never makes links (novox/hq ADR 0012), and the host's service\n# shape must not start these units by hand, which would put the GPU to sleep with the machine awake.\n[Unit]\nWants=nvidia-suspend.service nvidia-resume.service\n"
+    },
+    {
+      "id": "hibernate-drop-ins",
+      "type": "directory",
+      "path": "/etc/systemd/system/systemd-hibernate.service.d",
+      "mode": "0755"
+    },
+    {
+      "id": "nvidia-on-hibernate",
+      "type": "file",
+      "path": "/etc/systemd/system/systemd-hibernate.service.d/asus-zephyrus-g14-nvidia.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The NVIDIA driver's own sleep actions, asked for by the sleep itself rather than enabled as\n# links: the mesh declares files and never makes links (novox/hq ADR 0012), and the host's service\n# shape must not start these units by hand, which would put the GPU to sleep with the machine awake.\n[Unit]\nWants=nvidia-hibernate.service nvidia-resume.service\n"
+    },
+    {
+      "id": "suspend-then-hibernate-drop-ins",
+      "type": "directory",
+      "path": "/etc/systemd/system/systemd-suspend-then-hibernate.service.d",
+      "mode": "0755"
+    },
+    {
+      "id": "nvidia-on-suspend-then-hibernate",
+      "type": "file",
+      "path": "/etc/systemd/system/systemd-suspend-then-hibernate.service.d/asus-zephyrus-g14-nvidia.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The NVIDIA driver's own sleep actions, asked for by the sleep itself rather than enabled as\n# links: the mesh declares files and never makes links (novox/hq ADR 0012), and the host's service\n# shape must not start these units by hand, which would put the GPU to sleep with the machine awake.\n[Unit]\nWants=nvidia-suspend-then-hibernate.service nvidia-resume.service\n"
+    },
+    {
+      "id": "powerd-drop-ins",
+      "type": "directory",
+      "path": "/etc/systemd/system/nvidia-powerd.service.d",
+      "mode": "0755"
+    },
+    {
+      "id": "powerd-opt-in",
+      "type": "file",
+      "path": "/etc/systemd/system/nvidia-powerd.service.d/asus-zephyrus-g14.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# nvidia-powerd (Dynamic Boost) was the first error in the chain that hung this model's GPU on a change\n# of power source, and asusd starts it on mains. It runs only when the kernel command line says\n# zephyrus.nvidia-powerd — an explicit opt-in, at boot.\n[Unit]\nConditionKernelCommandLine=zephyrus.nvidia-powerd\n"
+    },
+    {
+      "id": "logind-drop-ins",
+      "type": "directory",
+      "path": "/etc/systemd/logind.conf.d",
+      "mode": "0755"
+    },
+    {
+      "id": "logind-power",
+      "type": "file",
+      "path": "/etc/systemd/logind.conf.d/power.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The power key and the lid suspend, on battery, on mains and docked alike.\n[Login]\nHandlePowerKey=suspend\nHandleLidSwitch=suspend\nHandleLidSwitchExternalPower=suspend\nHandleLidSwitchDocked=suspend\n"
+    },
+    {
+      "id": "logind",
+      "type": "service",
+      "unit": "systemd-logind.service",
+      "reload-on": [
+        "logind-power"
+      ]
+    },
+    {
+      "id": "backlight-rule",
+      "type": "file",
+      "path": "/etc/udev/rules.d/90-backlight.rules",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The backlights are writable by the video group, so the brightness keys and the module's brightness tool\n# move the panel without root.\nACTION==\"add\", SUBSYSTEM==\"backlight\", RUN+=\"/usr/bin/chgrp video /sys/class/backlight/%k/brightness\", RUN+=\"/usr/bin/chmod g+w /sys/class/backlight/%k/brightness\"\n"
+    },
+    {
+      "id": "udev",
+      "type": "service",
+      "unit": "systemd-udevd.service",
+      "reload-on": [
+        "backlight-rule"
+      ]
+    },
+    {
+      "id": "triggerhappy-drop-ins",
+      "type": "directory",
+      "path": "/etc/systemd/system/triggerhappy.service.d",
+      "mode": "0755"
+    },
+    {
+      "id": "triggerhappy-as-account",
+      "type": "file",
+      "path": "/etc/systemd/system/triggerhappy.service.d/asus-zephyrus-g14.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# triggerhappy runs the vendor-key triggers as the operator's account, not as root: it opens the input\n# devices first and then drops to the account with its groups (input, video), so the triggers reach the\n# account's own session bus and the panel through the video group, with no su and no hard-coded user.\n[Service]\nExecStart=\nExecStart=/usr/bin/thd --triggers /etc/triggerhappy/triggers.d/ --socket /run/thd.socket --user ${machine:account} --deviceglob /dev/input/event*\n"
+    },
+    {
+      "id": "vendor-keys",
+      "type": "file",
+      "path": "/etc/triggerhappy/triggers.d/asus-g14.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The ROG Zephyrus G14's vendor keys, which reach no X client. Run as the operator's account (see the\n# module's drop-in on triggerhappy.service).\nKEY_PROG1\t1\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-session /usr/local/lib/asus-zephyrus-g14/bin/zephyrus-media play-pause\nKEY_PROG3\t1\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-session /usr/local/lib/asus-zephyrus-g14/bin/zephyrus-media previous\nKEY_PROG4\t1\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-session /usr/local/lib/asus-zephyrus-g14/bin/zephyrus-media next\nKEY_BRIGHTNESSDOWN\t1\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-backlight -\nKEY_BRIGHTNESSDOWN\t2\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-backlight -\nKEY_BRIGHTNESSUP\t1\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-backlight +\nKEY_BRIGHTNESSUP\t2\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-backlight +\nKEY_F21\t1\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-touchpad reset\n"
+    },
+    {
+      "id": "triggerhappy",
+      "type": "service",
+      "unit": "triggerhappy.service",
+      "state": "running",
+      "boot": "enabled",
+      "restart-on": [
+        "triggerhappy-as-account",
+        "vendor-keys",
+        "scripts",
+        "touchpad-on-resume",
+        "touchpad-after-suspend",
+        "touchpad-after-hibernate",
+        "touchpad-after-suspend-then-hibernate"
+      ]
+    },
+    {
+      "id": "upower-package",
+      "type": "package",
+      "package": "upower"
+    },
+    {
+      "id": "upower-drop-ins",
+      "type": "directory",
+      "path": "/etc/UPower/UPower.conf.d",
+      "mode": "0755"
+    },
+    {
+      "id": "low-battery",
+      "type": "file",
+      "path": "/etc/UPower/UPower.conf.d/50-asus-zephyrus-g14.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# On low battery the machine suspends rather than powering off, at 7 % — s2idle still draws a little,\n# so it leaves headroom. A drop-in over the package's own UPower.conf, which stays the package's.\n[UPower]\nUsePercentageForPolicy=true\nPercentageLow=15.0\nPercentageCritical=10.0\nPercentageAction=7.0\nCriticalPowerAction=Suspend\nAllowRiskyCriticalPowerAction=true\n"
+    },
+    {
+      "id": "upower",
+      "type": "service",
+      "unit": "upower.service",
+      "state": "running",
+      "boot": "enabled",
+      "restart-on": [
+        "low-battery"
+      ]
+    },
+    {
+      "id": "xorg-drop-ins",
+      "type": "directory",
+      "path": "/etc/X11/xorg.conf.d",
+      "mode": "0755"
+    },
+    {
+      "id": "touchpad",
+      "type": "file",
+      "path": "/etc/X11/xorg.conf.d/30-asus-zephyrus-g14-touchpad.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The touchpad's settings, applied by X every time the device appears — at login and after every\n# resume, when the device is initialised again. This replaces the predecessor's sleep hook, which ran\n# xinput after a resume as a named person on a guessed display.\nSection \"InputClass\"\n    Identifier \"asus-zephyrus-g14 touchpad\"\n    MatchIsTouchpad \"on\"\n    Option \"Tapping\" \"on\"\n    Option \"NaturalScrolling\" \"true\"\n    Option \"AccelSpeed\" \"0.15\"\nEndSection\n"
+    },
+    {
+      "id": "touchpad-on-resume",
+      "type": "file",
+      "path": "/etc/systemd/system/asus-zephyrus-g14-touchpad-resume.service",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# After a resume, the touchpad's settings once more in the operator's session. X applies the module's\n# input class whenever the device appears, which covers a resume that initialises the device again;\n# this covers one that does not, as the predecessor's sleep hook did. Started by the sleep services\n# themselves (their asus-zephyrus-g14-touchpad.conf drop-ins), never enabled, and ordered after them,\n# so it runs once the machine is awake.\n[Unit]\nDescription=Touchpad settings after resume (asus-zephyrus-g14)\nAfter=systemd-suspend.service systemd-hibernate.service systemd-suspend-then-hibernate.service\n\n[Service]\nType=oneshot\nUser=${machine:account}\nExecStartPre=/bin/sleep 2\nExecStart=/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-touchpad reset\n"
+    },
+    {
+      "id": "touchpad-after-suspend",
+      "type": "file",
+      "path": "/etc/systemd/system/systemd-suspend.service.d/asus-zephyrus-g14-touchpad.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The touchpad's settings again once the machine is awake (asus-zephyrus-g14-touchpad-resume.service).\n[Unit]\nWants=asus-zephyrus-g14-touchpad-resume.service\n"
+    },
+    {
+      "id": "touchpad-after-hibernate",
+      "type": "file",
+      "path": "/etc/systemd/system/systemd-hibernate.service.d/asus-zephyrus-g14-touchpad.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The touchpad's settings again once the machine is awake (asus-zephyrus-g14-touchpad-resume.service).\n[Unit]\nWants=asus-zephyrus-g14-touchpad-resume.service\n"
+    },
+    {
+      "id": "touchpad-after-suspend-then-hibernate",
+      "type": "file",
+      "path": "/etc/systemd/system/systemd-suspend-then-hibernate.service.d/asus-zephyrus-g14-touchpad.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The touchpad's settings again once the machine is awake (asus-zephyrus-g14-touchpad-resume.service).\n[Unit]\nWants=asus-zephyrus-g14-touchpad-resume.service\n"
+    },
+    {
+      "id": "i3-vendor-keys",
+      "type": "file",
+      "path": "${machine:account-home}/.config/i3/config.d/10-asus.conf",
+      "owner": "${machine:account}",
+      "mode": "0644",
+      "content": "# The laptop's own lines in i3 (module asus-zephyrus-g14, novox/hq ADR 0208, ADR 0210). Owned by the\n# mesh: replaced at every push. Once the controller places contributions to node-display-session\n# (ADR 0210), these become the module's contribution instead of a file in i3's directory.\n#\n# The keys the firmware turns into ordinary key presses. The vendor keys that reach no X client are\n# triggerhappy's (/etc/triggerhappy/triggers.d/asus-g14.conf): M4 and Fn+F4/F5 for media, Fn+F7/F8 for\n# the panel, Fn+F10 for the touchpad. The keyboard backlight (Fn+F2/F3) is the firmware's and asusd's.\n\n# Fn+F6, the screenshot key: the firmware sends Super+Shift+S. Released before it runs, because the\n# screenshot grabs the pointer to select a region, which fails while the key is still held.\nbindsym --release $mod+Shift+s exec --no-startup-id $XDG_CONFIG_HOME/i3/scripts/screenshot.sh\n\n# Fn+F9, the display key: the firmware sends Super+P. Odd workspaces to the panel, even ones to the\n# external output.\nbindsym $mod+p exec --no-startup-id /usr/local/lib/asus-zephyrus-g14/bin/zephyrus-display order\n\n# The keyboard backlight's level, shown when it changes.\nexec --no-startup-id /usr/local/lib/asus-zephyrus-g14/bin/zephyrus-kbd-notify\n"
+    },
+    {
+      "id": "i3-model",
+      "type": "file",
+      "path": "${machine:account-home}/.config/i3/config.d/20-g14.conf",
+      "owner": "${machine:account}",
+      "mode": "0644",
+      "content": "# The laptop's own lines in i3 (module asus-zephyrus-g14, novox/hq ADR 0208, ADR 0210). Owned by the\n# mesh: replaced at every push. Once the controller places contributions to node-display-session\n# (ADR 0210), these become the module's contribution instead of a file in i3's directory.\n#\n# The model's panel and touchpad.\n\n# The internal panel is the primary output, where the bars' tray goes. Which monitors are on and where\n# is the display server's (autorandr, run at every session start).\nexec --no-startup-id /usr/local/lib/asus-zephyrus-g14/bin/zephyrus-display primary\n\n# The touchpad's settings again, by hand. X applies them itself whenever the device appears.\nbindsym $mod+Shift+x exec --no-startup-id /usr/local/lib/asus-zephyrus-g14/bin/zephyrus-touchpad reset\n"
+    }
+  ],
+  "build": {
+    "artifacts": [
+      {
+        "name": "tools-go",
+        "kind": "bundle",
+        "language": "go",
+        "system": "arch",
+        "from": "cmd/zephyrus",
+        "binary": "zephyrus",
+        "loads": [
+          "zephyrus"
+        ]
+      },
+      {
+        "name": "scripts",
+        "kind": "archive",
+        "from": "files"
+      }
+    ]
+  }
+}

modules/audit-logger/test/audit.test.ts

@@ -15,7 +15,7 @@ test("audit-logger records every event to the trail as one line each", async ()
   const path = join(dir, "audit.log");
 
   // The audit-logger's whole behaviour: consume everything, record it.
-  await on("**", async (event) => record(event, path));
+  await on("#", async (event) => record(event, path)); // the pattern index.ts subscribes
 
   process.env.MESH_MODULE = "umami";
   process.env.MESH_NODE = "anchor";
@@ -24,7 +24,9 @@ test("audit-logger records every event to the trail as one line each", async ()
 
   const lines = (await readFile(path, "utf8")).trim().split("\n").map((l) => JSON.parse(l));
   assert.equal(lines.length, 2);
-  assert.deepEqual(lines.map((l) => l.type), ["umami.site.created", "node.anchor.joined"]);
+  // A module names its events locally (design 29); the module is the `source`, which together with
+  // the type says whose event it was. This broker does no namespacing, so the type is as emitted.
+  assert.deepEqual(lines.map((l) => l.type), ["site.created", "node.anchor.joined"]);
   assert.equal(lines[0].source, "umami");
   assert.equal(lines[0].node, "anchor");
   assert.equal(lines[0].body.domain, "my-app");

modules/avahi/README.md

@@ -0,0 +1,42 @@
+# avahi
+
+The local network's name and service discovery (mDNS/DNS-SD) as a module (novox/hq to-be 42 Phase 1,
+research 027).
+
+## What it owns
+
+- The `avahi` package.
+- `avahi-daemon.service`, running and enabled.
+
+## What it improves
+
+It was on all four machines and owned by none. It is now declared, and its tools show why discovery
+does not work today:
+
+- **The packet filter drops mDNS.** The mesh's filter has no rule for inbound UDP 5353 on any of the
+  four machines, so avahi announces this machine but hears no other machine's answers. A browse
+  finds nothing, and resolving even the machine's own `.local` name times out. A module's `listens`
+  can reach the private network, this machine or anywhere, but not the local link. Opening the port
+  to anywhere would answer the internet on a public machine, so the module opens nothing. This needs
+  a decision in novox/hq: a local-link source scope for `listens`. Until then, `avahi_status` reports
+  `inbound_mdns_accepted: false`, and browse and resolve say so whenever they hear nothing.
+
+## What it leaves found
+
+- **`nss-mdns` and `/etc/nsswitch.conf`.** An ordinary lookup reaches avahi only through the
+  `hosts:` line. That line is one ordered list shared by every name source: containers, files, DNS,
+  mDNS and the resolver daemon. The host can write a marked block into a file, but it cannot add a
+  member to a line. Owning the whole file would make this module the owner of every machine's name
+  resolution. On 2026-10-04 all four machines had the same file, with `mdns4_minimal` wired by hand
+  and nss-mdns installed. Both are left as found, and `avahi_status` reports the wiring.
+- `/etc/avahi/avahi-daemon.conf`, including each workstation's hand-set `allow-interfaces`, which
+  names that machine's own network interface.
+
+## Tools
+
+| tool | | answers |
+|---|---|---|
+| `avahi_status` | r | the daemon, its version and configuration, the `hosts:` line and whether mdns is on it, nss-mdns, whether the filter accepts inbound 5353, systemd-resolved beside it, and notes |
+| `avahi_browse` | r | every service announced in a few seconds (`avahi-browse -prt`), resolved where possible, narrowed to a type |
+| `avahi_resolve` | r | a `.local` name through avahi and through the name service side by side, or an address to its name |
+| `avahi_services` | r | what this machine publishes from `/etc/avahi/services` |

modules/avahi/cmd/avahi-tools/avahi.go

@@ -0,0 +1,353 @@
+package main
+
+// Avahi, the local network's name and service discovery (mDNS/DNS-SD), as a module (novox/hq to-be 42
+// Phase 1, research 027: "on all four, owned by none"). The module declares the package and the
+// daemon. Two things it does not declare, and these tools report instead:
+//
+//   - **The name service switch.** nss-mdns is what lets an ordinary lookup answer `<host>.local`, and
+//     it works only through the `hosts:` line of /etc/nsswitch.conf. That line is one ordered list
+//     shared by every name source on the machine (containers, files, DNS, mDNS, the resolver daemon),
+//     the host can write a marked block into a file but not a member into a line, and owning the whole
+//     file would make this module the owner of every machine's name resolution. So both stay as found
+//     (wired by hand, identically, on all four machines on 2026-10-04) and `avahi_status` says whether
+//     the wiring is there.
+//   - **The packet filter.** mDNS is multicast to UDP 5353 on the local link. The mesh's filter has no
+//     source scope for "the local link" — a module's `listens` reach the private network, this machine
+//     or anywhere — so it drops what other machines announce, and a browse hears nothing. Opening it to
+//     anywhere would answer the internet on a public machine. `avahi_status` reports whether inbound
+//     5353 is accepted; browse and resolve say so when they hear nothing.
+
+import (
+	"fmt"
+	"net"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+// The files avahi and the name service read.
+const (
+	DaemonConf  = "/etc/avahi/avahi-daemon.conf"
+	ServicesDir = "/etc/avahi/services"
+	NSSwitch    = "/etc/nsswitch.conf"
+	Daemon      = "avahi-daemon.service"
+)
+
+// Status is the daemon, its configuration, the name service's wiring and the filter.
+type Status struct {
+	Daemon      map[string]string            `json:"daemon"`
+	Version     string                       `json:"version,omitempty"`
+	Config      map[string]map[string]string `json:"config"`
+	HostsLine   string                       `json:"nsswitch_hosts"`
+	MDNSWired   bool                         `json:"nss_mdns_wired"`
+	NSSMDNS     string                       `json:"nss_mdns_package,omitempty"`
+	InboundMDNS *bool                        `json:"inbound_mdns_accepted"`
+	FilterError string                       `json:"filter_error,omitempty"`
+	ResolvedOn  bool                         `json:"systemd_resolved_active"`
+	Notes       []string                     `json:"notes"`
+}
+
+// ParseINI reads avahi-daemon.conf's sections and their set keys; commented keys are defaults.
+func ParseINI(text string) map[string]map[string]string {
+	out := map[string]map[string]string{}
+	section := ""
+	for _, l := range lines(text) {
+		l = strings.TrimSpace(l)
+		switch {
+		case strings.HasPrefix(l, "#") || strings.HasPrefix(l, ";"):
+		case strings.HasPrefix(l, "[") && strings.HasSuffix(l, "]"):
+			section = strings.Trim(l, "[]")
+			out[section] = map[string]string{}
+		default:
+			if k, v, ok := strings.Cut(l, "="); ok && section != "" {
+				out[section][strings.TrimSpace(k)] = strings.TrimSpace(v)
+			}
+		}
+	}
+	return out
+}
+
+// HostsLine is the `hosts:` line of nsswitch.conf, and whether an mdns source is on it.
+func HostsLine(text string) (string, bool) {
+	for _, l := range lines(text) {
+		l = strings.TrimSpace(l)
+		if !strings.HasPrefix(l, "hosts:") {
+			continue
+		}
+		for _, f := range strings.Fields(strings.TrimPrefix(l, "hosts:")) {
+			if strings.HasPrefix(f, "mdns") {
+				return l, true
+			}
+		}
+		return l, false
+	}
+	return "", false
+}
+
+var mdnsAccept = regexp.MustCompile(`(?m)\budp dport (?:\{[^}\n]*\b(?:5353|mdns)\b[^}\n]*\}|(?:5353|mdns)\b)[^\n]*\baccept\b`)
+
+// InboundMDNS is whether a ruleset accepts UDP 5353 coming in.
+func InboundMDNS(ruleset string) bool { return mdnsAccept.MatchString(ruleset) }
+
+// GetStatus reads the daemon, its configuration, the name service and the packet filter.
+func (m *Machine) GetStatus() (Status, error) {
+	s := Status{Config: map[string]map[string]string{}, Notes: []string{}}
+	d, err := m.unitProps(Daemon, "LoadState", "ActiveState", "SubState", "UnitFileState", "MainPID")
+	if err != nil {
+		return s, err
+	}
+	s.Daemon = d
+	if v, err := m.Out("avahi-daemon", "--version"); err == nil {
+		s.Version = strings.TrimSpace(v)
+	}
+	if text, err := m.ReadFile(DaemonConf); err == nil {
+		s.Config = ParseINI(string(text))
+	}
+	if text, err := m.ReadFile(NSSwitch); err == nil {
+		s.HostsLine, s.MDNSWired = HostsLine(string(text))
+	}
+	if r := m.Run(bg(), "pacman", "-Q", "nss-mdns"); r.Status == 0 && r.Err == "" {
+		s.NSSMDNS = strings.TrimSpace(r.Stdout)
+	}
+	if rs, err := m.Root("nft", "list", "ruleset"); err == nil {
+		open := InboundMDNS(rs)
+		s.InboundMDNS = &open
+		if !open {
+			s.Notes = append(s.Notes, "the packet filter drops inbound UDP 5353: this machine announces itself but hears no other machine's mDNS")
+		}
+	} else {
+		s.FilterError = err.Error()
+	}
+	if p, err := m.unitProps("systemd-resolved.service", "ActiveState"); err == nil {
+		s.ResolvedOn = p["ActiveState"] == "active"
+	}
+	if s.MDNSWired && s.NSSMDNS == "" {
+		s.Notes = append(s.Notes, "nsswitch names mdns and nss-mdns is not installed: those lookups fail")
+	}
+	if !s.MDNSWired {
+		s.Notes = append(s.Notes, "nsswitch does not name mdns: ordinary lookups never ask avahi")
+	}
+	return s, nil
+}
+
+// Service is one service a browse found.
+type Service struct {
+	Interface string   `json:"interface"`
+	Protocol  string   `json:"protocol"`
+	Name      string   `json:"name"`
+	Type      string   `json:"type"`
+	Domain    string   `json:"domain"`
+	Host      string   `json:"host,omitempty"`
+	Address   string   `json:"address,omitempty"`
+	Port      int      `json:"port,omitempty"`
+	TXT       []string `json:"txt,omitempty"`
+	Resolved  bool     `json:"resolved"`
+}
+
+// unescape undoes avahi-browse -p's escaping: a special byte as a backslash and three decimals, any
+// other character after a backslash as itself. Decoded as bytes, so a name in UTF-8 stays whole.
+func unescape(s string) string {
+	out := make([]byte, 0, len(s))
+	for i := 0; i < len(s); i++ {
+		if s[i] == '\\' {
+			if d := s[i+1 : min(i+4, len(s))]; len(d) == 3 && isDigits(d) {
+				n, _ := strconv.Atoi(d)
+				out = append(out, byte(n))
+				i += 3
+				continue
+			}
+			if i+1 < len(s) {
+				out = append(out, s[i+1])
+				i++
+				continue
+			}
+		}
+		out = append(out, s[i])
+	}
+	return string(out)
+}
+
+func isDigits(s string) bool {
+	for _, c := range s {
+		if c < '0' || c > '9' {
+			return false
+		}
+	}
+	return true
+}
+
+var txtItem = regexp.MustCompile(`"((?:[^"\\]|\\.)*)"`)
+
+// ParseBrowse reads `avahi-browse -p -r`: `+` lines found, `=` lines resolved; a found service
+// that resolved is answered once, resolved.
+func ParseBrowse(out string) []Service {
+	byKey := map[string]int{}
+	services := []Service{}
+	for _, l := range lines(out) {
+		f := strings.Split(l, ";")
+		if len(f) < 6 || (f[0] != "+" && f[0] != "=") {
+			continue
+		}
+		s := Service{Interface: f[1], Protocol: f[2], Name: unescape(f[3]), Type: f[4], Domain: f[5]}
+		if f[0] == "=" && len(f) >= 9 {
+			s.Resolved, s.Host, s.Address = true, f[6], f[7]
+			s.Port, _ = strconv.Atoi(f[8])
+			if len(f) >= 10 {
+				for _, t := range txtItem.FindAllStringSubmatch(strings.Join(f[9:], ";"), -1) {
+					s.TXT = append(s.TXT, t[1])
+				}
+			}
+		}
+		key := strings.Join([]string{s.Interface, s.Protocol, s.Name, s.Type, s.Domain}, "\x00")
+		if i, seen := byKey[key]; seen {
+			if s.Resolved {
+				services[i] = s
+			}
+			continue
+		}
+		byKey[key] = len(services)
+		services = append(services, s)
+	}
+	sort.SliceStable(services, func(i, j int) bool {
+		if services[i].Type != services[j].Type {
+			return services[i].Type < services[j].Type
+		}
+		return services[i].Name < services[j].Name
+	})
+	return services
+}
+
+var serviceType = regexp.MustCompile(`^_[A-Za-z0-9-]+\._(tcp|udp)$`)
+
+// Browse listens for a few seconds and answers every service announced, resolved where it could be.
+func (m *Machine) Browse(seconds int, kind string) (map[string]any, error) {
+	args := []string{strconv.Itoa(seconds), "avahi-browse", "-p", "-r", "-t"}
+	if kind == "" {
+		args = append(args, "-a")
+	} else {
+		if !serviceType.MatchString(kind) {
+			return nil, fmt.Errorf("%q is not a service type such as _ssh._tcp", kind)
+		}
+		args = append(args, kind)
+	}
+	r := m.Run(bg(), "timeout", args...)
+	// timeout's 124 is the listening time ending, which is how a browse that keeps hearing ends.
+	if r.Err != "" || (r.Status != 0 && r.Status != 124) {
+		return nil, failure("avahi-browse", "avahi-browse", r)
+	}
+	services := ParseBrowse(r.Stdout)
+	out := map[string]any{"seconds": seconds, "count": len(services), "services": services}
+	if len(services) == 0 {
+		out["note"] = m.silenceNote()
+	}
+	return out, nil
+}
+
+// silenceNote says why nothing may have been heard, from the packet filter when it can be read.
+func (m *Machine) silenceNote() string {
+	if rs, err := m.Root("nft", "list", "ruleset"); err == nil && !InboundMDNS(rs) {
+		return "nothing was heard, and this machine's packet filter drops inbound UDP 5353 (mDNS): other machines' answers do not reach avahi"
+	}
+	return "nothing was heard on the local network"
+}
+
+// Resolve asks avahi for a name's address (or an address's name), and the name service the same,
+// so an answer avahi has and an ordinary lookup does not shows the switch unwired.
+func (m *Machine) Resolve(name, address string) (map[string]any, error) {
+	if (name == "") == (address == "") {
+		return nil, fmt.Errorf("give a name or an address")
+	}
+	out := map[string]any{}
+	var r Ran
+	if name != "" {
+		if !strings.HasSuffix(name, ".local") {
+			name += ".local"
+		}
+		out["name"] = name
+		r = m.Run(bg(), "avahi-resolve", "-n", name)
+	} else {
+		if net.ParseIP(address) == nil {
+			return nil, fmt.Errorf("%q is not an address", address)
+		}
+		out["address"] = address
+		r = m.Run(bg(), "avahi-resolve", "-a", address)
+	}
+	if r.Err != "" {
+		return nil, failure("avahi-resolve", "avahi-resolve", r)
+	}
+	// avahi-resolve says a failure on stderr and exits 0.
+	avahi := map[string]any{"answers": []string{}}
+	for _, l := range lines(r.Stdout) {
+		if f := strings.Fields(l); len(f) >= 2 {
+			avahi["answers"] = append(avahi["answers"].([]string), f[1])
+		}
+	}
+	if said := firstLine(r.Stderr); said != "" {
+		avahi["error"] = said
+	}
+	avahi["resolved"] = len(avahi["answers"].([]string)) > 0
+	out["avahi"] = avahi
+	if name != "" {
+		nss := map[string]any{"answers": []string{}}
+		g := m.Run(bg(), "getent", "hosts", name)
+		for _, l := range lines(g.Stdout) {
+			if f := strings.Fields(l); len(f) >= 1 {
+				nss["answers"] = append(nss["answers"].([]string), f[0])
+			}
+		}
+		nss["resolved"] = len(nss["answers"].([]string)) > 0
+		out["name_service"] = nss
+	}
+	if avahi["resolved"] == false {
+		out["note"] = m.silenceNote()
+	}
+	return out, nil
+}
+
+// Published is one service this machine announces from a file of /etc/avahi/services.
+type Published struct {
+	File  string   `json:"file"`
+	Name  string   `json:"name,omitempty"`
+	Types []string `json:"types"`
+	Ports []int    `json:"ports"`
+}
+
+var (
+	xmlName = regexp.MustCompile(`<name[^>]*>([^<]*)</name>`)
+	xmlType = regexp.MustCompile(`<type>([^<]*)</type>`)
+	xmlPort = regexp.MustCompile(`<port>(\d+)</port>`)
+)
+
+// Services is what this machine publishes from its service files.
+func (m *Machine) Services() (map[string]any, error) {
+	r := m.Run(bg(), "find", ServicesDir, "-mindepth", "1", "-maxdepth", "1", "-name", "*.service", "-printf", "%f\n")
+	if r.Err != "" || r.Status != 0 {
+		if strings.Contains(r.Stderr, "No such file") {
+			return map[string]any{"directory": ServicesDir, "published": []Published{}}, nil
+		}
+		return nil, failure("find", "find", r)
+	}
+	pub := []Published{}
+	names := lines(r.Stdout)
+	sort.Strings(names)
+	for _, n := range names {
+		text, err := m.ReadFile(ServicesDir + "/" + n)
+		if err != nil {
+			return nil, err
+		}
+		p := Published{File: n, Types: []string{}, Ports: []int{}}
+		if x := xmlName.FindStringSubmatch(string(text)); x != nil {
+			p.Name = x[1]
+		}
+		for _, t := range xmlType.FindAllStringSubmatch(string(text), -1) {
+			p.Types = append(p.Types, t[1])
+		}
+		for _, x := range xmlPort.FindAllStringSubmatch(string(text), -1) {
+			port, _ := strconv.Atoi(x[1])
+			p.Ports = append(p.Ports, port)
+		}
+		pub = append(pub, p)
+	}
+	return map[string]any{"directory": ServicesDir, "published": pub}, nil
+}

modules/avahi/cmd/avahi-tools/avahi_test.go

@@ -0,0 +1,165 @@
+package main
+
+import (
+	"strings"
+	"testing"
+)
+
+const browse = `+;enp6s0;IPv4;home\032server;_ssh._tcp;local
++;enp6s0;IPv4;Printer\046Co;_ipp._tcp;local
+=;enp6s0;IPv4;home\032server;_ssh._tcp;local;home-server.local;192.168.1.10;22;
+=;enp6s0;IPv4;Printer\046Co;_ipp._tcp;local;printer.local;192.168.1.20;631;"txtvers=1" "rp=ipp/print"
++;enp6s0;IPv6;Kitchen;_spotify-connect._tcp;local
+`
+
+func TestABrowseIsReadResolvedOnceAndUnescaped(t *testing.T) {
+	s := ParseBrowse(browse)
+	if len(s) != 3 {
+		t.Fatalf("%+v", s)
+	}
+	by := map[string]Service{}
+	for _, x := range s {
+		by[x.Name] = x
+	}
+	ssh := by["home server"]
+	if !ssh.Resolved || ssh.Address != "192.168.1.10" || ssh.Port != 22 || ssh.Host != "home-server.local" {
+		t.Fatalf("%+v", ssh)
+	}
+	ipp := by["Printer.Co"]
+	if strings.Join(ipp.TXT, ",") != "txtvers=1,rp=ipp/print" {
+		t.Fatalf("%+v", ipp)
+	}
+	if k := by["Kitchen"]; k.Resolved || k.Type != "_spotify-connect._tcp" {
+		t.Fatalf("%+v", k)
+	}
+	if unescape(`caf\195\169`) != "café" || unescape(`a\.b`) != "a.b" {
+		t.Fatal("unescape")
+	}
+}
+
+func TestABrowseThatHearsNothingSaysTheFilterDropsMDNS(t *testing.T) {
+	var calls []call
+	m := machine(fake(func(c call) Ran {
+		switch c.String() {
+		case "timeout 5 avahi-browse -p -r -t -a":
+			return Ran{Status: 124}
+		case "sudo -n nft list ruleset":
+			return Ran{Stdout: "table inet mesh {\n chain input {\n type filter hook input priority filter; policy drop;\n tcp dport 22 accept\n }\n}\n"}
+		}
+		return Ran{Status: 99}
+	}, &calls), 1000)
+	r, err := m.Browse(5, "")
+	if err != nil || r["count"] != 0 || !strings.Contains(r["note"].(string), "drops inbound UDP 5353") {
+		t.Fatalf("%v %v", r, err)
+	}
+	if _, err := m.Browse(5, "ssh; rm"); err == nil {
+		t.Fatal("not a service type")
+	}
+}
+
+func TestTheFilterIsReadForAnAcceptedInboundMDNS(t *testing.T) {
+	for rs, want := range map[string]bool{
+		"\t\tudp dport 5353 accept\n":                            true,
+		"\t\tiifname \"enp6s0\" udp dport { 53, 5353 } accept\n": true,
+		"\t\tudp dport mdns accept\n":                            true,
+		"\t\tudp dport 53 accept\n":                              false,
+		"\t\tudp dport 5353 drop\n":                              false,
+		"\t\tip saddr 10.0.0.0/8 udp dport 15353 accept\n":       false,
+	} {
+		if InboundMDNS(rs) != want {
+			t.Errorf("%q: %v", rs, !want)
+		}
+	}
+}
+
+func TestStatusNamesTheSwitchTheFilterAndTheDaemon(t *testing.T) {
+	m := machine(fake(func(c call) Ran {
+		switch {
+		case c.name == "systemctl" && c.args[1] == Daemon:
+			return Ran{Stdout: "LoadState=loaded\nActiveState=active\nUnitFileState=enabled\n"}
+		case c.name == "systemctl":
+			return Ran{Stdout: "ActiveState=inactive\n"}
+		case c.String() == "avahi-daemon --version":
+			return Ran{Stdout: "avahi-daemon 0.9-rc5\n"}
+		case c.String() == "pacman -Q nss-mdns":
+			return Ran{Stdout: "nss-mdns 0.15.1-2\n"}
+		case c.String() == "sudo -n nft list ruleset":
+			return Ran{Stdout: "udp dport 53 accept\n"}
+		}
+		return Ran{Status: 99}
+	}, nil), 1000)
+	files := map[string]string{
+		DaemonConf: "[server]\nuse-ipv4=yes\n#host-name=foo\nallow-interfaces=enp6s0\n[publish]\npublish-hinfo=no\n",
+		NSSwitch:   "passwd: files\nhosts: mymachines files dns mdns4_minimal [NOTFOUND=return] resolve [!UNAVAIL=return]\n",
+	}
+	m.ReadFile = func(p string) ([]byte, error) {
+		if s, ok := files[p]; ok {
+			return []byte(s), nil
+		}
+		return nil, errNoFile
+	}
+	s, err := m.GetStatus()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !s.MDNSWired || s.NSSMDNS != "nss-mdns 0.15.1-2" || s.InboundMDNS == nil || *s.InboundMDNS || s.Version != "avahi-daemon 0.9-rc5" {
+		t.Fatalf("%+v", s)
+	}
+	if s.Config["server"]["allow-interfaces"] != "enp6s0" || s.Config["server"]["host-name"] != "" || s.Daemon["ActiveState"] != "active" {
+		t.Fatalf("%+v", s.Config)
+	}
+	if len(s.Notes) != 1 || !strings.Contains(s.Notes[0], "drops inbound UDP 5353") {
+		t.Fatalf("%v", s.Notes)
+	}
+	if _, wired := HostsLine("hosts: files dns\n"); wired {
+		t.Fatal("no mdns on the line")
+	}
+}
+
+func TestResolveAsksAvahiAndTheNameServiceAndReadsAFailureFromStderr(t *testing.T) {
+	m := machine(byLine(map[string]Ran{
+		"avahi-resolve -n printer.local": {Stdout: "printer.local\t192.168.1.20\n"},
+		"getent hosts printer.local":     {Status: 2},
+		"avahi-resolve -n nowhere.local": {Stderr: "Failed to resolve host name 'nowhere.local': Timeout reached\n"},
+		"getent hosts nowhere.local":     {Status: 2},
+		"sudo -n nft list ruleset":       {Stdout: "udp dport 5353 accept\n"},
+		"avahi-resolve -a 192.168.1.20":  {Stdout: "192.168.1.20\tprinter.local\n"},
+	}, nil), 1000)
+	r, err := m.Resolve("printer", "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if r["avahi"].(map[string]any)["resolved"] != true || r["name_service"].(map[string]any)["resolved"] != false {
+		t.Fatalf("%v", r)
+	}
+	r, _ = m.Resolve("nowhere.local", "")
+	if a := r["avahi"].(map[string]any); a["resolved"] != false || !strings.Contains(a["error"].(string), "Timeout reached") || r["note"] != "nothing was heard on the local network" {
+		t.Fatalf("%v", r)
+	}
+	r, _ = m.Resolve("", "192.168.1.20")
+	if r["avahi"].(map[string]any)["answers"].([]string)[0] != "printer.local" {
+		t.Fatalf("%v", r)
+	}
+	for _, bad := range [][2]string{{"", ""}, {"a", "1.2.3.4"}, {"", "not-an-ip"}} {
+		if _, err := m.Resolve(bad[0], bad[1]); err == nil {
+			t.Errorf("%v accepted", bad)
+		}
+	}
+}
+
+func TestPublishedServicesAreReadFromTheirFiles(t *testing.T) {
+	m := machine(byLine(map[string]Ran{
+		"find /etc/avahi/services -mindepth 1 -maxdepth 1 -name *.service -printf %f\n": {Stdout: "ssh.service\n"},
+	}, nil), 1000)
+	m.ReadFile = func(string) ([]byte, error) {
+		return []byte(`<service-group><name replace-wildcards="yes">%h</name><service><type>_ssh._tcp</type><port>22</port></service></service-group>`), nil
+	}
+	r, err := m.Services()
+	if err != nil {
+		t.Fatal(err)
+	}
+	p := r["published"].([]Published)
+	if len(p) != 1 || p[0].Name != "%h" || p[0].Types[0] != "_ssh._tcp" || p[0].Ports[0] != 22 {
+		t.Fatalf("%+v", p)
+	}
+}

modules/avahi/cmd/avahi-tools/machine.go

@@ -0,0 +1,289 @@
+package main
+
+// The commands this bundle runs on its machine, and who runs them.
+//
+// Who asks. The node's tool runtime runs as the operator account, not root (novox/hq ADR 0175 §4),
+// and launches this binary as a process of its own (ADR 0188, ADR 0193) with the runtime's words —
+// HOME, a PATH, MESH_OPERATOR_ACCOUNT — and no session words. Reading needs nothing more; what only
+// root may do goes through `sudo -n`, as the packet filter's, the service manager's and the
+// intrusion prevention's tools do (to-be 38 WP4), and the `sudo` module is what declares that the
+// account may (to-be 42, research 027). A refusal is named by how it failed, never read as an
+// empty answer.
+//
+// The runner is injected, so every tool is tested over a fake one without the machine.
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"io/fs"
+	"os"
+	"os/exec"
+	"strings"
+	"time"
+)
+
+// Ran is what one command did: its output, its exit status, and why it never ran to an answer.
+type Ran struct {
+	Stdout string
+	Stderr string
+	Status int
+	// Err is "ENOENT" when the program is not there, or that it was ended for taking too long.
+	Err string
+}
+
+// Runner runs one command, so the tools can be tested without the machine.
+type Runner func(ctx context.Context, name string, args ...string) Ran
+
+// CallTimeout is how long one command may take: below the runtime's thirty-second call limit, so a
+// command that hangs is answered as such rather than as a call the runtime gave up on.
+const CallTimeout = 20 * time.Second
+
+// outputLimit bounds what one command may hand back, so a runaway listing cannot exhaust the
+// process; well above anything a tool answers.
+const outputLimit = 16 << 20
+
+type bounded struct {
+	bytes.Buffer
+	cut bool
+}
+
+func (b *bounded) Write(p []byte) (int, error) {
+	if room := outputLimit - b.Len(); room < len(p) {
+		if room > 0 {
+			b.Buffer.Write(p[:room])
+		}
+		b.cut = true
+		return len(p), nil
+	}
+	return b.Buffer.Write(p)
+}
+
+// ExecRunner runs a command on this machine, in the C locale so what is parsed is one language.
+func ExecRunner(ctx context.Context, name string, args ...string) Ran {
+	ctx, cancel := context.WithTimeout(ctx, CallTimeout)
+	defer cancel()
+	cmd := exec.CommandContext(ctx, name, args...)
+	cmd.Env = append(os.Environ(), "LC_ALL=C")
+	var out, errb bounded
+	cmd.Stdout, cmd.Stderr = &out, &errb
+	err := cmd.Run()
+	r := Ran{Stdout: out.String(), Stderr: errb.String()}
+	if ctx.Err() == context.DeadlineExceeded {
+		r.Status, r.Err = 124, fmt.Sprintf("no answer within %d s", int(CallTimeout.Seconds()))
+		return r
+	}
+	var exit *exec.ExitError
+	switch {
+	case err == nil:
+	case errors.As(err, &exit):
+		r.Status = exit.ExitCode()
+	case errors.Is(err, exec.ErrNotFound) || errors.Is(err, fs.ErrNotExist):
+		r.Status, r.Err = 127, "ENOENT"
+	default:
+		r.Status, r.Err = 126, err.Error()
+	}
+	return r
+}
+
+// Escalated is the command as it is run: as given when this process is root, else through sudo
+// without a prompt.
+func Escalated(uid int, name string, args ...string) (string, []string) {
+	if uid == 0 {
+		return name, args
+	}
+	return "sudo", append([]string{"-n", name}, args...)
+}
+
+// Machine is this machine as the tools see it: a runner, who this process is, and its files.
+type Machine struct {
+	Run      Runner
+	UID      int
+	User     string
+	Account  string
+	ReadFile func(path string) ([]byte, error)
+	Now      func() time.Time
+	Sleep    func(time.Duration)
+}
+
+// ThisMachine is the machine the runtime launched this bundle on.
+func ThisMachine() *Machine {
+	user := os.Getenv("USER")
+	if user == "" {
+		user = os.Getenv("LOGNAME")
+	}
+	account := strings.TrimSpace(os.Getenv("MESH_OPERATOR_ACCOUNT"))
+	if account == "" {
+		account = user
+	}
+	return &Machine{Run: ExecRunner, UID: os.Getuid(), User: user, Account: account, ReadFile: os.ReadFile, Now: time.Now, Sleep: time.Sleep}
+}
+
+// Out runs a command that only reads, and fails with what went wrong named.
+func (m *Machine) Out(name string, args ...string) (string, error) {
+	r := m.Run(context.Background(), name, args...)
+	if r.Status == 0 && r.Err == "" {
+		return r.Stdout, nil
+	}
+	return r.Stdout, failure(name, name, r)
+}
+
+// Root runs a command that needs root, escalated when this process is not.
+func (m *Machine) Root(name string, args ...string) (string, error) {
+	program, argv := Escalated(m.UID, name, args...)
+	r := m.Run(context.Background(), program, argv...)
+	if r.Status == 0 && r.Err == "" {
+		return r.Stdout, nil
+	}
+	return r.Stdout, failure(name, program, r)
+}
+
+// RootRan is Root's raw answer, for a command whose non-zero status is itself an answer.
+func (m *Machine) RootRan(name string, args ...string) (Ran, error) {
+	program, argv := Escalated(m.UID, name, args...)
+	r := m.Run(context.Background(), program, argv...)
+	if r.Err != "" || (program == "sudo" && sudoRefused(r)) {
+		return r, failure(name, program, r)
+	}
+	return r, nil
+}
+
+func sudoRefused(r Ran) bool {
+	return strings.HasPrefix(strings.TrimSpace(r.Stderr), "sudo:")
+}
+
+// failure names what failed by how it failed: the program missing is a spawn error, sudo missing
+// or refusing speaks for itself, and the rest is the command's own first line.
+func failure(cmd, program string, r Ran) error {
+	said := strings.TrimSpace(r.Stderr + "\n" + r.Stdout)
+	if r.Err == "ENOENT" {
+		if program == "sudo" {
+			return fmt.Errorf("%s needs root for this, and sudo is not installed here for the runtime's account to escalate with", cmd)
+		}
+		return fmt.Errorf("%s is not installed on this machine", cmd)
+	}
+	if r.Err != "" {
+		return fmt.Errorf("%s did not answer: %s", cmd, r.Err)
+	}
+	if program == "sudo" && sudoRefused(r) {
+		if strings.Contains(said, "command not found") {
+			return fmt.Errorf("%s is not installed on this machine", cmd)
+		}
+		return fmt.Errorf("%s needs root for this and the runtime's account may not run it without a prompt: %s", cmd, firstLine(said))
+	}
+	if line := firstLine(said); line != "" {
+		return fmt.Errorf("%s failed (%d): %s", cmd, r.Status, line)
+	}
+	return fmt.Errorf("%s failed with status %d", cmd, r.Status)
+}
+
+func firstLine(text string) string {
+	for _, l := range strings.Split(text, "\n") {
+		if l = strings.TrimSpace(l); l != "" {
+			return l
+		}
+	}
+	return ""
+}
+
+func lines(text string) []string {
+	var out []string
+	for _, l := range strings.Split(text, "\n") {
+		if l = strings.TrimRight(l, "\r"); strings.TrimSpace(l) != "" {
+			out = append(out, l)
+		}
+	}
+	return out
+}
+
+// text is a string argument; required says whether it may be absent. It is never something a
+// command would read as an option, which under sudo would be root's option.
+func text(args map[string]any, key string, required bool) (string, error) {
+	raw, present := args[key]
+	if !present || raw == nil {
+		if required {
+			return "", fmt.Errorf("%s is required", key)
+		}
+		return "", nil
+	}
+	s, ok := raw.(string)
+	if !ok {
+		return "", fmt.Errorf("%s must be a string", key)
+	}
+	s = strings.TrimSpace(s)
+	if required && s == "" {
+		return "", fmt.Errorf("%s is required", key)
+	}
+	if strings.HasPrefix(s, "-") || strings.ContainsRune(s, 0) || strings.ContainsAny(s, "\n\r") {
+		return "", fmt.Errorf("%s %q is not a value this tool passes on", key, s)
+	}
+	return s, nil
+}
+
+// whole is a whole-number argument with a default, kept within bounds.
+func whole(args map[string]any, key string, def, least, most int) (int, error) {
+	raw, present := args[key]
+	if !present || raw == nil {
+		return def, nil
+	}
+	f, ok := raw.(float64)
+	if !ok || f != float64(int(f)) {
+		return 0, fmt.Errorf("%s must be a whole number", key)
+	}
+	n := int(f)
+	if n < least {
+		return 0, fmt.Errorf("%s must be at least %d", key, least)
+	}
+	if n > most {
+		n = most
+	}
+	return n, nil
+}
+
+// flag is a boolean argument, false when absent.
+func flag(args map[string]any, key string) (bool, error) {
+	raw, present := args[key]
+	if !present || raw == nil {
+		return false, nil
+	}
+	b, ok := raw.(bool)
+	if !ok {
+		return false, fmt.Errorf("%s must be true or false", key)
+	}
+	return b, nil
+}
+
+// schema is a tool's input: its properties and the ones it requires.
+func schema(properties map[string]any, required ...string) map[string]any {
+	s := map[string]any{"type": "object", "properties": properties}
+	if len(required) > 0 {
+		s["required"] = required
+	}
+	return s
+}
+
+// unitProps reads a unit's properties as systemctl shows them.
+func (m *Machine) unitProps(unit string, props ...string) (map[string]string, error) {
+	args := []string{"show", unit, "--no-pager"}
+	for _, p := range props {
+		args = append(args, "--property="+p)
+	}
+	out, err := m.Out("systemctl", args...)
+	if err != nil {
+		return nil, err
+	}
+	return keyValues(out, "="), nil
+}
+
+// keyValues reads `key<sep>value` lines; a line without the separator is skipped.
+func keyValues(out, sep string) map[string]string {
+	kv := map[string]string{}
+	for _, l := range strings.Split(out, "\n") {
+		k, v, ok := strings.Cut(l, sep)
+		if ok {
+			kv[strings.TrimSpace(k)] = strings.TrimSpace(v)
+		}
+	}
+	return kv
+}

modules/avahi/cmd/avahi-tools/machine_test.go

@@ -0,0 +1,107 @@
+package main
+
+import (
+	"context"
+	"strings"
+	"testing"
+	"time"
+)
+
+// call is one command a fake runner was asked to run.
+type call struct {
+	name string
+	args []string
+}
+
+func (c call) String() string {
+	if len(c.args) == 0 {
+		return c.name
+	}
+	return c.name + " " + strings.Join(c.args, " ")
+}
+
+// fake is a runner answering by the command line it is given, recording every call.
+func fake(answer func(c call) Ran, calls *[]call) Runner {
+	return func(_ context.Context, name string, args ...string) Ran {
+		c := call{name, append([]string(nil), args...)}
+		if calls != nil {
+			*calls = append(*calls, c)
+		}
+		return answer(c)
+	}
+}
+
+// byLine answers from a table keyed by the whole command line, and refuses anything else as a
+// command the test did not expect.
+func byLine(table map[string]Ran, calls *[]call) Runner {
+	return fake(func(c call) Ran {
+		if r, ok := table[c.String()]; ok {
+			return r
+		}
+		return Ran{Status: 99, Stderr: "unexpected command: " + c.String()}
+	}, calls)
+}
+
+func machine(run Runner, uid int) *Machine {
+	return &Machine{Run: run, UID: uid, User: "operator", Account: "operator",
+		ReadFile: func(string) ([]byte, error) { return nil, errNoFile },
+		Now:      func() time.Time { return time.Date(2026, 10, 4, 12, 0, 0, 0, time.UTC) },
+		Sleep:    func(time.Duration) {}}
+}
+
+type noFile struct{}
+
+func (noFile) Error() string { return "no such file" }
+
+var errNoFile = noFile{}
+
+func TestAnActNeedingRootGoesThroughSudoWithoutAPromptUnlessThisIsRoot(t *testing.T) {
+	if p, a := Escalated(1000, "visudo", "-c"); p != "sudo" || strings.Join(a, " ") != "-n visudo -c" {
+		t.Fatalf("not root: %s %v", p, a)
+	}
+	if p, a := Escalated(0, "visudo", "-c"); p != "visudo" || strings.Join(a, " ") != "-c" {
+		t.Fatalf("root: %s %v", p, a)
+	}
+}
+
+func TestFailuresAreNamedNeverReadAsEmpty(t *testing.T) {
+	cases := []struct {
+		r    Ran
+		want string
+	}{
+		{Ran{Status: 127, Err: "ENOENT"}, "sudo is not installed here"},
+		{Ran{Status: 1, Stderr: "sudo: a password is required\n"}, "may not run it without a prompt: sudo: a password is required"},
+		{Ran{Status: 124, Err: "no answer within 20 s"}, "did not answer: no answer within 20 s"},
+		{Ran{Status: 2, Stderr: "boom\nmore"}, "failed (2): boom"},
+	}
+	for _, c := range cases {
+		m := machine(fake(func(call) Ran { return c.r }, nil), 1000)
+		if _, err := m.Root("thing"); err == nil || !strings.Contains(err.Error(), c.want) {
+			t.Errorf("%+v: %v, want %q", c.r, err, c.want)
+		}
+	}
+	m := machine(fake(func(call) Ran { return Ran{Status: 127, Err: "ENOENT"} }, nil), 1000)
+	if _, err := m.Out("thing"); err == nil || !strings.Contains(err.Error(), "thing is not installed") {
+		t.Errorf("a missing program: %v", err)
+	}
+}
+
+func TestAnArgumentIsNeverAnOption(t *testing.T) {
+	for _, bad := range []any{"-rf", "a\nb", 3.0} {
+		if _, err := text(map[string]any{"x": bad}, "x", true); err == nil {
+			t.Errorf("%v was accepted", bad)
+		}
+	}
+	if s, err := text(map[string]any{"x": " ok "}, "x", true); err != nil || s != "ok" {
+		t.Errorf("a plain value: %q %v", s, err)
+	}
+	if _, err := text(map[string]any{}, "x", true); err == nil {
+		t.Error("a missing required value was accepted")
+	}
+	if n, _ := whole(map[string]any{"n": 10000.0}, "n", 5, 1, 100); n != 100 {
+		t.Errorf("not bounded: %d", n)
+	}
+	if _, err := whole(map[string]any{"n": 0.0}, "n", 5, 1, 100); err == nil {
+		t.Error("below the least was accepted")
+	}
+}

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

@@ -0,0 +1,85 @@
+// avahi's tools bundle (novox/hq to-be 42 Phase 1, research 026/05): a process the node's runtime
+// launches and speaks MCP over stdio to, through the Go SDK (ADR 0188, ADR 0193). It reads the
+// daemon, the name service's wiring and the packet filter's view of mDNS, browses the local network
+// for services, resolves a name, and lists what the machine publishes. It changes nothing.
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+// binaryName is what the build names this bundle's executable: the manifest's `binary`.
+const binaryName = "avahi-tools"
+
+func bg() context.Context { return context.Background() }
+
+func main() {
+	// An empty name serves as the module the runtime names (MESH_SERVED_MODULE): avahi.
+	if err := stdio.Serve("", tools(ThisMachine())); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+func tools(m *Machine) []stdio.Tool {
+	return []stdio.Tool{
+		{
+			Name: "avahi_status",
+			Description: "The daemon's state and version, its configuration as set, the name service switch's hosts line and whether mdns is on it, " +
+				"whether nss-mdns is installed, whether the packet filter accepts inbound mDNS (UDP 5353), whether systemd-resolved runs beside it, " +
+				"and notes naming what keeps discovery from working.",
+			Input: schema(map[string]any{}),
+			Run:   func(map[string]any) (any, error) { return m.GetStatus() },
+		},
+		{
+			Name: "avahi_browse",
+			Description: "Listen on the local network for a few seconds (avahi-browse -prt) and answer every service announced, with interface, " +
+				"protocol, name, type, host, address, port and TXT where it resolved; narrowed to one service type when given. Hearing nothing says why it may be.",
+			Input: schema(map[string]any{
+				"seconds": map[string]any{"type": "integer", "description": "how long to listen (default 5, at most 15)"},
+				"type":    map[string]any{"type": "string", "description": "one service type, e.g. _ssh._tcp (optional)"},
+			}),
+			Run: func(args map[string]any) (any, error) {
+				n, err := whole(args, "seconds", 5, 1, 15)
+				if err != nil {
+					return nil, err
+				}
+				kind, err := text(args, "type", false)
+				if err != nil {
+					return nil, err
+				}
+				return m.Browse(n, kind)
+			},
+		},
+		{
+			Name: "avahi_resolve",
+			Description: "Resolve a .local name to its addresses through avahi, and through the name service (getent) beside it, or an address to its name. " +
+				"An answer from avahi that the name service lacks shows nsswitch unwired; no answer says why it may be.",
+			Input: schema(map[string]any{
+				"name":    map[string]any{"type": "string", "description": "a host name; .local is added when missing"},
+				"address": map[string]any{"type": "string", "description": "an address to name instead"},
+			}),
+			Run: func(args map[string]any) (any, error) {
+				name, err := text(args, "name", false)
+				if err != nil {
+					return nil, err
+				}
+				address, err := text(args, "address", false)
+				if err != nil {
+					return nil, err
+				}
+				return m.Resolve(name, address)
+			},
+		},
+		{
+			Name:        "avahi_services",
+			Description: "What this machine publishes from /etc/avahi/services: each file with the service's name, types and ports.",
+			Input:       schema(map[string]any{}),
+			Run:         func(map[string]any) (any, error) { return m.Services() },
+		},
+	}
+}

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

@@ -0,0 +1,26 @@
+package main
+
+// The module's shape (novox/hq to-be 42 Phase 1, research 027): the package and the daemon, and
+// nothing written into the name service switch or opened in the packet filter — avahi.go says why
+// neither can be declared safely today, and the tools report both instead.
+
+import "testing"
+
+func TestItDeclaresThePackageAndTheDaemonOnly(t *testing.T) {
+	m := manifest(t)
+	if p := m.resource(t, "package"); p["package"] != "avahi" {
+		t.Fatalf("%v", p)
+	}
+	d := m.resource(t, "daemon")
+	if d["unit"] != Daemon || d["state"] != "running" || d["boot"] != "enabled" {
+		t.Fatalf("%v", d)
+	}
+	for _, r := range m.Resources {
+		if r["path"] == NSSwitch || r["package"] == "nss-mdns" {
+			t.Fatalf("%v: the name service switch is left as found", r["id"])
+		}
+	}
+	if len(m.Resources) != 2 {
+		t.Fatalf("%v", m.Resources)
+	}
+}

modules/avahi/cmd/avahi-tools/shape_test.go

@@ -0,0 +1,80 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"testing"
+)
+
+type resource map[string]any
+
+type manifestShape struct {
+	Module       string           `json:"module"`
+	Version      string           `json:"version"`
+	Capabilities []string         `json:"capabilities"`
+	Claims       []map[string]any `json:"claims"`
+	Tools        []string         `json:"tools"`
+	Resources    []resource       `json:"resources"`
+	Build        struct {
+		Artifacts []map[string]any `json:"artifacts"`
+	} `json:"build"`
+}
+
+func manifest(t *testing.T) manifestShape {
+	t.Helper()
+	raw, err := os.ReadFile("../../module.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var m manifestShape
+	if err := json.Unmarshal(raw, &m); err != nil {
+		t.Fatal(err)
+	}
+	return m
+}
+
+func (m manifestShape) resource(t *testing.T, id string) resource {
+	t.Helper()
+	for _, r := range m.Resources {
+		if r["id"] == id {
+			return r
+		}
+	}
+	t.Fatalf("no resource %s", id)
+	return nil
+}
+
+// TestToolsAreTheManifests holds the served tools and the manifest's list to one another, and the
+// bundle to the shape the builder compiles and the runtime loads.
+func TestToolsAreTheManifests(t *testing.T) {
+	m := manifest(t)
+	names := map[string]bool{}
+	for _, tool := range tools(machine(nil, 1000)) {
+		if names[tool.Name] {
+			t.Errorf("%s is served twice", tool.Name)
+		}
+		names[tool.Name] = true
+	}
+	for _, want := range m.Tools {
+		if !names[want] {
+			t.Errorf("the manifest lists %s and the bundle does not serve it", want)
+		}
+		delete(names, want)
+	}
+	if len(names) != 0 {
+		t.Errorf("served and not listed: %v", names)
+	}
+	var tools map[string]any
+	for _, a := range m.Build.Artifacts {
+		if a["name"] == "tools" {
+			tools = a
+		}
+	}
+	if tools == nil || tools["kind"] != "bundle" || tools["language"] != "go" || tools["system"] != "arch" ||
+		tools["from"] != "cmd/"+binaryName || tools["binary"] != binaryName {
+		t.Fatalf("the tools artifact: %v", tools)
+	}
+	if loads, _ := tools["loads"].([]any); len(loads) != 1 || loads[0] != binaryName {
+		t.Fatalf("loads: %v", tools["loads"])
+	}
+}

modules/avahi/go.mod

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

modules/avahi/go.sum

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

modules/avahi/module.json

@@ -0,0 +1,43 @@
+{
+  "module": "avahi",
+  "version": "1",
+  "capabilities": [
+    "package-manager",
+    "service-manager"
+  ],
+  "tools": [
+    "avahi_status",
+    "avahi_browse",
+    "avahi_resolve",
+    "avahi_services"
+  ],
+  "resources": [
+    {
+      "id": "package",
+      "type": "package",
+      "package": "avahi"
+    },
+    {
+      "id": "daemon",
+      "type": "service",
+      "unit": "avahi-daemon.service",
+      "state": "running",
+      "boot": "enabled"
+    }
+  ],
+  "build": {
+    "artifacts": [
+      {
+        "name": "tools",
+        "kind": "bundle",
+        "language": "go",
+        "system": "arch",
+        "from": "cmd/avahi-tools",
+        "binary": "avahi-tools",
+        "loads": [
+          "avahi-tools"
+        ]
+      }
+    ]
+  }
+}

modules/bluetooth/README.md

@@ -0,0 +1,53 @@
+# bluetooth
+
+Bluetooth on the two workstations (novox/hq research 027/02, to-be 42 phase 2 step 9).
+
+## Owns
+
+| what | where |
+|---|---|
+| the Bluetooth stack and its daemon | package `bluez` |
+| `bluetoothctl`, which the tools speak through | package `bluez-utils` |
+| the daemon, running and enabled | `bluetooth.service` |
+
+All official. `/etc/bluetooth/main.conf` is the package's file, unchanged on both workstations
+(every setting commented out). The module states nothing in it, so it declares nothing there.
+
+## Improves
+
+- **The stack is declared, not a dependency of something else.** On both workstations `bluez` is
+  installed only as a dependency. Removing the applet that pulled it in would have left it an orphan
+  for the next clean-up to take, and Bluetooth with it.
+- **An owner for the daemon**, running and enabled on both today with nothing recording why.
+- **Headphones from the mesh.** `bluetooth_connect` and `bluetooth_devices` (with battery) answer from
+  any machine, without the applet.
+
+## Tools
+
+All answer JSON; `(r)` reads, `(a)` acts. They run as the operator account. bluez's bus policy lets
+the account act; if it ever refuses (`AccessDenied`), the act is repeated through `sudo -n`. An act
+whose output says it failed (`Failed to …`, `org.bluez.Error…`, `not available`) is an error, whatever
+bluetoothctl's exit status.
+
+| tool | what |
+|---|---|
+| `bluetooth_controller` (r) | address, name, powered, discoverable, pairable, discovering |
+| `bluetooth_power` (r/a) | read, or switch the controller on or off |
+| `bluetooth_devices` (r) | all, paired, connected or trusted devices: kind, paired, bonded, trusted, blocked, connected, battery where reported |
+| `bluetooth_scan` (r) | discover for 1 to 15 s (default 8); the unpaired devices found, strongest signal first |
+| `bluetooth_connect` / `bluetooth_disconnect` (a) | one device; connect waits up to 15 s |
+| `bluetooth_trust` (a) | trust, or untrust |
+| `bluetooth_pair` (a) | pair with an agent that confirms nothing (headphones, speakers), then trust. A device that shows a code is paired from the desktop |
+| `bluetooth_remove` (a) | forget a device |
+
+## What changes when it is assigned
+
+Nothing on disk on either workstation: both packages are installed, and the service is enabled and
+running. `bluez` becomes explicitly the mesh's.
+
+## Leaves as found
+
+- The paired devices and their keys under `/var/lib/bluetooth` (bluez's state).
+- `blueman` on both workstations, and its applet, which the window manager's configuration starts.
+  That line is the `i3` module's to keep or drop.
+- `bluez-obex` and the AUR terminal client `bluetuith-bin` (with its `-debug`) on the laptop.

modules/bluetooth/cmd/bluetooth-tools/bluetooth.go

@@ -0,0 +1,281 @@
+package main
+
+import (
+	"fmt"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+)
+
+var macAddress = regexp.MustCompile(`^[0-9A-Fa-f]{2}(:[0-9A-Fa-f]{2}){5}$`)
+
+func addressOf(args map[string]any) (string, error) {
+	a, err := text(args, "address")
+	if err != nil {
+		return "", err
+	}
+	if !macAddress.MatchString(a) {
+		return "", fmt.Errorf("%q is not a Bluetooth address (six hex pairs separated by colons)", a)
+	}
+	return strings.ToUpper(a), nil
+}
+
+var ansi = regexp.MustCompile(`\x1b\[[0-9;]*[A-Za-z]|\x01|\x02`)
+
+// btFailed are the words bluetoothctl uses for an act that did not happen, whatever its exit status.
+var btFailed = regexp.MustCompile(`(?m)(Failed to \w+|not available|org\.bluez\.Error\.\w+|No default controller available)`)
+
+// bt runs bluetoothctl once, non-interactively, as the account; bluez's bus policy lets the
+// account act, and if it refuses, the act is run through sudo -n.
+func bt(timeout time.Duration, args ...string) (string, error) {
+	c := Cmd{Name: "bluetoothctl", Args: args, Timeout: timeout}
+	r := run(c)
+	if strings.Contains(r.Stdout+r.Stderr, "AccessDenied") || strings.Contains(r.Stdout+r.Stderr, "Not authorized") {
+		c.Root = true
+		r = run(c)
+	}
+	out := ansi.ReplaceAllString(r.Stdout+"\n"+r.Stderr, "")
+	if r.Error != "" {
+		return out, failure(c, r)
+	}
+	if strings.Contains(out, "No default controller available") {
+		return out, fmt.Errorf("this machine has no Bluetooth controller bluez can use: none is present, it is blocked (rfkill), or bluetooth.service is not running")
+	}
+	if m := btFailed.FindString(out); m != "" || r.Status != 0 {
+		said := strings.TrimSpace(out)
+		if said == "" {
+			said = fmt.Sprintf("exit status %d", r.Status)
+		}
+		return out, fmt.Errorf("bluetoothctl %s: %s", strings.Join(args, " "), tail(said, 1000))
+	}
+	return out, nil
+}
+
+// fields reads bluetoothctl's "\tKey: value" lines; a key seen twice keeps its first value.
+func fields(s string) map[string]string {
+	out := map[string]string{}
+	for _, l := range strings.Split(s, "\n") {
+		if !strings.HasPrefix(l, "\t") {
+			continue
+		}
+		k, v, ok := strings.Cut(strings.TrimSpace(l), ":")
+		if !ok {
+			continue
+		}
+		if _, seen := out[k]; !seen {
+			out[k] = strings.TrimSpace(v)
+		}
+	}
+	return out
+}
+
+func yes(v string) bool { return v == "yes" }
+
+// ControllerAnswer is what bluetooth_controller answers.
+type ControllerAnswer struct {
+	Address      string `json:"address"`
+	Name         string `json:"name"`
+	Alias        string `json:"alias"`
+	Powered      bool   `json:"powered"`
+	PowerState   string `json:"power_state,omitempty"`
+	Discoverable bool   `json:"discoverable"`
+	Pairable     bool   `json:"pairable"`
+	Discovering  bool   `json:"discovering"`
+}
+
+// Controller answers the default controller.
+func Controller() (ControllerAnswer, error) {
+	out, err := bt(CallTimeout, "show")
+	if err != nil {
+		return ControllerAnswer{}, err
+	}
+	c := ControllerAnswer{}
+	for _, l := range strings.Split(out, "\n") {
+		if f := strings.Fields(l); len(f) >= 2 && f[0] == "Controller" {
+			c.Address = f[1]
+			break
+		}
+	}
+	if c.Address == "" {
+		return ControllerAnswer{}, fmt.Errorf("bluetoothctl show answered no controller: %s", tail(strings.TrimSpace(out), 500))
+	}
+	f := fields(out)
+	c.Name, c.Alias, c.PowerState = f["Name"], f["Alias"], f["PowerState"]
+	c.Powered, c.Discoverable, c.Pairable, c.Discovering = yes(f["Powered"]), yes(f["Discoverable"]), yes(f["Pairable"]), yes(f["Discovering"])
+	return c, nil
+}
+
+// Power switches the controller on or off.
+func Power(on bool) (map[string]any, error) {
+	word := "off"
+	if on {
+		word = "on"
+	}
+	if _, err := bt(CallTimeout, "power", word); err != nil {
+		return nil, err
+	}
+	c, err := Controller()
+	if err != nil {
+		return nil, err
+	}
+	return map[string]any{"powered": c.Powered, "asked": word}, nil
+}
+
+// Device is one device bluez knows.
+type Device struct {
+	Address   string `json:"address"`
+	Name      string `json:"name"`
+	Icon      string `json:"kind,omitempty"`
+	Paired    bool   `json:"paired"`
+	Bonded    bool   `json:"bonded"`
+	Trusted   bool   `json:"trusted"`
+	Blocked   bool   `json:"blocked"`
+	Connected bool   `json:"connected"`
+	Battery   *int   `json:"battery_percent,omitempty"`
+	RSSI      *int   `json:"rssi,omitempty"`
+}
+
+var inParens = regexp.MustCompile(`\((-?[0-9]+)\)`)
+
+// number reads "0x50 (80)" or "-62" as a number.
+func number(v string) *int {
+	if m := inParens.FindStringSubmatch(v); m != nil {
+		v = m[1]
+	}
+	n, err := strconv.Atoi(strings.TrimSpace(v))
+	if err != nil {
+		return nil
+	}
+	return &n
+}
+
+// deviceInfo asks bluez for one device.
+func deviceInfo(address string) (Device, error) {
+	out, err := bt(CallTimeout, "info", address)
+	if err != nil {
+		return Device{}, err
+	}
+	f := fields(out)
+	d := Device{Address: address, Name: f["Name"], Icon: f["Icon"], Paired: yes(f["Paired"]), Bonded: yes(f["Bonded"]),
+		Trusted: yes(f["Trusted"]), Blocked: yes(f["Blocked"]), Connected: yes(f["Connected"])}
+	if d.Name == "" {
+		d.Name = f["Alias"]
+	}
+	if v, ok := f["Battery Percentage"]; ok {
+		d.Battery = number(v)
+	}
+	if v, ok := f["RSSI"]; ok {
+		d.RSSI = number(v)
+	}
+	return d, nil
+}
+
+// listed reads "Device <address> <name>" lines.
+func listed(out string) []string {
+	seen := map[string]bool{}
+	addrs := []string{}
+	for _, l := range strings.Split(out, "\n") {
+		f := strings.Fields(strings.TrimSpace(l))
+		if len(f) >= 2 && f[0] == "Device" && macAddress.MatchString(f[1]) && !seen[f[1]] {
+			seen[f[1]] = true
+			addrs = append(addrs, f[1])
+		}
+	}
+	return addrs
+}
+
+// Devices answers the devices bluez knows, with each one's state.
+func Devices(which string) (map[string]any, error) {
+	if err := oneOf("which", which, "all", "paired", "connected", "trusted"); err != nil {
+		return nil, err
+	}
+	args := []string{"devices"}
+	if which != "all" {
+		args = append(args, strings.ToUpper(which[:1])+which[1:])
+	}
+	out, err := bt(CallTimeout, args...)
+	if err != nil {
+		return nil, err
+	}
+	devices := []Device{}
+	for _, a := range listed(out) {
+		d, err := deviceInfo(a)
+		if err != nil {
+			return nil, err
+		}
+		devices = append(devices, d)
+	}
+	sort.SliceStable(devices, func(i, k int) bool {
+		if devices[i].Connected != devices[k].Connected {
+			return devices[i].Connected
+		}
+		return devices[i].Name < devices[k].Name
+	})
+	return map[string]any{"which": which, "count": len(devices), "devices": devices}, nil
+}
+
+// Scan discovers for a while and answers the devices found that are not paired.
+func Scan(seconds int) (map[string]any, error) {
+	// bluetoothctl's own --timeout ends the scan; the command's bound is a little longer.
+	limit := time.Duration(seconds+4) * time.Second
+	if _, err := bt(limit, "--timeout", strconv.Itoa(seconds), "scan", "on"); err != nil {
+		return nil, err
+	}
+	out, err := bt(CallTimeout, "devices")
+	if err != nil {
+		return nil, err
+	}
+	found := []Device{}
+	for _, a := range listed(out) {
+		// A device seen a moment ago may have gone out of reach: it is skipped, not a failure.
+		d, err := deviceInfo(a)
+		if err != nil {
+			continue
+		}
+		if !d.Paired {
+			found = append(found, d)
+		}
+	}
+	sort.SliceStable(found, func(i, k int) bool {
+		ri, rk := -1000, -1000
+		if found[i].RSSI != nil {
+			ri = *found[i].RSSI
+		}
+		if found[k].RSSI != nil {
+			rk = *found[k].RSSI
+		}
+		return ri > rk
+	})
+	return map[string]any{"seconds": seconds, "count": len(found), "found": found}, nil
+}
+
+// Act runs one act on a device and answers the device's state afterwards.
+func Act(verb, address string) (map[string]any, error) {
+	limit := CallTimeout
+	if verb == "connect" {
+		// A connect waits for the device; bluetoothctl's own timeout ends it first.
+		if _, err := bt(limit, "--timeout", "15", verb, address); err != nil {
+			return nil, err
+		}
+	} else if _, err := bt(limit, verb, address); err != nil {
+		return nil, err
+	}
+	if verb == "remove" {
+		return map[string]any{"act": verb, "address": address, "removed": true}, nil
+	}
+	d, err := deviceInfo(address)
+	if err != nil {
+		return nil, err
+	}
+	return map[string]any{"act": verb, "device": d}, nil
+}
+
+// Pair pairs a device with an agent that confirms nothing, then trusts it.
+func Pair(address string) (map[string]any, error) {
+	if _, err := bt(CallTimeout, "--agent", "NoInputNoOutput", "--timeout", "15", "pair", address); err != nil {
+		return nil, err
+	}
+	return Act("trust", address)
+}

modules/bluetooth/cmd/bluetooth-tools/bluetooth_test.go

@@ -0,0 +1,163 @@
+package main
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestTheManifestIsTheStackItsToolsAndTheDaemon(t *testing.T) {
+	m := readManifest(t)
+	holdsTheBundle(t, m, "bluetooth")
+	if got := strings.Join(m.packages(), ","); got != "bluez,bluez-utils" {
+		t.Errorf("packages %s: the applet and the TUI are the operator's", got)
+	}
+	s := m.services()["bluetooth.service"]
+	if s == nil || s["state"] != "running" || s["boot"] != "enabled" {
+		t.Errorf("%v", s)
+	}
+	if len(m.Resources) != 3 {
+		t.Errorf("no configuration file: /etc/bluetooth/main.conf is the package's, unchanged on both workstations: %v", m.Resources)
+	}
+}
+
+const show = "Controller 4C:82:A9:97:01:8E (public)\n\tName: g14\n\tAlias: g14\n\tPowered: yes\n\tPowerState: on\n\tDiscoverable: no\n\tPairable: yes\n\tUUID: Headset (00001108-0000-1000-8000-00805f9b34fb)\n\tDiscovering: no\n"
+
+func headphones(connected bool) string {
+	c := "no"
+	extra := ""
+	if connected {
+		c, extra = "yes", "\tBattery Percentage: 0x50 (80)\n"
+	}
+	return "Device 80:99:E7:C2:29:DA (public)\n\tName: WH-1000XM4\n\tAlias: WH-1000XM4\n\tIcon: audio-headset\n\tPaired: yes\n\tBonded: yes\n\tTrusted: yes\n\tBlocked: no\n\tConnected: " + c + "\n" + extra + "\tUUID: Headset (00001108-0000-1000-8000-00805f9b34fb)\n"
+}
+
+func TestControllerReadsShow(t *testing.T) {
+	using(t, func(string, Cmd) Result { return ok("\x1b[0;94m" + show) })
+	c, err := Controller()
+	if err != nil || c.Address != "4C:82:A9:97:01:8E" || c.Name != "g14" || !c.Powered || c.Discoverable || !c.Pairable {
+		t.Fatalf("%+v %v", c, err)
+	}
+	using(t, func(string, Cmd) Result { return ok("No default controller available\n") })
+	if _, err := Controller(); err == nil || !strings.Contains(err.Error(), "no Bluetooth controller") {
+		t.Fatalf("%v", err)
+	}
+}
+
+func TestDevicesAskEachOneAndReportBatteryWhereGiven(t *testing.T) {
+	f := using(t, func(line string, c Cmd) Result {
+		switch line {
+		case "bluetoothctl devices Paired":
+			return ok("Device 80:99:E7:C2:29:DA WH-1000XM4\nDevice 2C:41:A1:E4:EC:86 Earmuffs\n")
+		case "bluetoothctl info 80:99:E7:C2:29:DA":
+			return ok(headphones(true))
+		}
+		return ok("Device 2C:41:A1:E4:EC:86 (public)\n\tName: Earmuffs\n\tPaired: yes\n\tConnected: no\n")
+	})
+	got, err := Devices("paired")
+	devices := got["devices"].([]Device)
+	if err != nil || got["count"] != 2 || !devices[0].Connected || devices[0].Battery == nil || *devices[0].Battery != 80 || devices[1].Battery != nil {
+		t.Fatalf("%+v %v", got, err)
+	}
+	if f.lines()[0] != "bluetoothctl devices Paired" {
+		t.Errorf("%v", f.lines())
+	}
+	if _, err := Devices("nearby"); err == nil {
+		t.Error("an unknown which")
+	}
+}
+
+func TestAnActThatFailsIsAnErrorWhateverTheExitStatus(t *testing.T) {
+	using(t, func(line string, c Cmd) Result {
+		return ok("Attempting to connect to 80:99:E7:C2:29:DA\nFailed to connect: org.bluez.Error.Failed br-connection-page-timeout\n")
+	})
+	if _, err := Act("connect", "80:99:E7:C2:29:DA"); err == nil || !strings.Contains(err.Error(), "page-timeout") {
+		t.Fatalf("%v", err)
+	}
+	using(t, func(string, Cmd) Result { return Result{Status: 1, Stdout: "Device 00:11:22:33:44:55 not available\n"} })
+	if _, err := Act("trust", "00:11:22:33:44:55"); err == nil || !strings.Contains(err.Error(), "not available") {
+		t.Fatalf("%v", err)
+	}
+}
+
+func TestConnectWaitsWithBluetoothctlsOwnTimeoutAndAnswersTheState(t *testing.T) {
+	f := using(t, func(line string, c Cmd) Result {
+		if strings.Contains(line, "connect") {
+			return ok("Attempting to connect\n[CHG] Device Connected: yes\nConnection successful\n")
+		}
+		return ok(headphones(true))
+	})
+	got, err := Act("connect", "80:99:E7:C2:29:DA")
+	if err != nil || !got["device"].(Device).Connected {
+		t.Fatalf("%v %v", got, err)
+	}
+	if f.lines()[0] != "bluetoothctl --timeout 15 connect 80:99:E7:C2:29:DA" || f.asked[0].Timeout != CallTimeout {
+		t.Errorf("%v", f.lines())
+	}
+}
+
+func TestAnActBluezRefusesTheAccountIsRetriedThroughSudo(t *testing.T) {
+	f := using(t, func(line string, c Cmd) Result {
+		if strings.HasPrefix(line, "sudo") {
+			return ok("Changing power off succeeded\n" + show)
+		}
+		return ok("Failed to set power off: org.freedesktop.DBus.Error.AccessDenied\n")
+	})
+	if _, err := Power(false); err != nil {
+		t.Fatal(err)
+	}
+	if l := f.lines(); l[0] != "bluetoothctl power off" || l[1] != "sudo -n bluetoothctl power off" {
+		t.Errorf("%v", l)
+	}
+}
+
+func TestScanIsBoundedAndAnswersUnpairedDevicesStrongestFirst(t *testing.T) {
+	f := using(t, func(line string, c Cmd) Result {
+		switch {
+		case strings.Contains(line, "scan on"):
+			return ok("Discovery started\n[NEW] Device AA:BB:CC:DD:EE:01 Speaker\n")
+		case line == "bluetoothctl devices":
+			return ok("Device 80:99:E7:C2:29:DA WH-1000XM4\nDevice AA:BB:CC:DD:EE:01 Speaker\nDevice AA:BB:CC:DD:EE:02 Phone\nDevice AA:BB:CC:DD:EE:03 Gone\n")
+		case strings.HasSuffix(line, "EE:01"):
+			return ok("Device AA:BB:CC:DD:EE:01\n\tName: Speaker\n\tPaired: no\n\tRSSI: 0xffffffc4 (-60)\n")
+		case strings.HasSuffix(line, "EE:02"):
+			return ok("Device AA:BB:CC:DD:EE:02\n\tName: Phone\n\tPaired: no\n\tRSSI: -40\n")
+		case strings.HasSuffix(line, "EE:03"):
+			return Result{Status: 1, Stdout: "Device AA:BB:CC:DD:EE:03 not available\n"}
+		}
+		return ok(headphones(false))
+	})
+	got, err := Scan(8)
+	found := got["found"].([]Device)
+	if err != nil || len(found) != 2 || found[0].Name != "Phone" || *found[1].RSSI != -60 {
+		t.Fatalf("%+v %v", got, err)
+	}
+	if f.lines()[0] != "bluetoothctl --timeout 8 scan on" || f.asked[0].Timeout.Seconds() != 12 {
+		t.Errorf("%v %v", f.lines()[0], f.asked[0].Timeout)
+	}
+}
+
+func TestPairUsesAnAgentThatConfirmsNothingAndThenTrusts(t *testing.T) {
+	f := using(t, func(line string, c Cmd) Result {
+		if strings.Contains(line, " pair ") {
+			return ok("Pairing successful\n")
+		}
+		return ok(headphones(false))
+	})
+	if _, err := Pair("80:99:e7:c2:29:da"); err != nil {
+		t.Fatal(err)
+	}
+	if l := f.lines(); l[0] != "bluetoothctl --agent NoInputNoOutput --timeout 15 pair 80:99:e7:c2:29:da" || l[1] != "bluetoothctl trust 80:99:e7:c2:29:da" {
+		t.Errorf("%v", l)
+	}
+}
+
+func TestAnAddressIsSixHexPairs(t *testing.T) {
+	for _, bad := range []string{"", "80:99:E7:C2:29", "80:99:E7:C2:29:DA; rm", "--help", "GG:99:E7:C2:29:DA"} {
+		if _, err := addressOf(map[string]any{"address": bad}); err == nil {
+			t.Errorf("%q accepted", bad)
+		}
+	}
+	if a, err := addressOf(map[string]any{"address": "80:99:e7:c2:29:da"}); err != nil || a != "80:99:E7:C2:29:DA" {
+		t.Errorf("%s %v", a, err)
+	}
+}

modules/bluetooth/cmd/bluetooth-tools/kit.go

@@ -0,0 +1,352 @@
+package main
+
+// kit.go is the same file in each of the workstations' tool bundles (fonts, docker-compose, snapd,
+// flatpak, cups, bluetooth, xclip, dmenu): how a tool runs a command, escalates, bounds what it
+// keeps, and names a failure. A module is built from its own directory, so the file is copied rather
+// than shared; a change to one copy is made to all eight.
+//
+// The rules it holds (novox/hq research 026/05, to-be 38 WP4):
+//   - the node's tool runtime runs as the operator account, not root (ADR 0175 §4); a command that
+//     needs root goes through `sudo -n`, never a prompt, and a refusal is named as such;
+//   - one command gets 20 s, below the runtime's 30 s call limit, and is ended with everything it
+//     started when it takes longer;
+//   - each stream is kept to 256 KiB, and the answer says when it was cut;
+//   - a failure is an error with what went wrong in it, never an empty answer.
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"strings"
+	"syscall"
+	"time"
+)
+
+// Bounds every command is held to.
+const (
+	CallTimeout = 20 * time.Second
+	MostOutput  = 256 << 10
+)
+
+// Cmd is one command a tool runs.
+type Cmd struct {
+	Name string
+	Args []string
+	// Stdin is written to the command's standard input when not empty.
+	Stdin string
+	// Env is added to this process's own environment.
+	Env []string
+	// Root says the command needs root: it is run through `sudo -n` when this process is not root.
+	Root bool
+	// Timeout replaces CallTimeout; only a background job (jobs.go) asks for longer.
+	Timeout time.Duration
+	// Detached is for a program that forks a child which outlives it, as xclip does to keep the
+	// selection: its streams go to files, because a pipe the child inherits would hold the call open
+	// until the child exits.
+	Detached bool
+}
+
+// Result is what a command did.
+type Result struct {
+	Stdout string `json:"stdout"`
+	Stderr string `json:"stderr"`
+	Status int    `json:"status"`
+	// Error is why it did not run to an answer: "not-found" when the program is not there,
+	// "timeout" when it was ended for taking too long, else the spawn error.
+	Error     string `json:"error,omitempty"`
+	Truncated bool   `json:"truncated,omitempty"`
+}
+
+// Runner runs a command. Tests replace it; nothing else does.
+type Runner func(Cmd) Result
+
+var (
+	run  Runner = execRun
+	euid        = os.Geteuid
+)
+
+// argv is the command as it is run: through sudo without a prompt when it needs root and this
+// process is not root.
+func argv(c Cmd) (string, []string) {
+	if c.Root && euid() != 0 {
+		return "sudo", append([]string{"-n", c.Name}, c.Args...)
+	}
+	return c.Name, c.Args
+}
+
+// bounded keeps the first MostOutput bytes written to it and notes that more came.
+type bounded struct {
+	b   bytes.Buffer
+	cut bool
+}
+
+func (w *bounded) Write(p []byte) (int, error) {
+	room := MostOutput - w.b.Len()
+	if room <= 0 {
+		w.cut = w.cut || len(p) > 0
+		return len(p), nil
+	}
+	if len(p) > room {
+		w.b.Write(p[:room])
+		w.cut = true
+		return len(p), nil
+	}
+	return w.b.Write(p)
+}
+
+func execRun(c Cmd) Result {
+	timeout := c.Timeout
+	if timeout <= 0 {
+		timeout = CallTimeout
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), timeout)
+	defer cancel()
+	name, args := argv(c)
+	cmd := exec.CommandContext(ctx, name, args...)
+	cmd.Env = append(append(os.Environ(), "LC_ALL=C"), c.Env...)
+	if !c.Detached {
+		// Its own process group, so that ending it on a timeout ends what it started too.
+		cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+		cmd.Cancel = func() error {
+			if cmd.Process != nil {
+				_ = syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)
+			}
+			return nil
+		}
+	}
+	cmd.WaitDelay = 2 * time.Second
+	if c.Stdin != "" {
+		cmd.Stdin = strings.NewReader(c.Stdin)
+	}
+	var out, errs bounded
+	var outFile, errFile *os.File
+	if c.Detached {
+		var err error
+		if outFile, err = os.CreateTemp("", "mesh-tool-out-*"); err != nil {
+			return Result{Status: 127, Error: err.Error()}
+		}
+		defer os.Remove(outFile.Name())
+		defer outFile.Close()
+		if errFile, err = os.CreateTemp("", "mesh-tool-err-*"); err != nil {
+			return Result{Status: 127, Error: err.Error()}
+		}
+		defer os.Remove(errFile.Name())
+		defer errFile.Close()
+		cmd.Stdout, cmd.Stderr = outFile, errFile
+	} else {
+		cmd.Stdout, cmd.Stderr = &out, &errs
+	}
+	err := cmd.Run()
+	if c.Detached {
+		for _, f := range []struct {
+			file *os.File
+			into *bounded
+		}{{outFile, &out}, {errFile, &errs}} {
+			if _, e := f.file.Seek(0, io.SeekStart); e == nil {
+				_, _ = io.Copy(f.into, f.file)
+			}
+		}
+	}
+	r := Result{Stdout: out.b.String(), Stderr: errs.b.String(), Truncated: out.cut || errs.cut}
+	var exit *exec.ExitError
+	switch {
+	case err == nil:
+	case ctx.Err() == context.DeadlineExceeded:
+		r.Status, r.Error = 124, "timeout"
+	case errors.Is(err, exec.ErrNotFound) || errors.Is(err, os.ErrNotExist):
+		r.Status, r.Error = 127, "not-found"
+	case errors.As(err, &exit):
+		r.Status = exit.ExitCode()
+	default:
+		r.Status, r.Error = 127, err.Error()
+	}
+	return r
+}
+
+// call runs a command and answers its result, or an error naming what went wrong.
+func call(c Cmd) (Result, error) {
+	r := run(c)
+	if r.Status == 0 && r.Error == "" {
+		return r, nil
+	}
+	return r, failure(c, r)
+}
+
+// failure names how a command failed: not installed, refused escalation, too slow, or its exit
+// status with the end of what it said.
+func failure(c Cmd, r Result) error {
+	program, _ := argv(c)
+	switch {
+	case r.Error == "not-found" && program == "sudo":
+		return fmt.Errorf("%s needs root, and sudo is not installed here for the runtime's account to escalate with", c.Name)
+	case r.Error == "not-found":
+		if hint, ok := providedBy[c.Name]; ok {
+			return fmt.Errorf("%s is not installed on this machine (%s)", c.Name, hint)
+		}
+		return fmt.Errorf("%s is not installed on this machine", c.Name)
+	case r.Error == "timeout":
+		limit := c.Timeout
+		if limit <= 0 {
+			limit = CallTimeout
+		}
+		return fmt.Errorf("%s gave no answer within %s and was ended", c.Name, limit)
+	case r.Error != "":
+		return fmt.Errorf("%s did not run: %s", c.Name, r.Error)
+	case program == "sudo" && strings.Contains(r.Stderr, "command not found"):
+		if hint, ok := providedBy[c.Name]; ok {
+			return fmt.Errorf("%s is not installed on this machine (%s)", c.Name, hint)
+		}
+		return fmt.Errorf("%s is not installed on this machine", c.Name)
+	case program == "sudo" && strings.HasPrefix(strings.TrimSpace(r.Stderr), "sudo:"):
+		return fmt.Errorf("%s needs root, and sudo -n refused the runtime's account: %s (the escalation is the sudo module's to declare)",
+			c.Name, firstLine(r.Stderr))
+	}
+	said := tail(strings.TrimSpace(r.Stderr), 2000)
+	if said == "" {
+		said = tail(strings.TrimSpace(r.Stdout), 2000)
+	}
+	if said == "" {
+		said = "and said nothing"
+	}
+	return fmt.Errorf("%s %s exited %d: %s", c.Name, strings.Join(c.Args, " "), r.Status, said)
+}
+
+func firstLine(s string) string {
+	s = strings.TrimSpace(s)
+	if i := strings.IndexByte(s, '\n'); i >= 0 {
+		return s[:i]
+	}
+	return s
+}
+
+func tail(s string, n int) string {
+	if len(s) <= n {
+		return s
+	}
+	return "…" + s[len(s)-n:]
+}
+
+// lines are a command's output lines, blank ones dropped.
+func lines(s string) []string {
+	out := []string{}
+	for _, l := range strings.Split(s, "\n") {
+		if strings.TrimSpace(l) != "" {
+			out = append(out, strings.TrimRight(l, "\r"))
+		}
+	}
+	return out
+}
+
+// Arguments, read the way a tool's JSON arguments arrive.
+
+func text(args map[string]any, key string) (string, error) {
+	v, ok := args[key]
+	if !ok || v == nil {
+		return "", fmt.Errorf("%s is required", key)
+	}
+	s, ok := v.(string)
+	if !ok {
+		return "", fmt.Errorf("%s must be a string", key)
+	}
+	if strings.TrimSpace(s) == "" {
+		return "", fmt.Errorf("%s must not be empty", key)
+	}
+	return s, nil
+}
+
+func optText(args map[string]any, key, def string) (string, error) {
+	v, ok := args[key]
+	if !ok || v == nil {
+		return def, nil
+	}
+	s, ok := v.(string)
+	if !ok {
+		return "", fmt.Errorf("%s must be a string", key)
+	}
+	if strings.TrimSpace(s) == "" {
+		return def, nil
+	}
+	return s, nil
+}
+
+// optWhole reads a whole number, defaulted, refused below least and held to most.
+func optWhole(args map[string]any, key string, def, least, most int) (int, error) {
+	v, ok := args[key]
+	if !ok || 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 must be a number", key)
+		}
+	}
+	if f != float64(int(f)) {
+		return 0, fmt.Errorf("%s must be a whole number", key)
+	}
+	n := int(f)
+	if n < least {
+		return 0, fmt.Errorf("%s must be at least %d", key, least)
+	}
+	if n > most {
+		n = most
+	}
+	return n, nil
+}
+
+func optFlag(args map[string]any, key string, def bool) (bool, error) {
+	v, ok := args[key]
+	if !ok || v == nil {
+		return def, nil
+	}
+	b, ok := v.(bool)
+	if !ok {
+		return false, fmt.Errorf("%s must be true or false", key)
+	}
+	return b, nil
+}
+
+func optList(args map[string]any, key string) ([]string, error) {
+	v, ok := args[key]
+	if !ok || v == nil {
+		return nil, nil
+	}
+	items, ok := v.([]any)
+	if !ok {
+		return nil, fmt.Errorf("%s must be a list of strings", key)
+	}
+	out := make([]string, 0, len(items))
+	for _, it := range items {
+		s, ok := it.(string)
+		if !ok || strings.TrimSpace(s) == "" {
+			return nil, fmt.Errorf("%s must be a list of non-empty strings", key)
+		}
+		out = append(out, s)
+	}
+	return out, nil
+}
+
+// oneOf refuses a value outside a closed set.
+func oneOf(key, value string, allowed ...string) error {
+	for _, a := range allowed {
+		if value == a {
+			return nil
+		}
+	}
+	return fmt.Errorf("%s must be one of %s, not %q", key, strings.Join(allowed, ", "), value)
+}
+
+// plainName refuses a name that could be read as an option or carries a path or a space: package,
+// snap, application and printer names never do.
+func plainName(key, value string) error {
+	if strings.HasPrefix(value, "-") || strings.ContainsAny(value, " \t\n/\\") {
+		return fmt.Errorf("%s %q is not a plain name", key, value)
+	}
+	return nil
+}

modules/bluetooth/cmd/bluetooth-tools/kit_test.go

@@ -0,0 +1,147 @@
+package main
+
+// Tests of kit.go, the same in each workstation module.
+
+import (
+	"strings"
+	"testing"
+	"time"
+)
+
+// fake records the commands asked and answers each from a function of the command line.
+type fake struct {
+	asked  []Cmd
+	answer func(line string, c Cmd) Result
+}
+
+func (f *fake) runner() Runner {
+	return func(c Cmd) Result {
+		f.asked = append(f.asked, c)
+		name, args := argv(c)
+		line := strings.TrimSpace(name + " " + strings.Join(args, " "))
+		if f.answer == nil {
+			return Result{}
+		}
+		return f.answer(line, c)
+	}
+}
+
+func (f *fake) lines() []string {
+	out := []string{}
+	for _, c := range f.asked {
+		name, args := argv(c)
+		out = append(out, strings.TrimSpace(name+" "+strings.Join(args, " ")))
+	}
+	return out
+}
+
+// using installs a fake runner and a non-root uid for one test.
+func using(t *testing.T, answer func(line string, c Cmd) Result) *fake {
+	t.Helper()
+	f := &fake{answer: answer}
+	wasRun, wasUID := run, euid
+	run, euid = f.runner(), func() int { return 1000 }
+	t.Cleanup(func() { run, euid = wasRun, wasUID })
+	return f
+}
+
+func ok(stdout string) Result { return Result{Stdout: stdout} }
+
+func TestKitAnActThatNeedsRootGoesThroughSudoWithoutAPromptUnlessAlreadyRoot(t *testing.T) {
+	was := euid
+	defer func() { euid = was }()
+	euid = func() int { return 1000 }
+	if name, args := argv(Cmd{Name: "x", Args: []string{"a"}, Root: true}); name != "sudo" || strings.Join(args, " ") != "-n x a" {
+		t.Fatalf("not root: %s %v", name, args)
+	}
+	if name, _ := argv(Cmd{Name: "x"}); name != "x" {
+		t.Fatalf("a read is run as the account: %s", name)
+	}
+	euid = func() int { return 0 }
+	if name, _ := argv(Cmd{Name: "x", Root: true}); name != "x" {
+		t.Fatalf("as root no sudo: %s", name)
+	}
+}
+
+func TestKitAFailureIsNamedByHowItFailed(t *testing.T) {
+	was := euid
+	defer func() { euid = was }()
+	euid = func() int { return 1000 }
+	cases := []struct {
+		c    Cmd
+		r    Result
+		want string
+	}{
+		{Cmd{Name: "nothere"}, Result{Status: 127, Error: "not-found"}, "not installed"},
+		{Cmd{Name: "x", Root: true}, Result{Status: 127, Error: "not-found"}, "sudo is not installed"},
+		{Cmd{Name: "x", Root: true}, Result{Status: 1, Stderr: "sudo: a password is required\n"}, "sudo -n refused"},
+		{Cmd{Name: "x", Root: true}, Result{Status: 1, Stderr: "sudo: x: command not found\n"}, "x is not installed"},
+		{Cmd{Name: "x"}, Result{Status: 124, Error: "timeout"}, "within 20s"},
+		{Cmd{Name: "x", Args: []string{"y"}}, Result{Status: 3, Stderr: "boom\n"}, "x y exited 3: boom"},
+		{Cmd{Name: "x"}, Result{Status: 3}, "said nothing"},
+	}
+	for _, k := range cases {
+		err := failure(k.c, k.r)
+		if err == nil || !strings.Contains(err.Error(), k.want) {
+			t.Errorf("%+v: %v, want %q", k.r, err, k.want)
+		}
+	}
+}
+
+func TestKitOutputIsBoundedAndSaysSo(t *testing.T) {
+	var w bounded
+	big := strings.Repeat("a", MostOutput+10)
+	n, _ := w.Write([]byte(big))
+	if n != len(big) || w.b.Len() != MostOutput || !w.cut {
+		t.Fatalf("kept %d of %d, cut %v", w.b.Len(), len(big), w.cut)
+	}
+}
+
+func TestKitTheRealRunnerRunsEndsAndReportsAMissingProgram(t *testing.T) {
+	r := execRun(Cmd{Name: "sh", Args: []string{"-c", "echo out; echo err >&2; exit 3"}})
+	if r.Status != 3 || strings.TrimSpace(r.Stdout) != "out" || strings.TrimSpace(r.Stderr) != "err" {
+		t.Fatalf("%+v", r)
+	}
+	r = execRun(Cmd{Name: "sh", Args: []string{"-c", "sleep 5 & sleep 5"}, Timeout: 200 * time.Millisecond})
+	if r.Error != "timeout" {
+		t.Fatalf("a slow command: %+v", r)
+	}
+	r = execRun(Cmd{Name: "no-such-program-anywhere"})
+	if r.Error != "not-found" {
+		t.Fatalf("a missing program: %+v", r)
+	}
+	r = execRun(Cmd{Name: "cat", Stdin: "given"})
+	if r.Stdout != "given" {
+		t.Fatalf("stdin: %+v", r)
+	}
+	start := time.Now()
+	r = execRun(Cmd{Name: "sh", Args: []string{"-c", "echo kept; (sleep 3 &) ; exit 0"}, Detached: true})
+	if r.Status != 0 || strings.TrimSpace(r.Stdout) != "kept" || time.Since(start) > 2*time.Second {
+		t.Fatalf("a detached command returns when it exits, not when its child does: %+v after %s", r, time.Since(start))
+	}
+}
+
+func TestKitArgumentsAreReadStrictly(t *testing.T) {
+	args := map[string]any{"s": "x", "n": float64(5), "f": 1.5, "b": true, "l": []any{"a", "b"}}
+	if _, err := text(args, "missing"); err == nil {
+		t.Error("a missing required string")
+	}
+	if n, _ := optWhole(args, "n", 1, 1, 3); n != 3 {
+		t.Errorf("held to most: %d", n)
+	}
+	if _, err := optWhole(args, "n", 1, 6, 9); err == nil {
+		t.Error("below least")
+	}
+	if _, err := optWhole(args, "f", 1, 0, 9); err == nil {
+		t.Error("a fraction")
+	}
+	if l, _ := optList(args, "l"); len(l) != 2 {
+		t.Errorf("list: %v", l)
+	}
+	if b, _ := optFlag(args, "b", false); !b {
+		t.Error("flag")
+	}
+	if err := plainName("name", "--all"); err == nil {
+		t.Error("an option as a name")
+	}
+}

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

@@ -0,0 +1,135 @@
+// The bluetooth module's tools (novox/hq research 027/02, 026/05): the controller, the devices with
+// their state and battery, scanning, and pairing, connecting, trusting and forgetting a device. A Go
+// bundle the node's runtime launches over stdio (ADR 0188, ADR 0193); it runs as the operator
+// account, and speaks to bluez through bluetoothctl.
+package main
+
+import (
+	"fmt"
+	"os"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+var providedBy = map[string]string{
+	"bluetoothctl": "the bluez-utils package, which this module installs",
+}
+
+func main() {
+	if err := stdio.Serve("", tools()); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+var addressArg = map[string]any{"type": "string", "description": "the device's address, such as 80:99:E7:C2:29:DA, as bluetooth_devices answers it"}
+
+func withAddress(f func(string) (any, error)) func(map[string]any) (any, error) {
+	return func(args map[string]any) (any, error) {
+		a, err := addressOf(args)
+		if err != nil {
+			return nil, err
+		}
+		return f(a)
+	}
+}
+
+func tools() []stdio.Tool {
+	return []stdio.Tool{
+		{
+			Name:        "bluetooth_controller",
+			Description: "The machine's Bluetooth controller: address, name, powered, discoverable, pairable, discovering. (r)",
+			Input:       map[string]any{},
+			Run:         func(map[string]any) (any, error) { return Controller() },
+		},
+		{
+			Name:        "bluetooth_power",
+			Description: "Whether the controller is powered; with on, switch it on or off. (r/a)",
+			Input:       map[string]any{"on": map[string]any{"type": "boolean", "description": "power the controller on (true) or off (false)"}},
+			Run: func(args map[string]any) (any, error) {
+				if _, given := args["on"]; !given {
+					c, err := Controller()
+					if err != nil {
+						return nil, err
+					}
+					return map[string]any{"powered": c.Powered}, nil
+				}
+				on, err := optFlag(args, "on", true)
+				if err != nil {
+					return nil, err
+				}
+				return Power(on)
+			},
+		},
+		{
+			Name: "bluetooth_devices",
+			Description: "The devices bluez knows: every one, or only the paired, connected or trusted. Each with its " +
+				"name, kind, paired, bonded, trusted, blocked, connected, and its battery where the device reports it. (r)",
+			Input: map[string]any{"which": map[string]any{"type": "string", "enum": []string{"all", "paired", "connected", "trusted"}, "description": "which devices (default all)"}},
+			Run: func(args map[string]any) (any, error) {
+				which, err := optText(args, "which", "all")
+				if err != nil {
+					return nil, err
+				}
+				return Devices(which)
+			},
+		},
+		{
+			Name: "bluetooth_scan",
+			Description: "Discover devices nearby for a few seconds (default 8, at most 15), and answer the ones not " +
+				"paired, with their signal strength. (r)",
+			Input: map[string]any{"seconds": map[string]any{"type": "integer", "description": "how long to scan (default 8, at most 15)"}},
+			Run: func(args map[string]any) (any, error) {
+				s, err := optWhole(args, "seconds", 8, 1, 15)
+				if err != nil {
+					return nil, err
+				}
+				return Scan(s)
+			},
+		},
+		{
+			Name:        "bluetooth_connect",
+			Description: "Connect a paired device, such as headphones. Answers its state afterwards. (a)",
+			Input:       map[string]any{"address": addressArg},
+			Run:         withAddress(func(a string) (any, error) { return Act("connect", a) }),
+		},
+		{
+			Name:        "bluetooth_disconnect",
+			Description: "Disconnect a device. (a)",
+			Input:       map[string]any{"address": addressArg},
+			Run:         withAddress(func(a string) (any, error) { return Act("disconnect", a) }),
+		},
+		{
+			Name:        "bluetooth_trust",
+			Description: "Trust a device, so it may connect by itself; or with trusted false, stop trusting it. (a)",
+			Input:       map[string]any{"address": addressArg, "trusted": map[string]any{"type": "boolean", "description": "trust (default) or untrust"}},
+			Run: func(args map[string]any) (any, error) {
+				a, err := addressOf(args)
+				if err != nil {
+					return nil, err
+				}
+				trusted, err := optFlag(args, "trusted", true)
+				if err != nil {
+					return nil, err
+				}
+				if trusted {
+					return Act("trust", a)
+				}
+				return Act("untrust", a)
+			},
+		},
+		{
+			Name: "bluetooth_pair",
+			Description: "Pair a device found by a scan, and trust it. Works for a device that needs no code to be " +
+				"confirmed, such as headphones; one that shows a code is paired from the desktop. (a)",
+			Input: map[string]any{"address": addressArg},
+			Run:   withAddress(func(a string) (any, error) { return Pair(a) }),
+		},
+		{
+			Name:        "bluetooth_remove",
+			Description: "Forget a device: unpair it and drop what bluez knows of it. (a)",
+			Input:       map[string]any{"address": addressArg},
+			Run:         withAddress(func(a string) (any, error) { return Act("remove", a) }),
+		},
+	}
+}

modules/bluetooth/cmd/bluetooth-tools/manifest_kit_test.go

@@ -0,0 +1,107 @@
+package main
+
+// manifest_kit_test.go is the same file in each workstation module: it reads the module's
+// definition so the module's own tests can hold it to what it says.
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"testing"
+)
+
+type manifest struct {
+	Module       string           `json:"module"`
+	Capabilities []string         `json:"capabilities"`
+	Claims       []any            `json:"claims"`
+	Seats        []any            `json:"seats"`
+	Tools        []string         `json:"tools"`
+	Resources    []map[string]any `json:"resources"`
+	Build        struct {
+		Artifacts []map[string]any `json:"artifacts"`
+	} `json:"build"`
+}
+
+func readManifest(t *testing.T) manifest {
+	t.Helper()
+	raw, err := os.ReadFile(filepath.Join("..", "..", "module.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var m manifest
+	if err := json.Unmarshal(raw, &m); err != nil {
+		t.Fatalf("module.json: %v", err)
+	}
+	return m
+}
+
+func (m manifest) resource(id string) map[string]any {
+	for _, r := range m.Resources {
+		if r["id"] == id {
+			return r
+		}
+	}
+	return nil
+}
+
+// packages are the packages the module installs, sorted.
+func (m manifest) packages() []string {
+	out := []string{}
+	for _, r := range m.Resources {
+		if r["type"] == "package" && r["absent"] != true {
+			out = append(out, r["package"].(string))
+		}
+	}
+	sort.Strings(out)
+	return out
+}
+
+// services are the units the module declares, by unit name.
+func (m manifest) services() map[string]map[string]any {
+	out := map[string]map[string]any{}
+	for _, r := range m.Resources {
+		if r["type"] == "service" {
+			out[r["unit"].(string)] = r
+		}
+	}
+	return out
+}
+
+// holdsTheBundle holds the manifest to the Go bundle this directory builds: every tool registered
+// is listed and nothing else, each named <prefix>_…, and the artifact builds this command.
+func holdsTheBundle(t *testing.T, m manifest, prefix string) {
+	t.Helper()
+	registered := []string{}
+	for _, tool := range tools() {
+		registered = append(registered, tool.Name)
+		if !strings.HasPrefix(tool.Name, prefix+"_") {
+			t.Errorf("tool %s is not named %s_…", tool.Name, prefix)
+		}
+		if tool.Description == "" || tool.Run == nil || tool.Input == nil {
+			t.Errorf("tool %s is not described, runnable and given an input schema", tool.Name)
+		}
+	}
+	if strings.Join(registered, ",") != strings.Join(m.Tools, ",") {
+		t.Errorf("registered %v, listed %v", registered, m.Tools)
+	}
+	if len(m.Build.Artifacts) != 1 {
+		t.Fatalf("one artifact, got %d", len(m.Build.Artifacts))
+	}
+	cwd, _ := os.Getwd()
+	binary := filepath.Base(cwd)
+	a := m.Build.Artifacts[0]
+	want := map[string]any{"kind": "bundle", "language": "go", "system": "arch", "from": "cmd/" + binary, "binary": binary}
+	for k, v := range want {
+		if a[k] != v {
+			t.Errorf("artifact %s = %v, want %v", k, a[k], v)
+		}
+	}
+	if loads, _ := a["loads"].([]any); len(loads) != 1 || loads[0] != binary {
+		t.Errorf("artifact loads %v, want [%s]", a["loads"], binary)
+	}
+	if m.Claims != nil || m.Seats != nil {
+		t.Errorf("claims %v, seats %v: this module holds no seat", m.Claims, m.Seats)
+	}
+}

modules/bluetooth/go.mod

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

modules/bluetooth/go.sum

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

modules/bluetooth/module.json

@@ -0,0 +1,53 @@
+{
+  "module": "bluetooth",
+  "version": "1",
+  "capabilities": [
+    "package-manager",
+    "service-manager"
+  ],
+  "tools": [
+    "bluetooth_controller",
+    "bluetooth_power",
+    "bluetooth_devices",
+    "bluetooth_scan",
+    "bluetooth_connect",
+    "bluetooth_disconnect",
+    "bluetooth_trust",
+    "bluetooth_pair",
+    "bluetooth_remove"
+  ],
+  "resources": [
+    {
+      "id": "stack",
+      "type": "package",
+      "package": "bluez"
+    },
+    {
+      "id": "utilities",
+      "type": "package",
+      "package": "bluez-utils"
+    },
+    {
+      "id": "daemon",
+      "type": "service",
+      "unit": "bluetooth.service",
+      "state": "running",
+      "boot": "enabled"
+    }
+  ],
+  "build": {
+    "artifacts": [
+      {
+        "name": "tools",
+        "kind": "bundle",
+        "language": "go",
+        "system": "arch",
+        "from": "cmd/bluetooth-tools",
+        "binary": "bluetooth-tools",
+        "loads": [
+          "bluetooth-tools"
+        ]
+      }
+    ]
+  }
+}

modules/claude-code/README.md

@@ -0,0 +1,81 @@
+# claude-code
+
+The operator's agent on a machine (novox/hq design 36): its package, its machine-wide managed
+configuration, and the consumer side of the Anthropic licence manager (design 39, ADR 0183).
+
+## What it owns
+
+Two directories, declared, so the mesh refuses a second module owning either:
+
+- `/etc/claude-code`, the agent's machine-wide managed directory, root's, `0755`.
+- `~/.claude` under the operator account's home, the operator's, `0700`. The module owns the directory —
+  that it exists, who owns it, its mode — and of what is inside only what it writes. Everything else
+  in it (memory, history, projects, local settings, a person's own rules and skills) is the person's
+  and is never read or written (hq ADR 0182). Unassigned, the module leaves the directory: the host
+  removes a directory only when it is empty.
+
+## What it writes
+
+Under the agent's managed directory, `/etc/claude-code`, owned whole by this module and rewritten
+whenever the node's tool runtime collects the module's tools:
+
+| file | holds |
+|---|---|
+| `managed-mcp.json` | the tool servers every session loads: the mesh's console as `mesh`, and the servers set in this module's `mcp_servers` setting. **Exclusive**: a server not listed here does not load — not one added with `claude mcp add`, not a project's `.mcp.json`, not a plugin's |
+| `managed-settings.json` | the repositories' attribution convention, the claude.ai connectors kept beside the managed servers, and the key-helper while the node holds an API-key licence |
+| `CLAUDE.md` | how a session on this mesh works, this node's name and role, the conventions |
+
+Under the operator's home, only `~/.claude/.credentials.json`, and only when the licence manager hands
+this node a subscription token. Nothing else under the home is read or written.
+
+## Over NATS
+
+Everything between this module and the rest of the mesh is NATS, in three kinds: an **event** says that
+something happened and carries no secret, because a stream keeps it; a **request** carries a token,
+because nothing keeps it (hq design 32 §10); and **state** is the current value of something every node
+must see, a node that joins later included — kept, so it carries no secret either (hq ADR 0201).
+
+| what | how |
+|---|---|
+| what this node holds | the module's `holdings` state, one key for this node — the account, the kind, fingerprints and expiries, never a token — written at start and whenever the credentials file changes (hq ADR 0206) |
+| a person ran `/login` here | the credentials file gains a refresh token this module never writes; its next report shows it, and the licence manager asks `claude_code_grant` for it, giving its key — the one time a refresh token leaves the node, for the manager to adopt by refreshing it |
+| what this node should hold | the licence manager's `bindings` state, this node's key; on a newer generation this module asks `anthropic-licence-manager.current` for its token, sealed to the key it sends, and writes it access-token-only — so the agent here never refreshes. A node that was off reads its key when it is back |
+| an MCP server registered through this module | a key in the module's `servers` state — `all.<server>` for every node, `<node>.<server>` for one; every node watches it and renders what applies to it, a node's own entry over the one for every node. A node that joins later, or was off, reads the whole current set at start; unregistering is a delete. An entry with a secret in its `env` or `headers` is refused by the runtime |
+
+## Tools
+
+`claude_code_status`, `claude_code_render`, `claude_code_pull`, `claude_code_grant` (for the licence
+manager), `claude_code_mcp_list`,
+`claude_code_mcp_register` (this node by default; `nodes: "all"` or a list for more — called for this
+node alone, its answer names the other nodes running claude-code), `claude_code_mcp_unregister`.
+
+## Settings
+
+Per node or for the whole mesh, through `mesh-controller.settings module=claude-code`:
+
+- `role` — what this node is, in a few words; shown to every session.
+- `mcp_servers` — extra tool servers, set by the operator for the mesh or a node, beside the ones
+  registered through the tools; keyed by name, in the vendor's `.mcp.json` entry shape
+  (`{"type":"http","url":…}` or `{"type":"stdio","command":…,"args":[…]}`). The name `mesh` is the
+  module's own and cannot be set. Put a person's own servers here, or they stop loading.
+
+## On a machine that carried the predecessor
+
+Remove these by hand, once; the mesh removes nothing it did not make (ADR 0182):
+
+- `~/.claude/CLAUDE.md`
+- `~/.claude/rules/00-hal-mesh.md`, `~/.claude/rules/conventions.md`
+- `~/.claude/skills/cleanup/`, `~/.claude/skills/hal-switch-license/`
+- the hand-made console entry in `~/.claude.json` under `mcpServers` — it is ignored now anyway
+
+## Escalation
+
+Writing `/etc/claude-code` needs root. The runtime runs as the operator account, and the module uses
+that account's passwordless `sudo`; on a machine without it, `claude_code_render` says so and nothing
+is written.
+
+## Code
+
+Go, one binary (`cmd/claude-code`) the node's runtime launches. Tested with `go test ./...`; the managed
+instruction file is held to the TypeScript renderer it replaced (`testdata/rendered-by-typescript.json`),
+and the sealed box is the licence manager's own format.

modules/claude-code/cmd/claude-code/claude_code_test.go

@@ -0,0 +1,401 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+)
+
+var now = time.Now().UnixMilli()
+
+func node(t *testing.T, name string) (Paths, map[string]string) {
+	t.Helper()
+	root := t.TempDir()
+	p := Paths{State: filepath.Join(root, "state"), Facts: filepath.Join(root, "state", "facts.json"),
+		Settings: filepath.Join(root, "state", "settings.json"), Home: filepath.Join(root, "home"), Node: name}
+	_ = os.MkdirAll(p.State, 0o700)
+	_ = os.MkdirAll(filepath.Join(p.Home, ".claude"), 0o700)
+	_ = os.WriteFile(p.Facts, []byte(`{"node":"`+name+`","console":"http://127.0.0.1:4270/mcp"}`), 0o600)
+	_ = os.WriteFile(p.Settings, []byte(`{"role":"","mcp_servers":{}}`), 0o600)
+	return p, map[string]string{}
+}
+
+func writer(w map[string]string) WriteManaged {
+	return func(name, content string) (string, error) { w[name] = content; return name + ": written", nil }
+}
+
+func writeFile(t *testing.T, path, content string) {
+	t.Helper()
+	if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func creds(t *testing.T, p Paths) map[string]any {
+	t.Helper()
+	var c map[string]any
+	raw, _ := os.ReadFile(p.credentials())
+	if err := json.Unmarshal(raw, &c); err != nil {
+		t.Fatal(err)
+	}
+	return c["claudeAiOauth"].(map[string]any)
+}
+
+// ---- the renderer, held to the TypeScript it replaced -------------------------------------------------
+
+func TestTheRendererWritesWhatTheTypeScriptOneWrote(t *testing.T) {
+	raw, err := os.ReadFile("testdata/rendered-by-typescript.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var f struct {
+		Facts      Facts             `json:"facts"`
+		Settings   Settings          `json:"settings"`
+		Registered Servers           `json:"registered"`
+		WithKey    map[string]string `json:"withKey"`
+		Plain      map[string]string `json:"plain"`
+	}
+	if err := json.Unmarshal(raw, &f); err != nil {
+		t.Fatal(err)
+	}
+	same := func(label string, got, want map[string]string) {
+		if got["CLAUDE.md"] != want["CLAUDE.md"] {
+			t.Errorf("%s: CLAUDE.md differs from the TypeScript's:\n--- go\n%s\n--- typescript\n%s", label, got["CLAUDE.md"], want["CLAUDE.md"])
+		}
+		for _, file := range []string{"managed-mcp.json", "managed-settings.json"} {
+			var a, b any
+			_ = json.Unmarshal([]byte(got[file]), &a)
+			_ = json.Unmarshal([]byte(want[file]), &b)
+			if !reflect.DeepEqual(a, b) {
+				t.Errorf("%s: %s means something else:\n--- go\n%s\n--- typescript\n%s", label, file, got[file], want[file])
+			}
+		}
+	}
+	same("with an API key", Render(f.Facts, f.Settings, &Binding{Licence: "api", Kind: "api-key"}, "/state/api-key-helper", f.Registered), f.WithKey)
+	same("plain", Render(f.Facts, Settings{}, nil, "/h", Servers{}), f.Plain)
+}
+
+func TestASettingCannotReplaceTheMeshsOwnEntryAndABadNameIsLeftOut(t *testing.T) {
+	out := Render(Facts{Node: "w", Console: "http://127.0.0.1:4270/mcp"},
+		Settings{MCPServers: map[string]map[string]any{"mesh": {"type": "http", "url": "http://evil"}, "bad name": {}}}, nil, "/h", nil)
+	var mcp struct {
+		MCPServers map[string]map[string]any `json:"mcpServers"`
+	}
+	_ = json.Unmarshal([]byte(out["managed-mcp.json"]), &mcp)
+	if mcp.MCPServers["mesh"]["url"] != "http://127.0.0.1:4270/mcp" || mcp.MCPServers["bad name"] != nil {
+		t.Fatalf("%v", mcp.MCPServers)
+	}
+	if !reflect.DeepEqual(Render(Facts{Console: "x"}, Settings{}, nil, "/h", nil), Render(Facts{Console: "x"}, Settings{}, nil, "/h", nil)) {
+		t.Fatal("rendering is not deterministic")
+	}
+}
+
+// ---- the credentials file -----------------------------------------------------------------------------
+
+func i64(v int64) *int64 { return &v }
+
+func TestTheLineageRules(t *testing.T) {
+	const hour = 3_600_000
+	g := func(at string, exp int64, rtExp int64) Grant {
+		return Grant{AccessToken: at, ExpiresAt: exp, RefreshTokenExpiresAt: i64(rtExp)}
+	}
+	month := now + 30*24*hour
+	if d := DecideApply(&Grant{AccessToken: "A", ExpiresAt: now + hour, RefreshTokenExpiresAt: i64(month)}, g("B", now+2*hour, month), false); !d.Apply {
+		t.Fatal("a newer rotation was refused")
+	}
+	if d := DecideApply(&Grant{AccessToken: "new", ExpiresAt: now + 2*hour, RefreshTokenExpiresAt: i64(month)}, g("old", now+hour, month), false); d.Apply || d.Reason != "not-newer" {
+		t.Fatalf("a late older rotation: %+v", d)
+	}
+	if d := DecideApply(&Grant{AccessToken: "A", ExpiresAt: now + 8*hour, RefreshTokenExpiresAt: i64(month)}, g("re", now+hour, now+5*24*hour), false); !d.Apply || !d.Reissued {
+		t.Fatalf("a re-issued grant: %+v", d)
+	}
+	if d := DecideApply(&Grant{AccessToken: "A", ExpiresAt: now + 8*hour}, g("other", now+hour, month), true); !d.Apply {
+		t.Fatal("a switch was refused")
+	}
+	if d := DecideApply(&Grant{AccessToken: "A"}, Grant{AccessToken: "A"}, true); d.Apply || d.Reason != "already-current" {
+		t.Fatalf("the same token: %+v", d)
+	}
+}
+
+func TestALoginIsSeenAndStrippedWhenTheNodesOwnGrantIsWritten(t *testing.T) {
+	p, _ := node(t, "laptop")
+	writeFile(t, p.credentials(), `{"claudeAiOauth":{"accessToken":"at-login","refreshToken":"rt-login","expiresAt":1700000000000},"other":1}`)
+	login := ReadCredentials(p.credentials())
+	if !HoldsLogin(login) {
+		t.Fatal("a login was not seen")
+	}
+	if err := WriteCredentials(p.credentials(), WithGrant(login, Grant{AccessToken: "at-mesh", ExpiresAt: 1, Scopes: []string{"user:inference"}})); err != nil {
+		t.Fatal(err)
+	}
+	back := ReadCredentials(p.credentials())
+	raw, _ := os.ReadFile(p.credentials())
+	info, _ := os.Stat(p.credentials())
+	if HoldsLogin(back) || GrantOf(back).AccessToken != "at-mesh" || back["other"] == nil || strings.Contains(string(raw), "rt-login") || info.Mode().Perm() != 0o600 {
+		t.Fatalf("written %s (mode %v)", raw, info.Mode())
+	}
+}
+
+func TestTheAccountIsReadFromTheAgentsStateFileAndNeverGuessed(t *testing.T) {
+	p, _ := node(t, "laptop")
+	writeFile(t, p.account(), `{"oauthAccount":{"accountUuid":"u-1","emailAddress":"a@example.org"},"other":2}`)
+	if id := ReadIdentity(p.account()); id == nil || id.AccountUUID != "u-1" || id.EmailAddress != "a@example.org" {
+		t.Fatalf("%+v", id)
+	}
+	if ReadIdentity("/nonexistent/.claude.json") != nil {
+		t.Fatal("an identity from nothing")
+	}
+	writeFile(t, p.account(), `{}`)
+	if ReadIdentity(p.account()) != nil {
+		t.Fatal("an identity from an empty file")
+	}
+}
+
+// ---- the licence, ADR 0206 ----------------------------------------------------------------------------
+
+func TestWhatANodeHoldsIsReportedWithFingerprintsAndItsAccountNeverAToken(t *testing.T) {
+	p, _ := node(t, "laptop")
+	writeFile(t, p.credentials(), `{"claudeAiOauth":{"accessToken":"at-secret","refreshToken":"rt-secret","expiresAt":2000,"refreshTokenExpiresAt":9000}}`)
+	writeFile(t, p.account(), `{"oauthAccount":{"accountUuid":"u-1","emailAddress":"a@example.org"}}`)
+	h := HoldingsOf(p)
+	if h.Node != "laptop" || h.Identity.AccountUUID != "u-1" || *h.Kind != "subscription" || !h.Refresh.Present ||
+		!strings.HasPrefix(*h.Refresh.Fingerprint, "sha256:") || h.Access.ExpiresAt != 2000 || h.ChangedAt == nil {
+		t.Fatalf("%+v", h)
+	}
+	raw, _ := json.Marshal(h)
+	if strings.Contains(string(raw), "at-secret") || strings.Contains(string(raw), "rt-secret") {
+		t.Fatalf("a token is in the report: %s", raw)
+	}
+	var keys map[string]any
+	_ = json.Unmarshal(raw, &keys)
+	for k := range keys {
+		if strings.Contains(strings.ToLower(k), "token") || strings.Contains(strings.ToLower(k), "secret") {
+			t.Fatalf("a field the runtime would refuse: %s", k)
+		}
+	}
+	// The manager reads exactly this shape.
+	if _, err := time.Parse(time.RFC3339Nano, *h.ChangedAt); err != nil {
+		t.Fatalf("the manager cannot read the report's time: %v", err)
+	}
+}
+
+func TestTheGrantAnswersOnlyAWaitingLoginSealedToTheManagersKey(t *testing.T) {
+	p, _ := node(t, "laptop")
+	manager, _ := GenerateKeyPair()
+	if a, _ := GrantFor(p, manager.PublicKey); a.Sealed != nil || a.Waiting == nil || *a.Waiting {
+		t.Fatalf("%+v", a)
+	}
+	writeFile(t, p.credentials(), `{"claudeAiOauth":{"accessToken":"at","refreshToken":"rt-login","expiresAt":1}}`)
+	writeFile(t, p.account(), `{"oauthAccount":{"accountUuid":"u-9"}}`)
+	a, err := GrantFor(p, manager.PublicKey)
+	if err != nil || a.Identity.AccountUUID != "u-9" {
+		t.Fatalf("%+v %v", a, err)
+	}
+	plain, _ := Open(*a.Sealed, manager.PrivateKey)
+	if !strings.Contains(plain, `"refreshToken":"rt-login"`) {
+		t.Fatalf("opened %s", plain)
+	}
+	raw, _ := json.Marshal(a)
+	if strings.Contains(string(raw), "rt-login") {
+		t.Fatal("the refresh token crossed in the clear")
+	}
+}
+
+// seat answers `current` as the manager does: the grant sealed to the key the node sent.
+func seat(t *testing.T, licence, token string, gen int64, asked *[]string) Ask {
+	return func(address string, args any) (json.RawMessage, error) {
+		*asked = append(*asked, address)
+		key := args.(map[string]any)["public_key"].(string)
+		g, _ := json.Marshal(Grant{AccessToken: token, ExpiresAt: now + 3_600_000})
+		box, err := Seal(string(g), key)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return json.Marshal(Current{Licence: licence, Kind: "subscription", Generation: gen, Sealed: &box})
+	}
+}
+
+func TestANewerGenerationFetchesTheTokenOnceByTheSeatsVerb(t *testing.T) {
+	p, w := node(t, "laptop")
+	var asked []string
+	ask := seat(t, "personal", "at-1", 3, &asked)
+	if _, err := OnBinding(p, &BindingState{Licence: "personal", Kind: "subscription", Generation: 3}, ask, writer(w)); err != nil {
+		t.Fatal(err)
+	}
+	if len(asked) != 1 || asked[0] != "seat:anthropic-licence-manager.current" || creds(t, p)["accessToken"] != "at-1" {
+		t.Fatalf("asked %v, credentials %v", asked, creds(t, p))
+	}
+	if done, _ := OnBinding(p, &BindingState{Licence: "personal", Kind: "subscription", Generation: 3}, ask, writer(w)); done != "" || len(asked) != 1 {
+		t.Fatal("an equal generation asked again")
+	}
+	if HoldingsOf(p).Generation != 3 || w["managed-mcp.json"] == "" {
+		t.Fatal("the generation or the managed files were not written")
+	}
+}
+
+func TestTheTokenANodeIsHandedReplacesALoginsGrantAndLeavesNoRefreshToken(t *testing.T) {
+	p, w := node(t, "laptop")
+	writeFile(t, p.credentials(), `{"claudeAiOauth":{"accessToken":"at-old","refreshToken":"rt-spent","expiresAt":`+
+		strings.TrimSpace(string(mustJSON(now+7_200_000)))+`}}`)
+	var asked []string
+	out, err := Pull(p, seat(t, "personal", "at-new", 1, &asked), writer(w))
+	if err != nil || out["applied"] != true {
+		t.Fatalf("%v %v", out, err)
+	}
+	c := creds(t, p)
+	if c["accessToken"] != "at-new" || c["refreshToken"] != nil || HoldingsOf(p).Refresh.Present {
+		t.Fatalf("%v", c)
+	}
+}
+
+func mustJSON(v any) []byte { b, _ := json.Marshal(v); return b }
+
+// ---- MCP servers in state, ADR 0201 -------------------------------------------------------------------
+
+// bus is the `servers` state as every node in a test shares it, with each node's watch.
+type bus struct {
+	kept     map[string]map[string]any
+	watchers []func(ServerChange)
+}
+
+func (b *bus) Put(key string, value any) error {
+	v := value.(map[string]any)
+	b.kept[key] = v
+	for _, w := range b.watchers {
+		w(ServerChange{Key: key, Op: "put", Value: v})
+	}
+	return nil
+}
+
+func (b *bus) Delete(key string) error {
+	delete(b.kept, key)
+	for _, w := range b.watchers {
+		w(ServerChange{Key: key, Op: "delete"})
+	}
+	return nil
+}
+
+func (b *bus) Keys() ([]string, error) {
+	var out []string
+	for k := range b.kept {
+		out = append(out, k)
+	}
+	return out, nil
+}
+
+// join is a node joining: its view takes the current state, then every change.
+func (b *bus) join(p Paths, w map[string]string) *ServerView {
+	v := NewServerView(p)
+	for k, val := range b.kept {
+		_, _ = OnServerChange(v, ServerChange{Key: k, Op: "put", Value: val}, p, writer(w))
+	}
+	b.watchers = append(b.watchers, func(c ServerChange) { _, _ = OnServerChange(v, c, p, writer(w)) })
+	return v
+}
+
+func noOthers() ([]string, error) { return nil, nil }
+
+func TestRegisteringHerePutsItUnderThisNodesKeyAndAsksAboutTheOthers(t *testing.T) {
+	p, w := node(t, "laptop")
+	b := &bus{kept: map[string]map[string]any{}}
+	v := b.join(p, w)
+	r, err := RegisterServer(p, Registration{Name: "search", Entry: map[string]any{"type": "http", "url": "https://s.example/mcp"}}, b, v, writer(w),
+		func() ([]string, error) { return []string{"laptop", "server", "desktop"}, nil })
+	if err != nil || r["here"] != "changed" || !strings.Contains(r["also"].(string), "server, desktop") || b.kept["laptop.search"] == nil {
+		t.Fatalf("%v %v %v", r, err, b.kept)
+	}
+	if !strings.Contains(w["managed-mcp.json"], `"search"`) {
+		t.Fatal("not rendered")
+	}
+}
+
+func TestEveryNodeRegistrationReachesTheOthersAndALateNodeReadsIt(t *testing.T) {
+	a, wa := node(t, "laptop")
+	s, ws := node(t, "server")
+	b := &bus{kept: map[string]map[string]any{}}
+	va := b.join(a, wa)
+	b.join(s, ws)
+	_, _ = RegisterServer(a, Registration{Name: "docs", Entry: map[string]any{"type": "stdio", "command": "docs-mcp"}, Nodes: []string{"all"}}, b, va, writer(wa), noOthers)
+	if Registered(s)["docs"] == nil || !strings.Contains(ws["managed-mcp.json"], "docs-mcp") {
+		t.Fatalf("the other node did not take it: %v", Registered(s))
+	}
+	late, wl := node(t, "desktop")
+	b.join(late, wl)
+	if Registered(late)["docs"] == nil {
+		t.Fatal("a node joining later did not read the current set")
+	}
+	_, _ = RegisterServer(a, Registration{Name: "docs", Nodes: []string{"all"}}, b, va, writer(wa), noOthers)
+	if Registered(s)["docs"] != nil || Registered(late)["docs"] != nil {
+		t.Fatal("an unregistration did not reach every node")
+	}
+}
+
+func TestANodesOwnRegistrationOverridesTheOneForEveryNode(t *testing.T) {
+	a, wa := node(t, "laptop")
+	s, ws := node(t, "server")
+	b := &bus{kept: map[string]map[string]any{}}
+	va := b.join(a, wa)
+	b.join(s, ws)
+	_, _ = RegisterServer(a, Registration{Name: "x", Entry: map[string]any{"type": "http", "url": "https://all"}, Nodes: []string{"all"}}, b, va, writer(wa), noOthers)
+	_, _ = RegisterServer(a, Registration{Name: "x", Entry: map[string]any{"type": "http", "url": "https://laptop"}}, b, va, writer(wa), noOthers)
+	if Registered(a)["x"]["url"] != "https://laptop" || Registered(s)["x"]["url"] != "https://all" {
+		t.Fatalf("%v %v", Registered(a), Registered(s))
+	}
+	r, _ := RegisterServer(a, Registration{Name: "x"}, b, va, writer(wa), noOthers)
+	if !strings.Contains(r["still"].(string), "still applies here") || Registered(a)["x"]["url"] != "https://all" {
+		t.Fatalf("%v", r)
+	}
+}
+
+func TestABadEntryIsRefusedBeforeAnythingIsPut(t *testing.T) {
+	p, w := node(t, "laptop")
+	b := &bus{kept: map[string]map[string]any{}}
+	v := b.join(p, w)
+	r, _ := RegisterServer(p, Registration{Name: "mesh", Entry: map[string]any{"type": "http", "url": "https://x"}}, b, v, writer(w), noOthers)
+	if r["registered"] != false || len(b.kept) != 0 {
+		t.Fatalf("%v %v", r, b.kept)
+	}
+	if done, _ := OnServerChange(v, ServerChange{Key: "server.b", Op: "put", Value: map[string]any{"type": "http", "url": "https://b"}}, p, writer(w)); done != "" {
+		t.Fatal("another node's key changed this one")
+	}
+}
+
+// An API key goes to the manager sealed to its key, never in the clear, and its file is gone afterwards.
+func TestAnAPIKeyIsHandedOverSealedAndItsFileRemoved(t *testing.T) {
+	p, _ := node(t, "laptop")
+	manager, _ := GenerateKeyPair()
+	file := filepath.Join(p.Home, "api-key")
+	writeFile(t, file, "sk-ant-api03-secret\n")
+	var sent []string
+	ask := func(address string, args any) (json.RawMessage, error) {
+		raw, _ := json.Marshal(args)
+		sent = append(sent, address+" "+string(raw))
+		switch address {
+		case "seat:anthropic-licence-manager.public-key":
+			return json.Marshal(map[string]any{"public_key": manager.PublicKey})
+		case "seat:anthropic-licence-manager.adopt":
+			box := args.(map[string]any)["sealed"].(SealedBox)
+			if key, err := Open(box, manager.PrivateKey); err != nil || key != "sk-ant-api03-secret" {
+				t.Fatalf("the manager opened %q, %v", key, err)
+			}
+			return json.Marshal(map[string]any{"adopted": true})
+		case "seat:anthropic-licence-manager.switch":
+			return json.Marshal(map[string]any{"licence": "api"})
+		}
+		t.Fatalf("asked %s", address)
+		return nil, nil
+	}
+	out, err := AddAPIKey(p, "api", file, true, ask)
+	if err != nil || out["file"] != "removed" || out["switched"] == nil {
+		t.Fatalf("%v %v", out, err)
+	}
+	if _, err := os.Stat(file); !os.IsNotExist(err) {
+		t.Fatal("the key file is still there")
+	}
+	if strings.Contains(strings.Join(sent, "\n"), "sk-ant") {
+		t.Fatalf("the key crossed in the clear: %v", sent)
+	}
+}

modules/claude-code/cmd/claude-code/grant.go

@@ -0,0 +1,198 @@
+package main
+
+// The agent's credentials file, and whether an offered grant may replace what it holds (novox/hq ADR 0183,
+// ADR 0206, design 36 §5). Pure where it decides, so the rules are tested without a file.
+//
+// The file is the vendor's: `{ claudeAiOauth: { accessToken, expiresAt, refreshTokenExpiresAt?, scopes?,
+// subscriptionType?, rateLimitTier? }, ... }`. A node bound to a licence never holds a refresh token, so
+// the one this module writes never carries one; a refresh token found there is a person's login.
+//
+// The lineage rule is the predecessor's, with the incidents that earned it: a rotation of the same licence
+// is applied only if newer; a grant re-issued by a login is adopted whatever its expiry; a switch to another
+// licence is applied regardless, because across licences the expiries are unrelated numbers.
+
+import (
+	"bytes"
+	"encoding/json"
+	"math"
+	"os"
+	"path/filepath"
+)
+
+// Grant is what the manager hands a node: an access token and its expiries, never a refresh token.
+type Grant struct {
+	AccessToken           string   `json:"accessToken"`
+	ExpiresAt             int64    `json:"expiresAt"`
+	RefreshTokenExpiresAt *int64   `json:"refreshTokenExpiresAt,omitempty"`
+	Scopes                []string `json:"scopes,omitempty"`
+	SubscriptionType      string   `json:"subscriptionType,omitempty"`
+	RateLimitTier         string   `json:"rateLimitTier,omitempty"`
+}
+
+// Decision is whether a handed grant is applied, and why not.
+type Decision struct {
+	Apply    bool
+	Reissued bool
+	Reason   string // already-current | not-newer
+}
+
+// generationTolerance: two refresh-token expiries within a day are one lineage; a login starts a fresh
+// window weeks away.
+const generationTolerance = 24 * 60 * 60 * 1000
+
+func sameGeneration(a, b *int64) bool {
+	if a == nil || b == nil {
+		return true
+	}
+	return math.Abs(float64(*a-*b)) <= generationTolerance
+}
+
+// DecideApply says whether an offered grant replaces the one held; switch is a move to another licence.
+func DecideApply(local *Grant, offered Grant, switching bool) Decision {
+	if local == nil || local.AccessToken == "" {
+		return Decision{Apply: true}
+	}
+	if local.AccessToken == offered.AccessToken {
+		return Decision{Reason: "already-current"}
+	}
+	reissued := !sameGeneration(local.RefreshTokenExpiresAt, offered.RefreshTokenExpiresAt)
+	if !switching && !reissued && local.ExpiresAt >= offered.ExpiresAt {
+		return Decision{Reason: "not-newer"}
+	}
+	return Decision{Apply: true, Reissued: reissued}
+}
+
+// Credentials is the file as found, every key kept — the vendor's other keys are not this module's.
+type Credentials map[string]any
+
+func (c Credentials) oauth() map[string]any {
+	o, _ := c["claudeAiOauth"].(map[string]any)
+	return o
+}
+
+// ReadCredentials reads the file, keeping numbers as written; nil when there is none.
+func ReadCredentials(path string) Credentials {
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return nil
+	}
+	dec := json.NewDecoder(bytes.NewReader(raw))
+	dec.UseNumber()
+	var c Credentials
+	if dec.Decode(&c) != nil {
+		return nil
+	}
+	return c
+}
+
+func number(v any) (int64, bool) {
+	switch n := v.(type) {
+	case json.Number:
+		i, err := n.Int64()
+		if err != nil {
+			f, err := n.Float64()
+			return int64(f), err == nil
+		}
+		return i, true
+	case float64:
+		return int64(n), true
+	case int64:
+		return n, true
+	}
+	return 0, false
+}
+
+// GrantOf is the grant the file holds, or nil.
+func GrantOf(c Credentials) *Grant {
+	o := c.oauth()
+	at, _ := o["accessToken"].(string)
+	if at == "" {
+		return nil
+	}
+	g := &Grant{AccessToken: at}
+	g.ExpiresAt, _ = number(o["expiresAt"])
+	if v, ok := number(o["refreshTokenExpiresAt"]); ok {
+		g.RefreshTokenExpiresAt = &v
+	}
+	return g
+}
+
+// HoldsLogin says the file holds a refresh token — which this module never writes, so a person's login.
+func HoldsLogin(c Credentials) bool {
+	rt, _ := c.oauth()["refreshToken"].(string)
+	return rt != ""
+}
+
+// RefreshTokenOf is the refresh token a login left, or "".
+func RefreshTokenOf(c Credentials) string {
+	rt, _ := c.oauth()["refreshToken"].(string)
+	return rt
+}
+
+// WithGrant lays the handed grant over what is there, and deletes any refresh token.
+func WithGrant(local Credentials, g Grant) Credentials {
+	next := Credentials{}
+	for k, v := range local {
+		next[k] = v
+	}
+	oauth := map[string]any{}
+	for k, v := range local.oauth() {
+		oauth[k] = v
+	}
+	oauth["accessToken"] = g.AccessToken
+	oauth["expiresAt"] = g.ExpiresAt
+	if g.RefreshTokenExpiresAt != nil {
+		oauth["refreshTokenExpiresAt"] = *g.RefreshTokenExpiresAt
+	}
+	if len(g.Scopes) > 0 {
+		oauth["scopes"] = g.Scopes
+	}
+	if g.SubscriptionType != "" {
+		oauth["subscriptionType"] = g.SubscriptionType
+	}
+	if g.RateLimitTier != "" {
+		oauth["rateLimitTier"] = g.RateLimitTier
+	}
+	delete(oauth, "refreshToken")
+	next["claudeAiOauth"] = oauth
+	return next
+}
+
+// ReplacedBy is the handed grant in place of the old licence's, whole — scopes and subscription included;
+// only keys outside the grant stay. No refresh token survives.
+func ReplacedBy(local Credentials, g Grant) Credentials {
+	next := Credentials{}
+	for k, v := range local {
+		if k != "claudeAiOauth" {
+			next[k] = v
+		}
+	}
+	return WithGrant(next, g)
+}
+
+// WriteCredentials writes atomically at 0600: a partial credentials file must never be read as a whole one.
+func WriteCredentials(path string, c Credentials) error {
+	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+		return err
+	}
+	raw, err := indented(c)
+	if err != nil {
+		return err
+	}
+	tmp := path + ".mesh-tmp"
+	if err := os.WriteFile(tmp, raw, 0o600); err != nil {
+		return err
+	}
+	return os.Rename(tmp, path)
+}
+
+// indented is JSON as the agent's own files are written: two-space indent, a trailing newline, nothing
+// escaped that need not be.
+func indented(v any) ([]byte, error) {
+	var b bytes.Buffer
+	enc := json.NewEncoder(&b)
+	enc.SetEscapeHTML(false)
+	enc.SetIndent("", "  ")
+	err := enc.Encode(v)
+	return b.Bytes(), err
+}

modules/claude-code/cmd/claude-code/identity.go

@@ -0,0 +1,84 @@
+package main
+
+// Which account the agent is logged in as (novox/hq ADR 0183): not in the token, but in the agent's own
+// state file beside the home, `~/.claude.json` → `oauthAccount`. Read to report and attribute a login;
+// written, three keys and nothing else, when a licence is switched, so the account Claude Code shows is
+// the one whose token it now holds.
+
+import (
+	"bytes"
+	"encoding/json"
+	"os"
+)
+
+// Identity is an account as the agent's state file names it.
+type Identity struct {
+	AccountUUID      string `json:"accountUuid"`
+	EmailAddress     string `json:"emailAddress,omitempty"`
+	OrganizationUUID string `json:"organizationUuid,omitempty"`
+}
+
+func readState(path string) (map[string]any, bool) {
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return nil, false
+	}
+	dec := json.NewDecoder(bytes.NewReader(raw))
+	dec.UseNumber()
+	var m map[string]any
+	if dec.Decode(&m) != nil || m == nil {
+		return nil, false
+	}
+	return m, true
+}
+
+// ReadIdentity is the account the state file names, or nil — never a guess.
+func ReadIdentity(path string) *Identity {
+	m, ok := readState(path)
+	if !ok {
+		return nil
+	}
+	a, _ := m["oauthAccount"].(map[string]any)
+	uuid, _ := a["accountUuid"].(string)
+	if uuid == "" {
+		return nil
+	}
+	id := &Identity{AccountUUID: uuid}
+	id.EmailAddress, _ = a["emailAddress"].(string)
+	id.OrganizationUUID, _ = a["organizationUuid"].(string)
+	return id
+}
+
+// WriteIdentity points the state file's account at id, keeping every other key as found; answers whether
+// the file changed. A file that is there and cannot be read as an object is left alone.
+func WriteIdentity(path string, id Identity) (bool, error) {
+	m, ok := readState(path)
+	if !ok {
+		if _, err := os.Stat(path); err == nil {
+			return false, nil
+		}
+		m = map[string]any{}
+	}
+	current, _ := m["oauthAccount"].(map[string]any)
+	if current == nil {
+		current = map[string]any{}
+	}
+	e, _ := current["emailAddress"].(string)
+	o, _ := current["organizationUuid"].(string)
+	if current["accountUuid"] == id.AccountUUID && e == id.EmailAddress && o == id.OrganizationUUID {
+		return false, nil
+	}
+	current["accountUuid"] = id.AccountUUID
+	current["emailAddress"] = id.EmailAddress
+	current["organizationUuid"] = id.OrganizationUUID
+	m["oauthAccount"] = current
+	raw, err := indented(m)
+	if err != nil {
+		return false, err
+	}
+	tmp := path + ".mesh-tmp"
+	if err := os.WriteFile(tmp, raw, 0o600); err != nil {
+		return false, err
+	}
+	return true, os.Rename(tmp, path)
+}

modules/claude-code/cmd/claude-code/instructions.go

@@ -0,0 +1,12 @@
+package main
+
+// instructionsText is the managed instruction file, generated from the TypeScript renderer it replaced so
+// the file under the agent's managed directory did not change by a byte when the module moved to Go;
+// a test holds it to that renderer's own output (testdata/rendered-by-typescript.json).
+func instructionsText(node, role string) string {
+	return "# This machine is a node of a Novox mesh\n\nWritten by the mesh's `claude-code` module. Edit the module's settings or the catalogue, never this file:\nit is rewritten whenever the module renders.\n\n## Who this node is\n\n- **Node:** `" +
+		node +
+		"`\n- **Role:** " +
+		role +
+		"\n- The other nodes, their roles and what runs where: ask the controller (`mesh-controller.nodes`,\n  `mesh-controller.node`). Nothing here lists them, because a copy drifts.\n\n## How a session on this mesh works\n\nThe console is the only way to the mesh: the MCP server named `mesh`. It offers five tools, and\neverything else is an address you find and call through them:\n\n- `mesh_search` — words in, matching addresses out. `mesh_describe` — one address's arguments.\n- `mesh_call` — call an address. A seat the mesh holds once is `<seat>.<verb>` (the mesh's own verbs\n  are `mesh-controller.<verb>`: `status`, `plan`, `node`, `assign`, `push`, `settings`);\n  a module on a machine is `<node>/<module>.<tool>`.\n- `mesh_overview` and `mesh_machine` — the mesh's seats and machines, and what one machine runs.\n\n- **Symptom first.** For an error, a failing service or anything unexpected, search the record with the\n  literal text before forming a hypothesis: the records module's `records_search`, then\n  `records_read`.\n- **Ask the mesh before changing it**, and change it through the controller's verbs or the catalogue.\n- **A licence** through the `anthropic-licence-manager` seat's verbs. Never edit the agent's credentials\n  file by hand, never print or ask for a token.\n\n## Hard rules\n\n- A file the mesh manages is changed through the verb or the catalogue that owns it, never on disk. If\n  unsure, `mesh-controller.plan` for the node says what the mesh writes there.\n- Never write to a store's database by hand; schema changes are numbered migrations.\n- Never push to a main branch: a branch, a pull request, and a human approval for every merge.\n- The mesh creates no symlinks, and nobody else does either.\n- A package is declared in a module, never installed by hand.\n\n## Conventions\n\n- Commit messages are concise, in the imperative, about why.\n- Test before pushing: nodes update unattended.\n- The playbooks in the record say how research, decisions, designs, issues and hand-offs are done.\n"
+}

modules/claude-code/cmd/claude-code/main.go

@@ -0,0 +1,384 @@
+// claude-code's bundle (novox/hq design 36, ADR 0183, ADR 0206): a binary the node's runtime launches over
+// stdio as the operator account (ADR 0193) and is the bus for (ADR 0198). It is given its state directory
+// and two files the mesh renders into it (ADR 0192), beside the runtime's own words.
+//
+// At start it renders the agent's managed directory, reports what this node holds as the module's
+// `holdings` state and again whenever the credentials file changes, watches the licence manager's
+// `bindings` state for this node and fetches the token when it says so, and watches the module's
+// `servers` state — every node's MCP server registrations (ADR 0201). node.go holds the logic.
+//
+// stdout is the MCP channel; everything this module says, it says on stderr.
+package main
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"time"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+func say(format string, args ...any) {
+	fmt.Fprintf(os.Stderr, "[claude-code] "+format+"\n", args...)
+}
+
+// writeManaged writes one managed file as root, only when its content changed. From a staged file, never
+// /dev/stdin: a child's input may be a socket, which /dev/stdin cannot open (found on the first assignment).
+func writeManaged(name, content string) (string, error) {
+	path := filepath.Join(ManagedDir, name)
+	if was, err := os.ReadFile(path); err == nil && string(was) == content {
+		return name + ": unchanged", nil
+	}
+	staged, err := os.MkdirTemp("", "claude-code-")
+	if err != nil {
+		return "", err
+	}
+	defer os.RemoveAll(staged)
+	source := filepath.Join(staged, name)
+	if err := os.WriteFile(source, []byte(content), 0o644); err != nil {
+		return "", err
+	}
+	args := []string{"install", "-D", "-m", "0644", source, path}
+	if os.Geteuid() != 0 {
+		args = append([]string{"sudo", "-n"}, args...)
+	}
+	if out, err := exec.Command(args[0], args[1:]...).CombinedOutput(); err != nil {
+		return "", fmt.Errorf("%s: could not be written to %s (%s); the module writes there through the operator account's passwordless sudo",
+			name, ManagedDir, strings.TrimSpace(string(out)))
+	}
+	return name + ": written", nil
+}
+
+// ask is a tool on the bus, through the runtime: its answer is the tool's value.
+func ask(address string, args any) (json.RawMessage, error) { return stdio.Ask(address, args) }
+
+// stateOf adapts the SDK's state to what node.go asks of one.
+type stateOf struct{ s stdio.KeptState }
+
+func (s stateOf) Put(key string, value any) error { _, err := s.s.Put(key, value); return err }
+func (s stateOf) Delete(key string) error         { return s.s.Delete(key) }
+func (s stateOf) Keys() ([]string, error)         { return s.s.Keys() }
+
+// nodesRunningMe is the nodes claude-code runs on, from the controller's list of modules — for the register
+// tool's question.
+func nodesRunningMe() ([]string, error) {
+	raw, err := ask("seat:mesh-controller.modules", map[string]any{})
+	if err != nil {
+		return nil, err
+	}
+	var answer struct {
+		Output string `json:"output"`
+	}
+	text := string(raw)
+	if json.Unmarshal(raw, &answer) == nil && answer.Output != "" {
+		text = answer.Output
+	}
+	for _, line := range strings.Split(text, "\n") {
+		if !strings.HasPrefix(line, "claude-code ") {
+			continue
+		}
+		_, on, ok := strings.Cut(line, " on ")
+		if !ok || strings.TrimSpace(on) == "nothing" {
+			return nil, nil
+		}
+		var out []string
+		for _, n := range strings.Split(on, ",") {
+			if n = strings.TrimSpace(n); n != "" {
+				out = append(out, n)
+			}
+		}
+		return out, nil
+	}
+	return nil, nil
+}
+
+func fingerprintOfFile(path string) any {
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return nil
+	}
+	return Fingerprint(string(raw))
+}
+
+func status(p Paths) map[string]any {
+	creds := ReadCredentials(p.credentials())
+	var token any
+	if g := GrantOf(creds); g != nil {
+		token = map[string]any{"fingerprint": Fingerprint(g.AccessToken), "expiresAt": stamp(g.ExpiresAt), "loginWaiting": HoldsLogin(creds)}
+	}
+	var managed []map[string]any
+	for _, f := range []string{"managed-mcp.json", "managed-settings.json", "CLAUDE.md"} {
+		path := filepath.Join(ManagedDir, f)
+		managed = append(managed, map[string]any{"file": path, "fingerprint": fingerprintOfFile(path)})
+	}
+	var licence any
+	var b Binding
+	if readJSON(p.binding(), &b) {
+		licence = b
+	}
+	names := []string{}
+	for n := range Registered(p) {
+		names = append(names, n)
+	}
+	return map[string]any{"node": p.Node, "licence": licence, "token": token, "holdings": HoldingsOf(p),
+		"managed": managed, "registered": names}
+}
+
+func str(description string) map[string]any {
+	return map[string]any{"type": "string", "description": description}
+}
+
+// nodesOf reads the tools' `nodes` argument: absent is this node, "all" every node, else a list.
+func nodesOf(v any) []string {
+	s, _ := v.(string)
+	s = strings.TrimSpace(s)
+	switch s {
+	case "":
+		return nil
+	case "all":
+		return []string{"all"}
+	}
+	var out []string
+	for _, n := range strings.Split(s, ",") {
+		if n = strings.TrimSpace(n); n != "" {
+			out = append(out, n)
+		}
+	}
+	return out
+}
+
+func tools(p Paths, servers ServerState, view *ServerView) []stdio.Tool {
+	nodesArg := str(`more nodes: "all" for every node running claude-code, or a comma-separated list; absent is this node only`)
+	return []stdio.Tool{
+		{Name: "claude_code_status",
+			Description: "Claude Code on this machine as the mesh configured it: the licence it holds and when its token expires, what it reports holding, the managed files, the MCP servers registered here. Fingerprints only, never a token.",
+			Run:         func(map[string]any) (any, error) { return status(p), nil }},
+		{Name: "claude_code_render",
+			Description: "Write Claude Code's managed directory now, from the mesh's facts, this module's settings and the servers registered here.",
+			Run: func(map[string]any) (any, error) {
+				out, err := RenderNow(p, writeManaged)
+				return map[string]any{"rendered": out}, err
+			}},
+		{Name: "claude_code_pull",
+			Description: "Ask the licence manager for this node's current token now and apply it, rather than waiting for its binding to change.",
+			Run:         func(map[string]any) (any, error) { return Pull(p, ask, writeManaged) }},
+		{Name: "claude_code_grant",
+			Description: "For the licence manager (ADR 0206): the full grant in this node's credentials file — a login made here — sealed to the public key given, with the account it belongs to. Nothing when no login is waiting. Never answers a token in the clear.",
+			Input:       map[string]any{"public_key": str("the manager's public key, PEM; the grant opens only with its private half")},
+			Run: func(a map[string]any) (any, error) {
+				key, _ := a["public_key"].(string)
+				if !strings.Contains(key, "PUBLIC KEY") {
+					return nil, errors.New("claude_code_grant seals to a public key, and none was given")
+				}
+				return GrantFor(p, key)
+			}},
+		{Name: "claude_code_add_api_key",
+			Description: "Add an Anthropic API key as a licence (ADR 0209): read from a file on this machine — never typed as an argument — sealed to the licence manager's key, handed over, and the file removed once taken. With use_here, this machine switches to it at once; other machines move with the manager's `switch`.",
+			Input: map[string]any{
+				"name":     str("the licence's name, e.g. api"),
+				"file":     str("a file on this machine holding the key, e.g. ~/api-key (removed once the manager has it)"),
+				"use_here": map[string]any{"type": "boolean", "description": "switch this machine to the new licence"},
+			},
+			Run: func(a map[string]any) (any, error) {
+				name, _ := a["name"].(string)
+				file, _ := a["file"].(string)
+				if strings.TrimSpace(name) == "" || strings.TrimSpace(file) == "" {
+					return nil, errors.New("name and file are required")
+				}
+				if strings.HasPrefix(file, "~/") {
+					file = filepath.Join(p.Home, file[2:])
+				}
+				useHere, _ := a["use_here"].(bool)
+				return AddAPIKey(p, strings.TrimSpace(name), file, useHere, ask)
+			}},
+		{Name: "claude_code_mcp_list",
+			Description: "The MCP servers registered through this module: those that apply on this node (beside the console, `mesh`, and those set in the module's settings), and every registration on the mesh, by key — `all.<server>` for every node, `<node>.<server>` for one.",
+			Run: func(map[string]any) (any, error) {
+				keys, err := servers.Keys()
+				return map[string]any{"here": Registered(p), "everywhere": keys}, err
+			}},
+		{Name: "claude_code_mcp_register",
+			Description: "Register an MCP server with Claude Code on this node, every node, or a list — an http/sse server by url, or a stdio server by command. Kept on the bus, so a node that joins later takes it too. Never put a secret in env or headers: the mesh refuses one.",
+			Input: map[string]any{
+				"name":    str("the server's name: letters, digits, - and _"),
+				"type":    str("http, sse or stdio (default stdio when a command is given, http when a url is)"),
+				"url":     str("an http or sse server's url"),
+				"command": str("a stdio server's program"),
+				"args":    map[string]any{"type": "array", "description": "a stdio server's arguments"},
+				"env":     map[string]any{"type": "object", "description": "a stdio server's environment"},
+				"headers": map[string]any{"type": "object", "description": "an http server's headers"},
+				"nodes":   nodesArg,
+			},
+			Run: func(a map[string]any) (any, error) {
+				entry := map[string]any{}
+				if t, _ := a["type"].(string); t != "" {
+					entry["type"] = t
+				} else if _, hasURL := a["url"]; hasURL {
+					entry["type"] = "http"
+				} else {
+					entry["type"] = "stdio"
+				}
+				for _, k := range []string{"url", "command", "args", "env", "headers"} {
+					if v, ok := a[k]; ok {
+						entry[k] = v
+					}
+				}
+				name, _ := a["name"].(string)
+				return RegisterServer(p, Registration{Name: name, Entry: entry, Nodes: nodesOf(a["nodes"])}, servers, view, writeManaged, nodesRunningMe)
+			}},
+		{Name: "claude_code_mcp_unregister",
+			Description: "Remove an MCP server registered through this module, on this node or more.",
+			Input:       map[string]any{"name": str("the server's name"), "nodes": nodesArg},
+			Run: func(a map[string]any) (any, error) {
+				name, _ := a["name"].(string)
+				return RegisterServer(p, Registration{Name: name, Nodes: nodesOf(a["nodes"])}, servers, view, writeManaged, nodesRunningMe)
+			}},
+	}
+}
+
+// persist asks the state again until it answers: its bucket or the bus's grant may arrive after the module.
+func persist(what string, attempt func() error, done func(refusals int)) {
+	waits := []time.Duration{2 * time.Second, 5 * time.Second, 10 * time.Second, 30 * time.Second}
+	for n := 0; ; n++ {
+		err := attempt()
+		if err == nil {
+			done(n)
+			return
+		}
+		pause := time.Minute
+		if n < len(waits) {
+			pause = waits[n]
+		}
+		say("%s not yet (%v); asking again in %s", what, err, pause)
+		time.Sleep(pause)
+	}
+}
+
+func main() {
+	p, launched := PathsFrom(os.Getenv)
+	if !launched {
+		// Outside a launch — a build, a check — it serves nothing and says why.
+		say("not launched by the runtime with this module's words; serving no tools")
+		if err := stdio.Serve("", nil); err != nil {
+			os.Exit(1)
+		}
+		return
+	}
+	if _, err := Keypair(p); err != nil {
+		say("this module's key: %v", err)
+	}
+	if out, err := RenderNow(p, writeManaged); err != nil {
+		say("%v", err)
+	} else {
+		for _, line := range out {
+			if !strings.HasSuffix(line, "unchanged") {
+				say("%s", line)
+			}
+		}
+	}
+	servers := stateOf{stdio.State("servers")}
+	view := NewServerView(p)
+	go run(p, view)
+	if err := stdio.Serve("", tools(p, servers, view)); err != nil {
+		say("%v", err)
+		os.Exit(1)
+	}
+}
+
+// run is the module's long-running half, beside the tools (ADR 0198).
+func run(p Paths, view *ServerView) {
+	// Every node's MCP servers: the whole current set first, then each change (ADR 0201).
+	go persist("watching the MCP servers", func() error {
+		return stdio.State("servers").Watch("", func(c stdio.StateChange) error {
+			var value map[string]any
+			_ = json.Unmarshal(c.Value, &value)
+			if done, err := OnServerChange(view, ServerChange{Key: c.Key, Op: c.Op, Value: value}, p, writeManaged); err != nil {
+				say("taking %s %s: %v", c.Op, c.Key, err) // the view took it; the next render writes it
+			} else if done != "" {
+				say("%s", done)
+			}
+			return nil
+		})
+	}, func(n int) { say("watching the MCP servers%s", refusals(n)) })
+
+	// What this node holds (ADR 0206): at start — a node already logged in is reported at once — and on
+	// every change of the credentials file, polled, because the file is replaced by rename and a watch on
+	// the old inode would go quiet. Fingerprints and expiries only.
+	holdings := stdio.State("holdings")
+	reported := ""
+	report := func() {
+		now := HoldingsOf(p)
+		raw, _ := json.Marshal(now)
+		if string(raw) == reported {
+			return
+		}
+		persist("reporting what this node holds", func() error { _, err := holdings.Put(p.Node, now); return err }, func(int) {
+			reported = string(raw)
+			account := "no account"
+			if now.Identity != nil && now.Identity.EmailAddress != "" {
+				account = now.Identity.EmailAddress
+			}
+			line := "reported: " + account
+			if now.Kind != nil {
+				line += ", " + *now.Kind
+			}
+			if now.Refresh.Present {
+				line += ", a login waiting"
+			}
+			if now.Licence != nil {
+				line += fmt.Sprintf(", licence %s g%d", *now.Licence, now.Generation)
+			}
+			say("%s", line)
+		})
+	}
+
+	// What this node should hold (ADR 0206): the manager's `bindings` key for this node; a newer
+	// generation is fetched with the seat's `current`, sealed to this module's key.
+	go persist("watching this node's licence binding", func() error {
+		return stdio.State(Manager+".bindings").Watch(p.Node, func(c stdio.StateChange) error {
+			if c.Key != p.Node {
+				return nil
+			}
+			var b *BindingState
+			if c.Op == "put" {
+				b = &BindingState{}
+				if err := json.Unmarshal(c.Value, b); err != nil {
+					return nil
+				}
+			}
+			if done, err := OnBinding(p, b, ask, writeManaged); err != nil {
+				say("fetching this node's token failed: %v", err)
+			} else if done != "" {
+				say("%s", done)
+			}
+			go report()
+			return nil
+		})
+	}, func(n int) { say("watching this node's licence binding%s", refusals(n)) })
+
+	report()
+	var last string
+	for range time.Tick(5 * time.Second) {
+		info, err := os.Stat(p.credentials())
+		now := "absent"
+		if err == nil {
+			now = fmt.Sprintf("%d/%d", info.ModTime().UnixNano(), info.Size())
+		}
+		if now != last {
+			last = now
+			report()
+		}
+	}
+}
+
+func refusals(n int) string {
+	if n == 0 {
+		return ""
+	}
+	return fmt.Sprintf(" (after %d refusal(s))", n)
+}

modules/claude-code/cmd/claude-code/node.go

@@ -0,0 +1,577 @@
+package main
+
+// What claude-code does on a node, written against what it is handed — a way to ask a tool on the bus, its
+// own state, a way to write a managed file — so every path is tested without a bus (novox/hq design 36,
+// ADR 0183, ADR 0201, ADR 0206).
+//
+// Over NATS, and nothing an event: what is current is state, and a secret only ever travels on a request,
+// sealed to its one recipient.
+//   - What this node holds is the module's `holdings` state, one key per node: the account, the kind,
+//     fingerprints and expiries — never a token. Written at start and on every change of the credentials
+//     file, so the licence manager learns a login, or a node already logged in, from the state alone.
+//   - The grant itself leaves only when the manager asks `claude_code_grant`, sealed to the key it gives.
+//   - What this node should hold is the manager's `bindings` state; a newer generation for this node is
+//     fetched with the seat's `current` verb, sealed to this module's key, and written access-token-only.
+//   - An MCP server registered through this module is a key in its `servers` state — `all.<server>` for
+//     every node, `<node>.<server>` for one — which every node watches.
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"sync"
+	"time"
+)
+
+// Seat is the licence manager's role, and Manager the module whose `bindings` state this one reads.
+const (
+	Seat    = "anthropic-licence-manager"
+	Manager = "claude-licence-manager"
+)
+
+// SeatVerb is a seat's verb as the runtime addresses it: a role, not a module.
+func SeatVerb(verb string) string { return "seat:" + Seat + "." + verb }
+
+// Fingerprint names a token without being one: the first 16 hex of its SHA-256, as the manager computes it.
+func Fingerprint(s string) string {
+	sum := sha256.Sum256([]byte(s))
+	return "sha256:" + hex.EncodeToString(sum[:])[:16]
+}
+
+// Paths are where this node's files are, from the module's words (ADR 0192).
+type Paths struct {
+	State, Facts, Settings, Home, Node string
+}
+
+// PathsFrom reads them, or answers false outside a launch.
+func PathsFrom(env func(string) string) (Paths, bool) {
+	p := Paths{State: env("MESH_CLAUDE_CODE_STATE"), Facts: env("MESH_CLAUDE_CODE_FACTS"),
+		Settings: env("MESH_CLAUDE_CODE_SETTINGS"), Home: env("MESH_OPERATOR_HOME"), Node: env("MESH_NODE")}
+	return p, p.State != "" && p.Facts != "" && p.Settings != "" && p.Home != "" && p.Node != ""
+}
+
+func (p Paths) credentials() string { return filepath.Join(p.Home, ".claude", ".credentials.json") }
+func (p Paths) account() string     { return filepath.Join(p.Home, ".claude.json") }
+func (p Paths) binding() string     { return filepath.Join(p.State, "licence.json") }
+func (p Paths) apiKey() string      { return filepath.Join(p.State, "api-key") }
+func (p Paths) helper() string      { return filepath.Join(p.State, "api-key-helper") }
+func (p Paths) registry() string    { return filepath.Join(p.State, "mcp-servers.json") }
+
+// Ask is a tool on the bus: its address and arguments in, its JSON answer out.
+type Ask func(address string, args any) (json.RawMessage, error)
+
+// WriteManaged writes one managed file and answers what happened.
+type WriteManaged func(name, content string) (string, error)
+
+func readJSON(path string, into any) bool {
+	raw, err := os.ReadFile(path)
+	return err == nil && json.Unmarshal(raw, into) == nil
+}
+
+// Keypair is this module's own, made once in its state; the TypeScript module's files are kept, so a node
+// moving to this binary keeps the key it had.
+func Keypair(p Paths) (KeyPair, error) {
+	priv, pub := filepath.Join(p.State, "key.pem"), filepath.Join(p.State, "key.pub.pem")
+	if _, err := os.Stat(priv); errors.Is(err, os.ErrNotExist) {
+		k, err := GenerateKeyPair()
+		if err != nil {
+			return KeyPair{}, err
+		}
+		if err := os.WriteFile(priv, []byte(k.PrivateKey), 0o600); err != nil {
+			return KeyPair{}, err
+		}
+		if err := os.WriteFile(pub, []byte(k.PublicKey), 0o644); err != nil {
+			return KeyPair{}, err
+		}
+	}
+	a, err1 := os.ReadFile(priv)
+	b, err2 := os.ReadFile(pub)
+	return KeyPair{PrivateKey: string(a), PublicKey: string(b)}, errors.Join(err1, err2)
+}
+
+// Registered is what applies here of the servers registered through this module.
+func Registered(p Paths) Servers {
+	s := Servers{}
+	readJSON(p.registry(), &s)
+	return s
+}
+
+// RenderNow writes the managed directory from the facts, the settings, the licence held and the servers
+// registered here.
+func RenderNow(p Paths, write WriteManaged) ([]string, error) {
+	var facts Facts
+	if !readJSON(p.Facts, &facts) || facts.Console == "" {
+		return nil, fmt.Errorf("the mesh has not rendered %s yet; nothing to write", p.Facts)
+	}
+	var settings Settings
+	readJSON(p.Settings, &settings)
+	var binding *Binding
+	var b Binding
+	if readJSON(p.binding(), &b) {
+		binding = &b
+	}
+	files := Render(facts, settings, binding, p.helper(), Registered(p))
+	names := make([]string, 0, len(files))
+	for n := range files {
+		names = append(names, n)
+	}
+	sort.Strings(names)
+	var out []string
+	for _, n := range names {
+		line, err := write(n, files[n])
+		if err != nil {
+			return out, err
+		}
+		out = append(out, line)
+	}
+	return out, nil
+}
+
+// ---- the licence ----------------------------------------------------------------------------------
+
+// BindingState is what the manager's `bindings` state says one consumer should hold (ADR 0206).
+type BindingState struct {
+	Licence    string `json:"licence"`
+	Kind       string `json:"kind"`
+	Generation int64  `json:"generation"`
+}
+
+// Current is what the seat answers to `current`: the licence this node is bound to and its token, sealed.
+type Current struct {
+	Licence    string     `json:"licence"`
+	Kind       string     `json:"kind"`
+	Generation int64      `json:"generation"`
+	Sealed     *SealedBox `json:"sealed"`
+	Identity   *Identity  `json:"identity"`
+}
+
+// Holdings is what this node holds, as the `holdings` state carries it (ADR 0206): enough for the manager
+// to tell a login it has not adopted from one it has, and never a token — fingerprints and expiries only.
+type Holdings struct {
+	Node     string    `json:"node"`
+	Identity *Identity `json:"identity"`
+	Kind     *string   `json:"kind"`
+	Refresh  struct {
+		Present     bool    `json:"present"`
+		Fingerprint *string `json:"fingerprint"`
+		ExpiresAt   *int64  `json:"expiresAt"`
+	} `json:"refresh"`
+	Access *struct {
+		Fingerprint string `json:"fingerprint"`
+		ExpiresAt   int64  `json:"expiresAt"`
+	} `json:"access"`
+	Licence    *string `json:"licence"`
+	Generation int64   `json:"generation"`
+	ChangedAt  *string `json:"changedAt"`
+}
+
+// HoldingsOf is what this node holds now.
+func HoldingsOf(p Paths) Holdings {
+	h := Holdings{Node: p.Node, Identity: ReadIdentity(p.account())}
+	creds := ReadCredentials(p.credentials())
+	if info, err := os.Stat(p.credentials()); err == nil {
+		at := info.ModTime().UTC().Format("2006-01-02T15:04:05.000Z")
+		h.ChangedAt = &at
+	}
+	if rt := RefreshTokenOf(creds); rt != "" {
+		fp := Fingerprint(rt)
+		h.Refresh.Present, h.Refresh.Fingerprint = true, &fp
+	}
+	if v, ok := number(creds.oauth()["refreshTokenExpiresAt"]); ok {
+		h.Refresh.ExpiresAt = &v
+	}
+	if g := GrantOf(creds); g != nil {
+		h.Access = &struct {
+			Fingerprint string `json:"fingerprint"`
+			ExpiresAt   int64  `json:"expiresAt"`
+		}{Fingerprint(g.AccessToken), g.ExpiresAt}
+	}
+	kind := ""
+	if _, err := os.Stat(p.apiKey()); err == nil {
+		kind = "api-key"
+	} else if h.Access != nil {
+		kind = "subscription"
+	}
+	if kind != "" {
+		h.Kind = &kind
+	}
+	var applied Binding
+	if readJSON(p.binding(), &applied) && applied.Licence != "" {
+		h.Licence, h.Generation = &applied.Licence, applied.Generation
+	}
+	return h
+}
+
+// GrantAnswer is what `claude_code_grant` answers: a login sealed to the key given, or nothing waiting.
+type GrantAnswer struct {
+	Sealed      *SealedBox `json:"sealed,omitempty"`
+	Identity    *Identity  `json:"identity,omitempty"`
+	Fingerprint string     `json:"fingerprint,omitempty"`
+	Waiting     *bool      `json:"waiting,omitempty"`
+}
+
+// GrantFor is the full grant in the credentials file sealed to the manager's key — the one time a refresh
+// token leaves this node, for the manager to adopt by refreshing it (ADR 0206). Nothing waiting when the
+// file holds no refresh token.
+func GrantFor(p Paths, managerPublicKey string) (GrantAnswer, error) {
+	creds := ReadCredentials(p.credentials())
+	rt := RefreshTokenOf(creds)
+	if rt == "" {
+		no := false
+		return GrantAnswer{Waiting: &no}, nil
+	}
+	raw, err := json.Marshal(creds.oauth())
+	if err != nil {
+		return GrantAnswer{}, err
+	}
+	box, err := Seal(string(raw), managerPublicKey)
+	if err != nil {
+		return GrantAnswer{}, err
+	}
+	return GrantAnswer{Sealed: &box, Identity: ReadIdentity(p.account()), Fingerprint: Fingerprint(rt)}, nil
+}
+
+// Pull asks the seat for this node's current token and applies it.
+func Pull(p Paths, ask Ask, write WriteManaged) (map[string]any, error) {
+	keys, err := Keypair(p)
+	if err != nil {
+		return nil, err
+	}
+	raw, err := ask(SeatVerb("current"), map[string]any{"consumer": p.Node, "public_key": keys.PublicKey})
+	if err != nil {
+		return nil, err
+	}
+	var c Current
+	if err := json.Unmarshal(raw, &c); err != nil || c.Sealed == nil {
+		return map[string]any{"applied": false, "reason": "the seat holds no licence for this node"}, nil
+	}
+	return Apply(p, c, write)
+}
+
+// OnBinding takes a change to this node's key in the manager's `bindings` state (ADR 0206): the token is
+// fetched when the generation is newer than the one applied. A released binding keeps the last token,
+// which lives hours, and says so.
+func OnBinding(p Paths, b *BindingState, ask Ask, write WriteManaged) (string, error) {
+	if b == nil {
+		return "this node's binding was released; it keeps its last token until it expires", nil
+	}
+	var applied Binding
+	if readJSON(p.binding(), &applied) && applied.Generation >= b.Generation {
+		return "", nil
+	}
+	out, err := Pull(p, ask, write)
+	if err != nil {
+		return "", err
+	}
+	raw, _ := json.Marshal(out)
+	return string(raw), nil
+}
+
+// Apply applies what the seat handed over. A switch replaces the grant whole and cleans up after the old
+// licence; whatever it is, the file is written without a refresh token, so the agent here never refreshes.
+func Apply(p Paths, c Current, write WriteManaged) (map[string]any, error) {
+	keys, err := Keypair(p)
+	if err != nil {
+		return nil, err
+	}
+	plain, err := Open(*c.Sealed, keys.PrivateKey)
+	if err != nil {
+		return nil, err
+	}
+	var previous Binding
+	had := readJSON(p.binding(), &previous)
+	switched := !had || previous.Licence != c.Licence
+	out := map[string]any{"applied": true, "licence": c.Licence, "kind": c.Kind, "switched": switched}
+	if c.Kind == "api-key" {
+		if err := os.WriteFile(p.apiKey(), []byte(strings.TrimSpace(plain)+"\n"), 0o600); err != nil {
+			return nil, err
+		}
+		if err := os.WriteFile(p.helper(), []byte("#!/bin/sh\nexec cat '"+p.apiKey()+"'\n"), 0o700); err != nil {
+			return nil, err
+		}
+		_ = os.Chmod(p.helper(), 0o700)
+	} else {
+		var g Grant
+		if err := json.Unmarshal([]byte(plain), &g); err != nil {
+			return nil, err
+		}
+		local := ReadCredentials(p.credentials())
+		// A login waiting here was handed to the manager first (ADR 0206): what comes back is its successor,
+		// and the refresh token in the file is the one the manager just spent.
+		d := DecideApply(GrantOf(local), g, switched || HoldsLogin(local))
+		if d.Apply {
+			next := WithGrant(local, g)
+			if switched {
+				next = ReplacedBy(local, g)
+			}
+			if err := WriteCredentials(p.credentials(), next); err != nil {
+				return nil, err
+			}
+		} else {
+			out = map[string]any{"applied": false, "licence": c.Licence, "reason": d.Reason}
+		}
+		// Away from the API key: it goes, with its helper.
+		_ = os.Remove(p.apiKey())
+		_ = os.Remove(p.helper())
+	}
+	if switched && c.Identity != nil && c.Identity.AccountUUID != "" {
+		changed, err := WriteIdentity(p.account(), *c.Identity)
+		if err == nil {
+			out["account"] = map[bool]string{true: "updated", false: "unchanged"}[changed]
+		}
+	}
+	gen := c.Generation
+	if gen == 0 {
+		gen = previous.Generation
+	}
+	raw, _ := json.Marshal(Binding{Licence: c.Licence, Kind: c.Kind, Generation: gen})
+	if err := os.WriteFile(p.binding(), append(raw, '\n'), 0o600); err != nil {
+		return nil, err
+	}
+	// The key-helper comes or goes with the licence's kind.
+	if rendered, err := RenderNow(p, write); err != nil {
+		out["rendered"] = map[string]any{"failed": err.Error()}
+	} else {
+		out["rendered"] = rendered
+	}
+	return out, nil
+}
+
+// AddAPIKey adds an API key from a file on this node to the licence manager (ADR 0209): sealed to the
+// manager's public key, handed to the seat's `adopt` on request/reply, and the file removed once taken. With
+// useHere, this node is switched to the new licence. The key never crosses the bus in the clear and is
+// never an argument.
+func AddAPIKey(p Paths, name, file string, useHere bool, ask Ask) (map[string]any, error) {
+	raw, err := os.ReadFile(file)
+	if err != nil {
+		return nil, fmt.Errorf("the key is read from a file on this node: %w", err)
+	}
+	key := strings.TrimSpace(string(raw))
+	if key == "" {
+		return nil, fmt.Errorf("%s is empty", file)
+	}
+	answer, err := ask(SeatVerb("public-key"), map[string]any{})
+	if err != nil {
+		return nil, err
+	}
+	var pk struct {
+		PublicKey string `json:"public_key"`
+	}
+	if err := json.Unmarshal(answer, &pk); err != nil || !strings.Contains(pk.PublicKey, "PUBLIC KEY") {
+		return nil, errors.New("the licence manager did not say what key to seal to")
+	}
+	box, err := Seal(key, pk.PublicKey)
+	if err != nil {
+		return nil, err
+	}
+	adopted, err := ask(SeatVerb("adopt"), map[string]any{"name": name, "sealed": box, "from": p.Node})
+	if err != nil {
+		return nil, err
+	}
+	out := map[string]any{"adopted": json.RawMessage(adopted)}
+	// Taken: the key now lives encrypted in the manager's store alone.
+	if err := os.Remove(file); err != nil {
+		out["file"] = "could not be removed: " + err.Error()
+	} else {
+		out["file"] = "removed"
+	}
+	if useHere {
+		switched, err := ask(SeatVerb("switch"), map[string]any{"consumer": p.Node, "licence": name})
+		if err != nil {
+			return out, fmt.Errorf("adopted, and switching this node to it failed: %w", err)
+		}
+		out["switched"] = json.RawMessage(switched)
+	}
+	return out, nil
+}
+
+// ---- MCP servers ----------------------------------------------------------------------------------
+
+// Registration is a server registered (or, with no entry, unregistered) through this module.
+type Registration struct {
+	Name  string
+	Entry map[string]any
+	// Nodes: nil for this node, ["all"] for every node running the module, or a list.
+	Nodes []string
+}
+
+// ServerState is the `servers` state as this module reaches it through the runtime.
+type ServerState interface {
+	Put(key string, value any) error
+	Delete(key string) error
+	Keys() ([]string, error)
+}
+
+// ServerChange is one change to the `servers` state, as a watch hands it over.
+type ServerChange struct {
+	Key   string
+	Op    string // put | delete
+	Value map[string]any
+}
+
+// KeyOf is the key a registration lives at: `all.<server>` for every node, `<node>.<server>` for one.
+func KeyOf(scope, name string) string { return scope + "." + name }
+
+// ServerView is what this node takes from the `servers` state: the entries for every node and for this
+// one, kept in memory from the watch and written through to the module's own file whenever what applies
+// here changes, so the managed directory renders without the bus.
+type ServerView struct {
+	p       Paths
+	mu      sync.Mutex
+	entries map[string]map[string]any
+}
+
+// NewServerView is an empty view for this node.
+func NewServerView(p Paths) *ServerView {
+	return &ServerView{p: p, entries: map[string]map[string]any{}}
+}
+
+// Take takes one change, and answers whether what applies to this node changed.
+func (v *ServerView) Take(c ServerChange) bool {
+	scope, name, ok := strings.Cut(c.Key, ".")
+	if !ok || scope == "" || (scope != "all" && scope != v.p.Node) {
+		return false
+	}
+	v.mu.Lock()
+	if c.Op == "put" && c.Value != nil && EntryProblem(name, c.Value) == "" {
+		v.entries[c.Key] = c.Value
+	} else {
+		delete(v.entries, c.Key)
+	}
+	v.mu.Unlock()
+	return v.writeThrough()
+}
+
+// Effective is what applies here: every node's entries, with this node's own laid over them by name.
+func (v *ServerView) Effective() Servers {
+	v.mu.Lock()
+	defer v.mu.Unlock()
+	out := Servers{}
+	for _, scope := range []string{"all", v.p.Node} {
+		for key, entry := range v.entries {
+			if name, ok := strings.CutPrefix(key, scope+"."); ok {
+				out[name] = entry
+			}
+		}
+	}
+	return out
+}
+
+func (v *ServerView) writeThrough() bool {
+	now, _ := indented(v.Effective())
+	before, _ := os.ReadFile(v.p.registry())
+	if string(before) == string(now) {
+		return false
+	}
+	_ = os.WriteFile(v.p.registry(), now, 0o600)
+	return true
+}
+
+// OnServerChange takes a change from the watch, and renders when what applies here changed.
+func OnServerChange(v *ServerView, c ServerChange, p Paths, write WriteManaged) (string, error) {
+	if !v.Take(c) {
+		return "", nil
+	}
+	if _, err := RenderNow(p, write); err != nil {
+		return "", err
+	}
+	what := "registered"
+	if c.Op != "put" {
+		what = "unregistered"
+	}
+	return what + " " + c.Key, nil
+}
+
+// RegisterServer registers (or, with no entry, unregisters) a server: a put (or delete) per scope in the
+// `servers` state, taken into this node's view at once so the answer says what it did here; every other
+// node takes it from its watch, and a node that joins later from the current state.
+func RegisterServer(p Paths, r Registration, servers ServerState, v *ServerView, write WriteManaged,
+	others func() ([]string, error)) (map[string]any, error) {
+	if r.Entry != nil {
+		if problem := EntryProblem(r.Name, r.Entry); problem != "" {
+			return map[string]any{"registered": false, "reason": problem}, nil
+		}
+	}
+	scopes := r.Nodes
+	if len(scopes) == 0 {
+		scopes = []string{p.Node}
+	}
+	// Compared before and after rather than read from Take: this node's own watch may hand the view the
+	// same change first, and then Take here finds nothing new although this call made it.
+	before, _ := json.Marshal(v.Effective())
+	for _, scope := range scopes {
+		key := KeyOf(scope, r.Name)
+		var err error
+		if r.Entry != nil {
+			err = servers.Put(key, r.Entry)
+		} else {
+			err = servers.Delete(key)
+		}
+		if err != nil {
+			return nil, err
+		}
+		op := "put"
+		if r.Entry == nil {
+			op = "delete"
+		}
+		v.Take(ServerChange{Key: key, Op: op, Value: r.Entry})
+	}
+	after, _ := json.Marshal(v.Effective())
+	changed := string(before) != string(after)
+	here := false
+	for _, s := range scopes {
+		here = here || s == "all" || s == p.Node
+	}
+	verb := "registered"
+	if r.Entry == nil {
+		verb = "unregistered"
+	}
+	answer := map[string]any{verb: r.Name, "on": scopes}
+	switch {
+	case !here:
+		answer["here"] = "not this node"
+	case changed:
+		answer["here"] = "changed"
+	default:
+		answer["here"] = "already so"
+	}
+	if changed {
+		rendered, err := RenderNow(p, write)
+		if err != nil {
+			return nil, err
+		}
+		answer["rendered"] = rendered
+	}
+	if r.Entry == nil {
+		if _, still := v.Effective()[r.Name]; still {
+			answer["still"] = r.Name + " still applies here from another registration (for every node, or for this one); unregister that too"
+		}
+	}
+	if len(r.Nodes) == 0 {
+		// The question the operator wanted asked: here only, or more?
+		var elsewhere []string
+		if nodes, err := others(); err == nil {
+			for _, n := range nodes {
+				if n != p.Node {
+					elsewhere = append(elsewhere, n)
+				}
+			}
+		}
+		if len(elsewhere) > 0 {
+			answer["also"] = fmt.Sprintf("claude-code also runs on %s. To %s it there too, call again with nodes: \"all\" or a list of those nodes.",
+				strings.Join(elsewhere, ", "), map[bool]string{true: "register", false: "unregister"}[r.Entry != nil])
+		} else {
+			answer["also"] = "To do the same on every node running claude-code, call again with nodes: \"all\"."
+		}
+	}
+	return answer, nil
+}
+
+// stamp is a time as the status answers it.
+func stamp(ms int64) string { return time.UnixMilli(ms).UTC().Format(time.RFC3339) }

modules/claude-code/cmd/claude-code/render.go

@@ -0,0 +1,121 @@
+package main
+
+// What the module writes into the agent's machine-wide managed directory (novox/hq design 36 §1–§4).
+// Pure: composed from the facts the mesh rendered, the settings the operator set and the licence the node
+// holds, so what lands under /etc is tested without a machine.
+//
+// Three files, owned whole by this module:
+//
+//	managed-mcp.json        the tool servers every session loads: the mesh's console as `mesh`, and the
+//	                        servers the operator declared or registered through this module. Exclusive by
+//	                        the vendor's rule — a server not listed here does not load (operator's choice,
+//	                        2026-10-03).
+//	managed-settings.json   the mesh's keys only: the repositories' attribution convention, the claude.ai
+//	                        connectors kept beside the managed servers, and — for an API-key licence only —
+//	                        the key-helper. A person's preferences are theirs.
+//	CLAUDE.md               how a session on this mesh works, who this node is, the conventions.
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"regexp"
+	"strings"
+)
+
+// ManagedDir is the agent's machine-wide managed directory.
+const ManagedDir = "/etc/claude-code"
+
+const meshEntry = "mesh"
+
+// Facts are what the mesh rendered for this node.
+type Facts struct {
+	Node    string `json:"node"`
+	Console string `json:"console"`
+}
+
+// Settings are the operator's, for the mesh or this node.
+type Settings struct {
+	Role       string                    `json:"role"`
+	MCPServers map[string]map[string]any `json:"mcp_servers"`
+}
+
+// Binding is the licence this node holds, as it was last applied.
+type Binding struct {
+	Licence    string `json:"licence"`
+	Kind       string `json:"kind"` // subscription | api-key
+	Generation int64  `json:"generation,omitempty"`
+}
+
+// Servers are tool server entries by name, in the vendor's `.mcp.json` shape.
+type Servers map[string]map[string]any
+
+var serverName = regexp.MustCompile(`^[A-Za-z0-9_-]+$`)
+
+// EntryProblem says why the vendor's managed file would not take an entry, or "" when it would: a name of
+// letters, digits, `-` and `_`, and an http/sse server with a url or a stdio server with a command.
+func EntryProblem(name string, entry map[string]any) string {
+	if !serverName.MatchString(name) {
+		return fmt.Sprintf("%q is not a name the agent takes: letters, digits, - and _", name)
+	}
+	if name == meshEntry {
+		return fmt.Sprintf("%q is the mesh's own entry", meshEntry)
+	}
+	kind, _ := entry["type"].(string)
+	if kind == "" {
+		kind = "stdio"
+	}
+	switch kind {
+	case "http", "sse", "streamable-http":
+		if u, _ := entry["url"].(string); u != "" {
+			return ""
+		}
+		return fmt.Sprintf("an %s server needs a url", kind)
+	case "stdio":
+		if c, _ := entry["command"].(string); c != "" {
+			return ""
+		}
+		return "a stdio server needs a command"
+	}
+	return fmt.Sprintf("%q is not a server type the agent knows (http, sse, stdio)", kind)
+}
+
+// jsonFile is a value as the managed files are written: two-space indent, a trailing newline, nothing
+// escaped that need not be.
+func jsonFile(v any) string {
+	var b bytes.Buffer
+	enc := json.NewEncoder(&b)
+	enc.SetEscapeHTML(false)
+	enc.SetIndent("", "  ")
+	_ = enc.Encode(v)
+	return b.String()
+}
+
+// Render composes the three files. registered — what was registered through this module and applies
+// here — is laid over the servers the operator set in its settings.
+func Render(facts Facts, settings Settings, binding *Binding, helperPath string, registered Servers) map[string]string {
+	servers := map[string]any{}
+	for _, layer := range []map[string]map[string]any{settings.MCPServers, registered} {
+		for name, entry := range layer {
+			if EntryProblem(name, entry) != "" {
+				continue // the mesh's own entry, or one the agent would refuse
+			}
+			servers[name] = entry
+		}
+	}
+	servers[meshEntry] = map[string]any{"type": "http", "url": facts.Console}
+
+	managed := map[string]any{"attribution": map[string]any{"commit": "", "pr": ""}, "allowAllClaudeAiMcps": true}
+	if binding != nil && binding.Kind == "api-key" {
+		managed["apiKeyHelper"] = helperPath
+	}
+	role := strings.TrimSpace(settings.Role)
+	if role == "" {
+		role = "not stated — set it in this module's settings for the node"
+	}
+	return map[string]string{
+		"managed-mcp.json":      jsonFile(map[string]any{"mcpServers": servers}),
+		"managed-settings.json": jsonFile(managed),
+		"CLAUDE.md":             instructionsText(facts.Node, role),
+	}
+}

modules/claude-code/cmd/claude-code/seal.go

@@ -0,0 +1,189 @@
+package main
+
+// Sealing to one recipient (novox/hq ADR 0183, ADR 0206): the manager seals what it hands a consumer to
+// the key that consumer sent, and a node seals a waiting login to the key the manager gives. The same box
+// the agent module's TypeScript makes and opens, byte for byte — X25519 for the agreement, HKDF-SHA256 for
+// the key, AES-256-GCM for the box — so `testdata/sealed-by-typescript.json` is opened here, and a test
+// reopens what this seals with the same derivation.
+//
+// A box is `{ v: 1, eph, iv, tag, ct }`, every field base64; `eph` is the one-time public key as SPKI DER,
+// and the key is bound to it and to the recipient's raw public key, so a box cannot be re-addressed.
+
+import (
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/ecdh"
+	"crypto/hkdf"
+	"crypto/rand"
+	"crypto/sha256"
+	"crypto/x509"
+	"encoding/base64"
+	"encoding/pem"
+	"errors"
+	"fmt"
+)
+
+// SealedBox is a value sealed to one recipient.
+type SealedBox struct {
+	V   int    `json:"v"`
+	Eph string `json:"eph"`
+	IV  string `json:"iv"`
+	Tag string `json:"tag"`
+	Ct  string `json:"ct"`
+}
+
+// KeyPair is a recipient's keypair as the two PEM strings it is kept and sent as.
+type KeyPair struct {
+	PublicKey  string `json:"publicKey"`
+	PrivateKey string `json:"privateKey"`
+}
+
+const sealInfo = "novox-mesh sealed box v1"
+
+// GenerateKeyPair makes an X25519 keypair, PEM-encoded as the agent module's are.
+func GenerateKeyPair() (KeyPair, error) {
+	priv, err := ecdh.X25519().GenerateKey(rand.Reader)
+	if err != nil {
+		return KeyPair{}, err
+	}
+	pubDER, err := x509.MarshalPKIXPublicKey(priv.PublicKey())
+	if err != nil {
+		return KeyPair{}, err
+	}
+	privDER, err := x509.MarshalPKCS8PrivateKey(priv)
+	if err != nil {
+		return KeyPair{}, err
+	}
+	return KeyPair{
+		PublicKey:  string(pem.EncodeToMemory(&pem.Block{Type: "PUBLIC KEY", Bytes: pubDER})),
+		PrivateKey: string(pem.EncodeToMemory(&pem.Block{Type: "PRIVATE KEY", Bytes: privDER})),
+	}, nil
+}
+
+func publicFromPEM(p string) (*ecdh.PublicKey, error) {
+	block, _ := pem.Decode([]byte(p))
+	if block == nil {
+		return nil, errors.New("not a PEM public key")
+	}
+	k, err := x509.ParsePKIXPublicKey(block.Bytes)
+	if err != nil {
+		return nil, err
+	}
+	pub, ok := k.(*ecdh.PublicKey)
+	if !ok || pub.Curve() != ecdh.X25519() {
+		return nil, errors.New("not an X25519 public key")
+	}
+	return pub, nil
+}
+
+func privateFromPEM(p string) (*ecdh.PrivateKey, error) {
+	block, _ := pem.Decode([]byte(p))
+	if block == nil {
+		return nil, errors.New("not a PEM private key")
+	}
+	k, err := x509.ParsePKCS8PrivateKey(block.Bytes)
+	if err != nil {
+		return nil, err
+	}
+	priv, ok := k.(*ecdh.PrivateKey)
+	if !ok || priv.Curve() != ecdh.X25519() {
+		return nil, errors.New("not an X25519 private key")
+	}
+	return priv, nil
+}
+
+func boxKey(secret, ephDER, recipientRaw []byte) ([]byte, error) {
+	salt := append(append([]byte{}, ephDER...), recipientRaw...)
+	return hkdf.Key(sha256.New, secret, salt, sealInfo, 32)
+}
+
+// Seal seals plaintext to the recipient's public key.
+func Seal(plaintext, recipientPEM string) (SealedBox, error) {
+	recipient, err := publicFromPEM(recipientPEM)
+	if err != nil {
+		return SealedBox{}, err
+	}
+	eph, err := ecdh.X25519().GenerateKey(rand.Reader)
+	if err != nil {
+		return SealedBox{}, err
+	}
+	secret, err := eph.ECDH(recipient)
+	if err != nil {
+		return SealedBox{}, err
+	}
+	ephDER, err := x509.MarshalPKIXPublicKey(eph.PublicKey())
+	if err != nil {
+		return SealedBox{}, err
+	}
+	key, err := boxKey(secret, ephDER, recipient.Bytes())
+	if err != nil {
+		return SealedBox{}, err
+	}
+	gcm, err := newGCM(key)
+	if err != nil {
+		return SealedBox{}, err
+	}
+	iv := make([]byte, 12)
+	if _, err := rand.Read(iv); err != nil {
+		return SealedBox{}, err
+	}
+	out := gcm.Seal(nil, iv, []byte(plaintext), nil)
+	ct, tag := out[:len(out)-gcm.Overhead()], out[len(out)-gcm.Overhead():]
+	b64 := base64.StdEncoding.EncodeToString
+	return SealedBox{V: 1, Eph: b64(ephDER), IV: b64(iv), Tag: b64(tag), Ct: b64(ct)}, nil
+}
+
+// Open opens a box with the recipient's private key; it fails for a box to another key or one tampered with.
+func Open(box SealedBox, privatePEM string) (string, error) {
+	if box.V != 1 {
+		return "", errors.New("not a sealed box this module can open")
+	}
+	priv, err := privateFromPEM(privatePEM)
+	if err != nil {
+		return "", err
+	}
+	d := base64.StdEncoding.DecodeString
+	ephDER, err := d(box.Eph)
+	if err != nil {
+		return "", fmt.Errorf("the box's eph: %w", err)
+	}
+	ephKey, err := x509.ParsePKIXPublicKey(ephDER)
+	if err != nil {
+		return "", err
+	}
+	eph, ok := ephKey.(*ecdh.PublicKey)
+	if !ok {
+		return "", errors.New("the box's eph is not an X25519 key")
+	}
+	secret, err := priv.ECDH(eph)
+	if err != nil {
+		return "", err
+	}
+	key, err := boxKey(secret, ephDER, priv.PublicKey().Bytes())
+	if err != nil {
+		return "", err
+	}
+	iv, err1 := d(box.IV)
+	tag, err2 := d(box.Tag)
+	ct, err3 := d(box.Ct)
+	if err := errors.Join(err1, err2, err3); err != nil {
+		return "", err
+	}
+	gcm, err := newGCM(key)
+	if err != nil {
+		return "", err
+	}
+	plain, err := gcm.Open(nil, iv, append(ct, tag...), nil)
+	if err != nil {
+		return "", errors.New("the box does not open with this key")
+	}
+	return string(plain), nil
+}
+
+func newGCM(key []byte) (cipher.AEAD, error) {
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return nil, err
+	}
+	return cipher.NewGCM(block)
+}

modules/claude-code/cmd/claude-code/testdata/rendered-by-typescript.json

@@ -0,0 +1,42 @@
+{
+  "facts": {
+    "node": "workstation",
+    "console": "http://127.0.0.1:4270/mcp"
+  },
+  "settings": {
+    "role": "the laptop",
+    "mcp_servers": {
+      "search": {
+        "type": "http",
+        "url": "https://s.example/mcp"
+      },
+      "docs": {
+        "type": "stdio",
+        "command": "docs-mcp",
+        "args": [
+          "--x"
+        ]
+      }
+    }
+  },
+  "registered": {
+    "anton": {
+      "type": "stdio",
+      "command": "node",
+      "args": [
+        "/a/b.js"
+      ],
+      "env": {}
+    }
+  },
+  "withKey": {
+    "managed-mcp.json": "{\n  \"mcpServers\": {\n    \"anton\": {\n      \"type\": \"stdio\",\n      \"command\": \"node\",\n      \"args\": [\n        \"/a/b.js\"\n      ],\n      \"env\": {}\n    },\n    \"docs\": {\n      \"type\": \"stdio\",\n      \"command\": \"docs-mcp\",\n      \"args\": [\n        \"--x\"\n      ]\n    },\n    \"mesh\": {\n      \"type\": \"http\",\n      \"url\": \"http://127.0.0.1:4270/mcp\"\n    },\n    \"search\": {\n      \"type\": \"http\",\n      \"url\": \"https://s.example/mcp\"\n    }\n  }\n}\n",
+    "managed-settings.json": "{\n  \"attribution\": {\n    \"commit\": \"\",\n    \"pr\": \"\"\n  },\n  \"allowAllClaudeAiMcps\": true,\n  \"apiKeyHelper\": \"/state/api-key-helper\"\n}\n",
+    "CLAUDE.md": "# This machine is a node of a Novox mesh\n\nWritten by the mesh's `claude-code` module. Edit the module's settings or the catalogue, never this file:\nit is rewritten whenever the module renders.\n\n## Who this node is\n\n- **Node:** `workstation`\n- **Role:** the laptop\n- The other nodes, their roles and what runs where: ask the controller (`mesh-controller.nodes`,\n  `mesh-controller.node`). Nothing here lists them, because a copy drifts.\n\n## How a session on this mesh works\n\nThe console is the only way to the mesh: the MCP server named `mesh`. It offers five tools, and\neverything else is an address you find and call through them:\n\n- `mesh_search` — words in, matching addresses out. `mesh_describe` — one address's arguments.\n- `mesh_call` — call an address. A seat the mesh holds once is `<seat>.<verb>` (the mesh's own verbs\n  are `mesh-controller.<verb>`: `status`, `plan`, `node`, `assign`, `push`, `settings`);\n  a module on a machine is `<node>/<module>.<tool>`.\n- `mesh_overview` and `mesh_machine` — the mesh's seats and machines, and what one machine runs.\n\n- **Symptom first.** For an error, a failing service or anything unexpected, search the record with the\n  literal text before forming a hypothesis: the records module's `records_search`, then\n  `records_read`.\n- **Ask the mesh before changing it**, and change it through the controller's verbs or the catalogue.\n- **A licence** through the `anthropic-licence-manager` seat's verbs. Never edit the agent's credentials\n  file by hand, never print or ask for a token.\n\n## Hard rules\n\n- A file the mesh manages is changed through the verb or the catalogue that owns it, never on disk. If\n  unsure, `mesh-controller.plan` for the node says what the mesh writes there.\n- Never write to a store's database by hand; schema changes are numbered migrations.\n- Never push to a main branch: a branch, a pull request, and a human approval for every merge.\n- The mesh creates no symlinks, and nobody else does either.\n- A package is declared in a module, never installed by hand.\n\n## Conventions\n\n- Commit messages are concise, in the imperative, about why.\n- Test before pushing: nodes update unattended.\n- The playbooks in the record say how research, decisions, designs, issues and hand-offs are done.\n"
+  },
+  "plain": {
+    "managed-mcp.json": "{\n  \"mcpServers\": {\n    \"mesh\": {\n      \"type\": \"http\",\n      \"url\": \"http://127.0.0.1:4270/mcp\"\n    }\n  }\n}\n",
+    "managed-settings.json": "{\n  \"attribution\": {\n    \"commit\": \"\",\n    \"pr\": \"\"\n  },\n  \"allowAllClaudeAiMcps\": true\n}\n",
+    "CLAUDE.md": "# This machine is a node of a Novox mesh\n\nWritten by the mesh's `claude-code` module. Edit the module's settings or the catalogue, never this file:\nit is rewritten whenever the module renders.\n\n## Who this node is\n\n- **Node:** `workstation`\n- **Role:** not stated — set it in this module's settings for the node\n- The other nodes, their roles and what runs where: ask the controller (`mesh-controller.nodes`,\n  `mesh-controller.node`). Nothing here lists them, because a copy drifts.\n\n## How a session on this mesh works\n\nThe console is the only way to the mesh: the MCP server named `mesh`. It offers five tools, and\neverything else is an address you find and call through them:\n\n- `mesh_search` — words in, matching addresses out. `mesh_describe` — one address's arguments.\n- `mesh_call` — call an address. A seat the mesh holds once is `<seat>.<verb>` (the mesh's own verbs\n  are `mesh-controller.<verb>`: `status`, `plan`, `node`, `assign`, `push`, `settings`);\n  a module on a machine is `<node>/<module>.<tool>`.\n- `mesh_overview` and `mesh_machine` — the mesh's seats and machines, and what one machine runs.\n\n- **Symptom first.** For an error, a failing service or anything unexpected, search the record with the\n  literal text before forming a hypothesis: the records module's `records_search`, then\n  `records_read`.\n- **Ask the mesh before changing it**, and change it through the controller's verbs or the catalogue.\n- **A licence** through the `anthropic-licence-manager` seat's verbs. Never edit the agent's credentials\n  file by hand, never print or ask for a token.\n\n## Hard rules\n\n- A file the mesh manages is changed through the verb or the catalogue that owns it, never on disk. If\n  unsure, `mesh-controller.plan` for the node says what the mesh writes there.\n- Never write to a store's database by hand; schema changes are numbered migrations.\n- Never push to a main branch: a branch, a pull request, and a human approval for every merge.\n- The mesh creates no symlinks, and nobody else does either.\n- A package is declared in a module, never installed by hand.\n\n## Conventions\n\n- Commit messages are concise, in the imperative, about why.\n- Test before pushing: nodes update unattended.\n- The playbooks in the record say how research, decisions, designs, issues and hand-offs are done.\n"
+  }
+}

modules/claude-code/go.mod

@@ -0,0 +1,5 @@
+module claude-code
+
+go 1.25.0
+
+require git.novox.be/novox/mesh-sdk/go v0.1.7

modules/claude-code/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/claude-code/module.json

@@ -0,0 +1,95 @@
+{
+  "module": "claude-code",
+  "version": "1",
+  "slug": "agent",
+  "capabilities": [
+    "package-manager"
+  ],
+  "requires": [
+    "mcp-endpoint"
+  ],
+  "binds": {
+    "mcp-endpoint": "${dir:state}/mcp-endpoint.json"
+  },
+  "state": [
+    "servers",
+    "holdings"
+  ],
+  "reads": [
+    "claude-licence-manager.bindings"
+  ],
+  "tools": [
+    "claude_code_status",
+    "claude_code_render",
+    "claude_code_pull",
+    "claude_code_grant",
+    "claude_code_add_api_key",
+    "claude_code_mcp_list",
+    "claude_code_mcp_register",
+    "claude_code_mcp_unregister"
+  ],
+  "resources": [
+    {
+      "id": "package",
+      "type": "package",
+      "package": "claude-code"
+    },
+    {
+      "id": "managed",
+      "type": "directory",
+      "path": "/etc/claude-code",
+      "mode": "0755"
+    },
+    {
+      "id": "agent-home",
+      "type": "directory",
+      "path": "${machine:account-home}/.claude",
+      "mode": "0700",
+      "owner": "${machine:account}"
+    },
+    {
+      "id": "state",
+      "type": "directory",
+      "mode": "0700",
+      "owner": "${machine:account}",
+      "place": "."
+    },
+    {
+      "id": "facts",
+      "type": "file",
+      "path": "${dir:state}/facts.json",
+      "mode": "0600",
+      "owner": "${machine:account}",
+      "content": "{\n  \"node\": \"${machine:name}\",\n  \"console\": \"http://127.0.0.1:${bound:mcp-endpoint:port}/mcp\"\n}\n"
+    },
+    {
+      "id": "settings",
+      "type": "file",
+      "path": "${dir:state}/settings.json",
+      "mode": "0600",
+      "owner": "${machine:account}",
+      "merge": "json",
+      "content": "{\n  \"role\": \"\",\n  \"mcp_servers\": {}\n}\n"
+    }
+  ],
+  "build": {
+    "artifacts": [
+      {
+        "name": "tools",
+        "kind": "bundle",
+        "language": "go",
+        "system": "arch",
+        "from": "cmd/claude-code",
+        "binary": "claude-code",
+        "loads": [
+          "claude-code"
+        ],
+        "env": {
+          "MESH_CLAUDE_CODE_STATE": "${dir:state}",
+          "MESH_CLAUDE_CODE_FACTS": "${dir:state}/facts.json",
+          "MESH_CLAUDE_CODE_SETTINGS": "${dir:state}/settings.json"
+        }
+      }
+    ]
+  }
+}

modules/claude-licence-manager/README.md

@@ -0,0 +1,55 @@
+# claude-licence-manager
+
+Holds the `anthropic-licence-manager` seat: every Anthropic licence the mesh has, kept alive by one
+rotation source, and handed to each consumer sealed (novox/hq ADR 0183, ADR 0206, design 39).
+
+## How a licence comes to exist
+
+Nothing is configured. Every node running `claude-code` reports what it holds as that module's
+`holdings` state — the account, fingerprints and expiries, never a token. This module reads every report
+when it starts and watches them:
+
+1. A report with a refresh token it does not hold is a **candidate**.
+2. It asks that node's `claude_code_grant`, giving its public key, and receives the grant sealed to it.
+3. **It refreshes it.** If the vendor exchanges the token, the grant is this module's — encrypted at rest
+   with the key the vault made for it — and from then on it is the only refresher. If not, the candidate
+   is recorded dead and nothing is adopted.
+4. Several nodes logged in to one account: newest login first; the rest are never exchanged.
+5. A node reporting that account and bound to nothing is bound to it.
+
+Each node is then handed an access token only, so the agent there never refreshes, and a refresh token
+appearing on a node later can only be a person's login — which wins if it refreshes.
+
+An API key enters through `adopt`, from a file on this module's node.
+
+## What each consumer holds
+
+This module's `bindings` state: one key per consumer (a node's name) with the licence, its kind and a
+generation that grows with every rotation and switch. `claude-code` watches its own key and, on a newer
+generation, asks `current` with its public key.
+
+## The seat's verbs
+
+`licences`, `bindings`, `bind`, `switch`, `release`, `refresh`, `usage`, `adopt`, `current` — through
+the console as `anthropic-licence-manager.<verb>`. No answer carries a token.
+
+## Settings
+
+`settings.json` in the state directory: `cadence_minutes` (240), `floor_minutes` (60),
+`failures_to_notify` (3), `cooldown_hours` (24), `refresh_warn_days` (3).
+
+## Events
+
+`licence.adopted`, `licence.refused`, `licence.failing`, `usage.read` — none carries a secret.
+
+## Code and tests
+
+Go, one binary (`cmd/claude-licence-manager`): the seat's verbs and the daemon in one launched bundle,
+`prepare` as the run-once preparation step. The sealed box is `claude-code`'s own format, byte for byte —
+the two modules carry the same `seal.go` — and a test opens one sealed by the TypeScript agent module the
+Go one replaced, so the format is the one already on the machines.
+
+    go test ./...
+    # the store against a real postgres:
+    docker run -d --rm --name licmgr-pg -e POSTGRES_PASSWORD=t -p 15498:5432 postgres:16-alpine
+    MESH_TEST_POSTGRES=postgres://postgres:t@127.0.0.1:15498/postgres go test ./...

modules/claude-licence-manager/cmd/claude-licence-manager/crypt.go

@@ -0,0 +1,64 @@
+package main
+
+// The grants at rest (novox/hq ADR 0183): encrypted with a key the vault made for this module, so the
+// store holds ciphertext and only this module, reading its own secret, can open a row. AES-256-GCM, the
+// key derived from the vault's secret by SHA-256 so a secret of any length serves.
+
+import (
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/base64"
+	"errors"
+	"os"
+	"strings"
+)
+
+// Crypt seals and opens what the store keeps.
+type Crypt struct{ key []byte }
+
+// NewCrypt is the store's cipher from the vault's secret.
+func NewCrypt(secret string) (*Crypt, error) {
+	secret = strings.TrimSpace(secret)
+	if secret == "" {
+		return nil, errors.New("the key the grants are encrypted with is empty: the vault has not delivered it yet")
+	}
+	sum := sha256.Sum256([]byte(secret))
+	return &Crypt{key: sum[:]}, nil
+}
+
+// CryptFromFile reads the vault's secret from the file the mesh delivered it to.
+func CryptFromFile(path string) (*Crypt, error) {
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return nil, err
+	}
+	return NewCrypt(string(raw))
+}
+
+// Seal encrypts a plaintext as `v1.<iv>.<ciphertext and tag>`.
+func (c *Crypt) Seal(plaintext string) string {
+	gcm, _ := newGCM(c.key)
+	iv := make([]byte, 12)
+	_, _ = rand.Read(iv)
+	b64 := base64.StdEncoding.EncodeToString
+	return "v1." + b64(iv) + "." + b64(gcm.Seal(nil, iv, []byte(plaintext), nil))
+}
+
+// Open decrypts what Seal made with the same key.
+func (c *Crypt) Open(sealed string) (string, error) {
+	parts := strings.Split(sealed, ".")
+	if len(parts) != 3 || parts[0] != "v1" {
+		return "", errors.New("not a grant this module sealed")
+	}
+	iv, err1 := base64.StdEncoding.DecodeString(parts[1])
+	ct, err2 := base64.StdEncoding.DecodeString(parts[2])
+	if err := errors.Join(err1, err2); err != nil {
+		return "", err
+	}
+	gcm, _ := newGCM(c.key)
+	plain, err := gcm.Open(nil, iv, ct, nil)
+	if err != nil {
+		return "", errors.New("the grant does not open with this module's key")
+	}
+	return string(plain), nil
+}

modules/claude-licence-manager/cmd/claude-licence-manager/main.go

@@ -0,0 +1,367 @@
+// claude-licence-manager (novox/hq ADR 0183, ADR 0206, design 39): one binary, launched by the control
+// node's runtime and speaking MCP to it over stdio through the Go SDK (ADR 0193, ADR 0198). It serves the
+// `anthropic-licence-manager` seat's verbs and, beside them, runs long: it watches what every node reports
+// holding and adopts a login it does not hold, keeps every grant alive under a lease, and reads usage.
+//
+// `claude-licence-manager prepare` is the preparation step (ADR 0135): the host runs it once before the
+// version that needs it, with the module's words and no bus, and it brings the store's schema to shape.
+//
+// stdout is the MCP channel; everything this module says, it says on stderr.
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"sync"
+	"time"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+// Seat is the role this module holds.
+const Seat = "anthropic-licence-manager"
+
+func say(format string, args ...any) {
+	fmt.Fprintf(os.Stderr, "[claude-licence-manager] "+format+"\n", args...)
+}
+
+func main() {
+	if len(os.Args) > 1 && os.Args[1] == "prepare" {
+		if err := prepare(); err != nil {
+			say("preparing the store failed: %v", err)
+			os.Exit(1)
+		}
+		say("the store's schema is what this version needs")
+		return
+	}
+	go daemon()
+	if err := stdio.Serve("", tools()); err != nil {
+		say("%v", err)
+		os.Exit(1)
+	}
+}
+
+func prepare() error {
+	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
+	defer cancel()
+	store, err := PgStoreFromEnv(ctx)
+	if err != nil {
+		return err
+	}
+	defer store.Close()
+	return store.Migrate(ctx)
+}
+
+// ---- what the binary is handed -----------------------------------------------------------------------
+
+var (
+	built   *Manager
+	buildMu sync.Mutex
+)
+
+// manager builds the rules' dependencies once, from the module's words (ADR 0192): file paths, never
+// values. A failure is said and tried again on the next call, so a database that arrives late is not fatal.
+func manager() (*Manager, error) {
+	buildMu.Lock()
+	defer buildMu.Unlock()
+	if built != nil {
+		return built, nil
+	}
+	dir, keyFile := os.Getenv("MESH_LICENCE_STATE"), os.Getenv("MESH_LICENCE_KEY_FILE")
+	if dir == "" || keyFile == "" {
+		return nil, errors.New("MESH_LICENCE_STATE and MESH_LICENCE_KEY_FILE are not set: the mesh renders them for this module")
+	}
+	crypt, err := CryptFromFile(keyFile)
+	if err != nil {
+		return nil, err
+	}
+	keys, err := keypair(dir)
+	if err != nil {
+		return nil, err
+	}
+	store, err := PgStoreFromEnv(context.Background())
+	if err != nil {
+		return nil, err
+	}
+	node, _ := os.Hostname()
+	if n := os.Getenv("MESH_NODE"); n != "" {
+		node = n
+	}
+	bindings := stdio.State("bindings")
+	built = &Manager{
+		Store:  store,
+		Vendor: LiveVendor(),
+		Crypt:  crypt,
+		Keys:   keys,
+		AskGrant: func(_ context.Context, node, publicKey string) (GrantAnswer, error) {
+			var a GrantAnswer
+			raw, err := stdio.Ask("claude-code.claude_code_grant@"+node, map[string]any{"public_key": publicKey})
+			if err != nil {
+				return a, err
+			}
+			return a, json.Unmarshal(raw, &a)
+		},
+		PutBinding: func(_ context.Context, consumer string, b BindingState) error {
+			_, err := bindings.Put(consumer, b)
+			return err
+		},
+		DeleteBinding: func(_ context.Context, consumer string) error { return bindings.Delete(consumer) },
+		Emit:          func(event string, body map[string]any) error { return stdio.Emit(event, body) },
+		Now:           time.Now,
+		Log:           say,
+		Holder:        fmt.Sprintf("%s:%d", node, os.Getpid()),
+		Settings:      SettingsFrom(os.Getenv("MESH_LICENCE_SETTINGS")),
+	}
+	return built, nil
+}
+
+// keypair is this module's own, made once in its state directory; the private half never leaves it.
+// Written whole, then linked into place, so a second process reads the first's key and never half of it.
+func keypair(dir string) (KeyPair, error) {
+	file := filepath.Join(dir, "manager-key.json")
+	if _, err := os.Stat(file); errors.Is(err, os.ErrNotExist) {
+		k, err := GenerateKeyPair()
+		if err != nil {
+			return KeyPair{}, err
+		}
+		raw, _ := json.Marshal(k)
+		tmp := filepath.Join(dir, fmt.Sprintf(".manager-key.%d.json", os.Getpid()))
+		if err := os.WriteFile(tmp, raw, 0o600); err != nil {
+			return KeyPair{}, err
+		}
+		_ = os.Link(tmp, file) // fails when another made it first, which is right
+		_ = os.Remove(tmp)
+	}
+	raw, err := os.ReadFile(file)
+	if err != nil {
+		return KeyPair{}, err
+	}
+	var k KeyPair
+	return k, json.Unmarshal(raw, &k)
+}
+
+// ---- the long-running half ---------------------------------------------------------------------------
+
+func daemon() {
+	var mu sync.Mutex
+	reports := map[string]Holdings{}
+	var passing sync.Mutex
+	pass := func() {
+		passing.Lock() // one pass at a time: each account is leased, and a pass is cheap
+		defer passing.Unlock()
+		m, err := manager()
+		if err != nil {
+			say("not ready: %v", err)
+			return
+		}
+		mu.Lock()
+		all := make([]Holdings, 0, len(reports))
+		for _, r := range reports {
+			all = append(all, r)
+		}
+		mu.Unlock()
+		sort.Slice(all, func(i, j int) bool { return all[i].Node < all[j].Node })
+		adopted, err := m.Consider(context.Background(), all)
+		if err != nil {
+			say("considering the reports failed: %v", err)
+		}
+		if len(adopted) > 0 {
+			say("adopted %s", strings.Join(adopted, ", "))
+		}
+	}
+
+	// What every node holds (ADR 0206): the whole current set, then each change. Asked again until it
+	// answers — the channel to the runtime opens as the bundle starts, and the agent module's state may
+	// arrive after this one.
+	go func() {
+		waits := []time.Duration{2 * time.Second, 5 * time.Second, 10 * time.Second, 30 * time.Second}
+		for attempt := 0; ; attempt++ {
+			err := stdio.State("claude-code.holdings").Watch("", func(c stdio.StateChange) error {
+				mu.Lock()
+				if c.Op == "put" {
+					var h Holdings
+					if json.Unmarshal(c.Value, &h) == nil {
+						reports[c.Key] = h
+					}
+				} else {
+					delete(reports, c.Key)
+				}
+				mu.Unlock()
+				// During the current values the pass waits for the whole set: newest login first needs all.
+				if !c.Current {
+					go pass()
+				}
+				return nil
+			})
+			if err == nil {
+				mu.Lock()
+				n := len(reports)
+				mu.Unlock()
+				say("watching what %d node(s) hold", n)
+				pass()
+				return
+			}
+			pause := time.Minute
+			if attempt < len(waits) {
+				pause = waits[attempt]
+			}
+			say("what the nodes hold cannot be watched yet (%v); asking again in %s", err, pause)
+			time.Sleep(pause)
+		}
+	}()
+
+	refresh := time.NewTicker(time.Minute)
+	usage := time.NewTicker(5 * time.Minute)
+	for {
+		select {
+		case <-refresh.C:
+			if m, err := manager(); err == nil {
+				out, err := m.RotateDue(context.Background())
+				for _, r := range out {
+					b, _ := json.Marshal(r)
+					say("%s", b)
+				}
+				if err != nil {
+					say("refreshing failed: %v", err)
+				}
+			}
+			pass() // a login whose node did not answer last time is asked again
+		case <-usage.C:
+			if m, err := manager(); err == nil {
+				if err := m.ReadUsage(context.Background()); err != nil {
+					say("reading usage failed: %v", err)
+				}
+			}
+		}
+	}
+}
+
+// ---- the seat's verbs --------------------------------------------------------------------------------
+
+func text(a map[string]any, k string) (string, error) {
+	v, _ := a[k].(string)
+	if strings.TrimSpace(v) == "" {
+		return "", fmt.Errorf("%s is required", k)
+	}
+	return strings.TrimSpace(v), nil
+}
+
+// verb is one of the seat's verbs: listed as `<seat>.<verb>`, so the runtime serves it on the seat's subject.
+func verb(name, description string, input map[string]any, run func(ctx context.Context, m *Manager, a map[string]any) (any, error)) stdio.Tool {
+	return stdio.Tool{Name: Seat + "." + name, Description: description, Input: input,
+		Run: func(a map[string]any) (any, error) {
+			m, err := manager()
+			if err != nil {
+				return nil, err
+			}
+			return run(context.Background(), m, a)
+		}}
+}
+
+func str(description string) map[string]any {
+	return map[string]any{"type": "string", "description": description}
+}
+
+func two(a map[string]any, k1, k2 string) (string, string, error) {
+	v1, err1 := text(a, k1)
+	v2, err2 := text(a, k2)
+	return v1, v2, errors.Join(err1, err2)
+}
+
+func tools() []stdio.Tool {
+	consumer := str("the node's name")
+	return []stdio.Tool{
+		verb("licences", "Every licence the manager holds — account, kind, when its token and its refresh token expire, failures in a row, which consumers are bound to it. Never a token.",
+			nil, func(ctx context.Context, m *Manager, _ map[string]any) (any, error) { return m.Licences(ctx) }),
+		verb("bindings", "Which licence each consumer (a node's agent, by the node's name) is bound to, and the generation it was last given.",
+			nil, func(ctx context.Context, m *Manager, _ map[string]any) (any, error) { return m.Store.Bindings(ctx) }),
+		verb("bind", "Bind a consumer — a node's agent, by the node's name — to a licence. Its node fetches the licence's token at once.",
+			map[string]any{"consumer": consumer, "licence": str("a licence, as `licences` names it")},
+			func(ctx context.Context, m *Manager, a map[string]any) (any, error) {
+				c, l, err := two(a, "consumer", "licence")
+				if err != nil {
+					return nil, err
+				}
+				return m.Bind(ctx, c, l, "bind")
+			}),
+		verb("switch", "Move a consumer to another licence. Its node fetches the new licence's token at once and points the agent's account at it. A login on a node does this by itself (ADR 0209); this is for moving one without a login, or back.",
+			map[string]any{"consumer": consumer, "licence": str("the licence to move to")},
+			func(ctx context.Context, m *Manager, a map[string]any) (any, error) {
+				c, l, err := two(a, "consumer", "licence")
+				if err != nil {
+					return nil, err
+				}
+				return m.Bind(ctx, c, l, "switch")
+			}),
+		verb("release", "Unbind a consumer. Its node keeps its last token, which expires within hours.",
+			map[string]any{"consumer": consumer},
+			func(ctx context.Context, m *Manager, a map[string]any) (any, error) {
+				c, err := text(a, "consumer")
+				if err != nil {
+					return nil, err
+				}
+				return m.Release(ctx, c, "release")
+			}),
+		verb("refresh", "Refresh a licence now, or every due licence when none is named; under each licence's lease, so it never races the daemon. Answers the outcome, never a token.",
+			map[string]any{"licence": str("a licence; absent for every due one")},
+			func(ctx context.Context, m *Manager, a map[string]any) (any, error) {
+				if l, _ := a["licence"].(string); l != "" {
+					return m.Rotate(ctx, l, true)
+				}
+				return m.RotateDue(ctx)
+			}),
+		verb("usage", "Usage readings, the latest first, for every licence or one.",
+			map[string]any{"licence": str("a licence; absent for all"), "limit": map[string]any{"type": "number", "description": "how many readings (default 20)"}},
+			func(ctx context.Context, m *Manager, a map[string]any) (any, error) {
+				l, _ := a["licence"].(string)
+				limit := 20
+				if v, ok := a["limit"].(float64); ok && v > 0 {
+					limit = int(v)
+				}
+				return m.Store.Usage(ctx, l, limit)
+			}),
+		verb("adopt", "Adopt an API key — never as an argument: from a file on the manager's node (`file`), or sealed to the manager's `public-key` by a node's claude-code (`sealed`; its `claude_code_add_api_key` does this). Subscriptions are adopted from the nodes' logins by themselves.",
+			map[string]any{"name": str("the licence's name"), "file": str("a file on the manager's node holding the key"),
+				"sealed": map[string]any{"type": "object", "description": "the key sealed to the manager's public key"},
+				"from":   str("which node it came from, for the audit")},
+			func(ctx context.Context, m *Manager, a map[string]any) (any, error) {
+				n, err := text(a, "name")
+				if err != nil {
+					return nil, err
+				}
+				if raw, ok := a["sealed"]; ok && raw != nil {
+					b, _ := json.Marshal(raw)
+					var box SealedBox
+					if err := json.Unmarshal(b, &box); err != nil {
+						return nil, err
+					}
+					from, _ := a["from"].(string)
+					return m.AdoptSealedKey(ctx, n, box, "a node: "+from)
+				}
+				f, err := text(a, "file")
+				if err != nil {
+					return nil, errors.New("adopt takes a `file` on the manager's node, or a `sealed` key")
+				}
+				return m.AdoptKey(ctx, n, f)
+			}),
+		verb("public-key", "The manager's public key, PEM: what a node seals an API key or a login to before handing it over.",
+			nil, func(_ context.Context, m *Manager, _ map[string]any) (any, error) {
+				return map[string]any{"public_key": m.Keys.PublicKey}, nil
+			}),
+		verb("current", "For a consumer's agent module (ADR 0206): its token, sealed to the public key it sends, with the licence, kind and generation. Null when it is bound to nothing.",
+			map[string]any{"consumer": consumer, "public_key": str("the consumer's public key, PEM")},
+			func(ctx context.Context, m *Manager, a map[string]any) (any, error) {
+				c, k, err := two(a, "consumer", "public_key")
+				if err != nil {
+					return nil, err
+				}
+				return m.Current(ctx, c, k)
+			}),
+	}
+}

modules/claude-licence-manager/cmd/claude-licence-manager/manager.go

@@ -0,0 +1,708 @@
+package main
+
+// The Anthropic licence manager's rules (novox/hq ADR 0183, ADR 0206, design 39), written against what it
+// is handed — a store, the vendor, a way to ask a node, its own state, a way to emit — so every rule is
+// tested without a bus, a database or the vendor.
+//
+//   - A licence is an account, learned from what the nodes report (`holdings`, the agent module's state).
+//     A report with a refresh token the manager does not hold is a candidate.
+//   - The secret is asked for, sealed to this module's key, never published.
+//   - Adopting is refreshing: newest login first, once per account; a failure adopts nothing.
+//   - What each consumer should hold is this module's `bindings` state, with a generation that grows with
+//     every rotation and switch; the consumer fetches its token by asking `current`.
+//   - One rotation source: every exchange with the vendor runs under a lease.
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"regexp"
+	"sort"
+	"strings"
+	"time"
+)
+
+// Fingerprint names a token without being one: the agent module's own fingerprint, so the two compare.
+func Fingerprint(s string) string {
+	sum := sha256.Sum256([]byte(s))
+	return "sha256:" + hex.EncodeToString(sum[:])[:16]
+}
+
+// Identity is the account a grant belongs to, as the agent's own state file names it.
+type Identity struct {
+	AccountUUID      string `json:"accountUuid"`
+	EmailAddress     string `json:"emailAddress,omitempty"`
+	OrganizationUUID string `json:"organizationUuid,omitempty"`
+}
+
+// Holdings is one node's report, as the agent module writes it to its `holdings` state (ADR 0206).
+type Holdings struct {
+	Node     string    `json:"node"`
+	Identity *Identity `json:"identity"`
+	Kind     string    `json:"kind"`
+	Refresh  struct {
+		Present     bool   `json:"present"`
+		Fingerprint string `json:"fingerprint"`
+	} `json:"refresh"`
+	ChangedAt string `json:"changedAt"`
+}
+
+// BindingState is what `bindings` holds for one consumer: no secret, only what it should hold and which
+// generation.
+type BindingState struct {
+	Licence    string `json:"licence"`
+	Kind       string `json:"kind"`
+	Generation int64  `json:"generation"`
+}
+
+// Settings are the manager's own, declared with defaults (design 39 §8).
+type Settings struct {
+	Cadence          time.Duration // rotate a grant once older than this
+	Floor            time.Duration // refresh in any case with less than this left
+	FailuresToNotify int
+	Cooldown         time.Duration // at most one notification per licence in this window
+	RefreshWarn      time.Duration // warn this long before a refresh token itself expires
+}
+
+// Defaults are the settings a fresh mesh runs with.
+var Defaults = Settings{Cadence: 4 * time.Hour, Floor: time.Hour, FailuresToNotify: 3, Cooldown: 24 * time.Hour, RefreshWarn: 72 * time.Hour}
+
+// SettingsFrom reads the settings file, keeping a default for anything absent or not positive.
+func SettingsFrom(path string) Settings {
+	s := Defaults
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return s
+	}
+	var f map[string]float64
+	if json.Unmarshal(raw, &f) != nil {
+		return s
+	}
+	set := func(k string, unit time.Duration, into *time.Duration) {
+		if v := f[k]; v > 0 {
+			*into = time.Duration(v * float64(unit))
+		}
+	}
+	set("cadence_minutes", time.Minute, &s.Cadence)
+	set("floor_minutes", time.Minute, &s.Floor)
+	set("cooldown_hours", time.Hour, &s.Cooldown)
+	if v := f["refresh_warn_days"]; v > 0 {
+		s.RefreshWarn = time.Duration(v * float64(24*time.Hour))
+	}
+	if v := f["failures_to_notify"]; v > 0 {
+		s.FailuresToNotify = int(v)
+	}
+	return s
+}
+
+// GrantAnswer is what a node's `claude_code_grant` answers: a login sealed to the key given, or nothing.
+type GrantAnswer struct {
+	Sealed      *SealedBox `json:"sealed"`
+	Identity    *Identity  `json:"identity"`
+	Fingerprint string     `json:"fingerprint"`
+}
+
+// Manager is the rules and what they are handed.
+type Manager struct {
+	Store  Store
+	Vendor Vendor
+	Crypt  *Crypt
+	Keys   KeyPair
+	// AskGrant asks a node's agent module for the grant a login left there, sealed to publicKey. An error
+	// is the node not answering; a nil Sealed is no login waiting.
+	AskGrant func(ctx context.Context, node, publicKey string) (GrantAnswer, error)
+	// PutBinding and DeleteBinding are this module's `bindings` state.
+	PutBinding    func(ctx context.Context, consumer string, b BindingState) error
+	DeleteBinding func(ctx context.Context, consumer string) error
+	Emit          func(event string, body map[string]any) error
+	Now           func() time.Time
+	Log           func(format string, args ...any)
+	// Holder names this process in a lease, so a second run is told apart.
+	Holder   string
+	Settings Settings
+}
+
+const leaseFor = 2 * time.Minute
+
+// NameFor is a licence's name: the account's address where it has one, else its id.
+func NameFor(id Identity) string {
+	if e := strings.TrimSpace(id.EmailAddress); e != "" {
+		return e
+	}
+	return id.AccountUUID
+}
+
+// ---- learning licences from what the nodes hold ------------------------------------------------------
+
+// Candidate is a report the manager should try.
+type Candidate struct {
+	Node        string
+	Identity    Identity
+	Fingerprint string
+	ChangedAt   int64
+}
+
+// CandidatesIn is the candidates in a set of reports by account, newest login first (ADR 0206 §2, §4). A
+// report without an identity is not one: a grant is filed under its account or not at all.
+func (m *Manager) CandidatesIn(ctx context.Context, reports []Holdings) (map[string][]Candidate, error) {
+	out := map[string][]Candidate{}
+	for _, r := range reports {
+		if !r.Refresh.Present || r.Refresh.Fingerprint == "" || r.Identity == nil || r.Identity.AccountUUID == "" {
+			continue
+		}
+		settled, err := m.Store.Outcome(ctx, r.Refresh.Fingerprint)
+		if err != nil {
+			return nil, err
+		}
+		if settled != "" {
+			continue // adopted, dead, skipped, refused or gone: settled once
+		}
+		held, err := m.Store.LicenceForAccount(ctx, r.Identity.AccountUUID)
+		if err != nil {
+			return nil, err
+		}
+		if held != nil && held.RefreshFingerprint == r.Refresh.Fingerprint {
+			continue
+		}
+		var changed int64
+		if t, err := time.Parse(time.RFC3339Nano, r.ChangedAt); err == nil {
+			changed = t.UnixMilli()
+		}
+		// The latest login wins: one no newer than the grant held is not a newer login.
+		if held != nil && changed <= held.AdoptedAt {
+			continue
+		}
+		out[r.Identity.AccountUUID] = append(out[r.Identity.AccountUUID],
+			Candidate{Node: r.Node, Identity: *r.Identity, Fingerprint: r.Refresh.Fingerprint, ChangedAt: changed})
+	}
+	for _, list := range out {
+		sort.SliceStable(list, func(i, j int) bool { return list[i].ChangedAt > list[j].ChangedAt })
+	}
+	return out, nil
+}
+
+// Consider every report (ADR 0206): for each account with candidates, under that account's lease, try them
+// newest first; the first that refreshes is adopted and the rest are settled as skipped without being
+// exchanged. Answers what was adopted.
+func (m *Manager) Consider(ctx context.Context, reports []Holdings) ([]string, error) {
+	byAccount, err := m.CandidatesIn(ctx, reports)
+	if err != nil {
+		return nil, err
+	}
+	accounts := make([]string, 0, len(byAccount))
+	for a := range byAccount {
+		accounts = append(accounts, a)
+	}
+	sort.Strings(accounts)
+	// A node reporting an account the manager already holds, and bound to nothing, is bound to it
+	// (ADR 0206 §7) — whenever its report arrives, not only when the licence is adopted: a node whose own
+	// login is older than the one adopted is never a candidate, and would otherwise never be bound.
+	if err := m.bindReporters(ctx, reports); err != nil {
+		return nil, err
+	}
+	var adopted []string
+	for _, account := range accounts {
+		list := byAccount[account]
+		key := "account:" + account
+		ok, err := m.Store.Lease(ctx, key, m.Holder, leaseFor)
+		if err != nil || !ok {
+			continue
+		}
+		for i, c := range list {
+			name, err := m.adoptOne(ctx, c, reports)
+			if err != nil {
+				m.Log("adopting %s's login failed: %v", c.Node, err)
+				continue
+			}
+			if name != "" {
+				adopted = append(adopted, name)
+				for _, rest := range list[i+1:] {
+					_ = m.Store.RecordOutcome(ctx, rest.Fingerprint, rest.Node, account, Skipped, c.Node+"'s newer login was adopted first")
+				}
+				break
+			}
+		}
+		_ = m.Store.Unlease(ctx, key, m.Holder)
+	}
+	return adopted, nil
+}
+
+// bindReporters binds each reporting node that is bound to nothing to the licence its account already has.
+func (m *Manager) bindReporters(ctx context.Context, reports []Holdings) error {
+	for _, rep := range reports {
+		if rep.Identity == nil || rep.Identity.AccountUUID == "" {
+			continue
+		}
+		if b, err := m.Store.Binding(ctx, rep.Node); err != nil || b != nil {
+			if err != nil {
+				return err
+			}
+			continue
+		}
+		l, err := m.Store.LicenceForAccount(ctx, rep.Identity.AccountUUID)
+		if err != nil {
+			return err
+		}
+		if l == nil {
+			continue
+		}
+		b, err := m.Store.Bind(ctx, rep.Node, l.Name)
+		if err != nil {
+			return err
+		}
+		_ = m.Store.Audit(ctx, "bound", map[string]any{"consumer": rep.Node, "licence": l.Name, "by": "its account's report"})
+		if err := m.PutBinding(ctx, rep.Node, BindingState{Licence: l.Name, Kind: l.Kind, Generation: b.Generation}); err != nil {
+			return err
+		}
+		m.Log("bound %s to %s, the licence its account already has", rep.Node, l.Name)
+	}
+	return nil
+}
+
+func (m *Manager) adoptOne(ctx context.Context, c Candidate, reports []Holdings) (string, error) {
+	answer, err := m.AskGrant(ctx, c.Node, m.Keys.PublicKey)
+	if err != nil {
+		// Not answering is not an answer: asked again on the next pass.
+		m.Log("%s did not hand over its login: %v", c.Node, err)
+		return "", nil
+	}
+	if answer.Sealed == nil {
+		return "", m.Store.RecordOutcome(ctx, c.Fingerprint, c.Node, c.Identity.AccountUUID, Gone, "no login was waiting when asked")
+	}
+	plain, err := Open(*answer.Sealed, m.Keys.PrivateKey)
+	if err != nil {
+		return "", m.Store.RecordOutcome(ctx, c.Fingerprint, c.Node, c.Identity.AccountUUID, Refused, "the grant did not open with this module's key")
+	}
+	var offered FullGrant
+	if err := json.Unmarshal([]byte(plain), &offered); err != nil || offered.RefreshToken == "" {
+		return "", m.Store.RecordOutcome(ctx, c.Fingerprint, c.Node, c.Identity.AccountUUID, Refused, "the grant holds no refresh token")
+	}
+	if Fingerprint(offered.RefreshToken) != c.Fingerprint {
+		m.Log("%s's login changed while it was asked for; waiting for its next report", c.Node)
+		return "", nil
+	}
+
+	// Adopting is refreshing (ADR 0206 §4): the exchange is the check, and from here this module is the
+	// only holder of a live refresh token for the account.
+	r := m.Vendor.Refresh(ctx, offered)
+	if !r.OK {
+		_ = m.Store.RecordOutcome(ctx, c.Fingerprint, c.Node, c.Identity.AccountUUID, Dead, fmt.Sprintf("%d %s", r.Status, r.Reason))
+		_ = m.Store.Audit(ctx, "refused", map[string]any{"node": c.Node, "account": c.Identity.AccountUUID, "status": r.Status, "reason": r.Reason})
+		_ = m.Emit("licence.refused", map[string]any{"node": c.Node, "account": NameFor(c.Identity),
+			"reason": fmt.Sprintf("the login's refresh token did not refresh (%d)", r.Status)})
+		m.Log("%s's login for %s did not refresh: %d %s", c.Node, NameFor(c.Identity), r.Status, r.Reason)
+		return "", nil
+	}
+	// The identity guard, on two sources (ADR 0206 §8).
+	if r.Account != "" && r.Account != c.Identity.AccountUUID {
+		_ = m.Store.RecordOutcome(ctx, c.Fingerprint, c.Node, c.Identity.AccountUUID, Refused,
+			"the node says "+c.Identity.AccountUUID+", the vendor says "+r.Account)
+		_ = m.Store.Audit(ctx, "refused", map[string]any{"node": c.Node, "reported": c.Identity.AccountUUID, "vendor": r.Account})
+		_ = m.Emit("licence.refused", map[string]any{"node": c.Node, "account": NameFor(c.Identity),
+			"reason": "the account the node reported is not the one the vendor answered for"})
+		return "", nil
+	}
+
+	held, err := m.Store.LicenceForAccount(ctx, c.Identity.AccountUUID)
+	if err != nil {
+		return "", err
+	}
+	now := m.Now().UnixMilli()
+	l := Licence{Name: NameFor(c.Identity), Kind: "subscription", AccountUUID: c.Identity.AccountUUID,
+		Email: c.Identity.EmailAddress, OrganizationUUID: c.Identity.OrganizationUUID}
+	if held != nil {
+		l.Name, l.NotifiedAt = held.Name, held.NotifiedAt
+		if l.Email == "" {
+			l.Email = held.Email
+		}
+		if l.OrganizationUUID == "" {
+			l.OrganizationUUID = held.OrganizationUUID
+		}
+	}
+	m.keep(&l, r.Grant)
+	l.AdoptedAt = max(now, c.ChangedAt)
+	if err := m.Store.SaveLicence(ctx, l); err != nil {
+		return "", err
+	}
+	why := "a new licence"
+	if held != nil {
+		why = "a newer login"
+	}
+	_ = m.Store.RecordOutcome(ctx, c.Fingerprint, c.Node, c.Identity.AccountUUID, Adopted, why)
+	_ = m.Store.Audit(ctx, "adopted", map[string]any{"licence": l.Name, "node": c.Node, "account": c.Identity.AccountUUID,
+		"vendorNamedAccount": r.Account != ""})
+
+	// A login moves its node (ADR 0209): the node this login came from is bound to its licence —
+	// switched, if it was bound to another. Then every node reporting this account and bound to nothing.
+	if b, err := m.Store.Binding(ctx, c.Node); err != nil {
+		return "", err
+	} else if b == nil || b.Licence != l.Name {
+		if _, err := m.Store.Bind(ctx, c.Node, l.Name); err != nil {
+			return "", err
+		}
+		from := ""
+		if b != nil {
+			from = b.Licence
+		}
+		_ = m.Store.Audit(ctx, map[bool]string{true: "switched", false: "bound"}[b != nil],
+			map[string]any{"consumer": c.Node, "licence": l.Name, "from": from, "by": "a login there"})
+		if b != nil {
+			m.Log("%s moved from %s to %s: a login there", c.Node, from, l.Name)
+		}
+	}
+	for _, rep := range reports {
+		if rep.Identity == nil || rep.Identity.AccountUUID != c.Identity.AccountUUID {
+			continue
+		}
+		if b, err := m.Store.Binding(ctx, rep.Node); err != nil || b != nil {
+			continue
+		}
+		if _, err := m.Store.Bind(ctx, rep.Node, l.Name); err == nil {
+			_ = m.Store.Audit(ctx, "bound", map[string]any{"consumer": rep.Node, "licence": l.Name, "by": "its login"})
+		}
+	}
+	if err := m.publishAdvance(ctx, l); err != nil {
+		return "", err
+	}
+	_ = m.Emit("licence.adopted", map[string]any{"licence": l.Name, "from": c.Node, "replaced": held != nil})
+	m.Log("adopted %s from %s (%s)", l.Name, c.Node, why)
+	return l.Name, nil
+}
+
+// keep stores a grant on its licence: encrypted, fingerprinted, its expiries, fresh.
+func (m *Manager) keep(l *Licence, g FullGrant) {
+	raw, _ := json.Marshal(g)
+	l.Sealed = m.Crypt.Seal(string(raw))
+	l.RefreshFingerprint = Fingerprint(g.RefreshToken)
+	l.AccessExpiresAt = g.ExpiresAt
+	if g.RefreshTokenExpiresAt != nil {
+		l.RefreshExpiresAt = *g.RefreshTokenExpiresAt
+	}
+	l.Failures = 0
+	l.RotatedAt = m.Now().UnixMilli()
+}
+
+// publishAdvance gives every consumer of a licence a new generation, and tells each in the state.
+func (m *Manager) publishAdvance(ctx context.Context, l Licence) error {
+	bindings, err := m.Store.Advance(ctx, l.Name)
+	if err != nil {
+		return err
+	}
+	for _, b := range bindings {
+		if err := m.PutBinding(ctx, b.Consumer, BindingState{Licence: b.Licence, Kind: l.Kind, Generation: b.Generation}); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// ---- keeping grants alive ----------------------------------------------------------------------------
+
+// Due says whether a licence needs a refresh now: near expiry, or older than the cadence.
+func Due(l Licence, now time.Time, s Settings) bool {
+	if l.Kind != "subscription" || l.Sealed == "" {
+		return false
+	}
+	ms := now.UnixMilli()
+	if l.AccessExpiresAt != 0 && l.AccessExpiresAt-ms < s.Floor.Milliseconds() {
+		return true
+	}
+	return l.RotatedAt == 0 || ms-l.RotatedAt >= s.Cadence.Milliseconds()
+}
+
+// Rotate refreshes one licence under its lease (design 39 §3). A second run started together finds the
+// lease live and does nothing; one started just after finds a fresh grant and is not due. force refreshes
+// whatever the age — the seat's `refresh` verb.
+func (m *Manager) Rotate(ctx context.Context, name string, force bool) (map[string]any, error) {
+	key := "licence:" + name
+	ok, err := m.Store.Lease(ctx, key, m.Holder, leaseFor)
+	if err != nil {
+		return nil, err
+	}
+	if !ok {
+		return map[string]any{"licence": name, "refreshed": false, "reason": "another run holds its lease"}, nil
+	}
+	defer func() { _ = m.Store.Unlease(ctx, key, m.Holder) }()
+	l, err := m.Store.Licence(ctx, name)
+	if err != nil {
+		return nil, err
+	}
+	if l == nil {
+		return map[string]any{"licence": name, "refreshed": false, "reason": "no such licence"}, nil
+	}
+	if l.Kind != "subscription" || l.Sealed == "" {
+		return map[string]any{"licence": name, "refreshed": false, "reason": "an API key does not refresh"}, nil
+	}
+	now := m.Now()
+	if !force && !Due(*l, now, m.Settings) {
+		return map[string]any{"licence": name, "refreshed": false, "reason": "not due"}, nil
+	}
+	plain, err := m.Crypt.Open(l.Sealed)
+	if err != nil {
+		return nil, err
+	}
+	var g FullGrant
+	if err := json.Unmarshal([]byte(plain), &g); err != nil {
+		return nil, err
+	}
+	r := m.Vendor.Refresh(ctx, g)
+	if !r.OK {
+		l.Failures++
+		m.Log("%s did not refresh (%d in a row): %d %s", name, l.Failures, r.Status, r.Reason)
+		_ = m.Store.Audit(ctx, "failed", map[string]any{"licence": name, "status": r.Status, "reason": r.Reason, "failures": l.Failures})
+		m.notify(l, fmt.Sprintf("refresh failed %d time(s) in a row: %d", l.Failures, r.Status), l.Failures >= m.Settings.FailuresToNotify)
+		if err := m.Store.SaveLicence(ctx, *l); err != nil {
+			return nil, err
+		}
+		return map[string]any{"licence": name, "refreshed": false, "reason": fmt.Sprintf("%d %s", r.Status, r.Reason), "failures": l.Failures}, nil
+	}
+	m.keep(l, r.Grant)
+	if l.RefreshExpiresAt != 0 {
+		left := time.Duration(l.RefreshExpiresAt-now.UnixMilli()) * time.Millisecond
+		m.notify(l, fmt.Sprintf("its refresh token expires in %.1f day(s): a person must log in again", left.Hours()/24),
+			left < m.Settings.RefreshWarn)
+	}
+	if err := m.Store.SaveLicence(ctx, *l); err != nil {
+		return nil, err
+	}
+	_ = m.Store.Audit(ctx, "rotated", map[string]any{"licence": name, "expiresAt": l.AccessExpiresAt})
+	if err := m.publishAdvance(ctx, *l); err != nil {
+		return nil, err
+	}
+	return map[string]any{"licence": name, "refreshed": true, "expiresAt": time.UnixMilli(l.AccessExpiresAt).UTC().Format(time.RFC3339)}, nil
+}
+
+// notify emits `licence.failing` at most once per cooldown (design 39 §3); it carries no secret.
+func (m *Manager) notify(l *Licence, why string, when bool) {
+	if !when {
+		return
+	}
+	now := m.Now().UnixMilli()
+	if l.NotifiedAt != 0 && now-l.NotifiedAt < m.Settings.Cooldown.Milliseconds() {
+		return
+	}
+	l.NotifiedAt = now
+	_ = m.Emit("licence.failing", map[string]any{"licence": l.Name, "why": why})
+}
+
+// RotateDue refreshes every licence that is due.
+func (m *Manager) RotateDue(ctx context.Context) ([]map[string]any, error) {
+	all, err := m.Store.Licences(ctx)
+	if err != nil {
+		return nil, err
+	}
+	var out []map[string]any
+	for _, l := range all {
+		if Due(l, m.Now(), m.Settings) {
+			r, err := m.Rotate(ctx, l.Name, false)
+			if err != nil {
+				return out, err
+			}
+			out = append(out, r)
+		}
+	}
+	return out, nil
+}
+
+// ReadUsage reads and records each subscription's usage (ADR 0054); the event names the licence and numbers.
+func (m *Manager) ReadUsage(ctx context.Context) error {
+	all, err := m.Store.Licences(ctx)
+	if err != nil {
+		return err
+	}
+	for _, l := range all {
+		if l.Kind != "subscription" || l.Sealed == "" {
+			continue
+		}
+		plain, err := m.Crypt.Open(l.Sealed)
+		if err != nil {
+			return err
+		}
+		var g FullGrant
+		_ = json.Unmarshal([]byte(plain), &g)
+		raw, err := m.Vendor.Usage(ctx, g.AccessToken)
+		if err != nil || raw == nil {
+			continue
+		}
+		reading := FlattenUsage(raw)
+		if err := m.Store.RecordUsage(ctx, l.Name, m.Now().UnixMilli(), reading, raw); err != nil {
+			return err
+		}
+		_ = m.Emit("usage.read", map[string]any{"licence": l.Name, "sessionPct": reading.SessionPct,
+			"weeklyPct": reading.WeeklyPct, "sonnetPct": reading.SonnetPct})
+	}
+	return nil
+}
+
+// ---- the seat's verbs --------------------------------------------------------------------------------
+
+// Current is a consumer's token sealed to the key it sent (ADR 0206 §6): for a subscription the access
+// token and its expiries only — never the refresh token, which no node holds. Nil when it is bound to
+// nothing.
+func (m *Manager) Current(ctx context.Context, consumer, publicKey string) (map[string]any, error) {
+	if !strings.Contains(publicKey, "PUBLIC KEY") {
+		return nil, errors.New("current seals to the consumer's public key, and none was given")
+	}
+	b, err := m.Store.Binding(ctx, consumer)
+	if err != nil || b == nil {
+		return nil, err
+	}
+	l, err := m.Store.Licence(ctx, b.Licence)
+	if err != nil || l == nil || l.Sealed == "" {
+		return nil, err
+	}
+	plain, err := m.Crypt.Open(l.Sealed)
+	if err != nil {
+		return nil, err
+	}
+	handed := plain
+	if l.Kind == "subscription" {
+		var g FullGrant
+		if err := json.Unmarshal([]byte(plain), &g); err != nil {
+			return nil, err
+		}
+		access, _ := json.Marshal(map[string]any{"accessToken": g.AccessToken, "expiresAt": g.ExpiresAt,
+			"refreshTokenExpiresAt": g.RefreshTokenExpiresAt, "scopes": g.Scopes,
+			"subscriptionType": g.SubscriptionType, "rateLimitTier": g.RateLimitTier})
+		handed = string(access)
+	}
+	box, err := Seal(handed, publicKey)
+	if err != nil {
+		return nil, err
+	}
+	out := map[string]any{"licence": l.Name, "kind": l.Kind, "generation": b.Generation, "sealed": box}
+	if l.AccountUUID != "" {
+		out["identity"] = Identity{AccountUUID: l.AccountUUID, EmailAddress: l.Email, OrganizationUUID: l.OrganizationUUID}
+	}
+	return out, nil
+}
+
+// Bind binds or switches a consumer: a person's act (ADR 0183), told to the consumer as a new generation.
+func (m *Manager) Bind(ctx context.Context, consumer, licence, by string) (map[string]any, error) {
+	l, err := m.Store.Licence(ctx, licence)
+	if err != nil {
+		return nil, err
+	}
+	if l == nil {
+		return nil, fmt.Errorf("there is no licence %s; `licences` lists them", licence)
+	}
+	before, err := m.Store.Binding(ctx, consumer)
+	if err != nil {
+		return nil, err
+	}
+	b, err := m.Store.Bind(ctx, consumer, licence)
+	if err != nil {
+		return nil, err
+	}
+	from, what := "", "bound"
+	if before != nil {
+		from, what = before.Licence, "switched"
+	}
+	_ = m.Store.Audit(ctx, what, map[string]any{"consumer": consumer, "licence": licence, "from": from, "by": by})
+	if err := m.PutBinding(ctx, consumer, BindingState{Licence: licence, Kind: l.Kind, Generation: b.Generation}); err != nil {
+		return nil, err
+	}
+	return map[string]any{"consumer": consumer, "licence": licence, "generation": b.Generation, "from": from}, nil
+}
+
+// Release unbinds a consumer; its node keeps its last token, which expires within hours.
+func (m *Manager) Release(ctx context.Context, consumer, by string) (map[string]any, error) {
+	was, err := m.Store.Binding(ctx, consumer)
+	if err != nil {
+		return nil, err
+	}
+	if ok, err := m.Store.Unbind(ctx, consumer); err != nil || !ok {
+		return map[string]any{"consumer": consumer, "released": false, "reason": "it was bound to nothing"}, err
+	}
+	if err := m.DeleteBinding(ctx, consumer); err != nil {
+		return nil, err
+	}
+	_ = m.Store.Audit(ctx, "released", map[string]any{"consumer": consumer, "licence": was.Licence, "by": by})
+	return map[string]any{"consumer": consumer, "released": true, "was": was.Licence}, nil
+}
+
+var licenceName = regexp.MustCompile(`^[A-Za-z0-9@._-]+$`)
+
+// AdoptKey adopts an API key from a file on this node — never an argument (design 39 §6).
+func (m *Manager) AdoptKey(ctx context.Context, name, file string) (map[string]any, error) {
+	raw, err := os.ReadFile(file)
+	if err != nil {
+		return nil, err
+	}
+	return m.adoptKey(ctx, name, strings.TrimSpace(string(raw)), "a file on "+m.Holder)
+}
+
+// AdoptSealedKey adopts an API key sealed to this module's public key by a node's agent module (ADR 0209):
+// the key crosses the bus only sealed, on request/reply.
+func (m *Manager) AdoptSealedKey(ctx context.Context, name string, box SealedBox, from string) (map[string]any, error) {
+	key, err := Open(box, m.Keys.PrivateKey)
+	if err != nil {
+		return nil, err
+	}
+	return m.adoptKey(ctx, name, strings.TrimSpace(key), from)
+}
+
+func (m *Manager) adoptKey(ctx context.Context, name, key, from string) (map[string]any, error) {
+	if !licenceName.MatchString(name) {
+		return nil, fmt.Errorf("%q is not a licence name: letters, digits and @._-", name)
+	}
+	if key == "" {
+		return nil, errors.New("the key is empty")
+	}
+	held, err := m.Store.Licence(ctx, name)
+	if err != nil {
+		return nil, err
+	}
+	if held != nil && held.Kind != "api-key" {
+		return nil, fmt.Errorf("%s is a subscription; an API key needs a name of its own", name)
+	}
+	l := Licence{Name: name, Kind: "api-key", Sealed: m.Crypt.Seal(key), AdoptedAt: m.Now().UnixMilli()}
+	if err := m.Store.SaveLicence(ctx, l); err != nil {
+		return nil, err
+	}
+	_ = m.Store.Audit(ctx, "adopted", map[string]any{"licence": name, "kind": "api-key", "from": from})
+	if err := m.publishAdvance(ctx, l); err != nil {
+		return nil, err
+	}
+	_ = m.Emit("licence.adopted", map[string]any{"licence": name, "from": from, "replaced": held != nil})
+	return map[string]any{"licence": name, "kind": "api-key", "adopted": true, "fingerprint": Fingerprint(key)}, nil
+}
+
+// Licences is each licence as a person reads it: health and who is bound, never a token.
+func (m *Manager) Licences(ctx context.Context) ([]map[string]any, error) {
+	all, err := m.Store.Licences(ctx)
+	if err != nil {
+		return nil, err
+	}
+	bindings, err := m.Store.Bindings(ctx)
+	if err != nil {
+		return nil, err
+	}
+	stamp := func(ms int64) any {
+		if ms == 0 {
+			return nil
+		}
+		return time.UnixMilli(ms).UTC().Format(time.RFC3339)
+	}
+	out := []map[string]any{}
+	for _, l := range all {
+		bound := []string{}
+		for _, b := range bindings {
+			if b.Licence == l.Name {
+				bound = append(bound, b.Consumer)
+			}
+		}
+		account := l.Email
+		if account == "" {
+			account = l.AccountUUID
+		}
+		out = append(out, map[string]any{"name": l.Name, "kind": l.Kind, "account": account,
+			"accessExpiresAt": stamp(l.AccessExpiresAt), "refreshExpiresAt": stamp(l.RefreshExpiresAt),
+			"rotatedAt": stamp(l.RotatedAt), "failures": l.Failures, "bound": bound})
+	}
+	return out, nil
+}

modules/claude-licence-manager/cmd/claude-licence-manager/manager_test.go

@@ -0,0 +1,425 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+var t0 = time.Date(2026, 10, 4, 12, 0, 0, 0, time.UTC)
+
+// stubVendor rotates like the real one is presumed to: each refresh token exchanges once.
+type stubVendor struct {
+	mu        sync.Mutex
+	live      map[string]bool
+	exchanged []string
+	issued    int
+	account   string
+	now       func() time.Time
+}
+
+func (v *stubVendor) Refresh(_ context.Context, g FullGrant) Refreshed {
+	v.mu.Lock()
+	defer v.mu.Unlock()
+	v.exchanged = append(v.exchanged, g.RefreshToken)
+	if !v.live[g.RefreshToken] {
+		return Refreshed{Status: 400, Reason: `{"error":"invalid_grant"}`}
+	}
+	delete(v.live, g.RefreshToken)
+	v.issued++
+	next := fmt.Sprintf("rt-%d", v.issued)
+	v.live[next] = true
+	g.AccessToken = fmt.Sprintf("at-%d", v.issued)
+	g.RefreshToken = next
+	g.ExpiresAt = v.now().Add(8 * time.Hour).UnixMilli()
+	exp := v.now().Add(30 * 24 * time.Hour).UnixMilli()
+	g.RefreshTokenExpiresAt = &exp
+	return Refreshed{OK: true, Grant: g, Account: v.account}
+}
+
+func (v *stubVendor) Usage(context.Context, string) (map[string]any, error) {
+	return map[string]any{"five_hour": map[string]any{"utilization": 12.0}}, nil
+}
+
+type miniMesh struct {
+	m       *Manager
+	store   *MemoryStore
+	vendor  *stubVendor
+	logins  map[string]FullGrant // node → what its credentials file holds
+	state   map[string]BindingState
+	events  []string
+	now     time.Time
+	keys    KeyPair
+	askDown bool
+}
+
+func newMesh(t *testing.T) *miniMesh {
+	t.Helper()
+	mm := &miniMesh{logins: map[string]FullGrant{}, state: map[string]BindingState{}, now: t0}
+	now := func() time.Time { return mm.now }
+	mm.store = NewMemoryStore(now)
+	mm.vendor = &stubVendor{live: map[string]bool{}, now: now}
+	crypt, _ := NewCrypt("a key the vault made")
+	mm.keys, _ = GenerateKeyPair()
+	mm.m = &Manager{
+		Store: mm.store, Vendor: mm.vendor, Crypt: crypt, Keys: mm.keys,
+		AskGrant: func(_ context.Context, node, publicKey string) (GrantAnswer, error) {
+			if mm.askDown {
+				return GrantAnswer{}, fmt.Errorf("503 no responders")
+			}
+			g, ok := mm.logins[node]
+			if !ok {
+				return GrantAnswer{}, nil
+			}
+			raw, _ := json.Marshal(g)
+			box, err := Seal(string(raw), publicKey)
+			return GrantAnswer{Sealed: &box, Fingerprint: Fingerprint(g.RefreshToken)}, err
+		},
+		PutBinding:    func(_ context.Context, c string, b BindingState) error { mm.state[c] = b; return nil },
+		DeleteBinding: func(_ context.Context, c string) error { delete(mm.state, c); return nil },
+		Emit: func(event string, body map[string]any) error {
+			raw, _ := json.Marshal(body)
+			mm.events = append(mm.events, event+" "+string(raw))
+			return nil
+		},
+		Now: now, Log: func(string, ...any) {}, Holder: "test", Settings: Defaults,
+	}
+	return mm
+}
+
+func (mm *miniMesh) report(node, rt string, at time.Time, account string) Holdings {
+	h := Holdings{Node: node, Identity: &Identity{AccountUUID: account, EmailAddress: account + "@example.org"},
+		Kind: "subscription", ChangedAt: at.Format(time.RFC3339Nano)}
+	if rt != "" {
+		h.Refresh.Present, h.Refresh.Fingerprint = true, Fingerprint(rt)
+	}
+	return h
+}
+
+func (mm *miniMesh) login(node, rt string, valid bool, at time.Time) Holdings {
+	mm.logins[node] = FullGrant{AccessToken: "local-" + node, RefreshToken: rt, ExpiresAt: mm.now.Add(time.Hour).UnixMilli()}
+	if valid {
+		mm.vendor.live[rt] = true
+	}
+	return mm.report(node, rt, at, "acct-1")
+}
+
+const licence1 = "acct-1@example.org"
+
+func TestAManagerWithNoLicenceAdoptsTheNewestLoginThatRefreshesAndNeverExchangesTheRest(t *testing.T) {
+	mm := newMesh(t)
+	ctx := context.Background()
+	older := mm.login("server", "rt-server", true, t0.Add(-time.Hour))
+	newest := mm.login("laptop", "rt-laptop", true, t0.Add(-time.Minute))
+	adopted, err := mm.m.Consider(ctx, []Holdings{older, newest})
+	if err != nil || len(adopted) != 1 || adopted[0] != licence1 {
+		t.Fatalf("adopted %v, %v", adopted, err)
+	}
+	if strings.Join(mm.vendor.exchanged, ",") != "rt-laptop" {
+		t.Fatalf("exchanged %v: an older login was exchanged although a newer one refreshed", mm.vendor.exchanged)
+	}
+	if o, _ := mm.store.Outcome(ctx, Fingerprint("rt-server")); o != Skipped {
+		t.Fatalf("the older login is %q, not skipped", o)
+	}
+	// A first binding follows the login: both nodes reported this account and were bound to nothing.
+	bs, _ := mm.store.Bindings(ctx)
+	if len(bs) != 2 || mm.state["laptop"].Licence != licence1 || mm.state["server"].Licence != licence1 {
+		t.Fatalf("bindings %v, state %v", bs, mm.state)
+	}
+	if !strings.HasPrefix(strings.Join(mm.events, "|"), "licence.adopted") {
+		t.Fatalf("events %v", mm.events)
+	}
+}
+
+func TestALoginThatDoesNotRefreshAdoptsNothingAndIsNotTriedAgain(t *testing.T) {
+	mm := newMesh(t)
+	ctx := context.Background()
+	dead := mm.login("laptop", "rt-dead", false, t0)
+	if adopted, _ := mm.m.Consider(ctx, []Holdings{dead}); len(adopted) != 0 {
+		t.Fatalf("adopted %v", adopted)
+	}
+	if o, _ := mm.store.Outcome(ctx, Fingerprint("rt-dead")); o != Dead {
+		t.Fatalf("outcome %q", o)
+	}
+	if ls, _ := mm.store.Licences(ctx); len(ls) != 0 {
+		t.Fatalf("licences %v", ls)
+	}
+	if !strings.Contains(strings.Join(mm.events, "|"), "licence.refused") {
+		t.Fatalf("events %v", mm.events)
+	}
+	_, _ = mm.m.Consider(ctx, []Holdings{dead})
+	if len(mm.vendor.exchanged) != 1 {
+		t.Fatalf("a dead refresh token was exchanged %d times", len(mm.vendor.exchanged))
+	}
+}
+
+func TestANewerLoginReplacesTheGrantHeldAndAnOlderOneDoesNot(t *testing.T) {
+	mm := newMesh(t)
+	ctx := context.Background()
+	_, _ = mm.m.Consider(ctx, []Holdings{mm.login("laptop", "rt-a", true, t0.Add(-time.Minute))})
+	before, _ := mm.store.Licence(ctx, licence1)
+	_, _ = mm.m.Consider(ctx, []Holdings{mm.login("server", "rt-old", true, t0.Add(-24*time.Hour))})
+	if strings.Join(mm.vendor.exchanged, ",") != "rt-a" {
+		t.Fatalf("an older login was exchanged: %v", mm.vendor.exchanged)
+	}
+	mm.now = t0.Add(10 * time.Minute)
+	_, _ = mm.m.Consider(ctx, []Holdings{mm.login("desktop", "rt-new", true, t0.Add(10*time.Minute))})
+	after, _ := mm.store.Licence(ctx, licence1)
+	if after.RefreshFingerprint == before.RefreshFingerprint || mm.vendor.exchanged[len(mm.vendor.exchanged)-1] != "rt-new" {
+		t.Fatalf("a newer login did not win: %v", mm.vendor.exchanged)
+	}
+	if ls, _ := mm.store.Licences(ctx); len(ls) != 1 {
+		t.Fatalf("one account became %d licences", len(ls))
+	}
+}
+
+func TestAReportNamingAnotherAccountThanTheVendorAnsweredForIsRefused(t *testing.T) {
+	mm := newMesh(t)
+	ctx := context.Background()
+	mm.vendor.account = "someone-else"
+	if adopted, _ := mm.m.Consider(ctx, []Holdings{mm.login("laptop", "rt-a", true, t0)}); len(adopted) != 0 {
+		t.Fatalf("adopted %v", adopted)
+	}
+	if o, _ := mm.store.Outcome(ctx, Fingerprint("rt-a")); o != Refused {
+		t.Fatalf("outcome %q", o)
+	}
+}
+
+func TestTwoRefreshRunsStartedTogetherRotateAGrantOnce(t *testing.T) {
+	mm := newMesh(t)
+	ctx := context.Background()
+	_, _ = mm.m.Consider(ctx, []Holdings{mm.login("laptop", "rt-a", true, t0)})
+	mm.now = t0.Add(5 * time.Hour)
+	second := *mm.m
+	second.Holder = "another run"
+	var wg sync.WaitGroup
+	results := make([]map[string]any, 2)
+	for i, m := range []*Manager{mm.m, &second} {
+		wg.Add(1)
+		go func() { defer wg.Done(); results[i], _ = m.Rotate(ctx, licence1, false) }()
+	}
+	wg.Wait()
+	n := 0
+	for _, r := range results {
+		if r["refreshed"] == true {
+			n++
+		}
+	}
+	if n != 1 {
+		t.Fatalf("rotated %d times: %v", n, results)
+	}
+	if r, _ := second.Rotate(ctx, licence1, false); r["reason"] != "not due" {
+		t.Fatalf("a run just after was %v", r)
+	}
+}
+
+func TestARotationAndASwitchEachGiveANewerGeneration(t *testing.T) {
+	mm := newMesh(t)
+	ctx := context.Background()
+	_, _ = mm.m.Consider(ctx, []Holdings{mm.login("laptop", "rt-a", true, t0)})
+	g0 := mm.state["laptop"].Generation
+	_, _ = mm.m.Rotate(ctx, licence1, true)
+	g1 := mm.state["laptop"].Generation
+	if g1 <= g0 {
+		t.Fatalf("a rotation went from %d to %d", g0, g1)
+	}
+	file := filepath.Join(t.TempDir(), "key")
+	_ = os.WriteFile(file, []byte("sk-ant-api-key\n"), 0o600)
+	if _, err := mm.m.AdoptKey(ctx, "api", file); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := mm.m.Bind(ctx, "laptop", "api", "test"); err != nil {
+		t.Fatal(err)
+	}
+	if mm.state["laptop"].Licence != "api" || mm.state["laptop"].Generation <= g1 {
+		t.Fatalf("a switch to a licence rotated less often went backwards: %v", mm.state["laptop"])
+	}
+	if _, err := mm.m.Release(ctx, "laptop", "test"); err != nil {
+		t.Fatal(err)
+	}
+	if _, ok := mm.state["laptop"]; ok {
+		t.Fatal("a released consumer still has a binding in the state")
+	}
+}
+
+func TestCurrentHandsAnAccessTokenOnlySealedToTheConsumersKey(t *testing.T) {
+	mm := newMesh(t)
+	ctx := context.Background()
+	_, _ = mm.m.Consider(ctx, []Holdings{mm.login("laptop", "rt-a", true, t0)})
+	node, _ := GenerateKeyPair()
+	answer, err := mm.m.Current(ctx, "laptop", node.PublicKey)
+	if err != nil || answer["kind"] != "subscription" {
+		t.Fatalf("%v %v", answer, err)
+	}
+	box := answer["sealed"].(SealedBox)
+	plain, err := Open(box, node.PrivateKey)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var handed map[string]any
+	_ = json.Unmarshal([]byte(plain), &handed)
+	if !strings.HasPrefix(handed["accessToken"].(string), "at-") || handed["refreshToken"] != nil {
+		t.Fatalf("handed %v", handed)
+	}
+	other, _ := GenerateKeyPair()
+	if _, err := Open(box, other.PrivateKey); err == nil {
+		t.Fatal("the hand-over opened with another key")
+	}
+	if a, _ := mm.m.Current(ctx, "nobody", node.PublicKey); a != nil {
+		t.Fatalf("a consumer bound to nothing was answered %v", a)
+	}
+}
+
+func TestNothingTheManagerPublishesKeepsOrListsCarriesAToken(t *testing.T) {
+	mm := newMesh(t)
+	ctx := context.Background()
+	_, _ = mm.m.Consider(ctx, []Holdings{mm.login("laptop", "rt-secret-1", true, t0)})
+	_, _ = mm.m.Rotate(ctx, licence1, true)
+	_, _ = mm.m.Consider(ctx, []Holdings{mm.login("server", "rt-secret-dead", false, t0.Add(time.Hour))})
+	_ = mm.m.ReadUsage(ctx)
+	ls, _ := mm.m.Licences(ctx)
+	bs, _ := mm.store.Bindings(ctx)
+	everything, _ := json.Marshal([]any{mm.events, mm.state, ls, bs})
+	for _, token := range []string{"rt-secret", "rt-1", "rt-2", "at-1", "at-2", "local-"} {
+		if strings.Contains(string(everything), token) {
+			t.Fatalf("%s was published: %s", token, everything)
+		}
+	}
+	row, _ := mm.store.Licence(ctx, licence1)
+	if strings.Contains(row.Sealed, "rt-") {
+		t.Fatal("the grant is stored in the clear")
+	}
+}
+
+func TestANodeThatDoesNotAnswerIsAskedAgainAndOneWithNoLoginIsSettled(t *testing.T) {
+	mm := newMesh(t)
+	ctx := context.Background()
+	r := mm.login("laptop", "rt-a", true, t0)
+	mm.askDown = true
+	if adopted, _ := mm.m.Consider(ctx, []Holdings{r}); len(adopted) != 0 {
+		t.Fatalf("adopted %v from a node that did not answer", adopted)
+	}
+	if o, _ := mm.store.Outcome(ctx, Fingerprint("rt-a")); o != "" {
+		t.Fatalf("a node that was down was settled %q", o)
+	}
+	mm.askDown = false
+	if adopted, _ := mm.m.Consider(ctx, []Holdings{r}); len(adopted) != 1 {
+		t.Fatalf("adopted %v on the next pass", adopted)
+	}
+	gone := mm.report("server", "rt-gone", t0.Add(time.Second), "acct-2")
+	_, _ = mm.m.Consider(ctx, []Holdings{gone})
+	if o, _ := mm.store.Outcome(ctx, Fingerprint("rt-gone")); o != Gone {
+		t.Fatalf("outcome %q", o)
+	}
+}
+
+func TestAReportIsReadAsTheAgentModuleWritesIt(t *testing.T) {
+	// The agent module's own report shape (claude-code's holdingsOf), parsed here.
+	raw := `{"node":"laptop","identity":{"accountUuid":"u-1","emailAddress":"a@example.org"},"kind":"subscription",
+	  "refresh":{"present":true,"fingerprint":"sha256:0123456789abcdef","expiresAt":null},
+	  "access":{"fingerprint":"sha256:fedcba9876543210","expiresAt":1},"licence":null,"generation":0,
+	  "changedAt":"2026-10-04T11:00:00.000Z"}`
+	var h Holdings
+	if err := json.Unmarshal([]byte(raw), &h); err != nil {
+		t.Fatal(err)
+	}
+	if h.Node != "laptop" || h.Identity.AccountUUID != "u-1" || !h.Refresh.Present || h.Refresh.Fingerprint != "sha256:0123456789abcdef" {
+		t.Fatalf("%+v", h)
+	}
+	if _, err := time.Parse(time.RFC3339Nano, h.ChangedAt); err != nil {
+		t.Fatalf("the report's time does not parse: %v", err)
+	}
+}
+
+// A node whose report arrives after its account was adopted — with an older login, so never a candidate —
+// is still bound to that account's licence, once.
+func TestANodeReportingAnAdoptedAccountLaterIsBoundToIt(t *testing.T) {
+	mm := newMesh(t)
+	ctx := context.Background()
+	_, _ = mm.m.Consider(ctx, []Holdings{mm.login("novox", "rt-new", true, t0)})
+	late := mm.login("laptop", "rt-older", true, t0.Add(-24*time.Hour))
+	_, _ = mm.m.Consider(ctx, []Holdings{late})
+	if mm.state["laptop"].Licence != licence1 {
+		t.Fatalf("a node reporting the adopted account later was not bound: %v", mm.state)
+	}
+	if strings.Contains(strings.Join(mm.vendor.exchanged, ","), "rt-older") {
+		t.Fatal("the older login was exchanged")
+	}
+	g := mm.state["laptop"].Generation
+	_, _ = mm.m.Consider(ctx, []Holdings{late})
+	if mm.state["laptop"].Generation != g {
+		t.Fatal("a node already bound was bound again")
+	}
+}
+
+// A login to another account on one node adopts it and moves that node, and only that node (ADR 0209).
+func TestALoginToAnotherAccountMovesItsNodeAndNoOther(t *testing.T) {
+	mm := newMesh(t)
+	ctx := context.Background()
+	_, _ = mm.m.Consider(ctx, []Holdings{mm.login("laptop", "rt-a", true, t0), mm.report("server", "", t0, "acct-1")})
+	if mm.state["laptop"].Licence != licence1 || mm.state["server"].Licence != licence1 {
+		t.Fatalf("%v", mm.state)
+	}
+	mm.now = t0.Add(time.Hour)
+	mm.logins["laptop"] = FullGrant{AccessToken: "local", RefreshToken: "rt-b", ExpiresAt: 1}
+	mm.vendor.live["rt-b"] = true
+	second := mm.report("laptop", "rt-b", t0.Add(time.Hour), "acct-2")
+	adopted, _ := mm.m.Consider(ctx, []Holdings{second, mm.report("server", "", t0, "acct-1")})
+	if len(adopted) != 1 || adopted[0] != "acct-2@example.org" {
+		t.Fatalf("adopted %v", adopted)
+	}
+	if mm.state["laptop"].Licence != "acct-2@example.org" {
+		t.Fatalf("the node a login was made on stayed bound to %v", mm.state["laptop"])
+	}
+	if mm.state["server"].Licence != licence1 {
+		t.Fatalf("another node moved: %v", mm.state["server"])
+	}
+	ls, _ := mm.store.Licences(ctx)
+	if len(ls) != 2 {
+		t.Fatalf("%d licences", len(ls))
+	}
+}
+
+// A login that does not refresh moves nothing.
+func TestALoginThatDoesNotRefreshMovesNothing(t *testing.T) {
+	mm := newMesh(t)
+	ctx := context.Background()
+	_, _ = mm.m.Consider(ctx, []Holdings{mm.login("laptop", "rt-a", true, t0)})
+	g := mm.state["laptop"]
+	mm.logins["laptop"] = FullGrant{AccessToken: "local", RefreshToken: "rt-dead", ExpiresAt: 1}
+	_, _ = mm.m.Consider(ctx, []Holdings{mm.report("laptop", "rt-dead", t0.Add(time.Hour), "acct-2")})
+	if mm.state["laptop"] != g {
+		t.Fatalf("a dead login moved its node: %v", mm.state["laptop"])
+	}
+}
+
+// An API key sealed to the manager by a node is adopted, and opens only for the manager.
+func TestAnAPIKeySealedByANodeIsAdopted(t *testing.T) {
+	mm := newMesh(t)
+	ctx := context.Background()
+	box, _ := Seal("sk-ant-api03-test\n", mm.keys.PublicKey)
+	r, err := mm.m.AdoptSealedKey(ctx, "api", box, "laptop")
+	if err != nil || r["adopted"] != true {
+		t.Fatalf("%v %v", r, err)
+	}
+	l, _ := mm.store.Licence(ctx, "api")
+	if plain, _ := mm.m.Crypt.Open(l.Sealed); plain != "sk-ant-api03-test" {
+		t.Fatalf("stored %q", plain)
+	}
+	other, _ := GenerateKeyPair()
+	wrong, _ := Seal("sk", other.PublicKey)
+	if _, err := mm.m.AdoptSealedKey(ctx, "api2", wrong, "laptop"); err == nil {
+		t.Fatal("a key sealed to another key was adopted")
+	}
+	for _, e := range mm.events {
+		if strings.Contains(e, "sk-ant") {
+			t.Fatalf("the key was published: %s", e)
+		}
+	}
+}

modules/claude-licence-manager/cmd/claude-licence-manager/pgstore.go

@@ -0,0 +1,281 @@
+package main
+
+// The store on the mesh's postgres (novox/hq design 39 §1), the database the mesh provisioned for this
+// module. The schema is brought to this version's shape by the preparation step (ADR 0135), each
+// statement idempotent.
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// Schema is what this version needs.
+var Schema = []string{
+	`create table if not exists licence (
+	   name text primary key,
+	   kind text not null check (kind in ('subscription', 'api-key')),
+	   account_uuid text unique,
+	   email text,
+	   organization_uuid text,
+	   sealed text,
+	   refresh_fingerprint text,
+	   access_expires_at bigint,
+	   refresh_expires_at bigint,
+	   failures integer not null default 0,
+	   notified_at bigint,
+	   adopted_at bigint not null,
+	   rotated_at bigint)`,
+	`create sequence if not exists binding_generation`,
+	`create table if not exists binding (
+	   consumer text primary key,
+	   licence text not null references licence(name),
+	   generation bigint not null)`,
+	`create table if not exists lease (
+	   key text primary key,
+	   holder text not null,
+	   until timestamptz not null)`,
+	`create table if not exists offered (
+	   fingerprint text primary key,
+	   node text not null,
+	   account_uuid text,
+	   outcome text not null,
+	   why text not null,
+	   at timestamptz not null default now())`,
+	`create table if not exists usage (
+	   licence text not null,
+	   at bigint not null,
+	   reading jsonb not null,
+	   raw jsonb not null)`,
+	`create index if not exists usage_by_licence on usage (licence, at desc)`,
+	`create table if not exists audit (
+	   at timestamptz not null default now(),
+	   what text not null,
+	   detail jsonb not null)`,
+}
+
+// PgStore is the store on postgres.
+type PgStore struct{ pool *pgxpool.Pool }
+
+// PgStoreFromEnv opens the store the mesh provisioned, its URL in the file DATABASE_URL_FILE names.
+func PgStoreFromEnv(ctx context.Context) (*PgStore, error) {
+	file := os.Getenv("DATABASE_URL_FILE")
+	if file == "" {
+		return nil, errors.New("DATABASE_URL_FILE is not set: the manager's database is a requirement the mesh resolves")
+	}
+	raw, err := os.ReadFile(file)
+	if err != nil {
+		return nil, err
+	}
+	return OpenPgStore(ctx, strings.TrimSpace(string(raw)))
+}
+
+// OpenPgStore opens a store at a URL.
+func OpenPgStore(ctx context.Context, url string) (*PgStore, error) {
+	pool, err := pgxpool.New(ctx, url)
+	if err != nil {
+		return nil, err
+	}
+	return &PgStore{pool: pool}, nil
+}
+
+// Migrate brings the schema to this version's shape.
+func (s *PgStore) Migrate(ctx context.Context) error {
+	for _, q := range Schema {
+		if _, err := s.pool.Exec(ctx, q); err != nil {
+			return fmt.Errorf("%s: %w", strings.Fields(q)[0:6], err)
+		}
+	}
+	return nil
+}
+
+const licenceColumns = `name, kind, coalesce(account_uuid,''), coalesce(email,''), coalesce(organization_uuid,''),
+  coalesce(sealed,''), coalesce(refresh_fingerprint,''), coalesce(access_expires_at,0), coalesce(refresh_expires_at,0),
+  failures, coalesce(notified_at,0), adopted_at, coalesce(rotated_at,0)`
+
+func scanLicence(row pgx.Row) (*Licence, error) {
+	var l Licence
+	err := row.Scan(&l.Name, &l.Kind, &l.AccountUUID, &l.Email, &l.OrganizationUUID, &l.Sealed, &l.RefreshFingerprint,
+		&l.AccessExpiresAt, &l.RefreshExpiresAt, &l.Failures, &l.NotifiedAt, &l.AdoptedAt, &l.RotatedAt)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return nil, nil
+	}
+	return &l, err
+}
+
+func (s *PgStore) Licences(ctx context.Context) ([]Licence, error) {
+	rows, err := s.pool.Query(ctx, `select `+licenceColumns+` from licence order by name`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []Licence
+	for rows.Next() {
+		l, err := scanLicence(rows)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, *l)
+	}
+	return out, rows.Err()
+}
+
+func (s *PgStore) Licence(ctx context.Context, name string) (*Licence, error) {
+	return scanLicence(s.pool.QueryRow(ctx, `select `+licenceColumns+` from licence where name = $1`, name))
+}
+
+func (s *PgStore) LicenceForAccount(ctx context.Context, account string) (*Licence, error) {
+	return scanLicence(s.pool.QueryRow(ctx, `select `+licenceColumns+` from licence where account_uuid = $1`, account))
+}
+
+func nullable(s string) any {
+	if s == "" {
+		return nil
+	}
+	return s
+}
+
+func nullableInt(v int64) any {
+	if v == 0 {
+		return nil
+	}
+	return v
+}
+
+func (s *PgStore) SaveLicence(ctx context.Context, l Licence) error {
+	_, err := s.pool.Exec(ctx, `insert into licence (name, kind, account_uuid, email, organization_uuid, sealed, refresh_fingerprint,
+	    access_expires_at, refresh_expires_at, failures, notified_at, adopted_at, rotated_at)
+	  values ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13)
+	  on conflict (name) do update set kind = excluded.kind, account_uuid = excluded.account_uuid, email = excluded.email,
+	    organization_uuid = excluded.organization_uuid, sealed = excluded.sealed, refresh_fingerprint = excluded.refresh_fingerprint,
+	    access_expires_at = excluded.access_expires_at, refresh_expires_at = excluded.refresh_expires_at,
+	    failures = excluded.failures, notified_at = excluded.notified_at, adopted_at = excluded.adopted_at,
+	    rotated_at = excluded.rotated_at`,
+		l.Name, l.Kind, nullable(l.AccountUUID), nullable(l.Email), nullable(l.OrganizationUUID), nullable(l.Sealed),
+		nullable(l.RefreshFingerprint), nullableInt(l.AccessExpiresAt), nullableInt(l.RefreshExpiresAt), l.Failures,
+		nullableInt(l.NotifiedAt), l.AdoptedAt, nullableInt(l.RotatedAt))
+	return err
+}
+
+// Lease is taken in the store before a row is read (design 39 §3): a second run started together finds
+// it live and does nothing.
+func (s *PgStore) Lease(ctx context.Context, key, holder string, d time.Duration) (bool, error) {
+	tag, err := s.pool.Exec(ctx, `insert into lease (key, holder, until) values ($1, $2, now() + make_interval(secs => $3))
+	  on conflict (key) do update set holder = excluded.holder, until = excluded.until
+	    where lease.until < now() or lease.holder = excluded.holder`, key, holder, d.Seconds())
+	if err != nil {
+		return false, err
+	}
+	return tag.RowsAffected() == 1, nil
+}
+
+func (s *PgStore) Unlease(ctx context.Context, key, holder string) error {
+	_, err := s.pool.Exec(ctx, `delete from lease where key = $1 and holder = $2`, key, holder)
+	return err
+}
+
+func (s *PgStore) bindingsWhere(ctx context.Context, q string, args ...any) ([]Binding, error) {
+	rows, err := s.pool.Query(ctx, q, args...)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []Binding
+	for rows.Next() {
+		var b Binding
+		if err := rows.Scan(&b.Consumer, &b.Licence, &b.Generation); err != nil {
+			return nil, err
+		}
+		out = append(out, b)
+	}
+	return out, rows.Err()
+}
+
+func (s *PgStore) Bindings(ctx context.Context) ([]Binding, error) {
+	return s.bindingsWhere(ctx, `select consumer, licence, generation from binding order by consumer`)
+}
+
+func (s *PgStore) Binding(ctx context.Context, consumer string) (*Binding, error) {
+	out, err := s.bindingsWhere(ctx, `select consumer, licence, generation from binding where consumer = $1`, consumer)
+	if err != nil || len(out) == 0 {
+		return nil, err
+	}
+	return &out[0], nil
+}
+
+func (s *PgStore) Bind(ctx context.Context, consumer, licence string) (Binding, error) {
+	out, err := s.bindingsWhere(ctx, `insert into binding (consumer, licence, generation) values ($1, $2, nextval('binding_generation'))
+	  on conflict (consumer) do update set licence = excluded.licence, generation = excluded.generation
+	  returning consumer, licence, generation`, consumer, licence)
+	if err != nil {
+		return Binding{}, err
+	}
+	return out[0], nil
+}
+
+func (s *PgStore) Unbind(ctx context.Context, consumer string) (bool, error) {
+	tag, err := s.pool.Exec(ctx, `delete from binding where consumer = $1`, consumer)
+	return err == nil && tag.RowsAffected() == 1, err
+}
+
+func (s *PgStore) Advance(ctx context.Context, licence string) ([]Binding, error) {
+	return s.bindingsWhere(ctx, `update binding set generation = nextval('binding_generation') where licence = $1
+	  returning consumer, licence, generation`, licence)
+}
+
+func (s *PgStore) Outcome(ctx context.Context, fp string) (Outcome, error) {
+	var o string
+	err := s.pool.QueryRow(ctx, `select outcome from offered where fingerprint = $1`, fp).Scan(&o)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return "", nil
+	}
+	return Outcome(o), err
+}
+
+func (s *PgStore) RecordOutcome(ctx context.Context, fp, node, account string, o Outcome, why string) error {
+	_, err := s.pool.Exec(ctx, `insert into offered (fingerprint, node, account_uuid, outcome, why) values ($1,$2,$3,$4,$5)
+	  on conflict (fingerprint) do update set outcome = excluded.outcome, why = excluded.why, at = now()`,
+		fp, node, nullable(account), string(o), why)
+	return err
+}
+
+func (s *PgStore) RecordUsage(ctx context.Context, licence string, at int64, r UsageReading, raw map[string]any) error {
+	reading, _ := json.Marshal(r)
+	rawJSON, _ := json.Marshal(raw)
+	_, err := s.pool.Exec(ctx, `insert into usage (licence, at, reading, raw) values ($1,$2,$3,$4)`, licence, at, reading, rawJSON)
+	return err
+}
+
+func (s *PgStore) Usage(ctx context.Context, licence string, limit int) ([]UsageRow, error) {
+	rows, err := s.pool.Query(ctx, `select licence, at, reading from usage where ($1 = '' or licence = $1) order by at desc limit $2`, licence, limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []UsageRow
+	for rows.Next() {
+		var u UsageRow
+		var reading []byte
+		if err := rows.Scan(&u.Licence, &u.At, &reading); err != nil {
+			return nil, err
+		}
+		_ = json.Unmarshal(reading, &u.Reading)
+		out = append(out, u)
+	}
+	return out, rows.Err()
+}
+
+func (s *PgStore) Audit(ctx context.Context, what string, detail map[string]any) error {
+	raw, _ := json.Marshal(detail)
+	_, err := s.pool.Exec(ctx, `insert into audit (what, detail) values ($1, $2)`, what, raw)
+	return err
+}
+
+func (s *PgStore) Close() { s.pool.Close() }

modules/claude-licence-manager/cmd/claude-licence-manager/seal.go

@@ -0,0 +1,189 @@
+package main
+
+// Sealing to one recipient (novox/hq ADR 0183, ADR 0206): the manager seals what it hands a consumer to
+// the key that consumer sent, and a node seals a waiting login to the key the manager gives. The same box
+// the agent module's TypeScript makes and opens, byte for byte — X25519 for the agreement, HKDF-SHA256 for
+// the key, AES-256-GCM for the box — so `testdata/sealed-by-typescript.json` is opened here, and a test
+// reopens what this seals with the same derivation.
+//
+// A box is `{ v: 1, eph, iv, tag, ct }`, every field base64; `eph` is the one-time public key as SPKI DER,
+// and the key is bound to it and to the recipient's raw public key, so a box cannot be re-addressed.
+
+import (
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/ecdh"
+	"crypto/hkdf"
+	"crypto/rand"
+	"crypto/sha256"
+	"crypto/x509"
+	"encoding/base64"
+	"encoding/pem"
+	"errors"
+	"fmt"
+)
+
+// SealedBox is a value sealed to one recipient.
+type SealedBox struct {
+	V   int    `json:"v"`
+	Eph string `json:"eph"`
+	IV  string `json:"iv"`
+	Tag string `json:"tag"`
+	Ct  string `json:"ct"`
+}
+
+// KeyPair is a recipient's keypair as the two PEM strings it is kept and sent as.
+type KeyPair struct {
+	PublicKey  string `json:"publicKey"`
+	PrivateKey string `json:"privateKey"`
+}
+
+const sealInfo = "novox-mesh sealed box v1"
+
+// GenerateKeyPair makes an X25519 keypair, PEM-encoded as the agent module's are.
+func GenerateKeyPair() (KeyPair, error) {
+	priv, err := ecdh.X25519().GenerateKey(rand.Reader)
+	if err != nil {
+		return KeyPair{}, err
+	}
+	pubDER, err := x509.MarshalPKIXPublicKey(priv.PublicKey())
+	if err != nil {
+		return KeyPair{}, err
+	}
+	privDER, err := x509.MarshalPKCS8PrivateKey(priv)
+	if err != nil {
+		return KeyPair{}, err
+	}
+	return KeyPair{
+		PublicKey:  string(pem.EncodeToMemory(&pem.Block{Type: "PUBLIC KEY", Bytes: pubDER})),
+		PrivateKey: string(pem.EncodeToMemory(&pem.Block{Type: "PRIVATE KEY", Bytes: privDER})),
+	}, nil
+}
+
+func publicFromPEM(p string) (*ecdh.PublicKey, error) {
+	block, _ := pem.Decode([]byte(p))
+	if block == nil {
+		return nil, errors.New("not a PEM public key")
+	}
+	k, err := x509.ParsePKIXPublicKey(block.Bytes)
+	if err != nil {
+		return nil, err
+	}
+	pub, ok := k.(*ecdh.PublicKey)
+	if !ok || pub.Curve() != ecdh.X25519() {
+		return nil, errors.New("not an X25519 public key")
+	}
+	return pub, nil
+}
+
+func privateFromPEM(p string) (*ecdh.PrivateKey, error) {
+	block, _ := pem.Decode([]byte(p))
+	if block == nil {
+		return nil, errors.New("not a PEM private key")
+	}
+	k, err := x509.ParsePKCS8PrivateKey(block.Bytes)
+	if err != nil {
+		return nil, err
+	}
+	priv, ok := k.(*ecdh.PrivateKey)
+	if !ok || priv.Curve() != ecdh.X25519() {
+		return nil, errors.New("not an X25519 private key")
+	}
+	return priv, nil
+}
+
+func boxKey(secret, ephDER, recipientRaw []byte) ([]byte, error) {
+	salt := append(append([]byte{}, ephDER...), recipientRaw...)
+	return hkdf.Key(sha256.New, secret, salt, sealInfo, 32)
+}
+
+// Seal seals plaintext to the recipient's public key.
+func Seal(plaintext, recipientPEM string) (SealedBox, error) {
+	recipient, err := publicFromPEM(recipientPEM)
+	if err != nil {
+		return SealedBox{}, err
+	}
+	eph, err := ecdh.X25519().GenerateKey(rand.Reader)
+	if err != nil {
+		return SealedBox{}, err
+	}
+	secret, err := eph.ECDH(recipient)
+	if err != nil {
+		return SealedBox{}, err
+	}
+	ephDER, err := x509.MarshalPKIXPublicKey(eph.PublicKey())
+	if err != nil {
+		return SealedBox{}, err
+	}
+	key, err := boxKey(secret, ephDER, recipient.Bytes())
+	if err != nil {
+		return SealedBox{}, err
+	}
+	gcm, err := newGCM(key)
+	if err != nil {
+		return SealedBox{}, err
+	}
+	iv := make([]byte, 12)
+	if _, err := rand.Read(iv); err != nil {
+		return SealedBox{}, err
+	}
+	out := gcm.Seal(nil, iv, []byte(plaintext), nil)
+	ct, tag := out[:len(out)-gcm.Overhead()], out[len(out)-gcm.Overhead():]
+	b64 := base64.StdEncoding.EncodeToString
+	return SealedBox{V: 1, Eph: b64(ephDER), IV: b64(iv), Tag: b64(tag), Ct: b64(ct)}, nil
+}
+
+// Open opens a box with the recipient's private key; it fails for a box to another key or one tampered with.
+func Open(box SealedBox, privatePEM string) (string, error) {
+	if box.V != 1 {
+		return "", errors.New("not a sealed box this module can open")
+	}
+	priv, err := privateFromPEM(privatePEM)
+	if err != nil {
+		return "", err
+	}
+	d := base64.StdEncoding.DecodeString
+	ephDER, err := d(box.Eph)
+	if err != nil {
+		return "", fmt.Errorf("the box's eph: %w", err)
+	}
+	ephKey, err := x509.ParsePKIXPublicKey(ephDER)
+	if err != nil {
+		return "", err
+	}
+	eph, ok := ephKey.(*ecdh.PublicKey)
+	if !ok {
+		return "", errors.New("the box's eph is not an X25519 key")
+	}
+	secret, err := priv.ECDH(eph)
+	if err != nil {
+		return "", err
+	}
+	key, err := boxKey(secret, ephDER, priv.PublicKey().Bytes())
+	if err != nil {
+		return "", err
+	}
+	iv, err1 := d(box.IV)
+	tag, err2 := d(box.Tag)
+	ct, err3 := d(box.Ct)
+	if err := errors.Join(err1, err2, err3); err != nil {
+		return "", err
+	}
+	gcm, err := newGCM(key)
+	if err != nil {
+		return "", err
+	}
+	plain, err := gcm.Open(nil, iv, append(ct, tag...), nil)
+	if err != nil {
+		return "", errors.New("the box does not open with this key")
+	}
+	return string(plain), nil
+}
+
+func newGCM(key []byte) (cipher.AEAD, error) {
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return nil, err
+	}
+	return cipher.NewGCM(block)
+}

modules/claude-licence-manager/cmd/claude-licence-manager/seal_test.go

@@ -0,0 +1,43 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"testing"
+)
+
+// A box the agent module's TypeScript sealed opens here: the two implementations are one format.
+func TestABoxSealedInTypeScriptOpensInGo(t *testing.T) {
+	raw, err := os.ReadFile("testdata/sealed-by-typescript.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var f struct {
+		PrivateKey string    `json:"privateKey"`
+		Box        SealedBox `json:"box"`
+		Plaintext  string    `json:"plaintext"`
+	}
+	if err := json.Unmarshal(raw, &f); err != nil {
+		t.Fatal(err)
+	}
+	got, err := Open(f.Box, f.PrivateKey)
+	if err != nil || got != f.Plaintext {
+		t.Fatalf("opened %q, %v", got, err)
+	}
+}
+
+// What Go seals opens with its own key and no other.
+func TestABoxOpensOnlyForItsRecipient(t *testing.T) {
+	a, _ := GenerateKeyPair()
+	b, _ := GenerateKeyPair()
+	box, err := Seal("a token", a.PublicKey)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got, err := Open(box, a.PrivateKey); err != nil || got != "a token" {
+		t.Fatalf("opened %q, %v", got, err)
+	}
+	if _, err := Open(box, b.PrivateKey); err == nil {
+		t.Fatal("a box opened for another key")
+	}
+}

modules/claude-licence-manager/cmd/claude-licence-manager/store.go

@@ -0,0 +1,263 @@
+package main
+
+// The manager's store (novox/hq ADR 0183, design 39 §1): licences with their grants encrypted, bindings
+// with a generation, what became of each login it was offered, usage readings, and the audit. One
+// interface, two implementations — postgres for the mesh (pgstore.go), memory for the tests — so every
+// rule is tested without a database, and the database is asked only to keep rows.
+
+import (
+	"context"
+	"sort"
+	"sync"
+	"time"
+)
+
+// Licence is one licence: an account, or an API key.
+type Licence struct {
+	Name               string `json:"name"`
+	Kind               string `json:"kind"` // subscription | api-key
+	AccountUUID        string `json:"accountUuid,omitempty"`
+	Email              string `json:"email,omitempty"`
+	OrganizationUUID   string `json:"organizationUuid,omitempty"`
+	Sealed             string `json:"-"` // the grant or the key, encrypted at rest
+	RefreshFingerprint string `json:"-"`
+	AccessExpiresAt    int64  `json:"accessExpiresAt,omitempty"`
+	RefreshExpiresAt   int64  `json:"refreshExpiresAt,omitempty"`
+	Failures           int    `json:"failures"`
+	NotifiedAt         int64  `json:"-"`
+	AdoptedAt          int64  `json:"adoptedAt"`
+	RotatedAt          int64  `json:"rotatedAt,omitempty"`
+}
+
+// Binding is one consumer's binding and the generation it was last given (ADR 0206).
+type Binding struct {
+	Consumer   string `json:"consumer"`
+	Licence    string `json:"licence"`
+	Generation int64  `json:"generation"`
+}
+
+// Outcome is what became of a login the manager was offered, by its refresh token's fingerprint.
+type Outcome string
+
+const (
+	Adopted Outcome = "adopted"
+	Dead    Outcome = "dead"
+	Skipped Outcome = "skipped"
+	Refused Outcome = "refused"
+	Gone    Outcome = "gone"
+)
+
+// UsageRow is one usage reading.
+type UsageRow struct {
+	Licence string       `json:"licence"`
+	At      int64        `json:"at"`
+	Reading UsageReading `json:"reading"`
+}
+
+// Store is what the manager keeps.
+type Store interface {
+	Licences(ctx context.Context) ([]Licence, error)
+	Licence(ctx context.Context, name string) (*Licence, error)
+	LicenceForAccount(ctx context.Context, account string) (*Licence, error)
+	SaveLicence(ctx context.Context, l Licence) error
+	// Lease takes a lease for d, or answers false while another holder's is live.
+	Lease(ctx context.Context, key, holder string, d time.Duration) (bool, error)
+	Unlease(ctx context.Context, key, holder string) error
+	Bindings(ctx context.Context) ([]Binding, error)
+	Binding(ctx context.Context, consumer string) (*Binding, error)
+	// Bind binds (or switches) a consumer at the next generation.
+	Bind(ctx context.Context, consumer, licence string) (Binding, error)
+	Unbind(ctx context.Context, consumer string) (bool, error)
+	// Advance gives every consumer of a licence a new generation: what a rotation is to them.
+	Advance(ctx context.Context, licence string) ([]Binding, error)
+	Outcome(ctx context.Context, fingerprint string) (Outcome, error)
+	RecordOutcome(ctx context.Context, fingerprint, node, account string, o Outcome, why string) error
+	RecordUsage(ctx context.Context, licence string, at int64, r UsageReading, raw map[string]any) error
+	Usage(ctx context.Context, licence string, limit int) ([]UsageRow, error)
+	Audit(ctx context.Context, what string, detail map[string]any) error
+	Close()
+}
+
+// MemoryStore is the tests' store.
+type MemoryStore struct {
+	mu     sync.Mutex
+	now    func() time.Time
+	rows   map[string]Licence
+	binds  map[string]Binding
+	leases map[string]struct {
+		holder string
+		until  time.Time
+	}
+	outcomes   map[string]Outcome
+	usage      []UsageRow
+	Audits     []map[string]any
+	generation int64
+}
+
+// NewMemoryStore is an empty store whose leases age by now.
+func NewMemoryStore(now func() time.Time) *MemoryStore {
+	return &MemoryStore{now: now, rows: map[string]Licence{}, binds: map[string]Binding{},
+		leases: map[string]struct {
+			holder string
+			until  time.Time
+		}{}, outcomes: map[string]Outcome{}}
+}
+
+func (m *MemoryStore) Licences(context.Context) ([]Licence, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	out := make([]Licence, 0, len(m.rows))
+	for _, l := range m.rows {
+		out = append(out, l)
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
+	return out, nil
+}
+
+func (m *MemoryStore) Licence(_ context.Context, name string) (*Licence, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if l, ok := m.rows[name]; ok {
+		return &l, nil
+	}
+	return nil, nil
+}
+
+func (m *MemoryStore) LicenceForAccount(_ context.Context, account string) (*Licence, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	for _, l := range m.rows {
+		if l.AccountUUID == account {
+			return &l, nil
+		}
+	}
+	return nil, nil
+}
+
+func (m *MemoryStore) SaveLicence(_ context.Context, l Licence) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.rows[l.Name] = l
+	return nil
+}
+
+func (m *MemoryStore) Lease(_ context.Context, key, holder string, d time.Duration) (bool, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if held, ok := m.leases[key]; ok && held.until.After(m.now()) && held.holder != holder {
+		return false, nil
+	}
+	m.leases[key] = struct {
+		holder string
+		until  time.Time
+	}{holder, m.now().Add(d)}
+	return true, nil
+}
+
+func (m *MemoryStore) Unlease(_ context.Context, key, holder string) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.leases[key].holder == holder {
+		delete(m.leases, key)
+	}
+	return nil
+}
+
+func (m *MemoryStore) Bindings(context.Context) ([]Binding, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	out := make([]Binding, 0, len(m.binds))
+	for _, b := range m.binds {
+		out = append(out, b)
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Consumer < out[j].Consumer })
+	return out, nil
+}
+
+func (m *MemoryStore) Binding(_ context.Context, consumer string) (*Binding, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if b, ok := m.binds[consumer]; ok {
+		return &b, nil
+	}
+	return nil, nil
+}
+
+func (m *MemoryStore) Bind(_ context.Context, consumer, licence string) (Binding, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.generation++
+	b := Binding{Consumer: consumer, Licence: licence, Generation: m.generation}
+	m.binds[consumer] = b
+	return b, nil
+}
+
+func (m *MemoryStore) Unbind(_ context.Context, consumer string) (bool, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	_, ok := m.binds[consumer]
+	delete(m.binds, consumer)
+	return ok, nil
+}
+
+func (m *MemoryStore) Advance(_ context.Context, licence string) ([]Binding, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	var out []Binding
+	for c, b := range m.binds {
+		if b.Licence != licence {
+			continue
+		}
+		m.generation++
+		b.Generation = m.generation
+		m.binds[c] = b
+		out = append(out, b)
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Consumer < out[j].Consumer })
+	return out, nil
+}
+
+func (m *MemoryStore) Outcome(_ context.Context, fp string) (Outcome, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	return m.outcomes[fp], nil
+}
+
+func (m *MemoryStore) RecordOutcome(_ context.Context, fp, _, _ string, o Outcome, _ string) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.outcomes[fp] = o
+	return nil
+}
+
+func (m *MemoryStore) RecordUsage(_ context.Context, licence string, at int64, r UsageReading, _ map[string]any) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.usage = append(m.usage, UsageRow{Licence: licence, At: at, Reading: r})
+	return nil
+}
+
+func (m *MemoryStore) Usage(_ context.Context, licence string, limit int) ([]UsageRow, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	var out []UsageRow
+	for i := len(m.usage) - 1; i >= 0 && len(out) < limit; i-- {
+		if licence == "" || m.usage[i].Licence == licence {
+			out = append(out, m.usage[i])
+		}
+	}
+	return out, nil
+}
+
+func (m *MemoryStore) Audit(_ context.Context, what string, detail map[string]any) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	d := map[string]any{"what": what}
+	for k, v := range detail {
+		d[k] = v
+	}
+	m.Audits = append(m.Audits, d)
+	return nil
+}
+
+func (m *MemoryStore) Close() {}

modules/claude-licence-manager/cmd/claude-licence-manager/store_test.go

@@ -0,0 +1,125 @@
+package main
+
+import (
+	"context"
+	"os"
+	"strings"
+	"testing"
+	"time"
+)
+
+// Against a real postgres, because the questions are the database's: does the schema apply twice, does a
+// lease refuse a second holder, does a generation only grow. Skipped unless one is named:
+//
+//	docker run -d --rm --name licmgr-pg -e POSTGRES_PASSWORD=t -p 15498:5432 postgres:16-alpine
+//	MESH_TEST_POSTGRES=postgres://postgres:t@127.0.0.1:15498/postgres go test ./...
+func TestTheStoreOnPostgres(t *testing.T) {
+	url := os.Getenv("MESH_TEST_POSTGRES")
+	if url == "" {
+		t.Skip("MESH_TEST_POSTGRES unset")
+	}
+	ctx := context.Background()
+	s, err := OpenPgStore(ctx, url)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer s.Close()
+	for _, table := range []string{"binding", "licence", "lease", "offered", "usage", "audit"} {
+		_, _ = s.pool.Exec(ctx, "drop table if exists "+table+" cascade")
+	}
+	_, _ = s.pool.Exec(ctx, "drop sequence if exists binding_generation")
+	for i := 0; i < 2; i++ {
+		if err := s.Migrate(ctx); err != nil {
+			t.Fatalf("migration %d: %v", i+1, err)
+		}
+	}
+	l := Licence{Name: "a@example.org", Kind: "subscription", AccountUUID: "u-1", Email: "a@example.org", Sealed: "v1.x.y",
+		RefreshFingerprint: "sha256:1", AccessExpiresAt: 1, RefreshExpiresAt: 2, AdoptedAt: 3}
+	if err := s.SaveLicence(ctx, l); err != nil {
+		t.Fatal(err)
+	}
+	l.Failures = 2
+	_ = s.SaveLicence(ctx, l)
+	if got, _ := s.LicenceForAccount(ctx, "u-1"); got == nil || got.Failures != 2 || got.OrganizationUUID != "" {
+		t.Fatalf("%+v", got)
+	}
+	if none, err := s.Licence(ctx, "nobody"); none != nil || err != nil {
+		t.Fatalf("%v %v", none, err)
+	}
+	lease := func(holder string) bool {
+		ok, err := s.Lease(ctx, "licence:a", holder, time.Minute)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return ok
+	}
+	if !lease("one") || lease("two") || !lease("one") {
+		t.Fatal("a lease did not refuse a second holder, or its own holder could not renew it")
+	}
+	_ = s.Unlease(ctx, "licence:a", "one")
+	if !lease("two") {
+		t.Fatal("a released lease was not taken")
+	}
+	b1, _ := s.Bind(ctx, "laptop", l.Name)
+	adv, _ := s.Advance(ctx, l.Name)
+	b3, _ := s.Bind(ctx, "laptop", l.Name)
+	if len(adv) != 1 || !(b1.Generation < adv[0].Generation && adv[0].Generation < b3.Generation) {
+		t.Fatalf("generations %d %v %d", b1.Generation, adv, b3.Generation)
+	}
+	_ = s.RecordOutcome(ctx, "sha256:x", "laptop", "u-1", Dead, "400")
+	if o, _ := s.Outcome(ctx, "sha256:x"); o != Dead {
+		t.Fatalf("outcome %q", o)
+	}
+	if o, _ := s.Outcome(ctx, "sha256:none"); o != "" {
+		t.Fatalf("an unknown login is %q", o)
+	}
+	pct := 1.0
+	_ = s.RecordUsage(ctx, l.Name, 5, UsageReading{SessionPct: &pct}, map[string]any{})
+	if u, _ := s.Usage(ctx, "", 5); len(u) != 1 || *u[0].Reading.SessionPct != 1 {
+		t.Fatalf("usage %v", u)
+	}
+	if err := s.Audit(ctx, "bound", map[string]any{"consumer": "laptop"}); err != nil {
+		t.Fatal(err)
+	}
+	if ok, _ := s.Unbind(ctx, "laptop"); !ok {
+		t.Fatal("unbind")
+	}
+	all, _ := s.Licences(ctx)
+	if len(all) != 1 || !strings.HasPrefix(all[0].Sealed, "v1.") {
+		t.Fatalf("%v", all)
+	}
+}
+
+func TestARefreshThatDoesNotRotateKeepsTheRefreshToken(t *testing.T) {
+	prev := FullGrant{AccessToken: "a", RefreshToken: "r", ExpiresAt: 1}
+	in := int64(60)
+	kept := NextGrant(prev, tokenResponse{AccessToken: "a2", ExpiresIn: &in}, 1000)
+	if !kept.OK || kept.Grant.RefreshToken != "r" || kept.Grant.ExpiresAt != 61_000 {
+		t.Fatalf("%+v", kept)
+	}
+	rotated := NextGrant(prev, tokenResponse{AccessToken: "a3", RefreshToken: "r2"}, 0)
+	if rotated.Grant.RefreshToken != "r2" {
+		t.Fatalf("%+v", rotated)
+	}
+	if NextGrant(prev, tokenResponse{}, 0).OK {
+		t.Fatal("an answer with no access token was a grant")
+	}
+}
+
+func TestAGrantAtRestOpensOnlyWithItsKey(t *testing.T) {
+	a, _ := NewCrypt("one key")
+	b, _ := NewCrypt("another key")
+	sealed := a.Seal(`{"refreshToken":"rt"}`)
+	if strings.Contains(sealed, "rt") {
+		t.Fatal("stored in the clear")
+	}
+	if got, err := a.Open(sealed); err != nil || got != `{"refreshToken":"rt"}` {
+		t.Fatalf("%q %v", got, err)
+	}
+	if _, err := b.Open(sealed); err == nil {
+		t.Fatal("opened with another key")
+	}
+	if _, err := NewCrypt("  "); err == nil {
+		t.Fatal("an empty key was accepted")
+	}
+}

modules/claude-licence-manager/cmd/claude-licence-manager/testdata/sealed-by-typescript.json

@@ -0,0 +1,12 @@
+{
+  "privateKey": "-----BEGIN PRIVATE KEY-----\nMC4CAQAwBQYDK2VuBCIEIAi2NK/bN+p7cqYUwv/kz72TgLdmJUfOHCDZTrMpQzpS\n-----END PRIVATE KEY-----\n",
+  "publicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VuAyEARYvD/w+9ah0KWS9T9pd6Ea6CBymUE48vEVk983QPKyY=\n-----END PUBLIC KEY-----\n",
+  "box": {
+    "v": 1,
+    "eph": "MCowBQYDK2VuAyEAIYlSGrJvF8qSjR1aTFWbEQM/NFbZXrarglN0aRLZZ0E=",
+    "iv": "ABqT/hMukn6+xpjh",
+    "tag": "POzmsWTPHSn9xLMMJJ9Akg==",
+    "ct": "m2u0kuQ0PwrsGelM99Z5aBw6FCd6lFISUbwiK5TzzDw4ZrGtsHEvxytoIeFC"
+  },
+  "plaintext": "a grant sealed by the TypeScript agent module"
+}

modules/claude-licence-manager/cmd/claude-licence-manager/vendor.go

@@ -0,0 +1,187 @@
+package main
+
+// The only file that talks to Anthropic (novox/hq ADR 0183): the token endpoint, which this module alone
+// calls — one rotation source — and the usage endpoint. Ported from the predecessor's manager, whose
+// client id and error handling were each earned by an incident.
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"strings"
+	"time"
+)
+
+// The public Claude Code client's id: not a secret, and a hard-won constant — a metadata URL in its place
+// answers 400, which the predecessor once misdiagnosed as a dead grant.
+const clientID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e"
+
+func tokenEndpoint() string {
+	if v := os.Getenv("MESH_ANTHROPIC_TOKEN_ENDPOINT"); v != "" {
+		return v
+	}
+	return "https://platform.claude.com/v1/oauth/token"
+}
+
+func usageEndpoint() string {
+	if v := os.Getenv("MESH_ANTHROPIC_USAGE_ENDPOINT"); v != "" {
+		return v
+	}
+	return "https://api.anthropic.com/api/oauth/usage"
+}
+
+// FullGrant is a subscription's grant as this module keeps it: what the agent's credentials file calls
+// `claudeAiOauth`.
+type FullGrant struct {
+	AccessToken           string   `json:"accessToken"`
+	RefreshToken          string   `json:"refreshToken"`
+	ExpiresAt             int64    `json:"expiresAt"`
+	RefreshTokenExpiresAt *int64   `json:"refreshTokenExpiresAt,omitempty"`
+	Scopes                []string `json:"scopes,omitempty"`
+	SubscriptionType      string   `json:"subscriptionType,omitempty"`
+	RateLimitTier         string   `json:"rateLimitTier,omitempty"`
+}
+
+// Refreshed is what a refresh came to: the next grant and the account the vendor answered for, or why not.
+type Refreshed struct {
+	OK      bool
+	Grant   FullGrant
+	Account string // empty when the vendor named none
+	Status  int
+	Reason  string
+}
+
+// Vendor is the vendor as the manager reaches it; a test stubs it.
+type Vendor interface {
+	Refresh(ctx context.Context, g FullGrant) Refreshed
+	Usage(ctx context.Context, accessToken string) (map[string]any, error)
+}
+
+type tokenResponse struct {
+	AccessToken           string   `json:"access_token"`
+	RefreshToken          string   `json:"refresh_token"`
+	ExpiresIn             *int64   `json:"expires_in"`
+	RefreshTokenExpiresIn *int64   `json:"refresh_token_expires_in"`
+	Scope                 string   `json:"scope"`
+	Scopes                []string `json:"scopes"`
+	SubscriptionType      string   `json:"subscription_type"`
+	Account               *struct {
+		UUID string `json:"uuid"`
+	} `json:"account"`
+}
+
+// NextGrant is the grant a refresh answered, laid over the one refreshed: a refresh token the vendor did
+// not rotate is kept, so a rotating vendor and one that does not are both handled.
+func NextGrant(prev FullGrant, r tokenResponse, nowMs int64) Refreshed {
+	if r.AccessToken == "" {
+		return Refreshed{Status: 200, Reason: "the vendor answered without an access token"}
+	}
+	g := prev
+	g.AccessToken = r.AccessToken
+	if r.RefreshToken != "" {
+		g.RefreshToken = r.RefreshToken
+	}
+	if r.ExpiresIn != nil {
+		g.ExpiresAt = nowMs + *r.ExpiresIn*1000
+	}
+	if r.RefreshTokenExpiresIn != nil {
+		v := nowMs + *r.RefreshTokenExpiresIn*1000
+		g.RefreshTokenExpiresAt = &v
+	}
+	if len(r.Scopes) > 0 {
+		g.Scopes = r.Scopes
+	} else if r.Scope != "" {
+		g.Scopes = strings.Fields(r.Scope)
+	}
+	if r.SubscriptionType != "" {
+		g.SubscriptionType = r.SubscriptionType
+	}
+	out := Refreshed{OK: true, Grant: g}
+	if r.Account != nil {
+		out.Account = r.Account.UUID
+	}
+	return out
+}
+
+type liveVendor struct{ client *http.Client }
+
+// LiveVendor is the vendor over the network.
+func LiveVendor() Vendor { return liveVendor{client: &http.Client{Timeout: 30 * time.Second}} }
+
+func (v liveVendor) Refresh(ctx context.Context, g FullGrant) Refreshed {
+	form := url.Values{"grant_type": {"refresh_token"}, "refresh_token": {g.RefreshToken}, "client_id": {clientID}}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, tokenEndpoint(), strings.NewReader(form.Encode()))
+	if err != nil {
+		return Refreshed{Reason: err.Error()}
+	}
+	req.Header.Set("content-type", "application/x-www-form-urlencoded")
+	resp, err := v.client.Do(req)
+	if err != nil {
+		return Refreshed{Reason: "the token endpoint did not answer: " + err.Error()}
+	}
+	defer resp.Body.Close()
+	body, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if resp.StatusCode/100 != 2 {
+		// The body, never only the status: a malformed request and a revoked grant both answer 400.
+		reason := string(body)
+		if len(reason) > 400 {
+			reason = reason[:400]
+		}
+		return Refreshed{Status: resp.StatusCode, Reason: reason}
+	}
+	var r tokenResponse
+	if err := json.Unmarshal(body, &r); err != nil {
+		return Refreshed{Status: resp.StatusCode, Reason: "the vendor's answer is not JSON"}
+	}
+	return NextGrant(g, r, time.Now().UnixMilli())
+}
+
+func (v liveVendor) Usage(ctx context.Context, accessToken string) (map[string]any, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, usageEndpoint(), nil)
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("authorization", "Bearer "+accessToken)
+	resp, err := v.client.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode/100 != 2 {
+		return nil, fmt.Errorf("the usage endpoint answered %d", resp.StatusCode)
+	}
+	var out map[string]any
+	return out, json.NewDecoder(resp.Body).Decode(&out)
+}
+
+// UsageReading is the licence-grain reading (ADR 0054), flattened from the vendor's windows.
+type UsageReading struct {
+	SessionPct      *float64 `json:"sessionPct"`
+	SessionResetsAt string   `json:"sessionResetsAt,omitempty"`
+	WeeklyPct       *float64 `json:"weeklyPct"`
+	SonnetPct       *float64 `json:"sonnetPct"`
+}
+
+// FlattenUsage reads the windows the predecessor read.
+func FlattenUsage(u map[string]any) UsageReading {
+	window := func(k string) (*float64, string) {
+		w, ok := u[k].(map[string]any)
+		if !ok {
+			return nil, ""
+		}
+		pct, ok := w["utilization"].(float64)
+		resets, _ := w["resets_at"].(string)
+		if !ok {
+			return nil, resets
+		}
+		return &pct, resets
+	}
+	s, resets := window("five_hour")
+	w, _ := window("seven_day")
+	so, _ := window("seven_day_sonnet")
+	return UsageReading{SessionPct: s, SessionResetsAt: resets, WeeklyPct: w, SonnetPct: so}
+}

modules/claude-licence-manager/go.mod

@@ -0,0 +1,16 @@
+module claude-licence-manager
+
+go 1.25.0
+
+require (
+	git.novox.be/novox/mesh-sdk/go v0.1.7
+	github.com/jackc/pgx/v5 v5.11.0
+)
+
+require (
+	github.com/jackc/pgpassfile v1.0.0 // indirect
+	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
+	github.com/jackc/puddle/v2 v2.2.2 // indirect
+	golang.org/x/sync v0.17.0 // indirect
+	golang.org/x/text v0.29.0 // indirect
+)

modules/claude-licence-manager/go.sum

@@ -0,0 +1,28 @@
+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=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
+github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
+github.com/jackc/pgx/v5 v5.11.0 h1:IzBBtyK9AHqf98cctWFifYSci2hgQR/cd56wB4p+ogg=
+github.com/jackc/pgx/v5 v5.11.0/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4=
+github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
+github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+golang.org/x/sync v0.17.0 h1:l60nONMj9l5drqw6jlhIELNv9I0A4OFgRsG9k2oT9Ug=
+golang.org/x/sync v0.17.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
+golang.org/x/text v0.29.0 h1:1neNs90w9YzJ9BocxfsQNHKuAT4pkghyXc4nhZ6sJvk=
+golang.org/x/text v0.29.0/go.mod h1:7MhJOA9CD2qZyOKYazxdYMF85OwPdEr9jTtBpO7ydH4=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

modules/claude-licence-manager/module.json

@@ -0,0 +1,132 @@
+{
+  "module": "claude-licence-manager",
+  "version": "1",
+  "slug": "licmgr",
+  "requires": [
+    "postgres-database",
+    "secret"
+  ],
+  "contributes": {
+    "postgres-database": {
+      "name": "claude_licences"
+    }
+  },
+  "binds": {
+    "postgres-database": "${dir:state}/database.json"
+  },
+  "secrets": {
+    "postgres-database": "${dir:state}/database.secret",
+    "secret": {
+      "grant-key": "${dir:state}/grant.key"
+    }
+  },
+  "seats": [
+    {
+      "name": "anthropic-licence-manager",
+      "scope": "mesh",
+      "serves": [
+        "licences",
+        "bindings",
+        "bind",
+        "switch",
+        "release",
+        "refresh",
+        "usage",
+        "adopt",
+        "current",
+        "public-key"
+      ]
+    }
+  ],
+  "claims": [
+    {
+      "name": "anthropic-licence-manager",
+      "scope": "mesh",
+      "serves": [
+        "licences",
+        "bindings",
+        "bind",
+        "switch",
+        "release",
+        "refresh",
+        "usage",
+        "adopt",
+        "current",
+        "public-key"
+      ]
+    }
+  ],
+  "emits": [
+    "licence.adopted",
+    "licence.refused",
+    "licence.failing",
+    "usage.read"
+  ],
+  "state": [
+    "bindings"
+  ],
+  "reads": [
+    "claude-code.holdings"
+  ],
+  "resources": [
+    {
+      "id": "state",
+      "type": "directory",
+      "mode": "0700",
+      "place": "."
+    },
+    {
+      "id": "database-url",
+      "type": "file",
+      "path": "${dir:state}/database.url",
+      "mode": "0600",
+      "content": "postgresql://${bound:postgres-database:as}:${secret:postgres-database}@${bound:postgres-database:at}:${bound:postgres-database:port}/${bound:postgres-database:as}\n"
+    },
+    {
+      "id": "settings",
+      "type": "file",
+      "path": "${dir:state}/settings.json",
+      "mode": "0600",
+      "merge": "json",
+      "content": "{\n  \"cadence_minutes\": 240,\n  \"floor_minutes\": 60,\n  \"failures_to_notify\": 3,\n  \"cooldown_hours\": 24,\n  \"refresh_warn_days\": 3\n}\n"
+    },
+    {
+      "id": "prepare",
+      "type": "process",
+      "name": "claude-licence-manager-prepare",
+      "artifact": "code",
+      "run": [
+        "./claude-licence-manager",
+        "prepare"
+      ],
+      "run-once": true,
+      "env": {
+        "DATABASE_URL_FILE": "${dir:state}/database.url"
+      },
+      "restart-on": [
+        "database-url"
+      ]
+    }
+  ],
+  "build": {
+    "artifacts": [
+      {
+        "name": "code",
+        "kind": "bundle",
+        "language": "go",
+        "system": "arch",
+        "from": "cmd/claude-licence-manager",
+        "binary": "claude-licence-manager",
+        "loads": [
+          "claude-licence-manager"
+        ],
+        "env": {
+          "DATABASE_URL_FILE": "${dir:state}/database.url",
+          "MESH_LICENCE_STATE": "${dir:state}",
+          "MESH_LICENCE_KEY_FILE": "${dir:state}/grant.key",
+          "MESH_LICENCE_SETTINGS": "${dir:state}/settings.json"
+        }
+      }
+    ]
+  }
+}

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)
+	}
+}