@celilo/cli 0.25.1 → 0.26.1

package/CELILO_CORE_MODULES.md

@@ -27,7 +27,7 @@ Each entry: `module id` — what it is — **provides** / **requires** capabilit
 - **knot-unbound-internal** — split-horizon internal DNS via Knot (authoritative) + Unbound (recursive); lightweight, plain apt, no .NET. **provides:** `dns_internal`. Ships a base-module-aspect (`modules/knot-unbound-internal/base-module-aspect/`).
 - **technitium** — internal split-horizon DNS resolver + authoritative server (web UI + HTTP API); heavier alternative to knot-unbound. **provides:** `dns_internal`. Ships a base-module-aspect (`modules/technitium/base-module-aspect/`).
 - **namecheap** — public DNS A-record management via Namecheap Dynamic DNS API (HTTP, no browser automation). A caller supplies a NAME and nothing else: the address is the source IP of celilo's own update, re-derived on every assert. Registering `<domain>` also claims `www.<domain>` and vice versa (best effort, reported back as `outputs.companion_fqdn` so the framework's `public_dns` check watches it — Namecheap answers `ErrCount 0` for `www` updates it does not apply). DDNS passwords are keyed by the **registrable domain**, never the FQDN. **provides:** `dns_registrar`.
-- **wireguard** — owns the admin WireGuard tunnel on the firewall host: interface, listen port, peers (as records), and client subnet are module config rather than hand-maintained state. Exposes the listen port and **registers the client subnet as a trusted source**, so VPN reach into the managed zones is in the firewall registry and every converge re-emits it. **REQUIRES the `control-plane-vpn` network and READS its range** (`requires.networks`; `client_subnet` is a `source: system` derive of `network.control-plane-vpn.subnet`). It does not write that network and has no way to — celilo owns the namespace, and the deploy will not reach any hook until the network is defined, asking for a range if one is missing. So `wg0` is attributable the moment it exists. This replaces a declare-before-you-create ordering inside `on_install`, which could only narrow the window and not close it: a consumer that captured config before the hook started could not see a value the hook wrote, whatever order it wrote it in, and that is exactly what left `wg0` unattributable (celilo#759). `health_check` still asserts the declaration matches what the tunnel serves — what it catches now is divergence, celilo's network having changed since the module resolved its config. That same key is what the internal resolver's split-horizon view consumes. Adopts a running tunnel in place (existing key retained; `wg syncconf`, never `wg-quick down`) because that tunnel is the operator's recovery path. **Adoption is a one-time IMPORT and it ENDS.** The marker is `registered_peers` — celilo's own config key, separate from the operator's `peers` so a machine can never rewrite what an operator typed. While that key has never been written the tunnel is not yet celilo's; the deploy that writes it (even as `[]`) CLAIMS the tunnel, importing whatever `[Peer]` blocks are running, and from then on the render is closed-world (`peers` ∪ `registered_peers`) with a `[Peer]` on the box in neither reported as drift by `on_install` and by `health_check`'s `unknown_peers`. An ABSENT `peers` declaration and a declared-EMPTY one are deliberately different (no `default: []` on either variable): they used to be the same value, so the module read every empty list as "adopt what is running", the last peer could not be revoked, and a hand-added peer rode along on every deploy unreported (celilo#765). On a tunnel celilo has not yet claimed, a declared-empty `peers` is REFUSED rather than obeyed — celilo's own variable-default seeding wrote a real `peers = []` row for every install of the previous version that never set one, so on the installed base an empty list cannot be told from a stored default, and obeying it would `wg syncconf` the admin tunnel down to zero peers. **requires:** `firewall` (and the provider must support trusted-source registration — `iptables` does; the ISP-router drivers `greenwave` and `axon` do not).
+- **wireguard** — owns the admin WireGuard tunnel on the firewall host: interface, listen port, peers (as records), and client subnet are module config rather than hand-maintained state. Exposes the listen port and **registers the client subnet as a trusted source**, so VPN reach into the managed zones is in the firewall registry and every converge re-emits it. **REQUIRES the `control-plane-vpn` network and READS its range** (`requires.networks`; `client_subnet` is a `source: system` derive of `network.control-plane-vpn.subnet`). It does not write that network and has no way to — celilo owns the namespace, and the deploy will not reach any hook until the network is defined, asking for a range if one is missing. So `wg0` is attributable the moment it exists. This replaces a declare-before-you-create ordering inside `on_install`, which could only narrow the window and not close it: a consumer that captured config before the hook started could not see a value the hook wrote, whatever order it wrote it in, and that is exactly what left `wg0` unattributable (celilo#759). `health_check` still asserts the declaration matches what the tunnel serves — what it catches now is divergence, celilo's network having changed since the module resolved its config. That same key is what the internal resolver's split-horizon view consumes. Adopts a running tunnel in place (existing key retained; `wg syncconf`, never `wg-quick down`) because that tunnel is the operator's recovery path. **Adoption is a one-time IMPORT and it ENDS.** The marker is `registered_peers` — celilo's own config key, separate from the operator's `peers` so a machine can never rewrite what an operator typed. While that key has never been written the tunnel is not yet celilo's; the deploy that writes it (even as `[]`) CLAIMS the tunnel, importing whatever `[Peer]` blocks are running, and from then on the render is closed-world (`peers` ∪ `registered_peers`) with a `[Peer]` on the box in neither reported as drift by `on_install` and by `health_check`'s `unknown_peers`. An ABSENT `peers` declaration and a declared-EMPTY one are deliberately different (no `default: []` on either variable): they used to be the same value, so the module read every empty list as "adopt what is running", the last peer could not be revoked, and a hand-added peer rode along on every deploy unreported (celilo#765). On a tunnel celilo has not yet claimed, a declared-empty `peers` is REFUSED rather than obeyed — celilo's own variable-default seeding wrote a real `peers = []` row for every install of the previous version that never set one, so on the installed base an empty list cannot be told from a stored default, and obeying it would `wg syncconf` the admin tunnel down to zero peers. **PROVIDES `control_plane_vpn`** so another module can enrol clients without an operator editing YAML: `registerClient` / `revokeClient` write to `registered_peers` — the same key the adoption claim uses — and `getEndpoint` reads the server's public key LIVE off the host rather than storing a copy that could be republished after the key changed. `client_pool` is the range a consumer may allocate from, a strict subset of the client subnet, and `validate_config` REFUSES any operator-declared peer inside it: the two allocators cannot see each other, so the range is divided rather than negotiated, and that check is the only place a bad division is caught. ⚠️ Granting this capability grants fleet-wide reach — the tunnel's client subnet is a registered trusted source, so every client enrolled through it reaches every managed zone. **requires:** `firewall` (and the provider must support trusted-source registration — `iptables` does; the ISP-router drivers `greenwave` and `axon` do not).
 
 ## Public edge (ingress / identity)
 

package/CELILO_SUBSYSTEMS.md

@@ -60,6 +60,8 @@ see `openspec/specs/`. Companion doc: [CELILO_CORE_MODULES.md](./CELILO_CORE_MOD
 | `registry_publish` | `packages/capabilities/src/registry-publish.ts` | celilo-registry |
 | `notification` | `packages/capabilities/src/notification.ts` (`send`, optional `receive`) | signal (planned) — transports are ordinary modules, both self-hosted and credential-only |
 | `cross_module_read` | `packages/capabilities/src/cross-module-read.ts` | framework (read other modules' capability data) |
+| `control_plane_vpn` | `packages/capabilities/src/control-plane-vpn.ts` (`registerClient`, `revokeClient`, `listClients`, `getEndpoint`). **Its state is NOT in a celilo table** — registrations live in the PROVIDER's own module config under `registered_peers`, kept separate from the operator's `peers` so a machine can never rewrite what an operator typed, and so `revokeClient` structurally cannot reach a declared peer. Do not go looking for a `vpn_clients` table; there isn't one and that is deliberate. Addresses are allocated by the CONSUMER from `client_pool` — celilo's IPAM deliberately does not cover VPN clients. ⚠️ Every client registered here reaches every managed zone: the tunnel's client subnet is a registered trusted source. | wireguard |
+| `private_web` | `packages/capabilities/src/private-web.ts` (`publishStaticSite`, `registerReverseProxy`, `unregisterRoutes`, `getCaCertificate`). **Fleet-only HTTP ingress** — internal DNS, an internally-issued certificate, and no public exposure. A SIBLING of `public_web` rather than a flag on it, because `public_web` treats an unreachable route as a deploy failure and publishes a public record to prevent one. Reuses `public_web`'s request types so a consumer can write `private_web ?? public_web` and call through the union without branching. | caddy-internal (planned) |
 
 ### In-fleet (`public_web`) vs off-fleet (`external_web`)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "0.25.1",
+  "version": "0.26.1",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {
@@ -58,7 +58,7 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1109.0",
     "@aws-sdk/lib-storage": "^3.1101.0",
-    "@celilo/capabilities": "^1.2.0",
+    "@celilo/capabilities": "^1.4.0",
     "@celilo/cli-display": "^0.2.0",
     "@celilo/core": "^0.8.0",
     "@celilo/event-bus": "^0.6.0",
@@ -75,10 +75,12 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
+    "@celilo/terraform-fake": "^0.3.0",
     "@types/bun": "^1.1.14",
     "@types/react": "^19.2.14",
     "drizzle-kit": "^0.30.0",
     "ink-testing-library": "^4.0.0",
+    "msw": "^2.15.0",
     "typescript": "^5.9.3",
     "zod-to-json-schema": "^3.25.2"
   }

package/src/api-clients/proxmox-over-http.test.ts

@@ -0,0 +1,328 @@
+/**
+ * The Proxmox client, exercised over a real socket — against the SAME handlers
+ * the e2e rig serves (D8).
+ *
+ * `proxmox.ts` hand-rolls `node:https` across 1,169 lines, and its existing
+ * 240-line test covers only the pure helpers: not one assertion reaches the
+ * wire. So the auth header, the `{data}` envelope, the 401 path and every
+ * non-2xx branch have gone unasserted — in the file that talks to the
+ * hypervisor.
+ *
+ * ## Why a real server rather than `setupServer`
+ *
+ * D8 proposed MSW's in-process `setupServer` for exactly this. **It does not
+ * work under Bun**, measured rather than assumed: `setupServer` intercepts
+ * global `fetch`, but a `node:https.request` goes straight past it and fails
+ * with `ECONNREFUSED` from Bun's own `node:_http_client`. `proxmox.ts` uses
+ * `node:https` directly, so the interceptor never sees it.
+ *
+ * `@celilo/terraform-fake` already exposes the same handlers as a real HTTPS
+ * server, so that is what these use. The D8 goal is met either way — ONE handler
+ * set behind both the client's unit tests and the rig's simulator, so the two
+ * cannot come to believe different things about what Proxmox returns — but it is
+ * met over a socket instead of an interceptor. The cost is a port and a
+ * self-signed certificate; the client already sets `rejectUnauthorized: false`,
+ * as every real consumer does.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import https from 'node:https';
+import type { AddressInfo } from 'node:net';
+import { type ProxmoxFake, createProxmoxFake } from '@celilo/terraform-fake';
+import {
+  ProxmoxClient,
+  type ProxmoxCredentials,
+  buildProxmoxApiUrl,
+  getNodeForVmid,
+  listNodeStorage,
+  testProxmoxConnection,
+} from './proxmox';
+
+let fake: ProxmoxFake;
+let credentials: ProxmoxCredentials;
+let tls: { key: string; cert: string };
+
+const TOKEN_ID = 'celilo@pve!e2e';
+const TOKEN_SECRET = '00000000-0000-0000-0000-000000000000';
+
+beforeAll(async () => {
+  tls = await generateSelfSigned();
+  fake = createProxmoxFake({
+    tls,
+    nodes: [{ name: 'pve1', cores: 8, memoryBytes: 16 * 1024 ** 3, diskBytes: 500 * 1024 ** 3 }],
+    storages: [{ name: 'local-lvm', content: 'images,rootdir' }],
+  });
+  const port = await fake.listen(0);
+  credentials = {
+    api_url: buildProxmoxApiUrl('127.0.0.1', port),
+    api_token_id: TOKEN_ID,
+    api_token_secret: TOKEN_SECRET,
+  };
+});
+
+afterAll(async () => {
+  await fake.close();
+});
+
+/**
+ * Run one request against a throwaway server that answers however the test
+ * needs, for the branches a well-behaved Proxmox never exercises.
+ */
+async function withStubServer<T>(
+  reply: (res: import('node:http').ServerResponse) => void,
+  run: (credentials: ProxmoxCredentials) => Promise<T>,
+): Promise<T> {
+  const server = https.createServer(tls, (_req, res) => reply(res));
+  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const { port } = server.address() as AddressInfo;
+  try {
+    return await run({
+      api_url: buildProxmoxApiUrl('127.0.0.1', port),
+      api_token_id: TOKEN_ID,
+      api_token_secret: TOKEN_SECRET,
+    });
+  } finally {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  }
+}
+
+describe('the request the client actually sends', () => {
+  test('carries the PVEAPIToken header Proxmox requires', async () => {
+    // Never asserted before. Proxmox rejects the session outright if this is
+    // malformed, and the client builds it by string concatenation.
+    let seen: string | undefined;
+    const server = https.createServer(tls, (req, res) => {
+      seen = req.headers.authorization;
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ data: [] }));
+    });
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const { port } = server.address() as AddressInfo;
+
+    await new ProxmoxClient({
+      ...credentials,
+      api_url: buildProxmoxApiUrl('127.0.0.1', port),
+    }).clusterResources();
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+
+    expect(seen).toBe(`PVEAPIToken=${TOKEN_ID}=${TOKEN_SECRET}`);
+  });
+
+  test('unwraps the `{data}` envelope rather than handing back the whole body', async () => {
+    const result = await listNodeStorage(credentials, 'pve1');
+
+    expect(result.success).toBe(true);
+    expect(Array.isArray(result.success && result.data)).toBe(true);
+  });
+
+  test('a query string is DROPPED — the constraint every caller works around', async () => {
+    // `makeProxmoxRequest` passes `url.pathname` and never `url.search`, so a
+    // filter silently does not arrive. `getNodeForVmid` documents this and
+    // fetches the whole inventory instead. Pinned here so that adding `?type=vm`
+    // somewhere and quietly getting unfiltered results is a test failure rather
+    // than a puzzling runtime one.
+    let seenUrl: string | undefined;
+    const server = https.createServer(tls, (req, res) => {
+      seenUrl = req.url;
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ data: [] }));
+    });
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const { port } = server.address() as AddressInfo;
+
+    await getNodeForVmid({ ...credentials, api_url: buildProxmoxApiUrl('127.0.0.1', port) }, 1);
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+
+    expect(seenUrl).toBe('/api2/json/cluster/resources');
+    expect(seenUrl).not.toContain('?');
+  });
+});
+
+describe('a POST — the other half of the wire contract', () => {
+  test('sends form-encoded parameters, not JSON', async () => {
+    // Proxmox only accepts `application/x-www-form-urlencoded`; sending JSON
+    // gets a 400 that names no field. Never asserted before.
+    //
+    // The stub answers BOTH paths, because `setGuestPower` first resolves the
+    // node via `/cluster/resources` and only then issues the POST.
+    let contentType: string | undefined;
+    let postedTo: string | undefined;
+    let body = '';
+    const server = https.createServer(tls, (req, res) => {
+      if (req.method === 'GET') {
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ data: [{ vmid: 403, node: 'pve1', type: 'lxc' }] }));
+        return;
+      }
+      contentType = req.headers['content-type'];
+      postedTo = req.url;
+      req.on('data', (c) => {
+        body += c;
+      });
+      req.on('end', () => {
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ data: 'UPID:pve1:00000001:0:66BF0000:vzshutdown:403:root@pam:' }));
+      });
+    });
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const { port } = server.address() as AddressInfo;
+
+    const result = await new ProxmoxClient({
+      ...credentials,
+      api_url: buildProxmoxApiUrl('127.0.0.1', port),
+    }).setGuestPower(403, 'lxc', 'shutdown');
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+
+    expect(result.success).toBe(true);
+    expect(contentType).toBe('application/x-www-form-urlencoded');
+    expect(body).not.toStartWith('{');
+    // `shutdown`, not `stop`: a pause is planned, so the guest is asked to go
+    // quietly rather than having its power pulled.
+    expect(postedTo).toBe('/api2/json/nodes/pve1/lxc/403/status/shutdown');
+  }, 30_000);
+});
+
+describe('what the client does with a response it did not want', () => {
+  test('401 says the credentials are wrong, not merely that something failed', async () => {
+    const result = await withStubServer(
+      (res) => {
+        res.writeHead(401);
+        res.end();
+      },
+      (creds) => new ProxmoxClient(creds).clusterResources(),
+    );
+
+    expect(result.success).toBe(false);
+    expect(result.success === false && result.message).toContain('Authentication failed');
+  });
+
+  test('a 500 reports the status, so a caller can tell it from a refusal', async () => {
+    const result = await withStubServer(
+      (res) => {
+        res.writeHead(500);
+        res.end('boom');
+      },
+      (creds) => new ProxmoxClient(creds).clusterResources(),
+    );
+
+    expect(result.success).toBe(false);
+    expect(result.success === false && result.message).toContain('500');
+  });
+
+  test('a non-JSON body is a parse failure, not a crash', async () => {
+    // Proxmox behind a misconfigured proxy answers HTML. The client must still
+    // return a result, because every caller branches on `.success`.
+    const result = await withStubServer(
+      (res) => {
+        res.writeHead(200, { 'content-type': 'text/html' });
+        res.end('<html>nope</html>');
+      },
+      (creds) => new ProxmoxClient(creds).clusterResources(),
+    );
+
+    expect(result.success).toBe(false);
+    expect(result.success === false && result.message).toContain('parse');
+  });
+
+  test('an unreachable host resolves to a failure instead of rejecting', async () => {
+    // The whole function is a `new Promise(resolve)` with no reject path, so a
+    // throw here would surface as an unhandled rejection inside a CLI command.
+    const result = await new ProxmoxClient({
+      ...credentials,
+      // Reserved for documentation (RFC 5737) and never routable.
+      api_url: buildProxmoxApiUrl('192.0.2.1', 9),
+    }).clusterResources();
+
+    expect(result.success).toBe(false);
+  }, 30_000);
+});
+
+describe('against the real handler set', () => {
+  test('listNodeStorage returns the storages the fake declares', async () => {
+    const result = await listNodeStorage(credentials, 'pve1');
+    const names = result.success
+      ? (result.data as Array<{ storage: string }>).map((s) => s.storage)
+      : [];
+
+    expect(names).toContain('local-lvm');
+  });
+
+  test('listClusterResources gets node rows AND guest rows from one unfiltered call', async () => {
+    // Why the fake returns both when no `?type=` is given, even though the
+    // Terraform provider needs the filtered form: this client cannot ask for a
+    // filter (see the dropped-query test) and needs both kinds at once.
+    fake.state.addGuest({
+      vmid: 401,
+      node: 'pve1',
+      kind: 'lxc',
+      hostname: 'client-test',
+      status: 'running',
+      config: { cores: '2', memory: '1024' },
+    });
+
+    const result = await new ProxmoxClient(credentials).clusterResources();
+    const kinds = new Set(result.success ? result.data.map((r) => r.type) : []);
+
+    expect(kinds.has('node')).toBe(true);
+    expect(kinds.has('lxc')).toBe(true);
+
+    fake.state.removeGuest(401);
+  });
+
+  test('getNodeForVmid finds the node a guest lives on', async () => {
+    fake.state.addGuest({
+      vmid: 402,
+      node: 'pve1',
+      kind: 'lxc',
+      hostname: 'placed',
+      status: 'running',
+      config: {},
+    });
+
+    const result = await getNodeForVmid(credentials, 402);
+
+    expect(result.success && result.data).toBe('pve1');
+
+    fake.state.removeGuest(402);
+  });
+
+  test('getNodeForVmid returns null for a vmid that does not exist yet', async () => {
+    // First deploy: the container has not been created. Distinct from an error,
+    // and the callers rely on the difference.
+    const result = await getNodeForVmid(credentials, 9999);
+
+    expect(result.success).toBe(true);
+    expect(result.success && result.data).toBeNull();
+  });
+});
+
+describe('testProxmoxConnection', () => {
+  test('succeeds against a token with full permissions', async () => {
+    const result = await testProxmoxConnection(credentials);
+
+    expect(result.success).toBe(true);
+  });
+
+  test('a 401 on the probe fails the connection test', async () => {
+    const result = await withStubServer(
+      (res) => {
+        res.writeHead(401);
+        res.end();
+      },
+      (creds) => testProxmoxConnection(creds),
+    );
+
+    expect(result.success).toBe(false);
+  });
+});
+
+/** A throwaway pair. Validity beyond "parses as a cert" is not the point. */
+async function generateSelfSigned(): Promise<{ key: string; cert: string }> {
+  const dir = `/tmp/proxmox-client-test-${process.pid}`;
+  await Bun.$`mkdir -p ${dir}`.quiet();
+  await Bun.$`openssl req -x509 -newkey rsa:2048 -keyout ${dir}/key.pem -out ${dir}/cert.pem -days 1 -nodes -subj /CN=proxmox.test`.quiet();
+  return {
+    key: await Bun.file(`${dir}/key.pem`).text(),
+    cert: await Bun.file(`${dir}/cert.pem`).text(),
+  };
+}

