n8n: its own image built from source, placed data, and what its workflows use

The module named /var/lib/n8n, /services/n8n/n8n-data and n8n.novox.be -
paths and a domain no definition may carry (ADR 0112). State and data are
placed directories; the public name is ${bound:route:name} (depends on
mesh-controller #149), for N8N_HOST and WEBHOOK_URL alike.

The endpoint said 5682 while the container publishes 5678. 5682 was one
machine's host port; the endpoint is the software's port and the mesh
assigns the machine's (ADR 0038).

n8n had been run from an image in a registry that no longer exists: the
upstream image plus shadow, a `media` group (2000) with `node` in it, and
a global `uuid`. That recipe is now this module's Dockerfile, built on the
upstream 1.71.3 image named in build.on by digest, with uuid pinned to the
version the running image carries (14.0.1) - Code nodes require() it. The
media group is how the container writes into the shared media library, a
read-write `access` (ADR 0051), mounted where workflows expect it,
/media-library.

The workflows also use a redis (the Redis nodes of the chat workflows) and a
Selenium Chrome (the scraper), which the previous deployment ran beside n8n.
Both are containers on the module's own network, publishing nothing, pinned
to the digests in use; redis keeps its append-only file in a placed
directory.

The basic-auth secret is gone: N8N_BASIC_AUTH_* was removed in n8n 1.0 and
did nothing. The grant's password is a 0400 file owned by `node`, read
through DB_POSTGRESDB_PASSWORD_FILE, so nothing secret is in the
environment. The credentials' encryption key is n8n's own, in the data
directory (config), and moves with it - nothing to mint or accept.

Verified: catalogue tests with MESH_CATALOGUE set; the Dockerfile built
against the pinned base gives n8n 1.71.3, uid 1000 in group 2000, uuid
14.0.1 - the running image's shape. Throwaway containers: an instance on
PostgreSQL 15 with an owner, a workflow and an encrypted credential;
stopped, copied, dumped from the copy, restored (--no-owner --role, the
uuid-ossp extension pre-made by the superuser) into a grant-shaped
database on the postgres module's pgvector image (PG17); the new shape
(password from the file, data dir copied) serves /healthz, the owner logs
in, the workflow is listed, and the credential decrypts with the carried
key. The node user writes into a root:2000 0775 library through the media
group; redis and Selenium resolve by name on the module network and
Selenium reports ready. Test containers and data removed.

modules/anthropic-consumer/Dockerfile

@@ -0,0 +1,22 @@
+# 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/module.json

@@ -9,20 +9,29 @@
     "model-access"
   ],
   "binds": {
-    "model-access": "${dir:state}/model.json"
+    "model-access": "/var/lib/anthropic-consumer/model.json"
   },
   "secrets": {
-    "model-access": "${dir:state}/access-token"
+    "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",
-      "mode": "0700",
-      "place": "."
+      "path": "/var/lib/anthropic-consumer",
+      "mode": "0700"
     },
     {
       "id": "claude-home",
@@ -33,43 +42,71 @@
     {
       "id": "out",
       "type": "directory",
+      "path": "/var/lib/anthropic-consumer/out",
       "mode": "0700"
     },
     {
       "id": "apply",
-      "type": "process",
-      "name": "anthropic-consumer-apply",
-      "artifact": "code",
-      "run": [
-        "node",
-        "apply/index.js"
-      ],
+      "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": "${dir:state}/access-token",
-        "MESH_MODEL_ACCESS_BIND_FILE": "${dir:state}/model.json",
-        "MESH_CLAUDE_CREDENTIALS_FILE": "${dir:state}/claude/.credentials.json",
-        "MESH_CLAUDE_IDENTITY_FILE": "${dir:state}/claude/.claude.json"
-      }
+        "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": "code",
-        "kind": "bundle",
-        "language": "typescript",
-        "entrypoints": [
-          "apply/index.js",
-          "usage/index.js"
-        ],
-        "loads": [
-          "usage/index.js"
-        ],
-        "env": {
-          "MESH_CLAUDE_PROJECTS_DIR": "${dir:state}/claude/projects",
-          "MESH_ANTHROPIC_USAGE_OUT": "${dir:state}/out/session-usage.json"
-        }
+        "name": "runtime",
+        "kind": "image",
+        "from": "Dockerfile"
       }
     ]
   }

modules/anthropic-consumer/usage/index.ts

@@ -3,15 +3,12 @@
 // 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 in the node's runtime (novox/hq ADR 0198), every five minutes, so events are emitted through
