@celilo/e2e 0.9.2 → 0.10.0

package/src/cli/command-registry.ts

@@ -25,16 +25,31 @@ export const COMMANDS: CommandDef[] = [
     name: 'run',
     description: 'Run e2e tests — pass a module path or pattern, or --all / --all-modules',
     flags: [
-      { name: '--all', description: 'Run the full regression: every module suite + top-level e2e/tests/' },
-      { name: '--complete', description: 'Alias of --all: run every test, including ci-unsafe (quarantined) ones' },
-      { name: '--ci-safe', description: 'Full regression EXCEPT tests marked cele2e-ci-unsafe (used by the nightly)' },
+      {
+        name: '--all',
+        description:
+          'Full regression: every module suite + top-level e2e/tests/ (quarantined cele2e-ci-unsafe tests skipped)',
+      },
+      {
+        name: '--complete',
+        description:
+          'Run EVERYTHING including quarantined (cele2e-ci-unsafe) tests — the only mode that opts into them',
+      },
+      {
+        name: '--ci-safe',
+        description:
+          'Alias for the default full regression (quarantined tests skipped); kept for the nightly',
+      },
       { name: '--all-modules', description: 'Run e2e tests for all modules with e2e/ directories' },
       { name: '--keep', description: 'Keep network running after tests' },
       { name: '--reuse', description: 'Reuse existing network if running' },
       { name: '--live', description: 'Use live (non-simulated) internet' },
       { name: '--published', description: 'Use published .netapp packages' },
       { name: '--notify', description: 'Desktop notification when the run finishes' },
-      { name: '--shuffle', description: 'Randomize test order to surface order-dependent bugs (seed is logged)' },
+      {
+        name: '--shuffle',
+        description: 'Randomize test order to surface order-dependent bugs (seed is logged)',
+      },
       { name: '--seed=', description: 'Replay a specific --shuffle order (e.g. --seed=12345)' },
     ],
   },
