Merge pull request 'The licence manager's verb is public-key' (#274) from fix/the-verb-is-public-key into main

public_key failed the builder's manifest check and stopped the manager's
rebuild; claude-code asks the new name.

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/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

@@ -33,18 +33,19 @@ this node a subscription token. Nothing else under the home is read or written.
 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 0202).
+must see, a node that joins later included — kept, so it carries no secret either (hq ADR 0201).
 
 | what | how |
 |---|---|
-| the licence manager rotated a licence, or switched this node | its `licence.rotated` / `licence.switched` event; this module then asks `anthropic-licence-manager.current` for its token, sealed to the key it sends |
-| this node starts | it asks `current` once, so a node that was off catches up |
-| a person ran `/login` here | the credentials file gains a refresh token this module never writes; it asks `anthropic-licence-manager.adopt` at once with the grant sealed to the manager's key — the one time a refresh token travels, because the login made the manager's stale |
+| 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_mcp_list`,
+`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`.
 
@@ -72,3 +73,9 @@ Remove these by hand, once; the mesh removes nothing it did not make (ADR 0182):
 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/grant.ts

@@ -1,112 +0,0 @@
-// The agent's credentials file, and whether an offered grant may replace what it holds (novox/hq
-// ADR 0183, 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 never holds a refresh token, so the
-// one this module writes never carries one, and a full grant a login left behind is stripped the
-// moment the manager hands the node its own.
-//
-// 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 { readFileSync, renameSync, writeFileSync, mkdirSync } from "node:fs";
-import { dirname } from "node:path";
-
-export interface Grant {
-  readonly accessToken: string;
-  readonly expiresAt: number;
-  readonly refreshTokenExpiresAt?: number | null;
-  readonly scopes?: readonly string[] | null;
-  readonly subscriptionType?: string | null;
-  readonly rateLimitTier?: string | null;
-}
-
-export type ApplySource = "rotation" | "switch";
-
-export type ApplyDecision =
-  | { apply: true; reissued?: boolean }
-  | { apply: false; reason: "already-current" }
-  | { apply: false; reason: "not-newer"; localExpiresAt: number };
-
-/** Two refresh-token expiries within a day are one lineage; a login starts a fresh window weeks away. */
-export const GENERATION_TOLERANCE_MS = 24 * 60 * 60 * 1000;
-
-export function sameGeneration(a?: number | null, b?: number | null): boolean {
-  if (a == null || b == null) return true;
-  return Math.abs(Number(a) - Number(b)) <= GENERATION_TOLERANCE_MS;
-}
-
-export function decideApply(local: Grant | null | undefined, offered: Grant, source: ApplySource): ApplyDecision {
-  if (!local?.accessToken) return { apply: true };
-  if (local.accessToken === offered.accessToken) return { apply: false, reason: "already-current" };
-  const reissued = !sameGeneration(local.refreshTokenExpiresAt, offered.refreshTokenExpiresAt);
-  if (source === "rotation" && !reissued && Number(local.expiresAt) >= Number(offered.expiresAt)) {
-    return { apply: false, reason: "not-newer", localExpiresAt: Number(local.expiresAt) };
-  }
-  return reissued ? { apply: true, reissued: true } : { apply: true };
-}
-
-type Oauth = Record<string, unknown> & { accessToken?: string; refreshToken?: string; expiresAt?: number };
-type Credentials = Record<string, unknown> & { claudeAiOauth?: Oauth };
-
-export function readCredentials(path: string): Credentials | null {
-  try {
-    const parsed = JSON.parse(readFileSync(path, "utf8")) as Credentials;
-    return parsed && typeof parsed === "object" ? parsed : null;
-  } catch {
-    return null;
-  }
-}
-
-/** The grant the file holds, or null. */
-export function grantOf(creds: Credentials | null): Grant | null {
-  const o = creds?.claudeAiOauth;
-  if (!o?.accessToken) return null;
-  return {
-    accessToken: o.accessToken,
-    expiresAt: Number(o.expiresAt ?? 0),
-    refreshTokenExpiresAt: o.refreshTokenExpiresAt == null ? null : Number(o.refreshTokenExpiresAt),
-  };
-}
-
-/** Does the file hold a full grant — a refresh token this module never writes, so a person's login? */
-export function holdsLogin(creds: Credentials | null): boolean {
-  return typeof creds?.claudeAiOauth?.refreshToken === "string" && creds.claudeAiOauth.refreshToken.length > 0;
-}
-
-/**
- * The handed grant laid over what is there — a rotation of the licence the node already holds — or,
- * for a switch, in place of it: the old licence's grant goes whole, scopes and subscription included,
- * and only keys outside the grant (another kind of credential the vendor keeps in the file) stay.
- * Either way, no refresh token survives.
- */
-export function replacedBy(local: Credentials | null, grant: Grant): Credentials {
-  const next: Credentials = { ...(local ?? {}) };
-  delete next.claudeAiOauth;
-  return withGrant(next, grant);
-}
-
-/** Overlay the handed grant on what is there, and delete any refresh token. */
-export function withGrant(local: Credentials | null, grant: Grant): Credentials {
-  const next: Credentials = { ...(local ?? {}) };
-  const oauth: Oauth = { ...(local?.claudeAiOauth ?? {}) };
-  oauth.accessToken = grant.accessToken;
-  oauth.expiresAt = grant.expiresAt;
-  for (const k of ["refreshTokenExpiresAt", "scopes", "subscriptionType", "rateLimitTier"] as const) {
-    const v = grant[k];
-    if (v != null) oauth[k] = v as unknown;
-  }
-  delete oauth.refreshToken;
-  next.claudeAiOauth = oauth;
-  return next;
-}
-
-/** Write atomically at 0600: a partial credentials file must never be read as a whole one. */
-export function writeCredentials(path: string, creds: Credentials): void {
-  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-  const tmp = `${path}.mesh-tmp`;
-  writeFileSync(tmp, JSON.stringify(creds, null, 2) + "\n", { mode: 0o600 });
-  renameSync(tmp, path);
-}

modules/claude-code/identity.ts

@@ -1,50 +0,0 @@
-// 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 attribute a login; written,
-// three keys and nothing else, when a licence is switched, so the file Claude Code shows the account from
-// names the account whose token it now holds (as the predecessor learned: two files that disagree make
-// a later login look like the wrong account).
-
-import { readFileSync, renameSync, writeFileSync } from "node:fs";
-
-export interface Identity {
-  readonly accountUuid: string;
-  readonly emailAddress?: string;
-  readonly organizationUuid?: string;
-}
-
-export function readIdentity(stateFile: string): Identity | null {
-  try {
-    const raw = JSON.parse(readFileSync(stateFile, "utf8")) as { oauthAccount?: Record<string, unknown> };
-    const a = raw.oauthAccount;
-    if (!a || typeof a.accountUuid !== "string") return null;
-    return {
-      accountUuid: a.accountUuid,
-      emailAddress: typeof a.emailAddress === "string" ? a.emailAddress : undefined,
-      organizationUuid: typeof a.organizationUuid === "string" ? a.organizationUuid : undefined,
-    };
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Point the state file's account at `id`, keeping every other key as found. Returns whether the file
- * changed; a file that cannot be read as an object is left alone rather than replaced.
- */
-export function writeIdentity(stateFile: string, id: Identity): boolean {
-  let raw: Record<string, unknown>;
-  try {
-    raw = JSON.parse(readFileSync(stateFile, "utf8")) as Record<string, unknown>;
-    if (!raw || typeof raw !== "object") return false;
-  } catch {
-    raw = {};
-  }
-  const current = (raw.oauthAccount ?? {}) as Record<string, unknown>;
-  if (current.accountUuid === id.accountUuid && current.emailAddress === id.emailAddress
-      && current.organizationUuid === id.organizationUuid) return false;
-  raw.oauthAccount = { ...current, accountUuid: id.accountUuid, emailAddress: id.emailAddress, organizationUuid: id.organizationUuid };
-  const tmp = `${stateFile}.mesh-tmp`;
-  writeFileSync(tmp, JSON.stringify(raw, null, 2), { mode: 0o600 });
-  renameSync(tmp, stateFile);
-  return true;
-}

modules/claude-code/module.json

@@ -11,17 +11,19 @@
   "binds": {
     "mcp-endpoint": "${dir:state}/mcp-endpoint.json"
   },
-  "consumes": [
-    "claude-licence-manager.licence.rotated",
-    "claude-licence-manager.licence.switched"
-  ],
   "state": [
-    "servers"
+    "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"
@@ -75,9 +77,12 @@
       {
         "name": "tools",
         "kind": "bundle",
-        "language": "typescript",
-        "entrypoints": [
-          "tools/index.js"
+        "language": "go",
+        "system": "arch",
+        "from": "cmd/claude-code",
+        "binary": "claude-code",
+        "loads": [
+          "claude-code"
         ],
         "env": {
           "MESH_CLAUDE_CODE_STATE": "${dir:state}",

modules/claude-code/node.ts

@@ -1,271 +0,0 @@
-// What claude-code does on a node, written against two things it is handed — a way to ask a tool on the
-// bus and a way to emit an event — so every path is tested without a bus (novox/hq design 36 §4–§5,
-// ADR 0183, ADR 0198).
-//
-// **Over NATS, in two kinds** (design 32 §10): an event says that something happened and carries no
-// secret, because a stream keeps it; a token travels on a request, which nothing keeps. So:
-//   - the licence manager's `licence.rotated` and `licence.switched` events tell this module to ask the
-//     seat for its current token, sealed to the key it sends with the request;
-//   - a login a person made here — a refresh token this module never writes — is offered to the seat at
-//     once, sealed to the seat's key: the one moment a refresh token travels, because the login made the
-//     manager's stale;
-//   - an MCP server registered through this module is **state, not an event** (novox/hq ADR 0202): one
-//     key per server in the module's `servers` bucket — `all.<server>` for every node, `<node>.<server>`
-//     for one — which every node watches. A node that joins later, or was off, reads the whole current set
-//     at start; unregistering is a delete. A secret never goes in an entry: the runtime refuses one.
-
-import { chmodSync, existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-
-import { render, entryProblem, MANAGED_DIR, type Binding, type Facts, type Settings, type Servers } from "./render.js";
-import { generateKeyPair, open, seal, type SealedBox } from "./seal.js";
-import { decideApply, grantOf, holdsLogin, readCredentials, replacedBy, withGrant, writeCredentials, type Grant } from "./grant.js";
-import { readIdentity, writeIdentity, type Identity } from "./identity.js";
-
-export const SEAT = "anthropic-licence-manager";
-
-export interface Paths {
-  state: string;
-  facts: string;
-  settings: string;
-  home: string;
-  node: string;
-}
-
-/** A tool on the bus: its address and arguments in, its JSON answer out. */
-export type Ask = (address: string, args: Record<string, unknown>) => Promise<unknown>;
-/** An event of this module's, by its local name. */
-export type Emit = (type: string, body: unknown) => Promise<void>;
-/** Write one managed file; answers what happened. */
-export type WriteManaged = (name: string, content: string) => string;
-
-export const readJson = <T>(p: string, fallback: T): T => {
-  try {
-    return JSON.parse(readFileSync(p, "utf8")) as T;
-  } catch {
-    return fallback;
-  }
-};
-
-const credentialsPath = (p: Paths) => join(p.home, ".claude", ".credentials.json");
-const accountPath = (p: Paths) => join(p.home, ".claude.json");
-const bindingPath = (p: Paths) => join(p.state, "licence.json");
-const apiKeyPath = (p: Paths) => join(p.state, "api-key");
-export const helperPath = (p: Paths) => join(p.state, "api-key-helper");
-const keyPath = (p: Paths) => join(p.state, "key.pem");
-const pubPath = (p: Paths) => join(p.state, "key.pub.pem");
-const registryPath = (p: Paths) => join(p.state, "mcp-servers.json");
-
-export function keypair(p: Paths): { publicKey: string; privateKey: string } {
-  if (!existsSync(keyPath(p))) {
-    const k = generateKeyPair();
-    writeFileSync(keyPath(p), k.privateKey, { mode: 0o600 });
-    writeFileSync(pubPath(p), k.publicKey, { mode: 0o644 });
-  }
-  return { privateKey: readFileSync(keyPath(p), "utf8"), publicKey: readFileSync(pubPath(p), "utf8") };
-}
-
-export function registered(p: Paths): Servers {
-  return readJson<Servers>(registryPath(p), {});
-}
-
-export function renderNow(p: Paths, write: WriteManaged): string[] {
-  const facts = readJson<Facts | null>(p.facts, null);
-  if (!facts?.console) throw new Error(`the mesh has not rendered ${p.facts} yet; nothing to write`);
-  const files = render(facts, readJson<Settings>(p.settings, {}), readJson<Binding | null>(bindingPath(p), null),
-    helperPath(p), registered(p));
-  return Object.entries(files).map(([name, content]) => write(name, content));
-}
-
-// ---- the licence ----------------------------------------------------------------------------------
-
-/** What the seat answers to `current`: the licence this node is bound to and its token, sealed. */
-export interface Current {
-  licence: string;
-  kind: "subscription" | "api-key";
-  sealed: SealedBox;
-  identity?: Identity | null;
-}
-
-/** Ask the seat for this node's current token and apply it. */
-export async function pull(p: Paths, ask: Ask, write: WriteManaged): Promise<Record<string, unknown>> {
-  const answer = (await ask(`${SEAT}.current`, { node: p.node, public_key: keypair(p).publicKey })) as Current | null;
-  if (!answer?.sealed) return { applied: false, reason: "the seat holds no licence for this node" };
-  return apply(p, answer, write);
-}
-
-/** Apply what the seat handed over. A switch replaces the grant whole and cleans up after the old licence. */
-export function apply(p: Paths, handed: Current, write: WriteManaged): Record<string, unknown> {
-  const plain = open(handed.sealed, keypair(p).privateKey);
-  const previous = readJson<Binding | null>(bindingPath(p), null);
-  const switched = previous?.licence !== handed.licence;
-  let outcome: Record<string, unknown> = { applied: true, licence: handed.licence, kind: handed.kind, switched };
-  if (handed.kind === "api-key") {
-    writeFileSync(apiKeyPath(p), plain.trim() + "\n", { mode: 0o600 });
-    writeFileSync(helperPath(p), `#!/bin/sh\nexec cat '${apiKeyPath(p)}'\n`, { mode: 0o700 });
-    chmodSync(helperPath(p), 0o700);
-  } else {
-    const grant = JSON.parse(plain) as Grant;
-    const local = readCredentials(credentialsPath(p));
-    const d = decideApply(grantOf(local), grant, switched ? "switch" : "rotation");
-    if (d.apply) writeCredentials(credentialsPath(p), switched ? replacedBy(local, grant) : withGrant(local, grant));
-    else outcome = { applied: false, licence: handed.licence, reason: "reason" in d ? d.reason : undefined }; // narrowed by hand: the build compiles without strict
-    // Away from the API key: it goes, with its helper.
-    rmSync(apiKeyPath(p), { force: true });
-    rmSync(helperPath(p), { force: true });
-  }
-  if (switched && handed.identity?.accountUuid) {
-    outcome.account = writeIdentity(accountPath(p), handed.identity) ? "updated" : "unchanged";
-  }
-  writeFileSync(bindingPath(p), JSON.stringify({ licence: handed.licence, kind: handed.kind }) + "\n", { mode: 0o600 });
-  try {
-    outcome.rendered = renderNow(p, write); // the key-helper comes or goes with the licence's kind
-  } catch (err) {
-    outcome.rendered = { failed: err instanceof Error ? err.message : String(err) };
-  }
-  return outcome;
-}
-
-/** A licence event from the manager: is it for this node? */
-export function concerns(p: Paths, type: string, body: { licence?: string; node?: string }): boolean {
-  if (type.endsWith("licence.switched")) return body.node === p.node;
-  if (type.endsWith("licence.rotated")) return body.licence === readJson<Binding | null>(bindingPath(p), null)?.licence;
-  return false;
-}
-
-/** A refresh token in the credentials file is a login: this module never writes one. Offer it to the seat. */
-export async function offerLogin(p: Paths, ask: Ask): Promise<Record<string, unknown> | null> {
-  const creds = readCredentials(credentialsPath(p));
-  if (!holdsLogin(creds)) return null;
-  const key = (await ask(`${SEAT}.public_key`, {})) as { public_key?: string } | null;
-  if (!key?.public_key) throw new Error("the licence manager did not say what key to seal a login to");
-  return (await ask(`${SEAT}.adopt`, {
-    node: p.node,
-    identity: readIdentity(accountPath(p)),
-    sealed: seal(JSON.stringify(creds!.claudeAiOauth), key.public_key),
-  })) as Record<string, unknown>;
-}
-
-// ---- MCP servers ----------------------------------------------------------------------------------
-
-export interface Registration {
-  name: string;
-  entry?: Record<string, unknown>;
-  /** Which nodes: this one (absent), every node running the module ("all"), or a list. */
-  nodes?: "all" | string[];
-}
-
-/** The `servers` state, as this module reaches it through the runtime (`state("servers")` in the SDK). */
-export interface ServerState {
-  put(key: string, value: Record<string, unknown>): Promise<number>;
-  delete(key: string): Promise<void>;
-  keys(): Promise<string[]>;
-}
-
-/** One change to the `servers` state, as a watch hands it over. */
-export interface ServerChange {
-  key: string;
-  op: "put" | "delete";
-  value?: Record<string, unknown>;
-}
-
-/** The key a registration lives at: `all.<server>` for every node, `<node>.<server>` for one. */
-export const keyOf = (scope: string, name: string) => `${scope}.${name}`;
-
-/**
- * What this node takes from the `servers` state: the entries for every node and for this one, by key —
- * kept in memory from the watch, and written through to the module's own file whenever what applies here
- * changes, so the managed directory can be rendered without the bus.
- */
-export class ServerView {
-  private readonly entries = new Map<string, Record<string, unknown>>();
-  constructor(private readonly p: Paths) {}
-
-  /** Take one change; answers whether what applies to this node changed. */
-  take(c: ServerChange): boolean {
-    const dot = c.key.indexOf(".");
-    const scope = c.key.slice(0, dot), name = c.key.slice(dot + 1);
-    if (dot <= 0 || (scope !== "all" && scope !== this.p.node)) return false;
-    if (c.op === "put" && c.value && entryProblem(name, c.value) === null) this.entries.set(c.key, c.value);
-    else this.entries.delete(c.key);
-    return this.writeThrough();
-  }
-
-  /** What applies here: every node's entries, with this node's own laid over them by server name. */
-  effective(): Servers {
-    const out: Record<string, Record<string, unknown>> = {};
-    for (const scope of ["all", this.p.node]) {
-      for (const [key, entry] of [...this.entries].sort(([a], [b]) => a.localeCompare(b))) {
-        if (key.startsWith(scope + ".")) out[key.slice(scope.length + 1)] = entry;
-      }
-    }
-    return out;
-  }
-
-  private writeThrough(): boolean {
-    const now = JSON.stringify(this.effective(), null, 2) + "\n";
-    let before = "";
-    try {
-      before = readFileSync(registryPath(this.p), "utf8");
-    } catch {
-      /* none yet */
-    }
-    if (now === before) return false;
-    writeFileSync(registryPath(this.p), now, { mode: 0o600 });
-    return true;
-  }
-}
-
-/** A change from the watch: take it, and render when what applies here changed. */
-export function onServerChange(view: ServerView, c: ServerChange, p: Paths, write: WriteManaged): string | null {
-  if (!view.take(c)) return null;
-  renderNow(p, write);
-  return `${c.op === "put" ? "registered" : "unregistered"} ${c.key}`;
-}
-
-const scopesOf = (p: Paths, nodes: Registration["nodes"]): string[] =>
-  nodes === undefined ? [p.node] : nodes === "all" ? ["all"] : nodes;
-
-/**
- * Register (or with no entry, unregister) 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.
- */
-export async function registerServer(p: Paths, r: Registration, servers: ServerState, view: ServerView,
-                                     write: WriteManaged, others: () => Promise<string[]>): Promise<Record<string, unknown>> {
-  if (r.entry) {
-    const problem = entryProblem(r.name, r.entry);
-    if (problem) return { registered: false, reason: problem };
-  }
-  const scopes = scopesOf(p, r.nodes);
-  // 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.
-  const before = JSON.stringify(view.effective());
-  for (const scope of scopes) {
-    const key = keyOf(scope, r.name);
-    if (r.entry) await servers.put(key, r.entry);
-    else await servers.delete(key);
-    view.take({ key, op: r.entry ? "put" : "delete", value: r.entry });
-  }
-  const changedHere = JSON.stringify(view.effective()) !== before;
-  const here = scopes.includes("all") || scopes.includes(p.node);
-  const answer: Record<string, unknown> = {
-    [r.entry ? "registered" : "unregistered"]: r.name,
-    on: r.nodes === undefined ? [p.node] : r.nodes,
-    here: here ? (changedHere ? "changed" : "already so") : "not this node",
-    rendered: changedHere ? renderNow(p, write) : [],
-  };
-  if (!r.entry && view.effective()[r.name]) {
-    answer.still = `${r.name} still applies here from another registration (for every node, or for this one); unregister that too`;
-  }
-  if (r.nodes === undefined) {
-    // The question the operator wanted asked: here only, or more?
-    const elsewhere = (await others().catch(() => [] as string[])).filter((n) => n !== p.node);
-    answer.also = elsewhere.length
-      ? `claude-code also runs on ${elsewhere.join(", ")}. To ${r.entry ? "register" : "unregister"} it there too, call again with nodes: "all" or a list of those nodes.`
-      : `To do the same on every node running claude-code, call again with nodes: "all".`;
-  }
-  return answer;
-}
-
-export { MANAGED_DIR };