-// the runtime as this module; the totals are also written to a file so the reading is observable
-// without one.
+// 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 { emit } from "@novox/mesh-sdk/events";
-
 import { readSessionFile, type SessionUsage } from "../transcript.js";
 
 /** The vendor-neutral usage row ADR 0054 fixes — the shape the model-usage store upserts. Kept local
@@ -119,20 +116,22 @@ function atomicWrite(path: string, content: string): void {
   renameSync(tmp, path);
 }
 
-/** Emit best-effort through the runtime: a reading that could not be announced is still in the file. */
+/** 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> {
-  try {
-    await emit("usage.session", body);
-  } catch (err) {
-    console.error(`[anthropic-consumer] could not emit usage: ${err}`);
-  }
+  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();
+    });
+  });
 }
 
-// The cadence the scheduled container had: once at start, then every five minutes. Not awaited, so the
-// runtime's handshake is answered while a long first reading is still under way.
-const EVERY_MS = 5 * 60 * 1000;
-const tick = (): void => {
-  void main().catch((err) => console.error(`[anthropic-consumer] usage reading failed: ${err}`));
-};
-tick();
-setInterval(tick, EVERY_MS);
+await main();

modules/anthropic-manager/module.json

@@ -9,13 +9,13 @@
     "model-access"
   ],
   "binds": {
-    "model-access": "${dir:mesh-state}/model.json"
+    "model-access": "/var/lib/mesh/anthropic-manager/model.json"
   },
   "secrets": {
-    "model-access": "${dir:mesh-state}/refresh-token"
+    "model-access": "/var/lib/mesh/anthropic-manager/refresh-token"
   },
   "own-secrets": {
-    "broker": "${dir:mesh-state}/broker"
+    "broker": "/var/lib/mesh/anthropic-manager/broker"
   },
   "emits": [
     "usage.read"
@@ -24,13 +24,13 @@
     {
       "id": "mesh-state",
       "type": "directory",
-      "mode": "0700",
-      "place": "mesh"
+      "path": "/var/lib/mesh/anthropic-manager",
+      "mode": "0700"
     },
     {
       "id": "out",
       "type": "directory",
-      "path": "${dir:mesh-state}/out",
+      "path": "/var/lib/mesh/anthropic-manager/out",
       "mode": "0700"
     },
     {
@@ -45,8 +45,8 @@
         "/app/modules/anthropic-manager/dist/refresh/index.js"
       ],
       "volumes": [
-        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
-        "${dir:mesh-state}:/run/state"
+        "/var/lib/mesh/anthropic-manager/broker:/run/secrets/broker:ro",
+        "/var/lib/mesh/anthropic-manager:/run/state"
       ],
       "env": {
         "MESH_BROKER_FILE": "/run/secrets/broker",

modules/audit-logger/Dockerfile

@@ -0,0 +1,33 @@
+# audit-logger's runtime: the shared runtime image, carrying this module's compiled code.
+#
+# **Built from this module's own directory and nothing else.** The toolkit is in the base image, so
+# nothing is copied out of a neighbouring checkout — which is what lets the mesh build this from a
+# repository and a path (novox/hq ADR 0069) rather than only on a workstation that happens to have
+# the siblings laid out beside it.
+
+# Two bases, named rather than pinned: the image this is COMPILED in, and the image it RUNS in.
+# They are different images on purpose — the first carries a compiler and the second must not, or
+# every running container would carry one it never invokes. The mesh answers both with the copies it
+# holds, because a fingerprint written here would name one particular copy and no other mesh has it
+# (novox/hq issue 044). Declared in module.json's `build.on`; deliberately no defaults, so a build
+# nobody told stops here and says which module to build first.
+ARG BUILD_BASE
+ARG RUNTIME_BASE
+
+FROM ${BUILD_BASE} AS build
+# Compiled under /app/modules so `@novox/mesh-sdk` resolves upward into the base's own
+# node_modules — the module is compiled against exactly the toolkit it will run against.
+WORKDIR /app/modules/audit-logger
+COPY . .
+# The compiler is invoked by its real path rather than through node_modules/.bin, whose entries are
+# symlinks to a launcher that requires its library relatively — resolved away when the base image
+# was assembled.
+RUN node /app/node_modules/typescript/bin/tsc audit.ts index.ts \
+      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
+
+FROM ${RUNTIME_BASE}
+COPY --from=build /app/modules/audit-logger/dist /app/modules/audit-logger/dist
+# **Served, not run.** This subscribes on import, and the serve mode binds the broker before it
+# imports anything — `run` exists for a step that works offline and exits, and would leave this
+# with nothing to subscribe to.
+ENV MESH_TOOL_MODULES=/app/modules/audit-logger/dist/index.js

modules/audit-logger/module.json

@@ -5,21 +5,27 @@
   "consumes": [
     "**"
   ],
+  "own-secrets": {
+    "broker": "/var/lib/audit-logger/broker"
+  },
   "build": {
+    "on": [
+      {
+        "arg": "BUILD_BASE",
+        "module": "mesh-tools",
+        "artifact": "build"
+      },
+      {
+        "arg": "RUNTIME_BASE",
+        "module": "mesh-tools",
+        "artifact": "runtime"
+      }
+    ],
     "artifacts": [
       {
-        "name": "code",
-        "kind": "bundle",
-        "language": "typescript",
-        "entrypoints": [
-          "index.js"
-        ],
-        "loads": [
-          "index.js"
-        ],
-        "env": {
-          "AUDIT_LOG": "${dir:trail}/audit.log"
-        }
+        "name": "runtime",
+        "kind": "image",
+        "from": "Dockerfile"
       }
     ]
   },
@@ -27,13 +33,29 @@
     {
       "id": "state",
       "type": "directory",
-      "mode": "0700",
-      "place": "."
+      "path": "/var/lib/audit-logger",
+      "mode": "0700"
     },
     {
       "id": "trail",
       "type": "directory",
+      "path": "/var/lib/audit-logger/trail",
       "mode": "0700"
+    },
+    {
+      "id": "run",
+      "type": "container",
+      "name": "mesh-audit-logger",
+      "network": "host",
+      "volumes": [
+        "/var/lib/audit-logger/broker:/run/secrets/broker:ro",
+        "/var/lib/audit-logger/trail:/trail"
+      ],
+      "env": {
+        "MESH_BROKER_FILE": "/run/secrets/broker",
+        "AUDIT_LOG": "/trail/audit.log"
+      },
+      "artifact": "runtime"
     }
   ],
   "capabilities": [

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

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

modules/baserow/Dockerfile

@@ -0,0 +1,24 @@
+# baserow'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/baserow
+COPY . .
+RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts \
+      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
+
+FROM ${RUNTIME_BASE}
+COPY --from=build /app/modules/baserow/dist /app/modules/baserow/dist
+# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
+# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
+# the convention novox/hq issues 060/061 settled.
+ENV MESH_TOOL_MODULES=/app/modules/baserow/dist/tools/index.js

modules/baserow/module.json

@@ -25,7 +25,8 @@
     "postgres-database": "${dir:state}/database.secret"
   },
   "own-secrets": {
-    "admin": "${dir:state}/admin.secret"
+    "admin": "${dir:state}/admin.secret",
+    "broker": "/var/lib/mesh/baserow/broker"
   },
   "listens": [
     {
@@ -40,8 +41,8 @@
     {
       "id": "mesh-state",
       "type": "directory",
-      "mode": "0700",
-      "place": "mesh"
+      "path": "/var/lib/mesh/baserow",
+      "mode": "0700"
     },
     {
       "id": "state",
@@ -87,28 +88,49 @@
     {
       "id": "runtime-config",
       "type": "file",
-      "path": "${dir:mesh-state}/config.json",
+      "path": "/var/lib/mesh/baserow/config.json",
       "mode": "0600",
       "content": "{\n  \"password\": \"${secret:admin}\",\n  \"host\": \"${bound:route:name}\"\n}\n",
       "merge": "json"
+    },
+    {
+      "id": "runtime",
+      "type": "container",
+      "name": "mesh-baserow",
+      "network": "baserow",
+      "volumes": [
+        "/var/lib/mesh/baserow/broker:/run/secrets/broker:ro",
+        "/var/lib/mesh/baserow/config.json:/run/config/config.json:ro"
+      ],
+      "env": {
+        "MESH_BROKER_FILE": "/run/secrets/broker",
+        "MESH_BASEROW_URL": "http://baserow:80",
+        "MESH_BASEROW_CONFIG_FILE": "/run/config/config.json"
+      },
+      "restart-on": [
+        "runtime-config"
+      ],
+      "artifact": "runtime"
     }
   ],
   "build": {
+    "on": [
+      {
+        "arg": "BUILD_BASE",
+        "module": "mesh-tools",
+        "artifact": "build"
+      },
+      {
+        "arg": "RUNTIME_BASE",
+        "module": "mesh-tools",
+        "artifact": "runtime"
+      }
+    ],
     "artifacts": [
       {
-        "name": "tools",
-        "kind": "bundle",
-        "language": "typescript",
-        "entrypoints": [
-          "tools/index.js"
-        ],
-        "loads": [
-          "tools/index.js"
-        ],
-        "env": {
-          "MESH_BASEROW_URL": "http://127.0.0.1:${port:80}",
-          "MESH_BASEROW_CONFIG_FILE": "${dir:mesh-state}/config.json"
-        }
+        "name": "runtime",
+        "kind": "image",
+        "from": "Dockerfile"
       }
     ]
   }

modules/bazarr/Dockerfile

@@ -0,0 +1,24 @@
+# bazarr'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/bazarr
+COPY . .
+RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts \
+      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
+
+FROM ${RUNTIME_BASE}
+COPY --from=build /app/modules/bazarr/dist /app/modules/bazarr/dist
+# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
+# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
+# the convention novox/hq issues 060/061 settled.
+ENV MESH_TOOL_MODULES=/app/modules/bazarr/dist/index.js,/app/modules/bazarr/dist/tools/index.js

modules/bazarr/client.ts

@@ -0,0 +1,173 @@
+// The Bazarr API client — bazarr's own code, living in the module (novox/hq ADR 0039). Bazarr
+// manages subtitles for a Sonarr/Radarr library: it tracks which episodes and movies are still
+// missing subtitles, searches providers for them, and records what it downloaded. This client
+// talks its /api surface (keyed by an X-API-KEY header); bazarr's tools and events import it.
+
+import { readFileSync } from "node:fs";
+
+export interface WantedSubtitle {
+  kind: "episode" | "movie";
+  title: string; // series + episode, or movie title
+  path?: string;
+  seriesId?: number; // sonarr series id (episodes)
+  episodeId?: number; // sonarr episode id (episodes)
+  radarrId?: number; // radarr movie id (movies)
+  missing: string[]; // language names still missing
+}
+
+export interface ProviderSubtitle {
+  provider: string;
+  language: string;
+  hearingImpaired: boolean;
+  forced: boolean;
+  score?: number;
+  release?: string;
+  subtitle: string; // the opaque token Bazarr uses to download this exact result
+}
+
+export interface HistoryEntry {
+  kind: "episode" | "movie";
+  id: string; // stable dedup key across polls
+  title: string;
+  language?: string;
+  provider?: string;
+  path?: string;
+  timestamp?: string;
+  description?: string;
+}
+
+/** The settings-merged config the mesh delivers (novox/hq ADR 0046): { url, apiKey, token, password, user, ... }. */
+function meshConfig(file?: string): Record<string, string> {
+  if (!file) return {};
+  try { return JSON.parse(readFileSync(file, "utf8")) as Record<string, string>; }
+  catch { return {}; }
+}
+
+/** Read a secret the mesh mounted at a file path (an own-secret delivered by `secret accept`);
+ *  absent or unreadable yields undefined so callers fall back rather than crash. */
+function readSecret(file?: string): string | undefined {
+  if (!file) return undefined;
+  try { return readFileSync(file, "utf8").trim(); }
+  catch { return undefined; }
+}
+
+export class BazarrClient {
+  readonly baseUrl: string;
+
+  constructor(
+    url: string,
+    private readonly apiKey: string,
+  ) {
+    this.baseUrl = url.replace(/\/$/, "");
+  }
+
+  /** Build from the module's resolved environment. Bazarr's API is keyed; without URL and key
+   *  there is nothing to talk to, so this throws rather than run half-configured. */
+  static fromEnv(env: NodeJS.ProcessEnv = process.env): BazarrClient {
+    const cfg = meshConfig(env.MESH_BAZARR_CONFIG_FILE);
+    const url = cfg.url ?? env.MESH_BAZARR_URL;
+    const apiKey = cfg.apiKey ?? readSecret(env.MESH_BAZARR_API_KEY_FILE) ?? env.MESH_BAZARR_API_KEY;
+    if (!url) throw new Error("no Bazarr URL — set MESH_BAZARR_URL");
+    if (!apiKey) throw new Error("no Bazarr API key — set MESH_BAZARR_API_KEY");
+    return new BazarrClient(url, apiKey);
+  }
+
+  private async request(method: string, path: string, params: Record<string, string> = {}): Promise<any> {
+    const url = new URL(`${this.baseUrl}/api${path}`);
+    for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
+    const res = await fetch(url.toString(), { method, headers: { "X-API-KEY": this.apiKey, Accept: "application/json" } });
+    if (!res.ok) throw new Error(`Bazarr API ${method} ${path}: ${res.status} ${await res.text()}`);
+    // Downloads/patches return an empty body; only GETs carry JSON.
+    const text = await res.text();
+    return text ? JSON.parse(text) : {};
+  }
+
+  private get(path: string, params?: Record<string, string>): Promise<any> {
+    return this.request("GET", path, params);
+  }
+
+  private languageNames(missing: any[]): string[] {
+    return (missing ?? []).map((m: any) => m?.name ?? m?.code2 ?? m?.code3).filter(Boolean);
+  }
+
+  /** Episodes and movies still missing subtitles — Bazarr's core "what's left to do" list. */
+  async getWanted(limit = 50): Promise<WantedSubtitle[]> {
+    const [eps, movies] = await Promise.all([
+      this.get("/episodes/wanted", { start: "0", length: String(limit) }),
+      this.get("/movies/wanted", { start: "0", length: String(limit) }),
+    ]);
+    const episodes: WantedSubtitle[] = (eps?.data ?? []).map((e: any) => ({
+      kind: "episode" as const,
+      title: `${e.seriesTitle ?? e.series ?? "Unknown"} — ${e.episodeTitle ?? e.episode_title ?? ""}`.trim(),
+      path: e.path,
+      seriesId: e.sonarrSeriesId,
+      episodeId: e.sonarrEpisodeId,
+      missing: this.languageNames(e.missing_subtitles),
+    }));
+    const films: WantedSubtitle[] = (movies?.data ?? []).map((m: any) => ({
+      kind: "movie" as const,
+      title: m.title ?? "Unknown",
+      path: m.path,
+      radarrId: m.radarrId,
+      missing: this.languageNames(m.missing_subtitles),
+    }));
+    return [...episodes, ...films];
+  }
+
+  /** Ask providers what subtitles are available for one wanted episode — a manual search. */
+  async searchEpisode(episodeId: number): Promise<ProviderSubtitle[]> {
+    const raw = await this.get("/providers/episodes", { episodeid: String(episodeId) });
+    return this.mapProviderResults(raw);
+  }
+
+  /** Ask providers what subtitles are available for one movie — a manual search. */
+  async searchMovie(radarrId: number): Promise<ProviderSubtitle[]> {
+    const raw = await this.get("/providers/movies", { radarrid: String(radarrId) });
+    return this.mapProviderResults(raw);
+  }
+
+  private mapProviderResults(raw: any): ProviderSubtitle[] {
+    const list = Array.isArray(raw) ? raw : (raw?.data ?? []);
+    return list.map((r: any) => ({
+      provider: r.provider,
+      language: r.language?.name ?? r.language ?? "unknown",
+      hearingImpaired: Boolean(r.hearing_impaired ?? r.hi),
+      forced: Boolean(r.forced),
+      score: r.score,
+      release: r.release_info?.[0] ?? r.release_info,
+      subtitle: r.subtitle,
+    }));
+  }
+
+  /** Recent subtitle-download history, episodes and movies together, newest first. Each entry
+   *  carries a stable id so the events poller can tell a fresh download from one already seen. */
+  async getHistory(limit = 40): Promise<HistoryEntry[]> {
+    const [eps, movies] = await Promise.all([
+      this.get("/episodes/history", { start: "0", length: String(limit) }),
+      this.get("/movies/history", { start: "0", length: String(limit) }),
+    ]);
+    const key = (kind: string, r: any): string =>
+      `${kind}:${r.timestamp ?? r.parsed_timestamp ?? ""}:${r.subtitles_path ?? r.path ?? ""}:${r.language?.code3 ?? r.language ?? ""}`;
+    const episodes: HistoryEntry[] = (eps?.data ?? []).map((r: any) => ({
+      kind: "episode" as const,
+      id: key("episode", r),
+      title: `${r.seriesTitle ?? "Unknown"} — ${r.episodeTitle ?? ""}`.trim(),
+      language: r.language?.name ?? r.language,
+      provider: r.provider,
+      path: r.subtitles_path,
+      timestamp: r.timestamp,
+      description: r.description,
+    }));
+    const films: HistoryEntry[] = (movies?.data ?? []).map((r: any) => ({
+      kind: "movie" as const,
+      id: key("movie", r),
+      title: r.title ?? "Unknown",
+      language: r.language?.name ?? r.language,
+      provider: r.provider,
+      path: r.subtitles_path,
+      timestamp: r.timestamp,
+      description: r.description,
+    }));
+    return [...episodes, ...films];
+  }
+}

modules/bazarr/index.ts

@@ -0,0 +1,47 @@
+// bazarr's events. The tool runtime imports this once the broker is bound. Bazarr's one genuinely
+// observable thing is a subtitle arriving: it works away in the background, searching providers for
+// the missing-subtitle list, and when it succeeds a subtitle appears in its history. That is worth
+// announcing to the mesh.
+//
+// Emits (novox/hq ADR 0041/0042):
+//   module.bazarr.subtitle.downloaded   — a subtitle was fetched for an episode or movie
+//
+// Bazarr has nothing on the mesh it usefully reacts to (a download completing is Sonarr/Radarr's
+// business, and they trigger Bazarr directly), so it consumes nothing — a pure emitter.
+//
+// The event is observation-based: poll history and diff. Primed silently on the first look, or a
+// restart would re-announce the whole recent history as freshly downloaded.
+
+import { emit } from "@novox/mesh-sdk/events";
+import { BazarrClient } from "./client.js";
+
+const bazarr = BazarrClient.fromEnv();
+
+const seen = new Set<string>();
+let primed = false;
+async function pollHistory(): Promise<void> {
+  const entries = await bazarr.getHistory(40);
+  for (const entry of entries) {
+    if (seen.has(entry.id)) continue;
+    if (primed) {
+      await emit("subtitle.downloaded", {
+        kind: entry.kind,
+        title: entry.title,
+        language: entry.language,
+        provider: entry.provider,
+        path: entry.path,
+      });
+    }
+    seen.add(entry.id);
+  }
+  primed = true;
+}
+
+const tick = (fn: () => Promise<void>, everyMs: number): void => {
+  const run = (): void => void fn().catch((err) => console.error(`[bazarr] ${err}`));
+  setInterval(run, everyMs);
+  run();
+};
+tick(pollHistory, 60_000);
+
+console.log("[bazarr] watching subtitle-download history");

modules/bazarr/module.json

