The store collects nightly again (hq ADR 0189)

Withdrawn 2026-10-04 to unblock novox: while-stopped named the module-local
id and the host refuses a declaration naming a container it does not have,
whole. mesh-controller#259 fixed the namespacing and it has been live since,
so the window composes as distribution.store and the host will take it.

Unchanged from before: plain garbage-collect at 03:30 with the server held
still. The store is at 40G and nothing reclaims it until this runs.

modules/blueman/README.md

@@ -0,0 +1,82 @@
+# blueman
+
+The Bluetooth tray applet on the workstations, as a module (novox/hq ADR 0208). It requires
+`x11-display`, so it is assigned only where a display server is held on the same machine.
+
+## Owns
+
+| what | where |
+|---|---|
+| the applet, the manager window, send-to | package `blueman`, from the official repositories |
+
+Nothing else. It holds no seat, makes no contribution and writes no file.
+
+- **No AUR.** Both workstations run the official package (`extra`), installed explicitly.
+- **The Bluetooth stack is not this module's.** `bluez`, `bluez-utils` and `bluetooth.service` belong
+  to the `bluetooth` module. This module declares none of them (ADR 0210 §4: one package, one module).
+  The devices, pairing and power are that module's tools (`bluetooth_*`). This module's tools are
+  about the applet.
+- **The operator's applet settings are found.** blueman keeps them in dconf (`org.blueman.*`): the
+  plugin switches, the recent connections, auto-connect and auto-power-on. The module neither sets nor
+  resets them. `blueman_status` shows the plugin switches.
+
+## How it starts: the package's autostart entry, and nothing else
+
+One process has one starter (the rule `picom` states for the desktop modules). The package ships
+`/etc/xdg/autostart/blueman.desktop` (`blueman-applet`). The session runs it once at login through
+the `i3` module's `dex --autostart --environment i3`. **That entry is the applet's one start.** The
+module adds no `xinitrc` slot and no `node-display-session` exec, because either would start it a
+second time.
+
+- **Excluded:** the window manager's `exec … blueman-applet`, which the `i3` module's configuration
+  dropped.
+- **Not a start:** the package's user unit `blueman-applet.service` is static. It exists for D-Bus
+  activation of `org.blueman.Applet`. A program that calls the applet's bus name while no applet runs
+  starts one through it. The applet is single-instance on that name, so this never makes a second
+  one. The tools always ask the bus with `--auto-start=no`, so asking never starts it.
+- The applet starts its tray icon, `blueman-tray`, itself.
+
+## Tools
+
+They are served by the node's runtime as the operator account (ADR 0175).
+
+| tool | does |
+|---|---|
+| `blueman_status` (r) | <ul><li>whether the applet and its tray icon run: pid, since, and the scope or unit they run in</li><li>the installed version, and what starts it at login</li><li>the plugins the running applet has loaded and those it has not (asked of the applet on the session bus)</li><li>the plugin switches in `org.blueman.general plugin-list`</li><li>whether the applet sees Bluetooth on</li></ul> |
+| `blueman_restart` (a) | asks the applet and the tray icon to end (SIGTERM), forces them after 5 s, and starts `blueman-applet` in the operator's session. The start is a transient user unit `mesh-blueman-applet`, so it outlives the tools runtime. Answers the pids. Refused plainly when nobody is logged in to the desktop |
+| `blueman_check` (r) | <ul><li>the package is installed</li><li>exactly one start: the package's entry is present and not hidden by an entry of the account, and `dex` is installed</li><li>no window-manager exec</li><li>one applet runs in a desktop session</li><li>`bluetooth.service` is active</li></ul>Each finding says what to do |
+
+The tools find the session's `DISPLAY` and `XAUTHORITY` from the window manager's own environment,
+as `clipmenu` and `screen-lock` do. Every command has a timeout and capped output. Everything runs
+through an injected runner and a fake root in the tests.
+
+## What changes when it is assigned
+
+| | g14 | shanks |
+|---|---|---|
+| package | none: `blueman` 2.4.6 is installed, explicitly, from `extra` | the same |
+| start | none: dex starts the applet from the package's entry, in the login session's scope; the tray icon with it | none on disk. **The applet running now came from the predecessor's window-manager line** (a child of i3, since the session of 2026-10-04 16:00). That session began before the `i3` module dropped the line and installed `dex`, so the next login is the first that starts it from the entry |
+| settings (dconf) | defaults, no plugin switched; recent connections only | no plugin switched; auto-connect for one headset, auto-power-on set |
+
+The workstations are already in the state this module describes.
+
+## Migration (ADR 0182)
+
+Nothing is required on either machine. On shanks, log out and in once, or run `blueman_restart`, and
+the applet runs from its one start. `blueman_check` then answers `ok`.
+
+## Leaves as found
+
+- The applet's dconf settings (`/org/blueman/`).
+- `/etc/xdg/autostart/blueman.desktop`, the package's own file.
+
+## Relies on
+
+- **The `bluetooth` module, for bluez and its daemon.** Without them the applet has nothing to
+  manage. There is no dependency mechanism between two modules that hold no seat. So nothing refuses
+  `blueman` on a node without `bluetooth`. `blueman_check` reports it instead, from
+  `bluetooth.service`. **Assign both.** When the stack becomes a seat (`node-bluetooth`), this module
+  depends on the seat.
+- **`i3`'s `dex` line for the start**, which is equally undeclared: XDG autostart has no seat.
+  Assigned without `i3`, the applet is installed and does not start. `blueman_check` says so.
+- A display server on the same machine (`x11-display`, ADR 0208 §3).

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

@@ -0,0 +1,221 @@
+package main
+
+// blueman's applet as the tools see it: its processes, its XDG autostart entry (the package's), the
+// applet's own answers on the session bus, and its settings in gsettings. Every bus call is made with
+// --auto-start=no: the applet is D-Bus activatable, and a question must never start it.
+
+import (
+	"encoding/json"
+	"fmt"
+	"sort"
+	"strings"
+	"time"
+)
+
+const (
+	appletComm = "blueman-applet"
+	trayComm   = "blueman-tray"
+	appletBin  = "/usr/bin/blueman-applet"
+	entryName  = "blueman.desktop"
+	restartAs  = "mesh-blueman-applet"
+	packageFor = "blueman"
+	busName    = "org.blueman.Applet"
+	busPath    = "/org/blueman/Applet"
+	stackUnit  = "bluetooth.service"
+)
+
+// appletCall asks the running applet one question over the session bus and answers busctl's JSON.
+func (m *Machine) appletCall(method string) (json.RawMessage, error) {
+	args := []string{"--user", "--auto-start=no", "--json=short", "call", busName, busPath, busName, method}
+	o := m.cmd(5*time.Second, m.bus(), "busctl", args...)
+	if err := failed(o, "busctl", args...); err != nil {
+		return nil, err
+	}
+	var doc struct {
+		Data []json.RawMessage `json:"data"`
+	}
+	if err := json.Unmarshal([]byte(o.Stdout), &doc); err != nil || len(doc.Data) != 1 {
+		return nil, fmt.Errorf("the applet's answer to %s is not busctl's JSON: %q", method, tail(o.Stdout, 200))
+	}
+	return doc.Data[0], nil
+}
+
+func (m *Machine) appletStrings(method string) ([]string, error) {
+	raw, err := m.appletCall(method)
+	if err != nil {
+		return nil, err
+	}
+	var out []string
+	if err := json.Unmarshal(raw, &out); err != nil {
+		return nil, fmt.Errorf("the applet's %s is not a list of names: %w", method, err)
+	}
+	sort.Strings(out)
+	return out, nil
+}
+
+// gvariantStrings reads gsettings' printed array of strings: "@as []" or "['a', '!b']".
+func gvariantStrings(s string) []string {
+	s = strings.TrimSpace(strings.TrimPrefix(strings.TrimSpace(s), "@as"))
+	s = strings.TrimSuffix(strings.TrimPrefix(s, "["), "]")
+	out := []string{}
+	for _, item := range strings.Split(s, ",") {
+		item = strings.Trim(strings.TrimSpace(item), `'"`)
+		if item != "" {
+			out = append(out, item)
+		}
+	}
+	return out
+}
+
+// Plugins is which applet plugins run, and what the operator's settings say about them.
+type Plugins struct {
+	// Loaded are the plugins the running applet answers it has loaded.
+	Loaded []string `json:"loaded"`
+	// NotLoaded are the plugins it knows but did not load: switched off, or not fit for this machine.
+	NotLoaded []string `json:"not_loaded"`
+	// Switched is the operator's plugin-list setting: a name to load it, !name to keep it off. Empty
+	// is blueman's defaults.
+	Switched []string `json:"switched"`
+}
+
+// AppletStatus is what blueman_status answers.
+type AppletStatus struct {
+	Installed string    `json:"installed,omitempty"`
+	Applet    []Proc    `json:"applet"`
+	Tray      []Proc    `json:"tray"`
+	StartedBy Autostart `json:"started_by"`
+	// Bluetooth is the applet's own view of the adapter's power, when it runs.
+	Bluetooth *bool   `json:"bluetooth_on,omitempty"`
+	Plugins   Plugins `json:"plugins"`
+	// Unanswered says why the running applet's view is missing.
+	Unanswered string `json:"unanswered,omitempty"`
+}
+
+// Status reads the applet: running or not, how it starts, and its plugins.
+func (m *Machine) Status() (AppletStatus, error) {
+	s := AppletStatus{Applet: m.procs(appletComm), Tray: m.procs(trayComm), StartedBy: m.autostart(entryName),
+		Plugins: Plugins{Loaded: []string{}, NotLoaded: []string{}, Switched: []string{}}}
+	if s.Applet == nil {
+		s.Applet = []Proc{}
+	}
+	if s.Tray == nil {
+		s.Tray = []Proc{}
+	}
+	if v, err := m.installed(packageFor); err == nil {
+		s.Installed = v
+	}
+	o := m.cmd(5*time.Second, m.bus(), "gsettings", "get", "org.blueman.general", "plugin-list")
+	if o.Err == nil && o.Code == 0 {
+		s.Plugins.Switched = gvariantStrings(o.Stdout)
+	}
+	if len(s.Applet) == 0 {
+		s.Unanswered = "the applet is not running"
+		return s, nil
+	}
+	loaded, err := m.appletStrings("QueryPlugins")
+	if err != nil {
+		s.Unanswered = err.Error()
+		return s, nil
+	}
+	s.Plugins.Loaded = loaded
+	if all, err := m.appletStrings("QueryAvailablePlugins"); err == nil {
+		in := map[string]bool{}
+		for _, p := range loaded {
+			in[p] = true
+		}
+		for _, p := range all {
+			if !in[p] {
+				s.Plugins.NotLoaded = append(s.Plugins.NotLoaded, p)
+			}
+		}
+	}
+	if raw, err := m.appletCall("GetBluetoothStatus"); err == nil {
+		var on bool
+		if json.Unmarshal(raw, &on) == nil {
+			s.Bluetooth = &on
+		}
+	}
+	return s, nil
+}
+
+// RestartAnswer is what blueman_restart answers.
+type RestartAnswer struct {
+	Ended   []int   `json:"ended"`
+	Killed  []int   `json:"killed,omitempty"`
+	Running []Proc  `json:"running"`
+	Session Session `json:"session"`
+	Unit    string  `json:"unit"`
+}
+
+// Restart ends the applet and its tray icon, and starts the applet again in the operator's session
+// under the account's service manager. The applet starts its tray icon itself.
+func (m *Machine) Restart() (RestartAnswer, error) {
+	s, err := m.session()
+	if err != nil {
+		return RestartAnswer{}, err
+	}
+	a := RestartAnswer{Session: s, Unit: restartAs + ".service"}
+	a.Ended, a.Killed = m.stop(5*time.Second, appletComm, trayComm)
+	if err := m.detach(s, restartAs, appletBin); err != nil {
+		return a, err
+	}
+	a.Running = m.waitFor(appletComm, 4*time.Second)
+	if len(a.Running) == 0 {
+		return a, fmt.Errorf("the applet was started as %s but no %s process appeared within 4 s: "+
+			"see `journalctl --user -u %s`", a.Unit, appletComm, a.Unit)
+	}
+	return a, nil
+}
+
+// CheckAnswer is what blueman_check answers.
+type CheckAnswer struct {
+	OK       bool      `json:"ok"`
+	Findings []Finding `json:"findings"`
+	Starts   []string  `json:"starts"`
+}
+
+// Check verifies what the module promises and relies on: the package; one start (the package's
+// autostart entry, which the session's dex runs); the applet running once in a session; and the
+// Bluetooth daemon it manages, which is the bluetooth module's.
+func (m *Machine) Check() (CheckAnswer, error) {
+	a := CheckAnswer{Findings: []Finding{}, Starts: []string{}}
+	add := func(what, do string) { a.Findings = append(a.Findings, Finding{what, do}) }
+	v, err := m.installed(packageFor)
+	if err != nil {
+		return a, err
+	}
+	if v == "" {
+		add("the package blueman is not installed", "push the module to the node")
+	}
+	entry := m.autostart(entryName)
+	if entry.Starts {
+		a.Starts = append(a.Starts, "XDG autostart: "+entry.From)
+		if entry.From != "/etc/xdg/autostart/"+entryName {
+			add("the account's own "+entry.From+" replaces the package's entry", "remove it, so the package's entry is the one start")
+		}
+	} else {
+		add("the applet does not start with the session ("+entry.Because+")", "remove ~/.config/autostart/"+entryName+" if it hides the package's entry")
+	}
+	if o := m.cmd(0, nil, "dex", "--version"); o.Err != nil {
+		add("dex, which runs the XDG autostart entries at login, is not installed", "assign the i3 module, which installs it and runs it")
+	}
+	for _, l := range m.i3Starts(appletComm) {
+		a.Starts = append(a.Starts, "window manager: "+l)
+		add("a second start: "+l, "remove the line; the package's autostart entry is the applet's one start")
+	}
+	if o := m.cmd(0, nil, "systemctl", "is-active", stackUnit); o.Err != nil || strings.TrimSpace(o.Stdout) != "active" {
+		add("the Bluetooth daemon ("+stackUnit+") is not running: the applet has nothing to manage",
+			"assign the bluetooth module, which owns bluez and its daemon")
+	}
+	running := m.procs(appletComm)
+	if _, err := m.session(); err == nil {
+		switch {
+		case len(running) == 0:
+			add("no applet runs in the desktop session", "blueman_restart")
+		case len(running) > 1:
+			add(fmt.Sprintf("%d applets run", len(running)), "blueman_restart ends them all and starts one")
+		}
+	}
+	a.OK = len(a.Findings) == 0
+	return a, nil
+}

modules/blueman/cmd/blueman-tools/blueman_test.go

@@ -0,0 +1,126 @@
+package main
+
+import (
+	"strings"
+	"testing"
+)
+
+func newApplet(t *testing.T, running bool) *fake {
+	f := newFake(t)
+	f.write("/etc/xdg/autostart/blueman.desktop", "[Desktop Entry]\nName=Blueman Applet\nExec=blueman-applet\nType=Application\n")
+	if running {
+		f.proc(3859, 1000, appletComm, []string{"/usr/bin/python", "/usr/bin/blueman-applet"}, "session-c1.scope")
+		f.proc(4084, 1000, trayComm, []string{"/usr/bin/python", "/usr/bin/blueman-tray"}, "session-c1.scope")
+	}
+	f.answer = func(name string, args []string) Output {
+		call := name + " " + strings.Join(args, " ")
+		switch {
+		case name == "pacman":
+			return Output{Stdout: "blueman 2.4.6-2\n"}
+		case name == "gsettings":
+			return Output{Stdout: "['!NetUsage', 'DhcpClient']\n"}
+		case strings.HasSuffix(call, " QueryPlugins"):
+			return Output{Stdout: `{"type":"as","data":[["StatusIcon","AuthAgent","PowerManager"]]}`}
+		case strings.HasSuffix(call, " QueryAvailablePlugins"):
+			return Output{Stdout: `{"type":"as","data":[["StatusIcon","AuthAgent","PowerManager","NetUsage"]]}`}
+		case strings.HasSuffix(call, " GetBluetoothStatus"):
+			return Output{Stdout: `{"type":"b","data":[true]}`}
+		case name == "systemctl" && len(args) > 1 && args[0] == "is-active":
+			return Output{Stdout: "active\n"}
+		}
+		return Output{}
+	}
+	return f
+}
+
+func TestStatusAsksTheRunningAppletAndNeverStartsIt(t *testing.T) {
+	f := newApplet(t, true)
+	s, err := f.Status()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if s.Installed != "2.4.6-2" || len(s.Applet) != 1 || len(s.Tray) != 1 || !s.StartedBy.Starts || s.Bluetooth == nil || !*s.Bluetooth {
+		t.Fatalf("%+v", s)
+	}
+	if strings.Join(s.Plugins.Loaded, ",") != "AuthAgent,PowerManager,StatusIcon" || strings.Join(s.Plugins.NotLoaded, ",") != "NetUsage" ||
+		strings.Join(s.Plugins.Switched, ",") != "!NetUsage,DhcpClient" {
+		t.Fatalf("%+v", s.Plugins)
+	}
+	for _, c := range f.calls {
+		if strings.HasPrefix(c, "busctl") && !strings.Contains(c, "--auto-start=no") {
+			t.Fatalf("a bus call that could start the applet: %s", c)
+		}
+	}
+
+	stopped := newApplet(t, false)
+	s, err = stopped.Status()
+	if err != nil || s.Unanswered != "the applet is not running" || len(s.Applet) != 0 || s.Bluetooth != nil {
+		t.Fatalf("%+v %v", s, err)
+	}
+	if stopped.called("busctl") {
+		t.Fatalf("asked the bus with no applet running: %q", stopped.calls)
+	}
+}
+
+func TestSettingsListsAreReadAsGSettingsPrintsThem(t *testing.T) {
+	for in, want := range map[string]string{"@as []\n": "", "['a']": "a", "['!a', 'b']\n": "!a,b"} {
+		if got := strings.Join(gvariantStrings(in), ","); got != want {
+			t.Errorf("%q: %q, not %q", in, got, want)
+		}
+	}
+}
+
+func TestRestartEndsAppletAndTrayAndStartsTheApplet(t *testing.T) {
+	f := newApplet(t, true)
+	if _, err := f.Restart(); err == nil || !strings.Contains(err.Error(), "no graphical session") {
+		t.Fatalf("without a desktop: %v", err)
+	}
+	f.desktopSession()
+	f.onStart = func(argv []string) { f.proc(9100, 1000, appletComm, argv, "app.slice/"+restartAs+".service") }
+	a, err := f.Restart()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(a.Ended) != 2 || len(a.Running) != 1 || a.Running[0].PID != 9100 || a.Running[0].Command != appletBin {
+		t.Fatalf("%+v", a)
+	}
+	if !f.called("systemd-run --user --collect --quiet --unit=" + restartAs + " --setenv=DISPLAY=:1") {
+		t.Fatalf("%q", f.calls)
+	}
+}
+
+func TestCheckPassesThePackagesOneStartAndNamesEveryOther(t *testing.T) {
+	f := newApplet(t, true)
+	f.desktopSession()
+	c, err := f.Check()
+	if err != nil || !c.OK || len(c.Starts) != 1 || c.Starts[0] != "XDG autostart: /etc/xdg/autostart/blueman.desktop" {
+		t.Fatalf("%+v %v", c, err)
+	}
+
+	f.write(testHome+"/.config/i3/config", "exec --no-startup-id blueman-applet\n")
+	f.write(testHome+"/.config/autostart/blueman.desktop", "[Desktop Entry]\nExec=blueman-applet\nHidden=true\n")
+	f.proc(3860, 1000, appletComm, []string{"blueman-applet"}, "session-c1.scope")
+	f.answer = func(name string, args []string) Output {
+		switch name {
+		case "pacman":
+			return Output{Code: 1}
+		case "systemctl":
+			return Output{Stdout: "inactive\n", Code: 3}
+		case "dex":
+			return Output{Code: 127, Err: ErrNotInstalled}
+		}
+		return Output{}
+	}
+	c, _ = f.Check()
+	var all []string
+	for _, x := range c.Findings {
+		all = append(all, x.What)
+	}
+	got := strings.Join(all, "\n")
+	for _, want := range []string{"not installed", "does not start with the session (Hidden=true)", "dex", "a second start: ~/.config/i3/config:1",
+		"bluetooth.service", "2 applets run"} {
+		if !strings.Contains(got, want) {
+			t.Errorf("no finding %q in\n%s", want, got)
+		}
+	}
+}

modules/blueman/cmd/blueman-tools/desktop.go

@@ -0,0 +1,574 @@
+package main
+
+// desktop.go is the same file in the nextcloud-client and blueman bundles: a tray application of the
+// operator's graphical session, seen from the node's tool runtime (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. A tool that starts something on the desktop finds the
+// session from a process of the account that carries DISPLAY (the window manager first), and starts
+// the program under the account's own service manager with `systemd-run --user`, never as its own
+// child: the runtime's unit is a cgroup that is emptied whenever the runtime restarts.
+//
+// Everything a tool touches goes through a Machine: its filesystem root, its commands (a Runner) and
+// its signals are injected, so the tests run against a fake /proc and a fake home.
+//
+// Bounds: one command gets at most CallTimeout (below the runtime's 30 s call limit) and is ended
+// with everything it started when it takes longer; each stream is kept to MostOutput; a file is read
+// to at most MostRead.
+
+import (
+	"bufio"
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"syscall"
+	"time"
+)
+
+// Bounds every command and read is held to.
+const (
+	CallTimeout = 10 * time.Second
+	MostOutput  = 256 << 10
+	MostRead    = 16 << 20
+)
+
+// Output is what a command did.
+type Output struct {
+	Stdout string
+	Stderr string
+	Code   int
+	// Err is why it did not run to an answer: not installed, ended on its timeout, or the spawn error.
+	Err error
+	Cut bool
+}
+
+// ErrNotInstalled and ErrTimedOut are what a Runner answers in Output.Err.
+var (
+	ErrNotInstalled = errors.New("not installed")
+	ErrTimedOut     = errors.New("timed out")
+	// ErrNoSession is answered by a tool that needs the desktop when nobody is logged in to it.
+	ErrNoSession = errors.New("no graphical session")
+)
+
+// Runner runs one command with extra environment, within the context's deadline. Tests replace it.
+type Runner func(ctx context.Context, env []string, name string, args ...string) Output
+
+// Machine is what the tools read and act on.
+type Machine struct {
+	Root    string // "" on the machine; a fake root in tests
+	Home    string // the operator's home, as the machine names it
+	UID     int
+	Run     Runner
+	Kill    func(pid int, sig syscall.Signal) error
+	Sleep   func(time.Duration)
+	Now     func() time.Time
+	Timeout time.Duration
+}
+
+// NewMachine is the machine the bundle runs on.
+func NewMachine() *Machine {
+	return &Machine{Home: operatorHome(), UID: os.Getuid(), Run: execRun, Kill: syscall.Kill,
+		Sleep: time.Sleep, Now: time.Now, Timeout: CallTimeout}
+}
+
+// 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
+}
+
+func (m *Machine) path(p string) string { return filepath.Join(m.Root, p) }
+
+// home is a path under the operator's home, on this machine's filesystem.
+func (m *Machine) home(rel ...string) string {
+	return filepath.Join(append([]string{m.Root, m.Home}, rel...)...)
+}
+
+// tilde shows a path under the home as ~/…, so an answer does not carry the account's name.
+func (m *Machine) tilde(p string) string {
+	if m.Home != "" && m.Home != "/" {
+		h := strings.TrimSuffix(m.Home, "/")
+		if p == h {
+			return "~"
+		}
+		if strings.HasPrefix(p, h+"/") {
+			return "~/" + strings.TrimPrefix(p, h+"/")
+		}
+	}
+	return p
+}
+
+// cmd runs a command within the machine's timeout (or a shorter one).
+func (m *Machine) cmd(timeout time.Duration, env []string, name string, args ...string) Output {
+	if timeout <= 0 || timeout > m.Timeout {
+		timeout = m.Timeout
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), timeout)
+	defer cancel()
+	return m.Run(ctx, env, name, args...)
+}
+
+// failed names how a command failed, or answers nil when it ran and exited 0.
+func failed(o Output, name string, args ...string) error {
+	switch {
+	case errors.Is(o.Err, ErrNotInstalled):
+		return fmt.Errorf("%s is not installed on this machine", name)
+	case errors.Is(o.Err, ErrTimedOut):
+		return fmt.Errorf("%s gave no answer in time and was ended", name)
+	case o.Err != nil:
+		return fmt.Errorf("%s did not run: %v", name, o.Err)
+	case o.Code != 0:
+		said := strings.TrimSpace(o.Stderr)
+		if said == "" {
+			said = strings.TrimSpace(o.Stdout)
+		}
+		if said == "" {
+			said = "and said nothing"
+		}
+		return fmt.Errorf("%s %s exited %d: %s", name, strings.Join(args, " "), o.Code, tail(said, 1000))
+	}
+	return nil
+}
+
+func tail(s string, n int) string {
+	if len(s) <= n {
+		return s
+	}
+	return "…" + s[len(s)-n:]
+}
+
+type capped struct {
+	b   bytes.Buffer
+	cut bool
+}
+
+func (c *capped) Write(p []byte) (int, error) {
+	if room := MostOutput - c.b.Len(); room < len(p) {
+		if room > 0 {
+			c.b.Write(p[:room])
+		}
+		c.cut = true
+		return len(p), nil
+	}
+	return c.b.Write(p)
+}
+
+func execRun(ctx context.Context, env []string, name string, args ...string) Output {
+	path, err := exec.LookPath(name)
+	if err != nil {
+		return Output{Code: 127, Err: ErrNotInstalled}
+	}
+	cmd := exec.CommandContext(ctx, path, args...)
+	cmd.Env = append(append(os.Environ(), "LC_ALL=C"), env...)
+	// 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
+	var out, errs capped
+	cmd.Stdout, cmd.Stderr = &out, &errs
+	err = cmd.Run()
+	o := Output{Stdout: out.b.String(), Stderr: errs.b.String(), Cut: out.cut || errs.cut}
+	var exit *exec.ExitError
+	switch {
+	case err == nil:
+	case ctx.Err() == context.DeadlineExceeded:
+		o.Code, o.Err = 124, ErrTimedOut
+	case errors.As(err, &exit):
+		o.Code = exit.ExitCode()
+	default:
+		o.Code, o.Err = 127, err
+	}
+	return o
+}
+
+// readBounded reads a file to at most MostRead bytes.
+func readBounded(path string) ([]byte, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return nil, err
+	}
+	defer f.Close()
+	return io.ReadAll(io.LimitReader(f, MostRead))
+}
+
+// Proc is one process of the account.
+type Proc struct {
+	PID     int    `json:"pid"`
+	Command string `json:"command"`
+	// StartedIn is the unit or scope it runs in: the login session's scope when the session's start
+	// (dex, the window manager) started it, a mesh-… unit when a tool restarted it.
+	StartedIn string `json:"started_in,omitempty"`
+	Since     string `json:"since,omitempty"`
+}
+
+// procs are this account's processes named comm, oldest first.
+func (m *Machine) procs(comm string) []Proc {
+	entries, err := os.ReadDir(m.path("/proc"))
+	if err != nil {
+		return nil
+	}
+	boot := m.bootTime()
+	var out []Proc
+	for _, e := range entries {
+		pid, err := strconv.Atoi(e.Name())
+		if err != nil {
+			continue
+		}
+		dir := m.path(filepath.Join("/proc", e.Name()))
+		if readTrimmed(filepath.Join(dir, "comm")) != comm || m.uidOf(dir) != m.UID {
+			continue
+		}
+		p := Proc{PID: pid, Command: strings.TrimSpace(strings.ReplaceAll(readTrimmed(filepath.Join(dir, "cmdline")), "\x00", " "))}
+		if p.Command == "" {
+			p.Command = comm
+		}
+		if cg := readTrimmed(filepath.Join(dir, "cgroup")); cg != "" {
+			line := strings.Split(cg, "\n")[0]
+			p.StartedIn = filepath.Base(line[strings.LastIndexByte(line, ':')+1:])
+		}
+		if t, ok := startOf(readTrimmed(filepath.Join(dir, "stat")), boot); ok {
+			p.Since = t.UTC().Format(time.RFC3339)
+		}
+		out = append(out, p)
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].PID < out[j].PID })
+	return out
+}
+
+// uidOf is the real uid on a process's status, -1 when unreadable.
+func (m *Machine) uidOf(dir string) int {
+	for _, l := range strings.Split(readTrimmed(filepath.Join(dir, "status")), "\n") {
+		if f := strings.Fields(l); len(f) > 1 && f[0] == "Uid:" {
+			if n, err := strconv.Atoi(f[1]); err == nil {
+				return n
+			}
+		}
+	}
+	return -1
+}
+
+func (m *Machine) bootTime() int64 {
+	for _, l := range strings.Split(readTrimmed(m.path("/proc/stat")), "\n") {
+		if f := strings.Fields(l); len(f) == 2 && f[0] == "btime" {
+			n, _ := strconv.ParseInt(f[1], 10, 64)
+			return n
+		}
+	}
+	return 0
+}
+
+// startOf reads a process's start from its stat line (field 22, in clock ticks of 1/100 s since boot).
+func startOf(stat string, boot int64) (time.Time, bool) {
+	i := strings.LastIndexByte(stat, ')')
+	if i < 0 || boot == 0 {
+		return time.Time{}, false
+	}
+	f := strings.Fields(stat[i+1:])
+	if len(f) < 20 {
+		return time.Time{}, false
+	}
+	ticks, err := strconv.ParseInt(f[19], 10, 64)
+	if err != nil {
+		return time.Time{}, false
+	}
+	return time.Unix(boot+ticks/100, 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
+}
+
+// Session is what a tool needs to start something on the operator's desktop.
+type Session struct {
+	Display    string `json:"display"`
+	XAuthority string `json:"xauthority,omitempty"`
+	Bus        string `json:"bus,omitempty"`
+	RuntimeDir string `json:"runtime_dir,omitempty"`
+	From       string `json:"found_in"`
+}
+
+// sessionHolders are the processes whose environment is the session's, best first.
+var sessionHolders = []string{"i3", "sway", "i3bar", "picom", "dunst", "xterm"}
+
+// session finds the account's graphical session, or ErrNoSession saying what it looked at.
+func (m *Machine) session() (Session, error) {
+	entries, _ := os.ReadDir(m.path("/proc"))
+	best, bestRank := -1, len(sessionHolders)+1
+	var env map[string]string
+	var from string
+	for _, e := range entries {
+		pid, err := strconv.Atoi(e.Name())
+		if err != nil {
+			continue
+		}
+		dir := m.path(filepath.Join("/proc", e.Name()))
+		if m.uidOf(dir) != m.UID {
+			continue
+		}
+		raw, err := os.ReadFile(filepath.Join(dir, "environ"))
+		if err != nil {
+			continue
+		}
+		vars := parseEnviron(raw)
+		if vars["DISPLAY"] == "" {
+			continue
+		}
+		comm := readTrimmed(filepath.Join(dir, "comm"))
+		rank := len(sessionHolders)
+		for i, h := range sessionHolders {
+			if h == comm {
+				rank = i
+			}
+		}
+		if rank < bestRank || (rank == bestRank && pid > best) {
+			best, bestRank, env, from = pid, rank, vars, fmt.Sprintf("process %s (pid %d)", comm, pid)
+		}
+	}
+	if env == nil {
+		return Session{}, fmt.Errorf("%w for uid %d on this machine: no process of the account carries DISPLAY. "+
+			"Is anyone logged in to the desktop?", ErrNoSession, m.UID)
+	}
+	s := Session{Display: env["DISPLAY"], XAuthority: env["XAUTHORITY"], Bus: env["DBUS_SESSION_BUS_ADDRESS"],
+		RuntimeDir: env["XDG_RUNTIME_DIR"], From: from}
+	if s.RuntimeDir == "" {
+		s.RuntimeDir = fmt.Sprintf("/run/user/%d", m.UID)
+	}
+	if s.Bus == "" && exists(m.path(filepath.Join(s.RuntimeDir, "bus"))) {
+		s.Bus = "unix:path=" + filepath.Join(s.RuntimeDir, "bus")
+	}
+	return s, nil
+}
+
+// bus is the account's session bus environment, which a logged-in account has with or without a
+// desktop: what a command needs to reach the user's service manager or a bus name.
+func (m *Machine) bus() []string {
+	runtime := fmt.Sprintf("/run/user/%d", m.UID)
+	return []string{"XDG_RUNTIME_DIR=" + runtime, "DBUS_SESSION_BUS_ADDRESS=unix:path=" + runtime + "/bus"}
+}
+
+// Env is the session's variables, for a command that draws or speaks to the desktop.
+func (s Session) Env() []string {
+	var env []string
+	for _, kv := range [][2]string{{"DISPLAY", s.Display}, {"XAUTHORITY", s.XAuthority},
+		{"DBUS_SESSION_BUS_ADDRESS", s.Bus}, {"XDG_RUNTIME_DIR", s.RuntimeDir}} {
+		if kv[1] != "" {
+			env = append(env, kv[0]+"="+kv[1])
+		}
+	}
+	return env
+}
+
+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
+}
+
+// detach starts a long-lived program under the account's service manager, as a transient unit that
+// carries the session's display. A unit left by an earlier start under the same name is stopped
+// first, so the fixed name means at most one.
+func (m *Machine) detach(s Session, unit string, argv ...string) error {
+	_ = m.cmd(5*time.Second, s.Env(), "systemctl", "--user", "stop", unit+".service")
+	call := []string{"--user", "--collect", "--quiet", "--unit=" + unit}
+	for _, kv := range [][2]string{{"DISPLAY", s.Display}, {"XAUTHORITY", s.XAuthority}} {
+		if kv[1] != "" {
+			call = append(call, "--setenv="+kv[0]+"="+kv[1])
+		}
+	}
+	call = append(append(call, "--"), argv...)
+	return failed(m.cmd(8*time.Second, s.Env(), "systemd-run", call...), "systemd-run", call...)
+}
+
+// stop ends every process of the account named in comms: SIGTERM, then SIGKILL for what is still
+// there after grace. It answers the pids that ended and those that had to be killed.
+func (m *Machine) stop(grace time.Duration, comms ...string) (ended, killed []int) {
+	var pids []int
+	for _, c := range comms {
+		for _, p := range m.procs(c) {
+			if m.Kill(p.PID, syscall.SIGTERM) == nil {
+				pids = append(pids, p.PID)
+			}
+		}
+	}
+	alive := func() []int {
+		var left []int
+		for _, pid := range pids {
+			if exists(m.path(filepath.Join("/proc", strconv.Itoa(pid)))) {
+				left = append(left, pid)
+			}
+		}
+		return left
+	}
+	step := 200 * time.Millisecond
+	for waited := time.Duration(0); waited < grace && len(alive()) > 0; waited += step {
+		m.Sleep(step)
+	}
+	left := alive()
+	for _, pid := range left {
+		if m.Kill(pid, syscall.SIGKILL) == nil {
+			killed = append(killed, pid)
+		}
+	}
+	gone := map[int]bool{}
+	for _, pid := range left {
+		gone[pid] = true
+	}
+	for _, pid := range pids {
+		if !gone[pid] {
+			ended = append(ended, pid)
+		}
+	}
+	return ended, killed
+}
+
+// waitFor waits up to d for a process of the account named comm, and answers what it found.
+func (m *Machine) waitFor(comm string, d time.Duration) []Proc {
+	step := 250 * time.Millisecond
+	for waited := time.Duration(0); ; waited += step {
+		if p := m.procs(comm); len(p) > 0 || waited >= d {
+			return p
+		}
+		m.Sleep(step)
+	}
+}
+
+// desktopEntry reads the [Desktop Entry] group of an XDG desktop file; nil when there is none.
+func desktopEntry(path string) map[string]string {
+	raw, err := readBounded(path)
+	if err != nil {
+		return nil
+	}
+	out := map[string]string{}
+	in := false
+	s := bufio.NewScanner(bytes.NewReader(raw))
+	for s.Scan() {
+		l := strings.TrimSpace(s.Text())
+		switch {
+		case strings.HasPrefix(l, "["):
+			in = l == "[Desktop Entry]"
+		case in && l != "" && !strings.HasPrefix(l, "#"):
+			if i := strings.IndexByte(l, '='); i > 0 {
+				out[strings.TrimSpace(l[:i])] = strings.TrimSpace(l[i+1:])
+			}
+		}
+	}
+	return out
+}
+
+// Autostart is what XDG autostart does with one entry: the account's file overrides the system's
+// of the same name, and Hidden=true (or the GNOME switch off) means it is not started.
+type Autostart struct {
+	Entry   string `json:"entry"`
+	From    string `json:"from"`
+	Exec    string `json:"exec,omitempty"`
+	Starts  bool   `json:"starts"`
+	Because string `json:"because,omitempty"`
+}
+
+// autostart resolves one XDG autostart entry by its file name, the account's directory first.
+func (m *Machine) autostart(name string) Autostart {
+	a := Autostart{Entry: name}
+	user := m.home(".config", "autostart", name)
+	system := m.path(filepath.Join("/etc/xdg/autostart", name))
+	var e map[string]string
+	switch {
+	case exists(user):
+		e, a.From = desktopEntry(user), m.tilde(filepath.Join(m.Home, ".config/autostart", name))
+	case exists(system):
+		e, a.From = desktopEntry(system), filepath.Join("/etc/xdg/autostart", name)
+	default:
+		a.Because = "no such entry in ~/.config/autostart or /etc/xdg/autostart"
+		return a
+	}
+	a.Exec = e["Exec"]
+	switch {
+	case strings.EqualFold(e["Hidden"], "true"):
+		a.Because = "Hidden=true"
+	case strings.EqualFold(e["X-GNOME-Autostart-enabled"], "false"):
+		a.Because = "X-GNOME-Autostart-enabled=false"
+	case a.Exec == "":
+		a.Because = "the entry has no Exec"
+	default:
+		a.Starts = true
+	}
+	return a
+}
+
+// i3Starts are the window manager's start-up lines (exec, exec_always) that run a program named
+// word, in the configuration and its config.d: a second start beside an autostart entry.
+func (m *Machine) i3Starts(word string) []string {
+	files := []string{m.home(".config", "i3", "config")}
+	more, _ := filepath.Glob(m.home(".config", "i3", "config.d", "*.conf"))
+	files = append(files, more...)
+	var out []string
+	for _, f := range files {
+		raw, err := readBounded(f)
+		if err != nil {
+			continue
+		}
+		for n, l := range strings.Split(string(raw), "\n") {
+			t := strings.TrimSpace(l)
+			if !strings.HasPrefix(t, "exec ") && !strings.HasPrefix(t, "exec_always ") {
+				continue
+			}
+			for _, w := range strings.Fields(t)[1:] {
+				if filepath.Base(strings.Trim(w, `"'`)) == word {
+					out = append(out, fmt.Sprintf("%s:%d: %s", m.tilde(strings.TrimPrefix(f, m.Root)), n+1, t))
+					break
+				}
+			}
+		}
+	}
+	return out
+}
+
+// installed asks the package manager for one package's version; "" when it is not installed.
+func (m *Machine) installed(pkg string) (string, error) {
+	o := m.cmd(0, nil, "pacman", "-Q", pkg)
+	if o.Err != nil {
+		return "", failed(o, "pacman", "-Q", pkg)
+	}
+	if o.Code != 0 {
+		return "", nil
+	}
+	f := strings.Fields(o.Stdout)
+	if len(f) < 2 {
+		return "", fmt.Errorf("pacman -Q %s answered %q", pkg, o.Stdout)
+	}
+	return f[1], nil
+}
+
+// Finding is one thing a check found wrong, and what to do about it.
+type Finding struct {
+	What string `json:"what"`
+	Do   string `json:"do,omitempty"`
+}

modules/blueman/cmd/blueman-tools/desktop_test.go

@@ -0,0 +1,202 @@
+package main
+
+// The fake machine the tests run against, and the tests of desktop.go. The same in the
+// nextcloud-client and blueman bundles.
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"sync"
+	"syscall"
+	"testing"
+	"time"
+)
+
+const testHome = "/home/operator"
+
+// fake is a machine with a fake root, a scripted Runner and signals that end fake processes.
+type fake struct {
+	*Machine
+	t      *testing.T
+	mu     sync.Mutex
+	calls  []string
+	answer func(name string, args []string) Output
+	// onStart is run when systemd-run starts something, to let a fake process appear.
+	onStart func(argv []string)
+	// stubborn pids ignore SIGTERM.
+	stubborn map[int]bool
+	signals  []string
+}
+
+func newFake(t *testing.T) *fake {
+	t.Helper()
+	root := t.TempDir()
+	f := &fake{t: t, stubborn: map[int]bool{}}
+	f.Machine = &Machine{Root: root, Home: testHome, UID: 1000, Timeout: CallTimeout,
+		Sleep: func(time.Duration) {}, Now: func() time.Time { return time.Unix(1_800_000_000, 0) }}
+	f.Run = func(_ context.Context, env []string, name string, args ...string) Output {
+		f.mu.Lock()
+		f.calls = append(f.calls, strings.TrimSpace(name+" "+strings.Join(args, " ")))
+		f.mu.Unlock()
+		if name == "systemd-run" && f.onStart != nil {
+			for i, a := range args {
+				if a == "--" {
+					f.onStart(args[i+1:])
+				}
+			}
+		}
+		if f.answer != nil {
+			return f.answer(name, args)
+		}
+		return Output{}
+	}
+	f.Kill = func(pid int, sig syscall.Signal) error {
+		f.signals = append(f.signals, strconv.Itoa(pid)+":"+sig.String())
+		if sig == syscall.SIGKILL || !f.stubborn[pid] {
+			return os.RemoveAll(filepath.Join(root, "proc", strconv.Itoa(pid)))
+		}
+		return nil
+	}
+	f.write("/proc/stat", "cpu 1 2 3\nbtime 1799990000\n")
+	return f
+}
+
+func (f *fake) write(path, content string) {
+	f.t.Helper()
+	p := filepath.Join(f.Root, path)
+	if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil {
+		f.t.Fatal(err)
+	}
+	if err := os.WriteFile(p, []byte(content), 0o644); err != nil {
+		f.t.Fatal(err)
+	}
+}
+
+// proc adds a process of uid with a command name, argv, cgroup and environment.
+func (f *fake) proc(pid, uid int, comm string, argv []string, cgroup string, env ...string) {
+	d := "/proc/" + strconv.Itoa(pid) + "/"
+	f.write(d+"comm", comm+"\n")
+	f.write(d+"status", "Name:\t"+comm+"\nUid:\t"+strconv.Itoa(uid)+"\t"+strconv.Itoa(uid)+"\t"+strconv.Itoa(uid)+"\t"+strconv.Itoa(uid)+"\n")
+	f.write(d+"cmdline", strings.Join(argv, "\x00")+"\x00")
+	f.write(d+"cgroup", "0::/user.slice/user-"+strconv.Itoa(uid)+".slice/"+cgroup+"\n")
+	f.write(d+"environ", strings.Join(env, "\x00")+"\x00")
+	// starttime (field 22) is 1000 ticks: 10 s after boot.
+	f.write(d+"stat", strconv.Itoa(pid)+" ("+comm+") S 1 1 1 0 -1 0 0 0 0 0 0 0 0 0 20 0 1 0 1000 0 0\n")
+}
+
+func (f *fake) desktopSession() {
+	f.proc(3700, 1000, "i3", []string{"i3"}, "session-c1.scope", "DISPLAY=:1", "XAUTHORITY="+testHome+"/.Xauthority")
+	f.write("/run/user/1000/bus", "")
+}
+
+func (f *fake) called(prefix string) bool {
+	for _, c := range f.calls {
+		if strings.HasPrefix(c, prefix) {
+			return true
+		}
+	}
+	return false
+}
+
+func TestProcessesAreTheAccountsOwnWithWhereAndWhenTheyStarted(t *testing.T) {
+	f := newFake(t)
+	f.proc(10, 1000, "worker", []string{"/usr/bin/worker", "--background"}, "session-c1.scope")
+	f.proc(11, 1001, "worker", []string{"/usr/bin/worker"}, "session-c2.scope")
+	f.proc(12, 1000, "other", []string{"other"}, "x.scope")
+	got := f.procs("worker")
+	if len(got) != 1 || got[0].PID != 10 || got[0].Command != "/usr/bin/worker --background" ||
+		got[0].StartedIn != "session-c1.scope" || got[0].Since != time.Unix(1799990010, 0).UTC().Format(time.RFC3339) {
+		t.Fatalf("%+v", got)
+	}
+}
+
+func TestTheSessionIsTheWindowManagersAndNoneIsSaidPlainly(t *testing.T) {
+	f := newFake(t)
+	if _, err := f.session(); err == nil || !strings.Contains(err.Error(), "no graphical session") {
+		t.Fatalf("%v", err)
+	}
+	f.proc(50, 1000, "xterm", []string{"xterm"}, "s.scope", "DISPLAY=:9")
+	f.desktopSession()
+	f.proc(60, 1001, "i3", []string{"i3"}, "s.scope", "DISPLAY=:5")
+	s, err := f.session()
+	if err != nil || s.Display != ":1" || s.XAuthority != testHome+"/.Xauthority" || s.Bus != "unix:path=/run/user/1000/bus" ||
+		!strings.Contains(s.From, "i3") {
+		t.Fatalf("%+v %v", s, err)
+	}
+}
+
+func TestStopAsksThenForcesAndDetachStartsUnderTheServiceManager(t *testing.T) {
+	f := newFake(t)
+	f.desktopSession()
+	f.proc(20, 1000, "app", []string{"app"}, "s.scope")
+	f.proc(21, 1000, "app", []string{"app"}, "s.scope")
+	f.stubborn[21] = true
+	ended, killed := f.stop(time.Second, "app")
+	if len(ended) != 1 || ended[0] != 20 || len(killed) != 1 || killed[0] != 21 {
+		t.Fatalf("ended %v killed %v (%v)", ended, killed, f.signals)
+	}
+	s, _ := f.session()
+	if err := f.detach(s, "mesh-app", "/usr/bin/app", "--background"); err != nil {
+		t.Fatal(err)
+	}
+	want := "systemd-run --user --collect --quiet --unit=mesh-app --setenv=DISPLAY=:1 --setenv=XAUTHORITY=" + testHome +
+		"/.Xauthority -- /usr/bin/app --background"
+	if !f.called("systemctl --user stop mesh-app.service") || !f.called(want) {
+		t.Fatalf("%q", f.calls)
+	}
+}
+
+func TestAnAutostartEntryOfTheAccountOverridesTheSystemsAndHiddenStartsNothing(t *testing.T) {
+	f := newFake(t)
+	if a := f.autostart("x.desktop"); a.Starts || a.Because == "" {
+		t.Fatalf("%+v", a)
+	}
+	f.write("/etc/xdg/autostart/x.desktop", "[Desktop Entry]\nExec=x-applet\n[Desktop Action y]\nExec=other\n")
+	if a := f.autostart("x.desktop"); !a.Starts || a.Exec != "x-applet" || a.From != "/etc/xdg/autostart/x.desktop" {
+		t.Fatalf("%+v", a)
+	}
+	f.write(testHome+"/.config/autostart/x.desktop", "[Desktop Entry]\nExec=x-applet\nHidden=true\n")
+	if a := f.autostart("x.desktop"); a.Starts || a.Because != "Hidden=true" || a.From != "~/.config/autostart/x.desktop" {
+		t.Fatalf("%+v", a)
+	}
+}
+
+func TestAWindowManagerStartIsFoundInTheConfigurationAndItsDropIns(t *testing.T) {
+	f := newFake(t)
+	f.write(testHome+"/.config/i3/config", "exec --no-startup-id dex --autostart --environment i3\n# exec app\nbindsym $mod+a exec app\n")
+	f.write(testHome+"/.config/i3/config.d/50-x.conf", "exec_always --no-startup-id /usr/bin/app --flag\n")
+	got := f.i3Starts("app")
+	if len(got) != 1 || got[0] != "~/.config/i3/config.d/50-x.conf:1: exec_always --no-startup-id /usr/bin/app --flag" {
+		t.Fatalf("%q", got)
+	}
+}
+
+func TestACommandThatFailsIsNamed(t *testing.T) {
+	if err := failed(Output{Code: 127, Err: ErrNotInstalled}, "dex"); err == nil || !strings.Contains(err.Error(), "dex is not installed") {
+		t.Fatal(err)
+	}
+	if err := failed(Output{Code: 1, Stderr: "nope"}, "pacman", "-Q", "x"); err == nil || !strings.Contains(err.Error(), "pacman -Q x exited 1: nope") {
+		t.Fatal(err)
+	}
+	if err := failed(Output{}, "true"); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestTheRealRunnerBoundsTimeAndOutput(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), 200*time.Millisecond)
+	defer cancel()
+	if o := execRun(ctx, nil, "sleep", "5"); o.Err != ErrTimedOut {
+		t.Fatalf("%+v", o)
+	}
+	if o := execRun(context.Background(), nil, "no-such-program-here"); o.Err != ErrNotInstalled {
+		t.Fatalf("%+v", o)
+	}
+	o := execRun(context.Background(), nil, "head", "-c", strconv.Itoa(MostOutput+10), "/dev/zero")
+	if !o.Cut || len(o.Stdout) != MostOutput {
+		t.Fatalf("cut %v, %d bytes", o.Cut, len(o.Stdout))
+	}
+}

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

@@ -0,0 +1,48 @@
+// The blueman module's Go tools bundle (novox/hq ADR 0188, ADR 0193, ADR 0208): the Bluetooth tray
+// applet in the operator's session, served by the node's runtime as the operator account. The module
+// holds no seat, so every tool is its own. The devices themselves are the bluetooth module's tools.
+package main
+
+import (
+	"fmt"
+	"os"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+func main() {
+	if err := stdio.Serve("", tools()); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+var machine = NewMachine()
+
+func tools() []stdio.Tool {
+	return []stdio.Tool{
+		{
+			Name: "blueman_status",
+			Description: "The Bluetooth applet: whether it and its tray icon run (pid, since, and the unit or " +
+				"session scope they run in), the installed version, what starts it at login, the plugins the " +
+				"running applet has loaded and those it has not, the plugin switches in the operator's settings, " +
+				"and whether the applet sees Bluetooth on. Never starts the applet. (r)",
+			Run: func(map[string]any) (any, error) { return machine.Status() },
+		},
+		{
+			Name: "blueman_restart",
+			Description: "End the applet and its tray icon (asked first, then forced after 5 s) and start the " +
+				"applet again in the operator's desktop session, under the account's service manager. Answers " +
+				"the pids ended and the new one. Needs someone logged in to the desktop. (a)",
+			Run: func(map[string]any) (any, error) { return machine.Restart() },
+		},
+		{
+			Name: "blueman_check",
+			Description: "Check what the module promises and relies on: the package is installed; the applet has " +
+				"exactly one start (the package's XDG autostart entry, which the session's dex runs; no " +
+				"window-manager exec); it runs once in a desktop session; and the Bluetooth daemon is running " +
+				"(the bluetooth module's). Answers ok and each finding with what to do. (r)",
+			Run: func(map[string]any) (any, error) { return machine.Check() },
+		},
+	}
+}

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

@@ -0,0 +1,109 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+// blueman's shape (novox/hq ADR 0208, ADR 0210): one official package, no seat, the X display on its
+// own machine, no start of its own (the package's autostart entry is the one start), nothing of the
+// bluetooth module's (bluez, its utilities, its daemon), and the Go bundle serving exactly the listed
+// blueman_ tools.
+
+type manifest struct {
+	Module        string           `json:"module"`
+	Version       string           `json:"version"`
+	Capabilities  []string         `json:"capabilities"`
+	Requires      []string         `json:"requires"`
+	Tools         []string         `json:"tools"`
+	Resources     []map[string]any `json:"resources"`
+	Claims        []any            `json:"claims"`
+	Seats         []any            `json:"seats"`
+	Shell         []any            `json:"shell"`
+	Contributions []any            `json:"contributions"`
+	Environment   any              `json:"environment"`
+	Build         struct {
+		Artifacts []map[string]any `json:"artifacts"`
+	} `json:"build"`
+}
+
+func readManifest(t *testing.T) (manifest, string) {
+	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, string(raw)
+}
+
+func TestItInstallsTheAppletAndNothingElse(t *testing.T) {
+	m, _ := readManifest(t)
+	if m.Module != "blueman" || !reflect.DeepEqual(m.Requires, []string{"x11-display"}) ||
+		!reflect.DeepEqual(m.Capabilities, []string{"package-manager"}) {
+		t.Fatalf("%+v", m)
+	}
+	if len(m.Resources) != 1 || m.Resources[0]["type"] != "package" || m.Resources[0]["package"] != packageFor {
+		t.Fatalf("resources: %v", m.Resources)
+	}
+	if m.Claims != nil || m.Seats != nil || m.Environment != nil {
+		t.Fatal("it holds no seat and sets no environment")
+	}
+}
+
+func TestItAddsNoSecondStartAndDeclaresNothingOfTheBluetoothModule(t *testing.T) {
+	m, raw := readManifest(t)
+	// The package ships its XDG autostart entry, which the session's dex runs: an xinitrc slot or a
+	// window-manager exec would start it twice.
+	if m.Shell != nil || m.Contributions != nil {
+		t.Fatalf("a second start: shell %v, contributions %v", m.Shell, m.Contributions)
+	}
+	for _, never := range []string{"autostart", "service", "bluez", "/etc/bluetooth"} {
+		if strings.Contains(raw, never) {
+			t.Errorf("module.json names %q: the start is the package's, the stack the bluetooth module's", never)
+		}
+	}
+}
+
+func TestTheToolsAgreeWithTheManifest(t *testing.T) {
+	m, raw := readManifest(t)
+	served := map[string]bool{}
+	for _, tool := range tools() {
+		served[tool.Name] = true
+		if !strings.HasPrefix(tool.Name, "blueman_") || strings.TrimSpace(tool.Description) == "" {
+			t.Errorf("%s: prefixed blueman_ and described", tool.Name)
+		}
+	}
+	for _, name := range m.Tools {
+		if !served[name] {
+			t.Errorf("module.json lists %s, which the bundle does not serve", name)
+		}
+		delete(served, name)
+	}
+	for name := range served {
+		t.Errorf("the bundle serves %s, which module.json does not list", name)
+	}
+	if len(m.Build.Artifacts) != 1 {
+		t.Fatalf("%v", m.Build.Artifacts)
+	}
+	b := m.Build.Artifacts[0]
+	if b["kind"] != "bundle" || b["language"] != "go" || b["system"] != "arch" ||
+		b["from"] != "cmd/blueman-tools" || b["binary"] != "blueman-tools" {
+		t.Errorf("the Go tools bundle: %v", b)
+	}
+	s := strings.ToLower(raw)
+	for _, never := range []string{"/home/", "jochen", "g14", "shanks", "novox.be", "http", "password", "token"} {
+		if strings.Contains(s, never) {
+			t.Errorf("module.json names %q", never)
+		}
+	}
+}

modules/blueman/go.mod

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

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

@@ -0,0 +1,37 @@
+{
+  "module": "blueman",
+  "version": "1",
+  "capabilities": [
+    "package-manager"
+  ],
+  "requires": [
+    "x11-display"
+  ],
+  "tools": [
+    "blueman_status",
+    "blueman_restart",
+    "blueman_check"
+  ],
+  "resources": [
+    {
+      "id": "package",
+      "type": "package",
+      "package": "blueman"
+    }
+  ],
+  "build": {
+    "artifacts": [
+      {
+        "name": "tools",
+        "kind": "bundle",
+        "language": "go",
+        "system": "arch",
+        "from": "cmd/blueman-tools",
+        "binary": "blueman-tools",
+        "loads": [
+          "blueman-tools"
+        ]
+      }
+    ]
+  }
+}

modules/bluetooth/README.md

@@ -48,6 +48,6 @@ 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.
+- `blueman` and its applet: the `blueman` module's, which relies on this one for the stack and
+  declares none of its packages. The applet starts from the package's XDG autostart entry.
 - `bluez-obex` and the AUR terminal client `bluetuith-bin` (with its `-debug`) on the laptop.

modules/claude-code/README.md

@@ -22,11 +22,17 @@ whenever the node's tool runtime collects the module's tools:
 | file | holds |
 |---|---|
 | `managed-mcp.json` | the tool servers every session loads: the mesh's console as `mesh`, and the servers set in this module's `mcp_servers` setting. **Exclusive**: a server not listed here does not load — not one added with `claude mcp add`, not a project's `.mcp.json`, not a plugin's |
-| `managed-settings.json` | the keys set in this module's `managed_settings` setting, under the mesh's own: the repositories' attribution convention, the claude.ai connectors kept beside the managed servers, and the key-helper while the node holds an API-key licence |
-| `CLAUDE.md` | how a session on this mesh works, this node's name and role, the conventions |
+| `managed-settings.json` | the keys set in this module's `managed_settings` setting, then the settings registered through this module (the mesh's, then this node's), under the mesh's own keys: the repositories' attribution convention, the claude.ai connectors kept beside the managed servers, the key-helper while the node holds an API-key licence, and the two that name the `nox-mesh` marketplace and enable its plugin |
+| `CLAUDE.md` | how a session on this mesh works, this node's name and role, the conventions — then the instruction sections registered for every node and for this one |
+| `marketplace/` | the `nox-mesh` plugin (hq ADR 0216): the skills, subagents, commands, hooks and output styles registered for every node and for this one, offered in a session as `nox-mesh:<name>`. Replaced whole, staged beside and swapped in |
 
-Under the operator's home, only `~/.claude/.credentials.json`, and only when the licence manager hands
-this node a subscription token. Nothing else under the home is read or written.
+Under the operator's home: `~/.claude/.credentials.json`, only when the licence manager hands this node a
+subscription token; and what is registered at the **home** scope for this node — a skill, subagent,
+command, output style, or instructions as a rule file — each path recorded in the module's state
+(`home-placed.json`). It writes, changes and removes only those — never a path the person made, even one with the
+same content, and never through a directory that is a symbolic link. A placed file changed by hand is left
+alone, and one the person deleted stays deleted until the item is unregistered (hq ADR 0182). The status tool reads the rest of the home's
+items to report them; nothing else is read or written.
 
 ## Over NATS
 
@@ -41,6 +47,7 @@ must see, a node that joins later included — kept, so it carries no secret eit
 | 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 |
+| the agent's configuration (hq ADR 0216) | a key in the module's `config` state per registration — `mesh.<kind>.<name>` for every node, `node.<node>.<kind>.<name>` for one, `home.<node>.<kind>.<name>` for one account's own directory — the item and its files in one value, at most 256 KiB. Every node watches it and renders what applies to it, a node item over a mesh item of the same kind and name |
 
 ## Tools
 
@@ -49,6 +56,24 @@ 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`.
 
+The agent's configuration (hq ADR 0216), each registered at a **scope** — `mesh` (the default), `node`
+(`nodes`: a list, or `"all"` for every node running claude-code; absent is this node) or `home` (the
+operator account's own `~/.claude` on those nodes):
+
+- for each kind — `skill`, `agent`, `command`, `hook`, `output_style`, `instructions` —
+  `claude_code_<kind>_list`, `_register`, `_unregister`. A skill is its files (`files`, or `content` for a
+  lone SKILL.md); a hook is an `event`, a `matcher`, a `command` and its scripts as `files`, with
+  `${HOOK_DIR}` in the command naming their directory. Hooks and settings take no home scope;
+- `claude_code_settings_get`, `_set` (merged into the scope, or `replace`), `_clear`;
+  `claude_code_permission_add` and `_remove` for one allow, ask or deny rule. The agent refuses to loosen
+  its own settings: these are the operator's to call;
+- `claude_code_config_list`, `_show` (one registration in full), `_status` (what applies here, the plugin
+  as written, and the home's own items — which the mesh placed, which share a name with a mesh item, which
+  call a tool server not loaded here) and `_import` (an item of this node's home, registered at a scope;
+  the original stays).
+
+A new session takes a change; a running one at `/reload-plugins`.
+
 ## Settings
 
 Per node or for the whole mesh, through `mesh-controller.settings module=claude-code`:

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

@@ -69,19 +69,25 @@ func TestTheRendererWritesWhatTheTypeScriptOneWrote(t *testing.T) {
 		for _, file := range []string{"managed-mcp.json", "managed-settings.json"} {
 			var a, b any
 			_ = json.Unmarshal([]byte(got[file]), &a)
+			// The plugin's two keys are new since the TypeScript (ADR 0216); everything else means the same.
+			if m, ok := a.(map[string]any); ok && file == "managed-settings.json" {
+				for k := range MarketplaceKeys() {
+					delete(m, k)
+				}
+			}
 			_ = 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)
+	same("with an API key", Render(f.Facts, f.Settings, &Binding{Licence: "api", Kind: "api-key"}, "/state/api-key-helper", f.Registered, Config{}), f.WithKey)
+	same("plain", Render(f.Facts, Settings{}, nil, "/h", Servers{}, Config{}), 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)
+		Settings{MCPServers: map[string]map[string]any{"mesh": {"type": "http", "url": "http://evil"}, "bad name": {}}}, nil, "/h", nil, Config{})
 	var mcp struct {
 		MCPServers map[string]map[string]any `json:"mcpServers"`
 	}
@@ -89,7 +95,7 @@ func TestASettingCannotReplaceTheMeshsOwnEntryAndABadNameIsLeftOut(t *testing.T)
 	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)) {
+	if !reflect.DeepEqual(Render(Facts{Console: "x"}, Settings{}, nil, "/h", nil, Config{}), Render(Facts{Console: "x"}, Settings{}, nil, "/h", nil, Config{})) {
 		t.Fatal("rendering is not deterministic")
 	}
 }
@@ -104,7 +110,7 @@ func TestTheOperatorsManagedSettingsAreLaidUnderTheMeshsOwnKeys(t *testing.T) {
 	}}
 	read := func(binding *Binding) map[string]any {
 		var m map[string]any
-		out := Render(Facts{Console: "x"}, settings, binding, "/h", nil)
+		out := Render(Facts{Console: "x"}, settings, binding, "/h", nil, Config{})
 		if err := json.Unmarshal([]byte(out["managed-settings.json"]), &m); err != nil {
 			t.Fatal(err)
 		}

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

@@ -0,0 +1,937 @@
+package main
+
+// The agent's configuration, registered through this module at three scopes (novox/hq ADR 0216, to-be 36 §8).
+//
+// Every registration is one key in the module's `config` state (ADR 0201):
+//
+//	mesh.<kind>.<name>          every node running the agent
+//	node.<node>.<kind>.<name>   one node — a list of nodes is one key each
+//	home.<node>.<kind>.<name>   the operator account's own agent directory on one node
+//
+// Every instance watches the state and takes what applies to it. What it takes lands in one place per kind,
+// the one place the vendor honours for it:
+//
+//	skill, agent, command, hook, output-style   the plugin `nox-mesh`, in a marketplace in the managed directory
+//	                                            (at the home scope: the home's own directories)
+//	instructions                                sections of the managed instruction file (home: a rule file)
+//	settings                                    the managed settings file, mesh then node, under the mesh's keys
+//
+// Tool servers keep their own state and file (`servers`, the managed tool-server file): the exclusive file
+// would block a plugin's.
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+	"sync"
+	"time"
+)
+
+// Plugin is the plugin's name, and its marketplace's: what its items are called in a session, `nox-mesh:<name>`.
+const Plugin = "nox-mesh"
+
+// MarketplaceDir is where the marketplace is written, inside the managed directory.
+const MarketplaceDir = "marketplace"
+
+// MaxItemBytes is the most one registration may carry, its files included: well under the bus's message limit.
+const MaxItemBytes = 256 << 10
+
+// The kinds a registration may be.
+const (
+	KindSkill        = "skill"
+	KindAgent        = "agent"
+	KindCommand      = "command"
+	KindHook         = "hook"
+	KindOutputStyle  = "output-style"
+	KindInstructions = "instructions"
+	KindSettings     = "settings"
+)
+
+// Kinds is every kind, in the order a list shows them.
+var Kinds = []string{KindSkill, KindAgent, KindCommand, KindHook, KindOutputStyle, KindInstructions, KindSettings}
+
+// The scopes.
+const (
+	ScopeMesh = "mesh"
+	ScopeNode = "node"
+	ScopeHome = "home"
+)
+
+// SettingsName is the one name a settings registration has: a scope holds one set of settings.
+const SettingsName = "settings"
+
+var itemName = regexp.MustCompile(`^[a-z0-9][a-z0-9-]{0,63}$`)
+
+// nodeName is what a node may be called in a key.
+var nodeName = regexp.MustCompile(`^[a-z0-9][a-z0-9-]{0,62}$`)
+
+// meshOwnedKeys are the settings a registration may not set: the mesh's own, and those that would deny
+// the mesh's console or its marketplace by another way.
+var meshOwnedKeys = []string{"attribution", "allowAllClaudeAiMcps", "apiKeyHelper", "extraKnownMarketplaces", "enabledPlugins",
+	"allowedMcpServers", "deniedMcpServers", "allowManagedMcpServersOnly", "strictKnownMarketplaces", "blockedMarketplaces"}
+
+// hookEvents are the events a hook may be registered for.
+var hookEvents = map[string]bool{"PreToolUse": true, "PostToolUse": true, "UserPromptSubmit": true, "Notification": true,
+	"Stop": true, "SubagentStop": true, "SessionStart": true, "SessionEnd": true, "PreCompact": true}
+
+// Item is one registration, as the state keeps it.
+type Item struct {
+	Kind  string `json:"kind"`
+	Name  string `json:"name"`
+	Scope string `json:"scope"`
+	// Files are the item's files by path relative to the item: a skill's SKILL.md and whatever sits beside
+	// it; for the one-file kinds, `<name>.md`; a hook's scripts.
+	Files map[string]string `json:"files,omitempty"`
+	// A hook's event, matcher and command. In the command, ${HOOK_DIR} is the directory its files are in.
+	Event   string `json:"event,omitempty"`
+	Matcher string `json:"matcher,omitempty"`
+	Command string `json:"command,omitempty"`
+	// Settings, for the settings kind: keys of the vendor's settings file.
+	Settings map[string]any `json:"settings,omitempty"`
+	// Where it was registered from, and when.
+	By string `json:"by,omitempty"`
+	At string `json:"at,omitempty"`
+}
+
+// Key is where an item lives in the state, for one node (ignored at the mesh scope).
+func (it Item) Key(node string) string {
+	if it.Scope == ScopeMesh {
+		return ScopeMesh + "." + it.Kind + "." + it.Name
+	}
+	return it.Scope + "." + node + "." + it.Kind + "." + it.Name
+}
+
+// ParseKey reads a key back: its scope, the node it is for ("" at the mesh scope), the kind and the name.
+func ParseKey(key string) (scope, node, kind, name string, ok bool) {
+	parts := strings.Split(key, ".")
+	switch {
+	case len(parts) == 3 && parts[0] == ScopeMesh:
+		return ScopeMesh, "", parts[1], parts[2], true
+	case len(parts) == 4 && (parts[0] == ScopeNode || parts[0] == ScopeHome):
+		return parts[0], parts[1], parts[2], parts[3], true
+	}
+	return "", "", "", "", false
+}
+
+func knownKind(k string) bool {
+	for _, x := range Kinds {
+		if x == k {
+			return true
+		}
+	}
+	return false
+}
+
+// Problem says why an item cannot be registered, or "".
+func (it Item) Problem() string {
+	if !knownKind(it.Kind) {
+		return fmt.Sprintf("%q is not a kind: %s", it.Kind, strings.Join(Kinds, ", "))
+	}
+	if it.Scope != ScopeMesh && it.Scope != ScopeNode && it.Scope != ScopeHome {
+		return fmt.Sprintf("%q is not a scope: mesh, node or home", it.Scope)
+	}
+	if it.Kind == KindSettings {
+		if it.Scope == ScopeHome {
+			return "settings take the mesh and node scopes only: the home's settings file is the person's"
+		}
+		if it.Name != SettingsName {
+			return "a scope holds one set of settings, named " + SettingsName
+		}
+		if len(it.Settings) == 0 {
+			return "no settings given"
+		}
+		for _, key := range meshOwnedKeys {
+			if _, ok := it.Settings[key]; ok {
+				return fmt.Sprintf("%q is one of the mesh's own keys, or would turn off the mesh's console or plugin; a registration cannot set it", key)
+			}
+		}
+	} else if !itemName.MatchString(it.Name) {
+		return fmt.Sprintf("%q is not a name: lower-case letters, digits and -, at most 64", it.Name)
+	}
+	if it.Kind == KindHook {
+		if it.Scope == ScopeHome {
+			return "a hook takes the mesh and node scopes only: at home it would live in the person's settings file"
+		}
+		if !hookEvents[it.Event] {
+			return fmt.Sprintf("%q is not a hook event the agent knows", it.Event)
+		}
+		if strings.TrimSpace(it.Command) == "" {
+			return "a hook needs a command"
+		}
+	}
+	for rel := range it.Files {
+		if problem := pathProblem(rel); problem != "" {
+			return problem
+		}
+		for other := range it.Files {
+			if strings.HasPrefix(other, rel+"/") {
+				return fmt.Sprintf("%q is a file and also the directory of %q", rel, other)
+			}
+		}
+	}
+	switch it.Kind {
+	case KindSkill:
+		if _, ok := it.Files["SKILL.md"]; !ok {
+			return "a skill needs a SKILL.md"
+		}
+	case KindAgent, KindCommand, KindOutputStyle, KindInstructions:
+		if len(it.Files) != 1 || strings.TrimSpace(it.Files[it.Name+".md"]) == "" {
+			return "this kind is one file, " + it.Name + ".md, with content"
+		}
+	}
+	if n := it.size(); n > MaxItemBytes {
+		return fmt.Sprintf("%d bytes: more than the %d one registration may carry", n, MaxItemBytes)
+	}
+	return ""
+}
+
+// pathProblem says why a file's path is not one inside the item, or "": relative, slash-separated, every
+// segment a real name — never empty, `.` or `..`.
+func pathProblem(rel string) string {
+	if rel == "" || path.IsAbs(rel) || strings.ContainsAny(rel, "\\\x00") {
+		return fmt.Sprintf("%q is not a path inside the item", rel)
+	}
+	for _, seg := range strings.Split(rel, "/") {
+		if seg == "" || seg == "." || seg == ".." {
+			return fmt.Sprintf("%q is not a path inside the item", rel)
+		}
+	}
+	return ""
+}
+
+func (it Item) size() int {
+	raw, _ := json.Marshal(it)
+	return len(raw)
+}
+
+// ---- the view -------------------------------------------------------------------------------------
+
+// ConfigView is what this node takes from the `config` state: every mesh item, and the node and home items
+// for this node — kept in memory from the watch and written through to the module's own file, so the
+// managed directory renders without the bus.
+type ConfigView struct {
+	p     Paths
+	mu    sync.Mutex
+	items map[string]Item
+}
+
+// NewConfigView is the view as last written through, or empty.
+func NewConfigView(p Paths) *ConfigView {
+	v := &ConfigView{p: p, items: map[string]Item{}}
+	_ = readJSON(p.config(), &v.items)
+	return v
+}
+
+// Applies says whether a key is this node's to take.
+func (v *ConfigView) Applies(key string) bool {
+	scope, node, _, _, ok := ParseKey(key)
+	return ok && (scope == ScopeMesh || node == v.p.Node)
+}
+
+// Take takes one change, and answers whether what applies to this node changed.
+func (v *ConfigView) Take(key, op string, item *Item) bool {
+	if !v.Applies(key) {
+		return false
+	}
+	_, node, _, _, _ := ParseKey(key)
+	v.mu.Lock()
+	defer v.mu.Unlock()
+	// Only an item that is what its key says: a key decides which nodes take an item, the item where it
+	// lands, and the two must agree — a mesh key holding a home item would land in every home.
+	if op == "put" && item != nil && item.Problem() == "" && item.Key(node) == key {
+		v.items[key] = *item
+	} else {
+		delete(v.items, key)
+	}
+	return v.writeThroughLocked()
+}
+
+// Prune drops what the view holds and the state no longer does: a registration removed while this node
+// was away is never handed over by the watch, which hands over what is there, not what went.
+func (v *ConfigView) Prune(present []string) bool {
+	keep := map[string]bool{}
+	for _, k := range present {
+		keep[k] = true
+	}
+	v.mu.Lock()
+	defer v.mu.Unlock()
+	for k := range v.items {
+		if !keep[k] {
+			delete(v.items, k)
+		}
+	}
+	return v.writeThroughLocked()
+}
+
+// Items is what applies here, by key.
+func (v *ConfigView) Items() map[string]Item {
+	v.mu.Lock()
+	defer v.mu.Unlock()
+	out := make(map[string]Item, len(v.items))
+	for k, it := range v.items {
+		out[k] = it
+	}
+	return out
+}
+
+// writeThroughLocked writes the view to its file, with v.mu held: the snapshot and the write are one step, so
+// an older snapshot never lands after a newer one.
+func (v *ConfigView) writeThroughLocked() bool {
+	now, _ := indented(v.items)
+	before, _ := os.ReadFile(v.p.config())
+	if string(before) == string(now) {
+		return false
+	}
+	_ = os.WriteFile(v.p.config(), now, 0o600)
+	return true
+}
+
+// Config is what applies to this node, sorted for rendering.
+type Config struct {
+	Mesh, Node, Home []Item
+}
+
+// ConfigOf sorts the items that apply here by scope, each scope by kind and name.
+func ConfigOf(items map[string]Item) Config {
+	var c Config
+	for _, it := range items {
+		switch it.Scope {
+		case ScopeMesh:
+			c.Mesh = append(c.Mesh, it)
+		case ScopeNode:
+			c.Node = append(c.Node, it)
+		case ScopeHome:
+			c.Home = append(c.Home, it)
+		}
+	}
+	for _, list := range [][]Item{c.Mesh, c.Node, c.Home} {
+		sort.Slice(list, func(i, j int) bool {
+			if list[i].Kind != list[j].Kind {
+				return list[i].Kind < list[j].Kind
+			}
+			return list[i].Name < list[j].Name
+		})
+	}
+	return c
+}
+
+// ---- rendering --------------------------------------------------------------------------------------
+
+// PluginFile is one file of the marketplace: its content and whether it is run.
+type PluginFile struct {
+	Content    string
+	Executable bool
+}
+
+// Marketplace is the marketplace directory's whole content, by path inside it. A node item of a name laid
+// over a mesh item of the same kind and name: the node's wins.
+func Marketplace(c Config) map[string]PluginFile {
+	root := "plugins/" + Plugin + "/"
+	out := map[string]PluginFile{
+		".claude-plugin/marketplace.json": {Content: jsonFile(map[string]any{
+			"name":  Plugin,
+			"owner": map[string]any{"name": "the mesh"},
+			"plugins": []any{map[string]any{"name": Plugin, "source": "./plugins/" + Plugin,
+				"description": "What the mesh registered for the agent: written by the claude-code module, never by hand."}},
+		})},
+		root + ".claude-plugin/plugin.json": {Content: jsonFile(map[string]any{
+			"name": Plugin, "version": "1.0.0",
+			"description": "What the mesh registered for the agent: written by the claude-code module, never by hand.",
+			"author":      map[string]any{"name": "the mesh"},
+		})},
+	}
+	chosen := map[string]Item{}
+	for _, layer := range [][]Item{c.Mesh, c.Node} {
+		for _, it := range layer {
+			chosen[it.Kind+"/"+it.Name] = it
+		}
+	}
+	keys := make([]string, 0, len(chosen))
+	for k := range chosen {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	hooks := map[string][]any{}
+	for _, k := range keys {
+		it := chosen[k]
+		switch it.Kind {
+		case KindSkill:
+			for rel, content := range it.Files {
+				out[root+"skills/"+it.Name+"/"+rel] = PluginFile{Content: content, Executable: isScript(rel, content)}
+			}
+		case KindAgent:
+			out[root+"agents/"+it.Name+".md"] = PluginFile{Content: it.Files[it.Name+".md"]}
+		case KindCommand:
+			out[root+"commands/"+it.Name+".md"] = PluginFile{Content: it.Files[it.Name+".md"]}
+		case KindOutputStyle:
+			out[root+"output-styles/"+it.Name+".md"] = PluginFile{Content: it.Files[it.Name+".md"]}
+		case KindHook:
+			for rel, content := range it.Files {
+				out[root+"hooks/"+it.Name+"/"+rel] = PluginFile{Content: content, Executable: true}
+			}
+			command := strings.ReplaceAll(it.Command, "${HOOK_DIR}", `"${CLAUDE_PLUGIN_ROOT}/hooks/`+it.Name+`"`)
+			entry := map[string]any{"hooks": []any{map[string]any{"type": "command", "command": command}}}
+			if it.Matcher != "" {
+				entry["matcher"] = it.Matcher
+			}
+			hooks[it.Event] = append(hooks[it.Event], entry)
+		}
+	}
+	if len(hooks) > 0 {
+		out[root+"hooks/hooks.json"] = PluginFile{Content: jsonFile(map[string]any{"hooks": hooks})}
+	}
+	return out
+}
+
+func isScript(rel, content string) bool {
+	return strings.HasPrefix(content, "#!") || strings.HasSuffix(rel, ".sh")
+}
+
+// MarketplaceKeys are the two managed settings keys that name the marketplace and enable the plugin.
+func MarketplaceKeys() map[string]any {
+	return map[string]any{
+		"extraKnownMarketplaces": map[string]any{Plugin: map[string]any{
+			"source": map[string]any{"source": "directory", "path": filepath.Join(ManagedDir, MarketplaceDir)}}},
+		"enabledPlugins": map[string]any{Plugin + "@" + Plugin: true},
+	}
+}
+
+// RegisteredSettings is the settings registered for the mesh, with those registered for this node laid over.
+func RegisteredSettings(c Config) map[string]any {
+	out := map[string]any{}
+	for _, layer := range [][]Item{c.Mesh, c.Node} {
+		for _, it := range layer {
+			if it.Kind == KindSettings {
+				out = mergeSettings(out, it.Settings)
+			}
+		}
+	}
+	return out
+}
+
+// mergeSettings lays b over a: objects are merged key by key, lists are joined without repeats (a
+// permission rule or an auto-mode rule added for a node adds to the mesh's), and anything else is b's.
+func mergeSettings(a, b map[string]any) map[string]any {
+	out := map[string]any{}
+	for k, v := range a {
+		out[k] = v
+	}
+	for k, v := range b {
+		switch nb := v.(type) {
+		case map[string]any:
+			if na, ok := out[k].(map[string]any); ok {
+				out[k] = mergeSettings(na, nb)
+				continue
+			}
+		case []any:
+			if la, ok := out[k].([]any); ok {
+				joined := append([]any{}, la...)
+				seen := map[string]bool{}
+				for _, x := range la {
+					raw, _ := json.Marshal(x)
+					seen[string(raw)] = true
+				}
+				for _, x := range nb {
+					raw, _ := json.Marshal(x)
+					if !seen[string(raw)] {
+						seen[string(raw)] = true
+						joined = append(joined, x)
+					}
+				}
+				out[k] = joined
+				continue
+			}
+		}
+		out[k] = v
+	}
+	return out
+}
+
+// InstructionSections is what the managed instruction file adds after the mesh's own text: the sections
+// registered for the mesh, then those for this node.
+func InstructionSections(c Config) string {
+	var b strings.Builder
+	for _, part := range []struct {
+		title string
+		items []Item
+	}{{"Instructions for every node", c.Mesh}, {"Instructions for this node", c.Node}} {
+		var sections []Item
+		for _, it := range part.items {
+			if it.Kind == KindInstructions {
+				sections = append(sections, it)
+			}
+		}
+		if len(sections) == 0 {
+			continue
+		}
+		fmt.Fprintf(&b, "\n## %s\n\nRegistered through the `claude-code` module's instruction tools; change them there.\n", part.title)
+		for _, it := range sections {
+			fmt.Fprintf(&b, "\n### %s\n\n%s\n", it.Name, strings.TrimSpace(it.Files[it.Name+".md"]))
+		}
+	}
+	return b.String()
+}
+
+// HomeFiles is what the home scope places in the operator account's agent directory, by path relative to
+// that directory.
+func HomeFiles(c Config) map[string]string {
+	out := map[string]string{}
+	for _, it := range c.Home {
+		switch it.Kind {
+		case KindSkill:
+			for rel, content := range it.Files {
+				out["skills/"+it.Name+"/"+rel] = content
+			}
+		case KindAgent:
+			out["agents/"+it.Name+".md"] = it.Files[it.Name+".md"]
+		case KindCommand:
+			out["commands/"+it.Name+".md"] = it.Files[it.Name+".md"]
+		case KindOutputStyle:
+			out["output-styles/"+it.Name+".md"] = it.Files[it.Name+".md"]
+		case KindInstructions:
+			out["rules/"+it.Name+".md"] = it.Files[it.Name+".md"]
+		}
+	}
+	return out
+}
+
+// ---- the home ---------------------------------------------------------------------------------------
+
+// Placed is what this module placed in the home, by path relative to the agent directory, with the digest
+// of what it wrote (ADR 0182: the mesh owns what it places, and only that).
+type Placed map[string]string
+
+func digest(s string) string {
+	sum := sha256.Sum256([]byte(s))
+	return hex.EncodeToString(sum[:])
+}
+
+// deletedByHand marks, in the record, a path the mesh placed and the person then deleted: their choice,
+// kept until the item is unregistered.
+const deletedByHand = "deleted-by-hand"
+
+// PlaceHome brings the home in line with what the home scope wants (ADR 0182): it writes what is wanted and
+// absent, or its own; it never writes a path the person made, nor through a directory that is a symbolic
+// link; it removes what it placed and is no longer wanted, unless the person changed it since; and a file it
+// placed that the person deleted stays deleted until the item is unregistered. Answers what it did and what
+// it left alone, and why.
+func PlaceHome(p Paths, want map[string]string) (done []string, left []string) {
+	dir := filepath.Join(p.Home, ".claude")
+	var placed Placed
+	if !readJSON(p.placed(), &placed) {
+		placed = Placed{}
+	}
+	paths := make([]string, 0, len(want))
+	for rel := range want {
+		paths = append(paths, rel)
+	}
+	sort.Strings(paths)
+	for _, rel := range paths {
+		full := filepath.Join(dir, filepath.FromSlash(rel))
+		content := want[rel]
+		if why := linkedParent(dir, rel); why != "" {
+			left = append(left, rel+": "+why+", left alone")
+			continue
+		}
+		current, err := os.ReadFile(full)
+		exists := err == nil
+		ours, wasPlaced := placed[rel]
+		switch {
+		case !exists && wasPlaced && ours == deletedByHand:
+			continue
+		case !exists && wasPlaced:
+			placed[rel] = deletedByHand
+			left = append(left, rel+": deleted by hand, left deleted until the item is unregistered")
+			continue
+		case exists && !wasPlaced:
+			left = append(left, rel+": the person's own, left alone")
+			continue
+		case exists && ours == deletedByHand:
+			left = append(left, rel+": made again by hand after the mesh's was deleted, left alone")
+			continue
+		case exists && string(current) == content:
+			continue
+		case exists && digest(string(current)) != ours:
+			left = append(left, rel+": changed by hand since it was placed, left alone")
+			continue
+		}
+		if err := os.MkdirAll(filepath.Dir(full), 0o755); err != nil {
+			left = append(left, rel+": "+err.Error())
+			continue
+		}
+		mode := os.FileMode(0o644)
+		if isScript(rel, content) {
+			mode = 0o755
+		}
+		if err := os.WriteFile(full, []byte(content), mode); err != nil {
+			left = append(left, rel+": "+err.Error())
+			continue
+		}
+		placed[rel] = digest(content)
+		done = append(done, rel+": placed")
+	}
+	for rel, ours := range placed {
+		if _, wanted := want[rel]; wanted {
+			continue
+		}
+		full := filepath.Join(dir, filepath.FromSlash(rel))
+		if ours == deletedByHand {
+			delete(placed, rel)
+			continue
+		}
+		if why := linkedParent(dir, rel); why != "" {
+			left = append(left, rel+": no longer registered, but "+why+", left alone")
+			continue
+		}
+		current, err := os.ReadFile(full)
+		if err == nil && digest(string(current)) != ours {
+			left = append(left, rel+": no longer registered, but changed by hand, left alone")
+			delete(placed, rel)
+			continue
+		}
+		if err := os.Remove(full); err != nil && !os.IsNotExist(err) {
+			left = append(left, rel+": no longer registered, and could not be removed: "+err.Error())
+			continue
+		}
+		// Up to the kind's own directory, never it: `skills/<name>` goes when empty, `skills` stays.
+		removeEmptyParents(filepath.Join(dir, strings.SplitN(rel, "/", 2)[0]), filepath.Dir(full))
+		delete(placed, rel)
+		done = append(done, rel+": removed")
+	}
+	raw, _ := indented(placed)
+	if err := os.WriteFile(p.placed(), raw, 0o600); err != nil {
+		left = append(left, "the record of what was placed could not be saved: "+err.Error())
+	}
+	return done, left
+}
+
+// linkedParent says, when a directory between the agent directory and a file is a symbolic link, which one:
+// writing through it would write wherever it points.
+func linkedParent(dir, rel string) string {
+	parts := strings.Split(rel, "/")
+	at := dir
+	for _, seg := range parts[:len(parts)-1] {
+		at = filepath.Join(at, seg)
+		if info, err := os.Lstat(at); err == nil && info.Mode()&os.ModeSymlink != 0 {
+			return at + " is a symbolic link"
+		}
+	}
+	return ""
+}
+
+// removeEmptyParents removes empty directories from dir up to, not including, root.
+func removeEmptyParents(root, dir string) {
+	for dir != root && strings.HasPrefix(dir, root+string(filepath.Separator)) {
+		if err := os.Remove(dir); err != nil {
+			return
+		}
+		dir = filepath.Dir(dir)
+	}
+}
+
+// HomeConflict says whether registering an item at the home scope here would collide with something the
+// person made: "" when it would not.
+func HomeConflict(p Paths, it Item) string {
+	var placed Placed
+	_ = readJSON(p.placed(), &placed)
+	for rel := range HomeFiles(Config{Home: []Item{it}}) {
+		if _, ours := placed[rel]; ours {
+			continue
+		}
+		if _, err := os.Stat(filepath.Join(p.Home, ".claude", filepath.FromSlash(rel))); err == nil {
+			return fmt.Sprintf("%s already exists in this home and the mesh did not place it; pick another name, or import it", rel)
+		}
+	}
+	return ""
+}
+
+// ---- what the module did not place ------------------------------------------------------------------
+
+// HomeItem is one item found in the home.
+type HomeItem struct {
+	Kind   string   `json:"kind"`
+	Name   string   `json:"name"`
+	Path   string   `json:"path"`
+	Placed bool     `json:"placedByTheMesh"`
+	Notes  []string `json:"notes,omitempty"`
+}
+
+var mcpToolRef = regexp.MustCompile(`mcp__([A-Za-z0-9_-]+)__[A-Za-z0-9_-]+`)
+
+// HomeItems lists the home's skills, subagents, commands, output styles and rule files, says which the mesh
+// placed, and notes those that share a name with a mesh item or call a tool server that is not loaded here.
+func HomeItems(p Paths, c Config, loaded Servers) []HomeItem {
+	dir := filepath.Join(p.Home, ".claude")
+	var placed Placed
+	_ = readJSON(p.placed(), &placed)
+	inPlugin := map[string]bool{}
+	for _, layer := range [][]Item{c.Mesh, c.Node} {
+		for _, it := range layer {
+			inPlugin[it.Kind+"/"+it.Name] = true
+		}
+	}
+	var out []HomeItem
+	add := func(kind, name, rel, body string) {
+		h := HomeItem{Kind: kind, Name: name, Path: filepath.Join(dir, filepath.FromSlash(rel))}
+		_, h.Placed = placed[rel]
+		if inPlugin[kind+"/"+name] {
+			h.Notes = append(h.Notes, "the mesh also registers a "+kind+" of this name, offered as "+Plugin+":"+name)
+		}
+		seen := map[string]bool{}
+		for _, m := range mcpToolRef.FindAllStringSubmatch(body, -1) {
+			if server := m[1]; !seen[server] && server != meshEntry && loaded[server] == nil {
+				seen[server] = true
+				h.Notes = append(h.Notes, "calls tools of `"+server+"`, a tool server not loaded on this node")
+			}
+		}
+		out = append(out, h)
+	}
+	if entries, err := os.ReadDir(filepath.Join(dir, "skills")); err == nil {
+		for _, e := range entries {
+			if !e.IsDir() {
+				continue
+			}
+			body, err := os.ReadFile(filepath.Join(dir, "skills", e.Name(), "SKILL.md"))
+			if err != nil {
+				continue // the vendor's own synced folders carry none at their top
+			}
+			add(KindSkill, e.Name(), "skills/"+e.Name()+"/SKILL.md", string(body))
+		}
+	}
+	for kind, sub := range map[string]string{KindAgent: "agents", KindCommand: "commands", KindOutputStyle: "output-styles", KindInstructions: "rules"} {
+		entries, err := os.ReadDir(filepath.Join(dir, sub))
+		if err != nil {
+			continue
+		}
+		for _, e := range entries {
+			if e.IsDir() || !strings.HasSuffix(e.Name(), ".md") {
+				continue
+			}
+			body, _ := os.ReadFile(filepath.Join(dir, sub, e.Name()))
+			add(kind, strings.TrimSuffix(e.Name(), ".md"), sub+"/"+e.Name(), string(body))
+		}
+	}
+	sort.Slice(out, func(i, j int) bool {
+		if out[i].Kind != out[j].Kind {
+			return out[i].Kind < out[j].Kind
+		}
+		return out[i].Name < out[j].Name
+	})
+	return out
+}
+
+// ImportFromHome reads one item of this node's home as an item to register. A rule file becomes instructions.
+func ImportFromHome(p Paths, kind, name string) (Item, error) {
+	dir := filepath.Join(p.Home, ".claude")
+	it := Item{Kind: kind, Name: name, Files: map[string]string{}}
+	switch kind {
+	case KindSkill:
+		root := filepath.Join(dir, "skills", name)
+		err := filepath.WalkDir(root, func(full string, d os.DirEntry, err error) error {
+			if err != nil || d.IsDir() {
+				return err
+			}
+			rel, _ := filepath.Rel(root, full)
+			raw, err := os.ReadFile(full)
+			if err != nil {
+				return err
+			}
+			it.Files[filepath.ToSlash(rel)] = string(raw)
+			return nil
+		})
+		if err != nil {
+			return Item{}, fmt.Errorf("the skill %s in this home: %w", name, err)
+		}
+	case KindAgent, KindCommand, KindOutputStyle, KindInstructions:
+		sub := map[string]string{KindAgent: "agents", KindCommand: "commands", KindOutputStyle: "output-styles", KindInstructions: "rules"}[kind]
+		raw, err := os.ReadFile(filepath.Join(dir, sub, name+".md"))
+		if err != nil {
+			return Item{}, fmt.Errorf("the %s %s in this home: %w", kind, name, err)
+		}
+		it.Files[name+".md"] = string(raw)
+	default:
+		return Item{}, fmt.Errorf("a %s is not imported from a home", kind)
+	}
+	return it, nil
+}
+
+// ---- registering ------------------------------------------------------------------------------------
+
+// ConfigState is the `config` state as this module reaches it through the runtime.
+type ConfigState interface {
+	Put(key string, value any) error
+	Delete(key string) error
+	Keys() ([]string, error)
+	Get(key string) (json.RawMessage, bool, error)
+}
+
+// Register puts an item (or, with unregister, removes it) at its scope: at the mesh scope one key, at the
+// node and home scopes one key per node — this node when none is given. Taken into this node's view at once,
+// so the answer says what it did here.
+func Register(p Paths, it Item, nodes []string, unregister bool, state ConfigState, v *ConfigView, write WriteManaged) (map[string]any, error) {
+	if !unregister {
+		it.By, it.At = p.Node, time.Now().UTC().Format(time.RFC3339)
+		if problem := it.Problem(); problem != "" {
+			return map[string]any{"registered": false, "reason": problem}, nil
+		}
+	} else if !knownKind(it.Kind) {
+		return map[string]any{"unregistered": false, "reason": fmt.Sprintf("%q is not a kind", it.Kind)}, nil
+	}
+	if it.Scope == ScopeMesh {
+		nodes = []string{""}
+	} else if len(nodes) == 0 {
+		nodes = []string{p.Node}
+	} else if problem := nodesProblem(nodes); problem != "" {
+		return map[string]any{verbOf(unregister): false, "reason": problem}, nil
+	}
+	if !unregister && it.Scope == ScopeHome {
+		for _, n := range nodes {
+			if n == p.Node {
+				if conflict := HomeConflict(p, it); conflict != "" {
+					return map[string]any{"registered": false, "reason": conflict}, nil
+				}
+			}
+		}
+	}
+	var keys []string
+	changed := false
+	for _, n := range nodes {
+		key := it.Key(n)
+		keys = append(keys, key)
+		var err error
+		if unregister {
+			err = state.Delete(key)
+		} else {
+			err = state.Put(key, it)
+		}
+		if err != nil {
+			return nil, err
+		}
+		op := "put"
+		if unregister {
+			op = "delete"
+		}
+		item := it
+		changed = v.Take(key, op, &item) || changed
+	}
+	verb := map[bool]string{false: "registered", true: "unregistered"}[unregister]
+	answer := map[string]any{verb: it.Kind + " " + it.Name, "keys": keys}
+	if !unregister {
+		switch {
+		case it.Scope == ScopeHome && it.Kind == KindCommand:
+			answer["offered as"] = "/" + it.Name
+		case it.Scope == ScopeHome:
+			answer["offered as"] = it.Name + ", from the home"
+		case it.Kind == KindSkill || it.Kind == KindAgent || it.Kind == KindOutputStyle:
+			answer["offered as"] = Plugin + ":" + it.Name
+		case it.Kind == KindCommand:
+			answer["offered as"] = "/" + Plugin + ":" + it.Name
+		}
+	}
+	if changed {
+		rendered, err := RenderNow(p, write)
+		answer["rendered here"] = rendered
+		if err != nil {
+			answer["not written here"] = err.Error() // kept on the bus all the same; the next render tries again
+		}
+		answer["sessions"] = "a new session takes it; a running one at /reload-plugins"
+	} else if v.Applies(keys[0]) || len(keys) > 1 {
+		answer["here"] = "already so"
+	} else {
+		answer["here"] = "not this node: each node it is for takes it from the bus"
+	}
+	return answer, nil
+}
+
+func verbOf(unregister bool) string {
+	return map[bool]string{false: "registered", true: "unregistered"}[unregister]
+}
+
+// nodesProblem says why a list of nodes cannot name keys, or "". "all" has been expanded before this.
+func nodesProblem(nodes []string) string {
+	for _, n := range nodes {
+		if !nodeName.MatchString(n) {
+			return fmt.Sprintf("%q is not a node's name", n)
+		}
+	}
+	return ""
+}
+
+// ExpandNodes turns `all` into every node running the module; anything else is kept.
+func ExpandNodes(nodes []string, running func() ([]string, error)) ([]string, error) {
+	if len(nodes) != 1 || nodes[0] != "all" {
+		return nodes, nil
+	}
+	all, err := running()
+	if err != nil {
+		return nil, fmt.Errorf("which nodes run claude-code: %w", err)
+	}
+	if len(all) == 0 {
+		return nil, fmt.Errorf("no node is known to run claude-code")
+	}
+	return all, nil
+}
+
+// List is every registration of a kind ("" for every kind) on the mesh, by key, read from the state.
+func List(state ConfigState, kind string) (map[string]any, error) {
+	keys, err := state.Keys()
+	if err != nil {
+		return nil, err
+	}
+	sort.Strings(keys)
+	out := map[string]any{}
+	for _, key := range keys {
+		_, _, k, _, ok := ParseKey(key)
+		if !ok || (kind != "" && k != kind) {
+			continue
+		}
+		raw, found, err := state.Get(key)
+		if err != nil || !found {
+			continue
+		}
+		var it Item
+		if json.Unmarshal(raw, &it) != nil {
+			continue
+		}
+		files := make([]string, 0, len(it.Files))
+		for f := range it.Files {
+			files = append(files, f)
+		}
+		sort.Strings(files)
+		summary := map[string]any{"by": it.By, "at": it.At}
+		if len(files) > 0 {
+			summary["files"] = files
+		}
+		if it.Kind == KindHook {
+			summary["event"], summary["matcher"], summary["command"] = it.Event, it.Matcher, it.Command
+		}
+		if it.Kind == KindSettings {
+			summary["settings"] = it.Settings
+		}
+		out[key] = summary
+	}
+	return out, nil
+}
+
+// Show is one registration in full: its files' content included.
+func Show(state ConfigState, key string) (any, error) {
+	raw, found, err := state.Get(key)
+	if err != nil {
+		return nil, err
+	}
+	if !found {
+		return nil, fmt.Errorf("nothing is registered at %s", key)
+	}
+	var it Item
+	if err := json.Unmarshal(raw, &it); err != nil {
+		return nil, err
+	}
+	return it, nil
+}

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

@@ -0,0 +1,457 @@
+package main
+
+// The agent's configuration registered at three scopes (novox/hq ADR 0216): each test is one row of the
+// record's "How it is checked".
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// memConfig is the `config` state as a map, shared by the nodes of a test the way the bus shares it.
+type memConfig map[string]json.RawMessage
+
+func (m memConfig) Put(key string, value any) error {
+	raw, err := json.Marshal(value)
+	m[key] = raw
+	return err
+}
+func (m memConfig) Delete(key string) error { delete(m, key); return nil }
+func (m memConfig) Keys() ([]string, error) {
+	out := []string{}
+	for k := range m {
+		out = append(out, k)
+	}
+	return out, nil
+}
+func (m memConfig) Get(key string) (json.RawMessage, bool, error) {
+	raw, ok := m[key]
+	return raw, ok, nil
+}
+
+// deliver hands every key of the state to a node's view, as its watch would.
+func deliver(m memConfig, v *ConfigView) {
+	for key, raw := range m {
+		var it Item
+		_ = json.Unmarshal(raw, &it)
+		v.Take(key, "put", &it)
+	}
+}
+
+func one(name, content string) map[string]string { return map[string]string{name + ".md": content} }
+
+func pluginOf(t *testing.T, w map[string]string) map[string]PluginFile {
+	t.Helper()
+	var files map[string]PluginFile
+	if err := json.Unmarshal([]byte(w[MarketplaceDir+"/"]), &files); err != nil {
+		t.Fatalf("no marketplace written: %v", err)
+	}
+	return files
+}
+
+func TestEachKindLandsInItsOnePlace(t *testing.T) {
+	p, w := node(t, "laptop")
+	state, view := memConfig{}, NewConfigView(p)
+	register := func(it Item) {
+		t.Helper()
+		answer, err := Register(p, it, nil, false, state, view, writer(w))
+		if err != nil || answer["registered"] == false {
+			t.Fatalf("%s %s: %v %v", it.Kind, it.Name, answer, err)
+		}
+	}
+	register(Item{Kind: KindSkill, Name: "review", Scope: ScopeMesh,
+		Files: map[string]string{"SKILL.md": "---\nname: review\ndescription: d\n---\nbody", "scripts/run.sh": "#!/bin/sh\necho hi\n"}})
+	register(Item{Kind: KindAgent, Name: "reviewer", Scope: ScopeMesh, Files: one("reviewer", "---\nname: reviewer\n---\nx")})
+	register(Item{Kind: KindCommand, Name: "ship", Scope: ScopeMesh, Files: one("ship", "ship it")})
+	register(Item{Kind: KindOutputStyle, Name: "terse", Scope: ScopeMesh, Files: one("terse", "---\nname: terse\n---\nshort")})
+	register(Item{Kind: KindHook, Name: "guard", Scope: ScopeMesh, Event: "PreToolUse", Matcher: "Bash",
+		Command: "${HOOK_DIR}/guard.sh", Files: map[string]string{"guard.sh": "#!/bin/sh\nexit 0\n"}})
+	register(Item{Kind: KindInstructions, Name: "conventions", Scope: ScopeMesh, Files: one("conventions", "Commit in the imperative.")})
+	register(Item{Kind: KindSettings, Name: SettingsName, Scope: ScopeMesh,
+		Settings: map[string]any{"permissions": map[string]any{"deny": []any{"Bash(rm -rf:*)"}}}})
+
+	plugin := pluginOf(t, w)
+	root := "plugins/" + Plugin + "/"
+	for _, want := range []string{".claude-plugin/marketplace.json", root + ".claude-plugin/plugin.json",
+		root + "skills/review/SKILL.md", root + "skills/review/scripts/run.sh", root + "agents/reviewer.md",
+		root + "commands/ship.md", root + "output-styles/terse.md", root + "hooks/hooks.json", root + "hooks/guard/guard.sh"} {
+		if _, ok := plugin[want]; !ok {
+			t.Errorf("the plugin lacks %s", want)
+		}
+	}
+	if !plugin[root+"skills/review/scripts/run.sh"].Executable || !plugin[root+"hooks/guard/guard.sh"].Executable {
+		t.Error("a script is not executable")
+	}
+	var hooks struct {
+		Hooks map[string][]struct {
+			Matcher string `json:"matcher"`
+			Hooks   []struct {
+				Command string `json:"command"`
+			} `json:"hooks"`
+		} `json:"hooks"`
+	}
+	_ = json.Unmarshal([]byte(plugin[root+"hooks/hooks.json"].Content), &hooks)
+	if pre := hooks.Hooks["PreToolUse"]; len(pre) != 1 || pre[0].Matcher != "Bash" ||
+		pre[0].Hooks[0].Command != `"${CLAUDE_PLUGIN_ROOT}/hooks/guard"/guard.sh` {
+		t.Errorf("the hook's command does not name its directory, quoted: %s", plugin[root+"hooks/hooks.json"].Content)
+	}
+	if !strings.Contains(w["CLAUDE.md"], "### conventions\n\nCommit in the imperative.") {
+		t.Errorf("the instruction section is not in the managed instruction file:\n%s", w["CLAUDE.md"])
+	}
+	var managed map[string]any
+	_ = json.Unmarshal([]byte(w["managed-settings.json"]), &managed)
+	if managed["permissions"] == nil || managed["enabledPlugins"].(map[string]any)[Plugin+"@"+Plugin] != true {
+		t.Errorf("managed settings: %v", managed)
+	}
+	if _, inPlugin := plugin[root+"settings.json"]; inPlugin {
+		t.Error("settings were put in the plugin, which drops them")
+	}
+}
+
+func TestAMeshItemReachesEveryNodeANodeItemOneAndAHomeItemOneHome(t *testing.T) {
+	a, wa := node(t, "laptop")
+	b, wb := node(t, "server")
+	state := memConfig{}
+	va, vb := NewConfigView(a), NewConfigView(b)
+	for _, r := range []struct {
+		it    Item
+		nodes []string
+	}{
+		{Item{Kind: KindCommand, Name: "everywhere", Scope: ScopeMesh, Files: one("everywhere", "x")}, nil},
+		{Item{Kind: KindCommand, Name: "server-only", Scope: ScopeNode, Files: one("server-only", "x")}, []string{"server"}},
+		{Item{Kind: KindCommand, Name: "at-home", Scope: ScopeHome, Files: one("at-home", "x")}, []string{"laptop"}},
+	} {
+		if _, err := Register(a, r.it, r.nodes, false, state, va, writer(wa)); err != nil {
+			t.Fatal(err)
+		}
+	}
+	deliver(state, vb)
+	if _, err := RenderNow(b, writer(wb)); err != nil {
+		t.Fatal(err)
+	}
+	root := "plugins/" + Plugin + "/commands/"
+	pa, pb := pluginOf(t, wa), pluginOf(t, wb)
+	if _, ok := pa[root+"everywhere.md"]; !ok {
+		t.Error("the mesh item is missing on the laptop")
+	}
+	if _, ok := pb[root+"everywhere.md"]; !ok {
+		t.Error("the mesh item is missing on the server")
+	}
+	if _, ok := pa[root+"server-only.md"]; ok {
+		t.Error("the server's item reached the laptop")
+	}
+	if _, ok := pb[root+"server-only.md"]; !ok {
+		t.Error("the server's item is missing on the server")
+	}
+	if _, err := os.Stat(filepath.Join(a.Home, ".claude", "commands", "at-home.md")); err != nil {
+		t.Error("the home item was not placed in the laptop's home")
+	}
+	if _, err := os.Stat(filepath.Join(b.Home, ".claude", "commands", "at-home.md")); err == nil {
+		t.Error("the laptop's home item reached the server's home")
+	}
+	if _, ok := pa[root+"at-home.md"]; ok {
+		t.Error("a home item went into the plugin")
+	}
+}
+
+func TestTheMeshsOwnKeysCannotBeSetOrReplaced(t *testing.T) {
+	for _, key := range []string{"extraKnownMarketplaces", "enabledPlugins", "attribution", "apiKeyHelper"} {
+		it := Item{Kind: KindSettings, Name: SettingsName, Scope: ScopeMesh, Settings: map[string]any{key: true}}
+		if it.Problem() == "" {
+			t.Errorf("a registration could set %s", key)
+		}
+	}
+	out := Render(Facts{Console: "x"}, Settings{ManagedSettings: map[string]any{"enabledPlugins": map[string]any{Plugin + "@" + Plugin: false}}},
+		nil, "/h", nil, Config{})
+	var managed map[string]any
+	_ = json.Unmarshal([]byte(out["managed-settings.json"]), &managed)
+	if managed["enabledPlugins"].(map[string]any)[Plugin+"@"+Plugin] != true {
+		t.Error("the operator's setting turned the mesh's plugin off")
+	}
+}
+
+func TestSettingsLayMeshThenNodeAndJoinTheirLists(t *testing.T) {
+	c := Config{
+		Mesh: []Item{{Kind: KindSettings, Scope: ScopeMesh, Settings: map[string]any{
+			"permissions": map[string]any{"deny": []any{"A"}}, "model": "mesh-model"}}},
+		Node: []Item{{Kind: KindSettings, Scope: ScopeNode, Settings: map[string]any{
+			"permissions": map[string]any{"deny": []any{"A", "B"}}, "model": "node-model"}}},
+	}
+	out := Render(Facts{Console: "x"}, Settings{ManagedSettings: map[string]any{"permissions": map[string]any{"allow": []any{"C"}}}},
+		nil, "/h", nil, c)
+	var managed struct {
+		Permissions map[string][]string `json:"permissions"`
+		Model       string              `json:"model"`
+	}
+	_ = json.Unmarshal([]byte(out["managed-settings.json"]), &managed)
+	if strings.Join(managed.Permissions["deny"], ",") != "A,B" || strings.Join(managed.Permissions["allow"], ",") != "C" || managed.Model != "node-model" {
+		t.Fatalf("%+v", managed)
+	}
+}
+
+func TestTheHomeScopeOwnsOnlyWhatItPlaced(t *testing.T) {
+	p, w := node(t, "laptop")
+	state, view := memConfig{}, NewConfigView(p)
+	mine := filepath.Join(p.Home, ".claude", "agents", "mine.md")
+	_ = os.MkdirAll(filepath.Dir(mine), 0o755)
+	writeFile(t, mine, "the person's own")
+
+	answer, _ := Register(p, Item{Kind: KindAgent, Name: "mine", Scope: ScopeHome, Files: one("mine", "the mesh's")}, nil, false, state, view, writer(w))
+	if answer["registered"] != false {
+		t.Fatalf("a name the person uses was taken: %v", answer)
+	}
+	if raw, _ := os.ReadFile(mine); string(raw) != "the person's own" {
+		t.Fatal("the person's file was overwritten")
+	}
+
+	placed := filepath.Join(p.Home, ".claude", "agents", "placed.md")
+	if _, err := Register(p, Item{Kind: KindAgent, Name: "placed", Scope: ScopeHome, Files: one("placed", "v1")}, nil, false, state, view, writer(w)); err != nil {
+		t.Fatal(err)
+	}
+	if raw, _ := os.ReadFile(placed); string(raw) != "v1" {
+		t.Fatal("the home item was not placed")
+	}
+	if _, err := Register(p, Item{Kind: KindAgent, Name: "placed", Scope: ScopeHome}, nil, true, state, view, writer(w)); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := os.Stat(placed); err == nil {
+		t.Fatal("unregistering did not remove what the mesh placed")
+	}
+	if _, err := os.Stat(mine); err != nil {
+		t.Fatal("unregistering removed the person's file")
+	}
+
+	// Changed by hand after it was placed: left alone when unregistered.
+	if _, err := Register(p, Item{Kind: KindAgent, Name: "edited", Scope: ScopeHome, Files: one("edited", "v1")}, nil, false, state, view, writer(w)); err != nil {
+		t.Fatal(err)
+	}
+	edited := filepath.Join(p.Home, ".claude", "agents", "edited.md")
+	writeFile(t, edited, "changed by hand")
+	if _, err := Register(p, Item{Kind: KindAgent, Name: "edited", Scope: ScopeHome}, nil, true, state, view, writer(w)); err != nil {
+		t.Fatal(err)
+	}
+	if raw, _ := os.ReadFile(edited); string(raw) != "changed by hand" {
+		t.Fatal("a placed file changed by hand was removed")
+	}
+}
+
+func TestAnItemAboveTheLimitOrMisshapenIsRefused(t *testing.T) {
+	big := Item{Kind: KindSkill, Name: "big", Scope: ScopeMesh, Files: map[string]string{"SKILL.md": strings.Repeat("x", MaxItemBytes+1)}}
+	cases := map[string]Item{
+		"too big":             big,
+		"a bad name":          {Kind: KindAgent, Name: "Bad Name", Scope: ScopeMesh, Files: one("Bad Name", "x")},
+		"a skill without one": {Kind: KindSkill, Name: "s", Scope: ScopeMesh, Files: map[string]string{"other.md": "x"}},
+		"a path outside":      {Kind: KindSkill, Name: "s", Scope: ScopeMesh, Files: map[string]string{"SKILL.md": "x", "../escape": "x"}},
+		"a hook at home":      {Kind: KindHook, Name: "h", Scope: ScopeHome, Event: "Stop", Command: "true"},
+		"settings at home":    {Kind: KindSettings, Name: SettingsName, Scope: ScopeHome, Settings: map[string]any{"model": "x"}},
+		"an unknown event":    {Kind: KindHook, Name: "h", Scope: ScopeMesh, Event: "Whenever", Command: "true"},
+	}
+	for label, it := range cases {
+		if it.Problem() == "" {
+			t.Errorf("%s was accepted", label)
+		}
+	}
+}
+
+func TestAHomeItemIsImportedAndTheStaleOnesAreNamed(t *testing.T) {
+	p, _ := node(t, "laptop")
+	dir := filepath.Join(p.Home, ".claude")
+	_ = os.MkdirAll(filepath.Join(dir, "skills", "old", "scripts"), 0o755)
+	writeFile(t, filepath.Join(dir, "skills", "old", "SKILL.md"), "---\nname: old\n---\nuse mcp__gone__do_it")
+	writeFile(t, filepath.Join(dir, "skills", "old", "scripts", "a.sh"), "#!/bin/sh\n")
+	it, err := ImportFromHome(p, KindSkill, "old")
+	if err != nil || len(it.Files) != 2 || it.Files["scripts/a.sh"] == "" {
+		t.Fatalf("%+v %v", it, err)
+	}
+	items := HomeItems(p, Config{Mesh: []Item{{Kind: KindSkill, Name: "old"}}}, Servers{})
+	if len(items) != 1 || len(items[0].Notes) != 2 {
+		t.Fatalf("%+v", items)
+	}
+}
+
+// The manifest lists exactly the tools the bundle serves: a tool missing from it is never announced.
+func TestTheManifestListsEveryToolServed(t *testing.T) {
+	raw, err := os.ReadFile("../../module.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var m struct {
+		Tools []string `json:"tools"`
+	}
+	_ = json.Unmarshal(raw, &m)
+	listed := map[string]bool{}
+	for _, n := range m.Tools {
+		listed[n] = true
+	}
+	p, _ := node(t, "laptop")
+	served := tools(p, nil, NewServerView(p), memConfig{}, NewConfigView(p))
+	for _, tool := range served {
+		if !listed[tool.Name] {
+			t.Errorf("%s is served and not in the manifest", tool.Name)
+		}
+		delete(listed, tool.Name)
+	}
+	for n := range listed {
+		t.Errorf("%s is in the manifest and not served", n)
+	}
+}
+
+// The tree writer's comparison: a directory holding exactly the files given, executable bits included.
+func TestATreeIsTheSameOnlyWhenEveryFileAndModeIs(t *testing.T) {
+	dir := t.TempDir()
+	files := map[string]PluginFile{"a.md": {Content: "a"}, "s/run.sh": {Content: "#!/bin/sh\n", Executable: true}}
+	_ = os.MkdirAll(filepath.Join(dir, "s"), 0o755)
+	writeFile(t, filepath.Join(dir, "a.md"), "a")
+	writeFile(t, filepath.Join(dir, "s", "run.sh"), "#!/bin/sh\n")
+	if sameTree(dir, files) {
+		t.Fatal("a script without its executable bit counted as the same")
+	}
+	_ = os.Chmod(filepath.Join(dir, "s", "run.sh"), 0o755)
+	if !sameTree(dir, files) {
+		t.Fatal("the same tree counted as different")
+	}
+	writeFile(t, filepath.Join(dir, "extra.md"), "x")
+	if sameTree(dir, files) {
+		t.Fatal("an extra file counted as the same")
+	}
+}
+
+// A registration removed while a node was away is dropped when it is back: the watch hands over only what is
+// there, so the view is pruned to the keys the state still holds.
+func TestWhatWasRemovedWhileANodeWasAwayIsDropped(t *testing.T) {
+	p, w := node(t, "laptop")
+	state, view := memConfig{}, NewConfigView(p)
+	for _, name := range []string{"kept", "gone"} {
+		if _, err := Register(p, Item{Kind: KindCommand, Name: name, Scope: ScopeMesh, Files: one(name, "x")}, nil, false, state, view, writer(w)); err != nil {
+			t.Fatal(err)
+		}
+	}
+	delete(state, "mesh.command.gone") // removed from another node while this one was off
+	back := NewConfigView(p)           // the node starts again from what it last wrote
+	if len(back.Items()) != 2 {
+		t.Fatalf("the view did not start from what was last written: %v", back.Items())
+	}
+	keys, _ := state.Keys()
+	if !back.Prune(keys) || len(back.Items()) != 1 {
+		t.Fatalf("after pruning: %v", back.Items())
+	}
+}
+
+// The review's findings, each held by a test.
+
+func TestAPathOrAKeyThatIsNotWhatItSaysIsRefused(t *testing.T) {
+	for label, files := range map[string]map[string]string{
+		"a dot":                {"SKILL.md": "x", ".": "x"},
+		"an empty segment":     {"SKILL.md": "x", "a//b": "x"},
+		"a parent segment":     {"SKILL.md": "x", "a/../b": "x"},
+		"a file and directory": {"SKILL.md": "x", "a": "x", "a/b": "x"},
+	} {
+		if (Item{Kind: KindSkill, Name: "s", Scope: ScopeMesh, Files: files}).Problem() == "" {
+			t.Errorf("%s was accepted", label)
+		}
+	}
+	p, _ := node(t, "laptop")
+	v := NewConfigView(p)
+	home := Item{Kind: KindCommand, Name: "x", Scope: ScopeHome, Files: one("x", "y")}
+	if v.Take("mesh.command.x", "put", &home); len(v.Items()) != 0 {
+		t.Fatal("a mesh key holding a home item was taken")
+	}
+	for _, key := range []string{"mesh.command.x", "mesh.agent.x"} {
+		mesh := Item{Kind: KindCommand, Name: "x", Scope: ScopeMesh, Files: one("x", "y")}
+		v.Take(key, "put", &mesh)
+	}
+	if len(v.Items()) != 1 {
+		t.Fatalf("an item under a key of another kind was taken: %v", v.Items())
+	}
+}
+
+func TestAllIsEveryNodeAndANameThatCannotBeAKeyIsRefused(t *testing.T) {
+	nodes, err := ExpandNodes([]string{"all"}, func() ([]string, error) { return []string{"ace", "g14"}, nil })
+	if err != nil || strings.Join(nodes, ",") != "ace,g14" {
+		t.Fatalf("%v %v", nodes, err)
+	}
+	p, w := node(t, "laptop")
+	answer, _ := Register(p, Item{Kind: KindCommand, Name: "c", Scope: ScopeNode, Files: one("c", "x")}, []string{"a.b"}, false, memConfig{}, NewConfigView(p), writer(w))
+	if answer["registered"] != false {
+		t.Fatalf("a node name with a dot was used in a key: %v", answer)
+	}
+	if (Item{Kind: KindSettings, Name: SettingsName, Scope: ScopeMesh, Settings: map[string]any{"deniedMcpServers": []any{}}}).Problem() == "" {
+		t.Fatal("a registration could deny the mesh's console")
+	}
+}
+
+func TestTheOperatorsOwnPluginsAndMarketplacesAreKept(t *testing.T) {
+	out := Render(Facts{Console: "x"}, Settings{ManagedSettings: map[string]any{
+		"enabledPlugins":         map[string]any{"theirs@market": true},
+		"extraKnownMarketplaces": map[string]any{"market": map[string]any{"source": map[string]any{"source": "github", "repo": "o/r"}}},
+	}}, nil, "/h", nil, Config{})
+	var managed struct {
+		Enabled map[string]any `json:"enabledPlugins"`
+		Known   map[string]any `json:"extraKnownMarketplaces"`
+	}
+	_ = json.Unmarshal([]byte(out["managed-settings.json"]), &managed)
+	if managed.Enabled["theirs@market"] != true || managed.Enabled[Plugin+"@"+Plugin] != true || managed.Known["market"] == nil || managed.Known[Plugin] == nil {
+		t.Fatalf("%+v", managed)
+	}
+}
+
+func TestTheHomeLeavesThePersonsChoicesAlone(t *testing.T) {
+	p, _ := node(t, "laptop")
+	dir := filepath.Join(p.Home, ".claude")
+	// An identical file the person made is not taken over, so unregistering never removes it.
+	_ = os.MkdirAll(filepath.Join(dir, "agents"), 0o755)
+	writeFile(t, filepath.Join(dir, "agents", "same.md"), "x")
+	if _, left := PlaceHome(p, map[string]string{"agents/same.md": "x"}); len(left) != 1 {
+		t.Fatalf("an identical file of the person's was taken over: %v", left)
+	}
+	PlaceHome(p, map[string]string{})
+	if _, err := os.Stat(filepath.Join(dir, "agents", "same.md")); err != nil {
+		t.Fatal("the person's file was removed")
+	}
+	// A placed file the person deleted stays deleted while it is registered.
+	PlaceHome(p, map[string]string{"commands/c.md": "x"})
+	_ = os.Remove(filepath.Join(dir, "commands", "c.md"))
+	PlaceHome(p, map[string]string{"commands/c.md": "x"})
+	if _, err := os.Stat(filepath.Join(dir, "commands", "c.md")); err == nil {
+		t.Fatal("a file the person deleted was placed again")
+	}
+	// The kind's own directory stays when the mesh's last item in it goes.
+	PlaceHome(p, map[string]string{"skills/s/SKILL.md": "x"})
+	PlaceHome(p, map[string]string{})
+	if _, err := os.Stat(filepath.Join(dir, "skills", "s")); err == nil {
+		t.Fatal("the item's own directory was left")
+	}
+	if _, err := os.Stat(filepath.Join(dir, "skills")); err != nil {
+		t.Fatal("the kind's directory was removed")
+	}
+	// Never through a symbolic link.
+	elsewhere := t.TempDir()
+	if err := os.Symlink(elsewhere, filepath.Join(dir, "output-styles")); err != nil {
+		t.Skip("no symbolic links here")
+	}
+	PlaceHome(p, map[string]string{"output-styles/o.md": "x"})
+	if _, err := os.Stat(filepath.Join(elsewhere, "o.md")); err == nil {
+		t.Fatal("a file was written through a symbolic link")
+	}
+}
+
+func TestOneFileThatCannotBeWrittenDoesNotStopTheOthers(t *testing.T) {
+	p, _ := node(t, "laptop")
+	w := map[string]string{}
+	failing := func(name, content string) (string, error) {
+		if name == MarketplaceDir+"/" {
+			return "", os.ErrPermission
+		}
+		w[name] = content
+		return name + ": written", nil
+	}
+	if _, err := RenderNow(p, failing); err == nil {
+		t.Fatal("the failure was not reported")
+	}
+	if w["managed-settings.json"] == "" || w["managed-mcp.json"] == "" || w["CLAUDE.md"] == "" {
+		t.Fatalf("the other files were not written: %v", w)
+	}
+}

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

@@ -0,0 +1,353 @@
+package main
+
+// The tools that register the agent's configuration (novox/hq ADR 0216): for each kind a list, a register and an
+// unregister; for settings, a read, a set, a clear and the permission rules; and the status and import tools
+// for what the module did not place.
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+// kindTool is how one kind is named in its tools and described to whoever calls them.
+type kindTool struct {
+	kind, tool, what, lands string
+}
+
+var kindTools = []kindTool{
+	{KindSkill, "skill", "a skill: a folder with a SKILL.md (front matter `name` and `description`) and any files beside it",
+		"the plugin's skills/<name>/ (home: ~/.claude/skills/<name>/)"},
+	{KindAgent, "agent", "a subagent: one markdown file with front matter (`name`, `description`, optionally `tools`, `model`)",
+		"the plugin's agents/<name>.md (home: ~/.claude/agents/<name>.md)"},
+	{KindCommand, "command", "a slash command: one markdown file, its front matter optional (`description`, `argument-hint`, `allowed-tools`)",
+		"the plugin's commands/<name>.md, run as /" + Plugin + ":<name> (home: ~/.claude/commands/<name>.md, run as /<name>)"},
+	{KindHook, "hook", "a hook: an event, an optional matcher, a command, and optionally the scripts it runs — ${HOOK_DIR} in the command is their directory",
+		"the plugin's hooks/hooks.json, its scripts in hooks/<name>/ (mesh and node scopes only)"},
+	{KindOutputStyle, "output_style", "an output style: one markdown file with front matter (`name`, `description`)",
+		"the plugin's output-styles/<name>.md (home: ~/.claude/output-styles/<name>.md)"},
+	{KindInstructions, "instructions", "a section of instructions every session reads",
+		"a section of the managed instruction file, after the mesh's own text (home: a rule file, ~/.claude/rules/<name>.md)"},
+}
+
+func boolArg(a map[string]any, k string) bool { b, _ := a[k].(bool); return b }
+func strArg(a map[string]any, k string) string {
+	s, _ := a[k].(string)
+	return strings.TrimSpace(s)
+}
+
+// targetNodes reads the `nodes` argument: absent is this node, "all" every node running claude-code, else a list.
+func targetNodes(a map[string]any) ([]string, error) {
+	return ExpandNodes(nodesOf(a["nodes"]), nodesRunningMe)
+}
+
+// scopeOf reads the `scope` argument; absent is the mesh, which is what a registration is most often for.
+func scopeOf(a map[string]any) string {
+	if s := strArg(a, "scope"); s != "" {
+		return s
+	}
+	return ScopeMesh
+}
+
+// filesOf reads an item's files: `content` for a one-file kind, or `files`, a map of path to content.
+func filesOf(kind, name string, a map[string]any) (map[string]string, error) {
+	out := map[string]string{}
+	if raw, ok := a["files"].(map[string]any); ok {
+		for rel, v := range raw {
+			s, ok := v.(string)
+			if !ok {
+				return nil, fmt.Errorf("files.%s is not text", rel)
+			}
+			out[rel] = s
+		}
+	}
+	if content, ok := a["content"].(string); ok && content != "" {
+		switch kind {
+		case KindSkill:
+			out["SKILL.md"] = content
+		case KindHook:
+			return nil, errors.New("a hook's scripts are given as files")
+		default:
+			out[name+".md"] = content
+		}
+	}
+	return out, nil
+}
+
+func configTools(p Paths, state ConfigState, view *ConfigView) []stdio.Tool {
+	scopeArg := str(`mesh (every node; the default), node (the nodes given, or this one) or home (the operator account's own ~/.claude on the nodes given, or this one)`)
+	nodesArg := str(`for the node and home scopes: "all" for every node running claude-code, or a comma-separated list; absent is this node`)
+	var out []stdio.Tool
+	for _, k := range kindTools {
+		k := k
+		input := map[string]any{
+			"name":  str("the name: lower-case letters, digits and -"),
+			"scope": scopeArg,
+			"nodes": nodesArg,
+		}
+		switch k.kind {
+		case KindSkill:
+			input["content"] = str("the SKILL.md, when the skill is that one file")
+			input["files"] = map[string]any{"type": "object", "description": "the skill's files by path inside it, SKILL.md among them, e.g. {\"SKILL.md\": \"...\", \"scripts/run.sh\": \"#!/bin/sh ...\"}"}
+		case KindHook:
+			input["event"] = str("PreToolUse, PostToolUse, UserPromptSubmit, Notification, Stop, SubagentStop, SessionStart, SessionEnd or PreCompact")
+			input["matcher"] = str("for tool events, which tools, e.g. Bash or Edit|Write; absent is every one")
+			input["command"] = str("the shell command; ${HOOK_DIR} is the directory of the files given, e.g. ${HOOK_DIR}/check.sh")
+			input["files"] = map[string]any{"type": "object", "description": "the scripts the command runs, by path, e.g. {\"check.sh\": \"#!/bin/sh ...\"}"}
+		default:
+			input["content"] = str("the file's content, front matter included")
+		}
+		out = append(out,
+			stdio.Tool{Name: "claude_code_" + k.tool + "_list",
+				Description: "Every " + k.kind + " registered for Claude Code on the mesh, by key (`mesh.…` every node, `node.<node>.…` one node, `home.<node>.…` an account's own directory), with who registered it and its files. Lands in " + k.lands + ".",
+				Run:         func(map[string]any) (any, error) { return List(state, k.kind) }},
+			stdio.Tool{Name: "claude_code_" + k.tool + "_register",
+				Description: "Register " + k.what + ", for every node (scope mesh, the default), some nodes (node) or an account's own directory (home). Kept on the bus: a node that joins later takes it too. Lands in " + k.lands + "; a new session takes it, a running one at /reload-plugins. Refused above 256 KiB, or at home where the person already has one of that name.",
+				Input:       input,
+				Run: func(a map[string]any) (any, error) {
+					name := strArg(a, "name")
+					files, err := filesOf(k.kind, name, a)
+					if err != nil {
+						return nil, err
+					}
+					it := Item{Kind: k.kind, Name: name, Scope: scopeOf(a), Files: files,
+						Event: strArg(a, "event"), Matcher: strArg(a, "matcher"), Command: strArg(a, "command")}
+					nodes, err := targetNodes(a)
+					if err != nil {
+						return nil, err
+					}
+					return Register(p, it, nodes, false, state, view, writeManaged)
+				}},
+			stdio.Tool{Name: "claude_code_" + k.tool + "_unregister",
+				Description: "Remove a " + k.kind + " registered through this module, at its scope. At home, only what the mesh placed is removed, and not if it was changed by hand since.",
+				Input:       map[string]any{"name": str("the name"), "scope": scopeArg, "nodes": nodesArg},
+				Run: func(a map[string]any) (any, error) {
+					it := Item{Kind: k.kind, Name: strArg(a, "name"), Scope: scopeOf(a)}
+					nodes, err := targetNodes(a)
+					if err != nil {
+						return nil, err
+					}
+					return Register(p, it, nodes, true, state, view, writeManaged)
+				}},
+		)
+	}
+
+	settingsScope := str(`mesh (every node; the default) or node (the nodes given, or this one)`)
+	out = append(out,
+		stdio.Tool{Name: "claude_code_settings_get",
+			Description: "Claude Code's managed settings on this node as written, and where each part came from: the operator's `managed_settings` setting (ADR 0213), the settings registered for the mesh and for this node, and the mesh's own keys, which always win.",
+			Run: func(map[string]any) (any, error) {
+				written := map[string]any{}
+				_ = readJSON(filepath.Join(ManagedDir, "managed-settings.json"), &written)
+				var settings Settings
+				_ = readJSON(p.Settings, &settings)
+				c := ConfigOf(view.Items())
+				layers := map[string]any{"managed_settings setting": settings.ManagedSettings}
+				for _, it := range c.Mesh {
+					if it.Kind == KindSettings {
+						layers["registered for the mesh"] = it.Settings
+					}
+				}
+				for _, it := range c.Node {
+					if it.Kind == KindSettings {
+						layers["registered for this node"] = it.Settings
+					}
+				}
+				return map[string]any{"written": written, "layers": layers,
+					"order": "managed_settings setting, then mesh, then node — objects merged, lists joined — then the mesh's own keys"}, nil
+			}},
+		stdio.Tool{Name: "claude_code_settings_set",
+			Description: "Set Claude Code settings (the vendor's settings keys: permissions, autoMode, env, model, hooks, statusLine, …) for every node or some. Merged into what that scope holds — objects key by key, lists joined — unless replace is set. The mesh's own keys (attribution, the connectors key, the key-helper, the plugin's marketplace) cannot be set. The agent refuses to loosen its own settings: this is the operator's act.",
+			Input: map[string]any{
+				"settings": map[string]any{"type": "object", "description": "settings keys, e.g. {\"permissions\": {\"deny\": [\"Bash(rm -rf:*)\"]}}"},
+				"replace":  map[string]any{"type": "boolean", "description": "replace what the scope holds instead of merging into it"},
+				"scope":    settingsScope, "nodes": nodesArg,
+			},
+			Run: func(a map[string]any) (any, error) {
+				given, _ := a["settings"].(map[string]any)
+				if len(given) == 0 {
+					return nil, errors.New("no settings given; to remove a scope's settings, claude_code_settings_clear")
+				}
+				nodes, err := targetNodes(a)
+				if err != nil {
+					return nil, err
+				}
+				return SetSettings(p, scopeOf(a), nodes, func(held map[string]any) map[string]any {
+					if boolArg(a, "replace") {
+						return given
+					}
+					return mergeSettings(held, given)
+				}, state, view)
+			}},
+		stdio.Tool{Name: "claude_code_settings_clear",
+			Description: "Remove the Claude Code settings registered at a scope.",
+			Input:       map[string]any{"scope": settingsScope, "nodes": nodesArg},
+			Run: func(a map[string]any) (any, error) {
+				it := Item{Kind: KindSettings, Name: SettingsName, Scope: scopeOf(a)}
+				nodes, err := targetNodes(a)
+				if err != nil {
+					return nil, err
+				}
+				return Register(p, it, nodes, true, state, view, writeManaged)
+			}},
+		stdio.Tool{Name: "claude_code_permission_add",
+			Description: "Add a permission rule to Claude Code's managed settings, for every node or some: allow (runs without asking), ask (always asks) or deny (never runs). A rule is a tool and an optional specifier, e.g. Bash(git status:*), Read(./secrets/**), mcp__mesh__mesh_call.",
+			Input:       map[string]any{"list": str("allow, ask or deny"), "rule": str("the rule"), "scope": settingsScope, "nodes": nodesArg},
+			Run: func(a map[string]any) (any, error) {
+				list, rule := strArg(a, "list"), strArg(a, "rule")
+				if (list != "allow" && list != "ask" && list != "deny") || rule == "" {
+					return nil, errors.New("list is allow, ask or deny, and a rule is needed")
+				}
+				nodes, err := targetNodes(a)
+				if err != nil {
+					return nil, err
+				}
+				return SetSettings(p, scopeOf(a), nodes, func(held map[string]any) map[string]any {
+					return mergeSettings(held, map[string]any{"permissions": map[string]any{list: []any{rule}}})
+				}, state, view)
+			}},
+		stdio.Tool{Name: "claude_code_permission_remove",
+			Description: "Remove a permission rule added through this module, at its scope.",
+			Input:       map[string]any{"list": str("allow, ask or deny"), "rule": str("the rule"), "scope": settingsScope, "nodes": nodesArg},
+			Run: func(a map[string]any) (any, error) {
+				list, rule := strArg(a, "list"), strArg(a, "rule")
+				nodes, err := targetNodes(a)
+				if err != nil {
+					return nil, err
+				}
+				return SetSettings(p, scopeOf(a), nodes, func(held map[string]any) map[string]any {
+					perms, _ := held["permissions"].(map[string]any)
+					rules, _ := perms[list].([]any)
+					if len(rules) == 0 {
+						return held // nothing to remove: what the scope holds stays as it is
+					}
+					kept := []any{}
+					for _, r := range rules {
+						if r != rule {
+							kept = append(kept, r)
+						}
+					}
+					next := mergeSettings(map[string]any{}, held)
+					np := mergeSettings(map[string]any{}, perms)
+					np[list] = kept
+					next["permissions"] = np
+					return next
+				}, state, view)
+			}},
+		stdio.Tool{Name: "claude_code_config_list",
+			Description: "Everything registered for Claude Code on the mesh through this module — skills, subagents, commands, hooks, output styles, instruction sections, settings — by key, with who registered each and its files.",
+			Run:         func(map[string]any) (any, error) { return List(state, "") }},
+		stdio.Tool{Name: "claude_code_config_show",
+			Description: "One registration in full, its files' content included, by its key as a list shows it (e.g. mesh.skill.review).",
+			Input:       map[string]any{"key": str("the key")},
+			Run:         func(a map[string]any) (any, error) { return Show(state, strArg(a, "key")) }},
+		stdio.Tool{Name: "claude_code_config_status",
+			Description: "Claude Code's configuration on this node: what was registered and applies here (mesh, node, home), the plugin as written, and the home's own skills, subagents, commands, output styles and rule files — which the mesh placed, which share a name with a mesh item, and which call tools of a tool server not loaded here (stale).",
+			Run: func(map[string]any) (any, error) {
+				c := ConfigOf(view.Items())
+				names := func(items []Item) []string {
+					out := []string{}
+					for _, it := range items {
+						out = append(out, it.Kind+" "+it.Name)
+					}
+					return out
+				}
+				var mcp struct {
+					MCPServers Servers `json:"mcpServers"`
+				}
+				_ = readJSON(filepath.Join(ManagedDir, "managed-mcp.json"), &mcp)
+				var placed Placed
+				_ = readJSON(p.placed(), &placed)
+				plugin := []string{}
+				root := filepath.Join(ManagedDir, MarketplaceDir, "plugins", Plugin)
+				_ = filepath.WalkDir(root, func(full string, d os.DirEntry, err error) error {
+					if err == nil && !d.IsDir() {
+						rel, _ := filepath.Rel(root, full)
+						plugin = append(plugin, rel)
+					}
+					return nil
+				})
+				return map[string]any{
+					"applies here": map[string]any{"mesh": names(c.Mesh), "node": names(c.Node), "home": names(c.Home)},
+					"plugin":       map[string]any{"name": Plugin, "files": plugin},
+					"home":         HomeItems(p, c, mcp.MCPServers),
+					"placed":       placed,
+				}, nil
+			}},
+		stdio.Tool{Name: "claude_code_config_import",
+			Description: "Register an item found in this node's own ~/.claude — a skill, subagent, command, output style, or a rule file as instructions — at the scope given, so something written by hand on one machine reaches every node, some, or stays at home under the mesh's care. The original is left where it is: removing it is the person's act.",
+			Input: map[string]any{
+				"kind":  str("skill, agent, command, output-style or instructions (a rule file)"),
+				"name":  str("its name in the home: the skill's folder, or the file without .md"),
+				"scope": scopeArg, "nodes": nodesArg,
+			},
+			Run: func(a map[string]any) (any, error) {
+				it, err := ImportFromHome(p, strArg(a, "kind"), strArg(a, "name"))
+				if err != nil {
+					return nil, err
+				}
+				it.Scope = scopeOf(a)
+				if it.Scope == ScopeHome {
+					return nil, errors.New("it is already at home; import it to the mesh or node scope")
+				}
+				nodes, err := targetNodes(a)
+				if err != nil {
+					return nil, err
+				}
+				return Register(p, it, nodes, false, state, view, writeManaged)
+			}},
+	)
+	return out
+}
+
+// SetSettings changes the settings registered at a scope, one key per node, by what change makes of what
+// the key holds. An empty result removes the key.
+func SetSettings(p Paths, scope string, nodes []string, change func(held map[string]any) map[string]any,
+	state ConfigState, view *ConfigView) (map[string]any, error) {
+	if scope != ScopeMesh && scope != ScopeNode {
+		return map[string]any{"set": false, "reason": "settings take the mesh and node scopes only"}, nil
+	}
+	if scope == ScopeMesh {
+		nodes = []string{""}
+	} else if len(nodes) == 0 {
+		nodes = []string{p.Node}
+	} else if problem := nodesProblem(nodes); problem != "" {
+		return map[string]any{"set": false, "reason": problem}, nil
+	}
+	answers := map[string]any{}
+	for _, n := range nodes {
+		it := Item{Kind: KindSettings, Name: SettingsName, Scope: scope}
+		held := map[string]any{}
+		if raw, found, err := state.Get(it.Key(n)); err != nil {
+			return nil, err
+		} else if found {
+			var was Item
+			if json.Unmarshal(raw, &was) == nil && was.Settings != nil {
+				held = was.Settings
+			}
+		}
+		it.Settings = change(held)
+		target := []string(nil)
+		if n != "" {
+			target = []string{n}
+		}
+		var answer map[string]any
+		var err error
+		if len(it.Settings) == 0 {
+			answer, err = Register(p, it, target, true, state, view, writeManaged)
+		} else {
+			answer, err = Register(p, it, target, false, state, view, writeManaged)
+		}
+		if err != nil {
+			return nil, err
+		}
+		answer["settings"] = it.Settings
+		answers[it.Key(n)] = answer
+	}
+	return answers, nil
+}

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

@@ -30,6 +30,9 @@ func say(format string, args ...any) {
 // 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) {
+	if strings.HasSuffix(name, "/") {
+		return writeManagedTree(strings.TrimSuffix(name, "/"), content)
+	}
 	path := filepath.Join(ManagedDir, name)
 	if was, err := os.ReadFile(path); err == nil && string(was) == content {
 		return name + ": unchanged", nil
@@ -54,6 +57,74 @@ func writeManaged(name, content string) (string, error) {
 	return name + ": written", nil
 }
 
+// writeManagedTree replaces one directory of the managed directory whole — the plugin's marketplace (ADR
+// 0216) — when what it holds differs from the files given (a JSON map of path to PluginFile). Staged
+// beside, then swapped in as root, so a session never reads half of it.
+func writeManagedTree(name, content string) (string, error) {
+	var files map[string]PluginFile
+	if err := json.Unmarshal([]byte(content), &files); err != nil {
+		return "", err
+	}
+	target := filepath.Join(ManagedDir, name)
+	if sameTree(target, files) {
+		return name + "/: unchanged", nil
+	}
+	staged, err := os.MkdirTemp("", "claude-code-tree-")
+	if err != nil {
+		return "", err
+	}
+	defer os.RemoveAll(staged)
+	for rel, f := range files {
+		full := filepath.Join(staged, filepath.FromSlash(rel))
+		if err := os.MkdirAll(filepath.Dir(full), 0o755); err != nil {
+			return "", err
+		}
+		mode := os.FileMode(0o644)
+		if f.Executable {
+			mode = 0o755
+		}
+		if err := os.WriteFile(full, []byte(f.Content), mode); err != nil {
+			return "", err
+		}
+		_ = os.Chmod(full, mode)
+	}
+	_ = os.Chmod(staged, 0o755)
+	script := `set -e; rm -rf "$2.next" "$2.old"; cp -r "$1" "$2.next"; chown -R root:root "$2.next"; chmod -R go-w,a+rX "$2.next";
+if [ -d "$2" ]; then mv "$2" "$2.old"; fi; mv "$2.next" "$2"; rm -rf "$2.old"`
+	args := []string{"sh", "-c", script, "sh", staged, target}
+	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 fmt.Sprintf("%s/: written, %d file(s)", name, len(files)), nil
+}
+
+// sameTree says whether a directory holds exactly these files, with these contents and executable bits.
+func sameTree(dir string, files map[string]PluginFile) bool {
+	found := 0
+	err := filepath.WalkDir(dir, func(full string, d os.DirEntry, err error) error {
+		if err != nil || d.IsDir() {
+			return err
+		}
+		rel, _ := filepath.Rel(dir, full)
+		f, ok := files[filepath.ToSlash(rel)]
+		if !ok {
+			return errors.New("not wanted")
+		}
+		raw, err := os.ReadFile(full)
+		info, ierr := d.Info()
+		if err != nil || ierr != nil || string(raw) != f.Content || (info.Mode()&0o111 != 0) != f.Executable {
+			return errors.New("differs")
+		}
+		found++
+		return nil
+	})
+	return err == nil && found == len(files)
+}
+
 // 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) }
 
@@ -63,6 +134,13 @@ 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() }
+func (s stateOf) Get(key string) (json.RawMessage, bool, error) {
+	e, err := s.s.Get(key)
+	if err != nil || e == nil {
+		return nil, false, err
+	}
+	return e.Value, true, nil
+}
 
 // nodesRunningMe is the nodes claude-code runs on, from the controller's list of modules — for the register
 // tool's question.
@@ -152,9 +230,9 @@ func nodesOf(v any) []string {
 	return out
 }
 
-func tools(p Paths, servers ServerState, view *ServerView) []stdio.Tool {
+func tools(p Paths, servers ServerState, view *ServerView, config ConfigState, configView *ConfigView) []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{
+	out := []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 }},
@@ -239,6 +317,7 @@ func tools(p Paths, servers ServerState, view *ServerView) []stdio.Tool {
 				return RegisterServer(p, Registration{Name: name, Nodes: nodesOf(a["nodes"])}, servers, view, writeManaged, nodesRunningMe)
 			}},
 	}
+	return append(out, configTools(p, config, configView)...)
 }
 
 // persist asks the state again until it answers: its bucket or the bus's grant may arrive after the module.
@@ -283,15 +362,53 @@ func main() {
 	}
 	servers := stateOf{stdio.State("servers")}
 	view := NewServerView(p)
-	go run(p, view)
-	if err := stdio.Serve("", tools(p, servers, view)); err != nil {
+	config := stateOf{stdio.State("config")}
+	configView := NewConfigView(p)
+	go run(p, view, configView)
+	if err := stdio.Serve("", tools(p, servers, view, config, configView)); 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) {
+func run(p Paths, view *ServerView, configView *ConfigView) {
+	// The agent's configuration, at every scope (ADR 0216): the whole current set first, then each change.
+	go persist("watching the agent's configuration", func() error {
+		keys, err := stdio.State("config").Keys()
+		if err != nil {
+			return err
+		}
+		if configView.Prune(keys) {
+			if _, err := RenderNow(p, writeManaged); err != nil {
+				say("rendering after what was removed while away: %v", err)
+			}
+		}
+		return stdio.State("config").Watch("", func(c stdio.StateChange) error {
+			var item *Item
+			if c.Op == "put" {
+				item = &Item{}
+				if json.Unmarshal(c.Value, item) != nil {
+					item = nil
+				}
+			}
+			if !configView.Take(c.Key, c.Op, item) {
+				return nil
+			}
+			if out, err := RenderNow(p, writeManaged); err != nil {
+				say("taking %s %s: %v", c.Op, c.Key, err)
+			} else {
+				say("took %s %s", c.Op, c.Key)
+				for _, line := range out {
+					if !strings.HasSuffix(line, "unchanged") {
+						say("%s", line)
+					}
+				}
+			}
+			return nil
+		})
+	}, func(n int) { say("watching the agent's configuration%s", refusals(n)) })
+
 	// 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 {

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

@@ -62,6 +62,8 @@ func (p Paths) binding() string     { return filepath.Join(p.State, "licence.jso
 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") }
+func (p Paths) config() string      { return filepath.Join(p.State, "config.json") }
+func (p Paths) placed() string      { return filepath.Join(p.State, "home-placed.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)
@@ -102,9 +104,15 @@ func Registered(p Paths) Servers {
 	return s
 }
 
+var renderMu sync.Mutex
+
 // 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) {
+	// One at a time: the watches and the tools all render, and the home's record of what was placed is
+	// read and written whole.
+	renderMu.Lock()
+	defer renderMu.Unlock()
 	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)
@@ -116,21 +124,44 @@ func RenderNow(p Paths, write WriteManaged) ([]string, error) {
 	if readJSON(p.binding(), &b) {
 		binding = &b
 	}
-	files := Render(facts, settings, binding, p.helper(), Registered(p))
+	var items map[string]Item
+	_ = readJSON(p.config(), &items)
+	config := ConfigOf(items)
+	files := Render(facts, settings, binding, p.helper(), Registered(p), config)
+	tree, _ := json.Marshal(Marketplace(config))
+	files[MarketplaceDir+"/"] = string(tree)
 	names := make([]string, 0, len(files))
 	for n := range files {
 		names = append(names, n)
 	}
-	sort.Strings(names)
+	// The marketplace first: the settings that enable its plugin must never name one that is not there yet.
+	sort.Slice(names, func(i, j int) bool {
+		if (names[i] == MarketplaceDir+"/") != (names[j] == MarketplaceDir+"/") {
+			return names[i] == MarketplaceDir+"/"
+		}
+		return names[i] < names[j]
+	})
+	// Every file is attempted: one that cannot be written — a registration the vendor's layout refuses, a
+	// failed escalation — must not keep the licence, the tool servers or the instructions from landing.
 	var out []string
+	var failed []error
 	for _, n := range names {
 		line, err := write(n, files[n])
 		if err != nil {
-			return out, err
+			failed = append(failed, err)
+			continue
 		}
 		out = append(out, line)
 	}
-	return out, nil
+	// The home scope: what this module places in the account's own agent directory (ADR 0182).
+	done, left := PlaceHome(p, HomeFiles(config))
+	for _, line := range done {
+		out = append(out, "home "+line)
+	}
+	for _, line := range left {
+		out = append(out, "home "+line)
+	}
+	return out, errors.Join(failed...)
 }
 
 // ---- the licence ----------------------------------------------------------------------------------

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

@@ -96,8 +96,10 @@ func jsonFile(v any) 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 {
+// here — is laid over the servers the operator set in its settings; config is the rest of what was
+// registered (ADR 0216): its settings laid over the operator's `managed_settings`, its instruction sections
+// after the mesh's own text. The plugin itself is Marketplace's, and the home's PlaceHome's.
+func Render(facts Facts, settings Settings, binding *Binding, helperPath string, registered Servers, config Config) map[string]string {
 	servers := map[string]any{}
 	for _, layer := range []map[string]map[string]any{settings.MCPServers, registered} {
 		for name, entry := range layer {
@@ -109,14 +111,27 @@ func Render(facts Facts, settings Settings, binding *Binding, helperPath string,
 	}
 	servers[meshEntry] = map[string]any{"type": "http", "url": facts.Console}
 
-	managed := map[string]any{}
-	for key, value := range settings.ManagedSettings {
-		managed[key] = value
-	}
+	// The operator's `managed_settings` (ADR 0213), then what was registered for the mesh, then for this node.
+	managed := mergeSettings(map[string]any{}, settings.ManagedSettings)
+	managed = mergeSettings(managed, RegisteredSettings(config))
 	// The mesh's own keys are laid last: a setting never replaces them.
 	managed["attribution"] = map[string]any{"commit": "", "pr": ""}
 	managed["allowAllClaudeAiMcps"] = true
 	delete(managed, "apiKeyHelper")
+	// The plugin's marketplace and the plugin itself, as entries in the operator's own maps, the mesh's
+	// entry winning: the operator may know more marketplaces and enable more plugins.
+	for key, value := range MarketplaceKeys() {
+		entries := map[string]any{}
+		if held, ok := managed[key].(map[string]any); ok {
+			for k, v := range held {
+				entries[k] = v
+			}
+		}
+		for k, v := range value.(map[string]any) {
+			entries[k] = v
+		}
+		managed[key] = entries
+	}
 	if binding != nil && binding.Kind == "api-key" {
 		managed["apiKeyHelper"] = helperPath
 	}
@@ -127,6 +142,6 @@ func Render(facts Facts, settings Settings, binding *Binding, helperPath string,
 	return map[string]string{
 		"managed-mcp.json":      jsonFile(map[string]any{"mcpServers": servers}),
 		"managed-settings.json": jsonFile(managed),
-		"CLAUDE.md":             instructionsText(facts.Node, role),
+		"CLAUDE.md":             instructionsText(facts.Node, role) + InstructionSections(config),
 	}
 }

modules/claude-code/module.json

@@ -13,7 +13,8 @@
   },
   "state": [
     "servers",
-    "holdings"
+    "holdings",
+    "config"
   ],
   "reads": [
     "claude-licence-manager.bindings"
@@ -26,7 +27,34 @@
     "claude_code_add_api_key",
     "claude_code_mcp_list",
     "claude_code_mcp_register",
-    "claude_code_mcp_unregister"
+    "claude_code_mcp_unregister",
+    "claude_code_skill_list",
+    "claude_code_skill_register",
+    "claude_code_skill_unregister",
+    "claude_code_agent_list",
+    "claude_code_agent_register",
+    "claude_code_agent_unregister",
+    "claude_code_command_list",
+    "claude_code_command_register",
+    "claude_code_command_unregister",
+    "claude_code_hook_list",
+    "claude_code_hook_register",
+    "claude_code_hook_unregister",
+    "claude_code_output_style_list",
+    "claude_code_output_style_register",
+    "claude_code_output_style_unregister",
+    "claude_code_instructions_list",
+    "claude_code_instructions_register",
+    "claude_code_instructions_unregister",
+    "claude_code_settings_get",
+    "claude_code_settings_set",
+    "claude_code_settings_clear",
+    "claude_code_permission_add",
+    "claude_code_permission_remove",
+    "claude_code_config_list",
+    "claude_code_config_show",
+    "claude_code_config_status",
+    "claude_code_config_import"
   ],
   "resources": [
     {

modules/distribution/module.json

@@ -63,6 +63,23 @@
       "env": {
         "REGISTRY_STORAGE_DELETE_ENABLED": "true"
       }
+    },
+    {
+      "id": "collect",
+      "type": "container",
+      "name": "mesh-registry-collect",
+      "image": "registry@sha256:a3d8aaa63ed8681a604f1dea0aa03f100d5895b6a58ace528858a7b332415373",
+      "volumes": [
+        "/var/lib/mesh-registry:/var/lib/registry"
+      ],
+      "args": [
+        "garbage-collect",
+        "/etc/docker/registry/config.yml"
+      ],
+      "schedule": "30 3 * * *",
+      "while-stopped": [
+        "store"
+      ]
     }
   ]
 }

modules/fail2ban/client.ts

@@ -1,236 +0,0 @@
-// fail2ban's own code, in the module (novox/hq ADR 0039). The jails are composed by the mesh from
-// the modules a machine runs (to-be 31) and written as declared resources; the daemon is kept
-// running by one. This code exists only to read and steer the *live* state the daemon owns: who is
-// banned now and until when, and the ban or release an operator asks for — the node-intrusion-
-// prevention seat's four verbs (ADR 0179). The daemon's state is fail2ban's, not the mesh's: the
-// mesh composes the jails and never writes the ban list.
-//
-// Spoken through fail2ban-client over the daemon's socket. Client and daemon come from the one
-// package this module declares on the machine, and the socket is root's: root is the module's
-// concern (ADR 0175 §4), and the runtime loading this bundle runs as the operator's account (to-be
-// 38 WP4), so the client is run through sudo without a prompt where the account is not root.
-
-import { execFile } from "node:child_process";
-import { accessSync, constants } from "node:fs";
-import { isIP } from "node:net";
-import { delimiter, join } from "node:path";
-import { promisify } from "node:util";
-
-const execFileP = promisify(execFile);
-
-/** A command runner, so the verbs can be tested without a daemon. */
-export type Runner = (cmd: string, args: string[]) => Promise<string>;
-
-/** The command as it is run: as given when this process is root, else through sudo without a
- *  prompt. The daemon's socket answers only to root. */
-export function escalated(cmd: string, args: string[], uid: number | undefined = process.getuid?.()): [string, string[]] {
-  if (uid === 0) return [cmd, args];
-  return ["sudo", ["-n", cmd, ...args]];
-}
-
-/** Whether a tool is on this machine: an executable of that name on the path, or where the
- *  system keeps its administration. */
-export function installed(tool: string, path: string = process.env.PATH ?? ""): boolean {
-  const dirs = [...path.split(delimiter), "/usr/sbin", "/sbin", "/usr/bin"].filter((d) => d !== "");
-  return dirs.some((dir) => {
-    try {
-      accessSync(join(dir, tool), constants.X_OK);
-      return true;
-    } catch {
-      return false;
-    }
-  });
-}
-
-export const execRunner: Runner = async (cmd, args) => {
-  if (!installed(cmd)) throw new Error(`${cmd} is not installed on this machine`);
-  const [program, argv] = escalated(cmd, args);
-  try {
-    const { stdout } = await execFileP(program, argv, { maxBuffer: 16 * 1024 * 1024 });
-    return stdout;
-  } catch (err) {
-    const e = err as { code?: string | number; stderr?: string; stdout?: string; message?: string };
-    const said = `${e.stdout ?? ""}${e.stderr ?? ""}`.trim();
-    // What failed is named by how it failed: sudo missing is a spawn error, sudo refusing speaks
-    // on its own stderr line, and the rest is the client's own answer.
-    if (program === "sudo") {
-      if (e.code === "ENOENT") throw new Error(`${cmd} needs root, and sudo is not installed here for the runtime's account to escalate with`);
-      if (/^sudo:/m.test(said)) throw new Error(`${cmd} needs root and the runtime's account may not run it without a prompt: ${said}`);
-    }
-    if (/Failed to access socket path|Is fail2ban running|Permission denied to socket/i.test(said)) {
-      throw new Error("fail2ban is not running on this machine, or its socket does not answer the runtime's account");
-    }
-    // fail2ban-client's own last line is the one a person reads ("Sorry but the jail 'x' does not exist").
-    const lines = said.split("\n").map((l) => l.trim()).filter(Boolean);
-    throw new Error(lines.length ? lines[lines.length - 1] : (e.message ?? `${cmd} failed`));
-  }
-};
-
-/** One jail as the daemon reports it. */
-export interface JailStatus {
-  jail: string;
-  /** What the jail is reading: files or journal matches, as fail2ban names them. */
-  watching: string[];
-  /** Addresses with failures counted against them right now, and all failures since the jail started. */
-  failing: { now: number; total: number };
-  /** Addresses held right now, and all bans since the jail started. */
-  banned: { now: number; total: number; addresses: string[] };
-}
-
-/** One ban as the daemon holds it. */
-export interface Ban {
-  ip: string;
-  jail: string;
-  /** When the ban was placed, in the machine's local time as fail2ban prints it. */
-  since: string;
-  /** When the ban ends; "never" for a permanent ban. */
-  until: string;
-}
-
-export interface JailSettings {
-  jail: string;
-  bantime: string;
-  findtime: string;
-  maxretry: number;
-  ignoreip: string[];
-  actions: string[];
-  /** The log files the jail reads, when it reads files. */
-  logpath: string[];
-  /** The journal match the jail reads, when it reads the journal. */
-  journalmatch: string;
-}
-
-export class Fail2banClient {
-  private readonly run: Runner;
-
-  constructor(run: Runner = execRunner) {
-    this.run = run;
-  }
-
-  /** The daemon as this machine has it, through its own client. */
-  static onThisMachine(): Fail2banClient {
-    return new Fail2banClient();
-  }
-
-  private client(...args: string[]): Promise<string> {
-    return this.run("fail2ban-client", args);
-  }
-
-  /** The jails the daemon runs, by name. */
-  async jails(): Promise<string[]> {
-    const out = await this.client("status");
-    const m = out.match(/Jail list:\s*(.*)/);
-    if (!m) return [];
-    return m[1].split(",").map((j) => j.trim()).filter(Boolean);
-  }
-
-  /** Every jail with what it watches and holds, or one jail's detail. */
-  async status(jail?: string): Promise<{ jails: JailStatus[] }> {
-    const names = jail ? [jail] : await this.jails();
-    const jails: JailStatus[] = [];
-    for (const name of names) {
-      jails.push(parseJailStatus(name, await this.client("status", name)));
-    }
-    return { jails };
-  }
-
-  /** Every address banned now, with the jail holding it and when the ban ends. */
-  async banned(jail?: string): Promise<{ banned: Ban[] }> {
-    const names = jail ? [jail] : await this.jails();
-    const banned: Ban[] = [];
-    for (const name of names) {
-      banned.push(...parseBans(name, await this.client("get", name, "banip", "--with-time")));
-    }
-    banned.sort((a, b) => a.until.localeCompare(b.until) || a.ip.localeCompare(b.ip));
-    return { banned };
-  }
-
-  /** Ban one address in one jail now. The daemon's own answer is how many addresses it added. */
-  async ban(ip: string, jail: string): Promise<{ banned: Ban | null; added: number }> {
-    address(ip);
-    name(jail);
-    const out = await this.client("set", jail, "banip", ip);
-    const added = Number.parseInt(out.trim(), 10) || 0;
-    const held = (await this.banned(jail)).banned.find((b) => b.ip === ip) ?? null;
-    return { banned: held, added };
-  }
-
-  /** Let one address go, from one jail or from every jail. The daemon's answer is how many it released. */
-  async unban(ip: string, jail?: string): Promise<{ released: number; ip: string; jail: string | "every jail" }> {
-    address(ip);
-    let out: string;
-    if (jail) {
-      name(jail);
-      out = await this.client("set", jail, "unbanip", ip);
-    } else {
-      out = await this.client("unban", ip);
-    }
-    return { released: Number.parseInt(out.trim(), 10) || 0, ip, jail: jail ?? "every jail" };
-  }
-
-  /** One jail's effective settings — the module's own tool, beside the seat's verbs. */
-  async settings(jail: string): Promise<JailSettings> {
-    name(jail);
-    const get = (key: string) => this.client("get", jail, key);
-    const [bantime, findtime, maxretry, ignoreip, actions, logpath, journalmatch] = await Promise.all([
-      get("bantime"), get("findtime"), get("maxretry"), get("ignoreip"), get("actions"), get("logpath"),
-      get("journalmatch"),
-    ]);
-    return {
-      jail,
-      bantime: bantime.trim(),
-      findtime: findtime.trim(),
-      maxretry: Number.parseInt(maxretry.trim(), 10),
-      ignoreip: listed(ignoreip),
-      actions: actions.split("\n").slice(1).map((l) => l.trim()).filter(Boolean),
-      logpath: /No file is currently monitored/.test(logpath) ? [] : listed(logpath),
-      journalmatch: journalmatch.split("\n").slice(1).map((l) => l.trim()).filter(Boolean).join(" "),
-    };
-  }
-}
-
-/** fail2ban's tree listings: lines like "|- 127.0.0.0/8" and "`- ::1", after a heading. */
-function listed(out: string): string[] {
-  return out
-    .split("\n")
-    .map((l) => l.replace(/^[\s|`-]+/, "").trim())
-    .filter((l, i) => i > 0 && l.length > 0);
-}
-
-export function parseJailStatus(jail: string, out: string): JailStatus {
-  const field = (label: string) => {
-    const m = out.match(new RegExp(label.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + ":\\t?\\s*(.*)"));
-    return m ? m[1].trim() : "";
-  };
-  const num = (label: string) => Number.parseInt(field(label), 10) || 0;
-  const watching = [field("File list"), field("Journal matches")].filter(Boolean);
-  return {
-    jail,
-    watching,
-    failing: { now: num("Currently failed"), total: num("Total failed") },
-    banned: {
-      now: num("Currently banned"),
-      total: num("Total banned"),
-      addresses: field("Banned IP list").split(/\s+/).filter(Boolean),
-    },
-  };
-}
-
-/** `get <jail> banip --with-time` prints one ban per line: "IP \tsince + seconds = until". */
-export function parseBans(jail: string, out: string): Ban[] {
-  const bans: Ban[] = [];
-  for (const line of out.split("\n")) {
-    const m = line.match(/^(\S+)\s+(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}) \+ (-?\d+) = (\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}|\S+)/);
-    if (!m) continue;
-    bans.push({ ip: m[1], jail, since: m[2], until: Number(m[3]) < 0 ? "never" : m[4] });
-  }
-  return bans;
-}
-
-function address(ip: string): void {
-  if (!isIP(ip)) throw new Error(`${JSON.stringify(ip)} is not an address`);
-}
-
-function name(jail: string): void {
-  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(jail)) throw new Error(`${JSON.stringify(jail)} is not a jail's name`);
-}

modules/fail2ban/cmd/fail2ban-tools/client.go

@@ -0,0 +1,407 @@
+// fail2ban's own code, in the module (novox/hq ADR 0039). The jails are composed by the mesh from the
+// modules a machine runs (to-be 31) and written as declared resources; the daemon is kept running by
+// one. This code exists only to read and steer the *live* state the daemon owns: who is banned now
+// and until when, and the ban or release an operator asks for — the node-intrusion-prevention seat's
+// four verbs (ADR 0179). The daemon's state is fail2ban's, not the mesh's: the mesh composes the
+// jails and never writes the ban list.
+//
+// Spoken through fail2ban-client over the daemon's socket. Client and daemon come from the one
+// package this module declares on the machine, and the socket is root's: root is the module's
+// concern (ADR 0175 §4), and the runtime launching this binary runs as the operator's account (to-be
+// 38 WP4), so the client is run through sudo without a prompt where the account is not root.
+package main
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"net"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// Runner runs one command and answers what it printed, so the verbs can be tested without a daemon.
+type Runner func(ctx context.Context, name string, args ...string) (string, error)
+
+// escalated is the command as it is run: as given when this process is root, else through sudo
+// without a prompt. The daemon's socket answers only to root.
+func escalated(uid int, name string, args []string) (string, []string) {
+	if uid == 0 {
+		return name, args
+	}
+	return "sudo", append([]string{"-n", name}, args...)
+}
+
+// installed is whether a tool is on this machine: an executable of that name on the path, or where
+// the system keeps its administration.
+func installed(tool, path string) bool {
+	dirs := append(filepath.SplitList(path), "/usr/sbin", "/sbin", "/usr/bin")
+	for _, dir := range dirs {
+		if dir == "" {
+			continue
+		}
+		if info, err := os.Stat(filepath.Join(dir, tool)); err == nil && !info.IsDir() && info.Mode()&0o111 != 0 {
+			return true
+		}
+	}
+	return false
+}
+
+var socketTrouble = regexp.MustCompile(`(?i)Failed to access socket path|Is fail2ban running|Permission denied to socket`)
+
+func execRunner(ctx context.Context, name string, args ...string) (string, error) {
+	if !installed(name, os.Getenv("PATH")) {
+		return "", fmt.Errorf("%s is not installed on this machine", name)
+	}
+	ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
+	defer cancel()
+	program, argv := escalated(os.Getuid(), name, args)
+	var stdout, stderr bytes.Buffer
+	cmd := exec.CommandContext(ctx, program, argv...)
+	cmd.Stdout, cmd.Stderr = &stdout, &stderr
+	err := cmd.Run()
+	if err == nil {
+		return stdout.String(), nil
+	}
+	said := strings.TrimSpace(stdout.String() + stderr.String())
+	// What failed is named by how it failed: sudo missing is a spawn error, sudo refusing speaks on
+	// its own stderr line, and the rest is the client's own answer.
+	if program == "sudo" {
+		if errors.Is(err, exec.ErrNotFound) {
+			return "", fmt.Errorf("%s needs root, and sudo is not installed here for the runtime's account to escalate with", name)
+		}
+		if regexp.MustCompile(`(?m)^sudo:`).MatchString(said) {
+			return "", fmt.Errorf("%s needs root and the runtime's account may not run it without a prompt: %s", name, said)
+		}
+	}
+	if socketTrouble.MatchString(said) {
+		return "", errors.New("fail2ban is not running on this machine, or its socket does not answer the runtime's account")
+	}
+	// fail2ban-client's own last line is the one a person reads ("Sorry but the jail 'x' does not exist").
+	var lines []string
+	for _, l := range strings.Split(said, "\n") {
+		if l = strings.TrimSpace(l); l != "" {
+			lines = append(lines, l)
+		}
+	}
+	if len(lines) > 0 {
+		return "", errors.New(lines[len(lines)-1])
+	}
+	return "", fmt.Errorf("%s failed: %v", name, err)
+}
+
+// Counted is a jail's count now and since it started.
+type Counted struct {
+	Now   int `json:"now"`
+	Total int `json:"total"`
+}
+
+// Held is what a jail holds: the count now and since it started, and the addresses.
+type Held struct {
+	Now       int      `json:"now"`
+	Total     int      `json:"total"`
+	Addresses []string `json:"addresses"`
+}
+
+// JailStatus is one jail as the daemon reports it.
+type JailStatus struct {
+	Jail string `json:"jail"`
+	// Watching is what the jail is reading: files or journal matches, as fail2ban names them.
+	Watching []string `json:"watching"`
+	// Failing is the addresses with failures counted against them now, and all failures since the
+	// jail started.
+	Failing Counted `json:"failing"`
+	// Banned is the addresses held right now, and all bans since the jail started.
+	Banned Held `json:"banned"`
+}
+
+// Ban is one ban as the daemon holds it.
+type Ban struct {
+	IP   string `json:"ip"`
+	Jail string `json:"jail"`
+	// Since is when the ban was placed, in the machine's local time as fail2ban prints it.
+	Since string `json:"since"`
+	// Until is when the ban ends; "never" for a permanent ban.
+	Until string `json:"until"`
+}
+
+// JailSettings is one jail's effective settings.
+type JailSettings struct {
+	Jail     string   `json:"jail"`
+	Bantime  string   `json:"bantime"`
+	Findtime string   `json:"findtime"`
+	Maxretry int      `json:"maxretry"`
+	Ignoreip []string `json:"ignoreip"`
+	Actions  []string `json:"actions"`
+	Logpath  []string `json:"logpath"`
+	Journal  string   `json:"journalmatch"`
+}
+
+// Fail2ban is the daemon as this machine has it, through its own client.
+type Fail2ban struct {
+	Run Runner
+}
+
+func (f Fail2ban) client(ctx context.Context, args ...string) (string, error) {
+	return f.Run(ctx, "fail2ban-client", args...)
+}
+
+var jailList = regexp.MustCompile(`Jail list:[ \t]*(.*)`)
+
+// Jails is the jails the daemon runs, by name.
+func (f Fail2ban) Jails(ctx context.Context) ([]string, error) {
+	out, err := f.client(ctx, "status")
+	if err != nil {
+		return nil, err
+	}
+	m := jailList.FindStringSubmatch(out)
+	if m == nil {
+		return []string{}, nil
+	}
+	var jails []string
+	for _, j := range strings.Split(m[1], ",") {
+		if j = strings.TrimSpace(j); j != "" {
+			jails = append(jails, j)
+		}
+	}
+	return jails, nil
+}
+
+func (f Fail2ban) named(ctx context.Context, jail string) ([]string, error) {
+	if jail != "" {
+		return []string{jail}, nil
+	}
+	return f.Jails(ctx)
+}
+
+// Status is every jail with what it watches and holds, or one jail's detail.
+func (f Fail2ban) Status(ctx context.Context, jail string) (map[string][]JailStatus, error) {
+	names, err := f.named(ctx, jail)
+	if err != nil {
+		return nil, err
+	}
+	jails := []JailStatus{}
+	for _, name := range names {
+		out, err := f.client(ctx, "status", name)
+		if err != nil {
+			return nil, err
+		}
+		jails = append(jails, parseJailStatus(name, out))
+	}
+	return map[string][]JailStatus{"jails": jails}, nil
+}
+
+// Banned is every address banned now, with the jail holding it and when the ban ends, soonest to
+// end first.
+func (f Fail2ban) Banned(ctx context.Context, jail string) (map[string][]Ban, error) {
+	names, err := f.named(ctx, jail)
+	if err != nil {
+		return nil, err
+	}
+	banned := []Ban{}
+	for _, name := range names {
+		out, err := f.client(ctx, "get", name, "banip", "--with-time")
+		if err != nil {
+			return nil, err
+		}
+		banned = append(banned, parseBans(name, out)...)
+	}
+	sort.SliceStable(banned, func(a, b int) bool {
+		if banned[a].Until != banned[b].Until {
+			return banned[a].Until < banned[b].Until
+		}
+		return banned[a].IP < banned[b].IP
+	})
+	return map[string][]Ban{"banned": banned}, nil
+}
+
+// BanOutcome is a ban as held, and how many addresses the daemon said it added.
+type BanOutcome struct {
+	Banned *Ban `json:"banned"`
+	Added  int  `json:"added"`
+}
+
+// Ban bans one address in one jail now. The daemon's own answer is how many addresses it added.
+func (f Fail2ban) Ban(ctx context.Context, ip, jail string) (*BanOutcome, error) {
+	if err := address(ip); err != nil {
+		return nil, err
+	}
+	if err := jailName(jail); err != nil {
+		return nil, err
+	}
+	out, err := f.client(ctx, "set", jail, "banip", ip)
+	if err != nil {
+		return nil, err
+	}
+	added, _ := strconv.Atoi(strings.TrimSpace(out))
+	held, err := f.Banned(ctx, jail)
+	if err != nil {
+		return nil, err
+	}
+	outcome := &BanOutcome{Added: added}
+	for _, b := range held["banned"] {
+		if b.IP == ip {
+			b := b
+			outcome.Banned = &b
+		}
+	}
+	return outcome, nil
+}
+
+// Released is how many bans the daemon let go, of which address, from where.
+type Released struct {
+	Released int    `json:"released"`
+	IP       string `json:"ip"`
+	Jail     string `json:"jail"`
+}
+
+// Unban lets one address go, from one jail or from every jail. The daemon's answer is how many it
+// released.
+func (f Fail2ban) Unban(ctx context.Context, ip, jail string) (*Released, error) {
+	if err := address(ip); err != nil {
+		return nil, err
+	}
+	var out string
+	var err error
+	if jail != "" {
+		if err := jailName(jail); err != nil {
+			return nil, err
+		}
+		out, err = f.client(ctx, "set", jail, "unbanip", ip)
+	} else {
+		out, err = f.client(ctx, "unban", ip)
+		jail = "every jail"
+	}
+	if err != nil {
+		return nil, err
+	}
+	released, _ := strconv.Atoi(strings.TrimSpace(out))
+	return &Released{Released: released, IP: ip, Jail: jail}, nil
+}
+
+// Settings is one jail's effective settings — the module's own tool, beside the seat's verbs.
+func (f Fail2ban) Settings(ctx context.Context, jail string) (*JailSettings, error) {
+	if err := jailName(jail); err != nil {
+		return nil, err
+	}
+	got := map[string]string{}
+	for _, key := range []string{"bantime", "findtime", "maxretry", "ignoreip", "actions", "logpath", "journalmatch"} {
+		out, err := f.client(ctx, "get", jail, key)
+		if err != nil {
+			return nil, err
+		}
+		got[key] = out
+	}
+	maxretry, _ := strconv.Atoi(strings.TrimSpace(got["maxretry"]))
+	s := &JailSettings{
+		Jail:     jail,
+		Bantime:  strings.TrimSpace(got["bantime"]),
+		Findtime: strings.TrimSpace(got["findtime"]),
+		Maxretry: maxretry,
+		Ignoreip: listed(got["ignoreip"]),
+		Actions:  afterHeading(got["actions"]),
+		Logpath:  []string{},
+		Journal:  strings.Join(afterHeading(got["journalmatch"]), " "),
+	}
+	if !strings.Contains(got["logpath"], "No file is currently monitored") {
+		s.Logpath = listed(got["logpath"])
+	}
+	return s, nil
+}
+
+var treeMarks = regexp.MustCompile("^[\\s|`-]+")
+
+// listed reads fail2ban's tree listings: lines like "|- 127.0.0.0/8" and "`- ::1", after a heading.
+func listed(out string) []string {
+	items := []string{}
+	for i, l := range strings.Split(out, "\n") {
+		l = strings.TrimSpace(treeMarks.ReplaceAllString(l, ""))
+		if i > 0 && l != "" {
+			items = append(items, l)
+		}
+	}
+	return items
+}
+
+// afterHeading is every non-empty line after the first, trimmed.
+func afterHeading(out string) []string {
+	items := []string{}
+	for i, l := range strings.Split(out, "\n") {
+		if l = strings.TrimSpace(l); i > 0 && l != "" {
+			items = append(items, l)
+		}
+	}
+	return items
+}
+
+func parseJailStatus(jail, out string) JailStatus {
+	field := func(label string) string {
+		m := regexp.MustCompile(regexp.QuoteMeta(label) + `:\t?[ \t]*(.*)`).FindStringSubmatch(out)
+		if m == nil {
+			return ""
+		}
+		return strings.TrimSpace(m[1])
+	}
+	num := func(label string) int {
+		n, _ := strconv.Atoi(field(label))
+		return n
+	}
+	watching := []string{}
+	for _, w := range []string{field("File list"), field("Journal matches")} {
+		if w != "" {
+			watching = append(watching, w)
+		}
+	}
+	addresses := strings.Fields(field("Banned IP list"))
+	if addresses == nil {
+		addresses = []string{}
+	}
+	return JailStatus{
+		Jail:     jail,
+		Watching: watching,
+		Failing:  Counted{Now: num("Currently failed"), Total: num("Total failed")},
+		Banned:   Held{Now: num("Currently banned"), Total: num("Total banned"), Addresses: addresses},
+	}
+}
+
+var banLine = regexp.MustCompile(`^(\S+)\s+(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}) \+ (-?\d+) = (\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}|\S+)`)
+
+// parseBans reads `get <jail> banip --with-time`, one ban per line: "IP \tsince + seconds = until".
+func parseBans(jail, out string) []Ban {
+	bans := []Ban{}
+	for _, line := range strings.Split(out, "\n") {
+		m := banLine.FindStringSubmatch(line)
+		if m == nil {
+			continue
+		}
+		until := m[4]
+		if seconds, _ := strconv.Atoi(m[3]); seconds < 0 {
+			until = "never"
+		}
+		bans = append(bans, Ban{IP: m[1], Jail: jail, Since: m[2], Until: until})
+	}
+	return bans
+}
+
+func address(ip string) error {
+	if net.ParseIP(ip) == nil {
+		return fmt.Errorf("%q is not an address", ip)
+	}
+	return nil
+}
+
+var jailNamed = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._-]*$`)
+
+func jailName(jail string) error {
+	if !jailNamed.MatchString(jail) {
+		return fmt.Errorf("%q is not a jail's name", jail)
+	}
+	return nil
+}

modules/fail2ban/cmd/fail2ban-tools/client_test.go

@@ -0,0 +1,226 @@
+package main
+
+// The intrusion prevention's verbs over a fake daemon, with the shapes fail2ban-client 1.1.0 printed
+// on the control node on 2026-10-02 (novox/hq ADR 0179).
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+const statusAll = "Status\n|- Number of jail:\t2\n`- Jail list:\trecidive, sshd\n"
+const recidive = "Status for the jail: recidive\n|- Filter\n|  |- Currently failed:\t36\n|  |- Total failed:\t149\n" +
+	"|  `- File list:\t/var/log/fail2ban.log\n`- Actions\n   |- Currently banned:\t9\n   |- Total banned:\t13\n" +
+	"   `- Banned IP list:\t195.178.110.30 45.148.10.240 92.118.39.71\n"
+const sshd = "Status for the jail: sshd\n|- Filter\n|  |- Currently failed:\t5\n|  |- Total failed:\t11776\n" +
+	"|  `- Journal matches:\t_SYSTEMD_UNIT=sshd.service + _COMM=sshd\n`- Actions\n   |- Currently banned:\t0\n" +
+	"   |- Total banned:\t150\n   `- Banned IP list:\t\n"
+const withTime = "195.178.110.30 \t2026-09-26 23:18:47 + 604800 = 2026-10-03 23:18:47\n" +
+	"92.118.39.71 \t2026-09-28 10:33:49 + 604800 = 2026-10-05 10:33:49\n"
+
+func fake(answers map[string]string, calls *[][]string) Runner {
+	return func(_ context.Context, name string, args ...string) (string, error) {
+		if calls != nil {
+			*calls = append(*calls, append([]string{name}, args...))
+		}
+		if out, ok := answers[strings.Join(args, " ")]; ok {
+			return out, nil
+		}
+		return "", fmt.Errorf("unexpected %s %s", name, strings.Join(args, " "))
+	}
+}
+
+var ctx = context.Background()
+
+func TestAJailsStatusIsReadIntoNumbersWhatItWatchesAndWhoItHolds(t *testing.T) {
+	got := parseJailStatus("recidive", recidive)
+	want := JailStatus{Jail: "recidive", Watching: []string{"/var/log/fail2ban.log"}, Failing: Counted{36, 149},
+		Banned: Held{9, 13, []string{"195.178.110.30", "45.148.10.240", "92.118.39.71"}}}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("%+v", got)
+	}
+	j := parseJailStatus("sshd", sshd)
+	if !reflect.DeepEqual(j.Watching, []string{"_SYSTEMD_UNIT=sshd.service + _COMM=sshd"}) {
+		t.Errorf("watching %v", j.Watching)
+	}
+	if !reflect.DeepEqual(j.Banned, Held{0, 150, []string{}}) {
+		t.Errorf("banned %+v", j.Banned)
+	}
+}
+
+func TestStatusCoversEveryJailTheDaemonListsOrTheOneNamed(t *testing.T) {
+	var calls [][]string
+	f := Fail2ban{Run: fake(map[string]string{"status": statusAll, "status recidive": recidive, "status sshd": sshd}, &calls)}
+	all, err := f.Status(ctx, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(all["jails"]) != 2 || all["jails"][0].Jail != "recidive" || all["jails"][1].Jail != "sshd" {
+		t.Errorf("%+v", all)
+	}
+	one, err := f.Status(ctx, "sshd")
+	if err != nil || len(one["jails"]) != 1 {
+		t.Fatalf("%+v %v", one, err)
+	}
+	if !reflect.DeepEqual(calls[len(calls)-1], []string{"fail2ban-client", "status", "sshd"}) {
+		t.Errorf("last call %v", calls[len(calls)-1])
+	}
+}
+
+func TestBansAreReadWithWhenTheyEndAPermanentOneAsNever(t *testing.T) {
+	bans := parseBans("recidive", withTime+"203.0.113.9 \t2026-10-01 00:00:00 + -1 = never\n")
+	if len(bans) != 3 {
+		t.Fatalf("%+v", bans)
+	}
+	if bans[0] != (Ban{IP: "195.178.110.30", Jail: "recidive", Since: "2026-09-26 23:18:47", Until: "2026-10-03 23:18:47"}) {
+		t.Errorf("%+v", bans[0])
+	}
+	if bans[2].Until != "never" {
+		t.Errorf("a permanent ban ends %q", bans[2].Until)
+	}
+	if got := parseBans("sshd", "\n"); len(got) != 0 {
+		t.Errorf("%+v", got)
+	}
+}
+
+func TestBannedGathersEveryJailsBansSoonestToEndFirst(t *testing.T) {
+	f := Fail2ban{Run: fake(map[string]string{
+		"status":                         statusAll,
+		"get recidive banip --with-time": withTime,
+		"get sshd banip --with-time":     "198.51.100.7 \t2026-10-02 15:06:58 + 600 = 2026-10-02 15:16:58\n",
+	}, nil)}
+	got, err := f.Banned(ctx, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var order []string
+	for _, b := range got["banned"] {
+		order = append(order, b.IP+"@"+b.Jail)
+	}
+	if !reflect.DeepEqual(order, []string{"198.51.100.7@sshd", "195.178.110.30@recidive", "92.118.39.71@recidive"}) {
+		t.Errorf("%v", order)
+	}
+}
+
+func TestBanAsksByJailAndAnswersTheBanAsHeldRefusingANonAddressFirst(t *testing.T) {
+	var calls [][]string
+	f := Fail2ban{Run: fake(map[string]string{
+		"set recidive banip 198.51.100.7": "1\n",
+		"get recidive banip --with-time":  withTime + "198.51.100.7 \t2026-10-02 17:00:00 + 604800 = 2026-10-09 17:00:00\n",
+	}, &calls)}
+	r, err := f.Ban(ctx, "198.51.100.7", "recidive")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if r.Added != 1 || r.Banned == nil || r.Banned.Until != "2026-10-09 17:00:00" {
+		t.Errorf("%+v", r)
+	}
+	if !reflect.DeepEqual(calls[0], []string{"fail2ban-client", "set", "recidive", "banip", "198.51.100.7"}) {
+		t.Errorf("first call %v", calls[0])
+	}
+	if _, err := f.Ban(ctx, "not-an-ip", "recidive"); err == nil || !strings.Contains(err.Error(), "is not an address") {
+		t.Errorf("a non-address: %v", err)
+	}
+	if _, err := f.Ban(ctx, "198.51.100.7", "a jail; rm"); err == nil || !strings.Contains(err.Error(), "is not a jail's name") {
+		t.Errorf("a non-name: %v", err)
+	}
+	if len(calls) != 2 {
+		t.Errorf("a refused ban reached the daemon: %v", calls)
+	}
+}
+
+func TestUnbanReleasesFromOneJailOrFromEveryJail(t *testing.T) {
+	var calls [][]string
+	f := Fail2ban{Run: fake(map[string]string{"set sshd unbanip 198.51.100.7": "1\n", "unban 198.51.100.7": "2\n"}, &calls)}
+	one, err := f.Unban(ctx, "198.51.100.7", "sshd")
+	if err != nil || *one != (Released{1, "198.51.100.7", "sshd"}) {
+		t.Errorf("%+v %v", one, err)
+	}
+	every, err := f.Unban(ctx, "198.51.100.7", "")
+	if err != nil || *every != (Released{2, "198.51.100.7", "every jail"}) {
+		t.Errorf("%+v %v", every, err)
+	}
+	if !reflect.DeepEqual(calls[1], []string{"fail2ban-client", "unban", "198.51.100.7"}) {
+		t.Errorf("%v", calls[1])
+	}
+}
+
+func TestAJailsSettingsAreReadFromTheDaemonsListings(t *testing.T) {
+	f := Fail2ban{Run: fake(map[string]string{
+		"get sshd bantime": "86400\n", "get sshd findtime": "86400\n", "get sshd maxretry": "3\n",
+		"get sshd ignoreip":     "These IP addresses/networks are ignored:\n|- 127.0.0.0/8\n|- 10.10.0.0/24\n`- ::1\n",
+		"get sshd actions":      "The jail sshd has the following actions:\niptables-allports-dualchain\n",
+		"get sshd logpath":      "No file is currently monitored\n",
+		"get sshd journalmatch": "Current match filter:\n_SYSTEMD_UNIT=sshd.service + _COMM=sshd\n",
+	}, nil)}
+	got, err := f.Settings(ctx, "sshd")
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := &JailSettings{Jail: "sshd", Bantime: "86400", Findtime: "86400", Maxretry: 3,
+		Ignoreip: []string{"127.0.0.0/8", "10.10.0.0/24", "::1"}, Actions: []string{"iptables-allports-dualchain"},
+		Logpath: []string{}, Journal: "_SYSTEMD_UNIT=sshd.service + _COMM=sshd"}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("%+v", got)
+	}
+}
+
+func TestTheClientRunsAsGivenByRootAndThroughSudoByAnyoneElse(t *testing.T) {
+	if p, a := escalated(0, "fail2ban-client", []string{"status"}); p != "fail2ban-client" || !reflect.DeepEqual(a, []string{"status"}) {
+		t.Errorf("as root: %s %v", p, a)
+	}
+	if p, a := escalated(1000, "fail2ban-client", []string{"set", "sshd", "banip", "198.51.100.7"}); p != "sudo" ||
+		!reflect.DeepEqual(a, []string{"-n", "fail2ban-client", "set", "sshd", "banip", "198.51.100.7"}) {
+		t.Errorf("as an account: %s %v", p, a)
+	}
+	if !installed("sh", "/bin:/usr/bin") || installed("no-such-client-of-the-mesh", "/bin:/usr/bin") {
+		t.Error("installed is wrong about sh or about a tool nobody has")
+	}
+}
+
+// The tools carry the seat's four verbs under the seat's name, and the module's own under its own.
+func TestTheSeatsVerbsAndTheModulesOwnToolAreServed(t *testing.T) {
+	var names []string
+	for _, tool := range tools(Fail2ban{Run: fake(nil, nil)}) {
+		names = append(names, tool.Name)
+	}
+	want := []string{"node-intrusion-prevention.status", "node-intrusion-prevention.banned", "node-intrusion-prevention.ban",
+		"node-intrusion-prevention.unban", "fail2ban_settings"}
+	if !reflect.DeepEqual(names, want) {
+		t.Errorf("%v", names)
+	}
+}
+
+// The daemon on this machine, read only — status, bans and one jail's settings — when asked for with
+// FAIL2BAN_LIVE=1: the shapes above are what fail2ban-client printed once, and this is what it prints
+// now.
+func TestTheLiveDaemonReadsBack(t *testing.T) {
+	if os.Getenv("FAIL2BAN_LIVE") != "1" {
+		t.Skip("set FAIL2BAN_LIVE=1 to read the daemon on this machine")
+	}
+	f := Fail2ban{Run: execRunner}
+	status, err := f.Status(ctx, "")
+	if err != nil || len(status["jails"]) == 0 {
+		t.Fatalf("status: %+v %v", status, err)
+	}
+	for _, j := range status["jails"] {
+		t.Logf("%s: watching %v, failing %d, banned %d now of %d", j.Jail, j.Watching, j.Failing.Now, j.Banned.Now, j.Banned.Total)
+		if len(j.Watching) == 0 {
+			t.Errorf("%s watches nothing as read", j.Jail)
+		}
+	}
+	banned, err := f.Banned(ctx, "")
+	if err != nil {
+		t.Fatalf("banned: %v", err)
+	}
+	t.Logf("%d bans held", len(banned["banned"]))
+	settings, err := f.Settings(ctx, "sshd")
+	if err != nil || settings.Maxretry == 0 || len(settings.Ignoreip) == 0 {
+		t.Fatalf("settings: %+v %v", settings, err)
+	}
+	t.Logf("sshd: bantime %s, maxretry %d, ignores %v", settings.Bantime, settings.Maxretry, settings.Ignoreip)
+}

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

@@ -0,0 +1,64 @@
+// fail2ban-tools (novox/hq to-be 31, ADR 0179): the intrusion prevention's tools. One binary, launched
+// by the machine's tool runtime and speaking MCP to it over stdio through the Go SDK (ADR 0193, ADR
+// 0198): the node-intrusion-prevention seat's four verbs — who is banned, the jails' state, ban one,
+// let one go — and the module's own reading of a jail's settings. The jails themselves are composed
+// by the mesh from the modules a machine runs and written as declared resources; these touch only
+// what the running daemon holds.
+//
+// stdout is the MCP channel; everything this module says, it says on stderr.
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"strings"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+// Seat is the role this module holds.
+const Seat = "node-intrusion-prevention"
+
+func main() {
+	if err := stdio.Serve("", tools(Fail2ban{Run: execRunner})); err != nil {
+		fmt.Fprintf(os.Stderr, "[fail2ban] %v\n", err)
+		os.Exit(1)
+	}
+}
+
+func str(description string) map[string]any {
+	return map[string]any{"type": "string", "description": description}
+}
+
+func arg(a map[string]any, k string) string {
+	v, _ := a[k].(string)
+	return strings.TrimSpace(v)
+}
+
+// verb is one of the seat's verbs: listed as `<seat>.<verb>`, so the runtime serves it on the seat's
+// subject. The module's own tools keep their bare names.
+func verb(name, description string, input map[string]any, run func(a map[string]any) (any, error)) stdio.Tool {
+	return stdio.Tool{Name: Seat + "." + name, Description: description, Input: input, Run: run}
+}
+
+func tools(f Fail2ban) []stdio.Tool {
+	ctx := context.Background()
+	oneJail := map[string]any{"jail": str("one jail (optional)")}
+	return []stdio.Tool{
+		verb("status", "Every jail on this machine with what it watches, how many addresses it is counting failures against and holding now, and the totals since it started; one jail's detail when named.",
+			oneJail, func(a map[string]any) (any, error) { return f.Status(ctx, arg(a, "jail")) }),
+		verb("banned", "Every address banned on this machine right now, with the jail that holds it, when it was banned and when the ban ends.",
+			oneJail, func(a map[string]any) (any, error) { return f.Banned(ctx, arg(a, "jail")) }),
+		verb("ban", "Ban one address in one jail now, for the jail's ban time — an operator's act on the live ban list, which the mesh never writes itself.",
+			map[string]any{"ip": str("the address"), "jail": str("the jail to hold it (recidive for the long ban)")},
+			func(a map[string]any) (any, error) { return f.Ban(ctx, arg(a, "ip"), arg(a, "jail")) }),
+		verb("unban", "Let one address go, from one jail or from every jail when none is named.",
+			map[string]any{"ip": str("the address"), "jail": str("one jail (optional)")},
+			func(a map[string]any) (any, error) { return f.Unban(ctx, arg(a, "ip"), arg(a, "jail")) }),
+		{Name: "fail2ban_settings",
+			Description: "One jail's effective settings on this machine: ban time, window, tries, the addresses it never bans, its actions and what it reads.",
+			Input:       map[string]any{"jail": str("the jail")},
+			Run:         func(a map[string]any) (any, error) { return f.Settings(ctx, arg(a, "jail")) }},
+	}
+}

modules/fail2ban/go.mod

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

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

@@ -116,9 +116,12 @@
       {
         "name": "tools",
         "kind": "bundle",
-        "language": "typescript",
-        "entrypoints": [
-          "tools/index.js"
+        "language": "go",
+        "system": "arch",
+        "from": "cmd/fail2ban-tools",
+        "binary": "fail2ban-tools",
+        "loads": [
+          "fail2ban-tools"
         ]
       }
     ]

modules/fail2ban/package.json

@@ -1,18 +0,0 @@
-{
-  "name": "@novox/module-fail2ban",
-  "version": "0.1.0",
-  "description": "fail2ban \u2014 intrusion prevention: the mesh composes the jails and keeps the daemon running; this module holds the node-intrusion-prevention seat and serves its verbs status, banned, ban and unban (novox/hq to-be 31, ADR 0179).",
-  "type": "module",
-  "private": true,
-  "dependencies": {
-    "@novox/mesh-sdk": "^0.1.1"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.6.0"
-  },
-  "scripts": {
-    "build": "tsc client.ts tools/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --rootDir . --outDir dist",
-    "test": "node --test --experimental-strip-types 'test/*.test.ts'"
-  }
-}

modules/fail2ban/test/client.test.ts

@@ -1,114 +0,0 @@
-// The intrusion prevention's verbs over a fake daemon, with the shapes fail2ban-client 1.1.0 printed
-// on the control node on 2026-10-02 (novox/hq ADR 0179).
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { Fail2banClient, escalated, installed, parseBans, parseJailStatus, type Runner } from "../client.ts";
-
-const STATUS = "Status\n|- Number of jail:\t2\n`- Jail list:\trecidive, sshd\n";
-const RECIDIVE =
-  "Status for the jail: recidive\n|- Filter\n|  |- Currently failed:\t36\n|  |- Total failed:\t149\n" +
-  "|  `- File list:\t/var/log/fail2ban.log\n`- Actions\n   |- Currently banned:\t9\n   |- Total banned:\t13\n" +
-  "   `- Banned IP list:\t195.178.110.30 45.148.10.240 92.118.39.71\n";
-const SSHD =
-  "Status for the jail: sshd\n|- Filter\n|  |- Currently failed:\t5\n|  |- Total failed:\t11776\n" +
-  "|  `- Journal matches:\t_SYSTEMD_UNIT=sshd.service + _COMM=sshd\n`- Actions\n   |- Currently banned:\t0\n" +
-  "   |- Total banned:\t150\n   `- Banned IP list:\t\n";
-const WITH_TIME =
-  "195.178.110.30 \t2026-09-26 23:18:47 + 604800 = 2026-10-03 23:18:47\n" +
-  "92.118.39.71 \t2026-09-28 10:33:49 + 604800 = 2026-10-05 10:33:49\n";
-
-function fake(answers: Record<string, string>, calls: string[][] = []): Runner {
-  return async (cmd, args) => {
-    calls.push([cmd, ...args]);
-    const key = args.join(" ");
-    if (key in answers) return answers[key];
-    throw new Error(`unexpected ${cmd} ${key}`);
-  };
-}
-
-test("a jail's status is read into numbers, what it watches and who it holds", () => {
-  const s = parseJailStatus("recidive", RECIDIVE);
-  assert.deepEqual(s, {
-    jail: "recidive",
-    watching: ["/var/log/fail2ban.log"],
-    failing: { now: 36, total: 149 },
-    banned: { now: 9, total: 13, addresses: ["195.178.110.30", "45.148.10.240", "92.118.39.71"] },
-  });
-  const j = parseJailStatus("sshd", SSHD);
-  assert.deepEqual(j.watching, ["_SYSTEMD_UNIT=sshd.service + _COMM=sshd"]);
-  assert.deepEqual(j.banned, { now: 0, total: 150, addresses: [] });
-});
-
-test("status covers every jail the daemon lists, or the one named", async () => {
-  const calls: string[][] = [];
-  const f = new Fail2banClient(fake({ status: STATUS, "status recidive": RECIDIVE, "status sshd": SSHD }, calls));
-  const all = await f.status();
-  assert.deepEqual(all.jails.map((j) => j.jail), ["recidive", "sshd"]);
-  const one = await f.status("sshd");
-  assert.equal(one.jails.length, 1);
-  assert.deepEqual(calls[calls.length - 1], ["fail2ban-client", "status", "sshd"]);
-});
-
-test("bans are read with when they were placed and when they end, a permanent one as never", () => {
-  const bans = parseBans("recidive", WITH_TIME + "203.0.113.9 \t2026-10-01 00:00:00 + -1 = never\n");
-  assert.equal(bans.length, 3);
-  assert.deepEqual(bans[0], { ip: "195.178.110.30", jail: "recidive", since: "2026-09-26 23:18:47", until: "2026-10-03 23:18:47" });
-  assert.equal(bans[2].until, "never");
-  assert.deepEqual(parseBans("sshd", "\n"), []);
-});
-
-test("banned gathers every jail's bans, soonest to end first", async () => {
-  const f = new Fail2banClient(fake({
-    status: STATUS,
-    "get recidive banip --with-time": WITH_TIME,
-    "get sshd banip --with-time": "198.51.100.7 \t2026-10-02 15:06:58 + 600 = 2026-10-02 15:16:58\n",
-  }));
-  const { banned } = await f.banned();
-  assert.deepEqual(banned.map((b) => `${b.ip}@${b.jail}`), ["198.51.100.7@sshd", "195.178.110.30@recidive", "92.118.39.71@recidive"]);
-});
-
-test("ban asks the daemon by jail and answers with the ban as held; a non-address is refused before anything runs", async () => {
-  const calls: string[][] = [];
-  const f = new Fail2banClient(fake({
-    "set recidive banip 198.51.100.7": "1\n",
-    "get recidive banip --with-time": WITH_TIME + "198.51.100.7 \t2026-10-02 17:00:00 + 604800 = 2026-10-09 17:00:00\n",
-  }, calls));
-  const r = await f.ban("198.51.100.7", "recidive");
-  assert.equal(r.added, 1);
-  assert.equal(r.banned?.until, "2026-10-09 17:00:00");
-  assert.deepEqual(calls[0], ["fail2ban-client", "set", "recidive", "banip", "198.51.100.7"]);
-  await assert.rejects(() => f.ban("not-an-ip", "recidive"), /is not an address/);
-  await assert.rejects(() => f.ban("198.51.100.7", "a jail; rm"), /is not a jail's name/);
-  assert.equal(calls.length, 2);
-});
-
-test("unban releases from one jail or from every jail", async () => {
-  const calls: string[][] = [];
-  const f = new Fail2banClient(fake({ "set sshd unbanip 198.51.100.7": "1\n", "unban 198.51.100.7": "2\n" }, calls));
-  assert.deepEqual(await f.unban("198.51.100.7", "sshd"), { released: 1, ip: "198.51.100.7", jail: "sshd" });
-  assert.deepEqual(await f.unban("198.51.100.7"), { released: 2, ip: "198.51.100.7", jail: "every jail" });
-  assert.deepEqual(calls[1], ["fail2ban-client", "unban", "198.51.100.7"]);
-});
-
-test("a jail's settings are read from the daemon's listings", async () => {
-  const f = new Fail2banClient(fake({
-    "get sshd bantime": "86400\n", "get sshd findtime": "86400\n", "get sshd maxretry": "3\n",
-    "get sshd ignoreip": "These IP addresses/networks are ignored:\n|- 127.0.0.0/8\n|- 10.10.0.0/24\n`- ::1\n",
-    "get sshd actions": "The jail sshd has the following actions:\niptables-allports-dualchain\n",
-    "get sshd logpath": "No file is currently monitored\n",
-    "get sshd journalmatch": "Current match filter:\n_SYSTEMD_UNIT=sshd.service + _COMM=sshd\n",
-  }));
-  assert.deepEqual(await f.settings("sshd"), {
-    jail: "sshd", bantime: "86400", findtime: "86400", maxretry: 3,
-    ignoreip: ["127.0.0.0/8", "10.10.0.0/24", "::1"], actions: ["iptables-allports-dualchain"],
-    logpath: [], journalmatch: "_SYSTEMD_UNIT=sshd.service + _COMM=sshd",
-  });
-});
-
-test("the client runs as given by root and through sudo without a prompt by anyone else", () => {
-  assert.deepEqual(escalated("fail2ban-client", ["status"], 0), ["fail2ban-client", ["status"]]);
-  assert.deepEqual(escalated("fail2ban-client", ["set", "sshd", "banip", "198.51.100.7"], 1000),
-    ["sudo", ["-n", "fail2ban-client", "set", "sshd", "banip", "198.51.100.7"]]);
-  assert.equal(installed("sh"), true);
-  assert.equal(installed("no-such-client-of-the-mesh"), false);
-});

modules/fail2ban/tools/index.ts

@@ -1,62 +0,0 @@
-// The intrusion prevention's tools: the node-intrusion-prevention seat's four verbs — who is banned,
-// the jails' state, ban one, let one go — and the module's own reading of a jail's settings
-// (novox/hq to-be 31, ADR 0179). The jails themselves are composed by the mesh from the modules a
-// machine runs and written as declared resources; these touch only what the running daemon holds.
-
-import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
-import { Fail2banClient } from "../client.js";
-
-export function getSeatVerbs(fail2ban: Fail2banClient): ToolDefinition[] {
-  return [
-    {
-      name: "status",
-      description:
-        "Every jail on this machine with what it watches, how many addresses it is counting failures against and holding now, and the totals since it started; one jail's detail when named.",
-      input: { jail: { type: "string", description: "one jail (optional)" } },
-      run: async (args) => fail2ban.status(args.jail ? String(args.jail) : undefined),
-    },
-    {
-      name: "banned",
-      description: "Every address banned on this machine right now, with the jail that holds it, when it was banned and when the ban ends.",
-      input: { jail: { type: "string", description: "one jail (optional)" } },
-      run: async (args) => fail2ban.banned(args.jail ? String(args.jail) : undefined),
-    },
-    {
-      name: "ban",
-      description:
-        "Ban one address in one jail now, for the jail's ban time — an operator's act on the live ban list, which the mesh never writes itself.",
-      input: {
-        ip: { type: "string", description: "the address" },
-        jail: { type: "string", description: "the jail to hold it (recidive for the long ban)" },
-      },
-      run: async (args) => fail2ban.ban(String(args.ip ?? ""), String(args.jail ?? "")),
-    },
-    {
-      name: "unban",
-      description: "Let one address go, from one jail or from every jail when none is named.",
-      input: {
-        ip: { type: "string", description: "the address" },
-        jail: { type: "string", description: "one jail (optional)" },
-      },
-      run: async (args) => fail2ban.unban(String(args.ip ?? ""), args.jail ? String(args.jail) : undefined),
-    },
-  ];
-}
-
-export function getFail2banTools(fail2ban: Fail2banClient): ToolDefinition[] {
-  return [
-    {
-      name: "fail2ban_settings",
-      description:
-        "One jail's effective settings on this machine: ban time, window, tries, the addresses it never bans, its actions and what it reads.",
-      input: { jail: { type: "string", description: "the jail" } },
-      run: async (args) => fail2ban.settings(String(args.jail ?? "")),
-    },
-  ];
-}
-
-const fail2ban = Fail2banClient.onThisMachine();
-// The seat's verbs under the seat's name: the runtime serves them on the seat's subjects where this
-// module holds it (ADR 0159, 0160). The module's own under its own.
-registerModuleTools("node-intrusion-prevention", () => getSeatVerbs(fail2ban));
-registerModuleTools("fail2ban", () => getFail2banTools(fail2ban));

modules/fail2ban/tsconfig.json

@@ -1,15 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "noEmit": true
-  },
-  "include": [
-    "client.ts",
-    "tools/index.ts"
-  ]
-}

modules/gitea/module.json

@@ -222,5 +222,12 @@
       "failregex": "^.*Failed authentication attempt for .* from <HOST>(?::\\d+)?\\s*$\n            ^.*Invalid user .* from <HOST> port \\d+\\s*$\n            ^.*User \\S+ from <HOST> not allowed because .*$",
       "jail": "backend = systemd\njournalmatch = CONTAINER_NAME=gitea\nport = http,https,222\nmaxretry = 3\nfindtime = 1d\nbantime = 1d"
     }
+  ],
+  "contributions": [
+    {
+      "seat": "node-backup",
+      "kind": "backup",
+      "content": "path ${dir:data}\n"
+    }
   ]
 }

modules/influxdb/module.json

@@ -132,5 +132,12 @@
         }
       }
     ]
-  }
+  },
+  "contributions": [
+    {
+      "seat": "node-backup",
+      "kind": "backup",
+      "content": "path ${dir:data}\npath ${dir:config}\n"
+    }
+  ]
 }

modules/mailu/module.json

@@ -558,5 +558,12 @@
       "failregex": "^.*(?:imap|pop3|submission|managesieve)-login: .*\\(auth failed, \\d+ attempts(?: in \\d+ secs)?\\):.*rip=<HOST>(?:,|$)",
       "jail": "backend = systemd\njournalmatch = CONTAINER_NAME=mailu-front\nport = smtp,submission,submissions,imap,imaps,pop3,pop3s\nmaxretry = 3\nfindtime = 1d\nbantime = 1d"
     }
+  ],
+  "contributions": [
+    {
+      "seat": "node-backup",
+      "kind": "backup",
+      "content": "path ${dir:data-mail}\npath ${dir:data-dkim}\npath ${dir:data-data}\npath ${dir:data-dav}\npath ${dir:data-webmail}\n"
+    }
   ]
 }

modules/mesh-vault/module.json

@@ -79,5 +79,12 @@
       "name": "mesh-vault",
       "scope": "mesh"
     }
+  ],
+  "contributions": [
+    {
+      "seat": "node-backup",
+      "kind": "backup",
+      "content": "path ${dir:state}\npath ${dir:ledger}\npath ${dir:root}\n"
+    }
   ]
 }

modules/minio/module.json

@@ -151,5 +151,12 @@
         }
       }
     ]
-  }
+  },
+  "contributions": [
+    {
+      "seat": "node-backup",
+      "kind": "backup",
+      "content": "path ${dir:data}\n"
+    }
+  ]
 }

modules/mongodb/module.json

@@ -58,6 +58,11 @@
       "type": "directory",
       "mode": "0700"
     },
+    {
+      "id": "dumps",
+      "type": "directory",
+      "mode": "0700"
+    },
     {
       "id": "net",
       "type": "network",
@@ -113,5 +118,12 @@
         }
       }
     ]
-  }
+  },
+  "contributions": [
+    {
+      "seat": "node-backup",
+      "kind": "backup",
+      "content": "run docker exec mongodb-server sh -c 'printf \"password: %s\\n\" \"$(cat /run/secrets/root)\" > /tmp/.backup.yaml && mongodump --quiet --config /tmp/.backup.yaml --username root --authenticationDatabase admin --archive; s=$?; rm -f /tmp/.backup.yaml; exit $s' > ${dir:dumps}/all.archive.partial && mv ${dir:dumps}/all.archive.partial ${dir:dumps}/all.archive\npath ${dir:dumps}\n"
+    }
+  ]
 }

modules/mssql/module.json

@@ -65,6 +65,13 @@
       "mode": "0700",
       "owner": "10001:0"
     },
+    {
+      "id": "dumps",
+      "type": "directory",
+      "path": "${dir:data}/backup",
+      "mode": "0700",
+      "owner": "10001:0"
+    },
     {
       "id": "net",
       "type": "network",
@@ -86,6 +93,13 @@
         "${dir:data}:/var/opt/mssql"
       ],
       "secrets-in-environment": "the image documents only MSSQL_SA_PASSWORD, no _FILE and no configuration field; not convertible without a wrapper entrypoint"
+    },
+    {
+      "id": "backup-sql",
+      "type": "file",
+      "path": "${dir:state}/backup.sql",
+      "mode": "0600",
+      "content": "SET NOCOUNT ON;\nDECLARE @n sysname, @s nvarchar(max);\nDECLARE c CURSOR LOCAL FAST_FORWARD FOR\n  SELECT name FROM sys.databases WHERE database_id > 4 AND state = 0 AND source_database_id IS NULL;\nOPEN c;\nFETCH NEXT FROM c INTO @n;\nWHILE @@FETCH_STATUS = 0\nBEGIN\n  SET @s = N'BACKUP DATABASE ' + QUOTENAME(@n) + N' TO DISK = N''/var/opt/mssql/backup/' + REPLACE(@n, N'''', N'''''') + N'.bak'' WITH INIT, COPY_ONLY, CHECKSUM';\n  EXEC (@s);\n  FETCH NEXT FROM c INTO @n;\nEND\nCLOSE c;\nDEALLOCATE c;\n"
     }
   ],
   "build": {
@@ -112,5 +126,12 @@
         }
       }
     ]
-  }
+  },
+  "contributions": [
+    {
+      "seat": "node-backup",
+      "kind": "backup",
+      "content": "run { cat ${dir:state}/sa.secret; echo; cat ${dir:state}/backup.sql; } | docker exec -i mssql sh -c 'read -r p; SQLCMDPASSWORD=\"$p\" exec /opt/mssql-tools18/bin/sqlcmd -C -b -S localhost -U sa -i /dev/stdin'\npath ${dir:dumps}\n"
+    }
+  ]
 }

modules/nextcloud-client/README.md

@@ -0,0 +1,106 @@
+# nextcloud-client
+
+The Nextcloud desktop sync client on the workstations, as a module (novox/hq ADR 0208). It requires
+`x11-display`, so it is assigned only where a display server is held on the same machine.
+
+## Owns
+
+| what | where |
+|---|---|
+| the client | package `nextcloud-client`, from the official repositories |
+
+Nothing else. It holds no seat, makes no contribution and writes no file.
+
+- **No AUR, no vendored copy.** Both workstations run the official package (`extra`), installed
+  explicitly. ADR 0205 does not apply.
+- **The account configuration stays the operator's.** `~/.config/Nextcloud/nextcloud.cfg` is the
+  client's own file, and the client rewrites it. That makes it *found* in ADR 0182's terms: the module
+  never declares, reads into or writes it. The tools only read it. The accounts, the sync folders, the
+  server and the credentials are set in the client.
+
+## How it starts: the client's own autostart entry, and nothing else
+
+One process has one starter (the rule `picom` states for the desktop modules). The client's starter is
+**its own XDG autostart entry**, `~/.config/autostart/Nextcloud.desktop` (`nextcloud --background`).
+
+- The client writes that entry itself while its setting *Launch on system startup* is ticked, and
+  removes it when the setting is unticked.
+- The session runs every XDG autostart entry once at login: the `i3` module's
+  `dex --autostart --environment i3`.
+- The package ships no `/etc/xdg/autostart` entry.
+
+**Why not a contribution to `node-display-session` or the `xinitrc` slot:** the client would still
+write its own entry whenever the setting is ticked, and the session would start it twice. The module
+cannot own the entry either, because the client rewrites it on every start. Declaring that file would
+make two writers of one file. So the module adds no start, and `nextcloud_check` holds the rule
+instead: it names any second start it finds.
+
+- **Excluded:** the window manager's `exec … nextcloud` (the `i3` module's configuration dropped it),
+  and the package's user unit `com.nextcloud.desktopclient.nextcloud.service`, which stays disabled.
+  User-scoped units are not declarable yet (mesh-host #72).
+- **One caveat:** `dex` ignores the entry's `X-GNOME-Autostart-Delay=10`, so the client starts with
+  the session. It retries its connection by itself, so that is harmless.
+
+## Tools
+
+They are served by the node's runtime as the operator account (ADR 0175), and are read-only except
+`restart`. **No answer carries the server's address, the account's user ids or a credential.**
+
+- `nextcloud.cfg` is read only to learn what to hide.
+- The log tools replace the server's host with `<server>` and the user ids with `<account>`.
+- Anything shaped like a credential (`Authorization:`, `token=`, `password=`, a cookie) becomes `<hidden>`.
+
+| tool | does |
+|---|---|
+| `nextcloud_status` (r) | <ul><li>whether the client runs: pid, since, and the scope or unit it runs in</li><li>the installed version, and what starts it at login</li><li>each account by display name and auth type, with each sync folder: local path (`~/…`), remote path, paused, virtual files, journal present</li><li>each folder's **last sync run**: started, finished or still running, items, errors, the first ten failing files</li><li>the latest warnings and worse in the client's log</li></ul> |
+| `nextcloud_log` (r) | the last `lines` (default 100, at most 2000) of the client's log (`source: client`). The log rotates every two hours, and older gzipped files are read until the count is reached. `problems: true` keeps warnings and worse. `source: sync` gives the sync runs' log. Answers are capped at 256 KiB |
+| `nextcloud_restart` (a) | asks the client to end (SIGTERM), forces it after 6 s, and starts `nextcloud --background` in the operator's session. The start is a transient user unit `mesh-nextcloud-client`, so it outlives the tools runtime. Answers the pids. Refused plainly when nobody is logged in to the desktop |
+| `nextcloud_check` (r) | <ul><li>the package is installed</li><li>exactly one start: the entry is present and enabled, and `dex` is installed</li><li>no window-manager exec and no enabled user unit</li><li>one client runs in a desktop session</li><li>an account exists, its folders exist with a journal, and none is paused</li></ul>Each finding says what to do |
+
+**Where the tools read:**
+
+- The client's settings are read from `~/.config/Nextcloud/nextcloud.cfg`.
+- Its log is read from `~/.config/Nextcloud/logs/*_nextcloud.log*`.
+- Each folder's sync runs are read from the `*_sync.log` whose first line is that folder's path. That
+  file is in `~/.local/share/Nextcloud/`, or in `~/.config/Nextcloud/` for older clients, and the
+  newest one wins.
+
+The tools find the session's `DISPLAY` and `XAUTHORITY` from the window manager's own environment,
+as `clipmenu` and `screen-lock` do. Every command has a timeout and capped output. Everything runs
+through an injected runner and a fake root in the tests.
+
+## What changes when it is assigned
+
+| | g14 | shanks |
+|---|---|---|
+| package | none: `nextcloud-client` 34.0.4 is installed, explicitly, from `extra` | the same |
+| start | none: dex starts it from the client's own entry (`--background`, in the login session's scope) | none on disk. **The client running now came from the predecessor's window-manager line** (`nextcloud`, a child of i3, since the session of 2026-10-04 16:00). That session began before the `i3` module dropped the line and installed `dex`, so the next login is the first that starts it from its entry |
+| settings | one account, one folder (`~/Nextcloud/`, whole server), not paused, no virtual files; *Launch on system startup* on | the same |
+
+The workstations are already in the state this module describes.
+
+## Migration (ADR 0182)
+
+Nothing is required on either machine.
+
+- **shanks:** log out and in once, or run `nextcloud_restart`, and the client runs from its one start.
+  `nextcloud_check` then answers `ok`.
+- **Optional, both:** the client has kept a `nextcloud.cfg.backup_<date>_<version>` from every upgrade
+  since 2023 (about twenty on each machine). It also keeps a sync log that it no longer writes, at
+  `~/.config/Nextcloud/Nextcloud_sync.log`, from 2024 on g14 and 2023 on shanks. They are the
+  operator's to delete. The module leaves them.
+
+## Leaves as found
+
+- `~/.config/Nextcloud/`: the settings, their backups, `cookies0.db`, `sync-exclude.lst`, the logs.
+- `~/.local/share/Nextcloud/`: the sync runs' log.
+- `~/.config/autostart/Nextcloud.desktop`, the client's.
+- Every sync folder and its `.sync_*.db` journal.
+
+## Relies on
+
+- **`i3`'s `dex` line for the start.** Nothing in the mesh says so yet: XDG autostart has no seat, and
+  a module without a seat or contribution has no way to depend on another module. Assigned without
+  `i3`, the client is installed and does not start. `nextcloud_check` says so.
+- A display server on the same machine (`x11-display`, ADR 0208 §3). Under sway the client runs on
+  Wayland as well. A Wayland twin then requires `wayland-display`.

modules/nextcloud-client/cmd/nextcloud-client-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/nextcloud-client/cmd/nextcloud-client-tools/desktop.go

@@ -0,0 +1,574 @@
+package main
+
+// desktop.go is the same file in the nextcloud-client and blueman bundles: a tray application of the
+// operator's graphical session, seen from the node's tool runtime (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. A tool that starts something on the desktop finds the
+// session from a process of the account that carries DISPLAY (the window manager first), and starts
+// the program under the account's own service manager with `systemd-run --user`, never as its own
+// child: the runtime's unit is a cgroup that is emptied whenever the runtime restarts.
+//
+// Everything a tool touches goes through a Machine: its filesystem root, its commands (a Runner) and
+// its signals are injected, so the tests run against a fake /proc and a fake home.
+//
+// Bounds: one command gets at most CallTimeout (below the runtime's 30 s call limit) and is ended
+// with everything it started when it takes longer; each stream is kept to MostOutput; a file is read
+// to at most MostRead.
+
+import (
+	"bufio"
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"syscall"
+	"time"
+)
+
+// Bounds every command and read is held to.
+const (
+	CallTimeout = 10 * time.Second
+	MostOutput  = 256 << 10
+	MostRead    = 16 << 20
+)
+
+// Output is what a command did.
+type Output struct {
+	Stdout string
+	Stderr string
+	Code   int
+	// Err is why it did not run to an answer: not installed, ended on its timeout, or the spawn error.
+	Err error
+	Cut bool
+}
+
+// ErrNotInstalled and ErrTimedOut are what a Runner answers in Output.Err.
+var (
+	ErrNotInstalled = errors.New("not installed")
+	ErrTimedOut     = errors.New("timed out")
+	// ErrNoSession is answered by a tool that needs the desktop when nobody is logged in to it.
+	ErrNoSession = errors.New("no graphical session")
+)
+
+// Runner runs one command with extra environment, within the context's deadline. Tests replace it.
+type Runner func(ctx context.Context, env []string, name string, args ...string) Output
+
+// Machine is what the tools read and act on.
+type Machine struct {
+	Root    string // "" on the machine; a fake root in tests
+	Home    string // the operator's home, as the machine names it
+	UID     int
+	Run     Runner
+	Kill    func(pid int, sig syscall.Signal) error
+	Sleep   func(time.Duration)
+	Now     func() time.Time
+	Timeout time.Duration
+}
+
+// NewMachine is the machine the bundle runs on.
+func NewMachine() *Machine {
+	return &Machine{Home: operatorHome(), UID: os.Getuid(), Run: execRun, Kill: syscall.Kill,
+		Sleep: time.Sleep, Now: time.Now, Timeout: CallTimeout}
+}
+
+// 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
+}
+
+func (m *Machine) path(p string) string { return filepath.Join(m.Root, p) }
+
+// home is a path under the operator's home, on this machine's filesystem.
+func (m *Machine) home(rel ...string) string {
+	return filepath.Join(append([]string{m.Root, m.Home}, rel...)...)
+}
+
+// tilde shows a path under the home as ~/…, so an answer does not carry the account's name.
+func (m *Machine) tilde(p string) string {
+	if m.Home != "" && m.Home != "/" {
+		h := strings.TrimSuffix(m.Home, "/")
+		if p == h {
+			return "~"
+		}
+		if strings.HasPrefix(p, h+"/") {
+			return "~/" + strings.TrimPrefix(p, h+"/")
+		}
+	}
+	return p
+}
+
+// cmd runs a command within the machine's timeout (or a shorter one).
+func (m *Machine) cmd(timeout time.Duration, env []string, name string, args ...string) Output {
+	if timeout <= 0 || timeout > m.Timeout {
+		timeout = m.Timeout
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), timeout)
+	defer cancel()
+	return m.Run(ctx, env, name, args...)
+}
+
+// failed names how a command failed, or answers nil when it ran and exited 0.
+func failed(o Output, name string, args ...string) error {
+	switch {
+	case errors.Is(o.Err, ErrNotInstalled):
+		return fmt.Errorf("%s is not installed on this machine", name)
+	case errors.Is(o.Err, ErrTimedOut):
+		return fmt.Errorf("%s gave no answer in time and was ended", name)
+	case o.Err != nil:
+		return fmt.Errorf("%s did not run: %v", name, o.Err)
+	case o.Code != 0:
+		said := strings.TrimSpace(o.Stderr)
+		if said == "" {
+			said = strings.TrimSpace(o.Stdout)
+		}
+		if said == "" {
+			said = "and said nothing"
+		}
+		return fmt.Errorf("%s %s exited %d: %s", name, strings.Join(args, " "), o.Code, tail(said, 1000))
+	}
+	return nil
+}
+
+func tail(s string, n int) string {
+	if len(s) <= n {
+		return s
+	}
+	return "…" + s[len(s)-n:]
+}
+
+type capped struct {
+	b   bytes.Buffer
+	cut bool
+}
+
+func (c *capped) Write(p []byte) (int, error) {
+	if room := MostOutput - c.b.Len(); room < len(p) {
+		if room > 0 {
+			c.b.Write(p[:room])
+		}
+		c.cut = true
+		return len(p), nil
+	}
+	return c.b.Write(p)
+}
+
+func execRun(ctx context.Context, env []string, name string, args ...string) Output {
+	path, err := exec.LookPath(name)
+	if err != nil {
+		return Output{Code: 127, Err: ErrNotInstalled}
+	}
+	cmd := exec.CommandContext(ctx, path, args...)
+	cmd.Env = append(append(os.Environ(), "LC_ALL=C"), env...)
+	// 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
+	var out, errs capped
+	cmd.Stdout, cmd.Stderr = &out, &errs
+	err = cmd.Run()
+	o := Output{Stdout: out.b.String(), Stderr: errs.b.String(), Cut: out.cut || errs.cut}
+	var exit *exec.ExitError
+	switch {
+	case err == nil:
+	case ctx.Err() == context.DeadlineExceeded:
+		o.Code, o.Err = 124, ErrTimedOut
+	case errors.As(err, &exit):
+		o.Code = exit.ExitCode()
+	default:
+		o.Code, o.Err = 127, err
+	}
+	return o
+}
+
+// readBounded reads a file to at most MostRead bytes.
+func readBounded(path string) ([]byte, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return nil, err
+	}
+	defer f.Close()
+	return io.ReadAll(io.LimitReader(f, MostRead))
+}
+
+// Proc is one process of the account.
+type Proc struct {
+	PID     int    `json:"pid"`
+	Command string `json:"command"`
+	// StartedIn is the unit or scope it runs in: the login session's scope when the session's start
+	// (dex, the window manager) started it, a mesh-… unit when a tool restarted it.
+	StartedIn string `json:"started_in,omitempty"`
+	Since     string `json:"since,omitempty"`
+}
+
+// procs are this account's processes named comm, oldest first.
+func (m *Machine) procs(comm string) []Proc {
+	entries, err := os.ReadDir(m.path("/proc"))
+	if err != nil {
+		return nil
+	}
+	boot := m.bootTime()
+	var out []Proc
+	for _, e := range entries {
+		pid, err := strconv.Atoi(e.Name())
+		if err != nil {
+			continue
+		}
+		dir := m.path(filepath.Join("/proc", e.Name()))
+		if readTrimmed(filepath.Join(dir, "comm")) != comm || m.uidOf(dir) != m.UID {
+			continue
+		}
+		p := Proc{PID: pid, Command: strings.TrimSpace(strings.ReplaceAll(readTrimmed(filepath.Join(dir, "cmdline")), "\x00", " "))}
+		if p.Command == "" {
+			p.Command = comm
+		}
+		if cg := readTrimmed(filepath.Join(dir, "cgroup")); cg != "" {
+			line := strings.Split(cg, "\n")[0]
+			p.StartedIn = filepath.Base(line[strings.LastIndexByte(line, ':')+1:])
+		}
+		if t, ok := startOf(readTrimmed(filepath.Join(dir, "stat")), boot); ok {
+			p.Since = t.UTC().Format(time.RFC3339)
+		}
+		out = append(out, p)
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].PID < out[j].PID })
+	return out
+}
+
+// uidOf is the real uid on a process's status, -1 when unreadable.
+func (m *Machine) uidOf(dir string) int {
+	for _, l := range strings.Split(readTrimmed(filepath.Join(dir, "status")), "\n") {
+		if f := strings.Fields(l); len(f) > 1 && f[0] == "Uid:" {
+			if n, err := strconv.Atoi(f[1]); err == nil {
+				return n
+			}
+		}
+	}
+	return -1
+}
+
+func (m *Machine) bootTime() int64 {
+	for _, l := range strings.Split(readTrimmed(m.path("/proc/stat")), "\n") {
+		if f := strings.Fields(l); len(f) == 2 && f[0] == "btime" {
+			n, _ := strconv.ParseInt(f[1], 10, 64)
+			return n
+		}
+	}
+	return 0
+}
+
+// startOf reads a process's start from its stat line (field 22, in clock ticks of 1/100 s since boot).
+func startOf(stat string, boot int64) (time.Time, bool) {
+	i := strings.LastIndexByte(stat, ')')
+	if i < 0 || boot == 0 {
+		return time.Time{}, false
+	}
+	f := strings.Fields(stat[i+1:])
+	if len(f) < 20 {
+		return time.Time{}, false
+	}
+	ticks, err := strconv.ParseInt(f[19], 10, 64)
+	if err != nil {
+		return time.Time{}, false
+	}
+	return time.Unix(boot+ticks/100, 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
+}
+
+// Session is what a tool needs to start something on the operator's desktop.
+type Session struct {
+	Display    string `json:"display"`
+	XAuthority string `json:"xauthority,omitempty"`
+	Bus        string `json:"bus,omitempty"`
+	RuntimeDir string `json:"runtime_dir,omitempty"`
+	From       string `json:"found_in"`
+}
+
+// sessionHolders are the processes whose environment is the session's, best first.
+var sessionHolders = []string{"i3", "sway", "i3bar", "picom", "dunst", "xterm"}
+
+// session finds the account's graphical session, or ErrNoSession saying what it looked at.
+func (m *Machine) session() (Session, error) {
+	entries, _ := os.ReadDir(m.path("/proc"))
+	best, bestRank := -1, len(sessionHolders)+1
+	var env map[string]string
+	var from string
+	for _, e := range entries {
+		pid, err := strconv.Atoi(e.Name())
+		if err != nil {
+			continue
+		}
+		dir := m.path(filepath.Join("/proc", e.Name()))
+		if m.uidOf(dir) != m.UID {
+			continue
+		}
+		raw, err := os.ReadFile(filepath.Join(dir, "environ"))
+		if err != nil {
+			continue
+		}
+		vars := parseEnviron(raw)
+		if vars["DISPLAY"] == "" {
+			continue
+		}
+		comm := readTrimmed(filepath.Join(dir, "comm"))
+		rank := len(sessionHolders)
+		for i, h := range sessionHolders {
+			if h == comm {
+				rank = i
+			}
+		}
+		if rank < bestRank || (rank == bestRank && pid > best) {
+			best, bestRank, env, from = pid, rank, vars, fmt.Sprintf("process %s (pid %d)", comm, pid)
+		}
+	}
+	if env == nil {
+		return Session{}, fmt.Errorf("%w for uid %d on this machine: no process of the account carries DISPLAY. "+
+			"Is anyone logged in to the desktop?", ErrNoSession, m.UID)
+	}
+	s := Session{Display: env["DISPLAY"], XAuthority: env["XAUTHORITY"], Bus: env["DBUS_SESSION_BUS_ADDRESS"],
+		RuntimeDir: env["XDG_RUNTIME_DIR"], From: from}
+	if s.RuntimeDir == "" {
+		s.RuntimeDir = fmt.Sprintf("/run/user/%d", m.UID)
+	}
+	if s.Bus == "" && exists(m.path(filepath.Join(s.RuntimeDir, "bus"))) {
+		s.Bus = "unix:path=" + filepath.Join(s.RuntimeDir, "bus")
+	}
+	return s, nil
+}
+
+// bus is the account's session bus environment, which a logged-in account has with or without a
+// desktop: what a command needs to reach the user's service manager or a bus name.
+func (m *Machine) bus() []string {
+	runtime := fmt.Sprintf("/run/user/%d", m.UID)
+	return []string{"XDG_RUNTIME_DIR=" + runtime, "DBUS_SESSION_BUS_ADDRESS=unix:path=" + runtime + "/bus"}
+}
+
+// Env is the session's variables, for a command that draws or speaks to the desktop.
+func (s Session) Env() []string {
+	var env []string
+	for _, kv := range [][2]string{{"DISPLAY", s.Display}, {"XAUTHORITY", s.XAuthority},
+		{"DBUS_SESSION_BUS_ADDRESS", s.Bus}, {"XDG_RUNTIME_DIR", s.RuntimeDir}} {
+		if kv[1] != "" {
+			env = append(env, kv[0]+"="+kv[1])
+		}
+	}
+	return env
+}
+
+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
+}
+
+// detach starts a long-lived program under the account's service manager, as a transient unit that
+// carries the session's display. A unit left by an earlier start under the same name is stopped
+// first, so the fixed name means at most one.
+func (m *Machine) detach(s Session, unit string, argv ...string) error {
+	_ = m.cmd(5*time.Second, s.Env(), "systemctl", "--user", "stop", unit+".service")
+	call := []string{"--user", "--collect", "--quiet", "--unit=" + unit}
+	for _, kv := range [][2]string{{"DISPLAY", s.Display}, {"XAUTHORITY", s.XAuthority}} {
+		if kv[1] != "" {
+			call = append(call, "--setenv="+kv[0]+"="+kv[1])
+		}
+	}
+	call = append(append(call, "--"), argv...)
+	return failed(m.cmd(8*time.Second, s.Env(), "systemd-run", call...), "systemd-run", call...)
+}
+
+// stop ends every process of the account named in comms: SIGTERM, then SIGKILL for what is still
+// there after grace. It answers the pids that ended and those that had to be killed.
+func (m *Machine) stop(grace time.Duration, comms ...string) (ended, killed []int) {
+	var pids []int
+	for _, c := range comms {
+		for _, p := range m.procs(c) {
+			if m.Kill(p.PID, syscall.SIGTERM) == nil {
+				pids = append(pids, p.PID)
+			}
+		}
+	}
+	alive := func() []int {
+		var left []int
+		for _, pid := range pids {
+			if exists(m.path(filepath.Join("/proc", strconv.Itoa(pid)))) {
+				left = append(left, pid)
+			}
+		}
+		return left
+	}
+	step := 200 * time.Millisecond
+	for waited := time.Duration(0); waited < grace && len(alive()) > 0; waited += step {
+		m.Sleep(step)
+	}
+	left := alive()
+	for _, pid := range left {
+		if m.Kill(pid, syscall.SIGKILL) == nil {
+			killed = append(killed, pid)
+		}
+	}
+	gone := map[int]bool{}
+	for _, pid := range left {
+		gone[pid] = true
+	}
+	for _, pid := range pids {
+		if !gone[pid] {
+			ended = append(ended, pid)
+		}
+	}
+	return ended, killed
+}
+
+// waitFor waits up to d for a process of the account named comm, and answers what it found.
+func (m *Machine) waitFor(comm string, d time.Duration) []Proc {
+	step := 250 * time.Millisecond
+	for waited := time.Duration(0); ; waited += step {
+		if p := m.procs(comm); len(p) > 0 || waited >= d {
+			return p
+		}
+		m.Sleep(step)
+	}
+}
+
+// desktopEntry reads the [Desktop Entry] group of an XDG desktop file; nil when there is none.
+func desktopEntry(path string) map[string]string {
+	raw, err := readBounded(path)
+	if err != nil {
+		return nil
+	}
+	out := map[string]string{}
+	in := false
+	s := bufio.NewScanner(bytes.NewReader(raw))
+	for s.Scan() {
+		l := strings.TrimSpace(s.Text())
+		switch {
+		case strings.HasPrefix(l, "["):
+			in = l == "[Desktop Entry]"
+		case in && l != "" && !strings.HasPrefix(l, "#"):
+			if i := strings.IndexByte(l, '='); i > 0 {
+				out[strings.TrimSpace(l[:i])] = strings.TrimSpace(l[i+1:])
+			}
+		}
+	}
+	return out
+}
+
+// Autostart is what XDG autostart does with one entry: the account's file overrides the system's
+// of the same name, and Hidden=true (or the GNOME switch off) means it is not started.
+type Autostart struct {
+	Entry   string `json:"entry"`
+	From    string `json:"from"`
+	Exec    string `json:"exec,omitempty"`
+	Starts  bool   `json:"starts"`
+	Because string `json:"because,omitempty"`
+}
+
+// autostart resolves one XDG autostart entry by its file name, the account's directory first.
+func (m *Machine) autostart(name string) Autostart {
+	a := Autostart{Entry: name}
+	user := m.home(".config", "autostart", name)
+	system := m.path(filepath.Join("/etc/xdg/autostart", name))
+	var e map[string]string
+	switch {
+	case exists(user):
+		e, a.From = desktopEntry(user), m.tilde(filepath.Join(m.Home, ".config/autostart", name))
+	case exists(system):
+		e, a.From = desktopEntry(system), filepath.Join("/etc/xdg/autostart", name)
+	default:
+		a.Because = "no such entry in ~/.config/autostart or /etc/xdg/autostart"
+		return a
+	}
+	a.Exec = e["Exec"]
+	switch {
+	case strings.EqualFold(e["Hidden"], "true"):
+		a.Because = "Hidden=true"
+	case strings.EqualFold(e["X-GNOME-Autostart-enabled"], "false"):
+		a.Because = "X-GNOME-Autostart-enabled=false"
+	case a.Exec == "":
+		a.Because = "the entry has no Exec"
+	default:
+		a.Starts = true
+	}
+	return a
+}
+
+// i3Starts are the window manager's start-up lines (exec, exec_always) that run a program named
+// word, in the configuration and its config.d: a second start beside an autostart entry.
+func (m *Machine) i3Starts(word string) []string {
+	files := []string{m.home(".config", "i3", "config")}
+	more, _ := filepath.Glob(m.home(".config", "i3", "config.d", "*.conf"))
+	files = append(files, more...)
+	var out []string
+	for _, f := range files {
+		raw, err := readBounded(f)
+		if err != nil {
+			continue
+		}
+		for n, l := range strings.Split(string(raw), "\n") {
+			t := strings.TrimSpace(l)
+			if !strings.HasPrefix(t, "exec ") && !strings.HasPrefix(t, "exec_always ") {
+				continue
+			}
+			for _, w := range strings.Fields(t)[1:] {
+				if filepath.Base(strings.Trim(w, `"'`)) == word {
+					out = append(out, fmt.Sprintf("%s:%d: %s", m.tilde(strings.TrimPrefix(f, m.Root)), n+1, t))
+					break
+				}
+			}
+		}
+	}
+	return out
+}
+
+// installed asks the package manager for one package's version; "" when it is not installed.
+func (m *Machine) installed(pkg string) (string, error) {
+	o := m.cmd(0, nil, "pacman", "-Q", pkg)
+	if o.Err != nil {
+		return "", failed(o, "pacman", "-Q", pkg)
+	}
+	if o.Code != 0 {
+		return "", nil
+	}
+	f := strings.Fields(o.Stdout)
+	if len(f) < 2 {
+		return "", fmt.Errorf("pacman -Q %s answered %q", pkg, o.Stdout)
+	}
+	return f[1], nil
+}
+
+// Finding is one thing a check found wrong, and what to do about it.
+type Finding struct {
+	What string `json:"what"`
+	Do   string `json:"do,omitempty"`
+}

modules/nextcloud-client/cmd/nextcloud-client-tools/desktop_test.go

@@ -0,0 +1,202 @@
+package main
+
+// The fake machine the tests run against, and the tests of desktop.go. The same in the
+// nextcloud-client and blueman bundles.
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"sync"
+	"syscall"
+	"testing"
+	"time"
+)
+
+const testHome = "/home/operator"
+
+// fake is a machine with a fake root, a scripted Runner and signals that end fake processes.
+type fake struct {
+	*Machine
+	t      *testing.T
+	mu     sync.Mutex
+	calls  []string
+	answer func(name string, args []string) Output
+	// onStart is run when systemd-run starts something, to let a fake process appear.
+	onStart func(argv []string)
+	// stubborn pids ignore SIGTERM.
+	stubborn map[int]bool
+	signals  []string
+}
+
+func newFake(t *testing.T) *fake {
+	t.Helper()
+	root := t.TempDir()
+	f := &fake{t: t, stubborn: map[int]bool{}}
+	f.Machine = &Machine{Root: root, Home: testHome, UID: 1000, Timeout: CallTimeout,
+		Sleep: func(time.Duration) {}, Now: func() time.Time { return time.Unix(1_800_000_000, 0) }}
+	f.Run = func(_ context.Context, env []string, name string, args ...string) Output {
+		f.mu.Lock()
+		f.calls = append(f.calls, strings.TrimSpace(name+" "+strings.Join(args, " ")))
+		f.mu.Unlock()
+		if name == "systemd-run" && f.onStart != nil {
+			for i, a := range args {
+				if a == "--" {
+					f.onStart(args[i+1:])
+				}
+			}
+		}
+		if f.answer != nil {
+			return f.answer(name, args)
+		}
+		return Output{}
+	}
+	f.Kill = func(pid int, sig syscall.Signal) error {
+		f.signals = append(f.signals, strconv.Itoa(pid)+":"+sig.String())
+		if sig == syscall.SIGKILL || !f.stubborn[pid] {
+			return os.RemoveAll(filepath.Join(root, "proc", strconv.Itoa(pid)))
+		}
+		return nil
+	}
+	f.write("/proc/stat", "cpu 1 2 3\nbtime 1799990000\n")
+	return f
+}
+
+func (f *fake) write(path, content string) {
+	f.t.Helper()
+	p := filepath.Join(f.Root, path)
+	if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil {
+		f.t.Fatal(err)
+	}
+	if err := os.WriteFile(p, []byte(content), 0o644); err != nil {
+		f.t.Fatal(err)
+	}
+}
+
+// proc adds a process of uid with a command name, argv, cgroup and environment.
+func (f *fake) proc(pid, uid int, comm string, argv []string, cgroup string, env ...string) {
+	d := "/proc/" + strconv.Itoa(pid) + "/"
+	f.write(d+"comm", comm+"\n")
+	f.write(d+"status", "Name:\t"+comm+"\nUid:\t"+strconv.Itoa(uid)+"\t"+strconv.Itoa(uid)+"\t"+strconv.Itoa(uid)+"\t"+strconv.Itoa(uid)+"\n")
+	f.write(d+"cmdline", strings.Join(argv, "\x00")+"\x00")
+	f.write(d+"cgroup", "0::/user.slice/user-"+strconv.Itoa(uid)+".slice/"+cgroup+"\n")
+	f.write(d+"environ", strings.Join(env, "\x00")+"\x00")
+	// starttime (field 22) is 1000 ticks: 10 s after boot.
+	f.write(d+"stat", strconv.Itoa(pid)+" ("+comm+") S 1 1 1 0 -1 0 0 0 0 0 0 0 0 0 20 0 1 0 1000 0 0\n")
+}
+
+func (f *fake) desktopSession() {
+	f.proc(3700, 1000, "i3", []string{"i3"}, "session-c1.scope", "DISPLAY=:1", "XAUTHORITY="+testHome+"/.Xauthority")
+	f.write("/run/user/1000/bus", "")
+}
+
+func (f *fake) called(prefix string) bool {
+	for _, c := range f.calls {
+		if strings.HasPrefix(c, prefix) {
+			return true
+		}
+	}
+	return false
+}
+
+func TestProcessesAreTheAccountsOwnWithWhereAndWhenTheyStarted(t *testing.T) {
+	f := newFake(t)
+	f.proc(10, 1000, "worker", []string{"/usr/bin/worker", "--background"}, "session-c1.scope")
+	f.proc(11, 1001, "worker", []string{"/usr/bin/worker"}, "session-c2.scope")
+	f.proc(12, 1000, "other", []string{"other"}, "x.scope")
+	got := f.procs("worker")
+	if len(got) != 1 || got[0].PID != 10 || got[0].Command != "/usr/bin/worker --background" ||
+		got[0].StartedIn != "session-c1.scope" || got[0].Since != time.Unix(1799990010, 0).UTC().Format(time.RFC3339) {
+		t.Fatalf("%+v", got)
+	}
+}
+
+func TestTheSessionIsTheWindowManagersAndNoneIsSaidPlainly(t *testing.T) {
+	f := newFake(t)
+	if _, err := f.session(); err == nil || !strings.Contains(err.Error(), "no graphical session") {
+		t.Fatalf("%v", err)
+	}
+	f.proc(50, 1000, "xterm", []string{"xterm"}, "s.scope", "DISPLAY=:9")
+	f.desktopSession()
+	f.proc(60, 1001, "i3", []string{"i3"}, "s.scope", "DISPLAY=:5")
+	s, err := f.session()
+	if err != nil || s.Display != ":1" || s.XAuthority != testHome+"/.Xauthority" || s.Bus != "unix:path=/run/user/1000/bus" ||
+		!strings.Contains(s.From, "i3") {
+		t.Fatalf("%+v %v", s, err)
+	}
+}
+
+func TestStopAsksThenForcesAndDetachStartsUnderTheServiceManager(t *testing.T) {
+	f := newFake(t)
+	f.desktopSession()
+	f.proc(20, 1000, "app", []string{"app"}, "s.scope")
+	f.proc(21, 1000, "app", []string{"app"}, "s.scope")
+	f.stubborn[21] = true
+	ended, killed := f.stop(time.Second, "app")
+	if len(ended) != 1 || ended[0] != 20 || len(killed) != 1 || killed[0] != 21 {
+		t.Fatalf("ended %v killed %v (%v)", ended, killed, f.signals)
+	}
+	s, _ := f.session()
+	if err := f.detach(s, "mesh-app", "/usr/bin/app", "--background"); err != nil {
+		t.Fatal(err)
+	}
+	want := "systemd-run --user --collect --quiet --unit=mesh-app --setenv=DISPLAY=:1 --setenv=XAUTHORITY=" + testHome +
+		"/.Xauthority -- /usr/bin/app --background"
+	if !f.called("systemctl --user stop mesh-app.service") || !f.called(want) {
+		t.Fatalf("%q", f.calls)
+	}
+}
+
+func TestAnAutostartEntryOfTheAccountOverridesTheSystemsAndHiddenStartsNothing(t *testing.T) {
+	f := newFake(t)
+	if a := f.autostart("x.desktop"); a.Starts || a.Because == "" {
+		t.Fatalf("%+v", a)
+	}
+	f.write("/etc/xdg/autostart/x.desktop", "[Desktop Entry]\nExec=x-applet\n[Desktop Action y]\nExec=other\n")
+	if a := f.autostart("x.desktop"); !a.Starts || a.Exec != "x-applet" || a.From != "/etc/xdg/autostart/x.desktop" {
+		t.Fatalf("%+v", a)
+	}
+	f.write(testHome+"/.config/autostart/x.desktop", "[Desktop Entry]\nExec=x-applet\nHidden=true\n")
+	if a := f.autostart("x.desktop"); a.Starts || a.Because != "Hidden=true" || a.From != "~/.config/autostart/x.desktop" {
+		t.Fatalf("%+v", a)
+	}
+}
+
+func TestAWindowManagerStartIsFoundInTheConfigurationAndItsDropIns(t *testing.T) {
+	f := newFake(t)
+	f.write(testHome+"/.config/i3/config", "exec --no-startup-id dex --autostart --environment i3\n# exec app\nbindsym $mod+a exec app\n")
+	f.write(testHome+"/.config/i3/config.d/50-x.conf", "exec_always --no-startup-id /usr/bin/app --flag\n")
+	got := f.i3Starts("app")
+	if len(got) != 1 || got[0] != "~/.config/i3/config.d/50-x.conf:1: exec_always --no-startup-id /usr/bin/app --flag" {
+		t.Fatalf("%q", got)
+	}
+}
+
+func TestACommandThatFailsIsNamed(t *testing.T) {
+	if err := failed(Output{Code: 127, Err: ErrNotInstalled}, "dex"); err == nil || !strings.Contains(err.Error(), "dex is not installed") {
+		t.Fatal(err)
+	}
+	if err := failed(Output{Code: 1, Stderr: "nope"}, "pacman", "-Q", "x"); err == nil || !strings.Contains(err.Error(), "pacman -Q x exited 1: nope") {
+		t.Fatal(err)
+	}
+	if err := failed(Output{}, "true"); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestTheRealRunnerBoundsTimeAndOutput(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), 200*time.Millisecond)
+	defer cancel()
+	if o := execRun(ctx, nil, "sleep", "5"); o.Err != ErrTimedOut {
+		t.Fatalf("%+v", o)
+	}
+	if o := execRun(context.Background(), nil, "no-such-program-here"); o.Err != ErrNotInstalled {
+		t.Fatalf("%+v", o)
+	}
+	o := execRun(context.Background(), nil, "head", "-c", strconv.Itoa(MostOutput+10), "/dev/zero")
+	if !o.Cut || len(o.Stdout) != MostOutput {
+		t.Fatalf("cut %v, %d bytes", o.Cut, len(o.Stdout))
+	}
+}

modules/nextcloud-client/cmd/nextcloud-client-tools/main.go

@@ -0,0 +1,81 @@
+// The nextcloud-client module's Go tools bundle (novox/hq ADR 0188, ADR 0193, ADR 0208): the
+// Nextcloud desktop sync client in the operator's session, served by the node's runtime as the
+// operator account. The module holds no seat, so every tool is its own.
+//
+// The client's account configuration is the operator's: the tools read the client's own files and
+// never write them, and no answer carries the server's address, the account's ids or a credential.
+package main
+
+import (
+	"fmt"
+	"os"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+func main() {
+	if err := stdio.Serve("", tools()); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+var machine = NewMachine()
+
+func tools() []stdio.Tool {
+	return []stdio.Tool{
+		{
+			Name: "nextcloud_status",
+			Description: "The Nextcloud desktop client: whether it runs (pid, since, and the unit or session scope " +
+				"it runs in), the installed version, what starts it at login, each account by name (never the " +
+				"server's address or a credential) with its sync folders' local paths, remote paths, paused, and " +
+				"the last sync run (started, finished, items, errors and the first failing files), and the latest " +
+				"warnings in the client's log. (r)",
+			Run: func(map[string]any) (any, error) { return machine.Status() },
+		},
+		{
+			Name: "nextcloud_log",
+			Description: "The last lines of the client's log (source client, the default) or of the sync runs' " +
+				"log (source sync, file by file), newest last. With problems, only warnings and worse. The " +
+				"server's address and the account's ids are replaced by <server> and <account>. (r)",
+			Input: map[string]any{
+				"lines":    map[string]any{"type": "integer", "description": "how many lines (default 100, at most 2000)"},
+				"source":   map[string]any{"type": "string", "enum": []string{"client", "sync"}, "description": "client (default) or sync"},
+				"problems": map[string]any{"type": "boolean", "description": "only warning, critical and fatal lines of the client's log (default false)"},
+			},
+			Run: func(args map[string]any) (any, error) {
+				n, err := whole(args, "lines", 100, 1, 2000)
+				if err != nil {
+					return nil, err
+				}
+				source, err := text(args, "source", false)
+				if err != nil {
+					return nil, err
+				}
+				if source == "" {
+					source = "client"
+				}
+				problems, err := flag(args, "problems", false)
+				if err != nil {
+					return nil, err
+				}
+				return machine.Log(source, n, problems)
+			},
+		},
+		{
+			Name: "nextcloud_restart",
+			Description: "End the running client (asked first, then forced after 6 s) and start it again in the " +
+				"operator's desktop session, in the tray, under the account's service manager. Answers the pids " +
+				"ended and the new one. Needs someone logged in to the desktop. (a)",
+			Run: func(map[string]any) (any, error) { return machine.Restart() },
+		},
+		{
+			Name: "nextcloud_check",
+			Description: "Check what the module promises: the package is installed; the client has exactly one " +
+				"start (its own XDG autostart entry, which the session's dex runs; no window-manager exec, no " +
+				"enabled user unit); it runs once in a desktop session; it has an account and its folders exist " +
+				"and are not paused. Answers ok and each finding with what to do. (r)",
+			Run: func(map[string]any) (any, error) { return machine.Check() },
+		},
+	}
+}

modules/nextcloud-client/cmd/nextcloud-client-tools/manifest_test.go

@@ -0,0 +1,108 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+// nextcloud-client's shape (novox/hq ADR 0208, ADR 0210, ADR 0182): one official package, no seat,
+// the X display on its own machine, no start of its own (the client's own autostart entry is the one
+// start), no file of the client's, and the Go bundle serving exactly the listed nextcloud_ tools.
+
+type manifest struct {
+	Module        string           `json:"module"`
+	Version       string           `json:"version"`
+	Capabilities  []string         `json:"capabilities"`
+	Requires      []string         `json:"requires"`
+	Tools         []string         `json:"tools"`
+	Resources     []map[string]any `json:"resources"`
+	Claims        []any            `json:"claims"`
+	Seats         []any            `json:"seats"`
+	Shell         []any            `json:"shell"`
+	Contributions []any            `json:"contributions"`
+	Environment   any              `json:"environment"`
+	Build         struct {
+		Artifacts []map[string]any `json:"artifacts"`
+	} `json:"build"`
+}
+
+func readManifest(t *testing.T) (manifest, string) {
+	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, string(raw)
+}
+
+func TestItInstallsTheClientAndNothingElse(t *testing.T) {
+	m, _ := readManifest(t)
+	if m.Module != "nextcloud-client" || !reflect.DeepEqual(m.Requires, []string{"x11-display"}) ||
+		!reflect.DeepEqual(m.Capabilities, []string{"package-manager"}) {
+		t.Fatalf("%+v", m)
+	}
+	if len(m.Resources) != 1 || m.Resources[0]["type"] != "package" || m.Resources[0]["package"] != packageFor {
+		t.Fatalf("resources: %v", m.Resources)
+	}
+	if m.Claims != nil || m.Seats != nil || m.Environment != nil {
+		t.Fatal("it holds no seat and sets no environment")
+	}
+}
+
+func TestItAddsNoSecondStartAndOwnsNoneOfTheClientsFiles(t *testing.T) {
+	m, raw := readManifest(t)
+	// The client writes its own XDG autostart entry, which the session's dex runs: an xinitrc slot
+	// or a window-manager exec would start it twice.
+	if m.Shell != nil || m.Contributions != nil {
+		t.Fatalf("a second start: shell %v, contributions %v", m.Shell, m.Contributions)
+	}
+	for _, never := range []string{"nextcloud.cfg", "autostart", "service"} {
+		if strings.Contains(raw, never) {
+			t.Errorf("module.json names %q: the client's files and start are its own", never)
+		}
+	}
+}
+
+func TestTheToolsAgreeWithTheManifest(t *testing.T) {
+	m, raw := readManifest(t)
+	served := map[string]bool{}
+	for _, tool := range tools() {
+		served[tool.Name] = true
+		if !strings.HasPrefix(tool.Name, "nextcloud_") || strings.TrimSpace(tool.Description) == "" {
+			t.Errorf("%s: prefixed nextcloud_ and described", tool.Name)
+		}
+	}
+	for _, name := range m.Tools {
+		if !served[name] {
+			t.Errorf("module.json lists %s, which the bundle does not serve", name)
+		}
+		delete(served, name)
+	}
+	for name := range served {
+		t.Errorf("the bundle serves %s, which module.json does not list", name)
+	}
+	if len(m.Build.Artifacts) != 1 {
+		t.Fatalf("%v", m.Build.Artifacts)
+	}
+	b := m.Build.Artifacts[0]
+	if b["kind"] != "bundle" || b["language"] != "go" || b["system"] != "arch" ||
+		b["from"] != "cmd/nextcloud-client-tools" || b["binary"] != "nextcloud-client-tools" {
+		t.Errorf("the Go tools bundle: %v", b)
+	}
+	s := strings.ToLower(raw)
+	for _, never := range []string{"/home/", "jochen", "g14", "shanks", "novox.be", "http", "password", "token"} {
+		if strings.Contains(s, never) {
+			t.Errorf("module.json names %q", never)
+		}
+	}
+}

modules/nextcloud-client/cmd/nextcloud-client-tools/nextcloud.go

@@ -0,0 +1,667 @@
+package main
+
+// The Nextcloud desktop client as the tools see it, read from the client's own files only:
+//   - ~/.config/Nextcloud/nextcloud.cfg, the client's settings (Qt's INI form), which the client
+//     rewrites and the module never writes. Accounts and sync folders are read from it. The server's
+//     address, the account's user ids and every credential-like key are never answered: they are
+//     read only to be hidden in what the log tools answer;
+//   - the sync-run log of each folder (<appdata>/Nextcloud/*_sync.log), whose first line is the
+//     folder's local path, and whose run markers and per-file lines give the last sync's state and
+//     errors;
+//   - the client's log directory, ~/.config/Nextcloud/logs, rotated by the client every two hours
+//     (the newest file plain, the older ones gzipped).
+
+import (
+	"bufio"
+	"bytes"
+	"compress/gzip"
+	"fmt"
+	"io"
+	"net/url"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// Where the client keeps things, under the operator's home.
+const (
+	configFile = ".config/Nextcloud/nextcloud.cfg"
+	logDir     = ".config/Nextcloud/logs"
+	entryName  = "Nextcloud.desktop"
+	clientComm = "nextcloud"
+	clientBin  = "/usr/bin/nextcloud"
+	restartAs  = "mesh-nextcloud-client"
+	packageFor = "nextcloud-client"
+	userUnit   = "com.nextcloud.desktopclient.nextcloud.service"
+)
+
+// syncLogDirs are where the client has kept its sync-run logs, newest convention first.
+var syncLogDirs = []string{".local/share/Nextcloud", ".config/Nextcloud"}
+
+// ini is a Qt INI file: section → key → value. Keys keep Qt's backslash-separated groups.
+type ini map[string]map[string]string
+
+func parseINI(raw []byte) ini {
+	out := ini{}
+	section := "General"
+	s := bufio.NewScanner(bytes.NewReader(raw))
+	s.Buffer(make([]byte, 64<<10), 4<<20) // a certificate is one long line
+	for s.Scan() {
+		l := strings.TrimSpace(s.Text())
+		if l == "" || strings.HasPrefix(l, ";") || strings.HasPrefix(l, "#") {
+			continue
+		}
+		if strings.HasPrefix(l, "[") && strings.HasSuffix(l, "]") {
+			section = l[1 : len(l)-1]
+			continue
+		}
+		i := strings.IndexByte(l, '=')
+		if i <= 0 {
+			continue
+		}
+		v := strings.TrimSpace(l[i+1:])
+		if len(v) >= 2 && v[0] == '"' && v[len(v)-1] == '"' {
+			v = v[1 : len(v)-1]
+		}
+		if out[section] == nil {
+			out[section] = map[string]string{}
+		}
+		out[section][strings.TrimSpace(l[:i])] = v
+	}
+	return out
+}
+
+// Folder is one sync folder as the client is configured.
+type Folder struct {
+	LocalPath    string `json:"-"`
+	Local        string `json:"local_path"`
+	RemotePath   string `json:"remote_path"`
+	Paused       bool   `json:"paused"`
+	VirtualFiles string `json:"virtual_files,omitempty"`
+	Journal      string `json:"-"`
+	JournalFound bool   `json:"journal_found"`
+	LastSync     *Run   `json:"last_sync,omitempty"`
+}
+
+// Account is one account, by name only.
+type Account struct {
+	ID      string   `json:"id"`
+	Name    string   `json:"name"`
+	Auth    string   `json:"auth,omitempty"`
+	Folders []Folder `json:"folders"`
+	// hidden are the values never answered: the server's host and the account's user ids.
+	hosts []string
+	users []string
+}
+
+// Config is what the tools read from nextcloud.cfg.
+type Config struct {
+	Found           bool      `json:"found"`
+	ClientVersion   string    `json:"client_version,omitempty"`
+	LaunchAtStartup *bool     `json:"launch_on_system_startup,omitempty"`
+	Accounts        []Account `json:"accounts"`
+}
+
+func (m *Machine) config() (Config, error) {
+	raw, err := readBounded(m.home(configFile))
+	if os.IsNotExist(err) {
+		return Config{Accounts: []Account{}}, nil
+	}
+	if err != nil {
+		return Config{}, fmt.Errorf("reading the client's settings: %w", err)
+	}
+	f := parseINI(raw)
+	c := Config{Found: true, ClientVersion: f["General"]["clientVersion"], Accounts: []Account{}}
+	if v, ok := f["General"]["launchOnSystemStartup"]; ok {
+		b := v == "true"
+		c.LaunchAtStartup = &b
+	}
+	byID := map[string]*Account{}
+	folders := map[string]map[string]*Folder{}
+	var ids []string
+	for k, v := range f["Accounts"] {
+		parts := strings.Split(k, `\`)
+		if len(parts) < 2 {
+			continue
+		}
+		id := parts[0]
+		if _, err := strconv.Atoi(id); err != nil {
+			continue
+		}
+		a := byID[id]
+		if a == nil {
+			a = &Account{ID: id, Folders: []Folder{}}
+			byID[id] = a
+			folders[id] = map[string]*Folder{}
+			ids = append(ids, id)
+		}
+		if len(parts) == 2 {
+			switch parts[1] {
+			case "displayName":
+				a.Name = v
+			case "authType":
+				a.Auth = v
+			case "url":
+				if u, err := url.Parse(v); err == nil && u.Host != "" {
+					a.hosts = append(a.hosts, u.Host)
+					if u.Hostname() != u.Host {
+						a.hosts = append(a.hosts, u.Hostname())
+					}
+				}
+			case "user", "dav_user", "webflow_user", "http_user":
+				if v != "" {
+					a.users = append(a.users, v)
+				}
+			}
+			continue
+		}
+		// <id>\Folders\<n>\<key>, and the other folder groups (FoldersWithPlaceholders, Multifolders).
+		if len(parts) == 4 && strings.HasPrefix(parts[1], "Folders") || len(parts) == 4 && parts[1] == "Multifolders" {
+			key := parts[1] + `\` + parts[2]
+			fo := folders[id][key]
+			if fo == nil {
+				fo = &Folder{}
+				folders[id][key] = fo
+			}
+			switch parts[3] {
+			case "localPath":
+				fo.LocalPath = v
+			case "targetPath":
+				fo.RemotePath = v
+			case "paused":
+				fo.Paused = v == "true"
+			case "virtualFilesMode":
+				fo.VirtualFiles = v
+			case "journalPath":
+				fo.Journal = v
+			}
+		}
+	}
+	sort.Strings(ids)
+	for _, id := range ids {
+		a := byID[id]
+		if a.Name == "" {
+			a.Name = "account " + id
+		}
+		var keys []string
+		for k := range folders[id] {
+			keys = append(keys, k)
+		}
+		sort.Strings(keys)
+		for _, k := range keys {
+			fo := *folders[id][k]
+			if fo.LocalPath == "" {
+				continue
+			}
+			fo.Local = m.tilde(fo.LocalPath)
+			if fo.Journal != "" {
+				fo.JournalFound = exists(filepath.Join(m.Root, fo.LocalPath, fo.Journal))
+			}
+			a.Folders = append(a.Folders, fo)
+		}
+		c.Accounts = append(c.Accounts, *a)
+	}
+	return c, nil
+}
+
+// redactor hides what an answer must never carry: the servers' hosts, the accounts' user ids, and
+// anything shaped like a credential.
+type redactor struct{ hosts, users []string }
+
+var credential = regexp.MustCompile(`(?i)\b(authorization|bearer|basic|token|apppassword|app_password|password|passwd|secret|cookie|set-cookie)(["']?\s*[:=]\s*["']?|\s+)(?:(?:bearer|basic)\s+)?[^\s"',;&]+`)
+
+func (c Config) redactor() redactor {
+	var r redactor
+	for _, a := range c.Accounts {
+		r.hosts = append(r.hosts, a.hosts...)
+		r.users = append(r.users, a.users...)
+	}
+	// Longest first, so a host's port form is replaced before its bare name.
+	sort.Slice(r.hosts, func(i, j int) bool { return len(r.hosts[i]) > len(r.hosts[j]) })
+	sort.Slice(r.users, func(i, j int) bool { return len(r.users[i]) > len(r.users[j]) })
+	return r
+}
+
+func (r redactor) clean(s string) string {
+	s = credential.ReplaceAllString(s, "${1}${2}<hidden>")
+	for _, u := range r.users {
+		s = strings.ReplaceAll(s, u, "<account>")
+	}
+	for _, h := range r.hosts {
+		s = strings.ReplaceAll(s, h, "<server>")
+	}
+	return s
+}
+
+// Run is one folder's last sync run, from its sync-run log.
+type Run struct {
+	Started  string `json:"started,omitempty"`
+	Finished string `json:"finished,omitempty"`
+	// State is "finished", "running", or "never" when the log has no run.
+	State    string    `json:"state"`
+	Changes  int       `json:"items"`
+	Errors   int       `json:"errors"`
+	Problems []Problem `json:"problems,omitempty"`
+	Log      string    `json:"log"`
+}
+
+// Problem is one item of a run that ended with an error.
+type Problem struct {
+	File  string `json:"file"`
+	Error string `json:"error"`
+	HTTP  string `json:"http,omitempty"`
+}
+
+const mostProblems = 10
+
+// syncLogFor finds the sync-run log whose first line is the folder's local path; the newest wins.
+func (m *Machine) syncLogFor(local string) string {
+	want := strings.TrimSuffix(local, "/")
+	best, bestAt := "", time.Time{}
+	for _, d := range syncLogDirs {
+		files, _ := filepath.Glob(m.home(d, "*_sync.log"))
+		for _, f := range files {
+			h, err := os.Open(f)
+			if err != nil {
+				continue
+			}
+			first, _ := bufio.NewReader(io.LimitReader(h, 4096)).ReadString('\n')
+			h.Close()
+			if strings.TrimSuffix(strings.TrimSpace(first), "/") != want {
+				continue
+			}
+			if st, err := os.Stat(f); err == nil && st.ModTime().After(bestAt) {
+				best, bestAt = f, st.ModTime()
+			}
+		}
+	}
+	return best
+}
+
+// lastRun reads the end of a sync-run log: the last run's markers and its items.
+func (m *Machine) lastRun(path string, r redactor) (*Run, error) {
+	lines, err := tailLines(path, 4000)
+	if err != nil {
+		return nil, err
+	}
+	run := &Run{State: "never", Log: m.tilde(strings.TrimPrefix(path, m.Root))}
+	start := -1
+	for i := len(lines) - 1; i >= 0; i-- {
+		if strings.HasPrefix(lines[i], "#=#=#=# Syncrun started ") {
+			start = i
+			break
+		}
+	}
+	if start < 0 {
+		return run, nil
+	}
+	run.Started = marker(lines[start], "#=#=#=# Syncrun started ")
+	run.State = "running"
+	for _, l := range lines[start+1:] {
+		switch {
+		case strings.HasPrefix(l, "#=#=#=# Syncrun finished "):
+			run.Finished = marker(l, "#=#=#=# Syncrun finished ")
+			run.State = "finished"
+		case strings.HasPrefix(l, "#"):
+		default:
+			f := strings.Split(l, "|")
+			if len(f) < 12 {
+				continue
+			}
+			run.Changes++
+			if e := strings.TrimSpace(f[10]); e != "" {
+				run.Errors++
+				if len(run.Problems) < mostProblems {
+					run.Problems = append(run.Problems, Problem{File: r.clean(f[2]), Error: r.clean(e), HTTP: strings.TrimSpace(f[11])})
+				}
+			}
+		}
+	}
+	return run, nil
+}
+
+func marker(line, prefix string) string {
+	f := strings.Fields(strings.TrimPrefix(line, prefix))
+	if len(f) == 0 {
+		return ""
+	}
+	return f[0]
+}
+
+// tailLines answers the last n lines of a file, plain or gzipped, read to at most MostRead.
+func tailLines(path string, n int) ([]string, error) {
+	h, err := os.Open(path)
+	if err != nil {
+		return nil, err
+	}
+	defer h.Close()
+	var r io.Reader = h
+	if strings.HasSuffix(path, ".gz") {
+		z, err := gzip.NewReader(h)
+		if err != nil {
+			return nil, fmt.Errorf("%s: %w", filepath.Base(path), err)
+		}
+		defer z.Close()
+		r = z
+	} else if st, err := h.Stat(); err == nil && st.Size() > MostRead {
+		// A plain file is read from its end.
+		if _, err := h.Seek(st.Size()-MostRead, io.SeekStart); err != nil {
+			return nil, err
+		}
+	}
+	raw, err := io.ReadAll(io.LimitReader(r, MostRead))
+	if err != nil {
+		return nil, err
+	}
+	all := strings.Split(strings.TrimRight(string(raw), "\n"), "\n")
+	if len(all) == 1 && all[0] == "" {
+		all = nil
+	}
+	if len(all) > n {
+		all = all[len(all)-n:]
+	}
+	return all, nil
+}
+
+// clientLogs are the client's log files, newest first.
+func (m *Machine) clientLogs() []string {
+	entries, err := os.ReadDir(m.home(logDir))
+	if err != nil {
+		return nil
+	}
+	type file struct {
+		path string
+		at   time.Time
+	}
+	var files []file
+	for _, e := range entries {
+		// The client's own log, not its permanent-delete records beside it.
+		if e.IsDir() || !strings.Contains(e.Name(), "_nextcloud.log") {
+			continue
+		}
+		if info, err := e.Info(); err == nil {
+			files = append(files, file{m.home(logDir, e.Name()), info.ModTime()})
+		}
+	}
+	sort.Slice(files, func(i, j int) bool { return files[i].at.After(files[j].at) })
+	out := make([]string, len(files))
+	for i, f := range files {
+		out[i] = f.path
+	}
+	return out
+}
+
+// level is a client log line's level: "[ warning category file:line ]:" → warning.
+func level(line string) string {
+	i := strings.Index(line, "[ ")
+	if i < 0 {
+		return ""
+	}
+	f := strings.Fields(line[i+2:])
+	if len(f) == 0 {
+		return ""
+	}
+	return f[0]
+}
+
+func isProblem(line string) bool {
+	switch level(line) {
+	case "warning", "critical", "fatal":
+		return true
+	}
+	return false
+}
+
+// LogAnswer is what nextcloud_log answers.
+type LogAnswer struct {
+	Source string   `json:"source"`
+	Files  []string `json:"files"`
+	Lines  []string `json:"lines"`
+	Cut    bool     `json:"cut,omitempty"`
+	Note   string   `json:"note,omitempty"`
+}
+
+const mostAnswer = 256 << 10
+
+// Log answers the last n lines of the client's log (or only its warnings and worse), or of the sync
+// runs' log, the server's address and the account's ids hidden.
+func (m *Machine) Log(source string, n int, problemsOnly bool) (LogAnswer, error) {
+	c, err := m.config()
+	if err != nil {
+		return LogAnswer{}, err
+	}
+	r := c.redactor()
+	a := LogAnswer{Source: source, Files: []string{}, Lines: []string{}}
+	var files []string
+	switch source {
+	case "client":
+		files = m.clientLogs()
+		if len(files) == 0 {
+			a.Note = "the client keeps no log files in ~/" + logDir + ": it writes them there only while its logging is switched on"
+			return a, nil
+		}
+	case "sync":
+		for _, acc := range c.Accounts {
+			for _, f := range acc.Folders {
+				if p := m.syncLogFor(f.LocalPath); p != "" {
+					files = append(files, p)
+				}
+			}
+		}
+		if len(files) == 0 {
+			a.Note = "no sync-run log found for any configured folder"
+			return a, nil
+		}
+	default:
+		return a, fmt.Errorf("source is client or sync, not %q", source)
+	}
+	// The newest file first; older ones until n lines are found, at most four files.
+	var got []string
+	for i, f := range files {
+		if i == 4 || len(got) >= n {
+			break
+		}
+		lines, err := tailLines(f, 1<<20)
+		if err != nil {
+			return a, err
+		}
+		if problemsOnly {
+			var keep []string
+			for _, l := range lines {
+				if isProblem(l) {
+					keep = append(keep, l)
+				}
+			}
+			lines = keep
+		}
+		if len(lines) > n-len(got) {
+			lines = lines[len(lines)-(n-len(got)):]
+		}
+		got = append(lines, got...)
+		a.Files = append(a.Files, m.tilde(strings.TrimPrefix(f, m.Root)))
+		if source == "sync" {
+			// Each folder's log is its own story: the newest folder's only, unless asked again.
+			break
+		}
+	}
+	size := 0
+	for i := len(got) - 1; i >= 0; i-- {
+		l := r.clean(got[i])
+		if size+len(l) > mostAnswer {
+			a.Cut = true
+			got = got[i+1:]
+			break
+		}
+		size += len(l) + 1
+		got[i] = l
+	}
+	if got == nil {
+		got = []string{}
+	}
+	a.Lines = got
+	return a, nil
+}
+
+// Status is what nextcloud_status answers.
+type Status struct {
+	Installed string    `json:"installed,omitempty"`
+	Running   []Proc    `json:"running"`
+	Config    Config    `json:"settings"`
+	Problems  []string  `json:"recent_client_problems"`
+	StartedBy Autostart `json:"started_by"`
+}
+
+// Status reads the client: whether it runs, its accounts and folders with their last sync, and the
+// warnings and worse at the end of its log.
+func (m *Machine) Status() (Status, error) {
+	c, err := m.config()
+	if err != nil {
+		return Status{}, err
+	}
+	r := c.redactor()
+	s := Status{Running: m.procs(clientComm), Config: c, Problems: []string{}, StartedBy: m.autostart(entryName)}
+	if s.Running == nil {
+		s.Running = []Proc{}
+	}
+	if v, err := m.installed(packageFor); err == nil {
+		s.Installed = v
+	}
+	for ai := range s.Config.Accounts {
+		for fi := range s.Config.Accounts[ai].Folders {
+			f := &s.Config.Accounts[ai].Folders[fi]
+			if p := m.syncLogFor(f.LocalPath); p != "" {
+				if run, err := m.lastRun(p, r); err == nil {
+					f.LastSync = run
+				}
+			}
+		}
+	}
+	// The two newest files: the log rotates every two hours, and may just have.
+	logs := m.clientLogs()
+	if len(logs) > 2 {
+		logs = logs[:2]
+	}
+	for i := len(logs) - 1; i >= 0; i-- {
+		if lines, err := tailLines(logs[i], 1<<20); err == nil {
+			for _, l := range lines {
+				if isProblem(l) {
+					s.Problems = append(s.Problems, r.clean(l))
+				}
+			}
+		}
+	}
+	if len(s.Problems) > 10 {
+		s.Problems = s.Problems[len(s.Problems)-10:]
+	}
+	return s, nil
+}
+
+// RestartAnswer is what nextcloud_restart answers.
+type RestartAnswer struct {
+	Ended   []int   `json:"ended"`
+	Killed  []int   `json:"killed,omitempty"`
+	Running []Proc  `json:"running"`
+	Session Session `json:"session"`
+	Unit    string  `json:"unit"`
+}
+
+// Restart ends the running client and starts it again in the operator's session, under the account's
+// service manager, as its autostart entry does (--background: to the tray, no window).
+func (m *Machine) Restart() (RestartAnswer, error) {
+	s, err := m.session()
+	if err != nil {
+		return RestartAnswer{}, err
+	}
+	a := RestartAnswer{Session: s, Unit: restartAs + ".service"}
+	a.Ended, a.Killed = m.stop(6*time.Second, clientComm)
+	if err := m.detach(s, restartAs, clientBin, "--background"); err != nil {
+		return a, err
+	}
+	a.Running = m.waitFor(clientComm, 4*time.Second)
+	if len(a.Running) == 0 {
+		return a, fmt.Errorf("the client was started as %s but no %s process appeared within 4 s: "+
+			"see `journalctl --user -u %s`", a.Unit, clientComm, a.Unit)
+	}
+	return a, nil
+}
+
+// CheckAnswer is what nextcloud_check answers.
+type CheckAnswer struct {
+	OK       bool      `json:"ok"`
+	Findings []Finding `json:"findings"`
+	Starts   []string  `json:"starts"`
+}
+
+// Check verifies the module's promises: the package, one start (the client's own autostart entry,
+// which the session's dex runs), the client running once in a session, and its folders present.
+func (m *Machine) Check() (CheckAnswer, error) {
+	a := CheckAnswer{Findings: []Finding{}, Starts: []string{}}
+	add := func(what, do string) { a.Findings = append(a.Findings, Finding{what, do}) }
+	v, err := m.installed(packageFor)
+	if err != nil {
+		return a, err
+	}
+	if v == "" {
+		add("the package "+packageFor+" is not installed", "push the module to the node")
+	}
+	c, err := m.config()
+	if err != nil {
+		return a, err
+	}
+	entry := m.autostart(entryName)
+	if entry.Starts {
+		a.Starts = append(a.Starts, "XDG autostart: "+entry.From)
+		if !strings.Contains(entry.Exec, clientComm) {
+			add("the autostart entry runs "+entry.Exec+", not the client", "untick and tick again 'Launch on system startup' in the client's settings")
+		}
+	} else {
+		add("the client does not start with the session ("+entry.Because+")",
+			"tick 'Launch on system startup' in the client's General settings: the client writes its own entry")
+	}
+	if c.LaunchAtStartup != nil && !*c.LaunchAtStartup && entry.Starts {
+		add("the client's setting says not to launch at startup, but its autostart entry is there", "tick and untick the setting, or remove ~/.config/autostart/"+entryName)
+	}
+	if o := m.cmd(0, nil, "dex", "--version"); o.Err != nil {
+		add("dex, which runs the XDG autostart entries at login, is not installed", "assign the i3 module, which installs it and runs it")
+	}
+	for _, l := range m.i3Starts(clientComm) {
+		a.Starts = append(a.Starts, "window manager: "+l)
+		add("a second start: "+l, "remove the line; the autostart entry is the client's one start")
+	}
+	if o := m.cmd(0, m.bus(), "systemctl", "--user", "is-enabled", userUnit); o.Err == nil && strings.TrimSpace(o.Stdout) == "enabled" {
+		a.Starts = append(a.Starts, "user unit: "+userUnit)
+		add("a second start: the packaged user unit "+userUnit+" is enabled", "systemctl --user disable "+userUnit)
+	}
+	running := m.procs(clientComm)
+	if _, err := m.session(); err == nil {
+		switch {
+		case len(running) == 0:
+			add("no client runs in the desktop session", "nextcloud_restart")
+		case len(running) > 1:
+			add(fmt.Sprintf("%d clients run", len(running)), "nextcloud_restart ends them all and starts one")
+		}
+	}
+	if !c.Found {
+		add("the client has no settings yet (~/"+configFile+")", "open the client and add the account: its configuration is the operator's")
+	} else if len(c.Accounts) == 0 {
+		add("the client has no account", "add the account in the client")
+	}
+	for _, acc := range c.Accounts {
+		for _, f := range acc.Folders {
+			if !exists(filepath.Join(m.Root, f.LocalPath)) {
+				add("the sync folder "+m.tilde(f.LocalPath)+" of "+acc.Name+" does not exist", "recreate it, or remove the folder from the client")
+			} else if f.Journal != "" && !f.JournalFound {
+				add("the sync folder "+m.tilde(f.LocalPath)+" has no sync journal yet", "it is written at the first sync")
+			}
+			if f.Paused {
+				add("the sync folder "+m.tilde(f.LocalPath)+" is paused", "resume it in the client")
+			}
+		}
+	}
+	a.OK = len(a.Findings) == 0
+	return a, nil
+}

modules/nextcloud-client/cmd/nextcloud-client-tools/nextcloud_test.go

@@ -0,0 +1,269 @@
+package main
+
+import (
+	"bytes"
+	"compress/gzip"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+// A client's settings as the client writes them, with a certificate, a server and user ids that no
+// answer may carry.
+const cfg = `[General]
+clientVersion=34.0.4daily
+launchOnSystemStartup=true
+
+[Accounts]
+0\Folders\1\journalPath=.sync_abc.db
+0\Folders\1\localPath=/home/operator/Nextcloud/
+0\Folders\1\paused=false
+0\Folders\1\targetPath=/
+0\Folders\1\virtualFilesMode=off
+0\Folders\2\localPath=/home/operator/Photos/
+0\Folders\2\paused=true
+0\Folders\2\targetPath=/Photos
+0\General\CaCertificates="@ByteArray(-----BEGIN CERTIFICATE-----\nMIIE6zCC\n-----END CERTIFICATE-----)"
+0\authType=webflow
+0\dav_user=kc-1234-uid
+0\displayName=The Operator
+0\url=https://cloud.example.test:8443
+0\user=kc-1234-uid@cloud.example.test
+0\webflow_user=kc-1234-uid
+version=13
+`
+
+const syncLog = `/home/operator/Nextcloud/
+# timestamp | duration | file | instruction | dir | modtime | etag | size | fileId | status | errorString | http result code | other size | other modtime | X-Request-ID
+#=#=#=# Syncrun started 2026-10-05T07:27:35Z
+||old.md|2|2|1|e|1|i|13||0|1|1||
+#=#=#=# Syncrun finished 2026-10-05T07:27:35Z (last step: 16 msec, total: 170 msec)
+#=#=#=# Syncrun started 2026-10-05T09:27:40Z
+#=#=#=#=# Propagation starts 2026-10-05T09:27:40Z (last step: 131 msec, total: 131 msec)
+13:58:53||Notes/a.md|8|1|1|e|1|i|13||201|0|0|r|
+13:58:54||Notes/b.md|8|1|1|e|1|i|13|"/Notes/b.md" is locked|423|0|0|r|
+13:58:55||kc-1234-uid/c.md|8|1|1|e|1|i|13|File has changed since discovery|200|0|0|r|
+#=#=#=# Syncrun finished 2026-10-05T09:27:40Z (last step: 17 msec, total: 148 msec)
+`
+
+func clientLine(level, text string) string {
+	return "2026-10-05 11:27:41:151 [ " + level + " nextcloud.gui.folder /src/folder.cpp:1 ]:\t" + text
+}
+
+func newClient(t *testing.T) *fake {
+	f := newFake(t)
+	f.write(testHome+"/"+configFile, cfg)
+	f.write(testHome+"/Nextcloud/.sync_abc.db", "")
+	f.write(testHome+"/.local/share/Nextcloud/Nextcloud_sync.log", syncLog)
+	// An older log of the same folder, in the old place: the newer one wins.
+	f.write(testHome+"/.config/Nextcloud/Nextcloud_sync.log", "/home/operator/Nextcloud/\n#=#=#=# Syncrun started 2023-11-17T00:00:00Z\n")
+	old := filepath.Join(f.Root, testHome, ".config/Nextcloud/Nextcloud_sync.log")
+	_ = os.Chtimes(old, time.Unix(1_700_000_000, 0), time.Unix(1_700_000_000, 0))
+	var gz bytes.Buffer
+	z := gzip.NewWriter(&gz)
+	_, _ = z.Write([]byte(clientLine("info", "older") + "\n" + clientLine("warning", "Network error on https://cloud.example.test:8443/x Authorization: Bearer abc.def") + "\n"))
+	_ = z.Close()
+	f.write(testHome+"/"+logDir+"/20261005_0927_nextcloud.log.0.gz", gz.String())
+	f.write(testHome+"/"+logDir+"/20261005_1127_permanent_delete.log.0", "not the client's log\n")
+	f.write(testHome+"/"+logDir+"/20261005_1127_nextcloud.log.0",
+		clientLine("info", "Sync finished for folder of account [kc-1234-uid@cloud.example.test]")+"\n"+clientLine("critical", "Could not read journal")+"\n")
+	gzPath := filepath.Join(f.Root, testHome, logDir, "20261005_0927_nextcloud.log.0.gz")
+	_ = os.Chtimes(gzPath, time.Now().Add(-time.Hour), time.Now().Add(-time.Hour))
+	f.write(testHome+"/.config/autostart/Nextcloud.desktop", "[Desktop Entry]\nName=Nextcloud\nExec=\"/usr/bin/nextcloud\" --background\nX-GNOME-Autostart-enabled=true\n")
+	f.answer = func(name string, args []string) Output {
+		switch {
+		case name == "pacman":
+			return Output{Stdout: "nextcloud-client 2:34.0.4-1\n"}
+		case name == "systemctl" && len(args) > 1 && args[1] == "is-enabled":
+			return Output{Stdout: "disabled\n", Code: 1}
+		}
+		return Output{}
+	}
+	return f
+}
+
+func noSecrets(t *testing.T, v any) string {
+	t.Helper()
+	raw, err := json.Marshal(v)
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := string(raw)
+	for _, never := range []string{"example.test", "kc-1234", "CERTIFICATE", "abc.def", "/home/operator"} {
+		if strings.Contains(s, never) {
+			t.Errorf("the answer carries %q: %s", never, s)
+		}
+	}
+	return s
+}
+
+func TestStatusNamesAccountsAndFoldersWithTheirLastSyncAndNothingSecret(t *testing.T) {
+	f := newClient(t)
+	f.proc(3865, 1000, clientComm, []string{"/usr/bin/nextcloud", "--background"}, "session-c1.scope")
+	s, err := f.Status()
+	if err != nil {
+		t.Fatal(err)
+	}
+	noSecrets(t, s)
+	if s.Installed != "2:34.0.4-1" || len(s.Running) != 1 || s.Running[0].StartedIn != "session-c1.scope" {
+		t.Fatalf("%+v", s)
+	}
+	if !s.StartedBy.Starts || s.StartedBy.From != "~/.config/autostart/Nextcloud.desktop" {
+		t.Fatalf("%+v", s.StartedBy)
+	}
+	if s.Config.ClientVersion != "34.0.4daily" || s.Config.LaunchAtStartup == nil || !*s.Config.LaunchAtStartup {
+		t.Fatalf("%+v", s.Config)
+	}
+	if len(s.Config.Accounts) != 1 {
+		t.Fatalf("%+v", s.Config.Accounts)
+	}
+	a := s.Config.Accounts[0]
+	if a.Name != "The Operator" || a.Auth != "webflow" || len(a.Folders) != 2 {
+		t.Fatalf("%+v", a)
+	}
+	main, photos := a.Folders[0], a.Folders[1]
+	if main.Local != "~/Nextcloud/" || main.RemotePath != "/" || main.Paused || !main.JournalFound || main.VirtualFiles != "off" {
+		t.Fatalf("%+v", main)
+	}
+	run := main.LastSync
+	if run == nil || run.State != "finished" || run.Started != "2026-10-05T09:27:40Z" || run.Finished != "2026-10-05T09:27:40Z" ||
+		run.Changes != 3 || run.Errors != 2 || run.Log != "~/.local/share/Nextcloud/Nextcloud_sync.log" {
+		t.Fatalf("%+v", run)
+	}
+	if run.Problems[0].File != "Notes/b.md" || run.Problems[0].HTTP != "423" || run.Problems[1].File != "<account>/c.md" {
+		t.Fatalf("%+v", run.Problems)
+	}
+	if !photos.Paused || photos.RemotePath != "/Photos" || photos.LastSync != nil {
+		t.Fatalf("%+v", photos)
+	}
+	// Warnings and worse of the two newest client logs, oldest first, hidden.
+	if len(s.Problems) != 2 || !strings.Contains(s.Problems[0], "<server>/x Authorization: <hidden>") ||
+		!strings.Contains(s.Problems[1], "Could not read journal") {
+		t.Fatalf("%q", s.Problems)
+	}
+}
+
+func TestARunWithoutItsEndIsRunningAndALogWithoutRunsIsNever(t *testing.T) {
+	f := newClient(t)
+	f.write(testHome+"/.local/share/Nextcloud/Nextcloud_sync.log", "/home/operator/Nextcloud/\n#=#=#=# Syncrun started 2026-10-05T10:00:00Z\n||x|1|1|1|e|1|i|13||200|0|0||\n")
+	s, _ := f.Status()
+	if r := s.Config.Accounts[0].Folders[0].LastSync; r.State != "running" || r.Finished != "" || r.Changes != 1 {
+		t.Fatalf("%+v", r)
+	}
+	f.write(testHome+"/.local/share/Nextcloud/Nextcloud_sync.log", "/home/operator/Nextcloud/\n")
+	s, _ = f.Status()
+	if r := s.Config.Accounts[0].Folders[0].LastSync; r.State != "never" {
+		t.Fatalf("%+v", r)
+	}
+}
+
+func TestNoSettingsIsNoAccountNotAnError(t *testing.T) {
+	f := newFake(t)
+	f.answer = func(string, []string) Output { return Output{Code: 1} }
+	s, err := f.Status()
+	if err != nil || s.Config.Found || len(s.Config.Accounts) != 0 || s.Installed != "" {
+		t.Fatalf("%+v %v", s, err)
+	}
+}
+
+func TestTheLogIsBoundedHiddenAndReadAcrossRotations(t *testing.T) {
+	f := newClient(t)
+	l, err := f.Log("client", 3, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	noSecrets(t, l)
+	if len(l.Lines) != 3 || !strings.Contains(l.Lines[0], "Authorization: <hidden>") || !strings.Contains(l.Lines[1], "[<account>]") ||
+		len(l.Files) != 2 || !strings.HasSuffix(l.Files[0], "_1127_nextcloud.log.0") {
+		t.Fatalf("%+v", l)
+	}
+	l, _ = f.Log("client", 1, false)
+	if len(l.Lines) != 1 || len(l.Files) != 1 || !strings.Contains(l.Lines[0], "Could not read journal") {
+		t.Fatalf("%+v", l)
+	}
+	l, _ = f.Log("client", 50, true)
+	if len(l.Lines) != 2 {
+		t.Fatalf("%+v", l)
+	}
+	l, _ = f.Log("sync", 2, false)
+	noSecrets(t, l)
+	if len(l.Lines) != 2 || !strings.HasPrefix(l.Lines[1], "#=#=#=# Syncrun finished") || l.Files[0] != "~/.local/share/Nextcloud/Nextcloud_sync.log" {
+		t.Fatalf("%+v", l)
+	}
+	if _, err := f.Log("server", 2, false); err == nil {
+		t.Fatal("an unknown source is refused")
+	}
+	empty := newFake(t)
+	if l, err := empty.Log("client", 5, false); err != nil || l.Note == "" || l.Lines == nil {
+		t.Fatalf("%+v %v", l, err)
+	}
+}
+
+func TestRestartEndsTheClientAndStartsOneInTheSession(t *testing.T) {
+	f := newClient(t)
+	if _, err := f.Restart(); err == nil || !strings.Contains(err.Error(), "no graphical session") {
+		t.Fatalf("without a desktop: %v", err)
+	}
+	f.desktopSession()
+	f.proc(3865, 1000, clientComm, []string{"nextcloud"}, "session-4.scope")
+	f.onStart = func(argv []string) {
+		f.proc(9000, 1000, clientComm, argv, "app.slice/"+restartAs+".service")
+	}
+	a, err := f.Restart()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(a.Ended) != 1 || a.Ended[0] != 3865 || len(a.Running) != 1 || a.Running[0].PID != 9000 ||
+		a.Running[0].StartedIn != restartAs+".service" || a.Running[0].Command != "/usr/bin/nextcloud --background" {
+		t.Fatalf("%+v", a)
+	}
+	f.onStart = nil
+	if _, err := f.Restart(); err == nil || !strings.Contains(err.Error(), "journalctl --user -u "+restartAs) {
+		t.Fatalf("a start that shows no process: %v", err)
+	}
+}
+
+func TestCheckPassesOneStartAndNamesEveryOther(t *testing.T) {
+	f := newClient(t)
+	f.desktopSession()
+	f.write(testHome+"/Photos/.keep", "")
+	f.proc(3865, 1000, clientComm, []string{"nextcloud"}, "session-c1.scope")
+	c, err := f.Check()
+	if err != nil {
+		t.Fatal(err)
+	}
+	// The one finding is the paused folder.
+	if c.OK || len(c.Findings) != 1 || !strings.Contains(c.Findings[0].What, "~/Photos/ is paused") || len(c.Starts) != 1 {
+		t.Fatalf("%+v", c)
+	}
+	noSecrets(t, c)
+
+	f.write(testHome+"/.config/i3/config", "exec --no-startup-id nextcloud\n")
+	f.answer = func(name string, args []string) Output {
+		switch name {
+		case "pacman":
+			return Output{Code: 1, Stderr: "error: package 'nextcloud-client' was not found"}
+		case "systemctl":
+			return Output{Stdout: "enabled\n"}
+		case "dex":
+			return Output{Code: 127, Err: ErrNotInstalled}
+		}
+		return Output{}
+	}
+	f.proc(3866, 1000, clientComm, []string{"nextcloud"}, "session-c1.scope")
+	f.write(testHome+"/.config/autostart/Nextcloud.desktop", "[Desktop Entry]\nExec=nextcloud\nHidden=true\n")
+	c, _ = f.Check()
+	all := noSecrets(t, c)
+	for _, want := range []string{"not installed", "does not start with the session (Hidden=true)", "dex", "a second start: ~/.config/i3/config:1",
+		"packaged user unit", "2 clients run"} {
+		if !strings.Contains(all, want) {
+			t.Errorf("no finding %q in %s", want, all)
+		}
+	}
+	if len(c.Starts) != 2 {
+		t.Fatalf("%q", c.Starts)
+	}
+}

modules/nextcloud-client/go.mod

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

modules/nextcloud-client/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/nextcloud-client/module.json

@@ -0,0 +1,38 @@
+{
+  "module": "nextcloud-client",
+  "version": "1",
+  "capabilities": [
+    "package-manager"
+  ],
+  "requires": [
+    "x11-display"
+  ],
+  "tools": [
+    "nextcloud_status",
+    "nextcloud_log",
+    "nextcloud_restart",
+    "nextcloud_check"
+  ],
+  "resources": [
+    {
+      "id": "package",
+      "type": "package",
+      "package": "nextcloud-client"
+    }
+  ],
+  "build": {
+    "artifacts": [
+      {
+        "name": "tools",
+        "kind": "bundle",
+        "language": "go",
+        "system": "arch",
+        "from": "cmd/nextcloud-client-tools",
+        "binary": "nextcloud-client-tools",
+        "loads": [
+          "nextcloud-client-tools"
+        ]
+      }
+    ]
+  }
+}

modules/nextcloud/module.json

@@ -117,5 +117,12 @@
         }
       }
     ]
-  }
+  },
+  "contributions": [
+    {
+      "seat": "node-backup",
+      "kind": "backup",
+      "content": "path ${dir:html}\n"
+    }
+  ]
 }

modules/postgres/module.json

@@ -74,6 +74,13 @@
       "mode": "0700",
       "owner": "999:70"
     },
+    {
+      "id": "dumps",
+      "type": "directory",
+      "path": "${dir:store-data}/dumps",
+      "mode": "0700",
+      "owner": "999:70"
+    },
     {
       "id": "server",
       "type": "container",
@@ -121,5 +128,12 @@
         }
       }
     ]
-  }
+  },
+  "contributions": [
+    {
+      "seat": "node-backup",
+      "kind": "backup",
+      "content": "run docker exec -u postgres postgres sh -c 'cd /var/lib/postgresql/data/dumps && for db in $(psql -Atc \"select datname from pg_database where oid >= 16384 order by 1\"); do pg_dump -Fc -f \"$db.dump.partial\" \"$db\" && mv \"$db.dump.partial\" \"$db.dump\" || exit 1; done'\npath ${dir:dumps}\n"
+    }
+  ]
 }

modules/restic/cmd/restic-backups/backups.go

@@ -0,0 +1,525 @@
+// The machine's backups (novox/hq ADR 0214, to-be 43).
+//
+// The mesh composes what to back up: every module on the machine contributes `backup` lines to the
+// node-backup seat, and the mesh writes them, each module's under a `# <module>` line and with its
+// directories already filled, into one file this module reads. Two kinds of line:
+//
+//	run <shell command>   run as root before the module's snapshot — a consistent dump of a store
+//	path <directory>      a directory the module's snapshot keeps
+//
+// Each module gets one snapshot a night, tagged with its name, so a module is listed, kept and
+// restored on its own. Everything lands in one repository on the machine — deduplicated, so every
+// night is a complete restore point and only what changed costs space — and is thinned to 14 daily,
+// 8 weekly and 6 monthly. Against mistakes, not disasters: nothing leaves the machine.
+//
+// Root's: the dumps read every store and the repository holds every module's data, and the runtime
+// launching this binary runs as the operator's account, so restic and the run lines go through sudo
+// without a prompt where the account is not root (ADR 0175 §4).
+package main
+
+import (
+	"bufio"
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"slices"
+	"strings"
+	"sync"
+	"time"
+)
+
+// Runner runs one command and answers what it printed, so the backups can be tested without restic
+// or a store.
+type Runner func(ctx context.Context, name string, args ...string) (string, error)
+
+// 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...)
+}
+
+// execRunner runs it for real. A night's dump of a large store takes a while; six hours is a dump
+// that will not finish.
+func execRunner(ctx context.Context, name string, args ...string) (string, error) {
+	ctx, cancel := context.WithTimeout(ctx, 6*time.Hour)
+	defer cancel()
+	program, argv := escalated(os.Getuid(), name, args)
+	var stdout, stderr bytes.Buffer
+	cmd := exec.CommandContext(ctx, program, argv...)
+	cmd.Stdout, cmd.Stderr = &stdout, &stderr
+	if err := cmd.Run(); err != nil {
+		said := strings.TrimSpace(stderr.String())
+		if said == "" {
+			said = strings.TrimSpace(stdout.String())
+		}
+		if program == "sudo" && strings.HasPrefix(said, "sudo:") {
+			return "", fmt.Errorf("%s needs root and the runtime's account may not run it without a prompt: %s", name, said)
+		}
+		lines := strings.Split(said, "\n")
+		if len(lines) > 3 {
+			lines = lines[len(lines)-3:]
+		}
+		if said == "" {
+			return "", fmt.Errorf("%s: %w", name, err)
+		}
+		return "", errors.New(strings.Join(lines, " / "))
+	}
+	return stdout.String(), nil
+}
+
+// Declared is what one module declared.
+type Declared struct {
+	Module string   `json:"module"`
+	Runs   []string `json:"runs"`
+	Paths  []string `json:"paths"`
+}
+
+var moduleHeader = regexp.MustCompile(`^#\s*([a-z0-9][a-z0-9-]*)$`)
+
+// parseDeclared reads the composed file into each module's declaration, in the order the mesh wrote
+// them. A line before any module, a comment that is not a module's name, or a blank, is nothing; a
+// line this holder does not read is refused, naming the module, rather than skipped.
+func parseDeclared(text string) ([]Declared, error) {
+	var out []Declared
+	current := -1
+	for _, raw := range strings.Split(text, "\n") {
+		line := strings.TrimSpace(raw)
+		if line == "" {
+			continue
+		}
+		if m := moduleHeader.FindStringSubmatch(line); m != nil {
+			out = append(out, Declared{Module: m[1]})
+			current = len(out) - 1
+			continue
+		}
+		if strings.HasPrefix(line, "#") || current < 0 {
+			continue
+		}
+		kind, value, _ := strings.Cut(line, " ")
+		value = strings.TrimSpace(value)
+		d := &out[current]
+		switch {
+		case kind == "run" && value != "":
+			d.Runs = append(d.Runs, value)
+		case kind == "path" && strings.HasPrefix(value, "/") && !strings.ContainsAny(value, " \t"):
+			d.Paths = append(d.Paths, value)
+		default:
+			return nil, fmt.Errorf("%s contributes a backup line this holder does not read: %s", d.Module, line)
+		}
+	}
+	kept := out[:0]
+	for _, d := range out {
+		if len(d.Runs) > 0 || len(d.Paths) > 0 {
+			kept = append(kept, d)
+		}
+	}
+	return kept, nil
+}
+
+// Snapshot is one restore point, as restic lists it.
+type Snapshot struct {
+	ID       string    `json:"id"`
+	ShortID  string    `json:"short_id"`
+	Time     time.Time `json:"time"`
+	Paths    []string  `json:"paths"`
+	Tags     []string  `json:"tags"`
+	Hostname string    `json:"hostname"`
+}
+
+// Night is how one module's last night went.
+type Night struct {
+	OK       bool      `json:"ok"`
+	At       time.Time `json:"at"`
+	Snapshot string    `json:"snapshot,omitempty"`
+	Error    string    `json:"error,omitempty"`
+}
+
+// Keep is the rotation (novox/hq ADR 0214).
+var Keep = struct{ Daily, Weekly, Monthly int }{14, 8, 6}
+
+func tagOf(module string) string { return "module=" + module }
+
+// Where is where the mesh put this module's things.
+type Where struct {
+	Declared, Repository, PasswordFile, State string
+}
+
+func whereFromEnv() (Where, error) {
+	var missing []string
+	get := func(k string) string {
+		v := os.Getenv(k)
+		if v == "" {
+			missing = append(missing, k)
+		}
+		return v
+	}
+	w := Where{
+		Declared:     get("MESH_BACKUP_DECLARED"),
+		Repository:   get("MESH_BACKUP_REPOSITORY"),
+		PasswordFile: get("MESH_BACKUP_PASSWORD_FILE"),
+		State:        get("MESH_BACKUP_STATE"),
+	}
+	if len(missing) > 0 {
+		return w, fmt.Errorf("%s not set; the mesh gives them to this module", strings.Join(missing, ", "))
+	}
+	return w, nil
+}
+
+// Backups is the machine's backups. One thing at a time: two nights, or a night and a restore, never
+// share a dump.
+type Backups struct {
+	Where Where
+	Run   Runner
+	Now   func() time.Time
+	Say   func(format string, args ...any)
+	mu    sync.Mutex
+}
+
+// exists is whether a path is there, asked as root: a store's directory is often its own user's
+// alone (postgres's 0700 data directory), and the runtime's account asking for itself would see
+// nothing — every such directory "missing", and its module never backed up.
+func (b *Backups) exists(ctx context.Context, path string) bool {
+	_, err := b.Run(ctx, "test", "-e", path)
+	return err == nil
+}
+
+func (b *Backups) restic(ctx context.Context, args ...string) (string, error) {
+	return b.Run(ctx, "restic", append([]string{"--repo", b.Where.Repository, "--password-file", b.Where.PasswordFile, "--no-cache"}, args...)...)
+}
+
+// Declared is what the modules on this machine declared.
+func (b *Backups) Declared() ([]Declared, error) {
+	raw, err := os.ReadFile(b.Where.Declared)
+	if err != nil {
+		return nil, err
+	}
+	return parseDeclared(string(raw))
+}
+
+func (b *Backups) nightsFile() string { return filepath.Join(b.Where.State, "nights.json") }
+
+// Nights is how each module's last night went.
+func (b *Backups) Nights() map[string]Night {
+	nights := map[string]Night{}
+	if raw, err := os.ReadFile(b.nightsFile()); err == nil {
+		_ = json.Unmarshal(raw, &nights)
+	}
+	return nights
+}
+
+func (b *Backups) record(module string, n Night) {
+	nights := b.Nights()
+	nights[module] = n
+	raw, _ := json.MarshalIndent(nights, "", "  ")
+	if err := os.WriteFile(b.nightsFile(), append(raw, '\n'), 0o600); err != nil {
+		b.Say("recording %s's night failed: %v", module, err)
+	}
+}
+
+var noRepository = regexp.MustCompile(`(?i)does not exist|unable to open config file|Is there a repository at the following location`)
+
+// ensureRepository makes the repository the first time. One that exists and cannot be opened is
+// said, never replaced: replacing it would discard every restore point to fix a password.
+func (b *Backups) ensureRepository(ctx context.Context) error {
+	_, err := b.restic(ctx, "cat", "config")
+	if err == nil {
+		return nil
+	}
+	if !noRepository.MatchString(err.Error()) {
+		return fmt.Errorf("the repository at %s cannot be opened, and is left as it is: %v", b.Where.Repository, err)
+	}
+	b.Say("no repository at %s; making one", b.Where.Repository)
+	_, err = b.restic(ctx, "init")
+	return err
+}
+
+// one is one module's night: its run lines, then one snapshot of its paths. A failure is that
+// module's alone.
+func (b *Backups) one(ctx context.Context, d Declared) Night {
+	n := Night{At: b.Now().UTC()}
+	fail := func(err error) Night {
+		n.Error = err.Error()
+		b.Say("%s: NOT backed up: %s", d.Module, n.Error)
+		return n
+	}
+	for _, command := range d.Runs {
+		if _, err := b.Run(ctx, "sh", "-c", command); err != nil {
+			return fail(err)
+		}
+	}
+	if len(d.Paths) == 0 {
+		return fail(errors.New("it runs a dump and names no directory to keep it from"))
+	}
+	var missing []string
+	for _, p := range d.Paths {
+		if !b.exists(ctx, p) {
+			missing = append(missing, p)
+		}
+	}
+	if len(missing) > 0 {
+		return fail(fmt.Errorf("%s does not exist", strings.Join(missing, ", ")))
+	}
+	out, err := b.restic(ctx, append([]string{"backup", "--json", "--tag", tagOf(d.Module)}, d.Paths...)...)
+	if err != nil {
+		return fail(err)
+	}
+	scanner := bufio.NewScanner(strings.NewReader(out))
+	scanner.Buffer(make([]byte, 1024*1024), 16*1024*1024)
+	for scanner.Scan() {
+		var m struct {
+			MessageType string `json:"message_type"`
+			SnapshotID  string `json:"snapshot_id"`
+		}
+		if json.Unmarshal(scanner.Bytes(), &m) == nil && m.MessageType == "summary" && len(m.SnapshotID) >= 8 {
+			n.Snapshot = m.SnapshotID[:8]
+		}
+	}
+	n.OK = true
+	b.Say("%s: backed up (%s)", d.Module, n.Snapshot)
+	return n
+}
+
+// BackUp is a night: every module, or one, then the rotation. It answers each module's outcome.
+func (b *Backups) BackUp(ctx context.Context, only string) (map[string]Night, error) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	if err := b.ensureRepository(ctx); err != nil {
+		return nil, err
+	}
+	all, err := b.Declared()
+	if err != nil {
+		return nil, err
+	}
+	chosen := all
+	if only != "" {
+		chosen = nil
+		var names []string
+		for _, d := range all {
+			names = append(names, d.Module)
+			if d.Module == only {
+				chosen = append(chosen, d)
+			}
+		}
+		if len(chosen) == 0 {
+			return nil, fmt.Errorf("%s declares nothing to back up on this machine; it backs up %s", only, orNothing(names))
+		}
+	}
+	outcome := map[string]Night{}
+	for _, d := range chosen {
+		outcome[d.Module] = b.one(ctx, d)
+		b.record(d.Module, outcome[d.Module])
+	}
+	if _, err := b.restic(ctx, "forget", "--prune", "--group-by", "host,tags",
+		"--keep-daily", fmt.Sprint(Keep.Daily), "--keep-weekly", fmt.Sprint(Keep.Weekly), "--keep-monthly", fmt.Sprint(Keep.Monthly)); err != nil {
+		b.Say("thinning the restore points failed, and every one is kept: %v", err)
+	}
+	return outcome, nil
+}
+
+func orNothing(names []string) string {
+	if len(names) == 0 {
+		return "nothing"
+	}
+	return strings.Join(names, ", ")
+}
+
+// Snapshots is the restore points, of one module or all.
+func (b *Backups) Snapshots(ctx context.Context, module string) ([]Snapshot, error) {
+	args := []string{"snapshots", "--json"}
+	if module != "" {
+		args = append(args, "--tag", tagOf(module))
+	}
+	out, err := b.restic(ctx, args...)
+	if err != nil {
+		return nil, err
+	}
+	var snaps []Snapshot
+	if strings.TrimSpace(out) == "" {
+		return nil, nil
+	}
+	if err := json.Unmarshal([]byte(out), &snaps); err != nil {
+		return nil, fmt.Errorf("restic listed its snapshots in a form this holder does not read: %v", err)
+	}
+	return snaps, nil
+}
+
+// ModuleBackups is what `backed-up` says about one module.
+type ModuleBackups struct {
+	Module        string    `json:"module"`
+	Runs          int       `json:"runs"`
+	Paths         []string  `json:"paths"`
+	LastNight     *Night    `json:"lastNight"`
+	RestorePoints int       `json:"restorePoints"`
+	Newest        *Snapshot `json:"newest,omitempty"`
+}
+
+// BackedUp is what is backed up here: each module, what it declared, its last night and its restore
+// points.
+func (b *Backups) BackedUp(ctx context.Context, module string) ([]ModuleBackups, error) {
+	declared, err := b.Declared()
+	if err != nil {
+		return nil, err
+	}
+	nights := b.Nights()
+	snaps, _ := b.Snapshots(ctx, module)
+	out := []ModuleBackups{}
+	for _, d := range declared {
+		if module != "" && d.Module != module {
+			continue
+		}
+		m := ModuleBackups{Module: d.Module, Runs: len(d.Runs), Paths: d.Paths}
+		if n, ok := nights[d.Module]; ok {
+			m.LastNight = &n
+		}
+		for _, s := range snaps {
+			if slices.Contains(s.Tags, tagOf(d.Module)) {
+				m.RestorePoints++
+				newest := s
+				m.Newest = &newest
+			}
+		}
+		out = append(out, m)
+	}
+	return out, nil
+}
+
+// Restored is what a restore put where.
+type Restored struct {
+	Module   string   `json:"module"`
+	From     Snapshot `json:"from"`
+	Restored []string `json:"restored"`
+	Live     string   `json:"live"`
+}
+
+// Restore puts a module's data from a restore point BESIDE the live data: each directory as
+// <path>.restored-<stamp>. A target that already exists is refused, never overwritten.
+func (b *Backups) Restore(ctx context.Context, module, snapshot, path string) (*Restored, error) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	mine, err := b.Snapshots(ctx, module)
+	if err != nil {
+		return nil, err
+	}
+	if len(mine) == 0 {
+		return nil, fmt.Errorf("%s has no restore point on this machine", module)
+	}
+	chosen := mine[len(mine)-1]
+	if snapshot != "" {
+		found := false
+		var listed []string
+		for _, s := range mine {
+			listed = append(listed, fmt.Sprintf("%s (%s)", s.ShortID, s.Time.Format(time.RFC3339)))
+			if s.ShortID == snapshot || strings.HasPrefix(s.ID, snapshot) {
+				chosen, found = s, true
+			}
+		}
+		if !found {
+			return nil, fmt.Errorf("%s has no restore point %s; it has %s", module, snapshot, strings.Join(listed, ", "))
+		}
+	}
+	paths := chosen.Paths
+	if path != "" {
+		if !slices.Contains(chosen.Paths, path) {
+			return nil, fmt.Errorf("restore point %s of %s holds %s, not %s", chosen.ShortID, module, strings.Join(chosen.Paths, ", "), path)
+		}
+		paths = []string{path}
+	}
+	stamp := b.Now().UTC().Format("20060102-150405")
+	r := &Restored{Module: module, From: chosen, Live: "untouched — swapping it in is a person's act"}
+	for _, p := range paths {
+		target := p + ".restored-" + stamp
+		if b.exists(ctx, target) {
+			return nil, fmt.Errorf("%s already exists; nothing is restored over anything", target)
+		}
+		if err := b.restoreOne(ctx, chosen.ID, p, target); err != nil {
+			return nil, err
+		}
+		r.Restored = append(r.Restored, target)
+		b.Say("%s: restored %s from %s to %s", module, p, chosen.ShortID, target)
+	}
+	return r, nil
+}
+
+// restoreOne puts one kept path at target. A directory is restored as the snapshot's subfolder, so
+// its contents land directly in target; a single file cannot be — restic restores a subfolder, not a
+// file (a settings file refused with "not a directory" on the first restore of an app, 2026-10-05) —
+// so it is restored with its full path into a scratch directory beside target, moved into place, and
+// the scratch directory removed.
+func (b *Backups) restoreOne(ctx context.Context, id, path, target string) error {
+	file, err := b.isFile(ctx, id, path)
+	if err != nil {
+		return err
+	}
+	if !file {
+		_, err := b.restic(ctx, "restore", id+":"+path, "--target", target)
+		return err
+	}
+	scratch := target + ".partial"
+	if _, err := b.restic(ctx, "restore", id, "--target", scratch, "--include", path); err != nil {
+		return err
+	}
+	if _, err := b.Run(ctx, "mv", scratch+path, target); err != nil {
+		return err
+	}
+	_, err = b.Run(ctx, "rm", "-rf", scratch)
+	return err
+}
+
+// isFile is whether a kept path is a single file in the snapshot, as restic lists it.
+func (b *Backups) isFile(ctx context.Context, id, path string) (bool, error) {
+	out, err := b.restic(ctx, "ls", "--json", id, path)
+	if err != nil {
+		return false, err
+	}
+	scanner := bufio.NewScanner(strings.NewReader(out))
+	scanner.Buffer(make([]byte, 1024*1024), 16*1024*1024)
+	for scanner.Scan() {
+		var node struct {
+			Type string `json:"type"`
+			Path string `json:"path"`
+		}
+		if json.Unmarshal(scanner.Bytes(), &node) == nil && node.Path == path {
+			return node.Type == "file", nil
+		}
+	}
+	return false, fmt.Errorf("restore point %s does not list %s", id, path)
+}
+
+// Check is the weekly look at the repository's own integrity, with a sample of the data read back.
+func (b *Backups) Check(ctx context.Context) error {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	_, err := b.restic(ctx, "check", "--read-data-subset", "5%")
+	return err
+}
+
+// nextNight is when the next night is due: the given hour, local time, today while it is still
+// ahead, else tomorrow.
+func nextNight(now time.Time, hour int) time.Time {
+	next := time.Date(now.Year(), now.Month(), now.Day(), hour, 0, 0, 0, now.Location())
+	if !next.After(now) {
+		next = next.AddDate(0, 0, 1)
+	}
+	return next
+}
+
+// missedANight is whether a night was missed: the newest good night of any module is older than a
+// day and a bit — the machine was off, or this module was not running, at the hour.
+func missedANight(nights map[string]Night, now time.Time) bool {
+	var newest time.Time
+	for _, n := range nights {
+		if n.OK && n.At.After(newest) {
+			newest = n.At
+		}
+	}
+	return newest.IsZero() || now.Sub(newest) > 26*time.Hour
+}

modules/restic/cmd/restic-backups/backups_test.go

@@ -0,0 +1,286 @@
+package main
+
+// The machine's backups over a fake restic and fake stores (novox/hq ADR 0214, to-be 43), and — where
+// restic is installed — over the real one, on throwaway directories.
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+)
+
+const composed = "# What the modules on this machine back up, composed by the mesh. Do not edit.\n" +
+	"# postgres\nrun docker exec -u postgres postgres sh -c 'pg-dump-all'\npath /var/lib/mesh-store/dumps\n" +
+	"# mailu\npath /var/lib/mailu/data-mail\npath /var/lib/mailu/data-dkim\n"
+
+func placed(t *testing.T, declared string) Where {
+	t.Helper()
+	dir := t.TempDir()
+	must(t, os.WriteFile(filepath.Join(dir, "backups.conf"), []byte(declared), 0o600))
+	must(t, os.WriteFile(filepath.Join(dir, "pw"), []byte("secret\n"), 0o600))
+	return Where{Declared: filepath.Join(dir, "backups.conf"), Repository: filepath.Join(dir, "repo"),
+		PasswordFile: filepath.Join(dir, "pw"), State: dir}
+}
+
+func must(t *testing.T, err error) {
+	t.Helper()
+	if err != nil {
+		t.Fatal(err)
+	}
+}
+
+func quiet(string, ...any) {}
+
+func TestTheComposedFileIsReadIntoEachModulesRunsAndPaths(t *testing.T) {
+	got, err := parseDeclared(composed)
+	must(t, err)
+	want := []Declared{
+		{Module: "postgres", Runs: []string{"docker exec -u postgres postgres sh -c 'pg-dump-all'"}, Paths: []string{"/var/lib/mesh-store/dumps"}},
+		{Module: "mailu", Paths: []string{"/var/lib/mailu/data-mail", "/var/lib/mailu/data-dkim"}},
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("read %#v, want %#v", got, want)
+	}
+}
+
+func TestALineThisHolderDoesNotReadIsRefusedNamingTheModule(t *testing.T) {
+	for _, bad := range []string{"# pg\ncopy /x\n", "# pg\npath relative/dir\n"} {
+		if _, err := parseDeclared(bad); err == nil || !strings.Contains(err.Error(), "pg contributes a backup line") {
+			t.Errorf("%q: %v", bad, err)
+		}
+	}
+}
+
+func TestResticAndTheDumpsRunThroughSudoWhereTheAccountIsNotRoot(t *testing.T) {
+	if p, a := escalated(1000, "restic", []string{"snapshots"}); p != "sudo" || !reflect.DeepEqual(a, []string{"-n", "restic", "snapshots"}) {
+		t.Errorf("as an account: %s %v", p, a)
+	}
+	if p, a := escalated(0, "restic", []string{"snapshots"}); p != "restic" || !reflect.DeepEqual(a, []string{"snapshots"}) {
+		t.Errorf("as root: %s %v", p, a)
+	}
+}
+
+func TestANightDumpsBeforeEachSnapshotAndOneFailingModuleFailsOnlyItself(t *testing.T) {
+	where := placed(t, "# pg\nrun dump-it\npath /\n# broken\nrun fail-it\npath /\n# mail\npath /\n")
+	var calls []string
+	run := func(_ context.Context, name string, args ...string) (string, error) {
+		line := name + " " + strings.Join(args, " ")
+		if name == "restic" {
+			line = "restic " + strings.Join(args[5:], " ")
+		}
+		if name == "test" {
+			return "", nil
+		}
+		calls = append(calls, line)
+		switch {
+		case line == "sh -c fail-it":
+			return "", errors.New("the dump failed")
+		case strings.HasPrefix(line, "restic backup"):
+			return "{\"message_type\":\"status\"}\n{\"message_type\":\"summary\",\"snapshot_id\":\"abcdef0123456789\"}\n", nil
+		}
+		return "", nil
+	}
+	b := &Backups{Where: where, Run: run, Now: func() time.Time { return time.Date(2026, 10, 6, 3, 0, 0, 0, time.UTC) }, Say: quiet}
+	outcome, err := b.BackUp(context.Background(), "")
+	must(t, err)
+	if !outcome["pg"].OK || outcome["pg"].Snapshot != "abcdef01" {
+		t.Errorf("pg: %+v", outcome["pg"])
+	}
+	if outcome["broken"].OK || !strings.Contains(outcome["broken"].Error, "the dump failed") {
+		t.Errorf("broken: %+v", outcome["broken"])
+	}
+	if !outcome["mail"].OK {
+		t.Errorf("mail failed with broken: %+v", outcome["mail"])
+	}
+	want := []string{
+		"restic cat config",
+		"sh -c dump-it",
+		"restic backup --json --tag module=pg /",
+		"sh -c fail-it",
+		"restic backup --json --tag module=mail /",
+		"restic forget --prune --group-by host,tags --keep-daily 14 --keep-weekly 8 --keep-monthly 6",
+	}
+	if !reflect.DeepEqual(calls, want) {
+		t.Errorf("ran\n%s\nwant\n%s", strings.Join(calls, "\n"), strings.Join(want, "\n"))
+	}
+	// Recorded, so `backed-up` and the missed-night check read it.
+	var nights map[string]Night
+	raw, err := os.ReadFile(filepath.Join(where.State, "nights.json"))
+	must(t, err)
+	must(t, json.Unmarshal(raw, &nights))
+	if nights["broken"].OK || !nights["mail"].OK {
+		t.Errorf("recorded %+v", nights)
+	}
+}
+
+func TestARepositoryThatWillNotOpenIsNeverReplaced(t *testing.T) {
+	var calls []string
+	run := func(_ context.Context, _ string, args ...string) (string, error) {
+		calls = append(calls, strings.Join(args[5:], " "))
+		if args[5] == "cat" {
+			return "", errors.New("Fatal: wrong password or no key found")
+		}
+		return "", nil
+	}
+	b := &Backups{Where: placed(t, "# pg\npath /\n"), Run: run, Now: time.Now, Say: quiet}
+	if _, err := b.BackUp(context.Background(), ""); err == nil || !strings.Contains(err.Error(), "cannot be opened, and is left as it is") {
+		t.Fatalf("got %v", err)
+	}
+	for _, c := range calls {
+		if c == "init" {
+			t.Fatal("it made a new repository over one it could not open")
+		}
+	}
+}
+
+func TestADeclaredDirectoryThatDoesNotExistFailsThatModulesNight(t *testing.T) {
+	run := func(_ context.Context, name string, args ...string) (string, error) {
+		if name == "test" && args[1] == "/nowhere/at/all" {
+			return "", errors.New("exit status 1")
+		}
+		return "", nil
+	}
+	b := &Backups{Where: placed(t, "# pg\npath /nowhere/at/all\n"), Run: run, Now: time.Now, Say: quiet}
+	outcome, err := b.BackUp(context.Background(), "")
+	must(t, err)
+	if outcome["pg"].OK || !strings.Contains(outcome["pg"].Error, "/nowhere/at/all does not exist") {
+		t.Fatalf("pg: %+v", outcome["pg"])
+	}
+}
+
+func TestANightIsDueAtTheHourAndAMissedOneIsNoticed(t *testing.T) {
+	morning := time.Date(2026, 10, 6, 1, 30, 0, 0, time.Local)
+	if got := nextNight(morning, 3); !got.Equal(time.Date(2026, 10, 6, 3, 0, 0, 0, time.Local)) {
+		t.Errorf("from the morning: %v", got)
+	}
+	afternoon := time.Date(2026, 10, 6, 15, 0, 0, 0, time.Local)
+	if got := nextNight(afternoon, 3); !got.Equal(time.Date(2026, 10, 7, 3, 0, 0, 0, time.Local)) {
+		t.Errorf("from the afternoon: %v", got)
+	}
+	at := func(day int, ok bool) map[string]Night {
+		return map[string]Night{"pg": {OK: ok, At: time.Date(2026, 10, day, 3, 5, 0, 0, time.Local)}}
+	}
+	for _, c := range []struct {
+		nights map[string]Night
+		missed bool
+	}{{map[string]Night{}, true}, {at(6, true), false}, {at(4, true), true}, {at(6, false), true}} {
+		if got := missedANight(c.nights, afternoon); got != c.missed {
+			t.Errorf("%+v: missed %v", c.nights, got)
+		}
+	}
+}
+
+// The real thing, where restic is installed: a dump, a snapshot, a mistake, and a restore beside.
+func TestWithTheRealResticAMistakeIsUndoneBesideTheLiveData(t *testing.T) {
+	if _, err := exec.LookPath("restic"); err != nil {
+		t.Skip("restic is not installed")
+	}
+	root := t.TempDir()
+	store, dumps := filepath.Join(root, "store"), filepath.Join(root, "dumps")
+	must(t, os.Mkdir(store, 0o700))
+	must(t, os.Mkdir(dumps, 0o700))
+	must(t, os.WriteFile(filepath.Join(store, "mailbox"), []byte("the only copy of a letter\n"), 0o600))
+	settings := filepath.Join(root, "settings.xml")
+	must(t, os.WriteFile(settings, []byte("<Config>kept</Config>\n"), 0o600))
+	where := placed(t, "# mail\npath "+store+"\npath "+settings+"\n# pg\nrun echo 'every row' > "+dumps+"/all.dump\npath "+dumps+"\n")
+	// As whoever runs the test, against its own repository: no sudo.
+	run := func(ctx context.Context, name string, args ...string) (string, error) {
+		out, err := exec.CommandContext(ctx, name, args...).Output()
+		if ee, ok := err.(*exec.ExitError); ok {
+			return string(out), errors.New(string(ee.Stderr))
+		}
+		return string(out), err
+	}
+	b := &Backups{Where: where, Run: run, Now: func() time.Time { return time.Date(2026, 10, 6, 3, 0, 0, 0, time.UTC) }, Say: quiet}
+	ctx := context.Background()
+
+	night, err := b.BackUp(ctx, "")
+	must(t, err)
+	if !night["mail"].OK || !night["pg"].OK {
+		t.Fatalf("the night: %+v", night)
+	}
+	if raw, _ := os.ReadFile(filepath.Join(dumps, "all.dump")); string(raw) != "every row\n" {
+		t.Fatalf("the dump: %q", raw)
+	}
+
+	// The mistake.
+	must(t, os.Remove(filepath.Join(store, "mailbox")))
+
+	listed, err := b.BackedUp(ctx, "")
+	must(t, err)
+	if len(listed) != 2 || listed[0].RestorePoints != 1 || listed[1].RestorePoints != 1 {
+		t.Fatalf("listed %+v", listed)
+	}
+
+	// The mistake to a single file, too.
+	must(t, os.WriteFile(settings, []byte("<Config>overwritten</Config>\n"), 0o600))
+
+	restored, err := b.Restore(ctx, "mail", "", "")
+	must(t, err)
+	if len(restored.Restored) != 2 {
+		t.Fatalf("restored %+v", restored)
+	}
+	var dir, file string
+	for _, r := range restored.Restored {
+		switch {
+		case strings.HasSuffix(r, "store.restored-20261006-030000"):
+			dir = r
+		case strings.HasSuffix(r, "settings.xml.restored-20261006-030000"):
+			file = r
+		}
+	}
+	if raw, _ := os.ReadFile(filepath.Join(dir, "mailbox")); string(raw) != "the only copy of a letter\n" {
+		t.Fatalf("the restored letter: %q", raw)
+	}
+	// A single file comes back as a file beside the live one, and nothing of the scratch remains.
+	if raw, _ := os.ReadFile(file); string(raw) != "<Config>kept</Config>\n" {
+		t.Fatalf("the restored settings: %q", raw)
+	}
+	if raw, _ := os.ReadFile(settings); string(raw) != "<Config>overwritten</Config>\n" {
+		t.Fatalf("the restore wrote over the live settings: %q", raw)
+	}
+	if _, err := os.Stat(file + ".partial"); err == nil {
+		t.Fatal("the scratch directory was left behind")
+	}
+	if _, err := os.Stat(filepath.Join(store, "mailbox")); err == nil {
+		t.Fatal("the restore wrote into the live directory")
+	}
+
+	// Never over anything: the same restore again finds its target taken.
+	if _, err := b.Restore(ctx, "mail", "", ""); err == nil || !strings.Contains(err.Error(), "nothing is restored over anything") {
+		t.Fatalf("a second restore: %v", err)
+	}
+}
+
+// A store's directory is often its own user's alone; whether it is there is asked as root, never by
+// the runtime's account looking for itself — which saw nothing in postgres's 0700 data directory and
+// called the dumps missing on the first run (2026-10-05).
+func TestWhetherADirectoryIsThereIsAskedAsRoot(t *testing.T) {
+	var asked []string
+	run := func(_ context.Context, name string, args ...string) (string, error) {
+		if name == "test" {
+			asked = append(asked, strings.Join(args, " "))
+		}
+		if name == "restic" && args[5] == "backup" {
+			return "{\"message_type\":\"summary\",\"snapshot_id\":\"0123456789abcdef\"}\n", nil
+		}
+		return "", nil
+	}
+	// A path the account cannot see, which root can.
+	b := &Backups{Where: placed(t, "# pg\npath /root/only/dumps\n"), Run: run, Now: time.Now, Say: quiet}
+	outcome, err := b.BackUp(context.Background(), "")
+	must(t, err)
+	if !outcome["pg"].OK {
+		t.Fatalf("a directory only root sees was called missing: %+v", outcome["pg"])
+	}
+	if !reflect.DeepEqual(asked, []string{"-e /root/only/dumps"}) {
+		t.Errorf("asked %v", asked)
+	}
+}

modules/restic/cmd/restic-backups/main.go

@@ -0,0 +1,137 @@
+// restic-backups (novox/hq ADR 0214, to-be 43): the machine's backups. One binary, launched by the
+// machine's tool runtime and speaking MCP to it over stdio through the Go SDK (ADR 0193, ADR 0198). It
+// serves the node-backup seat's three verbs — what is backed up, take one now, restore beside the
+// live data — and, beside them, runs the night that happens without anyone asking.
+//
+// stdout is the MCP channel; everything this module says, it says on stderr.
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+	"time"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+// Seat is the role this module holds.
+const Seat = "node-backup"
+
+func say(format string, args ...any) {
+	fmt.Fprintf(os.Stderr, "[restic] "+format+"\n", args...)
+}
+
+func main() {
+	where, err := whereFromEnv()
+	if err != nil {
+		say("%v", err)
+		os.Exit(1)
+	}
+	b := &Backups{Where: where, Run: execRunner, Now: time.Now, Say: say}
+	go nights(b)
+	if err := stdio.Serve("", tools(b)); err != nil {
+		say("%v", err)
+		os.Exit(1)
+	}
+}
+
+// nights runs at the hour, every module; and at start, if a night was missed — the machine was off
+// or this module was not running at the hour — one soon rather than a day later. Not at once: a
+// machine just started has its stores still coming up.
+func nights(b *Backups) {
+	hour := 3
+	if h, err := strconv.Atoi(os.Getenv("MESH_BACKUP_HOUR")); err == nil && h >= 0 && h < 24 {
+		hour = h
+	}
+	if missedANight(b.Nights(), time.Now()) {
+		time.Sleep(10 * time.Minute)
+		night(b)
+	}
+	for {
+		time.Sleep(time.Until(nextNight(time.Now(), hour)))
+		night(b)
+	}
+}
+
+func night(b *Backups) {
+	ctx := context.Background()
+	outcome, err := b.BackUp(ctx, "")
+	if err != nil {
+		say("the night did not run: %v", err)
+		return
+	}
+	var failed []string
+	for module, n := range outcome {
+		if !n.OK {
+			failed = append(failed, module)
+		}
+	}
+	if len(failed) > 0 {
+		say("the night left %s without a backup", strings.Join(failed, ", "))
+	}
+	// Sundays, the repository's own integrity with a sample of the data read back.
+	if time.Now().Weekday() == time.Sunday {
+		if err := b.Check(ctx); err != nil {
+			say("the repository does NOT check out: %v", err)
+		} else {
+			say("the repository checks out")
+		}
+	}
+}
+
+// ---- the seat's verbs --------------------------------------------------------------------------
+
+func str(description string) map[string]any {
+	return map[string]any{"type": "string", "description": description}
+}
+
+func arg(a map[string]any, k string) string {
+	v, _ := a[k].(string)
+	return strings.TrimSpace(v)
+}
+
+// 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(a map[string]any) (any, error)) stdio.Tool {
+	return stdio.Tool{Name: Seat + "." + name, Description: description, Input: input, Run: run}
+}
+
+func tools(b *Backups) []stdio.Tool {
+	return []stdio.Tool{
+		verb("backed-up", "What this machine backs up: each module, what it declared, its last good night, how many restore points are kept.",
+			map[string]any{"module": str("one module (optional)")},
+			func(a map[string]any) (any, error) { return b.BackedUp(context.Background(), arg(a, "module")) }),
+		verb("now", "Take a backup now, of one module or of every module on this machine — before a migration, a retirement or anything else that could go wrong. Answers when it has started; `backed-up` says how it went.",
+			map[string]any{"module": str("one module (optional)")},
+			func(a map[string]any) (any, error) {
+				only := arg(a, "module")
+				// A night of a large store outlasts any call; it is started, and its outcome recorded.
+				go func() {
+					if _, err := b.BackUp(context.Background(), only); err != nil {
+						say("a backup asked for now failed: %v", err)
+					}
+				}()
+				started := only
+				if started == "" {
+					started = "every module on this machine"
+				}
+				return map[string]any{"started": started, "follow": Seat + ".backed-up"}, nil
+			}),
+		verb("restore", "Restore one module's data from a restore point BESIDE the live data, never over it: each directory as <path>.restored-<date>. Swapping it in is a person's act.",
+			map[string]any{
+				"module":   str("the module"),
+				"snapshot": str("the restore point (the newest when omitted)"),
+				"path":     str("one of the module's directories (all of them when omitted)"),
+			},
+			func(a map[string]any) (any, error) {
+				module := arg(a, "module")
+				if module == "" {
+					return nil, fmt.Errorf("module is required")
+				}
+				return b.Restore(context.Background(), module, arg(a, "snapshot"), arg(a, "path"))
+			}),
+	}
+}

modules/restic/go.mod

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

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

@@ -0,0 +1,69 @@
+{
+  "module": "restic",
+  "version": "1",
+  "claims": [
+    {
+      "name": "node-backup",
+      "scope": "node",
+      "serves": [
+        "backed-up",
+        "now",
+        "restore"
+      ]
+    }
+  ],
+  "own-secrets": {
+    "repository": "${dir:state}/repository.secret"
+  },
+  "resources": [
+    {
+      "id": "state",
+      "type": "directory",
+      "mode": "0700",
+      "place": "."
+    },
+    {
+      "id": "repository",
+      "type": "directory",
+      "mode": "0700"
+    },
+    {
+      "id": "declared",
+      "type": "file",
+      "path": "${dir:state}/backups.conf",
+      "mode": "0600",
+      "content": "# What the modules on this machine back up, composed by the mesh (novox/hq to-be 43). Do not edit.\n${contribution:node-backup:backup}"
+    },
+    {
+      "id": "tool",
+      "type": "package",
+      "package": "restic"
+    },
+    {
+      "id": "sqlite",
+      "type": "package",
+      "package": "sqlite"
+    }
+  ],
+  "build": {
+    "artifacts": [
+      {
+        "name": "tools",
+        "kind": "bundle",
+        "language": "go",
+        "system": "arch",
+        "from": "cmd/restic-backups",
+        "binary": "restic-backups",
+        "loads": [
+          "restic-backups"
+        ],
+        "env": {
+          "MESH_BACKUP_DECLARED": "${dir:state}/backups.conf",
+          "MESH_BACKUP_REPOSITORY": "${dir:repository}",
+          "MESH_BACKUP_PASSWORD_FILE": "${dir:state}/repository.secret",
+          "MESH_BACKUP_STATE": "${dir:state}"
+        }
+      }
+    ]
+  }
+}

modules/xdg/README.md

@@ -0,0 +1,182 @@
+# xdg
+
+The workstations' XDG desktop conventions as a module (novox/hq ADR 0208, ADR 0182): the account's
+folders, the default applications, and a view of what starts at login. It claims no seat: nothing
+calls "the conventions" as a role. It needs no display; every tool reads files, asks xdg-mime and gio,
+or reads `/proc`. It is for the two workstations only.
+
+- **Packages:** `xdg-user-dirs` and `xdg-utils` (`xdg-open`, `xdg-mime`, which the tools use).
+  `dex`, which runs the autostart entries, is `i3`'s. `desktop-file-utils` and `shared-mime-info` come
+  as other packages' dependencies and are held as found.
+- **No contribution, no session code.** The window manager's `dex --autostart --environment i3` line
+  is `i3`'s, and stays there.
+
+## What it owns
+
+| path | class (ADR 0182) | from |
+|---|---|---|
+| `~/.config/user-dirs.dirs` | owned, the found file kept once | [`config/user-dirs.dirs`](config/user-dirs.dirs), three folders from settings |
+| `~/.config/user-dirs.locale` | owned, the found file kept once | [`config/user-dirs.locale`](config/user-dirs.locale) |
+| `~/.config/user-dirs.conf` | owned, new | [`config/user-dirs.conf`](config/user-dirs.conf): `enabled=False` |
+| `/etc/xdg/mimeapps.list` | owned, new | [`config/mimeapps.list`](config/mimeapps.list): the machine's default applications |
+
+## What it does not own, and why
+
+| | whose | why |
+|---|---|---|
+| `~/.config/mimeapps.list` | the person's, held as found | every program offering "always open with" rewrites it, and so does `xdg-mime default` (below) |
+| the folders themselves (`~/Downloads`, …) | the person's, held as found | they hold the person's files. Declaring a directory would make its mode the mesh's (ADR 0182), and on one workstation `~/Desktop` is a file, not a folder |
+| `~/.config/autostart/*`, `/etc/xdg/autostart/*` | each application's | an autostart entry belongs to the module of the application it starts (below) |
+| `~/.config/xdg-desktop-portal/portals.conf` | `adwaita` | the portal's backends are the theme's business |
+| `~/.local/share/applications/*.desktop` | the person's and their installers' | JetBrains Toolbox, Steam, Telegram and the agent write their own launchers and handlers there |
+
+## The folders
+
+`user-dirs.dirs` is owned whole, with the operator's own values. Three folders differ between the
+workstations, so they are settings; the rest are the same on both.
+
+| setting | the mesh's layer | the laptop | the desktop machine |
+|---|---|---|---|
+| `desktop-dir` | `$HOME/Desktop` | as the mesh's | `$HOME/` |
+| `publicshare-dir` | `$HOME/Public` | as the mesh's | `$HOME/` |
+| `videos-dir` | `$HOME/Videos` | as the mesh's | `$HOME/` |
+
+A value is written into the file as it is, in xdg-user-dirs' format: `"$HOME/yyy"` or `"/yyy"`. `$HOME/`
+is the home itself, xdg-user-dirs' way of saying the folder is not wanted. The settings have no
+default, so the mesh's layer is set before the first assignment (as `power`'s are). They land in this
+one file: the module has no merged file and no contribution, so issue 168 cannot carry them anywhere
+else.
+
+**Why `xdg-user-dirs-update` is disabled.** It runs at every login, from its XDG autostart entry, which
+`dex` starts. Measured on xdg-user-dirs 0.20 against a copy of the folders:
+
+- enabled, it reassigns a folder it cannot find to the home (`Videos was removed, reassigning VIDEOS to
+  homedir`), adds a line and creates the folder for every default it knows that the file lacks
+  (`PROJECTS` arrived this way), and rewrites the file with its own header. Every login would undo
+  the mesh's file, and every push would undo the login;
+- disabled by `enabled=False` in the account's `user-dirs.conf`, it does nothing, even with `--force`.
+  Only an explicit `--set` still writes.
+
+The package's systemd user unit `xdg-user-dirs.service` is enabled by preset but never runs: it is
+wanted by `graphical-session-pre.target`, which the xinit session does not reach. Disabled, it would
+do nothing either way, so it is left as found.
+
+`user-dirs.locale` (`en_US` on both) only tells xdg-user-dirs-gtk, which neither workstation has,
+which language the folders were named in. It is owned so the account's xdg-user-dirs files are one
+set.
+
+## Default applications: the mesh's list is the last one read
+
+**Decision.** The mesh owns `/etc/xdg/mimeapps.list`, the system's list, and never writes the
+person's `~/.config/mimeapps.list`. An application reads the person's list first and the system's
+after it (the XDG MIME Applications specification), so every choice the person makes wins, and the
+mesh's list answers only what the person has not chosen. `xdg_default` gets and sets a default, and
+setting writes the person's list through `xdg-mime default`, as any program would.
+
+**Why not own the person's file, or a block in it.** Measured on 2026-10-05 with xdg-utils 1.2.1 and
+GLib's `gio`, against copies:
+
+1. **Owned whole** fights the person: Firefox's "make default", a file manager's "always open with" and
+   `xdg-mime default` all rewrite that file, and the next push would take each choice back.
+2. **A mesh block at its start** (`into: block`, as `zsh` and `xorg` do) breaks three ways, because a
+   mimeapps list is a key file and not a script:
+   - the block's `[Default Applications]` and the person's are one group written twice. **xdg-mime reads
+     the first and GLib the last**, so `xdg-open` and every GTK or Electron program answered differently
+     for the same type;
+   - `gio mime` (what GTK programs do on "always open with") **rewrote the file as one merged group and
+     dropped the block's markers**: the next push would find no block and add a second;
+   - `xdg-mime default` **wrote the person's choice into the first group, inside the mesh's block**,
+     where the next push removes it.
+3. **The system's list** has none of this: nothing but the mesh writes it, each reader reads one group
+   per file, and a person's choice in their own file is never touched. A default naming an
+   application that is not installed is passed over, to the next list.
+
+**What the mesh's list holds.** The operator's own defaults, adopted from both workstations' lists of
+2026-10-05 (the two were byte-identical), except entries naming an application installed on neither:
+
+- dropped: 55 types for `code-oss.desktop` (no Code-OSS on either machine; plain text opens in
+  Fleet, from its own declaration), `jetbrains-rider.desktop`, `org.kde.korganizer.desktop`,
+  `Postman.desktop`, and a Fleet launcher whose name is the id one machine's JetBrains Toolbox
+  generated (a different one on the other machine);
+- kept: Firefox for the web, HTML and PDF; Thunar for folders; ghostwriter for Markdown; Plexamp, Slack,
+  Telegram and JetBrains Toolbox for their own links; and mpv, mplayer, vlc for MP4.
+
+The person's list keeps every line as found, the dropped ones included. `xdg_check` names them.
+
+## Autostart: listed, not owned
+
+An XDG autostart entry belongs to the module of the application it starts, as `picom` does: picom's
+package entry is its one starter. A future `nextcloud-client` module owns `Nextcloud.desktop` (the
+client writes it itself), a blueman module beside `bluetooth` owns blueman's, and Slack's and JetBrains
+Toolbox's entries would be their modules'.
+This module only says what is there, and what the session does with it.
+
+The session's starter is `i3`'s `dex --autostart --environment i3`. `xdg_autostart` decides each
+entry by dex's own rules (dex 0.10):
+
+- a user entry hides the system entry of the same name;
+- `Hidden=true` keeps an entry from starting;
+- an `OnlyShowIn` without `i3` keeps it from starting, and so does a `NotShowIn` with it;
+- a `TryExec` that is not installed keeps it from starting;
+- `X-GNOME-Autostart-enabled=false` and `AutostartCondition` are GNOME's, and **dex ignores them**: the
+  entry still starts.
+
+## Tools
+
+| tool | | what |
+|---|---|---|
+| `xdg_user_dirs` | r | each folder as written, the path it resolves to, whether it exists as a directory or points at the home, the folder xdg-user-dirs would have made; whether the update may rewrite the file, and from which file that is decided; the locale |
+| `xdg_default` | r/a | the default for a MIME type or a URL scheme (`https`, `mailto`): what `xdg-open` uses (xdg-mime) and what GTK programs use (gio), flagged when they differ; which list decided it and which named applications were passed over as not installed; the application and whether its program is installed. `set` makes an installed desktop file the default through `xdg-mime default`, in the person's list |
+| `xdg_open_handlers` | r | the same for http, https, mailto, HTML, folders, plain text, Markdown, PDF, PNG, JPEG, MP4, MP3 and any types given; every mimeapps list in reading order and whose it is; every default naming an application that is not installed; every installed handler whose program is missing |
+| `xdg_autostart` | r | every autostart entry, the account's and the system's: what it runs and whether that is installed, Hidden, OnlyShowIn/NotShowIn, whether dex starts it (and if not, why), whether the window manager's configuration starts the same program too, and how many of the account's processes run it now |
+| `xdg_check` | r | the folders file is the mesh's, every folder it names exists, the update cannot rewrite it; the mesh's list is in place, every list parses with no group or key written twice, no default names a missing application, no handler's program is missing; no program has two starters at login, every program dex starts is installed |
+
+From `/proc` only the account's own processes are read, and of each only its command line and name.
+
+## What it leaves found
+
+The person's `~/.config/mimeapps.list`; the folders; every autostart entry; every desktop file under
+`~/.local/share/applications`, including its `mimeinfo.cache`; `/etc/xdg/user-dirs.conf` and
+`user-dirs.defaults` (the package's); and the `xdg-user-dirs.service` user unit.
+
+## The one-off migration (ADR 0182)
+
+**Before the first assignment,** set the three settings on the mesh's layer (`$HOME/Desktop`,
+`$HOME/Public`, `$HOME/Videos`) and on the desktop machine's layer (`$HOME/` for all three).
+
+**Once `xdg` is assigned, on the laptop:**
+
+1. Delete `~/.local/share/applications/mimeapps.list` and `~/.local/share/applications/defaults.list`.
+   Both are links the retired predecessor made into its own tree, which is gone; they point at nothing.
+2. `~/.config/autostart/slack.desktop` is the predecessor's too (its comment says so). It still starts
+   Slack, and is left until a Slack module owns it.
+
+**On the desktop machine:** nothing to remove. `~/Desktop` is a text file, not a folder, which is why
+`desktop-dir` is the home there; move it aside and change the setting if a Desktop folder is wanted.
+
+## What changes when it is assigned
+
+| | the laptop | the desktop machine |
+|---|---|---|
+| packages | none (both present) | the same |
+| `user-dirs.dirs` | the found file kept once, then the module's: the same eight folders, and `PROJECTS` becomes `~/projects` instead of the home | the found file kept once, then the module's: the same eight folders, and a `PROJECTS` line (`~/projects`) where there was none |
+| `user-dirs.conf` | new: the update stops rewriting the file at login | new: the update, which `dex` starts here since `i3` installed it, would otherwise have added `PROJECTS` and created `~/Projects` at the next login |
+| `/etc/xdg/mimeapps.list` | new; changes no answer today, because the person's list says the same | the same |
+| running programs, the person's list, autostart | nothing | nothing |
+
+**The one visible change is `PROJECTS`:** `xdg-user-dir PROJECTS` answers `~/projects`, the folder
+where the operator's repositories are, on both machines. GLib knows only the eight older folders, so
+GTK programs see no change at all.
+
+## What `xdg_check` will say at first
+
+Measured on the laptop before assignment, and expected on both: the defaults naming applications that
+are not installed (the 55 Code-OSS types and the four others above) fail "every default names an
+installed application", until the person removes them from their list or installs the editor. On the
+laptop, the predecessor's two dead links fail "the mimeapps lists are sane" until migration step 1. It
+also showed that `audio/mpeg` opens in Audacity from `xdg-open` and in mpv from GTK programs, because
+no list names a default for it: one `xdg_default` with `set` settles it.
+
+## Blockers
+
+- The three settings must be set before the first assignment (above).

modules/xdg/cmd/xdg-tools/autostart.go

@@ -0,0 +1,234 @@
+package main
+
+import (
+	"bufio"
+	"os"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"syscall"
+)
+
+// Autostart is one XDG autostart entry, and what the session does with it.
+type Autostart struct {
+	Entry
+	Scope string `json:"scope"` // user or system
+	// Overrides names the system entry of the same name this user entry hides; OverriddenBy the
+	// user entry hiding this system one.
+	Overrides    string `json:"overrides,omitempty"`
+	OverriddenBy string `json:"overridden_by,omitempty"`
+	DexStarts    bool   `json:"dex_starts"`
+	Why          string `json:"why"`
+	AlsoStarted  string `json:"also_started_by,omitempty"`
+	Running      int    `json:"running"`
+}
+
+// dexDecides says whether `dex --autostart --environment <env>` starts an entry, by dex's own
+// rules (dex 0.10): an entry of the same name in an earlier directory wins; Hidden=true, an
+// OnlyShowIn without the environment, a NotShowIn with it, a TryExec that is not there, or a type
+// other than Application keep it from starting. X-GNOME-Autostart-enabled and AutostartCondition
+// are GNOME's, and dex does not read them.
+func (m *Machine) dexDecides(a *Autostart, env string) {
+	switch {
+	case a.OverriddenBy != "":
+		a.Why = "hidden by the user entry " + a.OverriddenBy
+	case a.Broken != "":
+		a.Why = a.Broken
+	case a.Type != "" && a.Type != "Application":
+		a.Why = "type " + a.Type + ", not Application"
+	case a.Hidden:
+		a.Why = "Hidden=true"
+	case len(a.OnlyShow) > 0 && !contains(a.OnlyShow, env):
+		a.Why = "OnlyShowIn " + strings.Join(a.OnlyShow, ";") + " does not name " + env
+	case contains(a.NotShow, env):
+		a.Why = "NotShowIn names " + env
+	case a.TryExec != "" && !m.tryExecFound(a.TryExec):
+		a.Why = "TryExec " + a.TryExec + " is not installed"
+	default:
+		a.DexStarts = true
+		a.Why = "started at every login"
+		if !a.Found {
+			a.Why = "started at every login, and fails: " + a.Program + " is not installed"
+		}
+		if strings.EqualFold(a.GnomeEnabled, "false") {
+			a.Why += "; X-GNOME-Autostart-enabled=false does not stop dex (use Hidden=true)"
+		}
+	}
+}
+
+func (m *Machine) tryExecFound(p string) bool {
+	_, ok := m.executable(p)
+	return ok
+}
+
+func contains(list []string, s string) bool {
+	for _, x := range list {
+		if strings.EqualFold(x, s) {
+			return true
+		}
+	}
+	return false
+}
+
+// autostartDirs are the account's directory, then the system's, as dex reads them.
+func (m *Machine) autostartDirs() []struct{ dir, scope string } {
+	out := []struct{ dir, scope string }{{filepath.Join(m.configHome(), "autostart"), "user"}}
+	for _, d := range m.configDirs() {
+		out = append(out, struct{ dir, scope string }{filepath.Join(d, "autostart"), "system"})
+	}
+	return out
+}
+
+// Autostarts lists every entry, user and system, with dex's decision for env.
+func (m *Machine) Autostarts(env string) []Autostart {
+	var out []Autostart
+	first := map[string]int{}
+	procs := m.processes()
+	starts := m.windowManagerStarts()
+	for _, d := range m.autostartDirs() {
+		entries, _ := os.ReadDir(m.p(d.dir))
+		for _, de := range entries {
+			if !strings.HasSuffix(de.Name(), ".desktop") {
+				continue
+			}
+			a := Autostart{Entry: m.readEntry(filepath.Join(d.dir, de.Name())), Scope: d.scope}
+			if i, seen := first[de.Name()]; seen {
+				a.OverriddenBy = out[i].File
+				out[i].Overrides = a.File
+			} else {
+				first[de.Name()] = len(out)
+			}
+			out = append(out, a)
+		}
+	}
+	for i := range out {
+		a := &out[i]
+		m.dexDecides(a, env)
+		a.Running = procs.count(a.Program)
+		if by, ok := starts[filepath.Base(a.Program)]; ok && a.Program != "" {
+			a.AlsoStarted = by
+		}
+	}
+	return out
+}
+
+// procs are the account's processes: each one's first two words, base names only, and its name.
+type procs [][3]string
+
+// processes reads the account's own processes from /proc; nothing but the command line and the
+// process's name is read.
+func (m *Machine) processes() procs {
+	var out procs
+	entries, _ := os.ReadDir(m.p("/proc"))
+	self := strconv.Itoa(os.Getpid())
+	for _, e := range entries {
+		if _, err := strconv.Atoi(e.Name()); err != nil || e.Name() == self {
+			continue
+		}
+		dir := m.p(filepath.Join("/proc", e.Name()))
+		info, err := os.Stat(dir)
+		if err != nil {
+			continue
+		}
+		if st, ok := info.Sys().(*syscall.Stat_t); !ok || int(st.Uid) != m.UID {
+			continue
+		}
+		raw, err := os.ReadFile(filepath.Join(dir, "cmdline"))
+		if err != nil || len(raw) == 0 {
+			continue
+		}
+		words := strings.Split(strings.TrimRight(string(raw), "\x00"), "\x00")
+		if len(words) == 1 {
+			// Chromium and Electron rewrite their command line as one string, words joined by spaces.
+			words = strings.Fields(words[0])
+		}
+		if len(words) == 0 {
+			continue
+		}
+		var p [3]string
+		if comm, err := os.ReadFile(filepath.Join(dir, "comm")); err == nil {
+			p[2] = strings.TrimSpace(string(comm))
+		}
+		p[0] = filepath.Base(words[0])
+		if len(words) > 1 {
+			p[1] = filepath.Base(words[1])
+		}
+		out = append(out, p)
+	}
+	return out
+}
+
+// count is how many processes run a program: as their command, or as the script an interpreter
+// runs (a Python applet is "python3 /usr/bin/applet").
+func (ps procs) count(program string) int {
+	if program == "" {
+		return 0
+	}
+	name := filepath.Base(program)
+	n := 0
+	for _, p := range ps {
+		// The kernel keeps a process's name to 15 bytes.
+		if p[0] == name || p[1] == name && isInterpreter(p[0]) || p[2] != "" && p[2] == truncate(name, 15) {
+			n++
+		}
+	}
+	return n
+}
+
+func truncate(s string, n int) string {
+	if len(s) > n {
+		return s[:n]
+	}
+	return s
+}
+
+func isInterpreter(cmd string) bool {
+	for _, i := range []string{"python", "perl", "sh", "bash", "node", "ruby"} {
+		if strings.HasPrefix(cmd, i) {
+			return true
+		}
+	}
+	return false
+}
+
+// windowManagerStarts are the programs the window manager's configuration starts itself, by base
+// name, with the line that does it. Read only: the configuration is the window manager's module's.
+func (m *Machine) windowManagerStarts() map[string]string {
+	out := map[string]string{}
+	files := []string{filepath.Join(m.configHome(), "i3", "config")}
+	more, _ := filepath.Glob(m.p(filepath.Join(m.configHome(), "i3", "config.d", "*.conf")))
+	sort.Strings(more)
+	for _, f := range more {
+		files = append(files, strings.TrimPrefix(f, m.Root))
+	}
+	for _, f := range files {
+		h, err := os.Open(m.p(f))
+		if err != nil {
+			continue
+		}
+		sc := bufio.NewScanner(h)
+		n := 0
+		for sc.Scan() {
+			n++
+			words := strings.Fields(sc.Text())
+			if len(words) < 2 || words[0] != "exec" && words[0] != "exec_always" {
+				continue
+			}
+			rest := words[1:]
+			for len(rest) > 0 && strings.HasPrefix(rest[0], "--") {
+				rest = rest[1:]
+			}
+			if len(rest) == 0 {
+				continue
+			}
+			prog := filepath.Base(Program(strings.Join(rest, " ")))
+			if prog == "dex" {
+				continue
+			}
+			out[prog] = m.tilde(f) + ":" + strconv.Itoa(n)
+		}
+		h.Close()
+	}
+	return out
+}

modules/xdg/cmd/xdg-tools/check.go

@@ -0,0 +1,126 @@
+package main
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+)
+
+// Check is one line of xdg_check's answer.
+type Check struct {
+	Name   string `json:"name"`
+	OK     bool   `json:"ok"`
+	Detail string `json:"detail"`
+}
+
+// Check is xdg_check: whether the account's XDG conventions are as the module declares them, and
+// what is wrong in what it holds as found.
+func (m *Machine) Check(env string) map[string]any {
+	var checks []Check
+	add := func(name string, ok bool, detail string) { checks = append(checks, Check{name, ok, detail}) }
+
+	// The folders.
+	u := m.UserDirs()
+	add("user-dirs.dirs is the mesh's", u.Meshs, map[bool]string{
+		true:  u.File + " carries the module's header",
+		false: u.File + " has no header of module xdg: the module is not assigned here, or the file was rewritten since the last push",
+	}[u.Meshs])
+	var missing []string
+	for _, d := range u.Dirs {
+		if !d.Home && !d.Exists {
+			missing = append(missing, fmt.Sprintf("%s → %s (%s)", d.Name, d.Path, d.Kind))
+		}
+	}
+	add("every folder it names exists", len(missing) == 0, orNone(missing, "each is a directory, or the home"))
+	add("xdg-user-dirs-update leaves it alone", !u.Update.Enabled, "enabled is "+fmt.Sprint(u.Update.Enabled)+", from "+u.Update.DecidedBy)
+
+	// The default applications.
+	var listProblems []string
+	meshListFound := false
+	for _, l := range m.lists() {
+		if l.File == MeshList {
+			meshListFound = true
+		}
+		switch {
+		case l.Broken != "":
+			listProblems = append(listProblems, l.File+": "+l.Broken)
+		case len(l.Keys.DupGroups) > 0:
+			listProblems = append(listProblems, fmt.Sprintf("%s: the group %s is written twice, and GLib and xdg-mime then answer differently", l.File, strings.Join(l.Keys.DupGroups, ", ")))
+		case len(l.Keys.DupKeys) > 0:
+			listProblems = append(listProblems, fmt.Sprintf("%s: %s written twice, and GLib and xdg-mime then answer differently", l.File, strings.Join(l.Keys.DupKeys, ", ")))
+		case len(l.Keys.Unparsable) > 0:
+			listProblems = append(listProblems, fmt.Sprintf("%s: lines %v are not key=value under a group", l.File, l.Keys.Unparsable))
+		}
+		if m.deprecated(l.File) && strings.HasPrefix(l.File, "~/") {
+			listProblems = append(listProblems, l.File+": a list in the deprecated place, which nothing current writes (a predecessor's; remove it once)")
+		}
+	}
+	for _, f := range []string{filepath.Join(m.dataHome(), "applications", "defaults.list")} {
+		if m.kind(f) != "absent" || m.isLink(f) {
+			listProblems = append(listProblems, m.tilde(f)+": the long-obsolete defaults.list, which nothing reads any more; remove it once")
+		}
+	}
+	add("the mesh's default applications are in place", meshListFound, MeshList)
+	add("the mimeapps lists are sane", len(listProblems) == 0, orNone(listProblems, "each parses, with no group or key written twice"))
+	var dead []string
+	for _, d := range m.deadDefaults() {
+		dead = append(dead, fmt.Sprintf("%s: %s=%s", d.File, d.Type, d.ID))
+	}
+	add("every default names an installed application", len(dead) == 0, orNone(dead, "all installed"))
+	var broken []string
+	for _, e := range m.brokenHandlers() {
+		why := e.Broken
+		if why == "" {
+			why = e.Program + " is not installed"
+		}
+		broken = append(broken, fmt.Sprintf("%s (%s): %s", e.ID, e.File, why))
+	}
+	add("no handler's program is missing", len(broken) == 0, orNone(broken, "every application declaring a type can run"))
+
+	// Autostart.
+	starts := m.Autostarts(env)
+	byProgram := map[string][]string{}
+	var twice, failing []string
+	for _, a := range starts {
+		if !a.DexStarts {
+			continue
+		}
+		byProgram[filepath.Base(a.Program)] = append(byProgram[filepath.Base(a.Program)], a.File)
+		if a.AlsoStarted != "" {
+			twice = append(twice, fmt.Sprintf("%s: by %s and by %s", a.Program, a.File, a.AlsoStarted))
+		}
+		if !a.Found {
+			failing = append(failing, fmt.Sprintf("%s: %s is not installed", a.File, a.Program))
+		}
+	}
+	for _, p := range sortedKeys(byProgram) {
+		if len(byProgram[p]) > 1 {
+			twice = append(twice, fmt.Sprintf("%s: by %s", p, strings.Join(byProgram[p], " and ")))
+		}
+	}
+	sort.Strings(twice)
+	add("no program is started twice at login", len(twice) == 0, orNone(twice, "each autostarted program has one starter"))
+	add("every program dex starts is installed", len(failing) == 0, orNone(failing, "all installed"))
+
+	failingN := 0
+	for _, c := range checks {
+		if !c.OK {
+			failingN++
+		}
+	}
+	return map[string]any{"checks": checks, "failing": failingN}
+}
+
+func (m *Machine) isLink(path string) bool {
+	_, err := os.Lstat(m.p(path))
+	return err == nil
+}
+
+func orNone(items []string, fine string) string {
+	if len(items) == 0 {
+		return fine
+	}
+	return strings.Join(items, "; ")
+}

modules/xdg/cmd/xdg-tools/desktop.go

@@ -0,0 +1,234 @@
+package main
+
+import (
+	"bufio"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+)
+
+// KeyFile is a freedesktop key file (a desktop entry, a mimeapps list): groups of key=value.
+// Readers disagree on a group or a key written twice (GLib keeps the last, xdg-mime the first),
+// so both are recorded rather than merged silently.
+type KeyFile struct {
+	Groups     map[string]map[string]string
+	Order      []string
+	DupGroups  []string
+	DupKeys    []string // "group: key"
+	Unparsable []int    // line numbers
+}
+
+// ParseKeyFile reads a key file; `#` lines are comments. A localised key (Name[de]) is kept under
+// its own name.
+func ParseKeyFile(text string) KeyFile {
+	k := KeyFile{Groups: map[string]map[string]string{}}
+	group := ""
+	sc := bufio.NewScanner(strings.NewReader(text))
+	sc.Buffer(make([]byte, 64<<10), 1<<20)
+	n := 0
+	for sc.Scan() {
+		n++
+		l := strings.TrimSpace(sc.Text())
+		if l == "" || strings.HasPrefix(l, "#") {
+			continue
+		}
+		if strings.HasPrefix(l, "[") && strings.HasSuffix(l, "]") {
+			group = l[1 : len(l)-1]
+			if _, seen := k.Groups[group]; seen {
+				k.DupGroups = append(k.DupGroups, group)
+			} else {
+				k.Groups[group] = map[string]string{}
+				k.Order = append(k.Order, group)
+			}
+			continue
+		}
+		key, value, ok := strings.Cut(l, "=")
+		if !ok || group == "" {
+			k.Unparsable = append(k.Unparsable, n)
+			continue
+		}
+		key, value = strings.TrimSpace(key), strings.TrimSpace(value)
+		if _, seen := k.Groups[group][key]; seen {
+			k.DupKeys = append(k.DupKeys, group+": "+key)
+			// The first value is kept, as xdg-mime reads it; the duplicate is reported.
+			continue
+		}
+		k.Groups[group][key] = value
+	}
+	return k
+}
+
+// List splits a key's value at `;`, dropping empty items.
+func List(v string) []string {
+	var out []string
+	for _, s := range strings.Split(v, ";") {
+		if s = strings.TrimSpace(s); s != "" {
+			out = append(out, s)
+		}
+	}
+	return out
+}
+
+// Entry is one desktop entry, as the tools need it.
+type Entry struct {
+	ID        string   `json:"id"`
+	File      string   `json:"file"`
+	Name      string   `json:"name,omitempty"`
+	Type      string   `json:"type,omitempty"`
+	Exec      string   `json:"exec,omitempty"`
+	TryExec   string   `json:"try_exec,omitempty"`
+	Program   string   `json:"program,omitempty"`
+	Found     bool     `json:"program_found"`
+	MimeTypes []string `json:"mime_types,omitempty"`
+	Hidden    bool     `json:"hidden,omitempty"`
+	NoDisplay bool     `json:"no_display,omitempty"`
+	OnlyShow  []string `json:"only_show_in,omitempty"`
+	NotShow   []string `json:"not_show_in,omitempty"`
+	// GnomeEnabled is X-GNOME-Autostart-enabled as written ("" when absent).
+	GnomeEnabled string `json:"x_gnome_autostart_enabled,omitempty"`
+	Broken       string `json:"broken,omitempty"`
+}
+
+// readEntry reads one desktop file; a dangling link or an unreadable file is an entry that says so.
+func (m *Machine) readEntry(path string) Entry {
+	e := Entry{ID: filepath.Base(path), File: m.tilde(path)}
+	text, ok := m.read(path)
+	if !ok {
+		if _, err := os.Lstat(m.p(path)); err == nil {
+			e.Broken = "a link to nothing, or unreadable"
+		} else {
+			e.Broken = "absent"
+		}
+		return e
+	}
+	g := ParseKeyFile(text).Groups["Desktop Entry"]
+	if g == nil {
+		e.Broken = "no [Desktop Entry] group"
+		return e
+	}
+	e.Name, e.Type, e.Exec, e.TryExec = g["Name"], g["Type"], g["Exec"], g["TryExec"]
+	e.MimeTypes = List(g["MimeType"])
+	e.Hidden = g["Hidden"] == "true"
+	e.NoDisplay = g["NoDisplay"] == "true"
+	e.OnlyShow, e.NotShow = List(g["OnlyShowIn"]), List(g["NotShowIn"])
+	e.GnomeEnabled = g["X-GNOME-Autostart-enabled"]
+	e.Program = Program(e.Exec)
+	if e.TryExec != "" {
+		_, tryFound := m.executable(e.TryExec)
+		_, execFound := m.executable(e.Program)
+		e.Found = tryFound && execFound
+	} else {
+		_, e.Found = m.executable(e.Program)
+	}
+	return e
+}
+
+// Program is the program an Exec line runs: its first word, unquoted, past `env` and its
+// assignments, and into the command of `sh -c` (and bash's, zsh's), where a launcher hides it.
+func Program(exec string) string {
+	words := splitExec(exec)
+	for len(words) > 0 {
+		w := words[0]
+		switch {
+		case filepath.Base(w) == "env":
+			words = words[1:]
+			for len(words) > 0 && (strings.Contains(words[0], "=") || strings.HasPrefix(words[0], "-")) {
+				words = words[1:]
+			}
+			continue
+		case isShell(w) && len(words) >= 3 && words[1] == "-c":
+			words = splitExec(words[2])
+			continue
+		}
+		return w
+	}
+	return ""
+}
+
+func isShell(w string) bool {
+	switch filepath.Base(w) {
+	case "sh", "bash", "zsh", "dash":
+		return true
+	}
+	return false
+}
+
+// splitExec splits an Exec value into words: double quotes as the desktop-entry specification
+// says (with backslash escapes), single quotes as a shell would, field codes left as words.
+func splitExec(s string) []string {
+	var words []string
+	var cur strings.Builder
+	in, quote, started := false, byte(0), false
+	for i := 0; i < len(s); i++ {
+		c := s[i]
+		switch {
+		case in && c == quote:
+			in = false
+		case in && quote == '"' && c == '\\' && i+1 < len(s):
+			i++
+			cur.WriteByte(s[i])
+		case in:
+			cur.WriteByte(c)
+		case c == '"' || c == '\'':
+			in, quote, started = true, c, true
+		case c == ' ' || c == '\t':
+			if started {
+				words = append(words, cur.String())
+				cur.Reset()
+				started = false
+			}
+		default:
+			cur.WriteByte(c)
+			started = true
+		}
+	}
+	if started {
+		words = append(words, cur.String())
+	}
+	return words
+}
+
+// appDirs are where desktop files are found, most preferred first.
+func (m *Machine) appDirs() []string {
+	dirs := []string{filepath.Join(m.dataHome(), "applications")}
+	for _, d := range m.dataDirs() {
+		dirs = append(dirs, filepath.Join(d, "applications"))
+	}
+	return dirs
+}
+
+// findApp finds the desktop file an id names, as an application would: the first directory that
+// has it. A link to nothing, or an entry marked Hidden, is not an installed application.
+func (m *Machine) findApp(id string) (Entry, bool) {
+	for _, d := range m.appDirs() {
+		path := filepath.Join(d, id)
+		if _, err := os.Lstat(m.p(path)); err != nil {
+			continue
+		}
+		e := m.readEntry(path)
+		if e.Broken != "" || e.Hidden {
+			return e, false
+		}
+		return e, true
+	}
+	return Entry{ID: id}, false
+}
+
+// apps are every desktop file in the application directories, the first of each id.
+func (m *Machine) apps() []Entry {
+	seen := map[string]bool{}
+	var out []Entry
+	for _, d := range m.appDirs() {
+		entries, _ := os.ReadDir(m.p(d))
+		for _, de := range entries {
+			if !strings.HasSuffix(de.Name(), ".desktop") || seen[de.Name()] {
+				continue
+			}
+			seen[de.Name()] = true
+			out = append(out, m.readEntry(filepath.Join(d, de.Name())))
+		}
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].ID < out[j].ID })
+	return out
+}

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

@@ -0,0 +1,209 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"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 (
+	callTimeout = 5 * time.Second
+	outputCap   = 64 << 10
+)
+
+// Runner runs a command with an environment and answers its standard output; a failure carries
+// what the command said on standard error. Injected, so the tools are tested without a machine.
+type Runner func(ctx context.Context, env []string, name string, args ...string) (string, error)
+
+// Machine is everything the tools read. Root is "" on the machine and a fake tree in tests; every
+// other path is as the machine names it.
+type Machine struct {
+	Root    string
+	Home    string
+	UID     int
+	Desktop string // the session's XDG_CURRENT_DESKTOP, lower case
+	Run     Runner
+	Timeout time.Duration
+}
+
+// NewMachine is the real machine, as the operator's account the runtime serves the tools as.
+func NewMachine() *Machine {
+	home := os.Getenv("MESH_OPERATOR_HOME")
+	if home == "" {
+		home, _ = os.UserHomeDir()
+	}
+	desktop := strings.ToLower(os.Getenv("XDG_CURRENT_DESKTOP"))
+	if desktop == "" {
+		// The window manager's session says i3; the runtime is not in the session, so it says nothing.
+		desktop = "i3"
+	}
+	return &Machine{Home: home, UID: os.Getuid(), Desktop: desktop, Run: run, Timeout: callTimeout}
+}
+
+// run is the machine's Runner: the command in its own process group, killed with everything it
+// started at the deadline, each stream cut at outputCap.
+func run(ctx context.Context, env []string, name string, args ...string) (string, error) {
+	cmd := exec.Command(name, args...)
+	cmd.Env = env
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+	out, errb := &capped{}, &capped{}
+	cmd.Stdout, cmd.Stderr = out, errb
+	if err := cmd.Start(); err != nil {
+		return "", err
+	}
+	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)
+		<-done
+		return out.String(), fmt.Errorf("%s did not finish in time", name)
+	}
+	if err != nil {
+		said := strings.TrimSpace(errb.String())
+		if said == "" {
+			said = strings.TrimSpace(out.String())
+		}
+		var exit *exec.ExitError
+		if errors.As(err, &exit) {
+			return out.String(), fmt.Errorf("%s exited %d: %s", name, exit.ExitCode(), said)
+		}
+		return out.String(), fmt.Errorf("%s: %v", name, err)
+	}
+	return out.String(), nil
+}
+
+// capped keeps the first outputCap bytes written to it.
+type capped struct {
+	buf bytes.Buffer
+	cut bool
+}
+
+func (c *capped) Write(p []byte) (int, error) {
+	if room := outputCap - 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() }
+
+// cmd runs one command, bounded, with the account's XDG environment.
+func (m *Machine) cmd(name string, args ...string) (string, error) {
+	t := m.Timeout
+	if t == 0 {
+		t = callTimeout
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), t)
+	defer cancel()
+	return m.Run(ctx, m.env(), name, args...)
+}
+
+// env is what xdg-mime and gio are given: the account's home and the session's data directories,
+// so they look where the session looks. Nothing else of the runtime's environment is passed on.
+func (m *Machine) env() []string {
+	return []string{
+		"HOME=" + m.Home,
+		"PATH=" + strings.Join(m.pathDirs(), ":"),
+		"LANG=C.UTF-8",
+		"XDG_CONFIG_HOME=" + m.configHome(),
+		"XDG_DATA_HOME=" + m.dataHome(),
+		"XDG_DATA_DIRS=" + strings.Join(m.dataDirs(), ":"),
+		"XDG_CURRENT_DESKTOP=" + m.Desktop,
+	}
+}
+
+// p is a machine path inside Root.
+func (m *Machine) p(path string) string { return filepath.Join(m.Root, path) }
+
+func (m *Machine) configHome() string { return filepath.Join(m.Home, ".config") }
+func (m *Machine) dataHome() string   { return filepath.Join(m.Home, ".local", "share") }
+
+// configDirs are the system's configuration directories: XDG_CONFIG_DIRS is unset in both
+// workstations' sessions or says only this.
+func (m *Machine) configDirs() []string { return []string{"/etc/xdg"} }
+
+// dataDirs are the session's XDG_DATA_DIRS on the workstations, those that exist.
+func (m *Machine) dataDirs() []string {
+	candidates := []string{
+		filepath.Join(m.Home, ".local", "share", "flatpak", "exports", "share"),
+		"/var/lib/flatpak/exports/share",
+		"/usr/local/share",
+		"/usr/share",
+		"/var/lib/snapd/desktop",
+	}
+	var out []string
+	for _, d := range candidates {
+		if d == "/usr/share" || d == "/usr/local/share" || m.isDir(d) {
+			out = append(out, d)
+		}
+	}
+	return out
+}
+
+// pathDirs is where a program is looked for: the account's own bin, then the system's.
+func (m *Machine) pathDirs() []string {
+	return []string{filepath.Join(m.Home, ".local", "bin"), "/usr/local/sbin", "/usr/local/bin", "/usr/bin", "/bin", "/usr/lib/flatpak/bin"}
+}
+
+func (m *Machine) isDir(path string) bool {
+	info, err := os.Stat(m.p(path))
+	return err == nil && info.IsDir()
+}
+
+func (m *Machine) read(path string) (string, bool) {
+	b, err := os.ReadFile(m.p(path))
+	if err != nil {
+		return "", false
+	}
+	return string(b), true
+}
+
+// executable is whether a program is there to run: an absolute path that is an executable file,
+// or a name found on the path.
+func (m *Machine) executable(program string) (string, bool) {
+	if program == "" {
+		return "", false
+	}
+	if strings.Contains(program, "/") {
+		return program, isExecutable(m.p(program))
+	}
+	for _, d := range m.pathDirs() {
+		full := filepath.Join(d, program)
+		if isExecutable(m.p(full)) {
+			return full, true
+		}
+	}
+	return program, false
+}
+
+func isExecutable(path string) bool {
+	info, err := os.Stat(path)
+	return err == nil && !info.IsDir() && info.Mode()&0o111 != 0
+}
+
+// tilde writes a path under the home as ~/…, which is how the README and the person name it.
+func (m *Machine) tilde(path string) string {
+	if path == m.Home {
+		return "~"
+	}
+	if strings.HasPrefix(path, m.Home+"/") {
+		return "~/" + strings.TrimPrefix(path, m.Home+"/")
+	}
+	return path
+}

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

@@ -0,0 +1,429 @@
+package main
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+)
+
+const home = "/home/op"
+
+// fake is a machine with these files under a temporary root; a value starting with "->" is a
+// symbolic link to the rest, and one starting with "#!" is an executable.
+func fake(t *testing.T, files map[string]string) *Machine {
+	t.Helper()
+	root := t.TempDir()
+	for p, c := range files {
+		full := filepath.Join(root, p)
+		if err := os.MkdirAll(filepath.Dir(full), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		switch {
+		case strings.HasPrefix(c, "->"):
+			if err := os.Symlink(strings.TrimPrefix(c, "->"), full); err != nil {
+				t.Fatal(err)
+			}
+		case c == "<dir>":
+			if err := os.MkdirAll(full, 0o755); err != nil {
+				t.Fatal(err)
+			}
+		default:
+			mode := os.FileMode(0o644)
+			if strings.HasPrefix(c, "#!") {
+				mode = 0o755
+			}
+			if err := os.WriteFile(full, []byte(c), mode); err != nil {
+				t.Fatal(err)
+			}
+		}
+	}
+	return &Machine{Root: root, Home: home, UID: os.Getuid(), Desktop: "i3", Timeout: time.Second,
+		Run: func(context.Context, []string, string, ...string) (string, error) { return "", nil }}
+}
+
+func app(name, exec, mime string) string {
+	s := "[Desktop Entry]\nType=Application\nName=" + name + "\nExec=" + exec + "\n"
+	if mime != "" {
+		s += "MimeType=" + mime + "\n"
+	}
+	return s
+}
+
+// The desktop's folders as found on 2026-10-05, in the module's file with that machine's settings.
+func desktopUserDirs(t *testing.T) string {
+	raw, err := os.ReadFile(filepath.Join("..", "..", "config", "user-dirs.dirs"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	r := strings.NewReplacer("${setting:desktop-dir}", "$HOME/", "${setting:publicshare-dir}", "$HOME/", "${setting:videos-dir}", "$HOME/")
+	return r.Replace(string(raw))
+}
+
+func TestTheFoldersAreReadAsXdgUserDirResolvesThem(t *testing.T) {
+	conf, _ := os.ReadFile(filepath.Join("..", "..", "config", "user-dirs.conf"))
+	m := fake(t, map[string]string{
+		home + "/.config/user-dirs.dirs":   desktopUserDirs(t),
+		home + "/.config/user-dirs.conf":   string(conf),
+		home + "/.config/user-dirs.locale": "en_US\n",
+		"/etc/xdg/user-dirs.conf":          "enabled=True\n",
+		"/etc/xdg/user-dirs.defaults":      "# c\nDESKTOP=Desktop\nDOWNLOAD=Downloads\nPROJECTS=Projects\nNEWTHING=New\n",
+		home + "/Desktop":                  "a file where the folder would be\n",
+		home + "/Downloads":                "<dir>",
+		home + "/projects":                 "<dir>",
+	})
+	a := m.UserDirs()
+	if !a.Meshs || a.Locale != "en_US" || a.Update.Enabled || a.Update.DecidedBy != "~/.config/user-dirs.conf" {
+		t.Fatalf("%+v", a)
+	}
+	got := map[string]UserDir{}
+	for _, d := range a.Dirs {
+		got[d.Name] = d
+	}
+	if len(a.Dirs) != 9 {
+		t.Fatalf("%d folders: %+v", len(a.Dirs), a.Dirs)
+	}
+	if d := got["DESKTOP"]; !d.Home || d.Path != "~" || d.Default != "~/Desktop" {
+		t.Errorf("DESKTOP: %+v", d)
+	}
+	if d := got["DOWNLOAD"]; d.Home || !d.Exists || d.Path != "~/Downloads" {
+		t.Errorf("DOWNLOAD: %+v", d)
+	}
+	if d := got["PROJECTS"]; d.Path != "~/projects" || !d.Exists || d.Default != "~/Projects" {
+		t.Errorf("PROJECTS: %+v", d)
+	}
+	if d := got["MUSIC"]; d.Exists || d.Kind != "absent" {
+		t.Errorf("MUSIC: %+v", d)
+	}
+	if !reflect.DeepEqual(a.Missing, []string{"NEWTHING"}) {
+		t.Errorf("defaults without a line: %v", a.Missing)
+	}
+}
+
+func TestAnUpdateLeftEnabledIsSaid(t *testing.T) {
+	m := fake(t, map[string]string{"/etc/xdg/user-dirs.conf": "# c\nenabled=True\nfilename_encoding=UTF-8\n"})
+	a := m.UserDirs()
+	if !a.Update.Enabled || a.Update.DecidedBy != "/etc/xdg/user-dirs.conf" || !strings.Contains(a.Update.Note, "rewrites the file") {
+		t.Fatalf("%+v", a.Update)
+	}
+}
+
+func TestATypeIsAMimeTypeOrAScheme(t *testing.T) {
+	for in, want := range map[string]string{
+		"https": "x-scheme-handler/https", "mailto:": "x-scheme-handler/mailto", "http://": "x-scheme-handler/http",
+		"text/html": "text/html", "x-scheme-handler/tg": "x-scheme-handler/tg", "application/xhtml+xml": "application/xhtml+xml",
+	} {
+		if got, err := Normalise(in); err != nil || got != want {
+			t.Errorf("%s: %s %v", in, got, err)
+		}
+	}
+	for _, bad := range []string{"", "text/html; rm -rf", "../x", "Text Html"} {
+		if _, err := Normalise(bad); err == nil {
+			t.Errorf("%q accepted", bad)
+		}
+	}
+}
+
+func TestTheProgramIsFoundBehindLaunchers(t *testing.T) {
+	// Exec lines found on the workstations.
+	for exec, want := range map[string]string{
+		`env APPIMAGELAUNCHER_DISABLE=1 DESKTOPINTEGRATION=0 /usr/bin/Plexamp.AppImage --disable-seccomp-filter-sandbox`: "/usr/bin/Plexamp.AppImage",
+		`sh -c "/opt/forticlient/gui/FortiClient >/dev/null 2>&1"`:                                                       "/opt/forticlient/gui/FortiClient",
+		`zsh -c 'dockly'`: "dockly",
+		`"/opt/claude-code/bin/claude" --handle-uri %u`: "/opt/claude-code/bin/claude",
+		`env LIBGL_ALWAYS_SOFTWARE=1 Telegram -- %U`:    "Telegram",
+		`/usr/bin/slack --gtk-version=3 -s %U`:          "/usr/bin/slack",
+		`"/path with space/Fleet" %u`:                   "/path with space/Fleet",
+		`steam steam://rungameid/427520`:                "steam",
+		`xterm -fa monospace -fs 11 -e glow -p %f`:      "xterm",
+		``: "",
+	} {
+		if got := Program(exec); got != want {
+			t.Errorf("%s: %q, want %q", exec, got, want)
+		}
+	}
+}
+
+func TestADuplicateGroupOrKeyIsReportedNotMerged(t *testing.T) {
+	k := ParseKeyFile("# >>> mesh >>>\n[Default Applications]\nx=a.desktop\n# <<<\n\n[Default Applications]\nx=b.desktop\ny=c\n[Added Associations]\nz=d;\nstray\n")
+	if !reflect.DeepEqual(k.DupGroups, []string{"Default Applications"}) || !reflect.DeepEqual(k.DupKeys, []string{"Default Applications: x"}) {
+		t.Fatalf("%+v", k)
+	}
+	if k.Groups["Default Applications"]["x"] != "a.desktop" || k.Groups["Default Applications"]["y"] != "c" || len(k.Unparsable) != 1 {
+		t.Fatalf("%+v", k)
+	}
+}
+
+// A machine with the mesh's list, the person's list, and some applications.
+func mimeMachine(t *testing.T, extra map[string]string) *Machine {
+	mesh, err := os.ReadFile(filepath.Join("..", "..", "config", "mimeapps.list"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	files := map[string]string{
+		MeshList:                        string(mesh),
+		home + "/.config/mimeapps.list": "[Default Applications]\ntext/plain=code-oss.desktop;\ninode/directory=xplr.desktop\nx-scheme-handler/https=gone.desktop;chromium.desktop;\n",
+		"/usr/share/applications/firefox.desktop":         app("Firefox", "/usr/lib/firefox/firefox %u", "text/html;x-scheme-handler/https;"),
+		"/usr/share/applications/chromium.desktop":        app("Chromium", "/usr/bin/chromium %U", "x-scheme-handler/https;"),
+		"/usr/share/applications/thunar.desktop":          app("Thunar", "thunar %F", "inode/directory;"),
+		home + "/.local/share/applications/xplr.desktop":  app("xplr", "xplr", "inode/directory;"),
+		home + "/.local/share/applications/fleet.desktop": app("Fleet", `"/home/op/fleet/bin/Fleet" %u`, "text/plain;"),
+		"/usr/lib/firefox/firefox":                        "#!/bin/sh\n",
+		"/usr/bin/chromium":                               "#!/bin/sh\n",
+		"/usr/bin/thunar":                                 "#!/bin/sh\n",
+	}
+	for k, v := range extra {
+		files[k] = v
+	}
+	return fake(t, files)
+}
+
+func TestTheDefaultIsDecidedInTheSpecificationsOrder(t *testing.T) {
+	m := mimeMachine(t, nil)
+	// The person's list names an application that is gone, then one that is installed.
+	if d := m.Decide("x-scheme-handler/https"); d.ID != "chromium.desktop" || d.File != "~/.config/mimeapps.list" ||
+		!reflect.DeepEqual(d.Skipped, []string{"gone.desktop (~/.config/mimeapps.list): not installed"}) {
+		t.Fatalf("%+v", d)
+	}
+	// The person's choice wins over the mesh's.
+	if d := m.Decide("inode/directory"); d.ID != "xplr.desktop" {
+		t.Fatalf("%+v", d)
+	}
+	// What the person has not chosen, the mesh's list answers.
+	if d := m.Decide("text/html"); d.ID != "firefox.desktop" || d.File != MeshList {
+		t.Fatalf("%+v", d)
+	}
+	// Nothing installed is named: no list decides.
+	if d := m.Decide("text/plain"); d.ID != "" || len(d.Skipped) != 1 {
+		t.Fatalf("%+v", d)
+	}
+	// The desktop's own list comes first of all.
+	m2 := mimeMachine(t, map[string]string{home + "/.config/i3-mimeapps.list": "[Default Applications]\ninode/directory=thunar.desktop\n"})
+	if d := m2.Decide("inode/directory"); d.ID != "thunar.desktop" || d.File != "~/.config/i3-mimeapps.list" {
+		t.Fatalf("%+v", d)
+	}
+}
+
+// recorded answers xdg-mime and gio as they answered on the laptop on 2026-10-05.
+func recorded(calls *[]string) Runner {
+	return func(_ context.Context, env []string, name string, args ...string) (string, error) {
+		*calls = append(*calls, name+" "+strings.Join(args, " "))
+		key := name + " " + strings.Join(args, " ")
+		switch key {
+		case "xdg-mime query default audio/mpeg":
+			return "audacity.desktop\n", nil
+		case "gio mime audio/mpeg":
+			return "Default application for “audio/mpeg”: mpv.desktop\nRegistered applications:\n\tmpv.desktop\n\taudacity.desktop\nRecommended applications:\n\tmpv.desktop\n\taudacity.desktop\n", nil
+		case "xdg-mime query default x-scheme-handler/https":
+			return "chromium.desktop\n", nil
+		case "gio mime x-scheme-handler/https":
+			return "Default application for “x-scheme-handler/https”: chromium.desktop\nRegistered applications:\n\tchromium.desktop\n", nil
+		case "xdg-mime query default x-scheme-handler/nothing-here":
+			return "", nil
+		case "gio mime x-scheme-handler/nothing-here":
+			return "No default applications for “x-scheme-handler/nothing-here”\n", nil
+		}
+		return "", nil
+	}
+}
+
+func TestTwoReadersThatDisagreeAreSaid(t *testing.T) {
+	var calls []string
+	m := mimeMachine(t, map[string]string{
+		"/usr/share/applications/audacity.desktop": app("Audacity", "audacity %F", "audio/mpeg;"),
+		"/usr/share/applications/mpv.desktop":      app("mpv", "mpv -- %U", "audio/mpeg;video/mp4;"),
+		"/usr/bin/audacity":                        "#!/bin/sh\n",
+	})
+	m.Run = recorded(&calls)
+	h := m.Handle("audio/mpeg")
+	if h.XdgOpen != "audacity.desktop" || h.Gio != "mpv.desktop" || !h.Disagree || h.App == nil || !h.App.Found {
+		t.Fatalf("%+v", h)
+	}
+	if !strings.Contains(h.Decision.File, "no list names") {
+		t.Fatalf("%+v", h.Decision)
+	}
+	none := m.Handle("x-scheme-handler/nothing-here")
+	if none.XdgOpen != "" || none.Gio != "" || none.Problem != "nothing opens it" {
+		t.Fatalf("%+v", none)
+	}
+}
+
+func TestTheEnvironmentGivenIsTheAccountsXdgOnly(t *testing.T) {
+	var env []string
+	m := mimeMachine(t, nil)
+	m.Run = func(_ context.Context, e []string, _ string, _ ...string) (string, error) { env = e; return "", nil }
+	m.Handle("text/html")
+	joined := strings.Join(env, "\n")
+	for _, want := range []string{"HOME=" + home, "XDG_CONFIG_HOME=" + home + "/.config", "XDG_CURRENT_DESKTOP=i3", "LANG=C.UTF-8"} {
+		if !strings.Contains(joined, want) {
+			t.Errorf("lacks %s: %v", want, env)
+		}
+	}
+	if len(env) != 7 {
+		t.Errorf("only the seven XDG words are passed on: %v", env)
+	}
+}
+
+func TestSettingADefaultWritesThePersonsListThroughXdgMime(t *testing.T) {
+	var calls []string
+	m := mimeMachine(t, nil)
+	m.Run = recorded(&calls)
+	a, err := m.SetDefault("x-scheme-handler/https", "chromium.desktop")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !contains(calls, "xdg-mime default chromium.desktop x-scheme-handler/https") {
+		t.Fatalf("%v", calls)
+	}
+	if a["written_to"] != "~/.config/mimeapps.list" || a["after"] != "chromium.desktop" || a["problem"] != nil {
+		t.Fatalf("%v", a)
+	}
+	for _, refused := range []string{"gone.desktop", "../../etc/passwd", "firefox", "x.desktop; rm"} {
+		calls = nil
+		if _, err := m.SetDefault("text/html", refused); err == nil || len(calls) != 0 {
+			t.Errorf("%s: %v %v", refused, err, calls)
+		}
+	}
+}
+
+func TestDeadDefaultsBrokenHandlersAndListsAreFound(t *testing.T) {
+	m := mimeMachine(t, map[string]string{
+		home + "/.local/share/applications/mimeapps.list":     "->/home/op/.retired/dotfiles/mimeapps.list",
+		home + "/.local/share/applications/defaults.list":     "->/home/op/.retired/dotfiles/mimeapps.list",
+		home + "/.local/share/applications/fleet-old.desktop": app("Fleet", "/home/op/gone/Fleet %u", "x-scheme-handler/fleet;"),
+	})
+	dead := m.deadDefaults()
+	var ids []string
+	for _, d := range dead {
+		// The fake installs none of the mesh's list's applications but firefox and thunar.
+		if d.File == "~/.config/mimeapps.list" {
+			ids = append(ids, d.Type+"="+d.ID)
+		}
+	}
+	if !reflect.DeepEqual(ids, []string{"text/plain=code-oss.desktop", "x-scheme-handler/https=gone.desktop"}) {
+		t.Fatalf("%v", ids)
+	}
+	var broken []string
+	for _, e := range m.brokenHandlers() {
+		broken = append(broken, e.ID)
+	}
+	// xplr's program is not installed in the fake, nor fleet's.
+	if !reflect.DeepEqual(broken, []string{"fleet-old.desktop", "fleet.desktop", "xplr.desktop"}) {
+		t.Fatalf("%v", broken)
+	}
+	c := m.Check("i3")
+	checks := map[string]Check{}
+	for _, x := range c["checks"].([]Check) {
+		checks[x.Name] = x
+	}
+	if s := checks["the mimeapps lists are sane"]; s.OK || !strings.Contains(s.Detail, "a link to nothing") || !strings.Contains(s.Detail, "defaults.list") {
+		t.Fatalf("%+v", s)
+	}
+	if s := checks["the mesh's default applications are in place"]; !s.OK {
+		t.Fatalf("%+v", s)
+	}
+}
+
+func TestAMeshBlockInThePersonsListIsWhatTheCheckRefuses(t *testing.T) {
+	// Why the module does not write a block into ~/.config/mimeapps.list: GLib reads the last of two
+	// groups, xdg-mime the first, and either rewrites the file around the block.
+	m := mimeMachine(t, map[string]string{
+		home + "/.config/mimeapps.list": "# >>> mesh >>>\n[Default Applications]\ntext/html=firefox.desktop\n# <<< mesh <<<\n[Default Applications]\ntext/html=chromium.desktop\n",
+	})
+	c := m.Check("i3")
+	for _, x := range c["checks"].([]Check) {
+		if x.Name == "the mimeapps lists are sane" && (x.OK || !strings.Contains(x.Detail, "written twice")) {
+			t.Fatalf("%+v", x)
+		}
+	}
+}
+
+func autostartMachine(t *testing.T) *Machine {
+	return fake(t, map[string]string{
+		home + "/.config/autostart/slack.desktop":     app("Slack", "/usr/bin/slack -s %U", "") + "Hidden=false\n",
+		home + "/.config/autostart/blueman.desktop":   app("Blueman", "blueman-applet", "") + "Hidden=true\n",
+		home + "/.config/autostart/nextcloud.desktop": app("Nextcloud", `"/usr/bin/nextcloud" --background`, "") + "X-GNOME-Autostart-enabled=false\n",
+		"/etc/xdg/autostart/blueman.desktop":          app("Blueman", "blueman-applet", ""),
+		"/etc/xdg/autostart/picom.desktop":            app("picom", "picom", "") + "TryExec=picom\n",
+		"/etc/xdg/autostart/nm-applet.desktop":        app("nm", "nm-applet", "") + "NotShowIn=KDE;GNOME;\n",
+		"/etc/xdg/autostart/gnome-keyring.desktop":    app("keyring", "/usr/bin/gnome-keyring-daemon --start", "") + "OnlyShowIn=GNOME;Unity;\n",
+		"/etc/xdg/autostart/geoclue.desktop":          app("geoclue", "/usr/lib/geoclue-2.0/demos/agent", "") + "NotShowIn=i3;\n",
+		"/etc/xdg/autostart/print.desktop":            app("print", "system-config-printer-applet", "") + "TryExec=system-config-printer-applet\n",
+		"/etc/xdg/autostart/polychromatic.desktop":    app("poly", "polychromatic-helper --autostart", ""),
+		"/etc/xdg/autostart/slack-too.desktop":        app("Slack", "/usr/bin/slack", ""),
+		home + "/.config/i3/config":                   "exec --no-startup-id dex --autostart --environment i3\nexec --no-startup-id picom\n",
+		home + "/.config/i3/config.d/90-x.conf":       "exec_always --no-startup-id polychromatic-tray-applet\n",
+		"/usr/bin/slack":                              "#!/bin/sh\n",
+		"/usr/bin/picom":                              "#!/bin/sh\n",
+		"/usr/bin/nm-applet":                          "#!/bin/sh\n",
+		"/usr/bin/nextcloud":                          "#!/bin/sh\n",
+		"/usr/bin/polychromatic-helper":               "#!/bin/sh\n",
+		"/proc/101/cmdline":                           "/usr/lib/slack/slack --type=renderer --enable-crash-reporter",
+		"/proc/101/comm":                              "slack\n",
+		"/proc/102/cmdline":                           "picom\x00",
+		"/proc/103/cmdline":                           "python3\x00/usr/bin/polychromatic-helper\x00--autostart\x00",
+		"/proc/104/cmdline":                           "nextcloud-sync-helper\x00",
+		"/proc/self/cmdline":                          "not a process\x00",
+	})
+}
+
+func TestAutostartIsDecidedAsDexDecides(t *testing.T) {
+	m := autostartMachine(t)
+	got := map[string]Autostart{}
+	for _, a := range m.Autostarts("i3") {
+		got[a.Scope+"/"+a.ID] = a
+	}
+	want := map[string]bool{
+		"user/slack.desktop": true, "user/blueman.desktop": false, "user/nextcloud.desktop": true,
+		"system/blueman.desktop": false, "system/picom.desktop": true, "system/nm-applet.desktop": true,
+		"system/gnome-keyring.desktop": false, "system/geoclue.desktop": false, "system/print.desktop": false,
+		"system/polychromatic.desktop": true, "system/slack-too.desktop": true,
+	}
+	if len(got) != len(want) {
+		t.Fatalf("%d entries: %v", len(got), got)
+	}
+	for k, starts := range want {
+		if got[k].DexStarts != starts {
+			t.Errorf("%s: dex starts %v (%s)", k, got[k].DexStarts, got[k].Why)
+		}
+	}
+	if a := got["system/blueman.desktop"]; a.OverriddenBy != "~/.config/autostart/blueman.desktop" || got["user/blueman.desktop"].Overrides != "/etc/xdg/autostart/blueman.desktop" {
+		t.Errorf("the user's entry hides the system's of the same name: %+v", a)
+	}
+	if a := got["user/nextcloud.desktop"]; !strings.Contains(a.Why, "does not stop dex") {
+		t.Errorf("%s", a.Why)
+	}
+	if a := got["system/print.desktop"]; !strings.Contains(a.Why, "TryExec") {
+		t.Errorf("%s", a.Why)
+	}
+	if a := got["system/picom.desktop"]; a.AlsoStarted != "~/.config/i3/config:2" || a.Running != 1 {
+		t.Errorf("picom: %+v", a)
+	}
+	if got["user/slack.desktop"].Running != 1 || got["system/polychromatic.desktop"].Running != 1 || got["user/nextcloud.desktop"].Running != 0 {
+		t.Errorf("running: slack %d, polychromatic %d, nextcloud %d", got["user/slack.desktop"].Running,
+			got["system/polychromatic.desktop"].Running, got["user/nextcloud.desktop"].Running)
+	}
+}
+
+func TestTheCheckFindsTwoStartersAndAMissingProgram(t *testing.T) {
+	m := autostartMachine(t)
+	checks := map[string]Check{}
+	for _, c := range m.Check("i3")["checks"].([]Check) {
+		checks[c.Name] = c
+	}
+	twice := checks["no program is started twice at login"]
+	if twice.OK || !strings.Contains(twice.Detail, "picom: by /etc/xdg/autostart/picom.desktop and by ~/.config/i3/config:2") ||
+		!strings.Contains(twice.Detail, "slack: by ~/.config/autostart/slack.desktop and /etc/xdg/autostart/slack-too.desktop") {
+		t.Fatalf("%+v", twice)
+	}
+	// blueman's system entry is hidden by the user's, so dex starts nothing that is missing.
+	if c := checks["every program dex starts is installed"]; !c.OK {
+		t.Fatalf("%+v", c)
+	}
+	if c := checks["user-dirs.dirs is the mesh's"]; c.OK {
+		t.Fatalf("no file, yet %+v", c)
+	}
+}

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

@@ -0,0 +1,150 @@
+// xdg's Go tools bundle: the account's XDG desktop conventions — its folders, its default
+// applications and what starts at login. Served by the node's runtime as the operator account.
+//
+// None needs the display. Folders, lists and autostart entries are files; xdg-mime and gio answer
+// from the same files; whether a program runs is read from /proc. Only xdg_default's `set` changes
+// anything, and only the person's own list of defaults.
+package main
+
+import (
+	"fmt"
+	"os"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+func main() {
+	if err := stdio.Serve("", tools(NewMachine())); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+func text(args map[string]any, name string) (string, error) {
+	v, ok := args[name]
+	if !ok || v == nil {
+		return "", nil
+	}
+	s, isText := v.(string)
+	if !isText {
+		return "", fmt.Errorf("%s is text", name)
+	}
+	return s, nil
+}
+
+func tools(m *Machine) []stdio.Tool {
+	envArg := map[string]any{"type": "string", "description": "the desktop name dex is given (default: the session's, i3)"}
+	env := func(args map[string]any) (string, error) {
+		e, err := text(args, "environment")
+		if err != nil || e != "" {
+			return e, err
+		}
+		return m.Desktop, nil
+	}
+	return []stdio.Tool{
+		{
+			Name: "xdg_user_dirs",
+			Description: "The account's folders (Desktop, Downloads, Documents, …) as user-dirs.dirs names them: " +
+				"each one as written, the path it resolves to, whether it exists as a directory, whether it points " +
+				"at the home (not wanted), and the folder xdg-user-dirs would have made instead. Also whether " +
+				"xdg-user-dirs-update may rewrite the file at login, and the locale it was made in.",
+			Run: func(map[string]any) (any, error) { return m.UserDirs(), nil },
+		},
+		{
+			Name: "xdg_default",
+			Description: "The default application for a MIME type (text/html) or a URL scheme (https, mailto): what " +
+				"xdg-open uses, what GTK programs use, which mimeapps list decided it, the application's desktop " +
+				"file and whether its program is installed. With set (a desktop file id such as firefox.desktop), " +
+				"make it the default through xdg-mime: it is written to the person's own list, which the mesh " +
+				"never writes and which outranks the mesh's defaults.",
+			Input: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"type": map[string]any{"type": "string", "description": "a MIME type (application/pdf) or a URL scheme (https, mailto)"},
+					"set":  map[string]any{"type": "string", "description": "make this installed desktop file id the default (an action)"},
+				},
+				"required": []string{"type"},
+			},
+			Run: func(args map[string]any) (any, error) {
+				t, err := text(args, "type")
+				if err != nil {
+					return nil, err
+				}
+				mime, err := Normalise(t)
+				if err != nil {
+					return nil, err
+				}
+				set, err := text(args, "set")
+				if err != nil {
+					return nil, err
+				}
+				if set != "" {
+					return m.SetDefault(mime, set)
+				}
+				return m.Handle(mime), nil
+			},
+		},
+		{
+			Name: "xdg_open_handlers",
+			Description: "Who opens the links and files that matter (http, https, mailto, HTML, folders, text, " +
+				"Markdown, PDF, images, video, audio, and any types given): the application xdg-open and GTK " +
+				"programs pick and which list decided. Also every mimeapps list in the order applications read " +
+				"them, every default naming an application that is not installed, and every installed handler " +
+				"whose program is missing.",
+			Input: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"types": map[string]any{"type": "array", "items": map[string]any{"type": "string"}, "description": "more MIME types or URL schemes to answer for"},
+				},
+			},
+			Run: func(args map[string]any) (any, error) {
+				var extra []string
+				if v, ok := args["types"]; ok && v != nil {
+					list, isList := v.([]any)
+					if !isList {
+						return nil, fmt.Errorf("types is a list of text")
+					}
+					for _, x := range list {
+						s, isText := x.(string)
+						if !isText {
+							return nil, fmt.Errorf("types is a list of text")
+						}
+						extra = append(extra, s)
+					}
+				}
+				return m.OpenHandlers(extra)
+			},
+		},
+		{
+			Name: "xdg_autostart",
+			Description: "Every XDG autostart entry, the account's and the system's: what it runs, Hidden, " +
+				"OnlyShowIn and NotShowIn, whether dex starts it at login under the window manager (and if not, " +
+				"why), whether the window manager's own configuration starts the same program too, and how many " +
+				"of the account's processes run it now.",
+			Input: map[string]any{"type": "object", "properties": map[string]any{"environment": envArg}},
+			Run: func(args map[string]any) (any, error) {
+				e, err := env(args)
+				if err != nil {
+					return nil, err
+				}
+				return map[string]any{"environment": e, "entries": m.Autostarts(e)}, nil
+			},
+		},
+		{
+			Name: "xdg_check",
+			Description: "Whether the account's XDG conventions are sound: user-dirs.dirs is the mesh's, every folder " +
+				"it names exists and xdg-user-dirs-update cannot rewrite it; the mesh's default applications are " +
+				"in place, every mimeapps list parses with nothing written twice, no default names an application " +
+				"that is not installed, no handler's program is missing; no program is started twice at login and " +
+				"every program dex starts is installed.",
+			Input: map[string]any{"type": "object", "properties": map[string]any{"environment": envArg}},
+			Run: func(args map[string]any) (any, error) {
+				e, err := env(args)
+				if err != nil {
+					return nil, err
+				}
+				return m.Check(e), nil
+			},
+		},
+	}
+}

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

@@ -0,0 +1,196 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"reflect"
+	"regexp"
+	"sort"
+	"strings"
+	"testing"
+)
+
+// xdg's shape: it claims no seat (the conventions are not a role anything calls), needs no
+// display, owns the account's folders file whole and the machine's lowest list of default
+// applications, and holds the person's own list of defaults and every autostart entry as found.
+
+type manifest struct {
+	Module        string           `json:"module"`
+	Capabilities  []string         `json:"capabilities"`
+	Requires      []string         `json:"requires"`
+	Claims        []any            `json:"claims"`
+	Tools         []string         `json:"tools"`
+	Shell         []any            `json:"shell"`
+	Contributions []any            `json:"contributions"`
+	Resources     []map[string]any `json:"resources"`
+	Build         struct {
+		Artifacts []map[string]any `json:"artifacts"`
+	} `json:"build"`
+}
+
+func readManifest(t *testing.T) (manifest, string) {
+	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.Fatal(err)
+	}
+	return m, string(raw)
+}
+
+func TestItClaimsNoSeatNeedsNoDisplayAndContributesNothing(t *testing.T) {
+	m, _ := readManifest(t)
+	if m.Module != "xdg" || m.Claims != nil || m.Requires != nil || m.Shell != nil || m.Contributions != nil {
+		t.Fatalf("%+v", m)
+	}
+	if !reflect.DeepEqual(m.Capabilities, []string{"package-manager"}) {
+		t.Fatalf("%v", m.Capabilities)
+	}
+}
+
+func TestItOwnsTheFilesItsSourcesHold(t *testing.T) {
+	m, _ := readManifest(t)
+	want := map[string][3]string{
+		"user-dirs":            {"${machine:account-home}/.config/user-dirs.dirs", "0600", "user-dirs.dirs"},
+		"user-dirs-locale":     {"${machine:account-home}/.config/user-dirs.locale", "0644", "user-dirs.locale"},
+		"user-dirs-update":     {"${machine:account-home}/.config/user-dirs.conf", "0644", "user-dirs.conf"},
+		"default-applications": {MeshList, "0644", "mimeapps.list"},
+	}
+	var pkgs []string
+	files := 0
+	for _, r := range m.Resources {
+		id, _ := r["id"].(string)
+		if r["type"] == "package" {
+			pkgs = append(pkgs, r["package"].(string))
+			continue
+		}
+		w, ok := want[id]
+		if !ok || r["type"] != "file" {
+			t.Errorf("unexpected resource %v", r)
+			continue
+		}
+		files++
+		src, _ := os.ReadFile(filepath.Join("..", "..", "config", w[2]))
+		if r["path"] != w[0] || r["mode"] != w[1] || r["content"] != string(src) || r["into"] != nil {
+			t.Errorf("%s is not config/%s, whole, at %s mode %s: %v", id, w[2], w[0], w[1], r["path"])
+		}
+		home := strings.HasPrefix(w[0], "${machine:account-home}/")
+		if home != (r["owner"] == "${machine:account}") {
+			t.Errorf("%s: a file in the home is the account's, a system file root's: owner %v", id, r["owner"])
+		}
+	}
+	if files != len(want) {
+		t.Errorf("%d files, want %d", files, len(want))
+	}
+	if !reflect.DeepEqual(pkgs, []string{"xdg-user-dirs", "xdg-utils"}) {
+		t.Errorf("packages %v", pkgs)
+	}
+	for _, r := range m.Resources {
+		if p, _ := r["path"].(string); strings.Contains(p, "mimeapps.list") && strings.Contains(p, "account-home") {
+			t.Errorf("the person's mimeapps.list is held as found, never written: %v", r)
+		}
+		if p, _ := r["path"].(string); strings.Contains(p, "autostart") || strings.Contains(p, "xdg-desktop-portal") {
+			t.Errorf("autostart entries are their applications' modules', the portal is adwaita's: %v", r)
+		}
+	}
+}
+
+func TestTheFoldersFileIsXdgUserDirsOwnFormatWithThreeSettings(t *testing.T) {
+	raw, _ := os.ReadFile(filepath.Join("..", "..", "config", "user-dirs.dirs"))
+	text := string(raw)
+	settings := regexp.MustCompile(`\$\{setting:([a-z0-9-]+)\}`).FindAllStringSubmatch(text, -1)
+	var names []string
+	for _, s := range settings {
+		names = append(names, s[1])
+	}
+	sort.Strings(names)
+	if !reflect.DeepEqual(names, []string{"desktop-dir", "publicshare-dir", "videos-dir"}) {
+		t.Fatalf("the folders that differ between the workstations are the settings: %v", names)
+	}
+	lines := 0
+	for _, l := range strings.Split(strings.TrimSpace(text), "\n") {
+		if strings.HasPrefix(l, "#") {
+			continue
+		}
+		lines++
+		if !userDirLine.MatchString(l) {
+			t.Errorf("not xdg-user-dirs' format: %q", l)
+		}
+	}
+	// The eight folders GLib knows, and xdg-user-dirs' PROJECTS.
+	if lines != 9 {
+		t.Errorf("%d folders", lines)
+	}
+	if !strings.Contains(firstLines(text, 3), meshMark) {
+		t.Error("the header xdg_check recognises the file by")
+	}
+	conf, _ := os.ReadFile(filepath.Join("..", "..", "config", "user-dirs.conf"))
+	if !regexp.MustCompile(`(?m)^enabled=False$`).Match(conf) {
+		t.Error("xdg-user-dirs-update must be disabled, or it rewrites the mesh's file at login")
+	}
+}
+
+func TestTheMeshsDefaultsNameEachTypeOnceInOneGroupEach(t *testing.T) {
+	raw, _ := os.ReadFile(filepath.Join("..", "..", "config", "mimeapps.list"))
+	k := ParseKeyFile(string(raw))
+	if len(k.DupGroups)+len(k.DupKeys)+len(k.Unparsable) != 0 {
+		t.Fatalf("%+v", k)
+	}
+	if !reflect.DeepEqual(k.Order, []string{"Default Applications", "Added Associations"}) {
+		t.Fatalf("%v", k.Order)
+	}
+	for typ, v := range k.Groups["Default Applications"] {
+		if _, err := Normalise(typ); err != nil {
+			t.Errorf("%s: %v", typ, err)
+		}
+		for _, id := range List(v) {
+			if !desktopID.MatchString(id) || regexp.MustCompile(`[0-9a-f]{8}-[0-9a-f]{4}-`).MatchString(id) {
+				t.Errorf("%s=%s: an id one machine generated is not a default for every machine", typ, id)
+			}
+			if id == "code-oss.desktop" {
+				t.Errorf("%s: code-oss is installed on neither workstation", typ)
+			}
+		}
+	}
+	if k.Groups["Default Applications"]["x-scheme-handler/https"] != "firefox.desktop;" {
+		t.Error("the browser is the operator's")
+	}
+}
+
+func TestTheToolsAgreeWithTheManifest(t *testing.T) {
+	m, raw := readManifest(t)
+	served := map[string]bool{}
+	for _, tool := range tools(&Machine{}) {
+		served[tool.Name] = true
+		if !strings.HasPrefix(tool.Name, "xdg_") || strings.TrimSpace(tool.Description) == "" {
+			t.Errorf("%s", tool.Name)
+		}
+	}
+	if len(served) != len(m.Tools) {
+		t.Fatalf("%v %v", served, m.Tools)
+	}
+	for _, n := range m.Tools {
+		if !served[n] {
+			t.Errorf("module.json lists %s, which the bundle does not serve", n)
+		}
+	}
+	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/xdg-tools" || bundle["binary"] != "xdg-tools" {
+		t.Errorf("the Go tools bundle: %v", bundle)
+	}
+	s := strings.ToLower(raw)
+	for _, never := range []string{"/home/", "jochen", "g14", "shanks", "novox.be", "zurag", ".hal/", "api_key"} {
+		if strings.Contains(s, never) {
+			t.Errorf("module.json names %q", never)
+		}
+	}
+}

modules/xdg/cmd/xdg-tools/mime.go

@@ -0,0 +1,301 @@
+package main
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+// MeshList is the machine's default applications, the one mimeapps list this module writes.
+const MeshList = "/etc/xdg/mimeapps.list"
+
+// mimeLists are the mimeapps lists in the order an application consults them (the XDG MIME
+// Applications specification): the account's configuration, the system's, then the deprecated
+// lists in the application directories.
+func (m *Machine) mimeLists() []string {
+	var dirs []string
+	dirs = append(dirs, m.configHome())
+	dirs = append(dirs, m.configDirs()...)
+	dirs = append(dirs, filepath.Join(m.dataHome(), "applications"))
+	for _, d := range m.dataDirs() {
+		dirs = append(dirs, filepath.Join(d, "applications"))
+	}
+	var out []string
+	for _, d := range dirs {
+		if m.Desktop != "" {
+			out = append(out, filepath.Join(d, m.Desktop+"-mimeapps.list"))
+		}
+		out = append(out, filepath.Join(d, "mimeapps.list"))
+	}
+	return out
+}
+
+// deprecated is whether a list sits in an application directory, where the specification no
+// longer looks first and the person no longer writes.
+func (m *Machine) deprecated(list string) bool {
+	return strings.HasSuffix(filepath.Dir(list), "/applications")
+}
+
+// MimeList is one mimeapps list that exists.
+type MimeList struct {
+	File   string  `json:"file"`
+	Whose  string  `json:"whose"`
+	Broken string  `json:"broken,omitempty"`
+	Keys   KeyFile `json:"-"`
+}
+
+func (m *Machine) whose(list string) string {
+	switch {
+	case list == MeshList:
+		return "the mesh's (module xdg)"
+	case strings.HasPrefix(list, m.Home+"/") && !m.deprecated(list):
+		return "the person's: programs and xdg_default write here; the mesh never does"
+	case m.deprecated(list):
+		return "deprecated location: read last, written by nothing current"
+	}
+	return "the system's, as found"
+}
+
+// lists are the mimeapps lists that exist, in order.
+func (m *Machine) lists() []MimeList {
+	var out []MimeList
+	for _, f := range m.mimeLists() {
+		if _, err := os.Lstat(m.p(f)); err != nil {
+			continue
+		}
+		l := MimeList{File: m.tilde(f), Whose: m.whose(f)}
+		if text, ok := m.read(f); ok {
+			l.Keys = ParseKeyFile(text)
+		} else {
+			l.Broken = "a link to nothing, or unreadable"
+		}
+		out = append(out, l)
+	}
+	return out
+}
+
+// Decision is how a type's default was found.
+type Decision struct {
+	ID      string   `json:"id,omitempty"`
+	File    string   `json:"decided_by,omitempty"`
+	Skipped []string `json:"skipped,omitempty"` // "id (file): why"
+}
+
+// Decide finds a type's default as the specification says: the first list naming it in
+// [Default Applications], the first application of its value that is installed; an application
+// named but not installed is passed over, to the next one or the next list.
+func (m *Machine) Decide(mime string) Decision {
+	var d Decision
+	for _, l := range m.lists() {
+		v, ok := l.Keys.Groups["Default Applications"][mime]
+		if !ok {
+			continue
+		}
+		for _, id := range List(v) {
+			if _, installed := m.findApp(id); installed {
+				d.ID, d.File = id, l.File
+				return d
+			}
+			d.Skipped = append(d.Skipped, fmt.Sprintf("%s (%s): not installed", id, l.File))
+		}
+	}
+	return d
+}
+
+var (
+	mimeType  = regexp.MustCompile(`^[a-z0-9][a-z0-9.+-]*/[A-Za-z0-9][A-Za-z0-9.+_-]*$`)
+	urlScheme = regexp.MustCompile(`^[a-z][a-z0-9+.-]*$`)
+	desktopID = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9 ._+-]*\.desktop$`)
+)
+
+// Normalise accepts a MIME type (text/html), a URL scheme (https, mailto:) or the scheme's own
+// type (x-scheme-handler/https), and answers the type.
+func Normalise(t string) (string, error) {
+	t = strings.TrimSpace(t)
+	if s := strings.TrimSuffix(strings.TrimSuffix(t, "://"), ":"); urlScheme.MatchString(s) {
+		return "x-scheme-handler/" + s, nil
+	}
+	if mimeType.MatchString(t) {
+		return t, nil
+	}
+	return "", fmt.Errorf("%q is neither a MIME type (text/html) nor a URL scheme (https, mailto)", t)
+}
+
+// Handler is who opens one type, and with what.
+type Handler struct {
+	Type     string   `json:"type"`
+	XdgOpen  string   `json:"xdg_open"`
+	Gio      string   `json:"gtk_programs,omitempty"`
+	Disagree bool     `json:"readers_disagree,omitempty"`
+	Decision Decision `json:"decision"`
+	App      *Entry   `json:"application,omitempty"`
+	Problem  string   `json:"problem,omitempty"`
+}
+
+// queryDefault asks xdg-mime, which is what xdg-open uses.
+func (m *Machine) queryDefault(mime string) (string, error) {
+	out, err := m.cmd("xdg-mime", "query", "default", mime)
+	return strings.TrimSpace(out), err
+}
+
+var gioDefault = regexp.MustCompile(`(?m)^Default application for .*: (.+)$`)
+
+// gioDefault asks GLib, which GTK and Electron programs use; "" when it has none or no gio.
+func (m *Machine) gioDefault(mime string) string {
+	out, err := m.cmd("gio", "mime", mime)
+	if err != nil {
+		return ""
+	}
+	if g := gioDefault.FindStringSubmatch(out); g != nil {
+		return strings.TrimSpace(g[1])
+	}
+	return ""
+}
+
+// Handle answers who opens a type.
+func (m *Machine) Handle(mime string) Handler {
+	h := Handler{Type: mime, Decision: m.Decide(mime)}
+	id, err := m.queryDefault(mime)
+	if err != nil {
+		h.Problem = err.Error()
+	}
+	h.XdgOpen = id
+	h.Gio = m.gioDefault(mime)
+	h.Disagree = h.Gio != "" && h.XdgOpen != "" && h.Gio != h.XdgOpen
+	if id != "" {
+		if e, ok := m.findApp(id); ok {
+			h.App = &e
+			if !e.Found {
+				h.Problem = fmt.Sprintf("%s runs %s, which is not installed", id, e.Program)
+			}
+		} else {
+			h.Problem = id + " is not installed"
+		}
+	} else if h.Problem == "" {
+		h.Problem = "nothing opens it"
+	}
+	if h.Decision.ID == "" && id != "" {
+		h.Decision.File = "no list names an installed application; " + id + " declares the type"
+	}
+	return h
+}
+
+// SetDefault makes an installed application the default for a type, through xdg-mime: it writes
+// the person's own list, which the mesh never writes, and which comes before the mesh's.
+func (m *Machine) SetDefault(mime, id string) (map[string]any, error) {
+	if !desktopID.MatchString(id) {
+		return nil, fmt.Errorf("%q is not a desktop file id (firefox.desktop)", id)
+	}
+	app, ok := m.findApp(id)
+	if !ok {
+		return nil, fmt.Errorf("%s is not installed: no application directory has it (xdg_open_handlers lists what is)", id)
+	}
+	before := m.Handle(mime)
+	if _, err := m.cmd("xdg-mime", "default", id, mime); err != nil {
+		return nil, err
+	}
+	after := m.Handle(mime)
+	answer := map[string]any{
+		"type": mime, "before": before.XdgOpen, "after": after.XdgOpen, "gtk_programs": after.Gio,
+		"written_to": m.tilde(filepath.Join(m.configHome(), "mimeapps.list")),
+		"note":       "the person's list: it outlasts every push and comes before the mesh's " + MeshList,
+	}
+	if after.XdgOpen != id {
+		answer["problem"] = fmt.Sprintf("xdg-mime still answers %q: a list before the person's (%s) names it", after.XdgOpen, after.Decision.File)
+	}
+	if !app.Found {
+		answer["warning"] = fmt.Sprintf("%s runs %s, which is not installed", id, app.Program)
+	}
+	return answer, nil
+}
+
+// InterestingTypes are the types xdg_open_handlers always answers for.
+var InterestingTypes = []string{
+	"x-scheme-handler/http", "x-scheme-handler/https", "x-scheme-handler/mailto", "text/html",
+	"inode/directory", "text/plain", "text/markdown", "application/pdf", "image/png", "image/jpeg",
+	"video/mp4", "audio/mpeg",
+}
+
+// DeadDefault is a default naming an application that is not installed.
+type DeadDefault struct {
+	File string `json:"file"`
+	Type string `json:"type"`
+	ID   string `json:"id"`
+}
+
+// deadDefaults are the defaults, in every list, that name an application not installed.
+func (m *Machine) deadDefaults() []DeadDefault {
+	var out []DeadDefault
+	for _, l := range m.lists() {
+		g := l.Keys.Groups["Default Applications"]
+		for _, t := range sortedKeys(g) {
+			for _, id := range List(g[t]) {
+				if _, ok := m.findApp(id); !ok {
+					out = append(out, DeadDefault{File: l.File, Type: t, ID: id})
+				}
+			}
+		}
+	}
+	return out
+}
+
+// brokenHandlers are the desktop files that declare types and cannot run.
+func (m *Machine) brokenHandlers() []Entry {
+	var out []Entry
+	for _, e := range m.apps() {
+		if len(e.MimeTypes) == 0 || e.Hidden {
+			continue
+		}
+		if e.Broken != "" || !e.Found {
+			out = append(out, e)
+		}
+	}
+	return out
+}
+
+// OpenHandlers is xdg_open_handlers.
+func (m *Machine) OpenHandlers(extra []string) (map[string]any, error) {
+	types := append([]string{}, InterestingTypes...)
+	for _, t := range extra {
+		n, err := Normalise(t)
+		if err != nil {
+			return nil, err
+		}
+		types = append(types, n)
+	}
+	var handlers []Handler
+	seen := map[string]bool{}
+	for _, t := range types {
+		if !seen[t] {
+			seen[t] = true
+			handlers = append(handlers, m.Handle(t))
+		}
+	}
+	var lists []map[string]string
+	for _, l := range m.lists() {
+		row := map[string]string{"file": l.File, "whose": l.Whose}
+		if l.Broken != "" {
+			row["broken"] = l.Broken
+		}
+		lists = append(lists, row)
+	}
+	return map[string]any{
+		"handlers":            handlers,
+		"lists_in_order":      lists,
+		"dead_defaults":       m.deadDefaults(),
+		"broken_handlers":     m.brokenHandlers(),
+		"about_dead_defaults": "a default naming an application that is not installed is passed over: the next list, or an application declaring the type, answers instead",
+	}, nil
+}
+
+func sortedKeys[V any](m map[string]V) []string {
+	out := make([]string, 0, len(m))
+	for k := range m {
+		out = append(out, k)
+	}
+	sort.Strings(out)
+	return out
+}

modules/xdg/cmd/xdg-tools/userdirs.go

@@ -0,0 +1,155 @@
+package main
+
+import (
+	"bufio"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+)
+
+// meshMark is in the first lines of every file this module writes.
+const meshMark = "(module xdg"
+
+// UserDir is one line of user-dirs.dirs.
+type UserDir struct {
+	Name    string `json:"name"`
+	Written string `json:"written"`
+	Path    string `json:"path"`
+	// Home is a folder pointed at the home itself: xdg-user-dirs' way of saying "not wanted".
+	Home   bool   `json:"is_home"`
+	Exists bool   `json:"exists"`
+	Kind   string `json:"kind"` // directory, file, absent
+	// Default is the folder xdg-user-dirs would have made, from its system defaults.
+	Default string `json:"xdg_user_dirs_default,omitempty"`
+}
+
+var userDirLine = regexp.MustCompile(`^XDG_([A-Z0-9_]+)_DIR="(.*)"\s*$`)
+
+// ParseUserDirs reads user-dirs.dirs as xdg-user-dirs writes it: XDG_xxx_DIR="$HOME/yyy" or "/yyy".
+// The order of the file is kept.
+func ParseUserDirs(text string) [][2]string {
+	var out [][2]string
+	sc := bufio.NewScanner(strings.NewReader(text))
+	for sc.Scan() {
+		if m := userDirLine.FindStringSubmatch(strings.TrimSpace(sc.Text())); m != nil {
+			out = append(out, [2]string{m[1], strings.ReplaceAll(m[2], `\`, "")})
+		}
+	}
+	return out
+}
+
+// resolve turns a written value into a path, as xdg-user-dir does.
+func (m *Machine) resolve(written string) string {
+	switch {
+	case written == "$HOME" || written == "$HOME/":
+		return m.Home
+	case strings.HasPrefix(written, "$HOME/"):
+		return filepath.Clean(filepath.Join(m.Home, strings.TrimPrefix(written, "$HOME/")))
+	}
+	return filepath.Clean(written)
+}
+
+func (m *Machine) kind(path string) string {
+	info, err := os.Stat(m.p(path))
+	switch {
+	case err != nil:
+		return "absent"
+	case info.IsDir():
+		return "directory"
+	}
+	return "file"
+}
+
+// UserDirsAnswer is xdg_user_dirs' answer.
+type UserDirsAnswer struct {
+	File    string    `json:"file"`
+	Meshs   bool      `json:"written_by_the_mesh"`
+	Dirs    []UserDir `json:"dirs"`
+	Missing []string  `json:"defaults_without_a_line,omitempty"`
+	Update  struct {
+		Enabled   bool   `json:"enabled"`
+		DecidedBy string `json:"decided_by"`
+		Note      string `json:"note"`
+	} `json:"xdg_user_dirs_update"`
+	Locale string `json:"locale,omitempty"`
+}
+
+// userDirsDefaults reads the names xdg-user-dirs would create, from its system defaults.
+func (m *Machine) userDirsDefaults() map[string]string {
+	out := map[string]string{}
+	text, _ := m.read("/etc/xdg/user-dirs.defaults")
+	for _, l := range strings.Split(text, "\n") {
+		l = strings.TrimSpace(l)
+		if l == "" || strings.HasPrefix(l, "#") {
+			continue
+		}
+		if k, v, ok := strings.Cut(l, "="); ok {
+			out[k] = v
+		}
+	}
+	return out
+}
+
+// updateEnabled is xdg-user-dirs-update's own reading of `enabled`: the account's user-dirs.conf
+// over the system's, the last line saying it winning.
+func (m *Machine) updateEnabled() (bool, string) {
+	enabled, by := true, "xdg-user-dirs' built-in default"
+	for _, f := range []string{"/etc/xdg/user-dirs.conf", filepath.Join(m.configHome(), "user-dirs.conf")} {
+		text, ok := m.read(f)
+		if !ok {
+			continue
+		}
+		for _, l := range strings.Split(text, "\n") {
+			k, v, ok := strings.Cut(strings.TrimSpace(l), "=")
+			if ok && strings.TrimSpace(k) == "enabled" {
+				enabled, by = strings.EqualFold(strings.TrimSpace(v), "true"), m.tilde(f)
+			}
+		}
+	}
+	return enabled, by
+}
+
+// UserDirs is xdg_user_dirs.
+func (m *Machine) UserDirs() UserDirsAnswer {
+	var a UserDirsAnswer
+	file := filepath.Join(m.configHome(), "user-dirs.dirs")
+	a.File = m.tilde(file)
+	text, _ := m.read(file)
+	a.Meshs = strings.Contains(firstLines(text, 3), meshMark)
+	defaults := m.userDirsDefaults()
+	seen := map[string]bool{}
+	for _, kv := range ParseUserDirs(text) {
+		path := m.resolve(kv[1])
+		d := UserDir{Name: kv[0], Written: kv[1], Path: m.tilde(path), Home: path == m.Home, Kind: m.kind(path)}
+		d.Exists = d.Kind == "directory"
+		if def, ok := defaults[kv[0]]; ok {
+			d.Default = "~/" + def
+		}
+		seen[kv[0]] = true
+		a.Dirs = append(a.Dirs, d)
+	}
+	for _, k := range sortedKeys(defaults) {
+		if !seen[k] {
+			a.Missing = append(a.Missing, k)
+		}
+	}
+	a.Update.Enabled, a.Update.DecidedBy = m.updateEnabled()
+	if a.Update.Enabled {
+		a.Update.Note = "enabled: at the next login it reassigns a folder it cannot find to the home, adds a line for each default above, and rewrites the file"
+	} else {
+		a.Update.Note = "disabled: it leaves the file as it is"
+	}
+	if l, ok := m.read(filepath.Join(m.configHome(), "user-dirs.locale")); ok {
+		a.Locale = strings.TrimSpace(l)
+	}
+	return a
+}
+
+func firstLines(text string, n int) string {
+	lines := strings.SplitN(text, "\n", n+1)
+	if len(lines) > n {
+		lines = lines[:n]
+	}
+	return strings.Join(lines, "\n")
+}

modules/xdg/config/mimeapps.list

@@ -0,0 +1,30 @@
+# The machine's default applications (module xdg, novox/hq ADR 0182), written by the mesh and
+# replaced at every push.
+#
+# This is the lowest list an application consults. The account's own ~/.config/mimeapps.list comes
+# first: every program that offers "always open with" writes there, and so does xdg_default. That
+# file is the person's and is never written by the mesh, so a choice made there always wins; this
+# list answers only what the person has not chosen. Adopted from the workstations' own lists of
+# 2026-10-05, without the entries naming an application neither workstation has installed (see the
+# module's README).
+[Default Applications]
+application/pdf=firefox.desktop;
+application/x-extension-htm=firefox.desktop;
+application/x-extension-shtml=firefox.desktop;
+application/x-extension-xht=firefox.desktop;
+application/x-extension-xhtml=firefox.desktop;
+application/xhtml+xml=firefox.desktop;
+text/html=firefox.desktop;
+x-scheme-handler/chrome=firefox.desktop;
+x-scheme-handler/ftp=firefox.desktop;
+x-scheme-handler/http=firefox.desktop;
+x-scheme-handler/https=firefox.desktop;
+text/markdown=org.kde.ghostwriter.desktop;
+inode/directory=thunar.desktop;
+x-scheme-handler/abc=plexamp.desktop;
+x-scheme-handler/jetbrains=jetbrains-toolbox.desktop;
+x-scheme-handler/slack=slack.desktop;
+x-scheme-handler/tg=org.telegram.desktop.desktop;
+
+[Added Associations]
+video/mp4=mpv.desktop;mplayer.desktop;vlc.desktop;

modules/xdg/config/user-dirs.conf

@@ -0,0 +1,9 @@
+# xdg-user-dirs-update for this account (module xdg, novox/hq ADR 0182), written by the mesh and
+# replaced at every push.
+#
+# The update runs at every login (its XDG autostart entry, which the session's dex starts). Enabled,
+# it reassigns a folder it cannot find to the home and adds a line for every folder its defaults
+# know, rewriting user-dirs.dirs, which is the mesh's. Disabled, it does nothing, even with --force.
+# The folders are this module's to say.
+enabled=False
+filename_encoding=UTF-8

modules/xdg/config/user-dirs.dirs

@@ -0,0 +1,17 @@
+# The account's folders (module xdg, novox/hq ADR 0182), written by the mesh and replaced at every
+# push. Adopted from the workstations' own files of 2026-10-05. A folder that differs between the
+# machines is a setting of this module; every other one is the same everywhere. PROJECTS names the
+# folder the operator's repositories are in (it pointed at the home, or was absent).
+#
+# xdg-user-dirs-update never rewrites this file: user-dirs.conf beside it says enabled=False. Each
+# line is xdg-user-dirs' only format, XDG_xxx_DIR="$HOME/yyy" or XDG_xxx_DIR="/yyy". "$HOME/" is
+# the home itself: the folder is not wanted. xdg_user_dirs says what each one resolves to.
+XDG_DESKTOP_DIR="${setting:desktop-dir}"
+XDG_DOWNLOAD_DIR="$HOME/Downloads"
+XDG_TEMPLATES_DIR="$HOME/Templates"
+XDG_PUBLICSHARE_DIR="${setting:publicshare-dir}"
+XDG_DOCUMENTS_DIR="$HOME/Documents"
+XDG_MUSIC_DIR="$HOME/Music"
+XDG_PICTURES_DIR="$HOME/Pictures"
+XDG_VIDEOS_DIR="${setting:videos-dir}"
+XDG_PROJECTS_DIR="$HOME/projects"

modules/xdg/config/user-dirs.locale

@@ -0,0 +1 @@
+en_US

modules/xdg/go.mod

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

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

@@ -0,0 +1,72 @@
+{
+  "module": "xdg",
+  "version": "1",
+  "capabilities": [
+    "package-manager"
+  ],
+  "tools": [
+    "xdg_user_dirs",
+    "xdg_default",
+    "xdg_open_handlers",
+    "xdg_autostart",
+    "xdg_check"
+  ],
+  "resources": [
+    {
+      "id": "package-xdg-user-dirs",
+      "type": "package",
+      "package": "xdg-user-dirs"
+    },
+    {
+      "id": "package-xdg-utils",
+      "type": "package",
+      "package": "xdg-utils"
+    },
+    {
+      "id": "user-dirs",
+      "type": "file",
+      "path": "${machine:account-home}/.config/user-dirs.dirs",
+      "owner": "${machine:account}",
+      "mode": "0600",
+      "content": "# The account's folders (module xdg, novox/hq ADR 0182), written by the mesh and replaced at every\n# push. Adopted from the workstations' own files of 2026-10-05. A folder that differs between the\n# machines is a setting of this module; every other one is the same everywhere. PROJECTS names the\n# folder the operator's repositories are in (it pointed at the home, or was absent).\n#\n# xdg-user-dirs-update never rewrites this file: user-dirs.conf beside it says enabled=False. Each\n# line is xdg-user-dirs' only format, XDG_xxx_DIR=\"$HOME/yyy\" or XDG_xxx_DIR=\"/yyy\". \"$HOME/\" is\n# the home itself: the folder is not wanted. xdg_user_dirs says what each one resolves to.\nXDG_DESKTOP_DIR=\"${setting:desktop-dir}\"\nXDG_DOWNLOAD_DIR=\"$HOME/Downloads\"\nXDG_TEMPLATES_DIR=\"$HOME/Templates\"\nXDG_PUBLICSHARE_DIR=\"${setting:publicshare-dir}\"\nXDG_DOCUMENTS_DIR=\"$HOME/Documents\"\nXDG_MUSIC_DIR=\"$HOME/Music\"\nXDG_PICTURES_DIR=\"$HOME/Pictures\"\nXDG_VIDEOS_DIR=\"${setting:videos-dir}\"\nXDG_PROJECTS_DIR=\"$HOME/projects\"\n"
+    },
+    {
+      "id": "user-dirs-locale",
+      "type": "file",
+      "path": "${machine:account-home}/.config/user-dirs.locale",
+      "owner": "${machine:account}",
+      "mode": "0644",
+      "content": "en_US\n"
+    },
+    {
+      "id": "user-dirs-update",
+      "type": "file",
+      "path": "${machine:account-home}/.config/user-dirs.conf",
+      "owner": "${machine:account}",
+      "mode": "0644",
+      "content": "# xdg-user-dirs-update for this account (module xdg, novox/hq ADR 0182), written by the mesh and\n# replaced at every push.\n#\n# The update runs at every login (its XDG autostart entry, which the session's dex starts). Enabled,\n# it reassigns a folder it cannot find to the home and adds a line for every folder its defaults\n# know, rewriting user-dirs.dirs, which is the mesh's. Disabled, it does nothing, even with --force.\n# The folders are this module's to say.\nenabled=False\nfilename_encoding=UTF-8\n"
+    },
+    {
+      "id": "default-applications",
+      "type": "file",
+      "path": "/etc/xdg/mimeapps.list",
+      "mode": "0644",
+      "content": "# The machine's default applications (module xdg, novox/hq ADR 0182), written by the mesh and\n# replaced at every push.\n#\n# This is the lowest list an application consults. The account's own ~/.config/mimeapps.list comes\n# first: every program that offers \"always open with\" writes there, and so does xdg_default. That\n# file is the person's and is never written by the mesh, so a choice made there always wins; this\n# list answers only what the person has not chosen. Adopted from the workstations' own lists of\n# 2026-10-05, without the entries naming an application neither workstation has installed (see the\n# module's README).\n[Default Applications]\napplication/pdf=firefox.desktop;\napplication/x-extension-htm=firefox.desktop;\napplication/x-extension-shtml=firefox.desktop;\napplication/x-extension-xht=firefox.desktop;\napplication/x-extension-xhtml=firefox.desktop;\napplication/xhtml+xml=firefox.desktop;\ntext/html=firefox.desktop;\nx-scheme-handler/chrome=firefox.desktop;\nx-scheme-handler/ftp=firefox.desktop;\nx-scheme-handler/http=firefox.desktop;\nx-scheme-handler/https=firefox.desktop;\ntext/markdown=org.kde.ghostwriter.desktop;\ninode/directory=thunar.desktop;\nx-scheme-handler/abc=plexamp.desktop;\nx-scheme-handler/jetbrains=jetbrains-toolbox.desktop;\nx-scheme-handler/slack=slack.desktop;\nx-scheme-handler/tg=org.telegram.desktop.desktop;\n\n[Added Associations]\nvideo/mp4=mpv.desktop;mplayer.desktop;vlc.desktop;\n"
+    }
+  ],
+  "build": {
+    "artifacts": [
+      {
+        "name": "tools",
+        "kind": "bundle",
+        "language": "go",
+        "system": "arch",
+        "from": "cmd/xdg-tools",
+        "binary": "xdg-tools",
+        "loads": [
+          "xdg-tools"
+        ]
+      }
+    ]
+  }
+}