@celilo/e2e 0.12.0 → 0.13.1

package/README.md

@@ -20,7 +20,7 @@ The network consists of 7 Docker bridge networks simulating a realistic home lab
 | **dmz** | 10.226.10.0/24 | Public-facing services |
 | **app** | 10.226.20.0/24 | Internal applications |
 | **secure** | 10.226.30.0/24 | Sensitive services |
-| **isp-external** | 100.100.0.0/24 | ISP network (between home and internet) |
+| **isp-external** | 203.0.113.0/24 | ISP network (between home and internet) |
 | **internet-external** | 100.64.0.0/24 | Simulated internet (DNS, ACME, etc.) |
 | **real-internet** | 172.30.0.0/24 | Bridge to actual internet (for apt, pip, etc.) |
 
@@ -43,9 +43,9 @@ Don't hardcode an octet: use `zoneIp(zone, host)` / `ZONE_SUBNETS` / `ZONE_GATEW
 |---------|------|----------|-----|
 | **management** | Celilo CLI, Ansible, SSH | internal | 10.226.1.100 |
 | **fw-main** | iptables firewall (managed by Celilo) | internal, dmz, app, secure | 10.226.1.254, 10.226.10.1, 10.226.20.1, 10.226.30.1 |
-| **fw-isp** | Greenwave router simulator | internal, isp-external | 10.226.1.1, 100.100.0.100 |
-| **fw-ext** | Edge router + transparent HTTPS proxy (Squid) | isp-external, internet-external, real-internet | 100.100.0.101, 100.64.0.1, 172.30.0.5 |
-| **comcast-resolver** | Unbound recursive DNS resolver | isp-external, real-internet | 100.100.0.1, 172.30.0.4 |
+| **fw-isp** | Greenwave router simulator | internal, isp-external | 10.226.1.1, 203.0.113.100 |
+| **fw-ext** | Edge router + transparent HTTPS proxy (Squid) | isp-external, internet-external, real-internet | 203.0.113.101, 100.64.0.1, 172.30.0.5 |
+| **comcast-resolver** | Unbound recursive DNS resolver | isp-external, real-internet | 203.0.113.1, 172.30.0.4 |
 | **root-dns** | Knot authoritative DNS (root zone) | internet-external | 100.64.0.53 |
 | **tld-dns** | Knot authoritative DNS (.com, .org TLDs) | internet-external | 100.64.0.54 |
 | **namecheap-dns** | Knot DNS + DDNS API simulator | internet-external | 100.64.0.55 |
@@ -181,7 +181,7 @@ c system init --accept-defaults \
     network.internal.subnet=10.226.1.0/24 \
     primary_domain=iamtheinternet.org \
     admin.email=admin@iamtheinternet.org \
-    dns.primary=100.100.0.1 \
+    dns.primary=203.0.113.1 \
     dns.fallback=1.0.0.1,8.8.8.8
 
 # Import all modules

package/bin/e2e-status

@@ -22,7 +22,7 @@ docker compose -p "$PROJECT_NAME" exec -T comcast-resolver dig @127.0.0.1 www.ia
 
 echo ""
 echo "=== Connectivity (from management) ==="
-for target in "fw-main:10.226.1.254" "fw-isp:10.226.1.1" "comcast-resolver:100.100.0.1" "root-dns:100.64.0.53" "namecheap-dns:100.64.0.55"; do
+for target in "fw-main:10.226.1.254" "fw-isp:10.226.1.1" "comcast-resolver:203.0.113.1" "root-dns:100.64.0.53" "namecheap-dns:100.64.0.55"; do
   name="${target%%:*}"
   ip="${target##*:}"
   echo -n "  $name ($ip): "

package/bin/e2e-up

@@ -135,14 +135,14 @@ echo "  internal:          10.226.1.0/24"
 echo "  dmz:               10.226.10.0/24"
 echo "  app:               10.226.20.0/24"
 echo "  secure:            10.226.30.0/24"
-echo "  isp-external:      100.100.0.0/24"
+echo "  isp-external:      203.0.113.0/24"
 echo "  internet-external: 100.64.0.0/24"
 echo ""
 echo "Key machines:"
 echo "  management:        10.226.1.100  (conductor CLI)"
 echo "  fw-main:           10.226.1.254  (iptables firewall)"
 echo "  fw-isp:            10.226.1.1    (greenwave router sim)"
