Convert the resolver from the module it replaces: forward, answer at 127.0.0.1, point the runtime at it

Read against hal/modules/dnsmasq-app (hal dnsmasq-app conversion, hq 08-connectivity).
On the machines it runs, the predecessor's dnsmasq answers every name: the mesh's own
itself, the rest forwarded to 1.1.1.1 and 8.8.8.8, its module's defaults; resolv.conf
names it alone at 127.0.0.1, and the container runtime's dns is the machine's tunnel
address, so the host and every container resolve the world through it. The nox module
forwarded nothing, listened on 127.0.0.55 — a convention of its own beside the one every
machine already followed — and read a machines file that the module's `facts` already
asks the mesh for, so taking it would have left an adopted machine with a resolv.conf
pointing at an address nothing answered on, and no upstream for anything else.

Now the resolver keeps `no-resolv` (the documented loop — finding its own address in
resolv.conf and becoming its own upstream — stays impossible) and forwards to the same
two explicit upstreams; listens on mesh0 and 127.0.0.1, which systemd-resolved does not
hold; requires `mesh-addressing`, since its data is the mesh's addresses; and writes the
runtime's `dns` into daemon.json beside whatever the machine had (ADR 0102), at this
machine's own address — `${machine:address}`, new in the controller. The runtime is not
restarted for it: it reads the key at start, not on reload, and a restart stops every
container; on the machine this replaces the value is already there.

resolv-conf names the resolver alone, as the predecessor's file did; its placeholder second
line was a fallback nothing ever reached. resolved-split-dns follows the address. The
mesh's suffix as a local domain comes with the machines file, so a mesh name the resolver
does not know is refused here rather than asked upstream. mDNS is not carried: no module
does it and the design says mesh names are not multicast names.

modules/amqp-email-forwarder/module.json

@@ -0,0 +1,56 @@
+{
+  "module": "amqp-email-forwarder",
+  "version": "1",
+  "slug": "emailfwd",
+  "capabilities": [
+    "container-runtime"
+  ],
+  "requires": [
+    "amqp"
+  ],
+  "contributes": {},
+  "binds": {
+    "amqp": "/var/lib/amqp-email-forwarder/amqp.json"
+  },
+  "secrets": {
+    "amqp": "/var/lib/amqp-email-forwarder/amqp.secret"
+  },
+  "own-secrets": {
+    "smtp-user": "/var/lib/amqp-email-forwarder/smtp-user.secret",
+    "smtp-password": "/var/lib/amqp-email-forwarder/smtp-password.secret"
+  },
+  "resources": [
+    {
+      "id": "state",
+      "type": "directory",
+      "path": "/var/lib/amqp-email-forwarder",
+      "mode": "0700"
+    },
+    {
+      "id": "app-env",
+      "type": "file",
+      "path": "/var/lib/amqp-email-forwarder/app.env",
+      "mode": "0600",
+      "content": "AMQP_HOST=${bound:amqp:at}\nAMQP_PORT=${bound:amqp:port}\nAMQP_USER=${bound:amqp:as}\nAMQP_VHOST=EMAILDELIVERY_T\nAMQP_EXCHANGE=News.TransactionalEmailing.Command\nAMQP_QUEUE=email-forwarder\nAMQP_URL=amqp://${bound:amqp:as}:${secret:amqp}@${bound:amqp:at}:${bound:amqp:port}/EMAILDELIVERY_T\nSMTP_HOST=mail.novox.be\nSMTP_PORT=587\nSMTP_USER=${secret:smtp-user}\nSMTP_PASSWORD=${secret:smtp-password}\n"
+    },
+    {
+      "id": "net",
+      "type": "network",
+      "name": "amqp-email-forwarder"
+    },
+    {
+      "id": "app",
+      "type": "container",
+      "name": "amqp-email-forwarder",
+      "image": "registry-api.novox.be/novox/amqp-email-forwarder@sha256:f76d34646d9d3b2098c72688a63f6ae656f1888ffcb2f90a9c8dd2a44ad7f8af",
+      "network": "amqp-email-forwarder",
+      "env-file": [
+        "/var/lib/amqp-email-forwarder/app.env"
+      ],
+      "restart-on": [
+        "app-env"
+      ],
+      "secrets-in-environment": "the application's own code reads AMQP_URL, SMTP_USER and SMTP_PASSWORD from the environment (amqp-email-forwarder app.js); converting is that repository's change"
+    }
+  ]
+}

modules/amqp-ping/Dockerfile

@@ -0,0 +1,31 @@
+# amqp-ping'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 not
+# copied out of neighbouring checkouts — they are in the base image, which is published like any
+# other artifact. That 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: 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 resolving `@novox/mesh-sdk` walks up to the base's own
+# node_modules — the module is compiled against exactly the sdk it will run against.
+WORKDIR /app/modules/amqp-ping
+COPY . .
+# The compiler is invoked by its real path, not through node_modules/.bin. Those are symlinks to
+# a launcher that requires its library relatively, and the base image resolves them when copying —
+# leaving a launcher whose relative require no longer points at anything.
+RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts \
+      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
+
+FROM ${RUNTIME_BASE}
+COPY --from=build /app/modules/amqp-ping/dist /app/modules/amqp-ping/dist
+# Declared rather than derived from which files happen to exist: the module knows what it serves.
+ENV MESH_TOOL_MODULES=/app/modules/amqp-ping/dist/index.js

modules/amqp-ping/client.ts