@@ -0,0 +1,141 @@
+{
+  "module": "bazarr",
+  "version": "1",
+  "capabilities": [
+    "container-runtime"
+  ],
+  "emits": [
+    "subtitle.downloaded"
+  ],
+  "own-secrets": {
+    "broker": "/var/lib/mesh/bazarr/broker",
+    "api-key": "/var/lib/mesh/bazarr/api-key"
+  },
+  "listens": [
+    {
+      "name": "web",
+      "port": 6767,
+      "protocol": "tcp",
+      "from": "mesh",
+      "why": "managing subtitles"
+    }
+  ],
+  "accesses": [
+    {
+      "path": "/services/media/movies",
+      "mode": "read-write"
+    },
+    {
+      "path": "/services/media/series",
+      "mode": "read-write"
+    },
+    {
+      "path": "/services/media/anime",
+      "mode": "read-write"
+    },
+    {
+      "path": "/services/media/downloads",
+      "mode": "read"
+    }
+  ],
+  "resources": [
+    {
+      "id": "mesh-state",
+      "type": "directory",
+      "path": "/var/lib/mesh/bazarr",
+      "mode": "0700"
+    },
+    {
+      "id": "config",
+      "type": "directory",
+      "path": "/services/bazarr/config",
+      "mode": "0700",
+      "owner": "1000:1000"
+    },
+    {
+      "id": "server",
+      "type": "container",
+      "name": "bazarr",
+      "image": "lscr.io/linuxserver/bazarr@sha256:3a820372f19fcb2981ea19fe4b5382934d67414afaba974bce831ddda0a64a02",
+      "env": {
+        "PUID": "1000",
+        "PGID": "1000",
+        "TZ": "Etc/UTC"
+      },
+      "ports": [
+        "6767"
+      ],
+      "volumes": [
+        "/services/bazarr/config:/config",
+        "/services/media/movies:/movies",
+        "/services/media/series:/series",
+        "/services/media/anime:/anime",
+        "/services/media/downloads:/downloads"
+      ]
+    },
+    {
+      "id": "runtime-config",
+      "type": "file",
+      "path": "/var/lib/mesh/bazarr/config.json",
+      "mode": "0600",
+      "content": "{}\n",
+      "merge": "json"
+    },
+    {
+      "id": "runtime",
+      "type": "container",
+      "name": "mesh-bazarr",
+      "network": "host",
+      "volumes": [
+        "/var/lib/mesh/bazarr/broker:/run/secrets/broker:ro",
+        "/var/lib/mesh/bazarr/api-key:/run/secrets/api-key:ro",
+        "/var/lib/mesh/bazarr/config.json:/run/config/config.json:ro",
+        "/services/bazarr/config:/var/lib/bazarr/config:ro"
+      ],
+      "env": {
+        "MESH_BROKER_FILE": "/run/secrets/broker",
+        "MESH_BAZARR_URL": "http://127.0.0.1:6767",
+        "MESH_BAZARR_API_KEY_FILE": "/run/secrets/api-key",
+        "MESH_BAZARR_CONFIG_FILE": "/run/config/config.json",
+        "MESH_BAZARR_CONFIG_DIR": "/var/lib/bazarr/config"
+      },
+      "restart-on": [
+        "runtime-config"
+      ],
+      "artifact": "runtime"
+    }
+  ],
+  "requires": [
+    "route"
+  ],
+  "contributes": {
+    "route": {
+      "label": "subs",
+      "endpoint": "web"
+    }
+  },
+  "binds": {
+    "route": "/var/lib/mesh/bazarr/route.json"
+  },
+  "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/bazarr/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@novox/module-bazarr",
+  "version": "0.1.0",
+  "description": "bazarr — subtitle management. Its API client, tools and events live here (novox/hq ADR 0039).",
+  "type": "module",
+  "private": true,
+  "dependencies": {
+    "@novox/mesh-sdk": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}

modules/bazarr/tools/index.ts

@@ -0,0 +1,57 @@
+// bazarr's tools — its own code (novox/hq ADR 0039), importing bazarr's client. They return
+// structured data; the mesh serves them through the sdk's tool harness.
+
+import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
+import { BazarrClient } from "../client.js";
+
+export function getBazarrTools(bazarr: BazarrClient): ToolDefinition[] {
+  return [
+    {
+      name: "bazarr_wanted",
+      description: "Episodes and movies still missing subtitles, with the languages each still needs.",
+      input: { limit: { type: "number", description: "max items per kind (default 50)" } },
+      run: async (args) => {
+        const wanted = await bazarr.getWanted(args.limit ? Number(args.limit) : 50);
+        return { count: wanted.length, wanted };
+      },
+    },
+    {
+      name: "bazarr_search_subtitles",
+      description: "Manually search subtitle providers for one wanted item — pass an episodeId or a radarrId.",
+      input: {
+        episodeId: { type: "number", description: "a Sonarr episode id (from bazarr_wanted)" },
+        radarrId: { type: "number", description: "a Radarr movie id (from bazarr_wanted)" },
+      },
+      run: async (args) => {
+        if (args.episodeId !== undefined) {
+          const results = await bazarr.searchEpisode(Number(args.episodeId));
+          return { kind: "episode", episodeId: Number(args.episodeId), count: results.length, results };
+        }
+        if (args.radarrId !== undefined) {
+          const results = await bazarr.searchMovie(Number(args.radarrId));
+          return { kind: "movie", radarrId: Number(args.radarrId), count: results.length, results };
+        }
+        throw new Error("pass either episodeId or radarrId");
+      },
+    },
+    {
+      name: "bazarr_history",
+      description: "Recent subtitle-download history — what was downloaded, for which title, from which provider.",
+      input: { limit: { type: "number", description: "max entries per kind (default 40)" } },
+      run: async (args) => {
+        const history = await bazarr.getHistory(args.limit ? Number(args.limit) : 40);
+        return { count: history.length, history };
+      },
+    },
+  ];
+}
+
+// Exposed only when Bazarr is configured; otherwise bazarr contributes no tools rather than
+// failing the whole runtime.
+registerModuleTools("bazarr", (env) => {
+  try {
+    return getBazarrTools(BazarrClient.fromEnv(env));
+  } catch {
+    return [];
+  }
+});

modules/bazarr/tsconfig.json

@@ -8,8 +8,5 @@
     "skipLibCheck": true,
     "noEmit": true
   },
-  "include": [
-    "shell.ts",
-    "tools/index.ts"
-  ]
+  "include": ["client.ts", "index.ts", "tools/index.ts"]
 }

modules/bookshelf/Dockerfile

@@ -0,0 +1,24 @@
+# bookshelf'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/bookshelf
+COPY . .
+RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts \
+      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
+
+FROM ${RUNTIME_BASE}
+COPY --from=build /app/modules/bookshelf/dist /app/modules/bookshelf/dist
+# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
+# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
+# the convention novox/hq issues 060/061 settled.
+ENV MESH_TOOL_MODULES=/app/modules/bookshelf/dist/index.js,/app/modules/bookshelf/dist/tools/index.js

modules/bookshelf/client.ts

@@ -0,0 +1,136 @@
+// The Bookshelf API client — bookshelf's own code, living in the module (novox/hq ADR 0039).
+// Ported from the shared hal `arr` client, but self-contained: in nox each Servarr app owns its own
+// copy, so a change to Bookshelf's API rebuilds only bookshelf and nothing else. Both this module's
+// tools and its events entrypoint import it, and nothing outside bookshelf does.
+//
+// Bookshelf is a Readarr fork (ghcr.io/pennydreadful/bookshelf). It speaks the Servarr v1 API; its
+// content is "book". Unlike Sonarr/Radarr it exposes no calendar endpoint, so there is no calendar
+// tool here — matching hal, which excluded bookshelf from its calendar-capable apps.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+// Bookshelf speaks the v1 API; its content is "book".
+const API_VERSION = "v1";
+const CONTENT_ENDPOINT = "book";
+const APP_NAME = "Bookshelf";
+
+export interface BookshelfQueueItem {
+  /** The queue record id — stable while the item is in the queue, so events can diff on it. */
+  id: number;
+  title: string;
+  status: string;
+  size: string;
+  sizeleft: string;
+  timeleft?: string;
+}
+
+export interface BookshelfContentItem {
+  title: string;
+  author?: string;
+  year?: number;
+  status?: string;
+  monitored: boolean;
+}
+
+export class BookshelfClient {
+  readonly baseUrl: string;
+
+  constructor(
+    url: string,
+    private readonly apiKey: string,
+  ) {
+    this.baseUrl = url.replace(/\/$/, "");
+  }
+
+  /**
+   * Build from the module's resolved environment. The URL defaults to the server on this node (the
+   * runtime shares its network), and the API key is read from MESH_BOOKSHELF_API_KEY or, failing
+   * that, discovered from the server's own config.xml under MESH_BOOKSHELF_CONFIG_DIR — the same
+   * file Bookshelf writes it to, so a running server needs nothing configured by hand. Throws when
+   * no key can be found, so the tools/events simply do not load (the harness treats the throw as
+   * "exposes nothing").
+   */
+  static fromEnv(env: NodeJS.ProcessEnv = process.env): BookshelfClient {
+    const url = env.MESH_BOOKSHELF_URL ?? `http://127.0.0.1:${env.MESH_BOOKSHELF_PORT ?? "8787"}`;
+    const configDir = env.MESH_BOOKSHELF_CONFIG_DIR ?? "/config";
+    const apiKey = env.MESH_BOOKSHELF_API_KEY ?? BookshelfClient.detectApiKey(configDir);
+    if (!apiKey) {
+      throw new Error("Bookshelf not configured — set MESH_BOOKSHELF_API_KEY or make the config dir readable");
+    }
+    return new BookshelfClient(url, apiKey);
+  }
+
+  /** Discover the API key from the server's config.xml, falling back to null. Every Servarr app
+   *  writes <ApiKey> into config.xml at the root of its config directory. */
+  static detectApiKey(configDir: string): string | null {
+    const config = join(configDir, "config.xml");
+    if (existsSync(config)) {
+      const match = readFileSync(config, "utf8").match(/<ApiKey>([^<]+)<\/ApiKey>/);
+      if (match) return match[1];
+    }
+    return null;
+  }
+
+  private async get(endpoint: string, params?: Record<string, string>): Promise<unknown> {
+    const url = new URL(`${this.baseUrl}/api/${API_VERSION}/${endpoint}`);
+    if (params) {
+      for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
+    }
+    const res = await fetch(url.toString(), { headers: { "X-Api-Key": this.apiKey } });
+    if (!res.ok) throw new Error(`${APP_NAME} API /${endpoint}: ${res.status} ${await res.text()}`);
+    return res.json();
+  }
+
+  async getStatus(): Promise<{ appName: string; version: string }> {
+    const data = (await this.get("system/status")) as { appName?: string; version?: string };
+    return { appName: data.appName || APP_NAME, version: data.version ?? "unknown" };
+  }
+
+  async getContent(limit?: number): Promise<BookshelfContentItem[]> {
+    const data = await this.get(CONTENT_ENDPOINT);
+    const items: any[] = Array.isArray(data) ? data : ((data as any)?.records ?? []);
+    const mapped = items.map((item) => ({
+      title: item.title ?? "Unknown",
+      author: item.author?.authorName ?? item.authorName,
+      year: item.releaseDate ? new Date(item.releaseDate).getFullYear() : item.year,
+      status: item.status,
+      monitored: item.monitored ?? true,
+    }));
+    return limit ? mapped.slice(0, limit) : mapped;
+  }
+
+  /** Library search is a filter over existing content, not an indexer lookup — same as hal's. */
+  async searchContent(term: string): Promise<BookshelfContentItem[]> {
+    const all = await this.getContent();
+    const lower = term.toLowerCase();
+    return all.filter(
+      (item) =>
+        item.title.toLowerCase().includes(lower) ||
+        (item.author?.toLowerCase().includes(lower) ?? false),
+    );
+  }
+
+  async getQueue(): Promise<{ totalRecords: number; items: BookshelfQueueItem[] }> {
+    const data = (await this.get("queue", { pageSize: "50" })) as { totalRecords?: number; records?: any[] };
+    const records = data.records ?? [];
+    return {
+      totalRecords: data.totalRecords ?? records.length,
+      items: records.map((r) => ({
+        id: r.id,
+        title: r.title ?? r.book?.title ?? r.author?.authorName ?? "Unknown",
+        status: r.status ?? "unknown",
+        size: formatBytes(r.size ?? 0),
+        sizeleft: formatBytes(r.sizeleft ?? 0),
+        timeleft: r.timeleft,
+      })),
+    };
+  }
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes === 0) return "0 B";
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(1024));
+  return `${(bytes / Math.pow(1024, i)).toFixed(1)} ${units[i]}`;
+}

