@celilo/e2e 0.20.5 → 0.21.0

package/src/cli/build.ts

@@ -34,7 +34,7 @@ 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 { explainBuildFailure, readDockerfileBases } from '../doctor';
 import { isNetappCurrent } from '../netapp-staleness';
 import { ensureRegistryServerBundle, ensureTerraformFakeBundle } from '../registry-bundle';
 import { findMonorepoRoot } from '../repo-root';
@@ -582,6 +582,37 @@ export async function stageNetappsFromRegistry(netappsDir: string): Promise<void
   console.log('');
 }
 
+/**
+ * Pull every base image a `docker/Dockerfile.*` names into the local image
+ * store, so buildkit resolves each FROM locally instead of against a registry.
+ *
+ * This is the one-command fix for the base-images warn (celilo#1244). It is
+ * cheap — the layers are usually already in buildkit's cache, so a pull is ~2s
+ * and reports `Already exists` — and it removes the failure mode where a
+ * registry blip kills a build 30 seconds in with an error naming the network.
+ *
+ * Best-effort per image: a pull that fails leaves the build to try the same
+ * resolution itself, which is exactly today's behaviour, so refusing here would
+ * only make build-infra more brittle than the thing it is protecting.
+ */
+export function pullDockerfileBases(pkgDir: string): string[] {
+  const bases = [...new Set(readDockerfileBases(pkgDir).flatMap((d) => d.bases))].sort();
+  if (bases.length === 0) return [];
+  console.log(`${bold}Pulling ${bases.length} Docker base images...${reset}`);
+  const failed: string[] = [];
+  for (const ref of bases) {
+    const result = spawnSync('docker', ['pull', '--quiet', ref], { stdio: 'ignore' });
+    if (result.status !== 0) failed.push(ref);
+  }
+  if (failed.length > 0) {
+    console.error(
+      `${yellow}⚠ could not pull ${failed.join(', ')} — the build will try the same resolution itself${reset}`,
+    );
+  }
+  console.log('');
+  return failed;
+}
+
 function buildDockerImages(pkgDir: string): void {
   // Refresh the bundled registry-server source before docker build —
   // Dockerfile.registry copies from <pkgDir>/registry-server, which is
@@ -900,6 +931,10 @@ export async function runBuild(options: BuildOptions): Promise<void> {
     process.exit(1);
   }
 
+  // Before any build: put every base in the image store, so buildkit never has
+  // to ask a registry mid-build (celilo#1244).
+  pullDockerfileBases(pkgDir);
+
   console.log(`${bold}Building E2E Docker images...${reset}\n`);
   buildDockerImages(pkgDir);
 

package/src/cli/host.ts

@@ -75,6 +75,68 @@ export function colimaStartArgs(budget: HostVmBudget, profile: string): string[]
   ];
 }
 
