claude-code keeps its MCP servers in state, not events (novox/hq ADR 0202)

One key per registration in the module's servers bucket — all.<server> or
<node>.<server> — watched by every node, so a node assigned after a
registration takes it at start, which the mcp.registered event could not do.
Also narrows apply()'s refusal by hand: the builder compiles without strict,
where the discriminated union does not narrow and the build failed.

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

@@ -14,10 +14,19 @@
   "secrets": {
     "model-access": "${dir:state}/access-token"
   },
+  "own-secrets": {
+    "broker": "${dir:mesh-state}/broker"
+  },
   "emits": [
     "usage.session"
   ],
   "resources": [
+    {
+      "id": "mesh-state",
+      "type": "directory",
+      "mode": "0700",
+      "place": "mesh"
+    },
     {
       "id": "state",
       "type": "directory",
@@ -37,39 +46,66 @@
     },
     {
       "id": "apply",
-      "type": "process",
+      "type": "container",
-      "name": "anthropic-consumer-apply",
+      "name": "mesh-anthropic-consumer-apply",
-      "artifact": "code",
+      "network": "host",
-      "run": [
-        "node",
-        "apply/index.js"
-      ],
       "schedule": "*/5 * * * *",
+      "args": [
+        "run",
+        "/app/modules/anthropic-consumer/dist/apply/index.js"
+      ],
+      "volumes": [
+        "${dir:state}:/run/state"
+      ],
       "env": {
-        "MESH_MODEL_ACCESS_SECRET_FILE": "${dir:state}/access-token",
+        "MESH_MODEL_ACCESS_SECRET_FILE": "/run/state/access-token",
-        "MESH_MODEL_ACCESS_BIND_FILE": "${dir:state}/model.json",
+        "MESH_MODEL_ACCESS_BIND_FILE": "/run/state/model.json",
-        "MESH_CLAUDE_CREDENTIALS_FILE": "${dir:state}/claude/.credentials.json",
+        "MESH_CLAUDE_CREDENTIALS_FILE": "/run/state/claude/.credentials.json",
-        "MESH_CLAUDE_IDENTITY_FILE": "${dir:state}/claude/.claude.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": [
+        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "${dir:state}:/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",
+        "name": "runtime",
-        "kind": "bundle",
+        "kind": "image",
-        "language": "typescript",
+        "from": "Dockerfile"
-        "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"
-        }
       }
     ]
   }

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
+// Runs as `mesh-tools run` (no broker), so events are emitted best-effort via the sibling mesh-tools
-// the runtime as this module; the totals are also written to a file so the reading is observable
+// `emit` primitive; the totals are also written to a file so the reading is observable without one.
-// 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 {
+  const main = process.env.MESH_TOOLS_MAIN ?? "/app/dist/main.js";
-    await emit("usage.session", body);
+  const { spawn } = await import("node:child_process");
-  } catch (err) {
+  await new Promise<void>((resolve) => {
+    const child = spawn(
+      process.execPath,
+      [main, "emit", "usage.session", JSON.stringify(body)],
+      { stdio: "inherit" },
+    );
+    child.on("exit", () => resolve());
+    child.on("error", (err) => {
       console.error(`[anthropic-consumer] could not emit usage: ${err}`);
-  }
+      resolve();
+    });
+  });
 }
 
-// The cadence the scheduled container had: once at start, then every five minutes. Not awaited, so the
+await main();
-// 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);

modules/audit-logger/Dockerfile

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

modules/audit-logger/module.json

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

modules/claude-code/README.md

@@ -0,0 +1,74 @@
+# 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 0202).
+
+| 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

@@ -0,0 +1,112 @@
+// 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

@@ -0,0 +1,50 @@
+// 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

@@ -0,0 +1,90 @@
+{
+  "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

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

modules/claude-code/package.json

@@ -0,0 +1,18 @@
+{
+  "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

@@ -0,0 +1,135 @@
+// 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

@@ -0,0 +1,77 @@
+// 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

@@ -0,0 +1,54 @@
+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

@@ -0,0 +1,19 @@
+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

@@ -0,0 +1,173 @@
+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

@@ -0,0 +1,40 @@
+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

@@ -0,0 +1,31 @@
+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

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

modules/claude-code/tsconfig.json

@@ -8,5 +8,5 @@
     "skipLibCheck": true,
     "noEmit": true
   },
-  "include": ["http.ts", "tools/index.ts"]
+  "include": ["seal.ts", "grant.ts", "identity.ts", "render.ts", "node.ts", "tools/index.ts"]
 }

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

@@ -18,13 +18,20 @@
     "public-dns": "${dir:grants}/mesh.json"
   },
   "own-secrets": {
-    "token": "${dir:state}/token"
+    "token": "${dir:state}/token",
+    "broker": "${dir:mesh-state}/broker"
   },
   "emits": [
     "record.created",
     "record.removed"
   ],
   "resources": [
+    {
+      "id": "mesh-state",
+      "type": "directory",
+      "mode": "0700",
+      "place": "mesh"
+    },
     {
       "id": "state",
       "type": "directory",
@@ -43,30 +50,48 @@
       "merge": "json",
       "content": "{}",
       "mode": "0600"
+    },
+    {
+      "id": "runtime",
+      "type": "container",
+      "name": "mesh-cloudflare-dns",
+      "network": "host",
+      "volumes": [
+        "${dir:state}/config.json:/run/config/config.json:ro",
+        "${dir:grants}:/grants",
+        "${dir:state}/token:/run/secrets/token:ro",
+        "${dir:mesh-state}/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",
+        "name": "runtime",
-        "kind": "bundle",
+        "kind": "image",
-        "language": "typescript",
+        "from": "Dockerfile"
-        "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"
-        }
       }
     ]
   }

modules/gitea/Dockerfile

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

modules/gitea/module.json

@@ -85,6 +85,9 @@
       "scope": "mesh"
     }
   ],
+  "own-secrets": {
+    "broker": "${dir:mesh-state}/broker"
+  },
   "resources": [
     {
       "id": "mesh-state",
@@ -177,6 +180,32 @@
       "mode": "0600",
       "content": "{}\n",
       "merge": "json"
+    },
+    {
+      "id": "runtime",
+      "type": "container",
+      "name": "mesh-gitea",
+      "network": "host",
+      "volumes": [
+        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "${dir:mesh-state}/config.json:/run/config/config.json:ro",
+        "${dir:grants}:${dir:grants}:ro",
+        "${dir:state}/admin.secret:/run/secrets/admin:ro",
+        "${dir:runtime-state}:/run/state"
+      ],
+      "env": {
+        "MESH_BROKER_FILE": "/run/secrets/broker",
+        "MESH_GITEA_URL": "http://127.0.0.1:${port:3000}",
+        "MESH_GITEA_CONFIG_FILE": "/run/config/config.json",
+        "MESH_GITEA_ADMIN_USER": "mesh-admin",
+        "MESH_GITEA_ADMIN_PASSWORD_FILE": "/run/secrets/admin",
+        "MESH_GITEA_STATE_DIR": "/run/state",
+        "MESH_RECEIVES": "${dir:grants}/npm.json"
+      },
+      "artifact": "runtime",
+      "restart-on": [
+        "runtime-config"
+      ]
     }
   ],
   "provides": [
@@ -190,29 +219,23 @@
     }
   ],
   "build": {
+    "on": [
+      {
+        "arg": "BUILD_BASE",
+        "module": "mesh-tools",
+        "artifact": "build"
+      },
+      {
+        "arg": "RUNTIME_BASE",
+        "module": "mesh-tools",
+        "artifact": "runtime"
+      }
+    ],
     "artifacts": [
       {
-        "name": "code",
+        "name": "runtime",
-        "kind": "bundle",
+        "kind": "image",
-        "language": "typescript",
+        "from": "Dockerfile"
-        "entrypoints": [
-          "index.js",
-          "tools/index.js",
-          "provisioner/index.js"
-        ],
-        "loads": [
-          "index.js",
-          "tools/index.js",
-          "provisioner/index.js"
-        ],
-        "env": {
-          "MESH_GITEA_URL": "http://127.0.0.1:${port:3000}",
-          "MESH_GITEA_CONFIG_FILE": "${dir:mesh-state}/config.json",
-          "MESH_GITEA_ADMIN_USER": "mesh-admin",
-          "MESH_GITEA_ADMIN_PASSWORD_FILE": "${dir:state}/admin.secret",
-          "MESH_GITEA_STATE_DIR": "${dir:runtime-state}",
-          "MESH_RECEIVES": "${dir:grants}/npm.json"
-        }
       }
     ]
   },

modules/grafana/Dockerfile

@@ -0,0 +1,24 @@
+# grafana'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/grafana
+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/grafana/dist /app/modules/grafana/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/grafana/dist/index.js,/app/modules/grafana/dist/tools/index.js

modules/grafana/module.json

@@ -5,7 +5,8 @@
     "alert.firing"
   ],
   "own-secrets": {
-    "admin": "${dir:mesh-state}/admin"
+    "admin": "${dir:mesh-state}/admin",
+    "broker": "${dir:mesh-state}/broker"
   },
   "capabilities": [
     "container-runtime"
@@ -111,6 +112,25 @@
       "mode": "0600",
       "content": "{\n  \"user\": \"admin\",\n  \"password\": \"${secret:admin}\"\n}\n",
       "merge": "json"
+    },
+    {
+      "id": "runtime",
+      "type": "container",
+      "name": "mesh-grafana",
+      "network": "host",
+      "volumes": [
+        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "${dir:mesh-state}/config.json:/run/config/config.json:ro"
+      ],
+      "env": {
+        "MESH_BROKER_FILE": "/run/secrets/broker",
+        "MESH_GRAFANA_URL": "http://127.0.0.1:${port:3000}",
+        "MESH_GRAFANA_CONFIG_FILE": "/run/config/config.json"
+      },
+      "restart-on": [
+        "runtime-config"
+      ],
+      "artifact": "runtime"
     }
   ],
   "requires": [
@@ -142,23 +162,23 @@
     "influxdb-api": "${dir:mesh-state}/influxdb-api"
   },
   "build": {
+    "on": [
+      {
+        "arg": "BUILD_BASE",
+        "module": "mesh-tools",
+        "artifact": "build"
+      },
+      {
+        "arg": "RUNTIME_BASE",
+        "module": "mesh-tools",
+        "artifact": "runtime"
+      }
+    ],
     "artifacts": [
       {
-        "name": "code",
+        "name": "runtime",
-        "kind": "bundle",
+        "kind": "image",
-        "language": "typescript",
+        "from": "Dockerfile"
-        "entrypoints": [
-          "index.js",
-          "tools/index.js"
-        ],
-        "loads": [
-          "index.js",
-          "tools/index.js"
-        ],
-        "env": {
-          "MESH_GRAFANA_URL": "http://127.0.0.1:${port:3000}",
-          "MESH_GRAFANA_CONFIG_FILE": "${dir:mesh-state}/config.json"
-        }
       }
     ]
   }

modules/home-assistant/Dockerfile

@@ -0,0 +1,27 @@
+# home-assistant'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/home-assistant
+COPY . .
+RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts provisions/hass.ts provisions/probe.ts provisions/connections.ts provisions/mesh.ts provisions/index.ts \
+      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
+
+FROM ${RUNTIME_BASE}
+COPY --from=build /app/modules/home-assistant/dist /app/modules/home-assistant/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/home-assistant/dist/index.js,/app/modules/home-assistant/dist/tools/index.js
+# NOT dist/provisions/index.js: that is a step the host runs to completion, named by the
+# `provisions` container's args as `mesh-tools run …` (novox/hq ADR 0052). Listed here it would run
+# inside the serving sidecar too, and exit it.

modules/home-assistant/module.json

