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.
claude-code: declare using the licence manager's seat when that module exists; until then the mesh refuses a seat no module declares
2026-10-04 03:48:41 +02:00 · 2026-10-04 02:23:34 +02:00 · 2026-10-04 02:23:23 +02:00 · 2026-10-03 23:49:16 +02:00 · 2026-10-03 23:41:01 +02:00 · 2026-10-03 23:40:21 +02:00
64 changed files with 2871 additions and 994 deletions
@@ -1,24 +0,0 @@
 # baserow's runtime: the tool runtime, carrying this module's compiled code.
 #
 # **Built from this module's own directory and nothing else.** The sdk and the tool runtime are in
 # the base images, published like any other artifact — which is what makes this buildable by the
 # mesh from a repository and a path (novox/hq ADR 0069) rather than only on a workstation that
 # happens to have the siblings.
 #
 # Two bases, named rather than pinned (novox/hq issue 044): the image this is COMPILED in and the
 # image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
 ARG BUILD_BASE
 ARG RUNTIME_BASE
 FROM ${BUILD_BASE} AS build
 WORKDIR /app/modules/baserow
 COPY . .
 RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts \
      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
 FROM ${RUNTIME_BASE}
 COPY --from=build /app/modules/baserow/dist /app/modules/baserow/dist
 # Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
 # provider's provisioner runs its reconcile loop in the same process, with the broker connected —
 # the convention novox/hq issues 060/061 settled.
 ENV MESH_TOOL_MODULES=/app/modules/baserow/dist/tools/index.js
@@ -25,8 +25,7 @@
    "postgres-database": "${dir:state}/database.secret"
  },
  "own-secrets": {
-    "admin": "${dir:state}/admin.secret",
+    "admin": "${dir:state}/admin.secret"
    "broker": "${dir:mesh-state}/broker"
  },
  "listens": [
    {
@@ -92,45 +91,24 @@
      "mode": "0600",
      "content": "{\n  \"password\": \"${secret:admin}\",\n  \"host\": \"${bound:route:name}\"\n}\n",
      "merge": "json"
    },
    {
      "id": "runtime",
      "type": "container",
      "name": "mesh-baserow",
      "network": "baserow",
      "volumes": [
        "${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_BASEROW_URL": "http://baserow:80",
        "MESH_BASEROW_CONFIG_FILE": "/run/config/config.json"
      },
      "restart-on": [
        "runtime-config"
      ],
      "artifact": "runtime"
    }
  ],
  "build": {
    "on": [
      {
        "arg": "BUILD_BASE",
        "module": "mesh-tools",
        "artifact": "build"
      },
      {
        "arg": "RUNTIME_BASE",
        "module": "mesh-tools",
        "artifact": "runtime"
      }
    ],
    "artifacts": [
      {
-        "name": "runtime",
+        "name": "tools",
-        "kind": "image",
+        "kind": "bundle",
-        "from": "Dockerfile"
+        "language": "typescript",
        "entrypoints": [
          "tools/index.js"
        ],
        "loads": [
          "tools/index.js"
        ],
        "env": {
          "MESH_BASEROW_URL": "http://127.0.0.1:${port:80}",
          "MESH_BASEROW_CONFIG_FILE": "${dir:mesh-state}/config.json"
        }
      }
    ]
  }
@@ -1,6 +1,6 @@
 ARG GO_BASE
 ARG ALPINE_BASE
-# builder's own image: the build machine itself, compiled into a container.
+# build-agent's image: the build machine itself, compiled into a container (novox/hq ADR 0190).
 #
 # **The source is not vendored here.** builder's actual code — cmd/mesh-builder, internal/builder,
 # internal/catalogue — lives in the mesh-controller repository, the same control plane it is one
@@ -0,0 +1,15 @@
 # build-agent
 The mesh's build machine as a role every machine can hold (novox/hq ADR 0190). It holds the node seat
 `node-build-agent`: every holder pulls one build at a time from the role's one work queue when it is
 idle, so a tier of many images is built by as many machines as hold the seat and are online, and a
 machine that is off builds nothing and blocks nothing. The controller asks the role, never a machine;
 the outcome names the machine that built it.
 What a holding machine needs is what the builder always needed, said here once: a container runtime
 (the socket is mounted), the artifact store and the package registry as provisions, a workspace, and
 the bus credential. The code is `cmd/mesh-builder` in the mesh-controller repository, compiled from
 that repository's main (`build.artifacts[].context`); this module ships the packaging.
 Assign it to every machine with a container runtime. It replaces `builder`, the one-holder form of the
 same thing; retire that once this is assigned where it was.
@@ -1,13 +1,14 @@
 {
-  "module": "builder",
+  "module": "build-agent",
  "version": "1",
  "slug": "agent",
  "capabilities": [
    "container-runtime"
  ],
  "claims": [
    {
-      "name": "mesh-build-machine",
+      "name": "node-build-agent",
-      "scope": "mesh"
+      "scope": "node"
    }
  ],
  "requires": [
@@ -36,19 +37,19 @@
      "mode": "0700"
    },
    {
-      "id": "builder-env",
+      "id": "agent-env",
      "type": "file",
-      "path": "${dir:mesh-state}/builder.env",
+      "path": "${dir:mesh-state}/build-agent.env",
      "mode": "0600",
      "content": "MESH_BROKER_FILE=/run/mesh/broker\nMESH_NODE=${machine:name}\nMESH_REGISTRY=${bound:artifact-store:at}:${bound:artifact-store:port}\nMESH_PACKAGE_BINDING=/run/mesh/package-registry.json\nMESH_NPM_TOKEN_FILE=/run/mesh/package-registry.secret\nMESH_WORKSPACE=${dir:workspace}\n"
    },
    {
      "id": "server",
      "type": "container",
-      "name": "mesh-builder",
+      "name": "mesh-build-agent",
      "artifact": "server",
      "env-file": [
-        "${dir:mesh-state}/builder.env"
+        "${dir:mesh-state}/build-agent.env"
      ],
      "volumes": [
        "${dir:mesh-state}:/run/mesh:ro",
@@ -56,7 +57,7 @@
        "/var/run/docker.sock:/var/run/docker.sock"
      ],
      "restart-on": [
-        "builder-env"
+        "agent-env"
      ],
      "network": "host"
    }
@@ -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.
@@ -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);
 }
@@ -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;
 }
@@ -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"
        }
      }
    ]
  }
 }
@@ -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 };
@@ -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"
  }
 }