-echo "  comcast-resolver:  100.100.0.1        (DNS resolver)"
+echo "  comcast-resolver:  203.0.113.1        (DNS resolver)"
 echo "  namecheap-dns:     100.64.0.55       (DDNS simulator)"
 echo "  letsencrypt:       100.64.0.100      (Pebble ACME)"
 echo "  apt-cache:         100.64.0.2        (apt proxy → real internet)"

package/config/dns/tangohost.com.zone

@@ -7,7 +7,7 @@ $TTL 300
 
 ; The OFF-FLEET host's own public DNS — it owns this zone, celilo does not.
 ; Both names point at the host's own public address, NOT the customer
-; firewall (100.100.0.100): this host lives out on the simulated internet.
+; firewall (203.0.113.100): this host lives out on the simulated internet.
 @       IN NS   ns1.tangohost.com.
 ns1     IN A    100.64.0.55
 @       IN A    100.64.0.63

package/config/dns/templates/example.net.zone

@@ -8,9 +8,9 @@ $TTL 300
 ; Public DNS — RFC 1918 addresses NEVER appear here. The whole point of
 ; the e2e simulation is to model real internet connectivity, where
 ; private IPs are unreachable from outside. All public-facing names
-; resolve to the firewall's external IP (100.100.0.100), which DNATs
+; resolve to the firewall's external IP (203.0.113.100), which DNATs
 ; inbound to the right internal host.
 @       IN NS   ns1.example.net.
 ns1     IN A    100.64.0.55
-@       IN A    100.100.0.100
-www     IN A    100.100.0.100
+@       IN A    203.0.113.100
+www     IN A    203.0.113.100

package/config/dns/templates/iamtheinternet.org.zone

@@ -8,9 +8,9 @@ $TTL 300
 ; Public DNS — RFC 1918 addresses NEVER appear here. The whole point of
 ; the e2e simulation is to model real internet connectivity, where
 ; private IPs are unreachable from outside. All public-facing names
-; resolve to the firewall's external IP (100.100.0.100), which DNATs
+; resolve to the firewall's external IP (203.0.113.100), which DNATs
 ; inbound to the right internal host.
 @       IN NS   ns1.iamtheinternet.org.
 ns1     IN A    100.64.0.55
 @       IN A    0.0.0.0
-www     IN A    100.100.0.100
+www     IN A    203.0.113.100

package/config/routing/fw-ext-routes.sh

@@ -6,10 +6,10 @@ ip route del default 2>/dev/null || true
 # Default route via real-internet bridge (for Squid outbound to real internet)
 ip route add default via 172.30.0.1
 # Internal subnets via fw-isp
-ip route add 10.226.1.0/24 via 100.100.0.100     # Internal via fw-isp
-ip route add 10.226.10.0/24 via 100.100.0.100       # dmz via fw-isp
-ip route add 10.226.20.0/24 via 100.100.0.100       # app via fw-isp
-ip route add 10.226.30.0/24 via 100.100.0.100       # secure via fw-isp
+ip route add 10.226.1.0/24 via 203.0.113.100     # Internal via fw-isp
+ip route add 10.226.10.0/24 via 203.0.113.100       # dmz via fw-isp
+ip route add 10.226.20.0/24 via 203.0.113.100       # app via fw-isp
+ip route add 10.226.30.0/24 via 203.0.113.100       # secure via fw-isp
 
 # IP forwarding is set via sysctls in docker-compose
 
@@ -17,7 +17,7 @@ ip route add 10.226.30.0/24 via 100.100.0.100       # secure via fw-isp
 #
 # The customer's public /24 is ROUTED, never re-NAT'd. An ISP does not NAT a
 # subscriber that already holds a public address — the whole point of
-# 100.100.0.100 is that it IS the customer's address on the internet. fw-ext
+# 203.0.113.100 is that it IS the customer's address on the internet. fw-ext
 # used to MASQUERADE it anyway, so every packet leaving the fleet reached the
 # public simulators bearing fw-ext's own 100.64.0.1.
 #