@@ -9,6 +9,7 @@
     "state.changed"
   ],
   "own-secrets": {
+    "broker": "${dir:mesh-state}/broker",
     "token": "${dir:mesh-state}/token"
   },
   "listens": [
@@ -79,27 +80,55 @@
       "merge": "json"
     },
     {
-      "id": "provisions-env",
+      "id": "runtime",
-      "type": "file",
+      "type": "container",
-      "path": "${dir:state}/provisions.env",
+      "name": "mesh-home-assistant",
-      "mode": "0600",
+      "network": "host",
-      "content": "MESH_HOMEASSISTANT_URL=http://127.0.0.1:${port:8123}\nMESH_HOMEASSISTANT_TOKEN_FILE=${dir:mesh-state}/token\nMESH_PROVISIONS_DIR=${dir:state}\nMESH_WRITTEN_DIR=${dir:written}\n"
+      "volumes": [
+        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "${dir:mesh-state}/token:/run/secrets/token:ro",
+        "${dir:mesh-state}/config.json:/run/config/config.json:ro"
+      ],
+      "env": {
+        "MESH_BROKER_FILE": "/run/secrets/broker",
+        "MESH_HOMEASSISTANT_URL": "http://127.0.0.1:${port:8123}",
+        "MESH_HOMEASSISTANT_TOKEN_FILE": "/run/secrets/token",
+        "MESH_HOMEASSISTANT_CONFIG_FILE": "/run/config/config.json"
+      },
+      "restart-on": [
+        "runtime-config"
+      ],
+      "artifact": "runtime"
     },
     {
       "id": "provisions",
-      "type": "process",
+      "type": "container",
-      "name": "home-assistant-provisions",
+      "name": "mesh-home-assistant-provisions",
-      "artifact": "code",
+      "network": "host",
-      "run": [
-        "node",
-        "provisions/index.js"
-      ],
       "run-once": true,
-      "env-file": [
+      "volumes": [
-        "${dir:state}/provisions.env"
+        "${dir:mesh-state}/token:/run/secrets/token:ro",
+        "${dir:written}:/var/lib/home-assistant-provisions",
+        "${dir:state}/mqtt-topic.json:/run/provisions/mqtt-topic.json:ro",
+        "${dir:state}/mqtt-topic.secret:/run/provisions/mqtt-topic.secret:ro",
+        "${dir:state}/sonarr-api.json:/run/provisions/sonarr-api.json:ro",
+        "${dir:state}/sonarr-api.secret:/run/provisions/sonarr-api.secret:ro",
+        "${dir:state}/radarr-api.json:/run/provisions/radarr-api.json:ro",
+        "${dir:state}/radarr-api.secret:/run/provisions/radarr-api.secret:ro",
+        "${dir:state}/lidarr-api.json:/run/provisions/lidarr-api.json:ro",
+        "${dir:state}/lidarr-api.secret:/run/provisions/lidarr-api.secret:ro"
+      ],
+      "env": {
+        "MESH_HOMEASSISTANT_URL": "http://127.0.0.1:${port:8123}",
+        "MESH_HOMEASSISTANT_TOKEN_FILE": "/run/secrets/token",
+        "MESH_PROVISIONS_DIR": "/run/provisions",
+        "MESH_WRITTEN_DIR": "/var/lib/home-assistant-provisions"
+      },
+      "args": [
+        "run",
+        "/app/modules/home-assistant/dist/provisions/index.js"
       ],
       "restart-on": [
-        "provisions-env",
         "bound-mqtt-topic",
         "secret-mqtt-topic",
         "bound-sonarr-api",
@@ -108,7 +137,8 @@
         "secret-radarr-api",
         "bound-lidarr-api",
         "secret-lidarr-api"
-      ]
+      ],
+      "artifact": "runtime"
     }
   ],
   "requires": [
@@ -143,25 +173,23 @@
     "lidarr-api": "${dir:state}/lidarr-api.secret"
   },
   "build": {
+    "on": [
+      {
+        "arg": "BUILD_BASE",
+        "module": "mesh-tools",
+        "artifact": "build"
+      },
+      {
+        "arg": "RUNTIME_BASE",
+        "module": "mesh-tools",
+        "artifact": "runtime"
+      }
+    ],
     "artifacts": [
       {
-        "name": "code",
+        "name": "runtime",
-        "kind": "bundle",
+        "kind": "image",
-        "language": "typescript",
+        "from": "Dockerfile"
-        "entrypoints": [
-          "index.js",
-          "tools/index.js",
-          "provisions/index.js"
-        ],
-        "loads": [
-          "index.js",
-          "tools/index.js"
-        ],
-        "env": {
-          "MESH_HOMEASSISTANT_URL": "http://127.0.0.1:${port:8123}",
-          "MESH_HOMEASSISTANT_TOKEN_FILE": "${dir:mesh-state}/token",
-          "MESH_HOMEASSISTANT_CONFIG_FILE": "${dir:mesh-state}/config.json"
-        }
       }
     ]
   }

modules/icecast/Dockerfile

@@ -0,0 +1,24 @@
+# icecast'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/icecast
+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/icecast/dist /app/modules/icecast/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/icecast/dist/index.js,/app/modules/icecast/dist/tools/index.js

modules/icecast/module.json

@@ -28,6 +28,9 @@
     "stream.started",
     "stream.stopped"
   ],
+  "own-secrets": {
+    "broker": "${dir:mesh-state}/broker"
+  },
   "listens": [
     {
       "name": "stream",
@@ -92,26 +95,45 @@
       "mode": "0600",
       "content": "{}\n",
       "merge": "json"
+    },
+    {
+      "id": "runtime",
+      "type": "container",
+      "name": "mesh-icecast",
+      "network": "icecast",
+      "volumes": [
+        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "${dir:mesh-state}/config.json:/run/config/config.json:ro"
+      ],
+      "env": {
+        "MESH_BROKER_FILE": "/run/secrets/broker",
+        "MESH_ICECAST_URL": "http://icecast:8000",
+        "MESH_ICECAST_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": "code",
+        "name": "runtime",
-        "kind": "bundle",
+        "kind": "image",
-        "language": "typescript",
+        "from": "Dockerfile"
-        "entrypoints": [
-          "index.js",
-          "tools/index.js"
-        ],
-        "loads": [
-          "index.js",
-          "tools/index.js"
-        ],
-        "env": {
-          "MESH_ICECAST_URL": "http://127.0.0.1:${port:8000}",
-          "MESH_ICECAST_CONFIG_FILE": "${dir:mesh-state}/config.json"
-        }
       }
     ]
   }

modules/influxdb/Dockerfile

@@ -0,0 +1,24 @@
+# influxdb'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/influxdb
+COPY . .
+RUN node /app/node_modules/typescript/bin/tsc client.ts grants.ts provisioner/index.ts tools/index.ts \
+      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
+
+FROM ${RUNTIME_BASE}
+COPY --from=build /app/modules/influxdb/dist /app/modules/influxdb/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/influxdb/dist/tools/index.js,/app/modules/influxdb/dist/provisioner/index.js

modules/influxdb/module.json

@@ -11,6 +11,7 @@
     "container-runtime"
   ],
   "own-secrets": {
+    "broker": "${dir:mesh-state}/broker",
     "admin": "${dir:state}/admin.secret",
     "admin-token": "${dir:state}/admin-token.secret"
   },
@@ -99,6 +100,29 @@
       "mode": "0600",
       "content": "{}\n",
       "merge": "json"
+    },
+    {
+      "id": "runtime",
+      "type": "container",
+      "name": "mesh-influxdb",
+      "network": "host",
+      "volumes": [
+        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "${dir:mesh-state}/config.json:/run/config/config.json:ro",
+        "${dir:state}/admin-token.secret:/run/secrets/admin-token:ro",
+        "${dir:grants}:${dir:grants}:ro"
+      ],
+      "env": {
+        "MESH_BROKER_FILE": "/run/secrets/broker",
+        "MESH_INFLUXDB_URL": "http://127.0.0.1:${port:8086}",
+        "MESH_INFLUXDB_CONFIG_FILE": "/run/config/config.json",
+        "MESH_INFLUXDB_TOKEN_FILE": "/run/secrets/admin-token",
+        "MESH_RECEIVES": "${dir:grants}/mesh.json"
+      },
+      "restart-on": [
+        "runtime-config"
+      ],
+      "artifact": "runtime"
     }
   ],
   "requires": [
@@ -111,25 +135,23 @@
     }
   },
   "build": {
+    "on": [
+      {
+        "arg": "BUILD_BASE",
+        "module": "mesh-tools",
+        "artifact": "build"
+      },
+      {
+        "arg": "RUNTIME_BASE",
+        "module": "mesh-tools",
+        "artifact": "runtime"
+      }
+    ],
     "artifacts": [
       {
-        "name": "code",
+        "name": "runtime",
-        "kind": "bundle",
+        "kind": "image",
-        "language": "typescript",
+        "from": "Dockerfile"
-        "entrypoints": [
-          "tools/index.js",
-          "provisioner/index.js"
-        ],
-        "loads": [
-          "tools/index.js",
-          "provisioner/index.js"
-        ],
-        "env": {
-          "MESH_INFLUXDB_URL": "http://127.0.0.1:${port:8086}",
-          "MESH_INFLUXDB_CONFIG_FILE": "${dir:mesh-state}/config.json",
-          "MESH_INFLUXDB_TOKEN_FILE": "${dir:state}/admin-token.secret",
-          "MESH_RECEIVES": "${dir:grants}/mesh.json"
-        }
       }
     ]
   }

modules/keycloak/Dockerfile

@@ -0,0 +1,30 @@
+# keycloak'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
+# Compiled under /app/modules so `@novox/mesh-sdk` resolves upward into the base's own
+# node_modules — the module is compiled against exactly the sdk it will run against. The compiler
+# is invoked by its real path: node_modules/.bin entries are launcher symlinks the base image
+# resolved away.
+WORKDIR /app/modules/keycloak
+COPY . .
+RUN node /app/node_modules/typescript/bin/tsc client.ts oidc.ts index.ts provisioner/index.ts tools/index.ts \
+      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
+
+FROM ${RUNTIME_BASE}
+COPY --from=build /app/modules/keycloak/dist /app/modules/keycloak/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. A container that instead ran only its
+# provisioner (`run`) served no tools and emitted no events; a container that named no command
+# ran no provisioner at all.
+ENV MESH_TOOL_MODULES=/app/modules/keycloak/dist/index.js,/app/modules/keycloak/dist/tools/index.js,/app/modules/keycloak/dist/provisioner/index.js

modules/keycloak/module.json

@@ -62,7 +62,8 @@
     "oidc-client": "${dir:grants}"
   },
   "own-secrets": {
-    "admin": "${dir:state}/admin.secret"
+    "admin": "${dir:state}/admin.secret",
+    "broker": "${dir:mesh-state}/broker"
   },
   "resources": [
     {
@@ -143,30 +144,49 @@
       "mode": "0600",
       "content": "{}\n",
       "merge": "json"
+    },
+    {
+      "id": "runtime",
+      "type": "container",
+      "name": "mesh-keycloak",
+      "network": "host",
+      "volumes": [
+        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "${dir:mesh-state}/config.json:/run/config/config.json:ro",
+        "${dir:state}/admin.secret:/run/secrets/admin:ro",
+        "${dir:grants}:${dir:grants}:ro"
+      ],
+      "env": {
+        "MESH_BROKER_FILE": "/run/secrets/broker",
+        "MESH_KEYCLOAK_URL": "http://127.0.0.1:${port:8080}",
+        "MESH_KEYCLOAK_CONFIG_FILE": "/run/config/config.json",
+        "MESH_KEYCLOAK_PASSWORD_FILE": "/run/secrets/admin",
+        "MESH_RECEIVES": "${dir:grants}/mesh.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": "code",
+        "name": "runtime",
-        "kind": "bundle",
+        "kind": "image",
-        "language": "typescript",
+        "from": "Dockerfile"
-        "entrypoints": [
-          "index.js",
-          "tools/index.js",
-          "provisioner/index.js"
-        ],
-        "loads": [
-          "index.js",
-          "tools/index.js",
-          "provisioner/index.js"
-        ],
-        "env": {
-          "MESH_KEYCLOAK_URL": "http://127.0.0.1:${port:8080}",
-          "MESH_KEYCLOAK_CONFIG_FILE": "${dir:mesh-state}/config.json",
-          "MESH_KEYCLOAK_PASSWORD_FILE": "${dir:state}/admin.secret",
-          "MESH_RECEIVES": "${dir:grants}/mesh.json"
-        }
       }
     ]
   }

modules/lab/Dockerfile

