Write a provisioner client's files only on a change over the bus, never on a timer (issue 1129, ADR 0349 clause 4)

WithdrawRecord only ended the waiting ask locally; the router kept it open, so
the operator still saw Approve/Decline for a withdrawn record and an answer to
it was dropped silently. It now also publishes a cancel on the router's
subject once the withdraw is saved, as the controller's asker does; a cancel
the router cannot be told of is logged and the withdraw still stands. The
module's existing "uses": ["operator-channel"] already grants this; no manifest
change needed, since the ask and cancel subjects are both under that seat.

.gitignore

@@ -1,2 +1,28 @@
 node_modules/
 dist/
+
+# Go tool bundles built in place (go build in a module's cmd/<name>-tools) are build output.
+modules/slack/cmd/slack-tools/slack-tools
+modules/jetbrains-toolbox/cmd/toolbox-tools/toolbox-tools
+modules/messenger/cmd/messenger/messenger
+modules/mesh-watcher/cmd/mesh-watcher/mesh-watcher
+modules/claude-code/cmd/claude-code/claude-code
+modules/dnsmasq/cmd/dnsmasq-tools/dnsmasq-tools
+modules/mesh-delivery/cmd/mesh-delivery/mesh-delivery
+# ...and the same built from the module's root (go build ./cmd/<name>), which names it after the module.
+modules/messenger/messenger
+modules/claude-code/claude-code
+modules/mesh-watcher/mesh-watcher
+modules/dnsmasq/dnsmasq
+modules/mesh-delivery/mesh-delivery
+modules/mesh-issues/cmd/mesh-issues/mesh-issues
+modules/mounts/cmd/mounts/mounts
+modules/mesh-knowledge/cmd/mesh-knowledge/mesh-knowledge
+modules/mesh-knowledge/mesh-knowledge
+modules/mesh-reads/mesh-reads
+modules/mesh-reads/cmd/mesh-reads/mesh-reads
+modules/mesh-files/mesh-files
+modules/mesh-files/cmd/mesh-files/mesh-files
+
+# The provisioner client built in place (issue 671).
+modules/mesh-provisioner-client/cmd/mesh-provisioner-client/mesh-provisioner-client

RELEASE-57.md

@@ -0,0 +1,6 @@
+# Release 57: config and provisioning
+
+This branch carries the work of hq design 57 (ADR 0348, ADR 0349) in this repository. Each package
+merges here through its own reviewed pull request; the branch reaches main as one pull request, in one
+delivery group with the branch of the same name in mesh-controller, mesh-host, mesh-sdk, mesh-catalog
+and hq, after a rehearsal in the lab. This file is deleted by the last commit before that pull request.

checks/agenthome/go.mod

@@ -0,0 +1,3 @@
+module git.novox.be/novox/mesh-catalog/checks/agenthome
+
+go 1.22

checks/agenthome/main.go

@@ -0,0 +1,128 @@
+// Command agenthome refuses, in every module's manifest, a resource placed under the agent account's home
+// that the node-engine cannot write without a gap (novox/hq ADR 0266).
+//
+// The agent account owns its home and everything in it, so it can put a symbolic or hard link anywhere
+// there. The node-engine, as root, writes a whole file or a directory below a home through descriptors it
+// opened itself and refuses a link it finds; it unpacks an archive, and writes into an existing file (`into`:
+// json or block), only after checking the path, so a link swapped in between the check and the write would
+// point root's write at any file. No module does either today. This check keeps it so: a resource of type
+// `archive`, or a `file` with `into`, whose path is under ${machine:agent-home} — written so, reached through
+// one of the module's own directories (${dir:<id>}), or written as a literal /home path — is refused. The
+// node-engine refuses the same below the home of any account declared never to become root, whatever the path.
+//
+//	go run . <catalogue root>
+//
+// Exits 1 on a finding.
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+// AgentHome is the machine fact naming the agent account's home.
+const AgentHome = "${machine:agent-home}"
+
+// ofDir is where a manifest names one of its own directories: ${dir:<id>}.
+var ofDir = regexp.MustCompile(`\$\{dir:([a-z0-9][a-z0-9_-]*)\}`)
+
+// resolve replaces each ${dir:<id>} with that resource's own path, as far as the manifest says it, so a path
+// reaching the agent's home through one of the module's directories is seen for what it is.
+func resolve(p string, dirs map[string]string) string {
+	for i := 0; i < 8 && ofDir.MatchString(p); i++ {
+		p = ofDir.ReplaceAllStringFunc(p, func(word string) string {
+			if to, ok := dirs[ofDir.FindStringSubmatch(word)[1]]; ok {
+				return to
+			}
+			return word
+		})
+	}
+	return p
+}
+
+// underAHome says whether a resolved path lies under the agent's home: by its machine fact, or written as a
+// literal home, which no definition may carry anyway (ADR 0112) and which may well be the agent's.
+func underAHome(p string) bool {
+	// Cleaned first, so //home/x or /./home/x is seen as the /home/x it is.
+	if p != "" {
+		p = filepath.Clean(p)
+	}
+	return strings.HasPrefix(p, AgentHome) || strings.HasPrefix(p, "/home/") || p == "/home"
+}
+
+// Finding is one resource refused.
+type Finding struct {
+	Module, ID, Why string
+}
+
+// Check reads every manifest under root/modules and answers what it refuses.
+func Check(root string) ([]Finding, error) {
+	manifests, err := filepath.Glob(filepath.Join(root, "modules", "*", "module.json"))
+	if err != nil {
+		return nil, err
+	}
+	sort.Strings(manifests)
+	var out []Finding
+	for _, path := range manifests {
+		raw, err := os.ReadFile(path)
+		if err != nil {
+			return nil, err
+		}
+		var m struct {
+			Module    string           `json:"module"`
+			Resources []map[string]any `json:"resources"`
+		}
+		if err := json.Unmarshal(raw, &m); err != nil {
+			return nil, fmt.Errorf("%s: %w", path, err)
+		}
+		dirs := map[string]string{}
+		for _, r := range m.Resources {
+			id, _ := r["id"].(string)
+			if p, _ := r["path"].(string); id != "" && p != "" {
+				dirs[id] = p
+			}
+		}
+		for _, r := range m.Resources {
+			p, _ := r["path"].(string)
+			if !underAHome(resolve(p, dirs)) {
+				continue
+			}
+			id, _ := r["id"].(string)
+			kind, _ := r["type"].(string)
+			into, _ := r["into"].(string)
+			switch {
+			case kind == "archive":
+				out = append(out, Finding{m.Module, id, "an archive unpacked under the agent's home"})
+			case kind == "file" && into != "":
+				out = append(out, Finding{m.Module, id, "a file written into (" + into + ") under the agent's home"})
+			}
+		}
+	}
+	return out, nil
+}
+
+func main() {
+	root := "."
+	if len(os.Args) > 1 {
+		root = os.Args[1]
+	}
+	found, err := Check(root)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+	for _, f := range found {
+		fmt.Printf("%s: %s is %s: the node-engine writes it as root after checking the path, and the agent "+
+			"account could swap a link in between (novox/hq ADR 0266); place a whole file or a directory instead\n",
+			f.Module, f.ID, f.Why)
+	}
+	if len(found) > 0 {
+		os.Exit(1)
+	}
+	fmt.Println("agent-home: no archive and no file written into under the agent's home")
+}

checks/agenthome/main_test.go