@@ -28,7 +28,7 @@ ip route add 10.226.30.0/24 via 100.100.0.100       # secure via fw-isp
 # and any inbound reach. It also silently clobbered seeded apex records.
 # Anything that reasons about "the address the internet sees us as" was
 # measuring the simulator's own artefact.
-iptables -t nat -A POSTROUTING -s 100.100.0.0/24 -j RETURN
+iptables -t nat -A POSTROUTING -s 203.0.113.0/24 -j RETURN
 iptables -t nat -A POSTROUTING -j MASQUERADE
 iptables -P FORWARD ACCEPT
 
@@ -66,12 +66,12 @@ done
 
 # Transparent proxy: REDIRECT HTTP/HTTPS from isp-external to local Squid
 # Exception: traffic to simulated services (100.64.0.0/24) passes through directly
-ISP_IFACE=$(ip -o addr show | grep '100.100.0.101' | awk '{print $2}')
+ISP_IFACE=$(ip -o addr show | grep '203.0.113.101' | awk '{print $2}')
 iptables -t nat -A PREROUTING -i "$ISP_IFACE" -p tcp --dport 80 ! -d 100.64.0.0/24 -j REDIRECT --to-port 3128
 iptables -t nat -A PREROUTING -i "$ISP_IFACE" -p tcp --dport 443 ! -d 100.64.0.0/24 -j REDIRECT --to-port 3129
 
 # DNS
-echo "nameserver 100.100.0.1" > /etc/resolv.conf
+echo "nameserver 203.0.113.1" > /etc/resolv.conf
 
 # Fetch Pebble's runtime ACME root CA (Pebble generates a fresh root at each startup)
 # Retry until Pebble is up and responding

package/config/routing/fw-isp-routes.sh

@@ -10,7 +10,7 @@ chmod 600 /root/.ssh/authorized_keys
 
 # Routing
 ip route del default 2>/dev/null || true
-ip route add default via 100.100.0.101            # Internet via fw-ext
+ip route add default via 203.0.113.101            # Internet via fw-ext
 ip route add 10.226.10.0/24 via 10.226.1.254       # dmz via fw-main
 ip route add 10.226.20.0/24 via 10.226.1.254       # app via fw-main
 ip route add 10.226.30.0/24 via 10.226.1.254       # secure via fw-main
@@ -22,7 +22,7 @@ iptables -t nat -A POSTROUTING -j MASQUERADE
 iptables -P FORWARD ACCEPT
 
 # DNS
-echo "nameserver 100.100.0.1" > /etc/resolv.conf
+echo "nameserver 203.0.113.1" > /etc/resolv.conf
 
 # Start dnsmasq DHCP server on internal network
 dnsmasq --conf-dir=/etc/dnsmasq.d --keep-in-foreground --log-facility=- &

package/config/routing/fw-main-routes.sh

@@ -14,17 +14,17 @@ iptables -P FORWARD ACCEPT
 # Routing + egress NAT — depends on topology (detected by the presence of an
 # isp-external interface).
 ip route del default 2>/dev/null || true
-if ip -o addr show | grep -q '100.100.0'; then
+if ip -o addr show | grep -q '203.0.113'; then
   # Direct-internet: fw-main has its own external (WAN) interface.
-  ip route add default via 100.100.0.101
+  ip route add default via 203.0.113.101
   # Egress NAT SCOPED to the external/WAN interface (the one with the public
-  # 100.100.0.x address) — NOT a blanket MASQUERADE (ISS-0156). Scoping to the WAN
+  # 203.0.113.x address) — NOT a blanket MASQUERADE (ISS-0156). Scoping to the WAN
   # means inter-zone traffic (protected↔protected, protected↔internal) keeps its
   # source, so the dmz-resident resolver sees each client's real zone for
   # source-based DNS views. This boot-time rule is what target machines need for
   # egress/DNS BEFORE any module deploys; celilo's iptables module applies the
   # same WAN-scoped MASQUERADE on deploy (idempotent — the production code path).
-  EXT_IFACE=$(ip -o addr show | awk '/100\.100\.0\./{print $2; exit}')
+  EXT_IFACE=$(ip -o addr show | awk '/203\.0\.113\./{print $2; exit}')
   iptables -t nat -A POSTROUTING -o "$EXT_IFACE" -j MASQUERADE
 else
   # Two-layer: no external interface on fw-main; it routes outbound to the
