@celilo/e2e 0.11.3 → 0.13.0

package/src/doctor.ts

@@ -0,0 +1,421 @@
+/**
+ * cele2e doctor — "is my environment sane?" as one mechanical answer.
+ *
+ * Every check here exists because its absence was diagnosed as a product bug
+ * first. They share a shape: the mistake is silent, and the failure surfaces
+ * later and somewhere unrelated. A missing bake shows up as an SSH error
+ * against a firewall IP; a pruned base image shows up as a TLS handshake
+ * timeout 16 images into a build. Each one is cheap to detect BEFORE a run
+ * starts, so `run` calls this as its implicit preflight and refuses rather
+ * than starting something that cannot succeed.
+ *
+ * Docker access is behind DoctorProbe (Rule 2.3) so every check is unit-
+ * testable with the condition deliberately broken — which is the point: a gate
+ * nobody has seen fail is not a gate (Rule 7.6).
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  type LockHolder,
+  type LockStatus,
+  formatAge,
+  heartbeatAgeMs,
+  isSameSession,
+  isSuspect,
+  lockStatus,
+} from './run-lock';
+
+/**
+ * Images the per-test compose references by `image:` alone — it has no `build:`
+ * for them, so docker CANNOT produce them on demand. `cele2e build-infra` bakes
+ * both (install.sh, then `docker commit`). Missing → the run is doomed.
+ */
+export const BAKED_MANAGEMENT_IMAGES = [
+  'celilo-e2e/management:latest',
+  'celilo-e2e/management:vanilla',
+] as const;
+
+/**
+ * The bake commits a container that was started with `sleep infinity`, so it
+ * must override Cmd back to the management image's real entrypoint. When that
+ * override is lost the container comes up without ever running /startup.sh, the
+ * ssh-keys volume is never populated, and every machine the test adds fails
+ * with "Cannot connect to root@<ip> with provided SSH key" — an error that
+ * reads as a network or firewall bug and is neither (ce-um6).
+ */
+export const EXPECTED_MANAGEMENT_CMD = '/startup.sh';
+
+/** Warn above this much reclaimable image space — the pressure that makes people prune. */
+const RECLAIMABLE_WARN_BYTES = 20 * 1024 ** 3;
+
+export type CheckStatus = 'ok' | 'warn' | 'fail';
+
+export interface DoctorCheck {
+  /** Stable machine-readable id, e.g. 'management-image'. */
+  name: string;
+  status: CheckStatus;
+  /** What was actually found. */
+  detail: string;
+  /** The exact command that fixes it. Present whenever status is not 'ok'. */
+  remedy?: string;
+}
+
+export interface DoctorReport {
+  checks: DoctorCheck[];
+  /** True when no check failed. Warnings do not block a run. */
+  ok: boolean;
+}
+
+/** Every Docker fact doctor needs, injectable so the checks are testable. */
+export interface DoctorProbe {
+  /** Is this image present in the local store? An untagged ref means `:latest`. */
+  imageExists(ref: string): boolean;
+  /** The image's configured Cmd, or null when the image is absent. */
+  imageCmd(ref: string): string[] | null;
+  /** Names of leftover `celilo-e2e-*` containers. */
+  staleContainers(): string[];
+  /** Bytes docker reports as reclaimable image space. */
+  reclaimableImageBytes(): number;
+}
+
+// ─── Dockerfile parsing ──────────────────────────────────────────────
+
+/**
+ * External base images a Dockerfile pulls from, ignoring references to its own
+ * earlier build stages (`FROM x AS fetch` … `COPY --from=fetch`). Pure so the
+ * multi-stage and `--platform=` forms both stay covered by a unit test.
+ */
+export function parseBaseImages(dockerfile: string): string[] {
+  const stages = new Set<string>();
+  const bases: string[] = [];
+  for (const raw of dockerfile.split('\n')) {
+    const line = raw.trim();
+    const match = line.match(/^FROM\s+(.*)$/i);
+    if (!match) continue;
+    const tokens = match[1].split(/\s+/).filter((t) => !t.startsWith('--'));
+    const ref = tokens[0];
+    if (!ref) continue;
+    const asIdx = tokens.findIndex((t) => t.toLowerCase() === 'as');
+    if (asIdx >= 0 && tokens[asIdx + 1]) stages.add(tokens[asIdx + 1]);
+    if (!stages.has(ref) && !bases.includes(ref)) bases.push(ref);
+  }
+  return bases;
+}
+
+/** Map `docker/Dockerfile.observer` → `celilo-e2e/observer` (docker-compose-generator's imageTag). */
+function derivedImageTag(dockerfileName: string): string {
+  return `celilo-e2e/${dockerfileName.replace(/^Dockerfile\./, '')}`;
+}
+
+export interface DockerfileBases {
+  /** The `celilo-e2e/<name>` tag this Dockerfile produces. */
+  derived: string;
+  bases: string[];
+}
+
+/** Read every `docker/Dockerfile.*` and pair its produced tag with its base images. */
+export function readDockerfileBases(pkgDir: string): DockerfileBases[] {
+  const dir = join(pkgDir, 'docker');
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.startsWith('Dockerfile.'))
+    .sort()
+    .map((f) => ({
+      derived: derivedImageTag(f),
+      bases: parseBaseImages(readFileSync(join(dir, f), 'utf-8')),
+    }));
+}
+
+// ─── Checks ──────────────────────────────────────────────────────────
+
+/**
+ * The run-lock, including the two states `status` used to render identically to
+ * a healthy one: a stale-heartbeat holder (suspect) and this session's own kept
+ * stack (friction, not contention — the next run clears it).
+ */
+export function checkRunLock(lock: LockStatus): DoctorCheck {
+  if (lock.free || !lock.holder) {
+    return { name: 'run-lock', status: 'ok', detail: 'free' };
+  }
+  const h = lock.holder;
+  const age = formatAge(lock.heartbeatAgeMs ?? 0);
+  if (lock.suspect) {
+    return {
+      name: 'run-lock',
+      status: 'fail',
+      detail: `SUSPECT — ${h.session} running ${h.test} (pid ${h.pid}) has not beaten its heartbeat for ${age}; the process is alive but is not progressing`,
+      remedy: `Inspect it (\`docker ps\`, \`kill -0 ${h.pid}\`); if it is wedged, kill ${h.pid} then \`cele2e down\``,
+    };
+  }
+  if (lock.ownKept) {
+    return {
+      name: 'run-lock',
+      status: 'warn',
+      detail: `held by THIS session's own kept stack (${h.test}) — the next run auto-releases it`,
+      remedy: 'cele2e release   (or `cele2e down` to also tear the stack down)',
+    };
+  }
+  if (h.state === 'kept') {
+    return {
+      name: 'run-lock',
+      status: 'fail',
+      detail: `held by another session's kept stack: ${h.session} (${h.test})`,
+      remedy: 'Wait for that session, or `cele2e release` if you know it is abandoned',
+    };
+  }
+  return {
+    name: 'run-lock',
+    status: 'fail',
+    detail: `busy — ${h.session} running ${h.test} (pid ${h.pid}), heartbeat ${age} ago`,
+    remedy: 'Poll with `cele2e status --json` (exit 0 = free, 3 = busy) and wait',
+  };
+}
+
+/** The baked management images exist AND still run /startup.sh. */
+export function checkManagementImage(probe: DoctorProbe): DoctorCheck {
+  const missing = BAKED_MANAGEMENT_IMAGES.filter((ref) => !probe.imageExists(ref));
+  if (missing.length > 0) {
+    return {
+      name: 'management-image',
+      status: 'fail',
+      detail: `baked image missing: ${missing.join(', ')} — the test compose references these by tag and cannot build them`,
+      remedy: 'cele2e build-infra',
+    };
+  }
+  const unbaked = BAKED_MANAGEMENT_IMAGES.filter(
+    (ref) => !(probe.imageCmd(ref) ?? []).includes(EXPECTED_MANAGEMENT_CMD),
+  );
+  if (unbaked.length > 0) {
+    return {
+      name: 'management-image',
+      status: 'fail',
+      detail: `${unbaked.join(', ')} does not run ${EXPECTED_MANAGEMENT_CMD} — the bake commit lost its Cmd, so the ssh-keys volume will stay empty and every \`machine add\` will fail with "Cannot connect to root@<ip> with provided SSH key"`,
+      remedy: 'cele2e build-infra',
+    };
+  }
+  return {
+    name: 'management-image',
+    status: 'ok',
+    detail: `${BAKED_MANAGEMENT_IMAGES.length} baked images present, both running ${EXPECTED_MANAGEMENT_CMD}`,
+  };
+}
+
+/**
+ * Base images the next build genuinely has to fetch.
+ *
+ * A base image absent from the local store is only a problem when the image
+ * built FROM it is also absent — with the derived tag present, buildkit serves
+ * the build from cache and never resolves the reference. Requiring every base
+ * unconditionally would refuse environments that work today, so the check is
+ * the conjunction: no derived image AND no base image means the build must go
+ * to a registry, which is where `failed to solve: ubuntu:22.04: net/http: TLS
+ * handshake timeout` comes from — 16 images deep, blamed on the network.
+ */
+export function checkBaseImages(probe: DoctorProbe, dockerfiles: DockerfileBases[]): DoctorCheck {
+  const needPull = new Set<string>();
+  for (const { derived, bases } of dockerfiles) {
+    if (probe.imageExists(derived)) continue;
+    for (const base of bases) {
+      if (!probe.imageExists(base)) needPull.add(base);
+    }
+  }
+  if (needPull.size === 0) {
+    return { name: 'base-images', status: 'ok', detail: 'every image the build needs is local' };
+  }
+  const refs = [...needPull].sort();
+  return {
+    name: 'base-images',
+    status: 'fail',
+    detail: `${refs.length} base image(s) absent locally and needed by an image that must be rebuilt: ${refs.join(', ')}`,
+    remedy: refs.map((r) => `docker pull ${r}`).join('\n           '),
+  };
+}
+
+/** Leftover containers from a crashed run, which start-of-run cleanup will wipe. */
+export function checkStaleContainers(probe: DoctorProbe, lock: LockStatus): DoctorCheck {
+  const names = probe.staleContainers();
+  if (names.length === 0) {
+    return {
+      name: 'stale-containers',
+      status: 'ok',
+      detail: 'no leftover celilo-e2e-* containers',
+    };
+  }
+  // With a live holder these are simply that run's containers, not debris.
+  if (!lock.free && !lock.ownKept) {
+    return {
+      name: 'stale-containers',
+      status: 'ok',
+      detail: `${names.length} celilo-e2e-* container(s) belonging to the current lock holder`,
+    };
+  }
+  return {
+    name: 'stale-containers',
+    status: 'warn',
+    detail: `${names.length} celilo-e2e-* container(s) with no live run: ${names.slice(0, 4).join(', ')}${names.length > 4 ? ', …' : ''}`,
+    remedy: 'cele2e down   (start-of-run cleanup also removes these)',
+  };
+}
+
+/**
+ * Reclaimable image space. A warning, never a failure — the point is to steer
+ * the reflex: under disk pressure people reach for `docker image prune`, which
+ * deletes the base images the next build needs. Pruning e2e containers by name
+ * frees space without costing a 27-image rebuild.
+ */
+export function checkDiskPressure(probe: DoctorProbe): DoctorCheck {
+  const bytes = probe.reclaimableImageBytes();
+  const gib = (bytes / 1024 ** 3).toFixed(1);
+  if (bytes < RECLAIMABLE_WARN_BYTES) {
+    return { name: 'disk', status: 'ok', detail: `${gib} GiB reclaimable image space` };
+  }
+  return {
+    name: 'disk',
+    status: 'warn',
+    detail: `${gib} GiB reclaimable image space — do NOT run \`docker image prune\`; it deletes the base images the next build needs and costs a full rebuild`,
+    remedy:
+      'docker ps -aq --filter name=celilo-e2e | xargs -r docker rm -f && docker volume prune -f',
+  };
+}
+
+/**
+ * Turn buildkit's `failed to solve: <ref>: … TLS handshake timeout` into the
+ * one sentence that identifies the cause.
+ *
+ * That message names the network because buildkit was, technically, on the
+ * network — but it only went there because the base image was not in the local
+ * store, which is what `docker image prune` (the reflex under disk pressure)
+ * removes. Reading it as a connectivity problem cost a full 27-image rebuild.
+ * checkBaseImages preflights for this, so reaching here means the image went
+ * missing mid-run; either way, say what to pull.
+ *
+ * Returns '' when the failure names a RUN step rather than an image reference —
+ * a genuine build error, which needs no translation.
+ */
+export function explainBuildFailure(stderr: string): string {
+  const ref = stderr.match(/failed to solve:\s*([^\s:"]+(?::[^\s:"]+)?)/)?.[1];
+  if (!ref || ref === 'process') return '';
+  return [
+    '',
+    '',
+    `This names "${ref}" — buildkit had to fetch it, which means it is not in the local image store.`,
+    `A \`docker image prune\` removes exactly these. Fix: docker pull ${ref}`,
+    'Then re-run. `cele2e doctor` checks for this before a run starts.',
+  ].join('\n');
+}
+
+// ─── Real probe ──────────────────────────────────────────────────────
+
+function docker(args: string[]): string {
+  return execFileSync('docker', args, {
+    encoding: 'utf-8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+    timeout: 15_000,
+  }).trim();
+}
+
+export function createDockerProbe(): DoctorProbe {
+  // One `docker images` listing answers every existence question; per-image
+  // inspect calls would be ~40 process spawns on a preflight that must be fast.
+  let tags: Set<string> | null = null;
+  const knownTags = (): Set<string> => {
+    if (tags) return tags;
+    try {
+      tags = new Set(
+        docker(['images', '--format', '{{.Repository}}:{{.Tag}}'])
+          .split('\n')
+          .map((l) => l.trim())
+          .filter(Boolean),
+      );
+    } catch {
+      tags = new Set();
+    }
+    return tags;
+  };
+
+  return {
+    imageExists(ref) {
+      const withTag = ref.includes(':') ? ref : `${ref}:latest`;
+      return knownTags().has(withTag);
+    },
+    imageCmd(ref) {
+      try {
+        return JSON.parse(docker(['image', 'inspect', ref, '--format', '{{json .Config.Cmd}}']));
+      } catch {
+        return null;
+      }
+    },
+    staleContainers() {
+      try {
+        return docker(['ps', '-a', '--filter', 'name=celilo-e2e', '--format', '{{.Names}}'])
+          .split('\n')
+          .map((l) => l.trim())
+          .filter(Boolean);
+      } catch {
+        return [];
+      }
+    },
+    reclaimableImageBytes() {
+      try {
+        for (const line of docker(['system', 'df', '--format', '{{json .}}']).split('\n')) {
+          const row = JSON.parse(line) as { Type?: string; Reclaimable?: string };
+          if (row.Type !== 'Images') continue;
+          // Reclaimable looks like "12.3GB (48%)".
+          const m = row.Reclaimable?.match(/^([\d.]+)\s*([KMGT]?)B/i);
+          if (!m) return 0;
+          const scale = { '': 1, K: 1024, M: 1024 ** 2, G: 1024 ** 3, T: 1024 ** 4 }[
+            m[2].toUpperCase()
+          ];
+          return Number.parseFloat(m[1]) * (scale ?? 1);
+        }
+      } catch {}
+      return 0;
+    },
+  };
+}
+
+// ─── Report ──────────────────────────────────────────────────────────
+
+export interface DiagnoseOptions {
+  pkgDir: string;
+  probe?: DoctorProbe;
+  lock?: LockStatus;
+  /** Skip the run-lock check — `run` acquires the lock itself and reports contention its own way. */
+  skipLock?: boolean;
+}
+
+export function diagnose(options: DiagnoseOptions): DoctorReport {
+  const probe = options.probe ?? createDockerProbe();
+  const lock = options.lock ?? lockStatus();
+  const checks: DoctorCheck[] = [];
+  if (!options.skipLock) checks.push(checkRunLock(lock));
+  checks.push(checkManagementImage(probe));
+  checks.push(checkBaseImages(probe, readDockerfileBases(options.pkgDir)));
+  checks.push(checkStaleContainers(probe, lock));
+  checks.push(checkDiskPressure(probe));
+  return { checks, ok: !checks.some((c) => c.status === 'fail') };
+}
+
+const ICONS: Record<CheckStatus, string> = { ok: '✓', warn: '!', fail: '✗' };
+
+/** Render a report as the lines `doctor` prints and `run` prints on refusal. */
+export function formatReport(report: DoctorReport): string[] {
+  const lines: string[] = [];
+  for (const c of report.checks) {
+    lines.push(`  ${ICONS[c.status]} ${c.name.padEnd(18)} ${c.detail}`);
+    if (c.remedy) lines.push(`      fix: ${c.remedy}`);
+  }
+  return lines;
+}
+
+/** The holder line `status` prints, with heartbeat age always visible. */
+export function formatHolderLine(h: LockHolder): string {
+  const flags = [
+    isSuspect(h) ? 'SUSPECT' : null,
+    h.state === 'kept' && isSameSession(h) ? 'yours' : null,
+  ].filter(Boolean);
+  const suffix = flags.length ? ` [${flags.join(', ')}]` : '';
+  return `${h.session} — ${h.state} ${h.test} (pid ${h.pid}), heartbeat ${formatAge(heartbeatAgeMs(h))} ago${suffix}`;
+}