modules/claude-code/package.json

@@ -1,18 +0,0 @@
-{
-  "name": "@novox/module-claude-code",
-  "version": "0.1.0",
-  "description": "claude-code — the operator's agent on a machine: its managed configuration, and the consumer side of the Anthropic licence manager (novox/hq design 36).",
-  "type": "module",
-  "private": true,
-  "scripts": {
-    "build": "tsc seal.ts grant.ts identity.ts render.ts node.ts tools/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --rootDir . --outDir dist",
-    "test": "npm run build && node --test --experimental-strip-types 'test/*.test.ts'"
-  },
-  "dependencies": {
-    "@novox/mesh-sdk": "^0.1.7"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.6.0"
-  }
-}

modules/claude-code/render.ts

@@ -1,135 +0,0 @@
-// 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 for the mesh or this node. Exclusive by the
-//                           vendor's rule — a server not listed here does not load — which is why the
-//                           list is the module's settings and nothing else (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.
-
-export const MANAGED_DIR = "/etc/claude-code";
-
-export interface Facts {
-  readonly node: string;
-  readonly console: string;
-}
-
-export interface Settings {
-  readonly role?: string;
-  /** Extra tool servers, in the vendor's `.mcp.json` entry shape, keyed by name. */
-  readonly mcp_servers?: Readonly<Record<string, Record<string, unknown>>>;
-}
-
-export interface Binding {
-  readonly licence: string;
-  readonly kind: "subscription" | "api-key";
-}
-
-export interface Rendered {
-  readonly [file: string]: string;
-}
-
-const MESH_ENTRY = "mesh";
-
-export type Servers = Readonly<Record<string, Record<string, unknown>>>;
-
-/** Whether an entry is one the vendor's managed file takes: a name of letters, digits, `-` and `_`, and
- *  an http/sse server with a url or a stdio server with a command. Returns why not, or null. */
-export function entryProblem(name: string, entry: Record<string, unknown>): string | null {
-  if (!/^[A-Za-z0-9_-]+$/.test(name)) return `"${name}" is not a name the agent takes: letters, digits, - and _`;
-  if (name === MESH_ENTRY) return `"${MESH_ENTRY}" is the mesh's own entry`;
-  const type = entry?.type ?? "stdio";
-  if (type === "http" || type === "sse" || type === "streamable-http") {
-    return typeof entry.url === "string" && entry.url ? null : `an ${type} server needs a url`;
-  }
-  if (type === "stdio") return typeof entry.command === "string" && entry.command ? null : "a stdio server needs a command";
-  return `"${String(type)}" is not a server type the agent knows (http, sse, stdio)`;
-}
-
-/**
- * Compose the three files. `registered` is the module's own list on this node — what was registered
- * through its tools — laid over the servers the operator set in its settings.
- */
-export function render(facts: Facts, settings: Settings, binding: Binding | null, helperPath: string,
-                       registered: Servers = {}): Rendered {
-  const servers: Record<string, unknown> = {};
-  for (const [name, entry] of Object.entries({ ...(settings.mcp_servers ?? {}), ...registered })) {
-    if (entryProblem(name, entry) !== null) continue; // the mesh's own entry, or one the agent would refuse
-    servers[name] = entry;
-  }
-  servers[MESH_ENTRY] = { type: "http", url: facts.console };
-
-  const managed: Record<string, unknown> = {
-    attribution: { commit: "", pr: "" },
-    allowAllClaudeAiMcps: true,
-  };
-  if (binding?.kind === "api-key") managed.apiKeyHelper = helperPath;
-
-  return {
-    "managed-mcp.json": json({ mcpServers: sortKeys(servers) }),
-    "managed-settings.json": json(managed),
-    "CLAUDE.md": instructions(facts, settings),
-  };
-}
-
-function json(v: unknown): string {
-  return JSON.stringify(v, null, 2) + "\n";
-}
-
-function sortKeys(o: Record<string, unknown>): Record<string, unknown> {
-  return Object.fromEntries(Object.keys(o).sort().map((k) => [k, o[k]]));
-}
-
-export function instructions(facts: Facts, settings: Settings): string {
-  const role = settings.role?.trim() ? settings.role.trim() : "not stated — set it in this module's settings for the node";
-  return `# This machine is a node of a Novox mesh
-
-Written by the mesh's \`claude-code\` module. Edit the module's settings or the catalogue, never this file:
-it is rewritten whenever the module renders.
-
-## Who this node is
-
-- **Node:** \`${facts.node}\`
-- **Role:** ${role}
-- The other nodes, their roles and what runs where: ask the controller (\`mesh-controller.nodes\`,
-  \`mesh-controller.node\`). Nothing here lists them, because a copy drifts.
-
-## How a session on this mesh works
-
-The console is the only way to the mesh: the MCP server named \`mesh\`. It offers five tools, and
-everything else is an address you find and call through them:
-
-- \`mesh_search\` — words in, matching addresses out. \`mesh_describe\` — one address's arguments.
-- \`mesh_call\` — call an address. A seat the mesh holds once is \`<seat>.<verb>\` (the mesh's own verbs
-  are \`mesh-controller.<verb>\`: \`status\`, \`plan\`, \`node\`, \`assign\`, \`push\`, \`settings\`);
-  a module on a machine is \`<node>/<module>.<tool>\`.
-- \`mesh_overview\` and \`mesh_machine\` — the mesh's seats and machines, and what one machine runs.
-
-- **Symptom first.** For an error, a failing service or anything unexpected, search the record with the
-  literal text before forming a hypothesis: the records module's \`records_search\`, then
-  \`records_read\`.
-- **Ask the mesh before changing it**, and change it through the controller's verbs or the catalogue.
-- **A licence** through the \`anthropic-licence-manager\` seat's verbs. Never edit the agent's credentials
-  file by hand, never print or ask for a token.
-
-## Hard rules
-
-- A file the mesh manages is changed through the verb or the catalogue that owns it, never on disk. If
-  unsure, \`mesh-controller.plan\` for the node says what the mesh writes there.
-- Never write to a store's database by hand; schema changes are numbered migrations.
-- Never push to a main branch: a branch, a pull request, and a human approval for every merge.
-- The mesh creates no symlinks, and nobody else does either.
-- A package is declared in a module, never installed by hand.
-
-## Conventions
-
-- Commit messages are concise, in the imperative, about why.
-- Test before pushing: nodes update unattended.
-- The playbooks in the record say how research, decisions, designs, issues and hand-offs are done.
-`;
-}