@@ -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.
 `;
 }
@@ -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");
 }
@@ -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);
 });
@@ -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);
 });
@@ -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);
 });
@@ -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"));
 });
@@ -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"));
 });
@@ -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"));
  });
 }
@@ -0,0 +1,12 @@
 {
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "noEmit": true
  },
  "include": ["seal.ts", "grant.ts", "identity.ts", "render.ts", "node.ts", "tools/index.ts"]
 }
@@ -1,24 +0,0 @@
 # confluence's runtime: the tool runtime, carrying this module's compiled code.
 #
 # **Built from this module's own directory and nothing else.** The sdk and the tool runtime are in
 # the base images, published like any other artifact — which is what makes this buildable by the
 # mesh from a repository and a path (novox/hq ADR 0069) rather than only on a workstation that
 # happens to have the siblings.
 #
 # Two bases, named rather than pinned (novox/hq issue 044): the image this is COMPILED in and the
 # image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
 ARG BUILD_BASE
 ARG RUNTIME_BASE
 FROM ${BUILD_BASE} AS build
 WORKDIR /app/modules/confluence
 COPY . .
 RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts \
      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
 FROM ${RUNTIME_BASE}
 COPY --from=build /app/modules/confluence/dist /app/modules/confluence/dist
 # Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
 # provider's provisioner runs its reconcile loop in the same process, with the broker connected —
 # the convention novox/hq issues 060/061 settled.
 ENV MESH_TOOL_MODULES=/app/modules/confluence/dist/tools/index.js
@@ -3,16 +3,9 @@
  "version": "1",
  "slug": "confl",
  "own-secrets": {
-    "token": "${dir:state}/token",
+    "token": "${dir:state}/token"
    "broker": "${dir:mesh-state}/broker"
  },
  "resources": [
    {
      "id": "mesh-state",
      "type": "directory",
      "mode": "0700",
      "place": "mesh"
    },
    {
      "id": "state",
      "type": "directory",
@@ -26,46 +19,27 @@
      "merge": "json",
      "content": "{}",
      "mode": "0600"
    },
    {
      "id": "runtime",
      "type": "container",
      "name": "mesh-runtime-confluence",
      "network": "host",
      "volumes": [
        "${dir:state}/config.json:/run/config/config.json:ro",
        "${dir:state}/token:/run/secrets/token:ro",
        "${dir:mesh-state}/broker:/run/secrets/broker:ro"
      ],
      "env": {
        "MESH_CONFLUENCE_TOKEN_FILE": "/run/secrets/token",
        "MESH_CONFLUENCE_CONFIG_FILE": "/run/config/config.json",
        "MESH_BROKER_FILE": "/run/secrets/broker"
      },
      "artifact": "runtime"
    }
  ],
  "capabilities": [
    "container-runtime"
  ],
  "build": {
    "on": [
      {
        "arg": "BUILD_BASE",
        "module": "mesh-tools",
        "artifact": "build"
      },
      {
        "arg": "RUNTIME_BASE",
        "module": "mesh-tools",
        "artifact": "runtime"
      }
    ],
    "artifacts": [
      {
-        "name": "runtime",
+        "name": "tools",
-        "kind": "image",
+        "kind": "bundle",
-        "from": "Dockerfile"
+        "language": "typescript",
        "entrypoints": [
          "tools/index.js"
        ],
        "loads": [
          "tools/index.js"
        ],
        "env": {
          "MESH_CONFLUENCE_TOKEN_FILE": "${dir:state}/token",
          "MESH_CONFLUENCE_CONFIG_FILE": "${dir:state}/config.json"
        }
      }
    ]
  }
@@ -1,51 +1,236 @@
-// fail2ban's own code, in the module (novox/hq ADR 0039). The jails and the daemon are declared
+// fail2ban's own code, in the module (novox/hq ADR 0039). The jails are composed by the mesh from
-// resources — the mesh writes /etc/fail2ban/jail.d/* and keeps fail2ban.service running (see
+// the modules a machine runs (to-be 31) and written as declared resources; the daemon is kept
-// module.json). This code exists only to read and steer the *live* state the daemon owns at
+// running by one. This code exists only to read and steer the *live* state the daemon owns: who is
-// runtime: which IPs are banned right now, and the manual ban/unban an operator reaches for. That
+// banned now and until when, and the ban or release an operator asks for — the node-intrusion-
-// state (the running bans, /var/lib/fail2ban's sqlite) is fail2ban's, not the mesh's — the mesh
+// prevention seat's four verbs (ADR 0179). The daemon's state is fail2ban's, not the mesh's: the
-// reconciles the config, never the ban list.
+// mesh composes the jails and never writes the ban list.
 //
 // Spoken through fail2ban-client over the daemon's socket. Client and daemon come from the one
 // package this module declares on the machine, and the socket is root's: root is the module's
 // concern (ADR 0175 §4), and the runtime loading this bundle runs as the operator's account (to-be
 // 38 WP4), so the client is run through sudo without a prompt where the account is not root.
 import { execFile } from "node:child_process";
 import { accessSync, constants } from "node:fs";
 import { isIP } from "node:net";
 import { delimiter, join } from "node:path";
 import { promisify } from "node:util";
-const run = promisify(execFile);
+const execFileP = promisify(execFile);
 /** A command runner, so the verbs can be tested without a daemon. */
 export type Runner = (cmd: string, args: string[]) => Promise<string>;
 /** The command as it is run: as given when this process is root, else through sudo without a
 *  prompt. The daemon's socket answers only to root. */
 export function escalated(cmd: string, args: string[], uid: number | undefined = process.getuid?.()): [string, string[]] {
  if (uid === 0) return [cmd, args];
  return ["sudo", ["-n", cmd, ...args]];
 }
 /** Whether a tool is on this machine: an executable of that name on the path, or where the
 *  system keeps its administration. */
 export function installed(tool: string, path: string = process.env.PATH ?? ""): boolean {
  const dirs = [...path.split(delimiter), "/usr/sbin", "/sbin", "/usr/bin"].filter((d) => d !== "");
  return dirs.some((dir) => {
    try {
      accessSync(join(dir, tool), constants.X_OK);
      return true;
    } catch {
      return false;
    }
  });
 }
 export const execRunner: Runner = async (cmd, args) => {
  if (!installed(cmd)) throw new Error(`${cmd} is not installed on this machine`);
  const [program, argv] = escalated(cmd, args);
  try {
    const { stdout } = await execFileP(program, argv, { maxBuffer: 16 * 1024 * 1024 });
    return stdout;
  } catch (err) {
    const e = err as { code?: string | number; stderr?: string; stdout?: string; message?: string };
    const said = `${e.stdout ?? ""}${e.stderr ?? ""}`.trim();
    // What failed is named by how it failed: sudo missing is a spawn error, sudo refusing speaks
    // on its own stderr line, and the rest is the client's own answer.
    if (program === "sudo") {
      if (e.code === "ENOENT") throw new Error(`${cmd} needs root, and sudo is not installed here for the runtime's account to escalate with`);
      if (/^sudo:/m.test(said)) throw new Error(`${cmd} needs root and the runtime's account may not run it without a prompt: ${said}`);
    }
    if (/Failed to access socket path|Is fail2ban running|Permission denied to socket/i.test(said)) {
      throw new Error("fail2ban is not running on this machine, or its socket does not answer the runtime's account");
    }
    // fail2ban-client's own last line is the one a person reads ("Sorry but the jail 'x' does not exist").
    const lines = said.split("\n").map((l) => l.trim()).filter(Boolean);
    throw new Error(lines.length ? lines[lines.length - 1] : (e.message ?? `${cmd} failed`));
  }
 };
 /** One jail as the daemon reports it. */
 export interface JailStatus {
  jail: string;
  /** What the jail is reading: files or journal matches, as fail2ban names them. */
  watching: string[];
  /** Addresses with failures counted against them right now, and all failures since the jail started. */
  failing: { now: number; total: number };
  /** Addresses held right now, and all bans since the jail started. */
  banned: { now: number; total: number; addresses: string[] };
 }
 /** One ban as the daemon holds it. */
 export interface Ban {
  ip: string;
  jail: string;
  /** When the ban was placed, in the machine's local time as fail2ban prints it. */
  since: string;
  /** When the ban ends; "never" for a permanent ban. */
  until: string;
 }
 export interface JailSettings {
  jail: string;
  bantime: string;
  findtime: string;
  maxretry: number;
  ignoreip: string[];
  actions: string[];
  /** The log files the jail reads, when it reads files. */
  logpath: string[];
  /** The journal match the jail reads, when it reads the journal. */
  journalmatch: string;
 }
 export class Fail2banClient {
-  static fromEnv(_env: NodeJS.ProcessEnv = process.env): Fail2banClient {
+  private readonly run: Runner;
  constructor(run: Runner = execRunner) {
    this.run = run;
  }
  /** The daemon as this machine has it, through its own client. */
  static onThisMachine(): Fail2banClient {
    return new Fail2banClient();
  }
-  /** Overview of every jail, or the detailed status of one — currently-banned IPs and totals. */
+  private client(...args: string[]): Promise<string> {
-  async status(jail?: string): Promise<string> {
+    return this.run("fail2ban-client", args);
  }
  /** The jails the daemon runs, by name. */
  async jails(): Promise<string[]> {
    const out = await this.client("status");
    const m = out.match(/Jail list:\s*(.*)/);
    if (!m) return [];
    return m[1].split(",").map((j) => j.trim()).filter(Boolean);
  }
  /** Every jail with what it watches and holds, or one jail's detail. */
  async status(jail?: string): Promise<{ jails: JailStatus[] }> {
    const names = jail ? [jail] : await this.jails();
    const jails: JailStatus[] = [];
    for (const name of names) {
      jails.push(parseJailStatus(name, await this.client("status", name)));
    }
    return { jails };
  }
  /** Every address banned now, with the jail holding it and when the ban ends. */
  async banned(jail?: string): Promise<{ banned: Ban[] }> {
    const names = jail ? [jail] : await this.jails();
    const banned: Ban[] = [];
    for (const name of names) {
      banned.push(...parseBans(name, await this.client("get", name, "banip", "--with-time")));
    }
    banned.sort((a, b) => a.until.localeCompare(b.until) || a.ip.localeCompare(b.ip));
    return { banned };
  }
  /** Ban one address in one jail now. The daemon's own answer is how many addresses it added. */
  async ban(ip: string, jail: string): Promise<{ banned: Ban | null; added: number }> {
    address(ip);
    name(jail);
    const out = await this.client("set", jail, "banip", ip);
    const added = Number.parseInt(out.trim(), 10) || 0;
    const held = (await this.banned(jail)).banned.find((b) => b.ip === ip) ?? null;
    return { banned: held, added };
  }
  /** Let one address go, from one jail or from every jail. The daemon's answer is how many it released. */
  async unban(ip: string, jail?: string): Promise<{ released: number; ip: string; jail: string | "every jail" }> {
    address(ip);
    let out: string;
    if (jail) {
-      const { stdout } = await run("sudo", ["fail2ban-client", "status", jail]);
+      name(jail);
-      return stdout;
+      out = await this.client("set", jail, "unbanip", ip);
    } else {
      out = await this.client("unban", ip);
    }
-    const { stdout: overview } = await run("sudo", ["fail2ban-client", "status"]);
+    return { released: Number.parseInt(out.trim(), 10) || 0, ip, jail: jail ?? "every jail" };
    const match = overview.match(/Jail list:\s*(.+)/);
    if (!match) return overview;
    const jails = match[1].split(",").map((j) => j.trim()).filter(Boolean);
    const parts: string[] = [overview.trimEnd(), ""];
    for (const j of jails) {
      const { stdout } = await run("sudo", ["fail2ban-client", "status", j]);
      parts.push(`=== ${j} ===`, stdout.trimEnd(), "");
    }
    return parts.join("\n");
  }
-  /** Manually ban an IP in a jail. Mutates live state, not a mesh-managed file. */
+  /** One jail's effective settings — the module's own tool, beside the seat's verbs. */
-  async ban(jail: string, ip: string): Promise<string> {
+  async settings(jail: string): Promise<JailSettings> {
-    const { stdout } = await run("sudo", ["fail2ban-client", "set", jail, "banip", ip]);
+    name(jail);
-    return stdout;
+    const get = (key: string) => this.client("get", jail, key);
-  }
+    const [bantime, findtime, maxretry, ignoreip, actions, logpath, journalmatch] = await Promise.all([
-
+      get("bantime"), get("findtime"), get("maxretry"), get("ignoreip"), get("actions"), get("logpath"),
-  /** Unban an IP from one jail, or from every jail when no jail is given. */
+      get("journalmatch"),
-  async unban(ip: string, jail?: string): Promise<string> {
+    ]);
-    const args = jail
+    return {
-      ? ["fail2ban-client", "set", jail, "unbanip", ip]
+      jail,
-      : ["fail2ban-client", "unban", ip];
+      bantime: bantime.trim(),
-    const { stdout } = await run("sudo", args);
+      findtime: findtime.trim(),
-    return stdout;
+      maxretry: Number.parseInt(maxretry.trim(), 10),
      ignoreip: listed(ignoreip),
      actions: actions.split("\n").slice(1).map((l) => l.trim()).filter(Boolean),
      logpath: /No file is currently monitored/.test(logpath) ? [] : listed(logpath),
      journalmatch: journalmatch.split("\n").slice(1).map((l) => l.trim()).filter(Boolean).join(" "),
    };
  }
 }
 /** fail2ban's tree listings: lines like "|- 127.0.0.0/8" and "`- ::1", after a heading. */
 function listed(out: string): string[] {
  return out
    .split("\n")
    .map((l) => l.replace(/^[\s|`-]+/, "").trim())
    .filter((l, i) => i > 0 && l.length > 0);
 }
 export function parseJailStatus(jail: string, out: string): JailStatus {
  const field = (label: string) => {
    const m = out.match(new RegExp(label.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + ":\\t?\\s*(.*)"));
    return m ? m[1].trim() : "";
  };
  const num = (label: string) => Number.parseInt(field(label), 10) || 0;
  const watching = [field("File list"), field("Journal matches")].filter(Boolean);
  return {
    jail,
    watching,
    failing: { now: num("Currently failed"), total: num("Total failed") },
    banned: {
      now: num("Currently banned"),
      total: num("Total banned"),
      addresses: field("Banned IP list").split(/\s+/).filter(Boolean),
    },
  };
 }
 /** `get <jail> banip --with-time` prints one ban per line: "IP \tsince + seconds = until". */
 export function parseBans(jail: string, out: string): Ban[] {
  const bans: Ban[] = [];
  for (const line of out.split("\n")) {
    const m = line.match(/^(\S+)\s+(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}) \+ (-?\d+) = (\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}|\S+)/);
    if (!m) continue;
    bans.push({ ip: m[1], jail, since: m[2], until: Number(m[3]) < 0 ? "never" : m[4] });
  }
  return bans;
 }
 function address(ip: string): void {
  if (!isIP(ip)) throw new Error(`${JSON.stringify(ip)} is not an address`);
 }
 function name(jail: string): void {
  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(jail)) throw new Error(`${JSON.stringify(jail)} is not a jail's name`);
 }
@@ -7,9 +7,22 @@
  "claims": [
    {
      "name": "node-intrusion-prevention",
-      "scope": "node"
+      "scope": "node",
      "serves": [
        "status",
        "banned",
        "ban",
        "unban"
      ]
    }
  ],
  "tools": [
    "fail2ban_settings"
  ],
  "jailing": {
    "into": "/etc/fail2ban/jail.d/mesh.conf",
    "filter-into": "/etc/fail2ban/filter.d"
  },
  "resources": [
    {
      "id": "package",
@@ -28,19 +41,31 @@
      "path": "/etc/fail2ban/action.d",
      "mode": "0755"
    },
    {
      "id": "filter-d",
      "type": "directory",
      "path": "/etc/fail2ban/filter.d",
      "mode": "0755"
    },
    {
      "id": "run-dir",
      "type": "directory",
      "path": "/var/run/fail2ban",
      "mode": "0755"
    },
    {
      "id": "jail-local",
      "type": "file",
      "path": "/etc/fail2ban/jail.local",
      "mode": "0644",
-      "content": "[INCLUDES]\n\nbefore = paths-arch.conf\n\n[DEFAULT]\n\n# Never act on the machine itself or on a tunnel peer: the mesh's private range is\n# ${machine:mesh-range}, named here rather than written as a value the module cannot\n# know (novox/hq ADR 0112). Without this, fail2ban could ban the mesh's own nodes.\nignoreip = 127.0.0.1/8 ::1 ${machine:mesh-range}\n\nbantime  = 10m\nfindtime = 10m\nmaxretry = 5\n\n# Ban through iptables, not through a firewall front-end the machine may not have. ufw is\n# installed on two of this mesh's machines and absent on the other two, and fail2ban finds out\n# only at ban time: the service reports healthy, the jail counts the attempt, the ban command\n# exits 127, and nothing is blocked. Proven on 2026-09-28 -- 'ufw: command not found' on a\n# machine the mesh reported as protected.\n#\n# The action below is this module's own, already used by the recidive jail on every machine\n# here, and it bans in DOCKER-USER as well as INPUT, so a container's published port is\n# covered too.\nbanaction = iptables-allports-dualchain\nbanaction_allports = iptables-allports-dualchain\n\n[sshd]\nenabled = true\nport    = ssh\nlogpath = %(sshd_log)s\nbackend = %(sshd_backend)s\n"
+      "content": "[INCLUDES]\n\nbefore = paths-arch.conf\n\n[DEFAULT]\n\n# Never act on the machine itself or on a tunnel peer: the mesh's private range is\n# ${machine:mesh-range}, named here rather than written as a value the module cannot\n# know (novox/hq ADR 0112). Without this, fail2ban could ban the mesh's own nodes.\n# **A ban list never holds a neighbour.** The mesh's own range is named rather than written\n# (novox/hq ADR 0112), and every private range beside it: a source on one is somebody's own\n# network, not the internet. On a machine behind a router that reflects local traffic, every\n# client in the house arrives as the gateway's address — so one mistyped local request banned\n# 192.168.1.1 on the home server and would have cut the whole house off from it (ADR 0186).\nignoreip = 127.0.0.1/8 ::1 ${machine:mesh-range} 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16 169.254.0.0/16 fc00::/7 fe80::/10\n\n# Three failures in a day ban for a day (novox/hq ADR 0179). The attackers this mesh sees pace\n# themselves at one try every ten minutes, under any ten-minute window; a day's window counts\n# them, and a day's ban costs a person who mistyped three times once, from one address, while\n# the mesh's own range is never banned at all.\nbantime  = 1d\nfindtime = 1d\nmaxretry = 3\n\n# Ban through iptables, not through a firewall front-end the machine may not have. ufw is\n# installed on two of this mesh's machines and absent on the other two, and fail2ban finds out\n# only at ban time: the service reports healthy, the jail counts the attempt, the ban command\n# exits 127, and nothing is blocked. Proven on 2026-09-28 -- 'ufw: command not found' on a\n# machine the mesh reported as protected.\n#\n# The action below is this module's own, already used by the recidive jail on every machine\n# here, and it bans in DOCKER-USER as well as INPUT, so a container's published port is\n# covered too.\nbanaction = iptables-allports-dualchain\nbanaction_allports = iptables-allports-dualchain\n\n[sshd]\nenabled = true\nport    = ssh\nlogpath = %(sshd_log)s\nbackend = %(sshd_backend)s\n"
    },
    {
      "id": "jail-sshd",
      "type": "file",
      "path": "/etc/fail2ban/jail.d/sshd.conf",
      "mode": "0644",
-      "content": "[sshd]\nenabled = true\nport    = ssh\nlogpath = %(sshd_log)s\nbackend = %(sshd_backend)s\nmaxretry = 5\n"
+      "content": "[sshd]\nenabled = true\nport    = ssh\nlogpath = %(sshd_log)s\nbackend = %(sshd_backend)s\nmaxretry = 3\nfindtime = 1d\nbantime  = 1d\n"
    },
    {
      "id": "log",
@@ -55,7 +80,7 @@
      "type": "file",
      "path": "/etc/fail2ban/jail.d/recidive.conf",
      "mode": "0644",
-      "content": "[recidive]\nenabled = true\nlogpath  = /var/log/fail2ban.log\n# Ban in both INPUT (host services like SSH) and DOCKER-USER (container services)\nbanaction = iptables-allports-dualchain\nbantime  = 1w\nfindtime = 1d\n"
+      "content": "[recidive]\nenabled = true\nlogpath  = /var/log/fail2ban.log\n# Ban in both INPUT (host services like SSH) and DOCKER-USER (container services)\nbanaction = iptables-allports-dualchain\n# Banned twice in two weeks, by any jail, is banned for four (novox/hq ADR 0179).\nbantime  = 4w\nfindtime = 2w\nmaxretry = 2\n"
    },
    {
      "id": "action-dualchain",
@@ -81,8 +106,21 @@
        "jail-local",
        "jail-sshd",
        "jail-recidive",
-        "action-dualchain"
+        "action-dualchain",
        "composed-jails"
      ]
    }
-  ]
+  ],
  "build": {
    "artifacts": [
      {
        "name": "tools",
        "kind": "bundle",
        "language": "typescript",
        "entrypoints": [
          "tools/index.js"
        ]
      }
    ]
  }
 }
@@ -1,14 +1,18 @@
 {
  "name": "@novox/module-fail2ban",
  "version": "0.1.0",
-  "description": "fail2ban — intrusion prevention: the mesh declares the jails and keeps the daemon running; its ban/unban/status tools live here.",
+  "description": "fail2ban \u2014 intrusion prevention: the mesh composes the jails and keeps the daemon running; this module holds the node-intrusion-prevention seat and serves its verbs status, banned, ban and unban (novox/hq to-be 31, ADR 0179).",
  "type": "module",
  "private": true,
  "dependencies": {
-    "@novox/mesh-sdk": "^0.1.0"
+    "@novox/mesh-sdk": "^0.1.1"
  },
  "devDependencies": {
    "@types/node": "^22.0.0",
    "typescript": "^5.6.0"
  },
  "scripts": {
    "build": "tsc client.ts tools/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --rootDir . --outDir dist",
    "test": "node --test --experimental-strip-types 'test/*.test.ts'"
  }
 }
@@ -0,0 +1,114 @@
 // The intrusion prevention's verbs over a fake daemon, with the shapes fail2ban-client 1.1.0 printed
 // on the control node on 2026-10-02 (novox/hq ADR 0179).
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { Fail2banClient, escalated, installed, parseBans, parseJailStatus, type Runner } from "../client.ts";
 const STATUS = "Status\n|- Number of jail:\t2\n`- Jail list:\trecidive, sshd\n";
 const RECIDIVE =
  "Status for the jail: recidive\n|- Filter\n|  |- Currently failed:\t36\n|  |- Total failed:\t149\n" +
  "|  `- File list:\t/var/log/fail2ban.log\n`- Actions\n   |- Currently banned:\t9\n   |- Total banned:\t13\n" +
  "   `- Banned IP list:\t195.178.110.30 45.148.10.240 92.118.39.71\n";
 const SSHD =
  "Status for the jail: sshd\n|- Filter\n|  |- Currently failed:\t5\n|  |- Total failed:\t11776\n" +
  "|  `- Journal matches:\t_SYSTEMD_UNIT=sshd.service + _COMM=sshd\n`- Actions\n   |- Currently banned:\t0\n" +
  "   |- Total banned:\t150\n   `- Banned IP list:\t\n";
 const WITH_TIME =
  "195.178.110.30 \t2026-09-26 23:18:47 + 604800 = 2026-10-03 23:18:47\n" +
  "92.118.39.71 \t2026-09-28 10:33:49 + 604800 = 2026-10-05 10:33:49\n";
 function fake(answers: Record<string, string>, calls: string[][] = []): Runner {
  return async (cmd, args) => {
    calls.push([cmd, ...args]);
    const key = args.join(" ");
    if (key in answers) return answers[key];
    throw new Error(`unexpected ${cmd} ${key}`);
  };
 }
 test("a jail's status is read into numbers, what it watches and who it holds", () => {
  const s = parseJailStatus("recidive", RECIDIVE);
  assert.deepEqual(s, {
    jail: "recidive",
    watching: ["/var/log/fail2ban.log"],
    failing: { now: 36, total: 149 },
    banned: { now: 9, total: 13, addresses: ["195.178.110.30", "45.148.10.240", "92.118.39.71"] },
  });
  const j = parseJailStatus("sshd", SSHD);
  assert.deepEqual(j.watching, ["_SYSTEMD_UNIT=sshd.service + _COMM=sshd"]);
  assert.deepEqual(j.banned, { now: 0, total: 150, addresses: [] });
 });
 test("status covers every jail the daemon lists, or the one named", async () => {
  const calls: string[][] = [];
  const f = new Fail2banClient(fake({ status: STATUS, "status recidive": RECIDIVE, "status sshd": SSHD }, calls));
  const all = await f.status();
  assert.deepEqual(all.jails.map((j) => j.jail), ["recidive", "sshd"]);
  const one = await f.status("sshd");
  assert.equal(one.jails.length, 1);
  assert.deepEqual(calls[calls.length - 1], ["fail2ban-client", "status", "sshd"]);
 });
 test("bans are read with when they were placed and when they end, a permanent one as never", () => {
  const bans = parseBans("recidive", WITH_TIME + "203.0.113.9 \t2026-10-01 00:00:00 + -1 = never\n");
  assert.equal(bans.length, 3);
  assert.deepEqual(bans[0], { ip: "195.178.110.30", jail: "recidive", since: "2026-09-26 23:18:47", until: "2026-10-03 23:18:47" });
  assert.equal(bans[2].until, "never");
  assert.deepEqual(parseBans("sshd", "\n"), []);
 });
 test("banned gathers every jail's bans, soonest to end first", async () => {
  const f = new Fail2banClient(fake({
    status: STATUS,
    "get recidive banip --with-time": WITH_TIME,
    "get sshd banip --with-time": "198.51.100.7 \t2026-10-02 15:06:58 + 600 = 2026-10-02 15:16:58\n",
  }));
  const { banned } = await f.banned();
  assert.deepEqual(banned.map((b) => `${b.ip}@${b.jail}`), ["198.51.100.7@sshd", "195.178.110.30@recidive", "92.118.39.71@recidive"]);
 });
 test("ban asks the daemon by jail and answers with the ban as held; a non-address is refused before anything runs", async () => {
  const calls: string[][] = [];
  const f = new Fail2banClient(fake({
    "set recidive banip 198.51.100.7": "1\n",
    "get recidive banip --with-time": WITH_TIME + "198.51.100.7 \t2026-10-02 17:00:00 + 604800 = 2026-10-09 17:00:00\n",
  }, calls));
  const r = await f.ban("198.51.100.7", "recidive");
  assert.equal(r.added, 1);
  assert.equal(r.banned?.until, "2026-10-09 17:00:00");
  assert.deepEqual(calls[0], ["fail2ban-client", "set", "recidive", "banip", "198.51.100.7"]);
  await assert.rejects(() => f.ban("not-an-ip", "recidive"), /is not an address/);
  await assert.rejects(() => f.ban("198.51.100.7", "a jail; rm"), /is not a jail's name/);
  assert.equal(calls.length, 2);
 });
 test("unban releases from one jail or from every jail", async () => {
  const calls: string[][] = [];
  const f = new Fail2banClient(fake({ "set sshd unbanip 198.51.100.7": "1\n", "unban 198.51.100.7": "2\n" }, calls));
  assert.deepEqual(await f.unban("198.51.100.7", "sshd"), { released: 1, ip: "198.51.100.7", jail: "sshd" });
  assert.deepEqual(await f.unban("198.51.100.7"), { released: 2, ip: "198.51.100.7", jail: "every jail" });
  assert.deepEqual(calls[1], ["fail2ban-client", "unban", "198.51.100.7"]);
 });
 test("a jail's settings are read from the daemon's listings", async () => {
  const f = new Fail2banClient(fake({
    "get sshd bantime": "86400\n", "get sshd findtime": "86400\n", "get sshd maxretry": "3\n",
    "get sshd ignoreip": "These IP addresses/networks are ignored:\n|- 127.0.0.0/8\n|- 10.10.0.0/24\n`- ::1\n",
    "get sshd actions": "The jail sshd has the following actions:\niptables-allports-dualchain\n",
    "get sshd logpath": "No file is currently monitored\n",
    "get sshd journalmatch": "Current match filter:\n_SYSTEMD_UNIT=sshd.service + _COMM=sshd\n",
  }));
  assert.deepEqual(await f.settings("sshd"), {
    jail: "sshd", bantime: "86400", findtime: "86400", maxretry: 3,
    ignoreip: ["127.0.0.0/8", "10.10.0.0/24", "::1"], actions: ["iptables-allports-dualchain"],
    logpath: [], journalmatch: "_SYSTEMD_UNIT=sshd.service + _COMM=sshd",
  });
 });
 test("the client runs as given by root and through sudo without a prompt by anyone else", () => {
  assert.deepEqual(escalated("fail2ban-client", ["status"], 0), ["fail2ban-client", ["status"]]);
  assert.deepEqual(escalated("fail2ban-client", ["set", "sshd", "banip", "198.51.100.7"], 1000),
    ["sudo", ["-n", "fail2ban-client", "set", "sshd", "banip", "198.51.100.7"]]);
  assert.equal(installed("sh"), true);
  assert.equal(installed("no-such-client-of-the-mesh"), false);
 });
@@ -1,55 +1,62 @@
-// fail2ban's tools — reading and steering the live ban state. The jails themselves are declared
+// The intrusion prevention's tools: the node-intrusion-prevention seat's four verbs — who is banned,
-// resources (module.json); these three touch what the running daemon holds: what is banned now,
+// the jails' state, ban one, let one go — and the module's own reading of a jail's settings
-// and the manual ban/unban an operator reaches for. The daemon's state is fail2ban's own, so this
+// (novox/hq to-be 31, ADR 0179). The jails themselves are composed by the mesh from the modules a
-// is the only way to see or change it — the mesh reconciles the config, not the bans.
+// machine runs and written as declared resources; these touch only what the running daemon holds.
 import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
 import { Fail2banClient } from "../client.js";
-export function getFail2banTools(fail2ban: Fail2banClient): ToolDefinition[] {
+export function getSeatVerbs(fail2ban: Fail2banClient): ToolDefinition[] {
  return [
    {
-      name: "fail2ban_status",
+      name: "status",
      description:
-        "fail2ban status on this node — the jails and their live bans. Omit `jail` for every jail, or name one for its detail.",
+        "Every jail on this machine with what it watches, how many addresses it is counting failures against and holding now, and the totals since it started; one jail's detail when named.",
-      input: {
+      input: { jail: { type: "string", description: "one jail (optional)" } },
-        type: "object",
+      run: async (args) => fail2ban.status(args.jail ? String(args.jail) : undefined),
        properties: {
          jail: {
            type: "string",
            description: "A specific jail (e.g. sshd, recidive); omit for the overview of all jails.",
          },
        },
      },
      run: async (args) => ({ status: await fail2ban.status(args.jail as string | undefined) }),
    },
    {
-      name: "fail2ban_ban",
+      name: "banned",
-      description: "Manually ban an IP address in a jail — a live change to the running daemon, not a mesh-managed file.",
+      description: "Every address banned on this machine right now, with the jail that holds it, when it was banned and when the ban ends.",
-      input: {
+      input: { jail: { type: "string", description: "one jail (optional)" } },
-        type: "object",
+      run: async (args) => fail2ban.banned(args.jail ? String(args.jail) : undefined),
        properties: {
          jail: { type: "string", description: "Jail name (e.g. sshd, recidive)." },
          ip: { type: "string", description: "IP address to ban." },
        },
        required: ["jail", "ip"],
      },
      run: async (args) => ({ result: await fail2ban.ban(args.jail as string, args.ip as string) }),
    },
    {
-      name: "fail2ban_unban",
+      name: "ban",
-      description: "Unban an IP address from one jail, or from every jail when `jail` is omitted.",
+      description:
        "Ban one address in one jail now, for the jail's ban time — an operator's act on the live ban list, which the mesh never writes itself.",
      input: {
-        type: "object",
+        ip: { type: "string", description: "the address" },
-        properties: {
+        jail: { type: "string", description: "the jail to hold it (recidive for the long ban)" },
          ip: { type: "string", description: "IP address to unban." },
          jail: { type: "string", description: "A specific jail; omit to unban from all jails." },
        },
        required: ["ip"],
      },
-      run: async (args) => ({ result: await fail2ban.unban(args.ip as string, args.jail as string | undefined) }),
+      run: async (args) => fail2ban.ban(String(args.ip ?? ""), String(args.jail ?? "")),
    },
    {
      name: "unban",
      description: "Let one address go, from one jail or from every jail when none is named.",
      input: {
        ip: { type: "string", description: "the address" },
        jail: { type: "string", description: "one jail (optional)" },
      },
      run: async (args) => fail2ban.unban(String(args.ip ?? ""), args.jail ? String(args.jail) : undefined),
    },
  ];
 }
-registerModuleTools("fail2ban", () => getFail2banTools(Fail2banClient.fromEnv()));
+export function getFail2banTools(fail2ban: Fail2banClient): ToolDefinition[] {
  return [
    {
      name: "fail2ban_settings",
      description:
        "One jail's effective settings on this machine: ban time, window, tries, the addresses it never bans, its actions and what it reads.",
      input: { jail: { type: "string", description: "the jail" } },
      run: async (args) => fail2ban.settings(String(args.jail ?? "")),
    },
  ];
 }
 const fail2ban = Fail2banClient.onThisMachine();
 // The seat's verbs under the seat's name: the runtime serves them on the seat's subjects where this
 // module holds it (ADR 0159, 0160). The module's own under its own.
 registerModuleTools("node-intrusion-prevention", () => getSeatVerbs(fail2ban));
 registerModuleTools("fail2ban", () => getFail2banTools(fail2ban));
@@ -145,7 +145,8 @@
      "volumes": [
        "${dir:data}:/data"
      ],
-      "secrets-in-environment": "gitea honours GITEA__database__PASSWD__FILE and GITEA__security__INTERNAL_TOKEN__FILE; convertible, awaiting a bed that proves it"
+      "secrets-in-environment": "gitea honours GITEA__database__PASSWD__FILE and GITEA__security__INTERNAL_TOKEN__FILE; convertible, awaiting a bed that proves it",
      "logging": "journald"
    },
    {
      "id": "admin-bootstrap",
@@ -237,5 +238,12 @@
        "from": "Dockerfile"
      }
    ]
-  }
+  },
  "jails": [
    {
      "name": "gitea",
      "failregex": "^.*Failed authentication attempt for .* from <HOST>(?::\\d+)?\\s*$\n            ^.*Invalid user .* from <HOST> port \\d+\\s*$\n            ^.*User \\S+ from <HOST> not allowed because .*$",
      "jail": "backend = systemd\njournalmatch = CONTAINER_NAME=gitea\nport = http,https,222\nmaxretry = 3\nfindtime = 1d\nbantime = 1d"
    }
  ]
 }