@@ -53,7 +53,7 @@ else
 fi
 
 # DNS
-echo "nameserver 100.100.0.1" > /etc/resolv.conf
+echo "nameserver 203.0.113.1" > /etc/resolv.conf
 
 echo "fw-main ready"
 sleep infinity

package/config/routing/management-routes.sh

@@ -42,7 +42,7 @@ ip route add 10.226.120.0/24 via "$FW_MAIN" 2>/dev/null || true
 # Technitium at 10.226.1.10 is authoritative for iamtheinternet.org internally,
 # resolving www/auth to Caddy's DMZ IP (10.226.10.10) rather than the public WAN IP.
 # Fall back to the simulated public resolver if Technitium is not yet up.
-printf 'nameserver %s\nnameserver 100.100.0.1\n' "${INTERNAL_RESOLVER:-10.226.1.10}" > /etc/resolv.conf
+printf 'nameserver %s\nnameserver 203.0.113.1\n' "${INTERNAL_RESOLVER:-10.226.1.10}" > /etc/resolv.conf
 
 # Fetch Pebble's runtime ACME root CA (Pebble generates a fresh root at each
 # startup, unlike the static /config/pebble/pebble-ca.crt baked in at build

package/config/routing/observer-setup.sh

@@ -14,7 +14,7 @@ set -u
 
 GATEWAY="${OBSERVER_GATEWAY:?OBSERVER_GATEWAY is required}"
 INTERZONE="${OBSERVER_INTERZONE:-0}"
-RESOLVERS="${OBSERVER_RESOLVERS:-100.100.0.1}"
+RESOLVERS="${OBSERVER_RESOLVERS:-203.0.113.1}"
 
 echo "Observer starting: gateway=${GATEWAY} interzone=${INTERZONE} resolvers='${RESOLVERS}'"
 

package/config/routing/public-sim-entrypoint.sh

@@ -2,7 +2,7 @@
 # Entrypoint wrapper for a simulator on `internet-external` — a host out on
 # the simulated public internet.
 #
-# Such a host must reach the customer's public prefix (100.100.0.0/24) through
+# Such a host must reach the customer's public prefix (203.0.113.0/24) through
 # the ISP edge, fw-ext. Docker's default bridge gateway has no path across
 # networks, so without this route a reply to the customer's WAN address is
 # simply dropped and the connection hangs.

package/config/routing/resolver-internal-routes.sh

@@ -13,7 +13,7 @@ CADDY_IP="${CADDY_IP:-10.226.10.10}"
 # vars in docker-compose.
 DOMAINS="${DOMAINS:-iamtheinternet.org,example.net}"
 
-# Routing — reach comcast-resolver (100.100.0.1) via fw-main or fw-isp.
+# Routing — reach comcast-resolver (203.0.113.1) via fw-main or fw-isp.
 # DEFAULT_GATEWAY is set by docker-compose from the topology config.
 GATEWAY="${DEFAULT_GATEWAY:-10.226.1.254}"
 ip route del default 2>/dev/null || true
@@ -75,7 +75,7 @@ $(printf "${SPLIT_HORIZON_BLOCK}")
 
 forward-zone:
     name: "."
-    forward-addr: 100.100.0.1
+    forward-addr: 203.0.113.1
 EOF
 
 /usr/sbin/unbound -d &

package/config/routing/resolver-routes.sh

@@ -6,7 +6,7 @@ ip route del default 2>/dev/null || true
 ip route add default via 172.30.0.1
 
 # Keep route to simulated internet services via fw-ext
-ip route add 100.64.0.0/24 via 100.100.0.101
+ip route add 100.64.0.0/24 via 203.0.113.101
 
 # Start unbound
 /usr/sbin/unbound -d &

package/config/routing/target-routes.sh

@@ -17,7 +17,7 @@ ip route del default 2>/dev/null || true
 ip route add default via "$GATEWAY"
 
 # DNS
-echo "nameserver 100.100.0.1" > /etc/resolv.conf
+echo "nameserver 203.0.113.1" > /etc/resolv.conf
 
 echo "Target machine ready: $(hostname)"
 sleep infinity

package/config/routing/target-setup.sh

@@ -31,7 +31,7 @@ ip route del default 2>/dev/null || true
 ip route add default via "$GATEWAY"
 
 # DNS