modules/claude-code/seal.ts

@@ -1,77 +0,0 @@
-// Sealing a token to one recipient (novox/hq ADR 0183): the manager seals what it hands a node to that
-// node's agent module key, and a node seals a waiting login to the key the manager names. X25519 for
-// the agreement, HKDF-SHA256 for the key, AES-256-GCM for the box — all from Node's own library, so a
-// bundle carries no dependency and no secret ever crosses the bus in the clear.
-//
-// A sealed box is `{ v: 1, eph, iv, tag, ct }`, every field base64. `eph` is a one-time public key, so
-// two boxes of one value to one recipient share nothing, and only the recipient's private key opens it.
-
-import {
-  createCipheriv, createDecipheriv, createPrivateKey, createPublicKey, diffieHellman,
-  generateKeyPairSync, hkdfSync, randomBytes, type KeyObject,
-} from "node:crypto";
-
-export interface SealedBox {
-  readonly v: 1;
-  readonly eph: string;
-  readonly iv: string;
-  readonly tag: string;
-  readonly ct: string;
-}
-
-/** A recipient's keypair, as the two PEM strings it is kept and published as. */
-export interface KeyPairPem {
-  readonly publicKey: string;
-  readonly privateKey: string;
-}
-
-const INFO = Buffer.from("novox-mesh sealed box v1");
-
-export function generateKeyPair(): KeyPairPem {
-  const { publicKey, privateKey } = generateKeyPairSync("x25519");
-  return {
-    publicKey: publicKey.export({ type: "spki", format: "pem" }).toString(),
-    privateKey: privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
-  };
-}
-
-function keyFor(secret: Buffer, eph: Buffer, recipient: Buffer): Buffer {
-  // The ephemeral and the recipient's public halves are bound into the key, so a box cannot be
-  // re-addressed to another recipient by swapping its `eph`.
-  return Buffer.from(hkdfSync("sha256", secret, Buffer.concat([eph, recipient]), INFO, 32));
-}
-
-function rawPublic(key: KeyObject): Buffer {
-  return key.export({ type: "spki", format: "der" }).subarray(-32);
-}
-
-export function seal(plaintext: string, recipientPublicPem: string): SealedBox {
-  const recipient = createPublicKey(recipientPublicPem);
-  const eph = generateKeyPairSync("x25519");
-  const secret = diffieHellman({ privateKey: eph.privateKey, publicKey: recipient });
-  const ephRaw = eph.publicKey.export({ type: "spki", format: "der" });
-  const key = keyFor(secret, ephRaw, rawPublic(recipient));
-  const iv = randomBytes(12);
-  const cipher = createCipheriv("aes-256-gcm", key, iv);
-  const ct = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
-  return {
-    v: 1,
-    eph: ephRaw.toString("base64"),
-    iv: iv.toString("base64"),
-    tag: cipher.getAuthTag().toString("base64"),
-    ct: ct.toString("base64"),
-  };
-}
-
-/** Open a box with the recipient's private key. Throws on a box for another key or one tampered with. */
-export function open(box: SealedBox, privateKeyPem: string): string {
-  if (!box || box.v !== 1) throw new Error("not a sealed box this module can open");
-  const priv = createPrivateKey(privateKeyPem);
-  const ephRaw = Buffer.from(box.eph, "base64");
-  const eph = createPublicKey({ key: ephRaw, format: "der", type: "spki" });
-  const secret = diffieHellman({ privateKey: priv, publicKey: eph });
-  const key = keyFor(secret, ephRaw, rawPublic(createPublicKey(priv)));
-  const decipher = createDecipheriv("aes-256-gcm", key, Buffer.from(box.iv, "base64"));
-  decipher.setAuthTag(Buffer.from(box.tag, "base64"));
-  return Buffer.concat([decipher.update(Buffer.from(box.ct, "base64")), decipher.final()]).toString("utf8");
-}

modules/claude-code/test/grant.test.ts