modules/bookshelf/index.ts

@@ -0,0 +1,74 @@
+// bookshelf's events. The tool runtime imports this once the broker is bound. It watches the
+// download queue and turns its comings and goings into mesh events — the same mechanism radarr uses,
+// applied to a Servarr book manager.
+//
+// Emits (novox/hq ADR 0041/0042):
+//   module.bookshelf.book.grabbed        — a release entered the queue (Bookshelf grabbed it)
+//   module.bookshelf.download.completed  — a release left the queue, imported. This routing key is
+//                                          what the plex module consumes (module.*.download.completed)
+//                                          to rescan, so a new audiobook becomes a visible item.
+// Consumes: none.
+//
+// NOTE: the hal bookshelf module emitted no events (its hooks only did install-time provisioning).
+// This queue watcher is new in nox, modelled exactly on radarr's — bookshelf is a Servarr app with
+// the same queue semantics, so the diff-and-emit pattern carries over unchanged.
+//
+// The queue is polled and diffed, primed silently on the first look (like plex's index.ts) so a
+// restart mid-download does not re-announce everything already in flight as freshly grabbed.
+
+import { emit } from "@novox/mesh-sdk/events";
+import { BookshelfClient, type BookshelfQueueItem } from "./client.js";
+
+// Building the client throws when Bookshelf has no URL/key yet. Like the tools (see tools/index.ts),
+// the events entrypoint must not crash the runtime for that — it stays idle until configured.
+function buildClient(): BookshelfClient | null {
+  try {
+    return BookshelfClient.fromEnv();
+  } catch {
+    return null;
+  }
+}
+
+const bookshelf = buildClient();
+
+// Bookshelf removes an item from the queue once it has been imported; a "warning"/"failed" status is
+// how a stuck or broken grab shows itself, so we do not call those a completion when they vanish.
+const FAILED_STATUSES = new Set(["failed", "warning"]);
+
+const inQueue = new Map<number, BookshelfQueueItem>();
+let primed = false;
+
+async function pollQueue(bookshelf: BookshelfClient): Promise<void> {
+  const { items } = await bookshelf.getQueue();
+  const now = new Map(items.map((i) => [i.id, i]));
+
+  if (primed) {
+    // Entered the queue since last look — Bookshelf grabbed a release.
+    for (const [id, item] of now) {
+      if (!inQueue.has(id)) await emit("book.grabbed", { title: item.title, status: item.status });
+    }
+    // Left the queue — imported and done, unless it was last seen failing.
+    for (const [id, item] of inQueue) {
+      if (!now.has(id) && !FAILED_STATUSES.has(item.status)) {
+        await emit("download.completed", { title: item.title });
+      }
+    }
+  }
+
+  inQueue.clear();
+  for (const [id, item] of now) inQueue.set(id, item);
+  primed = true;
+}
+
+const tick = (fn: () => Promise<void>, everyMs: number): void => {
+  const run = (): void => void fn().catch((err) => console.error(`[bookshelf] ${err}`));
+  setInterval(run, everyMs);
+  run();
+};
+
+if (bookshelf) {
+  tick(() => pollQueue(bookshelf), 30_000);
+  console.log("[bookshelf] watching the download queue, emitting grabs and completions");
+} else {
+  console.log("[bookshelf] not configured — events idle until an API key is available");
+}

modules/bookshelf/module.json

@@ -0,0 +1,118 @@
+{
+  "module": "bookshelf",
+  "version": "1",
+  "slug": "books",
+  "capabilities": [
+    "container-runtime"
+  ],
+  "emits": [
+    "book.grabbed",
+    "download.completed"
+  ],
+  "consumes": [],
+  "own-secrets": {
+    "broker": "/var/lib/mesh/bookshelf/broker"
+  },
+  "listens": [
+    {
+      "name": "web",
+      "port": 8787,
+      "protocol": "tcp",
+      "from": "mesh",
+      "why": "managing the ebook/audiobook library"
+    }
+  ],
+  "accesses": [
+    {
+      "path": "/services/media/books",
+      "mode": "read-write"
+    },
+    {
+      "path": "/services/media/downloads",
+      "mode": "read-write"
+    }
+  ],
+  "resources": [
+    {
+      "id": "mesh-state",
+      "type": "directory",
+      "path": "/var/lib/mesh/bookshelf",
+      "mode": "0700"
+    },
+    {
+      "id": "config",
+      "type": "directory",
+      "path": "/services/bookshelf/config",
+      "mode": "0700",
+      "owner": "1000:1000"
+    },
+    {
+      "id": "server",
+      "type": "container",
+      "name": "bookshelf",
+      "image": "ghcr.io/pennydreadful/bookshelf@sha256:388eecc94362580eae31ee0a454be6af516f8a311f8432a521c202fb475f4359",
+      "env": {
+        "PUID": "1000",
+        "PGID": "1000",
+        "TZ": "Etc/UTC"
+      },
+      "ports": [
+        "8787"
+      ],
+      "volumes": [
+        "/services/bookshelf/config:/config",
+        "/services/media/books:/books",
+        "/services/media/downloads:/downloads"
+      ]
+    },
+    {
+      "id": "runtime",
+      "type": "container",
+      "name": "mesh-bookshelf",
+      "network": "host",
+      "volumes": [
+        "/var/lib/mesh/bookshelf/broker:/run/secrets/broker:ro",
+        "/services/bookshelf/config:/var/lib/bookshelf/config:ro"
+      ],
+      "env": {
+        "MESH_BROKER_FILE": "/run/secrets/broker",
+        "MESH_BOOKSHELF_URL": "http://127.0.0.1:8787",
+        "MESH_BOOKSHELF_CONFIG_DIR": "/var/lib/bookshelf/config"
+      },
+      "artifact": "runtime"
+    }
+  ],
+  "requires": [
+    "route"
+  ],
+  "contributes": {
+    "route": {
+      "label": "books",
+      "endpoint": "web"
+    }
+  },
+  "binds": {
+    "route": "/var/lib/mesh/bookshelf/route.json"
+  },
+  "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/bookshelf/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@novox/module-bookshelf",
+  "version": "0.1.0",
+  "description": "bookshelf — ebook/audiobook management (Readarr fork). Its API client, tools and events live here (novox/hq ADR 0039).",
+  "type": "module",
+  "private": true,
+  "dependencies": {
+    "@novox/mesh-sdk": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}

modules/bookshelf/tools/index.ts

@@ -0,0 +1,69 @@
+// bookshelf's tools — ported from the shared hal `arr` sdk (novox/hq ADR 0039), importing
+// bookshelf's own client. They return structured data (not the pre-formatted text hal returned); the
+// mesh serves them through the sdk's tool harness. Bookshelf has no calendar endpoint, so there is
+// no calendar tool — matching hal, which excluded it from its calendar-capable apps.
+
+import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
+import { BookshelfClient } from "../client.js";
+
+export function getBookshelfTools(bookshelf: BookshelfClient): ToolDefinition[] {
+  return [
+    {
+      name: "bookshelf_status",
+      description: "Bookshelf status overview: version, book count, monitored count, queue size.",
+      input: {},
+      run: async () => {
+        const [status, content, queue] = await Promise.all([
+          bookshelf.getStatus(),
+          bookshelf.getContent(),
+          bookshelf.getQueue(),
+        ]);
+        return {
+          app: status.appName,
+          version: status.version,
+          books: content.length,
+          monitored: content.filter((c) => c.monitored).length,
+          queue: queue.totalRecords,
+        };
+      },
+    },
+    {
+      name: "bookshelf_library",
+      description: "List books from the Bookshelf library.",
+      input: { limit: { type: "number", description: "max items to return (default 50)" } },
+      run: async (args) => {
+        const items = await bookshelf.getContent(args.limit ? Number(args.limit) : 50);
+        return { count: items.length, books: items };
+      },
+    },
+    {
+      name: "bookshelf_search",
+      description:
+        "Search the Bookshelf library for books by title or author (filters existing content, not indexers).",
+      input: { query: { type: "string", description: "the search term" } },
+      run: async (args) => {
+        const query = String(args.query);
+        return { query, results: await bookshelf.searchContent(query) };
+      },
+    },
+    {
+      name: "bookshelf_queue",
+      description: "Show the Bookshelf download queue — what is downloading and how far along.",
+      input: {},
+      run: async () => {
+        const queue = await bookshelf.getQueue();
+        return { count: queue.totalRecords, items: queue.items };
+      },
+    },
+  ];
+}
+
+// The tools exist only when Bookshelf is configured; without a URL and key, bookshelf contributes
+// none rather than failing the whole runtime.
+registerModuleTools("bookshelf", (env) => {
+  try {
+    return getBookshelfTools(BookshelfClient.fromEnv(env));
+  } catch {
+    return [];
+  }
+});

modules/bookshelf/tsconfig.json

@@ -8,8 +8,5 @@
     "skipLibCheck": true,
     "noEmit": true
   },
-  "include": [
-    "tools/index.ts",
-    "client.ts"
-  ]
+  "include": ["client.ts", "index.ts", "tools/index.ts"]
 }

modules/build-agent/README.md

@@ -1,15 +0,0 @@
-# build-agent
-
-The mesh's build machine as a role every machine can hold (novox/hq ADR 0190). It holds the node seat
-`node-build-agent`: every holder pulls one build at a time from the role's one work queue when it is
-idle, so a tier of many images is built by as many machines as hold the seat and are online, and a
-machine that is off builds nothing and blocks nothing. The controller asks the role, never a machine;
-the outcome names the machine that built it.
-
-What a holding machine needs is what the builder always needed, said here once: a container runtime
-(the socket is mounted), the artifact store and the package registry as provisions, a workspace, and
-the bus credential. The code is `cmd/mesh-builder` in the mesh-controller repository, compiled from
-that repository's main (`build.artifacts[].context`); this module ships the packaging.
-
-Assign it to every machine with a container runtime. It replaces `builder`, the one-holder form of the
-same thing; retire that once this is assigned where it was.

modules/builder/Dockerfile

@@ -1,6 +1,6 @@
 ARG GO_BASE
 ARG ALPINE_BASE
-# build-agent's image: the build machine itself, compiled into a container (novox/hq ADR 0190).
+# builder's own image: the build machine itself, compiled into a container.
 #
 # **The source is not vendored here.** builder's actual code — cmd/mesh-builder, internal/builder,
 # internal/catalogue — lives in the mesh-controller repository, the same control plane it is one

modules/builder/module.json

