The photo clients publish the endpoint they declare (hq issue 227)

Each declares a web endpoint — 4001, 4012, 4013 — and published a bare 80,
which the mesh has nothing to assign for, so 80 reached the machine and
collided with the reverse proxy. Written the long way, the software's 80 is
published at the port the module declares and the mesh rewrites the outer
half to whatever it assigned.

photos is the one that failed on the control node; the other two are the same
fault waiting for a machine that runs a proxy.

modules/claude-code/README.md

@@ -33,7 +33,7 @@ this node a subscription token. Nothing else under the home is read or written.
 Everything between this module and the rest of the mesh is NATS, in three kinds: an **event** says that
 something happened and carries no secret, because a stream keeps it; a **request** carries a token,
 because nothing keeps it (hq design 32 §10); and **state** is the current value of something every node
-must see, a node that joins later included — kept, so it carries no secret either (hq ADR 0202).
+must see, a node that joins later included — kept, so it carries no secret either (hq ADR 0201).
 
 | what | how |
 |---|---|

modules/claude-code/node.ts

@@ -9,7 +9,7 @@
 //   - a login a person made here — a refresh token this module never writes — is offered to the seat at
 //     once, sealed to the seat's key: the one moment a refresh token travels, because the login made the
 //     manager's stale;
-//   - an MCP server registered through this module is **state, not an event** (novox/hq ADR 0202): one
+//   - 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.

modules/claude-code/tools/index.ts

@@ -5,10 +5,11 @@
 //
 // At start it renders the agent's managed directory, asks the licence manager for this node's token,
 // begins watching the credentials file for a login, takes the manager's licence events, and watches the
-// module's `servers` state — every node's MCP server registrations (novox/hq ADR 0202). node.ts holds the
+// module's `servers` state — every node's MCP server registrations (novox/hq ADR 0201). node.ts holds the
 // logic.
 
-import { readFileSync, watchFile } from "node:fs";
+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";
@@ -41,9 +42,15 @@ const writeManaged: WriteManaged = (name, content) => {
   } 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", "/dev/stdin", path] : ["sudo", "-n", "install", "-D", "-m", "0644", "/dev/stdin", path];