@@ -0,0 +1,51 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func manifest(t *testing.T, root, module, resources string) {
+	t.Helper()
+	dir := filepath.Join(root, "modules", module)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	body := `{"module":"` + module + `","resources":[` + resources + `]}`
+	if err := os.WriteFile(filepath.Join(dir, "module.json"), []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestAnArchiveOrAFileWrittenIntoUnderTheAgentsHomeIsRefused(t *testing.T) {
+	root := t.TempDir()
+	manifest(t, root, "a", `{"id":"theme","type":"archive","path":"${machine:agent-home}/.local/share/x"}`)
+	manifest(t, root, "b", `{"id":"cfg","type":"file","path":"${machine:agent-home}/.claude.json","into":"json","content":"{}"}`)
+	manifest(t, root, "c", `{"id":"dir","type":"directory","path":"${machine:agent-home}/.claude"},`+
+		`{"id":"whole","type":"file","path":"${machine:agent-home}/x","content":"y"},`+
+		`{"id":"op","type":"archive","path":"${machine:account-home}/.local/share/x"}`)
+	manifest(t, root, "d", `{"id":"home","type":"directory","path":"${machine:agent-home}/.claude"},`+
+		`{"id":"inner","type":"directory","path":"${dir:home}/inner"},`+
+		`{"id":"via-dir","type":"archive","path":"${dir:inner}/theme"}`)
+	manifest(t, root, "e", `{"id":"literal","type":"file","path":"/home/agent/.bashrc","into":"block","content":"x"}`)
+	manifest(t, root, "f", `{"id":"unclean","type":"archive","path":"//./home/agent/x"}`)
+	found, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(found) != 5 || found[0].Module != "a" || found[1].Module != "b" || found[2].ID != "via-dir" ||
+		found[3].ID != "literal" || found[4].ID != "unclean" {
+		t.Fatalf("refused %+v", found)
+	}
+}
+
+func TestTheCatalogueHasNone(t *testing.T) {
+	found, err := Check("../..")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(found) != 0 {
+		t.Fatalf("%+v", found)
+	}
+}

checks/config/go.mod

@@ -0,0 +1,3 @@
+module git.novox.be/novox/mesh-catalog/checks/config
+
+go 1.22

checks/config/main.go

@@ -0,0 +1,201 @@
+// Command config refuses the settings form's names in a module that has moved to config (novox/hq ADR 0348
+// clauses 1 and 11, design 57 package K6, issue 665).
+//
+// "Config" replaces "settings": a manifest declares its values under `config`, a mergeable file names the keys it
+// takes under `takes-config`, and a file asks for a value with `${config:<key>}`. A mergeable file naming no keys at
+// all is the settings form's last shape: it takes every key of its module's layer and declares none, so mesh-config
+// could set none of them (ADR 0348 §10, ADR 0326 §3); it is found here like an old name (issue 735). The old names — `settings`,
+// `takes-settings` and `${setting:<key>}` — stay accepted by the controller as aliases until every module has
+// moved, and are then refused (ADR 0348 §1). The modules not yet moved are listed in the file `unmoved` beside this
+// check, one per line: the catalogue's list ADR 0348 §11 names. Every other module says no old name, in its
+// manifest or in a template file its manifest names; a module on the list that says none is taken off it; and a
+// line the trunk's copy (the merge base's, given with -base) does not hold is refused, so the list only shrinks;
+// while the trunk holds no copy, the modules in seed are the trunk's.
+// When it is empty, the controller refuses the old names itself (design 57 package R1).
+//
+// Prose is not judged: a comment in a file's text that says "settings" composes into the machine's file, and
+// rewording it would change what a node is sent.
+//
+//	go run . [-base <the trunk's unmoved>] <catalogue root>
+//
+// Exits 1 on a finding.
+package main
+
+import (
+	"bufio"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+// The settings form's names (ADR 0348 §1). A key of a JSON object is a quoted string followed by a colon; a
+// string value is never followed by one.
+var (
+	settingRef        = regexp.MustCompile(`\$\{setting:[a-z0-9][a-z0-9_.-]*\}`)
+	takesSettingsKey  = regexp.MustCompile(`"takes-settings"\s*:`)
+	oldPlaceholder    = "${setting:…}"
+	oldTakes          = "takes-settings"
+	oldDeclaration    = "settings"
+	wholeLayer        = "taking its whole layer"
+	listFile          = "unmoved"
+	listPathInCatalog = "checks/config/" + listFile
+)
+
+// Check answers, per module that says any, the settings form's names its manifest and its template files say.
+func Check(root string) (map[string][]string, error) {
+	manifests, err := filepath.Glob(filepath.Join(root, "modules", "*", "module.json"))
+	if err != nil {
+		return nil, err
+	}
+	sort.Strings(manifests)
+	out := map[string][]string{}
+	for _, path := range manifests {
+		raw, err := os.ReadFile(path)
+		if err != nil {
+			return nil, err
+		}
+		var m struct {
+			Module    string           `json:"module"`
+			Settings  json.RawMessage  `json:"settings"`
+			Resources []map[string]any `json:"resources"`
+		}
+		if err := json.Unmarshal(raw, &m); err != nil {
+			return nil, fmt.Errorf("%s: %w", path, err)
+		}
+		var said []string
+		if len(m.Settings) > 0 && string(m.Settings) != "null" {
+			said = append(said, oldDeclaration)
+		}
+		if takesSettingsKey.Match(raw) {
+			said = append(said, oldTakes)
+		}
+		if settingRef.Match(raw) {
+			said = append(said, oldPlaceholder)
+		}
+		for _, r := range m.Resources {
+			// A mergeable file naming no keys takes every key of the layer (ADR 0326 §3), declaring none of them.
+			if how, _ := r["merge"].(string); how != "" {
+				_, oldList := r["takes-settings"]
+				_, newList := r["takes-config"]
+				if !oldList && !newList {
+					said = append(said, fmt.Sprintf("%v %s", r["id"], wholeLayer))
+				}
+			}
+			name, _ := r["template"].(string)
+			if name == "" {
+				continue
+			}
+			text, err := os.ReadFile(filepath.Join(filepath.Dir(path), filepath.FromSlash(name)))
+			if err != nil {
+				return nil, fmt.Errorf("%s names the template %s: %w", m.Module, name, err)
+			}
+			if settingRef.Match(text) {
+				said = append(said, oldPlaceholder+" in "+name)
+			}
+		}
+		if len(said) > 0 {
+			sort.Strings(said)
+			out[m.Module] = said
+		}
+	}
+	return out, nil
+}
+
+// seed is the list as it was first written, standing for the trunk's copy until the trunk holds one.
+// The modules taking a whole layer were found after the list was first written and before the trunk held a copy
+// (issue 735), so they stand in it too.
+var seed = map[string]bool{
+	"betterbird": true, "fail2ban": true, "influxdb": true, "keycloak": true, "mailu": true, "searxng": true,
+	"baserow": true, "confluence": true, "gitea": true, "gitlab": true, "grafana": true, "home-assistant": true,
+	"icecast": true, "jira": true, "letta": true, "matrix": true, "nodered": true, "supabase": true, "unifi": true,
+}
+
+// Unmoved is the modules a list names, one per line; a line starting with # and a blank line are not modules.
+func Unmoved(path string) (map[string]bool, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return nil, err
+	}
+	defer f.Close()
+	out := map[string]bool{}
+	s := bufio.NewScanner(f)
+	for s.Scan() {
+		line := strings.TrimSpace(s.Text())
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		out[line] = true
+	}
+	return out, s.Err()
+}
+
+// Judge answers the modules that say an old name and are not on the list (refused), the modules on the list that
+// say none (stale), and the modules on the list that the trunk's list does not hold (added).
+func Judge(found map[string][]string, unmoved, base map[string]bool) (refused, stale, added []string) {
+	for m := range found {
+		if !unmoved[m] {
+			refused = append(refused, m)
+		}
+	}
+	for m := range unmoved {
+		if _, says := found[m]; !says {
+			stale = append(stale, m)
+		}
+		if !base[m] {
+			added = append(added, m)
+		}
+	}
+	sort.Strings(refused)
+	sort.Strings(stale)
+	sort.Strings(added)
+	return refused, stale, added
+}
+
+func main() {
+	basePath := flag.String("base", "", "the trunk's copy of unmoved (the merge base's); seed when absent")
+	flag.Parse()
+	root := "."
+	if flag.NArg() > 0 {
+		root = flag.Arg(0)
+	}
+	found, err := Check(root)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+	unmoved, err := Unmoved(listFile)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+	base := seed
+	if *basePath != "" {
+		if base, err = Unmoved(*basePath); err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			os.Exit(1)
+		}
+	}
+	refused, stale, added := Judge(found, unmoved, base)
+	for _, m := range refused {
+		fmt.Printf("%s says %s, the settings form's names, and is not on %s: write config, takes-config and "+
+			"${config:<key>} throughout, and name the keys each mergeable file takes (novox/hq ADR 0348 §1, §11)\n", m, strings.Join(found[m], ", "), listPathInCatalog)
+	}
+	for _, m := range stale {
+		fmt.Printf("%s names %s, which says no old name: take it off the list\n", listPathInCatalog, m)
+	}
+	for _, m := range added {
+		fmt.Printf("%s gains %s, which the trunk's copy does not hold: the list only shrinks — move the module to "+
+			"config instead (novox/hq ADR 0348 §11)\n", listPathInCatalog, m)
+	}
+	if len(refused) > 0 || len(stale) > 0 || len(added) > 0 {
+		os.Exit(1)
+	}
+	fmt.Printf("config: no moved module says settings, takes-settings or ${setting:<key>}, or takes a whole layer "+
+		"(%d not yet moved)\n",
+		len(unmoved))
+}

checks/config/main_test.go

@@ -0,0 +1,131 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func module(t *testing.T, root, name, body string, files map[string]string) {
+	t.Helper()
+	dir := filepath.Join(root, "modules", name)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "module.json"), []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	for path, text := range files {
+		full := filepath.Join(dir, filepath.FromSlash(path))
+		if err := os.MkdirAll(filepath.Dir(full), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(full, []byte(text), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+}
+
+// Each of the settings form's names is found where it stands: the declaration, a mergeable file's keys, a
+// placeholder in the manifest, and a placeholder in a template file the manifest names (novox/hq ADR 0348 §1).
+func TestEveryOldNameIsFound(t *testing.T) {
+	root := t.TempDir()
+	module(t, root, "declares", `{"module":"declares","settings":{"size":{"kind":"preference","default":1,"why":"w"}},`+
+		`"resources":[{"id":"f","type":"file","content":"${setting:size}"}]}`, nil)
+	module(t, root, "takes", `{"module":"takes","resources":[{"id":"f","type":"file","merge":"json",`+
+		`"takes-settings":["a"],"content":"{}"}]}`, nil)
+	module(t, root, "asks", `{"module":"asks","serves":{"x":{"d":"${setting:domain}"}}}`, nil)
+	module(t, root, "templated", `{"module":"templated","config":{"size":{"type":"number","description":"d",`+
+		`"default":1}},"resources":[{"id":"f","type":"file","template":"files/conf"}]}`,
+		map[string]string{"files/conf": "size = ${setting:size}\n"})
+	module(t, root, "moved", `{"module":"moved","config":{"size":{"type":"number","description":"d","default":1}},`+
+		`"resources":[{"id":"f","type":"file","template":"files/conf"},{"id":"g","type":"file","merge":"json",`+
+		`"takes-config":[],"content":"{\"settings\": 1}"}]}`,
+		map[string]string{"files/conf": "size = ${config:size}\n# change the settings, never this file\n"})
+	module(t, root, "none", `{"module":"none","resources":[{"id":"f","type":"file","content":"no settings here"}]}`, nil)
+	got, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := map[string][]string{
+		"asks":      {"${setting:…}"},
+		"declares":  {"${setting:…}", "settings"},
+		"takes":     {"takes-settings"},
+		"templated": {"${setting:…} in files/conf"},
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("found %v, want %v", got, want)
+	}
+}
+
+// A module not on the list says no old name; one on the list that says none is taken off it; a line the trunk's
+// list does not hold is refused, so the list only shrinks until it is empty (novox/hq ADR 0348 §11).
+func TestTheListOfModulesNotYetMovedOnlyShrinks(t *testing.T) {
+	found := map[string][]string{"old": {"settings"}, "forgotten": {"takes-settings"}}
+	unmoved := map[string]bool{"old": true, "done": true, "new": true}
+	base := map[string]bool{"old": true, "done": true, "forgotten": true}
+	refused, stale, added := Judge(found, unmoved, base)
+	if !reflect.DeepEqual(refused, []string{"forgotten"}) || !reflect.DeepEqual(stale, []string{"done", "new"}) ||
+		!reflect.DeepEqual(added, []string{"new"}) {
+		t.Fatalf("refused %v, stale %v, added %v", refused, stale, added)
+	}
+}
+
+func TestTheListIsReadWithoutItsComments(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "unmoved")
+	if err := os.WriteFile(path, []byte("# why\n\nmailu\n  searxng  \n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	got, err := Unmoved(path)
+	if err != nil || !reflect.DeepEqual(got, map[string]bool{"mailu": true, "searxng": true}) {
+		t.Fatalf("%v %v", got, err)
+	}
+}
+
+// The catalogue itself: every moved module says config alone, and the list names exactly the modules that
+// still say settings.
+func TestTheCatalogueSaysConfigInEveryMovedModule(t *testing.T) {
+	found, err := Check(filepath.Join("..", ".."))
+	if err != nil {
+		t.Fatal(err)
+	}
+	unmoved, err := Unmoved("unmoved")
+	if err != nil {
+		t.Fatal(err)
+	}
+	refused, stale, added := Judge(found, unmoved, seed)
+	for _, m := range refused {
+		t.Errorf("%s is not on checks/config/unmoved and says %s", m, strings.Join(found[m], ", "))
+	}
+	for _, m := range stale {
+		t.Errorf("checks/config/unmoved names %s, which says no old name", m)
+	}
+	for _, m := range added {
+		t.Errorf("checks/config/unmoved gains %s, which its first copy did not hold", m)
+	}
+}
+
+// A mergeable file that names no keys takes every key of its module's layer (novox/hq ADR 0326 §3): the settings
+// form's last shape, which declares none of what it takes, so mesh-config could set none of it (ADR 0348 §10). It
+// is found like an old name, in a module that says no other (issue 735); one naming its keys, an empty list
+// included, is not.
+func TestAMergeableFileTakingTheWholeLayerIsFound(t *testing.T) {
+	root := t.TempDir()
+	module(t, root, "whole", `{"module":"whole","resources":[{"id":"runtime-config","type":"file","merge":"json",`+
+		`"template":"files/config.json"}]}`, map[string]string{"files/config.json": "{}\n"})
+	module(t, root, "names", `{"module":"names","config":{"url":{"type":"string","description":"d","default":""}},`+
+		`"resources":[{"id":"runtime-config","type":"file","merge":"json","takes-config":["url"],"content":"{}"}]}`, nil)
+	module(t, root, "none", `{"module":"none","resources":[{"id":"c","type":"file","merge":"json",`+
+		`"takes-config":[],"content":"{}"}]}`, nil)
+	module(t, root, "plain", `{"module":"plain","resources":[{"id":"c","type":"file","content":"{}"}]}`, nil)
+	got, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := map[string][]string{"whole": {"runtime-config taking its whole layer"}}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("found %v, want %v", got, want)
+	}
+}

checks/config/unmoved

@@ -0,0 +1,5 @@
+# The modules still written in the settings form (`settings`, `takes-settings`, `${setting:<key>}`, or a mergeable
+# file naming no keys, which takes its whole layer), one per line: the catalogue's list of modules not yet moved to
+# config (novox/hq ADR 0348 §11). Every other module says config alone. This list only shrinks: a module that says no
+# old name is taken off, and a line the trunk's copy does not hold is refused. When it is empty, the controller
+# refuses the old names (design 57 package R1).

checks/deps/go.mod

@@ -0,0 +1,3 @@
+module git.novox.be/novox/mesh-catalog/checks/deps
+
+go 1.22

checks/deps/main.go

@@ -0,0 +1,255 @@
+// Command deps makes a module's dependencies available to the catalogue's check, or says why it cannot
+// (novox/hq issue 385).
+//
+// A module's tests run only when its dependencies can be fetched. The build seat clones what a check
+// needs with the forge credential and forgets that credential before the check runs, so a module pinning
+// an SDK commit the seat's module cache does not hold cannot fetch it from the forge. The SDK is cloned
+// beside the check all the same (MESH_CHECK_BESIDE, mesh-controller's besideRefs): every requirement of the
+// mesh's own forge is taken from the clone of its repository there, at the commit or the tag its version
+// names, through a go.mod of its own (-modfile) — the module's own files are not changed, and no forge
+// credential is added.
+//
+// Usage: deps -beside <dir> -work <dir> <module dir>. It prints the go.mod to build the module with, or
+// nothing when the module fetches what it needs; when it cannot, it prints why and exits 1, and the check
+// fails: a module whose tests could not run is a failure, never a note.
+package main
+
+import (
+	"archive/tar"
+	"bytes"
+	"encoding/json"
+	"errors"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"strings"
+)
+
+// forge is the prefix of the Go modules of the mesh's own forge: <forge><repository>[/<directory>].
+const forge = "git.novox.be/novox/"
+
+func main() {
+	beside := flag.String("beside", "", "where the repositories beside the check are cloned (MESH_CHECK_BESIDE)")
+	work := flag.String("work", os.TempDir(), "where the go.mod and the sources taken from beside are written")
+	flag.Parse()
+	if flag.NArg() != 1 {
+		fmt.Println("usage: deps -beside <dir> -work <dir> <module dir>")
+		os.Exit(2)
+	}
+	modfile, err := resolve(flag.Arg(0), *beside, *work)
+	if err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+	if modfile != "" {
+		fmt.Println(modfile)
+	}
+}
+
+// resolve is the go.mod the module at dir builds with: "" when its own fetches everything, else one
+// beside it in work that takes every requirement of the mesh's forge from its clone beside the check.
+func resolve(dir, beside, work string) (string, error) {
+	out, err := goIn(dir, "mod", "download")
+	if err == nil {
+		return "", nil
+	}
+	fetching := lastLine(out)
+	required, err := forgeRequirements(dir)
+	if err != nil {
+		return "", err
+	}
+	if len(required) == 0 {
+		return "", fmt.Errorf("its dependencies cannot be fetched: %s", fetching)
+	}
+	if beside == "" {
+		return "", fmt.Errorf("its dependencies cannot be fetched (%s), and nothing was cloned beside the check to "+
+			"take %s from", fetching, repositories(required))
+	}
+	into, err := os.MkdirTemp(work, filepath.Base(dir)+"-")
+	if err != nil {
+		return "", err
+	}
+	modfile := filepath.Join(into, "go.mod")
+	if err := copyFile(filepath.Join(dir, "go.mod"), modfile); err != nil {
+		return "", err
+	}
+	if err := copyFile(filepath.Join(dir, "go.sum"), filepath.Join(into, "go.sum")); err != nil &&
+		!errors.Is(err, os.ErrNotExist) {
+		return "", err
+	}
+	for _, r := range required {
+		source, err := export(beside, r, into)
+		if err != nil {
+			return "", fmt.Errorf("its dependencies cannot be fetched (%s), and %s@%s cannot be taken from the "+
+				"clone beside the check: %w", fetching, r.Path, r.Version, err)
+		}
+		if out, err := goIn(dir, "mod", "edit", "-replace", r.Path+"@"+r.Version+"="+source, modfile); err != nil {
+			return "", fmt.Errorf("%s@%s cannot be taken from the clone beside the check: %s", r.Path, r.Version,
+				lastLine(out))
+		}
+	}
+	if out, err := goIn(dir, "mod", "download", "-modfile="+modfile); err != nil {
+		return "", fmt.Errorf("its dependencies cannot be fetched even with %s taken from the clone beside the "+
+			"check: %s", repositories(required), lastLine(out))
+	}
+	return modfile, nil
+}
+
+// requirement is one module the module requires.
+type requirement struct {
+	Path    string
+	Version string
+}
+
+// forgeRequirements is every requirement of the module at dir that comes from the mesh's own forge.
+func forgeRequirements(dir string) ([]requirement, error) {
+	out, err := goIn(dir, "mod", "edit", "-json")
+	if err != nil {
+		return nil, fmt.Errorf("its go.mod cannot be read: %s", lastLine(out))
+	}
+	var mod struct{ Require []requirement }
+	if err := json.Unmarshal(out, &mod); err != nil {
+		return nil, fmt.Errorf("its go.mod cannot be read: %w", err)
+	}
+	var on []requirement
+	for _, r := range mod.Require {
+		if strings.HasPrefix(r.Path, forge) {
+			on = append(on, r)
+		}
+	}
+	return on, nil
+}
+
+// repositoryOf splits a module path of the forge into its repository and the directory in it.
+func repositoryOf(path string) (string, string) {
+	repo, sub, _ := strings.Cut(strings.TrimPrefix(path, forge), "/")
+	return repo, sub
+}
+
+func repositories(rs []requirement) string {
+	var names []string
+	for _, r := range rs {
+		repo, _ := repositoryOf(r.Path)
+		names = append(names, repo)
+	}
+	return strings.Join(names, ", ")
+}
+
+// pseudo is a pseudo-version's commit: v0.1.14-0.20261012082113-9747f3e1b1ac → 9747f3e1b1ac.
+var pseudo = regexp.MustCompile(`[-.]\d{14}-([0-9a-f]{12})$`)
+
+// refOf is the ref a version names in its repository: a pseudo-version's commit, else the tag a module in
+// a directory is released under (<directory>/<version>).
+func refOf(sub, version string) string {
+	version = strings.TrimSuffix(version, "+incompatible")
+	if m := pseudo.FindStringSubmatch(version); m != nil {
+		return m[1]
+	}
+	if sub != "" {
+		return sub + "/" + version
+	}
+	return version
+}
+
+// export writes the module r names, at its version, from its repository's clone beside the check into
+// into, and answers its directory.
+func export(beside string, r requirement, into string) (string, error) {
+	repo, sub := repositoryOf(r.Path)
+	clone := filepath.Join(beside, repo)
+	if _, err := os.Stat(filepath.Join(clone, ".git")); err != nil {
+		return "", fmt.Errorf("no clone of %s is beside the check", repo)
+	}
+	ref := refOf(sub, r.Version)
+	commit, err := exec.Command("git", "-C", clone, "rev-parse", "--verify", "--quiet", ref+"^{commit}").Output()
+	if err != nil {
+		return "", fmt.Errorf("the clone of %s holds no %s (a commit or tag not pushed to the forge?)", repo, ref)
+	}
+	at := strings.TrimSpace(string(commit))
+	args := []string{"-C", clone, "archive", "--format=tar", at}
+	if sub != "" {
+		args = append(args, "--", sub)
+	}
+	var stderr bytes.Buffer
+	archive := exec.Command("git", args...)
+	archive.Stderr = &stderr
+	raw, err := archive.Output()
+	if err != nil {
+		return "", fmt.Errorf("git archive of %s at %s: %v %s", repo, ref, err, strings.TrimSpace(stderr.String()))
+	}
+	root := filepath.Join(into, repo+"@"+at[:12])
+	if err := untar(raw, root); err != nil {
+		return "", err
+	}
+	source := filepath.Join(root, filepath.FromSlash(sub))
+	if _, err := os.Stat(filepath.Join(source, "go.mod")); err != nil {
+		return "", fmt.Errorf("%s at %s has no go.mod in %q", repo, ref, sub)
+	}
+	return source, nil
+}
+
+// untar writes a tar's directories and regular files under root.
+func untar(raw []byte, root string) error {
+	r := tar.NewReader(bytes.NewReader(raw))
+	for {
+		h, err := r.Next()
+		if err == io.EOF {
+			return nil
+		}
+		if err != nil {
+			return err
+		}
+		name := filepath.Clean(filepath.FromSlash(h.Name))
+		if name == "." || strings.HasPrefix(name, "..") || filepath.IsAbs(name) {
+			continue
+		}
+		path := filepath.Join(root, name)
+		switch h.Typeflag {
+		case tar.TypeDir:
+			if err := os.MkdirAll(path, 0o755); err != nil {
+				return err
+			}
+		case tar.TypeReg:
+			if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+				return err
+			}
+			body, err := io.ReadAll(r)
+			if err != nil {
+				return err
+			}
+			if err := os.WriteFile(path, body, 0o644); err != nil {
+				return err
+			}
+		}
+	}
+}
+
+func copyFile(from, to string) error {
+	raw, err := os.ReadFile(from)
+	if err != nil {
+		return err
+	}
+	return os.WriteFile(to, raw, 0o644)
+}
+
+// goIn runs the go command in dir.
+func goIn(dir string, args ...string) ([]byte, error) {
+	cmd := exec.Command("go", args...)
+	cmd.Dir = dir
+	var stderr bytes.Buffer
+	cmd.Stderr = &stderr
+	out, err := cmd.Output()
+	if err != nil {
+		return append(out, stderr.Bytes()...), err
+	}
+	return out, nil
+}
+
+// lastLine is the last line a command said, which is where go says what failed.
+func lastLine(out []byte) string {
+	lines := strings.Split(strings.TrimSpace(string(out)), "\n")
+	return strings.TrimSpace(lines[len(lines)-1])
+}

checks/deps/main_test.go

@@ -0,0 +1,177 @@
+package main
+
+import (
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// offline is a Go that fetches nothing: what the build seat is once the forge credential is gone, for a pin
+// its module cache does not hold (novox/hq issue 385).
+func offline(t *testing.T) {
+	t.Helper()
+	t.Setenv("GOPROXY", "off")
+	t.Setenv("GOFLAGS", "")
+	t.Setenv("GOWORK", "off")
+	// Not GOPRIVATE: a private module is fetched directly by git, around GOPROXY, with whatever credential
+	// the machine running the test holds.
+	t.Setenv("GOPRIVATE", "")
+	t.Setenv("GONOPROXY", "")
+	t.Setenv("GOSUMDB", "off")
+	t.Setenv("GOMODCACHE", t.TempDir())
+}
+
+func git(t *testing.T, dir string, args ...string) string {
+	t.Helper()
+	cmd := exec.Command("git", args...)
+	cmd.Dir = dir
+	cmd.Env = append(os.Environ(), "GIT_AUTHOR_NAME=t", "GIT_AUTHOR_EMAIL=t@t", "GIT_COMMITTER_NAME=t",
+		"GIT_COMMITTER_EMAIL=t@t", "GIT_AUTHOR_DATE=2026-10-12T08:21:13Z", "GIT_COMMITTER_DATE=2026-10-12T08:21:13Z")
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		t.Fatalf("git %s: %v\n%s", strings.Join(args, " "), err, out)
+	}
+	return strings.TrimSpace(string(out))
+}
+
+func write(t *testing.T, path, content string) {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// sdkBeside is the SDK's repository cloned beside a check, its Go module under go/, one commit tagged
+// go/v0.1.7. It answers the beside root and the commit.
+func sdkBeside(t *testing.T) (string, string) {
+	t.Helper()
+	beside := t.TempDir()
+	repo := filepath.Join(beside, "mesh-sdk")
+	write(t, filepath.Join(repo, "go", "go.mod"), "module git.novox.be/novox/mesh-sdk/go\n\ngo 1.22\n")
+	write(t, filepath.Join(repo, "go", "sdk", "sdk.go"), "package sdk\n\nfunc Hello() string { return \"hello\" }\n")
+	write(t, filepath.Join(repo, "README.md"), "the SDK\n")
+	git(t, repo, "init", "--quiet")
+	git(t, repo, "add", ".")
+	git(t, repo, "commit", "--quiet", "-m", "sdk")
+	git(t, repo, "tag", "go/v0.1.7")
+	return beside, git(t, repo, "rev-parse", "HEAD")
+}
+
+// moduleRequiring is a catalogue module whose code and test use the SDK at the version given.
+func moduleRequiring(t *testing.T, version string) string {
+	t.Helper()
+	dir := filepath.Join(t.TempDir(), "messenger")
+	write(t, filepath.Join(dir, "go.mod"), "module git.novox.be/novox/mesh-catalog/modules/messenger\n\ngo 1.22\n\n"+
+		"require git.novox.be/novox/mesh-sdk/go "+version+"\n")
+	write(t, filepath.Join(dir, "main.go"), "package main\n\nimport \"git.novox.be/novox/mesh-sdk/go/sdk\"\n\n"+
+		"func main() { println(sdk.Hello()) }\n")
+	return dir
+}
+
+func builds(t *testing.T, dir, modfile string) {
+	t.Helper()
+	args := []string{"vet"}
+	if modfile != "" {
+		args = append(args, "-modfile="+modfile)
+	}
+	cmd := exec.Command("go", append(args, "./...")...)
+	cmd.Dir = dir
+	if out, err := cmd.CombinedOutput(); err != nil {
+		t.Fatalf("the module does not build with %q: %v\n%s", modfile, err, out)
+	}
+}
+
+// A module that needs nothing it cannot fetch is left as it is: no other go.mod.
+func TestAModuleThatFetchesItsDependenciesNeedsNothingBeside(t *testing.T) {
+	offline(t)
+	dir := filepath.Join(t.TempDir(), "plain")
+	write(t, filepath.Join(dir, "go.mod"), "module example.com/plain\n\ngo 1.22\n")
+	write(t, filepath.Join(dir, "main.go"), "package main\n\nfunc main() {}\n")
+	modfile, err := resolve(dir, "", t.TempDir())
+	if err != nil || modfile != "" {
+		t.Fatalf("resolve = %q, %v; want nothing", modfile, err)
+	}
+}
+
+// The case of issue 385: the module pins an SDK commit the build seat cannot fetch. It is taken from the
+// SDK's clone beside the check, and the module builds against it.
+func TestAPinnedSDKCommitIsTakenFromTheCloneBeside(t *testing.T) {
+	offline(t)
+	beside, commit := sdkBeside(t)
+	dir := moduleRequiring(t, "v0.1.14-0.20261012082113-"+commit[:12])
+	modfile, err := resolve(dir, beside, t.TempDir())
+	if err != nil {
+		t.Fatalf("resolve: %v", err)
+	}
+	if modfile == "" {
+		t.Fatal("resolve said the module fetches its dependencies, with nothing to fetch them from")
+	}
+	builds(t, dir, modfile)
+	if raw, _ := os.ReadFile(filepath.Join(dir, "go.mod")); strings.Contains(string(raw), "replace") {
+		t.Fatalf("the module's own go.mod was changed:\n%s", raw)
+	}
+}
+
+// A released SDK is found by the tag it is released under: go/<version>.
+func TestATaggedSDKIsTakenFromTheCloneBeside(t *testing.T) {
+	offline(t)
+	beside, _ := sdkBeside(t)
+	dir := moduleRequiring(t, "v0.1.7")
+	modfile, err := resolve(dir, beside, t.TempDir())
+	if err != nil {
+		t.Fatalf("resolve: %v", err)
+	}
+	builds(t, dir, modfile)
+}
+
+// A commit the clone beside does not hold (a branch never pushed) cannot be tested, and says which.
+func TestACommitTheCloneBesideDoesNotHoldIsSaid(t *testing.T) {
+	offline(t)
+	beside, _ := sdkBeside(t)
+	dir := moduleRequiring(t, "v0.1.14-0.20261010132341-4f3efc98e0c0")
+	_, err := resolve(dir, beside, t.TempDir())
+	if err == nil {
+		t.Fatal("resolve found a commit nothing holds")
+	}
+	for _, want := range []string{"git.novox.be/novox/mesh-sdk/go@v0.1.14-0.20261010132341-4f3efc98e0c0", "4f3efc98e0c0"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("the reason %q does not name %s", err, want)
+		}
+	}
+}
+
+// With nothing cloned beside (a check by hand without the forge), the reason says that.
+func TestNoCloneBesideIsSaid(t *testing.T) {
+	offline(t)
+	_, commit := sdkBeside(t)
+	dir := moduleRequiring(t, "v0.1.14-0.20261012082113-"+commit[:12])
+	for _, beside := range []string{"", t.TempDir()} {
+		_, err := resolve(dir, beside, t.TempDir())
+		if err == nil {
+			t.Fatalf("resolve with %q beside found what is not there", beside)
+		}
+		if !strings.Contains(err.Error(), "mesh-sdk") {
+			t.Errorf("the reason %q does not name the repository it needed", err)
+		}
+	}
+}
+
+func TestTheRefOfAVersion(t *testing.T) {
+	cases := []struct{ sub, version, want string }{
+		{"go", "v0.1.14-0.20261012082113-9747f3e1b1ac", "9747f3e1b1ac"},
+		{"go", "v0.0.0-20261012082113-9747f3e1b1ac", "9747f3e1b1ac"},
+		{"go", "v0.1.7", "go/v0.1.7"},
+		{"", "v1.2.0", "v1.2.0"},
+		{"", "v2.0.0+incompatible", "v2.0.0"},
+	}
+	for _, c := range cases {
+		if got := refOf(c.sub, c.version); got != c.want {
+			t.Errorf("refOf(%q, %q) = %q, want %q", c.sub, c.version, got, c.want)
+		}
+	}
+}

checks/mailstore/go.mod

@@ -0,0 +1,3 @@
+module git.novox.be/novox/mesh-catalog/checks/mailstore
+
+go 1.22

checks/mailstore/main.go

@@ -0,0 +1,81 @@
+// Command mailstore refuses any manifest but modules/mesh-mail claiming the mail-store seat (novox/hq ADR 0378
+// §3, issue 800 part A): the operator's mail is read, searched and sent through this one seat, and a second
+// claimant would be a second path to the same mail that ADR 0378 never accounted for.
+//
+//	go run . <catalogue root>
+//
+// Exits 1 on a finding.
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+)
+
+// MailStoreSeat is the seat only mesh-mail may claim.
+const MailStoreSeat = "mail-store"
+
+// MailStoreModule is the one module allowed to claim it.
+const MailStoreModule = "mesh-mail"
+
+// Finding is one manifest refused: a module other than mesh-mail claiming mail-store.
+type Finding struct {
+	Module string
+}
+
+// Check reads every manifest under root/modules and answers which ones it refuses.
+func Check(root string) ([]Finding, error) {
+	manifests, err := filepath.Glob(filepath.Join(root, "modules", "*", "module.json"))
+	if err != nil {
+		return nil, err
+	}
+	sort.Strings(manifests)
+	var out []Finding
+	for _, path := range manifests {
+		raw, err := os.ReadFile(path)
+		if err != nil {
+			return nil, err
+		}
+		var m struct {
+			Module string `json:"module"`
+			Claims []struct {
+				Name string `json:"name"`
+			} `json:"claims"`
+		}
+		if err := json.Unmarshal(raw, &m); err != nil {
+			return nil, fmt.Errorf("%s: %w", path, err)
+		}
+		if m.Module == MailStoreModule {
+			continue
+		}
+		for _, c := range m.Claims {
+			if c.Name == MailStoreSeat {
+				out = append(out, Finding{Module: m.Module})
+				break
+			}
+		}
+	}
+	return out, nil
+}
+
+func main() {
+	root := "."
+	if len(os.Args) > 1 {
+		root = os.Args[1]
+	}
+	found, err := Check(root)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+	for _, f := range found {
+		fmt.Printf("%s claims the mail-store seat: only %s may (novox/hq ADR 0378 §3)\n", f.Module, MailStoreModule)
+	}
+	if len(found) > 0 {
+		os.Exit(1)
+	}
+	fmt.Println("mail-store: claimed only by mesh-mail")
+}

checks/mailstore/main_test.go

@@ -0,0 +1,43 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func manifest(t *testing.T, root, module, claims string) {
+	t.Helper()
+	dir := filepath.Join(root, "modules", module)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	body := `{"module":"` + module + `","claims":[` + claims + `]}`
+	if err := os.WriteFile(filepath.Join(dir, "module.json"), []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestAnotherModuleClaimingMailStoreIsRefused(t *testing.T) {
+	root := t.TempDir()
+	manifest(t, root, "mesh-mail", `{"name":"mail-store","scope":"mesh"}`)
+	manifest(t, root, "betterbird", `{"name":"mail-store","scope":"mesh"}`)
+	manifest(t, root, "dunst", `{"name":"node-notifier","scope":"node"}`)
+	found, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(found) != 1 || found[0].Module != "betterbird" {
+		t.Fatalf("refused %+v", found)
+	}
+}
+
+func TestTheCatalogueHasNone(t *testing.T) {
+	found, err := Check("../..")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(found) != 0 {
+		t.Fatalf("%+v", found)
+	}
+}

checks/owned/go.mod

@@ -0,0 +1,3 @@
+module git.novox.be/novox/mesh-catalog/checks/owned
+
+go 1.22

checks/owned/main.go

@@ -0,0 +1,236 @@
+// Command owned judges how the catalogue's directories and archives treat files they did not write (novox/hq
+// ADR 0422 §8, issue 1024). It refuses, naming the module, the resource and the reason:
+//
+//  1. a directory or archive without `unknown`, or with a value but move-out, module or program;
+//
+//  2. `move-out` on a path not under ${machine:account-home} or ${machine:agent-home};
+//
+//  3. `knows` with an empty, absolute, `.`/`..`/empty-component or repeated path;
+//
+//  4. a path one module declares (a resource's path, or a fact with "home": true) lying inside a directory of
+//     another module, after ${dir:<id>} is resolved within each module and both homes are read as one root.
+//     Archives are not containers for this rule. This holds for ~/.ssh what checks/sshdir held (ADR 0415 §6).
+//
+//     go run . <catalogue root>
+//
+// Exits 1 on a finding.
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+// Home is the one root both machine homes are read as.
+const Home = "${home}"
+
+var (
+	ofDir   = regexp.MustCompile(`\$\{dir:([a-z0-9][a-z0-9_-]*)\}`)
+	homeVar = strings.NewReplacer("${machine:account-home}", Home, "${machine:agent-home}", Home)
+	values  = map[string]bool{"move-out": true, "module": true, "program": true}
+)
+
+// Finding is one refusal.
+type Finding struct {
+	Rule            int
+	Module, ID, Why string
+}
+
+type resource struct {
+	ID, Type, Path, Unknown string
+	Knows                   []string
+	HasKnows                bool
+}
+
+type parsed struct {
+	Module    string
+	Resources []resource
+	Facts     []string // paths of facts with "home": true, under the home
+}
+
+func load(file string) (*parsed, error) {
+	raw, err := os.ReadFile(file)
+	if err != nil {
+		return nil, err
+	}
+	var m struct {
+		Module    string `json:"module"`
+		Resources []struct {
+			ID      string   `json:"id"`
+			Type    string   `json:"type"`
+			Path    string   `json:"path"`
+			Unknown *string  `json:"unknown"`
+			Knows   []string `json:"knows"`
+		} `json:"resources"`
+		Facts map[string]struct {
+			Path string `json:"path"`
+			Home bool   `json:"home"`
+		} `json:"facts"`
+	}
+	if err := json.Unmarshal(raw, &m); err != nil {
+		return nil, fmt.Errorf("%s: %w", file, err)
+	}
+	out := &parsed{Module: m.Module}
+	if out.Module == "" {
+		out.Module = filepath.Base(filepath.Dir(file))
+	}
+	for _, r := range m.Resources {
+		x := resource{ID: r.ID, Type: r.Type, Path: r.Path, Knows: r.Knows, HasKnows: r.Knows != nil}
+		if r.Unknown != nil {
+			x.Unknown = *r.Unknown
+			if x.Unknown == "" {
+				x.Unknown = "(empty)"
+			}
+		}
+		out.Resources = append(out.Resources, x)
+	}
+	keys := make([]string, 0, len(m.Facts))
+	for k := range m.Facts {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	for _, k := range keys {
+		if f := m.Facts[k]; f.Home && f.Path != "" {
+			out.Facts = append(out.Facts, f.Path)
+		}
+	}
+	return out, nil
+}
+
+// norm resolves ${dir:<id>} from the module's own resources, reads both homes as one root and cleans the path.
+func norm(p string, dirs map[string]string) string {
+	for i := 0; i < 8 && ofDir.MatchString(p); i++ {
+		p = ofDir.ReplaceAllStringFunc(p, func(w string) string {
+			if to, ok := dirs[ofDir.FindStringSubmatch(w)[1]]; ok {
+				return to
+			}
+			return w
+		})
+	}
+	p = homeVar.Replace(p)
+	if p == "" {
+		return ""
+	}
+	return path.Clean(p)
+}
+
+func underHome(p string) bool { return strings.HasPrefix(p, Home+"/") }
+
+// badKnows says why a knows entry is refused, or "".
+func badKnows(k string) string {
+	if k == "" {
+		return "is empty"
+	}
+	if strings.HasPrefix(k, "/") {
+		return "is absolute"
+	}
+	for _, c := range strings.Split(strings.TrimSuffix(k, "/"), "/") {
+		if c == "" || c == "." || c == ".." {
+			return "has an empty, . or .. component"
+		}
+	}
+	return ""
+}
+
+type declared struct {
+	module, id, path string
+}
+
+// Check reads every manifest under root/modules and answers what it refuses.
+func Check(root string) ([]Finding, error) {
+	files, err := filepath.Glob(filepath.Join(root, "modules", "*", "module.json"))
+	if err != nil {
+		return nil, err
+	}
+	sort.Strings(files)
+	var out []Finding
+	var paths []declared
+	type container struct{ module, path string }
+	var containers []container
+	for _, file := range files {
+		m, err := load(file)
+		if err != nil {
+			return nil, err
+		}
+		dirs := map[string]string{}
+		for _, r := range m.Resources {
+			if r.ID != "" && r.Path != "" {
+				dirs[r.ID] = r.Path
+			}
+		}
+		for _, r := range m.Resources {
+			p := norm(r.Path, dirs)
+			if p != "" {
+				paths = append(paths, declared{m.Module, r.ID, p})
+			}
+			if r.Type != "directory" && r.Type != "archive" {
+				continue
+			}
+			if r.Type == "directory" && p != "" {
+				containers = append(containers, container{m.Module, p})
+			}
+			add := func(rule int, why string) { out = append(out, Finding{rule, m.Module, r.ID, why}) }
+			switch {
+			case r.Unknown == "":
+				add(1, "a "+r.Type+" without `unknown` (move-out, module or program)")
+			case !values[r.Unknown]:
+				add(1, fmt.Sprintf("`unknown` is %q, not move-out, module or program", r.Unknown))
+			case r.Unknown == "move-out" && !underHome(p):
+				add(2, fmt.Sprintf("`move-out` on %q, which is not under ${machine:account-home} or ${machine:agent-home}", r.Path))
+			}
+			seen := map[string]bool{}
+			for _, k := range r.Knows {
+				if why := badKnows(k); why != "" {
+					add(3, fmt.Sprintf("`knows` entry %q %s", k, why))
+					continue
+				}
+				c := strings.TrimSuffix(k, "/")
+				if seen[c] {
+					add(3, fmt.Sprintf("`knows` entry %q is repeated", k))
+				}
+				seen[c] = true
+			}
+			if r.HasKnows && len(r.Knows) == 0 {
+				add(3, "`knows` is empty")
+			}
+		}
+		for _, f := range m.Facts {
+			if p := norm(Home+"/"+f, nil); p != "" {
+				paths = append(paths, declared{m.Module, "fact " + f, p})
+			}
+		}
+	}
+	for _, d := range paths {
+		for _, c := range containers {
+			if c.module != d.module && (d.path == c.path || strings.HasPrefix(d.path, c.path+"/")) {
+				out = append(out, Finding{4, d.module, d.id, fmt.Sprintf("declares %q, inside a directory of %s (%q)", d.path, c.module, c.path)})
+			}
+		}
+	}
+	return out, nil
+}
+
+func main() {
+	root := "."
+	if len(os.Args) > 1 {
+		root = os.Args[1]
+	}
+	found, err := Check(root)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+	for _, f := range found {
+		fmt.Printf("%s: %s: %s (rule %d, novox/hq ADR 0422 §8, issue 1024)\n", f.Module, f.ID, f.Why, f.Rule)
+	}
+	if len(found) > 0 {
+		os.Exit(1)
+	}
+	fmt.Println("owned paths: every directory and archive says how it treats unknown files; no module declares inside another's directory")
+}

checks/owned/main_test.go

@@ -0,0 +1,132 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func manifest(t *testing.T, root, module, body string) {
+	t.Helper()
+	dir := filepath.Join(root, "modules", module)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "module.json"), []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func check(t *testing.T, root string) []Finding {
+	t.Helper()
+	found, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return found
+}
+
+// only asserts exactly one finding, of the rule, naming the module and the resource (issue 1024).
+func only(t *testing.T, found []Finding, rule int, module, id string) {
+	t.Helper()
+	if len(found) != 1 || found[0].Rule != rule || found[0].Module != module || found[0].ID != id || found[0].Why == "" {
+		t.Fatalf("found %+v; want one finding of rule %d for %s/%s with a reason", found, rule, module, id)
+	}
+}
+
+func dir(id, path, rest string) string {
+	return `{"id":"` + id + `","type":"directory","path":"` + path + `"` + rest + `}`
+}
+
+func mod(name string, resources ...string) string {
+	return `{"module":"` + name + `","resources":[` + strings.Join(resources, ",") + `]}`
+}
+
+func TestMissingOrUnknownValueIsRefused(t *testing.T) {
+	root := t.TempDir()
+	manifest(t, root, "a", mod("a", dir("d", "/var/lib/a", "")))
+	only(t, check(t, root), 1, "a", "d")
+
+	root = t.TempDir()
+	manifest(t, root, "a", mod("a", `{"id":"z","type":"archive","path":"/opt/a","unknown":"delete"}`))
+	only(t, check(t, root), 1, "a", "z")
+}
+
+func TestMoveOutOutsideAHomeIsRefused(t *testing.T) {
+	root := t.TempDir()
+	manifest(t, root, "a", mod("a", dir("d", "/etc/a.d", `,"unknown":"move-out"`)))
+	only(t, check(t, root), 2, "a", "d")
+}
+
+func TestMoveOutUnderAHomeIsAllowed(t *testing.T) {
+	root := t.TempDir()
+	manifest(t, root, "a", mod("a",
+		dir("d", "${machine:account-home}/.config/a", `,"unknown":"move-out"`),
+		dir("e", "${dir:d}/sub", `,"unknown":"move-out"`),
+		dir("f", "${machine:agent-home}/x", `,"unknown":"move-out"`),
+		dir("g", "/var/lib/a", `,"unknown":"program"`),
+		dir("h", "${machine:account-home}/.ssh", `,"unknown":"module"`)))
+	if found := check(t, root); len(found) != 0 {
+		t.Fatalf("refused %+v", found)
+	}
+}
+
+func TestBadKnowsIsRefused(t *testing.T) {
+	for _, knows := range []string{`[""]`, `["/abs"]`, `["a/../b"]`, `["./a"]`, `["a//b"]`, `["a","a"]`, `["a","a/"]`} {
+		root := t.TempDir()
+		manifest(t, root, "a", mod("a", dir("d", "${machine:account-home}/.config/a", `,"unknown":"move-out","knows":`+knows)))
+		only(t, check(t, root), 3, "a", "d")
+	}
+	root := t.TempDir()
+	manifest(t, root, "a", mod("a", dir("d", "${machine:account-home}/.config/a", `,"unknown":"move-out","knows":["forge.credentials","kept/"]`)))
+	if found := check(t, root); len(found) != 0 {
+		t.Fatalf("refused %+v", found)
+	}
+}
+
+func TestAnotherModulesPathInsideADirectoryIsRefused(t *testing.T) {
+	root := t.TempDir()
+	manifest(t, root, "owner", mod("owner", dir("ssh", "${machine:account-home}/.ssh", `,"unknown":"module"`)))
+	manifest(t, root, "intruder", mod("intruder", `{"id":"f","type":"file","path":"${machine:account-home}/.ssh/config.d/20"}`))
+	manifest(t, root, "viahome", mod("viahome", `{"id":"g","type":"file","path":"${machine:agent-home}/.ssh/x"}`))
+	manifest(t, root, "facty", `{"module":"facty","facts":{"hosts":{"path":".ssh/config.d/00","home":true}}}`)
+	manifest(t, root, "outside", mod("outside", `{"id":"o","type":"file","path":"${machine:account-home}/.sshrc"}`))
+	got := map[string]int{}
+	for _, f := range check(t, root) {
+		if f.Rule != 4 || f.Why == "" {
+			t.Fatalf("finding %+v", f)
+		}
+		got[f.Module]++
+	}
+	if len(got) != 3 || got["intruder"] != 1 || got["viahome"] != 1 || got["facty"] != 1 {
+		t.Fatalf("refused %v; want intruder, viahome, facty", got)
+	}
+}
+
+func TestDirReferencesAreResolvedPerModule(t *testing.T) {
+	root := t.TempDir()
+	manifest(t, root, "owner", mod("owner", dir("base", "${machine:account-home}/.config/o", `,"unknown":"move-out"`)))
+	manifest(t, root, "other", mod("other",
+		dir("base", "${machine:account-home}/.config/p", `,"unknown":"move-out"`),
+		`{"id":"f","type":"file","path":"${dir:base}/x"}`))
+	if found := check(t, root); len(found) != 0 {
+		t.Fatalf("refused %+v", found)
+	}
+	manifest(t, root, "third", mod("third",
+		dir("d", "${machine:account-home}/.config/t", `,"unknown":"move-out"`),
+		`{"id":"f","type":"file","path":"${dir:d}/../o/x"}`))
+	only(t, check(t, root), 4, "third", "f")
+}
+
+func TestAnArchiveIsNotAContainerAndSameModuleIsFine(t *testing.T) {
+	root := t.TempDir()
+	manifest(t, root, "a", mod("a",
+		`{"id":"arc","type":"archive","path":"/opt/a","unknown":"program"}`,
+		dir("d", "/opt/a2", `,"unknown":"program"`),
+		`{"id":"f","type":"file","path":"/opt/a2/x"}`))
+	manifest(t, root, "b", mod("b", `{"id":"f","type":"file","path":"/opt/a/x"}`))
+	if found := check(t, root); len(found) != 0 {
+		t.Fatalf("refused %+v", found)
+	}
+}

checks/paths/go.mod

@@ -0,0 +1,3 @@
+module git.novox.be/novox/mesh-catalog/checks/paths
+
+go 1.22

checks/paths/known

@@ -0,0 +1,6 @@
+# Findings standing when the check took /etc and /usr/local/lib in (2026-10-08). Each is a module reading
+# another's file instead of asking over the bus. The list only shrinks: a finding that no longer occurs
+# must leave it. Format: <module> <path> <file>  # why it is still here
+asus-zephyrus-g14 /etc/mesh-power modules/asus-zephyrus-g14/cmd/zephyrus/check.go  # its check reads the power module's moment file; should ask power_hooks
+asus-zephyrus-g14 /etc/mesh-power/moments modules/asus-zephyrus-g14/cmd/zephyrus/check.go  # the same
+asus-zephyrus-g14 /etc/mesh-power/moments/after-wake modules/asus-zephyrus-g14/cmd/zephyrus/check.go  # the same

checks/paths/main.go

@@ -0,0 +1,278 @@
+// Command paths holds the catalogue's modules to talking over the bus (novox/hq ADR 0260): no module
+// names a path that another module's manifest places under /run, /var/lib, /usr/local/lib or /etc.
+// Such a path is that module's state or configuration on its machine, and a second module reading or
+// writing it is two modules talking through a file, which the bus exists to replace.
+//
+// A module owns every `path` of its resources under those roots. Every other module's manifest, and
+// every file of its own but its documentation, its tests and its binaries, is searched for each as a
+// whole path: followed by nothing, a slash, or a character no path takes. A path a container sees
+// inside itself (the target of a `volumes` entry) is the container's, and is not searched.
+//
+// **A drop-in directory is no module's.** A directory whose name ends in `.d` (`/etc/sysctl.d`,
+// `/etc/systemd/system/<unit>.d`, `/etc/X11/xorg.conf.d`) is a place several modules each put their own
+// file, so naming it is not reaching into one module's state; the files in it are each their placer's.
+//
+// Two lists beside this file narrow it, each line a path or a finding and its reason after a `#`:
+//
+//   - shared: paths every program on a machine reads as the machine's, not as a message from their
+//     owner — /etc/hosts, which every resolver reads.
+//   - known: the findings standing on the day the roots were widened (2026-10-08). The check fails on a
+//     finding not listed, and on a listed one that no longer occurs, so the list only shrinks.
+//
+// **Neither list may grow unseen.** With `-base <dir>` holding the base branch's copies of both, a line
+// the change adds is refused unless its reason says `allow:` and why — so an addition is a decision a
+// reviewer reads in the diff, not a way past the check.
+//
+// **What it cannot see:** a path built in code from pieces (`filepath.Join("/etc", name)`), one read
+// from the environment or a setting, and one reached through a shell the module runs. It reads text,
+// not what a program does; review and the runtime's grants cover the rest.
+//
+//	go run . <catalogue root>
+//
+// Exits 1 on a finding.
+package main
+
+import (
+	"bufio"
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+// stateRoots are where a machine keeps a module's state and configuration.
+var stateRoots = []string{"/run/", "/var/lib/", "/usr/local/lib/", "/etc/"}
+
+// Finding is one module naming another's path.
+type Finding struct {
+	Module, File, Path, Owner string
+}
+
+func (f Finding) String() string {
+	return fmt.Sprintf("%s names %s in %s, and the path is %s's; modules talk over the bus (novox/hq ADR 0260)",
+		f.Module, f.Path, f.File, f.Owner)
+}
+
+// Key is how a finding is listed in `known`: the module, the path and the file.
+func (f Finding) Key() string { return f.Module + " " + f.Path + " " + f.File }
+
+// containerTargets drops what a container sees inside itself from a manifest before it is searched:
+// the target half of every `volumes` entry of a container resource.
+func containerTargets(m map[string]any) {
+	resources, _ := m["resources"].([]any)
+	for _, raw := range resources {
+		r, ok := raw.(map[string]any)
+		if !ok || r["type"] != "container" {
+			continue
+		}
+		volumes, _ := r["volumes"].([]any)
+		for i, v := range volumes {
+			if s, ok := v.(string); ok {
+				if src, _, two := strings.Cut(s, ":"); two {
+					volumes[i] = src
+				}
+			}
+			if o, ok := v.(map[string]any); ok {
+				delete(o, "target")
+				delete(o, "container")
+			}
+		}
+	}
+}
+
+// Check is every finding in the catalogue at root, before the lists narrow it.
+func Check(root string) ([]Finding, error) {
+	files, err := filepath.Glob(filepath.Join(root, "modules", "*", "module.json"))
+	if err != nil {
+		return nil, err
+	}
+	owner := map[string]string{}
+	modules := map[string]string{}
+	for _, f := range files {
+		raw, err := os.ReadFile(f)
+		if err != nil {
+			return nil, err
+		}
+		var m struct {
+			Module    string           `json:"module"`
+			Resources []map[string]any `json:"resources"`
+		}
+		if err := json.Unmarshal(raw, &m); err != nil {
+			return nil, fmt.Errorf("%s: %w", f, err)
+		}
+		modules[m.Module] = filepath.Dir(f)
+		for _, r := range m.Resources {
+			p, _ := r["path"].(string)
+			if r["type"] == "directory" && strings.HasSuffix(filepath.Base(p), ".d") {
+				continue // a drop-in directory: several modules' place, no one module's
+			}
+			for _, root := range stateRoots {
+				if strings.HasPrefix(p, root) && len(p) > len(root) {
+					owner[strings.TrimRight(p, "/")] = m.Module
+				}
+			}
+		}
+	}
+	paths := make([]string, 0, len(owner))
+	for p := range owner {
+		paths = append(paths, p)
+	}
+	sort.Strings(paths)
+	patterns := map[string]*regexp.Regexp{}
+	for _, p := range paths {
+		patterns[p] = regexp.MustCompile(regexp.QuoteMeta(p) + `(?:$|[^A-Za-z0-9._-])`)
+	}
+	names := make([]string, 0, len(modules))
+	for n := range modules {
+		names = append(names, n)
+	}
+	sort.Strings(names)
+	var out []Finding
+	for _, module := range names {
+		err := filepath.WalkDir(modules[module], func(path string, d fs.DirEntry, err error) error {
+			if err != nil || d.IsDir() {
+				return err
+			}
+			name := d.Name()
+			if strings.HasSuffix(name, ".md") || strings.HasSuffix(name, "_test.go") ||
+				name == "go.sum" || name == "package-lock.json" {
+				return nil
+			}
+			raw, err := os.ReadFile(path)
+			if err != nil {
+				return err
+			}
+			if bytes.IndexByte(raw, 0) >= 0 {
+				return nil // a binary: what it says is in its source
+			}
+			if name == "module.json" {
+				var m map[string]any
+				if json.Unmarshal(raw, &m) == nil {
+					containerTargets(m)
+					raw, _ = json.Marshal(m)
+				}
+			}
+			text := string(raw)
+			for _, p := range paths {
+				if owner[p] != module && patterns[p].MatchString(text) {
+					rel, _ := filepath.Rel(root, path)
+					out = append(out, Finding{Module: module, File: rel, Path: p, Owner: owner[p]})
+				}
+			}
+			return nil
+		})
+		if err != nil {
+			return nil, err
+		}
+	}
+	return out, nil
+}
+
+// list reads one of the lists beside this check: each line's entry before a `#`, trimmed, with its
+// reason after it.
+func list(path string) (map[string]bool, map[string]string, error) {
+	out, why := map[string]bool{}, map[string]string{}
+	f, err := os.Open(path)
+	if err != nil {
+		return nil, nil, err
+	}
+	defer f.Close()
+	s := bufio.NewScanner(f)
+	for s.Scan() {
+		line, reason, _ := strings.Cut(s.Text(), "#")
+		if line = strings.TrimSpace(line); line != "" {
+			out[line] = true
+			why[line] = strings.TrimSpace(reason)
+		}
+	}
+	return out, why, s.Err()
+}
+
+// Grown is every entry a list has that its base copy does not, and whose reason does not say `allow:`.
+func Grown(name string, now map[string]bool, why map[string]string, base map[string]bool) []string {
+	var out []string
+	for entry := range now {
+		if !base[entry] && !strings.Contains(why[entry], "allow:") {
+			out = append(out, fmt.Sprintf("checks/paths/%s gains %q, which the base branch's copy does not hold; "+
+				"say why after `# allow:` on its line, or keep it out", name, entry))
+		}
+	}
+	sort.Strings(out)
+	return out
+}
+
+// Judge narrows the findings by the lists: what is left to refuse, and the known findings that no
+// longer occur, which must leave the list.
+func Judge(found []Finding, shared, known map[string]bool) (refused []Finding, gone []string) {
+	seen := map[string]bool{}
+	for _, f := range found {
+		if shared[f.Path] {
+			continue
+		}
+		seen[f.Key()] = true
+		if !known[f.Key()] {
+			refused = append(refused, f)
+		}
+	}
+	for k := range known {
+		if !seen[k] {
+			gone = append(gone, k)
+		}
+	}
+	sort.Strings(gone)
+	return refused, gone
+}
+
+func main() {
+	root, baseDir := ".", ""
+	args := os.Args[1:]
+	if len(args) >= 2 && args[0] == "-base" {
+		baseDir, args = args[1], args[2:]
+	}
+	if len(args) > 0 {
+		root = args[0]
+	}
+	found, err := Check(root)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(2)
+	}
+	here := filepath.Join(root, "checks", "paths")
+	shared, sharedWhy, err1 := list(filepath.Join(here, "shared"))
+	known, knownWhy, err2 := list(filepath.Join(here, "known"))
+	if err1 != nil || err2 != nil {
+		fmt.Fprintln(os.Stderr, "the lists beside the check cannot be read:", err1, err2)
+		os.Exit(2)
+	}
+	var grown []string
+	if baseDir == "" {
+		fmt.Println("NOT COMPARED: no base branch's lists were given, so additions to them were not judged")
+	} else {
+		baseShared, _, err1 := list(filepath.Join(baseDir, "shared"))
+		baseKnown, _, err2 := list(filepath.Join(baseDir, "known"))
+		if err1 != nil || err2 != nil {
+			fmt.Fprintln(os.Stderr, "the base branch's lists cannot be read:", err1, err2)
+			os.Exit(2)
+		}
+		grown = append(Grown("shared", shared, sharedWhy, baseShared), Grown("known", known, knownWhy, baseKnown)...)
+	}
+	refused, gone := Judge(found, shared, known)
+	for _, g := range grown {
+		fmt.Println(g)
+	}
+	for _, f := range refused {
+		fmt.Println(f)
+	}
+	for _, k := range gone {
+		fmt.Printf("%q is in checks/paths/known and no longer occurs: take it out, so it cannot come back\n", k)
+	}
+	if len(refused) > 0 || len(gone) > 0 || len(grown) > 0 {
+		os.Exit(1)
+	}
+	fmt.Printf("paths: no module names another's state on its machine (%d known, listed to go)\n", len(known))
+}

checks/paths/main_test.go

@@ -0,0 +1,135 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func catalogue(t *testing.T, files map[string]string) string {
+	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)
+		}
+		if err := os.WriteFile(full, []byte(c), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return root
+}
+
+const owner = `{"module":"power","resources":[{"id":"d","type":"directory","path":"/run/mesh-power"}]}`
+
+func TestAModuleReadingAnothersStateIsFound(t *testing.T) {
+	root := catalogue(t, map[string]string{
+		"modules/power/module.json":       owner,
+		"modules/power/cmd/power/draw.go": `const f = "/run/mesh-power/draw"`,
+		"modules/bar/module.json":         `{"module":"bar","resources":[{"id":"x","type":"file","path":"/etc/x","content":"cat /run/mesh-power/draw"}]}`,
+		"modules/other/module.json":       `{"module":"other"}`,
+		"modules/other/files/bin/read":    "#!/bin/sh\ncat /run/mesh-power\n",
+		"modules/other/README.md":         "it once read /run/mesh-power/draw",
+		"modules/other/cmd/x/x_test.go":   `"/run/mesh-power"`,
+		"modules/near/module.json":        `{"module":"near","resources":[{"id":"y","type":"file","path":"/etc/y","content":"/run/mesh-power-other/x"}]}`,
+	})
+	found, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var got []string
+	for _, f := range found {
+		got = append(got, f.Module+" "+f.File)
+	}
+	want := []string{"bar modules/bar/module.json", "other modules/other/files/bin/read"}
+	if strings.Join(got, "|") != strings.Join(want, "|") {
+		t.Fatalf("found %v, want %v", got, want)
+	}
+	if !strings.Contains(found[0].String(), "power's") {
+		t.Fatalf("%s", found[0])
+	}
+}
+
+func TestACatalogueWhereEachKeepsToItsOwnIsClean(t *testing.T) {
+	root := catalogue(t, map[string]string{
+		"modules/power/module.json":       owner,
+		"modules/power/cmd/power/draw.go": `const f = "/run/mesh-power/draw"`,
+	})
+	if found, err := Check(root); err != nil || len(found) != 0 {
+		t.Fatalf("%v %v", found, err)
+	}
+}
+
+func TestEtcAndUsrLocalLibAreAModulesTooButNotInsideAContainer(t *testing.T) {
+	root := catalogue(t, map[string]string{
+		"modules/power/module.json": `{"module":"power","resources":[{"id":"m","type":"directory","path":"/etc/mesh-power/moments"},` +
+			`{"id":"s","type":"archive","path":"/usr/local/lib/mesh-power"}]}`,
+		"modules/reader/module.json": `{"module":"reader"}`,
+		"modules/reader/cmd/r/r.go":  `const a, b = "/etc/mesh-power/moments/after-wake", "/usr/local/lib/mesh-power/bin/x"`,
+		// A container that mounts something at that path inside itself names its own world.
+		"modules/boxed/module.json": `{"module":"boxed","resources":[{"id":"c","type":"container",` +
+			`"volumes":["/srv/boxed:/etc/mesh-power/moments",{"source":"/srv/b","target":"/usr/local/lib/mesh-power"}]}]}`,
+		// A binary says what its source says.
+		"modules/boxed/bin/tool": "\x00\x01/etc/mesh-power/moments\x00",
+	})
+	found, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var got []string
+	for _, f := range found {
+		got = append(got, f.Module+" "+f.Path)
+	}
+	want := []string{"reader /etc/mesh-power/moments", "reader /usr/local/lib/mesh-power"}
+	if strings.Join(got, "|") != strings.Join(want, "|") {
+		t.Fatalf("found %v, want %v", got, want)
+	}
+}
+
+func TestSharedPathsPassAndKnownFindingsOnlyShrink(t *testing.T) {
+	found := []Finding{
+		{Module: "dns", File: "modules/dns/module.json", Path: "/etc/hosts", Owner: "hostname"},
+		{Module: "laptop", File: "modules/laptop/k.go", Path: "/etc/triggers", Owner: "keys"},
+		{Module: "new", File: "modules/new/n.go", Path: "/run/mesh-power", Owner: "power"},
+	}
+	shared := map[string]bool{"/etc/hosts": true}
+	known := map[string]bool{
+		"laptop /etc/triggers modules/laptop/k.go": true,
+		"old /run/x modules/old/o.go":              true,
+	}
+	refused, gone := Judge(found, shared, known)
+	if len(refused) != 1 || refused[0].Module != "new" {
+		t.Fatalf("refused %v", refused)
+	}
+	if len(gone) != 1 || gone[0] != "old /run/x modules/old/o.go" {
+		t.Fatalf("gone %v", gone)
+	}
+}
+
+func TestADropInDirectoryIsNoModulesButItsFilesAre(t *testing.T) {
+	root := catalogue(t, map[string]string{
+		"modules/memory/module.json": `{"module":"memory","resources":[{"id":"d","type":"directory","path":"/etc/sysctl.d"},` +
+			`{"id":"f","type":"file","path":"/etc/sysctl.d/90-memory.conf"}]}`,
+		"modules/other/module.json": `{"module":"other","resources":[{"id":"f","type":"file","path":"/etc/sysctl.d/80-other.conf"}]}`,
+		"modules/other/cmd/o/o.go":  `const a, b = "/etc/sysctl.d", "/etc/sysctl.d/90-memory.conf"`,
+	})
+	found, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(found) != 1 || found[0].Path != "/etc/sysctl.d/90-memory.conf" || found[0].Module != "other" {
+		t.Fatalf("%v", found)
+	}
+}
+
+func TestAListGrowsOnlyWithAReasonTheDiffShows(t *testing.T) {
+	base := map[string]bool{"/etc/hosts": true}
+	now := map[string]bool{"/etc/hosts": true, "/etc/a": true, "/etc/b": true}
+	why := map[string]string{"/etc/a": "because", "/etc/b": "allow: every program reads it"}
+	got := Grown("shared", now, why, base)
+	if len(got) != 1 || !strings.Contains(got[0], `"/etc/a"`) {
+		t.Fatalf("%v", got)
+	}
+}

checks/paths/shared

@@ -0,0 +1,3 @@
+# Paths every program on a machine reads as the machine's own, not as a message from the module that
+# writes them (checks/paths, novox/hq ADR 0260). One per line, with why.
+/etc/hosts  # every resolver on the machine reads it; the hostname module writes it for all of them

checks/predefined/go.mod

@@ -0,0 +1,3 @@
+module git.novox.be/novox/mesh-catalog/checks/predefined
+
+go 1.22

checks/predefined/main.go

@@ -0,0 +1,153 @@
+// Command predefined refuses a change to predefined.json that removes a key a module still names (novox/hq ADR
+// 0348 clause 7, design 57 package K2, issue 661).
+//
+// Mesh config and node config hold values only for the keys on the catalogue's list of predefined keys, at the
+// root of the repository; a module's config value may fall back to one, `"predefined": "<key>"`. A key removed
+// while a manifest still names it would leave that module falling back to nothing: the controller refuses its
+// build then, at the next merge that touches it. So the removal is refused here, in the pull request that makes
+// it, naming each module that names the key.
+//
+// **What it cannot know.** Whether a key still holds a value at the mesh or a node is mesh-config's to say (design
+// 57 package K3): it holds the values, and the catalogue's check reads no store. Until mesh-config refuses that
+// itself, removing a key nobody names is let through here, and said.
+//
+// The list it compares with is the trunk's at the merge base, given with -base; without one, nothing was removed.
+// The controller the mesh runs reads the list itself (type, validation, every manifest against it) in the
+// module check; this check reads only its keys.
+//
+//	go run . [-base <the trunk's predefined.json>] <catalogue root>
+//
+// Exits 1 on a finding.
+package main
+
+import (
+	"encoding/json"
+	"errors"
+	"flag"
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+)
+
+// File is the list's file at the root of the catalogue.
+const File = "predefined.json"
+
+// Keys is the keys of a list, read as a JSON object; an absent file has none.
+func Keys(path string) (map[string]bool, error) {
+	raw, err := os.ReadFile(path)
+	if errors.Is(err, fs.ErrNotExist) {
+		return map[string]bool{}, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	var keys map[string]json.RawMessage
+	if err := json.Unmarshal(raw, &keys); err != nil {
+		return nil, fmt.Errorf("%s is not a JSON object of keys: %w", path, err)
+	}
+	out := map[string]bool{}
+	for k := range keys {
+		out[k] = true
+	}
+	return out, nil
+}
+
+// Named is, per predefined key, the modules whose manifests name it: under `config`, or its alias `settings`.
+func Named(root string) (map[string][]string, error) {
+	manifests, err := filepath.Glob(filepath.Join(root, "modules", "*", "module.json"))
+	if err != nil {
+		return nil, err
+	}
+	sort.Strings(manifests)
+	named := map[string][]string{}
+	for _, path := range manifests {
+		raw, err := os.ReadFile(path)
+		if err != nil {
+			return nil, err
+		}
+		var m struct {
+			Module   string                     `json:"module"`
+			Config   map[string]json.RawMessage `json:"config"`
+			Settings map[string]json.RawMessage `json:"settings"`
+		}
+		if err := json.Unmarshal(raw, &m); err != nil {
+			return nil, fmt.Errorf("%s: %w", path, err)
+		}
+		for _, declared := range []map[string]json.RawMessage{m.Config, m.Settings} {
+			for _, d := range declared {
+				var value struct {
+					Predefined string `json:"predefined"`
+				}
+				if json.Unmarshal(d, &value) == nil && value.Predefined != "" {
+					named[value.Predefined] = append(named[value.Predefined], m.Module)
+				}
+			}
+		}
+	}
+	return named, nil
+}
+
+// Removed is each key the base list holds and the tree's does not, with the modules still naming it; a removed
+// key nobody names is answered with none.
+func Removed(base, tree map[string]bool, named map[string][]string) map[string][]string {
+	out := map[string][]string{}
+	for k := range base {
+		if !tree[k] {
+			out[k] = named[k]
+		}
+	}
+	return out
+}
+
+func main() {
+	basePath := flag.String("base", "", "the trunk's predefined.json at the merge base")
+	flag.Parse()
+	if flag.NArg() != 1 {
+		fmt.Fprintln(os.Stderr, "usage: predefined [-base <the trunk's predefined.json>] <catalogue root>")
+		os.Exit(2)
+	}
+	root := flag.Arg(0)
+	tree, err := Keys(filepath.Join(root, File))
+	if err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+	if *basePath == "" {
+		fmt.Printf("%s: %d key(s); no trunk list given, so none was removed\n", File, len(tree))
+		return
+	}
+	base, err := Keys(*basePath)
+	if err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+	named, err := Named(root)
+	if err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+	removed := Removed(base, tree, named)
+	keys := make([]string, 0, len(removed))
+	for k := range removed {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	failed := false
+	for _, k := range keys {
+		if modules := removed[k]; len(modules) > 0 {
+			failed = true
+			fmt.Printf("%s: the key %q is removed and still named by %s: move each off it first (novox/hq ADR 0348 "+
+				"clause 7)\n", File, k, strings.Join(modules, ", "))
+		} else {
+			fmt.Printf("%s: the key %q is removed and no module names it; whether the mesh or a node still holds a "+
+				"value for it is mesh-config's to refuse, not this check's\n", File, k)
+		}
+	}
+	if failed {
+		os.Exit(1)
+	}
+	fmt.Printf("%s: %d key(s), none removed that a module names\n", File, len(tree))
+}

checks/predefined/main_test.go

@@ -0,0 +1,100 @@
+package main
+
+import (
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// A catalogue whose dunst falls back to font-size, and the trunk's list holding font-size and
+// agent-managed-settings.
+func aCatalogue(t *testing.T, list string) (root, base string) {
+	t.Helper()
+	root = t.TempDir()
+	write := func(path, text string) {
+		t.Helper()
+		if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(path, []byte(text), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	write(filepath.Join(root, "modules", "dunst", "module.json"), `{"module": "dunst", "config": {"font-size":
+	  {"type": "number", "description": "points", "default": 10, "predefined": "font-size"}}}`)
+	write(filepath.Join(root, "modules", "claude-code", "module.json"), `{"module": "claude-code", "settings": {
+	  "managed_settings": {"kind": "preference", "default": "{}", "why": "none"}}}`)
+	write(filepath.Join(root, "modules", "plain", "module.json"), `{"module": "plain"}`)
+	if list != "" {
+		write(filepath.Join(root, File), list)
+	}
+	base = filepath.Join(t.TempDir(), "base.json")
+	write(base, `{"font-size": {"type": "number"}, "agent-managed-settings": {"type": "object"}}`)
+	return root, base
+}
+
+func run(t *testing.T, args ...string) (string, error) {
+	t.Helper()
+	out, err := exec.Command("go", append([]string{"run", "."}, args...)...).CombinedOutput()
+	return string(out), err
+}
+
+func TestARemovalOfAKeyAModuleStillNamesIsRefused(t *testing.T) {
+	// The planted removal: font-size goes while dunst still falls back to it.
+	root, base := aCatalogue(t, `{"agent-managed-settings": {"type": "object"}}`)
+	out, err := run(t, "-base", base, root)
+	if err == nil || !strings.Contains(out, `the key "font-size" is removed and still named by dunst`) {
+		t.Fatalf("a removal of a named key passed:\n%s", out)
+	}
+}
+
+func TestARemovalNobodyNamesPassesAndSaysWhatItCannotKnow(t *testing.T) {
+	root, base := aCatalogue(t, `{"font-size": {"type": "number"}}`)
+	out, err := run(t, "-base", base, root)
+	if err != nil || !strings.Contains(out, `"agent-managed-settings" is removed and no module names it`) ||
+		!strings.Contains(out, "mesh-config's to refuse") {
+		t.Fatalf("a removal nobody names: %v\n%s", err, out)
+	}
+}
+
+func TestAListUnchangedOrGrownPasses(t *testing.T) {
+	for _, list := range []string{
+		`{"font-size": {"type": "number"}, "agent-managed-settings": {"type": "object"}}`,
+		`{"font-size": {"type": "number"}, "agent-managed-settings": {"type": "object"}, "accent": {"type": "string"}}`,
+	} {
+		root, base := aCatalogue(t, list)
+		if out, err := run(t, "-base", base, root); err != nil || !strings.Contains(out, "none removed") {
+			t.Fatalf("%s: %v\n%s", list, err, out)
+		}
+	}
+	// No trunk list given: nothing was removed.
+	root, _ := aCatalogue(t, `{}`)
+	if out, err := run(t, root); err != nil || !strings.Contains(out, "none was removed") {
+		t.Fatalf("without a base: %v\n%s", err, out)
+	}
+}
+
+func TestTheFileRemovedWholeIsARemovalOfEveryKey(t *testing.T) {
+	root, base := aCatalogue(t, "")
+	out, err := run(t, "-base", base, root)
+	if err == nil || !strings.Contains(out, `"font-size" is removed and still named by dunst`) {
+		t.Fatalf("the list removed whole passed:\n%s", out)
+	}
+}
+
+func TestNamedReadsBothForms(t *testing.T) {
+	root, _ := aCatalogue(t, "")
+	if err := os.WriteFile(filepath.Join(root, "modules", "plain", "module.json"), []byte(`{"module": "plain",
+	  "settings": {"size": {"predefined": "font-size"}}}`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	named, err := Named(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := strings.Join(named["font-size"], ","); got != "dunst,plain" {
+		t.Fatalf("font-size named by %s", got)
+	}
+}

checks/secrets/go.mod

@@ -0,0 +1,3 @@
+module git.novox.be/novox/mesh-catalog/checks/secrets
+
+go 1.22

checks/secrets/known

@@ -0,0 +1,4 @@
+# Secrets nested below a key a mergeable file takes for its other values, which the controller cannot
+# protect alone yet (it protects top-level keys): "<module> <resource> <dotted key>". This list only shrinks:
+# a line that no longer names a finding is refused, and so is one the trunk's copy does not hold (hq issue 342).
+searxng settings server.secret_key

checks/secrets/main.go

@@ -0,0 +1,254 @@
+// Command secrets refuses, in every module's manifest, a mergeable file that a setting could fill with a
+// password, a token or an API key in place of the vault's (novox/hq issue 342).
+//
+// A password is not a setting: it comes from the key vault, and it can be rotated there. A file that says
+// `"merge": "json"` takes the keys of the mesh-wide and the node's layers over its own content, so a key the
+// content fills with `${secret:<name>}` is one a layer could replace, and the vault's value would lose to it
+// until somebody removed it by hand. The controller refuses a setting of a key the file keeps as `protected`,
+// naming the layer and the key, never the value. This check holds every such file to that: each top-level key
+// whose value holds `${secret:…}`, anywhere below it, is either listed in the file's `protected`, or left out
+// of the file's `takes-settings` (novox/hq ADR 0326), so that no layer reaches it. A file whose text is a template
+// in files/ is judged by the template's text.
+//
+// A secret nested below a key the file takes for its other values (`server.secret_key` below `server`) cannot
+// be protected alone today: the controller protects top-level keys. Such a file is named in the file `known`
+// beside this check, one line per key, until the controller refuses a nested key. The list only shrinks: a
+// line there that no longer names a finding is refused, and so is a line the trunk's copy (the merge base's,
+// given with -base) does not hold. While the trunk holds no copy, the lines in seed are the trunk's.
+//
+//	go run . [-base <the trunk's known>] <catalogue root>
+//
+// Exits 1 on a finding.
+package main
+
+import (
+	"bufio"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+)
+
+// Finding is one key of one mergeable file a layer could fill in place of the vault.
+type Finding struct {
+	Module, ID, Key string
+}
+
+func (f Finding) String() string { return f.Module + " " + f.ID + " " + f.Key }
+
+// Check reads every manifest under root/modules and answers each secret-bearing key a layer could replace.
+func Check(root string) ([]Finding, error) {
+	manifests, err := filepath.Glob(filepath.Join(root, "modules", "*", "module.json"))
+	if err != nil {
+		return nil, err
+	}
+	sort.Strings(manifests)
+	var out []Finding
+	for _, path := range manifests {
+		raw, err := os.ReadFile(path)
+		if err != nil {
+			return nil, err
+		}
+		var m struct {
+			Module    string           `json:"module"`
+			Resources []map[string]any `json:"resources"`
+		}
+		if err := json.Unmarshal(raw, &m); err != nil {
+			return nil, fmt.Errorf("%s: %w", path, err)
+		}
+		for _, r := range m.Resources {
+			if how, _ := r["merge"].(string); how == "" {
+				continue
+			}
+			id, _ := r["id"].(string)
+			content, _ := r["content"].(string)
+			// A file whose text is a template in its module's files/ (novox/hq ADR 0349 §2) is judged by that text,
+			// exactly as it would be inline.
+			if name, _ := r["template"].(string); name != "" {
+				text, err := os.ReadFile(filepath.Join(filepath.Dir(path), filepath.FromSlash(name)))
+				if err != nil {
+					return nil, fmt.Errorf("%s: %s names the template %s: %w", m.Module, id, name, err)
+				}
+				content = string(text)
+			}
+			var doc map[string]any
+			if strings.TrimSpace(content) == "" {
+				continue
+			}
+			if err := json.Unmarshal([]byte(content), &doc); err != nil {
+				return nil, fmt.Errorf("%s: %s merges as JSON and its content is not JSON: %w", m.Module, id, err)
+			}
+			protected := set(r["protected"])
+			takes, names := r["takes-settings"]
+			taken := set(takes)
+			for _, key := range sortedKeys(doc) {
+				for _, at := range secretsBelow(key, doc[key]) {
+					switch {
+					case protected[key]:
+					case names && !taken[key]:
+					default:
+						out = append(out, Finding{m.Module, id, at})
+					}
+				}
+			}
+		}
+	}
+	return out, nil
+}
+
+// secretsBelow answers the dotted path of every string at or below value that names a vault secret.
+func secretsBelow(at string, value any) []string {
+	switch v := value.(type) {
+	case string:
+		if strings.Contains(v, "${secret:") {
+			return []string{at}
+		}
+	case map[string]any:
+		var out []string
+		for _, k := range sortedKeys(v) {
+			out = append(out, secretsBelow(at+"."+k, v[k])...)
+		}
+		return out
+	case []any:
+		var out []string
+		for i, e := range v {
+			out = append(out, secretsBelow(fmt.Sprintf("%s[%d]", at, i), e)...)
+		}
+		return out
+	}
+	return nil
+}
+
+func set(v any) map[string]bool {
+	out := map[string]bool{}
+	list, _ := v.([]any)
+	for _, e := range list {
+		if s, ok := e.(string); ok {
+			out[s] = true
+		}
+	}
+	return out
+}
+
+func sortedKeys(m map[string]any) []string {
+	keys := make([]string, 0, len(m))
+	for k := range m {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	return keys
+}
+
+// Known reads the lines of the known list: "<module> <resource> <key>", # comments and blank lines skipped.
+func Known(path string) (map[string]bool, error) {
+	f, err := os.Open(path)
+	if os.IsNotExist(err) {
+		return map[string]bool{}, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	defer f.Close()
+	out := map[string]bool{}
+	s := bufio.NewScanner(f)
+	for s.Scan() {
+		line := strings.TrimSpace(s.Text())
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		out[strings.Join(strings.Fields(line), " ")] = true
+	}
+	return out, s.Err()
+}
+
+// seed is the known list as it was first written, standing for the trunk's copy until the trunk holds one.
+var seed = map[string]bool{
+	"searxng settings server.secret_key": true,
+}
+
+// Added answers the lines of known that base does not hold: a line may leave the list, never join it.
+func Added(known, base map[string]bool) []string {
+	var out []string
+	for line := range known {
+		if !base[line] {
+			out = append(out, line)
+		}
+	}
+	sort.Strings(out)
+	return out
+}
+
+// Judge splits the findings into those refused and the known lines that no longer name one.
+func Judge(found []Finding, known map[string]bool) (refused []Finding, stale []string) {
+	seen := map[string]bool{}
+	for _, f := range found {
+		seen[f.String()] = true
+		if !known[f.String()] {
+			refused = append(refused, f)
+		}
+	}
+	for line := range known {
+		if !seen[line] {
+			stale = append(stale, line)
+		}
+	}
+	sort.Strings(stale)
+	return refused, stale
+}
+
+// remedy says how a finding is put right.
+func remedy(key string) string {
+	top, _, nested := strings.Cut(key, ".")
+	if !nested {
+		return fmt.Sprintf("list %q in the file's \"protected\", so the controller refuses a setting of it", top)
+	}
+	return fmt.Sprintf("the controller protects a top-level key only; list %q in the file's \"protected\" if "+
+		"nothing else below it is the operator's, or leave it out of the file's \"takes-settings\"", top)
+}
+
+func main() {
+	basePath := flag.String("base", "", "the trunk's copy of known (the merge base's); seed when absent")
+	flag.Parse()
+	root := "."
+	if flag.NArg() > 0 {
+		root = flag.Arg(0)
+	}
+	found, err := Check(root)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+	known, err := Known("known")
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+	base := seed
+	if *basePath != "" {
+		if base, err = Known(*basePath); err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			os.Exit(1)
+		}
+	}
+	added := Added(known, base)
+	for _, line := range added {
+		fmt.Printf("checks/secrets/known gains %q, which the trunk's copy does not hold: the list only shrinks — "+
+			"protect the key instead (novox/hq issue 342)\n", line)
+	}
+	refused, stale := Judge(found, known)
+	for _, f := range refused {
+		fmt.Printf("%s: %s fills %s with a vault secret, and a setting could replace it (novox/hq issue 342): %s\n",
+			f.Module, f.ID, f.Key, remedy(f.Key))
+	}
+	for _, line := range stale {
+		fmt.Printf("checks/secrets/known names %q, which no longer holds a secret a setting could replace: "+
+			"remove the line\n", line)
+	}
+	if len(refused) > 0 || len(stale) > 0 || len(added) > 0 {
+		os.Exit(1)
+	}
+	fmt.Printf("secrets: no setting can replace a vault secret in a mergeable file (%d known, nested)\n", len(known))
+}

checks/secrets/main_test.go

@@ -0,0 +1,154 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func manifest(t *testing.T, root, module, resources string) {
+	t.Helper()
+	dir := filepath.Join(root, "modules", module)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	body := `{"module":"` + module + `","resources":[` + resources + `]}`
+	if err := os.WriteFile(filepath.Join(dir, "module.json"), []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestASecretASettingCouldReplaceIsRefused(t *testing.T) {
+	root := t.TempDir()
+	// Refused: the key holds the vault's secret and nothing keeps a layer off it.
+	manifest(t, root, "a", `{"id":"cfg","type":"file","merge":"json","content":"{\"password\": \"${secret:admin}\"}"}`)
+	// Refused: nested below a key the file takes.
+	manifest(t, root, "b", `{"id":"cfg","type":"file","merge":"json","takes-settings":["server"],`+
+		`"content":"{\"server\": {\"secret_key\": \"${secret:s}\", \"port\": 1}}"}`)
+	// Kept: protected.
+	manifest(t, root, "c", `{"id":"cfg","type":"file","merge":"json","protected":["password"],`+
+		`"content":"{\"password\": \"${secret:admin}\", \"user\": \"admin\"}"}`)
+	// Kept: the file names its keys, and not this one.
+	manifest(t, root, "d", `{"id":"cfg","type":"file","merge":"json","takes-settings":["ui"],`+
+		`"content":"{\"token\": \"${secret:t}\", \"ui\": {}}"}`)
+	// Kept: a file that does not merge takes no setting.
+	manifest(t, root, "e", `{"id":"cfg","type":"file","content":"{\"token\": \"${secret:t}\"}"}`)
+	// Refused: protecting another key does not protect this one; a list element counts too.
+	manifest(t, root, "f", `{"id":"cfg","type":"file","merge":"json","protected":["user"],`+
+		`"content":"{\"users\": [{\"password\": \"${secret:p}\"}]}"}`)
+	found, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := []string{"a cfg password", "b cfg server.secret_key", "f cfg users[0].password"}
+	if len(found) != len(want) {
+		t.Fatalf("found %v, want %v", found, want)
+	}
+	for i, f := range found {
+		if f.String() != want[i] {
+			t.Fatalf("found %v, want %v", found, want)
+		}
+	}
+}
+
+// A mergeable file whose text is a template in files/ (novox/hq ADR 0349 §2) is judged by the template's text,
+// exactly as the same text inline; a template the module's directory lacks is an error, never a silent pass.
+func TestAMergeableFilesTemplateIsJudgedAsItsText(t *testing.T) {
+	root := t.TempDir()
+	manifest(t, root, "a", `{"id":"cfg","type":"file","merge":"json","template":"files/cfg.json"}`)
+	manifest(t, root, "c", `{"id":"cfg","type":"file","merge":"json","protected":["password"],"template":"files/cfg.json"}`)
+	for _, m := range []string{"a", "c"} {
+		dir := filepath.Join(root, "modules", m, "files")
+		if err := os.MkdirAll(dir, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(dir, "cfg.json"), []byte(`{"password": "${secret:admin}"}`), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	found, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(found) != 1 || found[0].String() != "a cfg password" {
+		t.Fatalf("found %v, want [a cfg password]", found)
+	}
+
+	manifest(t, root, "g", `{"id":"cfg","type":"file","merge":"json","template":"files/gone.json"}`)
+	if _, err := Check(root); err == nil {
+		t.Fatal("a template the module's directory lacks passed the check")
+	}
+}
+
+func TestTheKnownListOnlyShrinks(t *testing.T) {
+	found := []Finding{{"b", "cfg", "server.secret_key"}, {"a", "cfg", "password"}}
+	refused, stale := Judge(found, map[string]bool{"b cfg server.secret_key": true, "gone cfg token": true})
+	if len(refused) != 1 || refused[0].String() != "a cfg password" {
+		t.Fatalf("refused %v", refused)
+	}
+	if len(stale) != 1 || stale[0] != "gone cfg token" {
+		t.Fatalf("stale %v", stale)
+	}
+}
+
+func TestTheCatalogueHoldsNoSecretASettingCouldReplace(t *testing.T) {
+	found, err := Check("../..")
+	if err != nil {
+		t.Fatal(err)
+	}
+	known, err := Known("known")
+	if err != nil {
+		t.Fatal(err)
+	}
+	refused, stale := Judge(found, known)
+	if len(refused) > 0 || len(stale) > 0 {
+		t.Fatalf("refused %v, stale %v", refused, stale)
+	}
+}
+
+func TestALineTheTrunkDoesNotHoldIsRefused(t *testing.T) {
+	trunk := map[string]bool{"b cfg server.secret_key": true}
+	// A key unprotected on the branch, and its line added to the list: refused, though it matches a finding.
+	branch := map[string]bool{"b cfg server.secret_key": true, "a cfg password": true}
+	if added := Added(branch, trunk); len(added) != 1 || added[0] != "a cfg password" {
+		t.Fatalf("added %v", added)
+	}
+	// A line removed is no addition.
+	if added := Added(map[string]bool{}, trunk); len(added) != 0 {
+		t.Fatalf("added %v", added)
+	}
+	// Until the trunk holds a copy, the seed stands for it, and the list as committed is within it.
+	known, err := Known("known")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if added := Added(known, seed); len(added) != 0 {
+		t.Fatalf("known holds lines the seed does not: %v", added)
+	}
+}
+
+func TestTheCheckRefusesALineAddedAgainstTheTrunk(t *testing.T) {
+	root := t.TempDir()
+	manifest(t, root, "a", `{"id":"cfg","type":"file","merge":"json","content":"{\"password\": \"${secret:admin}\"}"}`)
+	dir := t.TempDir()
+	base := filepath.Join(dir, "base")
+	if err := os.WriteFile(base, []byte("# the trunk's\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	branch := map[string]bool{"a cfg password": true}
+	found, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	trunk, err := Known(base)
+	if err != nil {
+		t.Fatal(err)
+	}
+	refused, stale := Judge(found, branch)
+	if len(refused) != 0 || len(stale) != 0 {
+		t.Fatalf("the line hides the finding from Judge alone: %v %v", refused, stale)
+	}
+	if added := Added(branch, trunk); len(added) != 1 {
+		t.Fatalf("an added line passed: %v", added)
+	}
+}

checks/sshdir/go.mod

@@ -0,0 +1,3 @@
+module git.novox.be/novox/mesh-catalog/checks/sshdir
+
+go 1.22

checks/sshdir/main.go

@@ -0,0 +1,112 @@
+// Command sshdir refuses any manifest but modules/ssh-client naming a path under ~/.ssh (novox/hq ADR 0415 §6,
+// issue 1020): ssh-client owns ~/.ssh and sweeps what it does not know, so a path another module placed there
+// would be moved out at the next sweep. A module that needs something there provides it to ssh-client instead.
+//
+//	go run . <catalogue root>
+//
+// Every string of a manifest is read, wherever it stands, except prose and a file's text (Prose): a path, a
+// place, a volume. Exits 1 on a finding.
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+)
+
+// SSHModule is the one module allowed to name a path under ~/.ssh.
+const SSHModule = "ssh-client"
+
+// underSSH is a path under ~/.ssh, or ~/.ssh itself, however the home is spelled: ${machine:account-home}/.ssh,
+// ~/.ssh, .ssh/config, or a volume's host side (…/.ssh:/root/.ssh).
+var underSSH = regexp.MustCompile(`(^|[/~])\.ssh($|[/:])`)
+
+// Prose are the keys whose strings are words or a file's text, not a path: a template may say ~/.ssh in a comment.
+var Prose = map[string]bool{"description": true, "why": true, "does": true, "template": true, "content": true, "title": true}
+
+// Finding is one path under ~/.ssh in a manifest other than ssh-client's.
+type Finding struct {
+	Module string
+	Key    string
+	Value  string
+}
+
+// Check reads every manifest under root/modules and answers which paths it refuses.
+func Check(root string) ([]Finding, error) {
+	manifests, err := filepath.Glob(filepath.Join(root, "modules", "*", "module.json"))
+	if err != nil {
+		return nil, err
+	}
+	sort.Strings(manifests)
+	var out []Finding
+	for _, path := range manifests {
+		raw, err := os.ReadFile(path)
+		if err != nil {
+			return nil, err
+		}
+		var m any
+		if err := json.Unmarshal(raw, &m); err != nil {
+			return nil, fmt.Errorf("%s: %w", path, err)
+		}
+		module := filepath.Base(filepath.Dir(path))
+		if obj, ok := m.(map[string]any); ok {
+			if name, ok := obj["module"].(string); ok && name != "" {
+				module = name
+			}
+		}
+		if module == SSHModule {
+			continue
+		}
+		walk(m, "", func(key, value string) {
+			out = append(out, Finding{Module: module, Key: key, Value: value})
+		})
+	}
+	return out, nil
+}
+
+// walk calls found for every string under v, outside Prose, that names a path under ~/.ssh.
+func walk(v any, key string, found func(key, value string)) {
+	switch x := v.(type) {
+	case map[string]any:
+		keys := make([]string, 0, len(x))
+		for k := range x {
+			keys = append(keys, k)
+		}
+		sort.Strings(keys)
+		for _, k := range keys {
+			if !Prose[k] {
+				walk(x[k], k, found)
+			}
+		}
+	case []any:
+		for _, e := range x {
+			walk(e, key, found)
+		}
+	case string:
+		if underSSH.MatchString(x) {
+			found(key, x)
+		}
+	}
+}
+
+func main() {
+	root := "."
+	if len(os.Args) > 1 {
+		root = os.Args[1]
+	}
+	found, err := Check(root)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+	for _, f := range found {
+		fmt.Printf("%s names %q (%s) under ~/.ssh: only %s may, and the sweep moves anything else out (novox/hq ADR 0415 §6)\n", f.Module, f.Value, f.Key, SSHModule)
+	}
+	if len(found) > 0 {
+		os.Exit(1)
+	}
+	fmt.Println("~/.ssh: named only by ssh-client")
+}

checks/sshdir/main_test.go

@@ -0,0 +1,48 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func manifest(t *testing.T, root, module, body string) {
+	t.Helper()
+	dir := filepath.Join(root, "modules", module)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "module.json"), []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestAnotherModuleNamingSSHIsRefused(t *testing.T) {
+	root := t.TempDir()
+	manifest(t, root, "ssh-client", `{"module":"ssh-client","resources":[{"path":"${machine:account-home}/.ssh/config"}]}`)
+	manifest(t, root, "forge-account", `{"module":"forge-account","resources":[{"path":"${machine:account-home}/.ssh/config.d/20-forge"}]}`)
+	manifest(t, root, "roster", `{"module":"roster","facts":{"hosts":{"path":".ssh/known_hosts"}}}`)
+	manifest(t, root, "box", `{"module":"box","containers":[{"volumes":["~/.ssh:/root/.ssh:ro"]}]}`)
+	manifest(t, root, "quiet", `{"module":"quiet","description":"reads ~/.ssh/config","resources":[{"path":"${machine:account-home}/.sshrc-not","template":"# see ~/.ssh/config"},{"path":"/etc/ssh/sshd_config"}]}`)
+	found, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := map[string]bool{}
+	for _, f := range found {
+		got[f.Module] = true
+	}
+	if len(found) != 3 || !got["forge-account"] || !got["roster"] || !got["box"] {
+		t.Fatalf("refused %+v; want forge-account, roster and box", found)
+	}
+}
+
+func TestTheCatalogueHasNone(t *testing.T) {
+	found, err := Check("../..")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(found) != 0 {
+		t.Fatalf("the catalogue names paths under ~/.ssh outside ssh-client: %+v", found)
+	}
+}

checks/templates/go.mod

@@ -0,0 +1,3 @@
+module git.novox.be/novox/mesh-catalog/checks/templates
+
+go 1.22

checks/templates/inline

@@ -0,0 +1,9 @@
+# The modules that still keep a file's text inline in module.json (`content`), one per line: the catalogue's list of
+# modules whose file text has not yet moved to a template in files/ (novox/hq ADR 0349 §2, design 57), or in the
+# templates directory its manifest names (`templates`, issue 731). Every other module's file resources name their
+# template. This list only shrinks: a module that keeps no file text inline is taken off, and a line the trunk's copy
+# does not hold is refused. When it is empty, no manifest in the catalogue carries file text (design 57 package T5,
+# issue 658).
+#
+# A window-manager addition (`contributions`, such as files/i3/*.conf) is not a file resource and takes no template;
+# it moves with the collections (design 57 package L2, issue 681) and is not judged here.

checks/templates/main.go

@@ -0,0 +1,178 @@
+// Command templates refuses a file's text kept inline in a manifest, outside the modules still to move (novox/hq
+// ADR 0349 §2, design 57 package T5, issue 658).
+//
+// A file resource names its text as a template in its module's templates directory (`"template": "<dir>/<name>"`;
+// the directory is the manifest's `"templates"`, files/ when it says none), which the module's build packs into an
+// archive; the controller reads each template back into the file's content, so the
+// mesh holds and composes what it would for the same text inline. A module whose file text has not yet moved is
+// listed in the file `inline` beside this check, one per line. Every other module's file resources say no
+// `content`; a module on the list that keeps none inline is taken off it; and a line the trunk's copy (the merge
+// base's, given with -base) does not hold is refused, so the list only shrinks; while the trunk holds no copy, the
+// modules in seed are the trunk's. When it is empty, no manifest in the catalogue carries file text.
+//
+// Only file resources are judged: a window-manager addition (`contributions`) takes no template and moves with the
+// collections (design 57 package L2, issue 681).
+//
+//	go run . [-base <the trunk's inline>] <catalogue root>
+//
+// Every refusal names the refused module's own templates directory. Exits 1 on a finding.
+package main
+
+import (
+	"bufio"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+)
+
+const (
+	listFile          = "inline"
+	listPathInCatalog = "checks/templates/" + listFile
+)
+
+// Check answers, per module that keeps any, the ids of its file resources that say their text inline.
+func Check(root string) (map[string][]string, error) {
+	manifests, err := filepath.Glob(filepath.Join(root, "modules", "*", "module.json"))
+	if err != nil {
+		return nil, err
+	}
+	sort.Strings(manifests)
+	out := map[string][]string{}
+	for _, path := range manifests {
+		raw, err := os.ReadFile(path)
+		if err != nil {
+			return nil, err
+		}
+		var m struct {
+			Module    string           `json:"module"`
+			Resources []map[string]any `json:"resources"`
+		}
+		if err := json.Unmarshal(raw, &m); err != nil {
+			return nil, fmt.Errorf("%s: %w", path, err)
+		}
+		for _, r := range m.Resources {
+			if _, inline := r["content"]; inline && r["type"] == "file" {
+				out[m.Module] = append(out[m.Module], fmt.Sprint(r["id"]))
+			}
+		}
+	}
+	return out, nil
+}
+
+// TemplatesDir answers the directory a module keeps its templates in, with a trailing slash: its manifest's
+// `templates`, files/ when the manifest says none or cannot be read here.
+func TemplatesDir(root, module string) string {
+	dir := "files/"
+	raw, err := os.ReadFile(filepath.Join(root, "modules", module, "module.json"))
+	if err != nil {
+		return dir
+	}
+	var m struct {
+		Templates string `json:"templates"`
+	}
+	if json.Unmarshal(raw, &m) == nil && m.Templates != "" {
+		dir = strings.TrimSuffix(m.Templates, "/") + "/"
+	}
+	return dir
+}
+
+// Refusal is the finding for a module that keeps file text inline and is not on the list.
+func Refusal(module string, ids []string, dir string) string {
+	return fmt.Sprintf("%s keeps the text of %s inline and is not on %s: keep each file's text in %s and name it as "+
+		"the file's template, packed by the build's archive from %s (novox/hq ADR 0349 §2)",
+		module, strings.Join(ids, ", "), listPathInCatalog, dir, dir)
+}
+
+// Gained is the finding for a module the list gains against the trunk's copy.
+func Gained(module, dir string) string {
+	return fmt.Sprintf("%s gains %s, which the trunk's copy does not hold: the list only shrinks — move its file text "+
+		"to %s instead (novox/hq ADR 0349 §2)", listPathInCatalog, module, dir)
+}
+
+// seed is the list as it was first written, standing for the trunk's copy until the trunk holds one.
+var seed = map[string]bool{"asus-zephyrus-g14": true, "power": true, "showcase": true}
+
+// Listed is the modules a list names, one per line; a line starting with # and a blank line are not modules.
+func Listed(path string) (map[string]bool, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return nil, err
+	}
+	defer f.Close()
+	out := map[string]bool{}
+	s := bufio.NewScanner(f)
+	for s.Scan() {
+		line := strings.TrimSpace(s.Text())
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		out[line] = true
+	}
+	return out, s.Err()
+}
+
+// Judge answers the modules that keep file text inline and are not on the list (refused), the modules on the list
+// that keep none (stale), and the modules on the list that the trunk's list does not hold (added).
+func Judge(found map[string][]string, listed, base map[string]bool) (refused, stale, added []string) {
+	for m := range found {
+		if !listed[m] {
+			refused = append(refused, m)
+		}
+	}
+	for m := range listed {
+		if _, keeps := found[m]; !keeps {
+			stale = append(stale, m)
+		}
+		if !base[m] {
+			added = append(added, m)
+		}
+	}
+	sort.Strings(refused)
+	sort.Strings(stale)
+	sort.Strings(added)
+	return refused, stale, added
+}
+
+func main() {
+	basePath := flag.String("base", "", "the trunk's copy of inline (the merge base's); seed when absent")
+	flag.Parse()
+	root := "."
+	if flag.NArg() > 0 {
+		root = flag.Arg(0)
+	}
+	found, err := Check(root)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+	listed, err := Listed(listFile)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+	base := seed
+	if *basePath != "" {
+		if base, err = Listed(*basePath); err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			os.Exit(1)
+		}
+	}
+	refused, stale, added := Judge(found, listed, base)
+	for _, m := range refused {
+		fmt.Println(Refusal(m, found[m], TemplatesDir(root, m)))
+	}
+	for _, m := range stale {
+		fmt.Printf("%s names %s, which keeps no file text inline: take it off the list\n", listPathInCatalog, m)
+	}
+	for _, m := range added {
+		fmt.Println(Gained(m, TemplatesDir(root, m)))
+	}
+	if len(refused) > 0 || len(stale) > 0 || len(added) > 0 {
+		os.Exit(1)
+	}
+	fmt.Printf("templates: no module keeps a file's text inline but the %d listed\n", len(listed))
+}

checks/templates/main_test.go

@@ -0,0 +1,102 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func module(t *testing.T, root, name, body string) {
+	t.Helper()
+	dir := filepath.Join(root, "modules", name)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "module.json"), []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// A file resource that says its text inline is found, by module and resource; one naming its template, a
+// resource that is not a file and a window-manager addition are not (novox/hq ADR 0349 §2).
+func TestEveryInlineFileTextIsFound(t *testing.T) {
+	root := t.TempDir()
+	module(t, root, "inline", `{"module":"inline","resources":[{"id":"a","type":"file","content":"x"},`+
+		`{"id":"b","type":"file","template":"files/b"},{"id":"c","type":"file","content":""}]}`)
+	module(t, root, "templated", `{"module":"templated","resources":[{"id":"a","type":"file","template":"files/a"},`+
+		`{"id":"d","type":"directory","path":"/x"}],"contributions":{"i3":[{"content":"bindsym x"}]}}`)
+	got, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := map[string][]string{"inline": {"a", "c"}}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("found %v, want %v", got, want)
+	}
+}
+
+// A module not on the list keeps no file text inline; one on the list that keeps none is taken off it; a line the
+// trunk's list does not hold is refused, so the list only shrinks until it is empty.
+func TestTheListOfModulesKeepingTextInlineOnlyShrinks(t *testing.T) {
+	found := map[string][]string{"old": {"a"}, "forgotten": {"b"}}
+	inline := map[string]bool{"old": true, "done": true, "new": true}
+	base := map[string]bool{"old": true, "done": true, "forgotten": true}
+	refused, stale, added := Judge(found, inline, base)
+	if !reflect.DeepEqual(refused, []string{"forgotten"}) || !reflect.DeepEqual(stale, []string{"done", "new"}) ||
+		!reflect.DeepEqual(added, []string{"new"}) {
+		t.Fatalf("refused %v, stale %v, added %v", refused, stale, added)
+	}
+}
+
+func TestTheListIsReadWithoutItsComments(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "inline")
+	if err := os.WriteFile(path, []byte("# why\n\npower\n  showcase  \n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	got, err := Listed(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !reflect.DeepEqual(got, map[string]bool{"power": true, "showcase": true}) {
+		t.Fatalf("read %v", got)
+	}
+}
+
+// The catalogue itself: no module keeps a file's text inline but those the list names, and the list names none
+// that keeps it no longer (design 57 package T5, issue 658: the ten modules without a build moved).
+func TestTheCatalogueKeepsFileTextInlineOnlyWhereListed(t *testing.T) {
+	found, err := Check("../..")
+	if err != nil {
+		t.Fatal(err)
+	}
+	inline, err := Listed(listFile)
+	if err != nil {
+		t.Fatal(err)
+	}
+	refused, stale, _ := Judge(found, inline, inline)
+	if len(refused) > 0 || len(stale) > 0 {
+		t.Fatalf("keeping file text inline and not listed: %v; listed and keeping none: %v", refused, stale)
+	}
+}
+
+// A refusal names the refused module's own templates directory, not files/ when the module names another (issue 809).
+func TestARefusalNamesTheModulesOwnTemplatesDirectory(t *testing.T) {
+	root := t.TempDir()
+	module(t, root, "own", `{"module":"own","templates":"t/","resources":[{"id":"a","type":"file","content":"x"}]}`)
+	module(t, root, "plain", `{"module":"plain","resources":[{"id":"a","type":"file","content":"x"}]}`)
+	module(t, root, "bare", `{"module":"bare","templates":"templates","resources":[]}`)
+	for module, dir := range map[string]string{"own": "t/", "plain": "files/", "bare": "templates/"} {
+		if got := TemplatesDir(root, module); got != dir {
+			t.Fatalf("%s: directory %q, want %q", module, got, dir)
+		}
+	}
+	msg := Refusal("own", []string{"a"}, TemplatesDir(root, "own"))
+	if !strings.Contains(msg, "t/") || strings.Contains(msg, "files/") {
+		t.Fatalf("refusal %q", msg)
+	}
+	if msg := Gained("own", TemplatesDir(root, "own")); !strings.Contains(msg, "t/") || strings.Contains(msg, "files/") {
+		t.Fatalf("gained %q", msg)
+	}
+}

checks/words/go.mod

@@ -0,0 +1,3 @@
+module git.novox.be/novox/mesh-catalog/checks/words
+
+go 1.22

checks/words/lines.go

@@ -0,0 +1,73 @@
+package main
+
+import (
+	"fmt"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+// The daemons' lines (novox/hq ADR 0272, its insight of 2026-10-09): the operator types one command, `nox`
+// (`mesh-cli`). The node-engine (`nox-mesh-host`) and the controller (`mesh-controller`) are daemons, and a
+// person never types their names — so no text a module can show names a line of theirs. The list is the
+// copy in retired-lines at the catalogue's root, which novox/hq's words.py prints (`--list lines`) and
+// compares; one line each, `<daemon> <command>`, and a trailing ` …` for a command that is a line only with
+// an argument after it (`mesh-controller module check` is a line; "the mesh-controller module" is prose).
+
+// retiredLine is one daemon's line: the daemon, its command, and whether an argument must follow.
+type retiredLine struct {
+	daemon, command string
+	withArgument    bool
+}
+
+// readLines reads retired-lines: one line a line; blank lines and lines starting with # are not lines.
+func readLines(path string) ([]retiredLine, error) {
+	entries, err := readList(path)
+	if err != nil {
+		return nil, err
+	}
+	var out []retiredLine
+	for _, e := range entries {
+		withArgument := strings.HasSuffix(e, " …")
+		e = strings.TrimSuffix(e, " …")
+		parts := strings.Fields(e)
+		if len(parts) != 2 {
+			return nil, fmt.Errorf("retired-lines: %q is not `<daemon> <command>`", e)
+		}
+		out = append(out, retiredLine{daemon: parts[0], command: parts[1], withArgument: withArgument})
+	}
+	return out, nil
+}
+
+// linePattern matches the line whole: the daemon, white space, the command. A command that is a line only
+// with an argument is matched as a line is written — at the start of a line or a code span, a prompt allowed,
+// with an argument after it — so prose that names the daemon beside the word ("the mesh-controller module is
+// assigned") is not one.
+func linePattern(l retiredLine) *regexp.Regexp {
+	daemon, command := regexp.QuoteMeta(l.daemon), regexp.QuoteMeta(l.command)
+	if l.withArgument {
+		tick := "`"
+		return regexp.MustCompile(`(?m)(?:^|` + tick + `)[ \t]*(?:\$[ \t]*)?(` + daemon + `\s+` + command + `\s+[^\s` + tick + `])`)
+	}
+	return regexp.MustCompile(`(?:^|[^\w-])(` + daemon + `\s+` + command + `)(?:$|[^\w-])`)
+}
+
+// checkLines finds every daemon's line in the texts.
+func checkLines(lines []retiredLine, texts []text) []string {
+	var out []string
+	for _, l := range lines {
+		rx := linePattern(l)
+		for _, t := range texts {
+			if m := rx.FindStringSubmatchIndex(t.s); m != nil {
+				line := t.line
+				if line > 0 {
+					line += strings.Count(t.s[:m[2]], "\n")
+				}
+				out = append(out, fmt.Sprintf("%s:%d: `%s %s` is a daemon's line — the operator types `nox …` (novox/hq "+
+					"ADR 0272) — in %q", t.file, line, l.daemon, l.command, excerpt(t.s, m[2], m[3])))
+			}
+		}
+	}
+	sort.Strings(out)
+	return out
+}

checks/words/main.go

@@ -0,0 +1,351 @@
+// Command words holds what the catalogue's modules say to an agent to the glossary's words (novox/hq ADR
+// 0244): no word the glossary retired for the tools' descriptions — the copy in retired-words at the
+// catalogue's root — in any text a module's tools can show. That text is every string literal in a module's
+// own code that is not a test (a tool's description, the notes and errors it answers with) and every
+// description in its manifest. Comments are not read: an agent never sees them. And no daemon's line
+// (novox/hq ADR 0272, lines.go): the copy in retired-lines, the lines a person would otherwise be told to
+// type of the node-engine's or the controller's binary, where the operator's command is `nox`.
+//
+// A word is matched whole and in any case, a space in it matching any run of white space, and its plural
+// (`s` or `es` on its last part) is matched as the word. A vendor word is
+// never on the list (the glossary does not retire one for the tools), so a wrapped program's own objects —
+// an identity provider's users, a media manager's releases — are never findings.
+//
+//	go run . <catalogue root>
+//
+// Exits 1 on a finding, 2 when the list cannot be read.
+package main
+
+import (
+	"bufio"
+	"encoding/json"
+	"fmt"
+	"go/scanner"
+	"go/token"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+// text is one piece of text an agent can be shown, and where it starts.
+type text struct {
+	file string
+	line int
+	s    string
+}
+
+func main() {
+	root := "."
+	if len(os.Args) > 1 {
+		root = os.Args[1]
+	}
+	words, err := readList(filepath.Join(root, "retired-words"))
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "words:", err)
+		os.Exit(2)
+	}
+	if len(words) == 0 {
+		fmt.Fprintln(os.Stderr, "words: retired-words lists no word — the check would pass on anything")
+		os.Exit(2)
+	}
+	var texts []text
+	files := 0
+	err = filepath.WalkDir(filepath.Join(root, "modules"), func(path string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if d.IsDir() {
+			switch d.Name() {
+			case "node_modules", "dist", "vendor", "test", "tests", "testdata", ".git":
+				return filepath.SkipDir
+			}
+			return nil
+		}
+		rel, _ := filepath.Rel(root, path)
+		name := d.Name()
+		var found []text
+		switch {
+		case strings.HasSuffix(name, "_test.go"), strings.Contains(name, ".test."), strings.Contains(name, ".spec."):
+			return nil
+		case strings.HasSuffix(name, ".go"):
+			found, err = goStrings(path, rel)
+		case strings.HasSuffix(name, ".ts"), strings.HasSuffix(name, ".js"), strings.HasSuffix(name, ".mjs"):
+			found, err = scriptStrings(path, rel)
+		case name == "module.json":
+			found, err = jsonStrings(path, rel)
+		default:
+			return nil
+		}
+		if err != nil {
+			return fmt.Errorf("%s: %w", rel, err)
+		}
+		files++
+		texts = append(texts, found...)
+		return nil
+	})
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "words:", err)
+		os.Exit(2)
+	}
+	findings := check(words, texts)
+	for _, f := range findings {
+		fmt.Println(f)
+	}
+	if len(findings) > 0 {
+		fmt.Printf("words: %d use(s) of a word the glossary retired (novox/hq ADR 0244) — say it in the glossary's word\n", len(findings))
+		os.Exit(1)
+	}
+	// And no daemon's line (novox/hq ADR 0272): what a module tells the operator to type is a `nox` line.
+	lines, err := readLines(filepath.Join(root, "retired-lines"))
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "words:", err)
+		os.Exit(2)
+	}
+	if len(lines) == 0 {
+		fmt.Fprintln(os.Stderr, "words: retired-lines lists no line — the check would pass on anything")
+		os.Exit(2)
+	}
+	if findings := checkLines(lines, texts); len(findings) > 0 {
+		for _, f := range findings {
+			fmt.Println(f)
+		}
+		fmt.Printf("words: %d daemon's line(s) in what a module shows — the operator types one command, nox (novox/hq ADR 0272)\n",
+			len(findings))
+		os.Exit(1)
+	}
+	fmt.Printf("words: %d retired words and %d daemons' lines, none in the %d strings of %d files\n", len(words), len(lines),
+		len(texts), files)
+}
+
+// readList reads retired-words: one word or phrase a line; blank lines and lines starting with # are not words.
+func readList(path string) ([]string, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return nil, err
+	}
+	defer f.Close()
+	var words []string
+	sc := bufio.NewScanner(f)
+	for sc.Scan() {
+		line := strings.TrimSpace(sc.Text())
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		words = append(words, line)
+	}
+	return words, sc.Err()
+}
+
+func pattern(word string) *regexp.Regexp {
+	parts := strings.Fields(word)
+	for i, p := range parts {
+		parts[i] = regexp.QuoteMeta(p)
+	}
+	// The plural is the word too: `s` or `es` on its last part, so "control planes" is found as "control
+	// plane" is. Anything else joined on is another word.
+	return regexp.MustCompile(`(?i)(?:^|[^\w-])(` + strings.Join(parts, `\s+`) + `(?:e?s)?)(?:$|[^\w-])`)
+}
+
+func check(words []string, texts []text) []string {
+	var out []string
+	for _, w := range words {
+		rx := pattern(w)
+		for _, t := range texts {
+			if m := rx.FindStringSubmatchIndex(t.s); m != nil {
+				line := t.line
+				if line > 0 {
+					line += strings.Count(t.s[:m[2]], "\n")
+				}
+				out = append(out, fmt.Sprintf("%s:%d: %q is retired — in %q", t.file, line, w, excerpt(t.s, m[2], m[3])))
+			}
+		}
+	}
+	sort.Strings(out)
+	return out
+}
+
+func excerpt(s string, from, to int) string {
+	a, b := from-50, to+50
+	if a < 0 {
+		a = 0
+	}
+	if b > len(s) {
+		b = len(s)
+	}
+	return strings.Join(strings.Fields(s[a:b]), " ")
+}
+
+// goStrings returns a Go file's string literals, adjacent ones joined across `+` as the program joins them.
+func goStrings(path, rel string) ([]text, error) {
+	src, err := os.ReadFile(path)
+	if err != nil {
+		return nil, err
+	}
+	fset := token.NewFileSet()
+	file := fset.AddFile(rel, -1, len(src))
+	var s scanner.Scanner
+	var bad error
+	s.Init(file, src, func(pos token.Position, msg string) { bad = fmt.Errorf("%s: %s", pos, msg) }, 0)
+	var out []text
+	var cur *text
+	joining := false
+	for {
+		pos, tok, lit := s.Scan()
+		if tok == token.EOF {
+			break
+		}
+		switch {
+		case tok == token.STRING:
+			v, err := strconv.Unquote(lit)
+			if err != nil {
+				v = lit
+			}
+			if cur != nil && joining {
+				cur.s += v
+			} else {
+				out = append(out, text{file: rel, line: fset.Position(pos).Line, s: v})
+				cur = &out[len(out)-1]
+			}
+			joining = false
+		case tok == token.ADD && cur != nil:
+			joining = true
+		default:
+			cur, joining = nil, false
+		}
+	}
+	return out, bad
+}
+
+// scriptStrings returns a TypeScript or JavaScript file's string literals, comments skipped, adjacent ones
+// joined across `+`. A template literal's `${…}` parts are left out of the text around them.
+func scriptStrings(path, rel string) ([]text, error) {
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return nil, err
+	}
+	src := string(b)
+	var out []text
+	line := 1
+	lastWasString, joining := false, false
+	for i := 0; i < len(src); i++ {
+		c := src[i]
+		switch {
+		case c == '\n':
+			line++
+		case c == '/' && i+1 < len(src) && src[i+1] == '/':
+			for i < len(src) && src[i] != '\n' {
+				i++
+			}
+			line++
+		case c == '/' && i+1 < len(src) && src[i+1] == '*':
+			end := strings.Index(src[i+2:], "*/")
+			if end < 0 {
+				end = len(src) - i - 2
+			}
+			line += strings.Count(src[i:i+2+end], "\n")
+			i += end + 3
+		case c == '"' || c == '\'' || c == '`':
+			start := line
+			var sb strings.Builder
+			depth := 0
+			j := i + 1
+			for ; j < len(src); j++ {
+				d := src[j]
+				if d == '\n' {
+					line++
+				}
+				if depth > 0 {
+					if d == '\n' {
+						sb.WriteByte('\n')
+					}
+					if d == '{' {
+						depth++
+					} else if d == '}' {
+						depth--
+					}
+					continue
+				}
+				if d == '\\' && j+1 < len(src) {
+					j++
+					sb.WriteByte(src[j])
+					continue
+				}
+				if c == '`' && d == '$' && j+1 < len(src) && src[j+1] == '{' {
+					depth = 1
+					j++
+					sb.WriteByte(' ')
+					continue
+				}
+				if d == c || (c != '`' && d == '\n') {
+					break
+				}
+				sb.WriteByte(d)
+			}
+			if lastWasString && joining && len(out) > 0 {
+				out[len(out)-1].s += sb.String()
+			} else {
+				out = append(out, text{file: rel, line: start, s: sb.String()})
+			}
+			lastWasString, joining = true, false
+			i = j
+			continue
+		case c == '+' && lastWasString:
+			joining = true
+			continue
+		case c == ' ' || c == '\t' || c == '\r':
+			continue
+		default:
+			lastWasString, joining = false, false
+		}
+		if c == '\n' {
+			continue
+		}
+	}
+	return out, nil
+}
+
+// jsonStrings returns the descriptions in a manifest — every string under a key named "description", at any
+// depth. The rest of a manifest is names, paths and the contents of files it places, none of which a tool
+// shows an agent.
+func jsonStrings(path, rel string) ([]text, error) {
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return nil, err
+	}
+	var v any
+	if err := json.Unmarshal(b, &v); err != nil {
+		return nil, err
+	}
+	var out []text
+	var walk func(any, bool)
+	walk = func(v any, described bool) {
+		switch x := v.(type) {
+		case string:
+			if described {
+				out = append(out, text{file: rel, line: lineOf(string(b), x), s: x})
+			}
+		case []any:
+			for _, e := range x {
+				walk(e, described)
+			}
+		case map[string]any:
+			for k, e := range x {
+				walk(e, k == "description")
+			}
+		}
+	}
+	walk(v, false)
+	return out, nil
+}
+
+func lineOf(src, s string) int {
+	q, _ := json.Marshal(s)
+	if i := strings.Index(src, string(q)); i >= 0 {
+		return strings.Count(src[:i], "\n") + 1
+	}
+	return 0
+}

checks/words/main_test.go

@@ -0,0 +1,89 @@
+package main
+
+import (
+	"os"
+	"testing"
+)
+
+// A retired word's plural is the word; anything else joined on is another word.
+func TestPatternMatchesTheWordAndItsPlural(t *testing.T) {
+	cases := []struct {
+		word, text string
+		want       bool
+	}{
+		{"control plane", "ask the control plane", true},
+		{"control plane", "two control planes", true},
+		{"control plane", "two control\n\tplanes", true},
+		{"substrate", "the substrates", true},
+		{"flavor", "flavors of a module", true},
+		{"flavor", "flavored", false},
+		{"node tools", "node toolsets", false},
+		{"mesh-console", "the mesh-consoles", true},
+		{"mesh-console", "mesh-console-x", false},
+	}
+	for _, c := range cases {
+		if got := pattern(c.word).MatchString(c.text); got != c.want {
+			t.Errorf("pattern(%q) on %q = %v, want %v", c.word, c.text, got, c.want)
+		}
+	}
+}
+
+// A daemon's line is found whole — the daemon, its command, and an argument where the command is a line only with
+// one — and prose that merely names the daemon beside a word is not one (novox/hq ADR 0272).
+func TestADaemonsLineIsFoundWhole(t *testing.T) {
+	push := retiredLine{daemon: "mesh-controller", command: "push"}
+	module := retiredLine{daemon: "mesh-controller", command: "module", withArgument: true}
+	handOver := retiredLine{daemon: "nox-mesh-host", command: "hand-over"}
+	cases := []struct {
+		line retiredLine
+		text string
+		want bool
+	}{
+		{push, "run `mesh-controller push laptop` after", true},
+		{push, "mesh-controller push", true},
+		{push, "mesh-controller\n  push", true},
+		{push, "mesh-controller pushed it", false},
+		{push, "the mesh-controller pushes", false},
+		{push, "mesh-controller-push", false},
+		{module, "`mesh-controller module check modules/*/module.json`", true},
+		{module, "run\n  $ mesh-controller module check x", true},
+		{module, "the mesh-controller module is assigned", false},
+		{module, "mesh-controller module", false},
+		{module, "`mesh-controller module`", false},
+		{handOver, "`nox-mesh-host hand-over /srv/x` at the machine", true},
+		{handOver, "`nox node hand-over laptop /srv/x`", false},
+		{retiredLine{daemon: "mesh-host", command: "hand-over"}, "nox-mesh-host hand-over", false},
+	}
+	for _, c := range cases {
+		if got := linePattern(c.line).MatchString(c.text); got != c.want {
+			t.Errorf("%s %s on %q = %v, want %v", c.line.daemon, c.line.command, c.text, got, c.want)
+		}
+	}
+	found := checkLines([]retiredLine{push, module}, []text{{file: "m/a.go", line: 3, s: "say\n`mesh-controller push`"},
+		{file: "m/b.go", line: 1, s: "the mesh-controller module"}})
+	if len(found) != 1 || found[0] != "m/a.go:4: `mesh-controller push` is a daemon's line — the operator types `nox …` (novox/hq ADR 0272) — in \"say `mesh-controller push`\"" {
+		t.Fatalf("found %q", found)
+	}
+}
+
+// The list's lines read as `<daemon> <command>`, a trailing ` …` meaning an argument must follow; anything else is
+// refused rather than read as some line.
+func TestRetiredLinesAreReadAsDaemonAndCommand(t *testing.T) {
+	dir := t.TempDir()
+	path := dir + "/retired-lines"
+	if err := os.WriteFile(path, []byte("# the list\nmesh-controller push\nmesh-controller module …\n\nnox-mesh-host hand-over\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	lines, err := readLines(path)
+	if err != nil || len(lines) != 3 || lines[0] != (retiredLine{daemon: "mesh-controller", command: "push"}) ||
+		lines[1] != (retiredLine{daemon: "mesh-controller", command: "module", withArgument: true}) ||
+		lines[2] != (retiredLine{daemon: "nox-mesh-host", command: "hand-over"}) {
+		t.Fatalf("read %+v, %v", lines, err)
+	}
+	if err := os.WriteFile(path, []byte("mesh-controller\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := readLines(path); err == nil {
+		t.Fatal("a line with no command was read")
+	}
+}

health-undeclared

@@ -0,0 +1,5 @@
+61
+The long-running resources of this catalogue that do not say how they are ready (`health`, novox/hq ADR 0240
+rule 8), as `module check` counts them. It may only go down: merge-check.sh fails a change that raises it, and
+one that lowers it writes the new number on the first line. From 2026-11-18, or once it is 0, a long-running
+resource without `health` is refused.

merge-check-typescript.sh

@@ -0,0 +1,140 @@
+#!/bin/sh
+# The catalogue's TypeScript part of its own check (novox/hq issue 302's `mesh-check-also`), declared in
+# merge-check.sh's header and run by the build seat in the TypeScript toolchain, after the Go part. The media
+# catalogue's twin is issue 311. Before this, a TypeScript module's change ran nothing of its own before it
+# merged: the Go part said "NOT TESTED HERE", and a type error in the forge module would first have shown in
+# its walk.
+#
+# For every touched module that has a package.json, in a copy of it outside the clone:
+#
+#   1. its dependencies are the toolchain's own (/app/node_modules: the mesh's SDK, Node's types and what the
+#      runtime carries), copied beside it, never fetched: the check holds no credential for the package
+#      registry. A module that depends on a package the toolchain does not hold **fails the check**, by name:
+#      it could not be type-checked or tested, and what could not run is a failure, never a note (novox/hq
+#      issue 385);
+#   2. every source that is not a test is type-checked with the toolchain's compiler and the flags a build
+#      compiles with — the same check the build makes, before the merge rather than in the walk;
+#   3. its tests (test/*.test.ts) run under Node's own runner with types stripped, as its own `npm test` does
+#      after its build: the sources are compiled to dist/ and beside themselves first, so a test that imports
+#      the compiled module, or a source that imports its sibling by its .js name, finds it.
+#
+# Said, never passed silently: a module with no tests is said NOT TESTED on every run that touches it —
+# nothing of it could fail. A module whose tests exist and could not run fails (novox/hq issue 385).
+#
+# By hand: MESH_CHECK_MODULES=gitea sh merge-check-typescript.sh, in the toolchain image (it reads
+# /app/node_modules), or with TOOLCHAIN_MODULES pointing at a node_modules that holds the same.
+#
+# **In an agent's session, outside the toolchain image** (novox/hq issue 742), the same node_modules is
+# assembled first, in a throwaway directory under the check's own workspace, the way the image's `deps` stage
+# assembles it: the toolchain's own package.json and lock (mesh-tools' node-tools/, read from the forge this
+# clone came from, so the list is never copied here) installed with `npm ci`, then the SDK the mesh last
+# published (`@novox/mesh-sdk@latest`), the @novox scope from the forge's package registry, read without a
+# credential. Node and npm are the dev-tools module's; nothing is installed on the machine, no npm
+# configuration or cache of the account's is read or written. Only when neither TOOLCHAIN_MODULES nor
+# /app/node_modules is there: the forge's check, in the image, fetches nothing, as before. The forge is
+# MESH_FORGE (default: the origin remote's), the owner MESH_FORGE_OWNER (default: the origin's owner).
+set -eu
+
+work=$(mktemp -d)
+trap 'rm -rf "$work"' EXIT
+
+deps="${TOOLCHAIN_MODULES:-/app/node_modules}"
+if [ -z "${TOOLCHAIN_MODULES:-}" ] && [ ! -f "$deps/typescript/bin/tsc" ]; then
+	origin=$(git remote get-url origin 2>/dev/null || true)
+	forge="${MESH_FORGE:-$(printf '%s\n' "$origin" | sed -n 's#^\(https\{0,1\}://[^/]*\)/.*#\1#p')}"
+	owner="${MESH_FORGE_OWNER:-$(printf '%s\n' "$origin" | sed -n 's#^https\{0,1\}://[^/]*/\([^/]*\)/.*#\1#p')}"
+	if [ -z "$forge" ] || [ -z "$owner" ]; then
+		echo "NOT CHECKED: no TypeScript toolchain at $deps, and no forge to assemble one from (origin is '$origin'; set MESH_FORGE and MESH_FORGE_OWNER, or TOOLCHAIN_MODULES)"
+		exit 1
+	fi
+	echo "no TypeScript toolchain at $deps: assembling one from $forge/$owner/mesh-tools node-tools/ and $owner's package registry (novox/hq issue 742)"
+	tc="$work/toolchain"
+	mkdir -p "$tc"
+	printf '@%s:registry=%s/api/packages/%s/npm/\n' "$owner" "$forge" "$owner" >"$work/npmrc"
+	# Read with Node's own fetch (dev-tools declares Node, not curl); a status that is not 2xx fails.
+	if ! { node -e '
+		const [base, dir] = process.argv.slice(1);
+		Promise.all(["package.json", "package-lock.json"].map(async (f) => {
+			const r = await fetch(base + f);
+			if (!r.ok) throw new Error(base + f + ": " + r.status);
+			require("fs").writeFileSync(dir + "/" + f, await r.text());
+		})).catch((e) => { console.error(e.message); process.exit(1); });' \
+		"$forge/$owner/mesh-tools/raw/branch/main/node-tools/" "$tc" &&
+		(cd "$tc" && export npm_config_userconfig="$work/npmrc" npm_config_cache="$work/npm-cache" &&
+			npm ci --ignore-scripts --no-audit --no-fund --loglevel=error &&
+			npm install --ignore-scripts --no-audit --no-fund --no-save --loglevel=error "@$owner/mesh-sdk@latest"); }; then
+		echo "NOT CHECKED: the TypeScript toolchain could not be assembled from $forge (novox/hq issue 742)"
+		exit 1
+	fi
+	deps="$tc/node_modules"
+fi
+tsc="$deps/typescript/bin/tsc"
+if [ ! -f "$tsc" ]; then
+	echo "NOT CHECKED: no TypeScript compiler at $tsc — this part runs in the TypeScript toolchain"
+	exit 1
+fi
+
+# The modules the change reaches: the planner's answer (hq ADR 0238), and every module a changed file is in —
+# a change to a module's tests alone moves no build (hq ADR 0267), and its tests must still run.
+touched=$({
+	printf '%s\n' "${MESH_CHECK_MODULES:-}" | tr ',' '\n' | sed -e 's#^modules/##' -e '/\//d'
+	printf '%s\n' "${MESH_CHECK_CHANGED:-}" | tr ',' '\n' | sed -n 's#^modules/\([^/]*\)/.*#\1#p'
+} | sed '/^$/d' | sort -u)
+
+failed=""
+for m in $touched; do
+	d="modules/$m"
+	[ -f "$d/package.json" ] || continue
+	copy="$work/$m"
+	mkdir -p "$copy"
+	(cd "$d" && tar --exclude=./node_modules --exclude=./dist -cf - .) | (cd "$copy" && tar -xf -)
+	# What it depends on, against what the toolchain holds.
+	missing=$(node -e '
+		const p = require(process.argv[1]); const have = require("fs").readdirSync(process.argv[2]);
+		const scoped = (n) => n.startsWith("@") ? n.split("/")[0] : n;
+		const names = Object.keys({ ...(p.dependencies || {}), ...(p.devDependencies || {}) });
+		const held = (n) => have.includes(n) || (n.startsWith("@") && have.includes(scoped(n)) &&
+			require("fs").existsSync(process.argv[2] + "/" + n));
+		console.log(names.filter((n) => n !== "typescript" && !held(n)).join(" "));' "$copy/package.json" "$deps")
+	if [ -n "$missing" ]; then
+		echo "FAILED: $d could not be checked — it depends on $missing, which the toolchain does not hold and the check cannot fetch (novox/hq issue 385)"
+		failed="$failed $m"
+		continue
+	fi
+	mkdir -p "$copy/node_modules"
+	for p in "$deps"/*; do
+		case "$(basename "$p")" in typescript | esbuild | @esbuild) continue ;; esac
+		cp -r "$p" "$copy/node_modules/"
+	done
+	sources=$(cd "$copy" && find . -name '*.ts' ! -name '*.d.ts' ! -path './test/*' ! -path './node_modules/*' ! -path './dist/*' | sort)
+	if [ -n "$sources" ]; then
+		echo "type-checking $d (TypeScript)"
+		# shellcheck disable=SC2086 # the module's sources, none with a space in its name
+		if ! (cd "$copy" && node "$tsc" --noEmit --module NodeNext --moduleResolution NodeNext --target ES2022 \
+			--types node $sources); then
+			failed="$failed $m"
+			continue
+		fi
+	else
+		echo "$d has no TypeScript sources of its own to type-check: its tests read its files"
+	fi
+	if ! ls "$copy"/test/*.test.ts >/dev/null 2>&1; then
+		echo "NOT TESTED: $d is TypeScript and has no tests of its own"
+		continue
+	fi
+	if [ -n "$sources" ]; then
+		# shellcheck disable=SC2086
+		(cd "$copy" && node "$tsc" --module NodeNext --moduleResolution NodeNext --target ES2022 --types node \
+			--rootDir . --outDir dist $sources && node "$tsc" --module NodeNext --moduleResolution NodeNext \
+			--target ES2022 --types node --rootDir . --outDir . $sources)
+	fi
+	echo "testing $d (TypeScript)"
+	if ! (cd "$copy" && node --test --test-reporter=spec --experimental-strip-types \
+		--no-warnings=ExperimentalWarning test/*.test.ts); then
+		failed="$failed $m"
+	fi
+done
+if [ -n "$failed" ]; then
+	echo "TypeScript modules that failed:$failed"
+	exit 1
+fi

merge-check.sh

@@ -0,0 +1,195 @@
+#!/bin/sh
+# mesh-check-toolchain: go
+# mesh-check-also: typescript merge-check-typescript.sh
+#
+# The catalogue's own check (novox/hq ADR 0237 as amended): the second layer of a pull request's merge
+# check, `mesh/repo-check`, run by the build seat in the mesh's Go toolchain.
+#
+# The gate — the manifests the change touches through the running controller's module check, every machine
+# of the facts snapshot composed with them and validated by the node-engine's own validator, the replays
+# against this tree — is the build seat's first layer (`mesh/merge-gate`), run because the mesh's module
+# graph builds these modules from here. It is not repeated here. This is the repository's own:
+#
+#   1. every manifest through the controller's module check, so one module's change cannot leave another
+#      it shares a rule with refused (MESH_GATE is the controller the mesh runs) — and the count of
+#      long-running resources without `health` held to the number in health-undeclared, which only goes down;
+#   2. the Go tests of every module the change touches that has them, under the race detector when the
+#      toolchain has a C compiler. A requirement of the mesh's own forge the module cache does not hold (a
+#      pinned SDK commit) is taken from its repository's clone beside the check (checks/deps); a module whose
+#      dependencies still cannot be had **fails the check**, by name and why — its tests could not run, and a
+#      test that could not run is a failure, never a note (novox/hq issue 385). The integration tests (`//go:build
+#      integration`) run here, with -tags integration, and only here. A module written in
+#      TypeScript is type-checked and tested by
+#      merge-check-typescript.sh, declared above, in the TypeScript toolchain (novox/hq issues 302, 311);
+#   3. the words (novox/hq ADR 0244): no word the glossary retired for the tools, as copied in
+#      retired-words, in any text a module's tools can show an agent — every string in its own code that is
+#      not a test, and every description in its manifest. Run over every module, not only the touched ones,
+#      so a word newly retired is found everywhere it stands. The check's own test runs first.
+#   4. the paths (novox/hq ADR 0260): no module names a path under /run, /var/lib, /usr/local/lib or /etc
+#      that another module's manifest places — modules talk over the bus, not through each other's files.
+#      Over every module; checks/paths/shared and checks/paths/known narrow it, and known only shrinks.
+#   5. the agent's home (novox/hq ADR 0266): no module unpacks an archive, or writes into a file, under
+#      ${machine:agent-home} — the node-engine does both after checking the path, and the agent account owns
+#      that home and could swap a link in between.
+#   6. the secrets (novox/hq issue 342): no mergeable file fills a key with a vault secret that a setting could
+#      replace — the key is `protected`, or left out of the file's `takes-settings`. checks/secrets/known names
+#      the nested ones the controller cannot protect alone yet, and only shrinks.
+#   7. the list of predefined keys (novox/hq ADR 0348 clause 7): a change to predefined.json removes no key a
+#      module still names, judged against the trunk's copy at the merge base. Whether a removed key still holds a
+#      value at the mesh or a node is mesh-config's to refuse; this check reads no store. The list itself and
+#      every manifest against it are judged by the controller's module check in step 1.
+#   8. the config form (novox/hq ADR 0348 clauses 1 and 11): no module says `settings`, `takes-settings` or
+#      `${setting:<key>}`, in its manifest or a template it names, or has a mergeable file naming no keys (which
+#      takes its whole layer), unless checks/config/unmoved lists it as not yet moved; that list only shrinks,
+#      judged against the trunk's copy at the merge base.
+#   9. the file text (novox/hq ADR 0349 §2): no module keeps a file's text inline in its manifest (`content`)
+#      unless checks/templates/inline lists it as not yet moved; each names its template in files/. That list
+#      only shrinks, judged against the trunk's copy at the merge base.
+#   10. the mail-store seat (novox/hq ADR 0378 §3, issue 800): no manifest but modules/mesh-mail claims it.
+#   11. owned paths (novox/hq ADR 0422 §8, issue 1024; it holds ~/.ssh for ssh-client as ADR 0415 §6 asked):
+#      every directory and archive says `unknown` (move-out, module or program) and a valid `knows`; `move-out`
+#      only under a home; and no module declares a path inside a directory of another module.
+#      checks/sshdir (ADR 0415 §6) stays while main runs it; it goes under issue 1035 once main runs checks/owned.
+set -eu
+
+(cd checks/words && go test -count=1 . && go run . ../..)
+# The agent's home (novox/hq ADR 0266): no archive, and no file written into, under it.
+(cd checks/agenthome && go test -count=1 . && go run . ../..)
+# The mail-store seat (novox/hq ADR 0378 §3): only mesh-mail may claim it.
+(cd checks/mailstore && go test -count=1 . && go run . ../..)
+# ~/.ssh (novox/hq ADR 0415 §6): only ssh-client may name a path under it. Main's merge check runs this line, so
+# checks/sshdir stays until main runs checks/owned; it goes under issue 1035.
+(cd checks/sshdir && go test -count=1 . && go run . ../..)
+# Owned paths (novox/hq ADR 0422 §8): unknown files named per directory; no path inside another module's directory.
+(cd checks/owned && go test -count=1 . && go run . ../..)
+# The secrets (novox/hq issue 342): a password is not a setting, so no setting can replace the vault's. The
+# known list only shrinks: judged against the trunk's copy at the merge base, a line it does not hold is refused.
+secrets_base=""
+secrets_ref="origin/${MESH_CHECK_BASE:-main}"
+if merge_base=$(git merge-base HEAD "$secrets_ref" 2>/dev/null); then
+	if git cat-file -e "$merge_base:checks/secrets/known" 2>/dev/null; then
+		secrets_base=$(mktemp)
+		git show "$merge_base:checks/secrets/known" >"$secrets_base"
+	fi
+else
+	echo "NOT COMPARED WITH THE TRUNK: no merge base with $secrets_ref; checks/secrets/known is held to the list it was first written with"
+fi
+(cd checks/secrets && go test -count=1 . && if [ -n "$secrets_base" ]; then go run . -base "$secrets_base" ../..; else go run . ../..; fi)
+# The list of predefined keys (novox/hq ADR 0348 clause 7): no key removed that a module still names. The trunk's
+# list at the merge base is what it is judged against; a trunk without the file had none.
+predefined_base=""
+if merge_base=$(git merge-base HEAD "origin/${MESH_CHECK_BASE:-main}" 2>/dev/null); then
+	predefined_base=$(mktemp)
+	if ! git show "$merge_base:predefined.json" >"$predefined_base" 2>/dev/null; then
+		echo '{}' >"$predefined_base"
+	fi
+else
+	echo "NOT COMPARED WITH THE TRUNK: no merge base with origin/${MESH_CHECK_BASE:-main}; no removal from predefined.json can be seen"
+fi
+(cd checks/predefined && go test -count=1 . && if [ -n "$predefined_base" ]; then go run . -base "$predefined_base" ../..; else go run . ../..; fi)
+# The config form (novox/hq ADR 0348 §1, §11): a moved module says no old name, and the list of modules not yet moved
+# only shrinks, judged against the trunk's copy at the merge base; a trunk without one is the list's first copy.
+unmoved_base=""
+if merge_base=$(git merge-base HEAD "origin/${MESH_CHECK_BASE:-main}" 2>/dev/null); then
+	if git cat-file -e "$merge_base:checks/config/unmoved" 2>/dev/null; then
+		unmoved_base=$(mktemp)
+		git show "$merge_base:checks/config/unmoved" >"$unmoved_base"
+	fi
+else
+	echo "NOT COMPARED WITH THE TRUNK: no merge base with origin/${MESH_CHECK_BASE:-main}; checks/config/unmoved is held to the list it was first written with"
+fi
+(cd checks/config && go test -count=1 . && if [ -n "$unmoved_base" ]; then go run . -base "$unmoved_base" ../..; else go run . ../..; fi)
+# The file text (novox/hq ADR 0349 §2): a file's text is a template in files/, outside the modules not yet moved; the
+# list of those only shrinks, judged against the trunk's copy at the merge base, a trunk without one being its first.
+inline_base=""
+if merge_base=$(git merge-base HEAD "origin/${MESH_CHECK_BASE:-main}" 2>/dev/null); then
+	if git cat-file -e "$merge_base:checks/templates/inline" 2>/dev/null; then
+		inline_base=$(mktemp)
+		git show "$merge_base:checks/templates/inline" >"$inline_base"
+	fi
+else
+	echo "NOT COMPARED WITH THE TRUNK: no merge base with origin/${MESH_CHECK_BASE:-main}; checks/templates/inline is held to the list it was first written with"
+fi
+(cd checks/templates && go test -count=1 . && if [ -n "$inline_base" ]; then go run . -base "$inline_base" ../..; else go run . ../..; fi)
+# The lists that narrow the paths check may not grow unseen: the base branch's copies are what they are
+# judged against (MESH_CHECK_BASE, main when unset), read from the clone the check runs in.
+base_lists=""
+base_ref="origin/${MESH_CHECK_BASE:-main}"
+if git rev-parse --verify --quiet "$base_ref^{commit}" >/dev/null 2>&1 &&
+	git cat-file -e "$base_ref:checks/paths/known" 2>/dev/null && git cat-file -e "$base_ref:checks/paths/shared" 2>/dev/null; then
+	base_lists=$(mktemp -d)
+	git show "$base_ref:checks/paths/known" >"$base_lists/known"
+	git show "$base_ref:checks/paths/shared" >"$base_lists/shared"
+fi
+(cd checks/paths && go test -count=1 . && if [ -n "$base_lists" ]; then go run . -base "$base_lists" ../..; else go run . ../..; fi)
+
+if [ -n "${MESH_GATE:-}" ]; then
+	checked=$("$MESH_GATE" module check modules/*/module.json) || { printf '%s\n' "$checked"; exit 1; }
+	# **The count only goes down** (novox/hq ADR 0240 rule 8): the long-running resources that do not say how
+	# they are ready, as the controller counts them, against the number kept in health-undeclared. A change
+	# that raises it fails; one that lowers it writes the new number there, so it can never rise again.
+	kept=$(sed -n 's/^\([0-9][0-9]*\).*/\1/p' health-undeclared | head -n 1)
+	counted=$(printf '%s\n' "$checked" | sed -n 's/^long-running resources without health: \([0-9][0-9]*\)$/\1/p')
+	if [ -z "$counted" ]; then
+		echo "NOT COUNTED: the controller the mesh runs is older than the count of resources without health (ADR 0240 Phase B)"
+	elif [ "$counted" -gt "$kept" ]; then
+		echo "the long-running resources without health rose from $kept to $counted: declare how each new one is ready (ADR 0240 rule 8)"
+		exit 1
+	elif [ "$counted" -lt "$kept" ]; then
+		echo "the long-running resources without health fell from $kept to $counted: write $counted in health-undeclared, so the count cannot rise again"
+		exit 1
+	else
+		echo "long-running resources without health: $counted, as kept"
+	fi
+else
+	echo "NOT CHECKED: no controller was built beside this check, so the manifests were not read by one"
+fi
+
+race=""
+if command -v gcc >/dev/null 2>&1; then race="-race"; else echo "NOT RACE-CHECKED: the toolchain holds no C compiler"; fi
+
+# The modules the change reaches are the controller's planner's answer (MESH_CHECK_MODULES, hq ADR 0238):
+# a module by its name, a new one by its directory. By hand, without it, the directories the changed files
+# are in.
+if [ -n "${MESH_CHECK_MODULES:-}" ]; then
+	touched=$(printf '%s\n' "$MESH_CHECK_MODULES" | tr ',' '\n' | sed -e 's#^modules/##' -e '/\//d' | sort -u)
+else
+	touched=$(printf '%s\n' "${MESH_CHECK_CHANGED:-}" | tr ',' '\n' | sed -n 's#^modules/\([^/]*\)/.*#\1#p' | sort -u)
+fi
+# A module's dependencies: fetched, or a forge requirement taken from its clone beside the check
+# (MESH_CHECK_BESIDE); its tests run against them (checks/deps, novox/hq issue 385). The helper's own test
+# runs first.
+(cd checks/deps && go test -count=1 .)
+deps=$(mktemp -d)
+trap 'rm -rf "$deps"' EXIT
+(cd checks/deps && go build -o "$deps/deps" .)
+untestable=""
+for m in $touched; do
+	[ -d "modules/$m" ] || continue
+	if [ ! -f "modules/$m/go.mod" ]; then
+		[ -f "modules/$m/package.json" ] && echo "modules/$m is TypeScript: merge-check-typescript.sh type-checks and tests it"
+		continue
+	fi
+	if ! modfile=$(GOPRIVATE=git.novox.be "$deps/deps" -beside "${MESH_CHECK_BESIDE:-}" -work "$deps" "modules/$m"); then
+		echo "FAILED: modules/$m could not be tested — $modfile"
+		untestable="$untestable modules/$m"
+		continue
+	fi
+	[ -n "$modfile" ] && echo "modules/$m takes its forge dependencies from the clones beside the check"
+	echo "testing modules/$m"
+	unformatted=$(cd "modules/$m" && gofmt -l .)
+	if [ -n "$unformatted" ]; then
+		echo "modules/$m is not gofmt'd: $unformatted"
+		exit 1
+	fi
+	cgo=0
+	[ -n "$race" ] && cgo=1
+	# The integration tests (a file whose first line is `//go:build integration`: a test that starts a bus, a store or
+	# another process) run here and nowhere else: the unit suite stays under a second (novox/hq playbook 07).
+	(cd "modules/$m" && CGO_ENABLED=$cgo GOPRIVATE=git.novox.be go vet -tags integration ${modfile:+"-modfile=$modfile"} ./... &&
+		CGO_ENABLED=$cgo GOPRIVATE=git.novox.be go test -tags integration ${modfile:+"-modfile=$modfile"} $race -count=1 ./...)
+done
+if [ -n "$untestable" ]; then
+	echo "the check fails: the tests of$untestable could not run (novox/hq issue 385)"
+	exit 1
+fi

modules/adwaita/README.md

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

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

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

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

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

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

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

modules/adwaita/files/cursor-index.theme

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

modules/adwaita/files/env-gtk-theme

@@ -0,0 +1 @@
+Adwaita:dark

modules/adwaita/files/env-gtk2-rc-files

@@ -0,0 +1 @@
+/usr/share/themes/Adwaita-dark/gtk-2.0/gtkrc

modules/adwaita/files/env-qt-qpa-platformtheme

@@ -0,0 +1 @@
+qt6ct

modules/adwaita/files/env-qt-select

@@ -0,0 +1 @@
+6

modules/adwaita/files/env-qt-style-override

@@ -0,0 +1 @@
+Fusion

modules/adwaita/files/env-xcursor-size

@@ -0,0 +1 @@
+24

modules/adwaita/files/env-xcursor-theme

@@ -0,0 +1 @@
+Adwaita

modules/adwaita/files/gtk-settings.ini

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

modules/adwaita/files/portals.conf

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

modules/adwaita/files/qt6ct.conf

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

modules/adwaita/files/xinitrc-normal

@@ -0,0 +1,10 @@
+# The appearance (module adwaita): GSettings is where the portal reads dark or light, and the portal is
+# the only way it reaches Electron, Chromium, Firefox and flatpaks. Set at every session start to the
+# module's default; adwaita_appearance switches it for a session.
+gsettings set org.gnome.desktop.interface color-scheme 'prefer-dark' || true
+gsettings set org.gnome.desktop.interface gtk-theme 'Adwaita' || true
+gsettings set org.gnome.desktop.interface icon-theme 'Adwaita' || true
+gsettings set org.gnome.desktop.interface cursor-theme 'Adwaita' || true
+gsettings set org.gnome.desktop.interface cursor-size 24 || true
+gsettings set org.gnome.desktop.interface font-name 'Inter 11' || true
+gsettings set org.gnome.desktop.interface monospace-font-name 'JetBrainsMono Nerd Font 11' || true

modules/adwaita/files/xresources-normal

@@ -0,0 +1,3 @@
+! adwaita: the cursor, for X programs that take it from the resources.
+Xcursor.theme: Adwaita
+Xcursor.size: 24

modules/adwaita/go.mod

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

modules/adwaita/go.sum

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

modules/adwaita/internal/desktop/args.go

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

modules/adwaita/internal/desktop/copies_test.go

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

modules/adwaita/internal/desktop/run.go

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

modules/adwaita/internal/desktop/session.go

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

modules/adwaita/internal/desktop/session_test.go

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

modules/adwaita/module.json

@@ -0,0 +1,176 @@
+{
+  "module": "adwaita",
+  "version": "1",
+  "moved": true,
+  "capabilities": [
+    "package-manager"
+  ],
+  "tools": [
+    "adwaita_appearance",
+    "adwaita_cursor",
+    "adwaita_icons",
+    "adwaita_portal_check"
+  ],
+  "items": [
+    {
+      "collection": "environment",
+      "name": "gtk-theme",
+      "attributes": {
+        "kind": "variable",
+        "name": "GTK_THEME"
+      },
+      "template": "files/env-gtk-theme"
+    },
+    {
+      "collection": "environment",
+      "name": "gtk2-rc-files",
+      "attributes": {
+        "kind": "variable",
+        "name": "GTK2_RC_FILES"
+      },
+      "template": "files/env-gtk2-rc-files"
+    },
+    {
+      "collection": "environment",
+      "name": "qt-qpa-platformtheme",
+      "attributes": {
+        "kind": "variable",
+        "name": "QT_QPA_PLATFORMTHEME"
+      },
+      "template": "files/env-qt-qpa-platformtheme"
+    },
+    {
+      "collection": "environment",
+      "name": "qt-style-override",
+      "attributes": {
+        "kind": "variable",
+        "name": "QT_STYLE_OVERRIDE"
+      },
+      "template": "files/env-qt-style-override"
+    },
+    {
+      "collection": "environment",
+      "name": "qt-select",
+      "attributes": {
+        "kind": "variable",
+        "name": "QT_SELECT"
+      },
+      "template": "files/env-qt-select"
+    },
+    {
+      "collection": "environment",
+      "name": "xcursor-theme",
+      "attributes": {
+        "kind": "variable",
+        "name": "XCURSOR_THEME"
+      },
+      "template": "files/env-xcursor-theme"
+    },
+    {
+      "collection": "environment",
+      "name": "xcursor-size",
+      "attributes": {
+        "kind": "variable",
+        "name": "XCURSOR_SIZE"
+      },
+      "template": "files/env-xcursor-size"
+    },
+    {
+      "collection": "shell:xresources:normal",
+      "name": "xresources-normal",
+      "template": "files/xresources-normal"
+    },
+    {
+      "collection": "shell:xinitrc:normal",
+      "name": "xinitrc-normal",
+      "template": "files/xinitrc-normal"
+    }
+  ],
+  "resources": [
+    {
+      "id": "package-gnome-themes-extra",
+      "type": "package",
+      "package": "gnome-themes-extra"
+    },
+    {
+      "id": "package-adwaita-icon-theme",
+      "type": "package",
+      "package": "adwaita-icon-theme"
+    },
+    {
+      "id": "package-adwaita-cursors",
+      "type": "package",
+      "package": "adwaita-cursors"
+    },
+    {
+      "id": "package-qt6ct",
+      "type": "package",
+      "package": "qt6ct"
+    },
+    {
+      "id": "package-xdg-desktop-portal-gtk",
+      "type": "package",
+      "package": "xdg-desktop-portal-gtk"
+    },
+    {
+      "id": "gtk3",
+      "type": "file",
+      "path": "${machine:account-home}/.config/gtk-3.0/settings.ini",
+      "owner": "${machine:account}",
+      "mode": "0644",
+      "template": "files/gtk-settings.ini"
+    },
+    {
+      "id": "gtk4",
+      "type": "file",
+      "path": "${machine:account-home}/.config/gtk-4.0/settings.ini",
+      "owner": "${machine:account}",
+      "mode": "0644",
+      "template": "files/gtk-settings.ini"
+    },
+    {
+      "id": "qt6ct",
+      "type": "file",
+      "path": "${machine:account-home}/.config/qt6ct/qt6ct.conf",
+      "owner": "${machine:account}",
+      "mode": "0644",
+      "template": "files/qt6ct.conf"
+    },
+    {
+      "id": "portals",
+      "type": "file",
+      "path": "${machine:account-home}/.config/xdg-desktop-portal/portals.conf",
+      "owner": "${machine:account}",
+      "mode": "0644",
+      "template": "files/portals.conf"
+    },
+    {
+      "id": "cursor",
+      "type": "file",
+      "path": "${machine:account-home}/.icons/default/index.theme",
+      "owner": "${machine:account}",
+      "mode": "0644",
+      "template": "files/cursor-index.theme"
+    }
+  ],
+  "build": {
+    "artifacts": [
+      {
+        "name": "tools",
+        "kind": "bundle",
+        "language": "go",
+        "system": "arch",
+        "from": "cmd/adwaita-tools",
+        "binary": "adwaita-tools",
+        "loads": [
+          "adwaita-tools"
+        ]
+      },
+      {
+        "name": "files",
+        "kind": "archive",
+        "from": "files"
+      }
+    ]
+  }
+}

modules/anthropic-consumer/Dockerfile

@@ -1,22 +0,0 @@
-# anthropic-consumer's runtime: the tool runtime, carrying this module's compiled code.
-#
-# **Built from this module's own directory and nothing else.** The sdk and the tool runtime are in
-# the base images, published like any other artifact — which is what makes this buildable by the
-# mesh from a repository and a path (novox/hq ADR 0069) rather than only on a workstation that
-# happens to have the siblings.
-#
-# Two bases, named rather than pinned (novox/hq issue 044): the image this is COMPILED in and the
-# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
-ARG BUILD_BASE
-ARG RUNTIME_BASE
-
-FROM ${BUILD_BASE} AS build
-WORKDIR /app/modules/anthropic-consumer
-COPY . .
-RUN node /app/node_modules/typescript/bin/tsc apply/index.ts usage/index.ts \
-      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
-
-FROM ${RUNTIME_BASE}
-COPY --from=build /app/modules/anthropic-consumer/dist /app/modules/anthropic-consumer/dist
-# No serve-time entrypoints: every container of this module names its command (`run` on a
-# schedule), so nothing here serves — deliberately no MESH_TOOL_MODULES.

modules/anthropic-consumer/apply/index.ts

@@ -1,75 +0,0 @@
-// The consumer's scheduled run: take the ACCESS token the mesh delivered and write it where the
-// Claude CLI reads it, access-token-only (novox/hq ADR 0050). The refresh token is never here to
-// strip — the manager holds it, and a holder's delivery has only ever been the access token.
-//
-// What the host delivers, per the manifest:
-//   secrets.model-access -> a file holding the sealed-then-unsealed ACCESS token (the host opened it
-//                           with this node's private key; this process reads plaintext).
-//   binds.model-access   -> a JSON file of the non-secret facts the licence serves (which licence,
-//                           model, and — when the control plane carries them — grant expiry/scopes).
-//
-// Runs as `mesh-tools run` (no broker) on a schedule, so it is idempotent: same token in, same file
-// out.
-
-import { readFileSync } from "node:fs";
-
-import { deliver, type DeliveredGrant } from "../credentials.js";
-import { readAccountUuid, check } from "../identity.js";
-
-function required(name: string): string {
-  const v = process.env[name];
-  if (!v) throw new Error(`${name} is not set — the consumer runtime was deployed without it`);
-  return v;
-}
-
-/** Read optional non-secret grant metadata (expiry, scopes, subscription) from the bound facts file. */
-function readBoundMeta(path: string | undefined): Partial<DeliveredGrant> {
-  if (!path) return {};
-  try {
-    const raw = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
-    return {
-      expiresAt: typeof raw.expiresAt === "number" ? raw.expiresAt : null,
-      refreshTokenExpiresAt: typeof raw.refreshTokenExpiresAt === "number" ? raw.refreshTokenExpiresAt : null,
-      scopes: Array.isArray(raw.scopes) ? (raw.scopes as string[]) : null,
-      subscriptionType: typeof raw.subscriptionType === "string" ? raw.subscriptionType : null,
-    };
-  } catch {
-    return {};
-  }
-}
-
-function main(): void {
-  const accessToken = readFileSync(required("MESH_MODEL_ACCESS_SECRET_FILE"), "utf8").trim();
-  if (!accessToken) {
-    // Nothing was delivered — which reads exactly like a credential that never arrived, so it is
-    // said rather than written as an empty file the CLI would take for a login it should not do.
-    throw new Error("[anthropic-consumer] the delivered access token is empty; nothing was written");
-  }
-
-  const meta = readBoundMeta(process.env.MESH_MODEL_ACCESS_BIND_FILE);
-  const grant: DeliveredGrant = { accessToken, ...meta };
-
-  const target = process.env.MESH_CLAUDE_CREDENTIALS_FILE ?? `${homedir()}/.claude/.credentials.json`;
-  deliver(target, grant);
-  console.error(`[anthropic-consumer] wrote an access-token-only credential to ${target}`);
-
-  // The mis-binding guard, best-effort and fail-closed. The expected account uuid is not yet plumbed
-  // (identity.ts TODO), so this reports what it can see rather than acting on it — it never delivers
-  // to a wrong account because it never learns one to deliver to.
-  const identityFile = process.env.MESH_CLAUDE_IDENTITY_FILE ?? `${homedir()}/.claude.json`;
-  const found = readAccountUuid(identityFile);
-  const expected = process.env.MESH_MODEL_ACCESS_ACCOUNT_UUID ?? null;
-  const verdict = check(found, expected);
-  if (verdict.state === "wrong-account") {
-    throw new Error(
-      `[anthropic-consumer] the CLI is logged in as ${verdict.found}, not the licensed ${verdict.expected}; refusing`,
-    );
-  }
-  console.error(`[anthropic-consumer] identity check: ${verdict.state}`);
-}
-
-function homedir(): string {
-  return process.env.HOME ?? "/root";
-}
-
-main();

modules/anthropic-consumer/credentials.ts

@@ -1,82 +0,0 @@
-// Writing the access token where the Claude CLI reads it — the consumer half of model-access
-// (novox/hq ADR 0050). A node holds an ACCESS token and nothing else: it cannot rotate, so it is
-// never given a refresh token, and this enforces that on every write.
-//
-// The file shape and the strip are ported byte-exact from the mature implementation (see the port
-// map): `~/.claude/.credentials.json` → `{ claudeAiOauth: { accessToken, expiresAt,
-// refreshTokenExpiresAt?, scopes?, subscriptionType? } }`, and the refresh token is deleted, not
-// merely omitted, so a full grant left by an interactive login is stripped back to access-only.
-
-import { readFileSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
-import { dirname } from "node:path";
-
-/** The access-token-only grant the mesh delivered — what the manager submitted, minus the refresh. */
-export interface DeliveredGrant {
-  readonly accessToken: string;
-  readonly expiresAt?: number | null;
-  readonly refreshTokenExpiresAt?: number | null;
-  readonly scopes?: string[] | null;
-  readonly subscriptionType?: string | null;
-}
-
-interface ClaudeOauth {
-  accessToken?: string;
-  expiresAt?: number;
-  refreshTokenExpiresAt?: number;
-  scopes?: string[];
-  subscriptionType?: string;
-  refreshToken?: string;
-}
-
-interface Credentials {
-  claudeAiOauth?: ClaudeOauth;
-  [key: string]: unknown;
-}
-
-/** Read the existing credentials file, or an empty object if there is none or it is unreadable. */
-function readLocal(path: string): Credentials {
-  try {
-    return JSON.parse(readFileSync(path, "utf8")) as Credentials;
-  } catch {
-    return {};
-  }
-}
-
-/**
- * Overlay the delivered grant onto whatever is on disk, then STRIP the refresh token — the node
- * carve-out. Returns the object to write, so the strip is testable without touching a file.
- */
-export function applyGrant(local: Credentials, grant: DeliveredGrant): Credentials {
-  const oauth = local.claudeAiOauth ?? {};
-  const next: Credentials = {
-    ...local,
-    claudeAiOauth: {
-      ...oauth,
-      accessToken: grant.accessToken,
-      ...(grant.expiresAt != null ? { expiresAt: grant.expiresAt } : {}),
-      ...(grant.refreshTokenExpiresAt != null
-        ? { refreshTokenExpiresAt: grant.refreshTokenExpiresAt }
-        : {}),
-      ...(grant.scopes ? { scopes: grant.scopes } : {}),
-      ...(grant.subscriptionType ? { subscriptionType: grant.subscriptionType } : {}),
-    },
-  };
-  // A node NEVER holds a refresh token: delete it, so a full grant on disk is reduced to access-only.
-  delete next.claudeAiOauth!.refreshToken;
-  return next;
-}
-
-/** Atomic write-then-rename at 0600 — a partial credentials file must never be read as a whole one. */
-export function writeCredentials(path: string, creds: Credentials): void {
-  mkdirSync(dirname(path), { recursive: true });
-  const tmp = `${path}.tmp`;
-  writeFileSync(tmp, JSON.stringify(creds, null, 2), { mode: 0o600 });
-  renameSync(tmp, path);
-}
-
-/** Read, overlay, strip, write — the whole consumer credential update, in one call. */
-export function deliver(path: string, grant: DeliveredGrant): Credentials {
-  const next = applyGrant(readLocal(path), grant);
-  writeCredentials(path, next);
-  return next;
-}

modules/anthropic-consumer/identity.ts

@@ -1,49 +0,0 @@
-// The mis-binding guard (novox/hq ADR 0050, port map §identity). Account identity is NOT in the
-// token or any API — it lives in a sibling CLI state file, `~/.claude.json` →
-// `oauthAccount.accountUuid`. The guard compares the account the CLI is actually logged in as to the
-// account the licence was recorded against, and FAILS CLOSED: an absent file or an unrecorded licence
-// account refuses rather than guesses, because delivering an access token to the wrong account is the
-// exact fault this exists to catch.
-//
-// **Partial first cut, FLAGGED.** Reading the sibling file is implemented; the licence's recorded
-// account uuid is not yet plumbed from the control plane to the consumer (the bound `model.json` does
-// not carry it today). So `check` returns `licence-not-adopted` when no expected uuid is supplied,
-// which is the fail-closed answer, and the wiring of the expected uuid is a TODO below.
-
-import { readFileSync } from "node:fs";
-
-export type IdentityVerdict =
-  | { state: "verified"; accountUuid: string }
-  | { state: "no-identity-file" }
-  | { state: "licence-not-adopted" }
-  | { state: "wrong-account"; found: string; expected: string };
-
-interface ClaudeJson {
-  oauthAccount?: { accountUuid?: string; emailAddress?: string; organizationUuid?: string };
-}
-
-/** Read `oauthAccount.accountUuid` from `~/.claude.json`, or null if the file or field is absent. */
-export function readAccountUuid(path: string): string | null {
-  try {
-    const raw = JSON.parse(readFileSync(path, "utf8")) as ClaudeJson;
-    return raw.oauthAccount?.accountUuid ?? null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Compare the CLI's logged-in account to the one the licence was recorded against. Pure over its
- * inputs so the fail-closed logic is tested without a filesystem.
- *
- * TODO(novox/hq ADR 0050, Phase C): plumb `expected` — the licence's recorded account uuid — from the
- * control plane into the consumer's bound `model.json`, then adopt-on-first-sight or refuse per the
- * port map's five states. Until then only the two safe verdicts are reachable: verified when an
- * expected uuid is provided and matches, refuse otherwise.
- */
-export function check(found: string | null, expected: string | null): IdentityVerdict {
-  if (found === null) return { state: "no-identity-file" };
-  if (!expected) return { state: "licence-not-adopted" };
-  if (found === expected) return { state: "verified", accountUuid: found };
-  return { state: "wrong-account", found, expected };
-}

modules/anthropic-consumer/module.json

@@ -1,113 +0,0 @@
-{
-  "module": "anthropic-consumer",
-  "version": "1",
-  "slug": "claude",
-  "capabilities": [
-    "container-runtime"
-  ],
-  "requires": [
-    "model-access"
-  ],
-  "binds": {
-    "model-access": "/var/lib/anthropic-consumer/model.json"
-  },
-  "secrets": {
-    "model-access": "/var/lib/anthropic-consumer/access-token"
-  },
-  "own-secrets": {
-    "broker": "/var/lib/mesh/anthropic-consumer/broker"
-  },
-  "emits": [
-    "usage.session"
-  ],
-  "resources": [
-    {
-      "id": "mesh-state",
-      "type": "directory",
-      "path": "/var/lib/mesh/anthropic-consumer",
-      "mode": "0700"
-    },
-    {
-      "id": "state",
-      "type": "directory",
-      "path": "/var/lib/anthropic-consumer",
-      "mode": "0700"
-    },
-    {
-      "id": "claude-home",
-      "type": "directory",
-      "path": "/var/lib/anthropic-consumer/claude",
-      "mode": "0700"
-    },
-    {
-      "id": "out",
-      "type": "directory",
-      "path": "/var/lib/anthropic-consumer/out",
-      "mode": "0700"
-    },
-    {
-      "id": "apply",
-      "type": "container",
-      "name": "mesh-anthropic-consumer-apply",
-      "network": "host",
-      "schedule": "*/5 * * * *",
-      "args": [
-        "run",
-        "/app/modules/anthropic-consumer/dist/apply/index.js"
-      ],
-      "volumes": [
-        "/var/lib/anthropic-consumer:/run/state"
-      ],
-      "env": {
-        "MESH_MODEL_ACCESS_SECRET_FILE": "/run/state/access-token",
-        "MESH_MODEL_ACCESS_BIND_FILE": "/run/state/model.json",
-        "MESH_CLAUDE_CREDENTIALS_FILE": "/run/state/claude/.credentials.json",
-        "MESH_CLAUDE_IDENTITY_FILE": "/run/state/claude/.claude.json"
-      },
-      "artifact": "runtime"
-    },
-    {
-      "id": "usage",
-      "type": "container",
-      "name": "mesh-anthropic-consumer-usage",
-      "network": "host",
-      "schedule": "*/5 * * * *",
-      "args": [
-        "run",
-        "/app/modules/anthropic-consumer/dist/usage/index.js"
-      ],
-      "volumes": [
-        "/var/lib/mesh/anthropic-consumer/broker:/run/secrets/broker:ro",
-        "/var/lib/anthropic-consumer:/run/state"
-      ],
-      "env": {
-        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_CLAUDE_PROJECTS_DIR": "/run/state/claude/projects",
-        "MESH_ANTHROPIC_USAGE_OUT": "/run/state/out/session-usage.json",
-        "MESH_TOOLS_MAIN": "/app/dist/main.js"
-      },
-      "artifact": "runtime"
-    }
-  ],
-  "build": {
-    "on": [
-      {
-        "arg": "BUILD_BASE",
-        "module": "mesh-tools",
-        "artifact": "build"
-      },
-      {
-        "arg": "RUNTIME_BASE",
-        "module": "mesh-tools",
-        "artifact": "runtime"
-      }
-    ],
-    "artifacts": [
-      {
-        "name": "runtime",
-        "kind": "image",
-        "from": "Dockerfile"
-      }
-    ]
-  }
-}

modules/anthropic-consumer/package.json

@@ -1,14 +0,0 @@
-{
-  "name": "@novox/module-anthropic-consumer",
-  "version": "0.1.0",
-  "description": "anthropic-consumer — the consumer side of model-access (ADR 0050): writes the delivered access token to ~/.claude/.credentials.json (access-token-only) and reports session-grain usage from the CLI transcripts (ADR 0054).",
-  "type": "module",
-  "private": true,
-  "dependencies": {
-    "@novox/mesh-sdk": "^0.1.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.6.0"
-  }
-}

modules/anthropic-consumer/test/credentials.test.ts

@@ -1,32 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import { applyGrant, deliver } from "../credentials.ts";
-
-test("applyGrant strips the refresh token a full grant on disk left behind", () => {
-  const local = { claudeAiOauth: { accessToken: "at-old", refreshToken: "rt-must-not-survive" } };
-  const next = applyGrant(local, { accessToken: "at-new", expiresAt: 123 });
-  assert.equal(next.claudeAiOauth!.accessToken, "at-new");
-  assert.equal(next.claudeAiOauth!.expiresAt, 123);
-  assert.ok(!("refreshToken" in next.claudeAiOauth!), "a node held onto a refresh token");
-});
-
-test("deliver writes the port-map shape, access-token-only, and never a refresh token", () => {
-  const dir = mkdtempSync(join(tmpdir(), "anthropic-consumer-"));
-  const path = join(dir, ".credentials.json");
-  // A prior interactive login left a full grant on disk.
-  writeFileSync(path, JSON.stringify({ claudeAiOauth: { accessToken: "at-old", refreshToken: "rt-login" } }));
-
-  deliver(path, { accessToken: "at-delivered", expiresAt: 999, subscriptionType: "max" });
-
-  const raw = readFileSync(path, "utf8");
-  const creds = JSON.parse(raw);
-  assert.equal(creds.claudeAiOauth.accessToken, "at-delivered");
-  assert.equal(creds.claudeAiOauth.expiresAt, 999);
-  assert.equal(creds.claudeAiOauth.subscriptionType, "max");
-  assert.doesNotMatch(raw, /rt-login/, "the refresh token is still on disk");
-  assert.ok(!("refreshToken" in creds.claudeAiOauth));
-});

modules/anthropic-consumer/test/transcript.test.ts

@@ -1,48 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-
-import { foldTranscript } from "../transcript.ts";
-
-// A captured-shape transcript: two assistant turns and a user line, exactly the fields the port map
-// names. Not imagined — the field names match the mature implementation's parse.
-const TRANSCRIPT = [
-  JSON.stringify({ type: "user", timestamp: "2026-01-01T00:00:00Z", cwd: "/work/app", gitBranch: "main" }),
-  JSON.stringify({
-    type: "assistant",
-    timestamp: "2026-01-01T00:00:01Z",
-    costUSD: 0.01,
-    message: {
-      model: "claude-opus-4-8",
-      usage: { input_tokens: 100, cache_creation_input_tokens: 20, cache_read_input_tokens: 5, output_tokens: 40 },
-    },
-  }),
-  JSON.stringify({
-    type: "assistant",
-    timestamp: "2026-01-01T00:00:02Z",
-    costUSD: 0.02,
-    message: { model: "claude-opus-4-8", usage: { input_tokens: 200, output_tokens: 60 } },
-  }),
-  "", // a half-written trailing line is ordinary and must not be fatal.
-].join("\n");
-
-test("a transcript sums per-session token counts, cost, and metadata", () => {
-  const s = foldTranscript("session-abc", TRANSCRIPT);
-  assert.equal(s.sessionId, "session-abc");
-  assert.equal(s.turns, 2);
-  assert.equal(s.inputTokens, 300);
-  assert.equal(s.cacheCreationTokens, 20);
-  assert.equal(s.cacheReadTokens, 5);
-  assert.equal(s.outputTokens, 100);
-  assert.equal(Math.round(s.costUSD * 100) / 100, 0.03);
-  assert.equal(s.model, "claude-opus-4-8");
-  assert.equal(s.gitBranch, "main");
-  assert.equal(s.cwd, "/work/app");
-  assert.equal(s.startedAt, "2026-01-01T00:00:00Z");
-  assert.equal(s.lastActive, "2026-01-01T00:00:02Z");
-});
-
-test("a malformed line is skipped, not fatal", () => {
-  const s = foldTranscript("s", 'not json\n{"type":"assistant","message":{"usage":{"output_tokens":7}}}');
-  assert.equal(s.outputTokens, 7);
-  assert.equal(s.turns, 1);
-});

modules/anthropic-consumer/transcript.ts

@@ -1,113 +0,0 @@
-// Session-grain usage from the CLI's own transcripts (novox/hq ADR 0054). The mature implementation
-// reads `~/.claude/projects/<projDir>/<sessionId>.jsonl` and sums the token counts each assistant
-// message reports; this ports the token extraction and DROPS the per-message account-attribution
-// timeline — the nox (node,module) session has a fixed licence binding (port map "don't-map" #3), so
-// there is nothing to attribute per message.
-//
-// The fields are ported from the port map: assistant lines carry
-// `message.usage.{input_tokens,cache_creation_input_tokens,cache_read_input_tokens,output_tokens}`,
-// `costUSD`, `message.model`, `timestamp`; user lines carry `cwd`, `gitBranch`.
-
-import { createInterface } from "node:readline";
-import { createReadStream } from "node:fs";
-
-/** One session's totals — the session-grain usage row ADR 0054 fixes. */
-export interface SessionUsage {
-  sessionId: string;
-  model: string | null;
-  gitBranch: string | null;
-  cwd: string | null;
-  turns: number;
-  inputTokens: number;
-  cacheCreationTokens: number;
-  cacheReadTokens: number;
-  outputTokens: number;
-  costUSD: number;
-  startedAt: string | null;
-  lastActive: string | null;
-}
-
-interface Line {
-  type?: string;
-  timestamp?: string;
-  cwd?: string;
-  gitBranch?: string;
-  costUSD?: number;
-  message?: {
-    model?: string;
-    usage?: {
-      input_tokens?: number;
-      cache_creation_input_tokens?: number;
-      cache_read_input_tokens?: number;
-      output_tokens?: number;
-    };
-  };
-}
-
-function empty(sessionId: string): SessionUsage {
-  return {
-    sessionId,
-    model: null,
-    gitBranch: null,
-    cwd: null,
-    turns: 0,
-    inputTokens: 0,
-    cacheCreationTokens: 0,
-    cacheReadTokens: 0,
-    outputTokens: 0,
-    costUSD: 0,
-    startedAt: null,
-    lastActive: null,
-  };
-}
-
-/** Fold one transcript line into a session's running totals. Pure, so it is tested on fixtures. */
-export function foldLine(acc: SessionUsage, raw: string): SessionUsage {
-  const line = parse(raw);
-  if (!line) return acc;
-
-  if (line.timestamp) {
-    if (!acc.startedAt || line.timestamp < acc.startedAt) acc.startedAt = line.timestamp;
-    if (!acc.lastActive || line.timestamp > acc.lastActive) acc.lastActive = line.timestamp;
-  }
-  if (line.type === "user") {
-    if (line.cwd) acc.cwd = line.cwd;
-    if (line.gitBranch) acc.gitBranch = line.gitBranch;
-  }
-  if (line.type === "assistant") {
-    acc.turns += 1;
-    const u = line.message?.usage ?? {};
-    acc.inputTokens += u.input_tokens ?? 0;
-    acc.cacheCreationTokens += u.cache_creation_input_tokens ?? 0;
-    acc.cacheReadTokens += u.cache_read_input_tokens ?? 0;
-    acc.outputTokens += u.output_tokens ?? 0;
-    acc.costUSD += line.costUSD ?? 0;
-    if (!acc.model && line.message?.model) acc.model = line.message.model;
-  }
-  return acc;
-}
-
-function parse(raw: string): Line | null {
-  const trimmed = raw.trim();
-  if (!trimmed) return null;
-  try {
-    return JSON.parse(trimmed) as Line;
-  } catch {
-    // A malformed line is skipped, never fatal: a transcript is an append-only log the CLI owns, and
-    // a half-written last line is ordinary.
-    return null;
-  }
-}
-
-/** Sum a whole transcript string into one session's usage — the tested core of the streaming read. */
-export function foldTranscript(sessionId: string, text: string): SessionUsage {
-  return text.split("\n").reduce(foldLine, empty(sessionId));
-}
-
-/** Stream one `<sessionId>.jsonl` file line by line, so a large transcript never loads whole. */
-export async function readSessionFile(path: string, sessionId: string): Promise<SessionUsage> {
-  const acc = empty(sessionId);
-  const rl = createInterface({ input: createReadStream(path), crlfDelay: Infinity });
-  for await (const line of rl) foldLine(acc, line);
-  return acc;
-}

modules/anthropic-consumer/tsconfig.json

@@ -1,18 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "noEmit": true
-  },
-  "include": [
-    "credentials.ts",
-    "transcript.ts",
-    "identity.ts",
-    "apply/index.ts",
-    "usage/index.ts"
-  ]
-}

modules/anthropic-consumer/usage/index.ts

@@ -1,137 +0,0 @@
-// Session-grain usage emission (novox/hq ADR 0054). On a schedule, read every transcript under
-// `~/.claude/projects/*/<sessionId>.jsonl`, sum its tokens, and emit one session-grain usage event
-// per session. The consumer IS the (node,module) session's fixed binding, so no per-message account
-// attribution is done — just the totals (port map "don't-map" #3).
-//
-// Runs as `mesh-tools run` (no broker), so events are emitted best-effort via the sibling mesh-tools
-// `emit` primitive; the totals are also written to a file so the reading is observable without one.
-
-import { readdirSync, statSync, readFileSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
-import { join, dirname } from "node:path";
-
-import { readSessionFile, type SessionUsage } from "../transcript.js";
-
-/** The vendor-neutral usage row ADR 0054 fixes — the shape the model-usage store upserts. Kept local
- *  to the producer (the normalisation lives in the adapter), so nothing here couples to the SDK. */
-interface UsageRow {
-  licence: string;
-  consumer: string;
-  period: string;
-  metric: string;
-  value: number;
-}
-
-/** The licence this session's usage is charged to. The model-access binding names it; failing that,
- *  the deployed env; failing that, "unknown" — a reading is never dropped for want of a licence. */
-function boundLicence(): string {
-  const bindFile = process.env.MESH_MODEL_ACCESS_BIND_FILE;
-  if (bindFile) {
-    try {
-      const raw = JSON.parse(readFileSync(bindFile, "utf8")) as { licence?: unknown };
-      if (typeof raw.licence === "string" && raw.licence) return raw.licence;
-    } catch {
-      // A missing or unreadable bind file is not fatal — fall through to the env, then to "unknown".
-    }
-  }
-  return process.env.MESH_ANTHROPIC_LICENCE || "unknown";
-}
-
-/** Normalise one session reading into ADR 0054 rows: one row per metric, a row omitted when its
- *  number is not finite. `consumer` is node/module/session — the session grain. */
-function sessionRows(licence: string, node: string, module: string, r: SessionUsage): UsageRow[] {
-  const consumer = `${node}/${module}/${r.sessionId}`;
-  const rows: UsageRow[] = [];
-  const add = (metric: string, value: number): void => {
-    if (Number.isFinite(value)) rows.push({ licence, consumer, period: "session", metric, value });
-  };
-  add("input_tokens", r.inputTokens);
-  add("output_tokens", r.outputTokens);
-  add("cache_creation_tokens", r.cacheCreationTokens);
-  add("cache_read_tokens", r.cacheReadTokens);
-  add("cost_usd", r.costUSD);
-  return rows;
-}
-
-function projectsDir(): string {
-  return process.env.MESH_CLAUDE_PROJECTS_DIR ?? `${process.env.HOME ?? "/root"}/.claude/projects`;
-}
-
-/** Every `<sessionId>.jsonl` under the projects tree, with the project directory it sits in. */
-function transcripts(root: string): { path: string; sessionId: string }[] {
-  const found: { path: string; sessionId: string }[] = [];
-  let projects: string[];
-  try {
-    projects = readdirSync(root);
-  } catch {
-    return found; // no projects yet is not a failure — there is simply nothing to report.
-  }
-  for (const proj of projects) {
-    const dir = join(root, proj);
-    let entries: string[];
-    try {
-      if (!statSync(dir).isDirectory()) continue;
-      entries = readdirSync(dir);
-    } catch {
-      continue;
-    }
-    for (const file of entries) {
-      if (!file.endsWith(".jsonl")) continue;
-      found.push({ path: join(dir, file), sessionId: file.replace(/\.jsonl$/, "") });
-    }
-  }
-  return found;
-}
-
-async function main(): Promise<void> {
-  const module = process.env.MESH_MODULE ?? "anthropic-consumer";
-  const node = process.env.MESH_NODE ?? "unknown";
-
-  const readings: SessionUsage[] = [];
-  for (const t of transcripts(projectsDir())) {
-    try {
-      readings.push(await readSessionFile(t.path, t.sessionId));
-    } catch (err) {
-      console.error(`[anthropic-consumer] could not read ${t.path}: ${err}`);
-    }
-  }
-
-  // Emit ADR-0054 rows, not a vendor-shaped body: the consumer of module.*.usage.* is the
-  // vendor-neutral model-usage store, so the session→row normalisation is done HERE. The full
-  // SessionUsage rides as `raw`, so model, branch, cwd and timestamps are not lost.
-  const licence = boundLicence();
-  for (const r of readings) {
-    await emitUsage({ rows: sessionRows(licence, node, module, r), raw: r });
-  }
-
-  if (process.env.MESH_ANTHROPIC_USAGE_OUT) {
-    atomicWrite(process.env.MESH_ANTHROPIC_USAGE_OUT, JSON.stringify(readings, null, 2));
-  }
-  console.error(`[anthropic-consumer] reported ${readings.length} session(s)`);
-}
-
-function atomicWrite(path: string, content: string): void {
-  mkdirSync(dirname(path), { recursive: true });
-  const tmp = `${path}.tmp`;
-  writeFileSync(tmp, content, { mode: 0o600 });
-  renameSync(tmp, path);
-}
-
-/** Emit best-effort via the sibling mesh-tools `emit`, which wires a broker a run step has none. */
-async function emitUsage(body: Record<string, unknown>): Promise<void> {
-  const main = process.env.MESH_TOOLS_MAIN ?? "/app/dist/main.js";
-  const { spawn } = await import("node:child_process");
-  await new Promise<void>((resolve) => {
-    const child = spawn(
-      process.execPath,
-      [main, "emit", "usage.session", JSON.stringify(body)],
-      { stdio: "inherit" },
-    );
-    child.on("exit", () => resolve());
-    child.on("error", (err) => {
-      console.error(`[anthropic-consumer] could not emit usage: ${err}`);
-      resolve();
-    });
-  });
-}
-
-await main();

modules/anthropic-manager/adopt/index.ts

@@ -1,35 +0,0 @@
-// Adoption: the ONE time an operator's refresh token enters the mesh, and it enters already sealed.
-//
-// The refresh token is read here, on the MANAGER NODE, sealed to that node's PUBLIC sealing key, and
-// only the sealed box leaves this process (novox/hq ADR 0050). The control plane stores that box via
-// `licence set-grant` without ever seeing the refresh token in the clear — the same bound every
-// delivery keeps. This is the counterpart to `refresh/index.js`: adoption seals the first box, refresh
-// re-seals a rotated one; both use the very anonymous box (`crypto_box_seal`) the mesh seals every
-// credential with, so the HOST unseals the stored box to mount the cleartext back — this module is
-// never given a private key and opens nothing.
-//
-//   MESH_ANTHROPIC_ADOPT_TOKEN_FILE  the operator's refresh token, read once and never written out
-//   MESH_MODEL_ACCESS_BIND_FILE      the manager holder's bound facts, carrying manager_public_key
-//   MESH_ANTHROPIC_GRANT_OUT         where the sealed box is written, for `licence set-grant`
-
-import { readFileSync } from "node:fs";
-
-import { seal } from "../sealedbox.js";
-import { managerPublicKey, writeSealedGrant } from "../grantfile.js";
-
-function required(name: string): string {
-  const v = process.env[name];
-  if (!v) throw new Error(`${name} is not set — adoption needs it`);
-  return v;
-}
-
-const refreshToken = readFileSync(required("MESH_ANTHROPIC_ADOPT_TOKEN_FILE"), "utf8").trim();
-if (!refreshToken) throw new Error("[anthropic-manager] there is no refresh token to adopt");
-
-// The node's PUBLIC sealing key, delivered by the mesh in the manager holder's bound facts. Public,
-// so it is safe to hand a module; the private half stays with the host, which is what opens the box.
-const nodePub = managerPublicKey(required("MESH_MODEL_ACCESS_BIND_FILE"));
-
-const sealed = seal(new Uint8Array(Buffer.from(refreshToken, "utf8")), nodePub);
-writeSealedGrant(required("MESH_ANTHROPIC_GRANT_OUT"), sealed, nodePub);
-console.error("[anthropic-manager] sealed the refresh token to this node's key; only the host opens it");

modules/anthropic-manager/client.ts

@@ -1,135 +0,0 @@
-// The only file that talks to Anthropic — the vendor half of the refreshable-grant adapter
-// (novox/hq ADR 0050). Isolated exactly as cloudflare-dns isolates its registrar call, so the
-// vendor is swappable and the one place a token endpoint is reached is auditable.
-//
-// Two endpoints, and they are different hosts (port-map "don't-map" #1): the TOKEN host mints a new
-// access token from the refresh token; the USAGE host reports utilisation against an access token.
-
-/** The token endpoint, overridable so the lab can point the whole flow at a stub without a vendor. */
-export function tokenEndpoint(env = process.env): string {
-  return env.MESH_ANTHROPIC_TOKEN_ENDPOINT ?? "https://platform.claude.com/v1/oauth/token";
-}
-
-/** The usage endpoint, likewise overridable for the lab. */
-export function usageEndpoint(env = process.env): string {
-  return env.MESH_ANTHROPIC_USAGE_ENDPOINT ?? "https://api.anthropic.com/api/oauth/usage";
-}
-
-// The OAuth client id is a hard-won constant, ported byte-exact from the mature implementation: a
-// metadata URL in its place yields 400. It is not a secret (it identifies the public Claude Code
-// client), so it lives in code.
-const CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
-
-/** The vendor's token response, snake_case as the wire has it. */
-export interface RefreshedGrant {
-  readonly access_token?: string;
-  readonly refresh_token?: string;
-  readonly expires_in?: number;
-  readonly refresh_token_expires_in?: number;
-  readonly scopes?: string[];
-  readonly subscription_type?: string;
-}
-
-/**
- * Exchange a refresh token for a fresh grant. Returns null on any non-ok response, surfacing the
- * OAuth error body (invalid_grant/invalid_client/…) — the difference between "the token is dead" and
- * "the endpoint was unreachable", which a bare status hides.
- */
-export async function refreshGrant(
-  refreshToken: string,
-  env = process.env,
-): Promise<RefreshedGrant | null> {
-  const resp = await fetch(tokenEndpoint(env), {
-    method: "POST",
-    headers: { "content-type": "application/x-www-form-urlencoded" },
-    body: new URLSearchParams({
-      grant_type: "refresh_token",
-      refresh_token: refreshToken,
-      client_id: CLIENT_ID,
-    }),
-  });
-  if (!resp.ok) {
-    const body = await resp.text().catch(() => "<unreadable>");
-    console.error(
-      `[anthropic-manager] token refresh failed: ${resp.status} ${resp.statusText} — ${body.slice(0, 400)}`,
-    );
-    return null;
-  }
-  return (await resp.json()) as RefreshedGrant;
-}
-
-/** The vendor's usage response — utilisation percentages against several windows. */
-export interface UsageLimits {
-  readonly five_hour?: { utilization: number; resets_at?: string };
-  readonly seven_day?: { utilization: number; resets_at?: string };
-  readonly seven_day_sonnet?: { utilization: number; resets_at?: string };
-  readonly seven_day_opus?: { utilization: number; resets_at?: string };
-  readonly extra_usage?: { utilization: number };
-  readonly [key: string]: unknown;
-}
-
-/**
- * Read utilisation for an access token. Never refreshes here (a 401 is just reported): a second
- * refresh source racing the first is the fault the mature implementation warns against.
- */
-export async function readUsage(accessToken: string, env = process.env): Promise<UsageLimits | null> {
-  const resp = await fetch(usageEndpoint(env), {
-    headers: { authorization: `Bearer ${accessToken}` },
-  });
-  if (!resp.ok) {
-    const body = await resp.text().catch(() => "");
-    console.error(`[anthropic-manager] usage endpoint returned ${resp.status}: ${body.slice(0, 200)}`);
-    return null;
-  }
-  return (await resp.json()) as UsageLimits;
-}
-
-/** The licence-grain reading ADR 0054 fixes, flattened from the vendor's windows. */
-export interface UsageReading {
-  readonly sessionPct: number | null;
-  readonly sessionResetsAt: string | null;
-  readonly weeklyPct: number | null;
-  readonly sonnetPct: number | null;
-  readonly extraPct: number | null;
-  readonly raw: UsageLimits;
-}
-
-export function flattenUsage(u: UsageLimits): UsageReading {
-  return {
-    sessionPct: u.five_hour?.utilization ?? null,
-    sessionResetsAt: u.five_hour?.resets_at ?? null,
-    weeklyPct: u.seven_day?.utilization ?? null,
-    sonnetPct: u.seven_day_sonnet?.utilization ?? null,
-    extraPct: u.extra_usage?.utilization ?? null,
-    raw: u,
-  };
-}
-
-/** The access-token-only grant a holder is delivered — the port-map credential-file shape's fields. */
-export interface AccessGrant {
-  readonly accessToken: string;
-  readonly expiresAt: number | null;
-  readonly refreshTokenExpiresAt: number | null;
-  readonly scopes: string[] | null;
-  readonly subscriptionType: string | null;
-}
-
-/**
- * Turn a vendor refresh into what the manager submits: the access-token-only grant for holders, and
- * the rotated refresh token if the vendor sent one. Never clobbers a good grant from an empty
- * response — no access_token means the caller keeps what it had.
- */
-export function grantFromRefresh(r: RefreshedGrant, nowMs: number): { access: AccessGrant; rotatedRefresh: string | null } | null {
-  if (!r.access_token) return null;
-  return {
-    access: {
-      accessToken: r.access_token,
-      expiresAt: typeof r.expires_in === "number" ? nowMs + r.expires_in * 1000 : null,
-      refreshTokenExpiresAt:
-        typeof r.refresh_token_expires_in === "number" ? nowMs + r.refresh_token_expires_in * 1000 : null,
-      scopes: r.scopes ?? null,
-      subscriptionType: r.subscription_type ?? null,
-    },
-    rotatedRefresh: r.refresh_token ?? null,
-  };
-}

modules/anthropic-manager/grantfile.ts

@@ -1,32 +0,0 @@
-// Reading the manager node's PUBLIC sealing key out of the bound facts the mesh delivers, and
-// writing a sealed refresh token in the wire shape mesh-controller reads.
-//
-// **The public key is delivered, not derived.** The manager module holds no node key of its own
-// (novox/hq ADR 0050) — it is deliberately never given one. To seal a refresh token to this node it
-// needs the node's PUBLIC sealing key, and mesh-controller puts that in the manager holder's bound facts
-// (`serves.manager_public_key`), safe to disclose because it is public. Both adoption and every
-// rotation read it from there.
-
-import { readFileSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
-import { dirname } from "node:path";
-
-/** The manager node's public sealing key, from the bound facts file the mesh delivers. */
-export function managerPublicKey(boundFile: string): string {
-  const raw = JSON.parse(readFileSync(boundFile, "utf8")) as { serves?: Record<string, unknown> };
-  const key = raw.serves?.["manager_public_key"];
-  if (typeof key !== "string" || key === "") {
-    throw new Error(
-      "the bound facts carry no manager_public_key — this node is not the licence's manager, or " +
-        "the manager holder has not been delivered yet",
-    );
-  }
-  return key;
-}
-
-/** Write a sealed refresh token in the {sealed, manager_key} wire shape mesh-controller reads. */
-export function writeSealedGrant(path: string, sealed: string, managerKey: string): void {
-  mkdirSync(dirname(path), { recursive: true });
-  const tmp = `${path}.tmp`;
-  writeFileSync(tmp, JSON.stringify({ sealed, manager_key: managerKey }), { mode: 0o600 });
-  renameSync(tmp, path);
-}

modules/anthropic-manager/module.json

@@ -1,63 +0,0 @@
-{
-  "module": "anthropic-manager",
-  "version": "1",
-  "slug": "anthmgr",
-  "capabilities": [
-    "container-runtime"
-  ],
-  "requires": [
-    "model-access"
-  ],
-  "binds": {
-    "model-access": "/var/lib/mesh/anthropic-manager/model.json"
-  },
-  "secrets": {
-    "model-access": "/var/lib/mesh/anthropic-manager/refresh-token"
-  },
-  "own-secrets": {
-    "broker": "/var/lib/mesh/anthropic-manager/broker"
-  },
-  "emits": [
-    "usage.read"
-  ],
-  "resources": [
-    {
-      "id": "mesh-state",
-      "type": "directory",
-      "path": "/var/lib/mesh/anthropic-manager",
-      "mode": "0700"
-    },
-    {
-      "id": "out",
-      "type": "directory",
-      "path": "/var/lib/mesh/anthropic-manager/out",
-      "mode": "0700"
-    },
-    {
-      "id": "refresh",
-      "type": "container",
-      "name": "mesh-anthropic-manager-refresh",
-      "image": "mesh-runtime-anthropic-manager@sha256:0000000000000000000000000000000000000000000000000000000000000000",
-      "network": "host",
-      "schedule": "*/5 * * * *",
-      "args": [
-        "run",
-        "/app/modules/anthropic-manager/dist/refresh/index.js"
-      ],
-      "volumes": [
-        "/var/lib/mesh/anthropic-manager/broker:/run/secrets/broker:ro",
-        "/var/lib/mesh/anthropic-manager:/run/state"
-      ],
-      "env": {
-        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_ANTHROPIC_LICENCE": "personal",
-        "MESH_MODEL_ACCESS_SECRET_FILE": "/run/state/refresh-token",
-        "MESH_MODEL_ACCESS_BIND_FILE": "/run/state/model.json",
-        "MESH_ANTHROPIC_ACCESS_OUT": "/run/state/out/access-token",
-        "MESH_ANTHROPIC_GRANT_OUT": "/run/state/out/grant.json",
-        "MESH_ANTHROPIC_USAGE_OUT": "/run/state/out/usage.json",
-        "MESH_TOOLS_MAIN": "/app/dist/main.js"
-      }
-    }
-  ]
-}

modules/anthropic-manager/package.json

@@ -1,16 +0,0 @@
-{
-  "name": "@novox/module-anthropic-manager",
-  "version": "0.1.0",
-  "description": "anthropic-manager — the manager side of the model-access refreshable-grant (ADR 0050): opens the refresh token on the manager node alone, refreshes it against Anthropic's OAuth endpoint, and submits back only the access token and the re-sealed refresh envelope.",
-  "type": "module",
-  "private": true,
-  "dependencies": {
-    "@novox/mesh-sdk": "^0.1.0",
-    "tweetnacl": "^1.0.3",
-    "tweetnacl-sealedbox-js": "^1.2.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.6.0"
-  }
-}

modules/anthropic-manager/refresh/index.ts

@@ -1,157 +0,0 @@
-// The manager's scheduled run (novox/hq ADR 0050/0053). It is the whole of the carve-out in one
-// place, and it runs on the MANAGER NODE, never in the control plane:
-//
-//   1. read the refresh token as CLEARTEXT — the host unsealed the stored box with THIS node's private
-//      key and mounted it at the module's bound secret path, exactly as it delivers any credential.
-//      This module holds no node key and opens nothing itself;
-//   2. call the vendor's OAuth token endpoint to mint a fresh access token (and maybe a rotated
-//      refresh token);
-//   3. if the vendor rotated the refresh token, SEAL the new one to this node's PUBLIC sealing key
-//      (delivered in the bound facts) with the same anonymous box the mesh seals every credential with;
-//   4. hand the control plane back ONLY the access token in the clear + the opaque re-sealed box —
-//      never the refresh token — which it seals per consumer holder and stores;
-//   5. poll usage with the fresh access token and record the licence-grain reading.
-//
-// mesh-controller receives the products of steps 3–4 through `licence submit-refresh` (access token +
-// sealed box). The refresh token never leaves this process except as ciphertext, and it never had to
-// be opened here at all — the host did that.
-//
-// This runs as `mesh-tools run`, which connects no broker, so the outputs are written to files the
-// host mounts; the submit itself (the transport to mesh-controller) is done by the caller invoking
-// `mesh-controller licence submit-refresh`. In the lab that caller is the scenario; in production it is
-// an authenticated call the manager node makes. The transport is the one part stubbed here — FLAGGED
-// — because a cross-node authenticated command surface is out of this module's scope.
-
-import { readFileSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
-import { dirname } from "node:path";
-
-import { readEnv } from "@novox/mesh-sdk/primitives";
-
-import { seal } from "../sealedbox.js";
-import { managerPublicKey, writeSealedGrant } from "../grantfile.js";
-import { refreshGrant, grantFromRefresh, readUsage, flattenUsage, type UsageReading } from "../client.js";
-
-/** The vendor-neutral usage row ADR 0054 fixes — the shape the model-usage store upserts. Kept local
- *  to the producer (the normalisation lives in the adapter), so nothing here couples to the SDK. */
-interface UsageRow {
-  licence: string;
-  consumer: string;
-  period: string;
-  metric: string;
-  value: number;
-}
-
-/** Normalise a licence-grain reading into ADR 0054 rows: one utilization row per window, a row
- *  omitted when its percentage is absent. `consumer` is the holding module — the licence grain. */
-function licenceRows(licence: string, consumer: string, reading: UsageReading): UsageRow[] {
-  const rows: UsageRow[] = [];
-  const add = (period: string, pct: number | null): void => {
-    if (pct !== null && pct !== undefined && Number.isFinite(pct)) {
-      rows.push({ licence, consumer, period, metric: "utilization", value: pct });
-    }
-  };
-  add("5h", reading.sessionPct);
-  add("7d", reading.weeklyPct);
-  add("extra", reading.extraPct);
-  return rows;
-}
-
-function required(name: string): string {
-  const v = process.env[name];
-  if (!v) throw new Error(`${name} is not set — the manager runtime was deployed without it`);
-  return v;
-}
-
-function atomicWrite(path: string, content: string): void {
-  mkdirSync(dirname(path), { recursive: true });
-  const tmp = `${path}.tmp`;
-  writeFileSync(tmp, content, { mode: 0o600 });
-  renameSync(tmp, path);
-}
-
-async function main(): Promise<void> {
-  const licence = process.env.MESH_ANTHROPIC_LICENCE ?? "unknown";
-
-  // Step 1: the refresh token as cleartext, unsealed and mounted by the HOST. No open here.
-  const refreshToken = readFileSync(required("MESH_MODEL_ACCESS_SECRET_FILE"), "utf8").trim();
-  if (!refreshToken) {
-    // Nothing was delivered — the manager has not adopted a refresh token yet, or the push has not
-    // landed. Said rather than treated as an empty token the vendor would reject obscurely.
-    throw new Error("[anthropic-manager] no refresh token was delivered; adopt one first");
-  }
-
-  // The node's PUBLIC sealing key, to re-seal a rotated refresh token. Public, delivered in the facts.
-  const nodePub = managerPublicKey(required("MESH_MODEL_ACCESS_BIND_FILE"));
-
-  // Step 2: the vendor call.
-  const refreshed = await refreshGrant(refreshToken);
-  if (!refreshed) {
-    // A dead endpoint or a rejected token: nothing to publish, and we do not clobber a good grant.
-    throw new Error(`[anthropic-manager] the refresh of ${licence} produced no grant`);
-  }
-  const grant = grantFromRefresh(refreshed, Date.now());
-  if (!grant) {
-    throw new Error(`[anthropic-manager] the refresh of ${licence} returned no access token`);
-  }
-
-  // Step 3: re-seal the rotated refresh token, if the vendor rotated it. Nothing to store otherwise.
-  if (grant.rotatedRefresh) {
-    const sealed = seal(new Uint8Array(Buffer.from(grant.rotatedRefresh, "utf8")), nodePub);
-    if (process.env.MESH_ANTHROPIC_GRANT_OUT) {
-      writeSealedGrant(process.env.MESH_ANTHROPIC_GRANT_OUT, sealed, nodePub);
-    }
-  }
-
-  // Step 4: the access token in the clear, for the control plane to seal per consumer holder. This is
-  // all it ever receives that is not ciphertext.
-  atomicWrite(required("MESH_ANTHROPIC_ACCESS_OUT"), grant.access.accessToken);
-
-  console.error(
-    `[anthropic-manager] refreshed ${licence}: access token minted` +
-      (grant.rotatedRefresh ? ", refresh token rotated and re-sealed" : ", refresh token unchanged"),
-  );
-
-  // Step 5: licence-grain usage, best-effort — a usage read failing must not fail the refresh.
-  try {
-    const usage = await readUsage(grant.access.accessToken);
-    if (usage) {
-      const reading = flattenUsage(usage);
-      if (process.env.MESH_ANTHROPIC_USAGE_OUT) {
-        atomicWrite(
-          process.env.MESH_ANTHROPIC_USAGE_OUT,
-          JSON.stringify({ licence, grain: "licence", ...reading }),
-        );
-      }
-      // Emit ADR-0054 rows, not a vendor-shaped body: the consumer of module.*.usage.* is the
-      // vendor-neutral model-usage store, so the normalisation is done HERE. The node names the
-      // holding module; with MESH_NODE unset the consumer is the module alone.
-      const node = readEnv("MESH_NODE", "");
-      const consumer = node ? `${node}/anthropic-manager` : "anthropic-manager";
-      await emitUsage({ rows: licenceRows(licence, consumer, reading), raw: usage });
-    }
-  } catch (err) {
-    console.error(`[anthropic-manager] usage poll for ${licence} failed: ${err}`);
-  }
-}
-
-/**
- * Emit a usage event best-effort by shelling out to the sibling mesh-tools `emit` primitive, which
- * is the one path that wires a broker from a run-once/scheduled step (which itself connects none).
- * A broker hiccup must never fail a refresh that already happened.
- */
-async function emitUsage(body: Record<string, unknown>): Promise<void> {
-  const main = process.env.MESH_TOOLS_MAIN ?? "/app/dist/main.js";
-  const { spawn } = await import("node:child_process");
-  await new Promise<void>((resolve) => {
-    const child = spawn(process.execPath, [main, "emit", "usage.read", JSON.stringify(body)], {
-      stdio: "inherit",
-    });
-    child.on("exit", () => resolve());
-    child.on("error", (err) => {
-      console.error(`[anthropic-manager] could not emit usage: ${err}`);
-      resolve();
-    });
-  });
-}
-
-await main();

modules/anthropic-manager/sealedbox.ts

@@ -1,57 +0,0 @@
-// A NaCl `crypto_box_seal`, byte-compatible with Go's `box.SealAnonymous`, over the audited
-// `tweetnacl-sealedbox-js`.
-//
-// **Why this file exists, and why it is exactly this.** novox/hq ADR 0050's refreshable-grant
-// carve-out delivers the refresh token to the manager module the way the mesh delivers every other
-// credential: sealed to the node's key, and unsealed by the *host* — never by the module. The host
-// unseals with Go's `golang.org/x/crypto/nacl/box.OpenAnonymous` (mesh-host
-// internal/identity/sealing.go), and mesh-controller seals with `box.SealAnonymous`
-// (mesh-controller internal/secrets/seal.go). Both are NaCl `crypto_box_seal`:
-//
-//     sealed = ephemeralPub(32) ‖ crypto_box(msg, nonce, recipientPub, ephemeralSecret)
-//     nonce  = blake2b( ephemeralPub ‖ recipientPub , 24 bytes, unkeyed )
-//
-// When the vendor rotates the refresh token, the manager module must store the new one back the
-// same way — sealed to the manager node's own sealing key — so mesh-controller keeps it without ever
-// reading it and the host can later unseal it to deliver the cleartext again. That reseal happens
-// here, on the manager node, in TypeScript. It therefore has to produce the *identical* byte format
-// Go's `Open` accepts, or the host would refuse the delivery.
-//
-// **The crypto is not ours.** `tweetnacl-sealedbox-js` is `crypto_box_seal` built on the audited
-// TweetNaCl (`tweetnacl`) and blakejs — the same construction, and the same libraries, the mesh used
-// to validate this seal during Phase C. It generates the ephemeral X25519 key pair, derives the
-// nonce as `blake2b(ephemeralPub ‖ recipientPub, 24)`, and produces `ephemeralPub ‖ box`. That is
-// exactly what Go's `box.OpenAnonymous` opens: the wire format is unchanged from the hand-transcribed
-// version this replaces — only the implementation is now a maintained, reviewed dependency rather
-// than a copy of TweetNaCl and blakejs carried inline. The module runtime image bundles it
-// (package.json dependencies; novox/hq ADR 0052).
-//
-// **How it is kept honest.** A cross-language test seals a fixture here and opens it in Go
-// (mesh-controller internal/secrets/sealedbox_xcheck_test.go); the fixture is regenerated from this
-// `seal()`. A drift between this seal and Go's box surfaces there as a seal Go cannot open, not as a
-// refresh token silently mangled in production.
-//
-// This module SEALS only. It never opens — opening is the host's job, with the node private key the
-// module is deliberately never given.
-
-// A default import, not `{ seal }`: the library is a CommonJS UMD bundle, and Node's ESM loader
-// cannot statically see its named exports — only its default, which is the whole module object.
-import sealedbox from "tweetnacl-sealedbox-js";
-
-const RAW_KEY_LEN = 32;
-
-/**
- * Seal a value to a node's public sealing key, producing what Go's `box.OpenAnonymous` opens.
- *
- * @param value               the plaintext (e.g. a rotated refresh token)
- * @param recipientPublicB64  the node's raw 32-byte X25519 public key, standard base64
- * @returns                   standard-base64( ephemeralPub ‖ box )
- */
-export function seal(value: Uint8Array, recipientPublicB64: string): string {
-  const recipientPub = Buffer.from(recipientPublicB64, "base64");
-  if (recipientPub.length !== RAW_KEY_LEN) {
-    throw new Error(`a sealing public key is 32 bytes, not ${recipientPub.length}`);
-  }
-  const sealed = sealedbox.seal(value, new Uint8Array(recipientPub));
-  return Buffer.from(sealed).toString("base64");
-}

modules/anthropic-manager/test/client.test.ts

@@ -1,43 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-
-import { grantFromRefresh, flattenUsage } from "../client.ts";
-
-test("an empty refresh response never clobbers a good grant", () => {
-  assert.equal(grantFromRefresh({}, 1000), null);
-});
-
-test("a refresh with an access token yields an access-token-only grant and epoch expiry", () => {
-  const out = grantFromRefresh(
-    { access_token: "at-new", expires_in: 3600, refresh_token: "rt-rotated", subscription_type: "pro" },
-    1_000_000,
-  );
-  assert.ok(out);
-  assert.equal(out!.access.accessToken, "at-new");
-  assert.equal(out!.access.expiresAt, 1_000_000 + 3600 * 1000);
-  assert.equal(out!.access.subscriptionType, "pro");
-  // The rotated refresh token is reported separately, for the manager to re-seal — never put in the
-  // holder grant.
-  assert.equal(out!.rotatedRefresh, "rt-rotated");
-  assert.ok(!("refreshToken" in (out!.access as object)));
-});
-
-test("a refresh that did not rotate the refresh token reports none to re-seal", () => {
-  const out = grantFromRefresh({ access_token: "at-new" }, 0);
-  assert.ok(out);
-  assert.equal(out!.rotatedRefresh, null);
-});
-
-test("usage flattens the vendor windows to the ADR 0054 grain", () => {
-  const r = flattenUsage({
-    five_hour: { utilization: 42, resets_at: "2026-01-01T00:00:00Z" },
-    seven_day: { utilization: 10 },
-    seven_day_sonnet: { utilization: 5 },
-    extra_usage: { utilization: 1 },
-  });
-  assert.equal(r.sessionPct, 42);
-  assert.equal(r.sessionResetsAt, "2026-01-01T00:00:00Z");
-  assert.equal(r.weeklyPct, 10);
-  assert.equal(r.sonnetPct, 5);
-  assert.equal(r.extraPct, 1);
-});

modules/anthropic-manager/test/sealedbox.test.ts

@@ -1,36 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { generateKeyPairSync } from "node:crypto";
-
-import { seal } from "../sealedbox.ts";
-
-// The definitive proof that this seal interoperates with Go's box.OpenAnonymous (the host's Unseal
-// and mesh-controller's secrets.Seal/Open) is a cross-language test in mesh-controller
-// (internal/secrets/sealedbox_xcheck_test.go), which opens a fixture this module's seal() produced.
-// These tests hold the TypeScript side: the output has the crypto_box_seal shape, and it is
-// randomised so a rotation that changed nothing looks nothing like one that changed everything.
-
-/** A node public key as the mesh records it: raw 32-byte X25519, standard base64. */
-function aNodePublicKey(): string {
-  const kp = generateKeyPairSync("x25519");
-  const x = (kp.publicKey.export({ format: "jwk" }) as { x: string }).x;
-  return Buffer.from(x, "base64url").toString("base64");
-}
-
-test("a seal has the crypto_box_seal shape: ephemeralPub(32) + tag(16) + ciphertext(len)", () => {
-  const pub = aNodePublicKey();
-  const msg = Buffer.from("rt-a-refresh-token", "utf8");
-  const blob = Buffer.from(seal(new Uint8Array(msg), pub), "base64");
-  // 32 (ephemeral public key) + 16 (Poly1305 tag) + message length.
-  assert.equal(blob.length, 32 + 16 + msg.length);
-});
-
-test("two seals of the same value differ — a fresh ephemeral key each time", () => {
-  const pub = aNodePublicKey();
-  const msg = new Uint8Array(Buffer.from("rt-a-refresh-token", "utf8"));
-  assert.notEqual(seal(msg, pub), seal(msg, pub));
-});
-
-test("a public key that is not 32 bytes is refused before anything is sealed", () => {
-  assert.throws(() => seal(new Uint8Array([1, 2, 3]), Buffer.from("short").toString("base64")));
-});

modules/anthropic-manager/tsconfig.json

@@ -1,19 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "noEmit": true
-  },
-  "include": [
-    "tweetnacl-sealedbox-js.d.ts",
-    "sealedbox.ts",
-    "grantfile.ts",
-    "client.ts",
-    "adopt/index.ts",
-    "refresh/index.ts"
-  ]
-}

modules/anthropic-manager/tweetnacl-sealedbox-js.d.ts

@@ -1,13 +0,0 @@
-// Ambient types for `tweetnacl-sealedbox-js` (crypto_box_seal), which ships without its own.
-// The library is a small UMD bundle over `tweetnacl` and `blakejs`; only `seal` is used here.
-declare module "tweetnacl-sealedbox-js" {
-  /** crypto_box_seal: returns ephemeralPub(32) ‖ box, sealed to `recipientPublicKey`. */
-  export function seal(message: Uint8Array, recipientPublicKey: Uint8Array): Uint8Array;
-  /** crypto_box_seal_open: returns the plaintext, or null if it does not open. */
-  export function open(
-    sealed: Uint8Array,
-    recipientPublicKey: Uint8Array,
-    recipientSecretKey: Uint8Array,
-  ): Uint8Array | null;
-  export const overheadLength: number;
-}

modules/artifact-store-tools/README.md

@@ -0,0 +1,117 @@
+# artifact-store-tools
+
+Tools that say what the mesh's artifact store holds, and what the controller's records say of it
+(novox/hq ADR 0251 §1–3, to-be 51). It changes nothing on its machine; its only resources are its state
+directory and the file the mesh writes there from its setting `older-store-names`.
+
+## Why a module beside the store
+
+The store is the `distribution` module. A module that provides the artifact store cannot also build an
+artifact: building publishes to the store, so the store would be needed to create itself, and the
+controller's module check refuses that manifest. So the store's tools are a second module, as the
+controller's refusal says to do. **Assign it to the machine that holds the store**: its tools read the
+store's files through the store's own container, and anywhere else they answer that the container is not
+on that machine.
+
+## Tools
+
+| tool | | what |
+|---|---|---|
+| `artifact_store_repositories` | r | every repository: tags and what each names, how many manifests (tagged or not), size |
+| `artifact_store_usage` | r | the store's size, the largest repositories, bytes shared between repositories, bytes no manifest marks (what the nightly collector frees next) |
+| `artifact_store_references` | r | what the controller's records and the catalogue's definitions say of each manifest, counted and sized by state and repository; each manifest listed when one repository is asked; what the records keep that the store does not hold |
+| `artifact_store_collect` | a | a dry run unless `dry_run` is false: what the controller would let go of, and the bytes the nightly collector would free then and now. A real run needs `why` and asks the controller's `collect` |
+
+### How the store is read
+
+The store's door lists repositories and tags, but not a manifest no tag names, and the mesh pins every
+machine by digest, so that is most of them. So the bundle reads the store's own files through its own
+container (`docker exec mesh-registry`, busybox `find`, `stat` and `cat`), and only reads them: every
+blob with its size, every manifest each repository holds, what each tag names, and each manifest's
+content, four hundred to an exec. What it read it keeps (a manifest is named by its content, so it never
+changes), and the next call reads only what is new. A manifest that could not be read is counted and
+said; what it marks beyond itself is then unknown, so sizes may read low and freed bytes high, and the
+answer says so.
+
+docker runs as the tool runner's account; a socket that refuses it is asked again through `sudo -n`,
+never with a prompt, as the container runtime's own tools do.
+
+A manifest *marks* its own content, its configuration and its layers, and an index marks the manifests
+it lists. The store's collector removes every blob no manifest marks, so these numbers are its own.
+
+### The states of a manifest
+
+| state | what | removable |
+|---|---|---|
+| `kept` | a definition names it, or one of the five most recent builds of a module the mesh holds; `why` says which | no |
+| `named-by-a-definition` | no record names it, and a definition in the catalogue pins it by digest, under the store's current name or an older one; `why` names the module (hq issue 323) | no |
+| `holder-of-kept-archive` | the manifest that keeps a kept archive's blob (hq issue 253) | no |
+| `eligible` | the mesh made it and keeps it for no reason | through the controller's `collect` |
+| `holder-of-eligible-archive` | the manifest that keeps an eligible archive's blob | with its archive |
+| `let-go-yet-present` | the controller recorded letting go of it, and the store still holds it | no — a finding |
+| `named-document` | a one-layer manifest the controller keeps under a tag (hq to-be 45 §9) | no |
+| `unrecorded` | no record names it | **never**, by any tool (ADR 0189 §3) |
+
+**A platform manifest takes the state of the recorded index naming it** (hq ADR 0257). An upstream
+image is an index over several platforms, and each platform manifest is a manifest of the repository in
+its own right; the controller lets an index go with the platform manifests only it names, so they are
+counted as the index's. Two indexes naming one platform give it the more keeping state. An index no
+record names leaves its platform manifests unrecorded with it.
+
+**What the definitions pin** (hq issue 323). A definition may pin an image of the store the mesh did not
+make: pushed before the mesh built it, and pinned under the store's current name or a name it had before.
+No record of the controller names it, yet a machine runs it, so `artifact_store_references` reads every
+definition the catalogue holds (`mesh-catalog.catalog_modules`, then `catalog_module` for each, eight at
+a time and within twenty seconds) and finds every `<name>/<repository>@sha256:…` in any of its strings,
+under each of the store's names: `artifact-store://`, the store's address as the controller answers it,
+and the names it had before. Those are the mesh's setting `older-store-names` (space-separated, `none` by
+default, set with the controller's `settings`), which the mesh writes to the module's `store-names` file: a
+catalogue names no installation. When they cannot be read, the answer's first line says so. A manifest no record
+names that a definition pins is `named-by-a-definition`; one the records name keeps the records' state. A
+definition read at its commit is kept, so the next call asks only for the list. Definitions that could
+not be read are listed under `definitions.unread`, and the answer's first line says that what they pin
+reads as unrecorded until they are.
+
+**Unrecorded copies of upstream images** are listed in `unrecorded_mirrors`: each manifest at the top of
+a repository only the build's mirror writes (`upstream/<host>/<path>`, or a module's `<module>/on-<argument>`
+from before hq ADR 0257) that no record names, with what it and its platforms mark alone. They are the
+input to the controller's `mirrors` verb, which records them as the mesh's on a person's word; the sweep
+then decides about them as about every other copy. This tool removes none of them.
+
+The records come from the controller's `artifacts` verb, asked with the references already let go of;
+when that answer is too large to carry, it is asked without them and the answer says so.
+
+### Collecting
+
+`artifact_store_collect` never deletes anything itself. The controller decides and records what it
+lets go of (ADR 0189 §2), so a real run asks its `collect` with `why` and `confirm`; the controller holds
+every kept archive first and records the run as a hand-act. Bytes come back at the store's nightly
+collection, which runs with the store held still.
+
+An index goes with the platform manifests it names that no kept index of its repository also names, as
+the controller's sweep lets them go (hq ADR 0257). The controller reads only its records; the store's
+files show what else names a platform, so a dry run lists in `platforms_named_by_what_stays` every
+manifest that stays and would lose a platform it names — to be read before a real run.
+
+## Tests
+
+```
+go test ./...
+```
+
+Against a fake container that prints what the two scripts would: the listing parsed (a repository name
+with slashes, a cut listing refused), manifests read with one absent or unreadable said as unread, a
+digest never becoming a path outside the blobs, the mark (an index, a shared blob, a blob nothing marks),
+every state, what the records keep that the store lacks, bytes freed counting a blob shared with a kept
+manifest as kept, a dry run never confirming, a real run without `why` refused before anything is asked,
+the fall-back when the references let go of cannot be carried, a manifest a definition pins under the
+store's current or an older name, a definition not read said first, escalation through `sudo -n`, and that the
+tools served are exactly the manifest's `tools` and its `invokes` exactly the two controller verbs and the
+catalogue's two tools.
+Any command other than the two read-only scripts fails the test.
+
+## Files it does not know
+
+Each directory or archive this module declares says how it treats a file it did not write (ADR 0422, ADR 0416).
+
+- `${dir:state}`: everything in it is the program's; the mesh moves nothing out (ADR 0422 §2).

modules/artifact-store-tools/cmd/artifact-store-tools/classify.go

@@ -0,0 +1,384 @@
+package main
+
+import (
+	"regexp"
+	"sort"
+)
+
+// The states a manifest the store holds can be in, as the records see it (novox/hq to-be 51).
+const (
+	StateKept             = "kept"
+	StateHolderKept       = "holder-of-kept-archive"
+	StateEligible         = "eligible"
+	StateHolderEligible   = "holder-of-eligible-archive"
+	StateCollectedPresent = "let-go-yet-present"
+	StateNamedDocument    = "named-document"
+	// StateNamedByDefinition is a manifest no record names that a definition pins by digest, under the
+	// store's current name or an older one (novox/hq issue 323): a machine may run it, so it is kept.
+	StateNamedByDefinition = "named-by-a-definition"
+	StateUnrecorded        = "unrecorded"
+	collectionRemovesThese = "eligible and holder-of-eligible-archive, through the controller's collect; nothing else"
+)
+
+// Entry is one manifest the store holds, and what the records say of it.
+type Entry struct {
+	Repository string   `json:"repository"`
+	Digest     string   `json:"digest"`
+	State      string   `json:"state"`
+	Why        []string `json:"why,omitempty"`
+	// Archive is the archive a holder keeps.
+	Archive string   `json:"archive,omitempty"`
+	Tags    []string `json:"tags,omitempty"`
+	// Bytes are the blobs it marks, its own content included.
+	Bytes int64 `json:"bytes"`
+	// Unread says its content could not be read, so what it marks is not known beyond itself.
+	Unread string `json:"unread,omitempty"`
+	// Index is the index of the same repository whose state a platform manifest takes (novox/hq ADR
+	// 0257): the controller lets an index go with the platform manifests it names, so they are its.
+	Index string `json:"index,omitempty"`
+	// Mirror says it is an unrecorded copy at the top of a repository the mirror writes — what the
+	// controller's mirrors verb may record as the mesh's (novox/hq ADR 0257).
+	Mirror bool `json:"mirror,omitempty"`
+}
+
+// mirrorRepository is a repository only the build's mirror writes: one upstream image's repository, or a
+// module's own repository of a base from before ADR 0257. The controller's mirrors verb takes the same.
+var mirrorRepository = regexp.MustCompile(`^(upstream/[a-z0-9][a-z0-9._/-]*|[a-z0-9][a-z0-9._-]*/on-[a-z0-9_]+)$`)
+
+// keeping orders the states a platform manifest may take from the indexes naming it: the most keeping
+// wins, so a platform two indexes name is as kept as the more kept of them.
+var keeping = map[string]int{
+	StateKept: 0, StateNamedByDefinition: 1, StateNamedDocument: 2, StateHolderKept: 3, StateEligible: 4,
+	StateHolderEligible: 5, StateCollectedPresent: 6,
+}
+
+// recordIndex finds a record by repository and digest.
+type recordIndex map[string]*Record
+
+func indexRecords(r *Records) recordIndex {
+	idx := recordIndex{}
+	for i := range r.References {
+		rec := &r.References[i]
+		if rec.Repository == "" || rec.Digest == "" {
+			continue
+		}
+		idx[rec.Kind+" "+Key(rec.Repository, rec.Digest)] = rec
+	}
+	return idx
+}
+
+// Classify gives every manifest the store holds one state. A manifest no record names that a definition
+// pins is named by a definition; defs may be nil, when the definitions were not read.
+func Classify(v *View, recs *Records, defs *Definitions) []Entry {
+	idx := indexRecords(recs)
+	var out []Entry
+	for _, name := range v.L.RepoNames() {
+		r := v.L.Repos[name]
+		tagsAt := map[string][]string{}
+		for t, d := range r.Tags {
+			tagsAt[d] = append(tagsAt[d], t)
+		}
+		digests := make([]string, 0, len(r.Revisions))
+		for d := range r.Revisions {
+			digests = append(digests, d)
+		}
+		sort.Strings(digests)
+		for _, d := range digests {
+			e := Entry{Repository: name, Digest: d, State: StateUnrecorded, Tags: tagsAt[d]}
+			sort.Strings(e.Tags)
+			blobs := map[string]bool{}
+			for _, b := range v.Marks(name, d) {
+				blobs[b] = true
+			}
+			e.Bytes = v.Bytes(blobs)
+			e.Unread = v.Unread[Key(name, d)]
+			m := v.M[Key(name, d)]
+			if rec := idx["image "+Key(name, d)]; rec != nil {
+				e.State, e.Why = stateOf(rec, false), rec.Why
+			} else if m.Holder() {
+				archive := m.Layers[0]
+				if rec := idx["archive "+Key(name, archive)]; rec != nil {
+					e.State, e.Why, e.Archive = stateOf(rec, true), rec.Why, archive
+				} else if len(e.Tags) > 0 {
+					e.State = StateNamedDocument
+				}
+			}
+			if e.State == StateUnrecorded && defs != nil {
+				for _, p := range defs.Pins[Key(name, d)] {
+					e.State = StateNamedByDefinition
+					e.Why = append(e.Why, p.why())
+				}
+			}
+			out = append(out, e)
+		}
+	}
+	return platformsOf(v, out)
+}
+
+// platformsOf gives each unrecorded platform manifest the state of the recorded index of its repository
+// that names it, the most keeping when several do, and marks each unrecorded copy at the top of a mirror
+// repository. An index no record names leaves its platform manifests unrecorded with it.
+func platformsOf(v *View, entries []Entry) []Entry {
+	at := map[string]int{}
+	for i, e := range entries {
+		at[Key(e.Repository, e.Digest)] = i
+	}
+	named := map[string]bool{}
+	for _, e := range entries {
+		m := v.M[Key(e.Repository, e.Digest)]
+		if m == nil {
+			continue
+		}
+		for _, c := range m.Children {
+			named[Key(e.Repository, c)] = true
+		}
+	}
+	for _, e := range entries {
+		rank, recorded := keeping[e.State]
+		if !recorded {
+			continue
+		}
+		m := v.M[Key(e.Repository, e.Digest)]
+		if m == nil {
+			continue
+		}
+		for _, c := range m.Children {
+			i, held := at[Key(e.Repository, c)]
+			if !held {
+				continue
+			}
+			child := &entries[i]
+			if current, was := keeping[child.State]; child.State != StateUnrecorded && (!was || current <= rank) {
+				continue
+			}
+			child.State, child.Why, child.Index = e.State, e.Why, e.Digest
+		}
+	}
+	for i := range entries {
+		e := &entries[i]
+		if e.State == StateUnrecorded && !named[Key(e.Repository, e.Digest)] && mirrorRepository.MatchString(e.Repository) {
+			e.Mirror = true
+		}
+	}
+	return entries
+}
+
+func stateOf(rec *Record, holder bool) string {
+	switch rec.State {
+	case "kept":
+		if holder {
+			return StateHolderKept
+		}
+		return StateKept
+	case "eligible":
+		if holder {
+			return StateHolderEligible
+		}
+		return StateEligible
+	case "collected":
+		return StateCollectedPresent
+	}
+	// A state this bundle does not know is kept: never offered as removable.
+	return StateKept
+}
+
+// Missing are the references the records keep that the store does not hold: an image whose manifest
+// is not in its repository, an archive whose blob is not in the store.
+func Missing(v *View, recs *Records) []string {
+	var out []string
+	for _, rec := range recs.References {
+		if rec.State != "kept" || rec.Repository == "" || rec.Digest == "" {
+			continue
+		}
+		switch rec.Kind {
+		case "image":
+			if r := v.L.Repos[rec.Repository]; r == nil || !r.Revisions[rec.Digest] {
+				out = append(out, rec.Reference)
+			}
+		case "archive":
+			if _, ok := v.L.Blobs[rec.Digest]; !ok {
+				out = append(out, rec.Reference)
+			}
+		}
+	}
+	sort.Strings(out)
+	return out
+}
+
+// StateSum is the manifests of one state: how many, the bytes they mark together, and the bytes only
+// they mark — what the store would give back if they alone went.
+type StateSum struct {
+	Manifests      int   `json:"manifests"`
+	Bytes          int64 `json:"bytes"`
+	OnlyTheirBytes int64 `json:"only_their_bytes"`
+}
+
+// Summarise sums entries by state, over the whole store or one repository's entries, the "only theirs"
+// always judged against every manifest in the store.
+func Summarise(v *View, entries []Entry, all []Entry) map[string]*StateSum {
+	statesOf := map[string]map[string]bool{}
+	for _, e := range all {
+		for _, b := range v.Marks(e.Repository, e.Digest) {
+			if statesOf[b] == nil {
+				statesOf[b] = map[string]bool{}
+			}
+			statesOf[b][e.State] = true
+		}
+	}
+	sums := map[string]*StateSum{}
+	blobs := map[string]map[string]bool{}
+	for _, e := range entries {
+		s := sums[e.State]
+		if s == nil {
+			s = &StateSum{}
+			sums[e.State] = s
+			blobs[e.State] = map[string]bool{}
+		}
+		s.Manifests++
+		for _, b := range v.Marks(e.Repository, e.Digest) {
+			blobs[e.State][b] = true
+		}
+	}
+	for state, set := range blobs {
+		sums[state].Bytes = v.Bytes(set)
+		only := map[string]bool{}
+		for b := range set {
+			if len(statesOf[b]) == 1 {
+				only[b] = true
+			}
+		}
+		sums[state].OnlyTheirBytes = v.Bytes(only)
+	}
+	return sums
+}
+
+// LetGoKeys are the manifests the store would no longer hold once the controller lets go of these
+// references: an image's manifest and, for an index, the platform manifests it names that no kept index
+// of the repository names too (novox/hq ADR 0257); and an archive's holder. Spared is the manifests a
+// kept index names, by Key.
+func LetGoKeys(v *View, refs []string, spared map[string]bool) map[string]bool {
+	out := map[string]bool{}
+	for _, ref := range refs {
+		repo, digest, kind := splitReference(ref)
+		r := v.L.Repos[repo]
+		if r == nil {
+			continue
+		}
+		switch kind {
+		case "image":
+			if r.Revisions[digest] {
+				out[Key(repo, digest)] = true
+				if m := v.M[Key(repo, digest)]; m != nil {
+					for _, c := range m.Children {
+						if r.Revisions[c] && !spared[Key(repo, c)] {
+							out[Key(repo, c)] = true
+						}
+					}
+				}
+			}
+		case "archive":
+			for d := range r.Revisions {
+				if m := v.M[Key(repo, d)]; m.Holder() && m.Layers[0] == digest {
+					out[Key(repo, d)] = true
+				}
+			}
+		}
+	}
+	return out
+}
+
+// Spared is every manifest the controller's sweep leaves in place when it lets an index go: each kept
+// manifest, and every platform manifest a kept index names (novox/hq ADR 0257).
+func Spared(v *View, entries []Entry) map[string]bool {
+	out := map[string]bool{}
+	for _, e := range entries {
+		if e.State != StateKept || e.Index != "" {
+			continue
+		}
+		out[Key(e.Repository, e.Digest)] = true
+		if m := v.M[Key(e.Repository, e.Digest)]; m != nil {
+			for _, c := range m.Children {
+				out[Key(e.Repository, c)] = true
+			}
+		}
+	}
+	return out
+}
+
+// Orphaned are the manifests that stay and name a platform manifest collection would remove: what the
+// controller cannot see, because it reads only the records, said before anybody runs it for real.
+func Orphaned(v *View, gone map[string]bool) []string {
+	var out []string
+	for _, name := range v.L.RepoNames() {
+		for d := range v.L.Repos[name].Revisions {
+			if gone[Key(name, d)] {
+				continue
+			}
+			if m := v.M[Key(name, d)]; m != nil {
+				for _, c := range m.Children {
+					if gone[Key(name, c)] {
+						out = append(out, Key(name, d))
+						break
+					}
+				}
+			}
+		}
+	}
+	sort.Strings(out)
+	return out
+}
+
+// UnrecordedMirror is one unrecorded copy at the top of a mirror repository, with what it and its
+// platform manifests mark that nothing else does.
+type UnrecordedMirror struct {
+	Reference string `json:"reference"`
+	Bytes     int64  `json:"bytes"`
+	OnlyTheir int64  `json:"only_their_bytes"`
+}
+
+// UnrecordedMirrors are the copies the controller's mirrors verb may record, largest first.
+func UnrecordedMirrors(v *View, entries []Entry) []UnrecordedMirror {
+	marks := map[string]int{}
+	for name, r := range v.L.Repos {
+		for d := range r.Revisions {
+			for _, b := range v.Marks(name, d) {
+				marks[b]++
+			}
+		}
+	}
+	var out []UnrecordedMirror
+	for _, e := range entries {
+		if !e.Mirror {
+			continue
+		}
+		family := map[string]bool{}
+		own := map[string]int{}
+		add := func(digest string) {
+			for _, b := range v.Marks(e.Repository, digest) {
+				family[b] = true
+				own[b]++
+			}
+		}
+		add(e.Digest)
+		if m := v.M[Key(e.Repository, e.Digest)]; m != nil {
+			for _, c := range m.Children {
+				add(c)
+			}
+		}
+		only := map[string]bool{}
+		for b, n := range own {
+			if marks[b] == n {
+				only[b] = true
+			}
+		}
+		out = append(out, UnrecordedMirror{Reference: "artifact-store://" + e.Repository + "@" + e.Digest,
+			Bytes: v.Bytes(family), OnlyTheir: v.Bytes(only)})
+	}
+	sort.Slice(out, func(i, j int) bool {
+		if out[i].OnlyTheir != out[j].OnlyTheir {
+			return out[i].OnlyTheir > out[j].OnlyTheir
+		}
+		return out[i].Reference < out[j].Reference
+	})
+	return out
+}

modules/artifact-store-tools/cmd/artifact-store-tools/definitions.go

@@ -0,0 +1,343 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"regexp"
+	"sort"
+	"strings"
+	"sync"
+	"time"
+)
+
+// What the definitions pin in the store (novox/hq issue 323). A definition may pin an image of the store by
+// digest that the mesh did not make: one pushed before the mesh built it, pinned under the store's current
+// name or under a name the store had before. No record of the controller names such a manifest, and yet a
+// machine runs it, so it is said to be named by a definition and never unrecorded.
+
+// NamesFileEnv names the file the mesh writes from the setting older-store-names: a line `older=` with the
+// names the store had before, as a definition may still write them — host names, or host:port, separated by
+// spaces — or `none`. A catalogue names no installation, so the names are the mesh's setting, not the
+// manifest's.
+const NamesFileEnv = "MESH_ARTIFACT_STORE_NAMES_FILE"
+
+// CatalogueModules and CatalogueModule are the catalogue's tools these definitions are read through.
+const (
+	CatalogueModules = "mesh-catalog.catalog_modules"
+	CatalogueModule  = "mesh-catalog.catalog_module"
+)
+
+// DefinitionsTimeout bounds reading every definition, below the runtime's thirty-second call limit; what
+// was read is kept, so a call that runs out reads only the rest the next time.
+const DefinitionsTimeout = 20 * time.Second
+
+// definitionReaders is how many definitions are asked at once.
+const definitionReaders = 8
+
+// StoreNames are the names a definition may pin an image of the store under: the scheme the mesh writes
+// (artifact-store://), the store's address now, and the names it had before.
+type StoreNames struct {
+	Current []string
+	Older   []string
+}
+
+// NamesOf is the store's names: its address as the controller answers it, and the older ones given.
+func NamesOf(address, older string) StoreNames {
+	n := StoreNames{Current: []string{"artifact-store://"}}
+	if a := strings.Trim(strings.TrimSpace(address), "/"); a != "" {
+		n.Current = append(n.Current, a+"/")
+	}
+	for _, o := range strings.FieldsFunc(older, func(r rune) bool { return r == ',' || r == ' ' || r == '\n' || r == '\t' }) {
+		if o = strings.Trim(o, "/"); o != "" && o != "none" {
+			n.Older = append(n.Older, o+"/")
+		}
+	}
+	return n
+}
+
+// OlderNames reads the older names from the file the mesh writes, and says why when it cannot.
+func OlderNames() (string, string) {
+	path := os.Getenv(NamesFileEnv)
+	if path == "" {
+		return "", NamesFileEnv + " is not set, so no older name of the store was read"
+	}
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return "", "the store's older names could not be read: " + err.Error()
+	}
+	for _, line := range strings.Split(string(raw), "\n") {
+		if v, ok := strings.CutPrefix(strings.TrimSpace(line), "older="); ok {
+			return v, ""
+		}
+	}
+	return "", path + " holds no line older=, so no older name of the store was read"
+}
+
+// Pin is one definition pinning a manifest of the store by digest.
+type Pin struct {
+	Module string `json:"module"`
+	// Name is the store's name it is pinned under, as written: "artifact-store://", an address, or an older name.
+	Name  string `json:"name"`
+	Older bool   `json:"older,omitempty"`
+}
+
+// pinned is one pin found in a manifest: where in the store, and under which name.
+type pinned struct {
+	Repository, Digest, Name string
+	Older                    bool
+}
+
+var pinShapes sync.Map // name -> *regexp.Regexp
+
+// pinShape is `<name><repository>@sha256:<hex>`, the name standing on its own: not the tail of a longer host.
+func pinShape(name string) *regexp.Regexp {
+	if re, ok := pinShapes.Load(name); ok {
+		return re.(*regexp.Regexp)
+	}
+	re := regexp.MustCompile(`(?:^|[^A-Za-z0-9.-])` + regexp.QuoteMeta(name) +
+		`([a-z0-9][a-z0-9._/-]*)@(sha256:[0-9a-f]{64})`)
+	pinShapes.Store(name, re)
+	return re
+}
+
+// PinsIn finds every image of the store a manifest pins by digest, in any string it holds: a resource's
+// image, a build's base, a file's content.
+func PinsIn(manifest json.RawMessage, names StoreNames) []pinned {
+	var doc any
+	if json.Unmarshal(manifest, &doc) != nil {
+		return nil
+	}
+	seen := map[string]bool{}
+	var out []pinned
+	var walk func(any)
+	walk = func(x any) {
+		switch v := x.(type) {
+		case map[string]any:
+			for _, e := range v {
+				walk(e)
+			}
+		case []any:
+			for _, e := range v {
+				walk(e)
+			}
+		case string:
+			for _, group := range []struct {
+				names []string
+				older bool
+			}{{names.Current, false}, {names.Older, true}} {
+				for _, name := range group.names {
+					for _, m := range pinShape(name).FindAllStringSubmatch(v, -1) {
+						p := pinned{Repository: strings.Trim(m[1], "/"), Digest: m[2], Name: name, Older: group.older}
+						if k := p.Repository + "@" + p.Digest + " " + p.Name; !seen[k] {
+							seen[k] = true
+							out = append(out, p)
+						}
+					}
+				}
+			}
+		}
+	}
+	walk(doc)
+	return out
+}
+
+// Definitions is what the catalogue's definitions pin in the store, and what of them could not be read.
+type Definitions struct {
+	// Pins are by Key(repository, digest).
+	Pins map[string][]Pin
+	// Read is how many definitions were read; Unread says, per module, why its definition was not.
+	Read   int
+	Unread map[string]string
+	// NotAsked says why the catalogue could not be asked at all, when it could not.
+	NotAsked string
+	// NamesNotRead says why the store's older names could not be read, when they could not.
+	NamesNotRead string
+	Names        StoreNames
+}
+
+// Catalogue reads the definitions through the catalogue's tools, and keeps each definition it read by its
+// module and commit, which never change together.
+type Catalogue struct {
+	Ask Asking
+
+	mu   sync.Mutex
+	kept map[string][]pinned // "<module>@<commit>|<names>" -> its pins
+}
+
+type catalogueEntry struct {
+	Module string `json:"module"`
+	Commit string `json:"commit"`
+}
+
+// Read asks the catalogue for every module and reads each definition, bounded by DefinitionsTimeout.
+func (c *Catalogue) Read(ctx context.Context, names StoreNames) *Definitions {
+	defs := &Definitions{Pins: map[string][]Pin{}, Unread: map[string]string{}, Names: names}
+	if c == nil || c.Ask == nil {
+		defs.NotAsked = "this bundle has no way to ask the catalogue"
+		return defs
+	}
+	raw, err := c.Ask(CatalogueModules, map[string]any{})
+	if err != nil {
+		defs.NotAsked = "the catalogue's modules could not be asked: " + err.Error()
+		return defs
+	}
+	answer, output, ok := answerOf(raw)
+	if !ok {
+		defs.NotAsked = "the catalogue refused its modules: " + lastLine(output)
+		return defs
+	}
+	var list struct {
+		Modules []catalogueEntry `json:"modules"`
+		Error   string           `json:"error"`
+	}
+	if err := json.Unmarshal(answer, &list); err != nil || list.Error != "" || list.Modules == nil {
+		defs.NotAsked = "the catalogue's modules answer is not readable: " + firstOf(list.Error, errText(err), lastLine(output))
+		return defs
+	}
+	c.mu.Lock()
+	if c.kept == nil {
+		c.kept = map[string][]pinned{}
+	}
+	c.mu.Unlock()
+	nameKey := strings.Join(names.Current, ",") + ";" + strings.Join(names.Older, ",")
+
+	ctx, cancel := context.WithTimeout(ctx, DefinitionsTimeout)
+	defer cancel()
+	type result struct {
+		module string
+		pins   []pinned
+		why    string
+	}
+	results := make(chan result, len(list.Modules))
+	work := make(chan catalogueEntry)
+	var wg sync.WaitGroup
+	for i := 0; i < definitionReaders; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			for m := range work {
+				pins, why := c.definition(m, names, nameKey)
+				results <- result{m.Module, pins, why}
+			}
+		}()
+	}
+	go func() {
+		defer close(work)
+		for _, m := range list.Modules {
+			select {
+			case work <- m:
+			case <-ctx.Done():
+				return
+			}
+		}
+	}()
+	go func() { wg.Wait(); close(results) }()
+
+	got := map[string]bool{}
+collect:
+	for {
+		select {
+		case r, open := <-results:
+			if !open {
+				break collect
+			}
+			got[r.module] = true
+			if r.why != "" {
+				defs.Unread[r.module] = r.why
+				continue
+			}
+			defs.Read++
+			for _, p := range r.pins {
+				k := Key(p.Repository, p.Digest)
+				defs.Pins[k] = append(defs.Pins[k], Pin{Module: r.module, Name: p.Name, Older: p.Older})
+			}
+		case <-ctx.Done():
+			break collect
+		}
+	}
+	for _, m := range list.Modules {
+		if !got[m.Module] {
+			defs.Unread[m.Module] = fmt.Sprintf("not read within %d s", int(DefinitionsTimeout/time.Second))
+		}
+	}
+	for k := range defs.Pins {
+		sort.Slice(defs.Pins[k], func(i, j int) bool { return defs.Pins[k][i].Module < defs.Pins[k][j].Module })
+	}
+	return defs
+}
+
+// definition reads one module's definition, or answers it from what was read before.
+func (c *Catalogue) definition(m catalogueEntry, names StoreNames, nameKey string) ([]pinned, string) {
+	key := m.Module + "@" + m.Commit + "|" + nameKey
+	if m.Commit != "" {
+		c.mu.Lock()
+		pins, had := c.kept[key]
+		c.mu.Unlock()
+		if had {
+			return pins, ""
+		}
+	}
+	args := map[string]any{"module": m.Module}
+	if m.Commit != "" {
+		args["commit"] = m.Commit
+	}
+	raw, err := c.Ask(CatalogueModule, args)
+	if err != nil {
+		return nil, "could not be asked: " + err.Error()
+	}
+	answer, output, ok := answerOf(raw)
+	if !ok {
+		return nil, "refused: " + lastLine(output)
+	}
+	var one struct {
+		Module *struct {
+			Manifest json.RawMessage `json:"manifest"`
+		} `json:"module"`
+		Error string `json:"error"`
+	}
+	if err := json.Unmarshal(answer, &one); err != nil || one.Error != "" || one.Module == nil || len(one.Module.Manifest) == 0 {
+		return nil, "not readable: " + firstOf(one.Error, errText(err), "no manifest in the answer")
+	}
+	pins := PinsIn(one.Module.Manifest, names)
+	if m.Commit != "" {
+		c.mu.Lock()
+		c.kept[key] = pins
+		c.mu.Unlock()
+	}
+	return pins, ""
+}
+
+// why says which definitions name a manifest, and under which of the store's names.
+func (p Pin) why() string {
+	if p.Older {
+		return fmt.Sprintf("a definition names it: %s, under %s, an older name of the store", p.Module, shownName(p.Name))
+	}
+	return "a definition names it: " + p.Module
+}
+
+func firstOf(s ...string) string {
+	for _, x := range s {
+		if strings.TrimSpace(x) != "" {
+			return x
+		}
+	}
+	return ""
+}
+
+func errText(err error) string {
+	if err == nil {
+		return ""
+	}
+	return err.Error()
+}
+
+// shownName is a name of the store as a person reads it: a host without the slash a pin puts after it, the
+// scheme as written.
+func shownName(name string) string {
+	if strings.HasSuffix(name, "://") {
+		return name
+	}
+	return strings.TrimSuffix(name, "/")
+}

modules/artifact-store-tools/cmd/artifact-store-tools/definitions_test.go

@@ -0,0 +1,259 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+// A definition may pin an image of the store the mesh did not make, under a name the store had before
+// (novox/hq issue 323): three apps the anchor runs are pinned so. No record names them; a definition does.
+
+const oldName = "registry-api.example.org"
+
+// container is a definition whose one container runs image.
+func container(image string) string {
+	return fmt.Sprintf(`{"module":"x","resources":[{"id":"server","type":"container","image":%q}]}`, image)
+}
+
+func TestAnImageADefinitionPinsUnderAnOlderNameOfTheStoreIsNamedByADefinition(t *testing.T) {
+	v := view(t, world())
+	names := NamesOf("store:5000", oldName)
+	defs := &Definitions{Pins: map[string][]Pin{}}
+	for module, manifest := range map[string]string{
+		// m-stranger: no record names it; the invoicing app pins it under the store's older name.
+		"invoicing": container(oldName + "/app/server@" + d("m-stranger")),
+		// m-old: the records say eligible; a definition pinning it does not change what the records say.
+		"website": container("store:5000/app/server@" + d("m-old")),
+	} {
+		for _, p := range PinsIn(json.RawMessage(manifest), names) {
+			defs.Pins[Key(p.Repository, p.Digest)] = append(defs.Pins[Key(p.Repository, p.Digest)], Pin{Module: module, Name: p.Name, Older: p.Older})
+		}
+	}
+	got := stateByName(Classify(v, withFill(records()), defs))
+	stranger := got["app/server "+d("m-stranger")]
+	if stranger.State != StateNamedByDefinition {
+		t.Fatalf("a manifest a definition pins under an older name reads %q, want %q", stranger.State, StateNamedByDefinition)
+	}
+	if want := []string{"a definition names it: invoicing, under " + oldName + ", an older name of the store"}; !reflect.DeepEqual(stranger.Why, want) {
+		t.Errorf("why %q, want %q", stranger.Why, want)
+	}
+	if s := got["app/server "+d("m-old")].State; s != StateEligible {
+		t.Errorf("a recorded manifest a definition pins reads %q: the records decide what the mesh made", s)
+	}
+	// Without the definitions it is what it was: unrecorded.
+	if s := stateByName(Classify(v, withFill(records()), nil))["app/server "+d("m-stranger")].State; s != StateUnrecorded {
+		t.Errorf("without definitions %q", s)
+	}
+}
+
+func TestPinsAreFoundInEveryStringAndOnlyUnderTheStoresNames(t *testing.T) {
+	names := NamesOf("store:5000", oldName+", older.example/")
+	manifest := `{"resources":[
+		{"type":"container","image":"` + oldName + `/team/www@` + d("www") + `"},
+		{"type":"file","content":"IMAGE=older.example/team/tool@` + d("tool") + `\n"},
+		{"type":"container","image":"artifact-store://mod/art@` + d("built") + `"},
+		{"type":"container","image":"store:5000/mod/art@` + d("addressed") + `"},
+		{"type":"container","image":"not` + oldName + `/team/www@` + d("lookalike") + `"},
+		{"type":"container","image":"docker.io/library/nginx@` + d("upstream") + `"},
+		{"type":"container","image":"` + oldName + `/team/www:latest"}],
+		"build":{"on":{"base":"` + oldName + `/team/www@` + d("www") + `"}}}`
+	var got []string
+	for _, p := range PinsIn(json.RawMessage(manifest), names) {
+		got = append(got, fmt.Sprintf("%s@%s %s %v", p.Repository, p.Digest, p.Name, p.Older))
+	}
+	want := map[string]bool{
+		"team/www@" + d("www") + " " + oldName + "/ true":    true,
+		"team/tool@" + d("tool") + " older.example/ true":    true,
+		"mod/art@" + d("built") + " artifact-store:// false": true,
+		"mod/art@" + d("addressed") + " store:5000/ false":   true,
+	}
+	if len(got) != len(want) {
+		t.Fatalf("found %d pins, want %d (one per image and name; not a longer host's tail, not another registry, not a tag): %v", len(got), len(want), got)
+	}
+	for _, g := range got {
+		if !want[g] {
+			t.Errorf("found %s", g)
+		}
+	}
+}
+
+func TestAPlatformTakesTheStateOfAnIndexADefinitionNames(t *testing.T) {
+	v := mirrorWorld()
+	defs := &Definitions{Pins: map[string][]Pin{
+		Key("route-proxy/on-go_base", d("i-pre")): {{Module: "route-proxy", Name: oldName + "/", Older: true}},
+	}}
+	got := stateByName(Classify(v, withFill(mirrorRecords()), defs))
+	for _, name := range []string{"i-pre", "p-pre"} {
+		if s := got["route-proxy/on-go_base "+d(name)].State; s != StateNamedByDefinition {
+			t.Errorf("%s reads %q, want %q", name, s, StateNamedByDefinition)
+		}
+	}
+	if e := got["route-proxy/on-go_base "+d("p-pre")]; e.Index != d("i-pre") {
+		t.Errorf("p-pre takes its state from %q", e.Index)
+	}
+	if s := got["route-proxy/on-go_base "+d("p-lost")].State; s != StateUnrecorded {
+		t.Errorf("a platform nothing names reads %q", s)
+	}
+	for _, um := range UnrecordedMirrors(v, Classify(v, withFill(mirrorRecords()), defs)) {
+		if strings.Contains(um.Reference, hexOf(d("i-pre"))) {
+			t.Errorf("a copy a definition names is offered to the mirrors verb: %v", um)
+		}
+	}
+}
+
+// olderNames writes the file the mesh writes from the setting older-store-names.
+func olderNames(t *testing.T, names string) {
+	t.Helper()
+	path := filepath.Join(t.TempDir(), "store-names")
+	if err := os.WriteFile(path, []byte("# written by the mesh\nolder="+names+"\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv(NamesFileEnv, path)
+}
+
+func TestTheOlderNamesAreReadFromTheFileTheMeshWrites(t *testing.T) {
+	olderNames(t, oldName+" older.example")
+	got, why := OlderNames()
+	if why != "" || !reflect.DeepEqual(NamesOf("", got).Older, []string{oldName + "/", "older.example/"}) {
+		t.Errorf("read %q (%s)", got, why)
+	}
+	olderNames(t, "none")
+	if got, why := OlderNames(); why != "" || len(NamesOf("", got).Older) != 0 {
+		t.Errorf("none read as %q (%s)", got, why)
+	}
+	t.Setenv(NamesFileEnv, filepath.Join(t.TempDir(), "absent"))
+	if _, why := OlderNames(); why == "" {
+		t.Error("an absent file was not said")
+	}
+}
+
+func TestOlderNamesNotReadAreSaidFirst(t *testing.T) {
+	t.Setenv(NamesFileEnv, "")
+	a := &asked{definitions: map[string]string{"invoicing": container(oldName + "/app/server@" + d("m-stranger"))}}
+	out, err := references(t, a)(map[string]any{"repository": "app/server"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	m := out.(map[string]any)
+	if w := m["said"].([]string)[0]; !strings.Contains(w, NamesFileEnv) {
+		t.Errorf("first said %q", w)
+	}
+	if s := manifestsOf(t, out)["app/server "+d("m-stranger")].State; s != StateUnrecorded {
+		t.Errorf("m-stranger reads %q without the older names", s)
+	}
+}
+
+// references is one artifact_store_references tool, kept across calls as the runtime keeps the bundle.
+func references(t *testing.T, a *asked) func(map[string]any) (any, error) {
+	f := world()
+	s := &Store{Container: "mesh-registry", Run: f.run(t)}
+	for _, tl := range Tools(s, Controller{Ask: a.ask}, &Catalogue{Ask: a.ask}) {
+		if tl.Name == "artifact_store_references" {
+			return tl.Run
+		}
+	}
+	t.Fatal("no artifact_store_references")
+	return nil
+}
+
+func manifestsOf(t *testing.T, out any) map[string]Entry {
+	t.Helper()
+	entries, ok := out.(map[string]any)["manifests"].([]Entry)
+	if !ok {
+		t.Fatalf("no manifests in %v", out)
+	}
+	return stateByName(entries)
+}
+
+func TestReferencesReadTheDefinitionsUnderTheStoresOlderNames(t *testing.T) {
+	olderNames(t, oldName)
+	a := &asked{definitions: map[string]string{
+		"invoicing": container(oldName + "/app/server@" + d("m-stranger")),
+		"grafana":   container("grafana/grafana@" + d("upstream")),
+	}}
+	run := references(t, a)
+	out, err := run(map[string]any{"repository": "app/server"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	e := manifestsOf(t, out)["app/server "+d("m-stranger")]
+	if e.State != StateNamedByDefinition || len(e.Why) != 1 || !strings.Contains(e.Why[0], "invoicing") || !strings.Contains(e.Why[0], oldName) {
+		t.Errorf("m-stranger: %+v", e)
+	}
+	said := out.(map[string]any)["definitions"].(map[string]any)
+	if said["read"] != 2 || !reflect.DeepEqual(said["older_store_names"], []string{oldName}) ||
+		!reflect.DeepEqual(said["store_names"], []string{"artifact-store://", "store:5000"}) {
+		t.Errorf("definitions said %v", said)
+	}
+	if w := out.(map[string]any)["said"].([]string)[0]; strings.Contains(w, "could not be read") {
+		t.Errorf("a warning with every definition read: %s", w)
+	}
+	// A definition read at its commit is kept: the next call asks only for the list.
+	before := 0
+	for _, c := range a.calls {
+		if c == CatalogueModule {
+			before++
+		}
+	}
+	if _, err := run(map[string]any{"repository": "app/server"}); err != nil {
+		t.Fatal(err)
+	}
+	after := 0
+	for _, c := range a.calls {
+		if c == CatalogueModule {
+			after++
+		}
+	}
+	if before != 2 || after != 2 {
+		t.Errorf("asked catalog_module %d times, then %d: each definition at its commit is read once", before, after)
+	}
+}
+
+func TestADefinitionNotReadIsSaidFirstAndLeavesWhatItPinsUnrecorded(t *testing.T) {
+	olderNames(t, oldName)
+	a := &asked{
+		definitions: map[string]string{"invoicing": container(oldName + "/app/server@" + d("m-stranger")), "grafana": container("x")},
+		failing:     map[string]bool{"invoicing": true},
+	}
+	out, err := references(t, a)(map[string]any{"repository": "app/server"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	m := out.(map[string]any)
+	if s := manifestsOf(t, out)["app/server "+d("m-stranger")].State; s != StateUnrecorded {
+		t.Errorf("m-stranger reads %q with its definition unread", s)
+	}
+	if w := m["said"].([]string)[0]; !strings.Contains(w, "1 definitions could not be read") {
+		t.Errorf("first said %q", w)
+	}
+	if u := m["definitions"].(map[string]any)["unread"].(map[string]string); u["invoicing"] == "" || len(u) != 1 {
+		t.Errorf("unread %v", u)
+	}
+
+	// The catalogue not answering at all: the records are still answered, and the warning stands first.
+	a = &asked{noCatalogue: true}
+	out, err = references(t, a)(map[string]any{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	m = out.(map[string]any)
+	if w := m["said"].([]string)[0]; !strings.Contains(w, "the definitions could not be read") || !strings.Contains(w, "no responders") {
+		t.Errorf("first said %q", w)
+	}
+	if m["definitions"].(map[string]any)["not_asked"] == nil {
+		t.Errorf("definitions %v", m["definitions"])
+	}
+}
+
+func TestNoCatalogueIsSaidAndNothingIsAsked(t *testing.T) {
+	defs := (&Catalogue{}).Read(context.Background(), NamesOf("", ""))
+	if defs.NotAsked == "" || defs.Read != 0 {
+		t.Errorf("%+v", defs)
+	}
+}

modules/artifact-store-tools/cmd/artifact-store-tools/main.go

@@ -0,0 +1,31 @@
+// The artifact-store-tools module's Go bundle (novox/hq ADR 0251 §1–3, to-be 51): a process the node's
+// runtime launches and speaks MCP over stdio to. It says what the artifact store holds — its
+// repositories, its size, and what the controller's records say of each manifest — read from the
+// store's own files through the store's own container, and writing nothing. A collection is asked of
+// the controller, which decides and records what it lets go of (ADR 0189).
+//
+// **A module beside the store, not the store's own.** A module that provides the artifact store cannot
+// also build an artifact: building publishes to the store, so the store would be needed to create
+// itself, and the controller refuses that manifest. So these tools are a second module, assigned to the
+// machine that holds the store. stdout is the protocol; what this bundle says, it says on stderr.
+package main
+
+import (
+	"fmt"
+	"os"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+func main() {
+	s := &Store{
+		Container: os.Getenv("MESH_ARTIFACT_STORE_CONTAINER"),
+		Run:       ExecRunner,
+		UID:       os.Getuid(),
+	}
+	// An empty name serves as the module the runtime names (MESH_SERVED_MODULE): artifact-store-tools.
+	if err := stdio.Serve("", Tools(s, Controller{Ask: stdio.Ask}, &Catalogue{Ask: stdio.Ask})); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}

modules/artifact-store-tools/cmd/artifact-store-tools/platforms_test.go

@@ -0,0 +1,131 @@
+package main
+
+import (
+	"reflect"
+	"testing"
+)
+
+// A copy of an upstream image is an index and the platform manifests it names, each a manifest of the
+// repository in its own right (novox/hq ADR 0257). The records name the index; its platforms are its.
+
+// mirrorWorld is two copies of golang in one image's repository and one module's old copy:
+//
+//	upstream/docker.io/library/golang: i-old (eligible) names p-amd and p-arm; i-new (kept) names p-arm and p-new
+//	route-proxy/on-go_base: i-pre, no record, names p-pre; and a platform manifest no index names (p-lost)
+func mirrorWorld() *View {
+	const up = "upstream/docker.io/library/golang"
+	const pre = "route-proxy/on-go_base"
+	l := &Listing{Blobs: map[string]int64{}, Repos: map[string]*Repo{}}
+	v := &View{L: l, M: map[string]*Manifest{}, Unread: map[string]string{}}
+	platform := func(repo, name string, size int64) {
+		l.repo(repo).Revisions[d(name)] = true
+		l.Blobs[d(name)] = 1
+		l.Blobs[d(name+"-layer")] = size
+		v.M[Key(repo, d(name))] = &Manifest{Refs: []string{d(name + "-layer")}, Layers: []string{d(name + "-layer")}}
+	}
+	idx := func(repo, name string, children ...string) {
+		l.repo(repo).Revisions[d(name)] = true
+		l.Blobs[d(name)] = 1
+		var cs []string
+		for _, c := range children {
+			cs = append(cs, d(c))
+		}
+		v.M[Key(repo, d(name))] = &Manifest{Children: cs}
+	}
+	platform(up, "p-amd", 100)
+	platform(up, "p-arm", 200)
+	platform(up, "p-new", 300)
+	idx(up, "i-old", "p-amd", "p-arm")
+	idx(up, "i-new", "p-arm", "p-new")
+	platform(pre, "p-pre", 1000)
+	platform(pre, "p-lost", 50)
+	idx(pre, "i-pre", "p-pre")
+	return v
+}
+
+func mirrorRecords() *Records {
+	const up = "artifact-store://upstream/docker.io/library/golang@"
+	return &Records{References: []Record{
+		{Reference: up + d("i-old"), State: "eligible"},
+		{Reference: up + d("i-new"), State: "kept", Why: []string{"stood-on"}},
+	}}
+}
+
+func stateByName(entries []Entry) map[string]Entry {
+	out := map[string]Entry{}
+	for _, e := range entries {
+		out[e.Repository+" "+e.Digest] = e
+	}
+	return out
+}
+
+func TestAPlatformManifestTakesTheStateOfTheIndexNamingIt(t *testing.T) {
+	v := mirrorWorld()
+	recs := mirrorRecords()
+	for i := range recs.References {
+		fill(&recs.References[i])
+	}
+	got := stateByName(Classify(v, recs, nil))
+	up := "upstream/docker.io/library/golang "
+	for name, want := range map[string]string{
+		up + d("p-amd"):                         StateEligible, // only the eligible index names it
+		up + d("p-arm"):                         StateKept,     // both do: the more keeping wins
+		up + d("p-new"):                         StateKept,
+		"route-proxy/on-go_base " + d("p-pre"):  StateUnrecorded, // its index has no record
+		"route-proxy/on-go_base " + d("p-lost"): StateUnrecorded,
+	} {
+		if got[name].State != want {
+			t.Errorf("%s reads %s, want %s", name, got[name].State, want)
+		}
+	}
+	if got[up+d("p-arm")].Index != d("i-new") {
+		t.Errorf("p-arm names its index as %q", got[up+d("p-arm")].Index)
+	}
+	// Only the top of an unrecorded copy is offered to the mirrors verb: its index, and a platform
+	// manifest no index names.
+	var mirrors []string
+	for _, e := range got {
+		if e.Mirror {
+			mirrors = append(mirrors, e.Digest)
+		}
+	}
+	if len(mirrors) != 2 || !got["route-proxy/on-go_base "+d("i-pre")].Mirror || !got["route-proxy/on-go_base "+d("p-lost")].Mirror {
+		t.Errorf("offered as unrecorded copies: %v", mirrors)
+	}
+	um := UnrecordedMirrors(v, Classify(v, recs, nil))
+	if len(um) != 2 || um[0].Reference != "artifact-store://route-proxy/on-go_base@"+d("i-pre") || um[0].OnlyTheir != 1+1+1000 {
+		t.Errorf("unrecorded copies: %+v", um)
+	}
+}
+
+func TestLettingAnIndexGoTakesItsOwnPlatformsAndSaysWhatStaysAndNamesOne(t *testing.T) {
+	v := mirrorWorld()
+	recs := mirrorRecords()
+	for i := range recs.References {
+		fill(&recs.References[i])
+	}
+	entries := Classify(v, recs, nil)
+	old := "artifact-store://upstream/docker.io/library/golang@" + d("i-old")
+	gone := LetGoKeys(v, []string{old}, Spared(v, entries))
+	up := "upstream/docker.io/library/golang"
+	want := map[string]bool{Key(up, d("i-old")): true, Key(up, d("p-amd")): true}
+	if !reflect.DeepEqual(gone, want) {
+		t.Fatalf("would go: %v; want the old index and the platform only it names", gone)
+	}
+	if o := Orphaned(v, gone); len(o) != 0 {
+		t.Fatalf("what stays names something that goes: %v", o)
+	}
+	// Spared nothing, the shared platform goes too, and the kept index that names it is said.
+	all := LetGoKeys(v, []string{old}, nil)
+	if o := Orphaned(v, all); len(o) != 1 || o[0] != Key(up, d("i-new")) {
+		t.Fatalf("a kept index losing a platform was not said: %v", o)
+	}
+	out := Collected(v, &CollectAnswer{DryRun: true, WouldLetGo: []string{old}, Eligible: 1}, true, entries)
+	if out["manifests_gone"] != 2 {
+		t.Fatalf("collect said %v manifests go", out["manifests_gone"])
+	}
+	if out["collector_frees_after_bytes"].(int64)-out["collector_frees_now_bytes"].(int64) != 1+1+100 {
+		t.Fatalf("collect frees %v more, want the index, its own platform and that platform's layer",
+			out["collector_frees_after_bytes"].(int64)-out["collector_frees_now_bytes"].(int64))
+	}
+}

modules/artifact-store-tools/cmd/artifact-store-tools/read.go

@@ -0,0 +1,175 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"sort"
+	"strings"
+	"sync"
+)
+
+// readScript prints each manifest named on its command line, each after a line naming its path. A
+// manifest is JSON, which holds no raw line break inside a string, so no line of one starts with the
+// marker. One the store does not have is said, not skipped.
+const readScript = `cd ` + storageRoot + `
+for p in "$@"; do
+  echo "#manifest $p"
+  if [ -f "$p" ]; then cat "$p"; echo; else echo "#absent"; fi
+done
+echo '#end'`
+
+// readBatch is how many manifests one exec reads: well under any command line's limit.
+const readBatch = 400
+
+// Store reaches the artifact store's own files, through its own container, and only reads them.
+type Store struct {
+	Container string
+	Run       Runner
+	UID       int
+
+	mu sync.Mutex
+	// cache holds every manifest read: a manifest is named by its content's digest, so it never changes.
+	cache map[string]*Manifest
+}
+
+// List reads the store's files.
+func (s *Store) List(ctx context.Context) (*Listing, error) {
+	if s.Container == "" {
+		return nil, fmt.Errorf("this bundle was not told the artifact store's container (MESH_ARTIFACT_STORE_CONTAINER)")
+	}
+	out, err := docker(ctx, s.Run, s.UID, "exec", s.Container, "sh", "-c", listScript)
+	if err != nil {
+		return nil, err
+	}
+	return ParseListing(out)
+}
+
+// Key names one manifest in one repository.
+func Key(repo, digest string) string { return repo + "@" + digest }
+
+// blobPath is where the store keeps a blob, under storageRoot.
+func blobPath(digest string) string {
+	algorithm, hex, _ := strings.Cut(digest, ":")
+	if algorithm == "" || len(hex) < 2 || strings.ContainsAny(digest, "/ \n") {
+		return ""
+	}
+	return "blobs/" + algorithm + "/" + hex[:2] + "/" + hex + "/data"
+}
+
+// Manifests reads every manifest the listing names, from the cache or the store's files. Answers each
+// one read, and each one not read with why.
+func (s *Store) Manifests(ctx context.Context, l *Listing) (map[string]*Manifest, map[string]string) {
+	need := map[string]bool{}
+	s.mu.Lock()
+	if s.cache == nil {
+		s.cache = map[string]*Manifest{}
+	}
+	for _, name := range l.RepoNames() {
+		for d := range l.Repos[name].Revisions {
+			if _, ok := s.cache[d]; !ok {
+				need[d] = true
+			}
+		}
+	}
+	s.mu.Unlock()
+
+	digests := make([]string, 0, len(need))
+	for d := range need {
+		digests = append(digests, d)
+	}
+	sort.Strings(digests)
+	failed := map[string]string{}
+	for start := 0; start < len(digests); start += readBatch {
+		batch := digests[start:min(start+readBatch, len(digests))]
+		read, err := s.read(ctx, batch)
+		s.mu.Lock()
+		for _, d := range batch {
+			switch m := read[d]; {
+			case err != nil:
+				failed[d] = err.Error()
+			case m == nil:
+				failed[d] = "the store holds no manifest content for it"
+			default:
+				s.cache[d] = m
+			}
+		}
+		s.mu.Unlock()
+	}
+
+	got := map[string]*Manifest{}
+	unread := map[string]string{}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	for _, name := range l.RepoNames() {
+		for d := range l.Repos[name].Revisions {
+			if m, ok := s.cache[d]; ok {
+				got[Key(name, d)] = m
+			} else if why, ok := failed[d]; ok {
+				unread[Key(name, d)] = why
+			} else {
+				unread[Key(name, d)] = "not read"
+			}
+		}
+	}
+	return got, unread
+}
+
+// read reads one batch of manifests. A blob that is not a manifest, or not there, is answered as nil;
+// an exec that fails fails the batch.
+func (s *Store) read(ctx context.Context, digests []string) (map[string]*Manifest, error) {
+	args := []string{"exec", s.Container, "sh", "-c", readScript, "sh"}
+	byPath := map[string]string{}
+	for _, d := range digests {
+		if p := blobPath(d); p != "" {
+			byPath[p] = d
+			args = append(args, p)
+		}
+	}
+	out, err := docker(ctx, s.Run, s.UID, args...)
+	if err != nil {
+		return nil, err
+	}
+	return parseManifests(out, byPath)
+}
+
+// parseManifests reads readScript's output.
+func parseManifests(out string, byPath map[string]string) (map[string]*Manifest, error) {
+	got := map[string]*Manifest{}
+	current := ""
+	var body strings.Builder
+	flush := func() {
+		if d := byPath[current]; d != "" {
+			m, err := ParseManifest([]byte(body.String()))
+			if err != nil {
+				m = nil
+			}
+			got[d] = m
+		}
+		current = ""
+		body.Reset()
+	}
+	ended := false
+	for _, line := range strings.Split(out, "\n") {
+		switch {
+		case strings.HasPrefix(line, "#manifest "):
+			flush()
+			current = strings.TrimPrefix(line, "#manifest ")
+		case line == "#absent":
+			if d := byPath[current]; d != "" {
+				got[d] = nil
+			}
+			current = ""
+			body.Reset()
+		case line == "#end":
+			flush()
+			ended = true
+		default:
+			body.WriteString(line)
+			body.WriteString("\n")
+		}
+	}
+	if !ended {
+		return nil, fmt.Errorf("reading the store's manifests was cut short (it never reached its end)")
+	}
+	return got, nil
+}

modules/artifact-store-tools/cmd/artifact-store-tools/read_test.go

@@ -0,0 +1,38 @@
+package main
+
+import "testing"
+
+func TestManifestsAreReadFromTheStoresFilesAndAMissingOneIsSaid(t *testing.T) {
+	got, err := parseManifests("#manifest blobs/sha256/aa/aa1/data\n"+image(d("cfg"), d("l"))+"\n\n#manifest blobs/sha256/bb/bb1/data\n#absent\n#manifest blobs/sha256/cc/cc1/data\nnot json\n#end\n",
+		map[string]string{"blobs/sha256/aa/aa1/data": "sha256:aa1", "blobs/sha256/bb/bb1/data": "sha256:bb1", "blobs/sha256/cc/cc1/data": "sha256:cc1"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if m := got["sha256:aa1"]; m == nil || len(m.Layers) != 1 || m.Layers[0] != d("l") {
+		t.Errorf("aa1 %+v", m)
+	}
+	if got["sha256:bb1"] != nil || got["sha256:cc1"] != nil {
+		t.Error("an absent or unreadable manifest was read as one")
+	}
+	if _, err := parseManifests("#manifest x\n{}\n", map[string]string{"x": "sha256:x"}); err == nil {
+		t.Error("a cut read was accepted")
+	}
+
+	f := world()
+	delete(f.manifests, d("m-old"))
+	v := view(t, f)
+	if v.Unread[Key("app/server", d("m-old"))] == "" {
+		t.Error("a manifest whose content is gone was not said as unread")
+	}
+	if out := Usage(v, 3); out["unread"] == nil {
+		t.Error("the answer did not say a manifest was unread")
+	}
+}
+
+func TestADigestNeverBecomesAPathOutsideTheBlobs(t *testing.T) {
+	for _, bad := range []string{"sha256:", "nocolon", "sha256:a/../../etc", "sha256:ab cd"} {
+		if p := blobPath(bad); p != "" {
+			t.Errorf("%q became %q", bad, p)
+		}
+	}
+}

modules/artifact-store-tools/cmd/artifact-store-tools/records.go

@@ -0,0 +1,209 @@
+package main
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strconv"
+	"strings"
+)
+
+// What the records say, asked of the controller and never copied (novox/hq ADR 0251 §2). The
+// controller decides what the mesh keeps; this bundle only sets that beside what the store holds.
+
+// Asking is how a tool on the mesh is asked: stdio.Ask, or a test's.
+type Asking func(key string, body any) (json.RawMessage, error)
+
+// ControllerSeat is the seat whose verbs the controller serves.
+const ControllerSeat = "mesh-controller"
+
+// Record is one reference the mesh recorded making, as the controller's `artifacts` answers it.
+type Record struct {
+	Reference  string   `json:"reference"`
+	Repository string   `json:"repository,omitempty"`
+	Digest     string   `json:"digest,omitempty"`
+	Kind       string   `json:"kind,omitempty"`
+	State      string   `json:"state"`
+	Why        []string `json:"why,omitempty"`
+}
+
+// Records is the controller's `artifacts` answer.
+type Records struct {
+	Store      string         `json:"store"`
+	KeptBuilds int            `json:"kept_builds"`
+	Counts     map[string]int `json:"counts"`
+	References []Record       `json:"references"`
+	// CollectedAsked is whether the references already let go of were asked for too.
+	CollectedAsked bool `json:"-"`
+	// Note says what could not be asked, when something could not.
+	Note string `json:"-"`
+}
+
+// CollectAnswer is the controller's `collect` answer.
+type CollectAnswer struct {
+	DryRun         bool     `json:"dry_run"`
+	Store          string   `json:"store"`
+	KeptArchives   int      `json:"kept_archives"`
+	Held           int      `json:"held"`
+	HoldersWritten int      `json:"holders_written"`
+	Missing        int      `json:"missing"`
+	Eligible       int      `json:"eligible"`
+	WouldLetGo     []string `json:"would_let_go"`
+	LetGo          []string `json:"let_go"`
+	Skipped        int      `json:"skipped"`
+	Left           int      `json:"left"`
+	Stopped        string   `json:"stopped"`
+	// Rest is whatever else the controller said, passed on as it said it.
+	Rest map[string]json.RawMessage `json:"-"`
+}
+
+// Controller asks the controller's seat through the runtime.
+type Controller struct{ Ask Asking }
+
+// answerOf reads a verb's answer whatever wraps it: the controller's {output, ok, answer}, a text the
+// runtime handed over, or the protocol's content list.
+func answerOf(raw json.RawMessage) (json.RawMessage, string, bool) {
+	var s string
+	if json.Unmarshal(raw, &s) == nil {
+		return answerOf(json.RawMessage(s))
+	}
+	var m map[string]json.RawMessage
+	if json.Unmarshal(raw, &m) != nil {
+		return raw, string(raw), true
+	}
+	if content, has := m["content"]; has {
+		var items []struct {
+			Text string `json:"text"`
+		}
+		var e struct {
+			IsError bool `json:"isError"`
+		}
+		_ = json.Unmarshal(raw, &e)
+		if json.Unmarshal(content, &items) == nil && len(items) > 0 {
+			inner, out, ok := answerOf(json.RawMessage(items[0].Text))
+			return inner, out, ok && !e.IsError
+		}
+	}
+	var v struct {
+		Output string          `json:"output"`
+		OK     *bool           `json:"ok"`
+		Answer json.RawMessage `json:"answer"`
+	}
+	if json.Unmarshal(raw, &v) == nil && v.OK != nil {
+		return v.Answer, v.Output, *v.OK
+	}
+	return raw, string(raw), true
+}
+
+func (c Controller) verb(name string, args map[string]any) (json.RawMessage, error) {
+	if c.Ask == nil {
+		return nil, errors.New("this bundle has no way to ask the controller")
+	}
+	raw, err := c.Ask("seat:"+ControllerSeat+"."+name, args)
+	if err != nil {
+		return nil, fmt.Errorf("the controller's %s could not be asked: %w", name, err)
+	}
+	answer, output, ok := answerOf(raw)
+	if !ok {
+		return nil, fmt.Errorf("the controller refused %s: %s", name, lastLine(output))
+	}
+	if len(answer) == 0 || string(answer) == "null" {
+		return nil, fmt.Errorf("the controller's %s answered no data: %s", name, lastLine(output))
+	}
+	return answer, nil
+}
+
+func lastLine(s string) string {
+	lines := strings.Split(strings.TrimSpace(s), "\n")
+	return strings.TrimSpace(lines[len(lines)-1])
+}
+
+// Artifacts asks what the records say, with the references already let go of when the answer can carry
+// them; when it cannot, without, and says so.
+func (c Controller) Artifacts(repository string) (*Records, error) {
+	args := map[string]any{"collected": "true"}
+	if repository != "" {
+		args["repository"] = repository
+	}
+	raw, err := c.verb("artifacts", args)
+	collected := true
+	note := ""
+	if err != nil {
+		delete(args, "collected")
+		var again error
+		raw, again = c.verb("artifacts", args)
+		if again != nil {
+			return nil, again
+		}
+		collected = false
+		note = "the references the mesh already let go of could not be asked for (" + err.Error() +
+			"), so a manifest the mesh let go of that the store still holds is counted as unrecorded"
+	}
+	var r Records
+	if err := json.Unmarshal(raw, &r); err != nil {
+		return nil, fmt.Errorf("the controller's artifacts answer is not readable: %v", err)
+	}
+	for i := range r.References {
+		fill(&r.References[i])
+	}
+	r.CollectedAsked, r.Note = collected, note
+	return &r, nil
+}
+
+// Collect asks the controller's sweep: a dry run unless confirm, which needs why.
+func (c Controller) Collect(why string, confirm bool, most int) (*CollectAnswer, error) {
+	args := map[string]any{}
+	if confirm {
+		if strings.TrimSpace(why) == "" {
+			return nil, errors.New("a real collection needs why: nothing was asked")
+		}
+		args["why"] = why
+		args["confirm"] = "true"
+	}
+	if most > 0 {
+		args["most"] = strconv.Itoa(most)
+	}
+	raw, err := c.verb("collect", args)
+	if err != nil {
+		return nil, err
+	}
+	var a CollectAnswer
+	if err := json.Unmarshal(raw, &a); err != nil {
+		return nil, fmt.Errorf("the controller's collect answer is not readable: %v", err)
+	}
+	_ = json.Unmarshal(raw, &a.Rest)
+	if !confirm && !a.DryRun && len(a.LetGo) > 0 {
+		return nil, fmt.Errorf("the controller let go of %d artifacts when only a dry run was asked", len(a.LetGo))
+	}
+	return &a, nil
+}
+
+// fill reads the repository, digest and kind out of a reference when the answer left them out.
+func fill(r *Record) {
+	repo, digest, kind := splitReference(r.Reference)
+	if r.Repository == "" {
+		r.Repository = repo
+	}
+	if r.Digest == "" {
+		r.Digest = digest
+	}
+	if r.Kind == "" {
+		r.Kind = kind
+	}
+}
+
+// splitReference reads `artifact-store://<repo>@sha256:…` (an image) and
+// `artifact-store://<repo>/blobs/sha256:…` (an archive).
+func splitReference(ref string) (repo, digest, kind string) {
+	path := ref
+	if _, after, ok := strings.Cut(ref, "://"); ok {
+		path = after
+	}
+	if before, after, ok := strings.Cut(path, "/blobs/sha256:"); ok {
+		return before, "sha256:" + after, "archive"
+	}
+	if before, after, ok := strings.Cut(path, "@sha256:"); ok {
+		return before, "sha256:" + after, "image"
+	}
+	return "", "", ""
+}