@@ -1,54 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { mkdtempSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import {
-  decideApply, grantOf, holdsLogin, readCredentials, withGrant, writeCredentials, type Grant,
-} from "../dist/grant.js";
-
-const NOW = 1_700_000_000_000;
-const HOUR = 3_600_000;
-const g = (over: Partial<Grant> = {}): Grant => ({
-  accessToken: "tok-A", expiresAt: NOW + HOUR, refreshTokenExpiresAt: NOW + 30 * 24 * HOUR, ...over,
-});
-
-test("a rotation applies a newer grant of the same licence", () => {
-  assert.deepEqual(decideApply(g(), g({ accessToken: "tok-B", expiresAt: NOW + 2 * HOUR }), "rotation"), { apply: true });
-});
-
-test("a rotation refuses a grant that arrived late and is older", () => {
-  const d = decideApply(g({ accessToken: "new", expiresAt: NOW + 2 * HOUR }), g({ accessToken: "old" }), "rotation");
-  assert.equal(d.apply === false && d.reason, "not-newer");
-});
-
-test("a grant re-issued by a login is adopted even though it expires sooner (2026-09-05)", () => {
-  const local = g({ expiresAt: NOW + 8 * HOUR, refreshTokenExpiresAt: NOW + 30 * 24 * HOUR });
-  const offered = g({ accessToken: "reissued", expiresAt: NOW + HOUR, refreshTokenExpiresAt: NOW + 5 * 24 * HOUR });
-  assert.deepEqual(decideApply(local, offered, "rotation"), { apply: true, reissued: true });
-});
-
-test("a switch to another licence applies whatever the expiries say", () => {
-  const local = g({ expiresAt: NOW + 8 * HOUR });
-  assert.equal(decideApply(local, g({ accessToken: "other", expiresAt: NOW + HOUR }), "switch").apply, true);
-});
-
-test("the same token is not rewritten", () => {
-  assert.deepEqual(decideApply(g(), g(), "switch"), { apply: false, reason: "already-current" });
-});
-
-test("a full grant left by a login is seen as a login, and stripped when the node's own is written", () => {
-  const dir = mkdtempSync(join(tmpdir(), "claude-code-"));
-  const path = join(dir, ".claude", ".credentials.json");
-  writeFileSync(join(dir, "x"), "");
-  const login = { claudeAiOauth: { accessToken: "at-login", refreshToken: "rt-login", expiresAt: NOW }, other: 1 };
-  assert.equal(holdsLogin(login), true);
-  writeCredentials(path, withGrant(login, g({ accessToken: "at-mesh", scopes: ["user:inference"] })));
-  const back = readCredentials(path)!;
-  assert.equal(holdsLogin(back), false);
-  assert.equal(grantOf(back)!.accessToken, "at-mesh");
-  assert.deepEqual(back.claudeAiOauth!.scopes, ["user:inference"]);
-  assert.equal(back.other, 1, "a key the module does not know was lost");
-  assert.ok(!readFileSync(path, "utf8").includes("rt-login"));
-  assert.equal(statSync(path).mode & 0o777, 0o600);
-});

modules/claude-code/test/identity.test.ts

@@ -1,19 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { mkdtempSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { readIdentity } from "../dist/identity.js";
-
-test("the account is read from the agent's state file", () => {
-  const p = join(mkdtempSync(join(tmpdir(), "cc-id-")), ".claude.json");
-  writeFileSync(p, JSON.stringify({ oauthAccount: { accountUuid: "u-1", emailAddress: "a@example.org" }, other: 2 }));
-  assert.deepEqual(readIdentity(p), { accountUuid: "u-1", emailAddress: "a@example.org", organizationUuid: undefined });
-});
-
-test("no state file, or no account in it, is no identity rather than a guess", () => {
-  assert.equal(readIdentity("/nonexistent/.claude.json"), null);
-  const p = join(mkdtempSync(join(tmpdir(), "cc-id-")), ".claude.json");
-  writeFileSync(p, "{}");
-  assert.equal(readIdentity(p), null);
-});

modules/claude-code/test/node.test.ts

@@ -1,173 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import {
-  apply, concerns, keypair, offerLogin, onServerChange, pull, registerServer, registered, ServerView, type Paths,
-  type ServerChange, type ServerState,
-} from "../dist/node.js";
-import { generateKeyPair, open, seal } from "../dist/seal.js";
-
-const NOW = Date.now();
-function node(name = "laptop"): { p: Paths; written: Record<string, string> } {
-  const root = mkdtempSync(join(tmpdir(), "cc-node-"));
-  const p = { state: join(root, "state"), facts: join(root, "state", "facts.json"), settings: join(root, "state", "settings.json"), home: join(root, "home"), node: name };
-  mkdirSync(p.state, { recursive: true });
-  mkdirSync(join(p.home, ".claude"), { recursive: true });
-  writeFileSync(p.facts, JSON.stringify({ node: name, console: "http://127.0.0.1:4270/mcp" }));
-  writeFileSync(p.settings, JSON.stringify({ role: "", mcp_servers: {} }));
-  return { p, written: {} };
-}
-const writer = (w: Record<string, string>) => (name: string, content: string) => { w[name] = content; return `${name}: written`; };
-const creds = (p: Paths) => JSON.parse(readFileSync(join(p.home, ".claude", ".credentials.json"), "utf8"));
-const grantFor = (p: Paths, licence: string, token: string, kind: "subscription" | "api-key" = "subscription", identity?: object) => ({
-  licence, kind, identity,
-  sealed: seal(kind === "api-key" ? token : JSON.stringify({ accessToken: token, expiresAt: NOW + 3_600_000, refreshTokenExpiresAt: NOW + 86_400_000, subscriptionType: licence }), keypair(p).publicKey),
-});
-
-test("a pull asks the seat with this node's key and applies what it answers", async () => {
-  const { p, written } = node();
-  let asked: [string, Record<string, unknown>] | null = null;
-  const r = await pull(p, async (address, args) => { asked = [address, args]; return grantFor(p, "personal", "at-1"); }, writer(written));
-  assert.equal(asked![0], "anthropic-licence-manager.current");
-  assert.equal(asked![1].node, "laptop");
-  assert.match(String(asked![1].public_key), /BEGIN PUBLIC KEY/);
-  assert.equal(r.applied, true);
-  assert.equal(creds(p).claudeAiOauth.accessToken, "at-1");
-  assert.ok(written["managed-mcp.json"]);
-});
-
-test("a switch replaces the old licence's grant whole and points the account at the new one", () => {
-  const { p, written } = node();
-  writeFileSync(join(p.home, ".claude.json"), JSON.stringify({ oauthAccount: { accountUuid: "old" }, projects: { keep: 1 } }));
-  apply(p, grantFor(p, "personal", "at-1"), writer(written));
-  const r = apply(p, grantFor(p, "work", "at-2", "subscription", { accountUuid: "new", emailAddress: "w@example.org" }), writer(written));
-  assert.equal(r.switched, true);
-  assert.equal(creds(p).claudeAiOauth.accessToken, "at-2");
-  assert.equal(creds(p).claudeAiOauth.subscriptionType, "work", "the old licence's subscription type survived the switch");
-  const account = JSON.parse(readFileSync(join(p.home, ".claude.json"), "utf8"));
-  assert.equal(account.oauthAccount.accountUuid, "new");
-  assert.deepEqual(account.projects, { keep: 1 });
-});
-
-test("switching to the API key adds the key-helper; switching away removes the key and the helper", () => {
-  const { p, written } = node();
-  apply(p, grantFor(p, "api", "sk-key", "api-key"), writer(written));
-  assert.ok(JSON.parse(written["managed-settings.json"]).apiKeyHelper);
-  assert.ok(existsSync(join(p.state, "api-key")));
-  apply(p, grantFor(p, "personal", "at-1"), writer(written));
-  assert.ok(!("apiKeyHelper" in JSON.parse(written["managed-settings.json"])));
-  assert.ok(!existsSync(join(p.state, "api-key")) && !existsSync(join(p.state, "api-key-helper")));
-});
-
-test("a rotation event concerns the node bound to that licence; a switch event the node it names", () => {
-  const { p, written } = node();
-  apply(p, grantFor(p, "personal", "at-1"), writer(written));
-  assert.equal(concerns(p, "claude-licence-manager.licence.rotated", { licence: "personal" }), true);
-  assert.equal(concerns(p, "claude-licence-manager.licence.rotated", { licence: "work" }), false);
-  assert.equal(concerns(p, "claude-licence-manager.licence.switched", { node: "laptop", licence: "work" }), true);
-  assert.equal(concerns(p, "claude-licence-manager.licence.switched", { node: "server" }), false);
-});
-
-test("a login is offered to the seat sealed to the seat's key, with the account it belongs to", async () => {
-  const { p } = node();
-  const manager = generateKeyPair();
-  writeFileSync(join(p.home, ".claude", ".credentials.json"), JSON.stringify({ claudeAiOauth: { accessToken: "at-login", refreshToken: "rt-login", expiresAt: NOW } }));
-  writeFileSync(join(p.home, ".claude.json"), JSON.stringify({ oauthAccount: { accountUuid: "u-9" } }));
-  const calls: [string, Record<string, unknown>][] = [];
-  await offerLogin(p, async (address, args) => { calls.push([address, args]); return address.endsWith("public_key") ? { public_key: manager.publicKey } : { adopted: true }; });
-  assert.deepEqual(calls.map((c) => c[0]), ["anthropic-licence-manager.public_key", "anthropic-licence-manager.adopt"]);
-  const adopt = calls[1][1] as { identity: { accountUuid: string }; sealed: never };
-  assert.equal(adopt.identity.accountUuid, "u-9");
-  assert.equal(JSON.parse(open(adopt.sealed, manager.privateKey)).refreshToken, "rt-login");
-  assert.ok(!JSON.stringify(adopt).includes("rt-login"), "the refresh token crossed in the clear");
-});
-
-test("no refresh token in the file is no login, and nothing is asked", async () => {
-  const { p } = node();
-  writeFileSync(join(p.home, ".claude", ".credentials.json"), JSON.stringify({ claudeAiOauth: { accessToken: "at", expiresAt: NOW } }));
-  assert.equal(await offerLogin(p, async () => { throw new Error("asked"); }), null);
-});
-
-/** The `servers` state as the bus holds it, shared by every node in a test, with each node's watch. */
-function bus() {
-  const kept = new Map<string, Record<string, unknown>>();
-  const watchers: ((c: ServerChange) => void)[] = [];
-  const state: ServerState = {
-    put: async (key, value) => { kept.set(key, value); watchers.forEach((w) => w({ key, op: "put", value })); return kept.size; },
-    delete: async (key) => { kept.delete(key); watchers.forEach((w) => w({ key, op: "delete" })); },
-    keys: async () => [...kept.keys()].sort(),
-  };
-  /** A node joining: its view takes the current state, then every change. */
-  const join = (n: { p: Paths; written: Record<string, string> }) => {
-    const view = new ServerView(n.p);
-    for (const [key, value] of kept) onServerChange(view, { key, op: "put", value }, n.p, writer(n.written));
-    watchers.push((c) => onServerChange(view, c, n.p, writer(n.written)));
-    return view;
-  };
-  return { state, join, kept };
-}
-
-test("registering a server here puts it under this node's key, renders it, and asks about the other nodes", async () => {
-  const n = node();
-  const b = bus();
-  const view = b.join(n);
-  const r = await registerServer(n.p, { name: "search", entry: { type: "http", url: "https://s.example/mcp" } },
-    b.state, view, writer(n.written), async () => ["laptop", "server", "desktop"]);
-  assert.equal(r.here, "changed");
-  assert.match(String(r.also), /server, desktop/);
-  assert.deepEqual([...b.kept.keys()], ["laptop.search"]);
-  assert.ok(JSON.parse(n.written["managed-mcp.json"]).mcpServers.search);
-});
-
-test("registering for every node reaches the others through their watch, and a node joining later reads it", async () => {
-  const a = node("laptop"), s = node("server");
-  const b = bus();
-  const va = b.join(a);
-  b.join(s);
-  await registerServer(a.p, { name: "docs", entry: { type: "stdio", command: "docs-mcp" }, nodes: "all" },
-    b.state, va, writer(a.written), async () => []);
-  assert.deepEqual([...b.kept.keys()], ["all.docs"]);
-  assert.deepEqual(registered(s.p).docs, { type: "stdio", command: "docs-mcp" });
-  assert.ok(JSON.parse(s.written["managed-mcp.json"]).mcpServers.docs);
-  // The gap events left: a node assigned after the registration takes the whole current set at start.
-  const late = node("desktop");
-  b.join(late);
-  assert.deepEqual(registered(late.p).docs, { type: "stdio", command: "docs-mcp" });
-  // Unregistering is a delete, and every node's view drops it.
-  await registerServer(a.p, { name: "docs", nodes: "all" }, b.state, va, writer(a.written), async () => []);
-  assert.equal(registered(s.p).docs, undefined);
-  assert.equal(registered(late.p).docs, undefined);
-});
-
-test("a node's own registration overrides the one for every node; other nodes' keys leave this one alone", async () => {
-  const a = node("laptop"), s = node("server");
-  const b = bus();
-  const va = b.join(a);
-  const vs = b.join(s);
-  await registerServer(a.p, { name: "x", entry: { type: "http", url: "https://all" }, nodes: "all" }, b.state, va, writer(a.written), async () => []);
-  await registerServer(a.p, { name: "x", entry: { type: "http", url: "https://laptop" } }, b.state, va, writer(a.written), async () => []);
-  assert.equal(registered(a.p).x.url, "https://laptop");
-  assert.equal(registered(s.p).x.url, "https://all");
-  await registerServer(a.p, { name: "only", entry: { type: "http", url: "https://o" }, nodes: ["server"] }, b.state, va, writer(a.written), async () => []);
-  assert.equal(registered(a.p).only, undefined);
-  assert.equal(registered(s.p).only.url, "https://o");
-  // Unregistering here leaves the every-node one applying, and says so.
-  const r = await registerServer(a.p, { name: "x" }, b.state, va, writer(a.written), async () => []);
-  assert.match(String(r.still), /still applies here/);
-  assert.equal(registered(a.p).x.url, "https://all");
-  assert.equal(vs.effective().x.url, "https://all");
-});
-
-test("a bad entry is refused before anything is put; a repeated change changes nothing", async () => {
-  const n = node();
-  const b = bus();
-  const view = b.join(n);
-  const r = await registerServer(n.p, { name: "mesh", entry: { type: "http", url: "https://x" } }, b.state, view, writer(n.written), async () => []);
-  assert.equal(r.registered, false);
-  assert.equal(b.kept.size, 0);
-  assert.equal(onServerChange(view, { key: "all.a", op: "put", value: { type: "http", url: "https://a" } }, n.p, writer(n.written)), "registered all.a");
-  assert.equal(onServerChange(view, { key: "all.a", op: "put", value: { type: "http", url: "https://a" } }, n.p, writer(n.written)), null);
-  assert.equal(onServerChange(view, { key: "server.b", op: "put", value: { type: "http", url: "https://b" } }, n.p, writer(n.written)), null);
-});

modules/claude-code/test/render.test.ts

@@ -1,40 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { render } from "../dist/render.js";
-
-const facts = { node: "workstation", console: "http://127.0.0.1:4270/mcp" };
-
-test("the console is the `mesh` server, and an operator's servers are listed beside it", () => {
-  const out = render(facts, { mcp_servers: { search: { type: "http", url: "https://s.example/mcp" } } }, null, "/h");
-  const mcp = JSON.parse(out["managed-mcp.json"]);
-  assert.deepEqual(Object.keys(mcp.mcpServers), ["mesh", "search"]);
-  assert.deepEqual(mcp.mcpServers.mesh, { type: "http", url: facts.console });
-});
-
-test("a setting cannot replace the mesh's own entry, and a name the vendor refuses is left out", () => {
-  const out = render(facts, { mcp_servers: { mesh: { type: "http", url: "http://evil" }, "bad name": {} } }, null, "/h");
-  const mcp = JSON.parse(out["managed-mcp.json"]);
-  assert.equal(mcp.mcpServers.mesh.url, facts.console);
-  assert.ok(!("bad name" in mcp.mcpServers));
-});
-
-test("managed settings carry the mesh's keys only, and the key-helper only for an API-key licence", () => {
-  const sub = JSON.parse(render(facts, {}, { licence: "personal", kind: "subscription" }, "/h")["managed-settings.json"]);
-  assert.deepEqual(sub, { attribution: { commit: "", pr: "" }, allowAllClaudeAiMcps: true });
-  const key = JSON.parse(render(facts, {}, { licence: "api", kind: "api-key" }, "/state/api-key-helper")["managed-settings.json"]);
-  assert.equal(key.apiKeyHelper, "/state/api-key-helper");
-  assert.ok(!("model" in key), "a preference is the person's");
-});
-
-test("the instruction file names the node and its role, and no other node", () => {
-  const md = render(facts, { role: "the laptop" }, null, "/h")["CLAUDE.md"];
-  assert.match(md, /\*\*Node:\*\* `workstation`/);
-  assert.match(md, /\*\*Role:\*\* the laptop/);
-  assert.match(md, /mesh_call/);
-  assert.match(md, /records_search/);
-});
-
-test("rendering is deterministic, so an unchanged input writes nothing", () => {
-  const s = { mcp_servers: { b: { type: "http", url: "https://b" }, a: { type: "http", url: "https://a" } } };
-  assert.deepEqual(render(facts, s, null, "/h"), render(facts, s, null, "/h"));
-});

modules/claude-code/test/seal.test.ts

@@ -1,31 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { generateKeyPair, open, seal } from "../dist/seal.js";
-
-test("a box opens with its recipient's key and yields the value", () => {
-  const k = generateKeyPair();
-  assert.equal(open(seal("at-secret", k.publicKey), k.privateKey), "at-secret");
-});
-
-test("a box sealed for one node does not open with another node's key", () => {
-  const a = generateKeyPair();
-  const b = generateKeyPair();
-  assert.throws(() => open(seal("at-secret", a.publicKey), b.privateKey));
-});
-
-test("a tampered box is refused, not opened to garbage", () => {
-  const k = generateKeyPair();
-  const box = seal("at-secret", k.publicKey);
-  const ct = Buffer.from(box.ct, "base64");
-  ct[0] ^= 0xff;
-  assert.throws(() => open({ ...box, ct: ct.toString("base64") }, k.privateKey));
-});
-
-test("two boxes of one value share nothing a reader could compare", () => {
-  const k = generateKeyPair();
-  const x = seal("at-secret", k.publicKey);
-  const y = seal("at-secret", k.publicKey);
-  assert.notEqual(x.ct, y.ct);
-  assert.notEqual(x.eph, y.eph);
-  assert.ok(!JSON.stringify(x).includes("at-secret"));
-});

modules/claude-code/tools/index.ts

@@ -1,208 +0,0 @@
-// claude-code's bundle (novox/hq design 36, ADR 0183). The node's runtime launches it over stdio, as the
-// operator account (ADR 0193), and is its bus (ADR 0198): it asks tools, emits and consumes through the
-// runtime. It is given its state directory and two files the mesh renders into it (ADR 0192), beside the
-// runtime's own words. **stdout is the MCP channel**: everything this module says, it says on stderr.
-//
-// At start it renders the agent's managed directory, asks the licence manager for this node's token,
-// begins watching the credentials file for a login, takes the manager's licence events, and watches the
-// module's `servers` state — every node's MCP server registrations (novox/hq ADR 0202). node.ts holds the
-// logic.
-
-import { readFileSync, watchFile } from "node:fs";
-import { spawnSync } from "node:child_process";
-import { join } from "node:path";
-import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
-import { broker } from "@novox/mesh-sdk/messaging";
-import { on } from "@novox/mesh-sdk/events";
-import { state } from "@novox/mesh-sdk/state";
-
-import {
-  MANAGED_DIR, SEAT, ServerView, concerns, keypair, offerLogin, onServerChange, pull, readJson, registerServer,
-  registered, renderNow, type Ask, type Paths, type Registration, type ServerChange, type ServerState, type WriteManaged,
-} from "../node.js";
-import { grantOf, holdsLogin, readCredentials } from "../grant.js";
-import { createHash } from "node:crypto";
-
-const say = (line: string) => console.error(`[claude-code] ${line}`);
-const fingerprint = (s: string) => "sha256:" + createHash("sha256").update(s).digest("hex").slice(0, 16);
-
-function pathsFrom(env: NodeJS.ProcessEnv): Paths | null {
-  const state = env.MESH_CLAUDE_CODE_STATE, facts = env.MESH_CLAUDE_CODE_FACTS;
-  const settings = env.MESH_CLAUDE_CODE_SETTINGS, home = env.MESH_OPERATOR_HOME, node = env.MESH_NODE;
-  if (!state || !facts || !settings || !home || !node) return null;
-  return { state, facts, settings, home, node };
-}
-
-/** Write one managed file as root, only when its content changed. */
-const writeManaged: WriteManaged = (name, content) => {
-  const path = join(MANAGED_DIR, name);
-  try {
-    if (readFileSync(path, "utf8") === content) return `${name}: unchanged`;
-  } catch {
-    /* absent */
-  }
-  const asRoot = process.getuid?.() === 0;
-  const cmd = asRoot ? ["install", "-D", "-m", "0644", "/dev/stdin", path] : ["sudo", "-n", "install", "-D", "-m", "0644", "/dev/stdin", path];
-  const r = spawnSync(cmd[0], cmd.slice(1), { input: content, encoding: "utf8" });
-  if (r.status !== 0) {
-    throw new Error(`${name}: could not be written to ${MANAGED_DIR} (${(r.stderr || r.error?.message || "").trim()}); ` +
-      `the module writes there through the operator account's passwordless sudo`);
-  }
-  return `${name}: written`;
-};
-
-/** A tool on the bus, through the runtime; its MCP answer read back as JSON where it is JSON. */
-const ask: Ask = async (address, args) => {
-  const answer = (await broker().request<Record<string, unknown>, { content?: { text?: string }[]; isError?: boolean }>(address, args)) ?? {};
-  const text = answer.content?.map((c) => c.text ?? "").join("") ?? "";
-  if (answer.isError) throw new Error(`${address}: ${text}`);
-  try {
-    return JSON.parse(text);
-  } catch {
-    return text;
-  }
-};
-
-/** The nodes claude-code runs on, from the controller's list of modules — for the register tool's question. */
-async function nodesRunningMe(): Promise<string[]> {
-  const out = await ask("mesh-controller.modules", {});
-  const text = typeof out === "string" ? out : String((out as { output?: string })?.output ?? "");
-  const line = text.split("\n").find((l) => /^claude-code\s/.test(l)) ?? "";
-  const on = line.split(" on ")[1] ?? "";
-  return on.trim() === "nothing" ? [] : on.split(",").map((s) => s.trim()).filter(Boolean);
-}
-
-function status(p: Paths): Record<string, unknown> {
-  const creds = readCredentials(join(p.home, ".claude", ".credentials.json"));
-  const grant = grantOf(creds);
-  const managed = ["managed-mcp.json", "managed-settings.json", "CLAUDE.md"].map((f) => {
-    try {
-      return { file: join(MANAGED_DIR, f), fingerprint: fingerprint(readFileSync(join(MANAGED_DIR, f), "utf8")) };
-    } catch {
-      return { file: join(MANAGED_DIR, f), fingerprint: null };
-    }
-  });
-  return {
-    node: p.node,
-    licence: readJson(join(p.state, "licence.json"), null),
-    token: grant ? { fingerprint: fingerprint(grant.accessToken), expiresAt: new Date(grant.expiresAt).toISOString(),
-      loginWaiting: holdsLogin(creds) } : null,
-    managed,
-    registered: Object.keys(registered(p)),
-  };
-}
-
-/** The module's MCP servers on the bus (ADR 0202): its own state, which every node of it watches. */
-const servers = () => state<Record<string, unknown>>("servers") as unknown as ServerState;
-
-/** What this node takes from that state, kept from the watch. One per process. */
-let view: ServerView | null = null;
-const viewOf = (p: Paths) => (view ??= new ServerView(p));
-
-function tools(p: Paths): ToolDefinition[] {
-  const nodesArg = { type: "string", description: 'more nodes: "all" for every node running claude-code, or a comma-separated list; absent is this node only' };
-  const nodesOf = (v: unknown): Registration["nodes"] =>
-    v === undefined || v === "" ? undefined : v === "all" ? "all" : String(v).split(",").map((s) => s.trim()).filter(Boolean);
-  return [
-    {
-      name: "claude_code_status",
-      description: "Claude Code on this machine as the mesh configured it: the licence it holds and when its token expires, the managed files, the MCP servers registered here. Fingerprints only, never a token.",
-      input: {},
-      run: async () => status(p),
-    },
-    {
-      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.",
-      input: {},
-      run: async () => ({ rendered: renderNow(p, writeManaged) }),
-    },
-    {
-      name: "claude_code_pull",
-      description: "Ask the licence manager for this node's current token now and apply it, rather than waiting for its next event.",
-      input: {},
-      run: async () => pull(p, ask, writeManaged),
-    },
-    {
-      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.",
-      input: {},
-      run: async () => ({ here: registered(p), everywhere: await servers().keys() }),
-    },
-    {
-      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: {
-        name: { type: "string", description: "the server's name: letters, digits, - and _" },
-        type: { type: "string", description: "http, sse or stdio (default stdio when a command is given, http when a url is)" },
-        url: { type: "string", description: "an http or sse server's url" },
-        command: { type: "string", description: "a stdio server's program" },
-        args: { type: "array", description: "a stdio server's arguments" },
-        env: { type: "object", description: "a stdio server's environment" },
-        headers: { type: "object", description: "an http server's headers" },
-        nodes: nodesArg,
-      },
-      run: async (a) => {
-        const entry: Record<string, unknown> = { type: a.type ?? (a.url ? "http" : "stdio") };
-        for (const k of ["url", "command", "args", "env", "headers"]) if (a[k] !== undefined) entry[k] = a[k];
-        return registerServer(p, { name: String(a.name ?? ""), entry, nodes: nodesOf(a.nodes) }, servers(), viewOf(p), writeManaged, nodesRunningMe);
-      },
-    },
-    {
-      name: "claude_code_mcp_unregister",
-      description: "Remove an MCP server registered through this module, on this node or more.",
-      input: { name: { type: "string", description: "the server's name" }, nodes: nodesArg },
-      run: async (a) => registerServer(p, { name: String(a.name ?? ""), nodes: nodesOf(a.nodes) }, servers(), viewOf(p), writeManaged, nodesRunningMe),
-    },
-  ];
-}
-
-registerModuleTools("claude-code", (env) => {
-  const p = pathsFrom(env);
-  if (!p) return [];
-  try {
-    keypair(p);
-    for (const line of renderNow(p, writeManaged)) if (!line.endsWith("unchanged")) say(line);
-  } catch (err) {
-    say(err instanceof Error ? err.message : String(err));
-  }
-  return tools(p);
-});
-
-// Launched by the runtime: the bus is there from the first line (ADR 0198). Outside it — a test, a
-// build — nothing below runs.
-const p = process.env.MESH_SERVED_MODULE ? pathsFrom(process.env) : null;
-if (p) {
-  const loud = (what: string) => (err: unknown) => say(`${what}: ${err instanceof Error ? err.message : String(err)}`);
-
-  void on<{ licence?: string; node?: string }>("claude-licence-manager.licence.*", async (event) => {
-    if (!concerns(p, event.type, event.body ?? {})) return;
-    say(`${event.type} — asking ${SEAT} for this node's token`);
-    say(JSON.stringify(await pull(p, ask, writeManaged).catch((e) => ({ failed: String(e) }))));
-  }).catch(loud("the licence events"));
-
-  // Every node's MCP servers: the whole current set first, then each change (ADR 0202). Awaited, so the
-  // managed directory holds every server that applies here before the bundle says what it serves.
-  try {
-    await state<Record<string, unknown>>("servers").watch((c) => {
-      try {
-        const done = onServerChange(viewOf(p), c as ServerChange, p, writeManaged);
-        if (done) say(done);
-      } catch (err) {
-        loud(`taking ${c.op} ${c.key}`)(err); // the view took it; the next render writes it
-      }
-    });
-  } catch (err) {
-    loud("watching the MCP servers")(err);
-  }
-
-  // Catch up once at start: a node that was off takes its current token now.
-  void pull(p, ask, writeManaged).then((r) => say(`at start: ${JSON.stringify(r)}`), loud("asking for this node's token at start"));
-
-  // A login: a refresh token appears in the credentials file. Polled, because the file is replaced by
-  // rename and a watch on the old inode would go quiet.
-  const credentials = join(p.home, ".claude", ".credentials.json");
-  watchFile(credentials, { interval: 5000 }, () => {
-    void offerLogin(p, ask).then((r) => { if (r) say(`a login here was offered to ${SEAT}: ${JSON.stringify(r)}`); },
-      loud("offering a login to the licence manager"));
-  });
-}

modules/claude-code/tsconfig.json

@@ -1,12 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "noEmit": true
-  },
-  "include": ["seal.ts", "grant.ts", "identity.ts", "render.ts", "node.ts", "tools/index.ts"]
-}

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

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

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

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

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

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

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

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

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

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

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

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

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