-  const r = spawnSync(cmd[0], cmd.slice(1), { input: content, encoding: "utf8" });
+  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`);
@@ -92,7 +99,7 @@ function status(p: Paths): Record<string, unknown> {
   };
 }
 
-/** The module's MCP servers on the bus (ADR 0202): its own state, which every node of it watches. */
+/** 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. */
@@ -180,20 +187,29 @@ if (p) {
     say(JSON.stringify(await pull(p, ask, writeManaged).catch((e) => ({ failed: String(e) }))));
   }).catch(loud("the licence events"));
 
-  // Every node's MCP servers: the whole current set first, then each change (ADR 0202). Awaited, so the
-  // managed directory holds every server that applies here before the bundle says what it serves.
-  try {
-    await state<Record<string, unknown>>("servers").watch((c) => {
+  // 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
       }
-    });
-  } catch (err) {
-    loud("watching the MCP servers")(err);
-  }
+    }).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"));

modules/photos-eef/module.json

@@ -45,7 +45,7 @@
       "image": "registry-api.novox.be/novox/photos-client@sha256:f87d63ee7bfb44c9f9748b99be6ba6dc0daf955a1d463699e9e7e3009693c0ab",
       "network": "photos-eef",
       "ports": [
-        "80"
+        "4012:80"
       ],
       "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)"

modules/photos-filip/module.json

@@ -45,7 +45,7 @@
       "image": "registry-api.novox.be/novox/photos-client@sha256:f87d63ee7bfb44c9f9748b99be6ba6dc0daf955a1d463699e9e7e3009693c0ab",
       "network": "photos-filip",
       "ports": [
-        "80"
+        "4013:80"
       ],
       "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)"

modules/photos/module.json

@@ -89,7 +89,7 @@
       "image": "registry-api.novox.be/novox/photos-admin-client@sha256:f437fa9ed28b29a012f715fb8d9b809a15cff4a672794c620d5d400f57695580",
       "network": "photos",
       "ports": [
-        "80"
+        "4001:80"
       ],
       "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)"

modules/systemd-networkd/module.json

@@ -2,7 +2,6 @@
   "module": "systemd-networkd",
   "version": "1",
   "capabilities": [
-    "package-manager",
     "service-manager",
     "uplink-systemd-networkd"
   ],
@@ -13,17 +12,12 @@
     }
   ],
   "resources": [
-    {
-      "id": "package",
-      "type": "package",
-      "package": "systemd"
-    },
     {
       "id": "config",
       "type": "file",
       "path": "/etc/systemd/network/00-mesh0.network",
       "mode": "0644",
-      "content": "# Managed by the mesh (module systemd-networkd). Replaced on every push; edit\n# the catalogue instead.\n#\n# This machine's uplink is systemd-networkd's, and the mesh asks one thing of it\n# here (novox/hq ADR 0117): leave the private network's interface alone. mesh0\n# is the mesh's; the mesh brings it up and configures it itself. The mesh never\n# declares a link, an address, a route, a wireless network or its credentials,\n# nor a network file for any of this machine's own interfaces \u2014 those are\n# the operator's, and the link they make is the only channel the mesh reaches\n# this machine over.\n#\n# 00-: networkd applies the first .network file, in alphanumeric order across\n# every directory, that matches an interface, and ignores every later one even\n# if it matches too (systemd.network(5), [Match]). A catch-all of the operator's\n# \u2014 Name=*, Type=ether, a file with no [Match] at all \u2014 sorted before\n# this one would claim mesh0 first. 00 sorts before every numbered prefix the\n# man page recommends.\n#\n# Unmanaged=yes: \"no attempts are made to bring up or configure matching links,\n# equivalent to when there are no matching network files\" (systemd.network(5),\n# [Link], since 233). A match that ends the search, and does nothing else.\n#\n# No DNS setting, because none is needed: networkd never writes\n# /etc/resolv.conf. What it learns from a lease it hands only to\n# systemd-resolved, and the resolver file stays whatever resolv-conf wrote.\n# Whether resolved runs, and what it does with that, is the resolver\n# configuration's question, not the uplink's.\n#\n# The service is reloaded when this file changes, never restarted: a restart\n# drops the links networkd holds, this machine's channel to the mesh among them.\n[Match]\nName=mesh0\n\n[Link]\nUnmanaged=yes\n"
+      "content": "# Managed by the mesh (module systemd-networkd). Replaced on every push; edit\n# the catalogue instead.\n#\n# This machine's uplink is systemd-networkd's, and the mesh asks one thing of it\n# here (novox/hq ADR 0117): leave the private network's interface alone. mesh0\n# is the mesh's; the mesh brings it up and configures it itself. The mesh never\n# declares a link, an address, a route, a wireless network or its credentials,\n# nor a network file for any of this machine's own interfaces — those are\n# the operator's, and the link they make is the only channel the mesh reaches\n# this machine over.\n#\n# 00-: networkd applies the first .network file, in alphanumeric order across\n# every directory, that matches an interface, and ignores every later one even\n# if it matches too (systemd.network(5), [Match]). A catch-all of the operator's\n# — Name=*, Type=ether, a file with no [Match] at all — sorted before\n# this one would claim mesh0 first. 00 sorts before every numbered prefix the\n# man page recommends.\n#\n# Unmanaged=yes: \"no attempts are made to bring up or configure matching links,\n# equivalent to when there are no matching network files\" (systemd.network(5),\n# [Link], since 233). A match that ends the search, and does nothing else.\n#\n# No DNS setting, because none is needed: networkd never writes\n# /etc/resolv.conf. What it learns from a lease it hands only to\n# systemd-resolved, and the resolver file stays whatever resolv-conf wrote.\n# Whether resolved runs, and what it does with that, is the resolver\n# configuration's question, not the uplink's.\n#\n# The service is reloaded when this file changes, never restarted: a restart\n# drops the links networkd holds, this machine's channel to the mesh among them.\n[Match]\nName=mesh0\n\n[Link]\nUnmanaged=yes\n"
     },
     {
       "id": "service",

modules/systemd/module.json

@@ -2,7 +2,8 @@
   "module": "systemd",
   "version": "1",
   "capabilities": [
-    "service-manager"
+    "service-manager",
+    "package-manager"
   ],
   "claims": [
     {
@@ -34,5 +35,12 @@
         ]
       }
     ]
-  }
+  },
+  "resources": [
+    {
+      "id": "package",
+      "type": "package",
+      "package": "systemd"
+    }
+  ]
 }

modules/systemd/test/client.test.ts

@@ -156,9 +156,12 @@ test("a unit's name is never an option", async () => {
   assert.deepEqual(calls[0].args.slice(-2), ["--", "-x*"]);
 });
 
-test("the manifest declares no package — the service manager is always there, and networkd declares it too", () => {
+test("the manifest owns the systemd package — the service manager's own, never a component module's", () => {
   const m = JSON.parse(readFileSync(new URL("../module.json", import.meta.url), "utf8"));
-  assert.ok(!(m.resources ?? []).some((r: { type: string }) => r.type === "package"));
-  assert.ok(!m.capabilities.includes("package-manager"));
+  assert.ok((m.resources ?? []).some((r: { type: string; package?: string }) => r.type === "package" && r.package === "systemd"));
+  assert.ok(m.capabilities.includes("package-manager"));
+  // networkd is a component of systemd and configures it; it never claims the package.
+  const networkd = JSON.parse(readFileSync(new URL("../../systemd-networkd/module.json", import.meta.url), "utf8"));
+  assert.ok(!(networkd.resources ?? []).some((r: { type: string; package?: string }) => r.type === "package" && r.package === "systemd"));
   assert.deepEqual(m.claims[0].serves, ["units", "status", "start", "stop", "restart", "enable", "disable", "journal"]);
 });

modules/zsh/module.json

@@ -51,7 +51,7 @@
       "mode": "0644",
       "into": "block",
       "at": "start",
-      "content": "# The mesh's block (module zsh, novox/hq ADR 0203, ADR 0204): the account's environment, read by\n# every zsh — a login, a script, and node-login-shell's execute. Replaced at every push; everything\n# outside it is yours.\nif [[ -r \"${machine:account-home}/.config/mesh/environment.sh\" ]]; then\n  source \"${machine:account-home}/.config/mesh/environment.sh\"\nfi\n"
+      "content": "# The mesh's block (module zsh, novox/hq ADR 0203, ADR 0204): the account's environment, read by\n# every zsh — a login, a script, and node-login-shell's execute. Replaced at every push; everything\n# outside it is yours.\n# PATH keeps each directory once, wherever it was added: the session, a nested shell or a\n# sourced file. Without it every nested shell prepended the same entries again.\ntypeset -U path PATH\nif [[ -r \"${machine:account-home}/.config/mesh/environment.sh\" ]]; then\n  source \"${machine:account-home}/.config/mesh/environment.sh\"\nfi\n"
     },
     {
       "id": "rc",
@@ -61,7 +61,7 @@
       "mode": "0644",
       "into": "block",
       "at": "start",
-      "content": "# The mesh's block (module zsh, novox/hq ADR 0204): the defaults every machine shares, and the code\n# other modules contribute in three slots. It is replaced at every push. Everything below it is\n# yours, kept as you wrote it, and runs after it, so your lines win.\n${shell:zsh:first}\n# Terminal title: host, directory, git branch\nfunction set_terminal_title() {\n  local git_branch=\"\"\n  if git rev-parse --is-inside-work-tree &>/dev/null; then\n    git_branch=\" ($(git branch --show-current 2>/dev/null))\"\n  fi\n  print -Pn \"\\e]2;%m: %~${git_branch}\\a\"\n}\nprecmd_functions+=(set_terminal_title)\n\n# Keybindings\nbindkey  \"^[[H\"   beginning-of-line   # Home\nbindkey  \"^[OH\"   beginning-of-line   # Home\nbindkey  \"^A\"   beginning-of-line     # Ctrl + A\nbindkey  \"^[[F\"   end-of-line         # End\nbindkey  \"^[OF\"   end-of-line         # End\nbindkey  \"^E\"   end-of-line           # Ctrl + E\nbindkey  \"^[[3~\"  delete-char         # Del\n\n# Colour support of ls and friends\nif [ -x /usr/bin/dircolors ]; then\n  test -r $HOME/.dircolors && eval \"$(dircolors -b $HOME/.dircolors)\" || eval \"$(dircolors -b)\"\n  alias ls='ls --color=auto'\n  alias dir='dir --color=auto'\n  alias vdir='vdir --color=auto'\n  alias grep='grep --color=auto'\n  alias fgrep='fgrep --color=auto'\n  alias egrep='egrep --color=auto'\nfi\nalias ll='ls -alhF'\nalias la='ls -Ah'\nalias l='ls -CFh'\n\n# A throwaway container, and what takes the space under a directory\nalias drun='docker run -it --rm'\ndisksize() {\n  du -h --max-depth=1 \"${1:-.}\" | sort -h\n}\nsudo-disksize() {\n  sudo du -h --max-depth=1 \"${1:-.}\" | sort -h\n}\n\n${shell:zsh:normal}${shell:zsh:last}\n"
+      "content": "# The mesh's block (module zsh, novox/hq ADR 0204): the defaults every machine shares, and the code\n# other modules contribute in three slots. It is replaced at every push. Everything below it is\n# yours, kept as you wrote it, and runs after it, so your lines win.\n${shell:zsh:first}\n# History, kept across sessions and shared between open shells. Without these zsh saves none:\n# SAVEHIST defaults to 0 (novox/hq to-be 41, found on review 2026-10-04).\nHISTFILE=\"$HOME/.zsh_history\"\nHISTSIZE=100000\nSAVEHIST=100000\nsetopt EXTENDED_HISTORY SHARE_HISTORY HIST_IGNORE_DUPS HIST_IGNORE_SPACE HIST_REDUCE_BLANKS\n\n# The completion system. Nothing initialised it, so only zsh's basic completion ran. Its cache\n# goes under ~/.cache rather than beside ~/.zshrc.\n[[ -d \"$HOME/.cache/zsh\" ]] || mkdir -p \"$HOME/.cache/zsh\"\nautoload -Uz compinit && compinit -d \"$HOME/.cache/zsh/zcompdump\"\nzstyle ':completion:*' menu select\n\n# Terminal title: host, directory, git branch\nfunction set_terminal_title() {\n  local git_branch=\"\"\n  if git rev-parse --is-inside-work-tree &>/dev/null; then\n    git_branch=\" ($(git branch --show-current 2>/dev/null))\"\n  fi\n  print -Pn \"\\e]2;%m: %~${git_branch}\\a\"\n}\nprecmd_functions+=(set_terminal_title)\n\n# Keybindings\nbindkey  \"^[[H\"   beginning-of-line   # Home\nbindkey  \"^[OH\"   beginning-of-line   # Home\nbindkey  \"^A\"   beginning-of-line     # Ctrl + A\nbindkey  \"^[[F\"   end-of-line         # End\nbindkey  \"^[OF\"   end-of-line         # End\nbindkey  \"^E\"   end-of-line           # Ctrl + E\nbindkey  \"^[[3~\"  delete-char         # Del\n\n# Colour support of ls and friends\nif [ -x /usr/bin/dircolors ]; then\n  test -r $HOME/.dircolors && eval \"$(dircolors -b $HOME/.dircolors)\" || eval \"$(dircolors -b)\"\n  alias ls='ls --color=auto'\n  alias dir='dir --color=auto'\n  alias vdir='vdir --color=auto'\n  alias grep='grep --color=auto'\n  alias fgrep='fgrep --color=auto'\n  alias egrep='egrep --color=auto'\nfi\nalias ll='ls -alhF'\nalias la='ls -Ah'\nalias l='ls -CFh'\n\n# A throwaway container, and what takes the space under a directory\nalias drun='docker run -it --rm'\ndisksize() {\n  du -h --max-depth=1 \"${1:-.}\" | sort -h\n}\nsudo-disksize() {\n  sudo du -h --max-depth=1 \"${1:-.}\" | sort -h\n}\n\n${shell:zsh:normal}${shell:zsh:last}\n"
     },
     {
       "id": "login",