@@ -0,0 +1,31 @@
+# lab's runtime: the tool runtime, carrying this module's code, and the toolchain the lab's suite
+# builds the mesh with (novox/hq ADR 0172). It reaches the machine's virtualisation and container
+# runtime through their sockets, so what it raises is what a hand run on this machine raises.
+#
+# Every download is pinned by its checksum: an image that builds the mesh is the last place to take
+# whatever an upstream serves today.
+ARG BUILD_BASE
+ARG RUNTIME_BASE
+
+FROM ${BUILD_BASE} AS build
+WORKDIR /app/modules/lab
+COPY . .
+RUN node /app/node_modules/typescript/bin/tsc tools/index.ts tools/runs.ts --rootDir . \
+      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
+
+FROM ${RUNTIME_BASE}
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends git make ca-certificates curl python3 file iproute2 sudo \
+ && rm -rf /var/lib/apt/lists/*
+RUN curl -fsSL -o /tmp/go.tgz https://go.dev/dl/go1.26.8.linux-amd64.tar.gz \
+ && echo "d0f743b33e8d8945e6b1f432edd15785c70507121d6e2a723b21285eddf8b57b  /tmp/go.tgz" | sha256sum -c - \
+ && tar -C /usr/local -xzf /tmp/go.tgz && rm /tmp/go.tgz
+RUN curl -fsSL -o /usr/local/bin/incus https://github.com/lxc/incus/releases/download/v7.5.1/bin.linux.incus.x86_64 \
+ && echo "7bd6223b369f4d693fcde695bd8549a73b5b3d403735329212483702aa22c179  /usr/local/bin/incus" | sha256sum -c - \
+ && chmod 0755 /usr/local/bin/incus
+RUN curl -fsSL -o /tmp/docker.tgz https://download.docker.com/linux/static/stable/x86_64/docker-28.5.2.tgz \
+ && echo "ea90cfd12e1eeb12aa1c971741adb8bd4ed88e2a574eaac13f5029a1dbc6300d  /tmp/docker.tgz" | sha256sum -c - \
+ && tar -C /tmp -xzf /tmp/docker.tgz docker/docker && mv /tmp/docker/docker /usr/local/bin/docker && rm -rf /tmp/docker /tmp/docker.tgz
+ENV PATH=/usr/local/go/bin:$PATH
+COPY --from=build /app/modules/lab/dist /app/modules/lab/dist
+ENV MESH_TOOL_MODULES=/app/modules/lab/dist/tools/index.js

modules/lab/module.json

@@ -5,7 +5,16 @@
     "container-runtime",
     "virtualisation"
   ],
+  "own-secrets": {
+    "broker": "${dir:mesh-state}/broker"
+  },
   "resources": [
+    {
+      "id": "mesh-state",
+      "type": "directory",
+      "mode": "0700",
+      "place": "mesh"
+    },
     {
       "id": "state",
       "type": "directory",
@@ -26,67 +35,47 @@
       "content": "MESH_LAB_FORGE=${setting:forge}\n"
     },
     {
-      "id": "git",
+      "id": "runtime",
-      "type": "package",
+      "type": "container",
-      "package": "git"
+      "name": "mesh-lab",
+      "network": "host",
+      "env-file": [
+        "${dir:state}/lab.env"
+      ],
+      "volumes": [
+        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "${dir:work}:${dir:work}",
+        "/var/run/docker.sock:/var/run/docker.sock",
+        "/var/lib/incus/unix.socket:/var/lib/incus/unix.socket"
+      ],
+      "env": {
+        "MESH_BROKER_FILE": "/run/secrets/broker",
+        "MESH_LAB_WORK": "${dir:work}"
       },
-    {
+      "restart-on": [
-      "id": "make",
+        "runtime-env"
-      "type": "package",
+      ],
-      "package": "make"
+      "artifact": "runtime"
-    },
-    {
-      "id": "python",
-      "type": "package",
-      "package": "python"
-    },
-    {
-      "id": "file",
-      "type": "package",
-      "package": "file"
-    },
-    {
-      "id": "iproute2",
-      "type": "package",
-      "package": "iproute2"
-    },
-    {
-      "id": "sudo",
-      "type": "package",
-      "package": "sudo"
-    },
-    {
-      "id": "npm",
-      "type": "package",
-      "package": "npm"
-    },
-    {
-      "id": "go",
-      "type": "package",
-      "package": "go"
-    },
-    {
-      "id": "incus",
-      "type": "package",
-      "package": "incus"
     }
   ],
   "build": {
+    "on": [
+      {
+        "arg": "BUILD_BASE",
+        "module": "mesh-tools",
+        "artifact": "build"
+      },
+      {
+        "arg": "RUNTIME_BASE",
+        "module": "mesh-tools",
+        "artifact": "runtime"
+      }
+    ],
     "artifacts": [
       {
-        "name": "code",
+        "name": "runtime",
-        "kind": "bundle",
+        "kind": "image",
-        "language": "typescript",
+        "from": "Dockerfile"
-        "entrypoints": [
-          "tools/index.js"
-        ],
-        "loads": [
-          "tools/index.js"
-        ],
-        "env": {
-          "MESH_LAB_WORK": "${dir:work}",
-          "MESH_LAB_ENV_FILE": "${dir:state}/lab.env"
-        }
       }
     ]
   }

modules/lab/tools/index.ts

@@ -2,23 +2,18 @@
 // lab is assigned to, and only there: a bed raises virtual machines on that machine's virtualisation.
 
 import { spawnSync } from "node:child_process";
-import { readFileSync } from "node:fs";
 import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
 import { listRuns, readStatus, REPOSITORIES, running, start, stop, tail } from "./runs.js";
 
 export function getLabTools(env: NodeJS.ProcessEnv): ToolDefinition[] {
   const work = env.MESH_LAB_WORK ?? "/var/lib/mesh-lab-runs";
-  // The forge is an operator's setting, which reaches a file and never a bundle's words (novox/hq
+  const forge = (env.MESH_LAB_FORGE ?? "").replace(/\/+$/, "");
-  // ADR 0192): read from the env-file the mesh fills, at each call, so a changed setting is used
-  // without restarting the runtime. MESH_LAB_FORGE itself still wins, for a hand-run instance.
-  const forgeOf = (): string => (env.MESH_LAB_FORGE ?? wordIn(env.MESH_LAB_ENV_FILE, "MESH_LAB_FORGE")).replace(/\/+$/, "");
   return [
     {
       name: "lab_check",
       description: "Whether this machine can run the lab's beds: the lab's own check, against the forge's main branch.",
       input: {},
       run: async () => {
-        const forge = forgeOf();
         if (!forge) return { ok: false, output: "the lab's forge is not set: settings for lab, {\"forge\": \"<url>\"}" };
         const dir = `${work}/check`;
         spawnSync("rm", ["-rf", dir]);
@@ -43,7 +38,6 @@ export function getLabTools(env: NodeJS.ProcessEnv): ToolDefinition[] {
         },
       },
       run: async (args) => {
-        const forge = forgeOf();
         if (!forge) return { started: false, reason: "the lab's forge is not set: settings for lab, {\"forge\": \"<url>\"}" };
         const tests = String(args.tests ?? "").split(",").map((s) => s.trim()).filter(Boolean);
         if (tests.length === 0) return { started: false, reason: "name at least one bed test file" };
@@ -89,20 +83,4 @@ export function getLabTools(env: NodeJS.ProcessEnv): ToolDefinition[] {
   ];
 }
 
-/** One word from an env-file (`KEY=value` lines), or "" when the file or the word is absent. */
-export function wordIn(file: string | undefined, word: string): string {
-  if (!file) return "";
-  let text: string;
-  try {
-    text = readFileSync(file, "utf8");
-  } catch {
-    return "";
-  }
-  for (const line of text.split("\n")) {
-    const at = line.indexOf("=");
-    if (at > 0 && line.slice(0, at).trim() === word) return line.slice(at + 1).trim();
-  }
-  return "";
-}
-
 registerModuleTools("lab", (env) => getLabTools(env));

modules/mailu/Dockerfile

@@ -0,0 +1,30 @@
+# mailu'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
+# Compiled under /app/modules so `@novox/mesh-sdk` resolves upward into the base's own
+# node_modules — the module is compiled against exactly the sdk it will run against. The compiler
+# is invoked by its real path: node_modules/.bin entries are launcher symlinks the base image
+# resolved away.
+WORKDIR /app/modules/mailu
+COPY . .
+RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts provisioner/index.ts \
+      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
+
+FROM ${RUNTIME_BASE}
+COPY --from=build /app/modules/mailu/dist /app/modules/mailu/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. A container that instead ran only its
+# provisioner (`run`) served no tools and emitted no events; a container that named no command
+# ran no provisioner at all.
+ENV MESH_TOOL_MODULES=/app/modules/mailu/dist/index.js,/app/modules/mailu/dist/tools/index.js,/app/modules/mailu/dist/provisioner/index.js

modules/mailu/module.json

@@ -135,15 +135,11 @@
       "protocol": "tcp",
       "from": "mesh",
       "why": "automx: mail client autoconfiguration; the autoconfig, autodiscover and automx names are route grants reaching it here"
-    },
-    {
-      "name": "admin-api",
-      "port": 8080,
-      "protocol": "tcp",
-      "from": "machine",
-      "why": "the admin API, which this module's own code reaches on loopback from the node's runtime now that it runs outside the mailu network"
     }
   ],