@@ -1,24 +0,0 @@
 # gitlab'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/gitlab
 COPY . .
 RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts \
      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
 FROM ${RUNTIME_BASE}
 COPY --from=build /app/modules/gitlab/dist /app/modules/gitlab/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/gitlab/dist/tools/index.js
@@ -2,16 +2,9 @@
  "module": "gitlab",
  "version": "1",
  "own-secrets": {
-    "token": "${dir:state}/token",
+    "token": "${dir:state}/token"
    "broker": "${dir:mesh-state}/broker"
  },
  "resources": [
    {
      "id": "mesh-state",
      "type": "directory",
      "mode": "0700",
      "place": "mesh"
    },
    {
      "id": "state",
      "type": "directory",
@@ -25,46 +18,27 @@
      "merge": "json",
      "content": "{}",
      "mode": "0600"
    },
    {
      "id": "runtime",
      "type": "container",
      "name": "mesh-runtime-gitlab",
      "network": "host",
      "volumes": [
        "${dir:state}/config.json:/run/config/config.json:ro",
        "${dir:state}/token:/run/secrets/token:ro",
        "${dir:mesh-state}/broker:/run/secrets/broker:ro"
      ],
      "env": {
        "MESH_GITLAB_TOKEN_FILE": "/run/secrets/token",
        "MESH_GITLAB_CONFIG_FILE": "/run/config/config.json",
        "MESH_BROKER_FILE": "/run/secrets/broker"
      },
      "artifact": "runtime"
    }
  ],
  "capabilities": [
    "container-runtime"
  ],
  "build": {
    "on": [
      {
        "arg": "BUILD_BASE",
        "module": "mesh-tools",
        "artifact": "build"
      },
      {
        "arg": "RUNTIME_BASE",
        "module": "mesh-tools",
        "artifact": "runtime"
      }
    ],
    "artifacts": [
      {
-        "name": "runtime",
+        "name": "tools",
-        "kind": "image",
+        "kind": "bundle",
-        "from": "Dockerfile"
+        "language": "typescript",
        "entrypoints": [
          "tools/index.js"
        ],
        "loads": [
          "tools/index.js"
        ],
        "env": {
          "MESH_GITLAB_TOKEN_FILE": "${dir:state}/token",
          "MESH_GITLAB_CONFIG_FILE": "${dir:state}/config.json"
        }
      }
    ]
  }