package/src/hooks/capability-loader.ts

@@ -109,6 +109,10 @@ export const CAPABILITY_MODULE_MAP: Record<string, { script: string; legacyFacto
       script: 'scripts/publish-functions.ts',
       legacyFactoryName: 'default',
     },
+    control_plane_vpn: {
+      script: 'scripts/control-plane-vpn-functions.ts',
+      legacyFactoryName: 'default',
+    },
   };
 
 /**

package/src/hooks/types.ts

@@ -121,7 +121,8 @@ export type HookName =
   | 'on_restore'
   | 'on_system_event'
   | 'refresh_registrations'
-  | 'reassert_dhcp_dns';
+  | 'reassert_dhcp_dns'
+  | 'reconcile_clients';
 
 /**
  * Hook manifest section - maps hook names to definitions

package/src/ipam/subnet-parser.ts

@@ -76,22 +76,19 @@ export function addCIDR(ip: string, maskBits: number): string {
 }
 
 /**
- * Check if an IP address belongs to a subnet
- * Example: isInSubnet("10.0.10.50/24", "10.0.10.0/24") → true
+ * Check if an IP address belongs to a subnet.
+ *
+ * Re-exported from `@celilo/capabilities` rather than implemented here, so the
+ * one answer serves both celilo and module scripts — which cannot import from
+ * the backend and would otherwise carry a second copy (celilo#809).
+ *
+ * The implementation that used to live here compared the first three octets and
+ * threw away the prefix it had parsed, so it was right for /24 and wrong in both
+ * directions for anything else. It also routed through `parseSubnet`, which
+ * REFUSES anything smaller than a /24 — an allocation rule that has no business
+ * constraining a containment question.
  */