@@ -1,14 +1,13 @@
 {
-  "module": "build-agent",
+  "module": "builder",
   "version": "1",
-  "slug": "agent",
   "capabilities": [
     "container-runtime"
   ],
   "claims": [
     {
-      "name": "node-build-agent",
-      "scope": "node"
+      "name": "mesh-build-machine",
+      "scope": "mesh"
     }
   ],
   "requires": [
@@ -16,48 +15,49 @@
     "npm-package-registry"
   ],
   "binds": {
-    "npm-package-registry": "${dir:mesh-state}/package-registry.json"
+    "npm-package-registry": "/var/lib/mesh/builder/package-registry.json"
   },
   "secrets": {
-    "npm-package-registry": "${dir:mesh-state}/package-registry.secret"
+    "npm-package-registry": "/var/lib/mesh/builder/package-registry.secret"
   },
   "own-secrets": {
-    "broker": "${dir:mesh-state}/broker"
+    "broker": "/var/lib/mesh/builder/broker"
   },
   "resources": [
     {
       "id": "mesh-state",
       "type": "directory",
-      "mode": "0700",
-      "place": "mesh"
+      "path": "/var/lib/mesh/builder",
+      "mode": "0700"
     },
     {
       "id": "workspace",
       "type": "directory",
+      "path": "/var/lib/builder/workspace",
       "mode": "0700"
     },
     {
-      "id": "agent-env",
+      "id": "builder-env",
       "type": "file",
-      "path": "${dir:mesh-state}/build-agent.env",
+      "path": "/var/lib/mesh/builder/builder.env",
       "mode": "0600",
-      "content": "MESH_BROKER_FILE=/run/mesh/broker\nMESH_NODE=${machine:name}\nMESH_REGISTRY=${bound:artifact-store:at}:${bound:artifact-store:port}\nMESH_PACKAGE_BINDING=/run/mesh/package-registry.json\nMESH_NPM_TOKEN_FILE=/run/mesh/package-registry.secret\nMESH_WORKSPACE=${dir:workspace}\n"
+      "content": "MESH_BROKER_FILE=/run/mesh/broker\nMESH_NODE=${machine:name}\nMESH_REGISTRY=${bound:artifact-store:at}:${bound:artifact-store:port}\nMESH_PACKAGE_BINDING=/run/mesh/package-registry.json\nMESH_NPM_TOKEN_FILE=/run/mesh/package-registry.secret\nMESH_WORKSPACE=/var/lib/builder/workspace\n"
     },
     {
       "id": "server",
       "type": "container",
-      "name": "mesh-build-agent",
+      "name": "mesh-builder",
       "artifact": "server",
       "env-file": [
-        "${dir:mesh-state}/build-agent.env"
+        "/var/lib/mesh/builder/builder.env"
       ],
       "volumes": [
-        "${dir:mesh-state}:/run/mesh:ro",
-        "${dir:workspace}:${dir:workspace}",
+        "/var/lib/mesh/builder:/run/mesh:ro",
+        "/var/lib/builder/workspace:/var/lib/builder/workspace",
         "/var/run/docker.sock:/var/run/docker.sock"
       ],
       "restart-on": [
-        "agent-env"
+        "builder-env"
       ],
       "network": "host"
     }

modules/claude-code/README.md

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

modules/claude-code/grant.ts

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

modules/claude-code/identity.ts

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

modules/claude-code/module.json

@@ -1,90 +0,0 @@
-{
-  "module": "claude-code",
-  "version": "1",
-  "slug": "agent",
-  "capabilities": [
-    "package-manager"
-  ],
-  "requires": [
-    "mcp-endpoint"
-  ],
-  "binds": {
-    "mcp-endpoint": "${dir:state}/mcp-endpoint.json"
-  },
-  "consumes": [
-    "claude-licence-manager.licence.rotated",
-    "claude-licence-manager.licence.switched"
-  ],
-  "state": [
-    "servers"
-  ],
-  "tools": [
-    "claude_code_status",
-    "claude_code_render",
-    "claude_code_pull",
-    "claude_code_mcp_list",
-    "claude_code_mcp_register",
-    "claude_code_mcp_unregister"
-  ],
-  "resources": [
-    {
-      "id": "package",
-      "type": "package",
-      "package": "claude-code"
-    },
-    {
-      "id": "managed",
-      "type": "directory",
-      "path": "/etc/claude-code",
-      "mode": "0755"
-    },
-    {
-      "id": "agent-home",
-      "type": "directory",
-      "path": "${machine:account-home}/.claude",
-      "mode": "0700",
-      "owner": "${machine:account}"
-    },
-    {
-      "id": "state",
-      "type": "directory",
-      "mode": "0700",
-      "owner": "${machine:account}",
-      "place": "."
-    },
-    {
-      "id": "facts",
-      "type": "file",
-      "path": "${dir:state}/facts.json",
-      "mode": "0600",
-      "owner": "${machine:account}",
-      "content": "{\n  \"node\": \"${machine:name}\",\n  \"console\": \"http://127.0.0.1:${bound:mcp-endpoint:port}/mcp\"\n}\n"
-    },
-    {
-      "id": "settings",
-      "type": "file",
-      "path": "${dir:state}/settings.json",
-      "mode": "0600",
-      "owner": "${machine:account}",
-      "merge": "json",
-      "content": "{\n  \"role\": \"\",\n  \"mcp_servers\": {}\n}\n"
-    }
-  ],
-  "build": {
-    "artifacts": [
-      {
-        "name": "tools",
-        "kind": "bundle",
-        "language": "typescript",
-        "entrypoints": [
-          "tools/index.js"
-        ],
-        "env": {
-          "MESH_CLAUDE_CODE_STATE": "${dir:state}",
-          "MESH_CLAUDE_CODE_FACTS": "${dir:state}/facts.json",
-          "MESH_CLAUDE_CODE_SETTINGS": "${dir:state}/settings.json"
-        }
-      }
-    ]
-  }
-}

modules/claude-code/node.ts

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

modules/claude-code/package.json

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

modules/claude-code/render.ts

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

modules/claude-code/seal.ts

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

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

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

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

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

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

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

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

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

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

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

modules/claude-code/tools/index.ts

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

modules/claude-code/tsconfig.json

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

modules/clipmenu/README.md

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

modules/clipmenu/go.mod

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

modules/clipmenu/go.sum

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

modules/clipmenu/module.json

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

modules/cloudflare-dns/Dockerfile

@@ -0,0 +1,24 @@
+# cloudflare-dns'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/cloudflare-dns
+COPY . .
+RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts provisioner/index.ts \
+      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
+
+FROM ${RUNTIME_BASE}
+COPY --from=build /app/modules/cloudflare-dns/dist /app/modules/cloudflare-dns/dist
+# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
+# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
+# the convention novox/hq issues 060/061 settled.
+ENV MESH_TOOL_MODULES=/app/modules/cloudflare-dns/dist/tools/index.js,/app/modules/cloudflare-dns/dist/provisioner/index.js

modules/cloudflare-dns/module.json

@@ -12,61 +12,87 @@
     "public-dns": {}
   },
   "grants": {
-    "public-dns": "${dir:grants}"
+    "public-dns": "/var/lib/cloudflare-dns/grants"
   },
   "receives": {
-    "public-dns": "${dir:grants}/mesh.json"
+    "public-dns": "/var/lib/cloudflare-dns/grants/mesh.json"
   },
   "own-secrets": {
-    "token": "${dir:state}/token"
+    "token": "/var/lib/cloudflare-dns/token",
+    "broker": "/var/lib/mesh/cloudflare-dns/broker"
   },
   "emits": [
     "record.created",
     "record.removed"
   ],
   "resources": [
+    {
+      "id": "mesh-state",
+      "type": "directory",
+      "path": "/var/lib/mesh/cloudflare-dns",
+      "mode": "0700"
+    },
     {
       "id": "state",
       "type": "directory",
-      "mode": "0700",
-      "place": "."
+      "path": "/var/lib/cloudflare-dns",
+      "mode": "0700"
     },
     {
       "id": "grants",
       "type": "directory",
+      "path": "/var/lib/cloudflare-dns/grants",
       "mode": "0700"
     },
     {
       "id": "config",
       "type": "file",
-      "path": "${dir:state}/config.json",
+      "path": "/var/lib/cloudflare-dns/config.json",
       "merge": "json",
       "content": "{}",
       "mode": "0600"
+    },
+    {
+      "id": "runtime",
+      "type": "container",
+      "name": "mesh-cloudflare-dns",
+      "network": "host",
+      "volumes": [
+        "/var/lib/cloudflare-dns/config.json:/run/config/config.json:ro",
+        "/var/lib/cloudflare-dns/grants:/grants",
+        "/var/lib/cloudflare-dns/token:/run/secrets/token:ro",
+        "/var/lib/mesh/cloudflare-dns/broker:/run/secrets/broker:ro"
+      ],
+      "env": {
+        "MESH_CLOUDFLARE_TOKEN_FILE": "/run/secrets/token",
+        "MESH_BROKER_FILE": "/run/secrets/broker",
+        "MESH_CLOUDFLARE_CONFIG_FILE": "/run/config/config.json",
+        "MESH_RECEIVES": "/var/lib/cloudflare-dns/grants/mesh.json"
+      },
+      "artifact": "runtime"
     }
   ],
   "capabilities": [
     "container-runtime"
   ],
   "build": {
+    "on": [
+      {
+        "arg": "BUILD_BASE",
+        "module": "mesh-tools",
+        "artifact": "build"
+      },
+      {
+        "arg": "RUNTIME_BASE",
+        "module": "mesh-tools",
+        "artifact": "runtime"
+      }
+    ],
     "artifacts": [
       {
-        "name": "code",
-        "kind": "bundle",
-        "language": "typescript",
-        "entrypoints": [
-          "tools/index.js",
-          "provisioner/index.js"
-        ],
-        "loads": [
-          "tools/index.js",
-          "provisioner/index.js"
-        ],
-        "env": {
-          "MESH_CLOUDFLARE_TOKEN_FILE": "${dir:state}/token",
-          "MESH_CLOUDFLARE_CONFIG_FILE": "${dir:state}/config.json",
-          "MESH_RECEIVES": "${dir:grants}/mesh.json"
-        }
+        "name": "runtime",
+        "kind": "image",
+        "from": "Dockerfile"
       }
     ]
   }

modules/confluence/Dockerfile

@@ -0,0 +1,24 @@
+# confluence'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/confluence
+COPY . .
+RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts \
+      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
+
+FROM ${RUNTIME_BASE}
+COPY --from=build /app/modules/confluence/dist /app/modules/confluence/dist
+# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
+# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
+# the convention novox/hq issues 060/061 settled.
+ENV MESH_TOOL_MODULES=/app/modules/confluence/dist/tools/index.js

modules/confluence/module.json

@@ -3,43 +3,69 @@
   "version": "1",
   "slug": "confl",
   "own-secrets": {
-    "token": "${dir:state}/token"
+    "token": "/var/lib/confluence/token",
+    "broker": "/var/lib/mesh/confluence/broker"
   },
   "resources": [
+    {
+      "id": "mesh-state",
+      "type": "directory",
+      "path": "/var/lib/mesh/confluence",
+      "mode": "0700"
+    },
     {
       "id": "state",
       "type": "directory",
-      "mode": "0700",
-      "place": "."
+      "path": "/var/lib/confluence",
+      "mode": "0700"
     },
     {
       "id": "config",
       "type": "file",
-      "path": "${dir:state}/config.json",
+      "path": "/var/lib/confluence/config.json",
       "merge": "json",
       "content": "{}",
       "mode": "0600"
+    },
+    {
+      "id": "runtime",
+      "type": "container",
+      "name": "mesh-runtime-confluence",
+      "network": "host",
+      "volumes": [
+        "/var/lib/confluence/config.json:/run/config/config.json:ro",
+        "/var/lib/confluence/token:/run/secrets/token:ro",
+        "/var/lib/mesh/confluence/broker:/run/secrets/broker:ro"
+      ],
+      "env": {
+        "MESH_CONFLUENCE_TOKEN_FILE": "/run/secrets/token",
+        "MESH_CONFLUENCE_CONFIG_FILE": "/run/config/config.json",
+        "MESH_BROKER_FILE": "/run/secrets/broker"
+      },
+      "artifact": "runtime"
     }
   ],
   "capabilities": [
     "container-runtime"
   ],
   "build": {
+    "on": [
+      {
+        "arg": "BUILD_BASE",
+        "module": "mesh-tools",
+        "artifact": "build"
+      },
+      {
+        "arg": "RUNTIME_BASE",
+        "module": "mesh-tools",
+        "artifact": "runtime"
+      }
+    ],
     "artifacts": [
       {
-        "name": "tools",
-        "kind": "bundle",
-        "language": "typescript",
-        "entrypoints": [
-          "tools/index.js"
-        ],
-        "loads": [
-          "tools/index.js"
-        ],
-        "env": {
-          "MESH_CONFLUENCE_TOKEN_FILE": "${dir:state}/token",
-          "MESH_CONFLUENCE_CONFIG_FILE": "${dir:state}/config.json"
-        }
+        "name": "runtime",
+        "kind": "image",
+        "from": "Dockerfile"
       }
     ]
   }

modules/de-spiegel/module.json

@@ -15,11 +15,11 @@
     }
   },
   "binds": {
-    "route": "${dir:state}/route.json"
+    "route": "/var/lib/de-spiegel/route.json"
   },
   "own-secrets": {
-    "smtp-user": "${dir:state}/smtp-user.secret",
-    "smtp-pass": "${dir:state}/smtp-pass.secret"
+    "smtp-user": "/var/lib/de-spiegel/smtp-user.secret",
+    "smtp-pass": "/var/lib/de-spiegel/smtp-pass.secret"
   },
   "listens": [
     {
@@ -34,13 +34,13 @@
     {
       "id": "state",
       "type": "directory",
-      "mode": "0700",
-      "place": "."
+      "path": "/var/lib/de-spiegel",
+      "mode": "0700"
     },
     {
       "id": "server-env",
       "type": "file",
-      "path": "${dir:state}/server.env",
+      "path": "/var/lib/de-spiegel/server.env",
       "mode": "0600",
       "content": "SMTP_AUTH_USER=${secret:smtp-user}\nSMTP_AUTH_PASS=${secret:smtp-pass}\n"
     },
@@ -56,7 +56,7 @@
       "image": "registry-api.novox.be/novox/de-spiegel@sha256:e144b72ce9c145870470d765343549f2c60211728cd118b9ff0e4029f36342ba",
       "network": "de-spiegel",
       "env-file": [
-        "${dir:state}/server.env"
+        "/var/lib/de-spiegel/server.env"
       ],
       "ports": [
         "35621"

modules/dhcpcd/module.json

@@ -3,8 +3,7 @@
   "version": "1",
   "capabilities": [
     "package-manager",
-    "service-manager",
-    "uplink-dhcpcd"
+    "service-manager"
   ],
   "claims": [
     {

modules/distribution/module.json

@@ -9,7 +9,7 @@
   ],
   "claims": [
     {
-      "name": "mesh-artifact-store",
+      "name": "the-artifact-store",
       "scope": "mesh"
     }
   ],
@@ -59,10 +59,7 @@
       ],
       "volumes": [
         "/var/lib/mesh-registry:/var/lib/registry"
-      ],
-      "env": {
-        "REGISTRY_STORAGE_DELETE_ENABLED": "true"
-      }
+      ]
     }
   ]
 }