@@ -1,24 +0,0 @@
 # jira'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/jira
 COPY . .
 RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts \
      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
 FROM ${RUNTIME_BASE}
 COPY --from=build /app/modules/jira/dist /app/modules/jira/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/jira/dist/tools/index.js
@@ -2,16 +2,9 @@
  "module": "jira",
  "version": "1",
  "own-secrets": {
-    "token": "${dir:state}/token",
+    "token": "${dir:state}/token"
    "broker": "${dir:mesh-state}/broker"
  },
  "resources": [
    {
      "id": "mesh-state",
      "type": "directory",
      "mode": "0700",
      "place": "mesh"
    },
    {
      "id": "state",
      "type": "directory",
@@ -25,46 +18,27 @@
      "merge": "json",
      "content": "{}",
      "mode": "0600"
    },
    {
      "id": "runtime",
      "type": "container",
      "name": "mesh-runtime-jira",
      "network": "host",
      "volumes": [
        "${dir:state}/config.json:/run/config/config.json:ro",
        "${dir:state}/token:/run/secrets/token:ro",
        "${dir:mesh-state}/broker:/run/secrets/broker:ro"
      ],
      "env": {
        "MESH_JIRA_TOKEN_FILE": "/run/secrets/token",
        "MESH_JIRA_CONFIG_FILE": "/run/config/config.json",
        "MESH_BROKER_FILE": "/run/secrets/broker"
      },
      "artifact": "runtime"
    }
  ],
  "capabilities": [
    "container-runtime"
  ],
  "build": {
    "on": [
      {
        "arg": "BUILD_BASE",
        "module": "mesh-tools",
        "artifact": "build"
      },
      {
        "arg": "RUNTIME_BASE",
        "module": "mesh-tools",
        "artifact": "runtime"
      }
    ],
    "artifacts": [
      {
-        "name": "runtime",
+        "name": "tools",
-        "kind": "image",
+        "kind": "bundle",
-        "from": "Dockerfile"
+        "language": "typescript",
        "entrypoints": [
          "tools/index.js"
        ],
        "loads": [
          "tools/index.js"
        ],
        "env": {
          "MESH_JIRA_TOKEN_FILE": "${dir:state}/token",
          "MESH_JIRA_CONFIG_FILE": "${dir:state}/config.json"
        }
      }
    ]
  }
@@ -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
@@ -0,0 +1,82 @@
 {
  "module": "lab",
  "version": "1",
  "capabilities": [
    "container-runtime",
    "virtualisation"
  ],
  "own-secrets": {
    "broker": "${dir:mesh-state}/broker"
  },
  "resources": [
    {
      "id": "mesh-state",
      "type": "directory",
      "mode": "0700",
      "place": "mesh"
    },
    {
      "id": "state",
      "type": "directory",
      "mode": "0700",
      "place": "."
    },
    {
      "id": "work",
      "type": "directory",
      "path": "/var/lib/mesh-lab-runs",
      "mode": "0700"
    },
    {
      "id": "runtime-env",
      "type": "file",
      "path": "${dir:state}/lab.env",
      "mode": "0600",
      "content": "MESH_LAB_FORGE=${setting:forge}\n"
    },
    {
      "id": "runtime",
      "type": "container",
      "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": [
        "runtime-env"
      ],
      "artifact": "runtime"
    }
  ],
  "build": {
    "on": [
      {
        "arg": "BUILD_BASE",
        "module": "mesh-tools",
        "artifact": "build"
      },
      {
        "arg": "RUNTIME_BASE",
        "module": "mesh-tools",
        "artifact": "runtime"
      }
    ],
    "artifacts": [
      {
        "name": "runtime",
        "kind": "image",
        "from": "Dockerfile"
      }
    ]
  }
 }
@@ -0,0 +1,9 @@
 {
  "name": "@novox/module-lab",
  "version": "0.1.0",
  "description": "lab — the lab, as a module: runs beds against the forge's branches when the mesh asks (novox/hq ADR 0172).",
  "type": "module",
  "private": true,
  "dependencies": { "@novox/mesh-sdk": "^0.1.0" },
  "devDependencies": { "@types/node": "^22.0.0", "typescript": "^5.6.0" }
 }
@@ -0,0 +1,86 @@
 // lab's tools — the lab, as the mesh asks for it (novox/hq ADR 0172). They run on the machine the
 // lab is assigned to, and only there: a bed raises virtual machines on that machine's virtualisation.
 import { spawnSync } from "node:child_process";
 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";
  const forge = (env.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 () => {
        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]);
        const clone = spawnSync("git", ["clone", "--quiet", "--depth", "1", `${forge}/novox/mesh-lab.git`, dir], { encoding: "utf8" });
        if (clone.status !== 0) return { ok: false, output: clone.stderr };
        spawnSync("npm", ["ci", "--no-audit", "--no-fund", "--loglevel=error"], { cwd: dir, encoding: "utf8" });
        const check = spawnSync("node", ["--experimental-strip-types", "src/cli.ts", "check"], { cwd: dir, encoding: "utf8" });
        return { ok: check.status === 0, output: `${check.stdout}${check.stderr}`.trim() };
      },
    },
    {
      name: "lab_run",
      description:
        "Run the lab's beds against branches on the forge: fresh checkouts of every repository the lab builds, " +
        "side by side, then the suite on the named test files. Answers at once with the run's id; lab_status " +
        "and lab_log follow it. One run at a time.",
      input: {
        tests: { type: "string", description: "the bed test files, comma-separated, relative to mesh-lab (e.g. test/integration/mesh.test.ts)" },
        refs: {
          type: "string",
          description: `a JSON object of repository to branch, for any of ${REPOSITORIES.join(", ")}; the rest run main`,
        },
      },
      run: async (args) => {
        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" };
        let refs: Record<string, string> = {};
        if (args.refs) {
          try {
            refs = JSON.parse(String(args.refs)) as Record<string, string>;
          } catch {
            return { started: false, reason: "refs is not a JSON object of repository to branch" };
          }
        }
        const stranger = Object.keys(refs).filter((r) => !REPOSITORIES.includes(r));
        if (stranger.length > 0) return { started: false, reason: `the lab does not build ${stranger.join(", ")}` };
        const busy = running(work);
        if (busy) return { started: false, reason: `${busy.id} is still ${busy.state}; one run at a time`, running: busy };
        return { started: true, run: start(work, forge, tests, refs) };
      },
    },
    {
      name: "lab_status",
      description: "A run's state, the commits it tested and how it ended — or every run, newest first, when no id is given.",
      input: { id: { type: "string", description: "the run's id (optional)" } },
      run: async (args) => {
        if (args.id) return readStatus(work, String(args.id)) ?? { found: false, id: String(args.id) };
        return { runs: listRuns(work).slice(0, 10) };
      },
    },
    {
      name: "lab_log",
      description: "The last lines of a run's log.",
      input: {
        id: { type: "string", description: "the run's id" },
        lines: { type: "number", description: "how many lines from the end (default 200)" },
      },
      run: async (args) => ({ id: String(args.id), log: tail(work, String(args.id), Number(args.lines ?? 200)) }),
    },
    {
      name: "lab_stop",
      description: "Stop a run and everything it started.",
      input: { id: { type: "string", description: "the run's id" } },
      run: async (args) => stop(work, String(args.id)) ?? { found: false, id: String(args.id) },
    },
  ];
 }
 registerModuleTools("lab", (env) => getLabTools(env));