-echo "nameserver 100.100.0.1" > /etc/resolv.conf
+echo "nameserver 203.0.113.1" > /etc/resolv.conf
 
 # Fetch Pebble's runtime ACME root CA (Pebble generates a fresh root
 # at each startup; the static pebble-ca.crt baked into the image only

package/config/socks/startup.sh

@@ -12,8 +12,8 @@ case "$VANTAGE" in
     # Residential-user view. Default route via fw-ext (.101) which DNATs
     # public-internet traffic into the dmz (caddy at 10.226.10.10). DNS via
     # comcast-resolver (.1) which walks the root → TLD → namecheap chain.
-    GATEWAY="100.100.0.101"
-    NAMESERVER="100.100.0.1"
+    GATEWAY="203.0.113.101"
+    NAMESERVER="203.0.113.1"
     ;;
   internal)
     # Operator-on-LAN view. Default route via fw-isp (.1); split-horizon

package/docker/Dockerfile.firewall

@@ -12,10 +12,21 @@ RUN apt-get update && apt-get install -y \
     dnsutils \
     procps \
     python3 \
-    wireguard-tools \
     wireguard-go \
     && rm -rf /var/lib/apt/lists/*
 
+# `wireguard-tools` is DELIBERATELY not installed here. The wireguard module's
+# job includes putting it on the host, and baking it in meant the rig proved the
+# tunnel worked on the one kind of host that could never exercise that: the
+# module only ever ran `wg --version`, found it, and moved on. On a real firewall
+# the deploy failed and told the operator to install wireguard by hand — over the
+# access the VPN was being deployed to provide.
+#
+# `wireguard-go` stays, and is a different kind of thing. A container cannot load
+# a kernel module, so wg-quick needs a userspace implementation to fall back to;
+# that is the simulator standing in for hardware it does not have, not a step
+# celilo is supposed to perform.
+
 # Containers have no wireguard kernel module to load, and a test must not depend
 # on whether the Docker host happens to have one. wg-quick falls back to this
 # userspace implementation when `ip link add type wireguard` fails, so the tunnel

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/e2e",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "description": "E2E test infrastructure for Celilo-deployed applications. Provides a simulated internet with DNS hierarchy, ACME server, firewalls, and target machines in Docker.",
   "type": "module",
   "main": "./src/index.ts",
@@ -18,7 +18,7 @@
     "celilo-e2e-infra": "./bin/e2e-infra"
   },
   "scripts": {
-    "test": "bun test tests/",
+    "test": "bun test --timeout 30000 tests/",
     "test:completion": "bun test tests/completion",
     "test:integration": "bun test tests-integration/"
   },
@@ -37,8 +37,9 @@
     "README.md"
   ],
   "dependencies": {
-    "@celilo/cli-display": "^0.1.10",
-    "@celilo/event-bus": "^0.4.0",
+    "@celilo/capabilities": "^1.2.0",
+    "@celilo/cli-display": "^0.2.0",
+    "@celilo/event-bus": "^0.5.0",
     "yaml": "^2.8.0",
     "zod": "^3.24.1"
   },

package/simulators/greenwave/server.ts

@@ -12,6 +12,7 @@
 
 import {
   addPortMapping,
+  currentDevice,
   getDhcpPool,
   getPublicIp,
   isAuthenticated,
@@ -19,6 +20,7 @@ import {
   login,
   logout,
   setDhcpPool,
+  swapDevice,
 } from './state';
 import type { CgiResponse } from './types';
 
@@ -78,6 +80,39 @@ const server = Bun.serve({
   async fetch(req) {
     const url = new URL(req.url);
 
+    // --- POST /sim/swap-device — HARNESS CONTROL, not part of the CGI API ---
+    //
+    // Replaces the physical device this container impersonates, on a RUNNING
+    // network, modelling an ISP swapping the box on the wall. Namespaced under
+    // /sim/ and deliberately unauthenticated: it is not reachable from any
+    // module (nothing in modules/ knows this path exists) and the whole
+    // container is a simulator. Real firmware has no such endpoint, which is
+    // exactly why it cannot live under /cgi/.
+    if (url.pathname === '/sim/swap-device' && req.method === 'POST') {
+      const body = await req.text();
+      const params = parseUrlEncoded(body);
+      if (!params.vendorPrefix) {
+        return new Response('vendorPrefix is required', { status: 400 });
+      }
+      const result = swapDevice({
+        vendorPrefix: params.vendorPrefix,
+        username: params.username,
+        password: params.password,
+      });
+      return new Response(JSON.stringify({ ...result, device: currentDevice() }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+
+    // --- GET /sim/device — what is currently being impersonated ---
+    if (url.pathname === '/sim/device' && req.method === 'GET') {
+      return new Response(JSON.stringify(currentDevice()), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+
     // --- POST /cgi/cgi_action (login/logout) ---
     if (url.pathname === '/cgi/cgi_action' && req.method === 'POST') {
       const body = await req.text();

package/simulators/greenwave/state.ts

@@ -2,9 +2,9 @@ import { execSync } from 'node:child_process';
 import { writeFileSync } from 'node:fs';
 import type { CgiObject, CgiParam, PortMapping, Session } from './types';
 
-const VALID_USERNAME = process.env.ROUTER_USERNAME || 'admin';
-const VALID_PASSWORD = process.env.ROUTER_PASSWORD || 'admin';
-const PUBLIC_IP = process.env.ROUTER_PUBLIC_IP || '100.100.0.100';
+let validUsername = process.env.ROUTER_USERNAME || 'admin';
+let validPassword = process.env.ROUTER_PASSWORD || 'admin';
+const PUBLIC_IP = process.env.ROUTER_PUBLIC_IP || '203.0.113.100';
 
 // The network interface facing the ISP (isp-external network)
 const EXTERNAL_INTERFACE = process.env.EXTERNAL_INTERFACE || 'eth1';
@@ -18,15 +18,68 @@ const EXTERNAL_INTERFACE = process.env.EXTERNAL_INTERFACE || 'eth1';
  * folds both into `X_AXON_`. Defaults to the GreenWave spelling so the existing
  * greenwave suite is byte-for-byte unaffected.
  */