modules/dunst/README.md

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

modules/dunst/files/dunstrc

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

modules/dunst/go.mod

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

modules/dunst/go.sum

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

modules/dunst/module.json

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

modules/fail2ban/client.ts

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

modules/fail2ban/module.json

@@ -7,22 +7,9 @@
   "claims": [
     {
       "name": "node-intrusion-prevention",
-      "scope": "node",
-      "serves": [
-        "status",
-        "banned",
-        "ban",
-        "unban"
-      ]
+      "scope": "node"
     }
   ],
-  "tools": [
-    "fail2ban_settings"
-  ],
-  "jailing": {
-    "into": "/etc/fail2ban/jail.d/mesh.conf",
-    "filter-into": "/etc/fail2ban/filter.d"
-  },
   "resources": [
     {
       "id": "package",
@@ -41,31 +28,19 @@
       "path": "/etc/fail2ban/action.d",
       "mode": "0755"
     },
-    {
-      "id": "filter-d",
-      "type": "directory",
-      "path": "/etc/fail2ban/filter.d",
-      "mode": "0755"
-    },
-    {
-      "id": "run-dir",
-      "type": "directory",
-      "path": "/var/run/fail2ban",
-      "mode": "0755"
-    },
     {
       "id": "jail-local",
       "type": "file",
       "path": "/etc/fail2ban/jail.local",
       "mode": "0644",
-      "content": "[INCLUDES]\n\nbefore = paths-arch.conf\n\n[DEFAULT]\n\n# Never act on the machine itself or on a tunnel peer: the mesh's private range is\n# ${machine:mesh-range}, named here rather than written as a value the module cannot\n# know (novox/hq ADR 0112). Without this, fail2ban could ban the mesh's own nodes.\n# **A ban list never holds a neighbour.** The mesh's own range is named rather than written\n# (novox/hq ADR 0112), and every private range beside it: a source on one is somebody's own\n# network, not the internet. On a machine behind a router that reflects local traffic, every\n# client in the house arrives as the gateway's address — so one mistyped local request banned\n# 192.168.1.1 on the home server and would have cut the whole house off from it (ADR 0186).\nignoreip = 127.0.0.1/8 ::1 ${machine:mesh-range} 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16 169.254.0.0/16 fc00::/7 fe80::/10\n\n# Three failures in a day ban for a day (novox/hq ADR 0179). The attackers this mesh sees pace\n# themselves at one try every ten minutes, under any ten-minute window; a day's window counts\n# them, and a day's ban costs a person who mistyped three times once, from one address, while\n# the mesh's own range is never banned at all.\nbantime  = 1d\nfindtime = 1d\nmaxretry = 3\n\n# Ban through iptables, not through a firewall front-end the machine may not have. ufw is\n# installed on two of this mesh's machines and absent on the other two, and fail2ban finds out\n# only at ban time: the service reports healthy, the jail counts the attempt, the ban command\n# exits 127, and nothing is blocked. Proven on 2026-09-28 -- 'ufw: command not found' on a\n# machine the mesh reported as protected.\n#\n# The action below is this module's own, already used by the recidive jail on every machine\n# here, and it bans in DOCKER-USER as well as INPUT, so a container's published port is\n# covered too.\nbanaction = iptables-allports-dualchain\nbanaction_allports = iptables-allports-dualchain\n\n[sshd]\nenabled = true\nport    = ssh\nlogpath = %(sshd_log)s\nbackend = %(sshd_backend)s\n"
+      "content": "[INCLUDES]\n\nbefore = paths-arch.conf\n\n[DEFAULT]\n\n# Never act on the machine itself or on a tunnel peer: the mesh's private range is\n# ${machine:mesh-range}, named here rather than written as a value the module cannot\n# know (novox/hq ADR 0112). Without this, fail2ban could ban the mesh's own nodes.\nignoreip = 127.0.0.1/8 ::1 ${machine:mesh-range}\n\nbantime  = 10m\nfindtime = 10m\nmaxretry = 5\n\n# Ban through iptables, not through a firewall front-end the machine may not have. ufw is\n# installed on two of this mesh's machines and absent on the other two, and fail2ban finds out\n# only at ban time: the service reports healthy, the jail counts the attempt, the ban command\n# exits 127, and nothing is blocked. Proven on 2026-09-28 -- 'ufw: command not found' on a\n# machine the mesh reported as protected.\n#\n# The action below is this module's own, already used by the recidive jail on every machine\n# here, and it bans in DOCKER-USER as well as INPUT, so a container's published port is\n# covered too.\nbanaction = iptables-allports-dualchain\nbanaction_allports = iptables-allports-dualchain\n\n[sshd]\nenabled = true\nport    = ssh\nlogpath = %(sshd_log)s\nbackend = %(sshd_backend)s\n"
     },
     {
       "id": "jail-sshd",
       "type": "file",
       "path": "/etc/fail2ban/jail.d/sshd.conf",
       "mode": "0644",
-      "content": "[sshd]\nenabled = true\nport    = ssh\nlogpath = %(sshd_log)s\nbackend = %(sshd_backend)s\nmaxretry = 3\nfindtime = 1d\nbantime  = 1d\n"
+      "content": "[sshd]\nenabled = true\nport    = ssh\nlogpath = %(sshd_log)s\nbackend = %(sshd_backend)s\nmaxretry = 5\n"
     },
     {
       "id": "log",
@@ -80,7 +55,7 @@
       "type": "file",
       "path": "/etc/fail2ban/jail.d/recidive.conf",
       "mode": "0644",
-      "content": "[recidive]\nenabled = true\nlogpath  = /var/log/fail2ban.log\n# Ban in both INPUT (host services like SSH) and DOCKER-USER (container services)\nbanaction = iptables-allports-dualchain\n# Banned twice in two weeks, by any jail, is banned for four (novox/hq ADR 0179).\nbantime  = 4w\nfindtime = 2w\nmaxretry = 2\n"
+      "content": "[recidive]\nenabled = true\nlogpath  = /var/log/fail2ban.log\n# Ban in both INPUT (host services like SSH) and DOCKER-USER (container services)\nbanaction = iptables-allports-dualchain\nbantime  = 1w\nfindtime = 1d\n"
     },
     {
       "id": "action-dualchain",
@@ -106,21 +81,8 @@
         "jail-local",
         "jail-sshd",
         "jail-recidive",
-        "action-dualchain",
-        "composed-jails"
+        "action-dualchain"
       ]
     }
-  ],
-  "build": {
-    "artifacts": [
-      {
-        "name": "tools",
-        "kind": "bundle",
-        "language": "typescript",
-        "entrypoints": [
-          "tools/index.js"
-        ]
-      }
-    ]
-  }
+  ]
 }

modules/fail2ban/package.json

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

modules/fail2ban/test/client.test.ts

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

modules/fail2ban/tools/index.ts

@@ -1,62 +1,55 @@
-// The intrusion prevention's tools: the node-intrusion-prevention seat's four verbs — who is banned,
-// the jails' state, ban one, let one go — and the module's own reading of a jail's settings
-// (novox/hq to-be 31, ADR 0179). The jails themselves are composed by the mesh from the modules a
-// machine runs and written as declared resources; these touch only what the running daemon holds.
+// fail2ban's tools — reading and steering the live ban state. The jails themselves are declared
+// resources (module.json); these three touch what the running daemon holds: what is banned now,
+// and the manual ban/unban an operator reaches for. The daemon's state is fail2ban's own, so this
+// is the only way to see or change it — the mesh reconciles the config, not the bans.
 
 import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
 import { Fail2banClient } from "../client.js";
 
-export function getSeatVerbs(fail2ban: Fail2banClient): ToolDefinition[] {
-  return [
-    {
-      name: "status",
-      description:
-        "Every jail on this machine with what it watches, how many addresses it is counting failures against and holding now, and the totals since it started; one jail's detail when named.",
-      input: { jail: { type: "string", description: "one jail (optional)" } },
-      run: async (args) => fail2ban.status(args.jail ? String(args.jail) : undefined),
-    },
-    {
-      name: "banned",
-      description: "Every address banned on this machine right now, with the jail that holds it, when it was banned and when the ban ends.",
-      input: { jail: { type: "string", description: "one jail (optional)" } },
-      run: async (args) => fail2ban.banned(args.jail ? String(args.jail) : undefined),
-    },
-    {
-      name: "ban",
-      description:
-        "Ban one address in one jail now, for the jail's ban time — an operator's act on the live ban list, which the mesh never writes itself.",
-      input: {
-        ip: { type: "string", description: "the address" },
-        jail: { type: "string", description: "the jail to hold it (recidive for the long ban)" },
-      },
-      run: async (args) => fail2ban.ban(String(args.ip ?? ""), String(args.jail ?? "")),
-    },
-    {
-      name: "unban",
-      description: "Let one address go, from one jail or from every jail when none is named.",
-      input: {
-        ip: { type: "string", description: "the address" },
-        jail: { type: "string", description: "one jail (optional)" },
-      },
-      run: async (args) => fail2ban.unban(String(args.ip ?? ""), args.jail ? String(args.jail) : undefined),
-    },
-  ];
-}
-
 export function getFail2banTools(fail2ban: Fail2banClient): ToolDefinition[] {
   return [
     {
-      name: "fail2ban_settings",
+      name: "fail2ban_status",
       description:
-        "One jail's effective settings on this machine: ban time, window, tries, the addresses it never bans, its actions and what it reads.",
-      input: { jail: { type: "string", description: "the jail" } },
-      run: async (args) => fail2ban.settings(String(args.jail ?? "")),
+        "fail2ban status on this node — the jails and their live bans. Omit `jail` for every jail, or name one for its detail.",
+      input: {
+        type: "object",
+        properties: {
+          jail: {
+            type: "string",
+            description: "A specific jail (e.g. sshd, recidive); omit for the overview of all jails.",
+          },
+        },
+      },
+      run: async (args) => ({ status: await fail2ban.status(args.jail as string | undefined) }),
+    },
+    {
+      name: "fail2ban_ban",
+      description: "Manually ban an IP address in a jail — a live change to the running daemon, not a mesh-managed file.",
+      input: {
+        type: "object",
+        properties: {
+          jail: { type: "string", description: "Jail name (e.g. sshd, recidive)." },
+          ip: { type: "string", description: "IP address to ban." },
+        },
+        required: ["jail", "ip"],
+      },
+      run: async (args) => ({ result: await fail2ban.ban(args.jail as string, args.ip as string) }),
+    },
+    {
+      name: "fail2ban_unban",
+      description: "Unban an IP address from one jail, or from every jail when `jail` is omitted.",
+      input: {
+        type: "object",
+        properties: {
+          ip: { type: "string", description: "IP address to unban." },
+          jail: { type: "string", description: "A specific jail; omit to unban from all jails." },
+        },
+        required: ["ip"],
+      },
+      run: async (args) => ({ result: await fail2ban.unban(args.ip as string, args.jail as string | undefined) }),
     },
   ];
 }
 