@@ -0,0 +1,175 @@
 // A lab run: fresh checkouts of the named branches, side by side, then the lab's suite on the named
 // beds (novox/hq ADR 0172).
 //
 // **A run is a detached script with its own process group**, so it outlives the tool call that started
 // it and `stop` ends everything it started. It writes what it is doing to a status file beside its log,
 // and that file is the whole of what the tools read back: a runtime that restarts mid-run still answers
 // for it, and says it was lost rather than pretending it is still going.
 import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 /** The repositories a lab run checks out, side by side, as the lab expects its siblings. */
 export const REPOSITORIES = ["mesh-lab", "mesh-controller", "mesh-host", "mesh-catalog", "mesh-tools", "mesh-sdk"];
 export interface RunStatus {
  id: string;
  state: "checking-out" | "building" | "running" | "passed" | "failed" | "stopped" | "lost";
  started: string;
  ended?: string;
  tests: string[];
  refs: Record<string, string>;
  commits?: Record<string, string>;
  exit?: number;
  pid?: number;
 }
 export function runDir(work: string, id: string): string {
  return join(work, id);
 }
 function statusPath(work: string, id: string): string {
  return join(runDir(work, id), "status.json");
 }
 export function readStatus(work: string, id: string): RunStatus | undefined {
  try {
    const s = JSON.parse(readFileSync(statusPath(work, id), "utf8")) as RunStatus;
    // A run whose process is gone while its status still says it is going was lost — the runtime or
    // the machine restarted under it. Said, rather than left reading as running for ever.
    if (!["passed", "failed", "stopped", "lost"].includes(s.state) && s.pid && !alive(s.pid)) {
      s.state = "lost";
    }
    return s;
  } catch {
    return undefined;
  }
 }
 function alive(pid: number): boolean {
  try {
    process.kill(pid, 0);
    return true;
  } catch {
    return false;
  }
 }
 export function listRuns(work: string): RunStatus[] {
  if (!existsSync(work)) return [];
  return readdirSync(work)
    .filter((d) => d.startsWith("run-"))
    .map((id) => readStatus(work, id))
    .filter((s): s is RunStatus => !!s)
    .sort((a, b) => b.started.localeCompare(a.started));
 }
 /** The run still going, if any: one at a time, because two would contend for the same machine. */
 export function running(work: string): RunStatus | undefined {
  return listRuns(work).find((s) => !["passed", "failed", "stopped", "lost"].includes(s.state));
 }
 const shellQuote = (s: string) => `'${s.replace(/'/g, `'\\''`)}'`;
 /**
 * The script one run executes. Every step writes its state first, so a run that dies says where.
 *
 * The environment is the one the lab's README describes for a run against sibling checkouts, pointed
 * at this run's own tree, so what is built and claimed is exactly what was checked out.
 */
 export function script(work: string, id: string, forge: string, tests: string[], refs: Record<string, string>): string {
  const dir = runDir(work, id);
  const setState = (state: string) =>
    `node -e ${shellQuote(
      `const f=${JSON.stringify(join(dir, "status.json"))};const s=JSON.parse(require("fs").readFileSync(f,"utf8"));s.state=${JSON.stringify(state)};require("fs").writeFileSync(f,JSON.stringify(s,null,2))`,
    )}`;
  const clones = REPOSITORIES.map((repo) => {
    const ref = refs[repo] ?? "main";
    return [
      `git clone --quiet --depth 50 --branch ${shellQuote(ref)} ${shellQuote(`${forge}/novox/${repo}.git`)} ${shellQuote(join(dir, repo))}`,
      `echo "${repo} $(git -C ${shellQuote(join(dir, repo))} rev-parse HEAD)" >> ${shellQuote(join(dir, "commits.txt"))}`,
    ].join("\n");
  }).join("\n");
  const bin = join(dir, "bin");
  return `set -euo pipefail
 cd ${shellQuote(dir)}
 ${setState("checking-out")}
 ${clones}
 node -e ${shellQuote(
    `const fs=require("fs");const f=${JSON.stringify(join(dir, "status.json"))};const s=JSON.parse(fs.readFileSync(f,"utf8"));s.commits=Object.fromEntries(fs.readFileSync(${JSON.stringify(join(dir, "commits.txt"))},"utf8").trim().split("\\n").map(l=>l.split(" ")));fs.writeFileSync(f,JSON.stringify(s,null,2))`,
  )}
 ${setState("building")}
 # The @novox scope resolves from the mesh's own package registry on the forge, as the build machine
 # resolves it; nothing else is asked of it.
 printf '%s\n' ${shellQuote(`@novox:registry=${forge}/api/packages/novox/npm/`)} > ${shellQuote(join(dir, ".npmrc"))}
 export NPM_CONFIG_USERCONFIG=${shellQuote(join(dir, ".npmrc"))}
 for repo in mesh-sdk mesh-tools mesh-lab; do (cd ${shellQuote(dir)}/$repo && npm ci --no-audit --no-fund --loglevel=error); done
 (cd ${shellQuote(dir)}/mesh-sdk && npm run build --if-present)
 (cd ${shellQuote(dir)}/mesh-tools && npm run build --if-present)
 mkdir -p ${shellQuote(bin)}
 for p in postgres-provisioner objectstore-provisioner route-proxy; do
  (cd ${shellQuote(dir)}/mesh-controller && CGO_ENABLED=0 go build -o ${shellQuote(bin)}/$p ./examples/$p)
 done
 export MESH_LAB_HOST_BINARY=${shellQuote(join(dir, "mesh-host", "mesh-host"))}
 export MESH_LAB_BUNDLE=${shellQuote(join(dir, "mesh-host", "examples", "foundation-first-node-nats.lock"))}
 export MESH_LAB_MODULES=${shellQuote(join(dir, "mesh-controller", "examples", "modules"))}
 export MESH_LAB_BUILDER=${shellQuote(join(dir, "mesh-controller", "build", "mesh-builder"))}
 export MESH_LAB_BOOTSTRAP_BINARY=${shellQuote(join(dir, "mesh-host", "mesh-bootstrap"))}
 export MESH_LAB_CATALOG=${shellQuote(join(dir, "mesh-catalog", "modules"))}
 export MESH_LAB_PROVISIONER=${shellQuote(join(bin, "postgres-provisioner"))}
 export MESH_LAB_OBJECTSTORE_PROVISIONER=${shellQuote(join(bin, "objectstore-provisioner"))}
 export MESH_LAB_ROUTE_PROXY=${shellQuote(join(bin, "route-proxy"))}
 ${setState("running")}
 cd ${shellQuote(join(dir, "mesh-lab"))}
 node --experimental-strip-types src/cli.ts suite ${tests.map(shellQuote).join(" ")}
 `;
 }
 /** start begins a run and returns at once with its status. */
 export function start(work: string, forge: string, tests: string[], refs: Record<string, string>): RunStatus {
  const id = `run-${new Date().toISOString().replace(/[:.]/g, "-")}`;
  const dir = runDir(work, id);
  mkdirSync(dir, { recursive: true });
  const status: RunStatus = { id, state: "checking-out", started: new Date().toISOString(), tests, refs };
  writeFileSync(statusPath(work, id), JSON.stringify(status, null, 2));
  writeFileSync(join(dir, "run.sh"), script(work, id, forge, tests, refs), { mode: 0o700 });
  // The wrapper records how the run ended, then removes the checkouts and keeps the log and status: a
  // run's tree is its own, and the next run starts from fresh ones (novox/hq ADR 0172).
  const wrapper = `bash ${shellQuote(join(dir, "run.sh"))} > ${shellQuote(join(dir, "run.log"))} 2>&1; code=$?
 node -e ${shellQuote(
    `const f=${JSON.stringify(statusPath(work, id))};const s=JSON.parse(require("fs").readFileSync(f,"utf8"));if(s.state!=="stopped"){s.state=process.argv[1]==="0"?"passed":"failed"};s.exit=Number(process.argv[1]);s.ended=new Date().toISOString();require("fs").writeFileSync(f,JSON.stringify(s,null,2))`,
  )} "$code"
 cd ${shellQuote(dir)} && rm -rf ${REPOSITORIES.map(shellQuote).join(" ")} bin`;
  const child = spawn("bash", ["-c", wrapper], { detached: true, stdio: "ignore" });
  child.unref();
  status.pid = child.pid;
  writeFileSync(statusPath(work, id), JSON.stringify(status, null, 2));
  return status;
 }
 /** stop ends a run and everything it started, by its process group. */
 export function stop(work: string, id: string): RunStatus | undefined {
  const s = readStatus(work, id);
  if (!s || !s.pid) return s;
  if (["passed", "failed", "stopped", "lost"].includes(s.state)) return s;
  s.state = "stopped";
  writeFileSync(statusPath(work, id), JSON.stringify(s, null, 2));
  try {
    process.kill(-s.pid, "SIGTERM");
  } catch {
    // Already gone between the read and the kill.
  }
  return s;
 }
 /** tail is the last lines of a run's log. */
 export function tail(work: string, id: string, lines: number): string {
  try {
    const all = readFileSync(join(runDir(work, id), "run.log"), "utf8").split("\n");
    return all.slice(-Math.max(1, lines)).join("\n");
  } catch {
    return "";
  }
 }
@@ -8,5 +8,5 @@
    "skipLibCheck": true,
    "noEmit": true
  },
-  "include": ["client.ts", "tools/index.ts"]
+  "include": ["tools/index.ts", "tools/runs.ts"]
 }
@@ -1,24 +0,0 @@
 # letta'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/letta
 COPY . .
 RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts \
      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
 FROM ${RUNTIME_BASE}
 COPY --from=build /app/modules/letta/dist /app/modules/letta/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/letta/dist/tools/index.js
@@ -26,8 +26,7 @@
  },
  "own-secrets": {
    "server-password": "${dir:state}/server-password.secret",
-    "openai-api-key": "${dir:state}/openai-api-key.secret",
+    "openai-api-key": "${dir:state}/openai-api-key.secret"
    "broker": "${dir:mesh-state}/broker"
  },
  "listens": [
    {
@@ -84,45 +83,24 @@
      "mode": "0600",
      "content": "{\n  \"password\": \"${secret:server-password}\"\n}\n",
      "merge": "json"
    },
    {
      "id": "runtime",
      "type": "container",
      "name": "mesh-letta",
      "network": "letta",
      "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_LETTA_URL": "http://letta:8283",
        "MESH_LETTA_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": "runtime",
+        "name": "tools",
-        "kind": "image",
+        "kind": "bundle",
-        "from": "Dockerfile"
+        "language": "typescript",
        "entrypoints": [
          "tools/index.js"
        ],
        "loads": [
          "tools/index.js"
        ],
        "env": {
          "MESH_LETTA_URL": "http://127.0.0.1:${port:8283}",
          "MESH_LETTA_CONFIG_FILE": "${dir:mesh-state}/config.json"
        }
      }
    ]
  }
@@ -462,7 +462,8 @@
      ],
      "dns": [
        "192.168.203.254"
-      ]
+      ],
      "logging": "journald"
    },
    {
      "id": "runtime-config",
@@ -561,5 +562,12 @@
  },
  "grants": {
    "smtp": "${dir:grants}"
-  }
+  },
  "jails": [
    {
      "name": "mailu-front",
      "failregex": "^.*(?:imap|pop3|submission|managesieve)-login: .*\\(auth failed, \\d+ attempts(?: in \\d+ secs)?\\):.*rip=<HOST>(?:,|$)",
      "jail": "backend = systemd\njournalmatch = CONTAINER_NAME=mailu-front\nport = smtp,submission,submissions,imap,imaps,pop3,pop3s\nmaxretry = 3\nfindtime = 1d\nbantime = 1d"
    }
  ]
 }
@@ -1,13 +0,0 @@
 # The console (novox/hq ADR 0152, design 34): the mesh's tools for whoever is on a machine, served
 # over MCP on that machine's loopback.
 #
 # **Nothing is compiled here.** The console is the tool runtime's own client — `mesh serve` — which
 # the runtime image already carries beside the runtime it runs modules with. This recipe changes the
 # program the image starts and nothing else, so the console is exactly the client a person can run by
 # hand, started by the mesh instead, on the credential the mesh sealed to the machine.
 #
 # One base, named rather than pinned: the mesh answers with the copy it holds (novox/hq issue 044).
 ARG RUNTIME_BASE
 FROM ${RUNTIME_BASE}
 ENTRYPOINT ["node", "dist/mesh.js"]
@@ -1,38 +0,0 @@
 # mesh-console
 The mesh's tools, on the machine a person sits at, served by a module the mesh assigned there
 (novox/hq [ADR 0152](https://git.novox.be/novox/hq), design 34).
 Assign it to a machine and an agent on that machine has the mesh's tools at
 `http://127.0.0.1:<port>/mcp` — MCP over HTTP, `initialize`, `tools/list`, `tools/call`. A person at
 a terminal reaches the same endpoint with `mesh tools --console http://127.0.0.1:<port>` and
 `mesh call <module>.<tool> --console …`, with no credential of their own: the console holds it.
 ## What it is
 The tool runtime's own client, `mesh serve`, started by the mesh on the credential it sealed to the
 machine for `<node>.mesh-console`. The manifest says three things nothing else in the catalogue says
 together:
 - `invokes: ["*"]` — it calls every tool on the mesh, and the bus grants exactly that publish side;
 - a listener `from: machine` — loopback only, and the filter opens nothing for it;
 - no `emits`, no `consumes`, no `tools` — nothing on the bus can address it.
 **Loopback is the authority boundary.** Whoever can connect is on the machine, and whoever is on the
 machine is the account that owns the mesh there (ADR 0034, ADR 0144). There is no token and no login,
 and `mesh serve` refuses to bind anything but a loopback address.
 ## What it lists
 What the running modules answer: every tool runtime serves a `tools` verb for its module, and the
 console asks the catalogue which modules the mesh holds and each module what it serves. A module that
 did not answer — not assigned, not up, or built before the runtime answered `tools` — is named in the
 list's `_meta.notAnswering` and can still be called by `<module>.<tool>`.
 The mesh's own verbs (`status`, `push`, `assign`) are the `mesh-controller` seat's tools under
 ADR 0132 and are not served on the bus yet; they appear here when they are.
 ## Port
 The manifest declares port 4270 and the mesh assigns the machine port as it does for any listener;
 the console binds `127.0.0.1:${port:4270}`. `node show <machine>` says which port a machine was given.
@@ -1,64 +0,0 @@
 {
  "module": "mesh-console",
  "version": "1",
  "slug": "console",
  "capabilities": [
    "container-runtime"
  ],
  "invokes": [
    "*"
  ],
  "own-secrets": {
    "broker": "${dir:mesh-state}/broker"
  },
  "listens": [
    {
      "name": "mcp",
      "port": 4270,
      "protocol": "tcp",
      "from": "machine",
      "why": "the mesh's tools for whoever is on this machine, over MCP on loopback; the machine's login is the authority (novox/hq ADR 0152)"
    }
  ],
  "resources": [
    {
      "id": "mesh-state",
      "type": "directory",
      "mode": "0700",
      "place": "mesh"
    },
    {
      "id": "server",
      "type": "container",
      "name": "mesh-console",
      "network": "host",
      "args": [
        "serve"
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
        "MESH_CONSOLE_LISTEN": "127.0.0.1:${port:4270}"
      },
      "volumes": [
        "${dir:mesh-state}/broker:/run/secrets/broker:ro"
      ],
      "artifact": "runtime"
    }
  ],
  "build": {
    "on": [
      {
        "arg": "RUNTIME_BASE",
        "module": "mesh-tools",
        "artifact": "runtime"
      }
    ],
    "artifacts": [
      {
        "name": "runtime",
        "kind": "image",
        "from": "Dockerfile"
      }
    ]
  }
 }
@@ -1,22 +1,269 @@
-// The firewall's own code, in the module (novox/hq ADR 0039). The mesh computes this node's whole
+// The packet filter's own code, in the module (novox/hq ADR 0039). The mesh computes this node's
-// rule set from every module's `listens` and writes it to /etc/nftables.conf (novox/hq ADR 0045);
+// rule set from every module's `listens` and writes it to the filter file (ADR 0045); the module
-// the module loads it through its own mesh-filter unit, reloaded whenever the rules change, whose
+// loads it through its own unit. This code reads the filter back as the machine enforces it, reloads
-// stop deletes only the mesh's table and never flushes the whole ruleset (novox/hq ADR 0100). This
+// the mesh's own table, and removes one thing the mesh did not write when the operator names it
-// code exists only to read back what is actually enforced — the enforcement itself is declarative.
+// (ADR 0168, ADR 0170) — the seat's three verbs, over the machine's own tools. Root is the module's
 // concern (ADR 0175 §4): the runtime loading this bundle runs as the operator's account (to-be 38
 // WP4), so the commands go through sudo without a prompt where the account is not root.
 import { execFile } from "node:child_process";
 import { accessSync, constants } from "node:fs";
 import { delimiter, join } from "node:path";
 import { promisify } from "node:util";