-const VENDOR_PREFIX = process.env.ROUTER_VENDOR_PREFIX || 'X_GWS_';
-const PARAM_VIA = `${VENDOR_PREFIX}Via`;
+let vendorPrefix = process.env.ROUTER_VENDOR_PREFIX || 'X_GWS_';
 
 /**
  * The C4000XG named the interface selector after the chipset vendor rather than
  * the device vendor, so it does NOT follow the prefix. Axon firmware does.
  */
-const PARAM_INTERFACE =
-  VENDOR_PREFIX === 'X_GWS_' ? 'X_LANTIQ_COM_INTERFACE' : `${VENDOR_PREFIX}INTERFACE`;
+function paramVia(): string {
+  return `${vendorPrefix}Via`;
+}
+
+function paramInterface(): string {
+  return vendorPrefix === 'X_GWS_' ? 'X_LANTIQ_COM_INTERFACE' : `${vendorPrefix}INTERFACE`;
+}
+
+/**
+ * Replace the physical device this container is impersonating, WITHOUT
+ * restarting it — the way an ISP swaps the box on the wall while the line, the
+ * public IP and everything downstream stay put.
+ *
+ * `ROUTER_VENDOR_PREFIX` alone cannot model this: it is baked into the compose
+ * file at network-build time and read once at module load, so a mid-run swap
+ * was not expressible and the migration this whole change exists for could not
+ * be tested end to end.
+ *
+ * Three things change together, because all three are true of a real swap and
+ * each one matters to what is under test:
+ *
+ *  1. The vendor prefix, so a module written for the old device now speaks the
+ *     wrong TR-181 spelling.
+ *  2. The CREDENTIALS. This is why the fleet wedges in practice rather than
+ *     merely misbehaving: the old module cannot even authenticate, so it can
+ *     neither drive the new box nor tear its own state down.
+ *  3. Every port forward is GONE. A new device arrives empty. This is the
+ *     assertion that gives the migration test its teeth — the forwards must be
+ *     recreated by unpausing the consumers that own them, and a simulator that
+ *     kept its old table would let a completely broken unpause pass.
+ */
+export function swapDevice(options: {
+  vendorPrefix: string;
+  username?: string;
+  password?: string;
+}): { forwardsDiscarded: number } {
+  const forwardsDiscarded = portMappings.length;
+
+  vendorPrefix = options.vendorPrefix;
+  if (options.username !== undefined) validUsername = options.username;
+  if (options.password !== undefined) validPassword = options.password;
+
+  portMappings.length = 0;
+  nextIndex = 1;
+  // Sessions are per-device: a cookie minted by the old box is meaningless to
+  // the new one, so anything still holding one gets a 401 rather than silently
+  // continuing to work.
+  sessions.clear();
+
+  return { forwardsDiscarded };
+}
+
+/** What the simulator is currently impersonating — for assertions and debugging. */
+export function currentDevice(): { vendorPrefix: string; username: string } {
+  return { vendorPrefix, username: validUsername };
+}
 
 const sessions = new Map<string, Session>();
 const portMappings: PortMapping[] = [];
