nftables holds the node-packet-filter seat: rules, reload and remove, from a runtime with NET_ADMIN (hq ADR 0169)

The seat's three verbs over the machine's own tools: the filter as enforced
(nftables and the legacy filter), the mesh's own table reloaded from its file,
and one rule set the mesh did not write removed by the name the host reports
it under (ADR 0168) — a predecessor's chain loses its jumps and goes, the
runtime's user chain is emptied back to its return, a table of the machine's
own goes whole; the mesh's tables, the runtime's chains, a built-in chain and
an active found firewall's chains are refused. Tested over the shapes two
machines of the first mesh reported live. The module's own tool stays.

modules/bazarr/Dockerfile

@@ -1,24 +0,0 @@
-# bazarr's runtime: the tool runtime, carrying this module's compiled code.
-#
-# **Built from this module's own directory and nothing else.** The sdk and the tool runtime are in
-# the base images, published like any other artifact — which is what makes this buildable by the
-# mesh from a repository and a path (novox/hq ADR 0069) rather than only on a workstation that
-# happens to have the siblings.
-#
-# Two bases, named rather than pinned (novox/hq issue 044): the image this is COMPILED in and the
-# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
-ARG BUILD_BASE
-ARG RUNTIME_BASE
-
-FROM ${BUILD_BASE} AS build
-WORKDIR /app/modules/bazarr
-COPY . .
-RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts \
-      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
-
-FROM ${RUNTIME_BASE}
-COPY --from=build /app/modules/bazarr/dist /app/modules/bazarr/dist
-# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
-# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
-# the convention novox/hq issues 060/061 settled.
-ENV MESH_TOOL_MODULES=/app/modules/bazarr/dist/index.js,/app/modules/bazarr/dist/tools/index.js

modules/bazarr/client.ts

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

modules/bazarr/index.ts

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

modules/bazarr/module.json

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

modules/bazarr/package.json

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

modules/bazarr/tools/index.ts

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

modules/bazarr/tsconfig.json

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

modules/bookshelf/Dockerfile

@@ -1,24 +0,0 @@
-# bookshelf's runtime: the tool runtime, carrying this module's compiled code.
-#
-# **Built from this module's own directory and nothing else.** The sdk and the tool runtime are in
-# the base images, published like any other artifact — which is what makes this buildable by the
-# mesh from a repository and a path (novox/hq ADR 0069) rather than only on a workstation that
-# happens to have the siblings.
-#
-# Two bases, named rather than pinned (novox/hq issue 044): the image this is COMPILED in and the
-# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
-ARG BUILD_BASE
-ARG RUNTIME_BASE
-
-FROM ${BUILD_BASE} AS build
-WORKDIR /app/modules/bookshelf
-COPY . .
-RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts \
-      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
-
-FROM ${RUNTIME_BASE}
-COPY --from=build /app/modules/bookshelf/dist /app/modules/bookshelf/dist
-# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
-# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
-# the convention novox/hq issues 060/061 settled.
-ENV MESH_TOOL_MODULES=/app/modules/bookshelf/dist/index.js,/app/modules/bookshelf/dist/tools/index.js

modules/bookshelf/client.ts

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

modules/bookshelf/index.ts

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

modules/bookshelf/module.json

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

modules/bookshelf/package.json

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

modules/bookshelf/tools/index.ts

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

modules/bookshelf/tsconfig.json

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

modules/dhcpcd/module.json

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

modules/gitea/client.ts

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

modules/gitea/test/token.test.ts

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

modules/gitea/tools/index.ts

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

modules/lidarr/Dockerfile

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

modules/lidarr/client.ts

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

modules/lidarr/index.ts

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

modules/lidarr/module.json

@@ -1,119 +0,0 @@
-{
-  "module": "lidarr",
-  "version": "1",
-  "capabilities": [
-    "container-runtime"
-  ],
-  "emits": [
-    "album.grabbed",
-    "download.completed"
-  ],
-  "consumes": [],
-  "own-secrets": {
-    "broker": "${dir:mesh-state}/broker"
-  },
-  "listens": [
-    {
-      "name": "web",
-      "port": 8686,
-      "protocol": "tcp",
-      "from": "mesh",
-      "why": "managing music"
-    }
-  ],
-  "accesses": [
-    {
-      "id": "music",
-      "path": "/services/media/music",
-      "mode": "read-write"
-    },
-    {
-      "id": "downloads",
-      "path": "/services/media/downloads",
-      "mode": "read-write"
-    }
-  ],
-  "resources": [
-    {
-      "id": "mesh-state",
-      "type": "directory",
-      "mode": "0700",
-      "place": "mesh"
-    },
-    {
-      "id": "config",
-      "type": "directory",
-      "path": "/services/lidarr/config",
-      "mode": "0700",
-      "owner": "1000:1000"
-    },
-    {
-      "id": "server",
-      "type": "container",
-      "name": "lidarr",
-      "image": "lscr.io/linuxserver/lidarr@sha256:6b38dd330b0c653351c2e23c8b962ea51c95683dd7acace9d106c922baf85f75",
-      "env": {
-        "PUID": "1000",
-        "PGID": "1000",
-        "TZ": "Etc/UTC"
-      },
-      "ports": [
-        "8686"
-      ],
-      "volumes": [
-        "/services/lidarr/config:/config",
-        "${access:music}:/music",
-        "${access:downloads}:/downloads"
-      ]
-    },
-    {
-      "id": "runtime",
-      "type": "container",
-      "name": "mesh-lidarr",
-      "network": "host",
-      "volumes": [
-        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
-        "/services/lidarr/config:/var/lib/lidarr/config:ro"
-      ],
-      "env": {
-        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_LIDARR_URL": "http://127.0.0.1:8686",
-        "MESH_LIDARR_CONFIG_DIR": "/var/lib/lidarr/config"
-      },
-      "artifact": "runtime"
-    }
-  ],
-  "requires": [
-    "route"
-  ],
-  "contributes": {
-    "route": {
-      "label": "lidarr",
-      "endpoint": "web"
-    }
-  },
-  "binds": {
-    "route": "${dir:mesh-state}/route.json"
-  },
-  "build": {
-    "on": [
-      {
-        "arg": "BUILD_BASE",
-        "module": "mesh-tools",
-        "artifact": "build"
-      },
-      {
-        "arg": "RUNTIME_BASE",
-        "module": "mesh-tools",
-        "artifact": "runtime"
-      }
-    ],
-    "artifacts": [
-      {
-        "name": "runtime",
-        "kind": "image",
-        "from": "Dockerfile"
-      }
-    ]
-  }
-}

modules/lidarr/package.json

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

modules/lidarr/tools/index.ts

@@ -1,78 +0,0 @@
-// lidarr's tools — ported from the shared hal sdk (novox/hq ADR 0039), importing lidarr's own
-// client. They return structured data (not pre-formatted text as hal did); the mesh serves them
-// through the sdk's tool harness.
-
-import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
-import { LidarrClient } from "../client.js";
-
-export function getLidarrTools(lidarr: LidarrClient): ToolDefinition[] {
-  return [
-    {
-      name: "lidarr_status",
-      description: "Lidarr status overview: version, artist count, monitored count, queue size.",
-      input: {},
-      run: async () => {
-        const [status, content, queue] = await Promise.all([
-          lidarr.getStatus(),
-          lidarr.getContent(),
-          lidarr.getQueue(),
-        ]);
-        return {
-          app: status.appName,
-          version: status.version,
-          artists: content.length,
-          monitored: content.filter((c) => c.monitored).length,
-          queue: queue.totalRecords,
-        };
-      },
-    },
-    {
-      name: "lidarr_library",
-      description: "List artists from the Lidarr library.",
-      input: { limit: { type: "number", description: "max items to return (default 50)" } },
-      run: async (args) => {
-        const items = await lidarr.getContent(args.limit ? Number(args.limit) : 50);
-        return { count: items.length, artists: items };
-      },
-    },
-    {
-      name: "lidarr_search",
-      description: "Search the Lidarr library for artists by name (filters existing content, not indexers).",
-      input: { query: { type: "string", description: "the search term" } },
-      run: async (args) => {
-        const query = String(args.query);
-        return { query, results: await lidarr.searchContent(query) };
-      },
-    },
-    {
-      name: "lidarr_queue",
-      description: "Show the Lidarr download queue — what is downloading and how far along.",
-      input: {},
-      run: async () => {
-        const queue = await lidarr.getQueue();
-        return { count: queue.totalRecords, items: queue.items };
-      },
-    },
-    {
-      name: "lidarr_calendar",
-      description: "Upcoming album releases from the Lidarr calendar.",
-      input: { days: { type: "number", description: "how many days to look ahead (default 7)" } },
-      run: async (args) => {
-        const days = args.days ? Number(args.days) : 7;
-        const items = await lidarr.getCalendar(days);
-        items.sort((a, b) => a.date.localeCompare(b.date));
-        return { days, count: items.length, items };
-      },
-    },
-  ];
-}
-
-// The tools exist only when Lidarr is configured; without a URL and key, lidarr contributes none
-// rather than failing the whole runtime.
-registerModuleTools("lidarr", (env) => {
-  try {
-    return getLidarrTools(LidarrClient.fromEnv(env));
-  } catch {
-    return [];
-  }
-});

modules/lidarr/tsconfig.json

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

modules/mesh-vault/index.ts

@@ -1,9 +1,9 @@
 // mesh-vault's events entrypoint, loaded by the per-node tool host (the provisioner runs in the same
 // process — ADR 0052). The lifecycle events are EMITTED from the provisioner, where custody
 // actually changes (novox/hq ADR 0041/0042):
-//   module.mesh-vault.secret.provisioned    — a consumer was granted a secret
-//   module.mesh-vault.secret.rotated        — that consumer's value changed (`rotate secret`)
-//   module.mesh-vault.secret.deprovisioned  — the consumer went away and its secret was withdrawn
+//   mesh-vault.provisioned    — a consumer was granted a secret
+//   mesh-vault.rotated        — that consumer's value changed (`rotate secret`)
+//   mesh-vault.deprovisioned  — the consumer went away and its secret was withdrawn
 // Here the vault reacts to them, keeping a lightweight audit line of who holds what and when it
 // moved — the audit an owner of secrets is best placed to log. Fingerprints, never values.
 
@@ -16,15 +16,15 @@ interface SecretEvent {
   rotations?: number;
 }
 