+/**
+ * The binfmt_misc handler amd64 emulation registers in the VM kernel.
+ * `tonistiigi/binfmt --install amd64` writes exactly this name.
+ */
+const AMD64_BINFMT_HANDLER = '/proc/sys/fs/binfmt_misc/qemu-x86_64';
+
+/** Is amd64 emulation registered in the VM right now? */
+function haveAmd64Emulation(profile: string): boolean {
+  // stdio ignored on purpose: colima ssh writes config warnings to stderr on
+  // every invocation, and only the exit status answers the question.
+  return (
+    spawnSync('colima', ['ssh', '-p', profile, '--', 'test', '-f', AMD64_BINFMT_HANDLER], {
+      stdio: 'ignore',
+    }).status === 0
+  );
+}
+
+/**
+ * Register amd64 emulation in the VM, idempotently.
+ *
+ * WHY THIS LIVES IN `host up` AND NOT IN A README. binfmt_misc registrations
+ * are kernel state inside the colima VM, so they do NOT survive a VM restart —
+ * and nothing about the resulting failure names emulation. `build-infra` dies
+ * building the signal image, whose Dockerfile pins `--platform=linux/amd64`,
+ * with an exec-format error that reads like a broken base image. It only ever
+ * appeared to work because CI builds on an amd64 runner and a warm local cache
+ * hid it on this arm64 Mac.
+ *
+ * Installing costs one small privileged container. The check above costs an
+ * ssh, so the install runs only when the handler is genuinely absent — which,
+ * on a VM that has just been created or restarted, it always is.
+ *
+ * Non-fatal by design: a host with no amd64 module still runs every suite that
+ * does not build the signal image, and failing `host up` over it would be a
+ * worse trade than the warning.
+ */
+function ensureAmd64Emulation(profile: string): void {
+  // On an x64 host amd64 is native, so no handler is registered and none is
+  // wanted — without this guard the install would re-run on every `host up`.
+  if (process.arch === 'x64') return;
+  if (haveAmd64Emulation(profile)) return;
+
+  console.log(
+    `${dim}Registering amd64 emulation (binfmt_misc does not survive a VM restart)${reset}`,
+  );
+  const result = spawnSync(
+    'docker',
+    ['run', '--privileged', '--rm', 'tonistiigi/binfmt', '--install', 'amd64'],
+    { stdio: 'ignore' },
+  );
+  if (result.status === 0 && haveAmd64Emulation(profile)) {
+    console.log(`${green}amd64 emulation registered.${reset}`);
+    return;
+  }
+  console.error(
+    `${yellow}!${reset} Could not register amd64 emulation. Suites that build an amd64 image`,
+  );
+  console.error(
+    `  (signal) will fail with an exec-format error. Retry with: ${bold}docker run --privileged --rm tonistiigi/binfmt --install amd64${reset}`,
+  );
+}
+
 function reportStatus(): number {
   const profile = activeProfile();
   const host = readHostFacts();
@@ -124,7 +186,9 @@ function bringUp(): number {
       `${bold}Creating the colima VM${reset} ${dim}(${budget.cpus} CPU, ${budget.memoryGiB} GiB, ${budget.mountType} mounts)${reset}`,
     );
     const result = spawnSync('colima', colimaStartArgs(budget, profile), { stdio: 'inherit' });
-    return result.status ?? 1;
+    if (result.status !== 0) return result.status ?? 1;
+    ensureAmd64Emulation(profile);
+    return 0;
   }
 
   const { problems, needsRecreate } = evaluateHostVm(existing, host, budget);