@@ -0,0 +1,191 @@
+// amqp-ping's AMQP client — the demo consumer's own code (novox/hq ADR 0039). It speaks AMQP 0-9-1
+// directly over a raw TCP socket (node:net), the way redis's client speaks RESP: the module carries
+// NO npm dependency beyond @novox/mesh-sdk — no amqplib, no CLI in the image. It does exactly one
+// thing, the round-trip that proves the grant works: connect, authenticate with PLAIN to the vhost
+// the mesh named, declare a queue, publish one message and get it back.
+//
+// This is the consumer half of the `amqp` interface. It connects as the login the mesh derived
+// (`${bound:amqp:as}`) with the password the mesh minted (`${secret:amqp}`) to a vhost of that SAME
+// name — the provider named the vhost after the login, so the consumer must too. Nothing here is
+// hardcoded: user AND vhost are both the bound login, and a wrong vhost is refused by the broker.
+
+import { createConnection, type Socket } from "node:net";
+import { readFileSync } from "node:fs";
+
+const FRAME_END = 0xce;
+const PROTOCOL_HEADER = Buffer.from([0x41, 0x4d, 0x51, 0x50, 0x00, 0x00, 0x09, 0x01]); // "AMQP" 0-9-1
+
+export interface AmqpConn {
+  readonly host: string;
+  readonly port: number;
+  readonly user: string;
+  readonly password: string;
+  readonly vhost: string;
+}
+
+/** Build the connection facts from the environment the mesh's env-file set (see the module manifest). */
+export function connFromEnv(env: NodeJS.ProcessEnv = process.env): AmqpConn {
+  const host = env.MESH_AMQP_HOST ?? "";
+  const port = Number(env.MESH_AMQP_PORT ?? "5672") || 5672;
+  const user = env.MESH_AMQP_USER ?? "";
+  const vhost = env.MESH_AMQP_VHOST ?? user; // the provider names the vhost after the login
+  const password = env.MESH_AMQP_PASSWORD ?? readMaybe(env.MESH_AMQP_PASSWORD_FILE);
+  if (!host || !user || !password) {
+    throw new Error(`amqp-ping: connection is not fully set yet (host=${host} user=${user} password=${password ? "set" : "unset"})`);
+  }
+  return { host, port, user, password, vhost };
+}
+
+// --- wire helpers ---------------------------------------------------------------------------------
+
+function shortstr(s: string): Buffer {
+  const b = Buffer.from(s, "utf8");
+  const o = Buffer.alloc(1 + b.length);
+  o.writeUInt8(b.length, 0);
+  b.copy(o, 1);
+  return o;
+}
+function longstr(s: Buffer | string): Buffer {
+  const b = Buffer.isBuffer(s) ? s : Buffer.from(s, "utf8");
+  const o = Buffer.alloc(4 + b.length);
+  o.writeUInt32BE(b.length, 0);
+  b.copy(o, 4);
+  return o;
+}
+function u16(n: number): Buffer {
+  const o = Buffer.alloc(2);
+  o.writeUInt16BE(n, 0);
+  return o;
+}
+function u32(n: number): Buffer {
+  const o = Buffer.alloc(4);
+  o.writeUInt32BE(n, 0);
+  return o;
+}
+function frame(type: number, channel: number, payload: Buffer): Buffer {
+  const o = Buffer.alloc(7 + payload.length + 1);
+  o.writeUInt8(type, 0);
+  o.writeUInt16BE(channel, 1);
+  o.writeUInt32BE(payload.length, 3);
+  payload.copy(o, 7);
+  o.writeUInt8(FRAME_END, 7 + payload.length);
+  return o;
+}
+function method(channel: number, classId: number, methodId: number, ...parts: Buffer[]): Buffer {
+  return frame(1, channel, Buffer.concat([u16(classId), u16(methodId), ...parts]));
+}
+
+interface MethodWaiter {
+  classId: number;
+  methodId: number;
+  resolve: (args: Buffer) => void;
+  reject: (e: Error) => void;
+}
+
+/**
+ * Connect, authenticate to the vhost, declare a queue, publish one message and get it back. Returns
+ * the body that came back — the caller checks it equals what went out. Throws on any protocol error,
+ * including the broker's `NOT_ALLOWED` refusal of a vhost the login has no permission on (the
+ * isolation the provider builds, seen from the consumer's side).
+ */
+export function roundTrip(conn: AmqpConn, queue = "amqp-ping", payload?: string): Promise<string> {
+  const body = Buffer.from(payload ?? `ping-${Date.now()}`);
+  return new Promise<string>((resolve, reject) => {
+    const sock: Socket = createConnection({ host: conn.host, port: conn.port });
+    let buf = Buffer.alloc(0);
+    const waiters: MethodWaiter[] = [];
+    let lastBody: Buffer | null = null;
+    let done = false;
+
+    const fail = (e: Error): void => {
+      if (done) return;
+      done = true;
+      sock.destroy();
+      reject(e);
+    };
+    const expect = (classId: number, methodId: number): Promise<Buffer> =>
+      new Promise((res, rej) => waiters.push({ classId, methodId, resolve: res, reject: rej }));
+
+    sock.on("error", (e) => fail(e));
+    sock.on("close", () => fail(new Error("amqp connection closed before the round-trip completed")));
+    sock.on("data", (chunk: Buffer) => {
+      buf = Buffer.concat([buf, chunk]);
+      for (;;) {
+        if (buf.length < 7) return;
+        const type = buf.readUInt8(0);
+        const size = buf.readUInt32BE(3);
+        if (buf.length < 7 + size + 1) return;
+        const framePayload = buf.subarray(7, 7 + size);
+        buf = buf.subarray(7 + size + 1);
+        if (type === 1) {
+          const classId = framePayload.readUInt16BE(0);
+          const methodId = framePayload.readUInt16BE(2);
+          const args = framePayload.subarray(4);
+          const w = waiters.shift();
+          if (!w) continue;
+          if (w.classId === classId && w.methodId === methodId) w.resolve(args);
+          else w.reject(new Error(`expected method ${w.classId}/${w.methodId}, got ${classId}/${methodId}: ${args.toString("utf8")}`));
+        } else if (type === 3) {
+          lastBody = framePayload; // a content body frame
+        }
+        // type 2 (content header) and type 8 (heartbeat) need no handling for this round-trip.
+      }
+    });
+
+    sock.on("connect", () => {
+      void (async () => {
+        try {
+          sock.write(PROTOCOL_HEADER);
+          await expect(10, 10); // Connection.Start
+          const response = Buffer.concat([
+            Buffer.from([0]), Buffer.from(conn.user, "utf8"), Buffer.from([0]), Buffer.from(conn.password, "utf8"),
+          ]);
+          // Connection.Start-Ok: empty client-properties table, PLAIN, the SASL response, locale.
+          sock.write(method(0, 10, 11, u32(0), shortstr("PLAIN"), longstr(response), shortstr("en_US")));
+          const tune = await expect(10, 30); // Connection.Tune
+          const frameMax = tune.readUInt32BE(2) || 131072;
+          sock.write(method(0, 10, 31, u16(tune.readUInt16BE(0)), u32(frameMax), u16(0))); // Tune-Ok, no heartbeat
+          sock.write(method(0, 10, 40, shortstr(conn.vhost), shortstr(""), Buffer.from([0]))); // Connection.Open
+          await expect(10, 41); // Open-Ok — authenticated and into the vhost
+
+          sock.write(method(1, 20, 10, shortstr(""))); // Channel.Open
+          await expect(20, 11);
+          // Queue.Declare: reserved, queue, bits(auto-delete=1), empty arguments table.
+          sock.write(method(1, 50, 10, u16(0), shortstr(queue), Buffer.from([0b00001000]), u32(0)));
+          await expect(50, 11);
+
+          // Basic.Publish to the default exchange, routing-key = queue; then content header + body.
+          sock.write(method(1, 60, 40, u16(0), shortstr(""), shortstr(queue), Buffer.from([0])));
+          const bodySize = Buffer.alloc(8);
+          bodySize.writeBigUInt64BE(BigInt(body.length), 0);
+          sock.write(frame(2, 1, Buffer.concat([u16(60), u16(0), bodySize, u16(0)]))); // content header, no properties
+          sock.write(frame(3, 1, body)); // content body
+
+          await new Promise((r) => setTimeout(r, 200));
+          lastBody = null;
+          sock.write(method(1, 60, 70, u16(0), shortstr(queue), Buffer.from([1]))); // Basic.Get, no-ack
+          await expect(60, 71); // Get-Ok (a Get-Empty would arrive as 60/72 and reject the expect)
+          await new Promise((r) => setTimeout(r, 200));
+          const received = lastBody ? (lastBody as Buffer).toString("utf8") : "";
+
+          sock.write(method(0, 10, 50, u16(200), shortstr("bye"), u16(0), u16(0))); // Connection.Close
+          await expect(10, 51).catch(() => undefined);
+          done = true;
+          sock.end();
+          resolve(received);
+        } catch (e) {
+          fail(e instanceof Error ? e : new Error(String(e)));
+        }
+      })();
+    });
+  });
+}
+
+function readMaybe(path: string | undefined): string {
+  if (!path) return "";
+  try {
+    return readFileSync(path, "utf8").replace(/\n$/, "");
+  } catch {
+    return "";
+  }
+}