-await on<SecretEvent>("secret.provisioned", async (e) => {
+await on<SecretEvent>("provisioned", async (e) => {
   console.log(`[mesh-vault] secret provisioned for ${e.body.as} on ${e.body.consumer} (${e.body.fingerprint})`);
 });
 
-await on<SecretEvent>("secret.rotated", async (e) => {
+await on<SecretEvent>("rotated", async (e) => {
   console.log(`[mesh-vault] secret rotated for ${e.body.as} — rotation ${e.body.rotations} (${e.body.fingerprint})`);
 });
 
-await on<SecretEvent>("secret.deprovisioned", async (e) => {
+await on<SecretEvent>("deprovisioned", async (e) => {
   console.log(`[mesh-vault] secret withdrawn from ${e.body.as}`);
 });
 

modules/mesh-vault/module.json

@@ -11,14 +11,14 @@
     "container-runtime"
   ],
   "emits": [
-    "secret.provisioned",
-    "secret.rotated",
-    "secret.deprovisioned"
+    "provisioned",
+    "rotated",
+    "deprovisioned"
   ],
   "consumes": [
-    "mesh-vault.secret.provisioned",
-    "mesh-vault.secret.rotated",
-    "mesh-vault.secret.deprovisioned"
+    "mesh-vault.provisioned",
+    "mesh-vault.rotated",
+    "mesh-vault.deprovisioned"
   ],
   "receives": {
     "secret": "${dir:grants}/mesh.json"
@@ -98,5 +98,11 @@
         "from": "Dockerfile"
       }
     ]
-  }
+  },
+  "claims": [
+    {
+      "name": "mesh-vault",
+      "scope": "mesh"
+    }
+  ]
 }

modules/mesh-vault/provisioner/index.ts

@@ -43,6 +43,6 @@ runProvisioner("secret", {
   async remove(p: { as: string }): Promise<void> {
     if (!ledger.withdraw(p.as)) return;
     console.log(`[mesh-vault] withdrawn: ${p.as}`);
-    await announce("secret.deprovisioned", { as: p.as });
+    await announce("deprovisioned", { as: p.as });
   },
 });

modules/mssql/Dockerfile

@@ -20,7 +20,20 @@ COPY . .
 RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts provisioner/index.ts \
       --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
 
+# **sqlcmd, which this module's client drives, has to be here** — it never was, so every tool failed
+# with `spawn sqlcmd ENOENT`. go-sqlcmd is one static binary; fetched at a pinned release and checked
+# against its digest, so a build that receives anything else stops here.
+FROM ${BUILD_BASE} AS sqlcmd
+ARG SQLCMD_VERSION=v1.10.0
+ARG SQLCMD_SHA256=92516d98c63d99b0994de5b61350c91f6915f9b76f139a59039fbcb225c2e987
+RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates bzip2 \
+      && curl -fsSL -o /tmp/sqlcmd.tar.bz2 \
+           "https://github.com/microsoft/go-sqlcmd/releases/download/${SQLCMD_VERSION}/sqlcmd-linux-amd64.tar.bz2" \
+      && echo "${SQLCMD_SHA256}  /tmp/sqlcmd.tar.bz2" | sha256sum -c - \
+      && tar -xjf /tmp/sqlcmd.tar.bz2 -C /usr/local/bin sqlcmd
+
 FROM ${RUNTIME_BASE}
+COPY --from=sqlcmd /usr/local/bin/sqlcmd /usr/local/bin/sqlcmd
 COPY --from=build /app/modules/mssql/dist /app/modules/mssql/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 —

modules/mssql/client.ts

@@ -29,11 +29,40 @@ export interface MssqlConn {
   readonly port: number;
   readonly user: string;
   readonly password: string;
+  /**
+   * The read-only login's password, which the mesh mints for this module (`own-secrets.reader`).
+   * Absent when the mesh has not delivered it: then a caller's statement is refused, never run as
+   * the administrator (novox/hq issue 193).
+   */
+  readonly readerPassword?: string;
+}
+
+/**
+ * The login a caller's statement runs as (novox/hq issue 193). It may connect to every database and
+ * read every table, and holds no other permission. A statement cannot climb out of a login the way it
+ * could out of a transaction wrapped around it as text, and the administrator — who can run programs
+ * on the server — never runs a caller's text.
+ */
+export const READER = "mesh_mssql_reader";
+
+/** Who a sqlcmd invocation logs in as, and whether the text is a caller's rather than the module's. */
+interface Invocation {
+  readonly user: string;
+  readonly password: string;
+  /**
+   * A caller's text: sqlcmd substitutes no `$(NAME)` in it, which would read this process's
+   * environment — the administrator's password among it. (Its own commands are kept out by the
+   * caller's text never beginning a line; see readOnlyQuery.)
+   */
+  readonly caller: boolean;
 }
 
 export class MssqlClient {
   constructor(private readonly conn: MssqlConn) {}
 
+  /** The reader is made once per process: idempotent, and repeating it re-sets a rotated password. */
+  private readerReady?: Promise<void>;
+
   /**
    * Build from the module's resolved environment. Reads MESH_MSSQL_* first (the documented
    * names), falling back to the MESH_PROVISION_* keys the manifest already sets on the provisioner
@@ -48,7 +77,9 @@ export class MssqlClient {
     if (!host || !password) {
       throw new Error("mssql host or admin password is not set — mssql's own code cannot reach the server");
     }
-    return new MssqlClient({ host, port, user, password });
+    const readerPassword = env.MESH_MSSQL_READER_PASSWORD ??
+      readSecretFile(env.MESH_MSSQL_READER_PASSWORD_FILE);
+    return new MssqlClient({ host, port, user, password, readerPassword });
   }
 
   get host(): string {
@@ -86,7 +117,12 @@ export class MssqlClient {
   }
 
   /** The one execution boundary: invoke `sqlcmd` and return its concatenated stdout. */
-  private async sqlcmd(sql: string, database: string, variables: Record<string, string> = {}): Promise<string> {
+  private async sqlcmd(
+    sql: string,
+    database: string,
+    variables: Record<string, string> = {},
+    as: Invocation = { user: this.conn.user, password: this.conn.password, caller: false },
+  ): Promise<string> {
     // `-h -1` drops the column-header rule; `-y 0`/`-Y 0` lift the display-width cap so a long
     // JSON document is not truncated; `-W` trims trailing whitespace so the JSON chunks rejoin
     // cleanly. sqlcmd from the mssql-tools ships in the runtime container, the way `psql` ships
@@ -95,8 +131,9 @@ export class MssqlClient {
       "sqlcmd",
       [
         "-S", `${this.conn.host},${this.conn.port}`,
-        "-U", this.conn.user,
+        "-U", as.user,
         "-d", database,
+        ...(as.caller ? ["-x"] : []),
         "-C",
         "-b",
         "-h", "-1",
@@ -107,7 +144,7 @@ export class MssqlClient {
       ],
       // `variables` reach sqlcmd as environment variables, which it substitutes as `$(NAME)` scripting
       // variables: a value that must not appear on argv, or in the message of a failed command.
-      { env: { ...process.env, ...variables, SQLCMDPASSWORD: this.conn.password }, maxBuffer: 16 << 20 },
+      { env: { ...process.env, ...variables, SQLCMDPASSWORD: as.password }, maxBuffer: 16 << 20 },
     );
     return stdout;
   }
@@ -225,16 +262,76 @@ export class MssqlClient {
     }));
   }
 
-  /** Run a read-only SELECT against a named database, for the mssql_query tool. */
-  async readOnlyQuery(database: string, sql: string): Promise<QueryResult> {
-    // The read-only guarantee is a wrapping transaction that is always rolled back: any write the
-    // statement attempts is undone. The rows are rendered by FOR JSON inside query().
-    const rows = await this.query(
-      `BEGIN TRANSACTION;\n${stripTrailingSemis(sql)}\nFOR JSON PATH, INCLUDE_NULL_VALUES;\nROLLBACK;`,
-      database,
+  /**
+   * Make the read-only login, idempotently, with the password the mesh minted for it: it may connect
+   * to every database and read every table, and is taken out of the administrators' role should
+   * anyone have put it there. Run as the administrator, because only it can make a login.
+   */
+  async ensureReader(): Promise<void> {
+    const password = this.conn.readerPassword;
+    if (!password) throw readerMissing();
+    const logins = await this.query(
+      `SELECT 1 AS ok FROM sys.server_principals WHERE name = ${literal(READER)}`,
     );
-    return { command: sql.trimStart().split(/\s+/)[0]?.toUpperCase() ?? "", rows };
+    if (logins.length === 0) {
+      await this.exec(
+        `CREATE LOGIN ${ident(READER)} WITH PASSWORD = ${literal(password)}, CHECK_POLICY = OFF`,
+      );
+    } else {
+      await this.exec(`ALTER LOGIN ${ident(READER)} WITH PASSWORD = ${literal(password)}`);
+      await this.exec(`ALTER LOGIN ${ident(READER)} ENABLE`);
+    }
+    await this.exec(
+      `IF IS_SRVROLEMEMBER('sysadmin', ${literal(READER)}) = 1 ` +
+        `ALTER SERVER ROLE sysadmin DROP MEMBER ${ident(READER)}`,
+    );
+    await this.exec(`GRANT CONNECT ANY DATABASE TO ${ident(READER)}`);
+    await this.exec(`GRANT SELECT ALL USER SECURABLES TO ${ident(READER)}`);
   }
+
+  /**
+   * Run a caller's SELECT against a named database as the read-only login, for the mssql_query tool
+   * (novox/hq issue 193). Read-only by the login, not by a transaction wrapped around the text; the
+   * rows are rendered by FOR JSON. Never as the administrator: without the reader's password the call
+   * is refused.
+   */
+  async readOnlyQuery(database: string, sql: string): Promise<QueryResult> {
+    const password = this.conn.readerPassword;
+    if (!password) throw readerMissing();
+    // **One line, refused otherwise.** sqlcmd reads a line that BEGINS with `:` or `!!` as its own
+    // command rather than SQL, and `:!!` starts a program in this container, which holds the
+    // administrator's password. Its switch for refusing those (-X) makes it ignore -Q in the
+    // version shipped here, so instead no line of a caller's text can begin one: the text follows
+    // this module's own on the first line, and a line break in it is refused. Proven on a throwaway
+    // server: the same text at the start of a line ran a program; mid-line it is a syntax error.
+    if (/[\r\n]/.test(sql)) {
+      throw new Error(
+        "mssql_query: the statement must be one line — sqlcmd takes a line beginning with ':' or " +
+          "'!!' as a command of its own, which can start a program (novox/hq issue 193)",
+      );
+    }
+    this.readerReady ??= this.ensureReader().catch((err) => {
+      this.readerReady = undefined; // asked again next call, not failed for the process's life
+      throw err;
+    });
+    await this.readerReady;
+    const stdout = await this.sqlcmd(
+      `SET NOCOUNT ON; ${stripTrailingSemis(sql)}\nFOR JSON PATH, INCLUDE_NULL_VALUES;`,
+      database,
+      {},
+      { user: READER, password, caller: true },
+    );
+    const command = /^\s*([A-Za-z]+)/.exec(sql)?.[1]?.toUpperCase() ?? "";
+    return { command, rows: parseJsonRows(stdout) };
+  }
+}
+
+function readerMissing(): Error {
+  return new Error(
+    "the read-only login's password was not delivered (own-secrets.reader, " +
+      "MESH_MSSQL_READER_PASSWORD_FILE), so the statement is refused rather than run as the " +
+      "administrator (novox/hq issue 193)",
+  );
 }
 
 /** Generate a URL-safe password. */

modules/mssql/module.json

@@ -38,7 +38,8 @@
   },
   "own-secrets": {
     "sa": "${dir:state}/sa.secret",
-    "broker": "${dir:mesh-state}/broker"
+    "broker": "${dir:mesh-state}/broker",
+    "reader": "${dir:state}/reader.secret"
   },
   "resources": [
     {
@@ -101,13 +102,15 @@
       "volumes": [
         "${dir:mesh-state}/broker:/run/secrets/broker:ro",
         "${dir:grants}:/var/lib/mssql/grants:ro",
-        "${dir:state}/sa.secret:/run/secrets/sa:ro"
+        "${dir:state}/sa.secret:/run/secrets/sa:ro",
+        "${dir:state}/reader.secret:/run/secrets/reader:ro"
       ],
       "env": {
         "MESH_PROVISION_MSSQL": "mssql://sa@mssql:1433/master",
         "MESH_PROVISION_PASSWORD_FILE": "/run/secrets/sa",
         "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_RECEIVES": "/var/lib/mssql/grants/mesh.json"
+        "MESH_RECEIVES": "/var/lib/mssql/grants/mesh.json",
+        "MESH_MSSQL_READER_PASSWORD_FILE": "/run/secrets/reader"
       },
       "artifact": "runtime"
     }

modules/mssql/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@novox/module-mssql",
   "version": "0.1.0",
-  "description": "mssql — provides the mesh mssql-database interface. Its client, provisioner, tools and events live here (novox/hq ADR 0039).",
+  "description": "mssql \u2014 provides the mesh mssql-database interface. Its client, provisioner, tools and events live here (novox/hq ADR 0039).",
   "type": "module",
   "private": true,
+  "scripts": {
+    "build": "tsc client.ts index.ts tools/index.ts provisioner/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist",
+    "test": "npm run build && node --test --experimental-strip-types 'test/*.test.ts'"
+  },
   "dependencies": {
     "@novox/mesh-sdk": "^0.1.1"
   },

modules/mssql/test/reader.test.ts

@@ -0,0 +1,96 @@
+// What holds mssql_query to being read-only (novox/hq issue 193): a caller's statement runs as the
+// reader login and never as the administrator, with sqlcmd's variable substitution off, on one line
+// that follows the module's own — a line break is refused before sqlcmd starts — and with no
+// transaction wrapped around it as text. Without the reader's password the statement is refused.
+//
+// sqlcmd is a fake on PATH that records each call's login, flags and text. That the reader cannot
+// write is the server's to enforce and was proven against a real server; this holds the module to
+// asking for it. Run against the compiled module (npm test builds first), the way the runtime loads it.
+
+import { test, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { chmod, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { MssqlClient, READER } from "../dist/client.js";
+
+let dir: string;
+let log: string;
+const originalPath = process.env.PATH;
+
+before(async () => {
+  dir = await mkdtemp(join(tmpdir(), "mssql-reader-"));
+  log = join(dir, "calls.jsonl");
+  await writeFile(join(dir, "sqlcmd"), `#!/usr/bin/env node
+const fs = require("node:fs");
+const args = process.argv.slice(2);
+const at = (flag) => args[args.indexOf(flag) + 1];
+fs.appendFileSync(${JSON.stringify(log)}, JSON.stringify({
+  user: at("-U"), database: at("-d"), sql: at("-Q"), noVariables: args.includes("-x"),
+  password: process.env.SQLCMDPASSWORD,
+}) + "\\n");
+const sql = at("-Q");
+if (/FROM sys.server_principals/.test(sql)) process.stdout.write("");
+else if (/FOR JSON/.test(sql)) process.stdout.write('[{"name":"alpha","n":1}]\\n');
+`);
+  await chmod(join(dir, "sqlcmd"), 0o755);
+  process.env.PATH = `${dir}:${originalPath}`;
+});
+
+after(async () => {
+  process.env.PATH = originalPath;
+  await rm(dir, { recursive: true, force: true });
+});
+
+async function calls(): Promise<Record<string, unknown>[]> {
+  const text = await readFile(log, "utf8").catch(() => "");
+  await writeFile(log, "");
+  return text.split("\n").filter(Boolean).map((line) => JSON.parse(line));
+}
+
+const conn = { host: "127.0.0.1", port: 1433, user: "sa", password: "admin-secret" };
+
+test("a caller's statement runs as the reader, without variables, on the module's first line", async () => {
+  const client = new MssqlClient({ ...conn, readerPassword: "reader-secret" });
+  const result = await client.readOnlyQuery("inventory", "SELECT '$(SQLCMDPASSWORD)' AS p");
+
+  const asked = (await calls()).at(-1)!;
+  assert.equal(asked.user, READER, "the statement never runs as the administrator");
+  assert.equal(asked.password, "reader-secret");
+  assert.equal(asked.noVariables, true, "no $(NAME) is substituted in a caller's text");
+  const [first] = String(asked.sql).split("\n");
+  assert.ok(first.startsWith("SET NOCOUNT ON; SELECT '$(SQLCMDPASSWORD)'"), "the caller's text never begins a line");
+  assert.doesNotMatch(String(asked.sql), /BEGIN TRANSACTION|ROLLBACK/, "no transaction wrapped around it as text");
+  assert.deepEqual(result.rows, [{ name: "alpha", n: 1 }]);
+  assert.equal(result.command, "SELECT");
+});
+
+test("a line break in a caller's statement is refused before sqlcmd starts", async () => {
+  const client = new MssqlClient({ ...conn, readerPassword: "reader-secret" });
+  for (const sql of ["SELECT 1\n:!! id", "SELECT 1\r\n:!! id", "SELECT 1\r:!! id"]) {
+    await assert.rejects(client.readOnlyQuery("inventory", sql), /must be one line/);
+  }
+  assert.deepEqual(await calls(), []);
+});
+
+test("the reader is made as the administrator, kept out of sysadmin, and granted only reading", async () => {
+  const client = new MssqlClient({ ...conn, readerPassword: "reader-secret" });
+  await client.readOnlyQuery("inventory", "SELECT 1 AS x");
+  await client.readOnlyQuery("inventory", "SELECT 2 AS x");
+
+  const made = await calls();
+  const asAdmin = made.filter((c) => c.user === "sa").map((c) => String(c.sql));
+  assert.ok(asAdmin.some((s) => s.startsWith(`CREATE LOGIN [${READER}]`)));
+  assert.ok(asAdmin.some((s) => /ALTER SERVER ROLE sysadmin DROP MEMBER/.test(s)));
+  assert.ok(asAdmin.includes(`GRANT CONNECT ANY DATABASE TO [${READER}]`));
+  assert.ok(asAdmin.includes(`GRANT SELECT ALL USER SECURABLES TO [${READER}]`));
+  assert.equal(asAdmin.filter((s) => s.startsWith("CREATE LOGIN")).length, 1, "made once, not per call");
+  assert.equal(made.filter((c) => c.user === READER).length, 2);
+});
+
+test("without the reader's password the statement is refused, and nothing runs as the administrator", async () => {
+  const client = new MssqlClient(conn);
+  await assert.rejects(client.readOnlyQuery("inventory", "SELECT 1"), /refused rather than run as the administrator/);
+  assert.deepEqual(await calls(), []);
+});

modules/mssql/tools/index.ts

@@ -16,7 +16,7 @@ export function getMssqlTools(mssql: MssqlClient): ToolDefinition[] {
     },
     {
       name: "mssql_query",
-      description: "Run a read-only SELECT against a named database (wrapped in a rolled-back transaction).",
+      description: "Run a read-only SELECT against a named database, as a login that can read every table and change nothing.",
       input: {
         database: { type: "string", description: "the database to query" },
         sql: { type: "string", description: "a single SELECT statement" },

modules/n8n/module.json

@@ -26,7 +26,7 @@
   },
   "accesses": [
     {
-      "path": "/services/media",
+      "id": "media",
       "mode": "read-write"
     }
   ],
@@ -93,7 +93,7 @@
       "volumes": [
         "${dir:data}:/home/node/.n8n",
         "${dir:state}/n8n-database.secret:/run/secrets/database:ro",
-        "/services/media:/media-library"
+        "${access:media}:/media-library"
       ]
     },
     {

modules/networkmanager/module.json

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

modules/nftables/Dockerfile

@@ -0,0 +1,23 @@
+# nftables' runtime: the tool runtime, carrying the packet filter's tools and the binaries they speak.
+#
+# Built from this module's own directory and nothing else (novox/hq ADR 0069). Two bases, named in
+# module.json's `build.on`: the image this is compiled in and the image it runs in.
+ARG BUILD_BASE
+ARG RUNTIME_BASE
+
+FROM ${BUILD_BASE} AS build
+WORKDIR /app/modules/nftables
+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}
+# The filter's own tools: nft for the machine's ruleset and the mesh's table, iptables for the
+# legacy filter and the tables iptables-nft manages — a predecessor's rules live there (ADR 0168).
+# The container runs on the machine's network with NET_ADMIN (ADR 0169), so these act on the
+# machine's packet filter, not on a namespace of their own.
+RUN apt-get update \
+      && apt-get install -y --no-install-recommends nftables iptables \
+      && rm -rf /var/lib/apt/lists/*
+COPY --from=build /app/modules/nftables/dist /app/modules/nftables/dist
+ENV MESH_TOOL_MODULES=/app/modules/nftables/dist/tools/index.js

modules/nftables/client.ts

@@ -1,22 +1,211 @@
-// The firewall's own code, in the module (novox/hq ADR 0039). The mesh computes this node's whole
-// rule set from every module's `listens` and writes it to /etc/nftables.conf (novox/hq ADR 0045);
-// the module loads it through its own mesh-filter unit, reloaded whenever the rules change, whose
-// stop deletes only the mesh's table and never flushes the whole ruleset (novox/hq ADR 0100). This
-// code exists only to read back what is actually enforced — the enforcement itself is declarative.
+// 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 the filter file (ADR 0045); the module
+// loads it through its own unit. This code reads the filter back as the machine enforces it, reloads
+// the mesh's own table, and removes one thing the mesh did not write when the operator names it
+// (ADR 0168, ADR 0169) — the seat's three verbs, over the machine's own tools.
 
 import { execFile } from "node:child_process";
 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>;
+
+export const execRunner: Runner = async (cmd, args) => {
+  const { stdout } = await execFileP(cmd, args, { maxBuffer: 16 * 1024 * 1024 });
+  return stdout;
+};
+
+/** 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 {
-    return new FirewallClient();
+  private readonly run: Runner;
+  private readonly filterFile: string;
+
+  constructor(run: Runner = execRunner, filterFile: string = process.env.MESH_FILTER_FILE ?? "/etc/nftables.conf") {
+    this.run = run;
+    this.filterFile = filterFile;
   }
 
-  /** The mesh's live table — exactly what is dropping and accepting on this node right now. */
+  static fromEnv(env: NodeJS.ProcessEnv = process.env): FirewallClient {
+    return new FirewallClient(execRunner, env.MESH_FILTER_FILE ?? "/etc/nftables.conf");
+  }
+
+  /** 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 stdout;
+    return this.run("nft", ["list", "table", "inet", "mesh"]);
+  }
+
+  /** 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"]) {
+        try {
+          const out = await this.run(tool, ["-S"]);
+          if (out.trim()) legacy[tool] = out;
+        } catch {
+          // the tool is not here, or the legacy filter is empty: nothing to list
+        }
+      }
+    }
+    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. */
+  private async ufwActive(): Promise<boolean> {
+    try {
+      const out = await this.run("ufw", ["status"]);
+      return /^Status:\s*active/m.test(out);
+    } catch {
+      return false;
+    }
+  }
+
+  /** 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, "\\$&");
+}

modules/nftables/module.json

@@ -2,18 +2,30 @@
   "module": "nftables",
   "version": "1",
   "capabilities": [
-    "firewall"
+    "firewall",
+    "container-runtime"
   ],
   "claims": [
     {
       "name": "node-packet-filter",
-      "scope": "node"
+      "scope": "node",
+      "serves": [
+        "rules",
+        "reload",
+        "remove"
+      ]
     }
   ],
   "filtering": {
     "into": "/etc/nftables.conf"
   },
   "resources": [
+    {
+      "id": "mesh-state",
+      "type": "directory",
+      "mode": "0700",
+      "place": "mesh"
+    },
     {
       "id": "package",
       "type": "package",
@@ -46,6 +58,51 @@
       "reload-on": [
         "filtering"
       ]
+    },
+    {
+      "id": "runtime",
+      "type": "container",
+      "name": "mesh-nftables",
+      "network": "host",
+      "capabilities": [
+        "NET_ADMIN"
+      ],
+      "volumes": [
+        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "/etc/nftables.conf:/etc/nftables.conf:ro"
+      ],
+      "env": {
+        "MESH_BROKER_FILE": "/run/secrets/broker",
+        "MESH_FILTER_FILE": "/etc/nftables.conf"
+      },
+      "artifact": "runtime"
     }
-  ]
+  ],
+  "tools": [
+    "firewall_rules"
+  ],
+  "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"
+      }
+    ]
+  }
 }

modules/nftables/package.json

@@ -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 0169).",
   "type": "module",
   "private": true,
+  "scripts": {
+    "build": "tsc client.ts tools/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --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",

modules/nftables/test/remove.test.ts

@@ -0,0 +1,74 @@
+// `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 { FirewallClient, chainsJumpingTo, 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).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).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).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).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);
+  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).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"]);
+});

modules/nftables/tools/index.ts

@@ -1,19 +1,51 @@
-// firewall's tools — one, and the useful one: what is actually enforced. The rules are the mesh's,
-// computed from every module's listens; this reads the live table so a declared scope can be checked
-// against what the packet filter is really doing.
-
+// The packet filter's tools: the node-packet-filter seat's three verbs — what the machine enforces,
+// reload the mesh's own, remove one thing the mesh did not write — and the module's own reading of
+// the mesh's table (novox/hq ADR 0045, ADR 0168, ADR 0169).
 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.fromEnv();
+// 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));

modules/nodered/module.json

@@ -5,8 +5,14 @@
     "flows.deployed"
   ],
   "own-secrets": {
-    "admin": "${dir:mesh-state}/admin",
-    "api-token": "${dir:mesh-state}/api-token",
+    "admin": {
+      "path": "${dir:mesh-state}/admin",
+      "taken": "at-start"
+    },
+    "api-token": {
+      "path": "${dir:mesh-state}/api-token",
+      "taken": "at-start"
+    },
     "broker": "${dir:mesh-state}/broker"
   },
   "capabilities": [

modules/nzbget/Dockerfile

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

modules/nzbget/client.ts

@@ -1,178 +0,0 @@
-// The NZBGet API client — nzbget's own code, living in the module (novox/hq ADR 0039). Ported from
-// hal's shared nzbget tools, but self-contained: a change to NZBGet's JSON-RPC now rebuilds only
-// nzbget and nothing else. Both this module's tools and its events entrypoint import it, and
-// nothing outside nzbget does. NZBGet speaks JSON-RPC at /jsonrpc, behind HTTP Basic auth.
-
-import { readFileSync } from "node:fs";
-
-export interface NzbgetStatus {
-  /** Bytes/sec — NZBGet reports it split across two 32-bit halves, rejoined here. */
-  speedBytesPerSec: number;
-  remainingMB: number;
-  downloadedTodayMB: number;
-  downloadedMonthMB: number;
-  freeDiskMB: number;
-  paused: boolean;
-  postJobs: number;
-  uptimeSec: number;
-}
-
-export interface NzbgetQueueItem {
-  /** The NZBID — stable while the item is queued, so events can diff on it. */
-  id: number;
-  name: string;
-  status: string;
-  category: string;
-  sizeMB: number;
-  remainingMB: number;
-  percent: number;
-}
-
-export interface NzbgetHistoryItem {
-  /** The NZBID — the same id the item carried in the queue. */
-  id: number;
-  name: string;
-  /** NZBGet's own status string, e.g. "SUCCESS/ALL", "FAILURE/PAR", "DELETED/MANUAL". */
-  status: string;
-  category: string;
-  sizeMB: number;
-  /** A genuine completion (status starts "SUCCESS") vs a failed or deleted entry — the difference
-   *  between something to announce as done and something that merely left the queue. */
-  success: boolean;
-}
-
-/** The settings-merged config the mesh delivers (novox/hq ADR 0046): { url, apiKey, token, password, user, ... }. */
-function meshConfig(file?: string): Record<string, string> {
-  if (!file) return {};
-  try { return JSON.parse(readFileSync(file, "utf8")) as Record<string, string>; }
-  catch { return {}; }
-}
-
-/** Read a secret the mesh mounted at a file path (an own-secret delivered by `secret accept`);
- *  absent or unreadable yields undefined so callers fall back rather than crash. */
-function readSecret(file?: string): string | undefined {
-  if (!file) return undefined;
-  try { return readFileSync(file, "utf8").trim(); }
-  catch { return undefined; }
-}
-
-export class NzbgetClient {
-  readonly rpcUrl: string;
-  private readonly auth: string;
-
-  constructor(url: string, user: string, password: string) {
-    this.rpcUrl = `${url.replace(/\/$/, "")}/jsonrpc`;
-    this.auth = Buffer.from(`${user}:${password}`).toString("base64");
-  }
-
-  /**
-   * Build from the module's resolved environment. URL and password are read from MESH_NZBGET_URL
-   * and MESH_NZBGET_PASSWORD; both must be present — an unconfigured NZBGet throws rather than
-   * pretend to be reachable, so the tools/events simply do not load (the harness treats the throw
-   * as "exposes nothing"). The control username defaults to "nzbget", NZBGet's own default.
-   */
-  static fromEnv(env: NodeJS.ProcessEnv = process.env): NzbgetClient {
-    const cfg = meshConfig(env.MESH_NZBGET_CONFIG_FILE);
-    const url = cfg.url ?? env.MESH_NZBGET_URL;
-    const password = cfg.password ?? readSecret(env.MESH_NZBGET_PASSWORD_FILE) ?? env.MESH_NZBGET_PASSWORD;
-    if (!url || !password) {
-      throw new Error("NZBGet not configured — set MESH_NZBGET_URL and MESH_NZBGET_PASSWORD");
-    }
-    const user = cfg.user ?? env.MESH_NZBGET_USER ?? "nzbget";
-    return new NzbgetClient(url, user, password);
-  }
-
-  private async rpc<T>(method: string, params: unknown[] = []): Promise<T> {
-    const res = await fetch(this.rpcUrl, {
-      method: "POST",
-      headers: { "Content-Type": "application/json", Authorization: `Basic ${this.auth}` },
-      body: JSON.stringify({ method, params, id: 1 }),
-    });
-    if (!res.ok) throw new Error(`NZBGet API ${method}: ${res.status} ${await res.text()}`);
-    const data = (await res.json()) as { result?: T; error?: unknown };
-    if (data.error) throw new Error(`NZBGet RPC ${method}: ${JSON.stringify(data.error)}`);
-    return data.result as T;
-  }
-
-  async getVersion(): Promise<string> {
-    return this.rpc<string>("version");
-  }
-
-  async getStatus(): Promise<NzbgetStatus> {
-    const s = await this.rpc<Record<string, number | boolean>>("status");
-    const lo = Number(s.DownloadRateLo ?? 0);
-    const hi = Number(s.DownloadRateHi ?? 0);
-    return {
-      speedBytesPerSec: lo + hi * 4294967296,
-      remainingMB: Number(s.RemainingSizeMB ?? 0),
-      downloadedTodayMB: Number(s.DaySizeMB ?? 0),
-      downloadedMonthMB: Number(s.MonthSizeMB ?? 0),
-      freeDiskMB: Number(s.FreeDiskSpaceMB ?? 0),
-      paused: Boolean(s.DownloadPaused),
-      postJobs: Number(s.PostJobCount ?? 0),
-      uptimeSec: Number(s.UpTimeSec ?? 0),
-    };
-  }
-
-  async getQueue(): Promise<NzbgetQueueItem[]> {
-    const groups = await this.rpc<Record<string, any>[]>("listgroups", [0]);
-    return groups.map((g) => {
-      const size = Number(g.FileSizeMB ?? 0);
-      const remaining = Number(g.RemainingSizeMB ?? 0);
-      return {
-        id: Number(g.NZBID),
-        name: String(g.NZBName ?? "Unknown"),
-        status: String(g.Status ?? "unknown"),
-        category: String(g.Category ?? ""),
-        sizeMB: size,
-        remainingMB: remaining,
-        percent: size > 0 ? Math.round(((size - remaining) / size) * 100) : 0,
-      };
-    });
-  }
-
-  async getHistory(limit = 20): Promise<NzbgetHistoryItem[]> {
-    const history = await this.rpc<Record<string, any>[]>("history", [false]);
-    return history.slice(0, limit).map((h) => {
-      const status = String(h.Status ?? "");
-      return {
-        id: Number(h.NZBID),
-        name: String(h.Name ?? "Unknown"),
-        status,
-        category: String(h.Category ?? ""),
-        sizeMB: Number(h.FileSizeMB ?? 0),
-        success: status.startsWith("SUCCESS"),
-      };
-    });
-  }
-
-  /** Queue an NZB by URL. Returns the new NZBID; a non-positive id means NZBGet refused it. */
-  async add(url: string, category = "", priority = 0, paused = false): Promise<number> {
-    const id = await this.rpc<number>("append", [
-      "", url, category, priority, false, paused, "", 0, "SCORE", false, [],
-    ]);
-    if (!id || id <= 0) throw new Error("NZBGet refused the NZB (append returned 0)");
-    return id;
-  }
-
-  async pauseAll(): Promise<void> {
-    await this.rpc("pausedownload");
-  }
-
-  async resumeAll(): Promise<void> {
-    await this.rpc("resumedownload");
-  }
-
-  async pauseItem(id: number): Promise<void> {
-    await this.rpc("editqueue", ["GroupPause", "", [id]]);
-  }
-
-  async resumeItem(id: number): Promise<void> {
-    await this.rpc("editqueue", ["GroupResume", "", [id]]);
-  }
-
-  /** Delete an item from the queue or from history. */
-  async delete(id: number, from: "queue" | "history" = "queue"): Promise<void> {
-    await this.rpc("editqueue", [from === "history" ? "HistoryDelete" : "GroupDelete", "", [id]]);
-  }
-}

modules/nzbget/index.ts

@@ -1,64 +0,0 @@
-// nzbget's events. The tool runtime imports this once the broker is bound. It watches the download
-// queue and the history and turns their comings and goings into mesh events.
-//
-// Emits (novox/hq ADR 0041/0042):
-//   module.nzbget.download.added       — an NZB entered the queue
-//   module.nzbget.download.completed   — an NZB finished successfully (left the queue, landed in
-//                                        history as SUCCESS). This exact routing key is what the
-//                                        plex module consumes (module.*.download.completed) to
-//                                        rescan, so the new file becomes a visible item.
-// Consumes: none.
-//
-// Two diffs, each primed silently on the first look (like plex's and sonarr's index.ts) so a
-// restart mid-download does not re-announce everything already in flight or already finished. The
-// queue tells us what was grabbed; history — not the queue's disappearance — tells us what actually
-// succeeded, since a failed or deleted download also leaves the queue.
-
-import { emit } from "@novox/mesh-sdk/events";
-import { NzbgetClient } from "./client.js";
-
-const nzbget = NzbgetClient.fromEnv();
-
-const inQueue = new Set<number>();
-let queuePrimed = false;
-async function pollQueue(): Promise<void> {
-  const items = await nzbget.getQueue();
-  const now = new Set(items.map((i) => i.id));
-  if (queuePrimed) {
-    for (const item of items) {
-      if (!inQueue.has(item.id)) {
-        await emit("download.added", { name: item.name, category: item.category, sizeMB: item.sizeMB });
-      }
-    }
-  }
-  inQueue.clear();
-  for (const id of now) inQueue.add(id);
-  queuePrimed = true;
-}
-
-const seenHistory = new Set<number>();
-let historyPrimed = false;
-async function pollHistory(): Promise<void> {
-  const items = await nzbget.getHistory(50);
-  for (const item of items) {
-    if (!seenHistory.has(item.id)) {
-      // A newly-appeared history entry is a completion only if it actually succeeded; a failure or
-      // a manual delete lands in history too, and neither is a "download.completed".
-      if (historyPrimed && item.success) {
-        await emit("download.completed", { name: item.name, category: item.category, sizeMB: item.sizeMB });
-      }
-      seenHistory.add(item.id);
-    }
-  }
-  historyPrimed = true;
-}
-
-const tick = (fn: () => Promise<void>, everyMs: number): void => {
-  const run = (): void => void fn().catch((err) => console.error(`[nzbget] ${err}`));
-  setInterval(run, everyMs);
-  run();
-};
-tick(pollQueue, 20_000);
-tick(pollHistory, 30_000);
-
-console.log("[nzbget] watching the queue and history, emitting adds and completions");

modules/nzbget/module.json

@@ -1,117 +0,0 @@
-{
-  "module": "nzbget",
-  "version": "1",
-  "capabilities": [
-    "container-runtime"
-  ],
-  "emits": [
-    "download.added",
-    "download.completed"
-  ],
-  "consumes": [],
-  "own-secrets": {
-    "broker": "${dir:mesh-state}/broker",
-    "password": "${dir:mesh-state}/password"
-  },
-  "listens": [
-    {
-      "name": "web",
-      "port": 6789,
-      "protocol": "tcp",
-      "from": "mesh",
-      "why": "the download client's pages"
-    }
-  ],
-  "accesses": [
-    {
-      "id": "downloads",
-      "path": "/services/media/downloads",
-      "mode": "read-write"
-    }
-  ],
-  "resources": [
-    {
-      "id": "mesh-state",
-      "type": "directory",
-      "mode": "0700",
-      "place": "mesh"
-    },
-    {
-      "id": "config",
-      "type": "directory",
-      "path": "/services/nzbget/config",
-      "mode": "0700",
-      "owner": "1000:1000"
-    },
-    {
-      "id": "server",
-      "type": "container",
-      "name": "nzbget",
-      "image": "lscr.io/linuxserver/nzbget@sha256:5f3d3fa71029004156eff2cbf4ef4455ce4ce59517cf13fa7d1d7c8a4cd2c8a4",
-      "env": {
-        "PUID": "1000",
-        "PGID": "1000",
-        "TZ": "Etc/UTC"
-      },
-      "ports": [
-        "6789"
-      ],
-      "volumes": [
-        "/services/nzbget/config:/config",
-        "${access:downloads}:/downloads"
-      ]
-    },
-    {
-      "id": "runtime-config",
-      "type": "file",
-      "path": "${dir:mesh-state}/config.json",
-      "mode": "0600",
-      "content": "{}\n",
-      "merge": "json"
-    },
-    {
-      "id": "runtime",
-      "type": "container",
-      "name": "mesh-nzbget",
-      "network": "host",
-      "volumes": [
-        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
-        "${dir:mesh-state}/password:/run/secrets/password:ro",
-        "${dir:mesh-state}/config.json:/run/config/config.json:ro",
-        "/services/nzbget/config:/var/lib/nzbget/config:ro"
-      ],
-      "env": {
-        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_NZBGET_URL": "http://127.0.0.1:6789",
-        "MESH_NZBGET_PASSWORD_FILE": "/run/secrets/password",
-        "MESH_NZBGET_CONFIG_FILE": "/run/config/config.json",
-        "MESH_NZBGET_CONFIG_DIR": "/var/lib/nzbget/config"
-      },
-      "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",
-        "kind": "image",
-        "from": "Dockerfile"
-      }
-    ]
-  }
-}

modules/nzbget/package.json

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

modules/nzbget/tools/index.ts

@@ -1,88 +0,0 @@
-// nzbget's tools — ported from the shared hal sdk (novox/hq ADR 0039), importing nzbget's own
-// client. They return structured data (not the pre-formatted text hal returned); the mesh serves
-// them through the sdk's tool harness.
-
-import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
-import { NzbgetClient } from "../client.js";
-
-export function getNzbgetTools(nzbget: NzbgetClient): ToolDefinition[] {
-  return [
-    {
-      name: "nzbget_status",
-      description: "NZBGet server status: download speed, queue remaining, disk free, paused state.",
-      input: {},
-      run: async () => nzbget.getStatus(),
-    },
-    {
-      name: "nzbget_queue",
-      description: "List the current NZBGet download queue — what is downloading and how far along.",
-      input: {},
-      run: async () => {
-        const items = await nzbget.getQueue();
-        return { count: items.length, items };
-      },
-    },
-    {
-      name: "nzbget_history",
-      description: "Recent NZBGet download history, newest first — completed, failed and deleted items.",
-      input: { limit: { type: "number", description: "how many entries (default 20)" } },
-      run: async (args) => {
-        const items = await nzbget.getHistory(args.limit ? Number(args.limit) : 20);
-        return { count: items.length, items };
-      },
-    },
-    {
-      name: "nzbget_add",
-      description: "Queue an NZB download by URL, optionally into a category.",
-      input: {
-        url: { type: "string", description: "URL to the NZB file" },
-        category: { type: "string", description: "category name (determines download directory)" },
-        priority: { type: "number", description: "-100 very low … 0 normal … 100 very high (default 0)" },
-        paused: { type: "boolean", description: "add in paused state (default false)" },
-      },
-      run: async (args) => {
-        const id = await nzbget.add(
-          String(args.url),
-          args.category ? String(args.category) : "",
-          args.priority ? Number(args.priority) : 0,
-          args.paused === true || args.paused === "true",
-        );
-        return { added: id, category: args.category ? String(args.category) : null };
-      },
-    },
-    {
-      name: "nzbget_pause",
-      description: "Pause or resume all NZBGet downloads.",
-      input: { resume: { type: "boolean", description: "true to resume, false to pause (default false)" } },
-      run: async (args) => {
-        const resume = args.resume === true || args.resume === "true";
-        if (resume) await nzbget.resumeAll();
-        else await nzbget.pauseAll();
-        return { paused: !resume };
-      },
-    },
-    {
-      name: "nzbget_delete",
-      description: "Delete an NZB from the queue or from history by its NZBID.",
-      input: {
-        id: { type: "number", description: "the NZBID to delete" },
-        from: { type: "string", description: "'queue' (default) or 'history'" },
-      },
-      run: async (args) => {
-        const from = args.from === "history" ? "history" : "queue";
-        await nzbget.delete(Number(args.id), from);
-        return { deleted: Number(args.id), from };
-      },
-    },
-  ];
-}
-
-// The tools exist only when NZBGet is configured; without a URL and password, nzbget contributes
-// none rather than failing the whole runtime.
-registerModuleTools("nzbget", (env) => {
-  try {
-    return getNzbgetTools(NzbgetClient.fromEnv(env));
-  } catch {
-    return [];
-  }
-});

modules/nzbget/tsconfig.json

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

modules/ombi/Dockerfile

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

modules/ombi/client.ts

@@ -1,122 +0,0 @@
-// The Ombi API client — ombi's own code, living in the module (novox/hq ADR 0039). Ombi is the
-// request front-end: viewers ask for movies and shows, and an operator approves them. This client
-// talks its /api/v1 REST API (keyed by an ApiKey header); ombi's tools and events import it.
-
-import { readFileSync } from "node:fs";
-
-export interface OmbiRequest {
-  kind: "movie" | "tv";
-  id: number;
-  title: string;
-  requestedBy?: string;
-  requestedDate?: string;
-  approved: boolean;
-  available: boolean;
-  denied: boolean;
-  tmdbId?: number;
-}
-
-export interface RequestCounts {
-  pending: number;
-  approved: number;
-  available: number;
-}
-
-/** The settings-merged config the mesh delivers (novox/hq ADR 0046): { url, apiKey, token, password, user, ... }. */
-function meshConfig(file?: string): Record<string, string> {
-  if (!file) return {};
-  try { return JSON.parse(readFileSync(file, "utf8")) as Record<string, string>; }
-  catch { return {}; }
-}
-
-/** Read a secret the mesh mounted at a file path (an own-secret delivered by `secret accept`);
- *  absent or unreadable yields undefined so callers fall back rather than crash. */
-function readSecret(file?: string): string | undefined {
-  if (!file) return undefined;
-  try { return readFileSync(file, "utf8").trim(); }
-  catch { return undefined; }
-}
-
-export class OmbiClient {
-  readonly baseUrl: string;
-
-  constructor(
-    url: string,
-    private readonly apiKey: string,
-  ) {
-    this.baseUrl = url.replace(/\/$/, "");
-  }
-
-  /** Build from the module's resolved environment. Ombi's API is keyed; without URL and key there
-   *  is nothing to talk to, so this throws rather than run half-configured. */
-  static fromEnv(env: NodeJS.ProcessEnv = process.env): OmbiClient {
-    const cfg = meshConfig(env.MESH_OMBI_CONFIG_FILE);
-    const url = cfg.url ?? env.MESH_OMBI_URL;
-    const apiKey = cfg.apiKey ?? readSecret(env.MESH_OMBI_API_KEY_FILE) ?? env.MESH_OMBI_API_KEY;
-    if (!url) throw new Error("no Ombi URL — set MESH_OMBI_URL");
-    if (!apiKey) throw new Error("no Ombi API key — set MESH_OMBI_API_KEY");
-    return new OmbiClient(url, apiKey);
-  }
-
-  private async request(method: string, path: string, body?: unknown): Promise<any> {
-    const res = await fetch(`${this.baseUrl}/api/v1${path}`, {
-      method,
-      headers: {
-        ApiKey: this.apiKey,
-        Accept: "application/json",
-        ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
-      },
-      body: body !== undefined ? JSON.stringify(body) : undefined,
-    });
-    if (!res.ok) throw new Error(`Ombi API ${method} ${path}: ${res.status} ${await res.text()}`);
-    const text = await res.text();
-    return text ? JSON.parse(text) : {};
-  }
-
-  /** All requests, movies and TV together — who asked for what, and where each stands. */
-  async getRequests(): Promise<OmbiRequest[]> {
-    const [movies, tv] = await Promise.all([
-      this.request("GET", "/Request/movie"),
-      this.request("GET", "/Request/tv"),
-    ]);
-    const films: OmbiRequest[] = (Array.isArray(movies) ? movies : []).map((r: any) => ({
-      kind: "movie" as const,
-      id: r.id,
-      title: r.title ?? "Unknown",
-      requestedBy: r.requestedUser?.userName ?? r.requestedUser?.userAlias,
-      requestedDate: r.requestedDate,
-      approved: Boolean(r.approved),
-      available: Boolean(r.available),
-      denied: Boolean(r.denied),
-      tmdbId: r.theMovieDbId,
-    }));
-    // TV requests carry per-season child requests; the top-level record is approved when all its
-    // children are, which is the grain an operator acts on.
-    const shows: OmbiRequest[] = (Array.isArray(tv) ? tv : []).map((r: any) => {
-      const children: any[] = r.childRequests ?? [];
-      return {
-        kind: "tv" as const,
-        id: r.id,
-        title: r.title ?? "Unknown",
-        requestedBy: children[0]?.requestedUser?.userName,
-        requestedDate: children[0]?.requestedDate,
-        approved: children.length > 0 && children.every((c) => c.approved),
-        available: children.length > 0 && children.every((c) => c.available),
-        denied: children.some((c) => c.denied),
-        tmdbId: r.theMovieDbId,
-      };
-    });
-    return [...films, ...shows];
-  }
-
-  /** Live pending/approved/available counts — a one-line health read without listing everything. */
-  async getCounts(): Promise<RequestCounts> {
-    const c = await this.request("GET", "/Request/count");
-    return { pending: c.pending ?? 0, approved: c.approved ?? 0, available: c.available ?? 0 };
-  }
-
-  /** Approve a request. TV approval fans out to the request's child (per-season) requests. */
-  async approve(kind: "movie" | "tv", id: number): Promise<void> {
-    await this.request("POST", `/Request/${kind}/approve`, { id });
-  }
-}

modules/ombi/index.ts

@@ -1,58 +0,0 @@
-// ombi's events. The tool runtime imports this once the broker is bound. Ombi's timeline is the
-// request lifecycle: a viewer files a request, and later an operator approves it. Both transitions
-// are worth announcing — the mesh can notify on a new request, and act on an approval (that is when
-// a downloader should start looking).
-//
-// Emits (novox/hq ADR 0041/0042):
-//   module.ombi.request.created    — a viewer filed a new request
-//   module.ombi.request.approved   — a request was approved
-//
-// Ombi is the origin of these decisions, not a reactor to the mesh, so it consumes nothing.
-//
-// Both events are observation-based: poll the request list and diff. Creation is diffed on the set
-// of request ids; approval on each request's approved flag flipping true. Primed silently on the
-// first look, or a restart would re-announce every existing request and approval.
-
-import { emit } from "@novox/mesh-sdk/events";
-import { OmbiClient, type OmbiRequest } from "./client.js";
-
-const ombi = OmbiClient.fromEnv();
-
-// Remember each seen request and whether it was approved last time, keyed by kind+id (ids are only
-// unique within a kind).
-const approvedState = new Map<string, boolean>();
-let primed = false;
-
-const keyOf = (r: OmbiRequest): string => `${r.kind}:${r.id}`;
-
-async function pollRequests(): Promise<void> {
-  const requests = await ombi.getRequests();
-  for (const r of requests) {
-    const key = keyOf(r);
-    const known = approvedState.has(key);
-    if (primed && !known) {
-      await emit("request.created", {
-        kind: r.kind,
-        id: r.id,
-        title: r.title,
-        requestedBy: r.requestedBy,
-        tmdbId: r.tmdbId,
-      });
-    }
-    // Approval: the flag went from false to true for a request we already knew about.
-    if (primed && known && r.approved && approvedState.get(key) === false) {
-      await emit("request.approved", { kind: r.kind, id: r.id, title: r.title, tmdbId: r.tmdbId });
-    }
-    approvedState.set(key, r.approved);
-  }
-  primed = true;
-}
-
-const tick = (fn: () => Promise<void>, everyMs: number): void => {
-  const run = (): void => void fn().catch((err) => console.error(`[ombi] ${err}`));
-  setInterval(run, everyMs);
-  run();
-};
-tick(pollRequests, 30_000);
-
-console.log("[ombi] watching requests for new filings and approvals");

modules/ombi/module.json

@@ -1,120 +0,0 @@
-{
-  "module": "ombi",
-  "version": "1",
-  "capabilities": [
-    "container-runtime"
-  ],
-  "emits": [
-    "request.created",
-    "request.approved"
-  ],
-  "own-secrets": {
-    "broker": "${dir:mesh-state}/broker",
-    "api-key": "${dir:mesh-state}/api-key"
-  },
-  "listens": [
-    {
-      "name": "web",
-      "port": 3579,
-      "protocol": "tcp",
-      "from": "mesh",
-      "why": "requests from viewers"
-    }
-  ],
-  "resources": [
-    {
-      "id": "mesh-state",
-      "type": "directory",
-      "mode": "0700",
-      "place": "mesh"
-    },
-    {
-      "id": "config",
-      "type": "directory",
-      "path": "/services/ombi/config",
-      "mode": "0700",
-      "owner": "1000:1000"
-    },
-    {
-      "id": "server",
-      "type": "container",
-      "name": "ombi",
-      "image": "lscr.io/linuxserver/ombi@sha256:a6f76ac521ba01eee2e9f0c23a3fed22e56630d97a04d5eeaeaa36c1e681640d",
-      "env": {
-        "PUID": "1000",
-        "PGID": "1000",
-        "TZ": "Etc/UTC"
-      },
-      "ports": [
-        "3579"
-      ],
-      "volumes": [
-        "/services/ombi/config:/config"
-      ]
-    },
-    {
-      "id": "runtime-config",
-      "type": "file",
-      "path": "${dir:mesh-state}/config.json",
-      "mode": "0600",
-      "content": "{}\n",
-      "merge": "json"
-    },
-    {
-      "id": "runtime",
-      "type": "container",
-      "name": "mesh-ombi",
-      "network": "host",
-      "volumes": [
-        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
-        "${dir:mesh-state}/api-key:/run/secrets/api-key:ro",
-        "${dir:mesh-state}/config.json:/run/config/config.json:ro",
-        "/services/ombi/config:/var/lib/ombi/config:ro"
-      ],
-      "env": {
-        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_OMBI_URL": "http://127.0.0.1:3579",
-        "MESH_OMBI_API_KEY_FILE": "/run/secrets/api-key",
-        "MESH_OMBI_CONFIG_FILE": "/run/config/config.json",
-        "MESH_OMBI_CONFIG_DIR": "/var/lib/ombi/config"
-      },
-      "restart-on": [
-        "runtime-config"
-      ],
-      "artifact": "runtime"
-    }
-  ],
-  "requires": [
-    "route"
-  ],
-  "contributes": {
-    "route": {
-      "label": "ombi",
-      "endpoint": "web"
-    }
-  },
-  "binds": {
-    "route": "${dir:mesh-state}/route.json"
-  },
-  "build": {
-    "on": [
-      {
-        "arg": "BUILD_BASE",
-        "module": "mesh-tools",
-        "artifact": "build"
-      },
-      {
-        "arg": "RUNTIME_BASE",
-        "module": "mesh-tools",
-        "artifact": "runtime"
-      }
-    ],
-    "artifacts": [
-      {
-        "name": "runtime",
-        "kind": "image",
-        "from": "Dockerfile"
-      }
-    ]
-  }
-}

modules/ombi/package.json

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

modules/ombi/tools/index.ts

@@ -1,46 +0,0 @@
-// ombi's tools — its own code (novox/hq ADR 0039), importing ombi's client. They return structured
-// data; the mesh serves them through the sdk's tool harness.
-
-import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
-import { OmbiClient } from "../client.js";
-
-export function getOmbiTools(ombi: OmbiClient): ToolDefinition[] {
-  return [
-    {
-      name: "ombi_requests",
-      description: "List media requests — movies and shows — with who asked and whether each is approved or available.",
-      input: { pending: { type: "boolean", description: "only requests not yet approved (default false)" } },
-      run: async (args) => {
-        let requests = await ombi.getRequests();
-        if (args.pending) requests = requests.filter((r) => !r.approved && !r.denied);
-        const counts = await ombi.getCounts();
-        return { counts, count: requests.length, requests };
-      },
-    },
-    {
-      name: "ombi_approve",
-      description: "Approve a media request by its kind and id (from ombi_requests).",
-      input: {
-        kind: { type: "string", description: '"movie" or "tv"' },
-        id: { type: "number", description: "the request id" },
-      },
-      run: async (args) => {
-        const kind = String(args.kind);
-        if (kind !== "movie" && kind !== "tv") throw new Error('kind must be "movie" or "tv"');
-        const id = Number(args.id);
-        await ombi.approve(kind, id);
-        return { approved: { kind, id } };
-      },
-    },
-  ];
-}
-
-// Exposed only when Ombi is configured; otherwise ombi contributes no tools rather than failing the
-// whole runtime.
-registerModuleTools("ombi", (env) => {
-  try {
-    return getOmbiTools(OmbiClient.fromEnv(env));
-  } catch {
-    return [];
-  }
-});

modules/ombi/tsconfig.json

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

modules/plex/Dockerfile

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

modules/plex/client.ts

@@ -1,158 +0,0 @@
-// The Plex API client — plex's own code, living in the module (novox/hq ADR 0039). Moved out of the
-// shared hal sdk, where a change to Plex's API rebuilt everything; here it rebuilds only plex. Both
-// this module's tools and its events entrypoint import it, and nothing outside plex does.
-
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-
-/** Read a secret the mesh mounted at a file path (an own-secret); absent or unreadable yields
- *  undefined, so callers can fall back rather than crash. */
-function readSecret(path: string | undefined): string | undefined {
-  if (!path) return undefined;
-  try {
-    return readFileSync(path, "utf8").trim();
-  } catch {
-    return undefined;
-  }
-}
-
-export interface PlexLibrary {
-  key: string;
-  title: string;
-  type: string;
-  count?: number;
-}
-
-export interface PlexSession {
-  key: string;
-  title: string;
-  user: string;
-  player: string;
-  state: string;
-  type: string;
-}
-
-export interface PlexItem {
-  title: string;
-  type: string;
-  year?: number;
-  summary?: string;
-  addedAt?: string;
-}
-
-export class PlexClient {
-  readonly baseUrl: string;
-
-  constructor(
-    url: string,
-    private readonly token: string,
-  ) {
-    this.baseUrl = url.replace(/\/$/, "");
-  }
-
-  /**
-   * Build from the module's resolved environment. The token is read from MESH_PLEX_TOKEN, or
-   * discovered from the server's own Preferences.xml under the data directory — the same file Plex
-   * writes it to, so a running server needs nothing configured by hand.
-   */
-  static fromEnv(env: NodeJS.ProcessEnv = process.env): PlexClient {
-    const url = env.MESH_PLEX_URL ?? `http://127.0.0.1:${env.PLEX_PORT ?? "32400"}`;
-    const dataDir = env.MESH_PLEX_DATA_DIR ?? "/var/lib/plex";
-    // The operator-provided token is an own-secret the mesh mounts at MESH_PLEX_TOKEN_FILE (delivered
-    // by `secret accept`); prefer it, fall back to a bare env var, then to discovery from the data dir.
-    const token = readSecret(env.MESH_PLEX_TOKEN_FILE) ?? env.MESH_PLEX_TOKEN ?? PlexClient.detectToken(dataDir);
-    if (!token) throw new Error("no Plex token — set MESH_PLEX_TOKEN or make the data dir readable");
-    return new PlexClient(url, token);
-  }
-
-  /** Discover the token from the server's Preferences.xml, falling back to null. */
-  static detectToken(dataDir: string): string | null {
-    const prefs = join(dataDir, "config", "Library", "Application Support", "Plex Media Server", "Preferences.xml");
-    if (existsSync(prefs)) {
-      const match = readFileSync(prefs, "utf8").match(/PlexOnlineToken="([^"]+)"/);
-      if (match) return match[1];
-    }
-    return null;
-  }
-
-  private async get(path: string): Promise<any> {
-    const url = `${this.baseUrl}${path}`;
-    const sep = url.includes("?") ? "&" : "?";
-    const res = await fetch(`${url}${sep}X-Plex-Token=${this.token}`, { headers: { Accept: "application/json" } });
-    if (!res.ok) throw new Error(`Plex API ${path}: ${res.status} ${await res.text()}`);
-    return res.json();
-  }
-
-  async getServerInfo(): Promise<{ name: string; version: string; platform: string }> {
-    const mc = (await this.get("/")).MediaContainer;
-    return { name: mc.friendlyName || mc.machineIdentifier, version: mc.version, platform: mc.platform };
-  }
-
-  async getLibraries(): Promise<PlexLibrary[]> {
-    const dirs = (await this.get("/library/sections")).MediaContainer?.Directory ?? [];
-    return dirs.map((d: any) => ({ key: d.key, title: d.title, type: d.type, count: d.count }));
-  }
-
-  async getSessions(): Promise<PlexSession[]> {
-    const sessions = (await this.get("/status/sessions")).MediaContainer?.Metadata ?? [];
-    return sessions.map((s: any) => ({
-      key: s.sessionKey ?? s.ratingKey,
-      title: s.title + (s.grandparentTitle ? ` (${s.grandparentTitle})` : ""),
-      user: s.User?.title ?? "unknown",
-      player: s.Player?.title ?? s.Player?.product ?? "unknown",
-      state: s.Player?.state ?? "unknown",
-      type: s.type,
-    }));
-  }
-
-  async search(query: string): Promise<PlexItem[]> {
-    const hubs = (await this.get(`/hubs/search?query=${encodeURIComponent(query)}&limit=20`)).MediaContainer?.Hub ?? [];
-    const results: PlexItem[] = [];
-    for (const hub of hubs) {
-      for (const m of hub.Metadata ?? []) {
-        results.push({
-          title: m.title + (m.grandparentTitle ? ` (${m.grandparentTitle})` : ""),
-          type: m.type,
-          year: m.year,
-          summary: m.summary?.slice(0, 200),
-        });
-      }
-    }
-    return results;
-  }
-
-  async getRecentlyAdded(limit = 20): Promise<PlexItem[]> {
-    const items = (await this.get(`/library/recentlyAdded?X-Plex-Container-Size=${limit}`)).MediaContainer?.Metadata ?? [];
-    return items.map((m: any) => ({
-      title: m.title + (m.grandparentTitle ? ` (${m.grandparentTitle})` : ""),
-      type: m.type,
-      year: m.year,
-      summary: m.summary?.slice(0, 200),
-      addedAt: m.addedAt ? new Date(m.addedAt * 1000).toISOString() : undefined,
-    }));
-  }
-
-  /** Ask Plex to rescan a library section — how a "new media arrived" event becomes a visible item. */
-  async refreshLibrary(key: string): Promise<void> {
-    await this.get(`/library/sections/${key}/refresh`);
-  }
-
-  /** Rescan every library, for when what arrived is not known to belong to one. */
-  async refreshAll(): Promise<void> {
-    for (const library of await this.getLibraries()) await this.refreshLibrary(library.key);
-  }
-
-  /**
-   * A health probe that never throws: report whether the Plex server this client is pointed at
-   * answers, and identify it when it does. Every other call assumes the server is up; this is the
-   * one that tells the mesh whether it is, so a diagnosis does not start from a stack trace.
-   */
-  async reachable(): Promise<{ reachable: boolean; url: string; server?: { name: string; version: string }; error?: string }> {
-    try {
-      const info = await this.getServerInfo();
-      return { reachable: true, url: this.baseUrl, server: { name: info.name, version: info.version } };
-    } catch (err) {
-      return { reachable: false, url: this.baseUrl, error: err instanceof Error ? err.message : String(err) };
-    }
-  }
-}

modules/plex/index.ts

@@ -1,68 +0,0 @@
-// plex's events. The tool runtime imports this once the broker is bound, and it does two things:
-// it watches the server and emits what happened, and it reacts to the mesh's media events.
-//
-// Emits (novox/hq ADR 0041/0042):
-//   module.plex.playback.started / .stopped   — someone began or ended watching
-//   module.plex.item.added                     — a new item appeared in a library
-// Consumes:
-//   module.*.download.completed                — a downloader finished; rescan so the file shows up
-//
-// The polling is deliberately unhurried: Plex is a neighbour on the same node, and an event a few
-// seconds late is an event, whereas hammering the server for immediacy nobody asked for is not.
-
-import { emit, on } from "@novox/mesh-sdk/events";
-import { PlexClient, type PlexSession } from "./client.js";
-
-const plex = PlexClient.fromEnv();
-
-// Playback, by diffing the set of active sessions. Primed silently on the first look so a server
-// that was already streaming when this started does not announce it as freshly begun.
-const active = new Map<string, PlexSession>();
-let playbackPrimed = false;
-async function pollSessions(): Promise<void> {
-  const sessions = await plex.getSessions();
-  const now = new Map(sessions.map((s) => [s.key, s]));
-  if (playbackPrimed) {
-    for (const [key, s] of now) {
-      if (!active.has(key)) await emit("playback.started", { title: s.title, user: s.user, player: s.player, kind: s.type });
-    }
-    for (const [key, s] of active) {
-      if (!now.has(key)) await emit("playback.stopped", { title: s.title, user: s.user, player: s.player });
-    }
-  }
-  active.clear();
-  for (const [key, s] of now) active.set(key, s);
-  playbackPrimed = true;
-}
-
-// New items, by diffing recently-added. Primed silently too, or a restart would re-announce the
-// whole recent list as new.
-const seen = new Set<string>();
-let itemsPrimed = false;
-async function pollRecent(): Promise<void> {
-  const items = await plex.getRecentlyAdded(20);
-  for (const item of items) {
-    const id = `${item.title}@${item.addedAt ?? ""}`;
-    if (!seen.has(id)) {
-      if (itemsPrimed) await emit("item.added", item);
-      seen.add(id);
-    }
-  }
-  itemsPrimed = true;
-}
-
-// A downloader finished somewhere on the mesh: rescan, so what it fetched becomes a visible item
-// rather than a file Plex has not noticed. Idempotent — a rescan too many costs a little disk I/O.
-await on("*.download.completed", async () => {
-  await plex.refreshAll();
-});
-
-const tick = (fn: () => Promise<void>, everyMs: number): void => {
-  const run = (): void => void fn().catch((err) => console.error(`[plex] ${err}`));
-  setInterval(run, everyMs);
-  run();
-};
-tick(pollSessions, 15_000);
-tick(pollRecent, 60_000);
-
-console.log("[plex] watching sessions and recently-added, reacting to downloads");

modules/plex/module.json

@@ -1,137 +0,0 @@
-{
-  "module": "plex",
-  "version": "1",
-  "capabilities": [
-    "container-runtime"
-  ],
-  "emits": [
-    "playback.started",
-    "playback.stopped",
-    "item.added"
-  ],
-  "consumes": [
-    "*.download.completed"
-  ],
-  "own-secrets": {
-    "broker": "${dir:mesh-state}/broker",
-    "token": "${dir:mesh-state}/token"
-  },
-  "listens": [
-    {
-      "name": "stream",
-      "port": 32400,
-      "protocol": "tcp",
-      "from": "mesh",
-      "why": "streaming and the app; reaching it from outside is a route grant later"
-    }
-  ],
-  "accesses": [
-    {
-      "id": "movies",
-      "path": "/services/media/movies",
-      "mode": "read"
-    },
-    {
-      "id": "series",
-      "path": "/services/media/series",
-      "mode": "read"
-    },
-    {
-      "id": "anime",
-      "path": "/services/media/anime",
-      "mode": "read"
-    },
-    {
-      "id": "music",
-      "path": "/services/media/music",
-      "mode": "read"
-    },
-    {
-      "id": "audiobooks",
-      "path": "/services/media/audiobooks",
-      "mode": "read"
-    }
-  ],
-  "resources": [
-    {
-      "id": "mesh-state",
-      "type": "directory",
-      "mode": "0700",
-      "place": "mesh"
-    },
-    {
-      "id": "config",
-      "type": "directory",
-      "path": "/services/plex/config",
-      "mode": "0700",
-      "owner": "1000:1000"
-    },
-    {
-      "id": "transcode",
-      "type": "directory",
-      "path": "/services/plex/transcode",
-      "mode": "0700",
-      "owner": "1000:1000"
-    },
-    {
-      "id": "server",
-      "type": "container",
-      "name": "plex",
-      "image": "plexinc/pms-docker@sha256:83a425ae9e133b1cb2cc3b809556e01c61cd8ff65c582e41b4374bc2210bac9e",
-      "network": "host",
-      "env": {
-        "PLEX_UID": "1000",
-        "PLEX_GID": "1000",
-        "TZ": "Etc/UTC"
-      },
-      "volumes": [
-        "/services/plex/config:/config",
-        "/services/plex/transcode:/transcode",
-        "${access:movies}:/movies",
-        "${access:series}:/series",
-        "${access:anime}:/anime",
-        "${access:music}:/music",
-        "${access:audiobooks}:/audiobooks"
-      ]
-    },
-    {
-      "id": "runtime",
-      "type": "container",
-      "name": "mesh-plex",
-      "network": "host",
-      "volumes": [
-        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
-        "${dir:mesh-state}/token:/run/secrets/token:ro",
-        "/services/plex/config:/var/lib/plex/config:ro"
-      ],
-      "env": {
-        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_PLEX_URL": "http://127.0.0.1:32400",
-        "MESH_PLEX_TOKEN_FILE": "/run/secrets/token",
-        "MESH_PLEX_DATA_DIR": "/var/lib/plex"
-      },
-      "artifact": "runtime"
-    }
-  ],
-  "build": {
-    "on": [
-      {
-        "arg": "BUILD_BASE",
-        "module": "mesh-tools",
-        "artifact": "build"
-      },
-      {
-        "arg": "RUNTIME_BASE",
-        "module": "mesh-tools",
-        "artifact": "runtime"
-      }
-    ],
-    "artifacts": [
-      {
-        "name": "runtime",
-        "kind": "image",
-        "from": "Dockerfile"
-      }
-    ]
-  }
-}

modules/plex/package.json

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

modules/plex/tools/index.ts

@@ -1,74 +0,0 @@
-// plex's tools — moved here from the shared sdk (novox/hq ADR 0039), importing plex's own client.
-// They return structured data; the mesh serves them through the sdk's tool harness.
-
-import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
-import { PlexClient } from "../client.js";
-
-export function getPlexTools(plex: PlexClient): ToolDefinition[] {
-  return [
-    {
-      name: "plex_status",
-      description: "Plex server status: server info, libraries, active sessions, recently added.",
-      input: {},
-      run: async () => {
-        const [server, libraries, sessions, recent] = await Promise.all([
-          plex.getServerInfo(),
-          plex.getLibraries(),
-          plex.getSessions(),
-          plex.getRecentlyAdded(10),
-        ]);
-        return { server, libraries, sessions, recentlyAdded: recent };
-      },
-    },
-    {
-      name: "plex_reachable",
-      description: "Health probe: whether the Plex server answers, and which server it is. Never fails.",
-      input: {},
-      run: async () => plex.reachable(),
-    },
-    {
-      name: "plex_search",
-      description: "Search across all Plex libraries — movies, shows, episodes, music.",
-      input: { query: { type: "string", description: "the search query" } },
-      run: async (args) => ({ query: String(args.query), results: await plex.search(String(args.query)) }),
-    },
-    {
-      name: "plex_sessions",
-      description: "Active Plex playback sessions — who is watching what, and where.",
-      input: {},
-      run: async () => {
-        const sessions = await plex.getSessions();
-        return { count: sessions.length, sessions };
-      },
-    },
-    {
-      name: "plex_recently_added",
-      description: "Recently added media in Plex.",
-      input: { limit: { type: "number", description: "how many items (default 20)" } },
-      run: async (args) => ({ items: await plex.getRecentlyAdded(args.limit ? Number(args.limit) : 20) }),
-    },
-    {
-      name: "plex_refresh",
-      description: "Ask Plex to rescan its libraries so new files on disk become visible items.",
-      input: { library: { type: "string", description: "a library section key; omitted rescans all" } },
-      run: async (args) => {
-        if (args.library) {
-          await plex.refreshLibrary(String(args.library));
-          return { refreshed: String(args.library) };
-        }
-        await plex.refreshAll();
-        return { refreshed: "all" };
-      },
-    },
-  ];
-}
-
-// The tools exist only when a token can be found; without one, plex contributes none rather than
-// failing the whole runtime.
-registerModuleTools("plex", (env) => {
-  try {
-    return getPlexTools(PlexClient.fromEnv(env));
-  } catch {
-    return [];
-  }
-});

modules/plex/tsconfig.json

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

modules/postgres/client.ts

@@ -25,12 +25,30 @@ export interface PgConn {
   readonly port: number;
   readonly user: string;
   readonly password: string;
+  /**
+   * The read-only login's password, which the mesh mints for this module (`own-secrets.reader`).
+   * Absent when the mesh has not delivered it: then a caller's statement is refused, never run as
+   * the admin (novox/hq issue 193).
+   */
+  readonly readerPassword?: string;
 }
 
+/**
+ * The login a caller's statement runs as (novox/hq issue 193). It may read every table and change
+ * nothing: `pg_read_all_data` and no other grant, and every transaction it opens is read-only by
+ * the server's own setting. A statement cannot climb out of a login the way it can out of a
+ * transaction wrapped around it as text: `COMMIT; DROP …` ended the old wrapper and ran the rest as
+ * the superuser, and even one read-only statement as a superuser can run a program on the server.
+ */
+export const READER = "mesh_store_reader";
+
 
 export class PostgresClient {
   constructor(private readonly conn: PgConn) {}
 
+  /** The reader is made once per process: idempotent, and repeating it re-sets a rotated password. */
+  private readerReady?: Promise<void>;
+
   /**
    * Build from the module's resolved environment. Reads MESH_POSTGRES_* first (the documented
    * names), falling back to the MESH_PROVISION_* keys the manifest already sets on the provisioner
@@ -54,7 +72,9 @@ export class PostgresClient {
     if (!host || !password) {
       throw new Error("postgres host or admin password is not set — postgres's own code cannot reach the server");
     }
-    return new PostgresClient({ host, port, user, password });
+    const readerPassword = env.MESH_POSTGRES_READER_PASSWORD ??
+      readSecretFile(env.MESH_POSTGRES_READER_PASSWORD_FILE);
+    return new PostgresClient({ host, port, user, password, readerPassword });
   }
 
   get host(): string {
@@ -143,11 +163,66 @@ export class PostgresClient {
     return res.rows.map((r) => ({ name: String(r.datname), sizeBytes: Number(r.size) }));
   }
 
-  /** Run a read-only SQL statement against a named database, for the postgres_query tool. */
-  async readOnlyQuery(database: string, sql: string): Promise<QueryResult> {
-    // The read-only guarantee is a wrapping transaction the server honours.
-    return this.query(`BEGIN TRANSACTION READ ONLY; ${sql}; ROLLBACK;`, database);
+  /**
+   * Make the read-only login, idempotently, with the password the mesh minted for it. Run as the
+   * admin, because only the admin can make a role.
+   */
+  async ensureReader(): Promise<void> {
+    const password = this.conn.readerPassword;
+    if (!password) throw readerMissing();
+    const roles = await this.query("SELECT 1 FROM pg_roles WHERE rolname = " + literal(READER));
+    const verb = roles.rows.length === 0 ? "CREATE" : "ALTER";
+    // Every attribute stated, so an existing role someone widened is narrowed again on every start.
+    await this.query(
+      `${verb} ROLE ${ident(READER)} WITH LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION ` +
+        `NOBYPASSRLS INHERIT PASSWORD ${literal(password)} VALID UNTIL 'infinity'`,
+    );
+    await this.query(`GRANT pg_read_all_data TO ${ident(READER)}`);
+    await this.query(`ALTER ROLE ${ident(READER)} SET default_transaction_read_only = on`);
+    await this.query(`ALTER ROLE ${ident(READER)} SET statement_timeout = '60s'`);
   }
+
+  /**
+   * Run a caller's statement against a named database as the read-only login, for the
+   * postgres_query tool and the store seat's `query` verb (novox/hq ADR 0159, issue 193).
+   *
+   * **Read-only by the login, not by text around the statement.** The statement is sent as it was
+   * given, as the reader, whose role can write nothing and whose transactions the server makes
+   * read-only. Never as the admin: without the reader's password the call is refused.
+   */
+  async readOnlyQuery(database: string, sql: string): Promise<QueryResult> {
+    this.readerReady ??= this.ensureReader().catch((err) => {
+      this.readerReady = undefined; // asked again next call, not failed for the process's life
+      throw err;
+    });
+    await this.readerReady;
+    const { stdout } = await run(
+      "psql",
+      // -q: no command tags, so the output is the header and the rows and nothing else — the tags
+      // were what came back as rows keyed by BEGIN.
+      ["-h", this.conn.host, "-p", String(this.conn.port), "-U", READER, "-d", database,
+        "-v", "ON_ERROR_STOP=1", "--no-psqlrc", "-q", "--csv", "-c", sql],
+      {
+        env: {
+          ...process.env,
+          PGPASSWORD: this.conn.readerPassword,
+          // Read-only from the first statement, before the role's own setting is read.
+          PGOPTIONS: "-c default_transaction_read_only=on -c statement_timeout=60s",
+        },
+        maxBuffer: 16 << 20,
+      },
+    );
+    const command = /^\s*([A-Za-z]+)/.exec(sql)?.[1]?.toUpperCase() ?? "";
+    return { command, rows: parseCsvRows(stdout) };
+  }
+}
+
+function readerMissing(): Error {
+  return new Error(
+    "the read-only login's password was not delivered (own-secrets.reader, " +
+      "MESH_POSTGRES_READER_PASSWORD_FILE), so the statement is refused rather than run as the " +
+      "admin (novox/hq issue 193)",
+  );
 }
 
 /** Generate a URL-safe password. */

modules/postgres/module.json

@@ -10,7 +10,11 @@
   "claims": [
     {
       "name": "mesh-store",
-      "scope": "mesh"
+      "scope": "mesh",
+      "serves": [
+        "databases",
+        "query"
+      ]
     }
   ],
   "capabilities": [
@@ -49,7 +53,8 @@
   },
   "own-secrets": {
     "superuser": "${dir:state}/superuser.secret",
-    "broker": "${dir:mesh-state}/broker"
+    "broker": "${dir:mesh-state}/broker",
+    "reader": "${dir:state}/reader.secret"
   },
   "resources": [
     {
@@ -79,7 +84,7 @@
     {
       "id": "server",
       "type": "container",
-      "name": "mesh-store",
+      "name": "postgres",
       "image": "pgvector/pgvector@sha256:cf134a767f474095eeba57e0117be8e568e011a63f33fbf252f14c9b760f8e6f",
       "env": {
         "POSTGRES_PASSWORD_FILE": "/run/secrets/superuser",
@@ -101,14 +106,16 @@
       "volumes": [
         "${dir:mesh-state}/broker:/run/secrets/broker:ro",
         "${dir:grants}:${dir:grants}:ro",
-        "${dir:state}/superuser.secret:/run/secrets/superuser:ro"
+        "${dir:state}/superuser.secret:/run/secrets/superuser:ro",
+        "${dir:state}/reader.secret:/run/secrets/reader:ro"
       ],
       "env": {
         "MESH_PROVISION_POSTGRES": "postgres://postgres@127.0.0.1:${port:5432}/postgres?sslmode=disable",
         "MESH_PROVISION_POSTGRES_PORT": "${seat:mesh-store:5432}",
         "MESH_PROVISION_PASSWORD_FILE": "/run/secrets/superuser",
         "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_RECEIVES": "${dir:grants}/mesh.json"
+        "MESH_RECEIVES": "${dir:grants}/mesh.json",
+        "MESH_POSTGRES_READER_PASSWORD_FILE": "/run/secrets/reader"
       },
       "artifact": "runtime"
     }

modules/postgres/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@novox/module-postgres",
   "version": "0.1.0",
-  "description": "postgres — provides the mesh postgres-database interface. Its client, provisioner, tools and events live here (novox/hq ADR 0039).",
+  "description": "postgres \u2014 provides the mesh postgres-database interface. Its client, provisioner, tools and events live here (novox/hq ADR 0039).",
   "type": "module",
   "private": true,
+  "scripts": {
+    "build": "tsc client.ts index.ts provisioner/index.ts tools/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist",
+    "test": "npm run build && node --test --experimental-strip-types 'test/*.test.ts'"
+  },
   "dependencies": {
     "@novox/mesh-sdk": "^0.1.1"
   },

modules/postgres/test/reader.test.ts

@@ -0,0 +1,112 @@
+// What holds the store's read-only query to being read-only (novox/hq issue 193): a caller's
+// statement runs as the reader login and never as the admin, is sent as given with no transaction
+// wrapped around it as text, and comes back as rows keyed by their columns. The reader is made once,
+// as the admin, with every attribute stated; without its password the statement is refused.
+//
+// psql is a fake on PATH that records each call's user, options and statement, and answers in CSV
+// the way the real one does with -q. That the reader cannot write is the server's to enforce and is
+// proven against a real server, not here; this holds the module to asking for it.
+// Run against the compiled module (npm test builds first), the way the runtime loads it.
+
+import { test, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { chmod, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { PostgresClient, READER } from "../dist/client.js";
+
+let dir: string;
+let log: string;
+const originalPath = process.env.PATH;
+
+before(async () => {
+  dir = await mkdtemp(join(tmpdir(), "postgres-reader-"));
+  log = join(dir, "calls.jsonl");
+  // Records argv, the user it connected as and the options it was given; answers a role lookup
+  // with no rows and anything else with a two-column result.
+  await writeFile(join(dir, "psql"), `#!/usr/bin/env node
+const fs = require("node:fs");
+const args = process.argv.slice(2);
+const at = (flag) => args[args.indexOf(flag) + 1];
+fs.appendFileSync(${JSON.stringify(log)}, JSON.stringify({
+  user: at("-U"), database: at("-d"), sql: at("-c"), quiet: args.includes("-q"),
+  password: process.env.PGPASSWORD, options: process.env.PGOPTIONS ?? "",
+}) + "\\n");
+const sql = at("-c");
+if (/FROM pg_roles/.test(sql)) process.stdout.write("?column?\\n");
+else if (/^(CREATE|ALTER|GRANT)/.test(sql)) process.stdout.write("");
+else process.stdout.write("name,n\\nalpha,1\\n\\"b,eta\\",2\\n");
+`);
+  await chmod(join(dir, "psql"), 0o755);
+  process.env.PATH = `${dir}:${originalPath}`;
+});
+
+after(async () => {
+  process.env.PATH = originalPath;
+  await rm(dir, { recursive: true, force: true });
+});
+
+async function calls(): Promise<Record<string, unknown>[]> {
+  const text = await readFile(log, "utf8").catch(() => "");
+  await writeFile(log, "");
+  return text.split("\n").filter(Boolean).map((line) => JSON.parse(line));
+}
+
+const conn = { host: "127.0.0.1", port: 5432, user: "postgres", password: "admin-secret" };
+
+test("a caller's statement runs as the reader, as given, read-only, and comes back keyed by its columns", async () => {
+  const client = new PostgresClient({ ...conn, readerPassword: "reader-secret" });
+  const statement = "COMMIT; DROP TABLE everything";
+  const result = await client.readOnlyQuery("inventory", statement);
+
+  const made = await calls();
+  const asked = made.at(-1)!;
+  assert.equal(asked.user, READER, "the statement never runs as the admin");
+  assert.equal(asked.password, "reader-secret");
+  assert.equal(asked.sql, statement, "sent as given: no transaction wrapped around it as text");
+  assert.equal(asked.database, "inventory");
+  assert.equal(asked.quiet, true, "no command tags, which came back as rows keyed by BEGIN");
+  assert.match(String(asked.options), /default_transaction_read_only=on/);
+
+  assert.deepEqual(result.rows, [{ name: "alpha", n: "1" }, { name: "b,eta", n: "2" }]);
+  assert.equal(result.command, "COMMIT");
+});
+
+test("the reader is made as the admin, with every attribute stated, once per process", async () => {
+  const client = new PostgresClient({ ...conn, readerPassword: "reader-secret" });
+  await client.readOnlyQuery("inventory", "SELECT 1");
+  await client.readOnlyQuery("inventory", "SELECT 2");
+
+  const made = await calls();
+  const asAdmin = made.filter((c) => c.user === "postgres");
+  assert.ok(asAdmin.every((c) => c.password === "admin-secret"));
+  const ddl = asAdmin.map((c) => String(c.sql));
+  const role = ddl.find((s) => s.startsWith(`CREATE ROLE "${READER}"`));
+  assert.ok(role, "made when it does not exist");
+  for (const attribute of ["LOGIN", "NOSUPERUSER", "NOCREATEDB", "NOCREATEROLE", "NOREPLICATION", "NOBYPASSRLS"]) {
+    assert.match(role!, new RegExp(`\\b${attribute}\\b`));
+  }
+  assert.ok(ddl.includes(`GRANT pg_read_all_data TO "${READER}"`), "reads everything and is granted nothing else");
+  assert.ok(ddl.some((s) => /default_transaction_read_only = on/.test(s)));
+  assert.equal(ddl.filter((s) => s.startsWith("CREATE ROLE")).length, 1, "made once, not per call");
+  assert.equal(made.filter((c) => c.user === READER).length, 2);
+});
+
+test("without the reader's password the statement is refused, and nothing runs as the admin", async () => {
+  const client = new PostgresClient(conn);
+  await assert.rejects(client.readOnlyQuery("inventory", "SELECT 1"), /refused rather than run as the admin/);
+  assert.deepEqual(await calls(), []);
+});
+
+test("the reader's password is read from the file the mesh delivers", async () => {
+  const file = join(dir, "reader.secret");
+  await writeFile(file, "from-the-file\n");
+  const client = PostgresClient.fromEnv({
+    MESH_POSTGRES_HOST: "127.0.0.1", MESH_POSTGRES_PASSWORD: "admin-secret",
+    MESH_POSTGRES_READER_PASSWORD_FILE: file,
+  });
+  await client.readOnlyQuery("inventory", "SELECT 1");
+  const asked = (await calls()).at(-1)!;
+  assert.equal(asked.password, "from-the-file");
+});

modules/postgres/tools/index.ts

@@ -16,7 +16,7 @@ export function getPostgresTools(postgres: PostgresClient): ToolDefinition[] {
     },
     {
       name: "postgres_query",
-      description: "Run a read-only SQL query against a named database (wrapped in a read-only transaction).",
+      description: "Run a read-only SQL query against a named database, as a login that can read every table and change nothing.",
       input: {
         database: { type: "string", description: "the database to query" },
         sql: { type: "string", description: "the SELECT (or other read-only) statement" },
@@ -33,6 +33,37 @@ export function getPostgresTools(postgres: PostgresClient): ToolDefinition[] {
   ];
 }
 
+// The store seat's verbs (novox/hq ADR 0159, 0160): the role's, not postgres's. Registered under the
+// seat's name, so the runtime serves them on the seat's subjects wherever this module holds the
+// seat and never lists them as postgres's own; scoped to what the store enables — asking what it
+// holds and reading from it — so creating a database is postgres's tool and not the store's.
+export function getStoreVerbs(postgres: PostgresClient): ToolDefinition[] {
+  return [
+    {
+      name: "databases",
+      description: "Every database the store holds, with its on-disk size.",
+      input: {},
+      run: async () => ({ databases: await postgres.listDatabases() }),
+    },
+    {
+      name: "query",
+      description: "One read-only statement against one database the store holds.",
+      input: {
+        database: { type: "string", description: "the database to query" },
+        sql: { type: "string", description: "the SELECT (or other read-only) statement" },
+      },
+      run: async (args) => {
+        const database = String(args.database ?? "");
+        const sql = String(args.sql ?? "");
+        if (!database) throw new Error("query: database is required");
+        if (!sql) throw new Error("query: sql is required");
+        const result = await postgres.readOnlyQuery(database, sql);
+        return { database, command: result.command, rows: result.rows };
+      },
+    },
+  ];
+}
+
 // The tools exist only when the server can be reached from the environment; without it, postgres
 // contributes none rather than failing the whole tool runtime.
 registerModuleTools("postgres", (env) => {
@@ -42,3 +73,11 @@ registerModuleTools("postgres", (env) => {
     return [];
   }
 });
+
+registerModuleTools("mesh-store", (env) => {
+  try {
+    return getStoreVerbs(PostgresClient.fromEnv(env));
+  } catch {
+    return [];
+  }
+});

modules/qbittorrent/Dockerfile

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

modules/qbittorrent/client.ts

@@ -1,188 +0,0 @@
-// The qBittorrent API client — qbittorrent's own code, living in the module (novox/hq ADR 0039).
-// Written against the WebUI API (/api/v2/...), self-contained so a change to it rebuilds only
-// qbittorrent. Both this module's tools and its events entrypoint import it, and nothing outside
-// qbittorrent does.
-//
-// The WebUI authenticates with a session cookie (SID) obtained by POSTing credentials, and guards
-// against CSRF by checking the Referer header. Node's fetch keeps no cookie jar, so the SID is
-// captured on login and carried by hand on every later call, with a single re-login on expiry.
-
-import { readFileSync } from "node:fs";
-
-export interface QbTransferInfo {
-  dlSpeedBytesPerSec: number;
-  upSpeedBytesPerSec: number;
-  dlData: number;
-  upData: number;
-  connectionStatus: string;
-}
-
-export interface QbTorrent {
-  hash: string;
-  name: string;
-  /** qBittorrent's state, e.g. "downloading", "stalledUP", "uploading", "pausedUP", "error". */
-  state: string;
-  /** 0..1 — 1 means the download is complete. */
-  progress: number;
-  sizeBytes: number;
-  dlSpeed: number;
-  upSpeed: number;
-  category: string;
-  ratio: number;
-  savePath: string;
-}
-
-/** The settings-merged config the mesh delivers (novox/hq ADR 0046): { url, apiKey, token, password, user, ... }. */
-function meshConfig(file?: string): Record<string, string> {
-  if (!file) return {};
-  try { return JSON.parse(readFileSync(file, "utf8")) as Record<string, string>; }
-  catch { return {}; }
-}
-
-/** Read a secret the mesh mounted at a file path (an own-secret delivered by `secret accept`);
- *  absent or unreadable yields undefined so callers fall back rather than crash. */
-function readSecret(file?: string): string | undefined {
-  if (!file) return undefined;
-  try { return readFileSync(file, "utf8").trim(); }
-  catch { return undefined; }
-}
-
-export class QbittorrentClient {
-  readonly baseUrl: string;
-  private sid: string | null = null;
-
-  constructor(
-    baseUrl: string,
-    private readonly user: string,
-    private readonly password: string,
-  ) {
-    this.baseUrl = baseUrl.replace(/\/$/, "");
-  }
-
-  /**
-   * Build from the module's resolved environment. URL and password are read from
-   * MESH_QBITTORRENT_URL and MESH_QBITTORRENT_PASSWORD; both must be present — an unconfigured
-   * qBittorrent throws rather than pretend to be reachable, so the tools/events simply do not load
-   * (the harness treats the throw as "exposes nothing"). The user defaults to "admin".
-   */
-  static fromEnv(env: NodeJS.ProcessEnv = process.env): QbittorrentClient {
-    const cfg = meshConfig(env.MESH_QBITTORRENT_CONFIG_FILE);
-    const url = cfg.url ?? env.MESH_QBITTORRENT_URL;
-    const password = cfg.password ?? readSecret(env.MESH_QBITTORRENT_PASSWORD_FILE) ?? env.MESH_QBITTORRENT_PASSWORD;
-    if (!url || !password) {
-      throw new Error("qBittorrent not configured — set MESH_QBITTORRENT_URL and MESH_QBITTORRENT_PASSWORD");
-    }
-    const user = cfg.user ?? env.MESH_QBITTORRENT_USER ?? "admin";
-    return new QbittorrentClient(url, user, password);
-  }
-
-  private async login(): Promise<void> {
-    const res = await fetch(`${this.baseUrl}/api/v2/auth/login`, {
-      method: "POST",
-      headers: { "Content-Type": "application/x-www-form-urlencoded", Referer: this.baseUrl },
-      body: new URLSearchParams({ username: this.user, password: this.password }),
-    });
-    if (!res.ok) throw new Error(`qBittorrent login: ${res.status} ${await res.text()}`);
-    if ((await res.text()).trim() !== "Ok.") {
-      throw new Error("qBittorrent login rejected — check credentials");
-    }
-    const match = res.headers.get("set-cookie")?.match(/SID=([^;]+)/);
-    if (!match) throw new Error("qBittorrent login returned no SID cookie");
-    this.sid = match[1];
-  }
-
-  private async call(method: "GET" | "POST", path: string, form?: Record<string, string>): Promise<Response> {
-    if (!this.sid) await this.login();
-    const doFetch = (): Promise<Response> => {
-      const headers: Record<string, string> = { Referer: this.baseUrl, Cookie: `SID=${this.sid}` };
-      const init: RequestInit = { method, headers };
-      if (form) {
-        headers["Content-Type"] = "application/x-www-form-urlencoded";
-        init.body = new URLSearchParams(form);
-      }
-      return fetch(`${this.baseUrl}/api/v2/${path}`, init);
-    };
-    let res = await doFetch();
-    if (res.status === 403) {
-      // The SID expired — re-authenticate once and retry, rather than fail a routine call.
-      await this.login();
-      res = await doFetch();
-    }
-    return res;
-  }
-
-  private async getJson<T>(path: string): Promise<T> {
-    const res = await this.call("GET", path);
-    if (!res.ok) throw new Error(`qBittorrent GET ${path}: ${res.status} ${await res.text()}`);
-    return (await res.json()) as T;
-  }
-
-  async getVersion(): Promise<string> {
-    const res = await this.call("GET", "app/version");
-    if (!res.ok) throw new Error(`qBittorrent app/version: ${res.status}`);
-    return (await res.text()).trim();
-  }
-
-  async getTransferInfo(): Promise<QbTransferInfo> {
-    const d = await this.getJson<Record<string, any>>("transfer/info");
-    return {
-      dlSpeedBytesPerSec: Number(d.dl_info_speed ?? 0),
-      upSpeedBytesPerSec: Number(d.up_info_speed ?? 0),
-      dlData: Number(d.dl_info_data ?? 0),
-      upData: Number(d.up_info_data ?? 0),
-      connectionStatus: String(d.connection_status ?? "unknown"),
-    };
-  }
-
-  async getTorrents(filter?: string): Promise<QbTorrent[]> {
-    const path = filter ? `torrents/info?filter=${encodeURIComponent(filter)}` : "torrents/info";
-    const list = await this.getJson<Record<string, any>[]>(path);
-    return list.map((t) => ({
-      hash: String(t.hash),
-      name: String(t.name ?? "Unknown"),
-      state: String(t.state ?? "unknown"),
-      progress: Number(t.progress ?? 0),
-      sizeBytes: Number(t.size ?? 0),
-      dlSpeed: Number(t.dlspeed ?? 0),
-      upSpeed: Number(t.upspeed ?? 0),
-      category: String(t.category ?? ""),
-      ratio: Number(t.ratio ?? 0),
-      savePath: String(t.save_path ?? ""),
-    }));
-  }
-
-  /** Add a torrent by magnet or http(s) .torrent URL, optionally into a category / save path. */
-  async add(url: string, category = "", savepath = "", paused = false): Promise<void> {
-    const form: Record<string, string> = { urls: url, paused: paused ? "true" : "false" };
-    if (category) form.category = category;
-    if (savepath) form.savepath = savepath;
-    const res = await this.call("POST", "torrents/add", form);
-    const text = (await res.text()).trim();
-    if (!res.ok || text.toLowerCase() === "fails.") {
-      throw new Error(`qBittorrent refused the torrent: ${res.status} ${text}`);
-    }
-  }
-
-  // qBittorrent 5.x renamed pause/resume to stop/start; try the modern name and fall back to the
-  // legacy one on a 404, so the client works against both.
-  private async command(modern: string, legacy: string, hashes: string): Promise<void> {
-    let res = await this.call("POST", `torrents/${modern}`, { hashes });
-    if (res.status === 404) res = await this.call("POST", `torrents/${legacy}`, { hashes });
-    if (!res.ok) throw new Error(`qBittorrent torrents/${modern}: ${res.status} ${await res.text()}`);
-  }
-
-  /** Pause torrents — a pipe-separated hash list, or "all" (the default). */
-  async pause(hashes = "all"): Promise<void> {
-    await this.command("stop", "pause", hashes);
-  }
-
-  /** Resume torrents — a pipe-separated hash list, or "all" (the default). */
-  async resume(hashes = "all"): Promise<void> {
-    await this.command("start", "resume", hashes);
-  }
-
-  async delete(hashes: string, deleteFiles = false): Promise<void> {
-    const res = await this.call("POST", "torrents/delete", { hashes, deleteFiles: deleteFiles ? "true" : "false" });
-    if (!res.ok) throw new Error(`qBittorrent torrents/delete: ${res.status} ${await res.text()}`);
-  }
-}

modules/qbittorrent/index.ts

@@ -1,52 +0,0 @@
-// qbittorrent's events. The tool runtime imports this once the broker is bound. It watches the
-// torrent list and turns its comings and goings into mesh events.
-//
-// Emits (novox/hq ADR 0041/0042):
-//   module.qbittorrent.download.added       — a torrent was added
-//   module.qbittorrent.download.completed   — a torrent finished downloading (progress reached 1).
-//                                             This exact routing key is what the plex module
-//                                             consumes (module.*.download.completed) to rescan, so
-//                                             the new file becomes a visible item.
-// Consumes: none.
-//
-// The torrent list is polled and diffed by hash, primed silently on the first look (like plex's and
-// sonarr's index.ts) so a restart does not re-announce everything already present. Completion is a
-// progress crossing from below 1 to exactly 1 — a torrent added already-complete is announced only
-// as added, never as freshly completed, since nothing was downloaded.
-
-import { emit } from "@novox/mesh-sdk/events";
-import { QbittorrentClient } from "./client.js";
-
-const qb = QbittorrentClient.fromEnv();
-
-const progressByHash = new Map<string, number>();
-let primed = false;
-
-async function pollTorrents(): Promise<void> {
-  const torrents = await qb.getTorrents();
-  const now = new Map(torrents.map((t) => [t.hash, t]));
-
-  if (primed) {
-    for (const [hash, t] of now) {
-      const before = progressByHash.get(hash);
-      if (before === undefined) {
-        await emit("download.added", { name: t.name, category: t.category, sizeBytes: t.sizeBytes });
-      } else if (before < 1 && t.progress >= 1) {
-        await emit("download.completed", { name: t.name, category: t.category, sizeBytes: t.sizeBytes });
-      }
-    }
-  }
-
-  progressByHash.clear();
-  for (const [hash, t] of now) progressByHash.set(hash, t.progress);
-  primed = true;
-}
-
-const tick = (fn: () => Promise<void>, everyMs: number): void => {
-  const run = (): void => void fn().catch((err) => console.error(`[qbittorrent] ${err}`));
-  setInterval(run, everyMs);
-  run();
-};
-tick(pollTorrents, 20_000);
-
-console.log("[qbittorrent] watching torrents, emitting adds and completions");

modules/qbittorrent/module.json

@@ -1,118 +0,0 @@
-{
-  "module": "qbittorrent",
-  "version": "1",
-  "slug": "qbt",
-  "capabilities": [
-    "container-runtime"
-  ],
-  "emits": [
-    "download.added",
-    "download.completed"
-  ],
-  "consumes": [],
-  "own-secrets": {
-    "broker": "${dir:mesh-state}/broker",
-    "password": "${dir:mesh-state}/password"
-  },
-  "listens": [
-    {
-      "name": "web",
-      "port": 8080,
-      "protocol": "tcp",
-      "from": "mesh",
-      "why": "the download client's pages"
-    }
-  ],
-  "accesses": [
-    {
-      "id": "downloads",
-      "path": "/services/media/downloads",
-      "mode": "read-write"
-    }
-  ],
-  "resources": [
-    {
-      "id": "mesh-state",
-      "type": "directory",
-      "mode": "0700",
-      "place": "mesh"
-    },
-    {
-      "id": "config",
-      "type": "directory",
-      "path": "/services/qbittorrent/config",
-      "mode": "0700",
-      "owner": "1000:1000"
-    },
-    {
-      "id": "server",
-      "type": "container",
-      "name": "qbittorrent",
-      "image": "lscr.io/linuxserver/qbittorrent@sha256:a00b6a597a3832a1814cde0ef60abc55c94644f3f80902c3432f6af6de8d4a96",
-      "env": {
-        "PUID": "1000",
-        "PGID": "1000",
-        "TZ": "Etc/UTC"
-      },
-      "ports": [
-        "8080"
-      ],
-      "volumes": [
-        "/services/qbittorrent/config:/config",
-        "${access:downloads}:/downloads"
-      ]
-    },
-    {
-      "id": "runtime-config",
-      "type": "file",
-      "path": "${dir:mesh-state}/config.json",
-      "mode": "0600",
-      "content": "{}\n",
-      "merge": "json"
-    },
-    {
-      "id": "runtime",
-      "type": "container",
-      "name": "mesh-qbittorrent",
-      "network": "host",
-      "volumes": [
-        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
-        "${dir:mesh-state}/password:/run/secrets/password:ro",
-        "${dir:mesh-state}/config.json:/run/config/config.json:ro",
-        "/services/qbittorrent/config:/var/lib/qbittorrent/config:ro"
-      ],
-      "env": {
-        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_QBITTORRENT_URL": "http://127.0.0.1:8080",
-        "MESH_QBITTORRENT_PASSWORD_FILE": "/run/secrets/password",
-        "MESH_QBITTORRENT_CONFIG_FILE": "/run/config/config.json",
-        "MESH_QBITTORRENT_CONFIG_DIR": "/var/lib/qbittorrent/config"
-      },
-      "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",
-        "kind": "image",
-        "from": "Dockerfile"
-      }
-    ]
-  }
-}

modules/qbittorrent/package.json

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

modules/qbittorrent/tools/index.ts

@@ -1,98 +0,0 @@
-// qbittorrent's tools — living in the module (novox/hq ADR 0039), importing qbittorrent's own
-// client. They return structured data; the mesh serves them through the sdk's tool harness.
-
-import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
-import { QbittorrentClient } from "../client.js";
-
-export function getQbittorrentTools(qb: QbittorrentClient): ToolDefinition[] {
-  return [
-    {
-      name: "qbittorrent_status",
-      description: "qBittorrent status: version, global transfer rates, and how many torrents are active.",
-      input: {},
-      run: async () => {
-        const [version, transfer, torrents] = await Promise.all([
-          qb.getVersion(),
-          qb.getTransferInfo(),
-          qb.getTorrents(),
-        ]);
-        const downloading = torrents.filter((t) => t.progress < 1).length;
-        return { version, transfer, torrents: torrents.length, downloading, seeding: torrents.length - downloading };
-      },
-    },
-    {
-      name: "qbittorrent_torrents",
-      description: "List torrents — name, state, progress and speed. Optional filter narrows the set.",
-      input: {
-        filter: { type: "string", description: "one of all|downloading|seeding|completed|paused|active|inactive|stalled" },
-      },
-      run: async (args) => {
-        const items = await qb.getTorrents(args.filter ? String(args.filter) : undefined);
-        return { count: items.length, torrents: items };
-      },
-    },
-    {
-      name: "qbittorrent_add",
-      description: "Add a torrent by magnet link or .torrent URL, optionally into a category.",
-      input: {
-        url: { type: "string", description: "magnet link or http(s) URL to a .torrent" },
-        category: { type: "string", description: "category name (determines save directory)" },
-        savepath: { type: "string", description: "explicit save path (overrides the category default)" },
-        paused: { type: "boolean", description: "add in paused state (default false)" },
-      },
-      run: async (args) => {
-        await qb.add(
-          String(args.url),
-          args.category ? String(args.category) : "",
-          args.savepath ? String(args.savepath) : "",
-          args.paused === true || args.paused === "true",
-        );
-        return { added: String(args.url), category: args.category ? String(args.category) : null };
-      },
-    },
-    {
-      name: "qbittorrent_pause",
-      description: "Pause torrents — a pipe-separated hash list, or 'all' (the default).",
-      input: { hashes: { type: "string", description: "pipe-separated torrent hashes, or 'all' (default)" } },
-      run: async (args) => {
-        const hashes = args.hashes ? String(args.hashes) : "all";
-        await qb.pause(hashes);
-        return { paused: hashes };
-      },
-    },
-    {
-      name: "qbittorrent_resume",
-      description: "Resume torrents — a pipe-separated hash list, or 'all' (the default).",
-      input: { hashes: { type: "string", description: "pipe-separated torrent hashes, or 'all' (default)" } },
-      run: async (args) => {
-        const hashes = args.hashes ? String(args.hashes) : "all";
-        await qb.resume(hashes);
-        return { resumed: hashes };
-      },
-    },
-    {
-      name: "qbittorrent_delete",
-      description: "Remove torrents by hash, optionally deleting their files on disk.",
-      input: {
-        hashes: { type: "string", description: "pipe-separated torrent hashes, or 'all'" },
-        deleteFiles: { type: "boolean", description: "also delete downloaded files (default false)" },
-      },
-      run: async (args) => {
-        const hashes = String(args.hashes);
-        const deleteFiles = args.deleteFiles === true || args.deleteFiles === "true";
-        await qb.delete(hashes, deleteFiles);
-        return { deleted: hashes, deleteFiles };
-      },
-    },
-  ];
-}
-
-// The tools exist only when qBittorrent is configured; without a URL and password, qbittorrent
-// contributes none rather than failing the whole runtime.
-registerModuleTools("qbittorrent", (env) => {
-  try {
-    return getQbittorrentTools(QbittorrentClient.fromEnv(env));
-  } catch {
-    return [];
-  }
-});

modules/qbittorrent/tsconfig.json

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

modules/radarr/Dockerfile

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

modules/radarr/client.ts

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

modules/radarr/index.ts

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

modules/radarr/module.json

@@ -1,119 +0,0 @@
-{
-  "module": "radarr",
-  "version": "1",
-  "capabilities": [
-    "container-runtime"
-  ],
-  "emits": [
-    "movie.grabbed",
-    "download.completed"
-  ],
-  "consumes": [],
-  "own-secrets": {
-    "broker": "${dir:mesh-state}/broker"
-  },
-  "listens": [
-    {
-      "name": "web",
-      "port": 7878,
-      "protocol": "tcp",
-      "from": "mesh",
-      "why": "managing films"
-    }
-  ],
-  "accesses": [
-    {
-      "id": "movies",
-      "path": "/services/media/movies",
-      "mode": "read-write"
-    },
-    {
-      "id": "downloads",
-      "path": "/services/media/downloads",
-      "mode": "read-write"
-    }
-  ],
-  "resources": [
-    {
-      "id": "mesh-state",
-      "type": "directory",
-      "mode": "0700",
-      "place": "mesh"
-    },
-    {
-      "id": "config",
-      "type": "directory",
-      "path": "/services/radarr/config",
-      "mode": "0700",
-      "owner": "1000:1000"
-    },
-    {
-      "id": "server",
-      "type": "container",
-      "name": "radarr",
-      "image": "lscr.io/linuxserver/radarr@sha256:119aaa4a4f7349bcd2a136c5373a0d7925b5479915c7dfe0c0ad352db2a6d438",
-      "env": {
-        "PUID": "1000",
-        "PGID": "1000",
-        "TZ": "Etc/UTC"
-      },
-      "ports": [
-        "7878"
-      ],
-      "volumes": [
-        "/services/radarr/config:/config",
-        "${access:movies}:/movies",
-        "${access:downloads}:/downloads"
-      ]
-    },
-    {
-      "id": "runtime",
-      "type": "container",
-      "name": "mesh-radarr",
-      "network": "host",
-      "volumes": [
-        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
-        "/services/radarr/config:/var/lib/radarr/config:ro"
-      ],
-      "env": {
-        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_RADARR_URL": "http://127.0.0.1:7878",
-        "MESH_RADARR_CONFIG_DIR": "/var/lib/radarr/config"
-      },
-      "artifact": "runtime"
-    }
-  ],
-  "requires": [
-    "route"
-  ],
-  "contributes": {
-    "route": {
-      "label": "movies",
-      "endpoint": "web"
-    }
-  },
-  "binds": {
-    "route": "${dir:mesh-state}/route.json"
-  },
-  "build": {
-    "on": [
-      {
-        "arg": "BUILD_BASE",
-        "module": "mesh-tools",
-        "artifact": "build"
-      },
-      {
-        "arg": "RUNTIME_BASE",
-        "module": "mesh-tools",
-        "artifact": "runtime"
-      }
-    ],
-    "artifacts": [
-      {
-        "name": "runtime",
-        "kind": "image",
-        "from": "Dockerfile"
-      }
-    ]
-  }
-}

modules/radarr/package.json

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

modules/radarr/tools/index.ts

@@ -1,78 +0,0 @@
-// radarr's tools — ported from the shared hal sdk (novox/hq ADR 0039), importing radarr's own
-// client. They return structured data (not pre-formatted text as hal did); the mesh serves them
-// through the sdk's tool harness.
-
-import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
-import { RadarrClient } from "../client.js";
-
-export function getRadarrTools(radarr: RadarrClient): ToolDefinition[] {
-  return [
-    {
-      name: "radarr_status",
-      description: "Radarr status overview: version, movie count, monitored count, queue size.",
-      input: {},
-      run: async () => {
-        const [status, content, queue] = await Promise.all([
-          radarr.getStatus(),
-          radarr.getContent(),
-          radarr.getQueue(),
-        ]);
-        return {
-          app: status.appName,
-          version: status.version,
-          movies: content.length,
-          monitored: content.filter((c) => c.monitored).length,
-          queue: queue.totalRecords,
-        };
-      },
-    },
-    {
-      name: "radarr_library",
-      description: "List movies from the Radarr library.",
-      input: { limit: { type: "number", description: "max items to return (default 50)" } },
-      run: async (args) => {
-        const items = await radarr.getContent(args.limit ? Number(args.limit) : 50);
-        return { count: items.length, movies: items };
-      },
-    },
-    {
-      name: "radarr_search",
-      description: "Search the Radarr library for movies by title (filters existing content, not indexers).",
-      input: { query: { type: "string", description: "the search term" } },
-      run: async (args) => {
-        const query = String(args.query);
-        return { query, results: await radarr.searchContent(query) };
-      },
-    },
-    {
-      name: "radarr_queue",
-      description: "Show the Radarr download queue — what is downloading and how far along.",
-      input: {},
-      run: async () => {
-        const queue = await radarr.getQueue();
-        return { count: queue.totalRecords, items: queue.items };
-      },
-    },
-    {
-      name: "radarr_calendar",
-      description: "Upcoming movie releases from the Radarr calendar.",
-      input: { days: { type: "number", description: "how many days to look ahead (default 7)" } },
-      run: async (args) => {
-        const days = args.days ? Number(args.days) : 7;
-        const items = await radarr.getCalendar(days);
-        items.sort((a, b) => a.date.localeCompare(b.date));
-        return { days, count: items.length, items };
-      },
-    },
-  ];
-}
-
-// The tools exist only when Radarr is configured; without a URL and key, radarr contributes none
-// rather than failing the whole runtime.
-registerModuleTools("radarr", (env) => {
-  try {
-    return getRadarrTools(RadarrClient.fromEnv(env));
-  } catch {
-    return [];
-  }
-});

modules/radarr/tsconfig.json

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

modules/route-proxy/README.md

@@ -27,6 +27,17 @@ No broker account, no own-secrets, no provisioner: the proxy neither mints a cre
 an event. It only reads the file the mesh writes. (Contrast `redis`, which mints passwords, and
 `cloudflare-dns`, which emits record events.)
 
+## Which issuer: the node that runs a proxy carries `public-acme`
+
+`acme-ca` has two providers in a full mesh — `public-acme` (Let's Encrypt, a facts-only module that
+runs nothing) and `step-ca` (the mesh's own authority, which also offers it so a lab without a public
+issuer still has one). A proxy beside both resolves by co-location only once a pin names the module
+(`pin <node> acme-ca <node> public-acme`, novox/hq #258); a proxy on another machine cannot resolve
+at all until it is told. **So every node that runs a route-proxy is assigned `public-acme` too**: the
+issuer is then on the proxy's own node, design 23's first rule answers, and `internal-acme-ca` has
+one provider mesh-wide. Nothing runs for it; it is the statement "this machine's public issuer is
+Let's Encrypt", on the machine that issues.
+
 ## How it ships the Go proxy
 
 The proxy is a Go program, unlike the TypeScript tool-runtime modules. The canonical source is

modules/route-proxy/module.json

@@ -25,6 +25,9 @@
     "acme-ca": "${dir:state}/acme-ca.json",
     "internal-acme-ca": "${dir:state}/internal-acme-ca.json"
   },
+  "own-secrets": {
+    "broker": "${dir:mesh-state}/broker"
+  },
   "listens": [
     {
       "name": "http",
@@ -48,6 +51,12 @@
       "mode": "0700",
       "place": "."
     },
+    {
+      "id": "mesh-state",
+      "type": "directory",
+      "mode": "0700",
+      "place": "mesh"
+    },
     {
       "id": "routes-dir",
       "type": "directory",
@@ -137,7 +146,8 @@
       "volumes": [
         "${dir:routes-dir}:/routes:ro",
         "${dir:acme-cache}:/acme",
-        "${dir:ca-dir}:/ca:ro"
+        "${dir:ca-dir}:/ca:ro",
+        "${dir:mesh-state}/broker:/run/secrets/broker:ro"
       ],
       "env": {
         "ROUTES": "/routes/mesh.json",
@@ -145,7 +155,8 @@
         "TLS_LISTEN": ":443",
         "ACME_CACHE": "/acme",
         "ACME_CA_BUNDLE": "/ca/root.crt",
-        "INTERNAL_ACME_CA_BUNDLE": "/ca/internal-root.crt"
+        "INTERNAL_ACME_CA_BUNDLE": "/ca/internal-root.crt",
+        "MESH_BROKER_FILE": "/run/secrets/broker"
       },
       "restart-on": [
         "trust",

modules/searxng/module.json

@@ -5,7 +5,10 @@
     "container-runtime"
   ],
   "own-secrets": {
-    "secret": "${dir:mesh-state}/secret",
+    "secret": {
+      "path": "${dir:mesh-state}/secret",
+      "taken": "at-start"
+    },
     "broker": "${dir:mesh-state}/broker"
   },
   "listens": [

modules/sonarr/Dockerfile

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

modules/sonarr/client.ts

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

modules/sonarr/index.ts

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

modules/sonarr/module.json

@@ -1,125 +0,0 @@
-{
-  "module": "sonarr",
-  "version": "1",
-  "capabilities": [
-    "container-runtime"
-  ],
-  "emits": [
-    "episode.grabbed",
-    "download.completed"
-  ],
-  "consumes": [],
-  "own-secrets": {
-    "broker": "${dir:mesh-state}/broker"
-  },
-  "listens": [
-    {
-      "name": "web",
-      "port": 8989,
-      "protocol": "tcp",
-      "from": "mesh",
-      "why": "managing series"
-    }
-  ],
-  "accesses": [
-    {
-      "id": "series",
-      "path": "/services/media/series",
-      "mode": "read-write"
-    },
-    {
-      "id": "anime",
-      "path": "/services/media/anime",
-      "mode": "read-write"
-    },
-    {
-      "id": "downloads",
-      "path": "/services/media/downloads",
-      "mode": "read-write"
-    }
-  ],
-  "resources": [
-    {
-      "id": "mesh-state",
-      "type": "directory",
-      "mode": "0700",
-      "place": "mesh"
-    },
-    {
-      "id": "config",
-      "type": "directory",
-      "path": "/services/sonarr/config",
-      "mode": "0700",
-      "owner": "1000:1000"
-    },
-    {
-      "id": "server",
-      "type": "container",
-      "name": "sonarr",
-      "image": "lscr.io/linuxserver/sonarr@sha256:c19aa4ecdf03d73e1d5c901da33744cb7eb4d921f89bafed1ca264601d7fa224",
-      "env": {
-        "PUID": "1000",
-        "PGID": "1000",
-        "TZ": "Etc/UTC"
-      },
-      "ports": [
-        "8989"
-      ],
-      "volumes": [
-        "/services/sonarr/config:/config",
-        "${access:series}:/series",
-        "${access:anime}:/anime",
-        "${access:downloads}:/downloads"
-      ]
-    },
-    {
-      "id": "runtime",
-      "type": "container",
-      "name": "mesh-sonarr",
-      "network": "host",
-      "volumes": [
-        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
-        "/services/sonarr/config:/var/lib/sonarr/config:ro"
-      ],
-      "env": {
-        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_SONARR_URL": "http://127.0.0.1:8989",
-        "MESH_SONARR_CONFIG_DIR": "/var/lib/sonarr/config"
-      },
-      "artifact": "runtime"
-    }
-  ],
-  "requires": [
-    "route"
-  ],
-  "contributes": {
-    "route": {
-      "label": "series",
-      "endpoint": "web"
-    }
-  },
-  "binds": {
-    "route": "${dir:mesh-state}/route.json"
-  },
-  "build": {
-    "on": [
-      {
-        "arg": "BUILD_BASE",
-        "module": "mesh-tools",
-        "artifact": "build"
-      },
-      {
-        "arg": "RUNTIME_BASE",
-        "module": "mesh-tools",
-        "artifact": "runtime"
-      }
-    ],
-    "artifacts": [
-      {
-        "name": "runtime",
-        "kind": "image",
-        "from": "Dockerfile"
-      }
-    ]
-  }
-}

modules/sonarr/package.json

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

modules/sonarr/tools/index.ts

@@ -1,78 +0,0 @@
-// sonarr's tools — ported from the shared hal sdk (novox/hq ADR 0039), importing sonarr's own
-// client. They return structured data (not pre-formatted text as hal did); the mesh serves them
-// through the sdk's tool harness.
-
-import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
-import { SonarrClient } from "../client.js";
-
-export function getSonarrTools(sonarr: SonarrClient): ToolDefinition[] {
-  return [
-    {
-      name: "sonarr_status",
-      description: "Sonarr status overview: version, series count, monitored count, queue size.",
-      input: {},
-      run: async () => {
-        const [status, content, queue] = await Promise.all([
-          sonarr.getStatus(),
-          sonarr.getContent(),
-          sonarr.getQueue(),
-        ]);
-        return {
-          app: status.appName,
-          version: status.version,
-          series: content.length,
-          monitored: content.filter((c) => c.monitored).length,
-          queue: queue.totalRecords,
-        };
-      },
-    },
-    {
-      name: "sonarr_library",
-      description: "List series from the Sonarr library.",
-      input: { limit: { type: "number", description: "max items to return (default 50)" } },
-      run: async (args) => {
-        const items = await sonarr.getContent(args.limit ? Number(args.limit) : 50);
-        return { count: items.length, series: items };
-      },
-    },
-    {
-      name: "sonarr_search",
-      description: "Search the Sonarr library for series by title (filters existing content, not indexers).",
-      input: { query: { type: "string", description: "the search term" } },
-      run: async (args) => {
-        const query = String(args.query);
-        return { query, results: await sonarr.searchContent(query) };
-      },
-    },
-    {
-      name: "sonarr_queue",
-      description: "Show the Sonarr download queue — what is downloading and how far along.",
-      input: {},
-      run: async () => {
-        const queue = await sonarr.getQueue();
-        return { count: queue.totalRecords, items: queue.items };
-      },
-    },
-    {
-      name: "sonarr_calendar",
-      description: "Upcoming episode releases from the Sonarr calendar.",
-      input: { days: { type: "number", description: "how many days to look ahead (default 7)" } },
-      run: async (args) => {
-        const days = args.days ? Number(args.days) : 7;
-        const items = await sonarr.getCalendar(days);
-        items.sort((a, b) => a.date.localeCompare(b.date));
-        return { days, count: items.length, items };
-      },
-    },
-  ];
-}
-
-// The tools exist only when Sonarr is configured; without a URL and key, sonarr contributes none
-// rather than failing the whole runtime.
-registerModuleTools("sonarr", (env) => {
-  try {
-    return getSonarrTools(SonarrClient.fromEnv(env));
-  } catch {
-    return [];
-  }
-});

modules/sonarr/tsconfig.json

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

modules/systemd-networkd/module.json

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

modules/tautulli/Dockerfile

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

modules/tautulli/client.ts

@@ -1,108 +0,0 @@
-// Tautulli's API client — tautulli's own code, living in the module (novox/hq ADR 0039). Both this
-// module's tools and its events entrypoint import it, and nothing outside tautulli does.
-//
-// Tautulli speaks one endpoint: GET /api/v2?apikey=…&cmd=…&<params>, answering
-// { response: { result: "success" | "error", message, data } }. This client unwraps that envelope
-// and hands back only the data.
-
-import { readFileSync } from "node:fs";
-
-export interface TautulliSession {
-  user: string;
-  title: string;
-  mediaType: string;
-  state: string;
-  progressPercent: number;
-  player: string;
-}
-
-export interface TautulliWatch {
-  /** Tautulli's history row id — the stable identity a recorded watch is diffed on. */
-  id: number;
-  user: string;
-  title: string;
-  mediaType: string;
-  /** "watched" | "watching" | ... — Tautulli's own watched_status label. */
-  watchedStatus: string;
-  percentComplete: number;
-  /** Unix seconds the play started, as Tautulli reports it. */
-  date?: number;
-}
-
-export interface TautulliHomeStat {
-  statId: string;
-  rows: Array<Record<string, unknown>>;
-}
-
-/** 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 TautulliClient {
-  readonly baseUrl: string;
-
-  constructor(
-    url: string,
-    private readonly apiKey: string,
-  ) {
-    this.baseUrl = url.replace(/\/$/, "");
-  }
-
-  /**
-   * Build from the module's resolved environment. The API key is read from MESH_TAUTULLI_APIKEY
-   * (Tautulli mints it in Settings → Web Interface); the base URL defaults to the local container.
-   * Throws when no key is configured — the module then contributes nothing rather than failing.
-   */
-  static fromEnv(env: NodeJS.ProcessEnv = process.env): TautulliClient {
-    const cfg = meshConfig(env.MESH_TAUTULLI_CONFIG_FILE);
-    const url = cfg.url ?? (env.MESH_TAUTULLI_URL ?? `http://127.0.0.1:${env.TAUTULLI_PORT ?? "8181"}`);
-    const apiKey = cfg.apiKey ?? env.MESH_TAUTULLI_APIKEY;
-    if (!apiKey) throw new Error("no Tautulli API key — set MESH_TAUTULLI_APIKEY");
-    return new TautulliClient(url, apiKey);
-  }
-
-  /** Call one Tautulli command and return its unwrapped data, throwing on a non-success result. */
-  private async cmd(command: string, params: Record<string, string> = {}): Promise<any> {
-    const q = new URLSearchParams({ apikey: this.apiKey, cmd: command, ...params });
-    const res = await fetch(`${this.baseUrl}/api/v2?${q.toString()}`);
-    if (!res.ok) throw new Error(`Tautulli ${command}: ${res.status} ${await res.text()}`);
-    const body = (await res.json()).response ?? {};
-    if (body.result !== "success") throw new Error(`Tautulli ${command}: ${body.message ?? "error"}`);
-    return body.data;
-  }
-
-  async getActivity(): Promise<{ streamCount: number; sessions: TautulliSession[] }> {
-    const data = await this.cmd("get_activity");
-    const sessions = ((data?.sessions ?? []) as any[]).map((s) => ({
-      user: s.friendly_name ?? s.user ?? "unknown",
-      title: s.full_title ?? s.title ?? "unknown",
-      mediaType: s.media_type ?? "unknown",
-      state: s.state ?? "unknown",
-      progressPercent: Number(s.progress_percent ?? 0),
-      player: s.player ?? "unknown",
-    }));
-    return { streamCount: Number(data?.stream_count ?? sessions.length), sessions };
-  }
-
-  async getHistory(length = 25): Promise<TautulliWatch[]> {
-    const data = await this.cmd("get_history", { length: String(length), order_column: "date", order_dir: "desc" });
-    return ((data?.data ?? []) as any[]).map((r) => ({
-      id: Number(r.row_id ?? r.id ?? r.reference_id ?? 0),
-      user: r.friendly_name ?? r.user ?? "unknown",
-      title: r.full_title ?? r.title ?? "unknown",
-      mediaType: r.media_type ?? "unknown",
-      watchedStatus: String(r.watched_status ?? ""),
-      percentComplete: Number(r.percent_complete ?? 0),
-      date: r.date != null ? Number(r.date) : undefined,
-    }));
-  }
-
-  /** The home-page statistics blocks — most-watched shows, most-active users, and so on. */
-  async getHomeStats(): Promise<TautulliHomeStat[]> {
-    const data = (await this.cmd("get_home_stats")) as any[];
-    return (data ?? []).map((s) => ({ statId: s.stat_id, rows: s.rows ?? [] }));
-  }
-}

modules/tautulli/index.ts

@@ -1,48 +0,0 @@
-// tautulli's events. The tool runtime imports this once the broker is bound. It watches Tautulli's
-// history and announces each newly recorded watch.
-//
-// Emits (novox/hq ADR 0041/0042):
-//   module.tautulli.watch.recorded   — a play appeared in Tautulli's history
-//
-// Diffed on the history row id and primed silently on the first look, so a restart does not
-// re-announce the whole existing history as freshly watched.
-
-import { emit } from "@novox/mesh-sdk/events";
-import { TautulliClient, type TautulliWatch } from "./client.js";
-
-// Constructed lazily so an unconfigured node (no API key) loads this entrypoint without crashing
-// the events host — it simply watches nothing.
-let tautulli: TautulliClient | undefined;
-try {
-  tautulli = TautulliClient.fromEnv();
-} catch (err) {
-  console.log(`[tautulli] not configured, not watching history: ${err}`);
-}
-
-const seen = new Set<number>();
-let primed = false;
-
-async function pollHistory(client: TautulliClient): Promise<void> {
-  const history = await client.getHistory(25);
-  for (const w of history) {
-    if (w.id === 0 || seen.has(w.id)) continue;
-    if (primed) await emitWatch(w);
-    seen.add(w.id);
-  }
-  primed = true;
-}
-
-async function emitWatch(w: TautulliWatch): Promise<void> {
-  await emit("watch.recorded", {
-    title: w.title, user: w.user, mediaType: w.mediaType,
-    watchedStatus: w.watchedStatus, percentComplete: w.percentComplete, at: w.date,
-  });
-}
-
-if (tautulli) {
-  const client = tautulli;
-  const run = (): void => void pollHistory(client).catch((err) => console.error(`[tautulli] ${err}`));
-  setInterval(run, 60_000);
-  run();
-  console.log("[tautulli] watching watch history");
-}

modules/tautulli/module.json

@@ -1,116 +0,0 @@
-{
-  "module": "tautulli",
-  "version": "1",
-  "emits": [
-    "watch.recorded"
-  ],
-  "own-secrets": {
-    "broker": "${dir:mesh-state}/broker"
-  },
-  "capabilities": [
-    "container-runtime"
-  ],
-  "listens": [
-    {
-      "name": "web",
-      "port": 8181,
-      "protocol": "tcp",
-      "from": "mesh",
-      "why": "watch statistics"
-    }
-  ],
-  "resources": [
-    {
-      "id": "mesh-state",
-      "type": "directory",
-      "mode": "0700",
-      "place": "mesh"
-    },
-    {
-      "id": "config",
-      "type": "directory",
-      "path": "/services/tautulli/config",
-      "mode": "0700",
-      "owner": "1000:1000"
-    },
-    {
-      "id": "server",
-      "type": "container",
-      "name": "tautulli",
-      "image": "lscr.io/linuxserver/tautulli@sha256:13f03ecfc61a7af89d492677389771ac29682a72153ce08a5cd4faffbc0197e8",
-      "env": {
-        "PUID": "1000",
-        "PGID": "1000",
-        "TZ": "Etc/UTC"
-      },
-      "ports": [
-        "8181"
-      ],
-      "volumes": [
-        "/services/tautulli/config:/config"
-      ]
-    },
-    {
-      "id": "runtime-config",
-      "type": "file",
-      "path": "${dir:mesh-state}/config.json",
-      "mode": "0600",
-      "content": "{}\n",
-      "merge": "json"
-    },
-    {
-      "id": "runtime",
-      "type": "container",
-      "name": "mesh-tautulli",
-      "network": "host",
-      "volumes": [
-        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
-        "${dir:mesh-state}/config.json:/run/config/config.json:ro",
-        "/services/tautulli/config:/var/lib/tautulli/config:ro"
-      ],
-      "env": {
-        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_TAUTULLI_URL": "http://127.0.0.1:8181",
-        "MESH_TAUTULLI_CONFIG_FILE": "/run/config/config.json",
-        "MESH_TAUTULLI_CONFIG_DIR": "/var/lib/tautulli/config"
-      },
-      "restart-on": [
-        "runtime-config"
-      ],
-      "artifact": "runtime"
-    }
-  ],
-  "requires": [
-    "route"
-  ],
-  "contributes": {
-    "route": {
-      "label": "tautulli",
-      "endpoint": "web"
-    }
-  },
-  "binds": {
-    "route": "${dir:mesh-state}/route.json"
-  },
-  "build": {
-    "on": [
-      {
-        "arg": "BUILD_BASE",
-        "module": "mesh-tools",
-        "artifact": "build"
-      },
-      {
-        "arg": "RUNTIME_BASE",
-        "module": "mesh-tools",
-        "artifact": "runtime"
-      }
-    ],
-    "artifacts": [
-      {
-        "name": "runtime",
-        "kind": "image",
-        "from": "Dockerfile"
-      }
-    ]
-  }
-}

modules/tautulli/package.json

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