-export function isInSubnet(ipWithMask: string, subnet: string): boolean {
-  const ip = stripCIDR(ipWithMask);
-  const subnetInfo = parseSubnet(subnet);
-
-  const ipOctets = ip.split('.').map((o) => Number.parseInt(o, 10));
-
-  // For /24 subnet, just check first 3 octets
-  return (
-    ipOctets[0] === subnetInfo.octets[0] &&
-    ipOctets[1] === subnetInfo.octets[1] &&
-    ipOctets[2] === subnetInfo.octets[2]
-  );
-}
+export { isInSubnet } from '@celilo/capabilities';
 
 /**
  * Generate all possible IPs in a subnet range

package/src/manifest/contracts/v1.ts

@@ -210,6 +210,25 @@ export const V1_HOOKS: ContractHooks = {
     inputs: {},
     outputs: {},
   },
+  /**
+   * Reconcile the clients a self-service app has enrolled against what the
+   * VPN provider actually carries (openspec/changes/wireguard-manager, D1).
+   *
+   * The hook, rather than a bus `handler` subscription, because it needs
+   * CAPABILITY INJECTION: it calls `control_plane_vpn.registerClient` and
+   * `revokeClient`, and a handler gets no capabilities. No framework inputs —
+   * it reads the app's address from its own `systems` and holds a token it
+   * minted for itself at install.
+   *
+   * Typically driven by a `timer.tick.*` subscription, and the tick interval IS
+   * the window in which a revoked device still has reach — which is why the
+   * design requires the UI to show the pending state rather than imply
+   * revocation is instant (D12).
+   */
+  reconcile_clients: {
+    inputs: {},
+    outputs: {},
+  },
   /**
    * Build-bus upstream publish hook. The executor passes the
    * PublishEvent fields as env vars (CELILO_EVENT_PAYLOAD,

package/src/manifest/schema.ts

@@ -674,6 +674,7 @@ export const ModuleManifestSchema = z
          * client can be handed the wrong resolver. See celilo#739.
          */
         reassert_dhcp_dns: LifecycleHookSchema.optional(),