-const fail2ban = Fail2banClient.onThisMachine();
-// The seat's verbs under the seat's name: the runtime serves them on the seat's subjects where this
-// module holds it (ADR 0159, 0160). The module's own under its own.
-registerModuleTools("node-intrusion-prevention", () => getSeatVerbs(fail2ban));
-registerModuleTools("fail2ban", () => getFail2banTools(fail2ban));
+registerModuleTools("fail2ban", () => getFail2banTools(Fail2banClient.fromEnv()));

modules/feh/README.md

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

modules/feh/files/fehbg

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

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

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

modules/feh/go.mod

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

modules/feh/go.sum

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

modules/feh/module.json

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

modules/gitea/Dockerfile

@@ -0,0 +1,37 @@
+# gitea's runtime: the tool runtime, carrying this module's compiled provisioner, tools and event
+# consumer.
+#
+# **Built from this module's own directory and nothing else.** The sdk is in the base image, so
+# nothing is copied out of a neighbouring checkout — which is what lets the mesh build this 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: the image this is COMPILED in, and the image it RUNS in.
+# They are different images on purpose — the first carries a compiler and the second must not, or
+# every running container would carry one it never invokes. The mesh answers both with the copies it
+# holds, because a fingerprint written here would name one particular copy and no other mesh has it
+# (novox/hq issue 044). Declared in module.json's `build.on`; deliberately no defaults, so a build
+# nobody told stops here and says which module to build first.
+ARG BUILD_BASE
+ARG RUNTIME_BASE
+
+FROM ${BUILD_BASE} AS build
+# Compiled under /app/modules so `@novox/mesh-sdk` resolves upward into the base's own
+# node_modules — the module is compiled against exactly the sdk it will run against.
+WORKDIR /app/modules/gitea
+COPY . .
+# The compiler is invoked by its real path rather than through node_modules/.bin, whose entries are
+# symlinks to a launcher that requires its library relatively — resolved away when the base image
+# was assembled.
+RUN node /app/node_modules/typescript/bin/tsc client.ts token.ts index.ts provisioner/index.ts tools/index.ts \
+      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
+
+FROM ${RUNTIME_BASE}
+# **No apt packages.** gitea's provisioner talks to the forge over HTTP (the gitea REST API), not
+# through a CLI the way postgres drives psql — so the runtime base holds everything this needs.
+COPY --from=build /app/modules/gitea/dist /app/modules/gitea/dist
+# What a tool host should load from this module: its event consumer and its tools, which are
+# separate entrypoints because they are loaded by different things. The provisioner is the third,
+# and is not listed here — the declaration names it in the container's `args`, because it is what
+# this module's own container runs. One image, because they are one module and share a client.
+ENV MESH_TOOL_MODULES=/app/modules/gitea/dist/index.js,/app/modules/gitea/dist/tools/index.js,/app/modules/gitea/dist/provisioner/index.js

modules/gitea/client.ts

@@ -45,14 +45,6 @@ export interface GiteaPull {
   html_url: string;
 }
 
-export interface GiteaComment {
-  id: number;
-  user?: string;
-  body: string;
-  created_at?: string;
-  html_url: string;
-}
-
 export interface GiteaLabel {
   id: number;
   name: string;
@@ -265,64 +257,6 @@ export class GiteaClient {
     );
   }
 
-  /** Close or reopen a pull request without merging it. A pull request is an issue to the forge's
-   *  state machine, and the pulls endpoint takes the same `state`. */
-  async setPullState(owner: string, repo: string, index: number, state: "open" | "closed"): Promise<GiteaPull> {
-    return GiteaClient.mapPull(
-      await this.request<any>(`/repos/${owner}/${repo}/pulls/${index}`, { method: "PATCH", body: JSON.stringify({ state }) }),
-    );
-  }
-
-  /** Change a pull request's title or body; a field left undefined is left alone. */
-  async updatePullRequest(owner: string, repo: string, index: number, data: { title?: string; body?: string }): Promise<GiteaPull> {
-    return GiteaClient.mapPull(
-      await this.request<any>(`/repos/${owner}/${repo}/pulls/${index}`, { method: "PATCH", body: JSON.stringify(data) }),
-    );
-  }
-
-  /** The unified diff of a pull request, as text. */
-  async pullDiff(owner: string, repo: string, index: number): Promise<string> {
-    return this.requestText(`/repos/${owner}/${repo}/pulls/${index}.diff`);
-  }
-
-  /** Every comment on an issue or pull request, oldest first. */
-  async listComments(owner: string, repo: string, index: number): Promise<GiteaComment[]> {
-    const raw = await this.request<any[]>(`/repos/${owner}/${repo}/issues/${index}/comments`);
-    return (raw ?? []).map((c) => ({
-      id: Number(c?.id ?? 0),
-      user: c?.user?.login,
-      body: String(c?.body ?? ""),
-      created_at: c?.created_at,
-      html_url: String(c?.html_url ?? ""),
-    }));
-  }
-
-  /** One file's contents at a ref (default the repository's default branch), decoded. */
-  async getFile(owner: string, repo: string, path: string, ref?: string): Promise<{ path: string; ref?: string; sha: string; size: number; content: string }> {
-    const qs = ref ? `?ref=${encodeURIComponent(ref)}` : "";
-    const f = await this.request<any>(`/repos/${owner}/${repo}/contents/${path.split("/").map(encodeURIComponent).join("/")}${qs}`);
-    if (!f || f.type !== "file") throw new Error(`Gitea API: ${path} is not a file`);
-    const content = f.encoding === "base64" ? Buffer.from(String(f.content ?? ""), "base64").toString("utf8") : String(f.content ?? "");
-    return { path, ref, sha: String(f.sha ?? ""), size: Number(f.size ?? content.length), content };
-  }
-
-  async listBranches(owner: string, repo: string): Promise<{ name: string; commit: string; protected: boolean }[]> {
-    const raw = await this.request<any[]>(`/repos/${owner}/${repo}/branches?limit=100`);
-    return (raw ?? []).map((b) => ({ name: String(b?.name ?? ""), commit: String(b?.commit?.id ?? ""), protected: Boolean(b?.protected) }));
-  }
-
-  async deleteBranch(owner: string, repo: string, branch: string): Promise<void> {
-    await this.request(`/repos/${owner}/${repo}/branches/${encodeURIComponent(branch)}`, { method: "DELETE" });
-  }
-
-  /** A request whose answer is text, not JSON — a diff. Same token handling as request(). */
-  private async requestText(path: string): Promise<string> {
-    const token = await this.tokens.current();
-    const res = await this.send(path, { headers: { Accept: "text/plain" } }, token);
-    if (!res.ok) throw new Error(`Gitea API ${path}: ${res.status} ${await res.text()}`);
-    return res.text();
-  }
-
   async mergePullRequest(owner: string, repo: string, index: number, method = "merge", deleteBranch = false): Promise<void> {
     await this.request(`/repos/${owner}/${repo}/pulls/${index}/merge`, {
       method: "POST",

modules/gitea/module.json

@@ -85,17 +85,20 @@
       "scope": "mesh"
     }
   ],
+  "own-secrets": {
+    "broker": "/var/lib/mesh/gitea/broker"
+  },
   "resources": [
     {
       "id": "mesh-state",
       "type": "directory",
-      "mode": "0700",
-      "place": "mesh"
+      "path": "/var/lib/mesh/gitea",
+      "mode": "0700"
     },
     {
       "id": "runtime-state",
       "type": "directory",
-      "path": "${dir:mesh-state}/state",
+      "path": "/var/lib/mesh/gitea/state",
       "mode": "0700"
     },
     {
@@ -142,8 +145,7 @@
       "volumes": [
         "${dir:data}:/data"
       ],
-      "secrets-in-environment": "gitea honours GITEA__database__PASSWD__FILE and GITEA__security__INTERNAL_TOKEN__FILE; convertible, awaiting a bed that proves it",
-      "logging": "journald"
+      "secrets-in-environment": "gitea honours GITEA__database__PASSWD__FILE and GITEA__security__INTERNAL_TOKEN__FILE; convertible, awaiting a bed that proves it"
     },
     {
       "id": "admin-bootstrap",
@@ -173,10 +175,36 @@
     {
       "id": "runtime-config",
       "type": "file",
-      "path": "${dir:mesh-state}/config.json",
+      "path": "/var/lib/mesh/gitea/config.json",
       "mode": "0600",
       "content": "{}\n",
       "merge": "json"
+    },
+    {
+      "id": "runtime",
+      "type": "container",
+      "name": "mesh-gitea",
+      "network": "host",
+      "volumes": [
+        "/var/lib/mesh/gitea/broker:/run/secrets/broker:ro",
+        "/var/lib/mesh/gitea/config.json:/run/config/config.json:ro",
+        "${dir:grants}:${dir:grants}:ro",
+        "${dir:state}/admin.secret:/run/secrets/admin:ro",
+        "/var/lib/mesh/gitea/state:/run/state"
+      ],
+      "env": {
+        "MESH_BROKER_FILE": "/run/secrets/broker",
+        "MESH_GITEA_URL": "http://127.0.0.1:${port:3000}",
+        "MESH_GITEA_CONFIG_FILE": "/run/config/config.json",
+        "MESH_GITEA_ADMIN_USER": "mesh-admin",
+        "MESH_GITEA_ADMIN_PASSWORD_FILE": "/run/secrets/admin",
+        "MESH_GITEA_STATE_DIR": "/run/state",
+        "MESH_RECEIVES": "${dir:grants}/npm.json"
+      },
+      "artifact": "runtime",
+      "restart-on": [
+        "runtime-config"
+      ]
     }
   ],
   "provides": [
@@ -190,37 +218,24 @@
     }
   ],
   "build": {
+    "on": [
+      {
+        "arg": "BUILD_BASE",
+        "module": "mesh-tools",
+        "artifact": "build"
+      },
+      {
+        "arg": "RUNTIME_BASE",
+        "module": "mesh-tools",
+        "artifact": "runtime"
+      }
+    ],
     "artifacts": [
       {
-        "name": "code",
-        "kind": "bundle",
-        "language": "typescript",
-        "entrypoints": [
-          "index.js",
-          "tools/index.js",
-          "provisioner/index.js"
-        ],
-        "loads": [
-          "index.js",
-          "tools/index.js",
-          "provisioner/index.js"
-        ],
-        "env": {
-          "MESH_GITEA_URL": "http://127.0.0.1:${port:3000}",
-          "MESH_GITEA_CONFIG_FILE": "${dir:mesh-state}/config.json",
-          "MESH_GITEA_ADMIN_USER": "mesh-admin",
-          "MESH_GITEA_ADMIN_PASSWORD_FILE": "${dir:state}/admin.secret",
-          "MESH_GITEA_STATE_DIR": "${dir:runtime-state}",
-          "MESH_RECEIVES": "${dir:grants}/npm.json"
-        }
+        "name": "runtime",
+        "kind": "image",
+        "from": "Dockerfile"
       }
     ]
-  },
-  "jails": [
-    {
-      "name": "gitea",
-      "failregex": "^.*Failed authentication attempt for .* from <HOST>(?::\\d+)?\\s*$\n            ^.*Invalid user .* from <HOST> port \\d+\\s*$\n            ^.*User \\S+ from <HOST> not allowed because .*$",
-      "jail": "backend = systemd\njournalmatch = CONTAINER_NAME=gitea\nport = http,https,222\nmaxretry = 3\nfindtime = 1d\nbantime = 1d"
-    }
-  ]
+  }
 }

modules/gitea/test/token.test.ts

@@ -31,9 +31,6 @@ interface Forge {
   tokens: Map<string, string>;
   scopesOf: Map<string, string[]>;
   admins: Map<string, string>;
-  pullState: string;
-  pullTitle: string;
-  branchDeleted: boolean;
   close(): Promise<void>;
 }
 