modules/clipmenu/go.mod

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

modules/clipmenu/go.sum

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

modules/clipmenu/module.json

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

modules/cups/README.md

@@ -0,0 +1,84 @@
+# cups
+
+Printing on the two workstations (novox/hq research 027/02: "`cups` with the printer's driver"; to-be 42
+phase 2 step 9).
+
+## Owns
+
+| what | where |
+|---|---|
+| the print scheduler | package `cups` |
+| driverless printing: the filters that turn a document into what an IPP Everywhere printer takes | package `cups-filters` |
+| the scheduler, started on demand and at boot | `cups.socket` and `cups.service`, running and enabled |
+
+All from the official repositories. The queues (`/etc/cups/printers.conf`, the PPDs CUPS generates)
+and the default printer are CUPS's own state, set through its tools. They are found (ADR 0182), and
+the module declares none of them.
+
+## The printer's driver: none needed for the Brother
+
+Research 027 asked for "`cups` with the printer's driver". Measured on 2026-10-04:
+
+| workstation | queue | device | prints through | driver package installed |
+|---|---|---|---|---|
+| laptop | `Brother` (MFC-L8690CDW) | `ipp://` on the LAN | **IPP Everywhere, driverless** | `brother-mfc-l8690cdw` (AUR), unused |
+| desktop | `Brother_MFC_Novox` (default) | `ipp://` on the LAN | **IPP Everywhere, driverless** | `brother-mfc-l8390cdw` and its `-debug` (AUR), unused |
+| desktop | `Kanjuro` (Canon PIXMA MG4200) | `cnijnet:` | the vendor's PPD and filter | `cnijfilter-mg4200` 3.80 (AUR) |
+
+**Both Brother queues already print without a vendor driver.** CUPS's own IPP Everywhere support,
+with `cups-filters`, is the whole driver. The vendor packages installed beside them serve no queue,
+and the laptop's pulls in 32-bit glibc from multilib for a filter nothing runs. So the module declares
+no driver, and the Brother needs nothing outside the official repositories.
+
+**The Canon is the exception, and it is blocked.** Its driver is a user-repository package from 2012,
+with its own network backend. Like snapd, it waits for the mesh's package repository (research 027
+question 1, option P2). Until then it stays as found on the desktop. If the printer answers IPP (check
+with `cups_drivers` on a fresh queue, or `driverless` from `cups-filters`), a driverless queue replaces
+it and the question goes away.
+
+## Improves
+
+- **An owner for the scheduler.** It runs on both workstations today, enabled by nothing the mesh records.
+- **No driver package that nothing uses.** The README's one-off step below removes them, once.
+- **Supplies and state from anywhere.** `cups_printers` answers each queue's toner levels and flags a
+  low one. It also answers why a queue stopped, without opening the printer's page.
+- **The laptop has no default printer**, so a print without a named printer fails there.
+  `cups_default` sets one; it is the operator's choice, not declared.
+
+## Tools
+
+All answer JSON; `(r)` reads, `(a)` acts. They run as the operator account. CUPS lets any account
+print and cancel its own jobs. Setting the default, resuming a printer, and cancelling another
+account's job are kept for its administrators, so those go through `sudo -n`; a cancel tries the
+account first.
+
+| tool | what |
+|---|---|
+| `cups_printers` (r) | every queue: state, enabled, accepting, default, device, make and model, driverless or not, state reasons, supply levels (low flagged) |
+| `cups_queue` (r) | jobs waiting or printing, or the completed ones, newest first, bounded |
+| `cups_cancel` (a) | one job, or every job on a printer |
+| `cups_print` (a) | a file on this machine to a printer or the default, with copies and IPP options; answers the job id |
+| `cups_default` (r/a) | read the default, or set it |
+| `cups_resume` (a) | enable a stopped printer and make it accept jobs |
+| `cups_drivers` (r) | how each queue prints, the packages that bring filters and backends (foreign ones flagged), findings, and the driver models CUPS offers, filtered |
+
+## What changes when it is assigned
+
+Nothing on disk on either workstation: both have `cups` (explicit) and `cups-filters` (as its
+dependency), with `cups.socket` and `cups.service` enabled and running. The packages become the
+mesh's; `cups-filters` is now declared explicitly.
+
+## The one-off step for the operator (ADR 0182)
+
+The mesh removes nothing it did not install. Once the Brother queues are confirmed printing (they do
+today), remove the unused vendor drivers, once:
+
+- **laptop:** `brother-mfc-l8690cdw`, then whatever `pacman -Qdtq` shows it alone pulled in
+  (`lib32-glibc`).
+- **desktop:** `brother-mfc-l8390cdw` and `brother-mfc-l8390cdw-debug`. Keep `cnijfilter-mg4200` while
+  the Canon queue is used.
+
+## Leaves as found
+
+The queues and their PPDs, the default printer, `cups.path` (enabled by the package's preset),
+`system-config-printer` on the desktop, and `cnijfilter-mg4200`.

modules/cups/cmd/cups-tools/cups.go

@@ -0,0 +1,560 @@
+package main
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+var queueName = regexp.MustCompile(`^[A-Za-z0-9_.@-]{1,127}$`)
+
+func checkPrinter(p string) error {
+	if !queueName.MatchString(p) || strings.HasPrefix(p, "-") {
+		return fmt.Errorf("%q is not a printer queue's name", p)
+	}
+	return nil
+}
+
+var optionName = regexp.MustCompile(`^[a-z][a-z0-9-]{0,63}$`)
+var optionValue = regexp.MustCompile(`^[A-Za-z0-9._:-]{1,128}$`)
+
+// optionsOf reads the print options object.
+func optionsOf(args map[string]any) (map[string]string, error) {
+	v, ok := args["options"]
+	if !ok || v == nil {
+		return nil, nil
+	}
+	m, ok := v.(map[string]any)
+	if !ok {
+		return nil, fmt.Errorf("options must be an object of names to values")
+	}
+	out := map[string]string{}
+	for k, val := range m {
+		s, ok := val.(string)
+		if !ok || !optionName.MatchString(k) || !optionValue.MatchString(s) {
+			return nil, fmt.Errorf("option %s=%v is not an IPP option name and a plain value", k, val)
+		}
+		out[k] = s
+	}
+	return out, nil
+}
+
+// lpoptionsOf reads lpoptions' answer: name=value pairs, a value quoted with ' or with backslash escapes.
+func lpoptionsOf(s string) map[string]string {
+	out := map[string]string{}
+	s = strings.TrimSpace(s)
+	i := 0
+	for i < len(s) {
+		for i < len(s) && s[i] == ' ' {
+			i++
+		}
+		start := i
+		for i < len(s) && s[i] != '=' && s[i] != ' ' {
+			i++
+		}
+		key := s[start:i]
+		if i >= len(s) || s[i] != '=' {
+			if key != "" {
+				out[key] = ""
+			}
+			continue
+		}
+		i++
+		var b strings.Builder
+		for i < len(s) && s[i] != ' ' {
+			switch s[i] {
+			case '\'':
+				i++
+				for i < len(s) && s[i] != '\'' {
+					if s[i] == '\\' && i+1 < len(s) {
+						i++
+					}
+					b.WriteByte(s[i])
+					i++
+				}
+				i++
+			case '\\':
+				if i+1 < len(s) {
+					b.WriteByte(s[i+1])
+				}
+				i += 2
+			default:
+				b.WriteByte(s[i])
+				i++
+			}
+		}
+		out[key] = b.String()
+	}
+	return out
+}
+
+// Marker is one supply the printer reports.
+type Marker struct {
+	Name  string `json:"name"`
+	Type  string `json:"type,omitempty"`
+	Level int    `json:"level_percent"`
+	Low   bool   `json:"low"`
+}
+
+// Printer is one queue.
+type Printer struct {
+	Name       string   `json:"name"`
+	State      string   `json:"state"`
+	Enabled    bool     `json:"enabled"`
+	Accepting  bool     `json:"accepting"`
+	Default    bool     `json:"default"`
+	URI        string   `json:"uri"`
+	MakeModel  string   `json:"make_and_model"`
+	Driverless bool     `json:"driverless"`
+	Shared     bool     `json:"shared"`
+	Reasons    []string `json:"reasons"`
+	Markers    []Marker `json:"markers"`
+	Since      string   `json:"since,omitempty"`
+	Message    string   `json:"message,omitempty"`
+}
+
+// PrintersAnswer is what cups_printers answers.
+type PrintersAnswer struct {
+	Scheduler string    `json:"scheduler"`
+	Default   string    `json:"default,omitempty"`
+	Printers  []Printer `json:"printers"`
+}
+
+func lpstat(args ...string) (string, error) {
+	r, err := call(Cmd{Name: "lpstat", Args: args})
+	if err != nil {
+		if strings.Contains(r.Stderr, "Scheduler is not running") || strings.Contains(r.Stderr, "Connection refused") {
+			return "", fmt.Errorf("the print scheduler is not running on this machine: %s", firstLine(r.Stderr))
+		}
+		// lpstat answers "No destinations added." with a non-zero status: that is no printers.
+		if strings.Contains(r.Stderr, "No destinations added") {
+			return "", nil
+		}
+		return "", err
+	}
+	return r.Stdout, nil
+}
+
+func defaultPrinter() (string, error) {
+	out, err := lpstat("-d")
+	if err != nil {
+		return "", err
+	}
+	if _, after, ok := strings.Cut(out, "system default destination: "); ok {
+		return strings.TrimSpace(firstLine(after)), nil
+	}
+	return "", nil
+}
+
+// Printers answers every queue with its state, device, model and supplies.
+func Printers() (PrintersAnswer, error) {
+	out := PrintersAnswer{Printers: []Printer{}}
+	sched, err := lpstat("-r")
+	if err != nil {
+		return out, err
+	}
+	out.Scheduler = strings.TrimSpace(sched)
+	if out.Default, err = defaultPrinter(); err != nil {
+		return out, err
+	}
+	ps, err := lpstat("-p")
+	if err != nil {
+		return out, err
+	}
+	var cur *Printer
+	for _, l := range strings.Split(ps, "\n") {
+		if strings.HasPrefix(l, "printer ") {
+			f := strings.Fields(l)
+			if len(f) < 3 {
+				continue
+			}
+			out.Printers = append(out.Printers, Printer{Name: f[1], Reasons: []string{}, Markers: []Marker{}})
+			cur = &out.Printers[len(out.Printers)-1]
+			rest := strings.Join(f[2:], " ")
+			switch {
+			case strings.HasPrefix(rest, "is idle"):
+				cur.State = "idle"
+			case strings.HasPrefix(rest, "now printing"):
+				cur.State = "printing"
+			default:
+				cur.State = "stopped"
+			}
+			// "disabled since …" (stopped), or "enabled since …" after the state.
+			cur.Enabled = !strings.HasPrefix(rest, "disabled") && !strings.Contains(rest, "disabled since")
+			if _, since, found := strings.Cut(rest, " since "); found {
+				cur.Since = strings.TrimSuffix(strings.TrimSpace(since), " -")
+			}
+			continue
+		}
+		if cur != nil && strings.HasPrefix(l, "\t") && strings.TrimSpace(l) != "" {
+			cur.Message = strings.TrimSpace(cur.Message + " " + strings.TrimSpace(l))
+		}
+	}
+	acc, err := lpstat("-a")
+	if err != nil {
+		return out, err
+	}
+	accepting := map[string]bool{}
+	for _, l := range lines(acc) {
+		if f := strings.Fields(l); len(f) >= 2 && f[1] == "accepting" {
+			accepting[f[0]] = true
+		}
+	}
+	for i := range out.Printers {
+		p := &out.Printers[i]
+		p.Accepting = accepting[p.Name]
+		p.Default = p.Name == out.Default
+		r, err := call(Cmd{Name: "lpoptions", Args: []string{"-p", p.Name}})
+		if err != nil {
+			return out, err
+		}
+		o := lpoptionsOf(r.Stdout)
+		p.URI = o["device-uri"]
+		p.MakeModel = o["printer-make-and-model"]
+		p.Driverless = driverless(p.MakeModel, p.URI)
+		p.Shared = o["printer-is-shared"] == "true"
+		for _, reason := range strings.Split(o["printer-state-reasons"], ",") {
+			if reason = strings.TrimSpace(reason); reason != "" && reason != "none" {
+				p.Reasons = append(p.Reasons, reason)
+			}
+		}
+		p.Markers = markersOf(o)
+	}
+	return out, nil
+}
+
+// driverless says a queue prints without a vendor driver: CUPS's own IPP Everywhere model, or a
+// driverless URI.
+func driverless(model, uri string) bool {
+	m := strings.ToLower(model)
+	return strings.Contains(m, "ipp everywhere") || strings.Contains(m, "driverless") || strings.HasPrefix(uri, "implicitclass:") ||
+		strings.HasPrefix(uri, "ipp://") && strings.Contains(m, "everywhere")
+}
+
+func markersOf(o map[string]string) []Marker {
+	split := func(k string) []string {
+		if o[k] == "" {
+			return nil
+		}
+		return strings.Split(o[k], ",")
+	}
+	names, levels, lows, types := split("marker-names"), split("marker-levels"), split("marker-low-levels"), split("marker-types")
+	out := []Marker{}
+	for i, n := range names {
+		if i >= len(levels) {
+			break
+		}
+		level, err := strconv.Atoi(strings.TrimSpace(levels[i]))
+		if err != nil {
+			continue
+		}
+		m := Marker{Name: strings.TrimSpace(n), Level: level}
+		if i < len(types) {
+			m.Type = strings.TrimSpace(types[i])
+		}
+		if i < len(lows) {
+			if low, err := strconv.Atoi(strings.TrimSpace(lows[i])); err == nil && level >= 0 && level <= low {
+				m.Low = true
+			}
+		}
+		out = append(out, m)
+	}
+	return out
+}
+
+// Job is one print job.
+type Job struct {
+	ID        string `json:"id"`
+	Printer   string `json:"printer"`
+	User      string `json:"user"`
+	Bytes     int64  `json:"bytes"`
+	Submitted string `json:"submitted"`
+}
+
+// Queue answers the jobs waiting, or the finished ones.
+func Queue(printer string, completed bool, limit int) (map[string]any, error) {
+	args := []string{}
+	if completed {
+		args = append(args, "-W", "completed")
+	}
+	args = append(args, "-o")
+	if printer != "" {
+		if err := checkPrinter(printer); err != nil {
+			return nil, err
+		}
+		args = append(args, printer)
+	}
+	out, err := lpstat(args...)
+	if err != nil {
+		return nil, err
+	}
+	jobs := []Job{}
+	for _, l := range lines(out) {
+		f := strings.Fields(l)
+		if len(f) < 4 {
+			continue
+		}
+		i := strings.LastIndex(f[0], "-")
+		if i <= 0 {
+			continue
+		}
+		size, _ := strconv.ParseInt(f[2], 10, 64)
+		jobs = append(jobs, Job{ID: f[0], Printer: f[0][:i], User: f[1], Bytes: size, Submitted: strings.Join(f[3:], " ")})
+	}
+	sort.SliceStable(jobs, func(a, b int) bool { return jobNumber(jobs[a].ID) > jobNumber(jobs[b].ID) })
+	total := len(jobs)
+	if len(jobs) > limit {
+		jobs = jobs[:limit]
+	}
+	return map[string]any{"count": total, "jobs": jobs, "completed": completed}, nil
+}
+
+func jobNumber(id string) int {
+	n, _ := strconv.Atoi(id[strings.LastIndex(id, "-")+1:])
+	return n
+}
+
+var jobID = regexp.MustCompile(`^([A-Za-z0-9_.@-]+-)?[0-9]+$`)
+
+// refused says CUPS kept an act for its administrators.
+func refused(r Result) bool {
+	s := r.Stderr + r.Stdout
+	return strings.Contains(s, "Forbidden") || strings.Contains(s, "not-authorized") || strings.Contains(s, "Not authorized") || strings.Contains(s, "not allowed")
+}
+
+// asAccountThenRoot runs an act as the account, and through sudo -n when CUPS refuses the account.
+func asAccountThenRoot(c Cmd) (Result, bool, error) {
+	r := run(c)
+	if r.Status == 0 && r.Error == "" {
+		return r, false, nil
+	}
+	if !refused(r) {
+		return r, false, failure(c, r)
+	}
+	c.Root = true
+	r, err := call(c)
+	return r, true, err
+}
+
+// Cancel cancels one job, or every job on a printer.
+func Cancel(job, printer string, all bool) (map[string]any, error) {
+	var c Cmd
+	switch {
+	case all:
+		if printer == "" {
+			return nil, fmt.Errorf("all needs printer: cancelling every job on every printer is not offered")
+		}
+		if err := checkPrinter(printer); err != nil {
+			return nil, err
+		}
+		c = Cmd{Name: "cancel", Args: []string{"-a", printer}}
+	case job != "":
+		if !jobID.MatchString(job) {
+			return nil, fmt.Errorf("%q is not a job id", job)
+		}
+		c = Cmd{Name: "cancel", Args: []string{job}}
+	default:
+		return nil, fmt.Errorf("give job, or printer with all")
+	}
+	_, escalated, err := asAccountThenRoot(c)
+	if err != nil {
+		return nil, err
+	}
+	return map[string]any{"cancelled": strings.Join(c.Args, " "), "as_root": escalated}, nil
+}
+
+var requestID = regexp.MustCompile(`request id is (\S+)`)
+
+// statFile tells a regular file. Tests replace it.
+var statFile = func(p string) error {
+	info, err := os.Stat(p)
+	if err != nil {
+		return err
+	}
+	if !info.Mode().IsRegular() {
+		return fmt.Errorf("%s is not a regular file", p)
+	}
+	return nil
+}
+
+// Print sends a file to a printer.
+func Print(file, printer string, copies int, opts map[string]string, title string) (map[string]any, error) {
+	if !filepath.IsAbs(file) {
+		return nil, fmt.Errorf("file must be an absolute path, not %q", file)
+	}
+	if err := statFile(file); err != nil {
+		return nil, fmt.Errorf("cannot print %s: %v", file, err)
+	}
+	args := []string{}
+	if printer != "" {
+		if err := checkPrinter(printer); err != nil {
+			return nil, err
+		}
+		args = append(args, "-d", printer)
+	}
+	args = append(args, "-n", strconv.Itoa(copies))
+	names := make([]string, 0, len(opts))
+	for k := range opts {
+		names = append(names, k)
+	}
+	sort.Strings(names)
+	for _, k := range names {
+		args = append(args, "-o", k+"="+opts[k])
+	}
+	if title == "" {
+		title = filepath.Base(file)
+	}
+	args = append(args, "-t", title, "--", file)
+	r, err := call(Cmd{Name: "lp", Args: args})
+	if err != nil {
+		if strings.Contains(r.Stderr, "No default destination") {
+			return nil, fmt.Errorf("no printer given and this machine has no default printer: name one, or set one with cups_default")
+		}
+		return nil, err
+	}
+	m := requestID.FindStringSubmatch(r.Stdout)
+	if m == nil {
+		return nil, fmt.Errorf("lp answered no job id: %s", strings.TrimSpace(r.Stdout+r.Stderr))
+	}
+	return map[string]any{"job": m[1], "file": file, "copies": copies, "follow": "cups_queue"}, nil
+}
+
+// Default answers the default printer, or sets it.
+func Default(printer string) (map[string]any, error) {
+	if printer == "" {
+		d, err := defaultPrinter()
+		if err != nil {
+			return nil, err
+		}
+		return map[string]any{"default": d}, nil
+	}
+	if err := checkPrinter(printer); err != nil {
+		return nil, err
+	}
+	was, err := defaultPrinter()
+	if err != nil {
+		return nil, err
+	}
+	if _, err := call(Cmd{Name: "lpadmin", Args: []string{"-d", printer}, Root: true}); err != nil {
+		return nil, err
+	}
+	return map[string]any{"default": printer, "was": was}, nil
+}
+
+// Resume enables a printer and makes it accept jobs.
+func Resume(printer string) (map[string]any, error) {
+	if err := checkPrinter(printer); err != nil {
+		return nil, err
+	}
+	for _, c := range []string{"cupsenable", "cupsaccept"} {
+		if _, err := call(Cmd{Name: c, Args: []string{printer}, Root: true}); err != nil {
+			return nil, err
+		}
+	}
+	return map[string]any{"printer": printer, "enabled": true, "accepting": true}, nil
+}
+
+// DriverPackage is a package that brings filters or backends.
+type DriverPackage struct {
+	Package string `json:"package"`
+	Version string `json:"version"`
+	Foreign bool   `json:"foreign"`
+}
+
+// Model is one driver model CUPS offers.
+type Model struct {
+	PPD         string `json:"ppd"`
+	Description string `json:"description"`
+}
+
+// QueueDriver is how one queue prints.
+type QueueDriver struct {
+	Printer    string `json:"printer"`
+	MakeModel  string `json:"make_and_model"`
+	Driverless bool   `json:"driverless"`
+	URI        string `json:"uri"`
+}
+
+// DriversAnswer is what cups_drivers answers.
+type DriversAnswer struct {
+	Queues   []QueueDriver   `json:"queues"`
+	Packages []DriverPackage `json:"driver_packages"`
+	Models   []Model         `json:"models"`
+	Matched  int             `json:"models_matched"`
+	Findings []string        `json:"findings"`
+}
+
+// driverDirs are where drivers put what CUPS runs.
+var driverDirs = []string{"/usr/lib/cups/filter", "/usr/lib/cups/backend"}
+
+// basePackages bring CUPS's own filters and backends, not a printer's driver.
+var basePackages = map[string]bool{"cups": true, "cups-filters": true, "libcups": true, "ghostscript": true, "cups-pdf": false}
+
+// Drivers answers how each queue prints and which packages bring drivers.
+func Drivers(match string, limit int) (DriversAnswer, error) {
+	out := DriversAnswer{Queues: []QueueDriver{}, Packages: []DriverPackage{}, Models: []Model{}, Findings: []string{}}
+	ps, err := Printers()
+	if err != nil {
+		return out, err
+	}
+	for _, p := range ps.Printers {
+		out.Queues = append(out.Queues, QueueDriver{Printer: p.Name, MakeModel: p.MakeModel, Driverless: p.Driverless, URI: p.URI})
+	}
+	r := run(Cmd{Name: "pacman", Args: append([]string{"-Qo"}, driverDirs...)})
+	if r.Error != "" {
+		return out, failure(Cmd{Name: "pacman", Args: []string{"-Qo"}}, r)
+	}
+	seen := map[string]bool{}
+	for _, l := range lines(r.Stdout) {
+		if _, after, ok := strings.Cut(l, " is owned by "); ok {
+			f := strings.Fields(after)
+			if len(f) >= 2 && !seen[f[0]] && !basePackages[f[0]] {
+				seen[f[0]] = true
+				out.Packages = append(out.Packages, DriverPackage{Package: f[0], Version: f[1]})
+			}
+		}
+	}
+	if len(out.Packages) > 0 {
+		r := run(Cmd{Name: "pacman", Args: []string{"-Qqm"}})
+		foreign := map[string]bool{}
+		for _, l := range lines(r.Stdout) {
+			foreign[strings.TrimSpace(l)] = true
+		}
+		for i := range out.Packages {
+			out.Packages[i].Foreign = foreign[out.Packages[i].Package]
+		}
+	}
+	sort.Slice(out.Packages, func(i, k int) bool { return out.Packages[i].Package < out.Packages[k].Package })
+	m, err := call(Cmd{Name: "lpinfo", Args: []string{"-m"}})
+	if err != nil {
+		return out, err
+	}
+	for _, l := range lines(m.Stdout) {
+		ppd, desc, _ := strings.Cut(l, " ")
+		if match != "" && !strings.Contains(strings.ToLower(desc), strings.ToLower(match)) && !strings.Contains(strings.ToLower(ppd), strings.ToLower(match)) {
+			continue
+		}
+		out.Matched++
+		if len(out.Models) < limit {
+			out.Models = append(out.Models, Model{PPD: ppd, Description: desc})
+		}
+	}
+	// Which driver packages no queue prints through.
+	allDriverless := len(out.Queues) > 0
+	for _, q := range out.Queues {
+		allDriverless = allDriverless && q.Driverless
+	}
+	for _, p := range out.Packages {
+		if p.Foreign {
+			out.Findings = append(out.Findings, "driver package "+p.Package+" is not from the official repositories")
+		}
+		if allDriverless {
+			out.Findings = append(out.Findings, "every queue prints driverless, so no queue uses the driver package "+p.Package)
+		}
+	}
+	return out, nil
+}

modules/cups/cmd/cups-tools/cups_test.go

@@ -0,0 +1,234 @@
+package main
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestTheManifestIsTheSchedulerAndDriverlessPrintingAndNoVendorDriver(t *testing.T) {
+	m := readManifest(t)
+	holdsTheBundle(t, m, "cups")
+	if got := strings.Join(m.packages(), ","); got != "cups,cups-filters" {
+		t.Errorf("packages %s: a vendor driver is from outside the official repositories, and no queue measured needs one but the desktop's Canon", got)
+	}
+	s := m.services()
+	for _, u := range []string{"cups.socket", "cups.service"} {
+		if s[u] == nil || s[u]["state"] != "running" || s[u]["boot"] != "enabled" {
+			t.Errorf("%s: %v", u, s[u])
+		}
+	}
+	for _, r := range m.Resources {
+		if r["type"] == "file" {
+			t.Errorf("the queues and cupsd's files are CUPS's own: %v", r["id"])
+		}
+	}
+}
+
+// The desktop's two queues on 2026-10-04.
+func theDesktop(t *testing.T, more func(line string, c Cmd) (Result, bool)) *fake {
+	return using(t, func(line string, c Cmd) Result {
+		if more != nil {
+			if r, handled := more(line, c); handled {
+				return r
+			}
+		}
+		switch line {
+		case "lpstat -r":
+			return ok("scheduler is running\n")
+		case "lpstat -d":
+			return ok("system default destination: Brother_MFC_Novox\n")
+		case "lpstat -p":
+			return ok("printer Brother_MFC_Novox is idle.  enabled since Mon Jun 29 21:34:30 2026\n" +
+				"printer Kanjuro disabled since Sun Jun  9 11:16:03 2024 -\n\tPaused\n")
+		case "lpstat -a":
+			return ok("Brother_MFC_Novox accepting requests since Mon Jun 29 21:34:30 2026\nKanjuro not accepting requests since Sun Jun  9 11:16:03 2024 -\n\tRejecting Jobs\n")
+		case "lpoptions -p Brother_MFC_Novox":
+			return ok(`copies=1 device-uri=ipp://192.0.2.171/ipp/port1 finishings=3 marker-levels=70,100,8,100 marker-low-levels=10,10,10,10 marker-names='Black\ Toner\ Cartridge,Cyan\ Toner\ Cartridge,Magenta\ Toner\ Cartridge,Yellow\ Toner\ Cartridge' marker-types=toner,toner,toner,toner printer-is-shared=false printer-make-and-model='Printer - IPP Everywhere' printer-state-reasons=none`)
+		case "lpoptions -p Kanjuro":
+			return ok(`device-uri=cnijnet:/18-0C-AC-B0-62-83 printer-is-shared=false printer-make-and-model='Canon MG4200 series Ver.3.80' printer-state-reasons=paused`)
+		}
+		return Result{Status: 9, Stderr: "unexpected " + line}
+	})
+}
+
+func TestPrintersReadsStateDeviceModelAndSupplies(t *testing.T) {
+	theDesktop(t, nil)
+	got, err := Printers()
+	if err != nil || len(got.Printers) != 2 || got.Default != "Brother_MFC_Novox" || got.Scheduler != "scheduler is running" {
+		t.Fatalf("%+v %v", got, err)
+	}
+	b, k := got.Printers[0], got.Printers[1]
+	if b.State != "idle" || !b.Enabled || !b.Accepting || !b.Default || !b.Driverless || b.URI != "ipp://192.0.2.171/ipp/port1" || len(b.Reasons) != 0 {
+		t.Errorf("%+v", b)
+	}
+	if len(b.Markers) != 4 || b.Markers[0].Name != "Black Toner Cartridge" || b.Markers[2].Level != 8 || !b.Markers[2].Low || b.Markers[0].Low {
+		t.Errorf("markers %+v", b.Markers)
+	}
+	if k.State != "stopped" || k.Enabled || k.Accepting || k.Driverless || strings.Join(k.Reasons, ",") != "paused" || k.Message != "Paused" {
+		t.Errorf("%+v", k)
+	}
+}
+
+func TestPrintersWithoutAQueueOrAScheduler(t *testing.T) {
+	using(t, func(line string, c Cmd) Result {
+		if line == "lpstat -r" {
+			return ok("scheduler is running\n")
+		}
+		return Result{Status: 1, Stderr: "lpstat: No destinations added.\n"}
+	})
+	got, err := Printers()
+	if err != nil || len(got.Printers) != 0 {
+		t.Fatalf("no queue is an empty answer, not a failure: %+v %v", got, err)
+	}
+	using(t, func(string, Cmd) Result { return Result{Status: 1, Stderr: "lpstat: Scheduler is not running.\n"} })
+	if _, err := Printers(); err == nil || !strings.Contains(err.Error(), "scheduler is not running") {
+		t.Fatalf("%v", err)
+	}
+}
+
+func TestLpoptionsQuotingIsRead(t *testing.T) {
+	o := lpoptionsOf(`a=1 b='x y' c=p\ q d e=`)
+	if o["a"] != "1" || o["b"] != "x y" || o["c"] != "p q" || o["d"] != "" || o["e"] != "" {
+		t.Errorf("%v", o)
+	}
+}
+
+func TestQueueReadsJobsNewestFirstAndBounded(t *testing.T) {
+	f := using(t, func(string, Cmd) Result {
+		return ok("Brother-6               jochen            1024   Mon Jul  8 12:15:34 2024\nBrother-8               jochen            2048   Mon Jul  8 12:19:56 2024\nBrother-7               other             1024   Mon Jul  8 12:15:23 2024\n")
+	})
+	got, err := Queue("Brother", true, 2)
+	jobs := got["jobs"].([]Job)
+	if err != nil || got["count"] != 3 || len(jobs) != 2 || jobs[0].ID != "Brother-8" || jobs[0].Printer != "Brother" || jobs[0].Bytes != 2048 || jobs[0].Submitted != "Mon Jul 8 12:19:56 2024" {
+		t.Fatalf("%+v %v", got, err)
+	}
+	if f.lines()[0] != "lpstat -W completed -o Brother" {
+		t.Errorf("%v", f.lines())
+	}
+	if _, err := Queue("-h", false, 5); err == nil {
+		t.Error("an option as a printer")
+	}
+}
+
+func TestCancelTriesTheAccountThenRootWhenCUPSRefusesIt(t *testing.T) {
+	f := using(t, func(line string, c Cmd) Result {
+		if !strings.HasPrefix(line, "sudo") {
+			return Result{Status: 1, Stderr: "cancel: Forbidden\n"}
+		}
+		return ok("")
+	})
+	got, err := Cancel("Brother-12", "", false)
+	if err != nil || got["as_root"] != true {
+		t.Fatalf("%v %v", got, err)
+	}
+	if strings.Join(f.lines(), "|") != "cancel Brother-12|sudo -n cancel Brother-12" {
+		t.Errorf("%v", f.lines())
+	}
+	f = using(t, func(string, Cmd) Result { return ok("") })
+	if got, err := Cancel("", "Brother", true); err != nil || got["as_root"] != false || f.lines()[0] != "cancel -a Brother" {
+		t.Fatalf("%v %v %v", got, err, f.lines())
+	}
+	using(t, func(string, Cmd) Result { return Result{Status: 1, Stderr: "cancel: Unknown job 99\n"} })
+	if _, err := Cancel("99", "", false); err == nil || !strings.Contains(err.Error(), "Unknown job") {
+		t.Errorf("a failure that is not a refusal is not retried as root: %v", err)
+	}
+	for _, bad := range [][3]string{{"", "", ""}, {"12; rm", "", ""}, {"", "", "all"}} {
+		if _, err := Cancel(bad[0], bad[1], bad[2] == "all"); err == nil {
+			t.Errorf("%v accepted", bad)
+		}
+	}
+}
+
+func TestPrintChecksTheFileAndOptionsAndAnswersTheJob(t *testing.T) {
+	was := statFile
+	defer func() { statFile = was }()
+	statFile = func(p string) error {
+		if p == "/home/op/doc.pdf" {
+			return nil
+		}
+		return errString("no such file")
+	}
+	f := using(t, func(string, Cmd) Result { return ok("request id is Brother-13 (1 file(s))\n") })
+	got, err := Print("/home/op/doc.pdf", "Brother", 2, map[string]string{"sides": "two-sided-long-edge", "media": "A4"}, "")
+	if err != nil || got["job"] != "Brother-13" {
+		t.Fatalf("%v %v", got, err)
+	}
+	if l := f.lines()[0]; l != "lp -d Brother -n 2 -o media=A4 -o sides=two-sided-long-edge -t doc.pdf -- /home/op/doc.pdf" {
+		t.Errorf("%s", l)
+	}
+	if _, err := Print("doc.pdf", "", 1, nil, ""); err == nil {
+		t.Error("a relative file")
+	}
+	if _, err := Print("/home/op/missing.pdf", "", 1, nil, ""); err == nil {
+		t.Error("a missing file")
+	}
+	if _, err := optionsOf(map[string]any{"options": map[string]any{"sides": "x y"}}); err == nil {
+		t.Error("an option value with a space")
+	}
+	if _, err := optionsOf(map[string]any{"options": map[string]any{"-o": "x"}}); err == nil {
+		t.Error("an option name that is an option")
+	}
+	using(t, func(string, Cmd) Result { return Result{Status: 1, Stderr: "lp: Error - No default destination."} })
+	if _, err := Print("/home/op/doc.pdf", "", 1, nil, ""); err == nil || !strings.Contains(err.Error(), "no default printer") {
+		t.Errorf("%v", err)
+	}
+}
+
+type errString string
+
+func (e errString) Error() string { return string(e) }
+
+func TestDefaultReadsAndSetsThroughSudo(t *testing.T) {
+	f := theDesktop(t, func(line string, c Cmd) (Result, bool) {
+		if strings.HasPrefix(line, "sudo -n lpadmin") {
+			return ok(""), true
+		}
+		return Result{}, false
+	})
+	got, err := Default("")
+	if err != nil || got["default"] != "Brother_MFC_Novox" {
+		t.Fatalf("%v %v", got, err)
+	}
+	got, err = Default("Kanjuro")
+	if err != nil || got["default"] != "Kanjuro" || got["was"] != "Brother_MFC_Novox" {
+		t.Fatalf("%v %v", got, err)
+	}
+	if l := f.lines(); l[len(l)-1] != "sudo -n lpadmin -d Kanjuro" {
+		t.Errorf("%v", l)
+	}
+}
+
+func TestResumeEnablesAndAcceptsThroughSudo(t *testing.T) {
+	f := using(t, func(string, Cmd) Result { return ok("") })
+	if _, err := Resume("Kanjuro"); err != nil {
+		t.Fatal(err)
+	}
+	if strings.Join(f.lines(), "|") != "sudo -n cupsenable Kanjuro|sudo -n cupsaccept Kanjuro" {
+		t.Errorf("%v", f.lines())
+	}
+}
+
+func TestDriversNamesForeignDriverPackagesAndOnesNoQueueUses(t *testing.T) {
+	theDesktop(t, func(line string, c Cmd) (Result, bool) {
+		switch {
+		case strings.HasPrefix(line, "pacman -Qo"):
+			return ok("/usr/lib/cups/filter/ is owned by brother-mfc-l8390cdw 3.5.1-2\n/usr/lib/cups/filter/ is owned by cups 2:2.4.19-1\n/usr/lib/cups/filter/ is owned by cups-filters 2.0.1-2\n/usr/lib/cups/backend/ is owned by cnijfilter-mg4200 3.80-6\n/usr/lib/cups/backend/ is owned by cups 2:2.4.19-1\n"), true
+		case line == "pacman -Qqm":
+			return ok("brother-mfc-l8390cdw\ncnijfilter-mg4200\nsnapd\n"), true
+		case line == "lpinfo -m":
+			return ok("drv:///sample.drv/dymo.ppd DYMO Label Printer\ncanonmg4200.ppd Canon MG4200 series Ver.3.80\neverywhere IPP Everywhere\n"), true
+		}
+		return Result{}, false
+	})
+	got, err := Drivers("canon", 10)
+	if err != nil || len(got.Queues) != 2 || len(got.Packages) != 2 || got.Matched != 1 || got.Models[0].PPD != "canonmg4200.ppd" {
+		t.Fatalf("%+v %v", got, err)
+	}
+	if !got.Packages[0].Foreign || got.Packages[0].Package != "brother-mfc-l8390cdw" {
+		t.Errorf("%+v", got.Packages)
+	}
+	all := strings.Join(got.Findings, ";")
+	if !strings.Contains(all, "cnijfilter-mg4200 is not from the official") || strings.Contains(all, "every queue prints driverless") {
+		t.Errorf("the Canon queue uses its driver, so not every queue is driverless: %s", all)
+	}
+}

modules/cups/cmd/cups-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/cups/cmd/cups-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/cups/cmd/cups-tools/main.go

@@ -0,0 +1,177 @@
+// The cups module's tools (novox/hq research 027/02, 026/05): the printers, their state, supplies and
+// driver, the queue, and printing, cancelling and choosing the default. A Go bundle the node's runtime
+// launches over stdio (ADR 0188, ADR 0193); it runs as the operator account. An act CUPS keeps for
+// its administrators goes through `sudo -n`.
+package main
+
+import (
+	"fmt"
+	"os"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+var providedBy = map[string]string{
+	"lpstat":     "the cups package, which this module installs",
+	"lpoptions":  "the cups package, which this module installs",
+	"lp":         "the cups package, which this module installs",
+	"cancel":     "the cups package, which this module installs",
+	"lpadmin":    "the cups package, which this module installs",
+	"lpinfo":     "the cups package, which this module installs",
+	"cupsenable": "the cups package, which this module installs",
+	"cupsaccept": "the cups package, which this module installs",
+	"pacman":     "this is not an Arch machine",
+}
+
+func main() {
+	if err := stdio.Serve("", tools()); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+var printerArg = map[string]any{"type": "string", "description": "the printer's queue name, as cups_printers answers it"}
+
+func tools() []stdio.Tool {
+	return []stdio.Tool{
+		{
+			Name: "cups_printers",
+			Description: "Every printer queue: state, whether it is enabled and accepting jobs, the default, its device " +
+				"address, make and model, whether it prints driverless (IPP Everywhere), the reasons for its state, and " +
+				"supply levels where the printer reports them. (r)",
+			Input: map[string]any{},
+			Run:   func(map[string]any) (any, error) { return Printers() },
+		},
+		{
+			Name: "cups_queue",
+			Description: "The jobs waiting or printing, on every printer or one; or, with completed, the finished ones. " +
+				"Each with its id, printer, owner, size and when it was submitted. (r)",
+			Input: map[string]any{
+				"printer":   printerArg,
+				"completed": map[string]any{"type": "boolean", "description": "the finished jobs instead"},
+				"limit":     map[string]any{"type": "integer", "description": "at most this many, newest first (default 50, at most 500)"},
+			},
+			Run: func(args map[string]any) (any, error) {
+				p, err := optText(args, "printer", "")
+				if err != nil {
+					return nil, err
+				}
+				done, err := optFlag(args, "completed", false)
+				if err != nil {
+					return nil, err
+				}
+				limit, err := optWhole(args, "limit", 50, 1, 500)
+				if err != nil {
+					return nil, err
+				}
+				return Queue(p, done, limit)
+			},
+		},
+		{
+			Name: "cups_cancel",
+			Description: "Cancel one job by its id (\"Brother-12\" or 12), or every job on a printer with all. Another " +
+				"account's job is cancelled through sudo -n. (a)",
+			Input: map[string]any{
+				"job":     map[string]any{"type": "string", "description": "the job id"},
+				"printer": printerArg,
+				"all":     map[string]any{"type": "boolean", "description": "every job on printer"},
+			},
+			Run: func(args map[string]any) (any, error) {
+				job, err := optText(args, "job", "")
+				if err != nil {
+					return nil, err
+				}
+				p, err := optText(args, "printer", "")
+				if err != nil {
+					return nil, err
+				}
+				all, err := optFlag(args, "all", false)
+				if err != nil {
+					return nil, err
+				}
+				return Cancel(job, p, all)
+			},
+		},
+		{
+			Name: "cups_print",
+			Description: "Print a file on this machine, to a printer or the default, with copies and IPP options such as " +
+				"sides=two-sided-long-edge or media=A4. Answers the job id. (a)",
+			Input: map[string]any{
+				"file":    map[string]any{"type": "string", "description": "the file's absolute path on this machine"},
+				"printer": printerArg,
+				"copies":  map[string]any{"type": "integer", "description": "copies (default 1, at most 99)"},
+				"options": map[string]any{"type": "object", "additionalProperties": map[string]any{"type": "string"}, "description": "IPP options, name to value"},
+				"title":   map[string]any{"type": "string", "description": "the job's title (default the file's name)"},
+			},
+			Run: func(args map[string]any) (any, error) {
+				file, err := text(args, "file")
+				if err != nil {
+					return nil, err
+				}
+				p, err := optText(args, "printer", "")
+				if err != nil {
+					return nil, err
+				}
+				copies, err := optWhole(args, "copies", 1, 1, 99)
+				if err != nil {
+					return nil, err
+				}
+				opts, err := optionsOf(args)
+				if err != nil {
+					return nil, err
+				}
+				title, err := optText(args, "title", "")
+				if err != nil {
+					return nil, err
+				}
+				return Print(file, p, copies, opts, title)
+			},
+		},
+		{
+			Name: "cups_default",
+			Description: "The machine's default printer; with printer, make that printer the default (through sudo -n). " +
+				"The default is CUPS's own setting, kept as the operator chose it: the mesh does not declare it. (r/a)",
+			Input: map[string]any{"printer": printerArg},
+			Run: func(args map[string]any) (any, error) {
+				p, err := optText(args, "printer", "")
+				if err != nil {
+					return nil, err
+				}
+				return Default(p)
+			},
+		},
+		{
+			Name:        "cups_resume",
+			Description: "Enable a printer and make it accept jobs again, after CUPS stopped it on an error. Through sudo -n. (a)",
+			Input:       map[string]any{"printer": printerArg},
+			Run: func(args map[string]any) (any, error) {
+				p, err := text(args, "printer")
+				if err != nil {
+					return nil, err
+				}
+				return Resume(p)
+			},
+		},
+		{
+			Name: "cups_drivers",
+			Description: "What each printer prints through (driverless or a driver's PPD), the packages that bring drivers " +
+				"and backends, which of them are from outside the official repositories, and the driver models CUPS " +
+				"offers, filtered by match. (r)",
+			Input: map[string]any{
+				"match": map[string]any{"type": "string", "description": "only models whose description contains this, any case"},
+				"limit": map[string]any{"type": "integer", "description": "at most this many models (default 50, at most 1000)"},
+			},
+			Run: func(args map[string]any) (any, error) {
+				match, err := optText(args, "match", "")
+				if err != nil {
+					return nil, err
+				}
+				limit, err := optWhole(args, "limit", 50, 0, 1000)
+				if err != nil {
+					return nil, err
+				}
+				return Drivers(match, limit)
+			},
+		},
+	}
+}

modules/cups/cmd/cups-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/cups/go.mod

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

modules/cups/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=