+  "own-secrets": {
+    "broker": "${dir:mesh-state}/broker"
+  },
   "resources": [
     {
       "id": "mesh-state",
@@ -309,9 +305,6 @@
       "name": "mailu-admin",
       "image": "ghcr.io/mailu/admin@sha256:6dbfdadc4a9590dcb7652357b505200115b689b74008653bbf369e4599a3be5a",
       "network": "mailu",
-      "ports": [
-        "8080"
-      ],
       "env-file": [
         "${dir:state}/mailu.env",
         "${dir:state}/secret.env",
@@ -480,6 +473,31 @@
       "content": "{}\n",
       "merge": "json"
     },
+    {
+      "id": "runtime",
+      "type": "container",
+      "name": "mesh-mailu",
+      "network": "mailu",
+      "volumes": [
+        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "${dir:state}/api-token.secret:/run/secrets/api-token:ro",
+        "${dir:grants}:${dir:grants}:ro",
+        "${dir:mesh-state}/config.json:/run/config/config.json:ro",
+        "/var/run/docker.sock:/var/run/docker.sock"
+      ],
+      "env": {
+        "MESH_BROKER_FILE": "/run/secrets/broker",
+        "MESH_MAILU_URL": "http://mailu-admin:8080/api/v1",
+        "MESH_MAILU_API_KEY_FILE": "/run/secrets/api-token",
+        "MESH_MAILU_IMAP_CONTAINER": "mailu-imap",
+        "MESH_MAILU_CONFIG_FILE": "/run/config/config.json",
+        "MESH_RECEIVES": "${dir:grants}/mesh.json"
+      },
+      "restart-on": [
+        "runtime-config"
+      ],
+      "artifact": "runtime"
+    },
     {
       "id": "automx",
       "type": "container",
@@ -499,6 +517,16 @@
   ],
   "build": {
     "on": [
+      {
+        "arg": "BUILD_BASE",
+        "module": "mesh-tools",
+        "artifact": "build"
+      },
+      {
+        "arg": "RUNTIME_BASE",
+        "module": "mesh-tools",
+        "artifact": "runtime"
+      },
       {
         "arg": "PYTHON_BASE",
         "image": "python@sha256:25f3cfeaceca14921366af4d1240b56457ef46273bdb508c7b0e8f469f6fd228"
@@ -506,26 +534,9 @@
     ],
     "artifacts": [
       {
-        "name": "code",
+        "name": "runtime",
-        "kind": "bundle",
+        "kind": "image",
-        "language": "typescript",
+        "from": "Dockerfile"
-        "entrypoints": [
-          "index.js",
-          "tools/index.js",
-          "provisioner/index.js"
-        ],
-        "loads": [
-          "index.js",
-          "tools/index.js",
-          "provisioner/index.js"
-        ],
-        "env": {
-          "MESH_MAILU_URL": "http://127.0.0.1:${port:8080}/api/v1",
-          "MESH_MAILU_API_KEY_FILE": "${dir:state}/api-token.secret",
-          "MESH_MAILU_IMAP_CONTAINER": "mailu-imap",
-          "MESH_MAILU_CONFIG_FILE": "${dir:mesh-state}/config.json",
-          "MESH_RECEIVES": "${dir:grants}/mesh.json"
-        }
       },
       {
         "name": "automx",

modules/mesh-vault/Dockerfile

@@ -0,0 +1,22 @@
+# mesh-vault's runtime: the tool runtime, carrying this module's compiled provisioner, tools and event
+# consumer. The same shape as postgres's, minus the client the database needs: mesh-vault reaches no
+# server, because what it provides is a value the mesh already delivered to its node.
+#
+# **Built from this module's own directory and nothing else.** The sdk is in the base image, so
+# nothing is copied out of a neighbouring checkout (novox/hq ADR 0069). Two bases, named rather than
+# pinned — the image this is COMPILED in and the image it RUNS in — answered by the mesh from
+# `build.on` in module.json (novox/hq issue 044).
+ARG BUILD_BASE
+ARG RUNTIME_BASE
+
+FROM ${BUILD_BASE} AS build
+WORKDIR /app/modules/vault
+COPY . .
+RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts provisioner/index.ts tools/index.ts \
+      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
+
+FROM ${RUNTIME_BASE}
+COPY --from=build /app/modules/vault/dist /app/modules/vault/dist
+# The entrypoints a tool host loads from this module: its event consumer, its tools and its
+# provisioner — one image, one process, one broker account (novox/hq ADR 0052).
+ENV MESH_TOOL_MODULES=/app/modules/vault/dist/index.js,/app/modules/vault/dist/tools/index.js,/app/modules/vault/dist/provisioner/index.js

modules/mesh-vault/module.json

@@ -27,7 +27,16 @@
     "secret": "${dir:grants}"
   },
   "keeps": "/var/lib/mesh-vault/root",
+  "own-secrets": {
+    "broker": "${dir:mesh-state}/broker"
+  },
   "resources": [
+    {
+      "id": "mesh-state",
+      "type": "directory",
+      "mode": "0700",
+      "place": "mesh"
+    },
     {
       "id": "state",
       "type": "directory",
@@ -48,29 +57,45 @@
       "id": "root",
       "type": "directory",
       "mode": "0700"
-    }
+    },
-  ],
-  "build": {
-    "artifacts": [
     {
-        "name": "code",
+      "id": "runtime",
-        "kind": "bundle",
+      "type": "container",
-        "language": "typescript",
+      "name": "mesh-vault",
-        "entrypoints": [
+      "network": "host",
-          "index.js",
+      "volumes": [
-          "tools/index.js",
+        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
-          "provisioner/index.js"
+        "${dir:grants}:${dir:grants}:ro",
-        ],
+        "${dir:ledger}:${dir:ledger}",
-        "loads": [
+        "${dir:root}:${dir:root}:ro"
-          "index.js",
-          "tools/index.js",
-          "provisioner/index.js"
       ],
       "env": {
+        "MESH_BROKER_FILE": "/run/secrets/broker",
         "MESH_RECEIVES": "${dir:grants}/mesh.json",
         "MESH_VAULT_LEDGER": "${dir:ledger}",
         "MESH_VAULT_ROOT": "${dir:root}"
+      },
+      "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/minio/Dockerfile

@@ -0,0 +1,40 @@
+# minio'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
+ARG MC_CLI
+
+# Named so the final stage's COPY --from can reference a stage, not an ARG — the legacy builder
+# this host still runs doesn't expand ARGs inside COPY --from, only inside FROM.
+FROM ${MC_CLI} AS mccli
+
+FROM ${BUILD_BASE} AS build
+# Compiled under /app/modules so `@novox/mesh-sdk` resolves upward into the base's own
+# node_modules — the module is compiled against exactly the sdk it will run against. The compiler
+# is invoked by its real path: node_modules/.bin entries are launcher symlinks the base image
+# resolved away.
+WORKDIR /app/modules/minio
+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/minio/dist /app/modules/minio/dist
+# The provisioner shells out to mc to actually create buckets and service accounts on the running
+# minio server — mc itself was never in this runtime image, only in minio's own. Silently retried
+# "spawn mc ENOENT" forever: a requirement was granted at the control-plane level without ever
+# materializing the credential on minio. /usr/bin/mc there is a symlink to the real binary, mcli —
+# both copied so the symlink resolves.
+COPY --from=mccli /usr/bin/mcli /usr/bin/mcli
+COPY --from=mccli /usr/bin/mc /usr/bin/mc
+# 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/minio/dist/tools/index.js,/app/modules/minio/dist/provisioner/index.js

modules/minio/module.json

@@ -59,9 +59,16 @@
     "s3-bucket": "${dir:grants}"
   },
   "own-secrets": {
-    "root": "${dir:state}/root.secret"
+    "root": "${dir:state}/root.secret",
+    "broker": "${dir:mesh-state}/broker"
   },
   "resources": [
+    {
+      "id": "mesh-state",
+      "type": "directory",
+      "mode": "0700",
+      "place": "mesh"
+    },
     {
       "id": "state",
       "type": "directory",
@@ -120,34 +127,48 @@
       }
     },
     {
-      "id": "client",
+      "id": "runtime",
-      "type": "package",
+      "type": "container",
-      "package": "minio-client"
+      "name": "mesh-minio",
+      "network": "minio-net",
+      "volumes": [
+        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "${dir:grants}:${dir:grants}:ro",
+        "${dir:state}/root.secret:/run/secrets/root:ro"
+      ],
+      "env": {
+        "MESH_MINIO_ENDPOINT": "http://minio:9000",
+        "MESH_MINIO_ROOT_USER": "meshroot",
+        "MESH_MINIO_ROOT_PASSWORD_FILE": "/run/secrets/root",
+        "MESH_MINIO_REGION": "eu-west",
+        "MESH_BROKER_FILE": "/run/secrets/broker",
+        "MESH_RECEIVES": "${dir:grants}/mesh.json"
+      },
+      "artifact": "runtime"
     }
   ],
   "build": {
+    "on": [
+      {
+        "arg": "BUILD_BASE",
+        "module": "mesh-tools",
+        "artifact": "build"
+      },
+      {
+        "arg": "RUNTIME_BASE",
+        "module": "mesh-tools",
+        "artifact": "runtime"
+      },
+      {
+        "arg": "MC_CLI",
+        "image": "docker.io/pgsty/minio@sha256:b6bfe7239bfc83fb90d31612d9704d86039dd714f7904b3f1ad68f211e602372"
+      }
+    ],
     "artifacts": [
       {
-        "name": "code",
+        "name": "runtime",
-        "kind": "bundle",
+        "kind": "image",
-        "language": "typescript",
+        "from": "Dockerfile"
-        "entrypoints": [
-          "tools/index.js",
-          "provisioner/index.js"
-        ],
-        "loads": [
-          "tools/index.js",
-          "provisioner/index.js"
-        ],
-        "env": {
-          "MESH_MINIO_ENDPOINT": "http://127.0.0.1:${port:9000}",
-          "MESH_MINIO_ROOT_USER": "meshroot",
-          "MESH_MINIO_ROOT_PASSWORD_FILE": "${dir:state}/root.secret",
-          "MESH_MINIO_REGION": "eu-west",
-          "MESH_MINIO_MC_BIN": "mcli",
-          "MESH_MINIO_MC_CONFIG": "${dir:state}/mc",
-          "MESH_RECEIVES": "${dir:grants}/mesh.json"
-        }
       }
     ]
   }

modules/mosquitto/Dockerfile

@@ -0,0 +1,28 @@
+# mosquitto'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/mosquitto
+COPY . .
+RUN node /app/node_modules/typescript/bin/tsc topics.ts client.ts index.ts tools/index.ts provisioner/index.ts bootstrap/index.ts \
+      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
+
+FROM ${RUNTIME_BASE}
+# mosquitto's client and bootstrap drive `mosquitto_ctrl`; the apt package carries it with its
+# shared libraries — the musl binary from the eclipse image would not load on this glibc base.
+RUN apt-get update && apt-get install -y --no-install-recommends mosquitto \
+ && rm -rf /var/lib/apt/lists/*
+COPY --from=build /app/modules/mosquitto/dist /app/modules/mosquitto/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/mosquitto/dist/index.js,/app/modules/mosquitto/dist/tools/index.js,/app/modules/mosquitto/dist/provisioner/index.js

modules/mosquitto/module.json

@@ -32,7 +32,8 @@
     "mqtt-topic": "${dir:grants}"
   },
   "own-secrets": {
-    "admin": "${dir:mesh-state}/admin"
+    "admin": "${dir:mesh-state}/admin",
+    "broker": "${dir:mesh-state}/broker"
   },
   "listens": [
     {
@@ -87,29 +88,26 @@
       "type": "network",
       "name": "mosquitto"
     },
-    {
-      "id": "bootstrap-env",
-      "type": "file",
-      "path": "${dir:state}/bootstrap.env",
-      "mode": "0600",
-      "content": "MESH_PROVISION_MQTT=127.0.0.1:${port:1883}\nMESH_PROVISION_ADMIN_USER=mesh-admin\nMESH_PROVISION_PASSWORD_FILE=${dir:mesh-state}/admin\nMESH_DYNSEC_FILE=${dir:data}/dynamic-security.json\n"
-    },
     {
       "id": "bootstrap",
-      "type": "process",
+      "type": "container",
       "name": "mosquitto-bootstrap",
-      "artifact": "code",
-      "run": [
-        "node",
-        "bootstrap/index.js"
-      ],
       "run-once": true,
-      "env-file": [
+      "volumes": [
-        "${dir:state}/bootstrap.env"
+        "${dir:data}:/mosquitto/data",
+        "${dir:mesh-state}/admin:/run/secrets/admin:ro"
       ],
-      "restart-on": [
+      "env": {
-        "bootstrap-env"
+        "MESH_PROVISION_MQTT": "mosquitto:1883",
-      ]
+        "MESH_PROVISION_ADMIN_USER": "mesh-admin",
+        "MESH_PROVISION_PASSWORD_FILE": "/run/secrets/admin",
+        "MESH_DYNSEC_FILE": "/mosquitto/data/dynamic-security.json"
+      },
+      "args": [
+        "run",
+        "/app/modules/mosquitto/dist/bootstrap/index.js"
+      ],
+      "artifact": "runtime"
     },
     {
       "id": "server",
@@ -127,34 +125,43 @@
       ]
     },
     {
-      "id": "client",
+      "id": "runtime",
-      "type": "package",
+      "type": "container",
-      "package": "mosquitto"
+      "name": "mesh-mosquitto",
+      "network": "mosquitto",
+      "volumes": [
+        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "${dir:grants}:${dir:grants}:ro",
+        "${dir:mesh-state}/admin:/run/secrets/admin:ro"
+      ],
+      "env": {
+        "MESH_BROKER_FILE": "/run/secrets/broker",
+        "MESH_RECEIVES": "${dir:grants}/mesh.json",
+        "MESH_PROVISION_MQTT": "mosquitto:1883",
+        "MESH_PROVISION_ADMIN_USER": "mesh-admin",
+        "MESH_PROVISION_PASSWORD_FILE": "/run/secrets/admin"
+      },
+      "artifact": "runtime"
     }
   ],
   "build": {
+    "on": [
+      {
+        "arg": "BUILD_BASE",
+        "module": "mesh-tools",
+        "artifact": "build"
+      },
+      {
+        "arg": "RUNTIME_BASE",
+        "module": "mesh-tools",
+        "artifact": "runtime"
+      }
+    ],
     "artifacts": [
       {
-        "name": "code",
+        "name": "runtime",
-        "kind": "bundle",
+        "kind": "image",
-        "language": "typescript",
+        "from": "Dockerfile"
-        "entrypoints": [
-          "index.js",
-          "tools/index.js",
-          "provisioner/index.js",
-          "bootstrap/index.js"
-        ],
-        "loads": [
-          "index.js",
-          "tools/index.js",
-          "provisioner/index.js"
-        ],
-        "env": {
-          "MESH_RECEIVES": "${dir:grants}/mesh.json",
-          "MESH_PROVISION_MQTT": "127.0.0.1:${port:1883}",
-          "MESH_PROVISION_ADMIN_USER": "mesh-admin",
-          "MESH_PROVISION_PASSWORD_FILE": "${dir:mesh-state}/admin"
-        }
       }
     ]
   }

modules/netcheck/cmd/netcheck/checks.go

@@ -1,173 +0,0 @@
-package main
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"math"
-	"net"
-	"sort"
-	"strconv"
-	"strings"
-	"time"
-)
-
-// Bounds on what a caller may ask: a check is a probe, never a wait anyone can make long.
-const (
-	DefaultTimeout = 3 * time.Second
-	MostTimeout    = 30 * time.Second
-)
-
-// TCPResult is what netcheck_tcp answers.
-type TCPResult struct {
-	Host      string `json:"host"`
-	Port      int    `json:"port"`
-	Address   string `json:"address,omitempty"`
-	Reachable bool   `json:"reachable"`
-	ElapsedMS int64  `json:"elapsed_ms"`
-	Error     string `json:"error,omitempty"`
-}
-
-// CheckTCP opens one TCP connection and closes it, sending nothing. A port that refuses or a host
-// that does not answer is a result, not a failure of the tool; only a malformed question is.
-func CheckTCP(host string, port int, timeout time.Duration) (TCPResult, error) {
-	if port < 1 || port > 65535 {
-		return TCPResult{}, fmt.Errorf("port %d is not a TCP port (1-65535)", port)
-	}
-	out := TCPResult{Host: host, Port: port}
-	start := time.Now()
-	conn, err := net.DialTimeout("tcp", net.JoinHostPort(host, strconv.Itoa(port)), timeout)
-	out.ElapsedMS = time.Since(start).Milliseconds()
-	if err != nil {
-		out.Error = err.Error()
-		return out, nil
-	}
-	out.Address = conn.RemoteAddr().String()
-	out.Reachable = true
-	_ = conn.Close()
-	return out, nil
-}
-
-// DNSResult is what netcheck_dns answers.
-type DNSResult struct {
-	Name      string   `json:"name"`
-	Type      string   `json:"type"`
-	Answers   []string `json:"answers"`
-	ElapsedMS int64    `json:"elapsed_ms"`
-	Error     string   `json:"error,omitempty"`
-}
-
-// DNSTypes are the record types netcheck_dns looks up.
-var DNSTypes = []string{"A", "AAAA", "CNAME", "TXT", "MX"}
-
-// CheckDNS looks a name up with the machine's resolver. Built without cgo, Go's own resolver reads
-// the machine's /etc/resolv.conf and /etc/hosts, which is the resolver this machine's programs use.
-// A name that does not resolve is a result with its error; an unknown type is refused.
-func CheckDNS(name, kind string, timeout time.Duration) (DNSResult, error) {
-	kind = strings.ToUpper(strings.TrimSpace(kind))
-	if kind == "" {
-		kind = "A"
-	}
-	known := false
-	for _, t := range DNSTypes {
-		known = known || t == kind
-	}
-	if !known {
-		return DNSResult{}, fmt.Errorf("type %q is not one netcheck_dns looks up (%s)", kind, strings.Join(DNSTypes, ", "))
-	}
-	out := DNSResult{Name: name, Type: kind, Answers: []string{}}
-	ctx, cancel := context.WithTimeout(context.Background(), timeout)
-	defer cancel()
-	r := net.DefaultResolver
-	start := time.Now()
-	var err error
-	switch kind {
-	case "A", "AAAA":
-		network := "ip4"
-		if kind == "AAAA" {
-			network = "ip6"
-		}
-		var ips []net.IP
-		if ips, err = r.LookupIP(ctx, network, name); err == nil {
-			for _, ip := range ips {
-				out.Answers = append(out.Answers, ip.String())
-			}
-		}
-	case "CNAME":
-		var cname string
-		if cname, err = r.LookupCNAME(ctx, name); err == nil {
-			out.Answers = append(out.Answers, cname)
-		}
-	case "TXT":
-		var txts []string
-		if txts, err = r.LookupTXT(ctx, name); err == nil {
-			out.Answers = append(out.Answers, txts...)
-		}
-	case "MX":
-		var mxs []*net.MX
-		if mxs, err = r.LookupMX(ctx, name); err == nil {
-			for _, mx := range mxs {
-				out.Answers = append(out.Answers, fmt.Sprintf("%d %s", mx.Pref, mx.Host))
-			}
-		}
-	}
-	out.ElapsedMS = time.Since(start).Milliseconds()
-	if err != nil {
-		out.Error = err.Error()
-	}
-	if kind != "MX" {
-		sort.Strings(out.Answers)
-	}
-	return out, nil
-}
-
-// text is a required string argument.
-func text(args map[string]any, key string) (string, error) {
-	s, _ := args[key].(string)
-	s = strings.TrimSpace(s)
-	if s == "" {
-		return "", fmt.Errorf("%s is required", key)
-	}
-	return s, nil
-}
-
-// whole is an integer argument, given as a JSON number or a numeric string; fallback when absent.
-func whole(args map[string]any, key string, fallback int) (int, error) {
-	v, given := args[key]
-	if !given || v == nil {
-		if fallback == 0 {
-			return 0, fmt.Errorf("%s is required", key)
-		}
-		return fallback, nil
-	}
-	switch n := v.(type) {
-	case float64:
-		if n != math.Trunc(n) {
-			return 0, fmt.Errorf("%s must be a whole number, not %v", key, n)
-		}
-		return int(n), nil
-	case string:
-		i, err := strconv.Atoi(strings.TrimSpace(n))
-		if err != nil {
-			return 0, fmt.Errorf("%s must be a whole number, not %q", key, n)
-		}
-		return i, nil
-	}
-	return 0, errors.New(key + " must be a whole number")
-}
-
-// timeoutOf is timeout_ms, defaulted and bounded.
-func timeoutOf(args map[string]any) (time.Duration, error) {
-	ms, err := whole(args, "timeout_ms", int(DefaultTimeout/time.Millisecond))
-	if err != nil {
-		return 0, err
-	}
-	if ms < 1 {
-		return 0, fmt.Errorf("timeout_ms must be at least 1, not %d", ms)
-	}
-	d := time.Duration(ms) * time.Millisecond
-	if d > MostTimeout {
-		d = MostTimeout
-	}
-	return d, nil
-}

modules/netcheck/cmd/netcheck/checks_test.go

@@ -1,68 +0,0 @@
-package main
-
-import (
-	"net"
-	"testing"
-	"time"
-)
-
-func TestATCPPortThatListensIsReachableAndOneThatDoesNotIsNot(t *testing.T) {
-	l, err := net.Listen("tcp", "127.0.0.1:0")
-	if err != nil {
-		t.Fatal(err)
-	}
-	port := l.Addr().(*net.TCPAddr).Port
-	got, err := CheckTCP("127.0.0.1", port, time.Second)
-	if err != nil || !got.Reachable || got.Error != "" {
-		t.Fatalf("a listening port: %+v, %v", got, err)
-	}
-	l.Close()
-	got, err = CheckTCP("127.0.0.1", port, time.Second)
-	if err != nil || got.Reachable || got.Error == "" {
-		t.Fatalf("a closed port is reported as a result with its error, not a failure: %+v, %v", got, err)
-	}
-}
-
-func TestAPortOutsideTheRangeIsRefused(t *testing.T) {
-	for _, p := range []int{0, -1, 65536} {
-		if _, err := CheckTCP("127.0.0.1", p, time.Second); err == nil {
-			t.Errorf("port %d was accepted", p)
-		}
-	}
-}
-
-func TestDNSAnswersFromTheMachinesResolverAndRefusesAnUnknownType(t *testing.T) {
-	got, err := CheckDNS("localhost", "a", time.Second)
-	if err != nil || got.Type != "A" || len(got.Answers) == 0 {
-		t.Fatalf("localhost A: %+v, %v", got, err)
-	}
-	if _, err := CheckDNS("localhost", "SRV", time.Second); err == nil {
-		t.Fatal("an unknown record type was accepted")
-	}
-	got, err = CheckDNS("no-such-name.invalid", "A", time.Second)
-	if err != nil || got.Error == "" || len(got.Answers) != 0 {
-		t.Fatalf("a name that does not resolve is a result with its error: %+v, %v", got, err)
-	}
-}
-
-func TestTimeoutIsDefaultedAndBounded(t *testing.T) {
-	if d, _ := timeoutOf(map[string]any{}); d != DefaultTimeout {
-		t.Errorf("default: %v", d)
-	}
-	if d, _ := timeoutOf(map[string]any{"timeout_ms": float64(10 * 60 * 1000)}); d != MostTimeout {
-		t.Errorf("bounded: %v", d)
-	}
-	if _, err := timeoutOf(map[string]any{"timeout_ms": float64(0)}); err == nil {
-		t.Error("a zero timeout was accepted")
-	}
-}
-
-func TestBothToolsAreListedUnprefixed(t *testing.T) {
-	names := map[string]bool{}
-	for _, tool := range tools() {
-		names[tool.Name] = true
-	}
-	if !names["netcheck_tcp"] || !names["netcheck_dns"] || len(names) != 2 {
-		t.Fatalf("tools: %v", names)
-	}
-}

modules/netcheck/cmd/netcheck/main.go

@@ -1,72 +0,0 @@
-// netcheck's Go tools bundle (novox/hq ADR 0188, ADR 0193): a process the node's runtime launches
-// and speaks MCP over stdio to, through the Go SDK. It serves the two checks that are the machine's
-// own sockets and resolver — a TCP connect and a DNS lookup — and nothing that changes anything.
-// The module's HTTP check is its TypeScript bundle; the runtime serves both under one module.
-package main
-
-import (
-	"fmt"
-	"os"
-
-	stdio "git.novox.be/novox/mesh-sdk/go"
-)
-
-func main() {
-	// An empty name serves as the module the runtime names (MESH_SERVED_MODULE): netcheck.
-	if err := stdio.Serve("", tools()); err != nil {
-		fmt.Fprintln(os.Stderr, err)
-		os.Exit(1)
-	}
-}
-
-func tools() []stdio.Tool {
-	return []stdio.Tool{
-		{
-			Name: "netcheck_tcp",
-			Description: "Check whether a TCP port is reachable from this machine: opens one connection " +
-				"and closes it at once, sending nothing. Answers reachable, elapsed_ms and the error when not.",
-			Input: map[string]any{
-				"host":       map[string]any{"type": "string", "description": "host name or IP address"},
-				"port":       map[string]any{"type": "integer", "description": "TCP port, 1-65535"},
-				"timeout_ms": map[string]any{"type": "integer", "description": "give up after this long (default 3000, at most 30000)"},
-			},
-			Run: func(args map[string]any) (any, error) {
-				host, err := text(args, "host")
-				if err != nil {
-					return nil, err
-				}
-				port, err := whole(args, "port", 0)
-				if err != nil {
-					return nil, err
-				}
-				timeout, err := timeoutOf(args)
-				if err != nil {
-					return nil, err
-				}
-				return CheckTCP(host, port, timeout)
-			},
-		},
-		{
-			Name: "netcheck_dns",
-			Description: "Look a name up with this machine's resolver (its /etc/resolv.conf and /etc/hosts). " +
-				"type is A, AAAA, CNAME, TXT or MX; answers the records found, or the error.",
-			Input: map[string]any{
-				"name":       map[string]any{"type": "string", "description": "the name to look up"},
-				"type":       map[string]any{"type": "string", "enum": []string{"A", "AAAA", "CNAME", "TXT", "MX"}, "description": "record type (default A)"},
-				"timeout_ms": map[string]any{"type": "integer", "description": "give up after this long (default 3000, at most 30000)"},
-			},
-			Run: func(args map[string]any) (any, error) {
-				name, err := text(args, "name")
-				if err != nil {
-					return nil, err
-				}
-				kind, _ := args["type"].(string)
-				timeout, err := timeoutOf(args)
-				if err != nil {
-					return nil, err
-				}
-				return CheckDNS(name, kind, timeout)
-			},
-		},
-	}
-}

modules/netcheck/go.mod

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

modules/netcheck/go.sum

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

modules/netcheck/http.ts

@@ -1,84 +0,0 @@
-// netcheck's HTTP check — the module's own code, in TypeScript (novox/hq ADR 0039, ADR 0188). One
-// request, HEAD or GET, never a body sent and never a body read: the status, how long it took and
-// a few headers that say what answered. Redirects are reported, not followed, so a check reaches
-// exactly the address it was given.
-
-export const METHODS = ["HEAD", "GET"] as const;
-export type Method = (typeof METHODS)[number];
-
-/** The headers worth reporting: what answered and what it says it is, nothing it set for a client. */
-export const REPORTED_HEADERS = [
-  "content-type", "content-length", "server", "location", "date",
-  "cache-control", "last-modified", "etag",
-] as const;
-
-export const DEFAULT_TIMEOUT_MS = 5000;
-export const MOST_TIMEOUT_MS = 30000;
-
-export interface HttpResult {
-  url: string;
-  method: Method;
-  status?: number;
-  statusText?: string;
-  elapsed_ms: number;
-  headers: Record<string, string>;
-  error?: string;
-}
-
-/** Only http and https are checked; anything else — file:, data:, ftp: — is refused by name. */
-export function checkedUrl(raw: unknown): URL {
-  const text = typeof raw === "string" ? raw.trim() : "";
-  if (!text) throw new Error("url is required");
-  let url: URL;
-  try {
-    url = new URL(text);
-  } catch {
-    throw new Error(`${JSON.stringify(text)} is not a URL`);
-  }
-  if (url.protocol !== "http:" && url.protocol !== "https:") {
-    throw new Error(`netcheck_http checks http and https URLs only, not ${url.protocol}`);
-  }
-  return url;
-}
-
-export function checkedMethod(raw: unknown): Method {
-  const m = (typeof raw === "string" && raw.trim() ? raw.trim() : "HEAD").toUpperCase();
-  if (!(METHODS as readonly string[]).includes(m)) {
-    throw new Error(`method ${m} is not one netcheck_http uses (${METHODS.join(", ")}): a check never changes anything`);
-  }
-  return m as Method;
-}
-
-export function checkedTimeout(raw: unknown): number {
-  if (raw === undefined || raw === null || raw === "") return DEFAULT_TIMEOUT_MS;
-  const n = Number(raw);
-  if (!Number.isInteger(n) || n < 1) throw new Error(`timeout_ms must be a whole number of at least 1, not ${String(raw)}`);
-  return Math.min(n, MOST_TIMEOUT_MS);
-}
-
-/** Make one request and report how it went. A refused connection or a timeout is a result with its
- *  error; only a malformed question throws. */
-export async function checkHttp(args: Readonly<Record<string, unknown>>, fetcher: typeof fetch = fetch): Promise<HttpResult> {
-  const url = checkedUrl(args.url);
-  const method = checkedMethod(args.method);
-  const timeout = checkedTimeout(args.timeout_ms);
-  const started = performance.now();
-  const out: HttpResult = { url: url.toString(), method, elapsed_ms: 0, headers: {} };
-  try {
-    const res = await fetcher(url, { method, redirect: "manual", signal: AbortSignal.timeout(timeout) });
-    out.elapsed_ms = Math.round(performance.now() - started);
-    out.status = res.status;
-    out.statusText = res.statusText;
-    for (const h of REPORTED_HEADERS) {
-      const v = res.headers.get(h);
-      if (v !== null) out.headers[h] = v;
-    }
-    // The body is not read: a check asks whether something answers, not what it says.
-    await res.body?.cancel().catch(() => {});
-  } catch (err) {
-    out.elapsed_ms = Math.round(performance.now() - started);
-    const e = err as Error & { cause?: { message?: string; code?: string } };
-    out.error = e.name === "TimeoutError" ? `no answer within ${timeout} ms` : (e.cause?.code ?? e.cause?.message ?? e.message);
-  }
-  return out;
-}

modules/netcheck/module.json

@@ -1,35 +0,0 @@
-{
-  "module": "netcheck",
-  "version": "1",
-  "tools": [
-    "netcheck_tcp",
-    "netcheck_dns",
-    "netcheck_http"
-  ],
-  "build": {
-    "artifacts": [
-      {
-        "name": "tools-go",
-        "kind": "bundle",
-        "language": "go",
-        "system": "arch",
-        "from": "cmd/netcheck",
-        "binary": "netcheck",
-        "loads": [
-          "netcheck"
-        ]
-      },
-      {
-        "name": "tools-typescript",
-        "kind": "bundle",
-        "language": "typescript",
-        "entrypoints": [
-          "tools/index.js"
-        ],
-        "loads": [
-          "tools/index.js"
-        ]
-      }
-    ]
-  }
-}

modules/netcheck/package.json

@@ -1,17 +0,0 @@
-{
-  "name": "@novox/module-netcheck",
-  "version": "0.1.0",
-  "description": "netcheck — read-only network checks from a machine, as one module carrying a Go tools bundle (TCP, DNS) and a TypeScript one (HTTP) (novox/hq ADR 0188, ADR 0193).",
-  "type": "module",
-  "private": true,
-  "scripts": {
-    "test": "node --test --experimental-strip-types 'test/*.test.ts'"
-  },
-  "dependencies": {
-    "@novox/mesh-sdk": "^0.1.6"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.6.0"
-  }
-}

modules/netcheck/test/http.test.ts

@@ -1,52 +0,0 @@
-// The HTTP check refuses what is not http(s) and what would change something, and reports a status,
-// a refusal and a timeout as results (novox/hq ADR 0188: a tools bundle is read-only and harmless).
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { createServer } from "node:http";
-import type { AddressInfo } from "node:net";
-import { checkHttp, checkedMethod, checkedUrl } from "../http.ts";
-
-test("only http and https URLs are checked", () => {
-  for (const bad of ["file:///etc/passwd", "ftp://example.org/", "data:text/plain,hi", "javascript:1", "", "not a url"]) {
-    assert.throws(() => checkedUrl(bad), `${bad} was accepted`);
-  }
-  assert.equal(checkedUrl("https://example.org/x").protocol, "https:");
-});
-
-test("only HEAD and GET are used", () => {
-  assert.equal(checkedMethod(undefined), "HEAD");
-  assert.equal(checkedMethod("get"), "GET");
-  for (const bad of ["POST", "PUT", "DELETE", "PATCH"]) assert.throws(() => checkedMethod(bad));
-});
-
-test("a status, its headers and a redirect not followed", async () => {
-  const server = createServer((req, res) => {
-    if (req.url === "/moved") { res.writeHead(302, { location: "/elsewhere" }); res.end(); return; }
-    res.writeHead(200, { "content-type": "text/plain", "x-secret": "not reported" });
-    res.end(req.method === "GET" ? "body" : undefined);
-  });
-  await new Promise<void>((ok) => server.listen(0, "127.0.0.1", ok));
-  const base = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
-  try {
-    const head = await checkHttp({ url: base + "/" });
-    assert.equal(head.status, 200);
-    assert.equal(head.method, "HEAD");
-    assert.equal(head.headers["content-type"], "text/plain");
-    assert.equal(head.headers["x-secret"], undefined);
-    const moved = await checkHttp({ url: base + "/moved", method: "GET" });
-    assert.equal(moved.status, 302);
-    assert.equal(moved.headers.location, "/elsewhere");
-  } finally {
-    server.close();
-  }
-});
-
-test("a refused connection is a result with its error", async () => {
-  const server = createServer();
-  await new Promise<void>((ok) => server.listen(0, "127.0.0.1", ok));
-  const port = (server.address() as AddressInfo).port;
-  await new Promise<void>((ok) => server.close(() => ok()));
-  const got = await checkHttp({ url: `http://127.0.0.1:${port}/`, timeout_ms: 2000 });
-  assert.equal(got.status, undefined);
-  assert.ok(got.error, "no error reported");
-});

modules/netcheck/tools/index.ts

@@ -1,28 +0,0 @@
-// netcheck's TypeScript tools bundle (novox/hq ADR 0188, ADR 0193): what the builder's launcher
-// imports and serves over MCP on stdio. Its Go bundle serves the TCP and DNS checks; this one the
-// HTTP check — one module, two languages, one runtime that knows neither.
-
-import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
-import { checkHttp, DEFAULT_TIMEOUT_MS, METHODS, MOST_TIMEOUT_MS } from "../http.js";
-
-export function getNetcheckHttpTools(): ToolDefinition[] {
-  return [
-    {
-      name: "netcheck_http",
-      description:
-        "Check whether an http(s) URL answers from this machine: one HEAD or GET, no body sent or read, " +
-        "redirects reported and not followed. Answers status, elapsed_ms and a few headers.",
-      input: {
-        url: { type: "string", description: "an http:// or https:// URL" },
-        method: { type: "string", enum: [...METHODS], description: "HEAD (default) or GET" },
-        timeout_ms: {
-          type: "integer",
-          description: `give up after this long (default ${DEFAULT_TIMEOUT_MS}, at most ${MOST_TIMEOUT_MS})`,
-        },
-      },
-      run: async (args) => checkHttp(args),
-    },
-  ];
-}
-
-registerModuleTools("netcheck", () => getNetcheckHttpTools());

modules/nextcloud/Dockerfile

@@ -0,0 +1,40 @@
+# nextcloud'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
+ARG DOCKER_CLI
+
+# Named so the final stage's COPY --from can reference a stage, not an ARG — the legacy builder
+# this host still runs doesn't expand ARGs inside COPY --from, only inside FROM.
+FROM ${DOCKER_CLI} AS dockercli
+
+FROM ${BUILD_BASE} AS build
+# Compiled under /app/modules so `@novox/mesh-sdk` resolves upward into the base's own
+# node_modules — the module is compiled against exactly the sdk it will run against. The compiler
+# is invoked by its real path: node_modules/.bin entries are launcher symlinks the base image
+# resolved away.
+WORKDIR /app/modules/nextcloud
+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/nextcloud/dist /app/modules/nextcloud/dist
+# occ runs inside nextcloud's own container, reached over the mounted docker socket — which needs
+# the docker CLI itself present here, not only the socket. Copied from Docker's own official client
+# image rather than apt-installed, so this stays the one binary and nothing else (no daemon, no
+# systemd unit, no package manager tree pulled in for it).
+COPY --from=dockercli /usr/local/bin/docker /usr/local/bin/docker
+# 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. A container that instead ran only its
+# provisioner (`run`) served no tools and emitted no events; a container that named no command
+# ran no provisioner at all.
+ENV MESH_TOOL_MODULES=/app/modules/nextcloud/dist/index.js,/app/modules/nextcloud/dist/tools/index.js

modules/nextcloud/module.json

@@ -30,7 +30,8 @@
     "share.created"
   ],
   "own-secrets": {
-    "admin": "${dir:state}/admin.secret"
+    "admin": "${dir:state}/admin.secret",
+    "broker": "${dir:mesh-state}/broker"
   },
   "capabilities": [
     "container-runtime"
@@ -93,28 +94,53 @@
       "mode": "0600",
       "content": "{}\n",
       "merge": "json"
+    },
+    {
+      "id": "runtime",
+      "type": "container",
+      "name": "mesh-nextcloud",
+      "network": "host",
+      "volumes": [
+        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "${dir:mesh-state}/config.json:/run/config/config.json:ro",
+        "${dir:state}/admin.secret:/run/secrets/admin:ro",
+        "/var/run/docker.sock:/var/run/docker.sock"
+      ],
+      "env": {
+        "MESH_BROKER_FILE": "/run/secrets/broker",
+        "MESH_NEXTCLOUD_URL": "http://127.0.0.1:${port:80}",
+        "MESH_NEXTCLOUD_CONFIG_FILE": "/run/config/config.json",
+        "MESH_NEXTCLOUD_ADMIN_USER": "mesh-admin",
+        "MESH_NEXTCLOUD_ADMIN_PASSWORD_FILE": "/run/secrets/admin"
+      },
+      "restart-on": [
+        "runtime-config"
+      ],
+      "artifact": "runtime"
     }
   ],
   "build": {
+    "on": [
+      {
+        "arg": "BUILD_BASE",
+        "module": "mesh-tools",
+        "artifact": "build"
+      },
+      {
+        "arg": "RUNTIME_BASE",
+        "module": "mesh-tools",
+        "artifact": "runtime"
+      },
+      {
+        "arg": "DOCKER_CLI",
+        "image": "docker@sha256:018edbc908e08fcc9dbf029c812c34251e9b4719e6f71ca0e5eae2a987d014ca"
+      }
+    ],
     "artifacts": [
       {
-        "name": "code",
+        "name": "runtime",
-        "kind": "bundle",
+        "kind": "image",
-        "language": "typescript",
+        "from": "Dockerfile"
-        "entrypoints": [
-          "index.js",
-          "tools/index.js"
-        ],
-        "loads": [
-          "index.js",
-          "tools/index.js"
-        ],
-        "env": {
-          "MESH_NEXTCLOUD_URL": "http://127.0.0.1:${port:80}",
-          "MESH_NEXTCLOUD_CONFIG_FILE": "${dir:mesh-state}/config.json",
-          "MESH_NEXTCLOUD_ADMIN_USER": "mesh-admin",
-          "MESH_NEXTCLOUD_ADMIN_PASSWORD_FILE": "${dir:state}/admin.secret"
-        }
       }
     ]
   }

modules/nodered/Dockerfile

@@ -0,0 +1,27 @@
+# nodered'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/nodered
+COPY . .
+RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts mqtt/probe.ts mqtt/connection.ts mqtt/index.ts \
+      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
+
+FROM ${RUNTIME_BASE}
+COPY --from=build /app/modules/nodered/dist /app/modules/nodered/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/nodered/dist/tools/index.js
+# NOT dist/mqtt/index.js: that is a step the host runs to completion, named by the `mqtt`
+# container's args as `mesh-tools run …` (novox/hq ADR 0052). Listed here it would run inside the
+# serving sidecar too, and exit it.

modules/nodered/module.json

@@ -12,7 +12,8 @@
     "api-token": {
       "path": "${dir:mesh-state}/api-token",
       "taken": "at-start"
-    }
+    },
+    "broker": "${dir:mesh-state}/broker"
   },
   "capabilities": [
     "container-runtime"
@@ -100,31 +101,53 @@
       "content": "{\n  \"token\": \"${secret:api-token}\"\n}\n"
     },
     {
-      "id": "mqtt-env",
+      "id": "runtime",
-      "type": "file",
+      "type": "container",
-      "path": "${dir:state}/mqtt.env",
+      "name": "mesh-nodered",
-      "mode": "0600",
+      "network": "host",
-      "content": "MESH_NODERED_URL=http://127.0.0.1:${port:1880}\nMESH_NODERED_CONFIG_FILE=${dir:mesh-state}/config.json\nMESH_PROVISIONS_DIR=${dir:state}\nMESH_WRITTEN_DIR=${dir:written}\n"
+      "volumes": [
+        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "${dir:mesh-state}/config.json:/run/config/config.json:ro"
+      ],
+      "env": {
+        "MESH_BROKER_FILE": "/run/secrets/broker",
+        "MESH_NODERED_URL": "http://127.0.0.1:${port:1880}",
+        "MESH_NODERED_CONFIG_FILE": "/run/config/config.json"
+      },
+      "restart-on": [
+        "runtime-config"
+      ],
+      "artifact": "runtime"
     },
     {
       "id": "mqtt",
-      "type": "process",
+      "type": "container",
-      "name": "nodered-mqtt",
+      "name": "mesh-nodered-mqtt",
-      "artifact": "code",
+      "network": "host",
-      "run": [
-        "node",
-        "mqtt/index.js"
-      ],
       "run-once": true,
-      "env-file": [
+      "volumes": [
-        "${dir:state}/mqtt.env"
+        "${dir:mesh-state}/config.json:/run/config/config.json:ro",
+        "${dir:written}:/var/lib/nodered-provisions",
+        "${dir:state}/mqtt-topic.json:/run/provisions/mqtt-topic.json:ro",
+        "${dir:state}/mqtt-topic.secret:/run/provisions/mqtt-topic.secret:ro",
+        "${dir:state}/settings.json:/run/provisions/settings.json:ro"
+      ],
+      "env": {
+        "MESH_NODERED_URL": "http://127.0.0.1:${port:1880}",
+        "MESH_NODERED_CONFIG_FILE": "/run/config/config.json",
+        "MESH_PROVISIONS_DIR": "/run/provisions",
+        "MESH_WRITTEN_DIR": "/var/lib/nodered-provisions"
+      },
+      "args": [
+        "run",
+        "/app/modules/nodered/dist/mqtt/index.js"
       ],
       "restart-on": [
-        "mqtt-env",
         "bound-mqtt-topic",
         "secret-mqtt-topic",
         "settings"
-      ]
+      ],
+      "artifact": "runtime"
     }
   ],
   "requires": [
@@ -150,22 +173,23 @@
     "mqtt-topic": "${dir:state}/mqtt-topic.secret"
   },
   "build": {
+    "on": [
+      {
+        "arg": "BUILD_BASE",
+        "module": "mesh-tools",
+        "artifact": "build"
+      },
+      {
+        "arg": "RUNTIME_BASE",
+        "module": "mesh-tools",
+        "artifact": "runtime"
+      }
+    ],
     "artifacts": [
       {
-        "name": "code",
+        "name": "runtime",
-        "kind": "bundle",
+        "kind": "image",
-        "language": "typescript",
+        "from": "Dockerfile"
-        "entrypoints": [
-          "tools/index.js",
-          "mqtt/index.js"
-        ],
-        "loads": [
-          "tools/index.js"
-        ],
-        "env": {
-          "MESH_NODERED_URL": "http://127.0.0.1:${port:1880}",
-          "MESH_NODERED_CONFIG_FILE": "${dir:mesh-state}/config.json"
-        }
       }
     ]
   }

modules/openai-consumer/Dockerfile

@@ -0,0 +1,22 @@
+# openai-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/openai-consumer
+COPY . .
+RUN node /app/node_modules/typescript/bin/tsc apply/index.ts \
+      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
+
+FROM ${RUNTIME_BASE}
+COPY --from=build /app/modules/openai-consumer/dist /app/modules/openai-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/openai-consumer/module.json

@@ -28,31 +28,44 @@
     },
     {
       "id": "apply",
-      "type": "process",
+      "type": "container",
-      "name": "openai-consumer-apply",
+      "name": "mesh-openai-consumer-apply",
-      "artifact": "code",
+      "network": "host",
-      "run": [
-        "node",
-        "apply/index.js"
-      ],
       "schedule": "*/5 * * * *",
+      "args": [
+        "run",
+        "/app/modules/openai-consumer/dist/apply/index.js"
+      ],
+      "volumes": [
+        "${dir:state}:/run/state"
+      ],
       "env": {
-        "MESH_MODEL_ACCESS_SECRET_FILE": "${dir:state}/api-key",
+        "MESH_MODEL_ACCESS_SECRET_FILE": "/run/state/api-key",
-        "MESH_MODEL_ACCESS_BIND_FILE": "${dir:state}/model.json",
+        "MESH_MODEL_ACCESS_BIND_FILE": "/run/state/model.json",
-        "MESH_OPENAI_ENV_FILE": "${dir:state}/config/openai.env",
+        "MESH_OPENAI_ENV_FILE": "/run/state/config/openai.env",
-        "MESH_OPENAI_CREDENTIALS_FILE": "${dir:state}/config/auth.json"
+        "MESH_OPENAI_CREDENTIALS_FILE": "/run/state/config/auth.json"
-      }
+      },
+      "artifact": "runtime"
     }
   ],
   "build": {
+    "on": [
+      {
+        "arg": "BUILD_BASE",
+        "module": "mesh-tools",
+        "artifact": "build"
+      },
+      {
+        "arg": "RUNTIME_BASE",
+        "module": "mesh-tools",
+        "artifact": "runtime"
+      }
+    ],
     "artifacts": [
       {
-        "name": "code",
+        "name": "runtime",
-        "kind": "bundle",
+        "kind": "image",
-        "language": "typescript",
+        "from": "Dockerfile"
-        "entrypoints": [
-          "apply/index.js"
-        ]
       }
     ]
   }