modules/amqp-ping/index.ts

@@ -0,0 +1,53 @@
+// amqp-ping — a tiny demo consumer of the mesh `amqp` interface, run as a long-lived container by
+// `mesh-tools run` (it never returns, so the container stays up). It exists to PROVE the grant end to
+// end: the mesh gave it a scoped login and a vhost of that name on the lavinmq provider, and this
+// connects with exactly those and round-trips a message.
+//
+// The connection facts arrive the way every consumer's do — the mesh writes them into an env-file the
+// container reads (novox/hq ADR 0048): MESH_AMQP_HOST/PORT from the binding, MESH_AMQP_USER and
+// MESH_AMQP_VHOST both from `${bound:amqp:as}` (the provider named the vhost after the login, so the
+// consumer uses the login for both — the db-name lesson applied to AMQP), and MESH_AMQP_PASSWORD from
+// `${secret:amqp}`.
+//
+// It retries: on first boot the provider may not have provisioned this consumer yet (the reconcile is
+// asynchronous and cross-container), so a refused or unreachable connection is a "not yet", not a
+// failure — it waits and tries again until the round-trip succeeds, then holds the connection idle
+// and re-pings on a slow cadence so the container is a stable, running proof.
+
+import { connFromEnv, roundTrip } from "./client.js";
+
+async function sleep(ms: number): Promise<void> {
+  await new Promise((r) => setTimeout(r, ms));
+}
+
+async function pingOnce(): Promise<boolean> {
+  try {
+    const conn = connFromEnv();
+    const sent = `ping-${Date.now()}`;
+    const got = await roundTrip(conn, "amqp-ping", sent);
+    if (got === sent) {
+      console.log(`[amqp-ping] round-trip ok as ${conn.user} on vhost ${conn.vhost} (${conn.host}:${conn.port})`);
+      return true;
+    }
+    console.error(`[amqp-ping] round-trip mismatch: sent ${sent}, got ${got}`);
+    return false;
+  } catch (err) {
+    console.error(`[amqp-ping] not ready yet: ${err instanceof Error ? err.message : err}`);
+    return false;
+  }
+}
+
+// Wait for the first successful round-trip — the proof this consumer's grant works — then stay up.
+let first = false;
+for (let i = 0; !first; i++) {
+  first = await pingOnce();
+  if (!first) await sleep(3000);
+}
+console.log("[amqp-ping] connected and round-tripped; holding steady");
+for (;;) {
+  await sleep(30000);
+  await pingOnce();
+}
+// changed by the one-node test at build 66e54af151df
+// changed by the one-node test at build 4fb41636cffd
+// changed by the one-node test at build a69f083bf6a6

modules/amqp-ping/module.json

@@ -0,0 +1,89 @@
+{
+  "module": "amqp-ping",
+  "slug": "ping",
+  "version": "1",
+  "capabilities": [
+    "container-runtime"
+  ],
+  "requires": [
+    "amqp"
+  ],
+  "contributes": {},
+  "binds": {
+    "amqp": "/var/lib/amqp-ping/amqp.json"
+  },
+  "secrets": {
+    "amqp": "/var/lib/amqp-ping/amqp.secret"
+  },
+  "own-secrets": {
+    "broker": "/var/lib/mesh/amqp-ping/broker"
+  },
+  "resources": [
+    {
+      "id": "mesh-state",
+      "type": "directory",
+      "path": "/var/lib/mesh/amqp-ping",
+      "mode": "0700"
+    },
+    {
+      "id": "state",
+      "type": "directory",
+      "path": "/var/lib/amqp-ping",
+      "mode": "0700"
+    },
+    {
+      "id": "amqp-env",
+      "type": "file",
+      "path": "/var/lib/amqp-ping/amqp.env",
+      "mode": "0600",
+      "content": "MESH_AMQP_HOST=${bound:amqp:at}\nMESH_AMQP_PORT=${bound:amqp:port}\nMESH_AMQP_USER=${bound:amqp:as}\nMESH_AMQP_VHOST=${bound:amqp:as}\n"
+    },
+    {
+      "id": "net",
+      "type": "network",
+      "name": "amqp-ping"
+    },
+    {
+      "id": "runtime",
+      "type": "container",
+      "name": "amqp-ping",
+      "network": "amqp-ping",
+      "volumes": [
+        "/var/lib/mesh/amqp-ping/broker:/run/secrets/broker:ro",
+        "/var/lib/amqp-ping/amqp.secret:/run/secrets/amqp:ro"
+      ],
+      "env": {
+        "MESH_BROKER_FILE": "/run/secrets/broker",
+        "MESH_AMQP_PASSWORD_FILE": "/run/secrets/amqp"
+      },
+      "env-file": [
+        "/var/lib/amqp-ping/amqp.env"
+      ],
+      "restart-on": [
+        "amqp-env"
+      ],
+      "artifact": "runtime"
+    }
+  ],
+  "build": {
+    "on": [
+      {
+        "arg": "BUILD_BASE",
+        "module": "mesh-tools",
+        "artifact": "build"
+      },
+      {
+        "arg": "RUNTIME_BASE",
+        "module": "mesh-tools",
+        "artifact": "runtime"
+      }
+    ],
+    "artifacts": [
+      {
+        "name": "runtime",
+        "kind": "image",
+        "from": "Dockerfile"
+      }
+    ]
+  }
+}