@@ -142,6 +206,9 @@ function bringUp(): number {
 
   if (colimaRunning(profile) && problems.length === 0) {
     console.log(`${green}Docker host already up and in policy.${reset}`);
+    // Still check: a VM someone started with a bare `colima start`, or one
+    // that restarted under us, is in policy and has no emulation registered.
+    ensureAmd64Emulation(profile);
     return 0;
   }
 
@@ -155,7 +222,9 @@ function bringUp(): number {
     ['start', '-p', profile, '--cpu', String(budget.cpus), '--memory', String(budget.memoryGiB)],
     { stdio: 'inherit' },
   );
-  return result.status ?? 1;
+  if (result.status !== 0) return result.status ?? 1;
+  ensureAmd64Emulation(profile);
+  return 0;
 }
 
 /**

package/src/docker-compose-generator.ts

@@ -450,7 +450,11 @@ export function generateSharedInfraYaml(): string {
     dockerfile: 'docker/Dockerfile.pebble',
     networks: { 'internet-external': { ipv4_address: SIMULATOR_IPS.PEBBLE } },
     cap_add: ['NET_ADMIN'],
-    command: '-config /config/pebble-config.json -dnsserver 203.0.113.1:53',
+    // -dnsserver is the resolver Pebble asks when validating a challenge. It
+    // MUST be a shared-infra resolver: comcast-resolver (203.0.113.1) is
+    // per-test, so naming it here left shared infra unable to finish ACME
+    // until a test stack existed (celilo#1365).
+    command: `-config /config/pebble-config.json -dnsserver ${SIMULATOR_IPS.PUBLIC_RESOLVER}:53`,
     volumes: [
       './config/pebble/pebble-config.json:/config/pebble-config.json:ro',
       './config/pebble/pebble-tls.crt:/config/pebble-tls.crt:ro',
@@ -511,7 +515,7 @@ export function generateSharedInfraYaml(): string {
     dockerfile: 'docker/Dockerfile.isitup',
     networks: { 'internet-external': { ipv4_address: SIMULATOR_IPS.ISITUP } },
     cap_add: ['NET_ADMIN'],
-    dns: ['203.0.113.1'],
+    dns: [SIMULATOR_IPS.PUBLIC_RESOLVER],
   });
 
   // celilo.computer static site simulator — serves install.sh and the docs
@@ -523,7 +527,7 @@ export function generateSharedInfraYaml(): string {
     dockerfile: 'docker/Dockerfile.celilo-website-sim',
     networks: { 'internet-external': { ipv4_address: SIMULATOR_IPS.WEBSITE } },
     cap_add: ['NET_ADMIN'],
-    dns: ['203.0.113.1'],
+    dns: [SIMULATOR_IPS.PUBLIC_RESOLVER],
   });
 
   // npm-compat registry simulator — serves @celilo/* tarballs to install.sh's

package/src/doctor.test.ts

@@ -29,7 +29,9 @@ import {
   checkStaleContainers,
   diagnose,
   explainBuildFailure,
+  imageLookupKey,
   parseBaseImages,
+  readDockerfileBases,
   stackStartedAt,
 } from './doctor';
 import type { LeakedStack } from './doctor';
@@ -133,25 +135,36 @@ describe('base images (problem 3: a missing image reads as a network failure)',
     { derived: 'celilo-e2e/pebble', bases: ['ghcr.io/letsencrypt/pebble:latest'] },
   ];
 
-  test('a base image missing with its derived image ALSO missing fails, with the pull', () => {
+  test('a base image missing with its derived image ALSO missing fails, naming the fix', () => {
     // Post `docker image prune`: nothing local, so the build must go to a
     // registry — the exact state that produced "failed to solve: ubuntu:22.04:
     // net/http: TLS handshake timeout" 16 images into a rebuild.
     const check = checkBaseImages(healthyProbe({ imageExists: () => false }), dockerfiles);
     expect(check.status).toBe('fail');
     expect(check.detail).toContain('ubuntu:22.04');
-    expect(check.remedy).toContain('docker pull ubuntu:22.04');
-    expect(check.remedy).toContain('docker pull ghcr.io/letsencrypt/pebble:latest');
+    expect(check.remedy).toContain('cele2e build-infra');
   });
 
-  test('a base image missing but its derived image present passes — the build is cached', () => {
-    // This is the ordinary steady state on a working machine, and a check that
-    // failed here would refuse environments that run fine today.
+  test('a base absent with its derived image PRESENT warns — it used to be silent', () => {
+    // The measured case this check existed and could not see (celilo#1244).
+    // 2026-09-04: all twelve bases absent, 29 derived tags present, doctor said
+    // `ok`, and buildkit went to the registry anyway — 30 of 32 suites died in
+    // 1-2s each. Not a `fail`: ten of twelve bases are routinely absent on a
+    // host where e2e passes, so failing would refuse a working machine.
     const check = checkBaseImages(
       healthyProbe({ imageExists: (ref) => ref.startsWith('celilo-e2e/') }),
       dockerfiles,
     );
+    expect(check.status).toBe('warn');
+    expect(check.detail).toContain('ubuntu:22.04');
+    expect(check.detail).toContain('cache key');
+    expect(check.remedy).toContain('cele2e build-infra');
+  });
+
+  test('every base present is the only state reported ok, and it says so', () => {
+    const check = checkBaseImages(healthyProbe(), dockerfiles);
     expect(check.status).toBe('ok');
+    expect(check.detail).toContain('2 base image(s)');
   });
 
   test('only the images that actually need fetching are named', () => {
@@ -165,6 +178,64 @@ describe('base images (problem 3: a missing image reads as a network failure)',
     expect(check.detail).toContain('ubuntu:22.04');
     expect(check.detail).not.toContain('pebble');
   });
+
+  // ─── Reach probe ───────────────────────────────────────────────────
+  //
+  // The set this check walks is COMPUTED (every `docker/Dockerfile.*` crossed
+  // with a store query), which is the shape apps/celilo/CLAUDE.md says to
+  // measure rather than reason about. So derive it from the REAL docker/ dir
+  // and plant one absence at a time: whichever base the check names is its
+  // actual reach. Hand-writing the Dockerfile list here would give confident
+  // reach data about a directory that does not exist.
+  describe('reach: every base a real Dockerfile names is examined', () => {
+    const real = readDockerfileBases(join(import.meta.dir, '..'));
+    const realBases = [...new Set(real.flatMap((d) => d.bases))].sort();
+
+    test('the probe has a set to measure', () => {
+      expect(real.length).toBeGreaterThan(0);
+      expect(realBases.length).toBeGreaterThan(0);
+    });
+
+    for (const planted of realBases) {
+      test(`${planted} absent from the image store is reported, not skipped`, () => {
+        // Every derived tag present — the state the old short-circuit treated
+        // as proof the base was irrelevant. It is the state that broke a run.
+        const check = checkBaseImages(
+          healthyProbe({ imageExists: (ref) => ref !== planted }),
+          real,
+        );
+        expect(check.status).not.toBe('ok');
+        expect(check.detail).toContain(planted);
+      });
+    }
+  });
+});
+
+describe('image lookup key (a pinned base read absent forever)', () => {
+  // Every e2e Dockerfile pins its bases by digest. `docker images` lists such an
+  // image as `nginx:<none>` plus `nginx@sha256:…`, so a lookup by `repo:tag`
+  // could never match and `base-images` would warn about all of them for good.
+  test('a digest-pinned ref collapses to repo@digest, dropping the tag', () => {
+    expect(imageLookupKey('nginx:alpine@sha256:abc')).toBe('nginx@sha256:abc');
+  });
+
+  test('a registry path with a digest keeps the whole repo', () => {
+    expect(imageLookupKey('ghcr.io/letsencrypt/pebble:latest@sha256:abc')).toBe(
+      'ghcr.io/letsencrypt/pebble@sha256:abc',
+    );
+  });
+
+  test('an untagged ref gets :latest, the way docker does', () => {
+    expect(imageLookupKey('cznic/knot')).toBe('cznic/knot:latest');
+  });
+
+  test('a host:port registry is not mistaken for a tag', () => {
+    expect(imageLookupKey('localhost:5000/thing')).toBe('localhost:5000/thing:latest');
+  });
+
+  test('a plain tagged ref is unchanged', () => {
+    expect(imageLookupKey('ubuntu:22.04')).toBe('ubuntu:22.04');
+  });
 });
 
 describe('run-lock (problems 2 and 5)', () => {
@@ -367,6 +438,16 @@ describe('build failure translation', () => {
     expect(text).toContain('docker pull ubuntu:22.04');
   });
 
+  test('an exec-format error is explained as missing amd64 emulation', () => {
+    const text = explainBuildFailure(
+      'ERROR: failed to solve: process "/bin/sh -c apt-get update" did not complete ' +
+        'successfully: exec /bin/sh: exec format error',
+    );
+    expect(text).toContain('exec format error');
+    expect(text).toContain('binfmt_misc');
+    expect(text).toContain('cele2e host up');
+  });
+
   test('a genuine RUN-step failure is left alone', () => {
     expect(
       explainBuildFailure(

package/src/doctor.ts

@@ -99,7 +99,14 @@ export interface LeakedStack {
 
 /** 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`. */