+        reconcile_clients: LifecycleHookSchema.optional(),
         /**
          * Build-bus upstream publish hooks. Array (a module can react
          * to multiple upstream packages with different actions). See

package/src/services/alerting/inbound.test.ts

@@ -410,3 +410,69 @@ describe('reply verbs', () => {
     expect(parseInbound('K7QM2X akc')).toEqual({ kind: 'unrecognised' });
   });
 });
+
+/**
+ * celilo#500. The accepted grammar, in one table, because it was previously
+ * knowable only by reading the parser.
+ *
+ * The headline case is `reply K7QM2X`: every page ends with that literal line,
+ * and an operator who did exactly what it said was told `unrecognised` while
+ * the alert kept firing. Two consecutive real operator replies were lost this
+ * way. The instruction the system gives was the one input it refused.
+ *
+ * The trailing-period case is the same shape of unkindness. iOS inserts a full
+ * stop on a double space by default, and a one-word message is precisely where
+ * that fires.
+ *
+ * Being liberal here costs nothing: authentication is the token plus the sender
+ * check (see the header of inbound.ts), never punctuation strictness.
+ */
+describe('the grammar accepts what a phone actually sends (#500)', () => {
+  const ACKNOWLEDGES: Array<[string, string]> = [
+    ['K7QM2X', 'the bare token'],
+    ['k7qm2x', 'lower case'],
+    ['K7-QM2X', 'a separator the operator kept'],
+    ['K7QM2X ack', 'a trailing verb'],
+    ['ack K7QM2X', 'the natural spoken order'],
+    ['reply K7QM2X', 'WHAT THE PAGE ITSELF INSTRUCTS'],
+    ['K7QM2X.', 'iOS double-space autocorrect'],
+    ['Ack K7QM2X.', 'both at once, capitalised'],
+    ['reply k7-qm2x.', 'everything at once'],
+  ];
+
+  test.each(ACKNOWLEDGES)('%p acknowledges (%s)', (body) => {
+    expect(parseInbound(body)).toEqual({ kind: 'ack', token: 'K7QM2X' });
+  });
+
+  /**
+   * The guard that must survive. `<token> resolve` silently acknowledging an
+   * alert the operator meant to escalate is the worst outcome available here,
+   * so widening the grammar must not widen THIS.
+   */
+  const REFUSED: Array<[string, string]> = [
+    ['K7QM2X resolve', 'a verb celilo does not implement'],
+    ['K7QM2X silence 2h', 'a request with an argument'],
+    ['K7QM2X akc', 'a typo, not guessed at'],
+    ['reply K7QM2X resolve', 'the new verb does not smuggle a sentence through'],
+    ['what is going on', 'no token-shaped word anywhere'],
+    ['K7QM2XY', 'too long to be a token'],
+    ['reply', 'the verb alone names nothing'],
+  ];
+
+  test.each(REFUSED)('%p is refused (%s)', (body) => {
+    expect(parseInbound(body)).toEqual({ kind: 'unrecognised' });
+  });
+
+  /**
+   * The instruction and the parser are pinned to the same literal from both
+   * sides, so they cannot drift apart again. `composeBody` in
+   * `modules/signal/scripts/notification.ts` emits `\n\nreply <token>`, and
+   * `signal-rpc.test.ts:273` asserts that exact output. This asserts the parser
+   * accepts it. Change the wording and one of the two goes red.
+   */
+  test('the exact line composeBody emits is accepted', () => {
+    const asSent = 'caddy is down\n\nreply K7QM2X'.split('\n\n')[1];
+    expect(asSent).toBe('reply K7QM2X');
+    expect(parseInbound(asSent)).toEqual({ kind: 'ack', token: 'K7QM2X' });
+  });
+});