-const run = promisify(execFile);
+const execFileP = promisify(execFile);
 /** A command runner, so the acts can be tested without a packet filter. */
 export type Runner = (cmd: string, args: string[]) => Promise<string>;
 /** Where the mesh writes this node's filter: the path the manifest's `filtering.into` names. A
 *  bundle has no environment of its own (to-be 38 WP4), so the path is said here once, and a test
 *  holds it to the manifest's. */
 export const FILTER_FILE = "/etc/nftables.conf";
 /** The command as it is run: as given when this process is root, else through sudo without a
 *  prompt. The packet filter answers only to root, listing included. */
 export function escalated(cmd: string, args: string[], uid: number | undefined = process.getuid?.()): [string, string[]] {
  if (uid === 0) return [cmd, args];
  return ["sudo", ["-n", cmd, ...args]];
 }
 /** Whether a tool is on this machine: an executable of that name on the path, or where the
 *  system keeps its administration. Asked before a tool is run, so "not here" and "refused" are
 *  never confused — the former is a fact to work around, the latter an error to say. */
 export function installed(tool: string, path: string = process.env.PATH ?? ""): boolean {
  const dirs = [...path.split(delimiter), "/usr/sbin", "/sbin", "/usr/bin"].filter((d) => d !== "");
  return dirs.some((dir) => {
    try {
      accessSync(join(dir, tool), constants.X_OK);
      return true;
    } catch {
      return false;
    }
  });
 }
 export const execRunner: Runner = async (cmd, args) => {
  const [program, argv] = escalated(cmd, args);
  try {
    const { stdout } = await execFileP(program, argv, { maxBuffer: 16 * 1024 * 1024 });
    return stdout;
  } catch (err) {
    // What failed is named by how it failed, not by prose: sudo missing is a spawn error; sudo
    // refusing speaks on its own stderr line; anything else is the command's own failure.
    const e = err as { code?: string | number; stderr?: string };
    if (program === "sudo") {
      if (e.code === "ENOENT") {
        throw new Error(`${cmd} needs root, and sudo is not installed here for the runtime's account to escalate with`);
      }
      const stderr = String(e.stderr ?? "").trim();
      if (/^sudo: .*command not found/m.test(stderr)) throw new Error(`${cmd} is not installed here`);
      if (/^sudo:/m.test(stderr)) {
        throw new Error(`${cmd} needs root and the runtime's account may not run it without a prompt: ${stderr}`);
      }
    }
    throw err;
  }
 };
 /** The mesh's own tables, which `remove` never touches. */
 const MESH_TABLES = new Set(["inet mesh", "inet mesh_guard"]);
 /** The tables iptables-nft manages, spoken through iptables rather than nft. */
 const IPTABLES_TABLES = new Set(["filter", "nat", "raw", "mangle", "security"]);
 /** The chains the kernel has built in; flushing one is the owner's act, not an operator's removal. */
 const BUILT_IN = new Set(["INPUT", "FORWARD", "OUTPUT", "PREROUTING", "POSTROUTING"]);
 /** The chain the container runtime leaves for an administrator, which is emptied, never deleted. */
 const USER_CHAIN = "DOCKER-USER";
 export interface Removal {
  where: string;
  did: string[];
 }
 export class FirewallClient {
-  static fromEnv(_env: NodeJS.ProcessEnv = process.env): FirewallClient {
+  private readonly run: Runner;
  private readonly filterFile: string;
  private readonly have: (tool: string) => boolean;
  constructor(run: Runner = execRunner, filterFile: string = FILTER_FILE, have: (tool: string) => boolean = installed) {
    this.run = run;
    this.filterFile = filterFile;
    this.have = have;
  }
  /** The filter as this machine has it: its own tools, the mesh's file. */
  static onThisMachine(): FirewallClient {
    return new FirewallClient();
  }
-  /** The mesh's live table — exactly what is dropping and accepting on this node right now. */
+  /** The mesh's live table — exactly what the mesh's own filter is dropping and accepting. */
  async ruleset(): Promise<string> {
-    const { stdout } = await run("nft", ["list", "table", "inet", "mesh"]);
+    return this.run("nft", ["list", "table", "inet", "mesh"]);
-    return stdout;
+  }
  /** The packet filter as the machine enforces it: nftables whole or narrowed, and the legacy filter's
   *  listings where the tools exist. */
  async rules(table?: string, chain?: string): Promise<{ nftables: string; legacy: Record<string, string> }> {
    let nftables: string;
    if (table && chain) {
      const [family, name] = splitTable(table);
      nftables = await this.run("nft", ["list", "chain", family, name, chain]);
    } else if (table) {
      const [family, name] = splitTable(table);
      nftables = await this.run("nft", ["list", "table", family, name]);
    } else {
      nftables = await this.run("nft", ["list", "ruleset"]);
    }
    const legacy: Record<string, string> = {};
    if (!table) {
      for (const tool of ["iptables-legacy", "ip6tables-legacy"]) {
        if (!this.have(tool)) continue; // no legacy tool, nothing to list
        try {
          const out = await this.run(tool, ["-S"]);
          if (out.trim()) legacy[tool] = out;
        } catch (err) {
          // The tool is here and would not answer: said, not swallowed — a listing that silently
          // leaves out a predecessor's rules reads as "none".
          legacy[tool] = `error: ${err instanceof Error ? err.message : String(err)}`;
        }
      }
    }
    return { nftables, legacy };
  }
  /** Load the mesh's own filter again from the file the mesh writes, and answer with the table. */
  async reload(): Promise<{ loaded: string; table: string }> {
    await this.run("nft", ["-f", this.filterFile]);
    return { loaded: this.filterFile, table: await this.ruleset() };
  }
  /** Whether the found front end is in force, whose chains `remove` leaves alone. Absent, it is
   *  not; present and not answering, nothing is removed on a guess. */
  private async ufwActive(): Promise<boolean> {
    if (!this.have("ufw")) return false;
    let out: string;
    try {
      out = await this.run("ufw", ["status"]);
    } catch (err) {
      throw new Error(`cannot tell whether the found firewall is in force, so nothing of its is removed: ${err instanceof Error ? err.message : String(err)}`);
    }
    return /^Status:\s*active/m.test(out);
  }
  /** Remove one rule set the mesh did not write, named as the host reports it (ADR 0168). */
  async remove(where: string): Promise<Removal> {
    const did: string[] = [];
    const legacy = /^chain (\S+) \((iptables-legacy|ip6tables-legacy|iptables|ip6tables)\)$/.exec(where.trim());
    const nft = /^table (\S+) (\S+), chain (\S+)$/.exec(where.trim());
    if (legacy) {
      const [, chain, tool] = legacy;
      await this.refuseOwned(chain, "ip", "filter");
      await this.removeChainWith(tool, undefined, chain, did);
      return { where, did };
    }
    if (nft) {
      const [, family, name, chain] = nft;
      const table = `${family} ${name}`;
      if (MESH_TABLES.has(table)) throw new Error(`${where} is the mesh's own table; it is not removed, it is composed`);
      await this.refuseOwned(chain, family, name);
      if ((family === "ip" || family === "ip6") && IPTABLES_TABLES.has(name)) {
        const tool = family === "ip6" ? "ip6tables" : "iptables";
        await this.removeChainWith(tool, name, chain, did);
        return { where, did };
      }
      // A table of the machine's own: a chain of it goes, and the table with it when nothing is left.
      const listing = await this.run("nft", ["list", "table", family, name]);
      const base = new RegExp(`chain ${escape(chain)} \\{[^}]*type \\S+ hook`).test(listing);
      for (const from of chainsJumpingTo(listing, chain)) {
        await this.deleteNftRules(family, name, from, chain, did);
      }
      if (base) {
        await this.run("nft", ["flush", "chain", family, name, chain]);
        did.push(`nft flush chain ${family} ${name} ${chain}`);
      } else {
        await this.run("nft", ["delete", "chain", family, name, chain]);
        did.push(`nft delete chain ${family} ${name} ${chain}`);
      }
      return { where, did };
    }
    throw new Error(`${JSON.stringify(where)} is not a rule set as the host reports one: ` +
      "`chain X (iptables-legacy)` or `table <family> <name>, chain X`");
  }
  private async refuseOwned(chain: string, family: string, table: string): Promise<void> {
    if (chain !== USER_CHAIN && chain.startsWith("DOCKER")) {
      throw new Error(`chain ${chain} is the container runtime's own; it is left`);
    }
    if (BUILT_IN.has(chain)) {
      throw new Error(`chain ${chain} is built in; its policy is its owner's and it is not flushed`);
    }
    if (chain.startsWith("ufw") && (await this.ufwActive())) {
      throw new Error(`chain ${chain} belongs to the found firewall, which is in force; converge retires it`);
    }
    void family; void table;
  }
  /** Through an iptables tool: the user chain is emptied back to its one return; another chain loses
   *  the jumps into it, is flushed and deleted. */
  private async removeChainWith(tool: string, table: string | undefined, chain: string, did: string[]): Promise<void> {
    const t = table && table !== "filter" ? ["-t", table] : [];
    if (chain === USER_CHAIN) {
      await this.run(tool, [...t, "-F", chain]);
      await this.run(tool, [...t, "-A", chain, "-j", "RETURN"]);
      did.push(`${tool} ${[...t, "-F", chain].join(" ")}`, `${tool} ${[...t, "-A", chain, "-j", "RETURN"].join(" ")}`);
      return;
    }
    const listing = await this.run(tool, [...t, "-S"]);
    for (const line of listing.split("\n")) {
      const fields = line.trim().split(/\s+/);
      if (fields[0] !== "-A") continue;
      const j = fields.indexOf("-j");
      const g = fields.indexOf("-g");
      const target = j >= 0 ? fields[j + 1] : g >= 0 ? fields[g + 1] : "";
      if (target !== chain) continue;
      const args = [...t, "-D", ...fields.slice(1)];
      await this.run(tool, args);
      did.push(`${tool} ${args.join(" ")}`);
    }
    await this.run(tool, [...t, "-F", chain]);
    await this.run(tool, [...t, "-X", chain]);
    did.push(`${tool} ${[...t, "-F", chain].join(" ")}`, `${tool} ${[...t, "-X", chain].join(" ")}`);
  }
  private async deleteNftRules(family: string, name: string, from: string, target: string, did: string[]): Promise<void> {
    const listing = await this.run("nft", ["-a", "list", "chain", family, name, from]);
    for (const line of listing.split("\n")) {
      if (!new RegExp(`\\b(jump|goto) ${escape(target)}\\b`).test(line)) continue;
      const handle = /# handle (\d+)/.exec(line)?.[1];
      if (!handle) continue;
      await this.run("nft", ["delete", "rule", family, name, from, "handle", handle]);
      did.push(`nft delete rule ${family} ${name} ${from} handle ${handle}`);
    }
  }
 }
 function splitTable(table: string): [string, string] {
  const parts = table.trim().split(/\s+/);
  if (parts.length !== 2) throw new Error(`a table is \`family name\`, not ${JSON.stringify(table)}`);
  return [parts[0], parts[1]];
 }
 /** Which chains of a listed table jump or go to the named one. */
 export function chainsJumpingTo(listing: string, target: string): string[] {
  const out: string[] = [];
  let chain = "";
  for (const raw of listing.split("\n")) {
    const line = raw.trim();
    const head = /^chain (\S+) \{/.exec(line);
    if (head) { chain = head[1]; continue; }
    if (line === "}") { chain = ""; continue; }
    if (chain && chain !== target && new RegExp(`\\b(jump|goto) ${escape(target)}\\b`).test(line) && !out.includes(chain)) {
      out.push(chain);
    }
  }
  return out;
 }
 function escape(s: string): string {
  return s.replace(/[.*+?^${}()|[\]\\-]/g, "\\$&");
 }
@@ -7,7 +7,12 @@
  "claims": [
    {
      "name": "node-packet-filter",
-      "scope": "node"
+      "scope": "node",
      "serves": [
        "rules",
        "reload",
        "remove"
      ]
    }
  ],
  "filtering": {
@@ -19,6 +24,11 @@
      "type": "package",
      "package": "nftables"
    },
    {
      "id": "legacy-tools",
      "type": "package",
      "package": "iptables"
    },
    {
      "id": "unit",
      "type": "file",
@@ -30,7 +40,7 @@
      "id": "stock-unit-stop",
      "type": "file",
      "path": "/etc/systemd/system/nftables.service.d/mesh.conf",
-      "content": "# The mesh: stopping the stock unit deletes only the mesh's table, never the whole ruleset\n# (novox/hq ADR 0100) \u2014 a flush would take the container runtime's rules and any firewall with it.\n[Service]\nExecStop=\nExecStop=nft delete table inet mesh\n",
+      "content": "# The mesh: stopping the stock unit deletes only the mesh's table, never the whole ruleset\n# (novox/hq ADR 0100) — a flush would take the container runtime's rules and any firewall with it.\n[Service]\nExecStop=\nExecStop=nft delete table inet mesh\n",
      "mode": "0644"
    },
    {
@@ -46,6 +56,27 @@
      "reload-on": [
        "filtering"
      ]
    },
    {
      "id": "front-end",
      "type": "package",
      "package": "ufw",
      "absent": true
    }
-  ]
+  ],
  "tools": [
    "firewall_rules"
  ],
  "build": {
    "artifacts": [
      {
        "name": "tools",
        "kind": "bundle",
        "language": "typescript",
        "entrypoints": [
          "tools/index.js"
        ]
      }
    ]
  }
 }