+  /**
+   * Is this image present in docker's IMAGE STORE (the `docker images` tag
+   * list)? An untagged ref means `:latest`.
+   *
+   * This is not buildkit's build cache. buildkit can build from a base absent
+   * here, so `false` means "may reach a registry", not "the build will fail" —
+   * see `checkBaseImages`, which is where that asymmetry decides a verdict.
+   */
   imageExists(ref: string): boolean;
   /** The image's configured Cmd, or null when the image is absent. */
   imageCmd(ref: string): string[] | null;
@@ -143,6 +150,29 @@ export function parseBaseImages(dockerfile: string): string[] {
   return bases;
 }
 
+/**
+ * The key a ref is found under in docker's image listing.
+ *
+ * A digest-pinned ref (`nginx:alpine@sha256:…`, which is how every e2e
+ * Dockerfile pins its bases) is listed by REPO AND DIGEST, never by the tag it
+ * was pulled with — `docker images` shows `nginx:<none>` for it. So looking a
+ * pinned ref up by `repo:tag` never matches and every pinned base reads absent
+ * forever. Pinned refs collapse to `repo@sha256:…`; an unpinned one gets
+ * `:latest` the way docker does.
+ */
+export function imageLookupKey(ref: string): string {
+  const at = ref.indexOf('@');
+  if (at >= 0) {
+    const digest = ref.slice(at + 1);
+    const name = ref.slice(0, at);
+    const lastSlash = name.lastIndexOf('/');
+    const colon = name.indexOf(':', lastSlash + 1);
+    return `${colon >= 0 ? name.slice(0, colon) : name}@${digest}`;
+  }
+  const lastSlash = ref.lastIndexOf('/');
+  return ref.includes(':', lastSlash + 1) ? ref : `${ref}:latest`;
+}
+
 /** Map `docker/Dockerfile.observer` → `celilo-e2e/observer` (docker-compose-generator's imageTag). */
 function derivedImageTag(dockerfileName: string): string {
   return `celilo-e2e/${dockerfileName.replace(/^Dockerfile\./, '')}`;
@@ -256,33 +286,70 @@ export function checkManagementImage(probe: DoctorProbe): DoctorCheck {
 }
 
 /**
- * Base images the next build genuinely has to fetch.
+ * Base images the next build must resolve, measured against docker's image
+ * store — which is NOT the store buildkit builds from.
+ *
+ * `imageExists` reads `docker images`, the image-store tag list. buildkit keeps
+ * its own cache, so a base absent from the tag list may still build fine. That
+ * asymmetry decides the verdict here, in one direction only:
+ *
+ *   base tag PRESENT  -> buildkit resolves it locally. Guaranteed safe.
+ *   base tag ABSENT   -> buildkit MAY reach a registry. Not knowably safe.
  *
- * 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.
+ * The old check turned the second case into silence whenever the derived image
+ * was present, on the premise that "buildkit serves the build from cache and
+ * never resolves the reference". That premise is false, measured twice: on
+ * 2026-09-03 three suites died on `failed to solve: debian:trixie-slim` with
+ * the derived tag present, and on 2026-09-04 all twelve bases were absent, all
+ * 29 derived tags were present, doctor said `ok`, and 30 of 32 suites died in
+ * 1-2s each. buildkit resolves a FROM reference to compute its cache key, and a
+ * tag is mutable, so that resolution can go to the registry.
+ *
+ * So the absent case is a WARN, never silence, and never a `fail` either: ten
+ * of twelve bases are routinely absent from this host's tag list while e2e
+ * passes on it, so failing would refuse a working machine ten times over. The
+ * exception is a base whose derived image is ALSO absent — then the build has
+ * to run and has nothing local to run from, which is a certainty, not a risk.
+ *
+ * `cele2e build-infra` now pulls every base a Dockerfile names, which is the
+ * one-command way out of the warn.
  */
 export function checkBaseImages(probe: DoctorProbe, dockerfiles: DockerfileBases[]): DoctorCheck {
-  const needPull = new Set<string>();
+  // Every base a Dockerfile names, and whether anything consuming it must be
+  // rebuilt from scratch. No short-circuit: the derived tag's presence changes
+  // the SEVERITY, never whether the base gets looked at.
+  const absent = new Map<string, boolean>();
   for (const { derived, bases } of dockerfiles) {
-    if (probe.imageExists(derived)) continue;
+    const mustBuild = !probe.imageExists(derived);
     for (const base of bases) {
-      if (!probe.imageExists(base)) needPull.add(base);
+      if (probe.imageExists(base)) continue;
+      absent.set(base, (absent.get(base) ?? false) || mustBuild);
     }
   }
-  if (needPull.size === 0) {
-    return { name: 'base-images', status: 'ok', detail: 'every image the build needs is local' };
+  const total = new Set(dockerfiles.flatMap((d) => d.bases)).size;
+  if (absent.size === 0) {
+    return {
+      name: 'base-images',
+      status: 'ok',
+      detail: `all ${total} base image(s) are in the local image store, so buildkit resolves every FROM without reaching a registry`,
+    };
+  }
+  const refs = [...absent.keys()].sort();
+  const certain = refs.filter((r) => absent.get(r));
+  const remedy = 'cele2e build-infra   (it pulls every base a Dockerfile names)';
+  if (certain.length > 0) {
+    return {
+      name: 'base-images',
+      status: 'fail',
+      detail: `${certain.length} base image(s) absent from the image store AND needed by an image that must be rebuilt, so the build has nothing local to build from: ${certain.join(', ')}`,
+      remedy,
+    };
   }
-  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           '),
+    status: 'warn',
+    detail: `${refs.length} of ${total} base image(s) absent from the image store: ${refs.join(', ')}. Their derived images are present, but buildkit still resolves each FROM to compute its cache key, so a registry blip fails the build ~30s in and blames the network (celilo#1244)`,
+    remedy,
   };
 }
 
@@ -518,6 +585,22 @@ export function checkDiskPressure(probe: DoctorProbe): DoctorCheck {
  * a genuine build error, which needs no translation.
  */
 export function explainBuildFailure(stderr: string): string {
+  // Missing amd64 emulation, which names neither amd64 nor emulation. The
+  // handler lives in binfmt_misc inside the colima VM and does NOT survive a
+  // VM restart, so a rig that built the signal image yesterday fails today
+  // with what reads like a corrupt base image. `cele2e host up` registers it.
+  if (/exec format error/i.test(stderr)) {
+    return [
+      '',
+      '',
+      'This is an "exec format error" — the image is a different architecture than',
+      'this host and the kernel has no emulator registered for it. The signal image',
+      'pins `--platform=linux/amd64`; on an arm64 Mac that needs binfmt_misc, which',
+      'lives in the colima VM kernel and is LOST on every VM restart.',
+      'Fix: cele2e host up   (registers it, idempotently)',
+    ].join('\n');
+  }
+
   const ref = stderr.match(/failed to solve:\s*([^\s:"]+(?::[^\s:"]+)?)/)?.[1];
   if (!ref || ref === 'process') return '';
   return [
@@ -542,15 +625,22 @@ function docker(args: string[]): string {
 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.
+  // Both keys, because a digest-pinned base is listed only by digest — see
+  // imageLookupKey. Indexing tags alone made every pinned base read absent.
   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')
+        docker([
+          'images',
+          '--digests',
+          '--format',
+          '{{.Repository}}:{{.Tag}}\t{{.Repository}}@{{.Digest}}',
+        ])
+          .split(/[\n\t]/)
           .map((l) => l.trim())
-          .filter(Boolean),
+          .filter((l) => l && !l.endsWith(':<none>') && !l.endsWith('@<none>')),
       );
     } catch {
       tags = new Set();
@@ -560,8 +650,7 @@ export function createDockerProbe(): DoctorProbe {
 
   return {
     imageExists(ref) {
-      const withTag = ref.includes(':') ? ref : `${ref}:latest`;
-      return knownTags().has(withTag);
+      return knownTags().has(imageLookupKey(ref));
     },
     imageCmd(ref) {
       try {

package/src/greenwave-external-interface.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from 'bun:test';
+/**
+ * A port forward must bind the interface that actually carries the public IP.
+ *
+ * celilo#1436. The greenwave simulator defaulted EXTERNAL_INTERFACE to 'eth1'
+ * and nothing set it, while on fw-isp eth0 carries 203.0.113.100 and eth1 is
+ * the internal leg. Every DNAT was therefore bound to the interface facing away
+ * from the internet: hairpin traffic from inside matched, inbound internet
+ * traffic was refused, and no per-test domain could obtain a certificate.
+ *
+ * This reads the REAL simulator source rather than re-implementing its logic —
+ * a test that restates the derivation would pass against a file that still
+ * hardcodes the wrong default.
+ */
+import { join } from 'node:path';
+
+// Resolved from THIS FILE, not from the cwd. `bun run test` runs each
+// workspace package's suite with that package's own cwd, so a repo-root
+// relative path resolves to packages/e2e/packages/e2e/... and Bun.file()
+// throws ENOENT -- while the same path works when run from the repo root,
+// which is where it gets tried by hand. A test that cannot reach the file it
+// reads is the shape celilo's CLAUDE.md calls "a check that cannot reach the
+// thing it is checking", and it is exactly what this test exists to avoid.
+const SRC = join(import.meta.dir, '..', 'simulators', 'greenwave', 'state.ts');
+
+describe('celilo#1436: the greenwave sim does not guess interface names', () => {
+  test('the port-forward DNAT is scoped by destination address, not by interface', async () => {
+    const src = await Bun.file(SRC).text();
+
+    // Docker hands out interface names in a non-deterministic order, so
+    // DERIVING the right one only chooses which direction breaks. The
+    // destination address is the discriminator that cannot be raced: only
+    // traffic actually addressed to PUBLIC_IP can match, whichever leg it
+    // arrived on.
+    expect(src).toMatch(/PREROUTING -d \$\{PUBLIC_IP\}/);
+  });
+
+  test('no port-forward rule binds an interface at all', async () => {
+    const src = await Bun.file(SRC).text();
+
+    // The control, and the reason this file exists: re-introducing `-i` on a
+    // forwarding rule is exactly the regression, and it would otherwise pass
+    // the assertion above unnoticed.
+    const forwardRules = src
+      .split('\n')
+      .filter((l) => l.includes('PREROUTING') && l.includes('DNAT'));
+    expect(forwardRules.length).toBeGreaterThan(0);
+    for (const rule of forwardRules) {
+      expect(rule).not.toMatch(/\s-i\s/);
+    }
+  });
+
+  test('the DHCP interface is derived from the address it serves, never hardcoded', async () => {
+    const src = await Bun.file(SRC).text();
+
+    // dnsmasq's `interface=` DOES still need a name -- it binds a socket, so
+    // an address cannot stand in for it. That one is derived from the router
+    // address it is about to serve.
+    expect(src).toContain('deriveDhcpInterface');
+    expect(src).toContain('interfaceCarrying');
+    expect(src).not.toMatch(/interface=eth[0-9]/);
+  });
+});

package/src/index.ts

@@ -65,6 +65,7 @@ export {
   internalNatIp,
   internalResolverIp,
   publicResolverIp,
+  zoneIp,
   ZONE_GATEWAYS,
   ZONE_SUBNETS,
 } from './types';