package/src/extract-failure.ts

@@ -12,6 +12,47 @@ export function stripAnsi(s: string): string {
   return s.replace(ANSI_RE, '');
 }
 
+export interface StageTally {
+  /** Stages that failed on their own merits. */
+  failed: number;
+  /** Stages that never ran because an earlier stage had already failed. */
+  skipped: number;
+}
+
+/**
+ * Split a staged suite's failures into real ones and cascade-skips.
+ *
+ * Staged e2e suites guard every stage with `requireStage`, which throws
+ * `Skipped: <stage> — <earlier error>` once anything upstream has failed. bun
+ * counts each of those as a failure, so ONE bad fixture line in stage 1 reports
+ * as "9 failed" in a 10-stage suite — nine counts of a defect that does not
+ * exist, and a summary that buries the one that does.
+ *
+ * The `Skipped:` marker is the semantic signal, so that is what we key on; the
+ * sub-millisecond durations those stages show are a symptom, not the contract.
+ */
+export function tallyStages(lines: string[]): StageTally {
+  const plain = lines.map(stripAnsi);
+  const isFailure = (l: string): boolean => /^\(fail\)\s+\S/.test(l);
+  let failed = 0;
+  let skipped = 0;
+  for (let i = 0; i < plain.length; i++) {
+    if (!isFailure(plain[i])) continue;
+    // bun prints the reason on the following lines, indented under the failure.
+    // The window MUST stop at the next failure: cascade-skips come in runs, and
+    // a window that reads past the boundary attributes the next stage's
+    // "Skipped:" to this one — which misreads the single real defect at the top
+    // of a cascade as just another skip, losing the only line worth reading.
+    const reason: string[] = [];
+    for (let j = i + 1; j < plain.length && j <= i + 4 && !isFailure(plain[j]); j++) {
+      reason.push(plain[j]);
+    }
+    if (/(?:^|\W)Skipped:\s/.test(reason.join('\n'))) skipped++;
+    else failed++;
+  }
+  return { failed, skipped };
+}
+
 export function extractFailureMessage(lines: string[], exitCode: number): string {
   const plain = lines.map(stripAnsi);
 

package/src/index.ts

@@ -102,3 +102,15 @@ export {
   SHARED_PROJECT_NAME,
   SHARED_NETWORKS,
 } from './docker-compose-generator';
+
+// Runtime router-device swap — the harness half of "the ISP replaced the box"
+// (openspec/changes/module-pause-lifecycle task 7.7).
+export {
+  ROUTER_DEVICES,
+  type RouterDevice,
+  type RouterSwapResult,
+  forwardedPorts,
+  listRouterForwards,
+  routerDhcpDnsServers,
+  swapRouterDevice,
+} from './router-swap';

package/src/last-run.test.ts

@@ -0,0 +1,62 @@
+import { afterEach, beforeEach, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { type LastRun, readLastRun, writeLastRun } from './last-run';
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'e2e-last-'));
+  process.env.CELILO_E2E_LAST_RUN_PATH = join(dir, 'last-run.json');
+});
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+  delete process.env.CELILO_E2E_LAST_RUN_PATH;
+});
+
+const RUN: LastRun = {
+  runId: 'abc-123',
+  resultsDir: '/repo/e2e/results/2026-08-12T10-00-00',
+  startedAt: '2026-08-12T17:00:00.000Z',
+  status: 'completed',
+  total: 3,
+  passed: 3,
+  failed: 0,
+  skipped: 0,
+  durationMs: 600_000,
+};
+
+test('with no run recorded, readLastRun is null rather than throwing', () => {
+  expect(readLastRun()).toBeNull();
+});
+
+test('a recorded run round-trips every field `cele2e last --json` promises', () => {
+  writeLastRun(RUN);
+  expect(readLastRun()).toEqual(RUN);
+});
+
+test('the record is overwritten, so `last` never returns a stale earlier run', () => {
+  // The whole point: inferring "my results dir" from `ls -t results | head -1`
+  // hands back the PREVIOUS run's numbers when a run refuses to start, and a
+  // suite that never executed then reads as a clean pass.
+  writeLastRun(RUN);
+  writeLastRun({ ...RUN, runId: 'def-456', resultsDir: '/repo/e2e/results/later', failed: 2 });
+  const last = readLastRun();
+  expect(last?.runId).toBe('def-456');
+  expect(last?.resultsDir).toBe('/repo/e2e/results/later');
+  expect(last?.failed).toBe(2);
+});
+
+test('a run still in flight is recorded as running, so its logs are findable', () => {
+  writeLastRun({ ...RUN, status: 'running', passed: 0, total: 3 });
+  expect(readLastRun()?.status).toBe('running');
+  expect(readLastRun()?.resultsDir).toBe(RUN.resultsDir);
+});
+
+test('a corrupt record is null, not fatal', () => {
+  writeLastRun(RUN);
+  Bun.write(process.env.CELILO_E2E_LAST_RUN_PATH as string, 'not json{');
+  expect(readLastRun()).toBeNull();
+});