@@ -1,11 +1,15 @@
 {
-  "name": "@novox/module-firewall",
+  "name": "@novox/module-nftables",
  "version": "0.1.0",
-  "description": "firewall — applies the mesh-computed packet filter (ADR 0045). Its diagnostic tool lives here.
+  "description": "nftables — loads the mesh's packet filter and holds the node-packet-filter seat: its verbs rules, reload and remove (novox/hq ADR 0045, ADR 0170).",
  "type": "module",
  "private": true,
  "scripts": {
    "build": "tsc client.ts tools/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --rootDir . --outDir dist",
    "test": "node --test --experimental-strip-types 'test/*.test.ts'"
  },
  "dependencies": {
-    "@novox/mesh-sdk": "^0.1.0"
+    "@novox/mesh-sdk": "^0.1.1"
  },
  "devDependencies": {
    "@types/node": "^22.0.0",
@@ -0,0 +1,108 @@
 // `remove` acts on one rule set the mesh did not write, named as the host reports it (novox/hq ADR
 // 0168, 0169), over the shapes two machines of the first mesh reported live: a predecessor's chain in
 // the legacy filter, the runtime's user chain in the IPv6 legacy filter, a leftover front-end chain,
 // and the same in an iptables-nft table. It refuses what is not the operator's to remove.
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { FILTER_FILE, FirewallClient, chainsJumpingTo, escalated, installed, type Runner } from "../client.ts";
 const legacy = [
  "-P INPUT ACCEPT", "-P FORWARD DROP", "-P OUTPUT ACCEPT",
  "-N DOCKER", "-N DOCKER-USER", "-N HAL-MESH-ONLY",
  "-A FORWARD -j DOCKER-USER",
  "-A DOCKER-USER -i enp6s0 -p tcp -m conntrack --ctstate NEW -j HAL-MESH-ONLY",
  "-A HAL-MESH-ONLY -m conntrack --ctorigdstport 80 -j RETURN",
  "-A HAL-MESH-ONLY -m comment --comment \"HAL: not public -> mesh only\" -j DROP",
 ].join("\n") + "\n";
 function fake(ufwActive = false): { run: Runner; asked: string[] } {
  const asked: string[] = [];
  const run: Runner = async (cmd, args) => {
    asked.push([cmd, ...args].join(" "));
    if (cmd === "ufw") return ufwActive ? "Status: active\n" : "Status: inactive\n";
    if (args.join(" ") === "-S") return legacy;
    if (cmd === "nft" && args[0] === "list" && args[1] === "table") {
      return "table ip6 own {\n\tchain forward {\n\t\ttype filter hook forward priority filter; policy accept;\n\t\tjump deny\n\t}\n\tchain deny {\n\t\tdrop\n\t}\n}\n";
    }
    if (cmd === "nft" && args[0] === "-a") {
      return "table ip6 own {\n\tchain forward {\n\t\ttype filter hook forward priority filter; policy accept;\n\t\tjump deny # handle 7\n\t}\n}\n";
    }
    return "";
  };
  return { run, asked };
 }
 test("a predecessor's chain in the legacy filter loses its jumps, is flushed and deleted", async () => {
  const f = fake();
  const out = await new FirewallClient(f.run, undefined, () => true).remove("chain HAL-MESH-ONLY (iptables-legacy)");
  assert.deepEqual(out.did, [
    "iptables-legacy -D DOCKER-USER -i enp6s0 -p tcp -m conntrack --ctstate NEW -j HAL-MESH-ONLY",
    "iptables-legacy -F HAL-MESH-ONLY",
    "iptables-legacy -X HAL-MESH-ONLY",
  ]);
 });
 test("the runtime's user chain is emptied back to its one return, never deleted", async () => {
  const f = fake();
  const out = await new FirewallClient(f.run, undefined, () => true).remove("chain DOCKER-USER (ip6tables-legacy)");
  assert.deepEqual(out.did, ["ip6tables-legacy -F DOCKER-USER", "ip6tables-legacy -A DOCKER-USER -j RETURN"]);
  const nft = await new FirewallClient(fake().run, undefined, () => true).remove("table ip6 filter, chain DOCKER-USER");
  assert.deepEqual(nft.did, ["ip6tables -F DOCKER-USER", "ip6tables -A DOCKER-USER -j RETURN"]);
 });
 test("a chain of the machine's own nftables table goes with the rules that reach it", async () => {
  const f = fake();
  const out = await new FirewallClient(f.run, undefined, () => true).remove("table ip6 own, chain deny");
  assert.deepEqual(out.did, ["nft delete rule ip6 own forward handle 7", "nft delete chain ip6 own deny"]);
 });
 test("what is not the operator's to remove is refused by name", async () => {
  const c = new FirewallClient(fake(true).run, undefined, () => true);
  await assert.rejects(c.remove("table inet mesh, chain forward"), /the mesh's own table/);
  await assert.rejects(c.remove("chain DOCKER (iptables-legacy)"), /container runtime's own/);
  await assert.rejects(c.remove("chain FORWARD (iptables-legacy)"), /built in/);
  await assert.rejects(c.remove("chain ufw6-docker-logging-deny (ip6tables-legacy)"), /found firewall, which is in force/);
  await assert.rejects(c.remove("something else"), /not a rule set as the host reports one/);
  // Retired, a front end's leftover is nobody's and goes.
  const retired = await new FirewallClient(fake(false).run, undefined, () => true).remove("chain ufw6-docker-logging-deny (ip6tables-legacy)");
  assert.ok(retired.did.includes("ip6tables-legacy -X ufw6-docker-logging-deny"));
 });
 test("which chains jump to a target is read from a listing", () => {
  const listing = "table ip6 own {\n\tchain a {\n\t\tjump deny\n\t}\n\tchain b {\n\t\tgoto deny\n\t}\n\tchain deny {\n\t\tdrop\n\t}\n}\n";
  assert.deepEqual(chainsJumpingTo(listing, "deny"), ["a", "b"]);
 });
 test("the filter's commands run as given by root and through sudo without a prompt by anyone else", () => {
  assert.deepEqual(escalated("nft", ["list", "ruleset"], 0), ["nft", ["list", "ruleset"]]);
  assert.deepEqual(escalated("nft", ["-f", "/etc/nftables.conf"], 1000), ["sudo", ["-n", "nft", "-f", "/etc/nftables.conf"]]);
  assert.deepEqual(escalated("iptables-legacy", ["-S"], undefined), ["sudo", ["-n", "iptables-legacy", "-S"]]);
 });
 test("the filter file is the one the manifest's filtering names", () => {
  const manifest = JSON.parse(readFileSync(new URL("../module.json", import.meta.url), "utf8")) as { filtering: { into: string } };
  assert.equal(FILTER_FILE, manifest.filtering.into);
 });
 test("a tool is installed when an executable of its name is on the path, and not otherwise", () => {
  assert.equal(installed("sh"), true);
  assert.equal(installed("no-such-tool-of-the-mesh"), false);
 });
 test("a found firewall that is absent guards nothing; one that will not answer stops the removal", async () => {
  // Absent: its leftover chain is nobody's and goes, without asking it.
  const absent = fake(true);
  const out = await new FirewallClient(absent.run, undefined, () => false).remove("chain ufw6-docker-logging-deny (ip6tables-legacy)");
  assert.ok(out.did.includes("ip6tables-legacy -X ufw6-docker-logging-deny"));
  assert.ok(!absent.asked.some((a) => a.startsWith("ufw ")));
  // Present and failing — refused by sudo, say — nothing is removed on a guess.
  const refusing: Runner = async (cmd, args) => {
    if (cmd === "ufw") throw new Error("ufw needs root and the runtime's account may not run it without a prompt");
    return fake().run(cmd, args);
  };
  await assert.rejects(
    new FirewallClient(refusing, undefined, () => true).remove("chain ufw6-docker-logging-deny (ip6tables-legacy)"),
    /cannot tell whether the found firewall is in force/,
  );
 });
@@ -1,19 +1,51 @@
-// firewall's tools — one, and the useful one: what is actually enforced. The rules are the mesh's,
+// The packet filter's tools: the node-packet-filter seat's three verbs — what the machine enforces,
-// computed from every module's listens; this reads the live table so a declared scope can be checked
+// reload the mesh's own, remove one thing the mesh did not write — and the module's own reading of
-// against what the packet filter is really doing.
+// the mesh's table (novox/hq ADR 0045, ADR 0168, ADR 0170).
 import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
 import { FirewallClient } from "../client.js";
 export function getSeatVerbs(firewall: FirewallClient): ToolDefinition[] {
  return [
    {
      name: "rules",
      description:
        "The packet filter as this machine enforces it now: the nftables ruleset and, where the tool exists, the legacy filter's listings. Narrowed to one table or chain when asked.",
      input: {
        table: { type: "string", description: "one nftables table, as `family name` (optional)" },
        chain: { type: "string", description: "one chain of that table (optional)" },
      },
      run: async (args) => firewall.rules(args.table ? String(args.table) : undefined, args.chain ? String(args.chain) : undefined),
    },
    {
      name: "reload",
      description: "Load the mesh's own filter again from the file the mesh writes, and answer with the mesh's table as loaded.",
      input: {},
      run: async () => firewall.reload(),
    },
    {
      name: "remove",
      description:
        "Remove one rule set the mesh did not write, named exactly as `node show` lists it: `chain X (iptables-legacy)` or `table ip6 filter, chain DOCKER-USER`. " +
        "Refuses the mesh's tables, the runtime's own chains, a built-in chain and an active found firewall's chains. An operator's act, by name, never a flush.",
      input: { where: { type: "string", description: "the rule set, as `node show` lists it" } },
      run: async (args) => firewall.remove(String(args.where ?? "")),
    },
  ];
 }
 export function getFirewallTools(firewall: FirewallClient): ToolDefinition[] {
  return [
    {
      name: "firewall_rules",
-      description: "The mesh's live nftables rules on this node — what is actually accepting and dropping.",
+      description: "The mesh's live nftables table on this node — what the mesh's own filter is accepting and dropping.",
      input: {},
      run: async () => ({ ruleset: await firewall.ruleset() }),
    },
  ];
 }
-registerModuleTools("firewall", () => getFirewallTools(FirewallClient.fromEnv()));
+const firewall = FirewallClient.onThisMachine();
 // The seat's verbs under the seat's name: the runtime serves them on the seat's subjects where this
 // module holds it (ADR 0159, 0160). The module's own under its own.
 registerModuleTools("node-packet-filter", () => getSeatVerbs(firewall));
 registerModuleTools("nftables", () => getFirewallTools(firewall));
@@ -1,30 +0,0 @@
 # portainer'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/portainer
 COPY . .
 RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts \
      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
 FROM ${RUNTIME_BASE}
 COPY --from=build /app/modules/portainer/dist /app/modules/portainer/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/portainer/dist/tools/index.js
@@ -1,107 +0,0 @@
 // The Portainer API client — portainer's own code, living in the module (novox/hq ADR 0039).
 // portainer is tools-only: its "events" would really be the underlying containers' lifecycle,
 // which the host owns and emits — so this module reads Portainer's own resources (endpoints,
 // stacks, containers) and exposes them, and stops there.
 import { readFileSync } from "node:fs";
 export interface PortainerEndpoint {
  id: number;
  name: string;
  type: number;
  url: string;
  status: number;
 }
 export interface PortainerStack {
  id: number;
  name: string;
  type: number;
  endpointId: number;
  status: number;
 }
 export interface PortainerContainer {
  id: string;
  names: string[];
  image: string;
  state: string;
  status: string;
 }
 /** The settings-merged config the mesh delivers (novox/hq ADR 0046): { url, apiKey, token, password, user, ... }. */
 function meshConfig(file?: string): Record<string, string> {
  if (!file) return {};
  try { return JSON.parse(readFileSync(file, "utf8")) as Record<string, string>; }
  catch { return {}; }
 }
 export class PortainerClient {
  readonly baseUrl: string;
  constructor(
    url: string,
    private readonly token: string,
  ) {
    this.baseUrl = url.replace(/\/+$/, "");
  }
  /**
   * Build from the module's resolved environment. The URL is MESH_PORTAINER_URL (or the local
   * dashboard port) and the API token is MESH_PORTAINER_TOKEN — an access token minted in
   * Portainer, sent as X-API-Key. Throws when no token is configured, so a misconfigured module
   * exposes nothing rather than calling Portainer unauthenticated.
   */
  static fromEnv(env: NodeJS.ProcessEnv = process.env): PortainerClient {
    const cfg = meshConfig(env.MESH_PORTAINER_CONFIG_FILE);
    const url = cfg.url ?? env.MESH_PORTAINER_URL ?? `https://127.0.0.1:${env.PORTAINER_PORT ?? "9443"}`;
    const token = cfg.token ?? env.MESH_PORTAINER_TOKEN;
    if (!token) throw new Error("no Portainer token — set MESH_PORTAINER_TOKEN");
    return new PortainerClient(url, token);
  }
  private async get<T>(path: string): Promise<T> {
    const res = await fetch(`${this.baseUrl}${path}`, { headers: { "X-API-Key": this.token } });
    if (!res.ok) throw new Error(`Portainer ${path}: ${res.status} ${await res.text()}`);
    return res.json() as Promise<T>;
  }
  /** The environments (endpoints) Portainer manages — each a Docker host or cluster it talks to. */
  async listEndpoints(): Promise<PortainerEndpoint[]> {
    const raw = await this.get<any[]>("/api/endpoints");
    return (raw ?? []).map((e) => ({
      id: e.Id,
      name: e.Name,
      type: e.Type,
      url: e.URL,
      status: e.Status,
    }));
  }
  /** The stacks (compose/swarm deployments) Portainer knows about. */
  async listStacks(): Promise<PortainerStack[]> {
    const raw = await this.get<any[]>("/api/stacks");
    return (raw ?? []).map((s) => ({
      id: s.Id,
      name: s.Name,
      type: s.Type,
      endpointId: s.EndpointId,
      status: s.Status,
    }));
  }
  /**
   * The containers on one endpoint, read through Portainer's Docker API proxy. Includes stopped
   * containers, so the caller sees the whole picture rather than only what is running.
   */
  async listContainers(endpointId: number): Promise<PortainerContainer[]> {
    const raw = await this.get<any[]>(`/api/endpoints/${endpointId}/docker/containers/json?all=1`);
    return (raw ?? []).map((c) => ({
      id: c.Id,
      names: c.Names ?? [],
      image: c.Image,
      state: c.State,
      status: c.Status,
    }));
  }
 }
@@ -1,114 +0,0 @@
 {
  "module": "portainer",
  "version": "1",
  "slug": "portain",
  "capabilities": [
    "container-runtime"
  ],
  "listens": [
    {
      "name": "web",
      "port": 9000,
      "protocol": "tcp",
      "from": "mesh",
      "why": "the dashboard over http; its public name is a route grant and the proxy reaches it here"
    },
    {
      "name": "web-tls",
      "port": 9443,
      "protocol": "tcp",
      "from": "mesh",
      "why": "the same dashboard over its own tls; the runtime sidecar talks to it here"
    }
  ],
  "resources": [
    {
      "id": "mesh-state",
      "type": "directory",
      "mode": "0700",
      "place": "mesh"
    },
    {
      "id": "data",
      "type": "directory",
      "mode": "0700"
    },
    {
      "id": "server",
      "type": "container",
      "name": "portainer",
      "image": "portainer/portainer-ce@sha256:4d616db18cfeb5dd41a69c0958bc825c84483ea9cde1106eb82a5d26f3bd8b0e",
      "ports": [
        "9000",
        "9443"
      ],
      "volumes": [
        "${dir:data}:/data",
        "/var/run/docker.sock:/var/run/docker.sock"
      ]
    },
    {
      "id": "runtime-config",
      "type": "file",
      "path": "${dir:mesh-state}/config.json",
      "mode": "0600",
      "content": "{}\n",
      "merge": "json"
    },
    {
      "id": "runtime",
      "type": "container",
      "name": "mesh-portainer",
      "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_PORTAINER_URL": "https://127.0.0.1:9443",
        "MESH_PORTAINER_CONFIG_FILE": "/run/config/config.json"
      },
      "restart-on": [
        "runtime-config"
      ],
      "artifact": "runtime"
    }
  ],
  "own-secrets": {
    "broker": "${dir:mesh-state}/broker"
  },
  "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"
      }
    ]
  },
  "requires": [
    "route"
  ],
  "contributes": {
    "route": {
      "label": "portainer",
      "endpoint": "web"
    }
  },
  "binds": {
    "route": "${dir:mesh-state}/route.json"
  }
 }
