Phase 3: asus-zephyrus-g14 and memory-pressure, with Go tools and long-running code

The laptop model's hardware module and a memory-pressure module for any machine (hq research 027/03, 026/05, to-be 42 phase 3). The predecessor's polling auto-profile and mem-guard user scripts become each module's own Go code launched by the node runtime (ADR 0198): a profile switcher woken by the kernel's power-supply uevents, and a guard that warns on RAM, swap or PSI before systemd-oomd acts, on the desktop over the account's bus and always as an event. supergfxctl and triggerhappy are kept as found (research 027 Q1).
Merge pull request 'The photo clients publish the endpoint they declare (hq issue 227)' (#263 ) from fix/the-photo-admin-client-publishes-the-port-it-declares into main
2026-10-04 12:56:23 +02:00 · 2026-10-04 10:27:22 +00:00 · 2026-10-04 12:25:28 +02:00 · 2026-10-04 10:17:23 +00:00 · 2026-10-04 12:17:08 +02:00 · 2026-10-04 10:01:17 +00:00
431 changed files with 52031 additions and 8123 deletions
@@ -1,22 +0,0 @@
-# anthropic-consumer's runtime: the tool runtime, carrying this module's compiled code.
-#
-# **Built from this module's own directory and nothing else.** The sdk and the tool runtime are in
-# the base images, published like any other artifact — which is what makes this buildable by the
-# mesh from a repository and a path (novox/hq ADR 0069) rather than only on a workstation that
-# happens to have the siblings.
-#
-# Two bases, named rather than pinned (novox/hq issue 044): the image this is COMPILED in and the
-# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
-ARG BUILD_BASE
-ARG RUNTIME_BASE
-
-FROM ${BUILD_BASE} AS build
-WORKDIR /app/modules/anthropic-consumer
-COPY . .
-RUN node /app/node_modules/typescript/bin/tsc apply/index.ts usage/index.ts \
-      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
-
-FROM ${RUNTIME_BASE}
-COPY --from=build /app/modules/anthropic-consumer/dist /app/modules/anthropic-consumer/dist
-# No serve-time entrypoints: every container of this module names its command (`run` on a
-# schedule), so nothing here serves — deliberately no MESH_TOOL_MODULES.
@@ -9,29 +9,20 @@
    "model-access"
  ],
  "binds": {
-    "model-access": "/var/lib/anthropic-consumer/model.json"
+    "model-access": "${dir:state}/model.json"
  },
  "secrets": {
-    "model-access": "/var/lib/anthropic-consumer/access-token"
-  },
-  "own-secrets": {
-    "broker": "/var/lib/mesh/anthropic-consumer/broker"
+    "model-access": "${dir:state}/access-token"
  },
  "emits": [
    "usage.session"
  ],
  "resources": [
-    {
-      "id": "mesh-state",
-      "type": "directory",
-      "path": "/var/lib/mesh/anthropic-consumer",
-      "mode": "0700"
-    },
    {
      "id": "state",
      "type": "directory",
-      "path": "/var/lib/anthropic-consumer",
-      "mode": "0700"
+      "mode": "0700",
+      "place": "."
    },
    {
      "id": "claude-home",
@@ -42,71 +33,43 @@
    {
      "id": "out",
      "type": "directory",
-      "path": "/var/lib/anthropic-consumer/out",
      "mode": "0700"
    },
    {
      "id": "apply",
-      "type": "container",
-      "name": "mesh-anthropic-consumer-apply",
-      "network": "host",
+      "type": "process",
+      "name": "anthropic-consumer-apply",
+      "artifact": "code",
+      "run": [
+        "node",
+        "apply/index.js"
+      ],
      "schedule": "*/5 * * * *",
-      "args": [
-        "run",
-        "/app/modules/anthropic-consumer/dist/apply/index.js"
-      ],
-      "volumes": [
-        "/var/lib/anthropic-consumer:/run/state"
-      ],
      "env": {
-        "MESH_MODEL_ACCESS_SECRET_FILE": "/run/state/access-token",
-        "MESH_MODEL_ACCESS_BIND_FILE": "/run/state/model.json",
-        "MESH_CLAUDE_CREDENTIALS_FILE": "/run/state/claude/.credentials.json",
-        "MESH_CLAUDE_IDENTITY_FILE": "/run/state/claude/.claude.json"
-      },
-      "artifact": "runtime"
-    },
-    {
-      "id": "usage",
-      "type": "container",
-      "name": "mesh-anthropic-consumer-usage",
-      "network": "host",
-      "schedule": "*/5 * * * *",
-      "args": [
-        "run",
-        "/app/modules/anthropic-consumer/dist/usage/index.js"
-      ],
-      "volumes": [
-        "/var/lib/mesh/anthropic-consumer/broker:/run/secrets/broker:ro",
-        "/var/lib/anthropic-consumer:/run/state"
-      ],
-      "env": {
-        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_CLAUDE_PROJECTS_DIR": "/run/state/claude/projects",
-        "MESH_ANTHROPIC_USAGE_OUT": "/run/state/out/session-usage.json",
-        "MESH_TOOLS_MAIN": "/app/dist/main.js"
-      },
-      "artifact": "runtime"
+        "MESH_MODEL_ACCESS_SECRET_FILE": "${dir:state}/access-token",
+        "MESH_MODEL_ACCESS_BIND_FILE": "${dir:state}/model.json",
+        "MESH_CLAUDE_CREDENTIALS_FILE": "${dir:state}/claude/.credentials.json",
+        "MESH_CLAUDE_IDENTITY_FILE": "${dir:state}/claude/.claude.json"
+      }
    }
  ],
  "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"
+        "name": "code",
+        "kind": "bundle",
+        "language": "typescript",
+        "entrypoints": [
+          "apply/index.js",
+          "usage/index.js"
+        ],
+        "loads": [
+          "usage/index.js"
+        ],
+        "env": {
+          "MESH_CLAUDE_PROJECTS_DIR": "${dir:state}/claude/projects",
+          "MESH_ANTHROPIC_USAGE_OUT": "${dir:state}/out/session-usage.json"
+        }
      }
    ]
  }
@@ -3,12 +3,15 @@
 // per session. The consumer IS the (node,module) session's fixed binding, so no per-message account
 // attribution is done — just the totals (port map "don't-map" #3).
 //
-// Runs as `mesh-tools run` (no broker), so events are emitted best-effort via the sibling mesh-tools
-// `emit` primitive; the totals are also written to a file so the reading is observable without one.
+// Runs in the node's runtime (novox/hq ADR 0198), every five minutes, so events are emitted through
+// the runtime as this module; the totals are also written to a file so the reading is observable
+// without one.

 import { readdirSync, statSync, readFileSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";

+import { emit } from "@novox/mesh-sdk/events";
+
 import { readSessionFile, type SessionUsage } from "../transcript.js";

 /** The vendor-neutral usage row ADR 0054 fixes — the shape the model-usage store upserts. Kept local
@@ -116,22 +119,20 @@ function atomicWrite(path: string, content: string): void {
  renameSync(tmp, path);
 }

-/** Emit best-effort via the sibling mesh-tools `emit`, which wires a broker a run step has none. */
+/** Emit best-effort through the runtime: a reading that could not be announced is still in the file. */
 async function emitUsage(body: Record<string, unknown>): Promise<void> {
-  const main = process.env.MESH_TOOLS_MAIN ?? "/app/dist/main.js";
-  const { spawn } = await import("node:child_process");
-  await new Promise<void>((resolve) => {
-    const child = spawn(
-      process.execPath,
-      [main, "emit", "usage.session", JSON.stringify(body)],
-      { stdio: "inherit" },
-    );
-    child.on("exit", () => resolve());
-    child.on("error", (err) => {
-      console.error(`[anthropic-consumer] could not emit usage: ${err}`);
-      resolve();
-    });
-  });
+  try {
+    await emit("usage.session", body);
+  } catch (err) {
+    console.error(`[anthropic-consumer] could not emit usage: ${err}`);
+  }
 }

-await main();
+// The cadence the scheduled container had: once at start, then every five minutes. Not awaited, so the
+// runtime's handshake is answered while a long first reading is still under way.
+const EVERY_MS = 5 * 60 * 1000;
+const tick = (): void => {
+  void main().catch((err) => console.error(`[anthropic-consumer] usage reading failed: ${err}`));
+};
+tick();
+setInterval(tick, EVERY_MS);
@@ -9,13 +9,13 @@
    "model-access"
  ],
  "binds": {
-    "model-access": "/var/lib/mesh/anthropic-manager/model.json"
+    "model-access": "${dir:mesh-state}/model.json"
  },
  "secrets": {
-    "model-access": "/var/lib/mesh/anthropic-manager/refresh-token"
+    "model-access": "${dir:mesh-state}/refresh-token"
  },
  "own-secrets": {
-    "broker": "/var/lib/mesh/anthropic-manager/broker"
+    "broker": "${dir:mesh-state}/broker"
  },
  "emits": [
    "usage.read"
@@ -24,13 +24,13 @@
    {
      "id": "mesh-state",
      "type": "directory",
-      "path": "/var/lib/mesh/anthropic-manager",
-      "mode": "0700"
+      "mode": "0700",
+      "place": "mesh"
    },
    {
      "id": "out",
      "type": "directory",
-      "path": "/var/lib/mesh/anthropic-manager/out",
+      "path": "${dir:mesh-state}/out",
      "mode": "0700"
    },
    {
@@ -45,8 +45,8 @@
        "/app/modules/anthropic-manager/dist/refresh/index.js"
      ],
      "volumes": [
-        "/var/lib/mesh/anthropic-manager/broker:/run/secrets/broker:ro",
-        "/var/lib/mesh/anthropic-manager:/run/state"
+        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "${dir:mesh-state}:/run/state"
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
@@ -0,0 +1,257 @@
+# asus-zephyrus-g14
+
+The hardware module for the **ASUS ROG Zephyrus G14** laptop: its vendor daemon and platform
+profiles, the hybrid GPU's mode and driver options, suspend, the lid and power key, low battery,
+the backlights, the vendor keys and the touchpad (novox/hq research 027/03 *Power management on
+the laptop*, research 026/05, to-be 42 phase 3).
+
+## Why this name
+
+A module is named after the hardware model, never the node (novox/hq ADR 0112; research 026/03:
+no flavors, no machine names). `asus-zephyrus-g14` is the model family exactly as the firmware
+reports it (`/sys/class/dmi/id/product_family` = `ROG Zephyrus G14`). The module's code checks that
+value and its switcher does nothing on any other model, and `zephyrus_check` reports it.
+
+A wider name such as `asus-rog-laptop` would promise what this module cannot keep. Its contents
+belong to this family: the vendor-key scan codes, the eDP panel beside an NVIDIA dGPU, and the NVIDIA
+D3 workaround. A second G14 is assigned the same module. Another ROG model gets its own.
+
+Written against the GA403 (2024, Ryzen 8945HS, RTX 4070 Laptop, hybrid). Older G14 years have the same
+daemons and probably the same keys. Their GPU options are unverified.
+
+## What it owns
+
+| | what | how |
+|---|---|---|
+| package | `asusctl` (asusd + client) | the distribution's package (`extra`). The machine was found with a local build of 6.4.0. The host only asserts *present*, so the switch to 6.5.0 from `extra` happens at the next `pacman -Syu` (or `pacman -S asusctl`). `zephyrus_check` flags a local build |
+| package | `upower`, `playerctl`, `xorg-xinput` | what the low-battery drop-in, the media keys and the touchpad key use |
+| service | `asusd` running (static unit: no boot state to declare), `supergfxd` running and enabled | |
+| archive | `/usr/local/lib/asus-zephyrus-g14/bin/` | the module's scripts, from `files/bin` (below) |
+| file | `/etc/modprobe.d/g14-nvidia-power.conf` | `NVreg_DynamicPowerManagement=0x00` (runtime D3 off: the ACPI D-Notifier hang) and `NVreg_PreserveVideoMemoryAllocations=1`. The path is adopted (ADR 0182) |
+| file | `/etc/modprobe.d/video-brightness-switch.conf` | `video.brightness_switch_enabled=0`, so the ACPI video driver does not also move a backlight on the keys. The file was on the machine and owned by nothing |
+| file ×3 | `systemd-{suspend,hibernate,suspend-then-hibernate}.service.d/asus-zephyrus-g14-nvidia.conf` | `Wants=` the matching `nvidia-*` sleep units and `nvidia-resume` (see *suspend units* below) |
+| file | `nvidia-powerd.service.d/asus-zephyrus-g14.conf` | `ConditionKernelCommandLine=zephyrus.nvidia-powerd`: Dynamic Boost runs only when the operator opts in at boot |
+| file | `/etc/systemd/logind.conf.d/power.conf` | the power key and the lid suspend, on battery, on mains and docked. `systemd-logind` is reloaded, never restarted |
+| file | `/etc/udev/rules.d/90-backlight.rules` | backlights writable by the `video` group. `systemd-udevd` is reloaded |
+| file | `triggerhappy.service.d/asus-zephyrus-g14.conf` | `thd … --user ${machine:account}`: the triggers run as the operator's account (below) |
+| file | `/etc/triggerhappy/triggers.d/asus-g14.conf` | the vendor keys: media (`KEY_PROG1/3/4`), panel brightness, touchpad (`KEY_F21`). The path is adopted, because two trigger files would fire every key twice |
+| file | `/etc/UPower/UPower.conf.d/50-asus-zephyrus-g14.conf` | low battery at 15/10/7 %; at 7 % **suspend**, not power off. A drop-in over the package's own file |
+| file | `/etc/X11/xorg.conf.d/30-asus-zephyrus-g14-touchpad.conf` | tap to click, natural scrolling, acceleration 0.15, as an X input class |
+
+**What it does not own, on purpose:**
+
+- `/etc/asusd/*.ron` belong to asusd, which rewrites them whenever a setting changes. RON is not a
+  format the host writes into (ADR 0102 speaks JSON and marked blocks). Owning the file whole would
+  repeat the predecessor's freeze: the measured file already differs from the one the predecessor
+  shipped. The settings the module needs are set through asusd, by its code (below).
+- `/etc/supergfxd.conf` and `/etc/modprobe.d/supergfxd.conf` belong to supergfxd, which writes both.
+- The swap file, its unit and the swap partition are the machine's swap layout (research 027,
+  question 3). They are not this module's, nor `memory-pressure`'s.
+- The i3 fragments (`~/.config/i3/config.d/10-asus.conf`, `20-g14.conf`) and the keyboard-backlight
+  notifier they start belong to phase 2 (the `i3` module).
+
+## Software outside the distribution (ADR 0205, research 027 question 1)
+
+`supergfxctl` (5.2.7, from the asus-linux repository, which is no longer configured) and
+`triggerhappy` (AUR) are **kept as found, and depended on**. The module declares no package for
+either, because the host installs from the official repositories only. It declares their services
+(`supergfxd` running, `triggerhappy` running), so on a machine without them the host refuses the
+service by name: *does not exist on this machine*. The refusal is loud, never a silent pass.
+`zephyrus_check` names both as foreign.
+
+This module does not choose between the options of research 027 question 1. Under the starting
+position (P2: the build machine builds AUR packages into a repository the mesh serves), both become
+`package` resources here, and a fresh G14 installs them. **Until P2 exists, a fresh G14 is blocked
+on installing these two by hand.** ADR 0205's vendored archive (P1) does not fit: supergfxctl is a
+daemon with a system-bus policy and udev rules, and triggerhappy is C.
+
+A later option for the keys: the module's own Go code could read the vendor keys from evdev, which
+the operator's account may do through the `input` group. That would retire triggerhappy entirely.
+It is not done here, because it would put the keys behind the node's runtime, and the runtime
+restarts a bundle that dies only on its next call (below).
+
+## The long-running code: the profile switcher (ADR 0198)
+
+The module's Go bundle serves the tools and runs the platform-profile switcher in the same process.
+The node's runtime launches the bundle at the runtime's start. It replaces the predecessor's
+`auto-profile`, a user unit that woke every five seconds, on battery too.
+
+- **Policy** (constants until settings exist, issue 168): battery → `Quiet`; mains → `Balanced`;
+  mains with the CPU at or above 50 % for 3 samples of 10 s → `Performance`, back to `Balanced` after
+  3 samples at or below 20 %. Between the lines nothing moves (hysteresis). iowait counts as idle.
+- **Woken by events, not a poll.** The kernel's power-supply uevents (netlink, group 1) wake the
+  switcher. Any account may listen on that group, and it needs no daemon, bus client or dependency;
+  upower re-announces the same changes but would need a D-Bus client in the bundle. The CPU is
+  sampled only on mains, every 10 s, because only there does the answer depend on it. On battery,
+  a safety re-read every 5 minutes covers an event lost across a suspend. If the uevent socket
+  cannot be opened, the switcher polls every 10 s and says so in `zephyrus_profile_policy`.
+- **The battery decides the source.** A battery that is *discharging* means battery, whatever any
+  adapter says. The predecessor took any `online` file reading 1 as mains, and on this model the USB-C
+  ports report `online`. Batteries of `scope=Device` (a mouse, a headset) are ignored.
+- **It acts on a change of its decision, never to restore one.** A profile someone chose by hand (the
+  profile key, asusctl, `zephyrus_profile`) stays until the power source changes or the load crosses
+  a line. The predecessor re-asserted its choice every five seconds, which made the profile key
+  useless. **Starting is not a decision**: the runtime restarts the bundle on every push that changes
+  one, and a push must not reset the operator's profile.
+- **A hold.** `zephyrus_profile` holds the profile it sets for 60 min (`hold_minutes`). A change of
+  power source ends the hold.
+- **One assertion at start:** through asusctl, the charge limit (80 %) and asusd's own on-mains and
+  on-battery profiles (`Balanced`, `Quiet`), each read first and set only if it differs. asusd's own
+  switching on a change of power source then agrees with the switcher's. A limit set later with
+  `zephyrus_charge_limit` stands until the bundle next starts. For a one-off full charge, use its
+  `oneshot`.
+- **Events:** `profile.switched` (`profile`, `from`, `reason`, `source`), published through the
+  runtime.
+
+No root is involved. asusd's and supergfxd's bus policies admit the `users` and `wheel` groups, and the
+runtime runs as the operator's account. The one write that may escalate is the panel's backlight,
+when the udev rule has not run yet. It uses `sudo -n` and never prompts. Every command is bounded at
+20 s.
+
+**Known limit.** The runtime restarts a launched bundle that exits *on its next tool call*, not at
+once (mesh-tools `launch.ts`), so a crashed switcher stays down until a tool is called. ADR 0198 §1
+says *started again when it exits*. The switcher recovers from a panic and reports it in
+`zephyrus_profile_policy` and `zephyrus_check`, but a crash of the process is the runtime's to restart.
+
+## The vendor keys and the scripts
+
+triggerhappy opens the input devices as root, then **drops to the operator's account with its groups**
+(`initgroups`: `input`, `video`). The packaged unit already drops to `nobody`, and the module's drop-in
+names the account instead. The predecessor replaced the packaged unit with one that ran every trigger
+as root, then `su`-ed to a named person with a hard-coded uid and display, and sourced a file of
+secrets on the way (research 027 question 2). Now:
+
+- `zephyrus-session CMD…`: runs a command in the account's graphical session. It sets the account's
+  own bus (`/run/user/<uid>/bus`) and finds the display from logind, or from a process of the account
+  that has one. Nothing is sourced.
+- `zephyrus-backlight + | - | N`: the panel in 5 % steps, never below 1 %. **The panel is the
+  backlight under the eDP connector**, because this model also registers `nvidia_0`, which moves
+  nothing. The predecessor named `amdgpu_bl1` literally.
+- `zephyrus-notify ID TEXT`: one replacing notification, through `busctl` (the service manager's
+  client, so no libnotify).
+- `zephyrus-touchpad reset | toggle`: bound to the touchpad key (`KEY_F21`).
+
+**Media keys** go to MPRIS through `playerctl`. The predecessor's Plex fallback needed a Plex token
+from the secrets file and is dropped until a module can be handed a secret (research 027 question 2).
+
+## The touchpad: an input class instead of a sleep hook
+
+The predecessor re-ran `xinput` from `/etc/systemd/system-sleep/` after every resume, as a named person
+on a guessed display, because settings made with `xinput` are lost when the device initialises again.
+An X input class is applied by X **every time the device appears**: at login, on hotplug and after a
+resume. So the cause is fixed, and the hook is gone. The class matches any touchpad on the machine,
+which is the model's, so it holds across G14 years whose touchpads differ. It takes effect at the next
+X start. `zephyrus-touchpad reset` stays as the manual form.
+
+## Suspend units without enabling them
+
+`nvidia-suspend`, `-hibernate`, `-suspend-then-hibernate` and `-resume` are enabled with links in the
+sleep services' `.wants` directories. The mesh makes no links (ADR 0012). The host's service shape
+cannot declare them either: it may only say *running* or *stopped*, and *running* on a one-shot that
+last failed would start `nvidia-sleep.sh suspend` with the machine awake. So the module asks for them
+from the other side: a drop-in on each sleep service that `Wants=` them. The units' own
+`Before=`/`After=` order them. The found links stay and are harmless.
+
+`suspend-then-hibernate` now also gets `nvidia-suspend-then-hibernate`, which the machine lacked.
+
+The drop-ins take effect at the service manager's next `daemon-reload`. In the same apply, the restart
+of `triggerhappy` (whose drop-in changes) performs one.
+
+## Tools
+
+| tool | r/a | what |
+|---|---|---|
+| `zephyrus_brightness` | r/a | panel (percent or ±step, floor 1 %) and keyboard (off/low/med/high, 0-3, ±) through asusd |
+| `zephyrus_battery` | r | charge, energy in Wh, health (full ÷ design), cycles (the firmware reports 0, and this is said), limit, watts, hours left |
+| `zephyrus_charge_limit` | r/a | 20-100 through asusd; `oneshot` |
+| `zephyrus_gpu_mode` | r/a | mode, supported modes, dGPU power, the pending mode and action; says that asusd switches the mode on every change of power source |
+| `zephyrus_profile` | r/a | active, on-mains and on-battery profile, kernel platform profile; set with a hold |
+| `zephyrus_thermals` | r | every hwmon temperature and fan, the hottest, the dGPU's temperature **only when it is awake** (nvidia-smi wakes a suspended GPU) |
+| `zephyrus_power_draw` | r | battery flow, APU package power (PPT), dGPU draw when awake, power source and why |
+| `zephyrus_profile_policy` | r | what the switcher would choose now and why: source, recent load against the thresholds, decision, hold, last switch, what woke it, what it asserted at start, and whether the predecessor's switcher still runs |
+| `zephyrus_fan_curves` | r | asusd's curves per profile and fan |
+| `zephyrus_check` | r | every expectation: model, packages (local or foreign), daemons, nvidia-powerd, sleep units, the NVIDIA options **in force** (`/proc/driver/nvidia/params`), charge limit, one authority each over the profile and the GPU mode, predecessor leftovers. It also lists what it did not check |
+
+`profile` is a candidate verb for a future `node-power-profile` seat (research 027/03). That seat has
+no record yet, so this is the module's own tool.
+
+## Found on the laptop, 2026-10-04 (read-only)
+
+- **Two authorities over the GPU mode.** `asusd.ron` has `ac_command: "supergfxctl -m Hybrid"` and
+  `bat_command: "supergfxctl -m Integrated"`, so asusd switches the GPU mode on every change of power
+  source. **supergfxd 5.2.7 cannot read logind's sessions** (`manager is an invalid variant`, every
+  boot), so a switch that needs a logout times out. `zephyrus_check` reports both. The fix is the
+  operator's, in asusd's file: clear both commands, or update supergfxctl once it can be packaged.
+- **`brightness.conf` did nothing.** `HandleBrightnessKey` is not a logind key, and logind logs
+  *Unknown key … ignoring* at every start. The module does not carry it. The brightness keys were
+  always triggerhappy's, with the ACPI video switch off.
+- **Two profile switchers** would run at once until `auto-profile` is stopped (below).
+- **asusctl is a local build** (6.4.0, *Unknown Packager*) beside a foreign `asusctl-debug`.
+
+## When assigned to the laptop: what changes
+
+1. `/usr/local/lib/asus-zephyrus-g14/` appears (four scripts).
+2. Written over found files (each original kept once by the host): `g14-nvidia-power.conf` and
+   `video-brightness-switch.conf` (same options, so no change until the next boot either),
+   `logind.conf.d/power.conf` (same keys; logind reloaded), `90-backlight.rules` (same effect;
+   udevd reloaded), `triggers.d/asus-g14.conf` (now the module's scripts).
+3. New: the three sleep drop-ins (behaviour gained: `nvidia-suspend-then-hibernate`), the
+   nvidia-powerd drop-in (no effect while it is masked), the triggerhappy drop-in, the UPower drop-in
+   (same values as today), and the touchpad input class (at the next X start).
+4. `daemon-reload` and a `triggerhappy` restart. thd now runs as the account and the keys run the
+   module's scripts. `upower` restarts.
+5. Packages, asusd and supergfxd: already as declared, so nothing changes. asusctl stays the local
+   6.4.0 until the next upgrade.
+6. The node runtime restarts with the new bundle. The switcher asserts the limit (80, already) and
+   asusd's profiles (Balanced and Quiet, already), so it sets nothing. It takes the current decision
+   as applied and acts from the first event on.
+
+## Predecessor files this module makes redundant — the operator removes them once (ADR 0182)
+
+**On the laptop:**
+
+1. `systemctl --user disable --now auto-profile.service`, then delete
+   `~/.config/systemd/user/auto-profile.service` and `~/scripts/auto-profile`. **Do this right after
+   the push**, or two switchers run at once.
+2. `~/scripts/asus-bright`, `~/scripts/asusctl-kbd-bright`, `~/scripts/xrandr-bright`,
+   `~/scripts/as-user`, `~/scripts/media-control`: no trigger and no i3 binding uses them any more.
+3. `~/scripts/xinput-reset-touchpad`: still started and bound by `~/.config/i3/config.d/20-g14.conf`.
+   Point those two lines at `/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-touchpad reset`, or wait for
+   the i3 module (phase 2) to rewrite the fragment.
+4. `/etc/systemd/system/triggerhappy.service`: the predecessor's replacement of the packaged unit. The
+   module's drop-in works over either, so delete it and `systemctl daemon-reload` to return to the
+   packaged unit (`Type=notify`, socket).
+5. `/etc/systemd/logind.conf.d/brightness.conf`: the unknown key, which does nothing.
+6. `/etc/systemd/system-sleep/xinput-reset-touchpad.sh`: replaced by the input class.
+7. `/etc/UPower/UPower.conf`: the predecessor's replacement of the package's file. Its values are now
+   the module's drop-in. Restore the package's copy (`rm` it, then `pacman -S upower`).
+8. Optional: `systemctl disable nvidia-suspend nvidia-resume nvidia-hibernate` (the drop-ins carry them
+   now), `/etc/asusd/*.ron-old` and `fan_curves.ron.bak`, the foreign `asusctl-debug` package, and
+   `pacman -S asusctl` for the distribution's build.
+
+**Stays the machine's:** `/swapfile` and `/etc/systemd/system/swapfile.swap` (the swap layout),
+`/etc/udev/rules.d/91-monitor-hotplug.rules` (the display's, phase 2), and the i3 fragments.
+
+**On the desktop** (the predecessor's G14 flavor reached it; part was removed on 2026-10-04): none of
+this module applies there. Still present and to be deleted:
+`/etc/systemd/logind.conf.d/brightness.conf`, `/etc/systemd/system-sleep/xinput-reset-touchpad.sh`,
+`~/scripts/xinput-reset-touchpad`, `~/scripts/xrandr-bright` and
+`~/.config/i3/scripts/kbd-brightness-notify.sh`.
+
+## Tests
+
+`go test ./...` in this directory. Every tool runs against a tree standing in for `/sys`, `/proc` and
+`/etc`, and an injected runner answering with what asusctl 6.4 and supergfxctl 5.2 said on the laptop.
+The tests cover:
+
+- the power-source rule;
+- battery arithmetic from `charge_*`;
+- the eDP panel choice;
+- brightness bounds;
+- the policy's sustain, relax and hysteresis, with iowait counted as idle;
+- the switcher: no act at start, one switch per change of source, a published event, boost from
+  samples, holds, retry after failure, start-up assertions only where they differ, inert on another
+  model;
+- the uevent filter;
+- the manifest: tools listed equal tools served, no machine named, triggers exist, every key runs a
+  shipped executable script, every script passes `bash -n`.
@@ -0,0 +1,264 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"regexp"
+	"strconv"
+	"strings"
+)
+
+// The vendor daemons are reached through their own command-line clients, which speak to them on the
+// system bus. Their bus policy admits the `users` and `wheel` groups, so none of this needs root.
+
+// Profiles are the platform profiles asusd offers on this model, in its spelling.
+var Profiles = []string{"Quiet", "Balanced", "Performance"}
+
+// canonicalProfile accepts any case and answers asusd's spelling, or an error naming the choices.
+func canonicalProfile(s string) (string, error) {
+	for _, p := range Profiles {
+		if strings.EqualFold(strings.TrimSpace(s), p) {
+			return p, nil
+		}
+	}
+	return "", fmt.Errorf("profile %q is not one of %s", s, strings.Join(Profiles, ", "))
+}
+
+// ProfileState is what asusd says about the platform profile.
+type ProfileState struct {
+	Active   string `json:"active"`
+	OnAC     string `json:"on_ac,omitempty"`
+	Battery  string `json:"on_battery,omitempty"`
+	Platform string `json:"platform_profile,omitempty"`
+	Choices  string `json:"platform_profile_choices,omitempty"`
+}
+
+var (
+	activeProfile  = regexp.MustCompile(`(?m)^Active profile:\s*(\S+)`)
+	acProfile      = regexp.MustCompile(`(?m)^AC profile\s+(\S+)`)
+	batteryProfile = regexp.MustCompile(`(?m)^Battery profile\s+(\S+)`)
+)
+
+// ParseProfileGet reads `asusctl profile get`.
+func ParseProfileGet(out string) (ProfileState, error) {
+	var p ProfileState
+	if m := activeProfile.FindStringSubmatch(out); m != nil {
+		p.Active = m[1]
+	} else {
+		return p, fmt.Errorf("asusctl profile get said no active profile: %q", strings.TrimSpace(out))
+	}
+	if m := acProfile.FindStringSubmatch(out); m != nil {
+		p.OnAC = m[1]
+	}
+	if m := batteryProfile.FindStringSubmatch(out); m != nil {
+		p.Battery = m[1]
+	}
+	return p, nil
+}
+
+// Profile reads the platform profile from asusd and the kernel.
+func (m *Machine) Profile(ctx context.Context) (ProfileState, error) {
+	out, err := m.Run(ctx, "asusctl", "profile", "get")
+	if err != nil {
+		return ProfileState{}, vendor("asusctl", err)
+	}
+	p, err := ParseProfileGet(out)
+	if err != nil {
+		return p, err
+	}
+	p.Platform = m.read("/sys/firmware/acpi/platform_profile")
+	p.Choices = m.read("/sys/firmware/acpi/platform_profile_choices")
+	return p, nil
+}
+
+// SetProfile has asusd switch the active profile.
+func (m *Machine) SetProfile(ctx context.Context, profile string) error {
+	_, err := m.Run(ctx, "asusctl", "profile", "set", profile)
+	return vendor("asusctl", err)
+}
+
+var chargeLimit = regexp.MustCompile(`charge limit:\s*(\d+)\s*%`)
+
+// ChargeLimit is the battery's charge limit as asusd reports it.
+func (m *Machine) ChargeLimit(ctx context.Context) (int, error) {
+	out, err := m.Run(ctx, "asusctl", "battery", "info")
+	if err != nil {
+		return 0, vendor("asusctl", err)
+	}
+	g := chargeLimit.FindStringSubmatch(out)
+	if g == nil {
+		return 0, fmt.Errorf("asusctl battery info said no limit: %q", strings.TrimSpace(out))
+	}
+	n, _ := strconv.Atoi(g[1])
+	return n, nil
+}
+
+// Keyboard backlight levels in asusd's spelling, index = the kernel's brightness value.
+var KeyboardLevels = []string{"off", "low", "med", "high"}
+
+var ledLevel = regexp.MustCompile(`(?i)brightness:\s*(off|low|med|high)`)
+
+// ParseLeds reads `asusctl leds get`.
+func ParseLeds(out string) (string, error) {
+	g := ledLevel.FindStringSubmatch(out)
+	if g == nil {
+		return "", fmt.Errorf("asusctl leds get said no level: %q", strings.TrimSpace(out))
+	}
+	return strings.ToLower(g[1]), nil
+}
+
+// FanCurve is one fan's curve in one profile: eight points of temperature (°C) and duty (0-255).
+type FanCurve struct {
+	Fan     string `json:"fan"`
+	Enabled bool   `json:"enabled"`
+	Temp    []int  `json:"temp_c"`
+	PWM     []int  `json:"pwm"`
+}
+
+var (
+	fanBlock = regexp.MustCompile(`(?s)fan:\s*(\w+),\s*pwm:\s*\(([^)]*)\),\s*temp:\s*\(([^)]*)\),\s*enabled:\s*(true|false)`)
+)
+
+// ParseFanCurves reads `asusctl fan-curve --mod-profile <p>`.
+func ParseFanCurves(out string) []FanCurve {
+	var curves []FanCurve
+	for _, g := range fanBlock.FindAllStringSubmatch(out, -1) {
+		curves = append(curves, FanCurve{Fan: g[1], PWM: ints(g[2]), Temp: ints(g[3]), Enabled: g[4] == "true"})
+	}
+	return curves
+}
+
+func ints(list string) []int {
+	var out []int
+	for _, f := range strings.Split(list, ",") {
+		if n, err := strconv.Atoi(strings.TrimSpace(f)); err == nil {
+			out = append(out, n)
+		}
+	}
+	return out
+}
+
+// GPUState is what supergfxd says about the hybrid GPU.
+type GPUState struct {
+	Mode          string   `json:"mode"`
+	Supported     []string `json:"supported"`
+	Power         string   `json:"dgpu_power,omitempty"`
+	PendingAction string   `json:"pending_action,omitempty"`
+	PendingMode   string   `json:"pending_mode,omitempty"`
+	Vendor        string   `json:"dgpu_vendor,omitempty"`
+}
+
+// ParseSupported reads `supergfxctl -s`: `[Integrated, Hybrid, AsusMuxDgpu]`.
+func ParseSupported(out string) []string {
+	out = strings.Trim(strings.TrimSpace(out), "[]")
+	var modes []string
+	for _, f := range strings.Split(out, ",") {
+		if f = strings.TrimSpace(f); f != "" {
+			modes = append(modes, f)
+		}
+	}
+	return modes
+}
+
+// GPU reads supergfxd.
+func (m *Machine) GPU(ctx context.Context) (GPUState, error) {
+	var g GPUState
+	mode, err := m.Run(ctx, "supergfxctl", "-g")
+	if err != nil {
+		return g, vendor("supergfxctl", err)
+	}
+	g.Mode = strings.TrimSpace(mode)
+	if s, err := m.Run(ctx, "supergfxctl", "-s"); err == nil {
+		g.Supported = ParseSupported(s)
+	}
+	if s, err := m.Run(ctx, "supergfxctl", "-S"); err == nil {
+		g.Power = strings.TrimSpace(s)
+	}
+	if s, err := m.Run(ctx, "supergfxctl", "-p"); err == nil {
+		g.PendingAction = strings.TrimSpace(s)
+	}
+	if s, err := m.Run(ctx, "supergfxctl", "-P"); err == nil {
+		g.PendingMode = strings.TrimSpace(s)
+	}
+	if s, err := m.Run(ctx, "supergfxctl", "-V"); err == nil {
+		g.Vendor = strings.TrimSpace(s)
+	}
+	return g, nil
+}
+
+// vendor names a vendor client that is not installed, rather than passing on "executable file not
+// found". asusctl is in the distribution's repositories; supergfxctl is not, and the module keeps it as
+// it was found until the mesh can build packages from the user repository (research 027, question 1).
+func vendor(name string, err error) error {
+	if err == nil {
+		return nil
+	}
+	if notInstalled(err) {
+		switch name {
+		case "supergfxctl":
+			return fmt.Errorf("supergfxctl is not installed: it is not in the distribution's repositories, " +
+				"and this module keeps the copy it finds rather than install one (novox/hq research 027, question 1)")
+		default:
+			return fmt.Errorf("%s is not installed; the module's package resource installs it", name)
+		}
+	}
+	return err
+}
+
+// AsusdConfig is the few settings of asusd's own file that decide what this module's code does. The
+// file is asusd's: it rewrites it whenever a setting changes, so the module reads it and never writes
+// it.
+type AsusdConfig struct {
+	ChargeLimit          *int   `json:"charge_control_end_threshold,omitempty"`
+	ProfileOnAC          string `json:"platform_profile_on_ac,omitempty"`
+	ProfileOnBattery     string `json:"platform_profile_on_battery,omitempty"`
+	ChangesProfileOnAC   *bool  `json:"change_platform_profile_on_ac,omitempty"`
+	ChangesProfileOnBatt *bool  `json:"change_platform_profile_on_battery,omitempty"`
+	ACCommand            string `json:"ac_command,omitempty"`
+	BatteryCommand       string `json:"bat_command,omitempty"`
+	DisablesPowerdOnBatt *bool  `json:"disable_nvidia_powerd_on_battery,omitempty"`
+}
+
+var ronField = regexp.MustCompile(`(?m)^\s{4}([a-z_]+):\s*(.*?),?\s*$`)
+
+// ParseAsusdRon reads the top-level scalar fields of asusd.ron. RON is not a format the mesh
+// speaks; these are one line each, and nothing nested is read.
+func ParseAsusdRon(text string) AsusdConfig {
+	var c AsusdConfig
+	for _, g := range ronField.FindAllStringSubmatch(text, -1) {
+		key, value := g[1], strings.TrimSuffix(strings.TrimSpace(g[2]), ",")
+		unquoted := strings.Trim(value, `"`)
+		boolean := func() *bool { b := value == "true"; return &b }
+		switch key {
+		case "charge_control_end_threshold":
+			if n, err := strconv.Atoi(value); err == nil {
+				c.ChargeLimit = &n
+			}
+		case "platform_profile_on_ac":
+			c.ProfileOnAC = unquoted
+		case "platform_profile_on_battery":
+			c.ProfileOnBattery = unquoted
+		case "change_platform_profile_on_ac":
+			c.ChangesProfileOnAC = boolean()
+		case "change_platform_profile_on_battery":
+			c.ChangesProfileOnBatt = boolean()
+		case "ac_command":
+			c.ACCommand = unquoted
+		case "bat_command":
+			c.BatteryCommand = unquoted
+		case "disable_nvidia_powerd_on_battery":
+			c.DisablesPowerdOnBatt = boolean()
+		}
+	}
+	return c
+}
+
+// Asusd reads asusd's file; nil when it is not there.
+func (m *Machine) Asusd() *AsusdConfig {
+	text := m.read("/etc/asusd/asusd.ron")
+	if text == "" {
+		return nil
+	}
+	c := ParseAsusdRon(text)
+	return &c
+}
@@ -0,0 +1,146 @@
+package main
+
+import (
+	"context"
+	"strings"
+	"testing"
+)
+
+// What asusctl 6.4 and supergfxctl 5.2 said on the laptop on 2026-10-04.
+const fanCurveQuiet = `
+Fan curves for Quiet
+
+[
+    (
+        fan: CPU,
+        pwm: (2, 0, 10, 20, 35, 55, 80, 100),
+        temp: (35, 45, 50, 55, 60, 65, 70, 80),
+        enabled: true,
+    ),
+    (
+        fan: GPU,
+        pwm: (0, 0, 10, 20, 35, 65, 90, 115),
+        temp: (35, 45, 50, 55, 60, 65, 70, 80),
+        enabled: false,
+    ),
+]
+`
+
+const asusdRon = `(
+    charge_control_end_threshold: 80,
+    base_charge_control_end_threshold: 0,
+    disable_nvidia_powerd_on_battery: true,
+    ac_command: "supergfxctl -m Hybrid",
+    bat_command: "supergfxctl -m Integrated",
+    platform_profile_linked_epp: true,
+    platform_profile_on_battery: Quiet,
+    change_platform_profile_on_battery: true,
+    platform_profile_on_ac: Balanced,
+    change_platform_profile_on_ac: true,
+    ac_profile_tunings: {
+        Quiet: (
+            enabled: false,
+            group: {},
+        ),
+    },
+)`
+
+func TestAsusctlsAnswersAreRead(t *testing.T) {
+	p, err := ParseProfileGet(profileGetBalanced)
+	if err != nil || p.Active != "Balanced" || p.OnAC != "Balanced" || p.Battery != "Quiet" {
+		t.Fatalf("%+v %v", p, err)
+	}
+	if _, err := ParseProfileGet("something else"); err == nil {
+		t.Fatal("an answer with no profile was read as one")
+	}
+	if l, err := ParseLeds("Current keyboard led brightness: High\n"); err != nil || l != "high" {
+		t.Fatalf("%q %v", l, err)
+	}
+	curves := ParseFanCurves(fanCurveQuiet)
+	if len(curves) != 2 || curves[0].Fan != "CPU" || curves[0].PWM[7] != 100 || curves[0].Temp[0] != 35 || curves[1].Enabled {
+		t.Fatalf("%+v", curves)
+	}
+	if got := ParseSupported("[Integrated, Hybrid, AsusMuxDgpu]\n"); strings.Join(got, ",") != "Integrated,Hybrid,AsusMuxDgpu" {
+		t.Fatalf("%v", got)
+	}
+}
+
+func TestAsusdsFileIsReadForWhatDecidesTheModulesCodeAndNothingNested(t *testing.T) {
+	c := ParseAsusdRon(asusdRon)
+	if *c.ChargeLimit != 80 || c.ProfileOnAC != "Balanced" || c.ProfileOnBattery != "Quiet" ||
+		c.ACCommand != "supergfxctl -m Hybrid" || c.BatteryCommand != "supergfxctl -m Integrated" ||
+		!*c.ChangesProfileOnAC || !*c.DisablesPowerdOnBatt {
+		t.Fatalf("%+v", c)
+	}
+}
+
+func TestAMissingVendorClientIsNamedWithWhyItIsMissing(t *testing.T) {
+	f := newFake(t)
+	f.fails["supergfxctl"] = notFound
+	_, err := f.machine().GPU(context.Background())
+	if err == nil || !strings.Contains(err.Error(), "research 027") {
+		t.Fatalf("%v", err)
+	}
+	f.fails["asusctl"] = notFound
+	_, err = f.machine().Profile(context.Background())
+	if err == nil || !strings.Contains(err.Error(), "package resource installs it") {
+		t.Fatalf("%v", err)
+	}
+}
+
+func TestAGPUModeIsSetOnlyWhenTheMachineSupportsItAndAsusdsSwitchingIsSaid(t *testing.T) {
+	f := newFake(t)
+	f.answers["supergfxctl -g"] = "Hybrid\n"
+	f.answers["supergfxctl -s"] = "[Integrated, Hybrid, AsusMuxDgpu]\n"
+	f.file("/etc/asusd/asusd.ron", asusdRon)
+	m := f.machine()
+	if _, err := GPUModeTool(context.Background(), m, map[string]any{"mode": "Vfio"}); err == nil {
+		t.Fatal("an unsupported mode was accepted")
+	}
+	out, err := GPUModeTool(context.Background(), m, map[string]any{"mode": "integrated"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !f.called("supergfxctl -m Integrated") {
+		t.Fatalf("calls %v", f.calls)
+	}
+	if _, said := out.(map[string]any)["asusd_switches_it"]; !said {
+		t.Fatalf("asusd's own switching of the mode was not said: %+v", out)
+	}
+}
+
+func TestTheChargeLimitIsBoundedAndSetThroughAsusd(t *testing.T) {
+	f := newFake(t)
+	f.answers["asusctl battery info"] = "Current battery charge limit: 60%\n"
+	m := f.machine()
+	for _, bad := range []any{float64(10), float64(101), "x", 55.5} {
+		if _, err := ChargeLimitTool(context.Background(), m, map[string]any{"limit": bad}); err == nil {
+			t.Errorf("limit %v was accepted", bad)
+		}
+	}
+	out, err := ChargeLimitTool(context.Background(), m, map[string]any{"limit": float64(60)})
+	if err != nil || !f.called("asusctl battery limit 60") || out.(map[string]any)["asusd_limit_percent"] != 60 {
+		t.Fatalf("%+v %v %v", out, err, f.calls)
+	}
+}
+
+func TestAProfileSetByToolIsHeldAndAnUnknownOneRefused(t *testing.T) {
+	f := newFake(t)
+	f.onMains()
+	f.answers["asusctl profile get"] = profileGetBalanced
+	m := f.machine()
+	sw := NewSwitcher(m, nil)
+	if _, err := ProfileTool(context.Background(), m, sw, map[string]any{"profile": "Turbo"}); err == nil {
+		t.Fatal("an unknown profile was accepted")
+	}
+	out, err := ProfileTool(context.Background(), m, sw, map[string]any{"profile": "performance", "hold_minutes": float64(30)})
+	if err != nil || !f.called("asusctl profile set Performance") {
+		t.Fatalf("%v %v", err, f.calls)
+	}
+	if _, held := out.(map[string]any)["held_until"]; !held {
+		t.Fatalf("not held: %+v", out)
+	}
+	if r := sw.Report(); r.Held != "Performance" {
+		t.Fatalf("%+v", r)
+	}
+}
@@ -0,0 +1,184 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+)
+
+// Check is one thing the module expects of the machine, and whether it holds.
+type Check struct {
+	Name   string `json:"name"`
+	OK     bool   `json:"ok"`
+	Detail string `json:"detail"`
+}
+
+// CheckReport is what zephyrus_check answers. NotChecked says what it did not look at, because a
+// check that reads as clean while skipping something is the predecessor's verifier again.
+type CheckReport struct {
+	Model      string   `json:"model"`
+	Checks     []Check  `json:"checks"`
+	Failing    int      `json:"failing"`
+	NotChecked []string `json:"not_checked"`
+}
+
+var (
+	pacmanVersion  = regexp.MustCompile(`(?m)^Version\s*:\s*(\S+)`)
+	pacmanPackager = regexp.MustCompile(`(?m)^Packager\s*:\s*(.+)$`)
+	nvidiaParam    = regexp.MustCompile(`(?m)^(\w+):\s*(\S+)`)
+)
+
+// ParseNvidiaParams reads /proc/driver/nvidia/params.
+func ParseNvidiaParams(text string) map[string]string {
+	out := map[string]string{}
+	for _, g := range nvidiaParam.FindAllStringSubmatch(text, -1) {
+		out[g[1]] = g[2]
+	}
+	return out
+}
+
+// predecessorProcess finds a running process whose command line names the predecessor's script.
+func (m *Machine) predecessorProcess(name string) (int, bool) {
+	for _, dir := range m.glob("/proc/[0-9]*") {
+		cmd := strings.ReplaceAll(m.read(dir+"/cmdline"), "\x00", " ")
+		if strings.Contains(cmd, "/"+name) && !strings.Contains(cmd, "zephyrus") {
+			var pid int
+			fmt.Sscanf(filepath.Base(dir), "%d", &pid)
+			return pid, true
+		}
+	}
+	return 0, false
+}
+
+func (m *Machine) unitIs(ctx context.Context, verb, unit string) string {
+	out, _ := m.Run(ctx, "systemctl", verb, unit)
+	return strings.TrimSpace(out)
+}
+
+// Check reads every expectation and reports each.
+func (m *Machine) Check(ctx context.Context, sw *Switcher) CheckReport {
+	r := CheckReport{Model: m.Model(), NotChecked: []string{
+		"the fan curves (asusd's own, read them with zephyrus_fan_curves)",
+		"whether the initramfs carries the NVIDIA options (they are read from the running driver instead)",
+		"the vendor keys themselves (press them)",
+	}}
+	add := func(name string, ok bool, format string, a ...any) {
+		r.Checks = append(r.Checks, Check{Name: name, OK: ok, Detail: fmt.Sprintf(format, a...)})
+		if !ok {
+			r.Failing++
+		}
+	}
+	add("model", m.ThisModel(), "the firmware reports %q; this module is for %q", r.Model, ModelFamily)
+
+	// asusctl: present, and from the distribution rather than a local build.
+	if info, err := m.Run(ctx, "pacman", "-Qi", "asusctl"); err != nil {
+		add("asusctl package", false, "not installed: %v", err)
+	} else {
+		v, p := "", ""
+		if g := pacmanVersion.FindStringSubmatch(info); g != nil {
+			v = g[1]
+		}
+		if g := pacmanPackager.FindStringSubmatch(info); g != nil {
+			p = strings.TrimSpace(g[1])
+		}
+		local := p == "Unknown Packager"
+		add("asusctl package", !local, "version %s, packager %s%s", v, p,
+			map[bool]string{true: "; a local build — the distribution's package replaces it at the next upgrade (pacman -S asusctl)", false: ""}[local])
+	}
+	for _, foreign := range []string{"supergfxctl", "triggerhappy"} {
+		_, err := m.Run(ctx, "pacman", "-Q", foreign)
+		add(foreign+" package", err == nil, "%s; not in the distribution's repositories, kept as found (novox/hq research 027, question 1)",
+			map[bool]string{true: "installed", false: "NOT installed"}[err == nil])
+	}
+	for _, unit := range []string{"asusd.service", "supergfxd.service", "triggerhappy.service"} {
+		state := m.unitIs(ctx, "is-active", unit)
+		add(unit, state == "active", "%s", state)
+	}
+	powerd := m.unitIs(ctx, "is-enabled", "nvidia-powerd.service")
+	add("nvidia-powerd.service", powerd == "masked" || powerd == "disabled" || powerd == "" || strings.Contains(powerd, "not-found"),
+		"%s; the module's drop-in keeps it from starting unless the kernel command line says zephyrus.nvidia-powerd", orNone(powerd))
+	wants, _ := m.Run(ctx, "systemctl", "show", "-p", "Wants", "systemd-suspend.service")
+	add("nvidia suspend and resume", strings.Contains(wants, "nvidia-suspend.service") && strings.Contains(wants, "nvidia-resume.service"),
+		"systemd-suspend.service %s", strings.TrimSpace(wants))
+
+	params := ParseNvidiaParams(m.read("/proc/driver/nvidia/params"))
+	if len(params) == 0 {
+		add("nvidia options", false, "the NVIDIA driver is not loaded (no /proc/driver/nvidia/params)")
+	} else {
+		add("nvidia options", params["PreserveVideoMemoryAllocations"] == "1" && params["DynamicPowerManagement"] == "0",
+			"PreserveVideoMemoryAllocations=%s DynamicPowerManagement=%s (want 1 and 0; a change applies when the driver loads again)",
+			params["PreserveVideoMemoryAllocations"], params["DynamicPowerManagement"])
+	}
+
+	for _, b := range m.Batteries() {
+		ok := b.LimitPercent != nil && *b.LimitPercent == ChargeLimitPercent
+		have := "unknown"
+		if b.LimitPercent != nil {
+			have = fmt.Sprintf("%d%%", *b.LimitPercent)
+		}
+		add("charge limit", ok, "%s is %s, the module's is %d%%", b.Name, have, ChargeLimitPercent)
+	}
+
+	if c := m.Asusd(); c != nil && (c.ACCommand != "" || c.BatteryCommand != "") {
+		add("one authority over the GPU mode", false,
+			"asusd runs %q on mains and %q on battery: it switches the GPU mode on every change of power source, "+
+				"so a mode set with zephyrus_gpu_mode lasts until the next one. Clear ac_command and bat_command in /etc/asusd/asusd.ron (asusd's file) to make it the operator's alone",
+			c.ACCommand, c.BatteryCommand)
+	}
+	if out, err := m.Run(ctx, "journalctl", "-b", "-u", "supergfxd.service", "-g", "invalid variant", "-n", "1", "-q", "-o", "cat"); err == nil && strings.TrimSpace(out) != "" {
+		add("supergfxd and logind", false, "supergfxd cannot read logind's sessions this boot (%s): a mode change that needs a logout times out", strings.TrimSpace(out))
+	}
+
+	if pid, ok := m.predecessorProcess("auto-profile"); ok {
+		add("one profile switcher", false, "the predecessor's auto-profile still runs (pid %d) and switches the profile every five seconds; "+
+			"stop it: systemctl --user disable --now auto-profile.service", pid)
+	} else {
+		add("one profile switcher", true, "no predecessor auto-profile is running")
+	}
+	if sw != nil {
+		rep := sw.Report()
+		add("profile switcher", rep.Running, "%s", orNone(firstNonEmpty(rep.Disabled, rep.LastError, "woken by "+rep.Watching)))
+	}
+	if home := os.Getenv("MESH_OPERATOR_HOME"); home != "" {
+		var left []string
+		for _, p := range PredecessorHomeFiles {
+			if _, err := os.Stat(filepath.Join(m.Root, home, p)); err == nil {
+				left = append(left, "~/"+p)
+			}
+		}
+		add("predecessor files in the home", len(left) == 0, "%s", orNone(strings.Join(left, ", ")))
+	} else {
+		r.NotChecked = append(r.NotChecked, "the predecessor's files in the operator's home (MESH_OPERATOR_HOME is not set)")
+	}
+	return r
+}
+
+// PredecessorHomeFiles are what the predecessor placed in the operator's home for this model and this
+// module replaces. The mesh removes nothing it did not make (novox/hq ADR 0182): the operator does,
+// once, and this list is how the check knows.
+var PredecessorHomeFiles = []string{
+	"scripts/auto-profile",
+	".config/systemd/user/auto-profile.service",
+	"scripts/asus-bright",
+	"scripts/asusctl-kbd-bright",
+	"scripts/xrandr-bright",
+}
+
+func orNone(s string) string {
+	if strings.TrimSpace(s) == "" {
+		return "none"
+	}
+	return s
+}
+
+func firstNonEmpty(ss ...string) string {
+	for _, s := range ss {
+		if s != "" {
+			return s
+		}
+	}
+	return ""
+}
@@ -0,0 +1,202 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"math"
+	"os"
+	"path"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+// MinPanelPercent is the floor a brightness change never goes below: a panel at zero is a black
+// screen that looks like a dead machine, and the keys cannot be seen to bring it back.
+const MinPanelPercent = 1
+
+// Panel is the internal display's backlight.
+type Panel struct {
+	Device  string   `json:"device"`
+	Percent float64  `json:"percent"`
+	Raw     int64    `json:"raw"`
+	Max     int64    `json:"max"`
+	Others  []string `json:"other_backlights,omitempty"`
+}
+
+// panelDevice chooses the backlight that drives the internal panel.
+//
+// **This model registers two.** In hybrid mode the integrated GPU drives the panel (amdgpu_bl1,
+// beneath the eDP connector) and the discrete GPU's driver registers one of its own (nvidia_0) that
+// moves nothing. The predecessor's scripts named amdgpu_bl1 literally, which is right until the GPU
+// mode puts the panel on the other GPU. The one that sits under an eDP connector is the panel's; failing
+// that, the kernel's own preference: firmware, then platform, then raw.
+func (m *Machine) panelDevice() (string, []string, error) {
+	all := m.glob("/sys/class/backlight/*")
+	if len(all) == 0 {
+		return "", nil, fmt.Errorf("this machine has no backlight in /sys/class/backlight")
+	}
+	names := make([]string, 0, len(all))
+	for _, d := range all {
+		names = append(names, path.Base(d))
+	}
+	sort.Strings(names)
+	rank := func(name string) int {
+		dir := "/sys/class/backlight/" + name
+		if target, err := os.Readlink(m.path(dir)); err == nil && strings.Contains(target, "-eDP-") {
+			return 0
+		}
+		switch m.read(dir + "/type") {
+		case "firmware":
+			return 1
+		case "platform":
+			return 2
+		}
+		return 3
+	}
+	best := names[0]
+	for _, n := range names[1:] {
+		if rank(n) < rank(best) {
+			best = n
+		}
+	}
+	var others []string
+	for _, n := range names {
+		if n != best {
+			others = append(others, n)
+		}
+	}
+	return best, others, nil
+}
+
+// PanelBrightness reads the panel.
+func (m *Machine) PanelBrightness() (Panel, error) {
+	dev, others, err := m.panelDevice()
+	if err != nil {
+		return Panel{}, err
+	}
+	dir := "/sys/class/backlight/" + dev
+	raw, ok1 := m.readInt(dir + "/brightness")
+	max, ok2 := m.readInt(dir + "/max_brightness")
+	if !ok1 || !ok2 || max <= 0 {
+		return Panel{}, fmt.Errorf("%s does not say its brightness", dir)
+	}
+	return Panel{Device: dev, Raw: raw, Max: max, Percent: round1(float64(raw) / float64(max) * 100), Others: others}, nil
+}
+
+// PanelTarget turns a request — "40", "40%", "+5", "-10" — into the percentage to set, clamped to
+// [MinPanelPercent, 100].
+func PanelTarget(current float64, request string) (float64, error) {
+	r := strings.TrimSuffix(strings.TrimSpace(request), "%")
+	if r == "" {
+		return 0, fmt.Errorf("panel needs a percentage (40) or a step (+5, -5)")
+	}
+	n, err := strconv.ParseFloat(r, 64)
+	if err != nil || math.IsNaN(n) || math.IsInf(n, 0) {
+		return 0, fmt.Errorf("panel %q is not a percentage or a step", request)
+	}
+	target := n
+	if strings.HasPrefix(r, "+") || strings.HasPrefix(r, "-") {
+		target = current + n
+	}
+	return math.Max(MinPanelPercent, math.Min(100, target)), nil
+}
+
+// SetPanel sets the panel to a percentage.
+func (m *Machine) SetPanel(ctx context.Context, request string) (Panel, error) {
+	p, err := m.PanelBrightness()
+	if err != nil {
+		return p, err
+	}
+	target, err := PanelTarget(p.Percent, request)
+	if err != nil {
+		return p, err
+	}
+	raw := int64(math.Round(target / 100 * float64(p.Max)))
+	if raw < 1 {
+		raw = 1
+	}
+	if err := m.write(ctx, "/sys/class/backlight/"+p.Device+"/brightness", strconv.FormatInt(raw, 10)); err != nil {
+		return p, err
+	}
+	return m.PanelBrightness()
+}
+
+// Keyboard is the keyboard's backlight.
+type Keyboard struct {
+	Device string `json:"device"`
+	Level  string `json:"level"`
+	Value  int64  `json:"value"`
+	Max    int64  `json:"max"`
+}
+
+// KeyboardBrightness reads the keyboard backlight from the kernel.
+func (m *Machine) KeyboardBrightness() (Keyboard, error) {
+	found := m.glob("/sys/class/leds/*kbd_backlight*")
+	if len(found) == 0 {
+		return Keyboard{}, fmt.Errorf("this machine has no keyboard backlight in /sys/class/leds")
+	}
+	dir := found[0]
+	v, ok1 := m.readInt(dir + "/brightness")
+	max, ok2 := m.readInt(dir + "/max_brightness")
+	if !ok1 || !ok2 {
+		return Keyboard{}, fmt.Errorf("%s does not say its brightness", dir)
+	}
+	k := Keyboard{Device: path.Base(dir), Value: v, Max: max}
+	if max == int64(len(KeyboardLevels)-1) && v >= 0 && v <= max {
+		k.Level = KeyboardLevels[v]
+	}
+	return k, nil
+}
+
+// KeyboardTarget turns a request — off/low/med/high, 0-3, "+", "-" — into asusd's level name.
+func KeyboardTarget(current int64, request string) (string, error) {
+	r := strings.ToLower(strings.TrimSpace(request))
+	switch r {
+	case "medium":
+		r = "med"
+	case "+", "up":
+		r = strconv.FormatInt(min64(current+1, int64(len(KeyboardLevels)-1)), 10)
+	case "-", "down":
+		r = strconv.FormatInt(max64(current-1, 0), 10)
+	}
+	for _, l := range KeyboardLevels {
+		if r == l {
+			return l, nil
+		}
+	}
+	if n, err := strconv.Atoi(r); err == nil && n >= 0 && n < len(KeyboardLevels) {
+		return KeyboardLevels[n], nil
+	}
+	return "", fmt.Errorf("keyboard %q is not one of off, low, med, high, 0-3, + or -", request)
+}
+
+// SetKeyboard has asusd set the keyboard backlight, so its own record of the level stays true.
+func (m *Machine) SetKeyboard(ctx context.Context, request string) (Keyboard, error) {
+	k, err := m.KeyboardBrightness()
+	if err != nil {
+		return k, err
+	}
+	level, err := KeyboardTarget(k.Value, request)
+	if err != nil {
+		return k, err
+	}
+	if _, err := m.Run(ctx, "asusctl", "leds", "set", level); err != nil {
+		return k, vendor("asusctl", err)
+	}
+	return m.KeyboardBrightness()
+}
+
+func min64(a, b int64) int64 {
+	if a < b {
+		return a
+	}
+	return b
+}
+
+func max64(a, b int64) int64 {
+	if a > b {
+		return a
+	}
+	return b
+}
@@ -0,0 +1,91 @@
+package main
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// backlight makes a backlight the way sysfs does: a link from /sys/class/backlight into the device
+// tree, which is where the eDP connector shows.
+func (f *fake) backlight(name, device string, raw, max string) {
+	dev := "/sys/devices/" + device + "/" + name
+	f.file(dev+"/brightness", raw)
+	f.file(dev+"/max_brightness", max)
+	f.file(dev+"/type", "raw")
+	link := filepath.Join(f.root, "/sys/class/backlight", name)
+	os.MkdirAll(filepath.Dir(link), 0o755)
+	if err := os.Symlink(filepath.Join(f.root, dev), link); err != nil {
+		f.t.Fatal(err)
+	}
+}
+
+func TestThePanelIsTheBacklightUnderTheEDPConnectorNotTheDiscreteGPUs(t *testing.T) {
+	f := newFake(t)
+	f.backlight("amdgpu_bl1", "pci0000:00/0000:65:00.0/drm/card1/card1-eDP-1", "199500", "399000")
+	f.backlight("nvidia_0", "pci0000:00/0000:01:00.0/backlight", "100", "100")
+	p, err := f.machine().PanelBrightness()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if p.Device != "amdgpu_bl1" || p.Percent != 50 || len(p.Others) != 1 || p.Others[0] != "nvidia_0" {
+		t.Fatalf("%+v", p)
+	}
+}
+
+func TestAPanelRequestIsAPercentageOrAStepAndNeverGoesDark(t *testing.T) {
+	for _, c := range []struct {
+		cur  float64
+		req  string
+		want float64
+	}{{50, "40", 40}, {50, "40%", 40}, {50, "+5", 55}, {50, "-10", 40}, {3, "-10", 1}, {98, "+5", 100}, {50, "0", 1}} {
+		got, err := PanelTarget(c.cur, c.req)
+		if err != nil || got != c.want {
+			t.Errorf("%v %q: %v %v, want %v", c.cur, c.req, got, err, c.want)
+		}
+	}
+	for _, bad := range []string{"", "bright", "NaN"} {
+		if _, err := PanelTarget(50, bad); err == nil {
+			t.Errorf("%q was accepted", bad)
+		}
+	}
+}
+
+func TestSettingThePanelWritesTheRawValue(t *testing.T) {
+	f := newFake(t)
+	f.backlight("amdgpu_bl1", "card1-eDP-1", "399000", "399000")
+	p, err := f.machine().SetPanel(context.Background(), "25")
+	if err != nil {
+		t.Fatal(err)
+	}
+	raw, _ := os.ReadFile(filepath.Join(f.root, "/sys/devices/card1-eDP-1/amdgpu_bl1/brightness"))
+	if strings.TrimSpace(string(raw)) != "99750" || p.Percent != 25 {
+		t.Fatalf("wrote %q, read back %+v", raw, p)
+	}
+}
+
+func TestTheKeyboardIsSetThroughAsusdByLevel(t *testing.T) {
+	f := newFake(t)
+	f.file("/sys/class/leds/asus::kbd_backlight/brightness", "1")
+	f.file("/sys/class/leds/asus::kbd_backlight/max_brightness", "3")
+	k, err := f.machine().KeyboardBrightness()
+	if err != nil || k.Level != "low" {
+		t.Fatalf("%+v %v", k, err)
+	}
+	if _, err := f.machine().SetKeyboard(context.Background(), "+"); err != nil {
+		t.Fatal(err)
+	}
+	if !f.called("asusctl leds set med") {
+		t.Fatalf("calls: %v", f.calls)
+	}
+	for req, want := range map[string]string{"high": "high", "0": "off", "medium": "med", "-": "off"} {
+		if got, err := KeyboardTarget(1, req); err != nil || got != want {
+			t.Errorf("%q: %q %v", req, got, err)
+		}
+	}
+	if _, err := KeyboardTarget(1, "7"); err == nil {
+		t.Error("level 7 was accepted")
+	}
+}
@@ -0,0 +1,103 @@
+package main
+
+import (
+	"context"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+)
+
+// fake is a machine for a test: a tree standing in for /, and a runner answering from a table and
+// recording every command it was asked to run.
+type fake struct {
+	t       *testing.T
+	root    string
+	mu      sync.Mutex
+	answers map[string]string
+	fails   map[string]error
+	calls   []string
+}
+
+func newFake(t *testing.T) *fake {
+	t.Helper()
+	return &fake{t: t, root: t.TempDir(), answers: map[string]string{}, fails: map[string]error{}}
+}
+
+func (f *fake) machine() *Machine { return &Machine{Root: f.root, Run: f.run} }
+
+func (f *fake) run(_ context.Context, name string, args ...string) (string, error) {
+	line := strings.TrimSpace(name + " " + strings.Join(args, " "))
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.calls = append(f.calls, line)
+	if err, ok := f.fails[line]; ok {
+		return "", err
+	}
+	if out, ok := f.answers[line]; ok {
+		return out, nil
+	}
+	if err, ok := f.fails[name]; ok {
+		return "", err
+	}
+	return "", nil
+}
+
+func (f *fake) called(line string) bool {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	for _, c := range f.calls {
+		if c == line {
+			return true
+		}
+	}
+	return false
+}
+
+func (f *fake) callsLike(prefix string) []string {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	var out []string
+	for _, c := range f.calls {
+		if strings.HasPrefix(c, prefix) {
+			out = append(out, c)
+		}
+	}
+	return out
+}
+
+// file writes a file under the fake root.
+func (f *fake) file(path, content string) {
+	f.t.Helper()
+	full := filepath.Join(f.root, path)
+	if err := os.MkdirAll(filepath.Dir(full), 0o755); err != nil {
+		f.t.Fatal(err)
+	}
+	if err := os.WriteFile(full, []byte(content), 0o644); err != nil {
+		f.t.Fatal(err)
+	}
+}
+
+// supply writes one power supply's attributes.
+func (f *fake) supply(name string, attrs map[string]string) {
+	for k, v := range attrs {
+		f.file("/sys/class/power_supply/"+name+"/"+k, v+"\n")
+	}
+}
+
+// onMains and onBattery are this model's two states as measured on 2026-10-04.
+func (f *fake) onMains() {
+	f.supply("ACAD", map[string]string{"type": "Mains", "online": "1"})
+	f.supply("BAT1", map[string]string{"type": "Battery", "status": "Not charging", "capacity": "80"})
+}
+
+func (f *fake) onBattery() {
+	f.supply("ACAD", map[string]string{"type": "Mains", "online": "0"})
+	f.supply("BAT1", map[string]string{"type": "Battery", "status": "Discharging", "capacity": "79"})
+}
+
+var notFound = &exec.Error{Name: "x", Err: exec.ErrNotFound}
+
+const profileGetBalanced = "Active profile: Balanced\n\nAC profile Balanced\nBattery profile Quiet\n"
@@ -0,0 +1,124 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// CommandTimeout bounds every command a tool or the switcher runs: a vendor daemon that hangs on its
+// bus must cost a tool call twenty seconds, never the runtime's thirty.
+const CommandTimeout = 20 * time.Second
+
+// Runner runs one command and answers its standard output. It is injected so that every tool is
+// tested against recorded answers rather than this machine's daemons.
+type Runner func(ctx context.Context, name string, args ...string) (string, error)
+
+// ExecRunner runs a command on the machine, bounded by CommandTimeout. A failure carries what the
+// command said on stderr, because "exit status 1" names nothing.
+func ExecRunner(ctx context.Context, name string, args ...string) (string, error) {
+	ctx, cancel := context.WithTimeout(ctx, CommandTimeout)
+	defer cancel()
+	cmd := exec.CommandContext(ctx, name, args...)
+	var stdout, stderr bytes.Buffer
+	cmd.Stdout, cmd.Stderr = &stdout, &stderr
+	err := cmd.Run()
+	if ctx.Err() == context.DeadlineExceeded {
+		return stdout.String(), fmt.Errorf("%s did not answer within %s", name, CommandTimeout)
+	}
+	if err != nil {
+		said := strings.TrimSpace(stderr.String())
+		if said == "" {
+			said = strings.TrimSpace(stdout.String())
+		}
+		if said != "" {
+			return stdout.String(), fmt.Errorf("%s %s: %w: %s", name, strings.Join(args, " "), err, said)
+		}
+		return stdout.String(), fmt.Errorf("%s %s: %w", name, strings.Join(args, " "), err)
+	}
+	return stdout.String(), nil
+}
+
+// Machine is what the module reads and acts on: a filesystem root (the real one, or a test's tree of
+// /sys and /proc and /etc) and a way to run commands.
+type Machine struct {
+	Root string
+	Run  Runner
+}
+
+// Here is the machine this process runs on.
+func Here() *Machine { return &Machine{Root: "/", Run: ExecRunner} }
+
+func (m *Machine) path(p string) string { return filepath.Join(m.Root, p) }
+
+// read is a file's content, trimmed; "" when it cannot be read.
+func (m *Machine) read(p string) string {
+	b, err := os.ReadFile(m.path(p))
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(string(b))
+}
+
+// readInt is a file holding one integer; ok false when it is absent or not a number.
+func (m *Machine) readInt(p string) (int64, bool) {
+	s := m.read(p)
+	if s == "" {
+		return 0, false
+	}
+	n, err := strconv.ParseInt(s, 10, 64)
+	return n, err == nil
+}
+
+func (m *Machine) glob(pattern string) []string {
+	found, _ := filepath.Glob(m.path(pattern))
+	out := make([]string, 0, len(found))
+	for _, f := range found {
+		rel, err := filepath.Rel(m.Root, f)
+		if err != nil {
+			continue
+		}
+		out = append(out, "/"+filepath.ToSlash(rel))
+	}
+	return out
+}
+
+// write puts a value into a file of the kernel's (a backlight). Where the account may not write it
+// — the udev rule that gives the video group the panel has not run yet — it escalates with `sudo -n`,
+// which never prompts: the operator's account may escalate without one, and when it may not, the
+// tool says so in sudo's words.
+func (m *Machine) write(ctx context.Context, p, value string) error {
+	err := os.WriteFile(m.path(p), []byte(value), 0)
+	if err == nil {
+		return nil
+	}
+	if !errors.Is(err, os.ErrPermission) {
+		return err
+	}
+	if _, serr := m.Run(ctx, "sudo", "-n", "sh", "-c", `printf '%s' "$1" > "$2"`, "sh", value, m.path(p)); serr != nil {
+		return fmt.Errorf("%s is not writable by this account and sudo -n refused: %v", p, serr)
+	}
+	return nil
+}
+
+// notInstalled says a command failed because it is not on this machine at all.
+func notInstalled(err error) bool { return errors.Is(err, exec.ErrNotFound) }
+
+// round to one decimal, for watts and percentages a person reads.
+func round1(f float64) float64 {
+	return float64(int64(f*10+sign(f)*0.5)) / 10
+}
+
+func sign(f float64) float64 {
+	if f < 0 {
+		return -1
+	}
+	return 1
+}
@@ -0,0 +1,25 @@
+// The asus-zephyrus-g14 module's Go bundle (novox/hq ADR 0188, ADR 0193, ADR 0198): one process the
+// node's runtime launches, serving the module's tools over MCP on stdio and running its long-running
+// code — the platform-profile switcher — beside them.
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+func main() {
+	m := Here()
+	sw := NewSwitcher(m, func(eventType string, body any) error { return stdio.Emit(eventType, body) })
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	go sw.Run(ctx)
+	// An empty name serves as the module the runtime names (MESH_SERVED_MODULE).
+	if err := stdio.Serve("", Tools(m, sw)); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
@@ -0,0 +1,110 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sort"
+	"strings"
+	"testing"
+)
+
+type manifest struct {
+	Module    string           `json:"module"`
+	Tools     []string         `json:"tools"`
+	Emits     []string         `json:"emits"`
+	Resources []map[string]any `json:"resources"`
+}
+
+func readManifest(t *testing.T) manifest {
+	t.Helper()
+	raw, err := os.ReadFile("../../module.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var m manifest
+	if err := json.Unmarshal(raw, &m); err != nil {
+		t.Fatal(err)
+	}
+	return m
+}
+
+func TestTheManifestNamesExactlyTheToolsTheBundleServes(t *testing.T) {
+	m := readManifest(t)
+	var served []string
+	for _, tool := range Tools(&Machine{Root: t.TempDir(), Run: newFake(t).run}, nil) {
+		served = append(served, tool.Name)
+	}
+	sort.Strings(served)
+	listed := append([]string(nil), m.Tools...)
+	sort.Strings(listed)
+	if strings.Join(served, ",") != strings.Join(listed, ",") {
+		t.Fatalf("served %v, listed %v", served, listed)
+	}
+	if len(m.Emits) != 1 || m.Emits[0] != "profile.switched" {
+		t.Fatalf("emits %v", m.Emits)
+	}
+}
+
+// The module names the model, never a node, a person or a user id (novox/hq ADR 0112), and every
+// trigger it names a service restart or reload on is one of its own resources.
+func TestTheManifestNamesNoMachineAndItsTriggersExist(t *testing.T) {
+	m := readManifest(t)
+	ids := map[string]bool{}
+	for _, r := range m.Resources {
+		ids[r["id"].(string)] = true
+	}
+	raw, _ := os.ReadFile("../../module.json")
+	for _, banned := range []string{"jochen", "/home/", "/run/user/1000", "\"g14\"", "shanks"} {
+		if strings.Contains(string(raw), banned) {
+			t.Errorf("the manifest says %q", banned)
+		}
+	}
+	for _, r := range m.Resources {
+		for _, key := range []string{"restart-on", "reload-on"} {
+			list, _ := r[key].([]any)
+			for _, id := range list {
+				if !ids[id.(string)] {
+					t.Errorf("%s %s names %v, which is not a resource", r["id"], key, id)
+				}
+			}
+		}
+	}
+}
+
+// Every trigger runs a script the module ships, and every script parses.
+func TestTheVendorKeysRunTheModulesOwnScriptsAndTheyParse(t *testing.T) {
+	m := readManifest(t)
+	var triggers string
+	for _, r := range m.Resources {
+		if r["id"] == "vendor-keys" {
+			triggers = r["content"].(string)
+		}
+	}
+	if triggers == "" {
+		t.Fatal("no vendor-keys resource")
+	}
+	for _, line := range strings.Split(triggers, "\n") {
+		f := strings.Split(line, "\t")
+		if strings.HasPrefix(line, "#") || len(f) < 3 {
+			continue
+		}
+		script := strings.Fields(f[2])[0]
+		local := filepath.Join("../../files/bin", filepath.Base(script))
+		if !strings.HasPrefix(script, "/usr/local/lib/asus-zephyrus-g14/bin/") {
+			t.Errorf("%s runs %s, which the module does not ship", f[0], script)
+		} else if st, err := os.Stat(local); err != nil || st.Mode()&0o111 == 0 {
+			t.Errorf("%s: %s is missing or not executable", f[0], local)
+		}
+	}
+	scripts, _ := filepath.Glob("../../files/bin/*")
+	if len(scripts) == 0 {
+		t.Fatal("no scripts")
+	}
+	for _, s := range scripts {
+		if out, err := exec.Command("bash", "-n", s).CombinedOutput(); err != nil {
+			t.Errorf("%s: %v %s", s, err, out)
+		}
+	}
+}
@@ -0,0 +1,137 @@
+package main
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// The policy, as constants until the mesh has settings a module can read (novox/hq issue 168). The
+// values are the predecessor's, made explicit, and two of its behaviours are changed on purpose:
+//
+//   - **Sustained, not momentary.** The predecessor boosted on one five-second sample above 50 %: a
+//     compile's first second, a browser's tab restore. Here the load must stay above the line for
+//     SustainSamples samples in a row, and below the lower line as long, before the profile moves.
+//   - **Waiting on a disk is not load.** iowait is counted as idle: a machine stalled on its SSD does
+//     not get faster with a higher power limit, only hotter.
+const (
+	ProfileOnBattery = "Quiet"
+	ProfileOnAC      = "Balanced"
+	ProfileUnderLoad = "Performance"
+
+	CPUHighPercent = 50.0 // on mains, sustained at or above this boosts to ProfileUnderLoad
+	CPULowPercent  = 20.0 // and sustained at or below this goes back to ProfileOnAC
+
+	SampleEvery    = 10 * time.Second // CPU is sampled only on mains; on battery nothing is sampled
+	SustainSamples = 3                // 30 s above CPUHighPercent to boost
+	RelaxSamples   = 3                // 30 s below CPULowPercent to relax
+
+	// SafetyRecheck is how often the power source is read when no event has said it changed: the
+	// kernel's event is the trigger, and this only covers one lost across a suspend.
+	SafetyRecheck = 5 * time.Minute
+
+	// DefaultHold is how long a profile chosen through the profile tool is kept before the switcher
+	// may move it again. A change of power source ends a hold at once.
+	DefaultHold = 60 * time.Minute
+
+	// ChargeLimitPercent is the battery charge limit the module asserts through asusd at start.
+	ChargeLimitPercent = 80
+)
+
+// Policy is the switcher's memory of recent load: how many samples in a row were above the upper line
+// or below the lower one, and whether it is boosted.
+type Policy struct {
+	Boosted      bool      `json:"boosted"`
+	Above        int       `json:"samples_above"`
+	Below        int       `json:"samples_below"`
+	Recent       []float64 `json:"recent_cpu_percent"`
+	BoostedSince time.Time `json:"boosted_since,omitempty"`
+}
+
+// Observe takes one CPU sample (busy percent since the previous one) taken on mains.
+func (p *Policy) Observe(cpu float64, at time.Time) {
+	p.Recent = append(p.Recent, round1(cpu))
+	if len(p.Recent) > 6 {
+		p.Recent = p.Recent[len(p.Recent)-6:]
+	}
+	switch {
+	case cpu >= CPUHighPercent:
+		p.Above++
+		p.Below = 0
+		if !p.Boosted && p.Above >= SustainSamples {
+			p.Boosted = true
+			p.BoostedSince = at
+		}
+	case cpu <= CPULowPercent:
+		p.Below++
+		p.Above = 0
+		if p.Boosted && p.Below >= RelaxSamples {
+			p.Boosted = false
+			p.BoostedSince = time.Time{}
+		}
+	default:
+		// Between the lines: no direction is sustained, and the profile stays where it is.
+		p.Above, p.Below = 0, 0
+	}
+}
+
+// Reset forgets the load, for a change of power source.
+func (p *Policy) Reset() { *p = Policy{} }
+
+// Decision is what the switcher would choose, and why.
+type Decision struct {
+	Profile string `json:"profile"`
+	Reason  string `json:"reason"`
+}
+
+// Decide is the policy: battery → ProfileOnBattery; mains → ProfileOnAC, or ProfileUnderLoad while
+// boosted.
+func (p *Policy) Decide(src Source) Decision {
+	if !src.OnAC {
+		return Decision{ProfileOnBattery, "on battery (" + src.Reason + ")"}
+	}
+	if p.Boosted {
+		return Decision{ProfileUnderLoad, fmt.Sprintf("on mains (%s) and CPU load sustained at or above %s%% for %d samples of %s",
+			src.Reason, strconv.FormatFloat(CPUHighPercent, 'f', -1, 64), SustainSamples, SampleEvery)}
+	}
+	return Decision{ProfileOnAC, fmt.Sprintf("on mains (%s), and CPU load not sustained at or above %s%%",
+		src.Reason, strconv.FormatFloat(CPUHighPercent, 'f', -1, 64))}
+}
+
+// CPUTimes is the first line of /proc/stat: total and idle jiffies (iowait counted as idle).
+type CPUTimes struct{ Total, Idle uint64 }
+
+// ParseProcStat reads the aggregate cpu line of /proc/stat.
+func ParseProcStat(text string) (CPUTimes, error) {
+	line := strings.SplitN(text, "\n", 2)[0]
+	f := strings.Fields(line)
+	if len(f) < 6 || f[0] != "cpu" {
+		return CPUTimes{}, fmt.Errorf("/proc/stat does not start with the cpu line")
+	}
+	var t CPUTimes
+	for i, s := range f[1:] {
+		if i >= 8 { // user nice system idle iowait irq softirq steal; guest is already in user
+			break
+		}
+		n, err := strconv.ParseUint(s, 10, 64)
+		if err != nil {
+			return CPUTimes{}, fmt.Errorf("/proc/stat: %v", err)
+		}
+		t.Total += n
+		if i == 3 || i == 4 {
+			t.Idle += n
+		}
+	}
+	return t, nil
+}
+
+// Busy is the percentage of time not idle between two readings.
+func Busy(before, after CPUTimes) (float64, bool) {
+	if after.Total <= before.Total {
+		return 0, false
+	}
+	total := float64(after.Total - before.Total)
+	idle := float64(after.Idle - before.Idle)
+	return (total - idle) / total * 100, true
+}
@@ -0,0 +1,180 @@
+package main
+
+import (
+	"path"
+	"sort"
+	"strings"
+)
+
+// Supply is one entry of /sys/class/power_supply as the kernel reports it.
+type Supply struct {
+	Name   string `json:"name"`
+	Type   string `json:"type"`
+	Scope  string `json:"scope,omitempty"`
+	Status string `json:"status,omitempty"`
+	Online *bool  `json:"online,omitempty"`
+}
+
+// Supplies is every power supply the kernel knows, sorted by name.
+func (m *Machine) Supplies() []Supply {
+	var out []Supply
+	for _, dir := range m.glob("/sys/class/power_supply/*") {
+		s := Supply{
+			Name:   path.Base(dir),
+			Type:   m.read(dir + "/type"),
+			Scope:  m.read(dir + "/scope"),
+			Status: m.read(dir + "/status"),
+		}
+		if v, ok := m.readInt(dir + "/online"); ok {
+			on := v == 1
+			s.Online = &on
+		}
+		out = append(out, s)
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
+	return out
+}
+
+// system is a supply that powers this machine. A mouse's or a headset's battery reports scope
+// Device, and it says nothing about whether the laptop is on mains.
+func (s Supply) system() bool { return !strings.EqualFold(s.Scope, "Device") }
+
+// Source is where the machine draws its power from, and why that was concluded.
+type Source struct {
+	OnAC   bool   `json:"on_ac"`
+	Source string `json:"source"`
+	Reason string `json:"reason"`
+}
+
+// PowerSource decides mains or battery.
+//
+// **A battery that says it is discharging wins over any adapter that says it is online.** The
+// predecessor's script took any `online` file reading 1 as mains, and a USB-C port reports `online`
+// for things that do not power the machine. The battery's own status is the one fact that cannot be
+// misread: it discharges exactly when nothing outside is carrying the load. Only when no battery says
+// so are the adapters asked, and a machine with no system battery at all is on mains.
+func PowerSource(supplies []Supply) Source {
+	batteries := 0
+	for _, s := range supplies {
+		if s.Type == "Battery" && s.system() {
+			batteries++
+			if strings.EqualFold(s.Status, "Discharging") {
+				return Source{OnAC: false, Source: "battery", Reason: s.Name + " is discharging"}
+			}
+		}
+	}
+	for _, s := range supplies {
+		if (s.Type == "Mains" || strings.HasPrefix(s.Type, "USB")) && s.system() && s.Online != nil && *s.Online {
+			return Source{OnAC: true, Source: "ac", Reason: s.Name + " (" + s.Type + ") is online"}
+		}
+	}
+	if batteries == 0 {
+		return Source{OnAC: true, Source: "ac", Reason: "this machine has no system battery"}
+	}
+	return Source{OnAC: false, Source: "battery", Reason: "no mains or USB supply is online"}
+}
+
+// Battery is what the battery tool answers.
+type Battery struct {
+	Name           string   `json:"name"`
+	Status         string   `json:"status"`
+	ChargePercent  *int64   `json:"charge_percent,omitempty"`
+	EnergyWh       *float64 `json:"energy_wh,omitempty"`
+	FullWh         *float64 `json:"full_wh,omitempty"`
+	DesignWh       *float64 `json:"design_wh,omitempty"`
+	HealthPercent  *float64 `json:"health_percent,omitempty"`
+	Cycles         *int64   `json:"cycles"`
+	CyclesNote     string   `json:"cycles_note,omitempty"`
+	LimitPercent   *int64   `json:"charge_limit_percent,omitempty"`
+	PowerW         *float64 `json:"power_w,omitempty"`
+	HoursRemaining *float64 `json:"hours_remaining,omitempty"`
+	Technology     string   `json:"technology,omitempty"`
+	Model          string   `json:"model,omitempty"`
+	Manufacturer   string   `json:"manufacturer,omitempty"`
+}
+
+// Batteries reads every system battery.
+func (m *Machine) Batteries() []Battery {
+	var out []Battery
+	for _, s := range m.Supplies() {
+		if s.Type != "Battery" || !s.system() {
+			continue
+		}
+		out = append(out, m.battery(s))
+	}
+	return out
+}
+
+func (m *Machine) battery(s Supply) Battery {
+	dir := "/sys/class/power_supply/" + s.Name
+	b := Battery{
+		Name: s.Name, Status: s.Status,
+		Technology:   m.read(dir + "/technology"),
+		Model:        m.read(dir + "/model_name"),
+		Manufacturer: strings.TrimSpace(m.read(dir + "/manufacturer")),
+	}
+	if v, ok := m.readInt(dir + "/capacity"); ok {
+		b.ChargePercent = &v
+	}
+	// Energy in Wh: energy_* (µWh) where the firmware reports it, else charge_* (µAh) times the
+	// design minimum voltage, which is how upower converts it too.
+	wh := func(energy, charge string) *float64 {
+		if v, ok := m.readInt(dir + "/" + energy); ok {
+			f := round1(float64(v) / 1e6)
+			return &f
+		}
+		c, okc := m.readInt(dir + "/" + charge)
+		volts, okv := m.readInt(dir + "/voltage_min_design")
+		if okc && okv {
+			f := round1(float64(c) * float64(volts) / 1e12)
+			return &f
+		}
+		return nil
+	}
+	b.EnergyWh = wh("energy_now", "charge_now")
+	b.FullWh = wh("energy_full", "charge_full")
+	b.DesignWh = wh("energy_full_design", "charge_full_design")
+	if b.FullWh != nil && b.DesignWh != nil && *b.DesignWh > 0 {
+		h := round1(*b.FullWh / *b.DesignWh * 100)
+		b.HealthPercent = &h
+	}
+	if v, ok := m.readInt(dir + "/cycle_count"); ok && v > 0 {
+		b.Cycles = &v
+	} else {
+		b.CyclesNote = "the firmware does not report a cycle count (it reads 0)"
+	}
+	if v, ok := m.readInt(dir + "/charge_control_end_threshold"); ok {
+		b.LimitPercent = &v
+	}
+	if w := m.batteryWatts(dir); w != nil {
+		b.PowerW = w
+		if strings.EqualFold(s.Status, "Discharging") && b.EnergyWh != nil && *w > 0.5 {
+			h := round1(*b.EnergyWh / *w)
+			b.HoursRemaining = &h
+		}
+	}
+	return b
+}
+
+// batteryWatts is how much the battery is giving or taking, in watts, unsigned: power_now where the
+// firmware reports it, else current times voltage.
+func (m *Machine) batteryWatts(dir string) *float64 {
+	if v, ok := m.readInt(dir + "/power_now"); ok {
+		f := round1(abs(float64(v)) / 1e6)
+		return &f
+	}
+	i, oki := m.readInt(dir + "/current_now")
+	u, oku := m.readInt(dir + "/voltage_now")
+	if oki && oku {
+		f := round1(abs(float64(i)) * float64(u) / 1e12)
+		return &f
+	}
+	return nil
+}
+
+func abs(f float64) float64 {
+	if f < 0 {
+		return -f
+	}
+	return f
+}
@@ -0,0 +1,73 @@
+package main
+
+import "testing"
+
+func on(b bool) *bool { return &b }
+
+func TestADischargingBatteryWinsOverAnAdapterThatSaysOnline(t *testing.T) {
+	got := PowerSource([]Supply{
+		{Name: "BAT1", Type: "Battery", Status: "Discharging"},
+		{Name: "ucsi-source-psy-USBC000:001", Type: "USB", Scope: "System", Online: on(true)},
+	})
+	if got.OnAC {
+		t.Fatalf("a USB-C port reporting online while the battery discharges was read as mains: %+v", got)
+	}
+}
+
+func TestMainsOnlineIsAC(t *testing.T) {
+	got := PowerSource([]Supply{
+		{Name: "ACAD", Type: "Mains", Online: on(true)},
+		{Name: "BAT1", Type: "Battery", Status: "Not charging"},
+	})
+	if !got.OnAC || got.Reason != "ACAD (Mains) is online" {
+		t.Fatalf("%+v", got)
+	}
+}
+
+func TestAPeripheralsBatteryDecidesNothing(t *testing.T) {
+	got := PowerSource([]Supply{
+		{Name: "hidpp_battery_0", Type: "Battery", Scope: "Device", Status: "Discharging"},
+		{Name: "ACAD", Type: "Mains", Online: on(true)},
+		{Name: "BAT1", Type: "Battery", Status: "Charging"},
+	})
+	if !got.OnAC {
+		t.Fatalf("a mouse's discharging battery put the laptop on battery: %+v", got)
+	}
+}
+
+func TestNoSupplyOnlineWithABatteryIsBatteryAndNoBatteryIsMains(t *testing.T) {
+	if got := PowerSource([]Supply{{Name: "ACAD", Type: "Mains", Online: on(false)}, {Name: "BAT1", Type: "Battery", Status: "Unknown"}}); got.OnAC {
+		t.Fatalf("%+v", got)
+	}
+	if got := PowerSource(nil); !got.OnAC {
+		t.Fatalf("a machine with no battery is on mains: %+v", got)
+	}
+}
+
+func TestTheBatteryIsReadInWattHoursFromChargeAndHealthAgainstDesign(t *testing.T) {
+	f := newFake(t)
+	// The laptop's own battery, as measured: charge_* in µAh, no energy_* and no power_now.
+	f.supply("BAT1", map[string]string{
+		"type": "Battery", "status": "Discharging", "capacity": "80",
+		"charge_now": "3073000", "charge_full": "3865000", "charge_full_design": "4580000",
+		"voltage_min_design": "15939000", "current_now": "1000000", "voltage_now": "16000000",
+		"cycle_count": "0", "charge_control_end_threshold": "80", "manufacturer": "ASUS ",
+	})
+	bs := f.machine().Batteries()
+	if len(bs) != 1 {
+		t.Fatalf("%+v", bs)
+	}
+	b := bs[0]
+	if *b.EnergyWh != 49 || *b.FullWh != 61.6 || *b.DesignWh != 73 || *b.HealthPercent != 84.4 {
+		t.Fatalf("energy %v full %v design %v health %v", *b.EnergyWh, *b.FullWh, *b.DesignWh, *b.HealthPercent)
+	}
+	if b.Cycles != nil || b.CyclesNote == "" {
+		t.Fatal("a cycle count of 0 is the firmware not reporting one, and said so")
+	}
+	if *b.LimitPercent != 80 || *b.PowerW != 16 || b.HoursRemaining == nil || *b.HoursRemaining != 3.1 {
+		t.Fatalf("limit %v power %v hours %v", *b.LimitPercent, *b.PowerW, b.HoursRemaining)
+	}
+	if b.Manufacturer != "ASUS" {
+		t.Fatalf("manufacturer %q", b.Manufacturer)
+	}
+}
@@ -0,0 +1,303 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+)
+
+// The module's long-running code (novox/hq ADR 0198): the profile switcher, launched with the tools
+// by the node's runtime and running beside them in the same process.
+//
+// It replaces the predecessor's `auto-profile`, a user unit that woke every five seconds for ever —
+// read the adapters, read /proc/stat, maybe call asusctl — on battery too, where its only possible
+// answer was the one it had already given. Here the kernel's power-supply event is the trigger; the
+// CPU is sampled only on mains, where the answer depends on it; and on battery the process sleeps
+// until the adapter comes back.
+//
+// **It acts on a change of its decision, never to restore one.** A profile chosen by hand — the
+// vendor's profile key, asusctl in a terminal, the profile tool — stays until the power source
+// changes or the load crosses a line. The predecessor re-asserted its choice every five seconds and so
+// made the profile key useless on battery.
+
+// Emitter publishes an event as the module; nil when the process is not under the runtime.
+type Emitter func(eventType string, body any) error
+
+// Switcher is the switcher's state, shared with the tools that report it.
+type Switcher struct {
+	m    *Machine
+	now  func() time.Time
+	emit Emitter
+
+	mu        sync.Mutex
+	policy    Policy
+	source    *Source
+	decision  *Decision
+	applied   string
+	appliedAt time.Time
+	lastError string
+	holdUntil time.Time
+	holdOf    string
+	watching  string
+	cpuPrev   *CPUTimes
+	disabled  string
+	asserted  []string
+}
+
+func NewSwitcher(m *Machine, emit Emitter) *Switcher {
+	return &Switcher{m: m, now: time.Now, emit: emit}
+}
+
+// Model is the machine's product family as its firmware reports it.
+func (m *Machine) Model() string { return m.read("/sys/class/dmi/id/product_family") }
+
+// ModelFamily is the family this module is written for.
+const ModelFamily = "ROG Zephyrus G14"
+
+// ThisModel says whether the machine is the model this module is written for.
+func (m *Machine) ThisModel() bool { return strings.EqualFold(m.Model(), ModelFamily) }
+
+// sampleCPU reads /proc/stat and answers the busy percentage since the previous reading.
+func (s *Switcher) sampleCPU() (float64, bool) {
+	t, err := ParseProcStat(s.m.read("/proc/stat"))
+	if err != nil {
+		return 0, false
+	}
+	prev := s.cpuPrev
+	s.cpuPrev = &t
+	if prev == nil {
+		return 0, false
+	}
+	return Busy(*prev, t)
+}
+
+// Evaluate reads the power source, takes a CPU sample when asked and on mains, decides, and applies
+// the decision when it changed. It is the whole of one wake-up and what the tests drive.
+func (s *Switcher) Evaluate(ctx context.Context, sample bool) {
+	if body := s.evaluate(ctx, sample); body != nil && s.emit != nil {
+		// Outside the lock: publishing waits for the bus, and the tools that report the switcher
+		// must not wait with it.
+		if err := s.emit("profile.switched", body); err != nil {
+			fmt.Fprintf(os.Stderr, "profile.switched not published: %v\n", err)
+		}
+	}
+}
+
+// evaluate is Evaluate under the lock; it answers the event to publish when it switched.
+func (s *Switcher) evaluate(ctx context.Context, sample bool) map[string]any {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.disabled != "" {
+		return nil
+	}
+	src := PowerSource(s.m.Supplies())
+	now := s.now()
+	first := s.source == nil
+	if first || s.source.OnAC != src.OnAC {
+		// A new power source: what was learnt about load on the other one says nothing here, and a
+		// hold was for the source it was asked on.
+		s.policy.Reset()
+		s.cpuPrev = nil
+		s.holdUntil = time.Time{}
+		s.holdOf = ""
+		s.sampleCPU() // the first reading on this source, so the next sample is a difference
+	} else if sample && src.OnAC {
+		if busy, ok := s.sampleCPU(); ok {
+			s.policy.Observe(busy, now)
+		}
+	}
+	s.source = &src
+	d := s.policy.Decide(src)
+	s.decision = &d
+	// **Starting is not a reason to switch.** The runtime starts this process on every push that
+	// changes a bundle; at boot and at every change of power source asusd has already applied its own
+	// profile for the source, which AssertVendorSettings made the policy's. So the first decision is
+	// taken as applied, and a profile someone chose by hand survives a push.
+	if first {
+		s.applied = d.Profile
+		return nil
+	}
+	// Compared with what the switcher itself last applied, never with the profile in force: a profile
+	// someone chose by hand is not a reason to act, a new decision is.
+	if d.Profile == s.applied || now.Before(s.holdUntil) {
+		return nil
+	}
+	from := s.applied
+	if err := s.m.SetProfile(ctx, d.Profile); err != nil {
+		s.lastError = err.Error() // and tried again at the next wake-up, since applied did not move
+		return nil
+	}
+	s.lastError = ""
+	s.applied, s.appliedAt = d.Profile, now
+	body := map[string]any{"profile": d.Profile, "reason": d.Reason, "source": src.Source}
+	if from != "" {
+		body["from"] = from
+	}
+	return body
+}
+
+// Hold keeps a profile chosen through the tool for a while: the switcher does not move it until the
+// hold ends or the power source changes.
+func (s *Switcher) Hold(profile string, d time.Duration) time.Time {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if d <= 0 {
+		s.holdUntil, s.holdOf = time.Time{}, ""
+		return time.Time{}
+	}
+	s.holdUntil, s.holdOf = s.now().Add(d), profile
+	return s.holdUntil
+}
+
+// Run is the switcher's life: assert asusd's settings once, then wake on each power-supply event, on
+// each CPU sample while on mains, and at SafetyRecheck otherwise.
+func (s *Switcher) Run(ctx context.Context) {
+	defer func() {
+		if r := recover(); r != nil {
+			s.mu.Lock()
+			s.disabled = fmt.Sprintf("the switcher stopped on a fault: %v", r)
+			s.mu.Unlock()
+			fmt.Fprintln(os.Stderr, s.disabled)
+		}
+	}()
+	if !s.m.ThisModel() {
+		s.mu.Lock()
+		s.disabled = fmt.Sprintf("this machine reports %q, not %q: the switcher does not act on another model",
+			s.m.Model(), ModelFamily)
+		s.mu.Unlock()
+		fmt.Fprintln(os.Stderr, s.disabled)
+		return
+	}
+	s.AssertVendorSettings(ctx)
+
+	events, err := listenPowerSupply(ctx)
+	s.mu.Lock()
+	if err != nil {
+		s.watching = "polling every " + SampleEvery.String() + ": " + err.Error()
+	} else {
+		s.watching = "the kernel's power-supply events"
+	}
+	s.mu.Unlock()
+
+	s.Evaluate(ctx, false)
+	timer := time.NewTimer(s.interval(err != nil))
+	defer timer.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case _, open := <-events:
+			if !open {
+				events = nil
+				s.mu.Lock()
+				s.watching = "polling every " + SampleEvery.String() + ": the uevent socket closed"
+				s.mu.Unlock()
+				err = fmt.Errorf("closed")
+				continue
+			}
+			// Settle: an adapter change arrives as several events within a moment.
+			time.Sleep(time.Second)
+			s.Evaluate(ctx, false)
+		case <-timer.C:
+			s.Evaluate(ctx, true)
+			timer.Reset(s.interval(err != nil))
+		}
+	}
+}
+
+// interval is how long to sleep: a CPU sample's period on mains (or with no events to wake on), the
+// safety recheck on battery.
+func (s *Switcher) interval(polling bool) time.Duration {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if polling || s.source == nil || s.source.OnAC {
+		return SampleEvery
+	}
+	return SafetyRecheck
+}
+
+// AssertVendorSettings puts asusd's own settings where the module wants them, once at start: the
+// battery charge limit, and the profiles asusd itself switches to on mains and on battery, so that the
+// vendor daemon's own switching and this module's never disagree. Each is read first and set only if
+// it differs. A value changed later with a tool stands until the next start.
+func (s *Switcher) AssertVendorSettings(ctx context.Context) []string {
+	var said []string
+	if limit, err := s.m.ChargeLimit(ctx); err != nil {
+		said = append(said, "charge limit not read: "+err.Error())
+	} else if limit != ChargeLimitPercent {
+		if _, err := s.m.Run(ctx, "asusctl", "battery", "limit", strconv.Itoa(ChargeLimitPercent)); err != nil {
+			said = append(said, "charge limit not set: "+vendor("asusctl", err).Error())
+		} else {
+			said = append(said, fmt.Sprintf("charge limit %d%% → %d%%", limit, ChargeLimitPercent))
+		}
+	} else {
+		said = append(said, fmt.Sprintf("charge limit already %d%%", ChargeLimitPercent))
+	}
+	p, err := s.m.Profile(ctx)
+	if err != nil {
+		said = append(said, "asusd's profiles not read: "+err.Error())
+	} else {
+		for _, want := range []struct{ flag, have, want, what string }{
+			{"-a", p.OnAC, ProfileOnAC, "on mains"},
+			{"-b", p.Battery, ProfileOnBattery, "on battery"},
+		} {
+			if want.have == "" || strings.EqualFold(want.have, want.want) {
+				continue
+			}
+			if _, err := s.m.Run(ctx, "asusctl", "profile", "set", want.flag, want.want); err != nil {
+				said = append(said, "asusd's profile "+want.what+" not set: "+err.Error())
+			} else {
+				said = append(said, fmt.Sprintf("asusd's profile %s %s → %s", want.what, want.have, want.want))
+			}
+		}
+	}
+	s.mu.Lock()
+	s.asserted = said
+	s.mu.Unlock()
+	for _, line := range said {
+		fmt.Fprintln(os.Stderr, line)
+	}
+	return said
+}
+
+// SwitcherReport is the switcher's state as the profile-policy tool shows it.
+type SwitcherReport struct {
+	Running         bool       `json:"running"`
+	Disabled        string     `json:"disabled,omitempty"`
+	Watching        string     `json:"woken_by,omitempty"`
+	Source          *Source    `json:"source,omitempty"`
+	Decision        *Decision  `json:"decision,omitempty"`
+	Load            Policy     `json:"load"`
+	LastApplied     string     `json:"last_applied,omitempty"`
+	LastAppliedAt   *time.Time `json:"last_applied_at,omitempty"`
+	LastError       string     `json:"last_error,omitempty"`
+	HeldUntil       *time.Time `json:"held_until,omitempty"`
+	Held            string     `json:"held_profile,omitempty"`
+	AssertedAtStart []string   `json:"asserted_at_start,omitempty"`
+}
+
+func (s *Switcher) Report() SwitcherReport {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	r := SwitcherReport{
+		Running: s.watching != "" && s.disabled == "", Disabled: s.disabled, Watching: s.watching,
+		Source: s.source, Decision: s.decision, Load: s.policy, LastApplied: s.applied,
+		LastAppliedAt: when(s.appliedAt), LastError: s.lastError, AssertedAtStart: s.asserted,
+	}
+	if s.now().Before(s.holdUntil) {
+		r.HeldUntil, r.Held = when(s.holdUntil), s.holdOf
+	}
+	return r
+}
+
+// when is a time for a report: absent rather than the zero time.
+func when(t time.Time) *time.Time {
+	if t.IsZero() {
+		return nil
+	}
+	return &t
+}
@@ -0,0 +1,190 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"strconv"
+	"testing"
+	"time"
+)
+
+func TestTheLoadMustBeSustainedToBoostAndToRelaxAndBetweenTheLinesNothingMoves(t *testing.T) {
+	var p Policy
+	at := time.Now()
+	mains := Source{OnAC: true, Reason: "ACAD (Mains) is online"}
+	for i := 0; i < SustainSamples-1; i++ {
+		p.Observe(90, at)
+	}
+	if p.Decide(mains).Profile != ProfileOnAC {
+		t.Fatal("boosted before the load was sustained")
+	}
+	p.Observe(35, at) // between the lines breaks the run
+	p.Observe(90, at)
+	if p.Boosted {
+		t.Fatal("a broken run still counted")
+	}
+	for i := 0; i < SustainSamples; i++ {
+		p.Observe(CPUHighPercent, at)
+	}
+	if d := p.Decide(mains); d.Profile != ProfileUnderLoad {
+		t.Fatalf("%+v", d)
+	}
+	p.Observe(35, at)
+	if !p.Boosted {
+		t.Fatal("load between the lines relaxed the boost")
+	}
+	for i := 0; i < RelaxSamples; i++ {
+		p.Observe(5, at)
+	}
+	if p.Decide(mains).Profile != ProfileOnAC {
+		t.Fatal("did not relax after a sustained low")
+	}
+	p.Boosted = true
+	if d := p.Decide(Source{OnAC: false, Reason: "BAT1 is discharging"}); d.Profile != ProfileOnBattery {
+		t.Fatalf("battery: %+v", d)
+	}
+}
+
+func TestIOWaitIsIdle(t *testing.T) {
+	a, err := ParseProcStat("cpu  100 0 100 700 100 0 0 0 0 0\ncpu0 1 2 3\n")
+	if err != nil {
+		t.Fatal(err)
+	}
+	b, _ := ParseProcStat("cpu  150 0 150 700 200 0 0 0 0 0\n")
+	busy, ok := Busy(a, b)
+	if !ok || busy != 50 {
+		t.Fatalf("%v %v", busy, ok)
+	}
+	if _, ok := Busy(b, b); ok {
+		t.Fatal("no time passed and a load was answered")
+	}
+	if _, err := ParseProcStat("intr 1 2"); err == nil {
+		t.Fatal("a file without the cpu line was read")
+	}
+}
+
+func switcherOn(t *testing.T) (*fake, *Switcher, *[]map[string]any) {
+	f := newFake(t)
+	f.onMains()
+	f.file("/proc/stat", "cpu  0 0 0 0 0 0 0 0\n")
+	var emitted []map[string]any
+	sw := NewSwitcher(f.machine(), func(_ string, body any) error {
+		emitted = append(emitted, body.(map[string]any))
+		return nil
+	})
+	return f, sw, &emitted
+}
+
+func TestStartingIsNotAReasonToSwitch(t *testing.T) {
+	f, sw, emitted := switcherOn(t)
+	sw.Evaluate(context.Background(), false)
+	if calls := f.callsLike("asusctl profile set"); len(calls) != 0 || len(*emitted) != 0 {
+		t.Fatalf("the first decision acted: %v %v", calls, *emitted)
+	}
+}
+
+func TestAChangeOfPowerSourceSwitchesOnceAndPublishesIt(t *testing.T) {
+	f, sw, emitted := switcherOn(t)
+	ctx := context.Background()
+	sw.Evaluate(ctx, false)
+	f.onBattery()
+	sw.Evaluate(ctx, false)
+	sw.Evaluate(ctx, true) // nothing changed: nothing done, and on battery nothing sampled
+	if calls := f.callsLike("asusctl profile set"); len(calls) != 1 || calls[0] != "asusctl profile set Quiet" {
+		t.Fatalf("%v", calls)
+	}
+	if len(*emitted) != 1 || (*emitted)[0]["profile"] != "Quiet" || (*emitted)[0]["from"] != "Balanced" {
+		t.Fatalf("%v", *emitted)
+	}
+	f.onMains()
+	sw.Evaluate(ctx, false)
+	if calls := f.callsLike("asusctl profile set"); len(calls) != 2 || calls[1] != "asusctl profile set Balanced" {
+		t.Fatalf("%v", calls)
+	}
+}
+
+func TestSustainedLoadOnMainsBoostsFromSamples(t *testing.T) {
+	f, sw, _ := switcherOn(t)
+	ctx := context.Background()
+	sw.Evaluate(ctx, false)
+	var user int
+	for i := 1; i <= SustainSamples; i++ {
+		user += 90
+		f.file("/proc/stat", "cpu  "+itoa(user)+" 0 0 "+itoa(i*10)+" 0 0 0 0\n")
+		sw.Evaluate(ctx, true)
+	}
+	if !f.called("asusctl profile set Performance") {
+		t.Fatalf("%v", f.calls)
+	}
+}
+
+func TestAHoldKeepsTheProfileUntilItEndsAndAFailureIsTriedAgain(t *testing.T) {
+	f, sw, _ := switcherOn(t)
+	ctx := context.Background()
+	now := time.Now()
+	sw.now = func() time.Time { return now }
+	sw.Evaluate(ctx, false)
+	f.onBattery()
+	sw.Evaluate(ctx, false) // source change ends any hold; switches to Quiet
+	sw.Hold("Performance", time.Hour)
+	f.fails["asusctl profile set Balanced"] = errors.New("asusd is restarting")
+	f.onMains()
+	sw.Evaluate(ctx, false) // a change of source: the hold ends, the switch is attempted and fails
+	if r := sw.Report(); r.LastError == "" || r.Held != "" {
+		t.Fatalf("%+v", r)
+	}
+	delete(f.fails, "asusctl profile set Balanced")
+	sw.Evaluate(ctx, false)
+	if r := sw.Report(); r.LastApplied != "Balanced" || r.LastError != "" {
+		t.Fatalf("not tried again: %+v", r)
+	}
+	// A hold on the same source keeps a new decision from acting until it ends.
+	sw.Hold("Quiet", time.Hour)
+	sw.policy.Boosted = true
+	sw.Evaluate(ctx, false)
+	if f.called("asusctl profile set Performance") {
+		t.Fatal("switched during a hold")
+	}
+	now = now.Add(2 * time.Hour)
+	sw.Evaluate(ctx, false)
+	if !f.called("asusctl profile set Performance") {
+		t.Fatal("did not act once the hold ended")
+	}
+}
+
+func TestAsusdsSettingsAreSetOnlyWhereTheyDiffer(t *testing.T) {
+	f := newFake(t)
+	f.answers["asusctl battery info"] = "Current battery charge limit: 100%\n"
+	f.answers["asusctl profile get"] = "Active profile: Balanced\nAC profile Performance\nBattery profile Quiet\n"
+	sw := NewSwitcher(f.machine(), nil)
+	sw.AssertVendorSettings(context.Background())
+	if !f.called("asusctl battery limit 80") || !f.called("asusctl profile set -a Balanced") || f.called("asusctl profile set -b Quiet") {
+		t.Fatalf("%v", f.calls)
+	}
+}
+
+func TestTheSwitcherDoesNotActOnAnotherModel(t *testing.T) {
+	f := newFake(t)
+	f.file("/sys/class/dmi/id/product_family", "ROG Strix\n")
+	sw := NewSwitcher(f.machine(), nil)
+	done := make(chan struct{})
+	go func() { sw.Run(context.Background()); close(done) }()
+	select {
+	case <-done:
+	case <-time.After(2 * time.Second):
+		t.Fatal("the switcher ran on another model")
+	}
+	if r := sw.Report(); r.Running || r.Disabled == "" || len(f.calls) != 0 {
+		t.Fatalf("%+v %v", r, f.calls)
+	}
+}
+
+func TestOnlyPowerSupplyUeventsWake(t *testing.T) {
+	yes := []byte("change@/devices/LNXSYSTM:00/ACPI0003:00/power_supply/ACAD\x00ACTION=change\x00SUBSYSTEM=power_supply\x00POWER_SUPPLY_ONLINE=0\x00")
+	no := []byte("change@/devices/virtual/net/wlan0\x00ACTION=change\x00SUBSYSTEM=net\x00")
+	if !powerSupplyEvent(yes) || powerSupplyEvent(no) {
+		t.Fatal("the uevent filter")
+	}
+}
+
+func itoa(n int) string { return strconv.Itoa(n) }
@@ -0,0 +1,168 @@
+package main
+
+import (
+	"context"
+	"path"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+// Sensor is one temperature, fan or power reading from hwmon.
+type Sensor struct {
+	Chip  string  `json:"chip"`
+	Label string  `json:"label"`
+	Value float64 `json:"value"`
+}
+
+// DGPU is the discrete GPU as the PCI bus and its driver see it.
+type DGPU struct {
+	Address string   `json:"pci_address"`
+	Runtime string   `json:"runtime_status"`
+	Name    string   `json:"name,omitempty"`
+	TempC   *float64 `json:"temp_c,omitempty"`
+	PowerW  *float64 `json:"power_w,omitempty"`
+	PState  string   `json:"pstate,omitempty"`
+	Note    string   `json:"note,omitempty"`
+}
+
+// hwmon reads every hwmon reading of one kind: "temp" (°C), "fan" (RPM) or "power" (W).
+func (m *Machine) hwmon(kind string) []Sensor {
+	var out []Sensor
+	for _, dir := range m.glob("/sys/class/hwmon/hwmon*") {
+		chip := m.read(dir + "/name")
+		inputs := m.glob(dir + "/" + kind + "*_input")
+		if kind == "power" {
+			inputs = append(inputs, m.glob(dir+"/power*_average")...)
+		}
+		for _, in := range inputs {
+			v, ok := m.readInt(in)
+			if !ok {
+				continue
+			}
+			base := path.Base(in)
+			stem := base[:strings.LastIndex(base, "_")]
+			label := m.read(dir + "/" + stem + "_label")
+			if label == "" {
+				label = base
+			} else if strings.HasSuffix(base, "_average") {
+				label += " (average)"
+			}
+			value := float64(v)
+			switch kind {
+			case "temp":
+				value = round1(value / 1000)
+			case "power":
+				value = round1(value / 1e6)
+			}
+			out = append(out, Sensor{Chip: chip, Label: label, Value: value})
+		}
+	}
+	sort.Slice(out, func(i, j int) bool {
+		if out[i].Chip != out[j].Chip {
+			return out[i].Chip < out[j].Chip
+		}
+		return out[i].Label < out[j].Label
+	})
+	return out
+}
+
+// dgpu finds the NVIDIA display controller and, only when it is already awake, asks its driver for
+// its temperature and draw. **Asking wakes it**: nvidia-smi brings a suspended GPU out of D3, which
+// is the power a reading of power draw should not cost.
+func (m *Machine) dgpu(ctx context.Context) *DGPU {
+	for _, dir := range m.glob("/sys/bus/pci/devices/*") {
+		if m.read(dir+"/vendor") != "0x10de" || !strings.HasPrefix(m.read(dir+"/class"), "0x03") {
+			continue
+		}
+		g := &DGPU{Address: path.Base(dir), Runtime: m.read(dir + "/power/runtime_status")}
+		if g.Runtime != "active" {
+			g.Note = "the discrete GPU is " + g.Runtime + "; not woken to be read"
+			return g
+		}
+		out, err := m.Run(ctx, "nvidia-smi", "--query-gpu=name,temperature.gpu,power.draw,pstate", "--format=csv,noheader,nounits")
+		if err != nil {
+			g.Note = "nvidia-smi: " + err.Error()
+			return g
+		}
+		f := strings.Split(strings.TrimSpace(strings.SplitN(out, "\n", 2)[0]), ",")
+		if len(f) >= 4 {
+			g.Name = strings.TrimSpace(f[0])
+			if t, err := strconv.ParseFloat(strings.TrimSpace(f[1]), 64); err == nil {
+				g.TempC = &t
+			}
+			if w, err := strconv.ParseFloat(strings.TrimSpace(f[2]), 64); err == nil {
+				w = round1(w)
+				g.PowerW = &w
+			}
+			g.PState = strings.TrimSpace(f[3])
+		}
+		return g
+	}
+	return nil
+}
+
+// Thermals is what the thermals tool answers.
+type Thermals struct {
+	Temperatures []Sensor `json:"temperatures_c"`
+	Fans         []Sensor `json:"fans_rpm"`
+	DGPU         *DGPU    `json:"dgpu,omitempty"`
+	Profile      string   `json:"platform_profile,omitempty"`
+	Hottest      *Sensor  `json:"hottest,omitempty"`
+}
+
+func (m *Machine) Thermals(ctx context.Context) Thermals {
+	t := Thermals{Temperatures: m.hwmon("temp"), Fans: m.hwmon("fan"), DGPU: m.dgpu(ctx),
+		Profile: m.read("/sys/firmware/acpi/platform_profile")}
+	if t.Temperatures == nil {
+		t.Temperatures = []Sensor{}
+	}
+	if t.Fans == nil {
+		t.Fans = []Sensor{}
+	}
+	for i := range t.Temperatures {
+		if t.Hottest == nil || t.Temperatures[i].Value > t.Hottest.Value {
+			h := t.Temperatures[i]
+			t.Hottest = &h
+		}
+	}
+	return t
+}
+
+// PowerDraw is what the power-draw tool answers.
+type PowerDraw struct {
+	Source      Source   `json:"source"`
+	BatteryW    *float64 `json:"battery_w,omitempty"`
+	BatteryFlow string   `json:"battery_flow,omitempty"`
+	CPUPackageW *float64 `json:"apu_package_w,omitempty"`
+	DGPU        *DGPU    `json:"dgpu,omitempty"`
+	Note        string   `json:"note"`
+}
+
+func (m *Machine) PowerDraw(ctx context.Context) PowerDraw {
+	p := PowerDraw{Source: PowerSource(m.Supplies()), DGPU: m.dgpu(ctx),
+		Note: "on battery, battery_w is what the whole machine draws; on mains it is only what the battery takes or gives"}
+	for _, b := range m.Batteries() {
+		if b.PowerW != nil {
+			w := *b.PowerW
+			p.BatteryW = &w
+			switch strings.ToLower(b.Status) {
+			case "discharging":
+				p.BatteryFlow = "discharging"
+			case "charging":
+				p.BatteryFlow = "charging"
+			default:
+				p.BatteryFlow = strings.ToLower(b.Status)
+			}
+			break
+		}
+	}
+	// The integrated GPU's hwmon reports the whole APU's package power (PPT) on this model.
+	for _, s := range m.hwmon("power") {
+		if s.Chip == "amdgpu" && s.Label == "PPT" {
+			w := s.Value
+			p.CPUPackageW = &w
+		}
+	}
+	return p
+}
@@ -0,0 +1,308 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"math"
+	"strconv"
+	"strings"
+	"time"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+// Tools is the module's tools, over one machine and its switcher.
+func Tools(m *Machine, sw *Switcher) []stdio.Tool {
+	ctx := context.Background
+	return []stdio.Tool{
+		{
+			Name: "zephyrus_brightness",
+			Description: "Read or set the internal panel's and the keyboard's backlight. With no argument, reads both. " +
+				"panel is a percentage (40) or a step (+5, -10), never below 1 %; keyboard is off, low, med, high, 0-3, + or -.",
+			Input: map[string]any{
+				"panel":    map[string]any{"type": "string", "description": "percentage or step, e.g. 40, +5, -10"},
+				"keyboard": map[string]any{"type": "string", "description": "off, low, med, high, 0-3, + or -"},
+			},
+			Run: func(args map[string]any) (any, error) {
+				out := map[string]any{}
+				if p := str(args, "panel"); p != "" {
+					got, err := m.SetPanel(ctx(), p)
+					if err != nil {
+						return nil, err
+					}
+					out["panel"] = got
+				} else if got, err := m.PanelBrightness(); err == nil {
+					out["panel"] = got
+				} else {
+					out["panel_error"] = err.Error()
+				}
+				if k := str(args, "keyboard"); k != "" {
+					got, err := m.SetKeyboard(ctx(), k)
+					if err != nil {
+						return nil, err
+					}
+					out["keyboard"] = got
+				} else if got, err := m.KeyboardBrightness(); err == nil {
+					out["keyboard"] = got
+				} else {
+					out["keyboard_error"] = err.Error()
+				}
+				return out, nil
+			},
+		},
+		{
+			Name:        "zephyrus_battery",
+			Description: "The battery: charge, energy, health (full against design), cycles, the charge limit, the power it gives or takes, and time left when discharging.",
+			Run: func(map[string]any) (any, error) {
+				return map[string]any{"source": PowerSource(m.Supplies()), "batteries": orEmpty(m.Batteries())}, nil
+			},
+		},
+		{
+			Name: "zephyrus_charge_limit",
+			Description: fmt.Sprintf("Read or set the battery charge limit through asusd. limit is 20-100; oneshot charges to full once "+
+				"and goes back to the limit. The module asserts %d %% again when its process next starts.", ChargeLimitPercent),
+			Input: map[string]any{
+				"limit":   map[string]any{"type": "integer", "description": "20-100"},
+				"oneshot": map[string]any{"type": "boolean", "description": "charge to full once, keeping the limit"},
+			},
+			Run: func(args map[string]any) (any, error) { return ChargeLimitTool(ctx(), m, args) },
+		},
+		{
+			Name: "zephyrus_gpu_mode",
+			Description: "Read or set the hybrid GPU's mode through supergfxd: Integrated, Hybrid or AsusMuxDgpu as the machine supports. " +
+				"Answers the mode, the discrete GPU's power state, any pending mode and the action it waits for (a logout, a reboot), " +
+				"and whether asusd will switch it again on the next change of power source.",
+			Input: map[string]any{
+				"mode": map[string]any{"type": "string", "description": "a supported mode, e.g. Integrated or Hybrid"},
+			},
+			Run: func(args map[string]any) (any, error) { return GPUModeTool(ctx(), m, args) },
+		},
+		{
+			Name: "zephyrus_profile",
+			Description: "Read or set the platform profile (Quiet, Balanced, Performance) through asusd. A profile set here is held " +
+				fmt.Sprintf("for hold_minutes (default %d, 0 for none) before the module's switcher may move it; a change of power source ends the hold.", int(DefaultHold.Minutes())),
+			Input: map[string]any{
+				"profile":      map[string]any{"type": "string", "enum": Profiles},
+				"hold_minutes": map[string]any{"type": "integer", "description": "how long the switcher leaves it (default 60, at most 1440)"},
+			},
+			Run: func(args map[string]any) (any, error) { return ProfileTool(ctx(), m, sw, args) },
+		},
+		{
+			Name:        "zephyrus_thermals",
+			Description: "Every temperature and fan the hardware reports (°C, RPM), the hottest, the platform profile, and the discrete GPU's temperature when it is awake (it is not woken to be read).",
+			Run:         func(map[string]any) (any, error) { return m.Thermals(ctx()), nil },
+		},
+		{
+			Name:        "zephyrus_power_draw",
+			Description: "What the machine draws: the battery's flow in watts, the APU's package power, the discrete GPU's draw when awake, and the power source with the reason it was decided.",
+			Run:         func(map[string]any) (any, error) { return m.PowerDraw(ctx()), nil },
+		},
+		{
+			Name: "zephyrus_profile_policy",
+			Description: "What the module's profile switcher would choose now and why: the power source, recent CPU load against the thresholds, " +
+				"the decision, the profile in force, any hold, what woke it, and what it asserted in asusd at start.",
+			Run: func(map[string]any) (any, error) { return PolicyTool(ctx(), m, sw), nil },
+		},
+		{
+			Name:        "zephyrus_fan_curves",
+			Description: "The fan curves asusd holds for each profile (or one profile): per fan, eight points of temperature and duty.",
+			Input: map[string]any{
+				"profile": map[string]any{"type": "string", "enum": Profiles},
+			},
+			Run: func(args map[string]any) (any, error) { return FanCurvesTool(ctx(), m, args) },
+		},
+		{
+			Name: "zephyrus_check",
+			Description: "Check what this module expects of the machine: the model, the vendor packages and daemons, the NVIDIA options in force, " +
+				"suspend and resume, the charge limit, one authority each over the profile and the GPU mode, and the predecessor's leftovers. Says what it did not check.",
+			Run: func(map[string]any) (any, error) { return m.Check(ctx(), sw), nil },
+		},
+	}
+}
+
+// ChargeLimitTool reads or sets the limit.
+func ChargeLimitTool(ctx context.Context, m *Machine, args map[string]any) (any, error) {
+	out := map[string]any{"module_limit_percent": ChargeLimitPercent}
+	if v, given := args["limit"]; given && v != nil {
+		n, err := whole(v, "limit")
+		if err != nil {
+			return nil, err
+		}
+		if n < 20 || n > 100 {
+			return nil, fmt.Errorf("limit %d is outside 20-100", n)
+		}
+		if _, err := m.Run(ctx, "asusctl", "battery", "limit", strconv.Itoa(n)); err != nil {
+			return nil, vendor("asusctl", err)
+		}
+		out["set"] = n
+	}
+	if b, _ := args["oneshot"].(bool); b {
+		if _, err := m.Run(ctx, "asusctl", "battery", "oneshot"); err != nil {
+			return nil, vendor("asusctl", err)
+		}
+		out["oneshot"] = "charging to full once; the limit returns after"
+	}
+	if n, err := m.ChargeLimit(ctx); err == nil {
+		out["asusd_limit_percent"] = n
+	} else {
+		out["asusd_error"] = err.Error()
+	}
+	for _, b := range m.Batteries() {
+		if b.LimitPercent != nil {
+			out["kernel_limit_percent"] = *b.LimitPercent
+		}
+	}
+	return out, nil
+}
+
+// GPUModeTool reads or sets the GPU mode.
+func GPUModeTool(ctx context.Context, m *Machine, args map[string]any) (any, error) {
+	g, err := m.GPU(ctx)
+	if err != nil {
+		return nil, err
+	}
+	out := map[string]any{}
+	if want := str(args, "mode"); want != "" {
+		mode := ""
+		for _, s := range g.Supported {
+			if strings.EqualFold(s, want) {
+				mode = s
+			}
+		}
+		if mode == "" {
+			return nil, fmt.Errorf("mode %q is not one this machine supports (%s)", want, strings.Join(g.Supported, ", "))
+		}
+		said, err := m.Run(ctx, "supergfxctl", "-m", mode)
+		if err != nil {
+			return nil, vendor("supergfxctl", err)
+		}
+		out["requested"] = mode
+		if s := strings.TrimSpace(said); s != "" {
+			out["supergfxctl_said"] = s
+		}
+		if g, err = m.GPU(ctx); err != nil {
+			return nil, err
+		}
+	}
+	out["gpu"] = g
+	if c := m.Asusd(); c != nil && (c.ACCommand != "" || c.BatteryCommand != "") {
+		out["asusd_switches_it"] = map[string]string{"on_ac": c.ACCommand, "on_battery": c.BatteryCommand,
+			"note": "asusd runs these on every change of power source, so a mode set here lasts until the next one"}
+	}
+	return out, nil
+}
+
+// ProfileTool reads or sets the profile.
+func ProfileTool(ctx context.Context, m *Machine, sw *Switcher, args map[string]any) (any, error) {
+	out := map[string]any{}
+	if want := str(args, "profile"); want != "" {
+		p, err := canonicalProfile(want)
+		if err != nil {
+			return nil, err
+		}
+		hold := DefaultHold
+		if v, given := args["hold_minutes"]; given && v != nil {
+			n, err := whole(v, "hold_minutes")
+			if err != nil {
+				return nil, err
+			}
+			if n < 0 {
+				return nil, fmt.Errorf("hold_minutes must not be negative")
+			}
+			hold = time.Duration(min(n, 1440)) * time.Minute
+		}
+		if err := m.SetProfile(ctx, p); err != nil {
+			return nil, err
+		}
+		out["set"] = p
+		if sw != nil {
+			if until := sw.Hold(p, hold); !until.IsZero() {
+				out["held_until"] = until
+			}
+		}
+	}
+	state, err := m.Profile(ctx)
+	if err != nil {
+		return nil, err
+	}
+	out["profile"] = state
+	return out, nil
+}
+
+// PolicyTool reports the switcher and, independently of it, what the policy says now.
+func PolicyTool(ctx context.Context, m *Machine, sw *Switcher) any {
+	out := map[string]any{
+		"thresholds": map[string]any{
+			"on_battery": ProfileOnBattery, "on_ac": ProfileOnAC, "under_load": ProfileUnderLoad,
+			"cpu_high_percent": CPUHighPercent, "cpu_low_percent": CPULowPercent,
+			"sample_every": SampleEvery.String(), "sustain_samples": SustainSamples, "relax_samples": RelaxSamples,
+			"set_by": "constants until settings exist (novox/hq issue 168)",
+		},
+	}
+	if sw != nil {
+		out["switcher"] = sw.Report()
+	} else {
+		var p Policy
+		out["decision_now"] = p.Decide(PowerSource(m.Supplies()))
+	}
+	if state, err := m.Profile(ctx); err == nil {
+		out["in_force"] = state
+	} else {
+		out["in_force_error"] = err.Error()
+	}
+	if pid, ok := m.predecessorProcess("auto-profile"); ok {
+		out["second_switcher"] = fmt.Sprintf("the predecessor's auto-profile still runs (pid %d) and overrides this every five seconds", pid)
+	}
+	return out
+}
+
+// FanCurvesTool reads asusd's fan curves.
+func FanCurvesTool(ctx context.Context, m *Machine, args map[string]any) (any, error) {
+	profiles := Profiles
+	if want := str(args, "profile"); want != "" {
+		p, err := canonicalProfile(want)
+		if err != nil {
+			return nil, err
+		}
+		profiles = []string{p}
+	}
+	out := map[string]any{}
+	for _, p := range profiles {
+		said, err := m.Run(ctx, "asusctl", "fan-curve", "--mod-profile", strings.ToLower(p))
+		if err != nil {
+			return nil, vendor("asusctl", err)
+		}
+		out[p] = orEmpty(ParseFanCurves(said))
+	}
+	return out, nil
+}
+
+func str(args map[string]any, key string) string {
+	s, _ := args[key].(string)
+	return strings.TrimSpace(s)
+}
+
+// whole is an integer argument given as a JSON number or a numeric string.
+func whole(v any, key string) (int, error) {
+	switch n := v.(type) {
+	case float64:
+		if n != math.Trunc(n) {
+			return 0, fmt.Errorf("%s must be a whole number, not %v", key, n)
+		}
+		return int(n), nil
+	case string:
+		i, err := strconv.Atoi(strings.TrimSpace(n))
+		if err != nil {
+			return 0, fmt.Errorf("%s must be a whole number, not %q", key, n)
+		}
+		return i, nil
+	}
+	return 0, fmt.Errorf("%s must be a whole number", key)
+}
+
+func orEmpty[T any](s []T) []T {
+	if s == nil {
+		return []T{}
+	}
+	return s
+}
@@ -0,0 +1,72 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"syscall"
+)
+
+// The kernel announces every change of a power supply — an adapter plugged or pulled, a battery
+// starting or stopping to discharge — as a uevent on a netlink socket that any account may listen
+// on. That is the event the switcher reacts to: no daemon, no bus client, no polling.
+//
+// upower re-announces the same changes on the system bus, and listening there would need a D-Bus
+// client in the bundle; udev's re-broadcast (netlink group 2) carries a libudev header. The kernel's
+// own group (1) is the source both of them read.
+
+// powerSupplyEvent says whether a uevent is about a power supply.
+func powerSupplyEvent(msg []byte) bool {
+	for _, field := range bytes.Split(msg, []byte{0}) {
+		if bytes.Equal(field, []byte("SUBSYSTEM=power_supply")) {
+			return true
+		}
+	}
+	return false
+}
+
+// listenPowerSupply opens the kernel's uevent socket and sends on the channel for each power-supply
+// event, never blocking: a burst of events is one wake-up. It stops when ctx ends.
+func listenPowerSupply(ctx context.Context) (<-chan struct{}, error) {
+	fd, err := syscall.Socket(syscall.AF_NETLINK, syscall.SOCK_RAW|syscall.SOCK_CLOEXEC, syscall.NETLINK_KOBJECT_UEVENT)
+	if err != nil {
+		return nil, fmt.Errorf("opening the kernel's uevent socket: %w", err)
+	}
+	if err := syscall.Bind(fd, &syscall.SockaddrNetlink{Family: syscall.AF_NETLINK, Groups: 1}); err != nil {
+		syscall.Close(fd)
+		return nil, fmt.Errorf("joining the kernel's uevent group: %w", err)
+	}
+	events := make(chan struct{}, 1)
+	go func() {
+		<-ctx.Done()
+		syscall.Close(fd)
+	}()
+	go func() {
+		defer close(events)
+		buf := make([]byte, 64*1024)
+		for {
+			n, _, err := syscall.Recvfrom(fd, buf, 0)
+			if err != nil {
+				if err == syscall.EINTR || err == syscall.ENOBUFS {
+					// ENOBUFS: events were dropped. Treat it as one, since a dropped one may have
+					// been the adapter.
+					if err == syscall.ENOBUFS {
+						select {
+						case events <- struct{}{}:
+						default:
+						}
+					}
+					continue
+				}
+				return
+			}
+			if powerSupplyEvent(buf[:n]) {
+				select {
+				case events <- struct{}{}:
+				default:
+				}
+			}
+		}
+	}()
+	return events, nil
+}
@@ -0,0 +1,33 @@
+#!/bin/bash
+# zephyrus-backlight + | - | PERCENT — step or set the internal panel's backlight, never below 1 %.
+# Shipped by the mesh's asus-zephyrus-g14 module; edit the catalogue.
+#
+# The panel is the backlight beneath the eDP connector, not a name: in hybrid mode this model also
+# registers the discrete GPU's backlight (nvidia_0), which moves nothing. Writable by the video group
+# through the module's udev rule, so the vendor-key trigger needs no root.
+set -u
+STEP=5
+dev=""
+for d in /sys/class/backlight/*; do
+	[ -e "$d" ] || continue
+	case "$(readlink -f "$d")" in *-eDP-*) dev=$d; break ;; esac
+done
+if [ -z "$dev" ]; then
+	for d in /sys/class/backlight/*; do [ -e "$d" ] && { dev=$d; break; }; done
+fi
+[ -n "$dev" ] || { echo "zephyrus-backlight: no backlight" >&2; exit 1; }
+cur=$(cat "$dev/brightness")
+max=$(cat "$dev/max_brightness")
+pct=$(( cur * 100 / max ))
+case "${1:-}" in
+	+|up|Up) pct=$(( pct + STEP )) ;;
+	-|down|Down) pct=$(( pct - STEP )) ;;
+	''|*[!0-9]*) echo "usage: zephyrus-backlight + | - | PERCENT" >&2; exit 2 ;;
+	*) pct=$1 ;;
+esac
+(( pct < 1 )) && pct=1
+(( pct > 100 )) && pct=100
+new=$(( max * pct / 100 ))
+(( new < 1 )) && new=1
+printf '%s' "$new" >"$dev/brightness" || exit 1
+exec "$(dirname "$0")/zephyrus-notify" 5555 "Brightness: ${pct}%"
@@ -0,0 +1,12 @@
+#!/bin/bash
+# zephyrus-notify ID SUMMARY — a short desktop notification that replaces the previous one with the
+# same ID, through the session's notification service on its bus. busctl is the service manager's
+# own client, so nothing is installed for it. Shipped by the mesh's asus-zephyrus-g14 module.
+set -u
+id=${1:-0}
+summary=${2:-}
+uid=$(id -u)
+DBUS_SESSION_BUS_ADDRESS="unix:path=/run/user/${uid}/bus" \
+	busctl --user call org.freedesktop.Notifications /org/freedesktop/Notifications \
+	org.freedesktop.Notifications Notify susssasa{sv}i \
+	asus-zephyrus-g14 "$id" "" "$summary" "" 0 1 urgency y 0 1500 >/dev/null 2>&1 || true
@@ -0,0 +1,38 @@
+#!/bin/bash
+# zephyrus-session COMMAND [ARG...] — run a command in the operator's graphical session from outside
+# it: from a vendor-key trigger, which triggerhappy runs as the operator's account but with none of
+# the session's environment. Shipped by the mesh's asus-zephyrus-g14 module; edit the catalogue.
+#
+# What it replaces: the predecessor's `as-user`, which triggerhappy ran as root and which `su`-ed to
+# a named person with a hard-coded user id and display, and sourced a file of secrets on the way.
+# Here the account is whoever runs it, the bus is that account's, and the display is the one the
+# account's own session uses. Nothing is sourced.
+set -u
+uid=$(id -u)
+export XDG_RUNTIME_DIR="/run/user/${uid}"
+export DBUS_SESSION_BUS_ADDRESS="unix:path=${XDG_RUNTIME_DIR}/bus"
+home=$(getent passwd "$uid" | cut -d: -f6)
+[ -n "$home" ] && export HOME="$home"
+if [ -z "${DISPLAY:-}" ]; then
+	# The login manager may not record the display with logind; any process of this account that
+	# has one says which it is.
+	for s in $(loginctl list-sessions --no-legend 2>/dev/null | awk -v u="$uid" '$2 == u { print $1 }'); do
+		d=$(loginctl show-session "$s" -p Display --value 2>/dev/null)
+		if [ -n "$d" ]; then export DISPLAY="$d"; break; fi
+	done
+fi
+if [ -z "${DISPLAY:-}" ]; then
+	for pid in $(pgrep -u "$uid" 2>/dev/null); do
+		env=$(tr '\0' '\n' <"/proc/$pid/environ" 2>/dev/null) || continue
+		d=$(printf '%s\n' "$env" | sed -n 's/^DISPLAY=//p' | head -n1)
+		if [ -n "$d" ]; then
+			export DISPLAY="$d"
+			a=$(printf '%s\n' "$env" | sed -n 's/^XAUTHORITY=//p' | head -n1)
+			[ -n "$a" ] && export XAUTHORITY="$a"
+			break
+		fi
+	done
+fi
+: "${XAUTHORITY:=${HOME}/.Xauthority}"
+export XAUTHORITY
+exec "$@"
@@ -0,0 +1,29 @@
+#!/bin/bash
+# zephyrus-touchpad reset | toggle — apply the touchpad's settings again, or switch it on or off.
+# Shipped by the mesh's asus-zephyrus-g14 module; edit the catalogue.
+#
+# The settings themselves are an X input class (/etc/X11/xorg.conf.d/30-asus-zephyrus-g14-touchpad.conf),
+# which X applies every time the device appears — after a resume too, which is what the predecessor's
+# sleep hook existed for. This is the manual form, bound to the touchpad key.
+set -u
+here=$(dirname "$0")
+name=$("$here/zephyrus-session" xinput list --name-only 2>/dev/null | grep -m1 -i 'touchpad')
+[ -n "$name" ] || { echo "zephyrus-touchpad: no touchpad in this session" >&2; exit 1; }
+x() { "$here/zephyrus-session" xinput "$@"; }
+case "${1:-reset}" in
+	reset)
+		x set-prop "$name" "libinput Tapping Enabled" 1
+		x set-prop "$name" "libinput Natural Scrolling Enabled" 1
+		x set-prop "$name" "libinput Accel Speed" 0.15
+		x enable "$name"
+		"$here/zephyrus-session" "$here/zephyrus-notify" 7779 "Touchpad: reset"
+		;;
+	toggle)
+		if x list-props "$name" | grep -q 'Device Enabled ([0-9]*):[[:space:]]*1'; then
+			x disable "$name"; "$here/zephyrus-session" "$here/zephyrus-notify" 7779 "Touchpad: off"
+		else
+			x enable "$name"; "$here/zephyrus-session" "$here/zephyrus-notify" 7779 "Touchpad: on"
+		fi
+		;;
+	*) echo "usage: zephyrus-touchpad reset | toggle" >&2; exit 2 ;;
+esac
@@ -0,0 +1,5 @@
+module asuszephyrusg14
+
+go 1.22
+
+require git.novox.be/novox/mesh-sdk/go v0.1.6
@@ -0,0 +1,2 @@
+git.novox.be/novox/mesh-sdk/go v0.1.6 h1:9qzdYONYbJdWcu6sxQcq9v1LI0JxcfkiKYkMUzJSkVQ=
+git.novox.be/novox/mesh-sdk/go v0.1.6/go.mod h1:GFuZUElBZ9A++mxgIKo97aXXo+kV0uJ/UkbhQPPIbrY=
@@ -0,0 +1,254 @@
+{
+  "module": "asus-zephyrus-g14",
+  "version": "1",
+  "capabilities": [
+    "package-manager",
+    "service-manager"
+  ],
+  "emits": [
+    "profile.switched"
+  ],
+  "tools": [
+    "zephyrus_brightness",
+    "zephyrus_battery",
+    "zephyrus_charge_limit",
+    "zephyrus_gpu_mode",
+    "zephyrus_profile",
+    "zephyrus_thermals",
+    "zephyrus_power_draw",
+    "zephyrus_profile_policy",
+    "zephyrus_fan_curves",
+    "zephyrus_check"
+  ],
+  "resources": [
+    {
+      "id": "asusctl",
+      "type": "package",
+      "package": "asusctl"
+    },
+    {
+      "id": "playerctl",
+      "type": "package",
+      "package": "playerctl"
+    },
+    {
+      "id": "xinput",
+      "type": "package",
+      "package": "xorg-xinput"
+    },
+    {
+      "id": "asusd",
+      "type": "service",
+      "unit": "asusd.service",
+      "state": "running"
+    },
+    {
+      "id": "supergfxd",
+      "type": "service",
+      "unit": "supergfxd.service",
+      "state": "running",
+      "boot": "enabled"
+    },
+    {
+      "id": "scripts",
+      "type": "archive",
+      "path": "/usr/local/lib/asus-zephyrus-g14",
+      "artifact": "scripts"
+    },
+    {
+      "id": "nvidia-options",
+      "type": "file",
+      "path": "/etc/modprobe.d/g14-nvidia-power.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The discrete GPU's driver options on the ROG Zephyrus G14 (GA403, RTX 40 series, hybrid graphics).\n#\n# NVreg_DynamicPowerManagement=0x00 turns runtime D3 off. With it on, a change of power source sends\n# the driver an ACPI notification it fails to handle on this model (\"RmHandleDNotifierEvent: Failed to\n# handle ACPI D-Notifier event, status=0x62\"), and the GPU stops making progress until the machine is\n# powered off. Off costs a few idle watts in hybrid mode and keeps the machine up.\n#\n# NVreg_PreserveVideoMemoryAllocations=1 saves video memory across suspend, so what used the GPU still\n# works after waking. It needs nvidia-suspend, -hibernate and -resume to run around a sleep, which this\n# module's drop-ins on the sleep services ask for.\n#\n# A change here applies when the driver next loads: at the next boot.\noptions nvidia NVreg_PreserveVideoMemoryAllocations=1\noptions nvidia NVreg_DynamicPowerManagement=0x00\n"
+    },
+    {
+      "id": "video-options",
+      "type": "file",
+      "path": "/etc/modprobe.d/video-brightness-switch.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The ACPI video driver does not change the backlight itself on the brightness keys: on this model it\n# moves the wrong one. The keys are triggerhappy's (see /etc/triggerhappy/triggers.d/asus-g14.conf).\n# Applies when the module next loads: at the next boot.\noptions video brightness_switch_enabled=0\n"
+    },
+    {
+      "id": "suspend-drop-ins",
+      "type": "directory",
+      "path": "/etc/systemd/system/systemd-suspend.service.d",
+      "mode": "0755"
+    },
+    {
+      "id": "nvidia-on-suspend",
+      "type": "file",
+      "path": "/etc/systemd/system/systemd-suspend.service.d/asus-zephyrus-g14-nvidia.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The NVIDIA driver's own sleep actions, asked for by the sleep itself rather than enabled as\n# links: the mesh declares files and never makes links (novox/hq ADR 0012), and the host's service\n# shape must not start these units by hand, which would put the GPU to sleep with the machine awake.\n[Unit]\nWants=nvidia-suspend.service nvidia-resume.service\n"
+    },
+    {
+      "id": "hibernate-drop-ins",
+      "type": "directory",
+      "path": "/etc/systemd/system/systemd-hibernate.service.d",
+      "mode": "0755"
+    },
+    {
+      "id": "nvidia-on-hibernate",
+      "type": "file",
+      "path": "/etc/systemd/system/systemd-hibernate.service.d/asus-zephyrus-g14-nvidia.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The NVIDIA driver's own sleep actions, asked for by the sleep itself rather than enabled as\n# links: the mesh declares files and never makes links (novox/hq ADR 0012), and the host's service\n# shape must not start these units by hand, which would put the GPU to sleep with the machine awake.\n[Unit]\nWants=nvidia-hibernate.service nvidia-resume.service\n"
+    },
+    {
+      "id": "suspend-then-hibernate-drop-ins",
+      "type": "directory",
+      "path": "/etc/systemd/system/systemd-suspend-then-hibernate.service.d",
+      "mode": "0755"
+    },
+    {
+      "id": "nvidia-on-suspend-then-hibernate",
+      "type": "file",
+      "path": "/etc/systemd/system/systemd-suspend-then-hibernate.service.d/asus-zephyrus-g14-nvidia.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The NVIDIA driver's own sleep actions, asked for by the sleep itself rather than enabled as\n# links: the mesh declares files and never makes links (novox/hq ADR 0012), and the host's service\n# shape must not start these units by hand, which would put the GPU to sleep with the machine awake.\n[Unit]\nWants=nvidia-suspend-then-hibernate.service nvidia-resume.service\n"
+    },
+    {
+      "id": "powerd-drop-ins",
+      "type": "directory",
+      "path": "/etc/systemd/system/nvidia-powerd.service.d",
+      "mode": "0755"
+    },
+    {
+      "id": "powerd-opt-in",
+      "type": "file",
+      "path": "/etc/systemd/system/nvidia-powerd.service.d/asus-zephyrus-g14.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# nvidia-powerd (Dynamic Boost) was the first error in the chain that hung this model's GPU on a change\n# of power source, and asusd starts it on mains. It runs only when the kernel command line says\n# zephyrus.nvidia-powerd — an explicit opt-in, at boot.\n[Unit]\nConditionKernelCommandLine=zephyrus.nvidia-powerd\n"
+    },
+    {
+      "id": "logind-drop-ins",
+      "type": "directory",
+      "path": "/etc/systemd/logind.conf.d",
+      "mode": "0755"
+    },
+    {
+      "id": "logind-power",
+      "type": "file",
+      "path": "/etc/systemd/logind.conf.d/power.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The power key and the lid suspend, on battery, on mains and docked alike.\n[Login]\nHandlePowerKey=suspend\nHandleLidSwitch=suspend\nHandleLidSwitchExternalPower=suspend\nHandleLidSwitchDocked=suspend\n"
+    },
+    {
+      "id": "logind",
+      "type": "service",
+      "unit": "systemd-logind.service",
+      "reload-on": [
+        "logind-power"
+      ]
+    },
+    {
+      "id": "backlight-rule",
+      "type": "file",
+      "path": "/etc/udev/rules.d/90-backlight.rules",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The backlights are writable by the video group, so the brightness keys and the module's brightness tool\n# move the panel without root.\nACTION==\"add\", SUBSYSTEM==\"backlight\", RUN+=\"/usr/bin/chgrp video /sys/class/backlight/%k/brightness\", RUN+=\"/usr/bin/chmod g+w /sys/class/backlight/%k/brightness\"\n"
+    },
+    {
+      "id": "udev",
+      "type": "service",
+      "unit": "systemd-udevd.service",
+      "reload-on": [
+        "backlight-rule"
+      ]
+    },
+    {
+      "id": "triggerhappy-drop-ins",
+      "type": "directory",
+      "path": "/etc/systemd/system/triggerhappy.service.d",
+      "mode": "0755"
+    },
+    {
+      "id": "triggerhappy-as-account",
+      "type": "file",
+      "path": "/etc/systemd/system/triggerhappy.service.d/asus-zephyrus-g14.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# triggerhappy runs the vendor-key triggers as the operator's account, not as root: it opens the input\n# devices first and then drops to the account with its groups (input, video), so the triggers reach the\n# account's own session bus and the panel through the video group, with no su and no hard-coded user.\n[Service]\nExecStart=\nExecStart=/usr/bin/thd --triggers /etc/triggerhappy/triggers.d/ --socket /run/thd.socket --user ${machine:account} --deviceglob /dev/input/event*\n"
+    },
+    {
+      "id": "vendor-keys",
+      "type": "file",
+      "path": "/etc/triggerhappy/triggers.d/asus-g14.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The ROG Zephyrus G14's vendor keys, which reach no X client. Run as the operator's account (see the\n# module's drop-in on triggerhappy.service).\nKEY_PROG1\t1\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-session playerctl play-pause\nKEY_PROG3\t1\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-session playerctl previous\nKEY_PROG4\t1\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-session playerctl next\nKEY_BRIGHTNESSDOWN\t1\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-backlight -\nKEY_BRIGHTNESSDOWN\t2\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-backlight -\nKEY_BRIGHTNESSUP\t1\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-backlight +\nKEY_BRIGHTNESSUP\t2\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-backlight +\nKEY_F21\t1\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-touchpad reset\n"
+    },
+    {
+      "id": "triggerhappy",
+      "type": "service",
+      "unit": "triggerhappy.service",
+      "state": "running",
+      "boot": "enabled",
+      "restart-on": [
+        "triggerhappy-as-account",
+        "vendor-keys",
+        "scripts"
+      ]
+    },
+    {
+      "id": "upower-package",
+      "type": "package",
+      "package": "upower"
+    },
+    {
+      "id": "upower-drop-ins",
+      "type": "directory",
+      "path": "/etc/UPower/UPower.conf.d",
+      "mode": "0755"
+    },
+    {
+      "id": "low-battery",
+      "type": "file",
+      "path": "/etc/UPower/UPower.conf.d/50-asus-zephyrus-g14.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# On low battery the machine suspends rather than powering off, at 7 % — s2idle still draws a little,\n# so it leaves headroom. A drop-in over the package's own UPower.conf, which stays the package's.\n[UPower]\nUsePercentageForPolicy=true\nPercentageLow=15.0\nPercentageCritical=10.0\nPercentageAction=7.0\nCriticalPowerAction=Suspend\nAllowRiskyCriticalPowerAction=true\n"
+    },
+    {
+      "id": "upower",
+      "type": "service",
+      "unit": "upower.service",
+      "state": "running",
+      "boot": "enabled",
+      "restart-on": [
+        "low-battery"
+      ]
+    },
+    {
+      "id": "xorg-drop-ins",
+      "type": "directory",
+      "path": "/etc/X11/xorg.conf.d",
+      "mode": "0755"
+    },
+    {
+      "id": "touchpad",
+      "type": "file",
+      "path": "/etc/X11/xorg.conf.d/30-asus-zephyrus-g14-touchpad.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The touchpad's settings, applied by X every time the device appears — at login and after every\n# resume, when the device is initialised again. This replaces the predecessor's sleep hook, which ran\n# xinput after a resume as a named person on a guessed display.\nSection \"InputClass\"\n    Identifier \"asus-zephyrus-g14 touchpad\"\n    MatchIsTouchpad \"on\"\n    Option \"Tapping\" \"on\"\n    Option \"NaturalScrolling\" \"true\"\n    Option \"AccelSpeed\" \"0.15\"\nEndSection\n"
+    }
+  ],
+  "build": {
+    "artifacts": [
+      {
+        "name": "tools-go",
+        "kind": "bundle",
+        "language": "go",
+        "system": "arch",
+        "from": "cmd/zephyrus",
+        "binary": "zephyrus",
+        "loads": [
+          "zephyrus"
+        ]
+      },
+      {
+        "name": "scripts",
+        "kind": "archive",
+        "from": "files"
+      }
+    ]
+  }
+}
@@ -1,33 +0,0 @@
-# audit-logger's runtime: the shared runtime image, carrying this module's compiled code.
-#
-# **Built from this module's own directory and nothing else.** The toolkit is in the base image, so
-# nothing is copied out of a neighbouring checkout — which is what lets the mesh build this from a
-# repository and a path (novox/hq ADR 0069) rather than only on a workstation that happens to have
-# the siblings laid out beside it.
-
-# Two bases, named rather than pinned: the image this is COMPILED in, and the image it RUNS in.
-# They are different images on purpose — the first carries a compiler and the second must not, or
-# every running container would carry one it never invokes. The mesh answers both with the copies it
-# holds, because a fingerprint written here would name one particular copy and no other mesh has it
-# (novox/hq issue 044). Declared in module.json's `build.on`; deliberately no defaults, so a build
-# nobody told stops here and says which module to build first.
-ARG BUILD_BASE
-ARG RUNTIME_BASE
-
-FROM ${BUILD_BASE} AS build
-# Compiled under /app/modules so `@novox/mesh-sdk` resolves upward into the base's own
-# node_modules — the module is compiled against exactly the toolkit it will run against.
-WORKDIR /app/modules/audit-logger
-COPY . .
-# The compiler is invoked by its real path rather than through node_modules/.bin, whose entries are
-# symlinks to a launcher that requires its library relatively — resolved away when the base image
-# was assembled.
-RUN node /app/node_modules/typescript/bin/tsc audit.ts index.ts \
-      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
-
-FROM ${RUNTIME_BASE}
-COPY --from=build /app/modules/audit-logger/dist /app/modules/audit-logger/dist
-# **Served, not run.** This subscribes on import, and the serve mode binds the broker before it
-# imports anything — `run` exists for a step that works offline and exits, and would leave this
-# with nothing to subscribe to.
-ENV MESH_TOOL_MODULES=/app/modules/audit-logger/dist/index.js
@@ -5,27 +5,21 @@
  "consumes": [
    "**"
  ],
-  "own-secrets": {
-    "broker": "/var/lib/audit-logger/broker"
-  },
  "build": {
-    "on": [
-      {
-        "arg": "BUILD_BASE",
-        "module": "mesh-tools",
-        "artifact": "build"
-      },
-      {
-        "arg": "RUNTIME_BASE",
-        "module": "mesh-tools",
-        "artifact": "runtime"
-      }
-    ],
    "artifacts": [
      {
-        "name": "runtime",
-        "kind": "image",
-        "from": "Dockerfile"
+        "name": "code",
+        "kind": "bundle",
+        "language": "typescript",
+        "entrypoints": [
+          "index.js"
+        ],
+        "loads": [
+          "index.js"
+        ],
+        "env": {
+          "AUDIT_LOG": "${dir:trail}/audit.log"
+        }
      }
    ]
  },
@@ -33,29 +27,13 @@
    {
      "id": "state",
      "type": "directory",
-      "path": "/var/lib/audit-logger",
-      "mode": "0700"
+      "mode": "0700",
+      "place": "."
    },
    {
      "id": "trail",
      "type": "directory",
-      "path": "/var/lib/audit-logger/trail",
      "mode": "0700"
-    },
-    {
-      "id": "run",
-      "type": "container",
-      "name": "mesh-audit-logger",
-      "network": "host",
-      "volumes": [
-        "/var/lib/audit-logger/broker:/run/secrets/broker:ro",
-        "/var/lib/audit-logger/trail:/trail"
-      ],
-      "env": {
-        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "AUDIT_LOG": "/trail/audit.log"
-      },
-      "artifact": "runtime"
    }
  ],
  "capabilities": [
@@ -15,7 +15,7 @@ test("audit-logger records every event to the trail as one line each", async ()
  const path = join(dir, "audit.log");

  // The audit-logger's whole behaviour: consume everything, record it.
-  await on("**", async (event) => record(event, path));
+  await on("#", async (event) => record(event, path)); // the pattern index.ts subscribes

  process.env.MESH_MODULE = "umami";
  process.env.MESH_NODE = "anchor";
@@ -24,7 +24,9 @@ test("audit-logger records every event to the trail as one line each", async ()

  const lines = (await readFile(path, "utf8")).trim().split("\n").map((l) => JSON.parse(l));
  assert.equal(lines.length, 2);
-  assert.deepEqual(lines.map((l) => l.type), ["umami.site.created", "node.anchor.joined"]);
+  // A module names its events locally (design 29); the module is the `source`, which together with
+  // the type says whose event it was. This broker does no namespacing, so the type is as emitted.
+  assert.deepEqual(lines.map((l) => l.type), ["site.created", "node.anchor.joined"]);
  assert.equal(lines[0].source, "umami");
  assert.equal(lines[0].node, "anchor");
  assert.equal(lines[0].body.domain, "my-app");
@@ -1,24 +0,0 @@
-# baserow's runtime: the tool runtime, carrying this module's compiled code.
-#
-# **Built from this module's own directory and nothing else.** The sdk and the tool runtime are in
-# the base images, published like any other artifact — which is what makes this buildable by the
-# mesh from a repository and a path (novox/hq ADR 0069) rather than only on a workstation that
-# happens to have the siblings.
-#
-# Two bases, named rather than pinned (novox/hq issue 044): the image this is COMPILED in and the
-# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
-ARG BUILD_BASE
-ARG RUNTIME_BASE
-
-FROM ${BUILD_BASE} AS build
-WORKDIR /app/modules/baserow
-COPY . .
-RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts \
-      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
-
-FROM ${RUNTIME_BASE}
-COPY --from=build /app/modules/baserow/dist /app/modules/baserow/dist
-# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
-# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
-# the convention novox/hq issues 060/061 settled.
-ENV MESH_TOOL_MODULES=/app/modules/baserow/dist/tools/index.js
@@ -2,12 +2,15 @@
 // module's tools and anything else baserow-specific import it; nothing outside baserow does.
 //
 // Baserow authenticates a person with email + password, exchanged for a JWT at /api/user/token-auth/.
-// Those credentials are the mesh's own: a person signs up in Baserow (the standard image creates no
-// admin from env), and the credential is placed in the runtime config file the mesh mounts. Until
-// that happens fromEnv throws and the module simply exposes no tools — the same dormant-until-
-// configured shape gitea uses for its token.
+// The standard image creates no admin from env, so the account is one a person made in Baserow: its
+// password is the module's `admin` secret, accepted from the operator, and its email and the public
+// host Baserow answers to reach the runtime config file the mesh mounts (the email from the
+// assignment's settings). Until both are there fromEnv throws and the module exposes no tools — the
+// same dormant-until-configured shape gitea uses for its token.

 import { readFileSync } from "node:fs";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";

 export interface BaserowApplication {
  id: number;
@@ -68,35 +71,63 @@ export class BaserowClient {
    return h;
  }

-  /** Exchange email + password for a JWT, caching it for the client's lifetime. Handles both the
+  /**
+   * One HTTP exchange. Not `fetch`: Node's fetch drops a caller's Host header and sends the URL's
+   * own, and Baserow answers only the host of its BASEROW_PUBLIC_URL — any other Host is looked up
+   * as a published builder site and gets 404, `/api/_health/` included. A co-located caller reaching
+   * it by container name must present the public host, so the request is made with node:http, which
+   * sends the Host it is given.
+   */
+  private send(path: string, method: string, headers: Record<string, string>, body?: string): Promise<{ status: number; text: string }> {
+    const url = new URL(`${this.baseUrl}${path}`);
+    const request = url.protocol === "https:" ? httpsRequest : httpRequest;
+    // A length, never chunked: Baserow's server reads a chunked body as empty.
+    const sent = body === undefined ? headers : { ...headers, "Content-Length": String(Buffer.byteLength(body)) };
+    return new Promise((resolve, reject) => {
+      const req = request(url, { method, headers: sent }, (res) => {
+        let text = "";
+        res.setEncoding("utf8");
+        res.on("data", (chunk: string) => (text += chunk));
+        res.on("end", () => resolve({ status: res.statusCode ?? 0, text }));
+        res.on("error", reject);
+      });
+      req.on("error", reject);
+      if (body !== undefined) req.write(body);
+      req.end();
+    });
+  }
+
+  /** Exchange email + password for a JWT, caching it until Baserow refuses it. Handles both the
   *  older `{ token }` and the newer `{ access_token }` response shapes. */
  async authenticate(): Promise<string> {
    if (this.token) return this.token;
-    const res = await fetch(`${this.baseUrl}/api/user/token-auth/`, {
-      method: "POST",
-      headers: this.headers(),
-      body: JSON.stringify({ email: this.email, password: this.password }),
-    });
-    if (!res.ok) throw new Error(`baserow auth failed: ${res.status} ${await res.text()}`);
-    const data = (await res.json()) as { token?: string; access_token?: string };
+    const res = await this.send(
+      "/api/user/token-auth/",
+      "POST",
+      this.headers(),
+      JSON.stringify({ email: this.email, password: this.password }),
+    );
+    if (res.status < 200 || res.status >= 300) throw new Error(`baserow auth failed: ${res.status} ${res.text}`);
+    const data = JSON.parse(res.text) as { token?: string; access_token?: string };
    const token = data.access_token ?? data.token;
    if (!token) throw new Error("baserow auth returned no token");
    this.token = token;
    return token;
  }

-  private async authed<T>(path: string, options: RequestInit = {}): Promise<T> {
-    const token = await this.authenticate();
-    const res = await fetch(`${this.baseUrl}${path}`, {
-      ...options,
-      headers: this.headers({
-        Authorization: `JWT ${token}`,
-        ...(options.headers as Record<string, string> | undefined),
-      }),
-    });
-    if (!res.ok) throw new Error(`baserow ${path}: ${res.status} ${await res.text()}`);
-    const text = await res.text();
-    return (text ? JSON.parse(text) : null) as T;
+  /** An authenticated GET. A refused token is dropped and the call made once more with a fresh one:
+   *  Baserow's access tokens expire after minutes, and the runtime lives for weeks. */
+  private async authed<T>(path: string): Promise<T> {
+    for (let attempt = 0; ; attempt++) {
+      const token = await this.authenticate();
+      const res = await this.send(path, "GET", this.headers({ Authorization: `JWT ${token}` }));
+      if (res.status === 401 && attempt === 0) {
+        this.token = null;
+        continue;
+      }
+      if (res.status < 200 || res.status >= 300) throw new Error(`baserow ${path}: ${res.status} ${res.text}`);
+      return (res.text ? JSON.parse(res.text) : null) as T;
+    }
  }

  /** The applications (databases) the account can see, across all its workspaces. */
@@ -18,15 +18,14 @@
    }
  },
  "binds": {
-    "postgres-database": "/var/lib/baserow/database.json",
-    "route": "/var/lib/baserow/route.json"
+    "postgres-database": "${dir:state}/database.json",
+    "route": "${dir:state}/route.json"
  },
  "secrets": {
-    "postgres-database": "/var/lib/baserow/database.secret"
+    "postgres-database": "${dir:state}/database.secret"
  },
  "own-secrets": {
-    "secret-key": "/var/lib/baserow/secret-key.secret",
-    "broker": "/var/lib/mesh/baserow/broker"
+    "admin": "${dir:state}/admin.secret"
  },
  "listens": [
    {
@@ -34,35 +33,34 @@
      "port": 80,
      "protocol": "tcp",
      "from": "mesh",
-      "why": "the Baserow web UI and REST API; a public name is a route grant later"
+      "why": "the Baserow web UI and REST API, served by the image's own Caddy; a public name is the route's"
    }
  ],
  "resources": [
    {
      "id": "mesh-state",
      "type": "directory",
-      "path": "/var/lib/mesh/baserow",
-      "mode": "0700"
+      "mode": "0700",
+      "place": "mesh"
    },
    {
      "id": "state",
      "type": "directory",
-      "path": "/var/lib/baserow",
-      "mode": "0700"
+      "mode": "0700",
+      "place": "."
    },
    {
      "id": "data",
      "type": "directory",
-      "path": "/services/baserow/data",
      "mode": "0755",
      "owner": "9999:9999"
    },
    {
      "id": "server-env",
      "type": "file",
-      "path": "/var/lib/baserow/server.env",
+      "path": "${dir:state}/server.env",
      "mode": "0600",
-      "content": "DATABASE_HOST=${bound:postgres-database:at}\nDATABASE_PORT=${bound:postgres-database:port}\nDATABASE_NAME=${bound:postgres-database:as}\nDATABASE_USER=${bound:postgres-database:as}\nDATABASE_PASSWORD=${secret:postgres-database}\nSECRET_KEY=${secret:secret-key}\nBASEROW_PUBLIC_URL=http://localhost\n"
+      "content": "DATABASE_HOST=${bound:postgres-database:at}\nDATABASE_PORT=${bound:postgres-database:port}\nDATABASE_NAME=${bound:postgres-database:as}\nDATABASE_USER=${bound:postgres-database:as}\nDATABASE_PASSWORD_FILE=/run/secrets/database\nDISABLE_EMBEDDED_PSQL=true\nBASEROW_PUBLIC_URL=https://${bound:route:name}\n"
    },
    {
      "id": "net",
@@ -73,65 +71,44 @@
      "id": "server",
      "type": "container",
      "name": "baserow",
-      "image": "baserow/baserow@sha256:834424a10413798567f76428f255dc259445b7f8dcec56598c05b4073bb2a124",
+      "image": "baserow/baserow@sha256:263ea6c4b72c9eccabcd975ffe9fdebf23913a293a514bec6a3897a5e0a5a080",
      "network": "baserow",
      "env-file": [
-        "/var/lib/baserow/server.env"
+        "${dir:state}/server.env"
      ],
      "ports": [
        "80"
      ],
      "volumes": [
-        "/services/baserow/data:/baserow/data"
-      ],
-      "secrets-in-environment": "baserow reads DATABASE_PASSWORD and SECRET_KEY with os.getenv and has no _FILE twin (settings/base.py); not convertible"
+        "${dir:data}:/baserow/data",
+        "${dir:state}/database.secret:/run/secrets/database:ro"
+      ]
    },
    {
      "id": "runtime-config",
      "type": "file",
-      "path": "/var/lib/mesh/baserow/config.json",
+      "path": "${dir:mesh-state}/config.json",
      "mode": "0600",
-      "content": "{}\n",
+      "content": "{\n  \"password\": \"${secret:admin}\",\n  \"host\": \"${bound:route:name}\"\n}\n",
      "merge": "json"
-    },
-    {
-      "id": "runtime",
-      "type": "container",
-      "name": "mesh-baserow",
-      "network": "baserow",
-      "volumes": [
-        "/var/lib/mesh/baserow/broker:/run/secrets/broker:ro",
-        "/var/lib/mesh/baserow/config.json:/run/config/config.json:ro"
-      ],
-      "env": {
-        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_BASEROW_URL": "http://baserow:80",
-        "MESH_BASEROW_CONFIG_FILE": "/run/config/config.json"
-      },
-      "restart-on": [
-        "runtime-config"
-      ],
-      "artifact": "runtime"
    }
  ],
  "build": {
-    "on": [
-      {
-        "arg": "BUILD_BASE",
-        "module": "mesh-tools",
-        "artifact": "build"
-      },
-      {
-        "arg": "RUNTIME_BASE",
-        "module": "mesh-tools",
-        "artifact": "runtime"
-      }
-    ],
    "artifacts": [
      {
-        "name": "runtime",
-        "kind": "image",
-        "from": "Dockerfile"
+        "name": "tools",
+        "kind": "bundle",
+        "language": "typescript",
+        "entrypoints": [
+          "tools/index.js"
+        ],
+        "loads": [
+          "tools/index.js"
+        ],
+        "env": {
+          "MESH_BASEROW_URL": "http://127.0.0.1:${port:80}",
+          "MESH_BASEROW_CONFIG_FILE": "${dir:mesh-state}/config.json"
+        }
      }
    ]
  }
@@ -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
@@ -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];
-  }
-}
@@ -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");
@@ -1,141 +0,0 @@
-{
-  "module": "bazarr",
-  "version": "1",
-  "capabilities": [
-    "container-runtime"
-  ],
-  "emits": [
-    "subtitle.downloaded"
-  ],
-  "own-secrets": {
-    "broker": "/var/lib/mesh/bazarr/broker",
-    "api-key": "/var/lib/mesh/bazarr/api-key"
-  },
-  "listens": [
-    {
-      "name": "web",
-      "port": 6767,
-      "protocol": "tcp",
-      "from": "mesh",
-      "why": "managing subtitles"
-    }
-  ],
-  "accesses": [
-    {
-      "path": "/services/media/movies",
-      "mode": "read-write"
-    },
-    {
-      "path": "/services/media/series",
-      "mode": "read-write"
-    },
-    {
-      "path": "/services/media/anime",
-      "mode": "read-write"
-    },
-    {
-      "path": "/services/media/downloads",
-      "mode": "read"
-    }
-  ],
-  "resources": [
-    {
-      "id": "mesh-state",
-      "type": "directory",
-      "path": "/var/lib/mesh/bazarr",
-      "mode": "0700"
-    },
-    {
-      "id": "config",
-      "type": "directory",
-      "path": "/services/bazarr/config",
-      "mode": "0700",
-      "owner": "1000:1000"
-    },
-    {
-      "id": "server",
-      "type": "container",
-      "name": "bazarr",
-      "image": "lscr.io/linuxserver/bazarr@sha256:3a820372f19fcb2981ea19fe4b5382934d67414afaba974bce831ddda0a64a02",
-      "env": {
-        "PUID": "1000",
-        "PGID": "1000",
-        "TZ": "Etc/UTC"
-      },
-      "ports": [
-        "6767"
-      ],
-      "volumes": [
-        "/services/bazarr/config:/config",
-        "/services/media/movies:/movies",
-        "/services/media/series:/series",
-        "/services/media/anime:/anime",
-        "/services/media/downloads:/downloads"
-      ]
-    },
-    {
-      "id": "runtime-config",
-      "type": "file",
-      "path": "/var/lib/mesh/bazarr/config.json",
-      "mode": "0600",
-      "content": "{}\n",
-      "merge": "json"
-    },
-    {
-      "id": "runtime",
-      "type": "container",
-      "name": "mesh-bazarr",
-      "network": "host",
-      "volumes": [
-        "/var/lib/mesh/bazarr/broker:/run/secrets/broker:ro",
-        "/var/lib/mesh/bazarr/api-key:/run/secrets/api-key:ro",
-        "/var/lib/mesh/bazarr/config.json:/run/config/config.json:ro",
-        "/services/bazarr/config:/var/lib/bazarr/config:ro"
-      ],
-      "env": {
-        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_BAZARR_URL": "http://127.0.0.1:6767",
-        "MESH_BAZARR_API_KEY_FILE": "/run/secrets/api-key",
-        "MESH_BAZARR_CONFIG_FILE": "/run/config/config.json",
-        "MESH_BAZARR_CONFIG_DIR": "/var/lib/bazarr/config"
-      },
-      "restart-on": [
-        "runtime-config"
-      ],
-      "artifact": "runtime"
-    }
-  ],
-  "requires": [
-    "route"
-  ],
-  "contributes": {
-    "route": {
-      "label": "subs",
-      "endpoint": "web"
-    }
-  },
-  "binds": {
-    "route": "/var/lib/mesh/bazarr/route.json"
-  },
-  "build": {
-    "on": [
-      {
-        "arg": "BUILD_BASE",
-        "module": "mesh-tools",
-        "artifact": "build"
-      },
-      {
-        "arg": "RUNTIME_BASE",
-        "module": "mesh-tools",
-        "artifact": "runtime"
-      }
-    ],
-    "artifacts": [
-      {
-        "name": "runtime",
-        "kind": "image",
-        "from": "Dockerfile"
-      }
-    ]
-  }
-}
@@ -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"
-  }
-}
@@ -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 [];
-  }
-});
@@ -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
@@ -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]}`;
-}
@@ -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");
-}
@@ -1,118 +0,0 @@
-{
-  "module": "bookshelf",
-  "version": "1",
-  "slug": "books",
-  "capabilities": [
-    "container-runtime"
-  ],
-  "emits": [
-    "book.grabbed",
-    "download.completed"
-  ],
-  "consumes": [],
-  "own-secrets": {
-    "broker": "/var/lib/mesh/bookshelf/broker"
-  },
-  "listens": [
-    {
-      "name": "web",
-      "port": 8787,
-      "protocol": "tcp",
-      "from": "mesh",
-      "why": "managing the ebook/audiobook library"
-    }
-  ],
-  "accesses": [
-    {
-      "path": "/services/media/books",
-      "mode": "read-write"
-    },
-    {
-      "path": "/services/media/downloads",
-      "mode": "read-write"
-    }
-  ],
-  "resources": [
-    {
-      "id": "mesh-state",
-      "type": "directory",
-      "path": "/var/lib/mesh/bookshelf",
-      "mode": "0700"
-    },
-    {
-      "id": "config",
-      "type": "directory",
-      "path": "/services/bookshelf/config",
-      "mode": "0700",
-      "owner": "1000:1000"
-    },
-    {
-      "id": "server",
-      "type": "container",
-      "name": "bookshelf",
-      "image": "ghcr.io/pennydreadful/bookshelf@sha256:388eecc94362580eae31ee0a454be6af516f8a311f8432a521c202fb475f4359",
-      "env": {
-        "PUID": "1000",
-        "PGID": "1000",
-        "TZ": "Etc/UTC"
-      },
-      "ports": [
-        "8787"
-      ],
-      "volumes": [
-        "/services/bookshelf/config:/config",
-        "/services/media/books:/books",
-        "/services/media/downloads:/downloads"
-      ]
-    },
-    {
-      "id": "runtime",
-      "type": "container",
-      "name": "mesh-bookshelf",
-      "network": "host",
-      "volumes": [
-        "/var/lib/mesh/bookshelf/broker:/run/secrets/broker:ro",
-        "/services/bookshelf/config:/var/lib/bookshelf/config:ro"
-      ],
-      "env": {
-        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_BOOKSHELF_URL": "http://127.0.0.1:8787",
-        "MESH_BOOKSHELF_CONFIG_DIR": "/var/lib/bookshelf/config"
-      },
-      "artifact": "runtime"
-    }
-  ],
-  "requires": [
-    "route"
-  ],
-  "contributes": {
-    "route": {
-      "label": "books",
-      "endpoint": "web"
-    }
-  },
-  "binds": {
-    "route": "/var/lib/mesh/bookshelf/route.json"
-  },
-  "build": {
-    "on": [
-      {
-        "arg": "BUILD_BASE",
-        "module": "mesh-tools",
-        "artifact": "build"
-      },
-      {
-        "arg": "RUNTIME_BASE",
-        "module": "mesh-tools",
-        "artifact": "runtime"
-      }
-    ],
-    "artifacts": [
-      {
-        "name": "runtime",
-        "kind": "image",
-        "from": "Dockerfile"
-      }
-    ]
-  }
-}
@@ -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"
-  }
-}
@@ -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 [];
-  }
-});
@@ -1,6 +1,6 @@
 ARG GO_BASE
 ARG ALPINE_BASE
-# builder's own image: the build machine itself, compiled into a container.
+# build-agent's image: the build machine itself, compiled into a container (novox/hq ADR 0190).
 #
 # **The source is not vendored here.** builder's actual code — cmd/mesh-builder, internal/builder,
 # internal/catalogue — lives in the mesh-controller repository, the same control plane it is one
@@ -0,0 +1,15 @@
+# build-agent
+
+The mesh's build machine as a role every machine can hold (novox/hq ADR 0190). It holds the node seat
+`node-build-agent`: every holder pulls one build at a time from the role's one work queue when it is
+idle, so a tier of many images is built by as many machines as hold the seat and are online, and a
+machine that is off builds nothing and blocks nothing. The controller asks the role, never a machine;
+the outcome names the machine that built it.
+
+What a holding machine needs is what the builder always needed, said here once: a container runtime
+(the socket is mounted), the artifact store and the package registry as provisions, a workspace, and
+the bus credential. The code is `cmd/mesh-builder` in the mesh-controller repository, compiled from
+that repository's main (`build.artifacts[].context`); this module ships the packaging.
+
+Assign it to every machine with a container runtime. It replaces `builder`, the one-holder form of the
+same thing; retire that once this is assigned where it was.
@@ -1,13 +1,14 @@
 {
-  "module": "builder",
+  "module": "build-agent",
  "version": "1",
+  "slug": "agent",
  "capabilities": [
    "container-runtime"
  ],
  "claims": [
    {
-      "name": "mesh-build-machine",
-      "scope": "mesh"
+      "name": "node-build-agent",
+      "scope": "node"
    }
  ],
  "requires": [
@@ -15,49 +16,48 @@
    "npm-package-registry"
  ],
  "binds": {
-    "npm-package-registry": "/var/lib/mesh/builder/package-registry.json"
+    "npm-package-registry": "${dir:mesh-state}/package-registry.json"
  },
  "secrets": {
-    "npm-package-registry": "/var/lib/mesh/builder/package-registry.secret"
+    "npm-package-registry": "${dir:mesh-state}/package-registry.secret"
  },
  "own-secrets": {
-    "broker": "/var/lib/mesh/builder/broker"
+    "broker": "${dir:mesh-state}/broker"
  },
  "resources": [
    {
      "id": "mesh-state",
      "type": "directory",
-      "path": "/var/lib/mesh/builder",
-      "mode": "0700"
+      "mode": "0700",
+      "place": "mesh"
    },
    {
      "id": "workspace",
      "type": "directory",
-      "path": "/var/lib/builder/workspace",
      "mode": "0700"
    },
    {
-      "id": "builder-env",
+      "id": "agent-env",
      "type": "file",
-      "path": "/var/lib/mesh/builder/builder.env",
+      "path": "${dir:mesh-state}/build-agent.env",
      "mode": "0600",
-      "content": "MESH_BROKER_FILE=/run/mesh/broker\nMESH_NODE=${machine:name}\nMESH_REGISTRY=${bound:artifact-store:at}:${bound:artifact-store:port}\nMESH_PACKAGE_BINDING=/run/mesh/package-registry.json\nMESH_NPM_TOKEN_FILE=/run/mesh/package-registry.secret\nMESH_WORKSPACE=/var/lib/builder/workspace\n"
+      "content": "MESH_BROKER_FILE=/run/mesh/broker\nMESH_NODE=${machine:name}\nMESH_REGISTRY=${bound:artifact-store:at}:${bound:artifact-store:port}\nMESH_PACKAGE_BINDING=/run/mesh/package-registry.json\nMESH_NPM_TOKEN_FILE=/run/mesh/package-registry.secret\nMESH_WORKSPACE=${dir:workspace}\n"
    },
    {
      "id": "server",
      "type": "container",
-      "name": "mesh-builder",
+      "name": "mesh-build-agent",
      "artifact": "server",
      "env-file": [
-        "/var/lib/mesh/builder/builder.env"
+        "${dir:mesh-state}/build-agent.env"
      ],
      "volumes": [
-        "/var/lib/mesh/builder:/run/mesh:ro",
-        "/var/lib/builder/workspace:/var/lib/builder/workspace",
+        "${dir:mesh-state}:/run/mesh:ro",
+        "${dir:workspace}:${dir:workspace}",
        "/var/run/docker.sock:/var/run/docker.sock"
      ],
      "restart-on": [
-        "builder-env"
+        "agent-env"
      ],
      "network": "host"
    }
@@ -69,7 +69,8 @@
        "kind": "image",
        "from": "Dockerfile",
        "context": {
-          "repository": "https://git.novox.be/novox/mesh-controller.git",
+          "seat": "git",
+          "repository": "novox/mesh-controller",
          "ref": "main"
        }
      }
@@ -0,0 +1,74 @@
+# claude-code
+
+The operator's agent on a machine (novox/hq design 36): its package, its machine-wide managed
+configuration, and the consumer side of the Anthropic licence manager (design 39, ADR 0183).
+
+## What it owns
+
+Two directories, declared, so the mesh refuses a second module owning either:
+
+- `/etc/claude-code`, the agent's machine-wide managed directory, root's, `0755`.
+- `~/.claude` under the operator account's home, the operator's, `0700`. The module owns the directory —
+  that it exists, who owns it, its mode — and of what is inside only what it writes. Everything else
+  in it (memory, history, projects, local settings, a person's own rules and skills) is the person's
+  and is never read or written (hq ADR 0182). Unassigned, the module leaves the directory: the host
+  removes a directory only when it is empty.
+
+## What it writes
+
+Under the agent's managed directory, `/etc/claude-code`, owned whole by this module and rewritten
+whenever the node's tool runtime collects the module's tools:
+
+| file | holds |
+|---|---|
+| `managed-mcp.json` | the tool servers every session loads: the mesh's console as `mesh`, and the servers set in this module's `mcp_servers` setting. **Exclusive**: a server not listed here does not load — not one added with `claude mcp add`, not a project's `.mcp.json`, not a plugin's |
+| `managed-settings.json` | the repositories' attribution convention, the claude.ai connectors kept beside the managed servers, and the key-helper while the node holds an API-key licence |
+| `CLAUDE.md` | how a session on this mesh works, this node's name and role, the conventions |
+
+Under the operator's home, only `~/.claude/.credentials.json`, and only when the licence manager hands
+this node a subscription token. Nothing else under the home is read or written.
+
+## Over NATS
+
+Everything between this module and the rest of the mesh is NATS, in three kinds: an **event** says that
+something happened and carries no secret, because a stream keeps it; a **request** carries a token,
+because nothing keeps it (hq design 32 §10); and **state** is the current value of something every node
+must see, a node that joins later included — kept, so it carries no secret either (hq ADR 0201).
+
+| what | how |
+|---|---|
+| the licence manager rotated a licence, or switched this node | its `licence.rotated` / `licence.switched` event; this module then asks `anthropic-licence-manager.current` for its token, sealed to the key it sends |
+| this node starts | it asks `current` once, so a node that was off catches up |
+| a person ran `/login` here | the credentials file gains a refresh token this module never writes; it asks `anthropic-licence-manager.adopt` at once with the grant sealed to the manager's key — the one time a refresh token travels, because the login made the manager's stale |
+| an MCP server registered through this module | a key in the module's `servers` state — `all.<server>` for every node, `<node>.<server>` for one; every node watches it and renders what applies to it, a node's own entry over the one for every node. A node that joins later, or was off, reads the whole current set at start; unregistering is a delete. An entry with a secret in its `env` or `headers` is refused by the runtime |
+
+## Tools
+
+`claude_code_status`, `claude_code_render`, `claude_code_pull`, `claude_code_mcp_list`,
+`claude_code_mcp_register` (this node by default; `nodes: "all"` or a list for more — called for this
+node alone, its answer names the other nodes running claude-code), `claude_code_mcp_unregister`.
+
+## Settings
+
+Per node or for the whole mesh, through `mesh-controller.settings module=claude-code`:
+
+- `role` — what this node is, in a few words; shown to every session.
+- `mcp_servers` — extra tool servers, set by the operator for the mesh or a node, beside the ones
+  registered through the tools; keyed by name, in the vendor's `.mcp.json` entry shape
+  (`{"type":"http","url":…}` or `{"type":"stdio","command":…,"args":[…]}`). The name `mesh` is the
+  module's own and cannot be set. Put a person's own servers here, or they stop loading.
+
+## On a machine that carried the predecessor
+
+Remove these by hand, once; the mesh removes nothing it did not make (ADR 0182):
+
+- `~/.claude/CLAUDE.md`
+- `~/.claude/rules/00-hal-mesh.md`, `~/.claude/rules/conventions.md`
+- `~/.claude/skills/cleanup/`, `~/.claude/skills/hal-switch-license/`
+- the hand-made console entry in `~/.claude.json` under `mcpServers` — it is ignored now anyway
+
+## Escalation
+
+Writing `/etc/claude-code` needs root. The runtime runs as the operator account, and the module uses
+that account's passwordless `sudo`; on a machine without it, `claude_code_render` says so and nothing
+is written.
@@ -0,0 +1,112 @@
+// The agent's credentials file, and whether an offered grant may replace what it holds (novox/hq
+// ADR 0183, design 36 §5). Pure where it decides, so the rules are tested without a file.
+//
+// The file is the vendor's: `{ claudeAiOauth: { accessToken, expiresAt, refreshTokenExpiresAt?,
+// scopes?, subscriptionType?, rateLimitTier? }, ... }`. A node never holds a refresh token, so the
+// one this module writes never carries one, and a full grant a login left behind is stripped the
+// moment the manager hands the node its own.
+//
+// The lineage rule is the predecessor's, with the incidents that earned it: a rotation of the same
+// licence is applied only if newer; a grant re-issued by a login is adopted whatever its expiry; a
+// switch to another licence is applied regardless, because across licences the expiries are
+// unrelated numbers.
+
+import { readFileSync, renameSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+export interface Grant {
+  readonly accessToken: string;
+  readonly expiresAt: number;
+  readonly refreshTokenExpiresAt?: number | null;
+  readonly scopes?: readonly string[] | null;
+  readonly subscriptionType?: string | null;
+  readonly rateLimitTier?: string | null;
+}
+
+export type ApplySource = "rotation" | "switch";
+
+export type ApplyDecision =
+  | { apply: true; reissued?: boolean }
+  | { apply: false; reason: "already-current" }
+  | { apply: false; reason: "not-newer"; localExpiresAt: number };
+
+/** Two refresh-token expiries within a day are one lineage; a login starts a fresh window weeks away. */
+export const GENERATION_TOLERANCE_MS = 24 * 60 * 60 * 1000;
+
+export function sameGeneration(a?: number | null, b?: number | null): boolean {
+  if (a == null || b == null) return true;
+  return Math.abs(Number(a) - Number(b)) <= GENERATION_TOLERANCE_MS;
+}
+
+export function decideApply(local: Grant | null | undefined, offered: Grant, source: ApplySource): ApplyDecision {
+  if (!local?.accessToken) return { apply: true };
+  if (local.accessToken === offered.accessToken) return { apply: false, reason: "already-current" };
+  const reissued = !sameGeneration(local.refreshTokenExpiresAt, offered.refreshTokenExpiresAt);
+  if (source === "rotation" && !reissued && Number(local.expiresAt) >= Number(offered.expiresAt)) {
+    return { apply: false, reason: "not-newer", localExpiresAt: Number(local.expiresAt) };
+  }
+  return reissued ? { apply: true, reissued: true } : { apply: true };
+}
+
+type Oauth = Record<string, unknown> & { accessToken?: string; refreshToken?: string; expiresAt?: number };
+type Credentials = Record<string, unknown> & { claudeAiOauth?: Oauth };
+
+export function readCredentials(path: string): Credentials | null {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as Credentials;
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The grant the file holds, or null. */
+export function grantOf(creds: Credentials | null): Grant | null {
+  const o = creds?.claudeAiOauth;
+  if (!o?.accessToken) return null;
+  return {
+    accessToken: o.accessToken,
+    expiresAt: Number(o.expiresAt ?? 0),
+    refreshTokenExpiresAt: o.refreshTokenExpiresAt == null ? null : Number(o.refreshTokenExpiresAt),
+  };
+}
+
+/** Does the file hold a full grant — a refresh token this module never writes, so a person's login? */
+export function holdsLogin(creds: Credentials | null): boolean {
+  return typeof creds?.claudeAiOauth?.refreshToken === "string" && creds.claudeAiOauth.refreshToken.length > 0;
+}
+
+/**
+ * The handed grant laid over what is there — a rotation of the licence the node already holds — or,
+ * for a switch, in place of it: the old licence's grant goes whole, scopes and subscription included,
+ * and only keys outside the grant (another kind of credential the vendor keeps in the file) stay.
+ * Either way, no refresh token survives.
+ */
+export function replacedBy(local: Credentials | null, grant: Grant): Credentials {
+  const next: Credentials = { ...(local ?? {}) };
+  delete next.claudeAiOauth;
+  return withGrant(next, grant);
+}
+
+/** Overlay the handed grant on what is there, and delete any refresh token. */
+export function withGrant(local: Credentials | null, grant: Grant): Credentials {
+  const next: Credentials = { ...(local ?? {}) };
+  const oauth: Oauth = { ...(local?.claudeAiOauth ?? {}) };
+  oauth.accessToken = grant.accessToken;
+  oauth.expiresAt = grant.expiresAt;
+  for (const k of ["refreshTokenExpiresAt", "scopes", "subscriptionType", "rateLimitTier"] as const) {
+    const v = grant[k];
+    if (v != null) oauth[k] = v as unknown;
+  }
+  delete oauth.refreshToken;
+  next.claudeAiOauth = oauth;
+  return next;
+}
+
+/** Write atomically at 0600: a partial credentials file must never be read as a whole one. */
+export function writeCredentials(path: string, creds: Credentials): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const tmp = `${path}.mesh-tmp`;
+  writeFileSync(tmp, JSON.stringify(creds, null, 2) + "\n", { mode: 0o600 });
+  renameSync(tmp, path);
+}
@@ -0,0 +1,50 @@
+// Which account the agent is logged in as (novox/hq ADR 0183): not in the token, but in the agent's
+// own state file beside the home, `~/.claude.json` → `oauthAccount`. Read to attribute a login; written,
+// three keys and nothing else, when a licence is switched, so the file Claude Code shows the account from
+// names the account whose token it now holds (as the predecessor learned: two files that disagree make
+// a later login look like the wrong account).
+
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+
+export interface Identity {
+  readonly accountUuid: string;
+  readonly emailAddress?: string;
+  readonly organizationUuid?: string;
+}
+
+export function readIdentity(stateFile: string): Identity | null {
+  try {
+    const raw = JSON.parse(readFileSync(stateFile, "utf8")) as { oauthAccount?: Record<string, unknown> };
+    const a = raw.oauthAccount;
+    if (!a || typeof a.accountUuid !== "string") return null;
+    return {
+      accountUuid: a.accountUuid,
+      emailAddress: typeof a.emailAddress === "string" ? a.emailAddress : undefined,
+      organizationUuid: typeof a.organizationUuid === "string" ? a.organizationUuid : undefined,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Point the state file's account at `id`, keeping every other key as found. Returns whether the file
+ * changed; a file that cannot be read as an object is left alone rather than replaced.
+ */
+export function writeIdentity(stateFile: string, id: Identity): boolean {
+  let raw: Record<string, unknown>;
+  try {
+    raw = JSON.parse(readFileSync(stateFile, "utf8")) as Record<string, unknown>;
+    if (!raw || typeof raw !== "object") return false;
+  } catch {
+    raw = {};
+  }
+  const current = (raw.oauthAccount ?? {}) as Record<string, unknown>;
+  if (current.accountUuid === id.accountUuid && current.emailAddress === id.emailAddress
+      && current.organizationUuid === id.organizationUuid) return false;
+  raw.oauthAccount = { ...current, accountUuid: id.accountUuid, emailAddress: id.emailAddress, organizationUuid: id.organizationUuid };
+  const tmp = `${stateFile}.mesh-tmp`;
+  writeFileSync(tmp, JSON.stringify(raw, null, 2), { mode: 0o600 });
+  renameSync(tmp, stateFile);
+  return true;
+}
@@ -0,0 +1,90 @@
+{
+  "module": "claude-code",
+  "version": "1",
+  "slug": "agent",
+  "capabilities": [
+    "package-manager"
+  ],
+  "requires": [
+    "mcp-endpoint"
+  ],
+  "binds": {
+    "mcp-endpoint": "${dir:state}/mcp-endpoint.json"
+  },
+  "consumes": [
+    "claude-licence-manager.licence.rotated",
+    "claude-licence-manager.licence.switched"
+  ],
+  "state": [
+    "servers"
+  ],
+  "tools": [
+    "claude_code_status",
+    "claude_code_render",
+    "claude_code_pull",
+    "claude_code_mcp_list",
+    "claude_code_mcp_register",
+    "claude_code_mcp_unregister"
+  ],
+  "resources": [
+    {
+      "id": "package",
+      "type": "package",
+      "package": "claude-code"
+    },
+    {
+      "id": "managed",
+      "type": "directory",
+      "path": "/etc/claude-code",
+      "mode": "0755"
+    },
+    {
+      "id": "agent-home",
+      "type": "directory",
+      "path": "${machine:account-home}/.claude",
+      "mode": "0700",
+      "owner": "${machine:account}"
+    },
+    {
+      "id": "state",
+      "type": "directory",
+      "mode": "0700",
+      "owner": "${machine:account}",
+      "place": "."
+    },
+    {
+      "id": "facts",
+      "type": "file",
+      "path": "${dir:state}/facts.json",
+      "mode": "0600",
+      "owner": "${machine:account}",
+      "content": "{\n  \"node\": \"${machine:name}\",\n  \"console\": \"http://127.0.0.1:${bound:mcp-endpoint:port}/mcp\"\n}\n"
+    },
+    {
+      "id": "settings",
+      "type": "file",
+      "path": "${dir:state}/settings.json",
+      "mode": "0600",
+      "owner": "${machine:account}",
+      "merge": "json",
+      "content": "{\n  \"role\": \"\",\n  \"mcp_servers\": {}\n}\n"
+    }
+  ],
+  "build": {
+    "artifacts": [
+      {
+        "name": "tools",
+        "kind": "bundle",
+        "language": "typescript",
+        "entrypoints": [
+          "tools/index.js"
+        ],
+        "env": {
+          "MESH_CLAUDE_CODE_STATE": "${dir:state}",
+          "MESH_CLAUDE_CODE_FACTS": "${dir:state}/facts.json",
+          "MESH_CLAUDE_CODE_SETTINGS": "${dir:state}/settings.json"
+        }
+      }
+    ]
+  }
+}
@@ -0,0 +1,271 @@
+// What claude-code does on a node, written against two things it is handed — a way to ask a tool on the
+// bus and a way to emit an event — so every path is tested without a bus (novox/hq design 36 §4–§5,
+// ADR 0183, ADR 0198).
+//
+// **Over NATS, in two kinds** (design 32 §10): an event says that something happened and carries no
+// secret, because a stream keeps it; a token travels on a request, which nothing keeps. So:
+//   - the licence manager's `licence.rotated` and `licence.switched` events tell this module to ask the
+//     seat for its current token, sealed to the key it sends with the request;
+//   - a login a person made here — a refresh token this module never writes — is offered to the seat at
+//     once, sealed to the seat's key: the one moment a refresh token travels, because the login made the
+//     manager's stale;
+//   - an MCP server registered through this module is **state, not an event** (novox/hq ADR 0201): one
+//     key per server in the module's `servers` bucket — `all.<server>` for every node, `<node>.<server>`
+//     for one — which every node watches. A node that joins later, or was off, reads the whole current set
+//     at start; unregistering is a delete. A secret never goes in an entry: the runtime refuses one.
+
+import { chmodSync, existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { render, entryProblem, MANAGED_DIR, type Binding, type Facts, type Settings, type Servers } from "./render.js";
+import { generateKeyPair, open, seal, type SealedBox } from "./seal.js";
+import { decideApply, grantOf, holdsLogin, readCredentials, replacedBy, withGrant, writeCredentials, type Grant } from "./grant.js";
+import { readIdentity, writeIdentity, type Identity } from "./identity.js";
+
+export const SEAT = "anthropic-licence-manager";
+
+export interface Paths {
+  state: string;
+  facts: string;
+  settings: string;
+  home: string;
+  node: string;
+}
+
+/** A tool on the bus: its address and arguments in, its JSON answer out. */
+export type Ask = (address: string, args: Record<string, unknown>) => Promise<unknown>;
+/** An event of this module's, by its local name. */
+export type Emit = (type: string, body: unknown) => Promise<void>;
+/** Write one managed file; answers what happened. */
+export type WriteManaged = (name: string, content: string) => string;
+
+export const readJson = <T>(p: string, fallback: T): T => {
+  try {
+    return JSON.parse(readFileSync(p, "utf8")) as T;
+  } catch {
+    return fallback;
+  }
+};
+
+const credentialsPath = (p: Paths) => join(p.home, ".claude", ".credentials.json");
+const accountPath = (p: Paths) => join(p.home, ".claude.json");
+const bindingPath = (p: Paths) => join(p.state, "licence.json");
+const apiKeyPath = (p: Paths) => join(p.state, "api-key");
+export const helperPath = (p: Paths) => join(p.state, "api-key-helper");
+const keyPath = (p: Paths) => join(p.state, "key.pem");
+const pubPath = (p: Paths) => join(p.state, "key.pub.pem");
+const registryPath = (p: Paths) => join(p.state, "mcp-servers.json");
+
+export function keypair(p: Paths): { publicKey: string; privateKey: string } {
+  if (!existsSync(keyPath(p))) {
+    const k = generateKeyPair();
+    writeFileSync(keyPath(p), k.privateKey, { mode: 0o600 });
+    writeFileSync(pubPath(p), k.publicKey, { mode: 0o644 });
+  }
+  return { privateKey: readFileSync(keyPath(p), "utf8"), publicKey: readFileSync(pubPath(p), "utf8") };
+}
+
+export function registered(p: Paths): Servers {
+  return readJson<Servers>(registryPath(p), {});
+}
+
+export function renderNow(p: Paths, write: WriteManaged): string[] {
+  const facts = readJson<Facts | null>(p.facts, null);
+  if (!facts?.console) throw new Error(`the mesh has not rendered ${p.facts} yet; nothing to write`);
+  const files = render(facts, readJson<Settings>(p.settings, {}), readJson<Binding | null>(bindingPath(p), null),
+    helperPath(p), registered(p));
+  return Object.entries(files).map(([name, content]) => write(name, content));
+}
+
+// ---- the licence ----------------------------------------------------------------------------------
+
+/** What the seat answers to `current`: the licence this node is bound to and its token, sealed. */
+export interface Current {
+  licence: string;
+  kind: "subscription" | "api-key";
+  sealed: SealedBox;
+  identity?: Identity | null;
+}
+
+/** Ask the seat for this node's current token and apply it. */
+export async function pull(p: Paths, ask: Ask, write: WriteManaged): Promise<Record<string, unknown>> {
+  const answer = (await ask(`${SEAT}.current`, { node: p.node, public_key: keypair(p).publicKey })) as Current | null;
+  if (!answer?.sealed) return { applied: false, reason: "the seat holds no licence for this node" };
+  return apply(p, answer, write);
+}
+
+/** Apply what the seat handed over. A switch replaces the grant whole and cleans up after the old licence. */
+export function apply(p: Paths, handed: Current, write: WriteManaged): Record<string, unknown> {
+  const plain = open(handed.sealed, keypair(p).privateKey);
+  const previous = readJson<Binding | null>(bindingPath(p), null);
+  const switched = previous?.licence !== handed.licence;
+  let outcome: Record<string, unknown> = { applied: true, licence: handed.licence, kind: handed.kind, switched };
+  if (handed.kind === "api-key") {
+    writeFileSync(apiKeyPath(p), plain.trim() + "\n", { mode: 0o600 });
+    writeFileSync(helperPath(p), `#!/bin/sh\nexec cat '${apiKeyPath(p)}'\n`, { mode: 0o700 });
+    chmodSync(helperPath(p), 0o700);
+  } else {
+    const grant = JSON.parse(plain) as Grant;
+    const local = readCredentials(credentialsPath(p));
+    const d = decideApply(grantOf(local), grant, switched ? "switch" : "rotation");
+    if (d.apply) writeCredentials(credentialsPath(p), switched ? replacedBy(local, grant) : withGrant(local, grant));
+    else outcome = { applied: false, licence: handed.licence, reason: "reason" in d ? d.reason : undefined }; // narrowed by hand: the build compiles without strict
+    // Away from the API key: it goes, with its helper.
+    rmSync(apiKeyPath(p), { force: true });
+    rmSync(helperPath(p), { force: true });
+  }
+  if (switched && handed.identity?.accountUuid) {
+    outcome.account = writeIdentity(accountPath(p), handed.identity) ? "updated" : "unchanged";
+  }
+  writeFileSync(bindingPath(p), JSON.stringify({ licence: handed.licence, kind: handed.kind }) + "\n", { mode: 0o600 });
+  try {
+    outcome.rendered = renderNow(p, write); // the key-helper comes or goes with the licence's kind
+  } catch (err) {
+    outcome.rendered = { failed: err instanceof Error ? err.message : String(err) };
+  }
+  return outcome;
+}
+
+/** A licence event from the manager: is it for this node? */
+export function concerns(p: Paths, type: string, body: { licence?: string; node?: string }): boolean {
+  if (type.endsWith("licence.switched")) return body.node === p.node;
+  if (type.endsWith("licence.rotated")) return body.licence === readJson<Binding | null>(bindingPath(p), null)?.licence;
+  return false;
+}
+
+/** A refresh token in the credentials file is a login: this module never writes one. Offer it to the seat. */
+export async function offerLogin(p: Paths, ask: Ask): Promise<Record<string, unknown> | null> {
+  const creds = readCredentials(credentialsPath(p));
+  if (!holdsLogin(creds)) return null;
+  const key = (await ask(`${SEAT}.public_key`, {})) as { public_key?: string } | null;
+  if (!key?.public_key) throw new Error("the licence manager did not say what key to seal a login to");
+  return (await ask(`${SEAT}.adopt`, {
+    node: p.node,
+    identity: readIdentity(accountPath(p)),
+    sealed: seal(JSON.stringify(creds!.claudeAiOauth), key.public_key),
+  })) as Record<string, unknown>;
+}
+
+// ---- MCP servers ----------------------------------------------------------------------------------
+
+export interface Registration {
+  name: string;
+  entry?: Record<string, unknown>;
+  /** Which nodes: this one (absent), every node running the module ("all"), or a list. */
+  nodes?: "all" | string[];
+}
+
+/** The `servers` state, as this module reaches it through the runtime (`state("servers")` in the SDK). */
+export interface ServerState {
+  put(key: string, value: Record<string, unknown>): Promise<number>;
+  delete(key: string): Promise<void>;
+  keys(): Promise<string[]>;
+}
+
+/** One change to the `servers` state, as a watch hands it over. */
+export interface ServerChange {
+  key: string;
+  op: "put" | "delete";
+  value?: Record<string, unknown>;
+}
+
+/** The key a registration lives at: `all.<server>` for every node, `<node>.<server>` for one. */
+export const keyOf = (scope: string, name: string) => `${scope}.${name}`;
+
+/**
+ * What this node takes from the `servers` state: the entries for every node and for this one, by key —
+ * kept in memory from the watch, and written through to the module's own file whenever what applies here
+ * changes, so the managed directory can be rendered without the bus.
+ */
+export class ServerView {
+  private readonly entries = new Map<string, Record<string, unknown>>();
+  constructor(private readonly p: Paths) {}
+
+  /** Take one change; answers whether what applies to this node changed. */
+  take(c: ServerChange): boolean {
+    const dot = c.key.indexOf(".");
+    const scope = c.key.slice(0, dot), name = c.key.slice(dot + 1);
+    if (dot <= 0 || (scope !== "all" && scope !== this.p.node)) return false;
+    if (c.op === "put" && c.value && entryProblem(name, c.value) === null) this.entries.set(c.key, c.value);
+    else this.entries.delete(c.key);
+    return this.writeThrough();
+  }
+
+  /** What applies here: every node's entries, with this node's own laid over them by server name. */
+  effective(): Servers {
+    const out: Record<string, Record<string, unknown>> = {};
+    for (const scope of ["all", this.p.node]) {
+      for (const [key, entry] of [...this.entries].sort(([a], [b]) => a.localeCompare(b))) {
+        if (key.startsWith(scope + ".")) out[key.slice(scope.length + 1)] = entry;
+      }
+    }
+    return out;
+  }
+
+  private writeThrough(): boolean {
+    const now = JSON.stringify(this.effective(), null, 2) + "\n";
+    let before = "";
+    try {
+      before = readFileSync(registryPath(this.p), "utf8");
+    } catch {
+      /* none yet */
+    }
+    if (now === before) return false;
+    writeFileSync(registryPath(this.p), now, { mode: 0o600 });
+    return true;
+  }
+}
+
+/** A change from the watch: take it, and render when what applies here changed. */
+export function onServerChange(view: ServerView, c: ServerChange, p: Paths, write: WriteManaged): string | null {
+  if (!view.take(c)) return null;
+  renderNow(p, write);
+  return `${c.op === "put" ? "registered" : "unregistered"} ${c.key}`;
+}
+
+const scopesOf = (p: Paths, nodes: Registration["nodes"]): string[] =>
+  nodes === undefined ? [p.node] : nodes === "all" ? ["all"] : nodes;
+
+/**
+ * Register (or with no entry, unregister) a server: a put (or delete) per scope in the `servers` state.
+ * Taken into this node's view at once, so the answer says what it did here; every other node takes it
+ * from its watch, and a node that joins later from the current state.
+ */
+export async function registerServer(p: Paths, r: Registration, servers: ServerState, view: ServerView,
+                                     write: WriteManaged, others: () => Promise<string[]>): Promise<Record<string, unknown>> {
+  if (r.entry) {
+    const problem = entryProblem(r.name, r.entry);
+    if (problem) return { registered: false, reason: problem };
+  }
+  const scopes = scopesOf(p, r.nodes);
+  // Compared before and after rather than read from take(): this node's own watch may hand the view the
+  // same change first, and then take() here finds nothing new although this call made it.
+  const before = JSON.stringify(view.effective());
+  for (const scope of scopes) {
+    const key = keyOf(scope, r.name);
+    if (r.entry) await servers.put(key, r.entry);
+    else await servers.delete(key);
+    view.take({ key, op: r.entry ? "put" : "delete", value: r.entry });
+  }
+  const changedHere = JSON.stringify(view.effective()) !== before;
+  const here = scopes.includes("all") || scopes.includes(p.node);
+  const answer: Record<string, unknown> = {
+    [r.entry ? "registered" : "unregistered"]: r.name,
+    on: r.nodes === undefined ? [p.node] : r.nodes,
+    here: here ? (changedHere ? "changed" : "already so") : "not this node",
+    rendered: changedHere ? renderNow(p, write) : [],
+  };
+  if (!r.entry && view.effective()[r.name]) {
+    answer.still = `${r.name} still applies here from another registration (for every node, or for this one); unregister that too`;
+  }
+  if (r.nodes === undefined) {
+    // The question the operator wanted asked: here only, or more?
+    const elsewhere = (await others().catch(() => [] as string[])).filter((n) => n !== p.node);
+    answer.also = elsewhere.length
+      ? `claude-code also runs on ${elsewhere.join(", ")}. To ${r.entry ? "register" : "unregister"} it there too, call again with nodes: "all" or a list of those nodes.`
+      : `To do the same on every node running claude-code, call again with nodes: "all".`;
+  }
+  return answer;
+}
+
+export { MANAGED_DIR };
@@ -0,0 +1,18 @@
+{
+  "name": "@novox/module-claude-code",
+  "version": "0.1.0",
+  "description": "claude-code — the operator's agent on a machine: its managed configuration, and the consumer side of the Anthropic licence manager (novox/hq design 36).",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "build": "tsc seal.ts grant.ts identity.ts render.ts node.ts tools/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --rootDir . --outDir dist",
+    "test": "npm run build && node --test --experimental-strip-types 'test/*.test.ts'"
+  },
+  "dependencies": {
+    "@novox/mesh-sdk": "^0.1.7"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}
@@ -0,0 +1,135 @@
+// What the module writes into the agent's machine-wide managed directory (novox/hq design 36 §1–§4).
+// Pure: composed from the facts the mesh rendered, the settings the operator set and the licence the
+// node holds, so what lands under /etc is tested without a machine.
+//
+// Three files, owned whole by this module:
+//   managed-mcp.json        the tool servers every session loads: the mesh's console as `mesh`, and the
+//                           servers the operator declared for the mesh or this node. Exclusive by the
+//                           vendor's rule — a server not listed here does not load — which is why the
+//                           list is the module's settings and nothing else (operator's choice, 2026-10-03).
+//   managed-settings.json   the mesh's keys only: the repositories' attribution convention, the
+//                           claude.ai connectors kept beside the managed servers, and — for an API-key
+//                           licence only — the key-helper. A person's preferences are theirs.
+//   CLAUDE.md               how a session on this mesh works, who this node is, the conventions.
+
+export const MANAGED_DIR = "/etc/claude-code";
+
+export interface Facts {
+  readonly node: string;
+  readonly console: string;
+}
+
+export interface Settings {
+  readonly role?: string;
+  /** Extra tool servers, in the vendor's `.mcp.json` entry shape, keyed by name. */
+  readonly mcp_servers?: Readonly<Record<string, Record<string, unknown>>>;
+}
+
+export interface Binding {
+  readonly licence: string;
+  readonly kind: "subscription" | "api-key";
+}
+
+export interface Rendered {
+  readonly [file: string]: string;
+}
+
+const MESH_ENTRY = "mesh";
+
+export type Servers = Readonly<Record<string, Record<string, unknown>>>;
+
+/** Whether an entry is one the vendor's managed file takes: a name of letters, digits, `-` and `_`, and
+ *  an http/sse server with a url or a stdio server with a command. Returns why not, or null. */
+export function entryProblem(name: string, entry: Record<string, unknown>): string | null {
+  if (!/^[A-Za-z0-9_-]+$/.test(name)) return `"${name}" is not a name the agent takes: letters, digits, - and _`;
+  if (name === MESH_ENTRY) return `"${MESH_ENTRY}" is the mesh's own entry`;
+  const type = entry?.type ?? "stdio";
+  if (type === "http" || type === "sse" || type === "streamable-http") {
+    return typeof entry.url === "string" && entry.url ? null : `an ${type} server needs a url`;
+  }
+  if (type === "stdio") return typeof entry.command === "string" && entry.command ? null : "a stdio server needs a command";
+  return `"${String(type)}" is not a server type the agent knows (http, sse, stdio)`;
+}
+
+/**
+ * Compose the three files. `registered` is the module's own list on this node — what was registered
+ * through its tools — laid over the servers the operator set in its settings.
+ */
+export function render(facts: Facts, settings: Settings, binding: Binding | null, helperPath: string,
+                       registered: Servers = {}): Rendered {
+  const servers: Record<string, unknown> = {};
+  for (const [name, entry] of Object.entries({ ...(settings.mcp_servers ?? {}), ...registered })) {
+    if (entryProblem(name, entry) !== null) continue; // the mesh's own entry, or one the agent would refuse
+    servers[name] = entry;
+  }
+  servers[MESH_ENTRY] = { type: "http", url: facts.console };
+
+  const managed: Record<string, unknown> = {
+    attribution: { commit: "", pr: "" },
+    allowAllClaudeAiMcps: true,
+  };
+  if (binding?.kind === "api-key") managed.apiKeyHelper = helperPath;
+
+  return {
+    "managed-mcp.json": json({ mcpServers: sortKeys(servers) }),
+    "managed-settings.json": json(managed),
+    "CLAUDE.md": instructions(facts, settings),
+  };
+}
+
+function json(v: unknown): string {
+  return JSON.stringify(v, null, 2) + "\n";
+}
+
+function sortKeys(o: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.keys(o).sort().map((k) => [k, o[k]]));
+}
+
+export function instructions(facts: Facts, settings: Settings): string {
+  const role = settings.role?.trim() ? settings.role.trim() : "not stated — set it in this module's settings for the node";
+  return `# This machine is a node of a Novox mesh
+
+Written by the mesh's \`claude-code\` module. Edit the module's settings or the catalogue, never this file:
+it is rewritten whenever the module renders.
+
+## Who this node is
+
+- **Node:** \`${facts.node}\`
+- **Role:** ${role}
+- The other nodes, their roles and what runs where: ask the controller (\`mesh-controller.nodes\`,
+  \`mesh-controller.node\`). Nothing here lists them, because a copy drifts.
+
+## How a session on this mesh works
+
+The console is the only way to the mesh: the MCP server named \`mesh\`. It offers five tools, and
+everything else is an address you find and call through them:
+
+- \`mesh_search\` — words in, matching addresses out. \`mesh_describe\` — one address's arguments.
+- \`mesh_call\` — call an address. A seat the mesh holds once is \`<seat>.<verb>\` (the mesh's own verbs
+  are \`mesh-controller.<verb>\`: \`status\`, \`plan\`, \`node\`, \`assign\`, \`push\`, \`settings\`);
+  a module on a machine is \`<node>/<module>.<tool>\`.
+- \`mesh_overview\` and \`mesh_machine\` — the mesh's seats and machines, and what one machine runs.
+
+- **Symptom first.** For an error, a failing service or anything unexpected, search the record with the
+  literal text before forming a hypothesis: the records module's \`records_search\`, then
+  \`records_read\`.
+- **Ask the mesh before changing it**, and change it through the controller's verbs or the catalogue.
+- **A licence** through the \`anthropic-licence-manager\` seat's verbs. Never edit the agent's credentials
+  file by hand, never print or ask for a token.
+
+## Hard rules
+
+- A file the mesh manages is changed through the verb or the catalogue that owns it, never on disk. If
+  unsure, \`mesh-controller.plan\` for the node says what the mesh writes there.
+- Never write to a store's database by hand; schema changes are numbered migrations.
+- Never push to a main branch: a branch, a pull request, and a human approval for every merge.
+- The mesh creates no symlinks, and nobody else does either.
+- A package is declared in a module, never installed by hand.
+
+## Conventions
+
+- Commit messages are concise, in the imperative, about why.
+- Test before pushing: nodes update unattended.
+- The playbooks in the record say how research, decisions, designs, issues and hand-offs are done.
+`;
+}
@@ -0,0 +1,77 @@
+// Sealing a token to one recipient (novox/hq ADR 0183): the manager seals what it hands a node to that
+// node's agent module key, and a node seals a waiting login to the key the manager names. X25519 for
+// the agreement, HKDF-SHA256 for the key, AES-256-GCM for the box — all from Node's own library, so a
+// bundle carries no dependency and no secret ever crosses the bus in the clear.
+//
+// A sealed box is `{ v: 1, eph, iv, tag, ct }`, every field base64. `eph` is a one-time public key, so
+// two boxes of one value to one recipient share nothing, and only the recipient's private key opens it.
+
+import {
+  createCipheriv, createDecipheriv, createPrivateKey, createPublicKey, diffieHellman,
+  generateKeyPairSync, hkdfSync, randomBytes, type KeyObject,
+} from "node:crypto";
+
+export interface SealedBox {
+  readonly v: 1;
+  readonly eph: string;
+  readonly iv: string;
+  readonly tag: string;
+  readonly ct: string;
+}
+
+/** A recipient's keypair, as the two PEM strings it is kept and published as. */
+export interface KeyPairPem {
+  readonly publicKey: string;
+  readonly privateKey: string;
+}
+
+const INFO = Buffer.from("novox-mesh sealed box v1");
+
+export function generateKeyPair(): KeyPairPem {
+  const { publicKey, privateKey } = generateKeyPairSync("x25519");
+  return {
+    publicKey: publicKey.export({ type: "spki", format: "pem" }).toString(),
+    privateKey: privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
+  };
+}
+
+function keyFor(secret: Buffer, eph: Buffer, recipient: Buffer): Buffer {
+  // The ephemeral and the recipient's public halves are bound into the key, so a box cannot be
+  // re-addressed to another recipient by swapping its `eph`.
+  return Buffer.from(hkdfSync("sha256", secret, Buffer.concat([eph, recipient]), INFO, 32));
+}
+
+function rawPublic(key: KeyObject): Buffer {
+  return key.export({ type: "spki", format: "der" }).subarray(-32);
+}
+
+export function seal(plaintext: string, recipientPublicPem: string): SealedBox {
+  const recipient = createPublicKey(recipientPublicPem);
+  const eph = generateKeyPairSync("x25519");
+  const secret = diffieHellman({ privateKey: eph.privateKey, publicKey: recipient });
+  const ephRaw = eph.publicKey.export({ type: "spki", format: "der" });
+  const key = keyFor(secret, ephRaw, rawPublic(recipient));
+  const iv = randomBytes(12);
+  const cipher = createCipheriv("aes-256-gcm", key, iv);
+  const ct = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+  return {
+    v: 1,
+    eph: ephRaw.toString("base64"),
+    iv: iv.toString("base64"),
+    tag: cipher.getAuthTag().toString("base64"),
+    ct: ct.toString("base64"),
+  };
+}
+
+/** Open a box with the recipient's private key. Throws on a box for another key or one tampered with. */
+export function open(box: SealedBox, privateKeyPem: string): string {
+  if (!box || box.v !== 1) throw new Error("not a sealed box this module can open");
+  const priv = createPrivateKey(privateKeyPem);
+  const ephRaw = Buffer.from(box.eph, "base64");
+  const eph = createPublicKey({ key: ephRaw, format: "der", type: "spki" });
+  const secret = diffieHellman({ privateKey: priv, publicKey: eph });
+  const key = keyFor(secret, ephRaw, rawPublic(createPublicKey(priv)));
+  const decipher = createDecipheriv("aes-256-gcm", key, Buffer.from(box.iv, "base64"));
+  decipher.setAuthTag(Buffer.from(box.tag, "base64"));
+  return Buffer.concat([decipher.update(Buffer.from(box.ct, "base64")), decipher.final()]).toString("utf8");
+}
@@ -0,0 +1,54 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  decideApply, grantOf, holdsLogin, readCredentials, withGrant, writeCredentials, type Grant,
+} from "../dist/grant.js";
+
+const NOW = 1_700_000_000_000;
+const HOUR = 3_600_000;
+const g = (over: Partial<Grant> = {}): Grant => ({
+  accessToken: "tok-A", expiresAt: NOW + HOUR, refreshTokenExpiresAt: NOW + 30 * 24 * HOUR, ...over,
+});
+
+test("a rotation applies a newer grant of the same licence", () => {
+  assert.deepEqual(decideApply(g(), g({ accessToken: "tok-B", expiresAt: NOW + 2 * HOUR }), "rotation"), { apply: true });
+});
+
+test("a rotation refuses a grant that arrived late and is older", () => {
+  const d = decideApply(g({ accessToken: "new", expiresAt: NOW + 2 * HOUR }), g({ accessToken: "old" }), "rotation");
+  assert.equal(d.apply === false && d.reason, "not-newer");
+});
+
+test("a grant re-issued by a login is adopted even though it expires sooner (2026-09-05)", () => {
+  const local = g({ expiresAt: NOW + 8 * HOUR, refreshTokenExpiresAt: NOW + 30 * 24 * HOUR });
+  const offered = g({ accessToken: "reissued", expiresAt: NOW + HOUR, refreshTokenExpiresAt: NOW + 5 * 24 * HOUR });
+  assert.deepEqual(decideApply(local, offered, "rotation"), { apply: true, reissued: true });
+});
+
+test("a switch to another licence applies whatever the expiries say", () => {
+  const local = g({ expiresAt: NOW + 8 * HOUR });
+  assert.equal(decideApply(local, g({ accessToken: "other", expiresAt: NOW + HOUR }), "switch").apply, true);
+});
+
+test("the same token is not rewritten", () => {
+  assert.deepEqual(decideApply(g(), g(), "switch"), { apply: false, reason: "already-current" });
+});
+
+test("a full grant left by a login is seen as a login, and stripped when the node's own is written", () => {
+  const dir = mkdtempSync(join(tmpdir(), "claude-code-"));
+  const path = join(dir, ".claude", ".credentials.json");
+  writeFileSync(join(dir, "x"), "");
+  const login = { claudeAiOauth: { accessToken: "at-login", refreshToken: "rt-login", expiresAt: NOW }, other: 1 };
+  assert.equal(holdsLogin(login), true);
+  writeCredentials(path, withGrant(login, g({ accessToken: "at-mesh", scopes: ["user:inference"] })));
+  const back = readCredentials(path)!;
+  assert.equal(holdsLogin(back), false);
+  assert.equal(grantOf(back)!.accessToken, "at-mesh");
+  assert.deepEqual(back.claudeAiOauth!.scopes, ["user:inference"]);
+  assert.equal(back.other, 1, "a key the module does not know was lost");
+  assert.ok(!readFileSync(path, "utf8").includes("rt-login"));
+  assert.equal(statSync(path).mode & 0o777, 0o600);
+});
@@ -0,0 +1,19 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { readIdentity } from "../dist/identity.js";
+
+test("the account is read from the agent's state file", () => {
+  const p = join(mkdtempSync(join(tmpdir(), "cc-id-")), ".claude.json");
+  writeFileSync(p, JSON.stringify({ oauthAccount: { accountUuid: "u-1", emailAddress: "a@example.org" }, other: 2 }));
+  assert.deepEqual(readIdentity(p), { accountUuid: "u-1", emailAddress: "a@example.org", organizationUuid: undefined });
+});
+
+test("no state file, or no account in it, is no identity rather than a guess", () => {
+  assert.equal(readIdentity("/nonexistent/.claude.json"), null);
+  const p = join(mkdtempSync(join(tmpdir(), "cc-id-")), ".claude.json");
+  writeFileSync(p, "{}");
+  assert.equal(readIdentity(p), null);
+});
@@ -0,0 +1,173 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  apply, concerns, keypair, offerLogin, onServerChange, pull, registerServer, registered, ServerView, type Paths,
+  type ServerChange, type ServerState,
+} from "../dist/node.js";
+import { generateKeyPair, open, seal } from "../dist/seal.js";
+
+const NOW = Date.now();
+function node(name = "laptop"): { p: Paths; written: Record<string, string> } {
+  const root = mkdtempSync(join(tmpdir(), "cc-node-"));
+  const p = { state: join(root, "state"), facts: join(root, "state", "facts.json"), settings: join(root, "state", "settings.json"), home: join(root, "home"), node: name };
+  mkdirSync(p.state, { recursive: true });
+  mkdirSync(join(p.home, ".claude"), { recursive: true });
+  writeFileSync(p.facts, JSON.stringify({ node: name, console: "http://127.0.0.1:4270/mcp" }));
+  writeFileSync(p.settings, JSON.stringify({ role: "", mcp_servers: {} }));
+  return { p, written: {} };
+}
+const writer = (w: Record<string, string>) => (name: string, content: string) => { w[name] = content; return `${name}: written`; };
+const creds = (p: Paths) => JSON.parse(readFileSync(join(p.home, ".claude", ".credentials.json"), "utf8"));
+const grantFor = (p: Paths, licence: string, token: string, kind: "subscription" | "api-key" = "subscription", identity?: object) => ({
+  licence, kind, identity,
+  sealed: seal(kind === "api-key" ? token : JSON.stringify({ accessToken: token, expiresAt: NOW + 3_600_000, refreshTokenExpiresAt: NOW + 86_400_000, subscriptionType: licence }), keypair(p).publicKey),
+});
+
+test("a pull asks the seat with this node's key and applies what it answers", async () => {
+  const { p, written } = node();
+  let asked: [string, Record<string, unknown>] | null = null;
+  const r = await pull(p, async (address, args) => { asked = [address, args]; return grantFor(p, "personal", "at-1"); }, writer(written));
+  assert.equal(asked![0], "anthropic-licence-manager.current");
+  assert.equal(asked![1].node, "laptop");
+  assert.match(String(asked![1].public_key), /BEGIN PUBLIC KEY/);
+  assert.equal(r.applied, true);
+  assert.equal(creds(p).claudeAiOauth.accessToken, "at-1");
+  assert.ok(written["managed-mcp.json"]);
+});
+
+test("a switch replaces the old licence's grant whole and points the account at the new one", () => {
+  const { p, written } = node();
+  writeFileSync(join(p.home, ".claude.json"), JSON.stringify({ oauthAccount: { accountUuid: "old" }, projects: { keep: 1 } }));
+  apply(p, grantFor(p, "personal", "at-1"), writer(written));
+  const r = apply(p, grantFor(p, "work", "at-2", "subscription", { accountUuid: "new", emailAddress: "w@example.org" }), writer(written));
+  assert.equal(r.switched, true);
+  assert.equal(creds(p).claudeAiOauth.accessToken, "at-2");
+  assert.equal(creds(p).claudeAiOauth.subscriptionType, "work", "the old licence's subscription type survived the switch");
+  const account = JSON.parse(readFileSync(join(p.home, ".claude.json"), "utf8"));
+  assert.equal(account.oauthAccount.accountUuid, "new");
+  assert.deepEqual(account.projects, { keep: 1 });
+});
+
+test("switching to the API key adds the key-helper; switching away removes the key and the helper", () => {
+  const { p, written } = node();
+  apply(p, grantFor(p, "api", "sk-key", "api-key"), writer(written));
+  assert.ok(JSON.parse(written["managed-settings.json"]).apiKeyHelper);
+  assert.ok(existsSync(join(p.state, "api-key")));
+  apply(p, grantFor(p, "personal", "at-1"), writer(written));
+  assert.ok(!("apiKeyHelper" in JSON.parse(written["managed-settings.json"])));
+  assert.ok(!existsSync(join(p.state, "api-key")) && !existsSync(join(p.state, "api-key-helper")));
+});
+
+test("a rotation event concerns the node bound to that licence; a switch event the node it names", () => {
+  const { p, written } = node();
+  apply(p, grantFor(p, "personal", "at-1"), writer(written));
+  assert.equal(concerns(p, "claude-licence-manager.licence.rotated", { licence: "personal" }), true);
+  assert.equal(concerns(p, "claude-licence-manager.licence.rotated", { licence: "work" }), false);
+  assert.equal(concerns(p, "claude-licence-manager.licence.switched", { node: "laptop", licence: "work" }), true);
+  assert.equal(concerns(p, "claude-licence-manager.licence.switched", { node: "server" }), false);
+});
+
+test("a login is offered to the seat sealed to the seat's key, with the account it belongs to", async () => {
+  const { p } = node();
+  const manager = generateKeyPair();
+  writeFileSync(join(p.home, ".claude", ".credentials.json"), JSON.stringify({ claudeAiOauth: { accessToken: "at-login", refreshToken: "rt-login", expiresAt: NOW } }));
+  writeFileSync(join(p.home, ".claude.json"), JSON.stringify({ oauthAccount: { accountUuid: "u-9" } }));
+  const calls: [string, Record<string, unknown>][] = [];
+  await offerLogin(p, async (address, args) => { calls.push([address, args]); return address.endsWith("public_key") ? { public_key: manager.publicKey } : { adopted: true }; });
+  assert.deepEqual(calls.map((c) => c[0]), ["anthropic-licence-manager.public_key", "anthropic-licence-manager.adopt"]);
+  const adopt = calls[1][1] as { identity: { accountUuid: string }; sealed: never };
+  assert.equal(adopt.identity.accountUuid, "u-9");
+  assert.equal(JSON.parse(open(adopt.sealed, manager.privateKey)).refreshToken, "rt-login");
+  assert.ok(!JSON.stringify(adopt).includes("rt-login"), "the refresh token crossed in the clear");
+});
+
+test("no refresh token in the file is no login, and nothing is asked", async () => {
+  const { p } = node();
+  writeFileSync(join(p.home, ".claude", ".credentials.json"), JSON.stringify({ claudeAiOauth: { accessToken: "at", expiresAt: NOW } }));
+  assert.equal(await offerLogin(p, async () => { throw new Error("asked"); }), null);
+});
+
+/** The `servers` state as the bus holds it, shared by every node in a test, with each node's watch. */
+function bus() {
+  const kept = new Map<string, Record<string, unknown>>();
+  const watchers: ((c: ServerChange) => void)[] = [];
+  const state: ServerState = {
+    put: async (key, value) => { kept.set(key, value); watchers.forEach((w) => w({ key, op: "put", value })); return kept.size; },
+    delete: async (key) => { kept.delete(key); watchers.forEach((w) => w({ key, op: "delete" })); },
+    keys: async () => [...kept.keys()].sort(),
+  };
+  /** A node joining: its view takes the current state, then every change. */
+  const join = (n: { p: Paths; written: Record<string, string> }) => {
+    const view = new ServerView(n.p);
+    for (const [key, value] of kept) onServerChange(view, { key, op: "put", value }, n.p, writer(n.written));
+    watchers.push((c) => onServerChange(view, c, n.p, writer(n.written)));
+    return view;
+  };
+  return { state, join, kept };
+}
+
+test("registering a server here puts it under this node's key, renders it, and asks about the other nodes", async () => {
+  const n = node();
+  const b = bus();
+  const view = b.join(n);
+  const r = await registerServer(n.p, { name: "search", entry: { type: "http", url: "https://s.example/mcp" } },
+    b.state, view, writer(n.written), async () => ["laptop", "server", "desktop"]);
+  assert.equal(r.here, "changed");
+  assert.match(String(r.also), /server, desktop/);
+  assert.deepEqual([...b.kept.keys()], ["laptop.search"]);
+  assert.ok(JSON.parse(n.written["managed-mcp.json"]).mcpServers.search);
+});
+
+test("registering for every node reaches the others through their watch, and a node joining later reads it", async () => {
+  const a = node("laptop"), s = node("server");
+  const b = bus();
+  const va = b.join(a);
+  b.join(s);
+  await registerServer(a.p, { name: "docs", entry: { type: "stdio", command: "docs-mcp" }, nodes: "all" },
+    b.state, va, writer(a.written), async () => []);
+  assert.deepEqual([...b.kept.keys()], ["all.docs"]);
+  assert.deepEqual(registered(s.p).docs, { type: "stdio", command: "docs-mcp" });
+  assert.ok(JSON.parse(s.written["managed-mcp.json"]).mcpServers.docs);
+  // The gap events left: a node assigned after the registration takes the whole current set at start.
+  const late = node("desktop");
+  b.join(late);
+  assert.deepEqual(registered(late.p).docs, { type: "stdio", command: "docs-mcp" });
+  // Unregistering is a delete, and every node's view drops it.
+  await registerServer(a.p, { name: "docs", nodes: "all" }, b.state, va, writer(a.written), async () => []);
+  assert.equal(registered(s.p).docs, undefined);
+  assert.equal(registered(late.p).docs, undefined);
+});
+
+test("a node's own registration overrides the one for every node; other nodes' keys leave this one alone", async () => {
+  const a = node("laptop"), s = node("server");
+  const b = bus();
+  const va = b.join(a);
+  const vs = b.join(s);
+  await registerServer(a.p, { name: "x", entry: { type: "http", url: "https://all" }, nodes: "all" }, b.state, va, writer(a.written), async () => []);
+  await registerServer(a.p, { name: "x", entry: { type: "http", url: "https://laptop" } }, b.state, va, writer(a.written), async () => []);
+  assert.equal(registered(a.p).x.url, "https://laptop");
+  assert.equal(registered(s.p).x.url, "https://all");
+  await registerServer(a.p, { name: "only", entry: { type: "http", url: "https://o" }, nodes: ["server"] }, b.state, va, writer(a.written), async () => []);
+  assert.equal(registered(a.p).only, undefined);
+  assert.equal(registered(s.p).only.url, "https://o");
+  // Unregistering here leaves the every-node one applying, and says so.
+  const r = await registerServer(a.p, { name: "x" }, b.state, va, writer(a.written), async () => []);
+  assert.match(String(r.still), /still applies here/);
+  assert.equal(registered(a.p).x.url, "https://all");
+  assert.equal(vs.effective().x.url, "https://all");
+});
+
+test("a bad entry is refused before anything is put; a repeated change changes nothing", async () => {
+  const n = node();
+  const b = bus();
+  const view = b.join(n);
+  const r = await registerServer(n.p, { name: "mesh", entry: { type: "http", url: "https://x" } }, b.state, view, writer(n.written), async () => []);
+  assert.equal(r.registered, false);
+  assert.equal(b.kept.size, 0);
+  assert.equal(onServerChange(view, { key: "all.a", op: "put", value: { type: "http", url: "https://a" } }, n.p, writer(n.written)), "registered all.a");
+  assert.equal(onServerChange(view, { key: "all.a", op: "put", value: { type: "http", url: "https://a" } }, n.p, writer(n.written)), null);
+  assert.equal(onServerChange(view, { key: "server.b", op: "put", value: { type: "http", url: "https://b" } }, n.p, writer(n.written)), null);
+});
@@ -0,0 +1,40 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { render } from "../dist/render.js";
+
+const facts = { node: "workstation", console: "http://127.0.0.1:4270/mcp" };
+
+test("the console is the `mesh` server, and an operator's servers are listed beside it", () => {
+  const out = render(facts, { mcp_servers: { search: { type: "http", url: "https://s.example/mcp" } } }, null, "/h");
+  const mcp = JSON.parse(out["managed-mcp.json"]);
+  assert.deepEqual(Object.keys(mcp.mcpServers), ["mesh", "search"]);
+  assert.deepEqual(mcp.mcpServers.mesh, { type: "http", url: facts.console });
+});
+
+test("a setting cannot replace the mesh's own entry, and a name the vendor refuses is left out", () => {
+  const out = render(facts, { mcp_servers: { mesh: { type: "http", url: "http://evil" }, "bad name": {} } }, null, "/h");
+  const mcp = JSON.parse(out["managed-mcp.json"]);
+  assert.equal(mcp.mcpServers.mesh.url, facts.console);
+  assert.ok(!("bad name" in mcp.mcpServers));
+});
+
+test("managed settings carry the mesh's keys only, and the key-helper only for an API-key licence", () => {
+  const sub = JSON.parse(render(facts, {}, { licence: "personal", kind: "subscription" }, "/h")["managed-settings.json"]);
+  assert.deepEqual(sub, { attribution: { commit: "", pr: "" }, allowAllClaudeAiMcps: true });
+  const key = JSON.parse(render(facts, {}, { licence: "api", kind: "api-key" }, "/state/api-key-helper")["managed-settings.json"]);
+  assert.equal(key.apiKeyHelper, "/state/api-key-helper");
+  assert.ok(!("model" in key), "a preference is the person's");
+});
+
+test("the instruction file names the node and its role, and no other node", () => {
+  const md = render(facts, { role: "the laptop" }, null, "/h")["CLAUDE.md"];
+  assert.match(md, /\*\*Node:\*\* `workstation`/);
+  assert.match(md, /\*\*Role:\*\* the laptop/);
+  assert.match(md, /mesh_call/);
+  assert.match(md, /records_search/);
+});
+
+test("rendering is deterministic, so an unchanged input writes nothing", () => {
+  const s = { mcp_servers: { b: { type: "http", url: "https://b" }, a: { type: "http", url: "https://a" } } };
+  assert.deepEqual(render(facts, s, null, "/h"), render(facts, s, null, "/h"));
+});
@@ -0,0 +1,31 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { generateKeyPair, open, seal } from "../dist/seal.js";
+
+test("a box opens with its recipient's key and yields the value", () => {
+  const k = generateKeyPair();
+  assert.equal(open(seal("at-secret", k.publicKey), k.privateKey), "at-secret");
+});
+
+test("a box sealed for one node does not open with another node's key", () => {
+  const a = generateKeyPair();
+  const b = generateKeyPair();
+  assert.throws(() => open(seal("at-secret", a.publicKey), b.privateKey));
+});
+
+test("a tampered box is refused, not opened to garbage", () => {
+  const k = generateKeyPair();
+  const box = seal("at-secret", k.publicKey);
+  const ct = Buffer.from(box.ct, "base64");
+  ct[0] ^= 0xff;
+  assert.throws(() => open({ ...box, ct: ct.toString("base64") }, k.privateKey));
+});
+
+test("two boxes of one value share nothing a reader could compare", () => {
+  const k = generateKeyPair();
+  const x = seal("at-secret", k.publicKey);
+  const y = seal("at-secret", k.publicKey);
+  assert.notEqual(x.ct, y.ct);
+  assert.notEqual(x.eph, y.eph);
+  assert.ok(!JSON.stringify(x).includes("at-secret"));
+});
@@ -0,0 +1,224 @@
+// claude-code's bundle (novox/hq design 36, ADR 0183). The node's runtime launches it over stdio, as the
+// operator account (ADR 0193), and is its bus (ADR 0198): it asks tools, emits and consumes through the
+// runtime. It is given its state directory and two files the mesh renders into it (ADR 0192), beside the
+// runtime's own words. **stdout is the MCP channel**: everything this module says, it says on stderr.
+//
+// At start it renders the agent's managed directory, asks the licence manager for this node's token,
+// begins watching the credentials file for a login, takes the manager's licence events, and watches the
+// module's `servers` state — every node's MCP server registrations (novox/hq ADR 0201). node.ts holds the
+// logic.
+
+import { mkdtempSync, readFileSync, rmSync, watchFile, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
+import { broker } from "@novox/mesh-sdk/messaging";
+import { on } from "@novox/mesh-sdk/events";
+import { state } from "@novox/mesh-sdk/state";
+
+import {
+  MANAGED_DIR, SEAT, ServerView, concerns, keypair, offerLogin, onServerChange, pull, readJson, registerServer,
+  registered, renderNow, type Ask, type Paths, type Registration, type ServerChange, type ServerState, type WriteManaged,
+} from "../node.js";
+import { grantOf, holdsLogin, readCredentials } from "../grant.js";
+import { createHash } from "node:crypto";
+
+const say = (line: string) => console.error(`[claude-code] ${line}`);
+const fingerprint = (s: string) => "sha256:" + createHash("sha256").update(s).digest("hex").slice(0, 16);
+
+function pathsFrom(env: NodeJS.ProcessEnv): Paths | null {
+  const state = env.MESH_CLAUDE_CODE_STATE, facts = env.MESH_CLAUDE_CODE_FACTS;
+  const settings = env.MESH_CLAUDE_CODE_SETTINGS, home = env.MESH_OPERATOR_HOME, node = env.MESH_NODE;
+  if (!state || !facts || !settings || !home || !node) return null;
+  return { state, facts, settings, home, node };
+}
+
+/** Write one managed file as root, only when its content changed. */
+const writeManaged: WriteManaged = (name, content) => {
+  const path = join(MANAGED_DIR, name);
+  try {
+    if (readFileSync(path, "utf8") === content) return `${name}: unchanged`;
+  } catch {
+    /* absent */
+  }
+  // From a file, never /dev/stdin: Node hands a child its input over a socket, which /dev/stdin cannot
+  // open (ENXIO) — found on the first assignment, where nothing under /etc/claude-code was ever written.
+  const staged = mkdtempSync(join(tmpdir(), "claude-code-"));
+  const source = join(staged, name);
+  writeFileSync(source, content, { mode: 0o644 });
+  const asRoot = process.getuid?.() === 0;
+  const cmd = asRoot ? ["install", "-D", "-m", "0644", source, path] : ["sudo", "-n", "install", "-D", "-m", "0644", source, path];
+  const r = spawnSync(cmd[0], cmd.slice(1), { encoding: "utf8" });
+  rmSync(staged, { recursive: true, force: true });
+  if (r.status !== 0) {
+    throw new Error(`${name}: could not be written to ${MANAGED_DIR} (${(r.stderr || r.error?.message || "").trim()}); ` +
+      `the module writes there through the operator account's passwordless sudo`);
+  }
+  return `${name}: written`;
+};
+
+/** A tool on the bus, through the runtime; its MCP answer read back as JSON where it is JSON. */
+const ask: Ask = async (address, args) => {
+  const answer = (await broker().request<Record<string, unknown>, { content?: { text?: string }[]; isError?: boolean }>(address, args)) ?? {};
+  const text = answer.content?.map((c) => c.text ?? "").join("") ?? "";
+  if (answer.isError) throw new Error(`${address}: ${text}`);
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+};
+
+/** The nodes claude-code runs on, from the controller's list of modules — for the register tool's question. */
+async function nodesRunningMe(): Promise<string[]> {
+  const out = await ask("mesh-controller.modules", {});
+  const text = typeof out === "string" ? out : String((out as { output?: string })?.output ?? "");
+  const line = text.split("\n").find((l) => /^claude-code\s/.test(l)) ?? "";
+  const on = line.split(" on ")[1] ?? "";
+  return on.trim() === "nothing" ? [] : on.split(",").map((s) => s.trim()).filter(Boolean);
+}
+
+function status(p: Paths): Record<string, unknown> {
+  const creds = readCredentials(join(p.home, ".claude", ".credentials.json"));
+  const grant = grantOf(creds);
+  const managed = ["managed-mcp.json", "managed-settings.json", "CLAUDE.md"].map((f) => {
+    try {
+      return { file: join(MANAGED_DIR, f), fingerprint: fingerprint(readFileSync(join(MANAGED_DIR, f), "utf8")) };
+    } catch {
+      return { file: join(MANAGED_DIR, f), fingerprint: null };
+    }
+  });
+  return {
+    node: p.node,
+    licence: readJson(join(p.state, "licence.json"), null),
+    token: grant ? { fingerprint: fingerprint(grant.accessToken), expiresAt: new Date(grant.expiresAt).toISOString(),
+      loginWaiting: holdsLogin(creds) } : null,
+    managed,
+    registered: Object.keys(registered(p)),
+  };
+}
+
+/** The module's MCP servers on the bus (ADR 0201): its own state, which every node of it watches. */
+const servers = () => state<Record<string, unknown>>("servers") as unknown as ServerState;
+
+/** What this node takes from that state, kept from the watch. One per process. */
+let view: ServerView | null = null;
+const viewOf = (p: Paths) => (view ??= new ServerView(p));
+
+function tools(p: Paths): ToolDefinition[] {
+  const nodesArg = { type: "string", description: 'more nodes: "all" for every node running claude-code, or a comma-separated list; absent is this node only' };
+  const nodesOf = (v: unknown): Registration["nodes"] =>
+    v === undefined || v === "" ? undefined : v === "all" ? "all" : String(v).split(",").map((s) => s.trim()).filter(Boolean);
+  return [
+    {
+      name: "claude_code_status",
+      description: "Claude Code on this machine as the mesh configured it: the licence it holds and when its token expires, the managed files, the MCP servers registered here. Fingerprints only, never a token.",
+      input: {},
+      run: async () => status(p),
+    },
+    {
+      name: "claude_code_render",
+      description: "Write Claude Code's managed directory now, from the mesh's facts, this module's settings and the servers registered here.",
+      input: {},
+      run: async () => ({ rendered: renderNow(p, writeManaged) }),
+    },
+    {
+      name: "claude_code_pull",
+      description: "Ask the licence manager for this node's current token now and apply it, rather than waiting for its next event.",
+      input: {},
+      run: async () => pull(p, ask, writeManaged),
+    },
+    {
+      name: "claude_code_mcp_list",
+      description: "The MCP servers registered through this module: those that apply on this node (beside the console, `mesh`, and those set in the module's settings), and every registration on the mesh, by key — `all.<server>` for every node, `<node>.<server>` for one.",
+      input: {},
+      run: async () => ({ here: registered(p), everywhere: await servers().keys() }),
+    },
+    {
+      name: "claude_code_mcp_register",
+      description: "Register an MCP server with Claude Code on this node, every node, or a list — an http/sse server by url, or a stdio server by command. Kept on the bus, so a node that joins later takes it too. Never put a secret in env or headers: the mesh refuses one.",
+      input: {
+        name: { type: "string", description: "the server's name: letters, digits, - and _" },
+        type: { type: "string", description: "http, sse or stdio (default stdio when a command is given, http when a url is)" },
+        url: { type: "string", description: "an http or sse server's url" },
+        command: { type: "string", description: "a stdio server's program" },
+        args: { type: "array", description: "a stdio server's arguments" },
+        env: { type: "object", description: "a stdio server's environment" },
+        headers: { type: "object", description: "an http server's headers" },
+        nodes: nodesArg,
+      },
+      run: async (a) => {
+        const entry: Record<string, unknown> = { type: a.type ?? (a.url ? "http" : "stdio") };
+        for (const k of ["url", "command", "args", "env", "headers"]) if (a[k] !== undefined) entry[k] = a[k];
+        return registerServer(p, { name: String(a.name ?? ""), entry, nodes: nodesOf(a.nodes) }, servers(), viewOf(p), writeManaged, nodesRunningMe);
+      },
+    },
+    {
+      name: "claude_code_mcp_unregister",
+      description: "Remove an MCP server registered through this module, on this node or more.",
+      input: { name: { type: "string", description: "the server's name" }, nodes: nodesArg },
+      run: async (a) => registerServer(p, { name: String(a.name ?? ""), nodes: nodesOf(a.nodes) }, servers(), viewOf(p), writeManaged, nodesRunningMe),
+    },
+  ];
+}
+
+registerModuleTools("claude-code", (env) => {
+  const p = pathsFrom(env);
+  if (!p) return [];
+  try {
+    keypair(p);
+    for (const line of renderNow(p, writeManaged)) if (!line.endsWith("unchanged")) say(line);
+  } catch (err) {
+    say(err instanceof Error ? err.message : String(err));
+  }
+  return tools(p);
+});
+
+// Launched by the runtime: the bus is there from the first line (ADR 0198). Outside it — a test, a
+// build — nothing below runs.
+const p = process.env.MESH_SERVED_MODULE ? pathsFrom(process.env) : null;
+if (p) {
+  const loud = (what: string) => (err: unknown) => say(`${what}: ${err instanceof Error ? err.message : String(err)}`);
+
+  void on<{ licence?: string; node?: string }>("claude-licence-manager.licence.*", async (event) => {
+    if (!concerns(p, event.type, event.body ?? {})) return;
+    say(`${event.type} — asking ${SEAT} for this node's token`);
+    say(JSON.stringify(await pull(p, ask, writeManaged).catch((e) => ({ failed: String(e) }))));
+  }).catch(loud("the licence events"));
+
+  // Every node's MCP servers: the whole current set first, then each change (ADR 0201). **Not awaited
+  // where the module is imported**: the runtime waits on the handshake, and a bucket that is not on the
+  // bus yet — or a grant the bus has not reloaded — answers late; awaited here, that left the bundle
+  // unable to answer `initialize` in time and the module unserved (found on its first assignment). So it
+  // watches beside the handshake and asks again until the state answers; until then the managed
+  // directory holds what the file kept from the last run.
+  const watchServers = (attempt = 0): void => {
+    state<Record<string, unknown>>("servers").watch((c) => {
+      try {
+        const done = onServerChange(viewOf(p), c as ServerChange, p, writeManaged);
+        if (done) say(done);
+      } catch (err) {
+        loud(`taking ${c.op} ${c.key}`)(err); // the view took it; the next render writes it
+      }
+    }).then(
+      () => say(`watching the MCP servers${attempt ? ` (after ${attempt} refusal(s))` : ""}`),
+      (err) => {
+        const wait = [2, 5, 10, 30][attempt] ?? 60;
+        say(`the MCP servers cannot be watched yet (${err instanceof Error ? err.message : String(err)}); asking again in ${wait}s`);
+        setTimeout(() => watchServers(attempt + 1), wait * 1000);
+      });
+  };
+  watchServers();
+
+  // Catch up once at start: a node that was off takes its current token now.
+  void pull(p, ask, writeManaged).then((r) => say(`at start: ${JSON.stringify(r)}`), loud("asking for this node's token at start"));
+
+  // A login: a refresh token appears in the credentials file. Polled, because the file is replaced by
+  // rename and a watch on the old inode would go quiet.
+  const credentials = join(p.home, ".claude", ".credentials.json");
+  watchFile(credentials, { interval: 5000 }, () => {
+    void offerLogin(p, ask).then((r) => { if (r) say(`a login here was offered to ${SEAT}: ${JSON.stringify(r)}`); },
+      loud("offering a login to the licence manager"));
+  });
+}
@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["seal.ts", "grant.ts", "identity.ts", "render.ts", "node.ts", "tools/index.ts"]
+}
@@ -1,24 +0,0 @@
-# cloudflare-dns's runtime: the tool runtime, carrying this module's compiled code.
-#
-# **Built from this module's own directory and nothing else.** The sdk and the tool runtime are in
-# the base images, published like any other artifact — which is what makes this buildable by the
-# mesh from a repository and a path (novox/hq ADR 0069) rather than only on a workstation that
-# happens to have the siblings.
-#
-# Two bases, named rather than pinned (novox/hq issue 044): the image this is COMPILED in and the
-# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
-ARG BUILD_BASE
-ARG RUNTIME_BASE
-
-FROM ${BUILD_BASE} AS build
-WORKDIR /app/modules/cloudflare-dns
-COPY . .
-RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts provisioner/index.ts \
-      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
-
-FROM ${RUNTIME_BASE}
-COPY --from=build /app/modules/cloudflare-dns/dist /app/modules/cloudflare-dns/dist
-# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
-# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
-# the convention novox/hq issues 060/061 settled.
-ENV MESH_TOOL_MODULES=/app/modules/cloudflare-dns/dist/tools/index.js,/app/modules/cloudflare-dns/dist/provisioner/index.js
@@ -12,87 +12,61 @@
    "public-dns": {}
  },
  "grants": {
-    "public-dns": "/var/lib/cloudflare-dns/grants"
+    "public-dns": "${dir:grants}"
  },
  "receives": {
-    "public-dns": "/var/lib/cloudflare-dns/grants/mesh.json"
+    "public-dns": "${dir:grants}/mesh.json"
  },
  "own-secrets": {
-    "token": "/var/lib/cloudflare-dns/token",
-    "broker": "/var/lib/mesh/cloudflare-dns/broker"
+    "token": "${dir:state}/token"
  },
  "emits": [
    "record.created",
    "record.removed"
  ],
  "resources": [
-    {
-      "id": "mesh-state",
-      "type": "directory",
-      "path": "/var/lib/mesh/cloudflare-dns",
-      "mode": "0700"
-    },
    {
      "id": "state",
      "type": "directory",
-      "path": "/var/lib/cloudflare-dns",
-      "mode": "0700"
+      "mode": "0700",
+      "place": "."
    },
    {
      "id": "grants",
      "type": "directory",
-      "path": "/var/lib/cloudflare-dns/grants",
      "mode": "0700"
    },
    {
      "id": "config",
      "type": "file",
-      "path": "/var/lib/cloudflare-dns/config.json",
+      "path": "${dir:state}/config.json",
      "merge": "json",
      "content": "{}",
      "mode": "0600"
-    },
-    {
-      "id": "runtime",
-      "type": "container",
-      "name": "mesh-cloudflare-dns",
-      "network": "host",
-      "volumes": [
-        "/var/lib/cloudflare-dns/config.json:/run/config/config.json:ro",
-        "/var/lib/cloudflare-dns/grants:/grants",
-        "/var/lib/cloudflare-dns/token:/run/secrets/token:ro",
-        "/var/lib/mesh/cloudflare-dns/broker:/run/secrets/broker:ro"
-      ],
-      "env": {
-        "MESH_CLOUDFLARE_TOKEN_FILE": "/run/secrets/token",
-        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_CLOUDFLARE_CONFIG_FILE": "/run/config/config.json",
-        "MESH_RECEIVES": "/var/lib/cloudflare-dns/grants/mesh.json"
-      },
-      "artifact": "runtime"
    }
  ],
  "capabilities": [
    "container-runtime"
  ],
  "build": {
-    "on": [
-      {
-        "arg": "BUILD_BASE",
-        "module": "mesh-tools",
-        "artifact": "build"
-      },
-      {
-        "arg": "RUNTIME_BASE",
-        "module": "mesh-tools",
-        "artifact": "runtime"
-      }
-    ],
    "artifacts": [
      {
-        "name": "runtime",
-        "kind": "image",
-        "from": "Dockerfile"
+        "name": "code",
+        "kind": "bundle",
+        "language": "typescript",
+        "entrypoints": [
+          "tools/index.js",
+          "provisioner/index.js"
+        ],
+        "loads": [
+          "tools/index.js",
+          "provisioner/index.js"
+        ],
+        "env": {
+          "MESH_CLOUDFLARE_TOKEN_FILE": "${dir:state}/token",
+          "MESH_CLOUDFLARE_CONFIG_FILE": "${dir:state}/config.json",
+          "MESH_RECEIVES": "${dir:grants}/mesh.json"
+        }
      }
    ]
  }
@@ -1,24 +0,0 @@
-# confluence's runtime: the tool runtime, carrying this module's compiled code.
-#
-# **Built from this module's own directory and nothing else.** The sdk and the tool runtime are in
-# the base images, published like any other artifact — which is what makes this buildable by the
-# mesh from a repository and a path (novox/hq ADR 0069) rather than only on a workstation that
-# happens to have the siblings.
-#
-# Two bases, named rather than pinned (novox/hq issue 044): the image this is COMPILED in and the
-# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
-ARG BUILD_BASE
-ARG RUNTIME_BASE
-
-FROM ${BUILD_BASE} AS build
-WORKDIR /app/modules/confluence
-COPY . .
-RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts \
-      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
-
-FROM ${RUNTIME_BASE}
-COPY --from=build /app/modules/confluence/dist /app/modules/confluence/dist
-# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
-# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
-# the convention novox/hq issues 060/061 settled.
-ENV MESH_TOOL_MODULES=/app/modules/confluence/dist/tools/index.js
@@ -3,69 +3,43 @@
  "version": "1",
  "slug": "confl",
  "own-secrets": {
-    "token": "/var/lib/confluence/token",
-    "broker": "/var/lib/mesh/confluence/broker"
+    "token": "${dir:state}/token"
  },
  "resources": [
-    {
-      "id": "mesh-state",
-      "type": "directory",
-      "path": "/var/lib/mesh/confluence",
-      "mode": "0700"
-    },
    {
      "id": "state",
      "type": "directory",
-      "path": "/var/lib/confluence",
-      "mode": "0700"
+      "mode": "0700",
+      "place": "."
    },
    {
      "id": "config",
      "type": "file",
-      "path": "/var/lib/confluence/config.json",
+      "path": "${dir:state}/config.json",
      "merge": "json",
      "content": "{}",
      "mode": "0600"
-    },
-    {
-      "id": "runtime",
-      "type": "container",
-      "name": "mesh-runtime-confluence",
-      "network": "host",
-      "volumes": [
-        "/var/lib/confluence/config.json:/run/config/config.json:ro",
-        "/var/lib/confluence/token:/run/secrets/token:ro",
-        "/var/lib/mesh/confluence/broker:/run/secrets/broker:ro"
-      ],
-      "env": {
-        "MESH_CONFLUENCE_TOKEN_FILE": "/run/secrets/token",
-        "MESH_CONFLUENCE_CONFIG_FILE": "/run/config/config.json",
-        "MESH_BROKER_FILE": "/run/secrets/broker"
-      },
-      "artifact": "runtime"
    }
  ],
  "capabilities": [
    "container-runtime"
  ],
  "build": {
-    "on": [
-      {
-        "arg": "BUILD_BASE",
-        "module": "mesh-tools",
-        "artifact": "build"
-      },
-      {
-        "arg": "RUNTIME_BASE",
-        "module": "mesh-tools",
-        "artifact": "runtime"
-      }
-    ],
    "artifacts": [
      {
-        "name": "runtime",
-        "kind": "image",
-        "from": "Dockerfile"
+        "name": "tools",
+        "kind": "bundle",
+        "language": "typescript",
+        "entrypoints": [
+          "tools/index.js"
+        ],
+        "loads": [
+          "tools/index.js"
+        ],
+        "env": {
+          "MESH_CONFLUENCE_TOKEN_FILE": "${dir:state}/token",
+          "MESH_CONFLUENCE_CONFIG_FILE": "${dir:state}/config.json"
+        }
      }
    ]
  }
@@ -15,11 +15,11 @@
    }
  },
  "binds": {
-    "route": "/var/lib/de-spiegel/route.json"
+    "route": "${dir:state}/route.json"
  },
  "own-secrets": {
-    "smtp-user": "/var/lib/de-spiegel/smtp-user.secret",
-    "smtp-pass": "/var/lib/de-spiegel/smtp-pass.secret"
+    "smtp-user": "${dir:state}/smtp-user.secret",
+    "smtp-pass": "${dir:state}/smtp-pass.secret"
  },
  "listens": [
    {
@@ -27,20 +27,20 @@
      "port": 35621,
      "protocol": "tcp",
      "from": "mesh",
-      "why": "the de-spiegel site and its /contact endpoint over http; the public name de-spiegel.novox.be is a route grant, and route-proxy reaches it on this published port"
+      "why": "the de-spiegel site and its /contact endpoint over http; its public name is a route grant, and route-proxy reaches it on this published port"
    }
  ],
  "resources": [
    {
      "id": "state",
      "type": "directory",
-      "path": "/var/lib/de-spiegel",
-      "mode": "0700"
+      "mode": "0700",
+      "place": "."
    },
    {
      "id": "server-env",
      "type": "file",
-      "path": "/var/lib/de-spiegel/server.env",
+      "path": "${dir:state}/server.env",
      "mode": "0600",
      "content": "SMTP_AUTH_USER=${secret:smtp-user}\nSMTP_AUTH_PASS=${secret:smtp-pass}\n"
    },
@@ -56,12 +56,15 @@
      "image": "registry-api.novox.be/novox/de-spiegel@sha256:e144b72ce9c145870470d765343549f2c60211728cd118b9ff0e4029f36342ba",
      "network": "de-spiegel",
      "env-file": [
-        "/var/lib/de-spiegel/server.env"
+        "${dir:state}/server.env"
      ],
      "ports": [
        "35621"
      ],
-      "secrets-in-environment": "the application's own code reads SMTP_AUTH_USER/PASS from the environment (de-spiegel server/index.js); converting is that repository's change"
+      "secrets-in-environment": "the application's own code reads SMTP_AUTH_USER/PASS from the environment (de-spiegel server/index.js); converting is that repository's change",
+      "names-on-purpose": {
+        "registry-api.novox.be": "built outside the mesh, from the application's own repository, and pulled from the registry that built it; moves when that repository is a build source on the git seat (novox/hq ADR 0155, issue 122)"
+      }
    }
  ]
 }
@@ -3,7 +3,8 @@
  "version": "1",
  "capabilities": [
    "package-manager",
-    "service-manager"
+    "service-manager",
+    "uplink-dhcpcd"
  ],
  "claims": [
    {
@@ -9,7 +9,7 @@
  ],
  "claims": [
    {
-      "name": "the-artifact-store",
+      "name": "mesh-artifact-store",
      "scope": "mesh"
    }
  ],
@@ -59,7 +59,10 @@
      ],
      "volumes": [
        "/var/lib/mesh-registry:/var/lib/registry"
-      ]
+      ],
+      "env": {
+        "REGISTRY_STORAGE_DELETE_ENABLED": "true"
+      }
    }
  ]
 }
@@ -1,51 +1,236 @@
-// fail2ban's own code, in the module (novox/hq ADR 0039). The jails and the daemon are declared
-// resources — the mesh writes /etc/fail2ban/jail.d/* and keeps fail2ban.service running (see
-// module.json). This code exists only to read and steer the *live* state the daemon owns at
-// runtime: which IPs are banned right now, and the manual ban/unban an operator reaches for. That
-// state (the running bans, /var/lib/fail2ban's sqlite) is fail2ban's, not the mesh's — the mesh
-// reconciles the config, never the ban list.
+// fail2ban's own code, in the module (novox/hq ADR 0039). The jails are composed by the mesh from
+// the modules a machine runs (to-be 31) and written as declared resources; the daemon is kept
+// running by one. This code exists only to read and steer the *live* state the daemon owns: who is
+// banned now and until when, and the ban or release an operator asks for — the node-intrusion-
+// prevention seat's four verbs (ADR 0179). The daemon's state is fail2ban's, not the mesh's: the
+// mesh composes the jails and never writes the ban list.
+//
+// Spoken through fail2ban-client over the daemon's socket. Client and daemon come from the one
+// package this module declares on the machine, and the socket is root's: root is the module's
+// concern (ADR 0175 §4), and the runtime loading this bundle runs as the operator's account (to-be
+// 38 WP4), so the client is run through sudo without a prompt where the account is not root.

 import { execFile } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+import { isIP } from "node:net";
+import { delimiter, join } from "node:path";
 import { promisify } from "node:util";

-const run = promisify(execFile);
+const execFileP = promisify(execFile);
+
+/** A command runner, so the verbs can be tested without a daemon. */
+export type Runner = (cmd: string, args: string[]) => Promise<string>;
+
+/** The command as it is run: as given when this process is root, else through sudo without a
+ *  prompt. The daemon's socket answers only to root. */
+export function escalated(cmd: string, args: string[], uid: number | undefined = process.getuid?.()): [string, string[]] {
+  if (uid === 0) return [cmd, args];
+  return ["sudo", ["-n", cmd, ...args]];
+}
+
+/** Whether a tool is on this machine: an executable of that name on the path, or where the
+ *  system keeps its administration. */
+export function installed(tool: string, path: string = process.env.PATH ?? ""): boolean {
+  const dirs = [...path.split(delimiter), "/usr/sbin", "/sbin", "/usr/bin"].filter((d) => d !== "");
+  return dirs.some((dir) => {
+    try {
+      accessSync(join(dir, tool), constants.X_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+}
+
+export const execRunner: Runner = async (cmd, args) => {
+  if (!installed(cmd)) throw new Error(`${cmd} is not installed on this machine`);
+  const [program, argv] = escalated(cmd, args);
+  try {
+    const { stdout } = await execFileP(program, argv, { maxBuffer: 16 * 1024 * 1024 });
+    return stdout;
+  } catch (err) {
+    const e = err as { code?: string | number; stderr?: string; stdout?: string; message?: string };
+    const said = `${e.stdout ?? ""}${e.stderr ?? ""}`.trim();
+    // What failed is named by how it failed: sudo missing is a spawn error, sudo refusing speaks
+    // on its own stderr line, and the rest is the client's own answer.
+    if (program === "sudo") {
+      if (e.code === "ENOENT") throw new Error(`${cmd} needs root, and sudo is not installed here for the runtime's account to escalate with`);
+      if (/^sudo:/m.test(said)) throw new Error(`${cmd} needs root and the runtime's account may not run it without a prompt: ${said}`);
+    }
+    if (/Failed to access socket path|Is fail2ban running|Permission denied to socket/i.test(said)) {
+      throw new Error("fail2ban is not running on this machine, or its socket does not answer the runtime's account");
+    }
+    // fail2ban-client's own last line is the one a person reads ("Sorry but the jail 'x' does not exist").
+    const lines = said.split("\n").map((l) => l.trim()).filter(Boolean);
+    throw new Error(lines.length ? lines[lines.length - 1] : (e.message ?? `${cmd} failed`));
+  }
+};
+
+/** One jail as the daemon reports it. */
+export interface JailStatus {
+  jail: string;
+  /** What the jail is reading: files or journal matches, as fail2ban names them. */
+  watching: string[];
+  /** Addresses with failures counted against them right now, and all failures since the jail started. */
+  failing: { now: number; total: number };
+  /** Addresses held right now, and all bans since the jail started. */
+  banned: { now: number; total: number; addresses: string[] };
+}
+
+/** One ban as the daemon holds it. */
+export interface Ban {
+  ip: string;
+  jail: string;
+  /** When the ban was placed, in the machine's local time as fail2ban prints it. */
+  since: string;
+  /** When the ban ends; "never" for a permanent ban. */
+  until: string;
+}
+
+export interface JailSettings {
+  jail: string;
+  bantime: string;
+  findtime: string;
+  maxretry: number;
+  ignoreip: string[];
+  actions: string[];
+  /** The log files the jail reads, when it reads files. */
+  logpath: string[];
+  /** The journal match the jail reads, when it reads the journal. */
+  journalmatch: string;
+}

 export class Fail2banClient {
-  static fromEnv(_env: NodeJS.ProcessEnv = process.env): Fail2banClient {
+  private readonly run: Runner;
+
+  constructor(run: Runner = execRunner) {
+    this.run = run;
+  }
+
+  /** The daemon as this machine has it, through its own client. */
+  static onThisMachine(): Fail2banClient {
    return new Fail2banClient();
  }

-  /** Overview of every jail, or the detailed status of one — currently-banned IPs and totals. */
-  async status(jail?: string): Promise<string> {
+  private client(...args: string[]): Promise<string> {
+    return this.run("fail2ban-client", args);
+  }
+
+  /** The jails the daemon runs, by name. */
+  async jails(): Promise<string[]> {
+    const out = await this.client("status");
+    const m = out.match(/Jail list:\s*(.*)/);
+    if (!m) return [];
+    return m[1].split(",").map((j) => j.trim()).filter(Boolean);
+  }
+
+  /** Every jail with what it watches and holds, or one jail's detail. */
+  async status(jail?: string): Promise<{ jails: JailStatus[] }> {
+    const names = jail ? [jail] : await this.jails();
+    const jails: JailStatus[] = [];
+    for (const name of names) {
+      jails.push(parseJailStatus(name, await this.client("status", name)));
+    }
+    return { jails };
+  }
+
+  /** Every address banned now, with the jail holding it and when the ban ends. */
+  async banned(jail?: string): Promise<{ banned: Ban[] }> {
+    const names = jail ? [jail] : await this.jails();
+    const banned: Ban[] = [];
+    for (const name of names) {
+      banned.push(...parseBans(name, await this.client("get", name, "banip", "--with-time")));
+    }
+    banned.sort((a, b) => a.until.localeCompare(b.until) || a.ip.localeCompare(b.ip));
+    return { banned };
+  }
+
+  /** Ban one address in one jail now. The daemon's own answer is how many addresses it added. */
+  async ban(ip: string, jail: string): Promise<{ banned: Ban | null; added: number }> {
+    address(ip);
+    name(jail);
+    const out = await this.client("set", jail, "banip", ip);
+    const added = Number.parseInt(out.trim(), 10) || 0;
+    const held = (await this.banned(jail)).banned.find((b) => b.ip === ip) ?? null;
+    return { banned: held, added };
+  }
+
+  /** Let one address go, from one jail or from every jail. The daemon's answer is how many it released. */
+  async unban(ip: string, jail?: string): Promise<{ released: number; ip: string; jail: string | "every jail" }> {
+    address(ip);
+    let out: string;
    if (jail) {
-      const { stdout } = await run("sudo", ["fail2ban-client", "status", jail]);
-      return stdout;
+      name(jail);
+      out = await this.client("set", jail, "unbanip", ip);
+    } else {
+      out = await this.client("unban", ip);
    }
-    const { stdout: overview } = await run("sudo", ["fail2ban-client", "status"]);
-    const match = overview.match(/Jail list:\s*(.+)/);
-    if (!match) return overview;
-
-    const jails = match[1].split(",").map((j) => j.trim()).filter(Boolean);
-    const parts: string[] = [overview.trimEnd(), ""];
-    for (const j of jails) {
-      const { stdout } = await run("sudo", ["fail2ban-client", "status", j]);
-      parts.push(`=== ${j} ===`, stdout.trimEnd(), "");
-    }
-    return parts.join("\n");
+    return { released: Number.parseInt(out.trim(), 10) || 0, ip, jail: jail ?? "every jail" };
  }

-  /** Manually ban an IP in a jail. Mutates live state, not a mesh-managed file. */
-  async ban(jail: string, ip: string): Promise<string> {
-    const { stdout } = await run("sudo", ["fail2ban-client", "set", jail, "banip", ip]);
-    return stdout;
-  }
-
-  /** Unban an IP from one jail, or from every jail when no jail is given. */
-  async unban(ip: string, jail?: string): Promise<string> {
-    const args = jail
-      ? ["fail2ban-client", "set", jail, "unbanip", ip]
-      : ["fail2ban-client", "unban", ip];
-    const { stdout } = await run("sudo", args);
-    return stdout;
+  /** One jail's effective settings — the module's own tool, beside the seat's verbs. */
+  async settings(jail: string): Promise<JailSettings> {
+    name(jail);
+    const get = (key: string) => this.client("get", jail, key);
+    const [bantime, findtime, maxretry, ignoreip, actions, logpath, journalmatch] = await Promise.all([
+      get("bantime"), get("findtime"), get("maxretry"), get("ignoreip"), get("actions"), get("logpath"),
+      get("journalmatch"),
+    ]);
+    return {
+      jail,
+      bantime: bantime.trim(),
+      findtime: findtime.trim(),
+      maxretry: Number.parseInt(maxretry.trim(), 10),
+      ignoreip: listed(ignoreip),
+      actions: actions.split("\n").slice(1).map((l) => l.trim()).filter(Boolean),
+      logpath: /No file is currently monitored/.test(logpath) ? [] : listed(logpath),
+      journalmatch: journalmatch.split("\n").slice(1).map((l) => l.trim()).filter(Boolean).join(" "),
+    };
  }
 }
+
+/** fail2ban's tree listings: lines like "|- 127.0.0.0/8" and "`- ::1", after a heading. */
+function listed(out: string): string[] {
+  return out
+    .split("\n")
+    .map((l) => l.replace(/^[\s|`-]+/, "").trim())
+    .filter((l, i) => i > 0 && l.length > 0);
+}
+
+export function parseJailStatus(jail: string, out: string): JailStatus {
+  const field = (label: string) => {
+    const m = out.match(new RegExp(label.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + ":\\t?\\s*(.*)"));
+    return m ? m[1].trim() : "";
+  };
+  const num = (label: string) => Number.parseInt(field(label), 10) || 0;
+  const watching = [field("File list"), field("Journal matches")].filter(Boolean);
+  return {
+    jail,
+    watching,
+    failing: { now: num("Currently failed"), total: num("Total failed") },
+    banned: {
+      now: num("Currently banned"),
+      total: num("Total banned"),
+      addresses: field("Banned IP list").split(/\s+/).filter(Boolean),
+    },
+  };
+}
+
+/** `get <jail> banip --with-time` prints one ban per line: "IP \tsince + seconds = until". */
+export function parseBans(jail: string, out: string): Ban[] {
+  const bans: Ban[] = [];
+  for (const line of out.split("\n")) {
+    const m = line.match(/^(\S+)\s+(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}) \+ (-?\d+) = (\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}|\S+)/);
+    if (!m) continue;
+    bans.push({ ip: m[1], jail, since: m[2], until: Number(m[3]) < 0 ? "never" : m[4] });
+  }
+  return bans;
+}
+
+function address(ip: string): void {
+  if (!isIP(ip)) throw new Error(`${JSON.stringify(ip)} is not an address`);
+}
+
+function name(jail: string): void {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(jail)) throw new Error(`${JSON.stringify(jail)} is not a jail's name`);
+}
@@ -7,9 +7,22 @@
  "claims": [
    {
      "name": "node-intrusion-prevention",
-      "scope": "node"
+      "scope": "node",
+      "serves": [
+        "status",
+        "banned",
+        "ban",
+        "unban"
+      ]
    }
  ],
+  "tools": [
+    "fail2ban_settings"
+  ],
+  "jailing": {
+    "into": "/etc/fail2ban/jail.d/mesh.conf",
+    "filter-into": "/etc/fail2ban/filter.d"
+  },
  "resources": [
    {
      "id": "package",
@@ -28,19 +41,31 @@
      "path": "/etc/fail2ban/action.d",
      "mode": "0755"
    },
+    {
+      "id": "filter-d",
+      "type": "directory",
+      "path": "/etc/fail2ban/filter.d",
+      "mode": "0755"
+    },
+    {
+      "id": "run-dir",
+      "type": "directory",
+      "path": "/var/run/fail2ban",
+      "mode": "0755"
+    },
    {
      "id": "jail-local",
      "type": "file",
      "path": "/etc/fail2ban/jail.local",
      "mode": "0644",
-      "content": "[INCLUDES]\n\nbefore = paths-arch.conf\n\n[DEFAULT]\n\n# Never act on the machine itself or on a tunnel peer: the mesh's private range is\n# ${machine:mesh-range}, named here rather than written as a value the module cannot\n# know (novox/hq ADR 0112). Without this, fail2ban could ban the mesh's own nodes.\nignoreip = 127.0.0.1/8 ::1 ${machine:mesh-range}\n\nbantime  = 10m\nfindtime = 10m\nmaxretry = 5\n\n# Ban through iptables, not through a firewall front-end the machine may not have. ufw is\n# installed on two of this mesh's machines and absent on the other two, and fail2ban finds out\n# only at ban time: the service reports healthy, the jail counts the attempt, the ban command\n# exits 127, and nothing is blocked. Proven on 2026-09-28 -- 'ufw: command not found' on a\n# machine the mesh reported as protected.\n#\n# The action below is this module's own, already used by the recidive jail on every machine\n# here, and it bans in DOCKER-USER as well as INPUT, so a container's published port is\n# covered too.\nbanaction = iptables-allports-dualchain\nbanaction_allports = iptables-allports-dualchain\n\n[sshd]\nenabled = true\nport    = ssh\nlogpath = %(sshd_log)s\nbackend = %(sshd_backend)s\n"
+      "content": "[INCLUDES]\n\nbefore = paths-arch.conf\n\n[DEFAULT]\n\n# Never act on the machine itself or on a tunnel peer: the mesh's private range is\n# ${machine:mesh-range}, named here rather than written as a value the module cannot\n# know (novox/hq ADR 0112). Without this, fail2ban could ban the mesh's own nodes.\n# **A ban list never holds a neighbour.** The mesh's own range is named rather than written\n# (novox/hq ADR 0112), and every private range beside it: a source on one is somebody's own\n# network, not the internet. On a machine behind a router that reflects local traffic, every\n# client in the house arrives as the gateway's address — so one mistyped local request banned\n# 192.168.1.1 on the home server and would have cut the whole house off from it (ADR 0186).\nignoreip = 127.0.0.1/8 ::1 ${machine:mesh-range} 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16 169.254.0.0/16 fc00::/7 fe80::/10\n\n# Three failures in a day ban for a day (novox/hq ADR 0179). The attackers this mesh sees pace\n# themselves at one try every ten minutes, under any ten-minute window; a day's window counts\n# them, and a day's ban costs a person who mistyped three times once, from one address, while\n# the mesh's own range is never banned at all.\nbantime  = 1d\nfindtime = 1d\nmaxretry = 3\n\n# Ban through iptables, not through a firewall front-end the machine may not have. ufw is\n# installed on two of this mesh's machines and absent on the other two, and fail2ban finds out\n# only at ban time: the service reports healthy, the jail counts the attempt, the ban command\n# exits 127, and nothing is blocked. Proven on 2026-09-28 -- 'ufw: command not found' on a\n# machine the mesh reported as protected.\n#\n# The action below is this module's own, already used by the recidive jail on every machine\n# here, and it bans in DOCKER-USER as well as INPUT, so a container's published port is\n# covered too.\nbanaction = iptables-allports-dualchain\nbanaction_allports = iptables-allports-dualchain\n\n[sshd]\nenabled = true\nport    = ssh\nlogpath = %(sshd_log)s\nbackend = %(sshd_backend)s\n"
    },
    {
      "id": "jail-sshd",
      "type": "file",
      "path": "/etc/fail2ban/jail.d/sshd.conf",
      "mode": "0644",
-      "content": "[sshd]\nenabled = true\nport    = ssh\nlogpath = %(sshd_log)s\nbackend = %(sshd_backend)s\nmaxretry = 5\n"
+      "content": "[sshd]\nenabled = true\nport    = ssh\nlogpath = %(sshd_log)s\nbackend = %(sshd_backend)s\nmaxretry = 3\nfindtime = 1d\nbantime  = 1d\n"
    },
    {
      "id": "log",
@@ -55,7 +80,7 @@
      "type": "file",
      "path": "/etc/fail2ban/jail.d/recidive.conf",
      "mode": "0644",
-      "content": "[recidive]\nenabled = true\nlogpath  = /var/log/fail2ban.log\n# Ban in both INPUT (host services like SSH) and DOCKER-USER (container services)\nbanaction = iptables-allports-dualchain\nbantime  = 1w\nfindtime = 1d\n"
+      "content": "[recidive]\nenabled = true\nlogpath  = /var/log/fail2ban.log\n# Ban in both INPUT (host services like SSH) and DOCKER-USER (container services)\nbanaction = iptables-allports-dualchain\n# Banned twice in two weeks, by any jail, is banned for four (novox/hq ADR 0179).\nbantime  = 4w\nfindtime = 2w\nmaxretry = 2\n"
    },
    {
      "id": "action-dualchain",
@@ -81,8 +106,21 @@
        "jail-local",
        "jail-sshd",
        "jail-recidive",
-        "action-dualchain"
+        "action-dualchain",
+        "composed-jails"
      ]
    }
-  ]
+  ],
+  "build": {
+    "artifacts": [
+      {
+        "name": "tools",
+        "kind": "bundle",
+        "language": "typescript",
+        "entrypoints": [
+          "tools/index.js"
+        ]
+      }
+    ]
+  }
 }
@@ -1,14 +1,18 @@
 {
  "name": "@novox/module-fail2ban",
  "version": "0.1.0",
-  "description": "fail2ban — intrusion prevention: the mesh declares the jails and keeps the daemon running; its ban/unban/status tools live here.",
+  "description": "fail2ban \u2014 intrusion prevention: the mesh composes the jails and keeps the daemon running; this module holds the node-intrusion-prevention seat and serves its verbs status, banned, ban and unban (novox/hq to-be 31, ADR 0179).",
  "type": "module",
  "private": true,
  "dependencies": {
-    "@novox/mesh-sdk": "^0.1.0"
+    "@novox/mesh-sdk": "^0.1.1"
  },
  "devDependencies": {
    "@types/node": "^22.0.0",
    "typescript": "^5.6.0"
+  },
+  "scripts": {
+    "build": "tsc client.ts tools/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --rootDir . --outDir dist",
+    "test": "node --test --experimental-strip-types 'test/*.test.ts'"
  }
 }
@@ -0,0 +1,114 @@
+// The intrusion prevention's verbs over a fake daemon, with the shapes fail2ban-client 1.1.0 printed
+// on the control node on 2026-10-02 (novox/hq ADR 0179).
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { Fail2banClient, escalated, installed, parseBans, parseJailStatus, type Runner } from "../client.ts";
+
+const STATUS = "Status\n|- Number of jail:\t2\n`- Jail list:\trecidive, sshd\n";
+const RECIDIVE =
+  "Status for the jail: recidive\n|- Filter\n|  |- Currently failed:\t36\n|  |- Total failed:\t149\n" +
+  "|  `- File list:\t/var/log/fail2ban.log\n`- Actions\n   |- Currently banned:\t9\n   |- Total banned:\t13\n" +
+  "   `- Banned IP list:\t195.178.110.30 45.148.10.240 92.118.39.71\n";
+const SSHD =
+  "Status for the jail: sshd\n|- Filter\n|  |- Currently failed:\t5\n|  |- Total failed:\t11776\n" +
+  "|  `- Journal matches:\t_SYSTEMD_UNIT=sshd.service + _COMM=sshd\n`- Actions\n   |- Currently banned:\t0\n" +
+  "   |- Total banned:\t150\n   `- Banned IP list:\t\n";
+const WITH_TIME =
+  "195.178.110.30 \t2026-09-26 23:18:47 + 604800 = 2026-10-03 23:18:47\n" +
+  "92.118.39.71 \t2026-09-28 10:33:49 + 604800 = 2026-10-05 10:33:49\n";
+
+function fake(answers: Record<string, string>, calls: string[][] = []): Runner {
+  return async (cmd, args) => {
+    calls.push([cmd, ...args]);
+    const key = args.join(" ");
+    if (key in answers) return answers[key];
+    throw new Error(`unexpected ${cmd} ${key}`);
+  };
+}
+
+test("a jail's status is read into numbers, what it watches and who it holds", () => {
+  const s = parseJailStatus("recidive", RECIDIVE);
+  assert.deepEqual(s, {
+    jail: "recidive",
+    watching: ["/var/log/fail2ban.log"],
+    failing: { now: 36, total: 149 },
+    banned: { now: 9, total: 13, addresses: ["195.178.110.30", "45.148.10.240", "92.118.39.71"] },
+  });
+  const j = parseJailStatus("sshd", SSHD);
+  assert.deepEqual(j.watching, ["_SYSTEMD_UNIT=sshd.service + _COMM=sshd"]);
+  assert.deepEqual(j.banned, { now: 0, total: 150, addresses: [] });
+});
+
+test("status covers every jail the daemon lists, or the one named", async () => {
+  const calls: string[][] = [];
+  const f = new Fail2banClient(fake({ status: STATUS, "status recidive": RECIDIVE, "status sshd": SSHD }, calls));
+  const all = await f.status();
+  assert.deepEqual(all.jails.map((j) => j.jail), ["recidive", "sshd"]);
+  const one = await f.status("sshd");
+  assert.equal(one.jails.length, 1);
+  assert.deepEqual(calls[calls.length - 1], ["fail2ban-client", "status", "sshd"]);
+});
+
+test("bans are read with when they were placed and when they end, a permanent one as never", () => {
+  const bans = parseBans("recidive", WITH_TIME + "203.0.113.9 \t2026-10-01 00:00:00 + -1 = never\n");
+  assert.equal(bans.length, 3);
+  assert.deepEqual(bans[0], { ip: "195.178.110.30", jail: "recidive", since: "2026-09-26 23:18:47", until: "2026-10-03 23:18:47" });
+  assert.equal(bans[2].until, "never");
+  assert.deepEqual(parseBans("sshd", "\n"), []);
+});
+
+test("banned gathers every jail's bans, soonest to end first", async () => {
+  const f = new Fail2banClient(fake({
+    status: STATUS,
+    "get recidive banip --with-time": WITH_TIME,
+    "get sshd banip --with-time": "198.51.100.7 \t2026-10-02 15:06:58 + 600 = 2026-10-02 15:16:58\n",
+  }));
+  const { banned } = await f.banned();
+  assert.deepEqual(banned.map((b) => `${b.ip}@${b.jail}`), ["198.51.100.7@sshd", "195.178.110.30@recidive", "92.118.39.71@recidive"]);
+});
+
+test("ban asks the daemon by jail and answers with the ban as held; a non-address is refused before anything runs", async () => {
+  const calls: string[][] = [];
+  const f = new Fail2banClient(fake({
+    "set recidive banip 198.51.100.7": "1\n",
+    "get recidive banip --with-time": WITH_TIME + "198.51.100.7 \t2026-10-02 17:00:00 + 604800 = 2026-10-09 17:00:00\n",
+  }, calls));
+  const r = await f.ban("198.51.100.7", "recidive");
+  assert.equal(r.added, 1);
+  assert.equal(r.banned?.until, "2026-10-09 17:00:00");
+  assert.deepEqual(calls[0], ["fail2ban-client", "set", "recidive", "banip", "198.51.100.7"]);
+  await assert.rejects(() => f.ban("not-an-ip", "recidive"), /is not an address/);
+  await assert.rejects(() => f.ban("198.51.100.7", "a jail; rm"), /is not a jail's name/);
+  assert.equal(calls.length, 2);
+});
+
+test("unban releases from one jail or from every jail", async () => {
+  const calls: string[][] = [];
+  const f = new Fail2banClient(fake({ "set sshd unbanip 198.51.100.7": "1\n", "unban 198.51.100.7": "2\n" }, calls));
+  assert.deepEqual(await f.unban("198.51.100.7", "sshd"), { released: 1, ip: "198.51.100.7", jail: "sshd" });
+  assert.deepEqual(await f.unban("198.51.100.7"), { released: 2, ip: "198.51.100.7", jail: "every jail" });
+  assert.deepEqual(calls[1], ["fail2ban-client", "unban", "198.51.100.7"]);
+});
+
+test("a jail's settings are read from the daemon's listings", async () => {
+  const f = new Fail2banClient(fake({
+    "get sshd bantime": "86400\n", "get sshd findtime": "86400\n", "get sshd maxretry": "3\n",
+    "get sshd ignoreip": "These IP addresses/networks are ignored:\n|- 127.0.0.0/8\n|- 10.10.0.0/24\n`- ::1\n",
+    "get sshd actions": "The jail sshd has the following actions:\niptables-allports-dualchain\n",
+    "get sshd logpath": "No file is currently monitored\n",
+    "get sshd journalmatch": "Current match filter:\n_SYSTEMD_UNIT=sshd.service + _COMM=sshd\n",
+  }));
+  assert.deepEqual(await f.settings("sshd"), {
+    jail: "sshd", bantime: "86400", findtime: "86400", maxretry: 3,
+    ignoreip: ["127.0.0.0/8", "10.10.0.0/24", "::1"], actions: ["iptables-allports-dualchain"],
+    logpath: [], journalmatch: "_SYSTEMD_UNIT=sshd.service + _COMM=sshd",
+  });
+});
+
+test("the client runs as given by root and through sudo without a prompt by anyone else", () => {
+  assert.deepEqual(escalated("fail2ban-client", ["status"], 0), ["fail2ban-client", ["status"]]);
+  assert.deepEqual(escalated("fail2ban-client", ["set", "sshd", "banip", "198.51.100.7"], 1000),
+    ["sudo", ["-n", "fail2ban-client", "set", "sshd", "banip", "198.51.100.7"]]);
+  assert.equal(installed("sh"), true);
+  assert.equal(installed("no-such-client-of-the-mesh"), false);
+});
@@ -1,55 +1,62 @@
-// fail2ban's tools — reading and steering the live ban state. The jails themselves are declared
-// resources (module.json); these three touch what the running daemon holds: what is banned now,
-// and the manual ban/unban an operator reaches for. The daemon's state is fail2ban's own, so this
-// is the only way to see or change it — the mesh reconciles the config, not the bans.
+// The intrusion prevention's tools: the node-intrusion-prevention seat's four verbs — who is banned,
+// the jails' state, ban one, let one go — and the module's own reading of a jail's settings
+// (novox/hq to-be 31, ADR 0179). The jails themselves are composed by the mesh from the modules a
+// machine runs and written as declared resources; these touch only what the running daemon holds.

 import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
 import { Fail2banClient } from "../client.js";

-export function getFail2banTools(fail2ban: Fail2banClient): ToolDefinition[] {
+export function getSeatVerbs(fail2ban: Fail2banClient): ToolDefinition[] {
  return [
    {
-      name: "fail2ban_status",
+      name: "status",
      description:
-        "fail2ban status on this node — the jails and their live bans. Omit `jail` for every jail, or name one for its detail.",
-      input: {
-        type: "object",
-        properties: {
-          jail: {
-            type: "string",
-            description: "A specific jail (e.g. sshd, recidive); omit for the overview of all jails.",
-          },
-        },
-      },
-      run: async (args) => ({ status: await fail2ban.status(args.jail as string | undefined) }),
+        "Every jail on this machine with what it watches, how many addresses it is counting failures against and holding now, and the totals since it started; one jail's detail when named.",
+      input: { jail: { type: "string", description: "one jail (optional)" } },
+      run: async (args) => fail2ban.status(args.jail ? String(args.jail) : undefined),
    },
    {
-      name: "fail2ban_ban",
-      description: "Manually ban an IP address in a jail — a live change to the running daemon, not a mesh-managed file.",
-      input: {
-        type: "object",
-        properties: {
-          jail: { type: "string", description: "Jail name (e.g. sshd, recidive)." },
-          ip: { type: "string", description: "IP address to ban." },
-        },
-        required: ["jail", "ip"],
-      },
-      run: async (args) => ({ result: await fail2ban.ban(args.jail as string, args.ip as string) }),
+      name: "banned",
+      description: "Every address banned on this machine right now, with the jail that holds it, when it was banned and when the ban ends.",
+      input: { jail: { type: "string", description: "one jail (optional)" } },
+      run: async (args) => fail2ban.banned(args.jail ? String(args.jail) : undefined),
    },
    {
-      name: "fail2ban_unban",
-      description: "Unban an IP address from one jail, or from every jail when `jail` is omitted.",
+      name: "ban",
+      description:
+        "Ban one address in one jail now, for the jail's ban time — an operator's act on the live ban list, which the mesh never writes itself.",
      input: {
-        type: "object",
-        properties: {
-          ip: { type: "string", description: "IP address to unban." },
-          jail: { type: "string", description: "A specific jail; omit to unban from all jails." },
-        },
-        required: ["ip"],
+        ip: { type: "string", description: "the address" },
+        jail: { type: "string", description: "the jail to hold it (recidive for the long ban)" },
      },
-      run: async (args) => ({ result: await fail2ban.unban(args.ip as string, args.jail as string | undefined) }),
+      run: async (args) => fail2ban.ban(String(args.ip ?? ""), String(args.jail ?? "")),
+    },
+    {
+      name: "unban",
+      description: "Let one address go, from one jail or from every jail when none is named.",
+      input: {
+        ip: { type: "string", description: "the address" },
+        jail: { type: "string", description: "one jail (optional)" },
+      },
+      run: async (args) => fail2ban.unban(String(args.ip ?? ""), args.jail ? String(args.jail) : undefined),
    },
  ];
 }

-registerModuleTools("fail2ban", () => getFail2banTools(Fail2banClient.fromEnv()));
+export function getFail2banTools(fail2ban: Fail2banClient): ToolDefinition[] {
+  return [
+    {
+      name: "fail2ban_settings",
+      description:
+        "One jail's effective settings on this machine: ban time, window, tries, the addresses it never bans, its actions and what it reads.",
+      input: { jail: { type: "string", description: "the jail" } },
+      run: async (args) => fail2ban.settings(String(args.jail ?? "")),
+    },
+  ];
+}
+
+const fail2ban = Fail2banClient.onThisMachine();
+// The seat's verbs under the seat's name: the runtime serves them on the seat's subjects where this
+// module holds it (ADR 0159, 0160). The module's own under its own.
+registerModuleTools("node-intrusion-prevention", () => getSeatVerbs(fail2ban));
+registerModuleTools("fail2ban", () => getFail2banTools(fail2ban));
@@ -1,37 +0,0 @@
-# gitea's runtime: the tool runtime, carrying this module's compiled provisioner, tools and event
-# consumer.
-#
-# **Built from this module's own directory and nothing else.** The sdk is in the base image, so
-# nothing is copied out of a neighbouring checkout — which is what lets the mesh build this from a
-# repository and a path (novox/hq ADR 0069) rather than only on a workstation that happens to have
-# the siblings.
-#
-# Two bases, named rather than pinned: the image this is COMPILED in, and the image it RUNS in.
-# They are different images on purpose — the first carries a compiler and the second must not, or
-# every running container would carry one it never invokes. The mesh answers both with the copies it
-# holds, because a fingerprint written here would name one particular copy and no other mesh has it
-# (novox/hq issue 044). Declared in module.json's `build.on`; deliberately no defaults, so a build
-# nobody told stops here and says which module to build first.
-ARG BUILD_BASE
-ARG RUNTIME_BASE
-
-FROM ${BUILD_BASE} AS build
-# Compiled under /app/modules so `@novox/mesh-sdk` resolves upward into the base's own
-# node_modules — the module is compiled against exactly the sdk it will run against.
-WORKDIR /app/modules/gitea
-COPY . .
-# The compiler is invoked by its real path rather than through node_modules/.bin, whose entries are
-# symlinks to a launcher that requires its library relatively — resolved away when the base image
-# was assembled.
-RUN node /app/node_modules/typescript/bin/tsc client.ts token.ts index.ts provisioner/index.ts tools/index.ts \
-      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
-
-FROM ${RUNTIME_BASE}
-# **No apt packages.** gitea's provisioner talks to the forge over HTTP (the gitea REST API), not
-# through a CLI the way postgres drives psql — so the runtime base holds everything this needs.
-COPY --from=build /app/modules/gitea/dist /app/modules/gitea/dist
-# What a tool host should load from this module: its event consumer and its tools, which are
-# separate entrypoints because they are loaded by different things. The provisioner is the third,
-# and is not listed here — the declaration names it in the container's `args`, because it is what
-# this module's own container runs. One image, because they are one module and share a client.
-ENV MESH_TOOL_MODULES=/app/modules/gitea/dist/index.js,/app/modules/gitea/dist/tools/index.js,/app/modules/gitea/dist/provisioner/index.js
@@ -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;
@@ -95,6 +103,13 @@ export class GiteaClient {
    if (res.status === 401) {
      token = await this.tokens.renew(token);
      res = await this.send(path, options, token);
+    } else if (res.status === 403) {
+      // A kept token minted before a scope was added lacks it. The forge says so; the source
+      // re-mints with the whole list and the call is retried once. Any other 403 stays a 403.
+      const text = await res.text();
+      if (!MintedToken.lacksScope(res.status, text)) throw new Error(`Gitea API ${path}: 403 ${text}`);
+      token = await this.tokens.renew(token);
+      res = await this.send(path, options, token);
    }
    if (!res.ok) throw new Error(`Gitea API ${path}: ${res.status} ${await res.text()}`);
    if (res.status === 204) return null as T;
@@ -250,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",
@@ -85,20 +85,17 @@
      "scope": "mesh"
    }
  ],
-  "own-secrets": {
-    "broker": "/var/lib/mesh/gitea/broker"
-  },
  "resources": [
    {
      "id": "mesh-state",
      "type": "directory",
-      "path": "/var/lib/mesh/gitea",
-      "mode": "0700"
+      "mode": "0700",
+      "place": "mesh"
    },
    {
      "id": "runtime-state",
      "type": "directory",
-      "path": "/var/lib/mesh/gitea/state",
+      "path": "${dir:mesh-state}/state",
      "mode": "0700"
    },
    {
@@ -145,7 +142,8 @@
      "volumes": [
        "${dir:data}:/data"
      ],
-      "secrets-in-environment": "gitea honours GITEA__database__PASSWD__FILE and GITEA__security__INTERNAL_TOKEN__FILE; convertible, awaiting a bed that proves it"
+      "secrets-in-environment": "gitea honours GITEA__database__PASSWD__FILE and GITEA__security__INTERNAL_TOKEN__FILE; convertible, awaiting a bed that proves it",
+      "logging": "journald"
    },
    {
      "id": "admin-bootstrap",
@@ -175,36 +173,10 @@
    {
      "id": "runtime-config",
      "type": "file",
-      "path": "/var/lib/mesh/gitea/config.json",
+      "path": "${dir:mesh-state}/config.json",
      "mode": "0600",
      "content": "{}\n",
      "merge": "json"
-    },
-    {
-      "id": "runtime",
-      "type": "container",
-      "name": "mesh-gitea",
-      "network": "host",
-      "volumes": [
-        "/var/lib/mesh/gitea/broker:/run/secrets/broker:ro",
-        "/var/lib/mesh/gitea/config.json:/run/config/config.json:ro",
-        "${dir:grants}:${dir:grants}:ro",
-        "${dir:state}/admin.secret:/run/secrets/admin:ro",
-        "/var/lib/mesh/gitea/state:/run/state"
-      ],
-      "env": {
-        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_GITEA_URL": "http://127.0.0.1:${port:3000}",
-        "MESH_GITEA_CONFIG_FILE": "/run/config/config.json",
-        "MESH_GITEA_ADMIN_USER": "mesh-admin",
-        "MESH_GITEA_ADMIN_PASSWORD_FILE": "/run/secrets/admin",
-        "MESH_GITEA_STATE_DIR": "/run/state",
-        "MESH_RECEIVES": "${dir:grants}/npm.json"
-      },
-      "artifact": "runtime",
-      "restart-on": [
-        "runtime-config"
-      ]
    }
  ],
  "provides": [
@@ -218,24 +190,37 @@
    }
  ],
  "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"
+        "name": "code",
+        "kind": "bundle",
+        "language": "typescript",
+        "entrypoints": [
+          "index.js",
+          "tools/index.js",
+          "provisioner/index.js"
+        ],
+        "loads": [
+          "index.js",
+          "tools/index.js",
+          "provisioner/index.js"
+        ],
+        "env": {
+          "MESH_GITEA_URL": "http://127.0.0.1:${port:3000}",
+          "MESH_GITEA_CONFIG_FILE": "${dir:mesh-state}/config.json",
+          "MESH_GITEA_ADMIN_USER": "mesh-admin",
+          "MESH_GITEA_ADMIN_PASSWORD_FILE": "${dir:state}/admin.secret",
+          "MESH_GITEA_STATE_DIR": "${dir:runtime-state}",
+          "MESH_RECEIVES": "${dir:grants}/npm.json"
+        }
      }
    ]
-  }
+  },
+  "jails": [
+    {
+      "name": "gitea",
+      "failregex": "^.*Failed authentication attempt for .* from <HOST>(?::\\d+)?\\s*$\n            ^.*Invalid user .* from <HOST> port \\d+\\s*$\n            ^.*User \\S+ from <HOST> not allowed because .*$",
+      "jail": "backend = systemd\njournalmatch = CONTAINER_NAME=gitea\nport = http,https,222\nmaxretry = 3\nfindtime = 1d\nbantime = 1d"
+    }
+  ]
 }
@@ -29,7 +29,11 @@ interface Forge {
  mints: number;
  lastScopes: string[] | null;
  tokens: Map<string, string>;
+  scopesOf: Map<string, string[]>;
  admins: Map<string, string>;
+  pullState: string;
+  pullTitle: string;
+  branchDeleted: boolean;
  close(): Promise<void>;
 }

@@ -40,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 =>
@@ -85,6 +92,51 @@ 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.
+      const h = req.headers.authorization ?? "";
+      const value = h.startsWith("token ") ? h.slice(6) : "";
+      if (![...forge.tokens.values()].includes(value)) return json(res, 401, { message: "token is required" });
+      if (!covers(forge.scopesOf.get(value) ?? [], "read:repository")) {
+        return json(res, 403, { message: `token does not have at least one of required scope(s), required=[read:repository]` });
+      }
+      return json(res, 200, {
+        ok: true,
+        data: [{ full_name: "novox/hq", name: "hq", owner: { login: "novox" }, private: true, html_url: "http://fake/novox/hq" }],
+      });
+    }
    if (url.pathname === "/api/v1/user/repos") {
      const h = req.headers.authorization ?? "";
      const value = h.startsWith("token ") ? h.slice(6) : "";
@@ -101,6 +153,21 @@ function fakeForge(): Promise<Forge> {
        { full_name: "novox/hq", name: "hq", owner: { login: "novox" }, private: true, html_url: "http://fake/novox/hq" },
      ]);
    }
+    const adminUser = url.pathname.match(/^\/api\/v1\/admin\/users\/([^/]+)$/);
+    if (adminUser && req.method === "PATCH") {
+      const h = req.headers.authorization ?? "";
+      const value = h.startsWith("token ") ? h.slice(6) : "";
+      if (![...forge.tokens.values()].includes(value)) return json(res, 401, { message: "token is required" });
+      if (!covers(forge.scopesOf.get(value) ?? [], "write:admin")) {
+        return json(res, 403, {
+          message: `token does not have at least one of required scope(s), required=[write:admin]`,
+        });
+      }
+      const login = decodeURIComponent(adminUser[1]);
+      if (login === "untouchable") return json(res, 403, { message: "user untouchable may not be edited" });
+      const patch = await body(req);
+      return json(res, 200, { login, is_admin: patch?.admin === true });
+    }
    return json(res, 404, { message: "no such route in the fake" });
  });
  return new Promise((resolve) => {
@@ -110,7 +177,11 @@ 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,
        close: () => new Promise((r) => server.close(() => r())),
      });
@@ -152,14 +223,14 @@ function minted(env: NodeJS.ProcessEnv, logs: string[]): GiteaClient {
 const forge = await fakeForge();
 after(() => forge.close());

-test("first start: mints with the admin account, keeps the token at 0600, asks for two scopes only", async () => {
+test("first start: mints with the admin account, keeps the token at 0600, asks for the tools' scopes only", async () => {
  const { env, file, logs } = await delivered(forge);

  const repos = await minted(env, logs).listRepos();

  assert.equal(repos[0]?.full_name, "novox/hq");
  assert.equal(forge.mints, 1);
-  assert.deepEqual(forge.lastScopes, ["write:repository", "write:issue", "read:user"]);
+  assert.deepEqual(forge.lastScopes, ["write:repository", "write:issue", "read:user", "write:admin"]);
  assert.deepEqual(forge.lastScopes, [...TOKEN_SCOPES]);
  const token = forge.tokens.get("mesh-tools")!;
  assert.equal(await readFile(file, "utf8"), token + "\n");
@@ -197,6 +268,34 @@ test("the forge rejects the kept token (its data was restored): minted afresh, o
  assert.ok(logs.some((l) => l.startsWith("the forge rejected the kept token")), logs.join("\n"));
 });

+test("a kept token from before write:admin: the forge refuses the admin route for the scope, the token is re-minted with the whole list, and the call goes through", async () => {
+  const { env, file, logs } = await delivered(forge);
+  const client = minted(env, logs);
+  await client.listRepos();
+  const before = forge.mints;
+  const old = forge.tokens.get("mesh-tools")!;
+  forge.scopesOf.set(old, ["write:repository", "write:issue", "read:user"]); // minted by the previous build
+
+  const user = await client.api<{ login: string; is_admin: boolean }>("/admin/users/mesh_novox_builder", {
+    method: "PATCH",
+    body: JSON.stringify({ admin: true }),
+  });
+
+  assert.equal(user.is_admin, true);
+  assert.equal(forge.mints, before + 1);
+  assert.deepEqual(forge.lastScopes, [...TOKEN_SCOPES]);
+  assert.notEqual(forge.tokens.get("mesh-tools"), old);
+  assert.equal(await readFile(file, "utf8"), forge.tokens.get("mesh-tools") + "\n");
+  assert.ok(logs.some((l) => l.startsWith("the forge rejected the kept token")), logs.join("\n"));
+  // A 403 that is not about scopes is the forge's answer, not a reason to mint.
+  const again = forge.mints;
+  await assert.rejects(
+    client.api("/admin/users/untouchable", { method: "PATCH", body: JSON.stringify({ admin: true }) }),
+    /403 .*untouchable/,
+  );
+  assert.equal(forge.mints, again);
+});
+
 test("the kept file is gone but the forge still holds a token by that name: replaced, not refused", async () => {
  const { env, file, logs } = await delivered(forge);
  await minted(env, logs).listRepos();
@@ -301,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",
    ],
@@ -311,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);
+});
@@ -34,15 +34,21 @@ export const TOKEN_NAME = "mesh-tools";
 *                      It sits under the `user` category despite listing repositories, not `repository`
 *                      — confirmed against the running forge (1.27.3), which answered
 *                      `required=[read:user]` to a token carrying only the other two.
- * Nothing under /admin, /orgs or write:user — the escape-hatch tool reaches only what these three cover.
+ *   write:admin      — /admin/users: the forge's own users are the mesh's to settle, such as making
+ *                      the builder's login a site admin so every repository the mesh may build is
+ *                      clonable (novox/hq 229). Nothing under /orgs or write:user.
+ *
+ * A token kept from before a scope was added lacks it: the forge answers such a call with
+ * `403 token does not have at least one of required scope(s)`, and the client treats that like a
+ * 401 — the source re-mints by name, with the whole list, and the call is retried once.
 */
-export const TOKEN_SCOPES: readonly string[] = ["write:repository", "write:issue", "read:user"];
+export const TOKEN_SCOPES: readonly string[] = ["write:repository", "write:issue", "read:user", "write:admin"];

 /** Where a client's token comes from, and what to do when the forge says it is wrong. */
 export interface TokenSource {
  /** The token to authenticate with now; minted, read or configured. */
  current(): Promise<string>;
-  /** The forge answered 401 to `rejected`. A fresh token, or a plain error when there is nothing to renew with. */
+  /** The forge answered 401 to `rejected`, or 403 for a scope it lacks. A fresh token, or a plain error when there is nothing to renew with. */
  renew(rejected: string): Promise<string>;
 }

@@ -170,6 +176,11 @@ export class MintedToken implements TokenSource {
    return this.mint("the forge rejected the kept token — minting a fresh one");
  }

+  /** What the forge's scoped tokens say when a kept token predates a scope the tools now need. */
+  static lacksScope(status: number, body: string): boolean {
+    return status === 403 && /required scope/i.test(body);
+  }
+
  /** One mint at a time: concurrent first calls share it, rather than each minting its own. */
  private mint(why: string): Promise<string> {
    if (this.inflight === null) {
@@ -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",
@@ -1,24 +0,0 @@
-# gitlab's runtime: the tool runtime, carrying this module's compiled code.
-#
-# **Built from this module's own directory and nothing else.** The sdk and the tool runtime are in
-# the base images, published like any other artifact — which is what makes this buildable by the
-# mesh from a repository and a path (novox/hq ADR 0069) rather than only on a workstation that
-# happens to have the siblings.
-#
-# Two bases, named rather than pinned (novox/hq issue 044): the image this is COMPILED in and the
-# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
-ARG BUILD_BASE
-ARG RUNTIME_BASE
-
-FROM ${BUILD_BASE} AS build
-WORKDIR /app/modules/gitlab
-COPY . .
-RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts \
-      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
-
-FROM ${RUNTIME_BASE}
-COPY --from=build /app/modules/gitlab/dist /app/modules/gitlab/dist
-# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
-# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
-# the convention novox/hq issues 060/061 settled.
-ENV MESH_TOOL_MODULES=/app/modules/gitlab/dist/tools/index.js
@@ -2,69 +2,43 @@
  "module": "gitlab",
  "version": "1",
  "own-secrets": {
-    "token": "/var/lib/gitlab/token",
-    "broker": "/var/lib/mesh/gitlab/broker"
+    "token": "${dir:state}/token"
  },
  "resources": [
-    {
-      "id": "mesh-state",
-      "type": "directory",
-      "path": "/var/lib/mesh/gitlab",
-      "mode": "0700"
-    },
    {
      "id": "state",
      "type": "directory",
-      "path": "/var/lib/gitlab",
-      "mode": "0700"
+      "mode": "0700",
+      "place": "."
    },
    {
      "id": "config",
      "type": "file",
-      "path": "/var/lib/gitlab/config.json",
+      "path": "${dir:state}/config.json",
      "merge": "json",
      "content": "{}",
      "mode": "0600"
-    },
-    {
-      "id": "runtime",
-      "type": "container",
-      "name": "mesh-runtime-gitlab",
-      "network": "host",
-      "volumes": [
-        "/var/lib/gitlab/config.json:/run/config/config.json:ro",
-        "/var/lib/gitlab/token:/run/secrets/token:ro",
-        "/var/lib/mesh/gitlab/broker:/run/secrets/broker:ro"
-      ],
-      "env": {
-        "MESH_GITLAB_TOKEN_FILE": "/run/secrets/token",
-        "MESH_GITLAB_CONFIG_FILE": "/run/config/config.json",
-        "MESH_BROKER_FILE": "/run/secrets/broker"
-      },
-      "artifact": "runtime"
    }
  ],
  "capabilities": [
    "container-runtime"
  ],
  "build": {
-    "on": [
-      {
-        "arg": "BUILD_BASE",
-        "module": "mesh-tools",
-        "artifact": "build"
-      },
-      {
-        "arg": "RUNTIME_BASE",
-        "module": "mesh-tools",
-        "artifact": "runtime"
-      }
-    ],
    "artifacts": [
      {
-        "name": "runtime",
-        "kind": "image",
-        "from": "Dockerfile"
+        "name": "tools",
+        "kind": "bundle",
+        "language": "typescript",
+        "entrypoints": [
+          "tools/index.js"
+        ],
+        "loads": [
+          "tools/index.js"
+        ],
+        "env": {
+          "MESH_GITLAB_TOKEN_FILE": "${dir:state}/token",
+          "MESH_GITLAB_CONFIG_FILE": "${dir:state}/config.json"
+        }
      }
    ]
  }
@@ -1,24 +0,0 @@
-# grafana's runtime: the tool runtime, carrying this module's compiled code.
-#
-# **Built from this module's own directory and nothing else.** The sdk and the tool runtime are in
-# the base images, published like any other artifact — which is what makes this buildable by the
-# mesh from a repository and a path (novox/hq ADR 0069) rather than only on a workstation that
-# happens to have the siblings.
-#
-# Two bases, named rather than pinned (novox/hq issue 044): the image this is COMPILED in and the
-# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
-ARG BUILD_BASE
-ARG RUNTIME_BASE
-
-FROM ${BUILD_BASE} AS build
-WORKDIR /app/modules/grafana
-COPY . .
-RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts \
-      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
-
-FROM ${RUNTIME_BASE}
-COPY --from=build /app/modules/grafana/dist /app/modules/grafana/dist
-# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
-# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
-# the convention novox/hq issues 060/061 settled.
-ENV MESH_TOOL_MODULES=/app/modules/grafana/dist/index.js,/app/modules/grafana/dist/tools/index.js
@@ -5,8 +5,7 @@
    "alert.firing"
  ],
  "own-secrets": {
-    "admin": "/var/lib/grafana-module/admin.secret",
-    "broker": "/var/lib/mesh/grafana/broker"
+    "admin": "${dir:mesh-state}/admin"
  },
  "capabilities": [
    "container-runtime"
@@ -24,103 +23,142 @@
    {
      "id": "mesh-state",
      "type": "directory",
-      "path": "/var/lib/mesh/grafana",
-      "mode": "0700"
+      "mode": "0700",
+      "place": "mesh"
    },
    {
      "id": "state",
      "type": "directory",
-      "path": "/var/lib/grafana-module",
-      "mode": "0700"
+      "mode": "0700",
+      "place": "."
    },
    {
      "id": "data",
      "type": "directory",
-      "path": "/services/grafana/data",
      "mode": "0700",
      "owner": "472:472"
    },
    {
-      "id": "server-env",
+      "id": "admin-secret",
      "type": "file",
-      "path": "/var/lib/grafana-module/server.env",
-      "mode": "0600",
-      "content": "GF_SECURITY_ADMIN_PASSWORD=${secret:admin}\n"
+      "path": "${dir:state}/admin.secret",
+      "mode": "0400",
+      "owner": "472:472",
+      "content": "${secret:admin}"
+    },
+    {
+      "id": "oidc-secret",
+      "type": "file",
+      "path": "${dir:state}/oidc-client.secret",
+      "mode": "0400",
+      "owner": "472:472",
+      "content": "${secret:oidc-client}"
+    },
+    {
+      "id": "oidc-env",
+      "type": "file",
+      "path": "${dir:state}/oidc.env",
+      "mode": "0644",
+      "content": "GF_SERVER_ROOT_URL=https://${bound:route:name}\nGF_AUTH_GENERIC_OAUTH_ENABLED=true\nGF_AUTH_GENERIC_OAUTH_NAME=Keycloak\nGF_AUTH_GENERIC_OAUTH_CLIENT_ID=${bound:oidc-client:as}\nGF_AUTH_GENERIC_OAUTH_CLIENT_SECRET__FILE=/run/secrets/oidc-client\nGF_AUTH_GENERIC_OAUTH_SCOPES=openid email profile roles\nGF_AUTH_GENERIC_OAUTH_AUTH_URL=${bound:oidc-client:issuer}${bound:oidc-client:authorization-path}\nGF_AUTH_GENERIC_OAUTH_TOKEN_URL=${bound:oidc-client:issuer}${bound:oidc-client:token-path}\nGF_AUTH_GENERIC_OAUTH_API_URL=${bound:oidc-client:issuer}${bound:oidc-client:userinfo-path}\nGF_AUTH_GENERIC_OAUTH_ROLE_ATTRIBUTE_PATH=contains(roles[*], 'admin') && 'Admin' || contains(realm_access.roles[*], 'admin') && 'Admin' || 'Viewer'\nGF_AUTH_GENERIC_OAUTH_USE_PKCE=true\nGF_AUTH_GENERIC_OAUTH_ALLOW_SIGN_UP=true\nGF_AUTH_GENERIC_OAUTH_ALLOW_ASSIGN_GRAFANA_ADMIN=true\n"
+    },
+    {
+      "id": "influxdb-secret",
+      "type": "file",
+      "path": "${dir:state}/influxdb-api.secret",
+      "mode": "0400",
+      "owner": "472:472",
+      "content": "${secret:influxdb-api}"
+    },
+    {
+      "id": "influxdb-datasource",
+      "type": "file",
+      "path": "${dir:state}/datasource-influxdb.yaml",
+      "mode": "0644",
+      "content": "apiVersion: 1\n# Written by the mesh from grafana's influxdb-api binding; grafana reads it at start. Its own name and\n# uid, so a data source somebody made in the UI is never overwritten, and read-only in the UI because\n# the mesh resets it. The password is read from the file the mesh delivers, never written here.\ndatasources:\n  - name: InfluxDB (mesh)\n    uid: mesh-influxdb-api\n    type: influxdb\n    access: proxy\n    url: ${bound:influxdb-api:scheme}://${bound:influxdb-api:at}:${bound:influxdb-api:port}\n    user: ${bound:influxdb-api:as}\n    isDefault: false\n    editable: false\n    jsonData:\n      dbName: ${bound:influxdb-api:bucket}\n      httpMode: POST\n    secureJsonData:\n      password: $__file{/run/secrets/influxdb-api}\n"
    },
    {
      "id": "server",
      "type": "container",
      "name": "grafana",
-      "image": "grafana/grafana@sha256:f772d434e8fab0049deb2b1b30abd43342bcfca1537614aa8d36080232cf4283",
+      "image": "grafana/grafana@sha256:ac461fb352abc50da10a51c7d02462e9c05488f11f53f14b3ad79a8145f638a0",
      "ports": [
        "3000"
      ],
      "volumes": [
-        "/services/grafana/data:/var/lib/grafana"
+        "${dir:data}:/var/lib/grafana",
+        "${dir:state}/admin.secret:/run/secrets/admin:ro",
+        "${dir:state}/oidc-client.secret:/run/secrets/oidc-client:ro",
+        "${dir:state}/influxdb-api.secret:/run/secrets/influxdb-api:ro",
+        "${dir:state}/datasource-influxdb.yaml:/etc/grafana/provisioning/datasources/mesh-influxdb.yaml:ro"
      ],
+      "env": {
+        "GF_SECURITY_ADMIN_PASSWORD__FILE": "/run/secrets/admin"
+      },
      "env-file": [
-        "/var/lib/grafana-module/server.env"
+        "${dir:state}/oidc.env"
      ],
-      "secrets-in-environment": "grafana honours GF_SECURITY_ADMIN_PASSWORD__FILE; convertible, awaiting a bed that exercises the admin password (assigned-grafana serves tools only)"
+      "restart-on": [
+        "oidc-env",
+        "oidc-secret",
+        "influxdb-datasource",
+        "influxdb-secret"
+      ]
    },
    {
      "id": "runtime-config",
      "type": "file",
-      "path": "/var/lib/mesh/grafana/config.json",
+      "path": "${dir:mesh-state}/config.json",
      "mode": "0600",
-      "content": "{}\n",
+      "content": "{\n  \"user\": \"admin\",\n  \"password\": \"${secret:admin}\"\n}\n",
      "merge": "json"
-    },
-    {
-      "id": "runtime",
-      "type": "container",
-      "name": "mesh-grafana",
-      "network": "host",
-      "volumes": [
-        "/var/lib/mesh/grafana/broker:/run/secrets/broker:ro",
-        "/var/lib/mesh/grafana/config.json:/run/config/config.json:ro"
-      ],
-      "env": {
-        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_GRAFANA_URL": "http://127.0.0.1:3000",
-        "MESH_GRAFANA_CONFIG_FILE": "/run/config/config.json"
-      },
-      "restart-on": [
-        "runtime-config"
-      ],
-      "artifact": "runtime"
    }
  ],
  "requires": [
-    "route"
+    "route",
+    "oidc-client",
+    "influxdb-api"
  ],
  "contributes": {
    "route": {
      "label": "grafana",
      "endpoint": "web"
+    },
+    "oidc-client": {
+      "label": "grafana",
+      "endpoint": "web",
+      "callback": "/login/generic_oauth"
+    },
+    "influxdb-api": {
+      "access": "read"
    }
  },
  "binds": {
-    "route": "/var/lib/mesh/grafana/route.json"
+    "route": "${dir:state}/route.json",
+    "oidc-client": "${dir:state}/oidc.json",
+    "influxdb-api": "${dir:state}/influxdb.json"
+  },
+  "secrets": {
+    "oidc-client": "${dir:mesh-state}/oidc-client",
+    "influxdb-api": "${dir:mesh-state}/influxdb-api"
  },
  "build": {
-    "on": [
-      {
-        "arg": "BUILD_BASE",
-        "module": "mesh-tools",
-        "artifact": "build"
-      },
-      {
-        "arg": "RUNTIME_BASE",
-        "module": "mesh-tools",
-        "artifact": "runtime"
-      }
-    ],
    "artifacts": [
      {
-        "name": "runtime",
-        "kind": "image",
-        "from": "Dockerfile"
+        "name": "code",
+        "kind": "bundle",
+        "language": "typescript",
+        "entrypoints": [
+          "index.js",
+          "tools/index.js"
+        ],
+        "loads": [
+          "index.js",
+          "tools/index.js"
+        ],
+        "env": {
+          "MESH_GRAFANA_URL": "http://127.0.0.1:${port:3000}",
+          "MESH_GRAFANA_CONFIG_FILE": "${dir:mesh-state}/config.json"
+        }
      }
    ]
  }
@@ -15,7 +15,7 @@
    }
  },
  "binds": {
-    "route": "/var/lib/hello-web/route.json"
+    "route": "${dir:state}/route.json"
  },
  "listens": [
    {
@@ -30,13 +30,13 @@
    {
      "id": "state",
      "type": "directory",
-      "path": "/var/lib/hello-web",
-      "mode": "0700"
+      "mode": "0700",
+      "place": "."
    },
    {
      "id": "page",
      "type": "file",
-      "path": "/var/lib/hello-web/index.html",
+      "path": "${dir:state}/index.html",
      "mode": "0644",
      "content": "hello from hello-web, routed by the mesh\n"
    },
@@ -54,7 +54,7 @@
        "8080"
      ],
      "volumes": [
-        "/var/lib/hello-web/index.html:/www/index.html:ro"
+        "${dir:state}/index.html:/www/index.html:ro"
      ],
      "args": [
        "sh",
@@ -1,24 +0,0 @@
-# home-assistant's runtime: the tool runtime, carrying this module's compiled code.
-#
-# **Built from this module's own directory and nothing else.** The sdk and the tool runtime are in
-# the base images, published like any other artifact — which is what makes this buildable by the
-# mesh from a repository and a path (novox/hq ADR 0069) rather than only on a workstation that
-# happens to have the siblings.
-#
-# Two bases, named rather than pinned (novox/hq issue 044): the image this is COMPILED in and the
-# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
-ARG BUILD_BASE
-ARG RUNTIME_BASE
-
-FROM ${BUILD_BASE} AS build
-WORKDIR /app/modules/home-assistant
-COPY . .
-RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts \
-      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
-
-FROM ${RUNTIME_BASE}
-COPY --from=build /app/modules/home-assistant/dist /app/modules/home-assistant/dist
-# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
-# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
-# the convention novox/hq issues 060/061 settled.
-ENV MESH_TOOL_MODULES=/app/modules/home-assistant/dist/index.js,/app/modules/home-assistant/dist/tools/index.js
@@ -9,8 +9,7 @@
    "state.changed"
  ],
  "own-secrets": {
-    "broker": "/var/lib/mesh/home-assistant/broker",
-    "token": "/var/lib/mesh/home-assistant/token"
+    "token": "${dir:mesh-state}/token"
  },
  "listens": [
    {
@@ -18,98 +17,151 @@
      "port": 8123,
      "protocol": "tcp",
      "from": "mesh",
-      "why": "the dashboard and the API"
+      "why": "the dashboard, the API and the companion apps"
+    },
+    {
+      "name": "sonos-events",
+      "port": 1400,
+      "protocol": "tcp",
+      "from": "mesh",
+      "why": "the Sonos integration's event callback: speakers push their state changes here"
+    },
+    {
+      "name": "webrtc",
+      "port": 18555,
+      "protocol": "tcp",
+      "from": "mesh",
+      "why": "the bundled go2rtc's WebRTC port, which camera streams to a browser use"
    }
  ],
  "resources": [
    {
      "id": "mesh-state",
      "type": "directory",
-      "path": "/var/lib/mesh/home-assistant",
-      "mode": "0700"
+      "mode": "0700",
+      "place": "mesh"
+    },
+    {
+      "id": "state",
+      "type": "directory",
+      "mode": "0700",
+      "place": "."
    },
    {
      "id": "config",
      "type": "directory",
-      "path": "/services/home-assistant/config",
-      "mode": "0700",
-      "owner": "1000:1000"
+      "mode": "0700"
+    },
+    {
+      "id": "written",
+      "type": "directory",
+      "mode": "0700"
    },
    {
      "id": "server",
      "type": "container",
      "name": "home-assistant",
-      "image": "ghcr.io/home-assistant/home-assistant@sha256:14931c6b13756317849f46da1d01b45937a1150db66c081cfe529d48215943fe",
+      "image": "ghcr.io/home-assistant/home-assistant@sha256:d8922685169707fd91e8b9729902d975f06157d005e422874d201e0261dda196",
      "network": "host",
      "env": {
        "TZ": "Etc/UTC"
      },
      "volumes": [
-        "/services/home-assistant/config:/config"
+        "${dir:config}:/config"
      ]
    },
    {
      "id": "runtime-config",
      "type": "file",
-      "path": "/var/lib/mesh/home-assistant/config.json",
+      "path": "${dir:mesh-state}/config.json",
      "mode": "0600",
      "content": "{}\n",
      "merge": "json"
    },
    {
-      "id": "runtime",
-      "type": "container",
-      "name": "mesh-home-assistant",
-      "network": "host",
-      "volumes": [
-        "/var/lib/mesh/home-assistant/broker:/run/secrets/broker:ro",
-        "/var/lib/mesh/home-assistant/token:/run/secrets/token:ro",
-        "/var/lib/mesh/home-assistant/config.json:/run/config/config.json:ro",
-        "/services/home-assistant/config:/var/lib/home-assistant/config:ro"
+      "id": "provisions-env",
+      "type": "file",
+      "path": "${dir:state}/provisions.env",
+      "mode": "0600",
+      "content": "MESH_HOMEASSISTANT_URL=http://127.0.0.1:${port:8123}\nMESH_HOMEASSISTANT_TOKEN_FILE=${dir:mesh-state}/token\nMESH_PROVISIONS_DIR=${dir:state}\nMESH_WRITTEN_DIR=${dir:written}\n"
+    },
+    {
+      "id": "provisions",
+      "type": "process",
+      "name": "home-assistant-provisions",
+      "artifact": "code",
+      "run": [
+        "node",
+        "provisions/index.js"
+      ],
+      "run-once": true,
+      "env-file": [
+        "${dir:state}/provisions.env"
      ],
-      "env": {
-        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_HOMEASSISTANT_URL": "http://127.0.0.1:8123",
-        "MESH_HOMEASSISTANT_TOKEN_FILE": "/run/secrets/token",
-        "MESH_HOMEASSISTANT_CONFIG_FILE": "/run/config/config.json",
-        "MESH_HOMEASSISTANT_CONFIG_DIR": "/var/lib/home-assistant/config"
-      },
      "restart-on": [
-        "runtime-config"
-      ],
-      "artifact": "runtime"
+        "provisions-env",
+        "bound-mqtt-topic",
+        "secret-mqtt-topic",
+        "bound-sonarr-api",
+        "secret-sonarr-api",
+        "bound-radarr-api",
+        "secret-radarr-api",
+        "bound-lidarr-api",
+        "secret-lidarr-api"
+      ]
    }
  ],
  "requires": [
-    "route"
+    "lidarr-api",
+    "mqtt-topic",
+    "radarr-api",
+    "route",
+    "sonarr-api"
  ],
  "contributes": {
+    "mqtt-topic": {
+      "topics": [
+        "#"
+      ]
+    },
    "route": {
      "label": "home-assistant",
      "endpoint": "web"
    }
  },
  "binds": {
-    "route": "/var/lib/mesh/home-assistant/route.json"
+    "route": "${dir:state}/route.json",
+    "mqtt-topic": "${dir:state}/mqtt-topic.json",
+    "sonarr-api": "${dir:state}/sonarr-api.json",
+    "radarr-api": "${dir:state}/radarr-api.json",
+    "lidarr-api": "${dir:state}/lidarr-api.json"
+  },
+  "secrets": {
+    "mqtt-topic": "${dir:state}/mqtt-topic.secret",
+    "sonarr-api": "${dir:state}/sonarr-api.secret",
+    "radarr-api": "${dir:state}/radarr-api.secret",
+    "lidarr-api": "${dir:state}/lidarr-api.secret"
  },
  "build": {
-    "on": [
-      {
-        "arg": "BUILD_BASE",
-        "module": "mesh-tools",
-        "artifact": "build"
-      },
-      {
-        "arg": "RUNTIME_BASE",
-        "module": "mesh-tools",
-        "artifact": "runtime"
-      }
-    ],
    "artifacts": [
      {
-        "name": "runtime",
-        "kind": "image",
-        "from": "Dockerfile"
+        "name": "code",
+        "kind": "bundle",
+        "language": "typescript",
+        "entrypoints": [
+          "index.js",
+          "tools/index.js",
+          "provisions/index.js"
+        ],
+        "loads": [
+          "index.js",
+          "tools/index.js"
+        ],
+        "env": {
+          "MESH_HOMEASSISTANT_URL": "http://127.0.0.1:${port:8123}",
+          "MESH_HOMEASSISTANT_TOKEN_FILE": "${dir:mesh-state}/token",
+          "MESH_HOMEASSISTANT_CONFIG_FILE": "${dir:mesh-state}/config.json"
+        }
      }
    ]
  }
@@ -1,9 +1,14 @@
 {
  "name": "@novox/module-home-assistant",
  "version": "0.1.0",
-  "description": "home-assistant — home automation platform. Its API client, tools and events live here (novox/hq ADR 0039).",
+  "description": "home-assistant \u2014 home automation platform. Its API client, tools and events live here (novox/hq ADR 0039).",
  "type": "module",
  "private": true,
+  "scripts": {
+    "build": "tsc client.ts index.ts tools/index.ts provisions/hass.ts provisions/probe.ts provisions/connections.ts provisions/mesh.ts provisions/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test --experimental-strip-types 'test/*.test.ts'"
+  },
  "dependencies": {
    "@novox/mesh-sdk": "^0.1.0"
  },
@@ -0,0 +1,486 @@
+// How home-assistant's provisions step brings Home Assistant's integrations in line with what the
+// mesh bound: the MQTT integration to `mqtt-topic`, the Sonarr, Radarr and Lidarr integrations to
+// `sonarr-api`, `radarr-api` and `lidarr-api`. Pure logic over two seams — Home Assistant's config
+// flows (hass.ts) and the broker/apps — so it is tested against fakes (test/provisions.test.ts).
+//
+// The half that reads files and talks HTTP lives beside it (mesh.ts, hass.ts, probe.ts, index.ts).
+
+import { createHash } from "node:crypto";
+
+import type { Hass, SchemaField } from "./hass.js";
+import type { Probe } from "./probe.js";
+
+/** What the mesh wrote at `binds.<provision>` (the controller's binding document). */
+export interface Binding {
+  provision?: string;
+  from?: string;
+  at?: string;
+  as?: string;
+  serves?: Record<string, unknown>;
+}
+
+/** How one provision came out. Never carries a credential. */
+export type Outcome =
+  | { what: string; result: "unchanged"; note?: string }
+  | { what: string; result: "written"; fields: string[]; note?: string }
+  | { what: string; result: "equivalent"; note: string }
+  | { what: string; result: "refused"; problem: string };
+
+/** A port the binding serves, or undefined when it names none usable. */
+export function portOf(serves: Record<string, unknown> | undefined): number | undefined {
+  const port = Number(serves?.port);
+  return Number.isInteger(port) && port > 0 && port <= 65535 ? port : undefined;
+}
+
+/** A host as it goes into a URL: an IPv6 literal bracketed. */
+export function urlHost(host: string): string {
+  return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+}
+
+/**
+ * What this step last wrote, per target, as a digest: the only way to know "already as the mesh
+ * says" for a credential Home Assistant will not show back. A sha256 over the target and the values,
+ * never the values; kept in the module's own placed directory.
+ */
+export interface Marks {
+  get(name: string): Promise<string | undefined>;
+  set(name: string, digest: string): Promise<void>;
+}
+
+export function digest(...parts: (string | number)[]): string {
+  return createHash("sha256").update(parts.map(String).join("\u0000")).digest("hex");
+}
+
+/** An error as text with the credential taken out, raw and URL-encoded. */
+export function scrub(err: unknown, ...secrets: (string | undefined)[]): string {
+  let text = err instanceof Error ? err.message : String(err);
+  for (const s of secrets) {
+    if (!s) continue;
+    for (const form of new Set([s, encodeURIComponent(s)])) text = text.split(form).join("***");
+  }
+  return text;
+}
+
+/**
+ * What a form would submit if a person pressed "submit" without touching it: each field's
+ * suggested value (what Home Assistant pre-fills from the entry), else its default; a section's
+ * fields nested under its name. The step lays only the connection fields over this, so every other
+ * choice the entry carries is sent back exactly as Home Assistant showed it.
+ */
+export function formValues(schema: readonly SchemaField[] | null | undefined): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const field of schema ?? []) {
+    if (Array.isArray(field.schema)) {
+      out[field.name] = formValues(field.schema);
+      continue;
+    }
+    const suggested = field.description?.suggested_value;
+    if (suggested !== undefined && suggested !== null) out[field.name] = suggested;
+    else if (field.default !== undefined) out[field.name] = field.default;
+  }
+  return out;
+}
+
+/** Whether a form has a field of this name at its top level. */
+export function hasField(schema: readonly SchemaField[] | null | undefined, name: string): boolean {
+  return (schema ?? []).some((f) => f.name === name);
+}
+
+// ---- MQTT ----
+
+// Home Assistant's MQTT integration, pointed at the broker the mesh bound — `mqtt-topic`.
+//
+// **Why a step.** Home Assistant keeps its broker, login and password in its MQTT config entry
+// (`.storage/core.config_entries`), not in a file the mesh could fill with `${bound:mqtt-topic:at}`.
+// So this reads the binding and the pair credential and makes the entry say the same thing, through
+// the MQTT integration's own reconfigure flow — the flow its "Reconfigure" button runs, which tests
+// the connection itself and saves nothing it could not connect with.
+//
+// **Only the connection, and only when it differs.** Broker, port, username, password. The protocol
+// version, client id, keepalive, TLS choices and discovery options the entry holds are sent back
+// exactly as Home Assistant pre-filled them. Whether the password already matches cannot be read
+// back (Home Assistant never shows a stored password), so the step keeps a digest of what it last
+// wrote: equal broker/port/username and an equal digest is "already as the mesh says".
+//
+// **Nothing loses its connection without someone seeing it.** Before Home Assistant is touched the
+// broker itself is asked whether it takes the delivered login (the provisioner creates it within
+// seconds of the grant): if not, nothing is written and the step fails saying why, and Home
+// Assistant keeps the login it has — the carried `luffy` on ace, which mosquitto keeps. If Home
+// Assistant's own connection test refuses the new settings, the flow saves nothing, and the step
+// fails with Home Assistant's reason. A login that may not subscribe to the discovery topics is said
+// as a warning: discovery would find nothing.
+
+export const MQTT_PROVISION = "mqtt-topic";
+/** Home Assistant's discovery prefix, subscribed to whenever discovery is on (the default). */
+export const DISCOVERY_FILTER = "homeassistant/#";
+
+export interface MqttWanted {
+  host: string;
+  port: number;
+  username: string;
+  password: string;
+}
+
+export type Wanted = { ok: true; want: MqttWanted } | { ok: false; problem: string };
+
+/** The broker, port and login the mesh says Home Assistant uses. */
+export function wantedMqtt(binding: Binding | undefined, credential: string | undefined): Wanted {
+  if (!binding) return { ok: false, problem: `no binding for ${MQTT_PROVISION} was delivered — the mesh writes it before this step runs` };
+  const host = typeof binding.at === "string" ? binding.at.trim() : "";
+  if (!host) return { ok: false, problem: `the ${MQTT_PROVISION} binding names no host (at)` };
+  const port = portOf(binding.serves);
+  if (port === undefined) return { ok: false, problem: `the ${MQTT_PROVISION} binding serves no usable port (${String(binding.serves?.port)})` };
+  const scheme = binding.serves?.scheme;
+  if (scheme !== undefined && scheme !== "mqtt") {
+    return { ok: false, problem: `the ${MQTT_PROVISION} binding serves scheme ${String(scheme)}; this step writes plain MQTT` };
+  }
+  const username = typeof binding.as === "string" ? binding.as.trim() : "";
+  if (!username) return { ok: false, problem: `the ${MQTT_PROVISION} binding names no login (as)` };
+  const password = (credential ?? "").replace(/\n$/, "");
+  if (!password) return { ok: false, problem: `the ${MQTT_PROVISION} credential is empty or was not delivered` };
+  return { ok: true, want: { host, port, username, password } };
+}
+
+export interface MqttDeps {
+  hass: Hass;
+  probe: Probe;
+  marks: Marks;
+}
+
+const markFor = (entryId: string, w: MqttWanted): string => digest("mqtt", entryId, w.host, w.port, w.username, w.password);
+
+/** Bring Home Assistant's MQTT entry in line with the mesh. Never throws: every failure is an outcome. */
+export async function reconcileMqtt(deps: MqttDeps, binding: Binding | undefined, credential: string | undefined): Promise<Outcome> {
+  const what = "mqtt";
+  const w = wantedMqtt(binding, credential);
+  if ("problem" in w) return { what, result: "refused", problem: w.problem };
+  const want = w.want;
+
+  // The broker first: a login it does not take is never written into Home Assistant.
+  let note: string | undefined;
+  try {
+    const probe = await deps.probe(want.host, want.port, want.username, want.password, DISCOVERY_FILTER);
+    if (probe.connack === 4 || probe.connack === 5) {
+      return {
+        what,
+        result: "refused",
+        problem:
+          `the broker at ${want.host}:${want.port} does not (yet) take the login ${want.username} with the delivered ` +
+          `password (CONNACK ${probe.connack}); mosquitto's provisioner creates it from the grant — nothing was ` +
+          `written, and Home Assistant keeps the broker login it has`,
+      };
+    }
+    if (probe.connack !== 0) {
+      return { what, result: "refused", problem: `the broker at ${want.host}:${want.port} answered CONNACK ${probe.connack}; nothing was written` };
+    }
+    if (probe.suback === 0x80) {
+      note =
+        `warning: ${want.username} may not subscribe to ${DISCOVERY_FILTER} — MQTT discovery will find nothing; ` +
+        `grant it with the mqtt-topic contribution's \`topics\``;
+    }
+  } catch (err) {
+    return {
+      what,
+      result: "refused",
+      problem: `the broker at ${want.host}:${want.port} could not be asked: ${scrub(err, want.password)}; nothing was written`,
+    };
+  }
+
+  try {
+    const entries = (await deps.hass.entries("mqtt")).filter((e) => e.domain === "mqtt");
+    if (entries.length > 1) {
+      return { what, result: "refused", problem: `Home Assistant has ${entries.length} MQTT entries; which one the mesh owns is not guessed` };
+    }
+    if (entries.length === 0) return await createEntry(deps, want, note);
+
+    const entry = entries[0];
+    const flow = await deps.hass.startFlow("mqtt", entry.entry_id);
+    if (flow.type !== "form" || !flow.flow_id || !flow.data_schema) {
+      if (flow.flow_id) await deps.hass.abortFlow(flow.flow_id);
+      return { what, result: "refused", problem: `Home Assistant's MQTT reconfigure flow answered ${flow.type}${flow.reason ? ` (${flow.reason})` : ""}` };
+    }
+    const current = formValues(flow.data_schema);
+    const fields: string[] = [];
+    if (String(current.broker ?? "") !== want.host) fields.push("broker");
+    if (Number(current.port ?? 0) !== want.port) fields.push("port");
+    if (String(current.username ?? "") !== want.username) fields.push("username");
+    if ((await deps.marks.get("mqtt")) !== markFor(entry.entry_id, want)) fields.push("password");
+    if (fields.length === 0) {
+      await deps.hass.abortFlow(flow.flow_id);
+      return note ? { what, result: "unchanged", note } : { what, result: "unchanged" };
+    }
+
+    const saved = await deps.hass.stepFlow(flow.flow_id, {
+      ...current,
+      broker: want.host,
+      port: want.port,
+      username: want.username,
+      password: want.password,
+    });
+    if (saved.type === "abort" && saved.reason === "reconfigure_successful") {
+      await deps.marks.set("mqtt", markFor(entry.entry_id, want));
+      return { what, result: "written", fields, ...(note ? { note } : {}) };
+    }
+    if (saved.flow_id) await deps.hass.abortFlow(saved.flow_id);
+    return {
+      what,
+      result: "refused",
+      problem:
+        `Home Assistant's own connection test refused ${want.username}@${want.host}:${want.port} ` +
+        `(${describe(saved)}); its MQTT entry is unchanged`,
+    };
+  } catch (err) {
+    return { what, result: "refused", problem: scrub(err, want.password) };
+  }
+}
+
+/** A fresh Home Assistant has no MQTT entry: made through the integration's user flow. */
+async function createEntry(deps: MqttDeps, want: MqttWanted, note?: string): Promise<Outcome> {
+  const what = "mqtt";
+  let flow = await deps.hass.startFlow("mqtt");
+  if (flow.type === "form" && flow.step_id !== "broker" && flow.flow_id) {
+    // Anything before the broker form (none outside the Supervisor) is not this step's to answer.
+    await deps.hass.abortFlow(flow.flow_id);
+    return { what, result: "refused", problem: `Home Assistant's MQTT user flow asked ${flow.step_id} before the broker` };
+  }
+  if (flow.type !== "form" || !flow.flow_id) {
+    return { what, result: "refused", problem: `Home Assistant's MQTT user flow answered ${describe(flow)}` };
+  }
+  const shown = formValues(flow.data_schema);
+  // A new entry's form has no value for its two certificate choices (a reconfigure pre-fills them
+  // from the entry): plain MQTT, so neither a CA nor a client certificate.
+  const other = (shown.other_settings ?? {}) as Record<string, unknown>;
+  if (flow.data_schema?.some((f) => f.name === "other_settings")) {
+    shown.other_settings = { set_ca_cert: "off", set_client_cert: false, ...other };
+  }
+  flow = await deps.hass.stepFlow(flow.flow_id, {
+    ...shown,
+    broker: want.host,
+    port: want.port,
+    username: want.username,
+    password: want.password,
+  });
+  if (flow.type === "create_entry") {
+    const id = (flow.result as { entry_id?: string } | undefined)?.entry_id;
+    if (id) await deps.marks.set("mqtt", markFor(id, want));
+    return { what, result: "written", fields: ["entry"], ...(note ? { note } : {}) };
+  }
+  if (flow.flow_id) await deps.hass.abortFlow(flow.flow_id);
+  return { what, result: "refused", problem: `Home Assistant refused a new MQTT entry for ${want.host}:${want.port} (${describe(flow)})` };
+}
+
+export function describe(r: { type: string; reason?: string; errors?: Record<string, string> | null }): string {
+  const errors = r.errors ? Object.entries(r.errors).map(([k, v]) => `${k}: ${v}`).join(", ") : "";
+  return [r.type, r.reason, errors].filter(Boolean).join(" — ");
+}
+
+// ---- Sonarr, Radarr, Lidarr ----
+
+// Home Assistant's Sonarr, Radarr and Lidarr integrations, pointed at the apps the mesh bound —
+// `sonarr-api`, `radarr-api`, `lidarr-api` (their providers: mesh-catalog #156).
+//
+// **What Home Assistant lets anyone change, and what it does not.** Each integration keeps a URL and
+// an API key in its config entry. None of the three has a reconfigure flow: Home Assistant changes
+// them only through the flow its UI runs —
+//   - a **user flow** makes a new entry (validated against the app);
+//   - a **reauth flow**, which Home Assistant starts by itself when the app refuses the key it holds,
+//     takes a new key (Sonarr) or a new URL and key (Radarr, Lidarr);
+//   - anything else — the URL of a working entry — only by removing the integration and adding it
+//     again, which throws away its entities' names, areas and history links. **This step never
+//     removes an entry.**
+// So, per app:
+//   1. The bound key is tried against the bound app first. Refused, nothing is written: until the
+//      operator accepts the app's own key for this pair, the mesh delivers a value it minted, which
+//      no Servarr app takes (novox/hq ADR 0092) — the failure names the `secret accept` that fixes it.
+//   2. No entry: one is made through the user flow.
+//   3. A reauth flow Home Assistant started for the entry: finished with the bound key (and URL,
+//      where the integration's reauth asks for one).
+//   4. An entry whose URL (read from the device the integration registered, `configuration_url`)
+//      is the bound one and which is loaded: already as the mesh says. The key needs no digest here:
+//      a Servarr app has one key, so an entry loaded against the app holds the key the app took.
+//   5. A working entry at a different URL that reaches **the same app** — the same process, by the
+//      app's own status (start time, data folder, version) — is left as it is and said: ace's entries
+//      say `127.0.0.1:<port>` and the binding says `ace.internal:<port>`, one Sonarr either way.
+//   6. Anything else is refused, loudly, with what the operator can do; nothing is removed.
+
+
+export interface ServarrApp {
+  /** The integration's domain, also the app. */
+  domain: "sonarr" | "radarr" | "lidarr";
+  /** The provision it is required as: the `requires`, `binds` and `secrets` key. */
+  provision: string;
+  /** The app's status endpoint: answers 401 to a wrong key, and says which process answered. */
+  statusPath: string;
+}
+
+export const APPS: readonly ServarrApp[] = [
+  { domain: "sonarr", provision: "sonarr-api", statusPath: "/api/v3/system/status" },
+  { domain: "radarr", provision: "radarr-api", statusPath: "/api/v3/system/status" },
+  { domain: "lidarr", provision: "lidarr-api", statusPath: "/api/v1/system/status" },
+];
+
+/** The HTTP the step needs toward the apps, so a test can stand fakes in. */
+export interface Http {
+  fetch(url: string, init?: { method?: string; headers?: Record<string, string> }): Promise<{ status: number; text(): Promise<string> }>;
+}
+
+export type AppWanted = { ok: true; url: string; key: string; from: string } | { ok: false; problem: string };
+
+/** The URL and key the mesh says Home Assistant uses for this app. */
+export function wantedApp(spec: ServarrApp, binding: Binding | undefined, credential: string | undefined): AppWanted {
+  if (!binding) return { ok: false, problem: `no binding for ${spec.provision} was delivered — the mesh writes it before this step runs` };
+  const at = typeof binding.at === "string" ? binding.at.trim() : "";
+  if (!at) return { ok: false, problem: `the ${spec.provision} binding names no host (at)` };
+  const port = portOf(binding.serves);
+  if (port === undefined) return { ok: false, problem: `the ${spec.provision} binding serves no usable port (${String(binding.serves?.port)})` };
+  const scheme = typeof binding.serves?.scheme === "string" && binding.serves.scheme ? binding.serves.scheme : "http";
+  if (scheme !== "http" && scheme !== "https") return { ok: false, problem: `the ${spec.provision} binding serves scheme ${scheme}` };
+  const base = typeof binding.serves?.["url-base"] === "string" ? String(binding.serves["url-base"]).trim().replace(/^\/+|\/+$/g, "") : "";
+  const key = (credential ?? "").trim();
+  if (!key) return { ok: false, problem: `the ${spec.provision} credential is empty or was not delivered` };
+  return {
+    ok: true,
+    url: `${scheme}://${urlHost(at)}:${port}${base ? `/${base}` : ""}`,
+    key,
+    from: typeof binding.from === "string" ? binding.from : "",
+  };
+}
+
+/** Two URLs naming the same place: scheme, host, port (explicit or default) and base path. */
+export function sameUrl(a: string | null | undefined, b: string): boolean {
+  if (!a) return false;
+  try {
+    const x = new URL(a);
+    const y = new URL(b);
+    const port = (u: URL) => u.port || (u.protocol === "https:" ? "443" : "80");
+    const path = (u: URL) => u.pathname.replace(/\/+$/, "");
+    return x.protocol === y.protocol && x.hostname.toLowerCase() === y.hostname.toLowerCase() && port(x) === port(y) && path(x) === path(y);
+  } catch {
+    return false;
+  }
+}
+
+type Status = { taken: true; status: Record<string, unknown> } | { taken: false };
+
+/** The app's status with this key: `taken: false` when it refuses the key; throws when it cannot be asked. */
+export async function appStatus(http: Http, spec: ServarrApp, url: string, key: string): Promise<Status> {
+  const res = await http.fetch(`${url.replace(/\/+$/, "")}${spec.statusPath}`, {
+    method: "GET",
+    headers: { "X-Api-Key": key, Accept: "application/json" },
+  });
+  if (res.status === 401 || res.status === 403) return { taken: false };
+  if (res.status < 200 || res.status >= 300) throw new Error(`${spec.domain} answered ${res.status} at ${spec.statusPath}`);
+  return { taken: true, status: JSON.parse(await res.text()) as Record<string, unknown> };
+}
+
+/** Whether two status answers came from one running app. */
+export function sameInstance(a: Record<string, unknown>, b: Record<string, unknown>): boolean {
+  const facts = ["startTime", "appData", "version"];
+  return facts.every((k) => a[k] !== undefined && a[k] !== null && a[k] === b[k]);
+}
+
+/** The remedy for a refused key, in the controller's words (ADR 0092). */
+export function acceptRemedy(spec: ServarrApp, from: string): string {
+  return (
+    `${spec.domain} refuses the ${spec.provision} credential the mesh delivered, so nothing was written into ` +
+    `Home Assistant. A Servarr app has one API key and the mesh cannot make it: accept ${spec.domain}'s own key ` +
+    `for this pair — \`secret accept <this node> home-assistant ${spec.provision} --provider ${from || "<its node>"} ` +
+    `--from <file holding ${spec.domain}'s ApiKey>\``
+  );
+}
+
+export interface ServarrDeps {
+  hass: Hass;
+  http: Http;
+}
+
+/** The input a Servarr form takes: what it shows, with the URL (where asked) and the key laid over. */
+function servarrInput(schema: readonly SchemaField[] | null | undefined, url: string, key: string): Record<string, unknown> {
+  const input = formValues(schema);
+  if (hasField(schema, "url")) input.url = url;
+  if (hasField(schema, "api_key")) input.api_key = key;
+  return input;
+}
+
+/** Bring Home Assistant's entry for one app in line with the mesh. Never throws. */
+export async function reconcileApp(deps: ServarrDeps, spec: ServarrApp, binding: Binding | undefined, credential: string | undefined): Promise<Outcome> {
+  const what = spec.domain;
+  const w = wantedApp(spec, binding, credential);
+  if ("problem" in w) return { what, result: "refused", problem: w.problem };
+
+  let bound: Status;
+  try {
+    bound = await appStatus(deps.http, spec, w.url, w.key);
+  } catch (err) {
+    return { what, result: "refused", problem: `${spec.domain} could not be asked at ${w.url}: ${scrub(err, w.key)}` };
+  }
+  if (!bound.taken) return { what, result: "refused", problem: acceptRemedy(spec, w.from) };
+
+  try {
+    const entries = (await deps.hass.entries(spec.domain)).filter((e) => e.domain === spec.domain);
+    if (entries.length > 1) {
+      return { what, result: "refused", problem: `Home Assistant has ${entries.length} ${spec.domain} entries; which one the mesh owns is not guessed` };
+    }
+
+    // No entry: made, through the integration's own user flow, which validates the key itself.
+    if (entries.length === 0) {
+      const flow = await deps.hass.startFlow(spec.domain);
+      if (flow.type !== "form" || !flow.flow_id) return { what, result: "refused", problem: `Home Assistant's ${spec.domain} user flow answered ${describe(flow)}` };
+      const made = await deps.hass.stepFlow(flow.flow_id, servarrInput(flow.data_schema, w.url, w.key));
+      if (made.type === "create_entry") return { what, result: "written", fields: ["entry"] };
+      if (made.flow_id) await deps.hass.abortFlow(made.flow_id);
+      return { what, result: "refused", problem: `Home Assistant refused a new ${spec.domain} entry at ${w.url} (${describe(made)})` };
+    }
+
+    const entry = entries[0];
+    if (entry.disabled_by) return { what, result: "unchanged", note: `the ${spec.domain} entry is disabled (by ${entry.disabled_by}); left alone` };
+
+    // A reauth Home Assistant started because the app refused its key: finished with the bound one.
+    const reauth = (await deps.hass.flowsInProgress()).find(
+      (f) => f.handler === spec.domain && f.context?.source === "reauth" && f.context?.entry_id === entry.entry_id,
+    );
+    if (reauth) {
+      let step = await deps.hass.stepFlow(reauth.flow_id, {}); // reauth_confirm: a confirmation, no fields
+      if (step.type === "form" && step.flow_id && step.step_id !== "reauth_confirm") {
+        const input = servarrInput(step.data_schema, w.url, w.key);
+        const fields = ["api_key", ...(hasField(step.data_schema, "url") ? ["url"] : [])];
+        step = await deps.hass.stepFlow(step.flow_id, input);
+        if (step.type === "abort" && step.reason === "reauth_successful") return { what, result: "written", fields };
+      }
+      return { what, result: "refused", problem: `Home Assistant's ${spec.domain} reauth did not take the bound key and URL (${describe(step)})` };
+    }
+
+    const device = (await deps.hass.devices()).find((d) => d.config_entries?.includes(entry.entry_id) && d.configuration_url);
+    const current = device?.configuration_url ?? undefined;
+    if (entry.state === "loaded" && sameUrl(current, w.url)) return { what, result: "unchanged" };
+
+    if (entry.state === "loaded" && current) {
+      let there: Status | undefined;
+      try {
+        there = await appStatus(deps.http, spec, current, w.key);
+      } catch {
+        there = undefined;
+      }
+      if (there?.taken && sameInstance(there.status, bound.status)) {
+        return {
+          what,
+          result: "equivalent",
+          note:
+            `Home Assistant reaches ${spec.domain} at ${current}, the same running app the mesh bound at ${w.url}; ` +
+            `Home Assistant has no way to change a working ${spec.domain} entry's URL short of removing it, so it is left as it is`,
+        };
+      }
+    }
+    return {
+      what,
+      result: "refused",
+      problem:
+        `Home Assistant's ${spec.domain} entry (${entry.state ?? "unknown state"}) points at ${current ?? "an unknown URL"}, ` +
+        `not the ${spec.domain} the mesh bound at ${w.url}. Home Assistant only lets a working entry's URL change by ` +
+        `removing and re-adding the integration, which this step never does: remove it in Home Assistant ` +
+        `(Settings → Devices & services → ${spec.domain}) and the next run adds it at the bound URL`,
+    };
+  } catch (err) {
+    return { what, result: "refused", problem: scrub(err, w.key) };
+  }
+}
@@ -0,0 +1,160 @@
+// Home Assistant's own configuration API, as the provisions step uses it — the supported way to
+// change an integration's connection. Home Assistant keeps every integration in
+// `.storage/core.config_entries`, a file it owns and rewrites; the mesh may not write it, and it is
+// not a file the mesh could merge into. What Home Assistant offers instead is the same thing its UI
+// uses: **config flows** over REST (`/api/config/config_entries/flow`) — a user flow creates an
+// entry, a reconfigure flow changes one, a reauth flow (which Home Assistant starts itself when a
+// credential stops working) replaces its credential — each validated by the integration's own
+// connection test before anything is saved. The two things REST does not answer (which flows Home
+// Assistant has started, which device an entry made) come over its WebSocket API.
+//
+// Nothing here reads `.storage`. Authenticated with the module's accepted long-lived access token.
+
+/** A config entry as `GET /api/config/config_entries/entry` lists it — no data, no credentials. */
+export interface ConfigEntry {
+  entry_id: string;
+  domain: string;
+  title?: string;
+  source?: string;
+  state?: string;
+  disabled_by?: string | null;
+}
+
+/** One field of a flow's form, as Home Assistant serializes a voluptuous schema. */
+export interface SchemaField {
+  name: string;
+  type?: string;
+  required?: boolean;
+  optional?: boolean;
+  default?: unknown;
+  description?: { suggested_value?: unknown } | null;
+  /** A section (`type: "expandable"`) carries its own fields. */
+  schema?: SchemaField[];
+}
+
+/** What a flow answered: another form, an entry made, or the flow ended (abort). */
+export interface FlowResult {
+  type: string;
+  flow_id?: string;
+  handler?: string;
+  step_id?: string;
+  data_schema?: SchemaField[] | null;
+  errors?: Record<string, string> | null;
+  reason?: string;
+  result?: { entry_id?: string } | unknown;
+}
+
+/** A flow in progress that Home Assistant started itself (a reauth, a discovery). */
+export interface FlowProgress {
+  flow_id: string;
+  handler: string;
+  step_id?: string;
+  context?: { source?: string; entry_id?: string };
+}
+
+/** A device from the device registry; an integration names where its app is as configuration_url. */
+export interface DeviceEntry {
+  id: string;
+  config_entries?: string[];
+  configuration_url?: string | null;
+}
+
+export interface Hass {
+  entries(domain: string): Promise<ConfigEntry[]>;
+  /** A user flow for `handler`, or — given an entry — a reconfigure flow for it. */
+  startFlow(handler: string, entryId?: string): Promise<FlowResult>;
+  stepFlow(flowId: string, input: Record<string, unknown>): Promise<FlowResult>;
+  abortFlow(flowId: string): Promise<void>;
+  flowsInProgress(): Promise<FlowProgress[]>;
+  devices(): Promise<DeviceEntry[]>;
+}
+
+/** Home Assistant over HTTP: REST for entries and flows, one short WebSocket session per question. */
+export class HassApi implements Hass {
+  private readonly base: string;
+
+  constructor(url: string, private readonly token: string) {
+    this.base = url.replace(/\/$/, "");
+  }
+
+  private async rest(method: string, path: string, body?: unknown): Promise<unknown> {
+    const res = await fetch(`${this.base}${path}`, {
+      method,
+      headers: {
+        Authorization: `Bearer ${this.token}`,
+        Accept: "application/json",
+        ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+      },
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    const text = await res.text();
+    if (!res.ok) {
+      // Home Assistant's error text names fields, never echoes their values.
+      throw new Error(`Home Assistant ${method} ${path} answered ${res.status}${text ? `: ${text.slice(0, 200)}` : ""}`);
+    }
+    return text ? (JSON.parse(text) as unknown) : undefined;
+  }
+
+  async entries(domain: string): Promise<ConfigEntry[]> {
+    return ((await this.rest("GET", `/api/config/config_entries/entry?domain=${encodeURIComponent(domain)}`)) ??
+      []) as ConfigEntry[];
+  }
+
+  async startFlow(handler: string, entryId?: string): Promise<FlowResult> {
+    return (await this.rest("POST", "/api/config/config_entries/flow", {
+      handler,
+      show_advanced_options: true,
+      ...(entryId ? { entry_id: entryId } : {}),
+    })) as FlowResult;
+  }
+
+  async stepFlow(flowId: string, input: Record<string, unknown>): Promise<FlowResult> {
+    return (await this.rest("POST", `/api/config/config_entries/flow/${encodeURIComponent(flowId)}`, input)) as FlowResult;
+  }
+
+  async abortFlow(flowId: string): Promise<void> {
+    await this.rest("DELETE", `/api/config/config_entries/flow/${encodeURIComponent(flowId)}`).catch(() => undefined);
+  }
+
+  async flowsInProgress(): Promise<FlowProgress[]> {
+    return (await this.ws("config_entries/flow/progress")) as FlowProgress[];
+  }
+
+  async devices(): Promise<DeviceEntry[]> {
+    return (await this.ws("config/device_registry/list")) as DeviceEntry[];
+  }
+
+  /** One WebSocket command: connect, authenticate, ask, close. */
+  private ws(type: string): Promise<unknown> {
+    const url = `${this.base.replace(/^http/, "ws")}/api/websocket`;
+    return new Promise((resolve, reject) => {
+      const socket = new WebSocket(url);
+      const timer = setTimeout(() => {
+        socket.close();
+        reject(new Error(`Home Assistant's WebSocket did not answer ${type} within 30s`));
+      }, 30_000);
+      const done = (fn: () => void): void => {
+        clearTimeout(timer);
+        socket.close();
+        fn();
+      };
+      socket.onerror = () => done(() => reject(new Error(`Home Assistant's WebSocket at ${url} failed`)));
+      socket.onmessage = (event: { data: unknown }) => {
+        const msg = JSON.parse(String(event.data)) as {
+          type: string;
+          id?: number;
+          success?: boolean;
+          result?: unknown;
+          error?: { message?: string };
+        };
+        if (msg.type === "auth_required") socket.send(JSON.stringify({ type: "auth", access_token: this.token }));
+        else if (msg.type === "auth_invalid") done(() => reject(new Error("Home Assistant refused the token")));
+        else if (msg.type === "auth_ok") socket.send(JSON.stringify({ id: 1, type }));
+        else if (msg.type === "result" && msg.id === 1) {
+          if (msg.success) done(() => resolve(msg.result));
+          else done(() => reject(new Error(`Home Assistant ${type}: ${msg.error?.message ?? "failed"}`)));
+        }
+      };
+    });
+  }
+}
@@ -0,0 +1,84 @@
+// home-assistant's provisions step — run once by the host after Home Assistant starts, and again
+// whenever a binding or pair credential it reads changes (the container's `restart-on`, novox/hq
+// ADR 0099). It points Home Assistant's MQTT integration at the `mqtt-topic` broker and its Sonarr,
+// Radarr and Lidarr integrations at the `sonarr-api`, `radarr-api` and `lidarr-api` apps, through
+// Home Assistant's own config flows (connections.ts). It connects to no mesh broker.
+//
+// Exits non-zero when anything could not be put right, so the node reports the step failed and the
+// host runs it again on the next apply. Declared last in the manifest, so its failing gates nothing
+// else of home-assistant's (novox/hq ADR 0136). Never prints a key or password.
+
+import { join } from "node:path";
+
+import { APPS, MQTT_PROVISION, reconcileApp, reconcileMqtt, type Outcome } from "./connections.js";
+import { HassApi } from "./hass.js";
+import { marksIn, readBinding, readIfThere } from "./mesh.js";
+import { probeBroker } from "./probe.js";
+
+const dir = process.env.MESH_PROVISIONS_DIR ?? "/run/provisions";
+const url = process.env.MESH_HOMEASSISTANT_URL ?? "http://127.0.0.1:8123";
+const token = (await readIfThere(process.env.MESH_HOMEASSISTANT_TOKEN_FILE))?.trim() ?? "";
+const marks = marksIn(process.env.MESH_WRITTEN_DIR ?? "/var/lib/home-assistant-provisions");
+const waitSeconds = Number(process.env.MESH_HOMEASSISTANT_WAIT_SECONDS ?? "300");
+
+if (!token) {
+  console.error("[hass-provisions] no Home Assistant token — home-assistant's own `token` secret has not been accepted");
+  process.exit(1);
+}
+
+/** Home Assistant answers /api/ with 200 once it is up and the token is good. */
+async function ready(): Promise<boolean> {
+  const until = Date.now() + waitSeconds * 1000;
+  for (;;) {
+    try {
+      const res = await fetch(`${url.replace(/\/$/, "")}/api/`, { headers: { Authorization: `Bearer ${token}` } });
+      if (res.status === 200) return true;
+      if (res.status === 401 || res.status === 403) {
+        console.error("[hass-provisions] Home Assistant refuses the token — accept a long-lived access token it issued");
+        return false;
+      }
+    } catch {
+      // not listening yet
+    }
+    if (Date.now() >= until) return false;
+    await new Promise((r) => setTimeout(r, 3000));
+  }
+}
+
+if (!(await ready())) {
+  console.error(`[hass-provisions] Home Assistant did not answer at ${url} within ${waitSeconds}s`);
+  process.exit(1);
+}
+
+const hass = new HassApi(url, token);
+const read = async (p: string) => [await readBinding(join(dir, `${p}.json`)), await readIfThere(join(dir, `${p}.secret`))] as const;
+
+const outcomes: Outcome[] = [];
+{
+  const [binding, secret] = await read(MQTT_PROVISION);
+  outcomes.push(await reconcileMqtt({ hass, probe: probeBroker, marks }, binding, secret));
+}
+for (const spec of APPS) {
+  const [binding, secret] = await read(spec.provision);
+  outcomes.push(await reconcileApp({ hass, http: { fetch: (u, init) => fetch(u, init) } }, spec, binding, secret));
+}
+
+let failed = 0;
+for (const o of outcomes) {
+  switch (o.result) {
+    case "unchanged":
+      console.log(`[hass-provisions] ${o.what}: already as the mesh says${o.note ? ` — ${o.note}` : ""}`);
+      break;
+    case "written":
+      console.log(`[hass-provisions] ${o.what}: wrote ${o.fields.join(", ")}; Home Assistant's own test passed${o.note ? ` — ${o.note}` : ""}`);
+      break;
+    case "equivalent":
+      console.log(`[hass-provisions] ${o.what}: ${o.note}`);
+      break;
+    case "refused":
+      failed++;
+      console.error(`[hass-provisions] ${o.what}: ${o.problem}`);
+      break;
+  }
+}
+process.exitCode = failed > 0 ? 1 : 0;
@@ -0,0 +1,42 @@
+// What the mesh delivered to home-assistant's provisions step, and the step's own small memory.
+//
+// Per provision it requires, the mesh writes two files beside each other (the manifest's `binds` and
+// `secrets`): `<provision>.json`, the binding — where the provider is (`at`), what it serves (`port`,
+// `scheme`, …) and the login this module presents (`as`) — and `<provision>.secret`, the pair
+// credential. Nothing here guesses a host, a port or a key.
+
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import type { Binding, Marks } from "./connections.js";
+
+/** A file the mesh wrote, or undefined when it is not there. */
+export async function readIfThere(path: string | undefined): Promise<string | undefined> {
+  if (!path) return undefined;
+  return readFile(path, "utf8").catch(() => undefined);
+}
+
+/** A binding file parsed, or undefined when absent or not JSON. */
+export async function readBinding(path: string): Promise<Binding | undefined> {
+  const raw = await readIfThere(path);
+  if (raw === undefined) return undefined;
+  try {
+    return JSON.parse(raw) as Binding;
+  } catch {
+    return undefined;
+  }
+}
+
+export function marksIn(dir: string): Marks {
+  return {
+    async get(name) {
+      return (await readIfThere(join(dir, `${name}.digest`)))?.trim() || undefined;
+    },
+    async set(name, value) {
+      await mkdir(dir, { recursive: true, mode: 0o700 });
+      const path = join(dir, `${name}.digest`);
+      await writeFile(`${path}.tmp`, `${value}\n`, { mode: 0o600 });
+      await rename(`${path}.tmp`, path);
+    },
+  };
+}
@@ -0,0 +1,117 @@
+// Ask the broker, before Home Assistant is told anything, whether it takes the login and password
+// the mesh delivered — and whether that login may subscribe to Home Assistant's discovery topics.
+//
+// One MQTT 3.1.1 session: CONNECT (clean, a throwaway client id, so Home Assistant's own session is
+// never taken over), read the CONNACK, optionally SUBSCRIBE once and read the SUBACK, DISCONNECT.
+// No dependency: the handful of bytes MQTT needs for this are written here.
+
+import { randomBytes } from "node:crypto";
+import { connect } from "node:net";
+
+export interface ProbeResult {
+  /** 0 accepted; 4 bad username or password; 5 not authorised. */
+  connack: number;
+  /** The SUBACK return code for the filter asked about: 0–2 granted, 0x80 refused. */
+  suback?: number;
+}
+
+export type Probe = (host: string, port: number, username: string, password: string, subscribe?: string) => Promise<ProbeResult>;
+
+function str(v: string): Buffer {
+  const b = Buffer.from(v, "utf8");
+  const len = Buffer.alloc(2);
+  len.writeUInt16BE(b.length);
+  return Buffer.concat([len, b]);
+}
+
+function packet(type: number, body: Buffer): Buffer {
+  let remaining = body.length;
+  const lenBytes: number[] = [];
+  do {
+    let byte = remaining % 128;
+    remaining = Math.floor(remaining / 128);
+    if (remaining > 0) byte |= 0x80;
+    lenBytes.push(byte);
+  } while (remaining > 0);
+  return Buffer.concat([Buffer.from([type, ...lenBytes]), body]);
+}
+
+/** The first complete packet in `buf`: its type byte, its body, and how many bytes it took. */
+export function firstPacket(buf: Buffer): { type: number; body: Buffer; used: number } | undefined {
+  if (buf.length < 2) return undefined;
+  let length = 0;
+  let multiplier = 1;
+  let i = 1;
+  for (;;) {
+    if (i >= buf.length) return undefined;
+    const byte = buf[i++];
+    length += (byte & 0x7f) * multiplier;
+    if ((byte & 0x80) === 0) break;
+    multiplier *= 128;
+    if (i > 4) throw new Error("malformed MQTT remaining length");
+  }
+  if (buf.length < i + length) return undefined;
+  return { type: buf[0], body: buf.subarray(i, i + length), used: i + length };
+}
+
+export const probeBroker: Probe = (host, port, username, password, subscribe) => {
+  const connectBody = Buffer.concat([
+    str("MQTT"),
+    Buffer.from([4, 0xc2, 0, 10]), // level 4 (3.1.1); username + password + clean session; keepalive 10s
+    str(`mesh-probe-${randomBytes(6).toString("hex")}`),
+    str(username),
+    str(password),
+  ]);
+  return new Promise((resolve, reject) => {
+    const socket = connect({ host, port });
+    let buf = Buffer.alloc(0);
+    const result: ProbeResult = { connack: -1 };
+    const timer = setTimeout(() => {
+      socket.destroy();
+      reject(new Error(`no answer from the broker at ${host}:${port} within 10s`));
+    }, 10_000);
+    const finish = (): void => {
+      clearTimeout(timer);
+      if (result.connack === 0) socket.end(Buffer.from([0xe0, 0]));
+      else socket.destroy();
+      resolve(result);
+    };
+    socket.on("connect", () => socket.write(packet(0x10, connectBody)));
+    socket.on("data", (chunk) => {
+      buf = Buffer.concat([buf, chunk]);
+      for (;;) {
+        let p;
+        try {
+          p = firstPacket(buf);
+        } catch (err) {
+          clearTimeout(timer);
+          socket.destroy();
+          reject(err);
+          return;
+        }
+        if (!p) return;
+        buf = buf.subarray(p.used);
+        const kind = p.type >> 4;
+        if (kind === 2) {
+          result.connack = p.body[1] ?? -1;
+          if (result.connack !== 0 || !subscribe) return finish();
+          // SUBSCRIBE, packet id 1, one filter at QoS 0.
+          socket.write(packet(0x82, Buffer.concat([Buffer.from([0, 1]), str(subscribe), Buffer.from([0])])));
+        } else if (kind === 9) {
+          result.suback = p.body[2];
+          return finish();
+        }
+      }
+    });
+    socket.on("error", (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+    socket.on("close", () => {
+      if (result.connack === -1) {
+        clearTimeout(timer);
+        reject(new Error(`the broker at ${host}:${port} closed the connection without answering`));
+      }
+    });
+  });
+};
@@ -0,0 +1,293 @@
+// What holds home-assistant's provisions step (provisions/*.ts): Home Assistant's MQTT entry is
+// made to use the broker, port and login the mesh bound — only after the broker takes that login,
+// through the reconfigure flow, keeping every other setting as Home Assistant pre-filled it, and not
+// again once it already says so; its Sonarr/Radarr/Lidarr entries are made, finished (reauth), left
+// alone when they already reach the bound app, and never removed; a key the app refuses (the mesh's
+// minted value before the operator accepts the app's) is never written.
+//
+// Home Assistant and the apps are fakes answering as the real ones do (flow shapes checked against
+// ghcr.io/home-assistant/home-assistant 2026.9.3, the build ace runs).
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import type { ConfigEntry, DeviceEntry, FlowProgress, FlowResult, Hass, SchemaField } from "../provisions/hass.ts";
+
+import type { Binding, Marks } from "../provisions/connections.ts";
+import { APPS, formValues, reconcileApp, reconcileMqtt, sameUrl, type Http, type ServarrApp } from "../provisions/connections.ts";
+import type { Probe } from "../provisions/probe.ts";
+
+const PWD_NOT_CHANGED = "__**password_not_changed**__";
+const MINTED = "mesh-minted-password";
+
+function mqttBinding(): Binding {
+  return { provision: "mqtt-topic", from: "ace", at: "ace.internal", as: "mesh_ace_hass", serves: { scheme: "mqtt", port: 1883 } };
+}
+
+/** The MQTT reconfigure form as Home Assistant serializes it, pre-filled from an entry. */
+function brokerForm(data: Record<string, unknown>): SchemaField[] {
+  return [
+    { name: "broker", type: "string", required: true, description: { suggested_value: data.broker } },
+    { name: "port", type: "integer", required: true, default: 1883, description: { suggested_value: data.port } },
+    { name: "protocol", type: "select", required: true, default: "3.1.1", description: { suggested_value: data.protocol } },
+    { name: "username", type: "string", optional: true, description: { suggested_value: data.username } },
+    { name: "password", type: "string", optional: true, description: { suggested_value: data.password ? PWD_NOT_CHANGED : undefined } },
+    {
+      name: "other_settings",
+      type: "expandable",
+      required: true,
+      schema: [
+        { name: "keepalive", type: "integer", optional: true, description: { suggested_value: 60 } },
+        { name: "transport", type: "select", required: true, default: "tcp", description: { suggested_value: "tcp" } },
+        { name: "set_ca_cert", type: "select", required: true, description: { suggested_value: "off" } },
+        { name: "set_client_cert", type: "boolean", required: true, description: { suggested_value: false } },
+      ],
+    },
+  ];
+}
+
+interface FakeOpts {
+  entries?: Record<string, (ConfigEntry & { data: Record<string, unknown> })[]>;
+  /** What Home Assistant's own connection test accepts. */
+  accepts?: (data: Record<string, unknown>) => boolean;
+  reauth?: FlowProgress[];
+  devices?: DeviceEntry[];
+}
+
+function fakeHass(opts: FakeOpts = {}) {
+  const entries = opts.entries ?? {};
+  const calls: string[] = [];
+  const submitted: Record<string, unknown>[] = [];
+  const flows = new Map<string, { handler: string; entryId?: string; step: string; reauth?: boolean }>();
+  let n = 0;
+  const accepts = opts.accepts ?? (() => true);
+  const form = (id: string, step: string, schema: SchemaField[], errors?: Record<string, string>): FlowResult => ({
+    type: "form", flow_id: id, step_id: step, data_schema: schema, errors: errors ?? null,
+  });
+  const servarrUser: SchemaField[] = [
+    { name: "url", type: "string", required: true },
+    { name: "api_key", type: "string", required: true },
+    { name: "more_options", type: "expandable", required: true, schema: [{ name: "verify_ssl", type: "boolean", optional: true, default: false }] },
+  ];
+  const hass: Hass = {
+    async entries(domain) {
+      calls.push(`entries ${domain}`);
+      return (entries[domain] ?? []).map(({ data: _d, ...e }) => e);
+    },
+    async startFlow(handler, entryId) {
+      calls.push(`start ${handler}${entryId ? ` ${entryId}` : ""}`);
+      const id = `f${++n}`;
+      if (handler === "mqtt") {
+        const entry = entryId ? entries.mqtt.find((e) => e.entry_id === entryId) : undefined;
+        if (entryId && !entry) return { type: "abort", reason: "not_found" };
+        flows.set(id, { handler, entryId, step: "broker" });
+        return form(id, "broker", brokerForm(entry?.data ?? {}));
+      }
+      if (entryId) return { type: "abort", reason: "not_implemented" }; // no reconfigure for Servarr
+      flows.set(id, { handler, step: "user" });
+      return form(id, "user", servarrUser);
+    },
+    async stepFlow(flowId, input) {
+      calls.push(`step ${flowId}`);
+      const flow = flows.get(flowId);
+      if (!flow) throw new Error(`Home Assistant POST flow/${flowId} answered 404`);
+      if (flow.step === "reauth_confirm") {
+        flow.step = "user";
+        return form(flowId, "user", [
+          { name: "url", type: "string", required: true, default: "http://old:1" },
+          { name: "api_key", type: "string", optional: true },
+          { name: "verify_ssl", type: "boolean", optional: true, default: false },
+        ]);
+      }
+      submitted.push(input);
+      if (flow.handler === "mqtt") {
+        const entry = entries.mqtt?.find((e) => e.entry_id === flow.entryId);
+        const data = { ...input, ...(input.password === PWD_NOT_CHANGED ? { password: entry?.data.password } : {}) };
+        if (!accepts(data)) return form(flowId, "broker", brokerForm(data), { base: "cannot_connect" });
+        flows.delete(flowId);
+        if (entry) {
+          entry.data = data;
+          return { type: "abort", reason: "reconfigure_successful" };
+        }
+        (entries.mqtt ??= []).push({ entry_id: "new-mqtt", domain: "mqtt", state: "loaded", data });
+        return { type: "create_entry", result: { entry_id: "new-mqtt" } };
+      }
+      if (!accepts(input)) return form(flowId, "user", servarrUser, { base: "invalid_auth" });
+      flows.delete(flowId);
+      if (flow.reauth) return { type: "abort", reason: "reauth_successful" };
+      (entries[flow.handler] ??= []).push({ entry_id: `new-${flow.handler}`, domain: flow.handler, state: "loaded", data: input });
+      return { type: "create_entry", result: { entry_id: `new-${flow.handler}` } };
+    },
+    async abortFlow(flowId) {
+      calls.push(`abort ${flowId}`);
+      flows.delete(flowId);
+    },
+    async flowsInProgress() {
+      for (const f of opts.reauth ?? []) flows.set(f.flow_id, { handler: f.handler, entryId: f.context?.entry_id, step: "reauth_confirm", reauth: true });
+      return opts.reauth ?? [];
+    },
+    async devices() {
+      return opts.devices ?? [];
+    },
+  };
+  return { hass, calls, submitted, entries };
+}
+
+function memoryMarks(): Marks & { store: Map<string, string> } {
+  const store = new Map<string, string>();
+  return { store, get: async (k) => store.get(k), set: async (k, v) => void store.set(k, v) };
+}
+
+const takes = (suback = 0): Probe => async (_h, _p, user, pass) => ({ connack: user === "mesh_ace_hass" && pass === MINTED ? 0 : 5, suback });
+
+const aceMqttEntry = () => ({
+  entry_id: "7d1e", domain: "mqtt", state: "loaded",
+  data: { broker: "127.0.0.1", port: 1883, protocol: "5", username: "luffy", password: "luffys-password" },
+});
+
+test("mqtt: the broker is asked first; a login it does not take is never written", async () => {
+  const f = fakeHass({ entries: { mqtt: [aceMqttEntry()] } });
+  const out = await reconcileMqtt({ hass: f.hass, probe: async () => ({ connack: 5 }), marks: memoryMarks() }, mqttBinding(), MINTED);
+  assert.equal(out.result, "refused");
+  assert.match((out as { problem: string }).problem, /does not \(yet\) take the login mesh_ace_hass/);
+  assert.deepEqual(f.calls, []); // Home Assistant not even asked
+  assert.equal(f.entries.mqtt[0].data.username, "luffy");
+});
+
+test("mqtt: ace's entry (127.0.0.1, luffy) is moved to the bound broker and login, every other setting kept", async () => {
+  const f = fakeHass({ entries: { mqtt: [aceMqttEntry()] } });
+  const marks = memoryMarks();
+  const out = await reconcileMqtt({ hass: f.hass, probe: takes(), marks }, mqttBinding(), `${MINTED}\n`);
+  assert.deepEqual(out, { what: "mqtt", result: "written", fields: ["broker", "username", "password"] });
+  assert.deepEqual(f.entries.mqtt[0].data, {
+    broker: "ace.internal", port: 1883, protocol: "5", username: "mesh_ace_hass", password: MINTED,
+    other_settings: { keepalive: 60, transport: "tcp", set_ca_cert: "off", set_client_cert: false },
+  });
+  assert.ok(marks.store.get("mqtt"));
+  assert.ok(![...marks.store.values()].some((v) => v.includes(MINTED)));
+
+  // Run again: nothing differs, the flow is opened to read and closed without submitting.
+  const before = f.submitted.length;
+  const again = await reconcileMqtt({ hass: f.hass, probe: takes(), marks }, mqttBinding(), MINTED);
+  assert.deepEqual(again, { what: "mqtt", result: "unchanged" });
+  assert.equal(f.submitted.length, before);
+  assert.match(f.calls.at(-1) ?? "", /^abort /);
+});
+
+test("mqtt: a new password alone is written (the digest tells)", async () => {
+  const f = fakeHass({ entries: { mqtt: [aceMqttEntry()] } });
+  const marks = memoryMarks();
+  await reconcileMqtt({ hass: f.hass, probe: takes(), marks }, mqttBinding(), MINTED);
+  const rotated: Probe = async () => ({ connack: 0, suback: 0 });
+  const out = await reconcileMqtt({ hass: f.hass, probe: rotated, marks }, mqttBinding(), "rotated");
+  assert.deepEqual(out, { what: "mqtt", result: "written", fields: ["password"] });
+  assert.equal(f.entries.mqtt[0].data.password, "rotated");
+});
+
+test("mqtt: Home Assistant's own connection test refusing saves nothing and fails loudly", async () => {
+  const f = fakeHass({ entries: { mqtt: [aceMqttEntry()] }, accepts: () => false });
+  const marks = memoryMarks();
+  const out = await reconcileMqtt({ hass: f.hass, probe: takes(), marks }, mqttBinding(), MINTED);
+  assert.equal(out.result, "refused");
+  assert.match((out as { problem: string }).problem, /cannot_connect.*unchanged/);
+  assert.equal(f.entries.mqtt[0].data.username, "luffy");
+  assert.equal(marks.store.size, 0);
+});
+
+test("mqtt: a fresh Home Assistant gets an entry; a grant without the discovery topics is warned about", async () => {
+  const f = fakeHass();
+  const out = await reconcileMqtt({ hass: f.hass, probe: takes(0x80), marks: memoryMarks() }, mqttBinding(), MINTED);
+  assert.equal(out.result, "written");
+  assert.match((out as { note?: string }).note ?? "", /may not subscribe to homeassistant\/#/);
+  assert.equal(f.entries.mqtt[0].data.broker, "ace.internal");
+});
+
+test("mqtt: two entries, or a binding without a port, are refused rather than guessed", async () => {
+  const f = fakeHass({ entries: { mqtt: [aceMqttEntry(), { ...aceMqttEntry(), entry_id: "other" }] } });
+  assert.equal((await reconcileMqtt({ hass: f.hass, probe: takes(), marks: memoryMarks() }, mqttBinding(), MINTED)).result, "refused");
+  const noPort = { ...mqttBinding(), serves: {} };
+  assert.match(((await reconcileMqtt({ hass: f.hass, probe: takes(), marks: memoryMarks() }, noPort, MINTED)) as { problem: string }).problem, /no usable port/);
+});
+
+// ---- Servarr ----
+
+const SONARR = APPS.find((a) => a.domain === "sonarr") as ServarrApp;
+const RADARR = APPS.find((a) => a.domain === "radarr") as ServarrApp;
+const KEY = "the-apps-own-key";
+const servarrBinding = (port: number, at = "ace.internal"): Binding => ({ provision: "sonarr-api", from: "ace", at, as: "mesh_ace_hass", serves: { scheme: "http", port, "url-base": "" } });
+
+/** One running Sonarr, answering on several addresses (127.0.0.1 and ace.internal are one host). */
+function apps(instances: Record<string, { startTime: string }>): Http & { asked: string[] } {
+  const asked: string[] = [];
+  return {
+    asked,
+    async fetch(url, init) {
+      asked.push(url);
+      const u = new URL(url);
+      const inst = instances[`${u.hostname}:${u.port}`];
+      if (!inst) throw new Error("connect ECONNREFUSED");
+      if (init?.headers?.["X-Api-Key"] !== KEY) return { status: 401, text: async () => "" };
+      return { status: 200, text: async () => JSON.stringify({ version: "4.0.15", appData: "/config", startTime: inst.startTime }) };
+    },
+  };
+}
+const oneSonarr = () => apps({ "ace.internal:8989": { startTime: "t1" }, "127.0.0.1:8989": { startTime: "t1" } });
+const sonarrEntry = (state = "loaded") => ({ entry_id: "5a1d", domain: "sonarr", state, data: { url: "http://127.0.0.1:8989", api_key: KEY } });
+
+test("servarr: the mesh's minted key is never written; the remedy names the accept", async () => {
+  const f = fakeHass({ entries: { sonarr: [sonarrEntry()] } });
+  const out = await reconcileApp({ hass: f.hass, http: oneSonarr() }, SONARR, servarrBinding(8989), "minted-by-the-mesh");
+  assert.equal(out.result, "refused");
+  assert.match((out as { problem: string }).problem, /secret accept <this node> home-assistant sonarr-api --provider ace/);
+  assert.deepEqual(f.calls, []);
+});
+
+test("servarr: ace's entry at 127.0.0.1 reaches the same Sonarr the mesh bound at ace.internal — left, and said", async () => {
+  const f = fakeHass({ entries: { sonarr: [sonarrEntry()] }, devices: [{ id: "d", config_entries: ["5a1d"], configuration_url: "http://127.0.0.1:8989" }] });
+  const out = await reconcileApp({ hass: f.hass, http: oneSonarr() }, SONARR, servarrBinding(8989), KEY);
+  assert.equal(out.result, "equivalent");
+  assert.equal(f.submitted.length, 0);
+});
+
+test("servarr: an entry already at the bound URL is unchanged", async () => {
+  const f = fakeHass({ entries: { sonarr: [sonarrEntry()] }, devices: [{ id: "d", config_entries: ["5a1d"], configuration_url: "http://ace.internal:8989" }] });
+  assert.deepEqual(await reconcileApp({ hass: f.hass, http: oneSonarr() }, SONARR, servarrBinding(8989), KEY), { what: "sonarr", result: "unchanged" });
+});
+
+test("servarr: a working entry that reaches a different app is refused, and nothing is removed", async () => {
+  const f = fakeHass({ entries: { sonarr: [sonarrEntry()] }, devices: [{ id: "d", config_entries: ["5a1d"], configuration_url: "http://127.0.0.1:8989" }] });
+  const two = apps({ "ace.internal:8989": { startTime: "t1" }, "127.0.0.1:8989": { startTime: "another" } });
+  const out = await reconcileApp({ hass: f.hass, http: two }, SONARR, servarrBinding(8989), KEY);
+  assert.equal(out.result, "refused");
+  assert.match((out as { problem: string }).problem, /never does/);
+  assert.equal(f.entries.sonarr.length, 1);
+});
+
+test("servarr: no entry — one is made at the bound URL through the user flow", async () => {
+  const f = fakeHass({ entries: {} });
+  const out = await reconcileApp({ hass: f.hass, http: oneSonarr() }, SONARR, servarrBinding(8989), KEY);
+  assert.deepEqual(out, { what: "sonarr", result: "written", fields: ["entry"] });
+  assert.deepEqual(f.submitted[0], { url: "http://ace.internal:8989", api_key: KEY, more_options: { verify_ssl: false } });
+});
+
+test("servarr: a reauth Home Assistant started is finished with the bound URL and key", async () => {
+  const entry = { ...sonarrEntry("setup_error"), domain: "radarr", entry_id: "1955" };
+  const f = fakeHass({
+    entries: { radarr: [entry] },
+    reauth: [{ flow_id: "r1", handler: "radarr", step_id: "reauth_confirm", context: { source: "reauth", entry_id: "1955" } }],
+  });
+  const radarr = apps({ "ace.internal:7878": { startTime: "t" } });
+  const out = await reconcileApp({ hass: f.hass, http: radarr }, RADARR, { ...servarrBinding(7878), provision: "radarr-api" }, KEY);
+  assert.deepEqual(out, { what: "radarr", result: "written", fields: ["api_key", "url"] });
+  assert.deepEqual(f.submitted[0], { url: "http://ace.internal:7878", api_key: KEY, verify_ssl: false });
+});
+
+test("form values: suggested first, then default, sections nested", () => {
+  assert.deepEqual(formValues(brokerForm({ broker: "b", port: 1, protocol: "5", username: "u", password: "p" })), {
+    broker: "b", port: 1, protocol: "5", username: "u", password: PWD_NOT_CHANGED,
+    other_settings: { keepalive: 60, transport: "tcp", set_ca_cert: "off", set_client_cert: false },
+  });
+  assert.ok(sameUrl("http://ace.internal:8989/", "http://ace.internal:8989"));
+  assert.ok(sameUrl("http://ACE.internal", "http://ace.internal:80"));
+  assert.ok(!sameUrl("http://127.0.0.1:8989", "http://ace.internal:8989"));
+});
@@ -8,5 +8,14 @@
    "skipLibCheck": true,
    "noEmit": true
  },
-  "include": ["client.ts", "index.ts", "tools/index.ts"]
+  "include": [
+    "client.ts",
+    "index.ts",
+    "tools/index.ts",
+    "provisions/hass.ts",
+    "provisions/probe.ts",
+    "provisions/connections.ts",
+    "provisions/mesh.ts",
+    "provisions/index.ts"
+  ]
 }
@@ -1,24 +0,0 @@
-# icecast's runtime: the tool runtime, carrying this module's compiled code.
-#
-# **Built from this module's own directory and nothing else.** The sdk and the tool runtime are in
-# the base images, published like any other artifact — which is what makes this buildable by the
-# mesh from a repository and a path (novox/hq ADR 0069) rather than only on a workstation that
-# happens to have the siblings.
-#
-# Two bases, named rather than pinned (novox/hq issue 044): the image this is COMPILED in and the
-# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
-ARG BUILD_BASE
-ARG RUNTIME_BASE
-
-FROM ${BUILD_BASE} AS build
-WORKDIR /app/modules/icecast
-COPY . .
-RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts \
-      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
-
-FROM ${RUNTIME_BASE}
-COPY --from=build /app/modules/icecast/dist /app/modules/icecast/dist
-# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
-# provider's provisioner runs its reconcile loop in the same process, with the broker connected —
-# the convention novox/hq issues 060/061 settled.
-ENV MESH_TOOL_MODULES=/app/modules/icecast/dist/index.js,/app/modules/icecast/dist/tools/index.js
--- a/Show More
+++ b/Show More