@@ -44,9 +41,6 @@ function fakeForge(): Promise<Forge> {
     tokens: new Map<string, string>(), // name -> value
     scopesOf: new Map<string, string[]>(), // value -> scopes, so a route can enforce them like gitea does
     admins: new Map([[ADMIN, PASSWORD]]),
-    pullState: "open",
-    pullTitle: "The console shipped",
-    branchDeleted: false,
   };
   // write:X implies read:X — gitea's own rule (models/auth/access_token_scope.go).
   const covers = (scopes: string[], required: string): boolean =>
@@ -92,37 +86,6 @@ function fakeForge(): Promise<Forge> {
       }
       return json(res, 405, { message: "method not allowed" });
     }
-    const tokenOf = (): string => {
-      const h = req.headers.authorization ?? "";
-      return h.startsWith("token ") ? h.slice(6) : "";
-    };
-    const pull = url.pathname.match(/^\/api\/v1\/repos\/novox\/hq\/pulls\/(\d+)(\.diff)?$/);
-    if (pull) {
-      if (![...forge.tokens.values()].includes(tokenOf())) return json(res, 401, { message: "token is required" });
-      if (pull[2]) {
-        res.writeHead(200, { "Content-Type": "text/plain" });
-        return res.end("diff --git a/x b/x\n--- a/x\n+++ b/x\n@@ -1 +1 @@\n-old\n+new\n");
-      }
-      if (req.method === "PATCH") {
-        const patch = await body(req);
-        forge.pullState = patch?.state ?? forge.pullState;
-        forge.pullTitle = patch?.title ?? forge.pullTitle;
-      }
-      return json(res, 200, { number: Number(pull[1]), title: forge.pullTitle, state: forge.pullState, merged: false,
-        user: { login: "mesh-admin" }, head: { ref: "feat/x" }, base: { ref: "main" }, html_url: "http://fake/novox/hq/pulls/" + pull[1] });
-    }
-    if (url.pathname === "/api/v1/repos/novox/hq/issues/223/comments") {
-      return json(res, 200, [{ id: 1, user: { login: "jochen" }, body: "landed elsewhere", created_at: "2026-10-01T00:00:00Z", html_url: "http://fake/c/1" }]);
-    }
-    if (url.pathname === "/api/v1/repos/novox/hq/contents/README.md") {
-      return json(res, 200, { type: "file", encoding: "base64", sha: "abc", size: 5, content: Buffer.from("hello").toString("base64") });
-    }
-    if (url.pathname === "/api/v1/repos/novox/hq/branches") {
-      return json(res, 200, [{ name: "main", protected: true, commit: { id: "aaaa" } }, { name: "feat/x", protected: false, commit: { id: "bbbb" } }]);
-    }
-    if (url.pathname === "/api/v1/repos/novox/hq/branches/feat%2Fx" || url.pathname === "/api/v1/repos/novox/hq/branches/feat/x") {
-      if (req.method === "DELETE") { forge.branchDeleted = true; return json(res, 204, null); }
-    }
     if (url.pathname === "/api/v1/repos/search") {
       // The client lists through the search endpoint since 2026-09-28 (the forge's whole view);
       // it sits under `repository`, which write:repository covers.
@@ -177,9 +140,6 @@ function fakeForge(): Promise<Forge> {
         url: `http://127.0.0.1:${port}`,
         get mints() { return forge.mints; },
         get lastScopes() { return forge.lastScopes; },
-        get pullState() { return forge.pullState; },
-        get pullTitle() { return forge.pullTitle; },
-        get branchDeleted() { return forge.branchDeleted; },
         tokens: forge.tokens,
         scopesOf: forge.scopesOf,
         admins: forge.admins,
@@ -400,16 +360,6 @@ test("the tools register once there is a way to a token, and the first call mint
       "gitea_list_repos", "gitea_create_repo", "gitea_delete_repo",
       "gitea_list_issues", "gitea_get_issue", "gitea_create_issue", "gitea_close_issue", "gitea_add_comment",
       "gitea_list_pull_requests", "gitea_get_pull_request", "gitea_create_pull_request", "gitea_merge_pull_request",
-      "gitea_close_pull_request",
-      "gitea_reopen_pull_request",
-      "gitea_update_pull_request",
-      "gitea_pull_request_files",
-      "gitea_pull_request_diff",
-      "gitea_list_comments",
-      "gitea_reopen_issue",
-      "gitea_get_file",
-      "gitea_list_branches",
-      "gitea_delete_branch",
       "gitea_list_labels", "gitea_create_label",
       "gitea_api",
     ],
@@ -420,32 +370,3 @@ test("the tools register once there is a way to a token, and the first call mint
   assert.equal(result.repos.length, 1);
   assert.equal(forge.mints, before + 1);
 });
-
-// The forge's tools reach every action a review needs without a checkout and without the API
-// escape hatch: close a pull request whose work landed elsewhere, read its diff, its comments, a
-// file, the branches, and delete the branch left behind. Against the fake forge, through the
-// compiled tools, the way the console calls them.
-test("a pull request can be closed, read and cleaned up through the tools", async () => {
-  const { env } = await delivered(forge);
-  const tools = collectTools(env).find((c) => c.module === "gitea")!.tools;
-  const tool = (name: string) => tools.find((t) => t.name === name)!;
-  for (const name of ["gitea_close_pull_request", "gitea_reopen_pull_request", "gitea_update_pull_request", "gitea_pull_request_files",
-    "gitea_pull_request_diff", "gitea_list_comments", "gitea_reopen_issue", "gitea_get_file", "gitea_list_branches", "gitea_delete_branch"]) {
-    assert.ok(tool(name), `${name} is not a tool`);
-  }
-  const closed = (await tool("gitea_close_pull_request").run({ owner: "novox", repo: "hq", number: 223 })) as { pull: { state: string } };
-  assert.equal(closed.pull.state, "closed");
-  assert.equal(forge.pullState, "closed");
-  const renamed = (await tool("gitea_update_pull_request").run({ owner: "novox", repo: "hq", number: 223, title: "Superseded" })) as { pull: { title: string } };
-  assert.equal(renamed.pull.title, "Superseded");
-  const diff = (await tool("gitea_pull_request_diff").run({ owner: "novox", repo: "hq", number: 223 })) as { diff: string };
-  assert.match(diff.diff, /^diff --git/);
-  const comments = (await tool("gitea_list_comments").run({ owner: "novox", repo: "hq", number: 223 })) as { comments: { body: string }[] };
-  assert.equal(comments.comments[0].body, "landed elsewhere");
-  const file = (await tool("gitea_get_file").run({ owner: "novox", repo: "hq", path: "README.md" })) as { file: { content: string } };
-  assert.equal(file.file.content, "hello");
-  const branches = (await tool("gitea_list_branches").run({ owner: "novox", repo: "hq" })) as { branches: { name: string }[] };
-  assert.deepEqual(branches.branches.map((b) => b.name), ["main", "feat/x"]);
-  await tool("gitea_delete_branch").run({ owner: "novox", repo: "hq", branch: "feat/x" });
-  assert.equal(forge.branchDeleted, true);
-});

modules/gitea/tools/index.ts

@@ -254,131 +254,6 @@ export function getGiteaTools(gitea: GiteaClient): ToolDefinition[] {
       },
     },
 
-    {
-      name: "gitea_close_pull_request",
-      description: "Close a pull request without merging it — one whose work landed elsewhere, or was abandoned.",
-      input: {
-        owner: { type: "string", description: "the repository owner" },
-        repo: { type: "string", description: "the repository name" },
-        number: { type: "number", description: "the PR number" },
-      },
-      run: async (args) => ({
-        pull: await gitea.setPullState(String(args.owner), String(args.repo), Number(args.number), "closed"),
-      }),
-    },
-    {
-      name: "gitea_reopen_pull_request",
-      description: "Reopen a closed, unmerged pull request.",
-      input: {
-        owner: { type: "string", description: "the repository owner" },
-        repo: { type: "string", description: "the repository name" },
-        number: { type: "number", description: "the PR number" },
-      },
-      run: async (args) => ({
-        pull: await gitea.setPullState(String(args.owner), String(args.repo), Number(args.number), "open"),
-      }),
-    },
-    {
-      name: "gitea_update_pull_request",
-      description: "Change a pull request's title or body; a field not given is left as it is.",
-      input: {
-        owner: { type: "string", description: "the repository owner" },
-        repo: { type: "string", description: "the repository name" },
-        number: { type: "number", description: "the PR number" },
-        title: { type: "string", description: "the new title (optional)" },
-        body: { type: "string", description: "the new body, markdown (optional)" },
-      },
-      run: async (args) => ({
-        pull: await gitea.updatePullRequest(String(args.owner), String(args.repo), Number(args.number), {
-          title: args.title === undefined ? undefined : String(args.title),
-          body: args.body === undefined ? undefined : String(args.body),
-        }),
-      }),
-    },
-    {
-      name: "gitea_pull_request_files",
-      description: "The files a pull request changes, as paths from the repository's root (up to 100; says when there are more).",
-      input: {
-        owner: { type: "string", description: "the repository owner" },
-        repo: { type: "string", description: "the repository name" },
-        number: { type: "number", description: "the PR number" },
-      },
-      run: async (args) => gitea.listPullFiles(String(args.owner), String(args.repo), Number(args.number)),
-    },
-    {
-      name: "gitea_pull_request_diff",
-      description: "A pull request's unified diff, as text — for reviewing it without a checkout.",
-      input: {
-        owner: { type: "string", description: "the repository owner" },
-        repo: { type: "string", description: "the repository name" },
-        number: { type: "number", description: "the PR number" },
-      },
-      run: async (args) => ({
-        diff: await gitea.pullDiff(String(args.owner), String(args.repo), Number(args.number)),
-      }),
-    },
-    {
-      name: "gitea_list_comments",
-      description: "Every comment on an issue or pull request, oldest first.",
-      input: {
-        owner: { type: "string", description: "the repository owner" },
-        repo: { type: "string", description: "the repository name" },
-        number: { type: "number", description: "the issue or PR number" },
-      },
-      run: async (args) => ({
-        comments: await gitea.listComments(String(args.owner), String(args.repo), Number(args.number)),
-      }),
-    },
-    {
-      name: "gitea_reopen_issue",
-      description: "Reopen a closed issue.",
-      input: {
-        owner: { type: "string", description: "the repository owner" },
-        repo: { type: "string", description: "the repository name" },
-        number: { type: "number", description: "the issue number" },
-      },
-      run: async (args) => ({
-        issue: await gitea.setIssueState(String(args.owner), String(args.repo), Number(args.number), "open"),
-      }),
-    },
-
-    // ---- Contents and branches ----
-    {
-      name: "gitea_get_file",
-      description: "One file's contents from a repository, decoded, at a branch, tag or commit (default the repository's default branch).",
-      input: {
-        owner: { type: "string", description: "the repository owner" },
-        repo: { type: "string", description: "the repository name" },
-        path: { type: "string", description: "the file's path from the repository's root" },
-        ref: { type: "string", description: "branch, tag or commit (optional)" },
-      },
-      run: async (args) => ({
-        file: await gitea.getFile(String(args.owner), String(args.repo), String(args.path), args.ref ? String(args.ref) : undefined),
-      }),
-    },
-    {
-      name: "gitea_list_branches",
-      description: "Every branch of a repository with the commit it points at.",
-      input: {
-        owner: { type: "string", description: "the repository owner" },
-        repo: { type: "string", description: "the repository name" },
-      },
-      run: async (args) => ({ branches: await gitea.listBranches(String(args.owner), String(args.repo)) }),
-    },
-    {
-      name: "gitea_delete_branch",
-      description: "Delete a branch — a feature branch whose pull request was closed rather than merged. Refused by the forge for a protected branch.",
-      input: {
-        owner: { type: "string", description: "the repository owner" },
-        repo: { type: "string", description: "the repository name" },
-        branch: { type: "string", description: "the branch name" },
-      },
-      run: async (args) => {
-        await gitea.deleteBranch(String(args.owner), String(args.repo), String(args.branch));
-        return { deleted: true, branch: String(args.branch) };
-      },
-    },
-
     // ---- Labels ----
     {
       name: "gitea_list_labels",