modules/amqp-ping/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@novox/module-amqp-ping",
+  "version": "0.1.0",
+  "description": "amqp-ping — a demo consumer of the mesh amqp interface. Connects with its scoped grant and round-trips one message to prove the broker the mesh gave it (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/amqp-ping/tsconfig.json

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

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"
+    "module.anthropic-consumer.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", "module.anthropic-consumer.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,28 +9,28 @@
     "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"
+    "module.anthropic-manager.usage.read"
   ],
   "resources": [
     {
       "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/anthropic-manager/refresh/index.ts

@@ -143,7 +143,7 @@ async function emitUsage(body: Record<string, unknown>): Promise<void> {
   const main = process.env.MESH_TOOLS_MAIN ?? "/app/dist/main.js";
   const { spawn } = await import("node:child_process");
   await new Promise<void>((resolve) => {
-    const child = spawn(process.execPath, [main, "emit", "usage.read", JSON.stringify(body)], {
+    const child = spawn(process.execPath, [main, "emit", "module.anthropic-manager.usage.read", JSON.stringify(body)], {
       stdio: "inherit",
     });
     child.on("exit", () => resolve());

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

@@ -3,23 +3,29 @@
   "version": "1",
   "slug": "audit",
   "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,18 +15,16 @@ 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";
-  await emit("site.created", { domain: "my-app" });
+  await emit("module.umami.site.created", { domain: "my-app" });
   await emit("node.anchor.joined", { role: "worker" }); // a node event, not a module one
 
   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), ["module.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/client.ts

@@ -2,15 +2,12 @@
 // module's tools and anything else baserow-specific import it; nothing outside baserow does.
 //
 // Baserow authenticates a person with email + password, exchanged for a JWT at /api/user/token-auth/.
-// The standard image creates no admin from env, so the account is one a person made in Baserow: its
-// password is the module's `admin` secret, accepted from the operator, and its email and the public
-// host Baserow answers to reach the runtime config file the mesh mounts (the email from the
-// assignment's settings). Until both are there fromEnv throws and the module exposes no tools — the
-// same dormant-until-configured shape gitea uses for its token.
+// Those credentials are the mesh's own: a person signs up in Baserow (the standard image creates no
+// admin from env), and the credential is placed in the runtime config file the mesh mounts. Until
+// that happens fromEnv throws and the module simply exposes no tools — the same dormant-until-
+// configured shape gitea uses for its token.
 
 import { readFileSync } from "node:fs";
-import { request as httpRequest } from "node:http";
-import { request as httpsRequest } from "node:https";
 
 export interface BaserowApplication {
   id: number;
@@ -71,63 +68,35 @@ export class BaserowClient {
     return h;
   }
 
-  /**
-   * One HTTP exchange. Not `fetch`: Node's fetch drops a caller's Host header and sends the URL's
-   * own, and Baserow answers only the host of its BASEROW_PUBLIC_URL — any other Host is looked up
-   * as a published builder site and gets 404, `/api/_health/` included. A co-located caller reaching
-   * it by container name must present the public host, so the request is made with node:http, which
-   * sends the Host it is given.
-   */
-  private send(path: string, method: string, headers: Record<string, string>, body?: string): Promise<{ status: number; text: string }> {
-    const url = new URL(`${this.baseUrl}${path}`);
-    const request = url.protocol === "https:" ? httpsRequest : httpRequest;
-    // A length, never chunked: Baserow's server reads a chunked body as empty.
-    const sent = body === undefined ? headers : { ...headers, "Content-Length": String(Buffer.byteLength(body)) };
-    return new Promise((resolve, reject) => {
-      const req = request(url, { method, headers: sent }, (res) => {
-        let text = "";
-        res.setEncoding("utf8");
-        res.on("data", (chunk: string) => (text += chunk));
-        res.on("end", () => resolve({ status: res.statusCode ?? 0, text }));
-        res.on("error", reject);
-      });
-      req.on("error", reject);
-      if (body !== undefined) req.write(body);
-      req.end();
-    });
-  }
-
-  /** Exchange email + password for a JWT, caching it until Baserow refuses it. Handles both the
+  /** Exchange email + password for a JWT, caching it for the client's lifetime. Handles both the
    *  older `{ token }` and the newer `{ access_token }` response shapes. */
   async authenticate(): Promise<string> {
     if (this.token) return this.token;
-    const res = await this.send(
-      "/api/user/token-auth/",
-      "POST",
-      this.headers(),
-      JSON.stringify({ email: this.email, password: this.password }),
-    );
-    if (res.status < 200 || res.status >= 300) throw new Error(`baserow auth failed: ${res.status} ${res.text}`);
-    const data = JSON.parse(res.text) as { token?: string; access_token?: string };
+    const res = await fetch(`${this.baseUrl}/api/user/token-auth/`, {
+      method: "POST",
+      headers: this.headers(),
+      body: JSON.stringify({ email: this.email, password: this.password }),
+    });
+    if (!res.ok) throw new Error(`baserow auth failed: ${res.status} ${await res.text()}`);
+    const data = (await res.json()) as { token?: string; access_token?: string };
     const token = data.access_token ?? data.token;
     if (!token) throw new Error("baserow auth returned no token");
     this.token = token;
     return token;
   }
 
-  /** An authenticated GET. A refused token is dropped and the call made once more with a fresh one:
-   *  Baserow's access tokens expire after minutes, and the runtime lives for weeks. */
-  private async authed<T>(path: string): Promise<T> {
-    for (let attempt = 0; ; attempt++) {
-      const token = await this.authenticate();
-      const res = await this.send(path, "GET", this.headers({ Authorization: `JWT ${token}` }));
-      if (res.status === 401 && attempt === 0) {
-        this.token = null;
-        continue;
-      }
-      if (res.status < 200 || res.status >= 300) throw new Error(`baserow ${path}: ${res.status} ${res.text}`);
-      return (res.text ? JSON.parse(res.text) : null) as T;
-    }
+  private async authed<T>(path: string, options: RequestInit = {}): Promise<T> {
+    const token = await this.authenticate();
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      ...options,
+      headers: this.headers({
+        Authorization: `JWT ${token}`,
+        ...(options.headers as Record<string, string> | undefined),
+      }),
+    });
+    if (!res.ok) throw new Error(`baserow ${path}: ${res.status} ${await res.text()}`);
+    const text = await res.text();
+    return (text ? JSON.parse(text) : null) as T;
   }
 
   /** The applications (databases) the account can see, across all its workspaces. */

modules/baserow/module.json

@@ -14,53 +14,54 @@
     },
     "route": {
       "label": "baserow",
-      "endpoint": "web"
+      "port": 80
     }
   },
   "binds": {
-    "postgres-database": "${dir:state}/database.json",
-    "route": "${dir:state}/route.json"
+    "postgres-database": "/var/lib/baserow/database.json",
+    "route": "/var/lib/baserow/route.json"
   },
   "secrets": {
-    "postgres-database": "${dir:state}/database.secret"
+    "postgres-database": "/var/lib/baserow/database.secret"
   },
   "own-secrets": {
-    "admin": "${dir:state}/admin.secret"
+    "secret-key": "/var/lib/baserow/secret-key.secret",
+    "broker": "/var/lib/mesh/baserow/broker"
   },
   "listens": [
     {
-      "name": "web",
       "port": 80,
       "protocol": "tcp",
       "from": "mesh",
-      "why": "the Baserow web UI and REST API, served by the image's own Caddy; a public name is the route's"
+      "why": "the Baserow web UI and REST API; a public name is a route grant later"
     }
   ],
   "resources": [
     {
       "id": "mesh-state",
       "type": "directory",
-      "mode": "0700",
-      "place": "mesh"
+      "path": "/var/lib/mesh/baserow",
+      "mode": "0700"
     },
     {
       "id": "state",
       "type": "directory",
-      "mode": "0700",
-      "place": "."
+      "path": "/var/lib/baserow",
+      "mode": "0700"
     },
     {
       "id": "data",
       "type": "directory",
+      "path": "/services/baserow/data",
       "mode": "0755",
       "owner": "9999:9999"
     },
     {
       "id": "server-env",
       "type": "file",
-      "path": "${dir:state}/server.env",
+      "path": "/var/lib/baserow/server.env",
       "mode": "0600",
-      "content": "DATABASE_HOST=${bound:postgres-database:at}\nDATABASE_PORT=${bound:postgres-database:port}\nDATABASE_NAME=${bound:postgres-database:as}\nDATABASE_USER=${bound:postgres-database:as}\nDATABASE_PASSWORD_FILE=/run/secrets/database\nDISABLE_EMBEDDED_PSQL=true\nBASEROW_PUBLIC_URL=https://${bound:route:name}\n"
+      "content": "DATABASE_HOST=${bound:postgres-database:at}\nDATABASE_PORT=${bound:postgres-database:port}\nDATABASE_NAME=${bound:postgres-database:as}\nDATABASE_USER=${bound:postgres-database:as}\nDATABASE_PASSWORD=${secret:postgres-database}\nSECRET_KEY=${secret:secret-key}\nBASEROW_PUBLIC_URL=http://localhost\n"
     },
     {
       "id": "net",
@@ -71,44 +72,65 @@
       "id": "server",
       "type": "container",
       "name": "baserow",
-      "image": "baserow/baserow@sha256:263ea6c4b72c9eccabcd975ffe9fdebf23913a293a514bec6a3897a5e0a5a080",
+      "image": "baserow/baserow@sha256:834424a10413798567f76428f255dc259445b7f8dcec56598c05b4073bb2a124",
       "network": "baserow",
       "env-file": [
-        "${dir:state}/server.env"
+        "/var/lib/baserow/server.env"
       ],
       "ports": [
         "80"
       ],
       "volumes": [
-        "${dir:data}:/baserow/data",
-        "${dir:state}/database.secret:/run/secrets/database:ro"
-      ]
+        "/services/baserow/data:/baserow/data"
+      ],
+      "secrets-in-environment": "baserow reads DATABASE_PASSWORD and SECRET_KEY with os.getenv and has no _FILE twin (settings/base.py); not convertible"
     },
     {
       "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",
+      "content": "{}\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("module.bazarr.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,140 @@
+{
+  "module": "bazarr",
+  "version": "1",
+  "capabilities": [
+    "container-runtime"
+  ],
+  "emits": [
+    "module.bazarr.subtitle.downloaded"
+  ],
+  "own-secrets": {
+    "broker": "/var/lib/mesh/bazarr/broker",
+    "api-key": "/var/lib/mesh/bazarr/api-key"
+  },
+  "listens": [
+    {
+      "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",
+      "port": 6767
+    }
+  },
+  "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": [
-    "tools/index.ts",
-    "client.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("module.bookshelf.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("module.bookshelf.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,117 @@
+{
+  "module": "bookshelf",
+  "version": "1",
+  "slug": "books",
+  "capabilities": [
+    "container-runtime"
+  ],
+  "emits": [
+    "module.bookshelf.book.grabbed",
+    "module.bookshelf.download.completed"
+  ],
+  "consumes": [],
+  "own-secrets": {
+    "broker": "/var/lib/mesh/bookshelf/broker"
+  },
+  "listens": [
+    {
+      "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",
+      "port": 8787
+    }
+  },
+  "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

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

modules/build-agent/Dockerfile

@@ -1,25 +0,0 @@
-ARG GO_BASE
-ARG ALPINE_BASE
-# build-agent's image: the build machine itself, compiled into a container (novox/hq ADR 0190).
-#
-# **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
-# half of. This module ships the packaging, not a second copy of the source, so the build context
-# is the mesh-controller repository root (declared under build.artifacts[].context), and this
-# Dockerfile compiles ./cmd/mesh-builder from it — the same shape route-proxy already uses for the
-# same reason.
-FROM ${GO_BASE} AS build
-WORKDIR /src
-COPY go.mod go.sum ./
-RUN go mod download
-COPY . .
-RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -o /mesh-builder ./cmd/mesh-builder
-
-# Unlike mesh-controller's own FROM scratch (ADR 0006: nothing to audit but one binary), the build
-# machine's whole job is shelling out to git and docker — it needs a real userland to do that in,
-# not a second copy of either tool vendored into this image. apk installs both from the base's own
-# packages, not fetched on its own at build time.
-FROM ${ALPINE_BASE}
-RUN apk add --no-cache docker-cli git
-COPY --from=build /mesh-builder /usr/local/bin/mesh-builder
-ENTRYPOINT ["/usr/local/bin/mesh-builder"]

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/build-agent/module.json

@@ -1,89 +0,0 @@
-{
-  "module": "build-agent",
-  "version": "1",
-  "slug": "agent",
-  "capabilities": [
-    "container-runtime"
-  ],
-  "claims": [
-    {
-      "name": "node-build-agent",
-      "scope": "node"
-    }
-  ],
-  "requires": [
-    "artifact-store",
-    "npm-package-registry"
-  ],
-  "binds": {
-    "npm-package-registry": "${dir:mesh-state}/package-registry.json"
-  },
-  "secrets": {
-    "npm-package-registry": "${dir:mesh-state}/package-registry.secret"
-  },
-  "own-secrets": {
-    "broker": "${dir:mesh-state}/broker"
-  },
-  "resources": [
-    {
-      "id": "mesh-state",
-      "type": "directory",
-      "mode": "0700",
-      "place": "mesh"
-    },
-    {
-      "id": "workspace",
-      "type": "directory",
-      "mode": "0700"
-    },
-    {
-      "id": "agent-env",
-      "type": "file",
-      "path": "${dir:mesh-state}/build-agent.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"
-    },
-    {
-      "id": "server",
-      "type": "container",
-      "name": "mesh-build-agent",
-      "artifact": "server",
-      "env-file": [
-        "${dir:mesh-state}/build-agent.env"
-      ],
-      "volumes": [
-        "${dir:mesh-state}:/run/mesh:ro",
-        "${dir:workspace}:${dir:workspace}",
-        "/var/run/docker.sock:/var/run/docker.sock"
-      ],
-      "restart-on": [
-        "agent-env"
-      ],
-      "network": "host"
-    }
-  ],
-  "build": {
-    "artifacts": [
-      {
-        "name": "server",
-        "kind": "image",
-        "from": "Dockerfile",
-        "context": {
-          "seat": "git",
-          "repository": "novox/mesh-controller",
-          "ref": "main"
-        }
-      }
-    ],
-    "on": [
-      {
-        "arg": "GO_BASE",
-        "image": "golang@sha256:8ac98ca534ac3f51e1f420a1dd2c15e74c75cfa0f23f3ad27eb5d7236c349a0c"
-      },
-      {
-        "arg": "ALPINE_BASE",
-        "image": "alpine@sha256:d9e853e87e55526f6b2917df91a2115c36dd7c696a35be12163d44e6e2a4b6bc"
-      }
-    ]
-  }
-}

modules/builder/module.json

@@ -0,0 +1,78 @@
+{
+  "module": "builder",
+  "version": "1",
+  "capabilities": [
+    "container-runtime"
+  ],
+  "claims": [
+    {
+      "name": "the-build-machine",
+      "scope": "node"
+    }
+  ],
+  "requires": [
+    "artifact-store"
+  ],
+  "emits": [
+    "module.builder.built"
+  ],
+  "own-secrets": {
+    "broker": "/var/lib/mesh/builder/broker",
+    "npm-password": "/var/lib/mesh/builder/npm-password"
+  },
+  "resources": [
+    {
+      "id": "mesh-state",
+      "type": "directory",
+      "path": "/var/lib/mesh/builder",
+      "mode": "0700"
+    },
+    {
+      "id": "workspace",
+      "type": "directory",
+      "path": "/var/lib/builder/workspace",
+      "mode": "0700"
+    },
+    {
+      "id": "builder-env",
+      "type": "file",
+      "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/npm-password\nMESH_WORKSPACE=/var/lib/builder/workspace\n"
+    },
+    {
+      "id": "package-binding",
+      "type": "file",
+      "path": "/var/lib/mesh/builder/package-registry.json",
+      "mode": "0600",
+      "merge": "json",
+      "protected": [
+        "provision",
+        "from",
+        "at",
+        "as"
+      ],
+      "content": "{\"provision\": \"package-registry\", \"from\": \"gitea\", \"at\": \"127.0.0.1\", \"as\": \"mesh-builder\", \"serves\": {\"scheme\": \"http\", \"port\": 3000, \"npm-path\": \"/api/packages/novox/npm/\"}}\n"
+    },
+    {
+      "id": "server",
+      "type": "container",
+      "name": "mesh-builder",
+      "image": "mesh-builder@sha256:0000000000000000000000000000000000000000000000000000000000000000",
+      "env-file": [
+        "/var/lib/mesh/builder/builder.env"
+      ],
+      "volumes": [
+        "/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": [
+        "builder-env",
+        "package-binding",
+        "needs-npm-password"
+      ],
+      "network": "host"
+    }
+  ]
+}

modules/ca-trust/module.json

@@ -1,56 +0,0 @@
-{
-  "module": "ca-trust",
-  "version": "1",
-  "slug": "catrust",
-  "capabilities": [
-    "service-manager"
-  ],
-  "requires": [
-    "internal-acme-ca"
-  ],
-  "seats": [
-    {
-      "name": "the-mesh-trust-anchor",
-      "scope": "node"
-    }
-  ],
-  "claims": [
-    {
-      "name": "the-mesh-trust-anchor",
-      "scope": "node"
-    }
-  ],
-  "resources": [
-    {
-      "id": "state",
-      "type": "directory",
-      "mode": "0700",
-      "place": "."
-    },
-    {
-      "id": "anchor",
-      "type": "file",
-      "path": "${dir:state}/anchor",
-      "mode": "0755",
-      "content": "#!/bin/sh\n# The mesh's internal certificate authority, trusted by this machine.\n#\n# Written by the mesh from the ca-trust module's manifest (novox/hq ADR 0147).\n# Editing it here lasts until the next apply.\n#\n# There is no prior trust to verify the fetch against \u2014 this is the thing that\n# establishes it \u2014 so it is made over the mesh's own private network, which is\n# what authenticates it (novox/hq ADR 0098, the same reasoning that lets the\n# route proxy fetch this root for itself). What comes back is checked here: a\n# body that is not a certificate is refused now, rather than believed and then\n# failed by whatever reads the trust store next.\nset -eu\n\nROOTS='https://${bound:internal-acme-ca:at}:${bound:internal-acme-ca:port}${bound:internal-acme-ca:roots}'\nANCHORS=/etc/ca-certificates/trust-source/anchors\nANCHOR=\"$ANCHORS/mesh-internal-ca.crt\"\n\n# Arch's layout, said out loud rather than assumed: a machine that keeps its\n# anchors elsewhere fails here, visibly, instead of writing a file nothing\n# reads. That failure is the signal that this belongs in the host, where one\n# operating system's difference lives (novox/hq ADR 0147, option 2).\n[ -d \"$ANCHORS\" ] || {\n\techo \"this machine keeps no trust anchors in $ANCHORS; ca-trust is written for that layout\" >&2\n\texit 1\n}\n\ncase \"${1:-}\" in\ninstall)\n\ttmp=$(mktemp)\n\ttrap 'rm -f \"$tmp\"' EXIT\n\t# The authority may still be starting, or this machine may have come up\n\t# before it: two minutes of asking, then an honest failure.\n\tn=0\n\twhile [ \"$n\" -lt 60 ]; do\n\t\tif curl --fail --silent --show-error --insecure --max-time 10 \\\n\t\t\t--output \"$tmp\" \"$ROOTS\" &&\n\t\t\tgrep -q 'BEGIN CERTIFICATE' \"$tmp\"; then\n\t\t\tinstall -m 0644 \"$tmp\" \"$ANCHOR\"\n\t\t\tupdate-ca-trust\n\t\t\texit 0\n\t\tfi\n\t\tn=$((n + 1))\n\t\tsleep 2\n\tdone\n\techo \"the authority at $ROOTS did not serve a certificate within two minutes\" >&2\n\texit 1\n\t;;\nremove)\n\t# What stopping the unit does, and therefore what being unassigned does.\n\trm -f \"$ANCHOR\"\n\tupdate-ca-trust\n\t;;\n*)\n\techo \"usage: $(basename \"$0\") install|remove\" >&2\n\texit 2\n\t;;\nesac\n"
-    },
-    {
-      "id": "unit",
-      "type": "file",
-      "path": "/etc/systemd/system/mesh-ca-trust.service",
-      "mode": "0644",
-      "content": "[Unit]\nDescription=The mesh's internal certificate authority, trusted by this machine\n# novox/hq ADR 0147. Starting this unit places the mesh's root among this\n# machine's trust anchors; stopping it takes the root away again, which is what\n# the host does when the module is no longer assigned here.\nWants=network-online.target\nAfter=network-online.target\n\n[Service]\nType=oneshot\nRemainAfterExit=yes\nExecStart=${dir:state}/anchor install\nExecStop=${dir:state}/anchor remove\n\n[Install]\nWantedBy=multi-user.target\n"
-    },
-    {
-      "id": "trust",
-      "type": "service",
-      "unit": "mesh-ca-trust.service",
-      "state": "running",
-      "boot": "enabled",
-      "restart-on": [
-        "anchor",
-        "unit"
-      ]
-    }
-  ]
-}

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/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"
+    "module.cloudflare-dns.record.created",
+    "module.cloudflare-dns.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/cloudflare-dns/provisioner/index.ts

@@ -20,7 +20,7 @@ runProvisioner("public-dns", {
   async create(p: Provision): Promise<void> {
     const fqdn = cloudflare.nameFor(p.as);
     await cloudflare.upsert(fqdn);
-    await announce("record.created", {
+    await announce("module.cloudflare-dns.record.created", {
       name: fqdn,
       target: cloudflare.ingress,
       consumer: p.consumer ?? "",
@@ -30,7 +30,7 @@ runProvisioner("public-dns", {
   async remove(p: { as: string }): Promise<void> {
     const fqdn = cloudflare.nameFor(p.as);
     await cloudflare.remove(fqdn);
-    await announce("record.removed", { name: fqdn, consumer: p.as });
+    await announce("module.cloudflare-dns.record.removed", { name: fqdn, consumer: p.as });
   },
 });
 

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

@@ -11,36 +11,35 @@
   "contributes": {
     "route": {
       "label": "de-spiegel",
-      "endpoint": "web"
+      "port": 35621
     }
   },
   "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": [
     {
-      "name": "web",
       "port": 35621,
       "protocol": "tcp",
       "from": "mesh",
-      "why": "the de-spiegel site and its /contact endpoint over http; its public name is a route grant, and route-proxy reaches it on this published port"
+      "why": "the de-spiegel site and its /contact endpoint over http; the public name de-spiegel.novox.be is a route grant, and route-proxy reaches it on this published port"
     }
   ],
   "resources": [
     {
       "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,15 +55,12 @@
       "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"
+        "35621:35621"
       ],
-      "secrets-in-environment": "the application's own code reads SMTP_AUTH_USER/PASS from the environment (de-spiegel server/index.js); converting is that repository's change",
-      "names-on-purpose": {
-        "registry-api.novox.be": "built outside the mesh, from the application's own repository, and pulled from the registry that built it; moves when that repository is a build source on the git seat (novox/hq ADR 0155, issue 122)"
-      }
+      "secrets-in-environment": "the application's own code reads SMTP_AUTH_USER/PASS from the environment (de-spiegel server/index.js); converting is that repository's change"
     }
   ]
 }

modules/dhcpcd/README.md

@@ -1,43 +0,0 @@
-# dhcpcd
-
-The uplink seat's module for a machine whose own network is dhcpcd's (novox/hq ADR 0117). It
-asks two things of dhcpcd, and nothing else: leave the resolver file to the mesh, and leave the
-private network's interface alone. It never declares an interface, an address, a route, a
-wireless network or its credentials — the link dhcpcd keeps is the only channel the mesh reaches
-the machine over.
-
-## What it writes
-
-Two lines into `/etc/dhcpcd.conf`, as the mesh's marked region (`into: block`) — dhcpcd reads no
-drop-in directory, so the mesh writes into its one file rather than over it (ADR 0102):
-
-- `nohook resolv.conf` — dhcpcd's resolv.conf hook rewrites `/etc/resolv.conf` on every lease it
-  takes or renews, which would silently replace the resolver `resolv-conf` names.
-- `denyinterfaces mesh0` — dhcpcd never asks for a lease on the private network's interface, and
-  never takes it down. dhcpcd leaves a point-to-point interface alone by default; this says so
-  rather than relying on it.
-
-**At the start of the file** (`at: start`). Both are global options, and dhcpcd reads every line
-after an `interface` or `ssid` line as that interface's own. A configured machine's file ends in
-exactly such a block (the interface, its static address), so appended at the end these two would
-quietly apply to one interface only.
-
-## Why it declares no service
-
-dhcpcd is the machine's, not the mesh's. The mesh never starts, stops or enables it: stopping it
-drops the address the machine is reached at, and a module unassigned by mistake must not be able
-to do that. And there is nothing to reload it with — `dhcpcd.service` reports `CanReload=no`, and
-a restart drops the lease. So the two lines take effect at **dhcpcd's next start**.
-
-On an adopted machine that is normally no gap: the predecessor wrote the same `nohook` line, and
-it is already in force. **On a machine that was not adopted, it is one:** until dhcpcd next
-starts (a reboot, or the operator restarting it in a window of their choosing), a lease renewal
-still rewrites `/etc/resolv.conf`, and `resolv-conf` puts it back at the next push. Assign this
-module before `resolv-conf` on such a machine, and restart dhcpcd once, by hand, when losing the
-link for a moment is acceptable.
-
-## One manager per machine
-
-It claims `the-uplink`: a machine runs one network manager, and assigning a second module that
-claims the seat is refused. Assigning this one to a machine whose network is NetworkManager's
-installs the package and writes the two lines, and starts nothing.

modules/dhcpcd/module.json

@@ -1,31 +0,0 @@
-{
-  "module": "dhcpcd",
-  "version": "1",
-  "capabilities": [
-    "package-manager",
-    "service-manager",
-    "uplink-dhcpcd"
-  ],
-  "claims": [
-    {
-      "name": "node-uplink",
-      "scope": "node"
-    }
-  ],
-  "resources": [
-    {
-      "id": "package",
-      "type": "package",
-      "package": "dhcpcd"
-    },
-    {
-      "id": "config",
-      "type": "file",
-      "path": "/etc/dhcpcd.conf",
-      "mode": "0644",
-      "into": "block",
-      "at": "start",
-      "content": "# The mesh's two lines (module dhcpcd, novox/hq ADR 0117). Global options, so\n# kept above any interface line; read at dhcpcd's next start.\nnohook resolv.conf\ndenyinterfaces mesh0\n"
-    }
-  ]
-}

modules/distribution/index.ts

@@ -33,7 +33,7 @@ async function pollCatalog(): Promise<void> {
     for (const tag of tags) {
       const id = `${repo}:${tag}`;
       if (!seen.has(id)) {
-        if (primed) await emit("image.pushed", { repo, tag });
+        if (primed) await emit("module.registry.image.pushed", { repo, tag });
         seen.add(id);
       }
     }

modules/distribution/module.json

@@ -9,15 +9,15 @@
   ],
   "claims": [
     {
-      "name": "mesh-artifact-store",
-      "scope": "mesh"
+      "name": "the-artifact-store",
+      "scope": "node"
     }
   ],
   "capabilities": [
     "container-runtime"
   ],
   "emits": [
-    "image.pushed"
+    "module.registry.image.pushed"
   ],
   "own-secrets": {
     "broker": "/var/lib/mesh/registry/broker"
@@ -29,7 +29,6 @@
   },
   "listens": [
     {
-      "name": "registry",
       "port": 5000,
       "protocol": "tcp",
       "from": "mesh",
@@ -43,12 +42,6 @@
       "path": "/var/lib/mesh/registry",
       "mode": "0700"
     },
-    {
-      "id": "registry-data",
-      "type": "directory",
-      "path": "/var/lib/mesh-registry",
-      "mode": "0700"
-    },
     {
       "id": "store",
       "type": "container",
@@ -58,11 +51,8 @@
         "5000:5000"
       ],
       "volumes": [
-        "/var/lib/mesh-registry:/var/lib/registry"
-      ],
-      "env": {
-        "REGISTRY_STORAGE_DELETE_ENABLED": "true"
-      }
+        "mesh-registry-data:/var/lib/registry"
+      ]
     }
   ]
 }

modules/dnsmasq/index.ts

@@ -20,10 +20,10 @@ async function poll(): Promise<void> {
   const now = new Map((await dnsmasq.answeredNames()).map((a) => [a.name, a.address]));
   if (primed) {
     for (const [name, address] of now) {
-      if (!known.has(name)) await emit("name.added", { name, address });
+      if (!known.has(name)) await emit("module.dnsmasq.name.added", { name, address });
     }
     for (const [name] of known) {
-      if (!now.has(name)) await emit("name.removed", { name });
+      if (!now.has(name)) await emit("module.dnsmasq.name.removed", { name });
     }
   }
   known.clear();

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

@@ -6,23 +6,10 @@
   ],
   "claims": [
     {
-      "name": "node-intrusion-prevention",
-      "scope": "node",
-      "serves": [
-        "status",
-        "banned",
-        "ban",
-        "unban"
-      ]
+      "name": "the-intrusion-prevention",
+      "scope": "node"
     }
   ],
-  "tools": [
-    "fail2ban_settings"
-  ],
-  "jailing": {
-    "into": "/etc/fail2ban/jail.d/mesh.conf",
-    "filter-into": "/etc/fail2ban/filter.d"
-  },
   "resources": [
     {
       "id": "package",
@@ -41,46 +28,26 @@
       "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\nbantime  = 10m\nfindtime = 10m\nmaxretry = 5\n\nbanaction = ufw\nbanaction_allports = iptables-allports\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"
-    },
-    {
-      "id": "log",
-      "type": "file",
-      "path": "/var/log/fail2ban.log",
-      "mode": "0640",
-      "create-once": true,
-      "content": ""
+      "content": "[sshd]\nenabled = true\nport    = ssh\nlogpath = %(sshd_log)s\nbackend = %(sshd_backend)s\nmaxretry = 5\n"
     },
     {
       "id": "jail-recidive",
       "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 +73,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
-}