package/src/last-run.ts

@@ -0,0 +1,54 @@
+/**
+ * A machine-global pointer to the most recent cele2e run.
+ *
+ * Without one, "how did my run go?" is answered by `ls -t e2e/results | head -1`
+ * — which returns the newest directory, not YOUR run. When a run refuses to
+ * start (a held lock, a failed preflight) that inference silently hands back the
+ * PREVIOUS run's numbers, and a suite that never executed reads as a clean pass.
+ *
+ * Written at run start (so a run that dies mid-way still has a findable results
+ * dir) and again at the end with the counts. Lives beside the run-lock rather
+ * than in a worktree, because which checkout started the run is not something
+ * the reader knows.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+export interface LastRun {
+  runId: string;
+  resultsDir: string;
+  startedAt: string;
+  /** 'running' until the suite finishes; then 'completed' or 'failed'. */
+  status: 'running' | 'completed' | 'failed';
+  total: number;
+  passed: number;
+  failed: number;
+  /** Stages a failing earlier stage blocked. Distinct from real failures. */
+  skipped: number;
+  durationMs: number;
+}
+
+export function lastRunPath(): string {
+  return (
+    process.env.CELILO_E2E_LAST_RUN_PATH || join(homedir(), '.cache', 'celilo-e2e', 'last-run.json')
+  );
+}
+
+export function writeLastRun(run: LastRun): void {
+  try {
+    mkdirSync(dirname(lastRunPath()), { recursive: true });
+    writeFileSync(lastRunPath(), `${JSON.stringify(run, null, 2)}\n`);
+  } catch {
+    // ponytail: a bookkeeping pointer must never be the thing that fails a run.
+  }
+}
+
+export function readLastRun(): LastRun | null {
+  try {
+    return JSON.parse(readFileSync(lastRunPath(), 'utf-8')) as LastRun;
+  } catch {
+    return null;
+  }
+}