@@ -1,14 +0,0 @@
 {
  "name": "@novox/module-portainer",
  "version": "0.1.0",
  "description": "portainer — container management UI. Its API client and tools live here (novox/hq ADR 0039).",
  "type": "module",
  "private": true,
  "dependencies": {
    "@novox/mesh-sdk": "^0.1.0"
  },
  "devDependencies": {
    "@types/node": "^22.0.0",
    "typescript": "^5.6.0"
  }
 }
@@ -1,50 +0,0 @@
 // portainer's tools — its own code (novox/hq ADR 0039), importing portainer's own client. They
 // return structured data; the mesh serves them through the sdk's tool harness. portainer is
 // tools-only (no events entrypoint): a container starting or stopping is the host's signal to emit,
 // not Portainer's to re-announce.
 import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
 import { PortainerClient } from "../client.js";
 export function getPortainerTools(portainer: PortainerClient): ToolDefinition[] {
  return [
    {
      name: "portainer_endpoints",
      description: "List the environments (endpoints) Portainer manages — each a Docker host or cluster.",
      input: {},
      run: async () => {
        const endpoints = await portainer.listEndpoints();
        return { count: endpoints.length, endpoints };
      },
    },
    {
      name: "portainer_stacks",
      description: "List the stacks (compose/swarm deployments) Portainer knows about.",
      input: {},
      run: async () => {
        const stacks = await portainer.listStacks();
        return { count: stacks.length, stacks };
      },
    },
    {
      name: "portainer_containers",
      description: "List the containers on one Portainer endpoint, including stopped ones.",
      input: { endpoint: { type: "number", description: "the endpoint id (see portainer_endpoints)" } },
      run: async (args) => {
        const endpointId = Number(args.endpoint);
        const containers = await portainer.listContainers(endpointId);
        return { endpointId, count: containers.length, containers };
      },
    },
  ];
 }
 // The tools exist only when a token is configured; without one, portainer contributes none rather
 // than failing the whole runtime.
 registerModuleTools("portainer", (env) => {
  try {
    return getPortainerTools(PortainerClient.fromEnv(env));
  } catch {
    return [];
  }
 });
@@ -163,7 +163,8 @@
        "acme-env",
        "internal-trust",
        "internal-acme-env"
-      ]
+      ],
      "logging": "journald"
    }
  ],
  "build": {
@@ -194,5 +195,12 @@
        "image": "alpine@sha256:d9e853e87e55526f6b2917df91a2115c36dd7c696a35be12163d44e6e2a4b6bc"
      }
    ]
-  }
+  },
  "jails": [
    {
      "name": "route-proxy",
      "failregex": "^.*TLS handshake error from <HOST>:\\d+: (?:no public route for|acme/autocert: missing server name)\n            ^.*refused: no route for .*, asked from <HOST>:\\d+$",
      "jail": "backend = systemd\njournalmatch = CONTAINER_NAME=route-proxy\nport = http,https\nmaxretry = 10\nfindtime = 1d\nbantime = 1d"
    }
  ]
 }
@@ -1,24 +0,0 @@
 # searxng'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/searxng
 COPY . .
 RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts \
      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
 FROM ${RUNTIME_BASE}
 COPY --from=build /app/modules/searxng/dist /app/modules/searxng/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/searxng/dist/tools/index.js
@@ -8,8 +8,7 @@
    "secret": {
      "path": "${dir:mesh-state}/secret",
      "taken": "at-start"
-    },
+    }
    "broker": "${dir:mesh-state}/broker"
  },
  "listens": [
    {
@@ -91,25 +90,6 @@
      "path": "${dir:mesh-state}/config.json",
      "mode": "0600",
      "content": "{}\n"
    },
    {
      "id": "runtime",
      "type": "container",
      "name": "mesh-searxng",
      "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_SEARXNG_URL": "http://127.0.0.1:${port:8080}",
        "MESH_SEARXNG_CONFIG_FILE": "/run/config/config.json"
      },
      "restart-on": [
        "runtime-config"
      ],
      "artifact": "runtime"
    }
  ],
  "requires": [
@@ -125,23 +105,21 @@
    "route": "${dir:state}/route.json"
  },
  "build": {
    "on": [
      {
        "arg": "BUILD_BASE",
        "module": "mesh-tools",
        "artifact": "build"
      },
      {
        "arg": "RUNTIME_BASE",
        "module": "mesh-tools",
        "artifact": "runtime"
      }
    ],
    "artifacts": [
      {
-        "name": "runtime",
+        "name": "tools",
-        "kind": "image",
+        "kind": "bundle",
-        "from": "Dockerfile"
+        "language": "typescript",
        "entrypoints": [
          "tools/index.js"
        ],
        "loads": [
          "tools/index.js"
        ],
        "env": {
          "MESH_SEARXNG_URL": "http://127.0.0.1:${port:8080}",
          "MESH_SEARXNG_CONFIG_FILE": "${dir:mesh-state}/config.json"
        }
      }
    ]
  }
@@ -0,0 +1,21 @@
 {
  "module": "ssh-client",
  "version": "1",
  "resources": [
    {
      "id": "ssh-dir",
      "type": "directory",
      "path": "${machine:account-home}/.ssh",
      "owner": "${machine:account}",
      "mode": "0700"
    }
  ],
  "facts": {
    "ssh-config": {
      "path": ".ssh/config",
      "home": true,
      "shared": true,
      "template": "# The mesh's Host blocks — every other node, so `ssh <node>` reaches it as the\n# right account. This region is replaced whenever a node joins, leaves or is\n# renamed; the rest of this file is yours and is kept untouched.\n{{range .Machines}}{{if ne .Name $.Node}}\nHost {{.Name}} {{.FQDN}}\n  HostName {{.FQDN}}\n{{if .Account}}  User {{.Account}}\n{{end}}{{end}}{{end}}"
    }
  }
 }
@@ -5,20 +5,12 @@
    "container-runtime"
  ],
  "provides": [
    {
      "name": "acme-ca",
      "scope": "mesh"
    },
    {
      "name": "internal-acme-ca",
      "scope": "mesh"
    }
  ],
  "serves": {
    "acme-ca": {
      "path": "/acme/acme/directory",
      "roots": "/roots.pem"
    },
    "internal-acme-ca": {
      "path": "/acme/acme/directory",
      "roots": "/roots.pem"
@@ -1,24 +0,0 @@
 # unifi'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/unifi
 COPY . .
 RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts \
      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
 FROM ${RUNTIME_BASE}
 COPY --from=build /app/modules/unifi/dist /app/modules/unifi/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/unifi/dist/tools/index.js
@@ -23,6 +23,19 @@ export interface UnifiPortForward {
  site_id?: string;
 }
 export interface UnifiNetwork {
  _id: string;
  name: string;
  purpose: string;
  ip_subnet?: string;
  dhcpd_enabled?: boolean;
  dhcpd_dns_enabled?: boolean;
  dhcpd_dns_1?: string;
  dhcpd_dns_2?: string;
  dhcpd_dns_3?: string;
  dhcpd_dns_4?: string;
 }
 export interface UnifiDevice {
  _id: string;
  name: string;
@@ -232,6 +245,17 @@ export class UnifiApiClient {
    await this.request<unknown>("DELETE", `/api/s/${this.site}/rest/portforward/${id}`);
  }
  // --- Networks ---
  async listNetworks(): Promise<UnifiNetwork[]> {
    return this.request<UnifiNetwork>("GET", `/api/s/${this.site}/rest/networkconf`);
  }
  async updateNetwork(id: string, fields: Partial<UnifiNetwork>): Promise<UnifiNetwork> {
    const result = await this.request<UnifiNetwork>("PUT", `/api/s/${this.site}/rest/networkconf/${id}`, fields);
    return result[0];
  }
  // --- Devices ---
  async listDevices(): Promise<UnifiDevice[]> {
@@ -122,25 +122,6 @@
      "mode": "0600",
      "content": "{\n  \"site\": \"default\",\n  \"password\": \"${secret:controller}\"\n}\n",
      "merge": "json"
    },
    {
      "id": "runtime",
      "type": "container",
      "name": "mesh-unifi",
      "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_UNIFI_URL": "https://127.0.0.1:${port:8443}",
        "MESH_UNIFI_CONFIG_FILE": "/run/config/config.json"
      },
      "restart-on": [
        "runtime-config"
      ],
      "artifact": "runtime"
    }
  ],
  "requires": [
@@ -158,27 +139,24 @@
    "route": "${dir:state}/route.json"
  },
  "own-secrets": {
    "broker": "${dir:mesh-state}/broker",
    "controller": "${dir:mesh-state}/controller"
  },
  "build": {
    "on": [
      {
        "arg": "BUILD_BASE",
        "module": "mesh-tools",
        "artifact": "build"
      },
      {
        "arg": "RUNTIME_BASE",
        "module": "mesh-tools",
        "artifact": "runtime"
      }
    ],
    "artifacts": [
      {
-        "name": "runtime",
+        "name": "tools",
-        "kind": "image",
+        "kind": "bundle",
-        "from": "Dockerfile"
+        "language": "typescript",
        "entrypoints": [
          "tools/index.js"
        ],
        "loads": [
          "tools/index.js"
        ],
        "env": {
          "MESH_UNIFI_URL": "https://127.0.0.1:${port:8443}",
          "MESH_UNIFI_CONFIG_FILE": "${dir:mesh-state}/config.json"
        }
      }
    ]
  }
@@ -1,10 +1,23 @@
 // unifi's tools — its own code (novox/hq ADR 0039), importing unifi's own client. They return
 // structured data; the mesh serves them through the sdk's tool harness. unifi is tools-only (no
 // events entrypoint): the controller does not push lifecycle events the mesh consumes, so this
-// module reads its resources — port forwards, devices, clients — and exposes them, and stops there.
+// module reads its resources — port forwards, networks, devices, clients — and exposes them, and stops there.
 import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
-import { UnifiApiClient, type UnifiPortForward } from "../client.js";
+import { UnifiApiClient, type UnifiNetwork, type UnifiPortForward } from "../client.js";
 function summarizeNetwork(n: UnifiNetwork): Record<string, unknown> {
  const dns = [n.dhcpd_dns_1, n.dhcpd_dns_2, n.dhcpd_dns_3, n.dhcpd_dns_4].filter((s): s is string => !!s);
  return {
    id: n._id,
    name: n.name,
    purpose: n.purpose,
    subnet: n.ip_subnet ?? null,
    dhcp: n.dhcpd_enabled ?? null,
    // What DHCP hands out as DNS: the listed servers when set, otherwise the gateway itself.
    dhcp_dns: n.dhcpd_dns_enabled ? dns : "the gateway",
  };
 }
 function summarizePortForward(r: UnifiPortForward): Record<string, unknown> {
  return {
@@ -88,6 +101,40 @@ export function getUnifiTools(unifi: UnifiApiClient): ToolDefinition[] {
        return { deleted: true, id: String(args.id) };
      },
    },
    {
      name: "unifi_list_networks",
      description: "List the networks the UniFi controller manages, with the DNS servers each one's DHCP hands out.",
      input: {},
      run: async () => {
        const nets = await unifi.listNetworks();
        return { count: nets.length, networks: nets.map(summarizeNetwork) };
      },
    },
    {
      name: "unifi_set_network_dns",
      description:
        "Set the DNS servers a network's DHCP hands out to its devices (see unifi_list_networks for ids). " +
        "Up to four addresses, comma-separated; \"gateway\" hands out the gateway itself. Devices pick it up when they renew.",
      input: {
        id: { type: "string", description: "the network id" },
        dns: { type: "string", description: "comma-separated DNS server addresses, or \"gateway\"" },
      },
      run: async (args) => {
        const asked = String(args.dns ?? "").trim();
        if (!asked) return { updated: false, reason: "say dns: addresses, or \"gateway\"" };
        const servers = asked === "gateway" ? [] : asked.split(",").map((s) => s.trim()).filter(Boolean);
        if (servers.length > 4) return { updated: false, reason: "DHCP hands out at most four DNS servers" };
        const fields: Partial<UnifiNetwork> = {
          dhcpd_dns_enabled: servers.length > 0,
          dhcpd_dns_1: servers[0] ?? "",
          dhcpd_dns_2: servers[1] ?? "",
          dhcpd_dns_3: servers[2] ?? "",
          dhcpd_dns_4: servers[3] ?? "",
        };
        const net = await unifi.updateNetwork(String(args.id), fields);
        return { updated: summarizeNetwork(net) };
      },
    },
    {
      name: "unifi_list_devices",
      description: "List the network devices (APs, switches, gateways) the UniFi controller manages.",