modules/postgres/Dockerfile

@@ -0,0 +1,41 @@
+# postgres's runtime: the tool runtime, carrying this module's compiled provisioner, tools and
+# event consumer.
+#
+# **Built from this module's own directory and nothing else.** The sdk is in the base image, so
+# nothing is copied out of a neighbouring checkout — which is what lets the mesh build this from a
+# repository and a path (novox/hq ADR 0069) rather than only on a workstation that happens to have
+# the siblings.
+#
+# Two bases, named rather than pinned: the image this is COMPILED in, and the image it RUNS in.
+# They are different images on purpose — the first carries a compiler and the second must not, or
+# every running container would carry one it never invokes. The mesh answers both with the copies it
+# holds, because a fingerprint written here would name one particular copy and no other mesh has it
+# (novox/hq issue 044). Declared in module.json's `build.on`; deliberately no defaults, so a build
+# nobody told stops here and says which module to build first.
+ARG BUILD_BASE
+ARG RUNTIME_BASE
+
+FROM ${BUILD_BASE} AS build
+# Compiled under /app/modules so `@novox/mesh-sdk` resolves upward into the base's own
+# node_modules — the module is compiled against exactly the sdk it will run against.
+WORKDIR /app/modules/postgres
+COPY . .
+# The compiler is invoked by its real path rather than through node_modules/.bin, whose entries are
+# symlinks to a launcher that requires its library relatively — resolved away when the base image
+# was assembled.
+RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts provisioner/index.ts tools/index.ts \
+      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
+
+FROM ${RUNTIME_BASE}
+# **This module talks to its database through psql, so psql has to be here.** The client is how
+# postgres's provisioner runs DDL — it does not carry a driver — and the runtime base holds only
+# what every module needs.
+RUN apt-get update \
+      && apt-get install -y --no-install-recommends postgresql-client \
+      && rm -rf /var/lib/apt/lists/*
+COPY --from=build /app/modules/postgres/dist /app/modules/postgres/dist
+# What a tool host should load from this module: its event consumer and its tools, which are
+# separate entrypoints because they are loaded by different things. The provisioner is the third,
+# and is not listed here — the declaration names it in the container's `args`, because it is what
+# this module's own container runs. One image, because they are one module and share a client.
+ENV MESH_TOOL_MODULES=/app/modules/postgres/dist/index.js,/app/modules/postgres/dist/tools/index.js,/app/modules/postgres/dist/provisioner/index.js

modules/postgres/module.json

@@ -53,9 +53,16 @@
   },
   "own-secrets": {
     "superuser": "${dir:state}/superuser.secret",
+    "broker": "${dir:mesh-state}/broker",
     "reader": "${dir:state}/reader.secret"
   },
   "resources": [
+    {
+      "id": "mesh-state",
+      "type": "directory",
+      "mode": "0700",
+      "place": "mesh"
+    },
     {
       "id": "state",
       "type": "directory",
@@ -92,33 +99,45 @@
       ]
     },
     {
-      "id": "client",
+      "id": "runtime",
-      "type": "package",
+      "type": "container",
-      "package": "postgresql-libs"
+      "name": "mesh-postgres",
-    }
+      "network": "host",
-  ],
+      "volumes": [
-  "build": {
+        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
-    "artifacts": [
+        "${dir:grants}:${dir:grants}:ro",
-      {
+        "${dir:state}/superuser.secret:/run/secrets/superuser:ro",
-        "name": "code",
+        "${dir:state}/reader.secret:/run/secrets/reader:ro"
-        "kind": "bundle",
-        "language": "typescript",
-        "entrypoints": [
-          "index.js",
-          "tools/index.js",
-          "provisioner/index.js"
-        ],
-        "loads": [
-          "index.js",
-          "tools/index.js",
-          "provisioner/index.js"
       ],
       "env": {
         "MESH_PROVISION_POSTGRES": "postgres://postgres@127.0.0.1:${port:5432}/postgres?sslmode=disable",
-          "MESH_PROVISION_PASSWORD_FILE": "${dir:state}/superuser.secret",
+        "MESH_PROVISION_POSTGRES_PORT": "${seat:mesh-store:5432}",
+        "MESH_PROVISION_PASSWORD_FILE": "/run/secrets/superuser",
+        "MESH_BROKER_FILE": "/run/secrets/broker",
         "MESH_RECEIVES": "${dir:grants}/mesh.json",
-          "MESH_POSTGRES_READER_PASSWORD_FILE": "${dir:state}/reader.secret"
+        "MESH_POSTGRES_READER_PASSWORD_FILE": "/run/secrets/reader"
+      },
+      "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/records/Dockerfile

@@ -0,0 +1,26 @@
+# records' runtime: the tool runtime, carrying this module's compiled reader and its tools.
+#
+# **Built from this module's own directory and nothing else.** The sdk is in the base image, so
+# nothing is copied out of a neighbouring checkout (novox/hq ADR 0069).
+#
+# Two bases, named rather than pinned: the image this is COMPILED in, and the image it RUNS in
+# (novox/hq issue 044). Declared in module.json's `build.on`; deliberately no defaults.
+ARG BUILD_BASE
+ARG RUNTIME_BASE
+
+FROM ${BUILD_BASE} AS build
+WORKDIR /app/modules/records
+COPY . .
+RUN node /app/node_modules/typescript/bin/tsc records.ts index.ts tools/index.ts \
+      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
+
+FROM ${RUNTIME_BASE}
+# **A module may need something the base image does not carry.** The reader keeps a checkout of the
+# repository it reads (novox/hq ADR 0153) — a git working copy, kept current, not a derived copy — and
+# the base image has no git. Certificates too, because the origin may be reached over TLS.
+RUN apt-get update \
+      && apt-get install -y --no-install-recommends git ca-certificates \
+      && rm -rf /var/lib/apt/lists/*
+COPY --from=build /app/modules/records/dist /app/modules/records/dist
+# Both entrypoints, loaded in serve mode: the consumer that pulls on a merge, and the tools.
+ENV MESH_TOOL_MODULES=/app/modules/records/dist/index.js,/app/modules/records/dist/tools/index.js

modules/records/module.json

@@ -11,6 +11,9 @@
   "binds": {
     "git": "${dir:mesh-state}/git.json"
   },
+  "own-secrets": {
+    "broker": "${dir:mesh-state}/broker"
+  },
   "consumes": [
     "gitea.pull.merged"
   ],
@@ -50,30 +53,47 @@
       "content": "${bound:git:scheme}://${bound:git:at}:${bound:git:port}\n"
     },
     {
-      "id": "git",
+      "id": "runtime",
-      "type": "package",
+      "type": "container",
-      "package": "git"
+      "name": "records",
+      "network": "host",
+      "volumes": [
+        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "${dir:mesh-state}/config.json:/run/config/config.json:ro",
+        "${dir:mesh-state}/origin:/run/config/origin:ro",
+        "${dir:checkout}:${dir:checkout}"
+      ],
+      "env": {
+        "MESH_BROKER_FILE": "/run/secrets/broker",
+        "MESH_RECORDS_CONFIG_FILE": "/run/config/config.json",
+        "MESH_RECORDS_ORIGIN_FILE": "/run/config/origin",
+        "MESH_RECORDS_DIR": "${dir:checkout}"
+      },
+      "artifact": "runtime",
+      "restart-on": [
+        "config",
+        "origin"
+      ]
     }
   ],
   "build": {
+    "on": [
+      {
+        "arg": "BUILD_BASE",
+        "module": "mesh-tools",
+        "artifact": "build"
+      },
+      {
+        "arg": "RUNTIME_BASE",
+        "module": "mesh-tools",
+        "artifact": "runtime"
+      }
+    ],
     "artifacts": [
       {
-        "name": "code",
+        "name": "runtime",
-        "kind": "bundle",
+        "kind": "image",
-        "language": "typescript",
+        "from": "Dockerfile"
-        "entrypoints": [
-          "index.js",
-          "tools/index.js"
-        ],
-        "loads": [
-          "index.js",
-          "tools/index.js"
-        ],
-        "env": {
-          "MESH_RECORDS_CONFIG_FILE": "${dir:mesh-state}/config.json",
-          "MESH_RECORDS_ORIGIN_FILE": "${dir:mesh-state}/origin",
-          "MESH_RECORDS_DIR": "${dir:checkout}"
-        }
       }
     ]
   }

modules/redis/Dockerfile

@@ -0,0 +1,30 @@
+# redis'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
+# Compiled under /app/modules so `@novox/mesh-sdk` resolves upward into the base's own
+# node_modules — the module is compiled against exactly the sdk it will run against. The compiler
+# is invoked by its real path: node_modules/.bin entries are launcher symlinks the base image
+# resolved away.
+WORKDIR /app/modules/redis
+COPY . .
+RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts provisioner/index.ts \
+      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
+
+FROM ${RUNTIME_BASE}
+COPY --from=build /app/modules/redis/dist /app/modules/redis/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. A container that instead ran only its
+# provisioner (`run`) served no tools and emitted no events; a container that named no command
+# ran no provisioner at all.
+ENV MESH_TOOL_MODULES=/app/modules/redis/dist/index.js,/app/modules/redis/dist/tools/index.js,/app/modules/redis/dist/provisioner/index.js

modules/redis/module.json

@@ -35,6 +35,9 @@
   "secrets": {
     "secret": "${dir:state}/default.secret"
   },
+  "own-secrets": {
+    "broker": "${dir:mesh-state}/broker"
+  },
   "listens": [
     {
       "name": "cache",
@@ -45,6 +48,12 @@
     }
   ],
   "resources": [
+    {
+      "id": "mesh-state",
+      "type": "directory",
+      "mode": "0700",
+      "place": "mesh"
+    },
     {
       "id": "state",
       "type": "directory",
@@ -94,29 +103,44 @@
       "restart-on": [
         "server-conf"
       ]
+    },
+    {
+      "id": "runtime",
+      "type": "container",
+      "name": "mesh-redis",
+      "network": "redis",
+      "volumes": [
+        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "${dir:grants}:/var/lib/redis-module/grants:ro",
+        "${dir:state}/default.secret:/run/secrets/default:ro"
+      ],
+      "env": {
+        "MESH_BROKER_FILE": "/run/secrets/broker",
+        "MESH_RECEIVES": "/var/lib/redis-module/grants/mesh.json",
+        "MESH_PROVISION_REDIS": "redis:6379",
+        "MESH_PROVISION_PASSWORD_FILE": "/run/secrets/default"
+      },
+      "artifact": "runtime"
     }
   ],
   "build": {
+    "on": [
+      {
+        "arg": "BUILD_BASE",
+        "module": "mesh-tools",
+        "artifact": "build"
+      },
+      {
+        "arg": "RUNTIME_BASE",
+        "module": "mesh-tools",
+        "artifact": "runtime"
+      }
+    ],
     "artifacts": [
       {
-        "name": "code",
+        "name": "runtime",
-        "kind": "bundle",
+        "kind": "image",
-        "language": "typescript",
+        "from": "Dockerfile"
-        "entrypoints": [
-          "index.js",
-          "tools/index.js",
-          "provisioner/index.js"
-        ],
-        "loads": [
-          "index.js",
-          "tools/index.js",
-          "provisioner/index.js"
-        ],
-        "env": {
-          "MESH_RECEIVES": "${dir:grants}/mesh.json",
-          "MESH_PROVISION_REDIS": "127.0.0.1:${port:6379}",
-          "MESH_PROVISION_PASSWORD_FILE": "${dir:state}/default.secret"
-        }
       }
     ]
   }

modules/route-adapter/Dockerfile

@@ -0,0 +1,24 @@
+# route-adapter'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/route-adapter
+COPY . .
+RUN node /app/node_modules/typescript/bin/tsc adapter.ts index.ts \
+      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
+
+FROM ${RUNTIME_BASE}
+COPY --from=build /app/modules/route-adapter/dist /app/modules/route-adapter/dist
+# **No MESH_TOOL_MODULES, deliberately.** This module serves no tool and consumes no event: it is a
+# step the host runs to completion, named by the container's `args` as `mesh-tools run …`. Setting a
+# serve-time entrypoint here would give the image a second way to be started — one that connects to
+# the broker and never exits.

modules/route-adapter/module.json

@@ -47,18 +47,23 @@
     },
     {
       "id": "adapt",
-      "type": "process",
+      "type": "container",
-      "name": "route-adapter",
+      "name": "mesh-route-adapter",
-      "artifact": "code",
+      "artifact": "runtime",
-      "run": [
-        "node",
-        "index.js"
-      ],
       "run-once": true,
+      "volumes": [
+        "${dir:routes-dir}/mesh.json:${dir:routes-dir}/mesh.json:ro",
+        "${dir:state}/config.json:/run/config/config.json:ro",
+        "${access:dynamic}:/services/traefik/dynamic"
+      ],
       "env": {
         "MESH_RECEIVES": "${dir:routes-dir}/mesh.json",
-        "MESH_ROUTE_ADAPTER_CONFIG": "${dir:state}/config.json"
+        "MESH_ROUTE_ADAPTER_CONFIG": "/run/config/config.json"
       },
+      "args": [
+        "run",
+        "/app/modules/route-adapter/dist/index.js"
+      ],
       "restart-on": [
         "received-route",
         "config"
@@ -66,14 +71,23 @@
     }
   ],
   "build": {
+    "on": [
+      {
+        "arg": "BUILD_BASE",
+        "module": "mesh-tools",
+        "artifact": "build"
+      },
+      {
+        "arg": "RUNTIME_BASE",
+        "module": "mesh-tools",
+        "artifact": "runtime"
+      }
+    ],
     "artifacts": [
       {
-        "name": "code",
+        "name": "runtime",
-        "kind": "bundle",
+        "kind": "image",
-        "language": "typescript",
+        "from": "Dockerfile"
-        "entrypoints": [
-          "index.js"
-        ]
       }
     ]
   }

modules/umami/Dockerfile

@@ -0,0 +1,30 @@
+# umami'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
+# Compiled under /app/modules so `@novox/mesh-sdk` resolves upward into the base's own
+# node_modules — the module is compiled against exactly the sdk it will run against. The compiler
+# is invoked by its real path: node_modules/.bin entries are launcher symlinks the base image
+# resolved away.
+WORKDIR /app/modules/umami
+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/umami/dist /app/modules/umami/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. A container that instead ran only its
+# provisioner (`run`) served no tools and emitted no events; a container that named no command
+# ran no provisioner at all.
+ENV MESH_TOOL_MODULES=/app/modules/umami/dist/tools/index.js,/app/modules/umami/dist/provisioner/index.js

modules/umami/module.json

@@ -44,6 +44,9 @@
   "grants": {
     "analytics": "${dir:grants}"
   },
+  "own-secrets": {
+    "broker": "${dir:mesh-state}/broker"
+  },
   "listens": [
     {
       "name": "web",
@@ -54,6 +57,12 @@
     }
   ],
   "resources": [
+    {
+      "id": "mesh-state",
+      "type": "directory",
+      "mode": "0700",
+      "place": "mesh"
+    },
     {
       "id": "state",
       "type": "directory",
@@ -72,6 +81,13 @@
       "mode": "0600",
       "content": "DATABASE_URL=postgresql://${bound:postgres-database:as}:${secret:postgres-database}@${bound:postgres-database:at}:${bound:postgres-database:port}/${bound:postgres-database:as}\nDATABASE_TYPE=postgresql\nAPP_SECRET=${secret:app-secret}\n"
     },
+    {
+      "id": "provisioner-env",
+      "type": "file",
+      "path": "${dir:state}/provisioner.env",
+      "mode": "0600",
+      "content": "MESH_PROVISION_UMAMI_URL=http://umami:3000\nGRANTS=${dir:grants}\n"
+    },
     {
       "id": "net",
       "type": "network",
@@ -90,27 +106,46 @@
         "3000"
       ],
       "secrets-in-environment": "a Next.js/Prisma application: DATABASE_URL and APP_SECRET are read from the environment only; not convertible"
+    },
+    {
+      "id": "runtime",
+      "type": "container",
+      "name": "mesh-umami",
+      "network": "umami",
+      "volumes": [
+        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "${dir:grants}:${dir:grants}",
+        "${dir:state}/admin.secret:/run/secrets/admin:ro"
+      ],
+      "env": {
+        "MESH_BROKER_FILE": "/run/secrets/broker",
+        "MESH_RECEIVES": "${dir:grants}/mesh.json",
+        "MESH_UMAMI_ADMIN_PASSWORD_FILE": "/run/secrets/admin"
+      },
+      "env-file": [
+        "${dir:state}/provisioner.env"
+      ],
+      "artifact": "runtime"
     }
   ],
   "build": {
+    "on": [
+      {
+        "arg": "BUILD_BASE",
+        "module": "mesh-tools",
+        "artifact": "build"
+      },
+      {
+        "arg": "RUNTIME_BASE",
+        "module": "mesh-tools",
+        "artifact": "runtime"
+      }
+    ],
     "artifacts": [
       {
-        "name": "code",
+        "name": "runtime",
-        "kind": "bundle",
+        "kind": "image",
-        "language": "typescript",
+        "from": "Dockerfile"
-        "entrypoints": [
-          "tools/index.js",
-          "provisioner/index.js"
-        ],
-        "loads": [
-          "tools/index.js",
-          "provisioner/index.js"
-        ],
-        "env": {
-          "MESH_RECEIVES": "${dir:grants}/mesh.json",
-          "MESH_UMAMI_ADMIN_PASSWORD_FILE": "${dir:state}/admin.secret",
-          "MESH_PROVISION_UMAMI_URL": "http://127.0.0.1:${port:3000}"
-        }
       }
     ]
   }