package/src/network-builder.ts

@@ -59,6 +59,17 @@ export class NetworkBuilder {
     return this;
   }
 
+  /**
+   * Make the `fw-isp` simulator stand in for an Axon Networks Q1000K rather
+   * than the default GreenWave C4000XG. The two speak an identical CGI
+   * protocol; only the TR-181 vendor extension prefix differs, so this swaps
+   * `X_GWS_Via`/`X_LANTIQ_COM_INTERFACE` for `X_AXON_Via`/`X_AXON_INTERFACE`.
+   */
+  axonRouter(): this {
+    this.config.routerVendorPrefix = 'X_AXON_';
+    return this;
+  }
+
   /**
    * Place the celilo management container in a given zone. Defaults to
    * `internal`; `secure-mgmt` gives celilo-mgr its own control-plane network

package/src/observer.test.ts

@@ -44,14 +44,14 @@ describe('placement faithfulness (the load-bearing invariants)', () => {
   });
 
   test('publicInternet uses only the public resolver (never the internal split-horizon view)', () => {
-    expect(OBSERVER_PLACEMENTS.publicInternet.resolvers).toEqual(['100.100.0.1']);
+    expect(OBSERVER_PLACEMENTS.publicInternet.resolvers).toEqual(['203.0.113.1']);
   });
 
   test('observerEnv serializes the routing profile for the setup script', () => {
     const env = observerEnv(OBSERVER_PLACEMENTS.internalDevice);
     expect(env.OBSERVER_INTERZONE).toBe('0');
     expect(env.OBSERVER_GATEWAY).toBe(OBSERVER_PLACEMENTS.internalDevice.gateway);
-    expect(env.OBSERVER_RESOLVERS).toContain('100.100.0.1');
+    expect(env.OBSERVER_RESOLVERS).toContain('203.0.113.1');
   });
 });
 

package/src/observer.ts

@@ -47,7 +47,7 @@ export interface ObserverPlacement {
 // NO route to the segmented zones, so a dmz/app/secure container IP is unreachable.
 const HOME_ROUTER = '10.226.1.1';
 const INTERNAL_RESOLVER = '10.226.1.10';
-const PUBLIC_RESOLVER = '100.100.0.1';
+const PUBLIC_RESOLVER = '203.0.113.1';
 const INTERNET_GATEWAY = '100.64.0.1'; // fw-ext, on internet-external
 
 /** Derive an observer host IP in a zone from its gateway (no new literal subnets). */