@@ -65,7 +80,10 @@ export const COMMANDS: CommandDef[] = [
     description: 'Rebuild Docker images and package all modules as .netapps',
     flags: [
       { name: '--save', description: 'Save Docker images to tarball after build' },
-      { name: '--skip-modules', description: 'Skip .netapp packaging (only rebuild Docker images)' },
+      {
+        name: '--skip-modules',
+        description: 'Skip .netapp packaging (only rebuild Docker images)',
+      },
     ],
   },
   {
@@ -109,7 +127,17 @@ export const COMMANDS: CommandDef[] = [
 
 export const UP_PRESETS = ['--caddy', '--full-stack', '--infrastructure'];
 
-export const RUN_FLAGS = ['--all', '--complete', '--ci-safe', '--all-modules', '--keep', '--reuse', '--live', '--published', '--notify'];
+export const RUN_FLAGS = [
+  '--all',
+  '--complete',
+  '--ci-safe',
+  '--all-modules',
+  '--keep',
+  '--reuse',
+  '--live',
+  '--published',
+  '--notify',
+];
 
 export const DOWN_FLAGS = ['--keep', '--all'];
 

package/src/cli/index.ts

@@ -19,19 +19,27 @@ import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, readdirSync, rmSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { parse as parseYaml } from 'yaml';
+import {
+  E2eBusyError,
+  acquireRunLock,
+  clearLock,
+  formatBusy,
+  lockStatus,
+  markKept,
+} from '../run-lock';
 import { runBuild } from './build';
-import { runScaffold } from './scaffold';
 import { generateBashCompletion, generateZshCompletion, getCompletions } from './completion';
 import { findAllModules, findModulesWithMatchingTest } from './module-discovery';
-import { acquireRunLock, clearLock, E2eBusyError, formatBusy, lockStatus, markKept } from '../run-lock';
+import { runScaffold } from './scaffold';
 
 const PKG_DIR = resolve(import.meta.dir, '../..');
 const BIN_DIR = join(PKG_DIR, 'bin');
 
-
 function readManifestTestsDir(manifestPath: string): string | undefined {
   try {
-    const parsed = parseYaml(readFileSync(manifestPath, 'utf-8')) as { e2e?: { tests_dir?: string } };
+    const parsed = parseYaml(readFileSync(manifestPath, 'utf-8')) as {
+      e2e?: { tests_dir?: string };
+    };
     return parsed?.e2e?.tests_dir;
   } catch {
     return undefined;
@@ -53,6 +61,12 @@ function detectTestDir(): { stateDir: string; testsPath: string } {
     }
   }
   if (existsSync(join(cwd, 'tests'))) return { stateDir: cwd, testsPath: join(cwd, 'tests') };
+  // The repo's own top-level suite lives at e2e/tests/, which is what `list`
+  // enumerates. Without this, `cele2e list` shows a test that `cele2e run
+  // <name>` then cannot find — the run/list disagreement in #412.
+  if (existsSync(join(cwd, 'e2e', 'tests'))) {
+    return { stateDir: join(cwd, 'e2e'), testsPath: join(cwd, 'e2e', 'tests') };
+  }
   return { stateDir: cwd, testsPath: join(cwd, 'tests') };
 }
 
@@ -90,14 +104,26 @@ function discoverSuiteTests(suiteRoot: string): { name: string; file: string; gr
       ? resolve(moduleDir, readManifestTestsDir(join(moduleDir, 'manifest.yml')) ?? 'e2e')
       : tp;
     if (!existsSync(testsDir)) continue;
-    for (const f of readdirSync(testsDir).filter((f) => f.endsWith('.test.ts')).sort()) {
-      out.push({ name: f.replace(/\.test\.ts$/, ''), file: join(testsDir, f), group: basename(moduleDir) });
+    for (const f of readdirSync(testsDir)
+      .filter((f) => f.endsWith('.test.ts'))
+      .sort()) {
+      out.push({
+        name: f.replace(/\.test\.ts$/, ''),
+        file: join(testsDir, f),
+        group: basename(moduleDir),
+      });
     }
   }
   const topLevel = join(suiteRoot, 'e2e', 'tests');
   if (existsSync(topLevel)) {
-    for (const f of readdirSync(topLevel).filter((f) => f.endsWith('.test.ts')).sort()) {
-      out.push({ name: f.replace(/\.test\.ts$/, ''), file: join(topLevel, f), group: '(top-level)' });
+    for (const f of readdirSync(topLevel)
+      .filter((f) => f.endsWith('.test.ts'))
+      .sort()) {
+      out.push({
+        name: f.replace(/\.test\.ts$/, ''),
+        file: join(topLevel, f),
+        group: '(top-level)',
+      });
     }
   }
   return out;
@@ -200,9 +226,10 @@ switch (command) {
       args.includes('--complete') ||
       args.includes('--ci-safe')
     ) {
-      // --complete and --ci-safe both run the full discovery (every module +
-      // the repo's top-level e2e/tests/). --ci-safe additionally has the runner
-      // skip tests marked `cele2e-ci-unsafe`. --all-modules stays modules-only.
+      // --all / --complete / --ci-safe all run the full discovery (every module +
+      // the repo's top-level e2e/tests/). Quarantined (`cele2e-ci-unsafe`) tests
+      // are skipped by default; only --complete opts back into them (the runner
+      // sees the flag — it's kept below). --all-modules stays modules-only.
       const wantTopLevel =
         args.includes('--all') || args.includes('--complete') || args.includes('--ci-safe');
       const suiteRoot = resolveSuiteRoot();
@@ -222,9 +249,9 @@ switch (command) {
       }
       runScript(
         'e2e-run',
-        // Strip the discovery aliases; KEEP --ci-safe so the runner applies the
-        // `cele2e-ci-unsafe` quarantine exclusion.
-        args.filter((a) => a !== '--all' && a !== '--all-modules' && a !== '--complete'),
+        // Strip the discovery-only aliases; KEEP --complete (the runner uses it to
+        // opt back into quarantined tests) and --ci-safe (harmless/no-op now).
+        args.filter((a) => a !== '--all' && a !== '--all-modules'),
         env,
       );
     }
@@ -236,10 +263,14 @@ switch (command) {
 
     if (modulePath) {
       const absModulePath = resolve(modulePath);
-      runScript('e2e-run', args.filter((a) => a !== modulePath), {
-        E2E_TEST_DIR: stateDir,
-        E2E_MODULE_DIR: absModulePath,
-      });
+      runScript(
+        'e2e-run',
+        args.filter((a) => a !== modulePath),
+        {
+          E2E_TEST_DIR: stateDir,
+          E2E_MODULE_DIR: absModulePath,
+        },
+      );
     }
 
     // If cwd is not a module, walk sibling modules so the user can invoke
@@ -261,7 +292,9 @@ switch (command) {
           for (const m of matches) {
             console.error(`  ${basename(m.moduleDir)}: ${m.matchedTests.join(', ')}`);
           }
-          console.error('\nDisambiguate by running from inside the module directory or passing its path.');
+          console.error(
+            '\nDisambiguate by running from inside the module directory or passing its path.',
+          );
           process.exit(1);
         }
       } else if (positionals.length === 0) {
@@ -364,7 +397,9 @@ switch (command) {
         console.log(`  Reuse:    cele2e run --reuse`);
         console.log(`  Tear down: cele2e down`);
         console.log('');
-      } catch { /* ignore parse errors */ }
+      } catch {
+        /* ignore parse errors */
+      }
     }
     runScript('e2e-status', args, projectName ? { CELILO_E2E_PROJECT: projectName } : undefined);
   }
@@ -380,7 +415,10 @@ switch (command) {
     // build-infra mutates the shared Docker images — serialize against runs.
     // Released via the lock's exit handler (runBuild may process.exit on failure).
     try {
-      acquireRunLock({ test: 'build-infra', runId: process.env.CELE2E_RUN_ID ?? crypto.randomUUID() });
+      acquireRunLock({
+        test: 'build-infra',
+        runId: process.env.CELE2E_RUN_ID ?? crypto.randomUUID(),
+      });
     } catch (err) {
       if (err instanceof E2eBusyError) {
         console.error(err.message);

package/src/container-manager.ts

@@ -922,7 +922,7 @@ export async function startNetwork(config: NetworkConfig): Promise<NetworkHandle
   if (config.managementVariant !== 'vanilla') {
     assertCliVersion(projectName, composeDir);
     console.log('[progress:start] initializing celilo | celilo initialized');
-    // Honest harness (v2/NETWORK_CONFIG_TO_FIREWALL.md): seed ONLY the
+    // Honest harness (openspec/specs/progressive-zone-disclosure/spec.md): seed ONLY the
     // `internal` zone — the network the management box is genuinely on —
     // plus DNS. dmz/app/secure are NOT pre-seeded; they come into being
     // when a test deploys the firewall (net.deployFirewall()), exactly as
@@ -935,7 +935,11 @@ export async function startNetwork(config: NetworkConfig): Promise<NetworkHandle
       `celilo system init --accept-defaults \
         network.internal.subnet=${ZONE_SUBNETS.internal} \
         network.internal.gateway=${ZONE_GATEWAYS.internal} \
-        dns.primary=100.100.0.1 \
+        ${
+          config.managementZone === 'secure-mgmt'
+            ? 'network.secure-mgmt.subnet=10.0.120.0/24 network.secure-mgmt.gateway=10.0.120.1 '
+            : ''
+        }dns.primary=100.100.0.1 \
         dns.fallback=1.0.0.1,8.8.8.8`,
     );
     if (initResult.exitCode !== 0) {

package/src/docker-compose-generator.ts

@@ -79,6 +79,8 @@ function baseService(opts: {
   tmpfs?: string[];
   privileged?: boolean;
   dns?: string[];
+  /** Host devices to expose, e.g. `/dev/net/tun` for a userspace WireGuard tunnel. */
+  devices?: string[];
 }) {
   // Auto-assign an image tag from the Dockerfile name so Docker can
   // skip builds when pre-built images exist.
@@ -109,6 +111,16 @@ export const SHARED_NETWORKS = {
  * Default topology: fw-isp (greenwave) + fw-main (iptables)
  * Two-layer NAT: internet → fw-isp → fw-main → target
  */
+/**
+ * celilo's own control-plane network, used only when `managementZone` is
+ * 'secure-mgmt'. Deliberately NOT one of the segmented data-plane tiers: it is
+ * where celilo-mgr itself lives, mirroring the production topology the suite
+ * previously could not express.
+ */
+const SECURE_MGMT_SUBNET = '10.0.120.0/24';
+const SECURE_MGMT_GATEWAY = '10.0.120.1';
+const SECURE_MGMT_MANAGEMENT_IP = '10.0.120.100';
+
 function defaultTopologyServices(): Record<string, unknown> {
   return {
     'fw-main': baseService({
@@ -120,6 +132,10 @@ function defaultTopologyServices(): Record<string, unknown> {
         secure: { ipv4_address: '10.0.30.1' },
       },
       cap_add: ['NET_ADMIN', 'SYS_ADMIN'],
+      // A firewall may also terminate a VPN (the admin tunnel the `wireguard`
+      // module owns). wireguard-go needs the tun device; the kernel module is
+      // deliberately not relied on — see Dockerfile.firewall.
+      devices: ['/dev/net/tun'],
       sysctls: ROUTER_SYSCTLS,
       volumes: ['ssh-keys:/ssh-keys:ro'],
     }),
@@ -130,6 +146,10 @@ function defaultTopologyServices(): Record<string, unknown> {
         'isp-external': { ipv4_address: '100.100.0.100' },
       },
       cap_add: ['NET_ADMIN', 'SYS_ADMIN'],
+      // A firewall may also terminate a VPN (the admin tunnel the `wireguard`
+      // module owns). wireguard-go needs the tun device; the kernel module is
+      // deliberately not relied on — see Dockerfile.firewall.
+      devices: ['/dev/net/tun'],
       sysctls: ROUTER_SYSCTLS,
       volumes: ['ssh-keys:/ssh-keys:ro'],
     }),
@@ -153,6 +173,10 @@ function directInternetTopologyServices(): Record<string, unknown> {
         'isp-external': { ipv4_address: '100.100.0.100' },
       },
       cap_add: ['NET_ADMIN', 'SYS_ADMIN'],
+      // A firewall may also terminate a VPN (the admin tunnel the `wireguard`
+      // module owns). wireguard-go needs the tun device; the kernel module is
+      // deliberately not relied on — see Dockerfile.firewall.
+      devices: ['/dev/net/tun'],
       sysctls: ROUTER_SYSCTLS,
       volumes: ['ssh-keys:/ssh-keys:ro'],
     }),
@@ -232,6 +256,7 @@ export function generateSharedInfraYaml(): string {
       './config/dns/celilo.computer.zone:/seed/celilo.computer.zone:ro',
       './config/dns/example.net.zone:/seed/example.net.zone:ro',
       './config/dns/park-your-domain.com.zone:/seed/park-your-domain.com.zone:ro',
+      './config/dns/tangohost.com.zone:/seed/tangohost.com.zone:ro',
     ],
   });
 
@@ -292,6 +317,17 @@ export function generateSharedInfraYaml(): string {
   // packages/e2e/scripts/pack-celilo-packages.ts (cli, capabilities,
   // cli-display, e2e, event-bus). Reachable at http://npm-registry.lab from
   // any container that uses the internal resolver.
+  // OFF-FLEET web host (external_web). A PUBLIC PEER on internet-external, not
+  // a fleet member and not behind the customer firewall: celilo reaches it by
+  // SSH egress the way it would reach any host on the real internet, and public
+  // DNS resolves tangohost.com straight to this address. It runs its own Apache
+  // and its own pre-installed TLS — celilo governs none of it.
+  services['cpanel-host'] = baseService({
+    build: { context: '.', dockerfile: 'docker/Dockerfile.cpanel-host-sim' },
+    networks: { 'internet-external': { ipv4_address: SIMULATOR_IPS.CPANEL_HOST } },
+    cap_add: ['NET_ADMIN'],
+  });
+
   services['npm-registry'] = baseService({
     build: { context: '.', dockerfile: 'docker/Dockerfile.npm-registry-sim' },
     networks: { 'internet-external': { ipv4_address: SIMULATOR_IPS.NPM_REGISTRY } },
@@ -337,11 +373,17 @@ export function generateSharedInfraYaml(): string {
  * Creates its own internal, dmz, app, secure networks.
  */
 export function generateTestComposeYaml(config: NetworkConfig, celiloRoot?: string): string {
+  const mgmtOnOwnNetwork = config.managementZone === 'secure-mgmt';
   const networks: Record<string, unknown> = {
     internal: networkDef('192.168.0.0/24', '192.168.0.250'),
     dmz: networkDef('10.0.10.0/24', '10.0.10.250'),
     app: networkDef('10.0.20.0/24', '10.0.20.250'),
     secure: networkDef('10.0.30.0/24', '10.0.30.250'),
+    // Only when celilo-mgr lives off the internal LAN — keeps the default
+    // topology's generated compose byte-identical for every existing test.
+    ...(mgmtOnOwnNetwork
+      ? { 'secure-mgmt': networkDef(SECURE_MGMT_SUBNET, '10.0.120.250') }
+      : {}),
     'isp-external': networkDef('100.100.0.0/24', '100.100.0.250'),
     // internet-external is owned by shared infra; real-internet is per-test
     // (it just bridges fw-ext ↔ comcast-resolver, no shared service uses it).
@@ -392,11 +434,15 @@ export function generateTestComposeYaml(config: NetworkConfig, celiloRoot?: stri
   // first. container-manager's celilo-init + routing-verify target the
   // `management` container by name, so `celilo-mgr-2` comes up fresh and
   // un-init'd — the empty target restore needs.
-  const emitManagement = (variant: 'default' | 'vanilla' | undefined, ip: string) =>
+  const emitManagement = (
+    variant: 'default' | 'vanilla' | undefined,
+    ip: string,
+    zone: 'internal' | 'secure-mgmt' = 'internal',
+  ) =>
     baseService({
       image:
         variant === 'vanilla' ? 'celilo-e2e/management:vanilla' : 'celilo-e2e/management:latest',
-      networks: { internal: { ipv4_address: ip } },
+      networks: { [zone]: { ipv4_address: ip } },
       cap_add: ['NET_ADMIN'],
       // ISS-0157: `module import`'s `bun install` hard-links packages from the
       // bun cache into node_modules, which on overlayfs forces a copy-up + fsync
@@ -416,12 +462,17 @@ export function generateTestComposeYaml(config: NetworkConfig, celiloRoot?: stri
       ],
       environment: {
         DDNS_ENDPOINT: `http://${SIMULATOR_IPS.NAMECHEAP_DNS}:8080/update`,
-        DEFAULT_GATEWAY: managementDefaultGw,
+        // On its own control-plane network the only router in reach is fw-main's
+        // leg there — both for the default route and for the segmented zones.
+        DEFAULT_GATEWAY: zone === 'secure-mgmt' ? SECURE_MGMT_GATEWAY : managementDefaultGw,
+        ...(zone === 'secure-mgmt' ? { FW_MAIN_HOP: SECURE_MGMT_GATEWAY } : {}),
         CELILO_REGISTRY_URL: 'http://e2e-registry.lab',
       },
     });
 
-  services.management = emitManagement(config.managementVariant, '192.168.0.100');
+  services.management = mgmtOnOwnNetwork
+    ? emitManagement(config.managementVariant, SECURE_MGMT_MANAGEMENT_IP, 'secure-mgmt')
+    : emitManagement(config.managementVariant, '192.168.0.100');
 
   if (config.secondaryManagementVariant) {
     services['celilo-mgr-2'] = emitManagement(config.secondaryManagementVariant, '192.168.0.101');
@@ -451,6 +502,17 @@ export function generateTestComposeYaml(config: NetworkConfig, celiloRoot?: stri
   const topologyFn = TOPOLOGY_SERVICES[config.topology] || TOPOLOGY_SERVICES.default;
   Object.assign(services, topologyFn());
 
+  // Give fw-main a leg on the control-plane network when celilo-mgr lives there,
+  // so the management box is routed like any other segmented network rather than
+  // being stranded. Applied as a post-step so the default topology's generated
+  // compose is untouched.
+  if (mgmtOnOwnNetwork) {
+    const fwMain = services['fw-main'] as { networks?: Record<string, unknown> } | undefined;
+    if (fwMain?.networks) {
+      fwMain.networks['secure-mgmt'] = { ipv4_address: SECURE_MGMT_GATEWAY };
+    }
+  }
+
   // --- Routing infrastructure (bridges per-test to shared infra) ---
   services['fw-ext'] = baseService({
     build: { context: '.', dockerfile: 'docker/Dockerfile.router' },
@@ -518,6 +580,44 @@ export function generateTestComposeYaml(config: NetworkConfig, celiloRoot?: stri
     });
   }
 
+  // --- Optional real signal-cli daemon ---
+  // On `internal`, matching the signal module's declared zone — it is a local
+  // service celilo talks to, not an internet-facing one, so it does not belong
+  // on internet-external. Unlinked: the JSON-RPC surface needs no account.
+  if (config.signalCli) {
+    services['signal-cli'] = baseService({
+      build: { context: '.', dockerfile: 'docker/Dockerfile.signal-cli' },
+      networks: { internal: { ipv4_address: '192.168.0.90' } },
+      cap_add: ['NET_ADMIN'],
+    });
+  }
+
+  // --- Optional signal-cli release host ---
+  // On internet-external because that is what it models: an artifact the
+  // module downloads FROM the internet at deploy time.
+  if (config.signalRelease) {
+    services['signal-release'] = baseService({
+      build: { context: '.', dockerfile: 'docker/Dockerfile.signal-release' },
+      networks: { 'internet-external': { ipv4_address: SIMULATOR_IPS.SIGNAL_RELEASE } },
+      cap_add: ['NET_ADMIN'],
+    });
+  }
+
+  // --- Optional signal-cli simulator ---
+  // Same network placement as the real daemon so a test can swap one for the
+  // other without touching the module's configured endpoint.
+  if (config.signalSim) {
+    services['signal-sim'] = baseService({
+      build: { context: '.', dockerfile: 'docker/Dockerfile.signal-sim' },
+      networks: { internal: { ipv4_address: '192.168.0.91' } },
+      cap_add: ['NET_ADMIN'],
+      environment: {
+        SIGNAL_ACCOUNT: '+15551234567',
+        SIGNAL_KNOWN_RECIPIENTS: '+15550001,+15550002',
+      },
+    });
+  }
+
   // --- Observer vantages (passive spies; ISS-0117) ---
   // Each is the SAME image at a different network location with a routing profile that
   // mirrors a real device there — that routing profile is what makes it a faithful seat
@@ -528,6 +628,9 @@ export function generateTestComposeYaml(config: NetworkConfig, celiloRoot?: stri
       build: { context: '.', dockerfile: 'docker/Dockerfile.observer' },
       networks: { [p.network]: { ipv4_address: p.ip } },
       cap_add: ['NET_ADMIN'],
+      // A vantage may dial a VPN and probe from INSIDE the tunnel — the only way
+      // to assert VPN reach by real signal instead of by reading a rule string.
+      devices: ['/dev/net/tun'],
       environment: observerEnv(p),
     });
   }
@@ -660,6 +763,7 @@ export function generateComposeYaml(config: NetworkConfig, celiloRoot = '..'): s
       './config/dns/celilo.computer.zone:/seed/celilo.computer.zone:ro',
       './config/dns/example.net.zone:/seed/example.net.zone:ro',
       './config/dns/park-your-domain.com.zone:/seed/park-your-domain.com.zone:ro',
+      './config/dns/tangohost.com.zone:/seed/tangohost.com.zone:ro',
     ],
   });
 

package/src/network-builder.ts

@@ -39,6 +39,9 @@ export class NetworkBuilder {
     secureMachines: [],
     internalMachines: [],
     dhcpClient: false,
+    signalCli: false,
+    signalSim: false,
+    signalRelease: false,
     observers: [],
     domain: 'iamtheinternet.org',
     ddnsPassword: 'test123',
@@ -51,6 +54,17 @@ export class NetworkBuilder {
     return this;
   }
 
+  /**
+   * Place the celilo management container in a given zone. Defaults to
+   * `internal`; `secure-mgmt` gives celilo-mgr its own control-plane network
+   * (the production topology), so a test can exercise celilo reaching and
+   * resolving for a fleet from OFF the internal LAN.
+   */
+  managementZone(zone: 'internal' | 'secure-mgmt'): this {
+    this.config.managementZone = zone;
+    return this;
+  }
+
   /** Append `{name, ip, zone, ...extra}` for each entry to a zone's machine list. */
   private addMachines(
     target: MachineSpec[],
@@ -97,6 +111,44 @@ export class NetworkBuilder {
     return this;
   }
 
+  /**
+   * Add a real, UNLINKED signal-cli daemon on the internal network.
+   *
+   * For verifying the JSON-RPC contract against the actual binary. It cannot
+   * send to a phone (no account, and CDSI/SVR2 attestation makes a local
+   * Signal substitute impossible), but every endpoint, envelope and error
+   * shape celilo's client relies on is checkable without one.
+   */
+  withSignalCli(): this {
+    this.config.signalCli = true;
+    return this;
+  }
+
+  /**
+   * Add the signal-cli SIMULATOR on the internal network.
+   *
+   * Use this for anything that drives the delivery or ack loop: unlike the
+   * real daemon it exposes a control surface (`/_control/inbound`,
+   * `/_control/sent`, `/_control/unlink`) so a test can make a human "reply"
+   * and then assert on what celilo did about it.
+   */
+  withSignalSim(): this {
+    this.config.signalSim = true;
+    return this;
+  }
+
+  /**
+   * Serve the signal-cli release tarball from the simulated internet.
+   *
+   * Needed to DEPLOY the signal module: its ansible role downloads signal-cli
+   * at deploy time, and the e2e network is sealed. Point the module at it with
+   * `module config set signal release_base_url http://signal-release.lab`.
+   */
+  withSignalRelease(): this {
+    this.config.signalRelease = true;
+    return this;
+  }
+
   /**
    * Inject one or more observer vantages (ISS-0117) — passive spies carrying the probe
    * toolbox, each placed at its vantage's network location with a routing profile that