@@ -47,7 +100,7 @@ const dhcpPool: Record<string, string> = {
 };
 
 export function login(username: string, password: string): string | null {
-  if (username !== VALID_USERNAME || password !== VALID_PASSWORD) {
+  if (username !== validUsername || password !== validPassword) {
     return null;
   }
   const sessionId = `sim-${Date.now()}-${Math.random().toString(36).slice(2)}`;
@@ -91,7 +144,7 @@ export function addPortMapping(params: Record<string, string>): CgiObject[] {
     enable: params.Enable || '1',
     description: params.Description || '',
     protocol: params.Protocol || 'TCP',
-    via: params[PARAM_VIA] || 'UI',
+    via: params[paramVia()] || 'UI',
     remoteHost: params.RemoteHost || '',
   };
 
@@ -219,9 +272,9 @@ function mappingToParams(pm: PortMapping): CgiParam[] {
     { ParamName: 'Enable', ParamValue: pm.enable },
     { ParamName: 'Description', ParamValue: pm.description },
     { ParamName: 'Protocol', ParamValue: pm.protocol },
-    { ParamName: PARAM_VIA, ParamValue: pm.via },
+    { ParamName: paramVia(), ParamValue: pm.via },
     { ParamName: 'RemoteHost', ParamValue: pm.remoteHost },
-    { ParamName: PARAM_INTERFACE, ParamValue: 'wan' },
+    { ParamName: paramInterface(), ParamValue: 'wan' },
     { ParamName: 'AllInterfaces', ParamValue: '0' },
   ];
 }

package/simulators/ip-echo/server.ts

@@ -38,7 +38,7 @@ const PORT = Number(process.env.ECHO_PORT) || 80;
 
 /**
  * Strip the IPv6-mapped-IPv4 prefix Bun returns for IPv4 connections over a
- * dual-stack socket (`::ffff:100.100.0.100` → `100.100.0.100`). Same fix as
+ * dual-stack socket (`::ffff:203.0.113.100` → `203.0.113.100`). Same fix as
  * the namecheap-ddns simulator: the mapped form is not a valid A-record value,
  * and here it would simply never compare equal to what DNS serves.
  */

package/src/address-plan.test.ts

@@ -17,8 +17,8 @@
 
 import { describe, expect, test } from 'bun:test';
 import { execSync } from 'node:child_process';
+import { subnetContains } from '@celilo/capabilities';
 import { SIM_PRIVATE_SUPERNET, ZONE_GATEWAYS, ZONE_SUBNETS, type Zone } from './types';
-import { inCidr } from './zone-classifier';
 
 const REPO_ROOT = execSync('git rev-parse --show-toplevel', {
   cwd: import.meta.dir,
@@ -73,9 +73,9 @@ describe('simulated address plan (#539)', () => {
   test('every zone lives inside the sim supernet', () => {
     for (const zone of Object.keys(ZONE_SUBNETS) as Zone[]) {
       const base = ZONE_SUBNETS[zone].split('/')[0];
-      expect(inCidr(base, SIM_PRIVATE_SUPERNET)).toBe(true);
-      expect(inCidr(ZONE_GATEWAYS[zone], SIM_PRIVATE_SUPERNET)).toBe(true);
-      expect(inCidr(ZONE_GATEWAYS[zone], ZONE_SUBNETS[zone])).toBe(true);
+      expect(subnetContains(SIM_PRIVATE_SUPERNET, base)).toBe(true);
+      expect(subnetContains(SIM_PRIVATE_SUPERNET, ZONE_GATEWAYS[zone])).toBe(true);
+      expect(subnetContains(ZONE_SUBNETS[zone], ZONE_GATEWAYS[zone])).toBe(true);
     }
   });
 

package/src/cli/build.ts

@@ -24,8 +24,16 @@ import { basename, join, resolve } from 'node:path';
 import { gunzipSync } from 'node:zlib';
 import { stageAptRepo } from '../../scripts/stage-apt-repo';
 import { stageLibsignal } from '../../scripts/stage-libsignal';
+import { explainBuildFailure } from '../doctor';
 import { ensureRegistryServerBundle } from '../registry-bundle';
 
+/**
+ * Ceiling on a single `docker build`. The slowest image here is a few minutes
+ * cold; 15 leaves generous headroom while bounding a wedged build, which
+ * otherwise hangs the whole invocation with no signal at all.
+ */
+const PER_IMAGE_BUILD_TIMEOUT_MS = 15 * 60_000;
+
 /**
  * Walk up from pkgDir to find the celilo monorepo root.
  *
@@ -533,12 +541,34 @@ function buildDockerImages(pkgDir: string): void {
     const result = spawnSync('docker', ['build', '-t', tag, '-f', join(dockerDir, file), context], {
       cwd: pkgDir,
       stdio: 'pipe',
+      timeout: PER_IMAGE_BUILD_TIMEOUT_MS,
     });
     const elapsed = Math.round((Date.now() - start) / 1000);
 
+    // A wedged `docker build` used to hang here forever: spawnSync blocks the
+    // event loop, so even the run-lock heartbeat stops — the holder looks alive
+    // (its PID is) while beating nothing, and the only way anyone noticed was
+    // comparing beatAt to wall-clock by hand. Twice in one evening, ~20 and ~32
+    // minutes. A bounded wait turns that into an immediate, nameable failure.
+    if (result.error && (result.error as NodeJS.ErrnoException).code === 'ETIMEDOUT') {
+      console.log(`${red}✗ TIMED OUT${reset}  ${dim}${elapsed}s${reset}`);
+      console.error(
+        `\n${red}Building ${name} exceeded ${Math.round(PER_IMAGE_BUILD_TIMEOUT_MS / 60_000)} minutes and was killed.${reset}`,
+      );
+      console.error(
+        `${dim}Docker itself is usually still responsive. Reproduce it alone with:${reset}`,
+      );
+      console.error(`${dim}  docker build -f docker/${file} -t ${tag} .${reset}`);
+      console.error(
+        `${dim}If that succeeds, the stall was transient — re-run \`cele2e build-infra\`.${reset}\n`,
+      );
+      process.exit(1);
+    }
+
     if (result.status !== 0) {
       console.log(`${red}✗${reset}  ${dim}${elapsed}s${reset}`);
       console.error(result.stderr?.toString());
+      console.error(explainBuildFailure(result.stderr?.toString() ?? ''));
       process.exit(1);
     }
 

package/src/cli/command-registry.ts

@@ -99,6 +99,22 @@ export const COMMANDS: CommandDef[] = [
     description: 'Show run-lock holder + network status (exit 3 if busy)',
     flags: [{ name: '--json', description: 'Emit a machine-readable lock snapshot for polling' }],
   },
+  {
+    name: 'doctor',
+    description:
+      "Check everything a run needs (baked images, base images, lock, disk) — run's implicit preflight",
+    flags: [{ name: '--json', description: 'Emit the full report as JSON' }],
+  },
+  {
+    name: 'last',
+    description: "Show the most recent run's results dir and counts",
+    flags: [
+      {
+        name: '--json',
+        description: 'Emit {runId, resultsDir, total, passed, failed} for scripting',
+      },
+    ],
+  },
   {
     name: 'release',
     description: 'Free a run-lock left by --keep/up (does not tear down)',
@@ -141,4 +157,7 @@ export const RUN_FLAGS = [
 
 export const DOWN_FLAGS = ['--keep', '--all'];
 
+/** Read-only reporters whose only flag is `--json`. */
+export const JSON_FLAG_COMMANDS = ['status', 'doctor', 'last'];
+
 export const BUILD_INFRA_FLAGS = ['--save', '--skip-modules', '--published'];