package/src/services/alerting/inbound.ts

@@ -65,6 +65,33 @@ export type InboundIntent =
   | { kind: 'unrecognised' };
 
 const ACK_VERB = /^(ack|ok|k|👍)$/iu;
+
+/**
+ * A verb that may only LEAD, and does not itself acknowledge.
+ *
+ * Every page ends with the literal line `reply <TOKEN>` (`composeBody` in
+ * modules/signal/scripts/notification.ts), and an operator who did exactly that
+ * was told `unrecognised` while the alert kept firing — the instruction the
+ * system gives was the one input it refused (#500). Two consecutive real
+ * operator replies were lost to it.
+ *
+ * Distinct from `ACK_VERB` on purpose: an ack synonym standing alone IS an
+ * acknowledgement (`bare_ack`), whereas `reply` alone is someone echoing the
+ * instruction without the token, which names nothing and stays unrecognised.
+ */
+const LEADING_VERB = /^reply$/i;
+
+/**
+ * Punctuation a phone added that the operator did not type.
+ *
+ * iOS turns a double space into a full stop by default, and a one-word reply is
+ * exactly where that fires. Stripping it costs nothing: authentication here is
+ * the token plus the sender check (see the header), never punctuation
+ * strictness.
+ */
+function stripTrailingPunctuation(word: string): string {
+  return word.replace(/[.,!?;:]+$/u, '');
+}
 /**
  * One to six characters of the token alphabet. Not anchored to the full
  * length: a prefix is legal input, and whether it identifies something is a
@@ -76,9 +103,15 @@ export function parseInbound(body: string): InboundIntent {
   const words = body.trim().split(/\s+/).filter(Boolean);
   if (words.length === 0) return { kind: 'unrecognised' };
 
+  // Drop a leading `reply` — instruction-echo, not content. Removed before
+  // anything else so the rest of the grammar is entirely unaffected by whether
+  // the operator included it.
+  if (LEADING_VERB.test(words[0])) words.shift();
+  if (words.length === 0) return { kind: 'unrecognised' };
+
   // Strip ack synonyms wherever they appear. What remains must be the token,
   // or nothing at all.
-  const remainder = words.filter((word) => !ACK_VERB.test(word));
+  const remainder = words.filter((word) => !ACK_VERB.test(stripTrailingPunctuation(word)));
   if (remainder.length === 0) return { kind: 'bare_ack' };
 
   // More than one non-verb word is not a token with politeness around it, it
@@ -89,7 +122,7 @@ export function parseInbound(body: string): InboundIntent {
   // so is strictly better than doing the wrong thing quietly.
   if (remainder.length > 1) return { kind: 'unrecognised' };
 
-  const token = normaliseToken(remainder[0]);
+  const token = normaliseToken(stripTrailingPunctuation(remainder[0]));
   if (!TOKEN_SHAPE.test(token)) return { kind: 'unrecognised' };
 
   return { kind: 'ack', token };