@specific.dev/spectest 0.26.0 → 0.28.0

package/dist/daemon.js

@@ -0,0 +1,4611 @@
+// Long-running HTTP daemon. Runs as a systemd unit on the VM host (not in
+// a container). Owns:
+//
+//   * Loading the user's `spectest/index.ts` and exposing the parsed
+//     `{ environment, tests? }` to the control plane.
+//   * Orchestrating Docker: image prep (pull/build), network + volumes,
+//     container start, ready probes — all by shelling out to the local
+//     `docker` CLI.
+//   * Running individual test cases on demand.
+//
+// The control plane handles VM lifecycle (create, snapshot, fork,
+// terminate) and the tarball uploads to `/workspace` and `/opt/spectest/app`.
+// Once those are in place the daemon does the rest.
+//
+// One sandbox = one daemon. Concurrency between tests is achieved by
+// forking the sandbox; inside a single daemon we never run two tests at
+// once — that keeps stdout capture and timeouts simple.
+import http from "node:http";
+import { execFile, spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { existsSync, promises as fs, readFileSync } from "node:fs";
+import net from "node:net";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard, proxy as makeProxyDecl, } from "./index.js";
+import { acquirePersistentBrowser } from "./browser.js";
+import { isMobileApp, openPersistentMobile } from "./mobile.js";
+import { openTerminal } from "./terminal.js";
+import { recordEnv, recordExec, recordFake, recordHttp, recordTerminal, recordWait, reserveEvent, recorderEventCount, recorderMarkChildren, recorderTruncate, startRecording, stopRecording, truncateUtf8, } from "./recorder.js";
+import { wrap, wrapResponse } from "./inspect.js";
+import { clearRecordSecrets, setRecordSecrets } from "./record-secrets.js";
+import { encodeReplayBundle, replayChunk } from "./replay-bundle.js";
+function namedServices(cfg) {
+    return Object.entries(cfg.services).map(([name, def]) => ({ name, ...def }));
+}
+const DEFAULT_PORT = 9876;
+const DEFAULT_TEST_TIMEOUT_MS = 60_000;
+const NETWORK_NAME = process.env.SPECTEST_NETWORK ?? "spectest-net";
+const WORKSPACE = process.env.SPECTEST_WORKSPACE ?? "/workspace";
+// Stable hostname every service container resolves to the host (the
+// `spectest-br0` gateway) — so apps that build or pull images at runtime
+// can point a builder at `spectest-host:5000` (the zot Docker Hub mirror)
+// or `spectest-host:1234` (the shared buildkitd) without hard-coding the
+// gateway IP. Injected into each container's /etc/hosts in runContainer.
+const SPECTEST_HOST_NAME = "spectest-host";
+// The host image-cache gateway, discovered once from the same
+// `registry-mirrors` entry the in-VM dockerd already uses (baked into the
+// local provider's golden /etc/docker/daemon.json). `null` when there's
+// no host cache, so nothing is injected.
+let _hostCacheGateway;
+function hostCacheGateway() {
+    if (_hostCacheGateway !== undefined)
+        return _hostCacheGateway;
+    try {
+        const cfg = JSON.parse(readFileSync("/etc/docker/daemon.json", "utf8"));
+        const first = cfg["registry-mirrors"]?.[0];
+        _hostCacheGateway = first ? new URL(first).hostname || null : null;
+    }
+    catch {
+        _hostCacheGateway = null;
+    }
+    return _hostCacheGateway;
+}
+const APP_DIR = process.env.SPECTEST_APP_DIR ?? "/opt/spectest/app";
+// Root CA baked into the base snapshot at base-snapshot build time
+// (see base.rs::BASE_SETUP_SH). Bind-mounted into every service
+// container so apps can verify HTTPS to the daemon's fakes, and
+// referenced when we layer it into each image's system trust store.
+const CA_PATH = process.env.SPECTEST_CA_PATH ?? "/etc/spectest/ca.crt";
+const CA_KEY_PATH = process.env.SPECTEST_CA_KEY_PATH ?? "/etc/spectest/ca.key";
+let loaded = null;
+function casesMetadata(suite) {
+    if (!suite)
+        return [];
+    return suite.tests.map((t) => ({
+        id: t.id,
+        name: t.name,
+        dependsOn: t.dependsOn?.id,
+        timeoutMs: t.timeoutMs,
+    }));
+}
+// Display-only summary of the project's fakes for the control plane (folded
+// into the env config's `fakes`, surfaced on the run page). Fakes aren't part
+// of `project.environment`, so they ride alongside it as a separate field of
+// the /load response — just the routing surface, no handler/state/helpers.
+function fakesSummary(project) {
+    if (!project?.fakes)
+        return [];
+    return Object.entries(project.fakes).map(([name, def]) => ({
+        name,
+        hostnames: def.hostnames.map((h) => h.toLowerCase()),
+        port: def.port ?? DEFAULT_FAKE_PORT,
+    }));
+}
+function resolveEntry() {
+    const explicit = process.env.SPECTEST_PROJECT_ENTRY;
+    if (explicit && existsSync(explicit))
+        return explicit;
+    const dir = process.env.SPECTEST_PROJECT_DIR ?? path.join(APP_DIR, "spectest");
+    for (const name of ["index.ts", "index.mts", "index.mjs", "index.js"]) {
+        const p = path.join(dir, name);
+        if (existsSync(p))
+            return p;
+    }
+    throw new Error(`could not find project entry in ${dir} (looked for index.ts/.mts/.mjs/.js)`);
+}
+// Import the env entry (`spectest/index.ts`) and load everything that
+// defines the *environment* — services, fakes, project setup — but not the
+// test bodies (those live in `spectest/tests/**`; see `loadTests`). The
+// import URL is deliberately stable (no cache-busting query): test files
+// import this same module (`import { env } from "../index"`) and must resolve
+// to the SAME `env` instance, so their `env.test(...)` calls land in the
+// registry the default-exported Project reads back. Each daemon process
+// imports the entry at most once — an env change always takes the cold path
+// with a fresh daemon — so there's nothing to bust.
+async function loadEnv() {
+    const entry = resolveEntry();
+    const url = pathToFileURL(entry).href;
+    const mod = await import(url);
+    const candidate = (mod && typeof mod === "object" && "default" in mod ? mod.default : mod);
+    if (!candidate || !candidate.environment) {
+        throw new Error(`project entry ${entry} must default-export a Project (from env.project(...) where env = defineEnvironment(...))`);
+    }
+    loaded = { project: candidate, byId: new Map() };
+    rebuildCatalogue();
+    // Any cached convenience clients belong to the previous project; drop
+    // them so the next test rebuilds against the freshly loaded definitions.
+    HELPERS_CACHE.clear();
+    // Register fakes + service-tls proxies here; startIngress() during
+    // /bootstrap actually binds the listeners — this just parses + validates
+    // and tears down any prior runtime so a reload picks up edits.
+    buildIngress(candidate);
+    return candidate;
+}
+// Import the test files under `spectest/tests/**` into the already-loaded
+// env, then refresh the catalogue. The split layout keeps test bodies out of
+// the warm-template cache key, so a test-only edit restores the cached env
+// and lands here to pick up the new tests. A no-op for the legacy single-file
+// layout (no `tests/` dir; the suite is already on the default export).
+//
+// Crucially this is only ever called AFTER the warm-template snapshot is
+// captured (cold path) or against a freshly restored VM (warm path), so each
+// test file is imported for the first time in that daemon process — no
+// cache-busting needed and no stale ESM module to fight.
+async function loadTests() {
+    requireLoaded();
+    const dir = path.join(path.dirname(resolveEntry()), "tests");
+    if (existsSync(dir)) {
+        for (const file of await collectTestFiles(dir)) {
+            await import(pathToFileURL(file).href);
+        }
+    }
+    rebuildCatalogue();
+    // The test set may have changed; drop cached helpers so the next test
+    // rebuilds cleanly.
+    HELPERS_CACHE.clear();
+}
+// (Re)build the id→TestCase index from whatever the loaded project currently
+// exposes as its suite: the lazy registry getter for split layouts, or the
+// frozen explicit suite for inline ones.
+function rebuildCatalogue() {
+    const l = requireLoaded();
+    const byId = new Map();
+    if (l.project.tests) {
+        for (const t of l.project.tests.tests)
+            byId.set(t.id, t);
+    }
+    l.byId = byId;
+}
+// Recursively collect importable test modules under `spectest/tests/`, sorted
+// for deterministic import order. Skips declaration files and dependency dirs.
+async function collectTestFiles(dir) {
+    const out = [];
+    const walk = async (d) => {
+        const entries = await fs.readdir(d, { withFileTypes: true });
+        for (const e of entries) {
+            const full = path.join(d, e.name);
+            if (e.isDirectory()) {
+                if (e.name === "node_modules" || e.name === ".spectest")
+                    continue;
+                await walk(full);
+            }
+            else if (e.isFile() &&
+                /\.(ts|mts|cts|js|mjs|cjs)$/.test(e.name) &&
+                !e.name.endsWith(".d.ts")) {
+                out.push(full);
+            }
+        }
+    };
+    await walk(dir);
+    out.sort();
+    return out;
+}
+function requireLoaded() {
+    if (!loaded) {
+        throw new Error("no project loaded; call POST /load first");
+    }
+    return loaded;
+}
+function shx(file, args, timeoutMs, env) {
+    return new Promise((resolve) => {
+        let done = false;
+        const child = execFile(file, args, { maxBuffer: 64 * 1024 * 1024, env: env ? { ...process.env, ...env } : process.env }, (err, stdout, stderr) => {
+            if (done)
+                return;
+            done = true;
+            const code = err && typeof err.code === "number"
+                ? Number(err.code)
+                : err
+                    ? 1
+                    : 0;
+            resolve({ stdout: String(stdout), stderr: String(stderr), code });
+        });
+        if (timeoutMs && timeoutMs > 0) {
+            setTimeout(() => {
+                if (!done) {
+                    done = true;
+                    try {
+                        child.kill("SIGKILL");
+                    }
+                    catch {
+                        /* already exited */
+                    }
+                    resolve({ stdout: "", stderr: `timeout after ${timeoutMs}ms`, code: 124 });
+                }
+            }, timeoutMs);
+        }
+    });
+}
+function docker(args, timeoutMs, env) {
+    return shx("docker", args, timeoutMs, env);
+}
+/**
+ * Like `shx` but invokes `onLine` for each line of combined stdout/stderr
+ * as it streams in, so callers can surface live progress (docker build
+ * steps, image pull layers) into bootstrap progress. Still resolves with
+ * the full captured output + exit code, so existing error handling and
+ * post-hoc parsing (`summarizeBuildKit`) are unchanged.
+ */
+function shxStream(file, args, timeoutMs, env, onLine) {
+    return new Promise((resolve) => {
+        const child = spawn(file, args, {
+            env: env ? { ...process.env, ...env } : process.env,
+        });
+        let stdout = "";
+        let stderr = "";
+        let buf = "";
+        let done = false;
+        const feed = (chunk) => {
+            buf += chunk;
+            let nl;
+            while ((nl = buf.indexOf("\n")) >= 0) {
+                const line = buf.slice(0, nl).replace(/\r$/, "");
+                buf = buf.slice(nl + 1);
+                try {
+                    onLine(line);
+                }
+                catch {
+                    /* a progress callback must never break the build */
+                }
+            }
+        };
+        child.stdout?.on("data", (d) => {
+            const s = String(d);
+            stdout += s;
+            feed(s);
+        });
+        child.stderr?.on("data", (d) => {
+            const s = String(d);
+            stderr += s;
+            feed(s);
+        });
+        const finish = (code, extraStderr) => {
+            if (done)
+                return;
+            done = true;
+            resolve({ stdout, stderr: extraStderr ? stderr + extraStderr : stderr, code });
+        };
+        child.on("error", () => finish(1));
+        child.on("close", (code) => finish(code == null ? 1 : code));
+        if (timeoutMs && timeoutMs > 0) {
+            setTimeout(() => {
+                if (done)
+                    return;
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch {
+                    /* already exited */
+                }
+                finish(124, `\ntimeout after ${timeoutMs}ms`);
+            }, timeoutMs);
+        }
+    });
+}
+// ── Boot log ─────────────────────────────────────────────────────────────
+// Everything the daemon logs while bringing the environment up, including
+// `console.log` from service `setup` hooks and project `setup`. Those used
+// to reach only the VM's journal, so on a *successful* boot they were
+// invisible — the one case where a long bootstrap most needs explaining.
+// Kept in daemon memory (so it rides snapshots like everything else) and
+// served by GET /boot-log; capped so a chatty setup can't grow unbounded.
+const BOOT_LOG_MAX_BYTES = 512 * 1024;
+const BOOT_LOG = {
+    lines: [],
+    bytes: 0,
+    dropped: 0,
+};
+/** A {@link LineSink} that appends to the capped boot log. */
+const BOOT_LOG_SINK = {
+    push(line) {
+        BOOT_LOG.lines.push(line);
+        BOOT_LOG.bytes += line.length;
+        // Drop from the front: the tail is what explains where a boot is now.
+        while (BOOT_LOG.bytes > BOOT_LOG_MAX_BYTES && BOOT_LOG.lines.length > 1) {
+            const gone = BOOT_LOG.lines.shift();
+            BOOT_LOG.bytes -= gone.length;
+            BOOT_LOG.dropped += 1;
+        }
+    },
+};
+function bootLogText() {
+    const head = BOOT_LOG.dropped > 0
+        ? `[spectest: ${BOOT_LOG.dropped} earlier line(s) dropped — boot log capped at ${BOOT_LOG_MAX_BYTES} bytes]\n`
+        : "";
+    return head + BOOT_LOG.lines.join("");
+}
+let BOOTSTRAP_PROGRESS = null;
+function progressInit(services) {
+    BOOTSTRAP_PROGRESS = {
+        phase: "Preparing images",
+        services: services.map((s) => ({
+            name: s.name,
+            kind: s.image.type === "registry" ? "pull" : "build",
+            status: "pending",
+        })),
+        startedAt: Date.now(),
+        updatedAt: Date.now(),
+        done: false,
+    };
+}
+function progressPhase(phase) {
+    if (!BOOTSTRAP_PROGRESS)
+        return;
+    BOOTSTRAP_PROGRESS.phase = phase;
+    BOOTSTRAP_PROGRESS.updatedAt = Date.now();
+}
+function progressService(name, patch) {
+    if (!BOOTSTRAP_PROGRESS)
+        return;
+    const svc = BOOTSTRAP_PROGRESS.services.find((s) => s.name === name);
+    if (!svc)
+        return;
+    Object.assign(svc, patch);
+    BOOTSTRAP_PROGRESS.updatedAt = Date.now();
+}
+function progressDone() {
+    if (!BOOTSTRAP_PROGRESS)
+        return;
+    BOOTSTRAP_PROGRESS.phase = "Ready";
+    BOOTSTRAP_PROGRESS.done = true;
+    BOOTSTRAP_PROGRESS.updatedAt = Date.now();
+}
+// BuildKit (docker buildx) gives per-step timing via `--progress=plain`,
+// parallel stages, and `RUN --mount=type=cache`. Detected once: where the
+// buildx plugin isn't installed (e.g. a Freestyle base without it) we fall
+// back to the legacy builder, which takes no `--progress` flag.
+let _buildxAvailable;
+async function hasBuildx() {
+    if (_buildxAvailable === undefined) {
+        const r = await docker(["buildx", "version"], 15_000);
+        _buildxAvailable = r.code === 0;
+    }
+    return _buildxAvailable;
+}
+// A single buildkitd runs on the host (see scripts/install-buildkitd.sh),
+// reachable from every VM at the bridge gateway. Building against it as a
+// `remote` buildx builder gives a persistent, shared layer/mount cache that
+// survives forks and warm-template misses — a fresh VM no longer rebuilds
+// from scratch. The build runs on the host (runc-isolated); `--load` pulls
+// the finished image back into the in-VM dockerd. Detected once; if the
+// builder can't be created or buildkitd is unreachable we fall back to the
+// in-VM builder, so a missing/dead buildkitd just means slower builds.
+const REMOTE_BUILDER_ADDR = process.env.SPECTEST_BUILDKIT_ADDR ?? "tcp://10.42.0.1:1234";
+const REMOTE_BUILDER_NAME = "spectest-remote";
+let _remoteBuilder;
+async function ensureRemoteBuilder() {
+    if (_remoteBuilder !== undefined)
+        return _remoteBuilder;
+    if (!(await hasBuildx())) {
+        _remoteBuilder = false;
+        return false;
+    }
+    // Idempotent: a repeat create with the same name errors ("existing
+    // instance"), which we treat as already-present.
+    const create = await docker(["buildx", "create", "--name", REMOTE_BUILDER_NAME, "--driver", "remote", REMOTE_BUILDER_ADDR], 30_000);
+    if (create.code !== 0 && !/existing instance|already exists/i.test(create.stderr)) {
+        _remoteBuilder = false;
+        return false;
+    }
+    // `inspect --bootstrap` actually dials buildkitd, so it's our reachability
+    // probe. If buildkitd is down this fails and we fall back.
+    const boot = await docker(["buildx", "inspect", "--bootstrap", REMOTE_BUILDER_NAME], 60_000);
+    _remoteBuilder = boot.code === 0;
+    if (!_remoteBuilder) {
+        // eslint-disable-next-line no-console
+        console.warn(`[build] remote buildkitd at ${REMOTE_BUILDER_ADDR} unreachable; using in-VM builder:\n${boot.stderr.trim()}`);
+    }
+    return _remoteBuilder;
+}
+// Parse `docker build --progress=plain` (BuildKit) output into per-step
+// timings, sorted slowest-first. Steps are correlated by their `#N` id:
+// the declaration line carries the command, the `DONE`/`CACHED` line the
+// duration. Best-effort — unparseable output yields an empty list.
+function summarizeBuildKit(out) {
+    const names = new Map();
+    const secs = new Map();
+    const cached = new Set();
+    for (const line of out.split("\n")) {
+        let m = line.match(/^#(\d+)\s+\[[^\]]*\]\s+(.+)$/);
+        if (m) {
+            const id = `#${m[1]}`;
+            if (!names.has(id))
+                names.set(id, m[2].trim().slice(0, 80));
+            continue;
+        }
+        m = line.match(/^#(\d+)\s+DONE\s+([\d.]+)s/);
+        if (m) {
+            secs.set(`#${m[1]}`, parseFloat(m[2]));
+            continue;
+        }
+        m = line.match(/^#(\d+)\s+CACHED/);
+        if (m) {
+            const id = `#${m[1]}`;
+            cached.add(id);
+            if (!secs.has(id))
+                secs.set(id, 0);
+        }
+    }
+    const steps = [];
+    for (const [id, name] of names) {
+        steps.push({ name, secs: secs.get(id) ?? 0, cached: cached.has(id) });
+    }
+    return steps.sort((a, b) => b.secs - a.secs);
+}
+// ────────────────────────────────────────────────────────────────────────
+// Bootstrap stages
+// ────────────────────────────────────────────────────────────────────────
+async function ensureNetwork() {
+    const inspect = await docker(["network", "inspect", NETWORK_NAME], 30_000);
+    if (inspect.code === 0)
+        return;
+    const create = await docker(["network", "create", NETWORK_NAME], 60_000);
+    if (create.code !== 0) {
+        throw new Error(`docker network create ${NETWORK_NAME} failed: ${create.stderr.trim() || create.stdout.trim()}`);
+    }
+}
+function sanitizeSegment(p) {
+    return p
+        .replace(/^\/+/, "")
+        .replace(/[^A-Za-z0-9_-]/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+function resolveHostPath(service, vol) {
+    if (vol.name) {
+        // Named shared volume: one backing dir per name, shared by every
+        // service that mounts the same name (storage-api ↔ imgproxy). Rooted
+        // in the per-env state tree (or the cache tree when cache-flagged),
+        // so teardown/fork semantics match ordinary volumes.
+        const root = vol.cache
+            ? ["/var/cache/spectest/volumes", "_shared"]
+            : [WORKSPACE, ".spectest", "volumes", "_shared"];
+        return path.join(...root, sanitizeSegment(vol.name));
+    }
+    if (vol.source && vol.source.startsWith("/"))
+        return vol.source;
+    // Cache volumes root OUTSIDE /workspace so the delta-restore teardown
+    // (rm -rf /workspace) keeps them — they hold only content-addressed
+    // accelerator data (see VolumeMount.cache), never env state.
+    const root = vol.cache
+        ? ["/var/cache/spectest/volumes", service]
+        : [WORKSPACE, ".spectest", "volumes", service];
+    if (vol.source) {
+        return path.join(...root, vol.source.replace(/^\/+/, ""));
+    }
+    return path.join(...root, sanitizeSegment(vol.target));
+}
+/// Where the daemon records every ABSOLUTE-source, non-cache volume dir it
+/// has created, one path per line. The delta-restore teardown wipes the
+/// listed dirs: they live outside /workspace (which the teardown removes
+/// wholesale) and outside /var/cache/spectest (deliberately kept), so
+/// without this manifest a `source: "/data/pg"` volume would carry the
+/// previous generation's data into a "fresh" environment. tmpfs-backed
+/// (/run) — survives snapshots like all guest memory, dies with the VM.
+const VOLUME_DIRS_MANIFEST = "/run/spectest-volume-dirs";
+const ABS_VOLUME_DIRS = new Set();
+async function recordAbsoluteVolumeDir(host) {
+    if (ABS_VOLUME_DIRS.has(host))
+        return;
+    ABS_VOLUME_DIRS.add(host);
+    await fs.writeFile(VOLUME_DIRS_MANIFEST, [...ABS_VOLUME_DIRS].join("\n") + "\n");
+}
+async function ensureVolumes(svc) {
+    const flags = [];
+    if (!svc.volumes || svc.volumes.length === 0)
+        return flags;
+    for (const vol of svc.volumes) {
+        // Boot services are validated in defineEnvironment; re-check here so
+        // runtime `startService` specs get the same contract.
+        if (vol.name && vol.source) {
+            throw new Error(`service "${svc.name}" volume for ${JSON.stringify(vol.target)} sets both \`name\` and \`source\``);
+        }
+        const host = resolveHostPath(svc.name, vol);
+        await fs.mkdir(host, { recursive: true });
+        if (vol.source?.startsWith("/") && !host.startsWith("/var/cache/spectest/")) {
+            await recordAbsoluteVolumeDir(host);
+        }
+        flags.push(`--volume=${host}:${vol.target}${vol.readOnly ? ":ro" : ""}`);
+    }
+    return flags;
+}
+// Materialize `svc.files` onto the VM host and return `--volume` flags
+// bind-mounting each into the container (read-only). Single-file bind
+// mounts mean the seeded config lands in place *before the container's
+// entrypoint runs* — the one injection point earlier than any setup
+// hook. Staging path mirrors ensureVolumes: a per-service dir derived
+// from the in-container path, so two files never collide and the
+// content is captured by snapshots like everything else under WORKSPACE.
+async function ensureFiles(svc) {
+    const flags = [];
+    if (!svc.files || svc.files.length === 0)
+        return flags;
+    const dir = path.join(WORKSPACE, ".spectest", "files", svc.name);
+    await fs.mkdir(dir, { recursive: true });
+    for (const f of svc.files) {
+        if (!f.path.startsWith("/")) {
+            throw new Error(`service "${svc.name}": file path ${JSON.stringify(f.path)} must be absolute`);
+        }
+        // `{{SPECTEST_SERVICE}}` expands to this service's name (its
+        // services-map key) so a component can author self-referential
+        // config without knowing the key the user will choose — e.g. k3s's
+        // registries.yaml keying on `<key>.internal:5000`.
+        const content = f.content.replaceAll("{{SPECTEST_SERVICE}}", svc.name);
+        const host = path.join(dir, sanitizeSegment(f.path));
+        await fs.writeFile(host, content);
+        if (f.mode)
+            await fs.chmod(host, parseInt(f.mode, 8));
+        flags.push(`--volume=${host}:${f.path}:ro`);
+    }
+    return flags;
+}
+/**
+ * Mint each `svc.certificates` entry from the in-VM root CA and return
+ * `--volume` flags bind-mounting the PEMs into the container, using the
+ * same pre-entrypoint injection point as {@link ensureFiles}.
+ *
+ * This is what lets a service terminate TLS *itself* with a certificate
+ * the environment already trusts — the `tls` field can't help there,
+ * since it terminates in the daemon and proxies plain HTTP to the
+ * upstream. Anything that routes by SNI, verifies a client cert, or
+ * speaks a protocol with its own TLS handshake needs the key material.
+ *
+ * Minted fresh on every bootstrap rather than cached: certs are cheap
+ * (~50 ms), and a stale one outliving a CA rotation would fail in a way
+ * that reads as a code bug.
+ */
+async function ensureCertificates(svc) {
+    const flags = [];
+    const certs = svc.certificates ?? [];
+    if (certs.length === 0)
+        return flags;
+    if (!existsSync(CA_PATH) || !existsSync(CA_KEY_PATH)) {
+        throw new Error(`service "${svc.name}": certificates require the in-VM root CA at ${CA_PATH}`);
+    }
+    const dir = path.join(WORKSPACE, ".spectest", "certs", svc.name);
+    await fs.mkdir(dir, { recursive: true });
+    for (const [i, c] of certs.entries()) {
+        for (const [label, p] of [
+            ["certPath", c.certPath],
+            ["keyPath", c.keyPath],
+            ...(c.caPath ? [["caPath", c.caPath]] : []),
+        ]) {
+            if (!p.startsWith("/")) {
+                throw new Error(`service "${svc.name}": certificate ${label} ${JSON.stringify(p)} must be absolute`);
+            }
+        }
+        const hostnames = c.hostnames.map((h) => h.replaceAll("{{SPECTEST_SERVICE}}", svc.name));
+        if (hostnames.length === 0) {
+            throw new Error(`service "${svc.name}": certificate entry ${i} lists no hostnames`);
+        }
+        const { cert, key } = await generateHostCert(`${svc.name}-${i}`, hostnames);
+        const certHost = path.join(dir, `${i}.crt`);
+        const keyHost = path.join(dir, `${i}.key`);
+        await fs.writeFile(certHost, cert);
+        await fs.writeFile(keyHost, key);
+        // The key's mode has to be set on the staged file: a bind mount
+        // carries the host inode's permissions straight through, and a
+        // server that checks (postgres, ssh) refuses a lax one.
+        if (c.mode)
+            await fs.chmod(keyHost, parseInt(c.mode, 8));
+        flags.push(`--volume=${certHost}:${c.certPath}:ro`);
+        flags.push(`--volume=${keyHost}:${c.keyPath}:ro`);
+        if (c.caPath)
+            flags.push(`--volume=${CA_PATH}:${c.caPath}:ro`);
+        console.log(`[bootstrap] ${svc.name}: minted certificate for ${hostnames.join(", ")}`);
+    }
+    return flags;
+}
+function imageTag(name) {
+    return `spectest/${name}:latest`;
+}
+const DEFAULT_DOCKERIGNORE = [
+    ".git",
+    ".spectest",
+    "spectest",
+    "node_modules",
+    "target",
+    "__pycache__",
+    ".venv",
+    ".env",
+    ".env.local",
+    ".env.*",
+    "dist",
+    "build",
+    ".next",
+    ".turbo",
+    ".DS_Store",
+];
+/** First line of the `.dockerignore` we generate ourselves, so a later
+ *  bootstrap can tell our file apart from one the project ships and never
+ *  mistakes its own output for user intent. */
+const GENERATED_DOCKERIGNORE_HEADER = "# spectest-generated — do not edit (your own .dockerignore is honoured verbatim)";
+/**
+ * The project's own `/workspace/.dockerignore`, read once per bootstrap
+ * before we write anything, or `null` when it ships none.
+ *
+ * This file is the project's statement about what belongs in a build
+ * context, and it is frequently the difference between a 30-second and a
+ * 30-minute build (the `**` + negations idiom keeps a monorepo's context
+ * down to the handful of files a Go build actually reads). We used to
+ * ignore it entirely *and* overwrite it — so a carefully minimised
+ * context silently became the whole repo, and the checked-out file was
+ * clobbered for any in-env tooling that read it too.
+ */
+let PROJECT_DOCKERIGNORE = null;
+async function readProjectDockerignore() {
+    try {
+        const text = await fs.readFile(path.join(WORKSPACE, ".dockerignore"), "utf8");
+        // Ours, from a previous bootstrap of this workspace — not the project's.
+        if (text.startsWith(GENERATED_DOCKERIGNORE_HEADER))
+            return null;
+        return text;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Ignore rules for one dockerfile build, in precedence order: our
+ * defaults, then the project's own `.dockerignore` verbatim, then that
+ * service's `exclude`.
+ *
+ * Order is load-bearing for the `**` + negations idiom — the project's
+ * `**` subsumes our defaults, its `!` lines re-include exactly what the
+ * build needs, and the per-service `exclude` still gets the last word.
+ */
+function serviceDockerignore(exclude) {
+    const parts = [DEFAULT_DOCKERIGNORE.join("\n")];
+    if (PROJECT_DOCKERIGNORE !== null) {
+        parts.push(`# --- from the project's .dockerignore ---\n${PROJECT_DOCKERIGNORE.trimEnd()}`);
+    }
+    if (exclude && exclude.length > 0) {
+        parts.push(`# --- from this service's exclude ---\n${exclude.join("\n")}`);
+    }
+    return parts.join("\n") + "\n";
+}
+function unionDockerignore(services) {
+    const seen = new Set(DEFAULT_DOCKERIGNORE);
+    const extras = [];
+    for (const s of services) {
+        if (s.image.type === "dockerfile" && s.image.exclude) {
+            for (const e of s.image.exclude) {
+                if (!seen.has(e)) {
+                    seen.add(e);
+                    extras.push(e);
+                }
+            }
+        }
+    }
+    return ([GENERATED_DOCKERIGNORE_HEADER, ...DEFAULT_DOCKERIGNORE, ...extras].join("\n") + "\n");
+}
+/// In-flight/finished dockerfile builds of this bootstrap, keyed by
+/// sha256(dockerfile content + exclude list). Services that share an
+/// identical image definition (e.g. an API server and a worker running the
+/// same codebase with different entrypoints) build ONCE; the others wait
+/// and `docker tag` the result. Cleared at every bootstrap() — the build
+/// CONTEXT (/workspace) is an input too, so dedup is only valid within one
+/// workspace generation (runtime services started mid-test share it).
+const BUILD_DEDUP = new Map();
+function buildContentKey(image) {
+    return new Bun.CryptoHasher("sha256")
+        .update(image.content)
+        .update("\0")
+        .update(JSON.stringify(image.exclude ?? []))
+        .digest("hex");
+}
+async function prepareServiceImage(svc, opts) {
+    const tag = imageTag(svc.name);
+    if (svc.image.type === "registry") {
+        const ref = svc.image.reference;
+        // Always pull — even when the (delta-restored) store already has the
+        // ref. With the layers present this costs ~a manifest round-trip per
+        // image ("Already exists" all the way down, through the zot mirror),
+        // off the bootstrap critical path; skipping it would freeze floating
+        // tags (`foo:latest`) at whatever the previous generation pulled, for
+        // as long as the delta chain lives — a silent semantic divergence
+        // from the cold build a delta restore must be equivalent to.
+        progressService(svc.name, { status: "pulling", detail: `pulling ${ref}` });
+        let layers = 0;
+        const pull = await shxStream("docker", ["pull", ref], 900_000, undefined, (line) => {
+            // `docker pull` (no TTY) prints one line per layer: "<id>: Pull
+            // complete" / "Already exists". Count them for a live layer tally.
+            if (/(?:Pull complete|Already exists)\s*$/.test(line)) {
+                layers++;
+                progressService(svc.name, { status: "pulling", detail: `${layers} layers` });
+            }
+        });
+        if (pull.code !== 0) {
+            progressService(svc.name, { status: "failed" });
+            throw new Error(`docker pull ${ref} failed: ${pull.stderr.trim() || pull.stdout.trim()}`);
+        }
+        const tagr = await docker(["tag", ref, tag], 30_000);
+        if (tagr.code !== 0) {
+            throw new Error(`docker tag ${ref} ${tag} failed: ${tagr.stderr.trim()}`);
+        }
+        await ensureCaTrustedImage(svc.name, tag);
+        return { tag };
+    }
+    // Dockerfile build. Within one bootstrap, identical definitions (shared
+    // codebase images) dedup to a single build. Only bootstrap opts in: the
+    // dedup key is dockerfile content + exclude, but the build CONTEXT
+    // (/workspace) is an input too — a runtime service started mid-test
+    // after setup/test code mutated /workspace must rebuild, not share a
+    // pre-mutation image.
+    const image = svc.image;
+    if (opts?.dedup) {
+        const key = buildContentKey(image);
+        const inflight = BUILD_DEDUP.get(key);
+        if (inflight) {
+            progressService(svc.name, { status: "building", detail: `sharing ${inflight.name}'s build` });
+            let first;
+            try {
+                first = await inflight.promise;
+            }
+            catch (err) {
+                progressService(svc.name, { status: "failed" });
+                throw err;
+            }
+            // first.tag is already CA-layered; tagging it covers this service too.
+            const tagr = await docker(["tag", first.tag, tag], 30_000);
+            if (tagr.code !== 0) {
+                throw new Error(`docker tag ${first.tag} ${tag} failed: ${tagr.stderr.trim()}`);
+            }
+            progressService(svc.name, { status: "prepared" });
+            return { tag, buildSteps: first.buildSteps };
+        }
+        const promise = buildServiceImage(svc.name, image, tag);
+        BUILD_DEDUP.set(key, { name: svc.name, promise });
+        try {
+            return await promise;
+        }
+        catch (err) {
+            // Let a sharer arriving later rebuild rather than inherit this
+            // build's failure forever.
+            BUILD_DEDUP.delete(key);
+            throw err;
+        }
+    }
+    return buildServiceImage(svc.name, image, tag);
+}
+async function buildServiceImage(name, image, tag) {
+    let buildSteps;
+    {
+        const dfDir = path.join(WORKSPACE, ".spectest", "services", name);
+        await fs.mkdir(dfDir, { recursive: true });
+        const dfPath = path.join(dfDir, "Dockerfile");
+        await fs.writeFile(dfPath, image.content);
+        // Per-service ignore: BuildKit resolves `<Dockerfile>.dockerignore`
+        // (next to the Dockerfile) in preference to the context root's
+        // `.dockerignore`, so this build sees the defaults, the project's own
+        // `.dockerignore`, and ITS OWN `exclude` — one service excluding
+        // `handhelds/**` no longer empties a sibling's build context. Verified
+        // on both the remote-buildx and DOCKER_BUILDKIT paths (client-side
+        // context filtering). The root `.dockerignore` written at bootstrap
+        // stays as the fallback for the legacy non-BuildKit builder, which
+        // predates per-Dockerfile ignores — and is written ONLY when the
+        // project ships none of its own (see readProjectDockerignore).
+        await fs.writeFile(`${dfPath}.dockerignore`, serviceDockerignore(image.exclude));
+        const useRemote = await ensureRemoteBuilder();
+        // Both the remote builder and a local buildx are BuildKit, so both emit
+        // per-step timing on stderr under `--progress=plain` (parsed below). Only
+        // the legacy in-VM builder takes no progress flag.
+        const useBuildKit = useRemote || (await hasBuildx());
+        const buildEnv = {};
+        let buildArgs;
+        if (useRemote) {
+            // Build on the host-side shared buildkitd (persistent cross-VM cache);
+            // `--load` brings the finished image back into the in-VM dockerd so
+            // runContainer can `docker run` it. The build context (WORKSPACE, minus
+            // .dockerignore) streams to buildkitd over the bridge.
+            buildArgs = [
+                "buildx", "build",
+                "--builder", REMOTE_BUILDER_NAME,
+                "--load",
+                "--progress=plain",
+                "-t", tag, "-f", dfPath, WORKSPACE,
+            ];
+        }
+        else if (useBuildKit) {
+            buildArgs = ["build", "-t", tag, "-f", dfPath, "--progress=plain", WORKSPACE];
+            buildEnv.DOCKER_BUILDKIT = "1";
+        }
+        else {
+            buildArgs = ["build", "-t", tag, "-f", dfPath, WORKSPACE];
+        }
+        progressService(name, { status: "building", detail: "starting build" });
+        const build = await shxStream("docker", buildArgs, 1_800_000, buildEnv, (line) => {
+            // BuildKit `--progress=plain` declares each step as
+            // `#N [<stage> M/N] <cmd>`; the legacy builder as `Step M/N : <cmd>`.
+            // Track the most-recent step as live detail.
+            let m = line.match(/^#\d+\s+\[([^\]]*)\]\s+(.+)$/);
+            if (m) {
+                const step = m[1].match(/\d+\/\d+/)?.[0];
+                const cmd = m[2].trim().slice(0, 60);
+                progressService(name, {
+                    status: "building",
+                    detail: step ? `step ${step} ${cmd}` : cmd,
+                });
+                return;
+            }
+            m = line.match(/^Step (\d+\/\d+)\s*:\s*(.+)$/);
+            if (m) {
+                progressService(name, {
+                    status: "building",
+                    detail: `step ${m[1]} ${m[2].trim().slice(0, 60)}`,
+                });
+            }
+        });
+        if (build.code !== 0) {
+            progressService(name, { status: "failed" });
+            throw new Error(`docker build for ${name} failed:\n${build.stderr.trim()}\n${build.stdout.trim()}`);
+        }
+        if (useBuildKit) {
+            // Keep only the slowest dozen steps ≥1s — enough to profile, small
+            // enough to ride back in the /bootstrap response and the journal.
+            buildSteps = summarizeBuildKit(build.stderr)
+                .filter((s) => s.secs >= 1)
+                .slice(0, 12);
+        }
+    }
+    // Layer the spectest CA into the image's system trust store so apps
+    // that read the system bundle (Go, Java, CLIs that don't honour the
+    // SSL_CERT_FILE env vars) accept HTTPS to fakes. Best-effort: images
+    // without `update-ca-certificates` / `update-ca-trust` (distroless,
+    // scratch) fall through to the env-var path that `runContainer` sets.
+    await ensureCaTrustedImage(name, tag);
+    return { tag, buildSteps };
+}
+/**
+ * Build a derivative image on top of `tag` that copies the spectest
+ * root CA into the system trust store. Tagged back as `tag`, so the
+ * rest of the orchestrator (runContainer, image cache) is oblivious.
+ * Failures are warned-and-ignored: the env-var injection in
+ * runContainer is the universal fallback, so apps that use it (most
+ * Node/Python/Ruby/AWS clients) still trust the CA even when the
+ * image's trust store can't be updated.
+ */
+async function ensureCaTrustedImage(serviceName, tag) {
+    if (!existsSync(CA_PATH)) {
+        // Daemon running outside a base-snapshot VM (dev/test). Nothing to
+        // layer; env vars also harmless (they point at a missing path, but
+        // most consumers ignore missing files).
+        return;
+    }
+    const ctxDir = path.join(WORKSPACE, ".spectest", "ca-trust", serviceName);
+    await fs.mkdir(ctxDir, { recursive: true });
+    await fs.copyFile(CA_PATH, path.join(ctxDir, "spectest-ca.crt"));
+    const dockerfile = `FROM ${tag}
+COPY spectest-ca.crt /usr/local/share/ca-certificates/spectest-ca.crt
+RUN if command -v update-ca-certificates >/dev/null 2>&1; then \\
+      update-ca-certificates; \\
+    elif command -v update-ca-trust >/dev/null 2>&1; then \\
+      cp /usr/local/share/ca-certificates/spectest-ca.crt /etc/pki/ca-trust/source/anchors/spectest-ca.crt && update-ca-trust extract; \\
+    else \\
+      echo "[spectest] no system CA trust tool in image; env-var trust only"; \\
+    fi
+`;
+    await fs.writeFile(path.join(ctxDir, "Dockerfile"), dockerfile);
+    const build = await docker(["build", "-t", tag, ctxDir], 300_000);
+    if (build.code !== 0) {
+        // eslint-disable-next-line no-console
+        console.warn(`[ca-trust] could not layer spectest CA into ${serviceName} (${tag}); env-var fallback only:\n${build.stderr.trim() || build.stdout.trim()}`);
+    }
+}
+async function runContainer(svc, tag, volumeFlags, 
+// Extra `--network-alias`es beyond the lowered `aliasesByService`. Used by
+// runtime `startService` (whose service isn't in LOWERED) to give the new
+// container docker-native multi-label resolution for its `hostnames`.
+extraAliases = []) {
+    // Idempotent: clean up any leftover container with the same name.
+    await docker(["rm", "-f", svc.name], 30_000);
+    const args = [
+        "run",
+        "-d",
+        "--restart=no",
+        `--name=${svc.name}`,
+        `--hostname=${svc.name}`,
+        `--network=${NETWORK_NAME}`,
+        // Every service is reachable at `<name>.internal` as well as its
+        // bare `<name>`. The fully-qualified form is what kubeconfigs and
+        // other tooling that expect a multi-label hostname should use; it's
+        // resolved both inside containers (Docker's embedded DNS) and on
+        // the VM host (spectest-resolver scans aliases).
+        `--network-alias=${svc.name}.internal`,
+    ];
+    // Extra peer aliases for this service — lowered from `hostnames` and any
+    // dnsName(h, { service }) into LOWERED.aliasesByService, plus any passed
+    // explicitly by a runtime startService (not present in LOWERED).
+    for (const h of [...(LOWERED.aliasesByService[svc.name] ?? []), ...extraAliases]) {
+        args.push(`--network-alias=${h}`);
+    }
+    // Bound TCP give-up time inside THIS container's network namespace.
+    // net.ipv4.tcp_retries2 is per-netns and a fresh netns resets to the kernel
+    // default (15 ≈ ~15 min of RTO backoff), so lowering it on the guest's init
+    // netns (BASE_SETUP_SH) does NOT reach containers — and the connections that
+    // actually wedge run here: buildkit/buildctl pulling base images + exporting
+    // cache, and the k3s container's containerd pulling images, all to the host
+    // zot over the VM↔host path. On a lost-retransmit (transient loss under
+    // concurrent forks) such a flow otherwise stalls a build/pull for minutes.
+    // Setting it per container resets a genuinely-stuck flow in ~tens of seconds
+    // so the client retries on a fresh connection; live connections keep getting
+    // ACKs and are unaffected. Safe because every service runs on the
+    // spectest-net bridge (own netns), never --network=host where net.* is denied.
+    args.push("--sysctl", "net.ipv4.tcp_retries2=6");
+    // Wire every ingress hostname (fakes, TLS-terminated proxies, and any
+    // dnsName(h, { ingress: true })) into the container's /etc/hosts so
+    // `fetch("http://api.stripe.com")` or `fetch("https://app.test")` from
+    // app code reaches the daemon's ingress listener via the bridge gateway.
+    // /etc/hosts beats Docker's embedded DNS (127.0.0.11), so we don't need
+    // to touch the container's resolver settings.
+    if (cachedGatewayIp) {
+        for (const h of LOWERED.ingressHosts) {
+            args.push(`--add-host=${h}:${cachedGatewayIp}`);
+        }
+    }
+    // Resolve `spectest-host` to the host image-cache gateway so apps can
+    // address the zot mirrors / shared buildkitd by name (see
+    // SPECTEST_HOST_NAME). Skipped where there's no host cache.
+    const hostGw = hostCacheGateway();
+    if (hostGw)
+        args.push(`--add-host=${SPECTEST_HOST_NAME}:${hostGw}`);
+    if (svc.workdir)
+        args.push(`--workdir=${svc.workdir}`);
+    // Trust the spectest root CA from inside the container. Bind-mount
+    // the cert + set the conventional env vars so language runtimes
+    // (Node, Python requests/httpx, AWS SDKs) pick it up without
+    // touching the image's system trust store. The per-image
+    // ensureCaTrustedImage layer also installs it into the system
+    // trust store; this env-var path is the belt-and-braces fallback
+    // for images where the layer step couldn't run (no
+    // update-ca-certificates).
+    args.push(`--volume=${CA_PATH}:${CA_PATH}:ro`);
+    args.push("-e", `NODE_EXTRA_CA_CERTS=${CA_PATH}`);
+    args.push("-e", `SSL_CERT_FILE=${CA_PATH}`);
+    args.push("-e", `REQUESTS_CA_BUNDLE=${CA_PATH}`);
+    args.push("-e", `AWS_CA_BUNDLE=${CA_PATH}`);
+    if (svc.env) {
+        for (const [k, v] of Object.entries(svc.env)) {
+            args.push("-e", `${k}=${v}`);
+        }
+    }
+    for (const flag of volumeFlags)
+        args.push(flag);
+    if (svc.privileged)
+        args.push("--privileged");
+    for (const p of svc.tmpfs ?? [])
+        args.push(`--tmpfs=${p}`);
+    if (svc.cgroupns)
+        args.push(`--cgroupns=${svc.cgroupns}`);
+    // `command` runs via sh -c, replacing the image entrypoint; `args` is a
+    // plain CMD override (`docker run <image> <args…>`) that keeps the
+    // entrypoint — what init-wrapped images (postgres) need for extra flags.
+    if (svc.command && svc.args?.length) {
+        throw new Error(`service ${svc.name}: \`command\` and \`args\` are mutually exclusive ` +
+            `(command replaces the entrypoint with /bin/sh -c; args keeps it)`);
+    }
+    if (svc.command)
+        args.push("--entrypoint=/bin/sh");
+    args.push(tag);
+    if (svc.command)
+        args.push("-c", svc.command);
+    else if (svc.args?.length)
+        args.push(...svc.args);
+    const r = await docker(args, 300_000);
+    if (r.code !== 0) {
+        throw new Error(`docker run ${svc.name} failed: ${r.stderr.trim() || r.stdout.trim()}`);
+    }
+}
+async function probeTcp(host, port) {
+    return new Promise((resolve) => {
+        const sock = net.createConnection({ host, port });
+        let settled = false;
+        const finish = (v) => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                sock.destroy();
+            }
+            catch {
+                /* ignore */
+            }
+            resolve(v);
+        };
+        sock.setTimeout(2000);
+        sock.once("connect", () => finish(true));
+        sock.once("error", () => finish(false));
+        sock.once("timeout", () => finish(false));
+    });
+}
+async function probeHttp(host, port, urlPath, headers, expectStatus) {
+    const ctrl = new AbortController();
+    const to = setTimeout(() => ctrl.abort(), 5000);
+    try {
+        const res = await fetch(`http://${host}:${port}${urlPath}`, {
+            signal: ctrl.signal,
+            headers,
+        });
+        return expectStatus !== undefined ? res.status === expectStatus : res.ok;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(to);
+    }
+}
+async function probeExec(name, command) {
+    const r = await docker(["exec", name, "sh", "-c", command], 10_000);
+    return r.code === 0;
+}
+async function waitForReady(svc) {
+    const check = svc.readyCheck;
+    if (!check)
+        return;
+    const timeoutSecs = check.timeoutSecs ?? 60;
+    const deadline = Date.now() + timeoutSecs * 1000;
+    // Ramped poll: a flat 500ms quantized every service's ready latency
+    // (and compounds down dependsOn chains). Fast early probes catch
+    // quick services; the ramp caps the polling load on slow ones. Exec
+    // probes keep a higher floor — each attempt spawns a docker exec.
+    const ramp = check.type === "exec" ? [250, 250, 400, 400, 500] : [50, 100, 150, 250, 400, 500];
+    let attempt = 0;
+    while (Date.now() < deadline) {
+        let ok = false;
+        if (check.type === "tcp") {
+            ok = await probeTcp(svc.name, check.port);
+        }
+        else if (check.type === "http") {
+            ok = await probeHttp(svc.name, check.port, check.path ?? "/", check.headers, check.expectStatus);
+        }
+        else {
+            ok = await probeExec(svc.name, check.command);
+        }
+        if (ok)
+            return;
+        const delay = ramp[Math.min(attempt, ramp.length - 1)];
+        attempt++;
+        await new Promise((r) => setTimeout(r, delay));
+    }
+    const logs = await docker(["logs", "--tail=200", svc.name], 30_000);
+    throw new Error(`service ${svc.name} not ready within ${timeoutSecs}s. Recent container logs:\n${logs.stdout}\n${logs.stderr}`);
+}
+/**
+ * Validate the `dependsOn` graph and return the name→service map used to
+ * walk it. Rejects unknown dependencies and cycles (the same two errors
+ * the old level scheduler raised) so the DAG runner can assume a clean
+ * graph.
+ */
+function validateServiceGraph(services) {
+    const byName = new Map(services.map((s) => [s.name, s]));
+    for (const s of services) {
+        for (const d of s.dependsOn ?? []) {
+            if (!byName.has(d)) {
+                throw new Error(`service ${s.name} depends on unknown service ${d}`);
+            }
+        }
+    }
+    // Cycle detection via DFS coloring (white=unseen, gray=on stack, black=done).
+    const WHITE = 0, GRAY = 1, BLACK = 2;
+    const color = new Map(services.map((s) => [s.name, WHITE]));
+    const visit = (name) => {
+        color.set(name, GRAY);
+        for (const d of byName.get(name).dependsOn ?? []) {
+            const c = color.get(d);
+            if (c === GRAY)
+                throw new Error("service dependency cycle");
+            if (c === WHITE)
+                visit(d);
+        }
+        color.set(name, BLACK);
+    };
+    for (const s of services)
+        if (color.get(s.name) === WHITE)
+            visit(s.name);
+    return byName;
+}
+/**
+ * Bring up every service as early as its own dependencies allow.
+ *
+ * Each service starts the instant all of its `dependsOn` services have
+ * finished `startOne` (run → readyCheck → setup) — not when its whole
+ * topological "level" has. Independent branches run fully concurrently;
+ * a slow probe on one service delays only its own transitive dependents,
+ * never an unrelated branch. `startOne(svc)`'s promise is memoized so each
+ * service runs exactly once even when several dependents share a dep, and
+ * a dependency failure propagates by rejecting every dependent's await.
+ */
+async function startServices(services, startOne) {
+    const byName = validateServiceGraph(services);
+    const started = new Map();
+    const start = (svc) => {
+        const existing = started.get(svc.name);
+        if (existing)
+            return existing;
+        const p = (async () => {
+            await Promise.all((svc.dependsOn ?? [])
+                .filter((d) => byName.has(d))
+                .map((d) => start(byName.get(d))));
+            await startOne(svc);
+        })();
+        started.set(svc.name, p);
+        return p;
+    };
+    await Promise.all(services.map(start));
+}
+// ────────────────────────────────────────────────────────────────────────
+// Ingress — in-daemon HTTP/HTTPS listeners that route by Host header.
+//
+// Two kinds of routes share the same listeners:
+//
+//   * Fakes — in-daemon mock APIs. Each fake declares `hostnames` and a
+//     `port` (default 80); the request hits the fake's handler with the
+//     fake's `state`. HTTPS always serves on 443 (SNI per hostname,
+//     leaf cert signed by the in-VM root CA).
+//
+//   * Service TLS — reverse-proxy fronts for user services. Each
+//     `services.<name>.tls` entry declares `{ hostname, port }`; the
+//     daemon binds the hostname on :80 AND :443 and proxies each
+//     request to `http://<service>:<port>` inside the docker network.
+//     WebSocket upgrades are bridged. The leaf cert is signed by the
+//     same root CA, so `ctx.browser()` and peer services trust it.
+//
+// Both listeners bind on 0.0.0.0 so containers reach them via the
+// bridge gateway IP (also written into /run/spectest-fakes.json for
+// spectest-resolver and injected as --add-host on every container).
+//
+// Per-fake `state` is plain JS memory and lives across snapshot/fork
+// along with the rest of the daemon — every fork sees its own copy.
+// ────────────────────────────────────────────────────────────────────────
+const FAKES_REGISTRY_PATH = process.env.SPECTEST_FAKES_REGISTRY ?? "/run/spectest-fakes.json";
+const DEFAULT_FAKE_PORT = 80;
+/** Fixed HTTPS port shared by every route (fakes + service-tls). */
+const INGRESS_HTTPS_PORT = 443;
+/** Fixed HTTP port always bound for service-tls (alongside any
+ * fakes whose `port` happens to be 80). */
+const INGRESS_HTTP_PORT = 80;
+/** All loaded fakes, keyed by stable name (the `fakes` map key). Holds the
+ *  in-daemon handler, forked state, and helpers — the parts intrinsic to a
+ *  fake. Their *networking* (certs, DNS, routes) comes from `LOWERED`. */
+const FAKES = new Map();
+/** Generic ingress derived from the loaded project (tls/hostnames/fakes/
+ *  component `provides`) by the SDK's `lowerIngress`. The daemon executes
+ *  this and never reads `svc.tls`/`svc.hostnames` itself. Rebuilt on /load. */
+let LOWERED = {
+    certificates: [],
+    proxies: [],
+    ingressHosts: [],
+    aliasesByService: {},
+    wildcards: [],
+};
+/** Running HTTP servers per port (Bun.Server). Rebuilt on /load. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const INGRESS_HTTP_SERVERS = new Map();
+/** Running HTTPS servers per port (currently always {INGRESS_HTTPS_PORT}). */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const INGRESS_HTTPS_SERVERS = new Map();
+/**
+ * Live per-port route tables, keyed by listen port (80 / 443 / fake ports).
+ * Each listener's `fetch` closure captures *this* Map object, so adding an
+ * entry takes effect immediately with no rebind — that's what lets a runtime
+ * `tls` (a `ctx.startService({ tls })`) bind a new ingress route after boot.
+ * Held at module scope so it's part of the live daemon process and forks
+ * with the snapshot, exactly like fake state / the names REGISTRY. Rebuilt on
+ * /load (cleared by {@link stopIngressServers}).
+ */
+const INGRESS_ROUTES_BY_PORT = new Map();
+/**
+ * The :443 SNI cert table: serverName → leaf. Unlike the route table, Bun's
+ * TLS config is fixed at `Bun.serve` time (reload won't add an SNI entry), so
+ * minting a cert for a *new* hostname requires rebinding the :443 listener
+ * (cheap, ~1ms — see {@link rebindHttpsListener}). A hostname already covered
+ * by an existing exact or wildcard cert needs no rebind, just a route entry.
+ */
+const HTTPS_CERT_BY_HOST = new Map();
+/**
+ * Tear down listener servers between /load calls so the new project's
+ * routes can rebind cleanly.
+ */
+function stopIngressServers() {
+    for (const [port, srv] of INGRESS_HTTP_SERVERS) {
+        try {
+            srv.stop?.();
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn(`[ingress] failed to stop http server on :${port}:`, err);
+        }
+    }
+    INGRESS_HTTP_SERVERS.clear();
+    for (const [port, srv] of INGRESS_HTTPS_SERVERS) {
+        try {
+            srv.stop?.();
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn(`[ingress] failed to stop https server on :${port}:`, err);
+        }
+    }
+    INGRESS_HTTPS_SERVERS.clear();
+    INGRESS_ROUTES_BY_PORT.clear();
+    HTTPS_CERT_BY_HOST.clear();
+}
+function buildIngress(project) {
+    stopIngressServers();
+    FAKES.clear();
+    // Lower the friendly surface (tls/hostnames/provides/fakes) into the
+    // generic decl set the daemon executes. The special-casing lives in the
+    // SDK's lowerIngress, not here.
+    LOWERED = lowerIngress(project);
+    if (!project.fakes)
+        return;
+    for (const [name, def] of Object.entries(project.fakes)) {
+        FAKES.set(name, {
+            def,
+            state: undefined, // built in startIngress after `state()` runs
+            hostnames: def.hostnames.map((h) => h.toLowerCase()),
+            port: def.port ?? DEFAULT_FAKE_PORT,
+        });
+    }
+}
+/**
+ * Generate a leaf cert + key for one ingress route (fake or service
+ * proxy), signed by the in-VM root CA at {CA_PATH}. SANs cover every
+ * hostname the route answers to, so a client connecting with TLS
+ * verifies cleanly regardless of which hostname it used. Shells out
+ * to `openssl req -x509 -CA ... -CAkey ...` (OpenSSL 3.0+; Debian
+ * bookworm ships 3.0.x).
+ *
+ * `label` is a short tag baked into the cert Subject CN and the temp
+ * file names — only used for diagnostics, not for TLS verification.
+ */
+async function generateHostCert(label, hostnames) {
+    const id = `spectest-host-${sanitizeSegment(label)}-${randomUUID().slice(0, 8)}`;
+    const keyPath = path.join("/tmp", `${id}.key`);
+    const crtPath = path.join("/tmp", `${id}.crt`);
+    const sans = hostnames.map((h) => `DNS:${h}`).join(",");
+    const args = [
+        "req",
+        "-newkey",
+        "rsa:2048",
+        "-nodes",
+        "-keyout",
+        keyPath,
+        "-out",
+        crtPath,
+        "-x509",
+        "-CA",
+        CA_PATH,
+        "-CAkey",
+        CA_KEY_PATH,
+        "-days",
+        "3650",
+        "-subj",
+        `/CN=spectest-${label}`,
+        "-addext",
+        `subjectAltName=${sans}`,
+        "-addext",
+        "basicConstraints=CA:FALSE",
+        "-addext",
+        "extendedKeyUsage=serverAuth",
+        "-addext",
+        "keyUsage=digitalSignature,keyEncipherment",
+    ];
+    const r = await shx("openssl", args, 30_000);
+    if (r.code !== 0) {
+        throw new Error(`openssl req for ${label} failed (rc=${r.code}): ${r.stderr.trim() || r.stdout.trim()}`);
+    }
+    try {
+        const [cert, key] = await Promise.all([
+            fs.readFile(crtPath, "utf8"),
+            fs.readFile(keyPath, "utf8"),
+        ]);
+        return { cert, key };
+    }
+    finally {
+        await Promise.all([
+            fs.unlink(keyPath).catch(() => { }),
+            fs.unlink(crtPath).catch(() => { }),
+        ]);
+    }
+}
+/** Resolve the spectest-net bridge gateway IP — the address containers
+ * use to reach the VM host. Asks dockerd via the docker CLI; cached for
+ * the daemon's life because the network is recreated only on reload. */
+let cachedGatewayIp = null;
+async function bridgeGatewayIp() {
+    if (cachedGatewayIp)
+        return cachedGatewayIp;
+    const out = await docker([
+        "network",
+        "inspect",
+        "--format",
+        "{{(index .IPAM.Config 0).Gateway}}",
+        NETWORK_NAME,
+    ], 10_000);
+    if (out.code !== 0) {
+        throw new Error(`docker network inspect ${NETWORK_NAME} failed (rc=${out.code}): ${out.stderr.trim()}`);
+    }
+    const ip = out.stdout.trim();
+    if (!ip)
+        throw new Error(`no gateway IP returned for network ${NETWORK_NAME}`);
+    cachedGatewayIp = ip;
+    return ip;
+}
+/**
+ * Pristine `fetch` captured at module load, before any test-scoped
+ * fetch wrapper can monkey-patch `globalThis.fetch`. The reverse-proxy
+ * uses this directly so its outbound HTTP calls aren't intercepted by
+ * the test recorder — they'd be (a) misattributed to the test's
+ * timeline, and (b) trip up the Response constructor because the
+ * recorder wraps `res.status` / `res.body` in inspectable proxies
+ * that don't pass through as primitives.
+ */
+const NATIVE_FETCH = globalThis.fetch.bind(globalThis);
+/** Hop-by-hop headers per RFC 7230 §6.1 — never forwarded by a proxy. */
+const HOP_BY_HOP_HEADERS = new Set([
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailers",
+    "transfer-encoding",
+    "upgrade",
+    "host",
+]);
+/**
+ * Is this a CORS preflight? A preflight is the browser's own probe (never
+ * app business logic): an `OPTIONS` carrying `Origin` +
+ * `Access-Control-Request-Method`. Plain `OPTIONS` calls (no `ACRM`) are real
+ * app requests and pass straight through to the upstream/fake.
+ */
+function isCorsPreflight(req) {
+    return (req.method === "OPTIONS" &&
+        req.headers.has("origin") &&
+        req.headers.has("access-control-request-method"));
+}
+/**
+ * Answer a CORS preflight at the ingress, permissively, reflecting exactly
+ * what the browser asked for.
+ *
+ * Why this belongs in the platform, not the app: inside the hermetic sandbox
+ * the app page's origin (e.g. `http://<svc>.internal:<port>`) and every host
+ * it fetches through this ingress (`https://api.example.com`) are *always*
+ * different origins, so any request with a non-safelisted header — which
+ * includes `Authorization`, and crucially `Cache-Control` / `Pragma` — is
+ * preflighted by the browser. If we forward the `OPTIONS` to the upstream, the
+ * request succeeds or fails on whether *that* app happens to enumerate the
+ * header in its `Access-Control-Allow-Headers`. Real apps list `Authorization`
+ * but almost never `Cache-Control`/`Pragma`, so a client that sends those (many
+ * HTTP libraries add `Cache-Control: no-cache` by default) fails the preflight
+ * with an instant "Failed to fetch" — even though the identical request works
+ * in production behind a permissive edge/gateway. Reflecting
+ * `Access-Control-Request-Headers` verbatim makes the ingress transparent to
+ * whatever header vocabulary the app under test uses.
+ */
+function corsPreflightResponse(req) {
+    const origin = req.headers.get("origin") ?? "*";
+    const reqHeaders = req.headers.get("access-control-request-headers");
+    const reqMethod = req.headers.get("access-control-request-method");
+    const headers = new Headers();
+    headers.set("access-control-allow-origin", origin);
+    // Echo the specific origin (not `*`) so credentialed requests are allowed;
+    // `Allow-Origin: *` + `Allow-Credentials: true` is a spec violation browsers
+    // reject.
+    headers.set("access-control-allow-credentials", "true");
+    headers.set("access-control-allow-methods", reqMethod && reqMethod.length > 0
+        ? reqMethod
+        : "GET,HEAD,PUT,PATCH,POST,DELETE,OPTIONS");
+    headers.set("access-control-allow-headers", reqHeaders && reqHeaders.length > 0 ? reqHeaders : "*");
+    headers.set("access-control-max-age", "600");
+    // The response varies by the reflected origin/headers — keep caches honest.
+    headers.append("vary", "Origin");
+    headers.append("vary", "Access-Control-Request-Headers");
+    return new Response(null, { status: 204, headers });
+}
+/**
+ * Make sure the browser sees an `Access-Control-Allow-Origin` it accepts on the
+ * *actual* cross-origin response. Only fills one in when the upstream/fake
+ * didn't set its own, so an app that manages CORS itself keeps full control;
+ * this just stops a missing header from turning an otherwise-fine 200 into a
+ * "Failed to fetch". No-op for same-origin requests (no `Origin`).
+ */
+function augmentCorsResponse(req, res) {
+    const origin = req.headers.get("origin");
+    if (!origin)
+        return res;
+    if (res.headers.has("access-control-allow-origin"))
+        return res;
+    try {
+        res.headers.set("access-control-allow-origin", origin);
+        res.headers.set("access-control-allow-credentials", "true");
+        res.headers.append("vary", "Origin");
+    }
+    catch {
+        // Some responses (e.g. a 101 upgrade stub) carry guarded/immutable
+        // headers — leave those untouched.
+    }
+    return res;
+}
+/**
+ * Bring ingress servers up: bind one Bun.serve per unique HTTP port
+ * (fakes' ports plus the always-on :80 for service proxies), plus a
+ * shared HTTPS :443 (SNI per hostname). Build each fake's initial state,
+ * then write the hostname→ip registry that spectest-resolver consults
+ * for DNS. Idempotent — calling twice rebuilds.
+ */
+async function startIngress() {
+    const hasIngress = FAKES.size > 0 ||
+        LOWERED.proxies.length > 0 ||
+        LOWERED.ingressHosts.length > 0 ||
+        LOWERED.wildcards.length > 0;
+    if (!hasIngress) {
+        // Make sure the resolver doesn't see stale entries from a prior project.
+        REGISTRY.hosts = {};
+        REGISTRY.wildcards = [];
+        await writeRegistry();
+        return;
+    }
+    const gw = await bridgeGatewayIp();
+    // Initialise per-fake state. Awaited sequentially — state factories
+    // are expected to be tiny constructors; the cost of serial init is
+    // dwarfed by the eventual snapshot.
+    for (const [name, fake] of FAKES) {
+        if (fake.def.state) {
+            try {
+                fake.state = await fake.def.state();
+            }
+            catch (err) {
+                throw new Error(`fake ${JSON.stringify(name)} state() factory threw: ${err.message}`);
+            }
+        }
+        else {
+            fake.state = {};
+        }
+    }
+    // Mint one leaf cert per `certificate` decl (SANs = its hostnames),
+    // signed by the in-VM root CA, and index it by hostname for SNI. Done
+    // before binding so the HTTPS listener has certs ready and a startup
+    // failure aborts /bootstrap cleanly.
+    const caPresent = existsSync(CA_PATH) && existsSync(CA_KEY_PATH);
+    if (caPresent) {
+        for (const group of LOWERED.certificates) {
+            if (group.hostnames.length === 0)
+                continue;
+            const leaf = await generateHostCert(group.hostnames[0], group.hostnames);
+            for (const h of group.hostnames)
+                HTTPS_CERT_BY_HOST.set(h, leaf);
+        }
+    }
+    else if (LOWERED.certificates.length > 0) {
+        // eslint-disable-next-line no-console
+        console.warn(`[ingress] root CA missing at ${CA_PATH}; skipping HTTPS bind (fakes/proxies will be HTTP-only)`);
+    }
+    const Bun = requireBun();
+    // Resolve every ingress hostname to its handler into the live per-port
+    // route tables (module scope, so runtime `tls` can extend them later).
+    // Fakes run an in-daemon handler on their declared port; proxies
+    // reverse-proxy to a service:port and bind :80 (HTTPS, if any, is :443).
+    const ensurePort = (port) => {
+        const m = INGRESS_ROUTES_BY_PORT.get(port) ?? new Map();
+        INGRESS_ROUTES_BY_PORT.set(port, m);
+        return m;
+    };
+    for (const fake of FAKES.values()) {
+        if (fake.port === INGRESS_HTTPS_PORT)
+            continue;
+        const routes = ensurePort(fake.port);
+        for (const h of fake.hostnames)
+            routes.set(h, { kind: "fake", fake });
+    }
+    if (LOWERED.proxies.length > 0) {
+        const routes = ensurePort(INGRESS_HTTP_PORT);
+        for (const p of LOWERED.proxies) {
+            routes.set(p.hostname, { kind: "proxy", service: p.service, port: p.port });
+        }
+    }
+    // The :443 route table mirrors every certificated hostname's handler.
+    if (HTTPS_CERT_BY_HOST.size > 0) {
+        const httpsRoutes = ensurePort(INGRESS_HTTPS_PORT);
+        for (const h of HTTPS_CERT_BY_HOST.keys()) {
+            for (const fake of FAKES.values()) {
+                if (fake.hostnames.includes(h))
+                    httpsRoutes.set(h, { kind: "fake", fake });
+            }
+            const proxy = LOWERED.proxies.find((p) => p.hostname === h);
+            if (proxy)
+                httpsRoutes.set(h, { kind: "proxy", service: proxy.service, port: proxy.port });
+        }
+    }
+    // ── HTTP listeners (one per non-443 port).
+    for (const [port, byHost] of INGRESS_ROUTES_BY_PORT) {
+        if (port === INGRESS_HTTPS_PORT)
+            continue;
+        INGRESS_HTTP_SERVERS.set(port, bindIngressServer(Bun, port, byHost, `port ${port}`));
+        // eslint-disable-next-line no-console
+        console.log(`[ingress] http :${port} for ${[...byHost.keys()].join(", ")}`);
+    }
+    // ── HTTPS listener on INGRESS_HTTPS_PORT: SNI per certificated hostname.
+    if (HTTPS_CERT_BY_HOST.size > 0)
+        rebindHttpsListener(Bun);
+    // Seed the resolver's names registry: ingress hostnames (fakes, TLS
+    // proxies, dnsName(→ingress)) → bridge gateway, plus ingress-targeted
+    // wildcards. Service-targeted wildcards wait for the post-container pass
+    // (their containers aren't up yet). Dynamic ctx.dnsName calls extend this.
+    await seedNamesRegistry({ servicesUp: false });
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function requireBun() {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const Bun = globalThis.Bun;
+    if (!Bun?.serve) {
+        throw new Error("ingress requires Bun.serve; the daemon must run under Bun (it does in-VM)");
+    }
+    return Bun;
+}
+/** Flatten {@link HTTPS_CERT_BY_HOST} into Bun's TLS-entry SNI array. */
+function tlsEntriesFromCerts() {
+    return [...HTTPS_CERT_BY_HOST].map(([serverName, leaf]) => ({
+        cert: leaf.cert,
+        key: leaf.key,
+        serverName,
+    }));
+}
+/**
+ * (Re)bind the :443 listener from the current cert table + route map. Bun's
+ * TLS config is immutable per `Bun.serve`, so adding an SNI cert means
+ * stopping the old listener and serving a fresh one — cheap (~1ms) and the
+ * window is sub-millisecond. The route Map is the persistent module object,
+ * so the new listener closes over the same table (later route additions need
+ * no rebind). No-ops to a plain rebind when only routes changed.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function rebindHttpsListener(Bun) {
+    const routes = INGRESS_ROUTES_BY_PORT.get(INGRESS_HTTPS_PORT) ?? new Map();
+    INGRESS_ROUTES_BY_PORT.set(INGRESS_HTTPS_PORT, routes);
+    const old = INGRESS_HTTPS_SERVERS.get(INGRESS_HTTPS_PORT);
+    if (old) {
+        try {
+            old.stop(true);
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn("[ingress] failed to stop https listener for rebind:", err);
+        }
+    }
+    const server = bindIngressServer(Bun, INGRESS_HTTPS_PORT, routes, `https :${INGRESS_HTTPS_PORT}`, tlsEntriesFromCerts());
+    INGRESS_HTTPS_SERVERS.set(INGRESS_HTTPS_PORT, server);
+    // eslint-disable-next-line no-console
+    console.log(`[ingress] https :${INGRESS_HTTPS_PORT} for ${[...routes.keys()].join(", ")}`);
+}
+/** True if an exact or wildcard cert already covers `hostname` for SNI. */
+function certCovers(hostname) {
+    if (HTTPS_CERT_BY_HOST.has(hostname))
+        return true;
+    for (const serverName of HTTPS_CERT_BY_HOST.keys()) {
+        if (isWildcard(serverName) && hostname.endsWith(wildcardSuffix(serverName))) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Bind a runtime ingress route for one `tls: [{ hostname, port }]` entry on a
+ * {@link RuntimeServiceSpec} — the runtime twin of a boot service's `tls`.
+ * Mints a leaf cert (unless one already covers the hostname), stands up a
+ * TLS-terminating reverse proxy at `https://<hostname>/` → `service:port`,
+ * also serves plain `http://<hostname>/`, and points the hostname at the
+ * daemon gateway in the resolver registry. Idempotent per hostname.
+ *
+ * Everything it mutates (the live route tables, the :443 cert table, the
+ * names REGISTRY) is daemon-process state, so the binding forks with the
+ * per-test snapshot exactly like fake state — a `dependsOn` child inherits
+ * it, siblings forked from an earlier snapshot never see it.
+ */
+async function bindRuntimeTls(hostname, service, port) {
+    // Reuse the boot primitives for validation + lowercasing; throws on a
+    // malformed hostname / upstream just like a boot `tls` would at load.
+    const decl = makeProxyDecl(hostname, { service, port });
+    const host = decl.hostname;
+    if (!existsSync(CA_PATH) || !existsSync(CA_KEY_PATH)) {
+        throw new Error(`runtime tls for ${JSON.stringify(host)} requires the in-VM root CA at ${CA_PATH}`);
+    }
+    const Bun = requireBun();
+    const route = { kind: "proxy", service, port };
+    // Plain HTTP on :80 (parity with boot `tls`, which serves both schemes).
+    let httpRoutes = INGRESS_ROUTES_BY_PORT.get(INGRESS_HTTP_PORT);
+    if (!httpRoutes) {
+        httpRoutes = new Map();
+        INGRESS_ROUTES_BY_PORT.set(INGRESS_HTTP_PORT, httpRoutes);
+    }
+    httpRoutes.set(host, route);
+    if (!INGRESS_HTTP_SERVERS.has(INGRESS_HTTP_PORT)) {
+        INGRESS_HTTP_SERVERS.set(INGRESS_HTTP_PORT, bindIngressServer(Bun, INGRESS_HTTP_PORT, httpRoutes, `port ${INGRESS_HTTP_PORT}`));
+    }
+    // HTTPS on :443. A new cert forces a listener rebind; an already-covered
+    // hostname (exact dup or a boot wildcard) just needs the route entry.
+    const needCert = !certCovers(host);
+    if (needCert) {
+        HTTPS_CERT_BY_HOST.set(host, await generateHostCert(host, [host]));
+    }
+    const httpsRoutes = INGRESS_ROUTES_BY_PORT.get(INGRESS_HTTPS_PORT) ?? new Map();
+    INGRESS_ROUTES_BY_PORT.set(INGRESS_HTTPS_PORT, httpsRoutes);
+    httpsRoutes.set(host, route);
+    if (needCert || !INGRESS_HTTPS_SERVERS.has(INGRESS_HTTPS_PORT)) {
+        rebindHttpsListener(Bun);
+    }
+    // Resolve the hostname to the daemon gateway (where :443/:80 listen).
+    const gw = await bridgeGatewayIp();
+    REGISTRY.hosts[host] = gw;
+    await writeRegistry();
+    // eslint-disable-next-line no-console
+    console.log(`[ingress] runtime https ${host} -> ${service}:${port}`);
+}
+/**
+ * Undo {@link bindRuntimeTls} for one hostname when its runtime service is
+ * stopped: drop the route (so it 404s) and the registry entry. The cert is
+ * left in the SNI table — harmless without a route, and removing it would
+ * mean an avoidable :443 rebind.
+ */
+async function unbindRuntimeTls(hostname) {
+    const host = hostname.toLowerCase();
+    INGRESS_ROUTES_BY_PORT.get(INGRESS_HTTP_PORT)?.delete(host);
+    INGRESS_ROUTES_BY_PORT.get(INGRESS_HTTPS_PORT)?.delete(host);
+    if (host in REGISTRY.hosts) {
+        delete REGISTRY.hosts[host];
+        await writeRegistry();
+    }
+}
+/**
+ * Spin up one Bun.serve listener bound to (port, optional TLS) that
+ * dispatches every request to the matching Route by Host header.
+ *
+ * Shared by the HTTP and HTTPS branches. Also exports a `websocket`
+ * handler so reverse-proxy targets can transparently bridge WS
+ * upgrades through to their upstream service.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function bindIngressServer(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+Bun, port, byHost, listenerLabel, tlsEntries) {
+    // A TLS listener terminates https; everything else is plain http. Used
+    // to stamp X-Forwarded-Proto so upstreams that build absolute URLs or
+    // redirect see the scheme the client actually used, not our http hop.
+    const proto = tlsEntries ? "https" : "http";
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const opts = {
+        port,
+        hostname: "0.0.0.0",
+        // Bun.serve defaults to a 10s idleTimeout, which kills any proxied
+        // request whose upstream takes >10s to produce bytes — under parallel
+        // test load that surfaced as "fetch failed"/"other side closed" on
+        // deploy-archive uploads and ERR_EMPTY_RESPONSE in browser tests
+        // ([Bun.serve]: request timed out after 10 seconds). Ingress fronts
+        // arbitrarily slow app endpoints (deploys can legitimately take
+        // minutes), so disable the idle timeout entirely; forked test VMs are
+        // short-lived, leaked-connection risk is bounded by the fork.
+        idleTimeout: 0,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        fetch: (req, server) => dispatchIngress(req, server, byHost, listenerLabel, proto),
+        websocket: {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            async open(ws) {
+                const data = ws.data;
+                try {
+                    const upstream = new WebSocket(data.upstreamUrl);
+                    // ArrayBuffer so binary frames can be ws.send()'d to the
+                    // downstream client verbatim — Blob would need an extra
+                    // .arrayBuffer() round-trip on every message.
+                    upstream.binaryType = "arraybuffer";
+                    data.upstream = upstream;
+                    upstream.addEventListener("open", () => {
+                        for (const m of data.pending)
+                            upstream.send(m);
+                        data.pending = [];
+                    });
+                    upstream.addEventListener("message", (ev) => {
+                        try {
+                            ws.send(ev.data);
+                        }
+                        catch {
+                            /* client gone */
+                        }
+                    });
+                    upstream.addEventListener("close", (ev) => {
+                        try {
+                            ws.close(ev.code, ev.reason);
+                        }
+                        catch {
+                            /* already closed */
+                        }
+                    });
+                    upstream.addEventListener("error", () => {
+                        try {
+                            ws.close(1011, "upstream error");
+                        }
+                        catch {
+                            /* already closed */
+                        }
+                    });
+                }
+                catch (err) {
+                    // eslint-disable-next-line no-console
+                    console.warn(`[ingress] ws upstream open failed for ${data.upstreamUrl}:`, err);
+                    try {
+                        ws.close(1011, "upstream open failed");
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                }
+            },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            message(ws, message) {
+                const data = ws.data;
+                const payload = typeof message === "string" ? message : new Uint8Array(message);
+                if (data.upstream && data.upstream.readyState === WebSocket.OPEN) {
+                    data.upstream.send(payload);
+                }
+                else {
+                    // Buffer until the upstream finishes its handshake.
+                    data.pending.push(payload);
+                }
+            },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            close(ws, code, reason) {
+                const data = ws.data;
+                try {
+                    data.upstream?.close(code, reason);
+                }
+                catch {
+                    /* ignore */
+                }
+            },
+        },
+    };
+    if (tlsEntries)
+        opts.tls = tlsEntries;
+    return Bun.serve(opts);
+}
+/**
+ * Per-request dispatch shared by every ingress listener. Looks up the
+ * Route by Host header (port stripped) and either:
+ *   - fake: invokes the handler, wraps thrown errors as 500;
+ *   - proxy: WebSocket upgrade → server.upgrade(); else reverse-proxy
+ *     to the upstream service over plain HTTP.
+ */
+async function dispatchIngress(req, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+server, byHost, listenerLabel, proto) {
+    const host = (req.headers.get("host") ?? "")
+        .toLowerCase()
+        .split(":")[0]
+        .trim();
+    const route = byHost.get(host);
+    if (!route) {
+        return new Response(`spectest-daemon: no ingress route bound to Host=${JSON.stringify(host)} on ${listenerLabel}\n`, { status: 404, headers: { "content-type": "text/plain" } });
+    }
+    // Answer CORS preflights at the ingress (see corsPreflightResponse) so a
+    // cross-origin browser request carrying any header — Authorization,
+    // Cache-Control, Pragma, … — isn't rejected by whatever the upstream happens
+    // to list in Access-Control-Allow-Headers.
+    if (isCorsPreflight(req))
+        return corsPreflightResponse(req);
+    if (route.kind === "fake") {
+        try {
+            const res = await route.fake.def.handler(req, route.fake.state, FAKE_CTX);
+            return augmentCorsResponse(req, res);
+        }
+        catch (err) {
+            const e = err;
+            return new Response(`spectest-daemon: fake ${route.fake.def.name} threw: ${e?.message ?? String(err)}\n`, { status: 500, headers: { "content-type": "text/plain" } });
+        }
+    }
+    const res = await proxyToService(req, server, route.service, route.port, listenerLabel, proto);
+    return augmentCorsResponse(req, res);
+}
+/**
+ * Reverse-proxy a request to `http://<service>:<port>` on
+ * `spectest-net`. Handles plain HTTP/1.1 + 2 and WebSocket upgrades:
+ *
+ *   - WS upgrade requests get routed through `server.upgrade()`, with
+ *     the upstream URL stashed on `ws.data`. The shared `websocket`
+ *     handler opens the upstream and bridges frames both ways.
+ *   - Plain requests pass through via `fetch()` with hop-by-hop
+ *     headers stripped; the response body is a ReadableStream returned
+ *     verbatim, so it streams back without buffering.
+ *
+ * `decompress: false` makes this a true byte-for-byte pass-through:
+ * Bun's fetch otherwise auto-decompresses the upstream body, which would
+ * leave us forwarding the original `Content-Encoding`/`Content-Length`
+ * over a now-plaintext body — browsers then fail with
+ * ERR_CONTENT_DECODING_FAILED or truncate on the stale length (the
+ * WHATWG fetch footgun in whatwg/fetch#1729). Keeping the body encoded
+ * means those headers still describe the bytes we send, and we relay the
+ * client's `Accept-Encoding` upstream so the upstream picks the scheme.
+ */
+async function proxyToService(req, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+server, service, port, listenerLabel, proto) {
+    const url = new URL(req.url);
+    const upstreamPath = `${url.pathname}${url.search}`;
+    const upgrade = req.headers.get("upgrade")?.toLowerCase() ?? "";
+    if (upgrade === "websocket") {
+        const upstreamUrl = `ws://${await proxyUpstreamHost(service)}:${port}${upstreamPath}`;
+        const wsData = {
+            upstreamUrl,
+            upstream: null,
+            pending: [],
+        };
+        const ok = server.upgrade(req, { data: wsData });
+        if (ok) {
+            // Bun has already taken over the response — return a stub.
+            return new Response(null, { status: 101 });
+        }
+        return new Response(`spectest-daemon: ws upgrade refused on ${listenerLabel}\n`, { status: 426, headers: { "content-type": "text/plain" } });
+    }
+    const fwdHeaders = new Headers();
+    for (const [k, v] of req.headers) {
+        if (HOP_BY_HOP_HEADERS.has(k.toLowerCase()))
+            continue;
+        fwdHeaders.append(k, v);
+    }
+    // Standard reverse-proxy provenance headers: the upstream sees the
+    // public scheme/host it was reached through and the client's address,
+    // even though we rewrite Host below to the service-net name.
+    const clientIp = server.requestIP?.(req)?.address;
+    const priorXff = req.headers.get("x-forwarded-for");
+    const xff = clientIp ? (priorXff ? `${priorXff}, ${clientIp}` : clientIp) : priorXff;
+    if (xff)
+        fwdHeaders.set("x-forwarded-for", xff);
+    fwdHeaders.set("x-forwarded-proto", proto);
+    const publicHost = req.headers.get("host");
+    if (publicHost)
+        fwdHeaders.set("x-forwarded-host", publicHost);
+    // Override Host so the upstream sees its own service-net name, not
+    // the public hostname. Lets origin servers that vhost by Host header
+    // continue to find the right virtual host.
+    fwdHeaders.set("host", `${service}:${port}`);
+    // Fresh connection per upstream request — never reuse a pooled
+    // keep-alive conn. Upstreams with short idle timeouts (uvicorn defaults
+    // to 5s) close pooled connections under Bun's fetch, and the next
+    // request on the dead socket fails with "socket closed unexpectedly"
+    // even though the service is healthy. In-VM connects to a peer
+    // container are sub-ms, so per-request connects cost nothing at test
+    // scale. `connection: close` makes the upstream tear down immediately;
+    // `keepalive: false` on the fetch below keeps Bun from pooling its end.
+    // (Both verified effective on Bun 1.3.14.)
+    fwdHeaders.set("connection", "close");
+    // Buffer bounded request bodies so a transient upstream connect failure
+    // can be retried (a ReadableStream body is consumed by the first
+    // attempt). Under heavy parallel-fork load an in-guest connect to a
+    // peer container occasionally fails outright ("Unable to connect" on a
+    // healthy upstream) — observed on deploy-tarball uploads to s3mock; a
+    // bounded retry absorbs it. Bodies above the cap (or with unknown
+    // length and a stream that exceeds it) keep streaming semantics and
+    // simply don't retry.
+    const RETRY_BODY_CAP = 128 * 1024 * 1024;
+    const hasBody = req.method !== "GET" && req.method !== "HEAD";
+    // Only bodies with a known, bounded length are buffered — an unknown
+    // (chunked/streaming) length could be an endless client stream, which
+    // must keep flowing through, not accumulate.
+    const declaredLen = Number(req.headers.get("content-length") ?? NaN);
+    let bufferedBody;
+    if (hasBody && Number.isFinite(declaredLen) && declaredLen <= RETRY_BODY_CAP) {
+        try {
+            bufferedBody = await req.arrayBuffer();
+        }
+        catch {
+            /* client aborted mid-upload; fall through, attempt will fail */
+        }
+    }
+    const retryable = !hasBody || (bufferedBody !== undefined && bufferedBody.byteLength <= RETRY_BODY_CAP);
+    const attempts = retryable ? 3 : 1;
+    let lastErr;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        // Resolve the upstream per attempt: a connect failure below drops the
+        // cached IP, so a retry re-inspects the container.
+        const upstreamUrl = `http://${await proxyUpstreamHost(service)}:${port}${upstreamPath}`;
+        try {
+            const upstreamReq = new Request(upstreamUrl, {
+                method: req.method,
+                headers: fwdHeaders,
+                body: hasBody ? (bufferedBody ?? req.body) : undefined,
+                redirect: "manual",
+            });
+            // decompress:false → forward the encoded body untouched (see fn doc).
+            // keepalive:false → fresh connection per request (see fwdHeaders above).
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const upstreamRes = await NATIVE_FETCH(upstreamReq, {
+                decompress: false,
+                keepalive: false,
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            });
+            // Strip hop-by-hop response headers; let Bun set content-length / TE.
+            const respHeaders = new Headers();
+            for (const [k, v] of upstreamRes.headers) {
+                if (HOP_BY_HOP_HEADERS.has(k.toLowerCase()))
+                    continue;
+                respHeaders.append(k, v);
+            }
+            return new Response(upstreamRes.body, {
+                status: upstreamRes.status,
+                statusText: upstreamRes.statusText,
+                headers: respHeaders,
+            });
+        }
+        catch (err) {
+            lastErr = err;
+            // Retry connection-level failures: connect errors, plus a socket
+            // that died before any response bytes ("socket closed unexpectedly",
+            // ECONNRESET, hang-up) — under boot-time bursts an upstream accepts
+            // and drops connections while still warming up. Pre-response
+            // failures are the standard retry class for reverse proxies
+            // (nginx's proxy_next_upstream error). Anything that produced a
+            // response is never replayed.
+            const msg = err?.message ?? String(err);
+            const connectFailure = /unable to connect|connection refused|connect|typo in the url|socket closed|connection closed|econnreset|socket hang ?up|epipe/i.test(msg);
+            if (!connectFailure || attempt === attempts)
+                break;
+            // The cached IP may be stale (container recreated) — re-resolve.
+            PROXY_IP_CACHE.delete(service);
+            // eslint-disable-next-line no-console
+            console.warn(`[ingress] upstream ${service}:${port} connect failed (attempt ${attempt}/${attempts}), retrying: ${msg}`);
+            await new Promise((r) => setTimeout(r, 250 * attempt));
+        }
+    }
+    const e = lastErr;
+    return new Response(`spectest-daemon: upstream ${service}:${port} unreachable: ${e?.message ?? String(lastErr)}\n`, { status: 502, headers: { "content-type": "text/plain" } });
+}
+/**
+ * In-memory names registry, serialised to FAKES_REGISTRY_PATH for the
+ * resolver. `startIngress` seeds it from LOWERED (the static
+ * tls/hostnames/fakes/wildcard decls); `registerDnsName` mutates it live
+ * when a test calls `ctx.dnsName`. It lives in daemon memory, so it forks
+ * with the rest of the snapshot — a test's dynamic registration is
+ * isolated to its own fork, exactly like fake state.
+ */
+const REGISTRY = { hosts: {}, wildcards: [] };
+async function writeRegistry() {
+    const body = JSON.stringify({
+        hosts: REGISTRY.hosts,
+        wildcards: REGISTRY.wildcards,
+        updatedAt: Date.now(),
+    });
+    try {
+        await fs.mkdir(path.dirname(FAKES_REGISTRY_PATH), { recursive: true });
+        await fs.writeFile(FAKES_REGISTRY_PATH, body);
+    }
+    catch (err) {
+        // Resolver gracefully degrades; just log.
+        // eslint-disable-next-line no-console
+        console.warn(`[names] failed to write registry at ${FAKES_REGISTRY_PATH}:`, err);
+    }
+}
+/** `*.example.com` → `.example.com` — the suffix the resolver matches. */
+function wildcardSuffix(pattern) {
+    return pattern.slice(1); // drop the leading "*"
+}
+/** A service container's IP on spectest-net. `null` if the container isn't
+ *  up or isn't attached to the network yet. */
+async function serviceContainerIp(name) {
+    const out = await docker([
+        "inspect",
+        "--format",
+        `{{(index .NetworkSettings.Networks "${NETWORK_NAME}").IPAddress}}`,
+        name,
+    ], 10_000);
+    if (out.code !== 0)
+        return null;
+    const ip = out.stdout.trim();
+    return ip.length > 0 && ip !== "<no value>" ? ip : null;
+}
+/** Cache of service container IPs for the ingress proxy, so the proxy hot
+ *  path doesn't depend on in-guest DNS: name resolution goes through
+ *  spectest-resolver — a single-threaded Bun process that can be starved
+ *  when the guest's vCPUs are saturated (observed as ~30s of
+ *  "tarballs-s3:9090 unreachable" 502s during parallel deploy tests while
+ *  the container was healthy). Populated lazily via `docker inspect`
+ *  (local socket, no DNS); the proxy drops an entry on connect failure so
+ *  a recreated container re-resolves on retry. */
+const PROXY_IP_CACHE = new Map();
+async function proxyUpstreamHost(service) {
+    const cached = PROXY_IP_CACHE.get(service);
+    if (cached)
+        return cached;
+    const ip = await serviceContainerIp(service).catch(() => null);
+    if (ip) {
+        PROXY_IP_CACHE.set(service, ip);
+        return ip;
+    }
+    // Fall back to the name (resolver / docker DNS) — e.g. a target that
+    // isn't a docker container on spectest-net.
+    return service;
+}
+/** Resolve a DnsTarget to a concrete IP: ingress → bridge gateway, service
+ *  → that container's IP. Throws if a service target has no IP yet. */
+async function resolveDnsTarget(target) {
+    if ("ingress" in target)
+        return bridgeGatewayIp();
+    const ip = await serviceContainerIp(target.service);
+    if (!ip) {
+        throw new Error(`dnsName target service ${JSON.stringify(target.service)} has no IP on ${NETWORK_NAME} (is it a running service?)`);
+    }
+    return ip;
+}
+/**
+ * Seed REGISTRY from the static lowered decls and write it. Run twice per
+ * /bootstrap: once from startIngress (`servicesUp: false`) so ingress
+ * hostnames answer during container startup, then once after every
+ * container is up (`servicesUp: true`) so service-targeted wildcards (e.g.
+ * k3s `ingressDomains`) can resolve their container IPs. The post-container
+ * pass is what's captured into the warm template.
+ */
+async function seedNamesRegistry(opts) {
+    const gw = await bridgeGatewayIp();
+    REGISTRY.hosts = {};
+    REGISTRY.wildcards = [];
+    for (const h of LOWERED.ingressHosts)
+        REGISTRY.hosts[h] = gw;
+    for (const w of LOWERED.wildcards) {
+        if ("ingress" in w.target) {
+            REGISTRY.wildcards.push({ suffix: wildcardSuffix(w.pattern), ip: gw });
+            continue;
+        }
+        // Service target — only resolvable once the container has an IP.
+        if (!opts.servicesUp)
+            continue;
+        const ip = await serviceContainerIp(w.target.service);
+        if (ip) {
+            REGISTRY.wildcards.push({ suffix: wildcardSuffix(w.pattern), ip });
+        }
+        else {
+            // eslint-disable-next-line no-console
+            console.warn(`[names] wildcard ${w.pattern}: service ${JSON.stringify(w.target.service)} has no IP on ${NETWORK_NAME}`);
+        }
+    }
+    await writeRegistry();
+}
+/**
+ * Register a hostname at runtime — the implementation behind `ctx.dnsName`.
+ * Validates via the same `dnsName` primitive the static path uses, resolves
+ * the target to an IP, and updates + persists the registry. Exact names go
+ * in `hosts`; `*.suffix` wildcards in `wildcards`. The resolver re-reads on
+ * the next query (it watches the file's mtime), so the name is live
+ * immediately — answered for VM-host/test/browser code and for peer
+ * containers (Docker forwards unknown names to the host resolver). It does
+ * NOT land in any container's /etc/hosts.
+ */
+async function registerDnsName(hostname, target) {
+    const resv = reserveEvent();
+    // Reuse the primitive purely for validation + lowercasing.
+    const decl = makeDnsDecl(hostname, target);
+    const ip = await resolveDnsTarget(target);
+    if (isWildcard(decl.hostname)) {
+        const suffix = wildcardSuffix(decl.hostname);
+        REGISTRY.wildcards = REGISTRY.wildcards.filter((w) => w.suffix !== suffix);
+        REGISTRY.wildcards.push({ suffix, ip });
+    }
+    else {
+        REGISTRY.hosts[decl.hostname] = ip;
+    }
+    await writeRegistry();
+    recordEnv({ op: "dnsName", hostname: decl.hostname, ip, durationMs: 0 }, resv);
+}
+/**
+ * Mint a leaf certificate from the in-VM root CA and hand back the PEMs
+ * — the implementation behind `ctx.certificate`.
+ *
+ * The value-returning counterpart to the `certificates` service field:
+ * use that to hand a cert to a container at boot, use this when a *test*
+ * needs the material as data — loading it into a Kubernetes Secret,
+ * posting it to a control-plane API, driving a client-cert handshake.
+ * The returned `ca` is the same root every service and `ctx.fetch` /
+ * `ctx.browser()` already trust, so a server configured with these PEMs
+ * verifies cleanly with no `rejectUnauthorized: false`.
+ */
+async function mintCertificate(hostnames) {
+    const resv = reserveEvent();
+    const t = Date.now();
+    if (!Array.isArray(hostnames) || hostnames.length === 0) {
+        throw new Error("ctx.certificate(hostnames): at least one hostname is required");
+    }
+    if (!existsSync(CA_PATH) || !existsSync(CA_KEY_PATH)) {
+        throw new Error(`ctx.certificate(): the in-VM root CA is missing at ${CA_PATH}`);
+    }
+    const { cert, key } = await generateHostCert("ctx", hostnames);
+    const ca = await fs.readFile(CA_PATH, "utf8");
+    recordEnv({ op: "certificate", hostnames, durationMs: Date.now() - t }, resv);
+    return { cert, key, ca };
+}
+// ────────────────────────────────────────────────────────────────────────
+// Runtime services — containers started after bootstrap (from a test, an
+// eval, project setup, or a fake handler reacting to the app under test).
+//
+// A runtime service is a *real machine on the network*: it joins
+// spectest-net with its own IP and is reached directly by name/IP, not
+// through the daemon's HTTP ingress. The same helpers bootstrap uses
+// (prepareServiceImage → runContainer → waitForReady) drive it, so it gets
+// the same image cache, CA trust, and ready-probing. Because it lives in
+// dockerd, it's captured by the per-test post-state snapshot exactly like
+// the boot services — a `dependsOn` child inherits the live container while
+// siblings (which fork from the parent's earlier snapshot) never see it.
+//
+// Tracked here only for in-VM bookkeeping (failure log capture, teardown);
+// the map forks with daemon memory, so each fork sees the services it (or
+// its ancestors) actually started.
+// ────────────────────────────────────────────────────────────────────────
+const RUNTIME_SERVICES = new Map();
+// A runtime service spec is a ServiceConfig (minus tls/dependsOn) + a name;
+// the orchestration helpers want a NamedService, which is the same shape.
+function specToNamedService(spec) {
+    const { name, ...rest } = spec;
+    return { name, ...rest };
+}
+/** Implementation behind `ctx.startService` / a fake's `ctx.startService`.
+ *  Prepares the image (pulling on first use through the host cache), runs
+ *  the container on spectest-net, and waits for its readyCheck. Returns the
+ *  container's name + IP. */
+async function startRuntimeService(spec) {
+    if (!spec.name || spec.name.length === 0) {
+        throw new Error("startService: `name` is required");
+    }
+    const t0 = Date.now();
+    const resv = reserveEvent();
+    const svc = specToNamedService(spec);
+    const aliases = (spec.hostnames ?? []).map((h) => h.toLowerCase());
+    const imageRef = svc.image.type === "registry" ? svc.image.reference : "(dockerfile)";
+    try {
+        const { tag } = await prepareServiceImage(svc);
+        const flags = [
+            ...(await ensureVolumes(svc)),
+            ...(await ensureFiles(svc)),
+            ...(await ensureCertificates(svc)),
+        ];
+        await runContainer(svc, tag, flags, aliases);
+        await waitForReady(svc);
+        const ip = (await serviceContainerIp(svc.name)) ?? "";
+        // `tls` is the runtime twin of a boot service's: stand up a
+        // TLS-terminating reverse proxy at https://<hostname>/ → this container.
+        for (const entry of svc.tls ?? []) {
+            await bindRuntimeTls(entry.hostname, svc.name, entry.port);
+        }
+        RUNTIME_SERVICES.set(svc.name, svc);
+        recordEnv({
+            op: "startService",
+            service: svc.name,
+            image: imageRef,
+            ip,
+            durationMs: Date.now() - t0,
+        }, resv);
+        return { name: svc.name, ip };
+    }
+    catch (err) {
+        recordEnv({
+            op: "startService",
+            service: svc.name,
+            image: imageRef,
+            durationMs: Date.now() - t0,
+            error: errMessage(err),
+        }, resv);
+        throw err;
+    }
+}
+/** Implementation behind `ctx.stopService`. Removes the container and drops
+ *  it from the runtime registry. No-op (rc ignored) if it's already gone. */
+async function stopRuntimeService(name) {
+    const t0 = Date.now();
+    const resv = reserveEvent();
+    const svc = RUNTIME_SERVICES.get(name);
+    await docker(["rm", "-f", name], 30_000);
+    RUNTIME_SERVICES.delete(name);
+    for (const entry of svc?.tls ?? [])
+        await unbindRuntimeTls(entry.hostname);
+    recordEnv({ op: "stopService", service: name, durationMs: Date.now() - t0 }, resv);
+}
+/** The runtime environment-control handle handed to fakes (3rd handler arg /
+ *  `ctx` in `helpers`). The same primitives tests get on `ctx`; module-level
+ *  because none of them depend on a running test. */
+const FAKE_CTX = {
+    startService: startRuntimeService,
+    stopService: stopRuntimeService,
+    dnsName: registerDnsName,
+    certificate: mintCertificate,
+};
+/** Build (or fetch from cache) the helpers record for a fake — the
+ * value that ends up at `ctx.fakes.<name>`. Defaults to `{}` (a fake
+ * with no `helpers` exposes nothing — tests never touch private state
+ * directly). Returns a tracking proxy (see `trackFakeHelpers`) so helper
+ * calls land in the test timeline. */
+async function ensureFakeHelpers(name) {
+    const fake = FAKES.get(name);
+    if (!fake)
+        throw new Error(`fake ${JSON.stringify(name)} is not loaded`);
+    if (fake.trackedHelpers)
+        return fake.trackedHelpers;
+    fake.helpers = fake.def.helpers
+        ? (await fake.def.helpers({
+            name,
+            state: fake.state,
+            ctx: FAKE_CTX,
+        }))
+        : {};
+    fake.trackedHelpers = trackFakeHelpers(name, fake.helpers);
+    return fake.trackedHelpers;
+}
+/** Wrap a fake's helpers so each call becomes a recorded `fake` event
+ * and its return value is `wrap()`ped for assertion provenance. Helpers
+ * are functions that read/mutate the fake's private state via closure;
+ * tests only ever see what those functions return. The proxy is built
+ * once and shared across tests; it consults the recorder at call time,
+ * so it's a transparent no-op when nothing is recording (eval / project
+ * setup).
+ *
+ * Only own function properties are intercepted — inherited members
+ * (`toString`, etc.), symbols, and any stray non-function property pass
+ * straight through untouched. */
+function trackFakeHelpers(fakeName, helpers) {
+    return new Proxy(helpers, {
+        get(target, prop, receiver) {
+            if (typeof prop === "symbol")
+                return Reflect.get(target, prop, receiver);
+            const desc = Object.getOwnPropertyDescriptor(target, prop);
+            if (!desc || typeof desc.value !== "function") {
+                return Reflect.get(target, prop, receiver);
+            }
+            const fn = desc.value;
+            const member = String(prop);
+            return (...args) => invokeFakeHelper(fakeName, member, fn, target, args);
+        },
+    });
+}
+/** Invoke a fake helper function, recording a `fake` event and wrapping
+ * the return value. Handles both sync and async helpers, and records an
+ * error event (then rethrows) if the helper throws. */
+function invokeFakeHelper(fakeName, member, fn, thisArg, args) {
+    const t = Date.now();
+    const resv = reserveEvent();
+    const safeArgs = args.map((a) => safeSerialize(a));
+    const recordResult = (value) => {
+        const seq = recordFake({
+            fake: fakeName,
+            member,
+            args: safeArgs,
+            result: safeSerialize(value),
+            durationMs: Date.now() - t,
+        }, resv);
+        return wrap(value, seq);
+    };
+    const recordError = (err) => {
+        recordFake({
+            fake: fakeName,
+            member,
+            args: safeArgs,
+            durationMs: Date.now() - t,
+            error: errMessage(err),
+        }, resv);
+    };
+    let result;
+    try {
+        result = fn.apply(thisArg, args);
+    }
+    catch (err) {
+        recordError(err);
+        throw err;
+    }
+    if (result instanceof Promise) {
+        return result.then(recordResult, (err) => {
+            recordError(err);
+            throw err;
+        });
+    }
+    return recordResult(result);
+}
+function errMessage(err) {
+    return err?.message ?? String(err);
+}
+/** Build the `fakes` map exposed on the test/eval context. Includes
+ * every loaded fake; helpers are constructed lazily but we eagerly
+ * materialise them here so a test can just read `ctx.fakes.x.y`. */
+async function buildFakeHandles() {
+    const handles = {};
+    for (const name of FAKES.keys()) {
+        handles[name] = await ensureFakeHelpers(name);
+    }
+    return handles;
+}
+function serviceTotalMs(s) {
+    return s.prepMs + (s.runMs ?? 0) + (s.readyMs ?? 0) + (s.setupMs ?? 0);
+}
+// Logged to the daemon journal (also folded into the /bootstrap response,
+// which the control plane logs). One compact line per service plus the
+// slowest BuildKit steps, so a slow cold start is profileable without
+// dumping the full build output.
+function logBootstrapTimings(t) {
+    for (const s of t.services) {
+        const parts = [`prep=${s.prepMs}ms(${s.kind})`];
+        if (s.runMs != null)
+            parts.push(`run=${s.runMs}ms`);
+        if (s.readyMs != null)
+            parts.push(`ready=${s.readyMs}ms`);
+        if (s.setupMs)
+            parts.push(`setup=${s.setupMs}ms`);
+        console.log(`[bootstrap] ${s.name}: ${parts.join(" ")}`);
+        if (s.buildSteps && s.buildSteps.length) {
+            const top = s.buildSteps
+                .map((x) => `${x.cached ? "cached" : x.secs.toFixed(1) + "s"} ${x.name}`)
+                .join(" | ");
+            console.log(`[bootstrap]   ${s.name} build steps: ${top}`);
+        }
+    }
+    console.log(`[bootstrap] total ${t.totalMs}ms across ${t.services.length} service(s)`);
+}
+async function bootstrap() {
+    // Tee everything this bootstrap logs — ours and every service `setup`
+    // hook's — into the boot log, so GET /boot-log can explain a slow or
+    // finished boot. Restored in the finally at the end.
+    const restoreBootLog = captureConsole(BOOT_LOG_SINK);
+    try {
+        return await bootstrapInner();
+    }
+    finally {
+        restoreBootLog();
+    }
+}
+async function bootstrapInner() {
+    const bootStart = Date.now();
+    const cfg = requireLoaded().project.environment;
+    const services = namedServices(cfg);
+    const timings = new Map();
+    progressInit(services);
+    // Build dedup is only valid within one workspace generation — a fresh
+    // bootstrap may follow a workspace re-upload with the same dockerfile
+    // text but different build-context content.
+    BUILD_DEDUP.clear();
+    // Network create is independent of the workspace-side prep, so run
+    // them concurrently. .dockerignore only blocks `docker build`s — pulls
+    // wouldn't need it — but the writes are sub-millisecond so we just
+    // gate image prep behind both.
+    await Promise.all([
+        ensureNetwork(),
+        (async () => {
+            await fs.mkdir(WORKSPACE, { recursive: true });
+            // Read the project's own .dockerignore BEFORE we consider writing
+            // one — every per-service ignore composes on top of it.
+            PROJECT_DOCKERIGNORE = await readProjectDockerignore();
+            if (PROJECT_DOCKERIGNORE !== null) {
+                console.log("[bootstrap] using the project's .dockerignore for every build context");
+                // Never overwrite it. BuildKit reads the per-service
+                // `<Dockerfile>.dockerignore` (which already folds this file in),
+                // and the legacy builder reads the project's file directly —
+                // which is what the project asked for. Clobbering it also broke
+                // any in-env tooling that reads it.
+                return;
+            }
+            await fs.writeFile(path.join(WORKSPACE, ".dockerignore"), unionDockerignore(services));
+        })(),
+    ]);
+    // Image prep is DECOUPLED from container start: every service's image
+    // prep kicks off now, independent of `dependsOn`, and each service's
+    // container start (in startServices below) gates on (its OWN image ready)
+    // AND (its deps up) — there is no whole-graph barrier. So a service whose
+    // image is pulled and whose deps are up starts immediately; it never sits
+    // at "image ready" waiting for an unrelated slow build elsewhere.
+    //
+    // Prep concurrency: registry pulls always run in parallel (network-bound,
+    // low VM RAM). Dockerfile builds parallelize *only* when the host
+    // buildkitd is in play — there the build executes host-side under runc, so
+    // N concurrent builds don't touch the VM's memory ceiling. When we fall
+    // back to the in-VM builder, two or more concurrent builds routinely OOM a
+    // single VM on monorepos with parallel pnpm/npm installs (each install
+    // fans out to ~16 fetchers + lifecycle workers, ~70 MB/process), so we
+    // serialize that case behind a FIFO chain — but only the in-VM builds
+    // serialize; pulls and starts run freely alongside them. The remote-builder
+    // probe is memoized, so this up-front call is free; skip it with no builds.
+    const tags = new Map();
+    const builds = services.filter((s) => s.image.type === "dockerfile");
+    const buildsRunHostSide = builds.length > 0 && (await ensureRemoteBuilder());
+    // A promise chain is a fair FIFO mutex: when builds run in-VM, each build
+    // waits for the previous to settle. Pulls and host-side builds bypass it.
+    let inVmBuildChain = Promise.resolve();
+    const prepImage = (svc) => {
+        // Bootstrap is the only dedup scope: all its builds share one
+        // /workspace generation (see prepareServiceImage).
+        const run = () => prepareServiceImage(svc, { dedup: true });
+        if (svc.image.type === "dockerfile" && !buildsRunHostSide) {
+            const next = inVmBuildChain.then(run, run);
+            // Keep the chain moving even if a build throws; the chain itself never
+            // rejects (the per-service prep promise below is what surfaces errors).
+            inVmBuildChain = next.then(() => undefined, () => undefined);
+            return next;
+        }
+        return run();
+    };
+    const prep = new Map();
+    for (const svc of services) {
+        const p = (async () => {
+            const t0 = Date.now();
+            const { tag, buildSteps } = await prepImage(svc);
+            progressService(svc.name, { status: "prepared", detail: undefined });
+            tags.set(svc.name, tag);
+            timings.set(svc.name, {
+                name: svc.name,
+                kind: svc.image.type === "registry" ? "pull" : "build",
+                prepMs: Date.now() - t0,
+                buildSteps,
+            });
+        })();
+        // A dependent whose dep fails aborts before it awaits this prep, which
+        // would leave the prep promise unobserved. Attach a no-op handler so a
+        // late rejection can't crash the daemon; startOne still re-throws it for
+        // services that do reach their await.
+        p.catch(() => undefined);
+        prep.set(svc.name, p);
+    }
+    // Ingress (fakes + service-tls proxies) comes up BEFORE services so
+    // that any service that calls a fake URL during its own startup
+    // probe finds it answering. Service-tls proxies will return 502
+    // until their upstream containers start, but no one is hitting
+    // https://<svc>.test/ during bootstrap so that's harmless. The
+    // bridge gateway IP is set on `network create` — independent of
+    // any container being up — so we don't need services to determine
+    // the listener address.
+    await startIngress();
+    progressPhase("Starting services");
+    // Container start + ready probe driven by the dependsOn DAG: each
+    // service starts the moment its own dependencies finish run→probe→setup,
+    // instead of waiting for a whole topological level to clear. We chain
+    // run→probe→setup per service so a dependent sees the post-setup state
+    // of its deps (a database with its schema applied, a k3s cluster with
+    // its ingress controller already running) — but an unrelated slow probe
+    // no longer holds back a branch that's ready to go.
+    await startServices(services, async (svc) => {
+        // Gate on our OWN image being ready. startServices already gated on our
+        // deps; this adds the image edge. The two compose: we run the moment
+        // both are satisfied, with no whole-graph barrier between them.
+        await prep.get(svc.name);
+        const flags = [
+            ...(await ensureVolumes(svc)),
+            ...(await ensureFiles(svc)),
+            ...(await ensureCertificates(svc)),
+        ];
+        const tag = tags.get(svc.name);
+        if (!tag)
+            throw new Error(`internal: no image tag for ${svc.name}`);
+        const tRun = Date.now();
+        progressService(svc.name, { status: "starting", detail: undefined });
+        await runContainer(svc, tag, flags);
+        const tReady = Date.now();
+        progressService(svc.name, { status: "probing", detail: "ready check" });
+        await waitForReady(svc);
+        const tSetup = Date.now();
+        if (svc.setup) {
+            progressService(svc.name, { status: "probing", detail: "running setup" });
+            const helpers = await ensureHelpers(svc.name, svc);
+            await svc.setup({ name: svc.name, helpers, ...componentContext() });
+        }
+        progressService(svc.name, { status: "ready", detail: undefined });
+        const ti = timings.get(svc.name);
+        if (ti) {
+            ti.runMs = tReady - tRun;
+            ti.readyMs = tSetup - tReady;
+            ti.setupMs = svc.setup ? Date.now() - tSetup : 0;
+        }
+    });
+    // Containers now have IPs — re-seed so service-targeted wildcards (e.g.
+    // k3s ingressDomains → the cluster container) resolve. Captured into the
+    // warm template, so warm starts inherit the resolved entries.
+    await seedNamesRegistry({ servicesUp: true });
+    // Browser pre-warm DISABLED (2026-06-08). We used to pre-open one view
+    // into the pool (browser.ts VIEW_POOL) here so every fork inherited a
+    // live renderer and the first ctx.browser() skipped the ~1.2-1.5s spawn.
+    // But a renderer spawned BEFORE the snapshot and restored in a fork holds
+    // stale DNS state: its first navigate to an ingress host fails
+    // `net::ERR_NAME_NOT_RESOLVED` even though getaddrinfo/fetch resolve fine
+    // (the --disable-features=AsyncDns flag doesn't save the pooled view). A
+    // view created fresh AFTER the fork (openBrowser → createView, since the
+    // pool is now empty) spawns a post-restore renderer with correct DNS. The
+    // tradeoff is the per-test spawn cost is back on the browser path; we
+    // accept it to keep the suite's browser-rooted DAGs working. See
+    // browser.ts:213 (the long-standing intermittent NAME_NOT_RESOLVED) and
+    // the clocksource-regression notes. Re-enabling requires fixing the
+    // restored-renderer DNS state, not just re-adding the prewarm call.
+    // NOTE: persistent sessions (ctx.browser/ctx.mobile keep one live view
+    // across tests, so restored forks navigate on a pre-snapshot renderer
+    // routinely) hit the same bug head-on; browser.ts handles it there by
+    // rebuilding the view in the same Chrome and retrying the navigation
+    // (`rebuildView`) — profile state survives, so auth carries over. That
+    // recovery is scoped to inherited-navigation failures and does NOT make
+    // the about:blank prewarm pool safe to re-enable.
+    const result = {
+        totalMs: Date.now() - bootStart,
+        services: [...timings.values()].sort((a, b) => serviceTotalMs(b) - serviceTotalMs(a)),
+    };
+    progressDone();
+    logBootstrapTimings(result);
+    return result;
+}
+/**
+ * Run the loaded project's `setup` hook, if any. Called by the control
+ * plane once between /bootstrap and the warm-template snapshot, so the
+ * effects (seeded DB rows, initial pods, fixture files) are captured
+ * exactly once and inherited by every later snapshot/fork.
+ *
+ * Unlike test runs, this is NOT instrumented — no recorder, no event
+ * timeline, no timeout from the test runner. Setup failures abort the
+ * env bring-up; the control plane surfaces them as a start failure.
+ */
+async function runProjectSetup() {
+    // Same tee as bootstrap: a project `setup` hook's console output is
+    // part of explaining the boot, not something to lose on success.
+    const restoreBootLog = captureConsole(BOOT_LOG_SINK);
+    try {
+        return await runProjectSetupInner();
+    }
+    finally {
+        restoreBootLog();
+    }
+}
+async function runProjectSetupInner() {
+    const proj = requireLoaded().project;
+    if (!proj.setup)
+        return { ran: false, durationMs: 0 };
+    const start = Date.now();
+    // Build the same `svc` handles tests see, so setup and tests share
+    // helper instances (e.g. a Bun.SQL pool created here is reused later).
+    const svc = (await buildServiceHandles(proj.environment));
+    const fakes = await buildFakeHandles();
+    // Install the fetch wrapper for the duration of setup so `ctx.fetch` (and any
+    // client routed through `globalThis.fetch`) returns a wrapped Response, same
+    // as in a test. No recorder is active here, so it wraps without provenance —
+    // but the wrapped type stays honest at runtime (`.unwrap()` works).
+    const restoreFetch = installFetchWrapper();
+    const ctx = {
+        fetch: globalThis.fetch,
+        exec: execInServiceWrapped,
+        svc,
+        fakes,
+        dnsName: registerDnsName,
+        certificate: mintCertificate,
+        startService: startRuntimeService,
+        stopService: stopRuntimeService,
+    };
+    try {
+        await proj.setup(ctx);
+    }
+    finally {
+        restoreFetch();
+    }
+    return { ran: true, durationMs: Date.now() - start };
+}
+// ────────────────────────────────────────────────────────────────────────
+// Replay bundles (rrweb sessions → gzipped side-channel, pulled in chunks)
+// ────────────────────────────────────────────────────────────────────────
+//
+// `RunResult.browserSessions` never rides the `/run` reply: the vm-agent
+// caps proxied daemon responses at 16 MB and a browser-heavy case's
+// recording is tens of MB of JSON (see replay-bundle.ts for the whole
+// story). Instead the /run handler encodes the sessions into a gzipped,
+// asset-deduplicated bundle, parks it here keyed by case id, and replies
+// with a tiny `replay: { bytes }` ref; the control plane then pulls the
+// bundle via `POST /replay-chunk` in base64 chunks sized under the cap,
+// before it tears the fork down.
+//
+// The map is module memory, so it FORKS with the snapshot (the post-test
+// snapshot is captured before the control plane fetches). The size cap
+// keeps a long handoff chain from accreting every ancestor's (gzipped)
+// bundle in guest RAM — entries older than the last few are always
+// already-fetched leftovers frozen into some snapshot.
+const REPLAY_BUNDLES = new Map();
+const REPLAY_BUNDLES_MAX = 8;
+function stashReplayBundle(caseId, gz) {
+    // Re-insert to refresh recency (Map iterates in insertion order).
+    REPLAY_BUNDLES.delete(caseId);
+    REPLAY_BUNDLES.set(caseId, gz);
+    while (REPLAY_BUNDLES.size > REPLAY_BUNDLES_MAX) {
+        const oldest = REPLAY_BUNDLES.keys().next().value;
+        if (oldest === undefined)
+            break;
+        REPLAY_BUNDLES.delete(oldest);
+    }
+}
+// ────────────────────────────────────────────────────────────────────────
+// Cumulative service logs (per-case deltas → S3, reconstructed on the web)
+// ────────────────────────────────────────────────────────────────────────
+//
+// A child test runs in a fork restored from its parent's memory+filesystem
+// snapshot, so `docker logs <svc>` in the child already contains the
+// parent's entire history plus the child's own output — logs are
+// inherently cumulative along each branch. Rather than store the (growing,
+// redundant) full log at every case, each case stores only its DELTA (the
+// lines it added), and the dashboard reconstructs a branch's full log by
+// concatenating deltas along the ancestor chain.
+//
+// The load-bearing trick: `LOG_MARKERS` lives in module memory, so it
+// FORKS with the snapshot (same mechanism as `TEST_DATA` / `RUNTIME_SERVICES`).
+// `runOne` advances the markers BEFORE `/run` returns, and the control
+// plane snapshots the fork AFTER `/run` returns — so a child (forked or
+// handed off) restores the parent's final markers and its delta tiles on
+// with no gap or cross-branch duplication.
+/**
+ * Per-(service, stream) count of newline-terminated log lines already
+ * captured by an ancestor case. Key is `"<service><stream>"`. The
+ * next case on this branch captures only `lines[marker..]`. Module-scope
+ * so it travels with the snapshot into every fork.
+ */
+const LOG_MARKERS = new Map();
+/** Per-(service, stream) delta byte cap. Over this we keep head+tail and
+ *  elide the middle — the head preserves the continuation from the parent,
+ *  the tail preserves the newest output — while still advancing the marker
+ *  to the true line count so the chain stays aligned. */
+const LOG_DELTA_MAX_BYTES = 2 * 1024 * 1024;
+/**
+ * Inspect a container's run state for {@link ServiceLogDelta}: `{}` while
+ * running (or when inspect fails — a removed container has no state left to
+ * report), `{ stopped, exitCode }` once it has exited/died.
+ */
+async function containerStopState(name) {
+    const r = await docker(["inspect", "-f", "{{.State.Status}} {{.State.ExitCode}}", name], 15_000);
+    if (r.code !== 0)
+        return {};
+    const [status, codeStr] = r.stdout.trim().split(/\s+/);
+    if (status !== "exited" && status !== "dead")
+        return {};
+    const exitCode = Number.parseInt(codeStr ?? "", 10);
+    return Number.isFinite(exitCode) ? { stopped: true, exitCode } : { stopped: true };
+}
+/** Keep the head and tail of `s`, eliding the middle when it exceeds
+ *  `max` (string length, a byte proxy as elsewhere here). Head+tail so an
+ *  over-long delta keeps both the parent-continuation and the newest
+ *  output. */
+function capMiddle(s, max) {
+    if (s.length <= max)
+        return { value: s, truncated: false };
+    const half = Math.floor(max / 2);
+    const elided = s.length - 2 * half;
+    return {
+        value: `${s.slice(0, half)}\n… [${elided} bytes elided] …\n${s.slice(s.length - half)}`,
+        truncated: true,
+    };
+}
+/**
+ * Compute one stream's delta beyond `marker` complete lines.
+ *  - Counts only newline-terminated lines; a trailing partial line (no
+ *    `\n` yet) is held back from both the delta and the count, so a line
+ *    completed by a later capture isn't split across the fork boundary.
+ *  - Reset guard: if the stream shrank below `marker` (container recreated
+ *    or rotated) the whole current log is re-emitted and `reset` is set.
+ */
+function streamDelta(full, marker) {
+    const lastNl = full.lastIndexOf("\n");
+    const complete = lastNl < 0 ? "" : full.slice(0, lastNl + 1);
+    let total = 0;
+    for (let i = 0; i < complete.length; i++) {
+        if (complete.charCodeAt(i) === 10)
+            total++;
+    }
+    let reset = false;
+    let startLine = marker;
+    if (total < marker) {
+        reset = true;
+        startLine = 0;
+    }
+    let delta;
+    if (startLine <= 0) {
+        delta = complete;
+    }
+    else if (startLine >= total) {
+        delta = "";
+    }
+    else {
+        // Byte offset just past the `startLine`-th newline.
+        let seen = 0;
+        let off = 0;
+        for (let i = 0; i < complete.length; i++) {
+            if (complete.charCodeAt(i) === 10 && ++seen === startLine) {
+                off = i + 1;
+                break;
+            }
+        }
+        delta = complete.slice(off);
+    }
+    const capped = capMiddle(delta, LOG_DELTA_MAX_BYTES);
+    return { delta: capped.value, total, reset, truncated: capped.truncated };
+}
+/**
+ * Capture the per-service log delta for the current case and advance the
+ * markers. Runs on EVERY case (pass or fail). Enumerates boot services
+ * (`namedServices`) plus any runtime services this fork started
+ * (`RUNTIME_SERVICES`), deduped by name. A `docker logs` failure surfaces
+ * as the service's `stderr` WITHOUT advancing the markers — a transient
+ * failure must never desync the chain.
+ */
+async function captureServiceLogDeltas() {
+    const l = loaded;
+    if (!l)
+        return [];
+    const byName = new Map();
+    for (const s of namedServices(l.project.environment))
+        byName.set(s.name, s);
+    for (const [name, s] of RUNTIME_SERVICES)
+        byName.set(name, s);
+    const services = [...byName.values()];
+    return Promise.all(services.map(async (svc) => {
+        const [r, stop] = await Promise.all([
+            docker(["logs", "--timestamps", svc.name], 30_000),
+            containerStopState(svc.name),
+        ]);
+        if (r.code !== 0) {
+            // Container gone/renamed — surface the CLI error, leave markers put.
+            const err = capMiddle(r.stderr || r.stdout, LOG_DELTA_MAX_BYTES);
+            return {
+                service: svc.name,
+                stdout: "",
+                stdoutTruncated: false,
+                stdoutReset: false,
+                stderr: err.value,
+                stderrTruncated: err.truncated,
+                stderrReset: false,
+                ...stop,
+            };
+        }
+        const outKey = `${svc.name}stdout`;
+        const errKey = `${svc.name}stderr`;
+        const out = streamDelta(r.stdout, LOG_MARKERS.get(outKey)?.lines ?? 0);
+        const err = streamDelta(r.stderr, LOG_MARKERS.get(errKey)?.lines ?? 0);
+        LOG_MARKERS.set(outKey, { lines: out.total });
+        LOG_MARKERS.set(errKey, { lines: err.total });
+        return {
+            service: svc.name,
+            stdout: out.delta,
+            stdoutTruncated: out.truncated,
+            stdoutReset: out.reset,
+            stderr: err.delta,
+            stderrTruncated: err.truncated,
+            stderrReset: err.reset,
+            ...stop,
+        };
+    }));
+}
+/**
+ * Mint a session id. `idScope` (the running test's case id; `"eval"`
+ * for eval-context sessions) is baked in because `randomUUID()` alone
+ * is NOT unique across test forks: sibling cases resume from the same
+ * snapshot, so the daemon process — and the guest kernel CSPRNG it
+ * draws from — restores identical RNG state in every clone, and the
+ * first UUID minted after the fork collides across siblings (observed
+ * in practice, not hypothetical). Persistence keys sessions by
+ * (run, case, session) so the collision never lost data, but anything
+ * that ever aggregates sessions across cases would conflate them.
+ * Sibling forks run different cases by construction, so the case id is
+ * exactly the entropy the clones are missing.
+ */
+function newSessionId(idScope) {
+    return idScope ? `${idScope}:${randomUUID()}` : randomUUID();
+}
+/**
+ * Cumulative raw-byte cap on one eval's artifacts. The bytes ride the
+ * `/eval` JSON reply base64'd (~1.33x), and the vm-agent hard-errors on
+ * proxied daemon responses over 16 MB (the same cap that pushed /run's
+ * replay bundles out-of-band — see REPLAY_BUNDLES). 8 MiB raw ≈ 10.7 MB
+ * encoded leaves headroom for the reply's sessions/log; screenshots are
+ * typically well under 2 MiB each. If artifacts ever need to grow past
+ * this, move them to the parked-chunk side channel instead of raising it.
+ */
+const MAX_EVAL_ARTIFACT_BYTES = 8 * 1024 * 1024;
+/**
+ * Per-eval artifact sink. `register` throws (failing the screenshot() call,
+ * never the eval) once the byte budget is exhausted.
+ */
+function newArtifactCollector() {
+    const artifacts = [];
+    let total = 0;
+    return {
+        artifacts,
+        register(artifact) {
+            total += artifact.sizeBytes;
+            if (total > MAX_EVAL_ARTIFACT_BYTES) {
+                throw new Error(`artifact byte budget for this eval exceeded (${MAX_EVAL_ARTIFACT_BYTES / (1024 * 1024)} MiB) — ` +
+                    "capture fewer screenshots per eval");
+            }
+            artifacts.push(artifact);
+        },
+    };
+}
+/**
+ * Build the recorder sink + bookkeeping for a single Browser session.
+ * The returned `recorder` is what `openBrowser` writes into; the
+ * returned `record` is the in-flight session object the daemon owns.
+ * `artifacts` (eval-only) wires `screenshot()`'s artifact registration —
+ * test-run sessions don't pass it, which is exactly what makes
+ * `screenshot()` throw outside eval.
+ */
+function newBrowserSession(testStart, idScope, frame = "browser", artifacts) {
+    const record = {
+        sessionId: newSessionId(idScope),
+        openedAtMs: Date.now() - testStart,
+        frame,
+        steps: [],
+    };
+    let closed = false;
+    return {
+        record,
+        recorder: {
+            sessionId: record.sessionId,
+            recordStep(step) {
+                if (closed)
+                    return;
+                record.steps.push(step);
+            },
+            noteNavigation(url) {
+                if (closed)
+                    return;
+                if (record.initialUrl === undefined)
+                    record.initialUrl = url;
+            },
+            ...(artifacts
+                ? { registerArtifact: (a) => artifacts.register(a) }
+                : {}),
+        },
+        markClosed() {
+            if (closed)
+                return;
+            closed = true;
+            record.closedAtMs = Date.now() - testStart;
+        },
+    };
+}
+/** New terminal session bookkeeping for a single `ctx.terminal(...)` call. */
+function newTerminalSession(testStart, service, command, cols, rows, idScope) {
+    const record = {
+        sessionId: newSessionId(idScope),
+        openedAtMs: Date.now() - testStart,
+        service,
+        command,
+        cols,
+        rows,
+        frames: [],
+    };
+    let closed = false;
+    return {
+        record,
+        pushFrame(tSec, data) {
+            if (closed)
+                return;
+            record.frames.push([tSec, "o", data]);
+        },
+        markClosed() {
+            if (closed)
+                return;
+            closed = true;
+            record.closedAtMs = Date.now() - testStart;
+        },
+    };
+}
+/** Grid a recorded `ctx.exec` asciicast claims. There's no PTY behind
+ *  an exec so no real size exists — 80×24 matches the `ctx.terminal`
+ *  default, and the player hard-wraps longer lines the way an actual
+ *  80-col terminal would. */
+const EXEC_CAST_COLS = 80;
+const EXEC_CAST_ROWS = 24;
+/** Cumulative cap on asciicast frame bytes per recorded exec. The exec
+ *  *event* caps its stdout/stderr separately (256 KiB each); this bounds
+ *  the recording, which would otherwise duplicate a huge output in the
+ *  run payload and the DB. On overflow the cast gets one trailing
+ *  notice frame and stops growing; the ExecResult is unaffected. */
+const EXEC_FRAME_CAP_BYTES = 1024 * 1024;
+/**
+ * Build the bookkeeping for a fresh `openTerminal` session and return
+ * the open Terminal handle alongside a frame sink the factory drains
+ * into. The daemon owns the `TerminalSessionRecord`; the factory just
+ * pushes frames and tells us when the session ends.
+ *
+ * Used by both:
+ *   - the long-lived `ctx.openTerminal(...)` API, where the test owns
+ *     the handle and decides when to close;
+ *   - the one-shot `ctx.terminal(...)` wrapper below, which opens a
+ *     terminal with `opts.command`, waits for the embedded program to
+ *     exit, then closes — same code path, just an immediate await.
+ *
+ * Heads-up for test authors: TTY-detecting CLIs may invoke a pager
+ * (psql → less, git → less, etc.) and block waiting for input now that
+ * stdin *is* a TTY. Disable paging in the command itself (e.g.
+ * `psql -P pager=off`) or pass `PAGER=cat` / `PSQL_PAGER=` via
+ * `opts.env`.
+ */
+async function openInstrumentedTerminal(service, opts, testStart, sessions, recordEvents, idScope) {
+    assertKnownOpts("ctx.terminal", opts, TERMINAL_OPT_KEYS);
+    const cols = opts?.cols ?? 80;
+    const rows = opts?.rows ?? 24;
+    const session = newTerminalSession(testStart, service, opts?.command ?? "(interactive)", cols, rows, idScope);
+    sessions.push(session.record);
+    const sink = {
+        pushFrame: (t, data) => session.pushFrame(t, data),
+        markClosed: () => session.markClosed(),
+    };
+    return await openTerminal({
+        service,
+        opts,
+        sink,
+        sessionId: session.record.sessionId,
+        recordEvents,
+    });
+}
+// Return value of each test that has completed in this daemon's lifetime.
+// Lives in daemon memory and is captured by every post-test snapshot, so
+// when a child case forks from its parent's snapshot it sees the same Map
+// already populated. Carries arbitrary JS values — no JSON round-trip.
+const TEST_DATA = new Map();
+// ────────────────────────────────────────────────────────────────────────
+// Component context — the exec / project-file surface handed to service
+// `setup` hooks and `helpers` factories (`ComponentContext` in index.ts),
+// so components don't hand-roll child_process docker execs or hard-code
+// control-plane paths like /workspace.
+// ────────────────────────────────────────────────────────────────────────
+const COMPONENT_EXEC_DEFAULT_TIMEOUT_MS = 120_000;
+/** Raw `docker exec` with optional piped stdin. Array command = exact
+ * argv (no shell); string = `sh -lc`. Non-zero exit is reported via
+ * `exitCode`, never thrown. Unlike `execInService` this records nothing —
+ * setup/helpers-factory time has no test timeline. */
+function componentExec(service, command, opts) {
+    assertKnownOpts("ctx.exec", opts, EXEC_OPT_KEYS);
+    const argv = ["exec", "-i"];
+    if (opts?.cwd)
+        argv.push("-w", opts.cwd);
+    argv.push(service);
+    if (typeof command === "string")
+        argv.push("sh", "-lc", command);
+    else
+        argv.push(...command);
+    const timeoutMs = opts?.timeoutMs ?? COMPONENT_EXEC_DEFAULT_TIMEOUT_MS;
+    return new Promise((resolve, reject) => {
+        const child = spawn("docker", argv, {
+            stdio: [opts?.stdin !== undefined ? "pipe" : "ignore", "pipe", "pipe"],
+        });
+        const out = [];
+        const err = [];
+        child.stdout.on("data", (c) => out.push(c));
+        child.stderr.on("data", (c) => err.push(c));
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGKILL");
+        }, timeoutMs);
+        child.on("error", (e) => {
+            clearTimeout(timer);
+            reject(e);
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            // A SIGKILL'd child reports 137, which reads like an OOM kill.
+            // Report the `timeout(1)` convention plus a note instead, so a
+            // wedged command is diagnosable from the result alone.
+            const stderrText = Buffer.concat(err).toString("utf8");
+            resolve({
+                stdout: Buffer.concat(out).toString("utf8"),
+                stderr: timedOut
+                    ? `${stderrText}\ntimeout after ${timeoutMs}ms`
+                    : stderrText,
+                exitCode: timedOut ? EXEC_TIMEOUT_EXIT_CODE : (code ?? -1),
+            });
+        });
+        feedStdin(child, opts?.stdin);
+    });
+}
+function componentContext() {
+    return {
+        projectRoot: WORKSPACE,
+        readProjectFile: (p) => fs.readFile(path.isAbsolute(p) ? p : path.join(WORKSPACE, p), "utf8"),
+        exec: componentExec,
+    };
+}
+// Cached helper namespaces produced by `ServiceDefinition.helpers`
+// factories. Built lazily on first access and reused for the daemon's
+// lifetime — Bun.SQL pools and similar resources are happy to live a
+// long time, and the underlying TCP connections survive snapshot/fork
+// along with the rest of daemon memory. Cleared on /load and /reload
+// (project change invalidates any cached state).
+const HELPERS_CACHE = new Map();
+/**
+ * Build (or fetch from cache) the helpers record for a single service.
+ * Returns an empty object if the service doesn't ship a `helpers`
+ * factory — symmetric with what gets passed to `setup`.
+ */
+async function ensureHelpers(name, def) {
+    if (!def.helpers)
+        return {};
+    if (!HELPERS_CACHE.has(name)) {
+        HELPERS_CACHE.set(name, await def.helpers({ name, ...componentContext() }));
+    }
+    return HELPERS_CACHE.get(name);
+}
+/**
+ * Build the `svc` map for one test/eval. The value at `svc[name]` is
+ * exactly the record the service's `helpers` factory returned (e.g.
+ * `{ client: SqlClient }` for `postgres(...)`). Services without a
+ * `helpers` factory don't appear in the map at all.
+ */
+async function buildServiceHandles(cfg) {
+    const handles = {};
+    for (const [name, rawDef] of Object.entries(cfg.services)) {
+        // The wire type drops the `helpers` function (JSON.stringify ignores
+        // functions), but in the daemon we hold the in-memory definition
+        // from the user's module — `helpers` is still there when present.
+        const def = rawDef;
+        if (!def.helpers)
+            continue;
+        handles[name] = await ensureHelpers(name, def);
+    }
+    return handles;
+}
+// ────────────────────────────────────────────────────────────────────────
+// Instrumentation helpers
+// ────────────────────────────────────────────────────────────────────────
+function describeFetchInput(input) {
+    if (typeof input === "string")
+        return { url: input };
+    if (input instanceof URL)
+        return { url: input.toString() };
+    // Request instance
+    const req = input;
+    return { url: req.url, methodFromInput: req.method };
+}
+function describeRequestBody(input, init) {
+    // For Request objects, body has already been consumed into the request;
+    // we can't read it back without cloning, which costs. Skip unless init.body
+    // is provided directly.
+    const body = init?.body;
+    if (body === undefined || body === null) {
+        if (input instanceof Request && input.bodyUsed === false) {
+            // Don't drain the request's body here — leaving it for the actual
+            // fetch. Return a marker.
+            return { body: "[Request body not captured]", truncated: false };
+        }
+        return {};
+    }
+    if (typeof body === "string") {
+        const t = truncateUtf8(body);
+        return { body: t.value, truncated: t.truncated };
+    }
+    if (body instanceof URLSearchParams) {
+        const t = truncateUtf8(body.toString());
+        return { body: t.value, truncated: t.truncated };
+    }
+    return { body: `[non-text body: ${body.constructor?.name ?? typeof body}]` };
+}
+/**
+ * Install a fetch wrapper on `globalThis` that emits HTTP events into the
+ * active recorder. Returns a restore function. Calls outside of a running
+ * test still hit the original fetch (the recorder is null then; the
+ * wrapper just adds a tiny amount of overhead — but we restore after each
+ * test anyway, so this only matters mid-test).
+ */
+function installFetchWrapper() {
+    const original = globalThis.fetch;
+    const wrappedFn = async (input, init) => {
+        const start = Date.now();
+        const resv = reserveEvent();
+        const { url, methodFromInput } = describeFetchInput(input);
+        const method = (init?.method ?? methodFromInput ?? "GET").toUpperCase();
+        const reqBody = describeRequestBody(input, init);
+        try {
+            const res = await original(input, init);
+            let responseBody;
+            let responseBodyTruncated;
+            try {
+                const cloned = res.clone();
+                const text = await cloned.text();
+                const t = truncateUtf8(text);
+                responseBody = t.value;
+                responseBodyTruncated = t.truncated;
+            }
+            catch {
+                // Binary or unreadable body — leave undefined.
+            }
+            const seq = recordHttp({
+                method,
+                url,
+                requestBody: reqBody.body,
+                requestBodyTruncated: reqBody.truncated,
+                status: res.status,
+                responseBody,
+                responseBodyTruncated,
+                durationMs: Date.now() - start,
+            }, resv);
+            return wrapResponse(res, seq);
+        }
+        catch (err) {
+            const e = err;
+            recordHttp({
+                method,
+                url,
+                requestBody: reqBody.body,
+                requestBodyTruncated: reqBody.truncated,
+                durationMs: Date.now() - start,
+                error: e?.message ?? String(err),
+            }, resv);
+            throw err;
+        }
+    };
+    // Preserve any provider-specific statics on `fetch` (e.g. Bun's
+    // `fetch.preconnect`) so consumers that touch them keep working.
+    const wrapped = wrappedFn;
+    for (const key of Object.keys(original)) {
+        wrapped[key] = original[key];
+    }
+    globalThis.fetch = wrapped;
+    return () => {
+        globalThis.fetch = original;
+    };
+}
+/** Build the `docker exec` argv for a service command. An optional `cwd`
+ *  becomes `-w <cwd>` (the working-directory option of `ctx.exec`), so the
+ *  command runs from that directory without it being baked into the command
+ *  string. `-i` is passed whenever stdin will be piped — without it docker
+ *  attaches no stdin and the payload is silently discarded. Used by both the
+ *  buffered and streaming variants so they stay in lockstep. */
+function dockerExecArgs(service, command, opts) {
+    const args = ["exec"];
+    if (opts?.stdin !== undefined)
+        args.push("-i");
+    if (opts?.cwd)
+        args.push("-w", opts.cwd);
+    args.push(service, "sh", "-lc", command);
+    return args;
+}
+/** Exit code reported when an exec is killed by its own `timeoutMs`
+ *  (the `timeout(1)` convention, matching `shx`). */
+const EXEC_TIMEOUT_EXIT_CODE = 124;
+/**
+ * Reject option objects carrying properties we don't implement, instead
+ * of ignoring them. TypeScript's excess-property check already flags
+ * these on an object literal, but `spectest test`'s typecheck is
+ * advisory and never gates a run — so a typo'd or unsupported option
+ * (`{ stdin }` before it was supported, `{ timeout }` for `timeoutMs`)
+ * would otherwise vanish without a trace and surface much later as
+ * "the command got no input".
+ */
+function assertKnownOpts(fnLabel, opts, allowed) {
+    if (!opts || typeof opts !== "object")
+        return;
+    const unknown = Object.keys(opts).filter((k) => !allowed.includes(k));
+    if (unknown.length === 0)
+        return;
+    throw new Error(`${fnLabel}: unsupported option${unknown.length > 1 ? "s" : ""} ` +
+        `${unknown.map((k) => JSON.stringify(k)).join(", ")} — supported: ` +
+        `${allowed.map((k) => JSON.stringify(k)).join(", ")}`);
+}
+const EXEC_OPT_KEYS = ["cwd", "stdin", "timeoutMs"];
+const TERMINAL_OPT_KEYS = ["cols", "rows", "env", "command", "timeoutMs"];
+const POLL_OPT_KEYS = ["timeoutMs", "intervalMs"];
+/** Write `stdin` to the child and close the stream. A command that never
+ *  reads stdin makes the write fail with EPIPE — harmless, and it must not
+ *  take down the daemon as an unhandled 'error' event. */
+function feedStdin(child, stdin) {
+    if (stdin === undefined)
+        return;
+    const s = child.stdin;
+    if (!s)
+        return;
+    s.on("error", () => { });
+    s.end(stdin);
+}
+function execInService(service, command, opts) {
+    return new Promise((resolve) => {
+        const child = execFile("docker", dockerExecArgs(service, command, opts), { maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+            if (timer)
+                clearTimeout(timer);
+            if (timedOut) {
+                resolve({
+                    stdout: stdout.toString(),
+                    stderr: `${stderr.toString()}\ntimeout after ${opts.timeoutMs}ms`,
+                    exitCode: EXEC_TIMEOUT_EXIT_CODE,
+                });
+                return;
+            }
+            const exitCode = err && typeof err.code === "number"
+                ? Number(err.code)
+                : err
+                    ? 1
+                    : 0;
+            resolve({
+                stdout: stdout.toString(),
+                stderr: stderr.toString(),
+                exitCode,
+            });
+        });
+        let timedOut = false;
+        const timer = opts?.timeoutMs && opts.timeoutMs > 0
+            ? setTimeout(() => {
+                timedOut = true;
+                child.kill("SIGKILL");
+            }, opts.timeoutMs)
+            : undefined;
+        feedStdin(child, opts?.stdin);
+    });
+}
+/** `execInService` for the no-recorder contexts (`setup`/`eval`): wraps the
+ *  result so `.unwrap()` is available and the ctx's wrapped `exec` type is
+ *  honest at runtime, but with no provenance (there's no event to link to).
+ *  The recorded `ctx.exec` used during tests is `recordedExec` below. */
+async function execInServiceWrapped(service, command, opts) {
+    assertKnownOpts("ctx.exec", opts, EXEC_OPT_KEYS);
+    const res = await execInService(service, command, opts);
+    return wrap(res, undefined);
+}
+/** Per-stream cap on the ExecResult strings the streaming variant
+ *  accumulates — parity with the buffered `execInService`'s `maxBuffer`.
+ *  Past the cap we keep draining (so the child never blocks on a full
+ *  pipe) but stop appending; unlike `execFile` we don't kill the
+ *  process, which only makes over-cap runs *more* survivable. */
+const EXEC_RESULT_CAP_BYTES = 16 * 1024 * 1024;
+/**
+ * Streaming variant of `execInService` for the recorded `ctx.exec`:
+ * the same `docker exec <svc> sh -lc <cmd>` invocation with the same
+ * result shape, but stdout/stderr are drained incrementally so the
+ * caller can timestamp each chunk into an asciicast frame as it
+ * arrives. No PTY is involved — the program still sees plain pipes
+ * (`isatty` false), so the streams stay byte-identical to what `exec`
+ * has always returned; the recording adds arrival *timing* only.
+ * `onChunk` fires in arrival order across both streams — the closest
+ * analogue of what a terminal would have shown — while the returned
+ * `ExecResult` keeps them separate as before.
+ */
+function execInServiceStreaming(service, command, onChunk, opts) {
+    return new Promise((resolve) => {
+        const child = spawn("docker", dockerExecArgs(service, command, opts), {
+            stdio: [opts?.stdin !== undefined ? "pipe" : "ignore", "pipe", "pipe"],
+        });
+        const acc = { stdout: "", stderr: "" };
+        const decoders = {
+            stdout: new TextDecoder("utf-8", { fatal: false }),
+            stderr: new TextDecoder("utf-8", { fatal: false }),
+        };
+        const drain = (which, chunk) => {
+            const data = decoders[which].decode(chunk, { stream: true });
+            if (data.length === 0)
+                return;
+            if (acc[which].length < EXEC_RESULT_CAP_BYTES) {
+                const room = EXEC_RESULT_CAP_BYTES - acc[which].length;
+                acc[which] += data.length > room ? data.slice(0, room) : data;
+            }
+            try {
+                onChunk(which, data);
+            }
+            catch {
+                // frame capture must never break the exec itself
+            }
+        };
+        child.stdout?.on("data", (c) => drain("stdout", c));
+        child.stderr?.on("data", (c) => drain("stderr", c));
+        let settled = false;
+        let timedOut = false;
+        const finish = (exitCode) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            // Flush any multi-byte tail the decoders are still holding.
+            acc.stdout += decoders.stdout.decode();
+            acc.stderr += decoders.stderr.decode();
+            if (timedOut) {
+                const note = `\ntimeout after ${opts.timeoutMs}ms`;
+                acc.stderr += note;
+                onChunk("stderr", note);
+            }
+            resolve({
+                stdout: acc.stdout,
+                stderr: acc.stderr,
+                exitCode: timedOut ? EXEC_TIMEOUT_EXIT_CODE : exitCode,
+            });
+        };
+        const timer = opts?.timeoutMs && opts.timeoutMs > 0
+            ? setTimeout(() => {
+                timedOut = true;
+                child.kill("SIGKILL");
+            }, opts.timeoutMs)
+            : undefined;
+        // `close` (not `exit`) so both pipes are fully drained first.
+        child.on("close", (code) => finish(code ?? 1));
+        child.on("error", () => finish(1));
+        feedStdin(child, opts?.stdin);
+    });
+}
+async function pollCall(description, fn, opts) {
+    assertKnownOpts("ctx.poll", opts, POLL_OPT_KEYS);
+    const timeoutMs = opts?.timeoutMs ?? 30_000;
+    const intervalMs = opts?.intervalMs ?? 1_000;
+    const start = Date.now();
+    // Reserve the wait's slot up front so it sorts at the poll's *start*,
+    // ahead of the iteration events it nests (which record as the poll runs).
+    const resv = reserveEvent();
+    let attempts = 0;
+    let value;
+    let success = false;
+    let predicateError;
+    // Record all iterations normally. Falsy iterations get truncated
+    // from the recorder so the timeline doesn't fill with polling
+    // noise; the LAST iteration's events stay, then get marked as
+    // children of the wait event so the UI can render them nested.
+    const beforePollIdx = recorderEventCount();
+    let lastIterStartIdx = beforePollIdx;
+    let keptIterStartIdx = beforePollIdx;
+    while (Date.now() - start < timeoutMs) {
+        attempts += 1;
+        lastIterStartIdx = recorderEventCount();
+        try {
+            const v = await fn();
+            if (v !== null && v !== undefined && v !== false) {
+                value = v;
+                success = true;
+                keptIterStartIdx = lastIterStartIdx;
+                break;
+            }
+        }
+        catch (err) {
+            predicateError = err;
+            break;
+        }
+        // Failed iteration — drop the events it emitted.
+        recorderTruncate(lastIterStartIdx);
+        if (Date.now() - start + intervalMs > timeoutMs)
+            break;
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
+    if (!success) {
+        // Timeout or predicate error: drop every attempt's events. The
+        // wait event we emit below is the only trace.
+        recorderTruncate(beforePollIdx);
+    }
+    const errMsg = predicateError !== undefined
+        ? (predicateError?.message ?? String(predicateError))
+        : success
+            ? undefined
+            : `timed out after ${timeoutMs}ms`;
+    const seq = recordWait({
+        description,
+        attempts,
+        durationMs: Date.now() - start,
+        passed: success,
+        ...(errMsg !== undefined ? { error: errMsg } : {}),
+    }, resv);
+    if (success && seq !== undefined) {
+        // Group the kept iteration's events under the wait so the UI can
+        // render them inside the wait card. The wait event itself is the
+        // very last entry; markChildren skips it via the seq match.
+        recorderMarkChildren(keptIterStartIdx, seq);
+    }
+    if (predicateError !== undefined)
+        throw predicateError;
+    if (success) {
+        return wrap(value, seq);
+    }
+    throw new Error(`poll ${JSON.stringify(description)} timed out after ${timeoutMs}ms (${attempts} attempts)`);
+}
+function captureConsole(chunks) {
+    const methods = ["log", "info", "warn", "error", "debug"];
+    const orig = new Map();
+    for (const m of methods) {
+        const fn = console[m].bind(console);
+        orig.set(m, console[m]);
+        console[m] = (...a) => {
+            try {
+                chunks.push(a.map((x) => (typeof x === "string" ? x : Bun.inspect(x))).join(" ") + "\n");
+            }
+            catch {
+                // capture must never break the test
+            }
+            fn(...a);
+        };
+    }
+    return () => {
+        for (const m of methods)
+            console[m] = orig.get(m);
+    };
+}
+async function runOne(testCase) {
+    const start = Date.now();
+    const chunks = [];
+    const origStdout = process.stdout.write.bind(process.stdout);
+    const origStderr = process.stderr.write.bind(process.stderr);
+    const capture = (s) => {
+        chunks.push(typeof s === "string" ? s : Buffer.from(s).toString("utf8"));
+        return true;
+    };
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    process.stdout.write = capture;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    process.stderr.write = capture;
+    const restoreConsole = captureConsole(chunks);
+    // Terminal sessions: each `ctx.exec` / `ctx.terminal(...)` /
+    // `ctx.openTerminal(...)` call opens its own session (asciicast frames
+    // live on the record; the inline TestEvent just carries metadata + a
+    // sessionId pointer). Drained at the end of the test and shipped on
+    // RunResult.terminalSessions.
+    //
+    // Unlike browsers, we don't auto-close terminals at test end. A
+    // `docker exec` subprocess is cheap to keep alive (a few KB), and
+    // Freestyle's snapshot captures it cleanly along with the container
+    // — so leaving it running between tests doesn't leak in any
+    // meaningful sense. Auto-closing only added a noisy `close` step
+    // at the end of every test that used `openTerminal`.
+    const terminalSessions = [];
+    // Wrap exec so each call shows up in the event log alongside its
+    // result. We do this here (not on `execInService` itself) so the
+    // bootstrap path stays uninstrumented. Each call also captures the
+    // full CLI run as an asciicast — one exec step = one run = one
+    // recording: output chunks are timestamped as they stream in, so slow
+    // or animated output replays with real timing in the web UI. The
+    // frames are presentation-only; the ExecResult (and any assertions on
+    // it) still sees the plain separated stdout/stderr.
+    const recordedExec = async (service, command, opts) => {
+        assertKnownOpts("ctx.exec", opts, EXEC_OPT_KEYS);
+        const t = Date.now();
+        const cwd = opts?.cwd;
+        const resv = reserveEvent();
+        const session = newTerminalSession(start, service, command, EXEC_CAST_COLS, EXEC_CAST_ROWS, testCase.id);
+        terminalSessions.push(session.record);
+        // Synthetic prompt frame so the replay is self-describing — the
+        // program's own output starts on the next line, like a real shell. A
+        // working directory rides in the prompt sigil (`svc:/dir $`) the way a
+        // real shell prompt shows it, so the recording stays self-describing.
+        const sigil = cwd ? `${service}:${cwd}` : service;
+        session.pushFrame(0, `\x1b[32m${sigil} $\x1b[0m \x1b[1m${command}\x1b[0m\r\n`);
+        let frameBytes = 0;
+        let frameCapped = false;
+        const res = await execInServiceStreaming(service, command, (_stream, data) => {
+            if (frameCapped)
+                return;
+            if (frameBytes + data.length > EXEC_FRAME_CAP_BYTES) {
+                frameCapped = true;
+                session.pushFrame((Date.now() - t) / 1000, "\r\n\x1b[2m[spectest: recording truncated — output exceeded the cast cap]\x1b[0m\r\n");
+                return;
+            }
+            frameBytes += data.length;
+            // Pipes deliver bare `\n`; a terminal renderer needs `\r\n` or
+            // every line starts at the previous line's end column
+            // (stair-stepping). PTY output is ONLCR-cooked by the kernel —
+            // pipe output is not, so cook it here. Normalising existing
+            // `\r\n` too keeps a CR|LF split across chunk boundaries
+            // harmless (`\r\r\n` renders identically).
+            session.pushFrame((Date.now() - t) / 1000, data.replace(/\r?\n/g, "\r\n"));
+        }, opts);
+        session.markClosed();
+        const stdout = truncateUtf8(res.stdout);
+        const stderr = truncateUtf8(res.stderr);
+        // The piped payload is never echoed by the process, so the asciicast
+        // can't show it — carry it on the event instead (truncated like the
+        // output streams) so the timeline shows what the command was fed.
+        const stdin = opts?.stdin !== undefined ? truncateUtf8(opts.stdin) : undefined;
+        const seq = recordExec({
+            service,
+            command,
+            cwd,
+            ...(stdin
+                ? { stdin: stdin.value, stdinTruncated: stdin.truncated }
+                : {}),
+            exitCode: res.exitCode,
+            stdout: stdout.value,
+            stdoutTruncated: stdout.truncated,
+            stderr: stderr.value,
+            stderrTruncated: stderr.truncated,
+            durationMs: Date.now() - t,
+            sessionId: session.record.sessionId,
+        }, resv);
+        return wrap(res, seq);
+    };
+    // One-shot: open a terminal with `command` as the entrypoint, wait
+    // for it to exit, close, and return the existing TerminalResult
+    // shape. The asciicast and one TerminalEvent line up exactly with
+    // the pre-interactive implementation, just routed through the new
+    // factory.
+    const recordedTerminal = async (service, command, opts) => {
+        const timeoutMs = opts?.timeoutMs ?? DEFAULT_TEST_TIMEOUT_MS;
+        const startedAt = Date.now();
+        const resv = reserveEvent();
+        const term = await openInstrumentedTerminal(service, { ...opts, command, timeoutMs }, start, terminalSessions, false, // one-shot doesn't emit per-op step events
+        testCase.id);
+        // `term.exited` resolves to a wrapped result; this one-shot path needs
+        // the plain `exitCode` number, so `.unwrap()` the result first.
+        const { exitCode } = (await term.exited).unwrap();
+        await term.close();
+        const output = term.rawOutput();
+        const preview = truncateUtf8(output);
+        const seq = recordTerminal({
+            service,
+            command,
+            exitCode,
+            durationMs: Date.now() - startedAt,
+            sessionId: term.sessionId,
+            cols: term.cols,
+            rows: term.rows,
+            outputPreview: preview.value,
+            outputTruncated: preview.truncated,
+        }, resv);
+        const result = {
+            output,
+            exitCode,
+            durationMs: Date.now() - startedAt,
+            sessionId: term.sessionId,
+        };
+        return wrap(result, seq);
+    };
+    // Long-lived: open an interactive terminal. Each method on the
+    // returned Terminal records a `terminal-step` event tied back to
+    // this session id; the per-op screen previews are written into the
+    // event so the UI can show "what the user saw after sendLine 'ls'".
+    const recordedOpenTerminal = async (service, opts) => {
+        const term = await openInstrumentedTerminal(service, opts, start, terminalSessions, true, testCase.id);
+        // Emit a one-time `terminal` event so the session shows up in the
+        // sidebar even before any step lands. `exitCode` is filled in by
+        // the eventual `exit`/`close` step event; the inline summary here
+        // uses -1 as a sentinel until then.
+        const preview = truncateUtf8(term.rawOutput());
+        recordTerminal({
+            service,
+            command: opts?.command ?? "(interactive)",
+            exitCode: -1,
+            durationMs: 0,
+            sessionId: term.sessionId,
+            cols: term.cols,
+            rows: term.rows,
+            outputPreview: preview.value,
+            outputTruncated: preview.truncated,
+        });
+        return term;
+    };
+    startRecording();
+    const restoreFetch = installFetchWrapper();
+    // Look up the parent's stored return value (if any). The parent ran in
+    // an ancestor fork; its TEST_DATA entry travels with the snapshot.
+    const parentId = testCase.dependsOn?.id;
+    const parent = parentId !== undefined ? TEST_DATA.get(parentId) : undefined;
+    // Browser/mobile sessions are PERSISTENT: `ctx.browser()` acquires THE
+    // shared desktop browser and `ctx.mobile(app)` the one session for that
+    // app (browser.ts's module-scoped registry, which forks with the
+    // snapshot like fake state). At test end we DETACH — final rrweb drain,
+    // stop writing to this test's recorder — but deliberately keep the
+    // Chromium alive so the post-test snapshot captures it and dependsOn
+    // children resume the live page (cookies, localStorage, signed-in SPA
+    // state) instead of re-navigating. Each test still gets its own session
+    // record (attach re-arms rrweb with a fresh full snapshot, so replays
+    // stay per-case self-contained); records flow back to the control plane
+    // on RunResult.browserSessions and are archived to S3 as the case's
+    // replay bundle. Within one test repeated ctx.browser()/ctx.mobile(app)
+    // calls return the same handle (memoized below) so one test = one
+    // session per device. An explicit `.close()` destroys the shared
+    // instance — the memo is cleared so a later call starts fresh.
+    const browserDetaches = [];
+    const sessions = [];
+    let sharedBrowser = null;
+    const sharedMobiles = new Map();
+    const trackedOpenBrowser = async (opts) => {
+        if (sharedBrowser)
+            return sharedBrowser;
+        const session = newBrowserSession(start, testCase.id);
+        sessions.push(session);
+        const { browser, attached, detach } = await acquirePersistentBrowser({
+            ...(opts ?? {}),
+            recorder: session.recorder,
+        });
+        if (browser.safeAreaInsets) {
+            session.record.safeAreaInsets = browser.safeAreaInsets;
+        }
+        // An attached session starts mid-page (no navigate event will fire) —
+        // stamp the inherited URL so the dashboard can still label the replay.
+        if (attached && session.record.initialUrl === undefined) {
+            session.record.initialUrl = browser.url();
+        }
+        browserDetaches.push(async () => {
+            await detach();
+            session.markClosed();
+        });
+        const innerClose = browser.close.bind(browser);
+        browser.close = async () => {
+            await innerClose();
+            if (sharedBrowser === browser)
+                sharedBrowser = null;
+        };
+        sharedBrowser = browser;
+        return browser;
+    };
+    const trackedOpenMobile = async (app) => {
+        if (!isMobileApp(app)) {
+            throw new Error("ctx.mobile(app): pass a mobile-app handle from ctx.svc, e.g. ctx.mobile(ctx.svc.app) for a service declared with expo().");
+        }
+        const existing = sharedMobiles.get(app.url);
+        if (existing)
+            return existing;
+        const session = newBrowserSession(start, testCase.id, "mobile");
+        sessions.push(session);
+        const { mobile, attached, detach, safeAreaInsets } = await openPersistentMobile({
+            url: app.url,
+            recorder: session.recorder,
+            initScript: app.initScript,
+        });
+        if (safeAreaInsets)
+            session.record.safeAreaInsets = safeAreaInsets;
+        if (attached && session.record.initialUrl === undefined) {
+            session.record.initialUrl = mobile.url();
+        }
+        browserDetaches.push(async () => {
+            await detach();
+            session.markClosed();
+        });
+        const innerClose = mobile.close.bind(mobile);
+        mobile.close = async () => {
+            await innerClose();
+            if (sharedMobiles.get(app.url) === mobile)
+                sharedMobiles.delete(app.url);
+        };
+        sharedMobiles.set(app.url, mobile);
+        return mobile;
+    };
+    // Build convenience handles (e.g. ctx.svc.db.client) from the loaded
+    // project. Done before installing the timeout so a slow client factory
+    // surfaces as a real error rather than getting attributed to the test.
+    const svc = await buildServiceHandles(requireLoaded().project.environment);
+    const fakes = await buildFakeHandles();
+    const ctx = {
+        // installFetchWrapper just swapped globalThis.fetch for the wrapped
+        // version, so capturing it here gets us instrumentation on ctx.fetch
+        // for free. The recorder is active for the test, so responses come
+        // back wrapped — hence the SpectestFetch type.
+        fetch: globalThis.fetch,
+        // exec/terminal/poll wrap their results at runtime (the recorder is
+        // active), so the ctx interface types them wrapped — same bridge as
+        // `fetch` above. The impls' own return types stay raw.
+        exec: recordedExec,
+        terminal: recordedTerminal,
+        openTerminal: recordedOpenTerminal,
+        browser: trackedOpenBrowser,
+        mobile: trackedOpenMobile,
+        testName: testCase.name,
+        parent,
+        svc,
+        fakes,
+        poll: pollCall,
+        dnsName: registerDnsName,
+        certificate: mintCertificate,
+        startService: startRuntimeService,
+        stopService: stopRuntimeService,
+    };
+    const timeoutMs = testCase.timeoutMs ?? DEFAULT_TEST_TIMEOUT_MS;
+    let timer;
+    const timedOut = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`test timed out after ${timeoutMs}ms`)), timeoutMs);
+    });
+    // Result events are gathered inside finally (after the final browser
+    // drains) so we hoist these out of the try/catch.
+    let outcome;
+    try {
+        const value = await Promise.race([
+            Promise.resolve(testCase.run(ctx)),
+            timedOut,
+        ]);
+        // Stash the return value so child cases — which fork from the snapshot
+        // we're about to capture — can read it off ctx.parent.
+        TEST_DATA.set(testCase.id, value);
+        outcome = { status: "passed" };
+    }
+    catch (err) {
+        const e = err;
+        outcome = {
+            status: "failed",
+            error: { message: e.message ?? String(err), stack: e.stack },
+        };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        restoreFetch();
+        restoreConsole();
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        process.stdout.write = origStdout;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        process.stderr.write = origStderr;
+        // Detach every browser/mobile session: final rrweb drain (must be
+        // awaited before collecting session records), then stop writing to
+        // this test's recorder. The Chromium itself deliberately stays alive
+        // — it's part of the state the post-test snapshot captures for
+        // dependsOn children (see the acquire comment above).
+        for (const detach of browserDetaches) {
+            try {
+                await detach();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        for (const s of sessions)
+            s.markClosed();
+    }
+    const durationMs = Date.now() - start;
+    // Capture each service's log delta (the lines THIS case added beyond its
+    // ancestors) on every case, pass or fail. Runs after the duration clock
+    // stops so the `docker logs` round trips aren't billed to the test.
+    // Advancing the markers here — before /run returns and the control plane
+    // snapshots the fork — is what lets children tile their own deltas on
+    // seamlessly. Shipped to S3: the dashboard reconstructs the full
+    // cumulative log for a branch, the CLI failure post-mortem shows the
+    // failing case's own delta.
+    let serviceLogDeltas = [];
+    try {
+        serviceLogDeltas = await captureServiceLogDeltas();
+    }
+    catch (err) {
+        // eslint-disable-next-line no-console
+        console.warn("[service-logs] delta capture failed:", err);
+    }
+    const events = stopRecording();
+    // Drop sessions whose linking event didn't survive — an exec/terminal
+    // inside a failed `ctx.poll` iteration has its events removed by
+    // recorderTruncate, so its recording would be an unreachable orphan in
+    // the UI (and a polled exec would ship one dead cast per attempt).
+    const referencedSessions = new Set();
+    for (const ev of events) {
+        const sid = ev.sessionId;
+        if (typeof sid === "string")
+            referencedSessions.add(sid);
+    }
+    return {
+        status: outcome.status,
+        durationMs,
+        log: chunks.join(""),
+        events,
+        browserSessions: sessions.map((s) => s.record),
+        terminalSessions: terminalSessions.filter((s) => referencedSessions.has(s.sessionId)),
+        serviceLogDeltas,
+        error: outcome.error,
+    };
+}
+const EVAL_DIR = path.join(APP_DIR, ".spectest-eval");
+// Persistent state across eval calls. Mutated by snippets via the
+// `state` global; survives until the daemon process restarts.
+const EVAL_STATE = {};
+// Transpiler instance reused for `scanImports`. We don't transpile the
+// user code — Bun runs the .ts file directly — but scanImports gives us
+// the imports so we can auto-install missing deps.
+const SCAN_TRANSPILER = new Bun.Transpiler({ loader: "ts" });
+function safeSerialize(v) {
+    if (v === undefined)
+        return undefined;
+    try {
+        return JSON.parse(JSON.stringify(v));
+    }
+    catch {
+        return String(v);
+    }
+}
+/** Top-level package name from an import specifier. */
+function packageName(spec) {
+    if (spec.startsWith("@")) {
+        return spec.split("/").slice(0, 2).join("/");
+    }
+    return spec.split("/")[0];
+}
+/**
+ * Scan the snippet's imports and `bun add` anything that doesn't already
+ * resolve. Skips relative paths, absolute paths, `node:`/`bun:` built-ins,
+ * and HTTP(S)/file: URLs.
+ */
+async function ensureDeps(code) {
+    let scanned;
+    try {
+        scanned = SCAN_TRANSPILER.scanImports(code);
+    }
+    catch {
+        // Invalid syntax — let the import call surface the real error.
+        return [];
+    }
+    const seen = new Set();
+    const missing = [];
+    for (const imp of scanned) {
+        const p = imp.path;
+        if (p.startsWith(".") ||
+            p.startsWith("/") ||
+            p.startsWith("node:") ||
+            p.startsWith("bun:") ||
+            p.startsWith("http:") ||
+            p.startsWith("https:") ||
+            p.startsWith("file:")) {
+            continue;
+        }
+        const pkg = packageName(p);
+        if (seen.has(pkg))
+            continue;
+        seen.add(pkg);
+        try {
+            Bun.resolveSync(p, APP_DIR);
+        }
+        catch {
+            missing.push(pkg);
+        }
+    }
+    if (missing.length === 0)
+        return [];
+    await new Promise((resolve, reject) => {
+        execFile("/usr/local/bin/bun", ["add", ...missing], { cwd: APP_DIR, maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+            if (err) {
+                reject(new Error(`bun add ${missing.join(" ")} failed:\n${String(stderr).trim()}\n${String(stdout).trim()}`));
+            }
+            else {
+                resolve();
+            }
+        });
+    });
+    return missing;
+}
+/**
+ * Turn the bare parser error an `export default` misuse produces
+ * ("Unexpected export") into something actionable.
+ *
+ * An eval snippet is imported as a **real ESM module**, so `export
+ * default` is a module-level declaration: there can be exactly one, and
+ * it cannot sit inside an `if`/`try`/loop body. Early-return style —
+ * `if (!x) { out.y = z; export default out; }` — is therefore a syntax
+ * error, and the raw message says nothing about why or what to do.
+ *
+ * We only ever *augment* a message that already failed, and only when
+ * the snippet actually uses `export default`, so a genuine unrelated
+ * syntax error keeps its own text.
+ */
+function explainEvalExportError(code, message) {
+    if (!/unexpected export|export declarations?|'export'|"export"/i.test(message)) {
+        return message;
+    }
+    // Not line-anchored: the early-return idiom this exists to explain puts
+    // the offending export mid-line (`if (!x) { …; export default out; }`),
+    // which an `^`-anchored match would miss entirely.
+    const matches = [...code.matchAll(/\bexport\s+default\s/g)];
+    if (matches.length === 0)
+        return message;
+    // Anything but whitespace before it on its own line means it's nested in
+    // a block or statement rather than declared at the top level.
+    const nested = matches.some((m) => {
+        const lineStart = code.lastIndexOf("\n", m.index) + 1;
+        return code.slice(lineStart, m.index).trim().length > 0;
+    });
+    const counted = matches.length > 1
+        ? `this snippet has ${matches.length} \`export default\` statements, but a module may only have one`
+        : null;
+    const placed = nested
+        ? "`export default` appears inside a block (`if`/`try`/loop), where a module-level declaration isn't allowed"
+        : null;
+    const reason = counted && placed
+        ? `${counted}, and ${placed}`
+        : (counted ?? placed ?? "`export default` isn't at the module's top level");
+    return (`${message}\n\n` +
+        `spectest: an eval snippet is imported as a real ES module, and ${reason}. ` +
+        "For early-return style, compute the value in a function and export its result once:\n\n" +
+        "  export default await (async () => {\n" +
+        "    const out = {};\n" +
+        "    if (!x) return { ...out, y: z };   // early return, not early export\n" +
+        "    out.more = await ctx.exec(\"web\", \"…\");\n" +
+        "    return out;\n" +
+        "  })();\n");
+}
+async function evalCode(code, secrets) {
+    const start = Date.now();
+    // Eval-scoped secret channel for record-mode fakes — set before the
+    // snippet runs, cleared in the `finally` below so a secret never
+    // persists into daemon memory (and thus into a forkable snapshot) past
+    // the eval that supplied it. See record-secrets.ts.
+    setRecordSecrets(secrets);
+    const chunks = [];
+    const origStdout = process.stdout.write.bind(process.stdout);
+    const origStderr = process.stderr.write.bind(process.stderr);
+    const capture = (s) => {
+        chunks.push(typeof s === "string" ? s : Buffer.from(s).toString("utf8"));
+        return true;
+    };
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    process.stdout.write = capture;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    process.stderr.write = capture;
+    // Bun's console.* bypasses process.stdout.write — tee it too.
+    const restoreConsole = captureConsole(chunks);
+    // Wrap fetch for the snippet's duration so `ctx.fetch` returns a wrapped
+    // Response just like in a test (no recorder here, so no provenance — but the
+    // wrapped type is honest at runtime). Restored in the `finally` below.
+    const restoreFetch = installFetchWrapper();
+    // Same persistent acquire/detach as a test run (see runOne): the browser
+    // survives the eval, so successive `spectest env eval` calls continue one
+    // live session — and a snapshot taken afterwards carries it.
+    const browserDetaches = [];
+    const sessions = [];
+    // Eval-only artifact sink — wiring it here (and nowhere in runOne) is
+    // what gates screenshot() to eval context.
+    const artifactCollector = newArtifactCollector();
+    let sharedBrowser = null;
+    const sharedMobiles = new Map();
+    const trackedOpenBrowser = async (opts) => {
+        if (sharedBrowser)
+            return sharedBrowser;
+        const session = newBrowserSession(start, "eval", "browser", artifactCollector);
+        sessions.push(session);
+        const { browser, attached, detach } = await acquirePersistentBrowser({
+            ...(opts ?? {}),
+            recorder: session.recorder,
+        });
+        if (browser.safeAreaInsets) {
+            session.record.safeAreaInsets = browser.safeAreaInsets;
+        }
+        if (attached && session.record.initialUrl === undefined) {
+            session.record.initialUrl = browser.url();
+        }
+        browserDetaches.push(async () => {
+            await detach();
+            session.markClosed();
+        });
+        const innerClose = browser.close.bind(browser);
+        browser.close = async () => {
+            await innerClose();
+            if (sharedBrowser === browser)
+                sharedBrowser = null;
+        };
+        sharedBrowser = browser;
+        return browser;
+    };
+    const trackedOpenMobile = async (app) => {
+        if (!isMobileApp(app)) {
+            throw new Error("ctx.mobile(app): pass a mobile-app handle from ctx.svc, e.g. ctx.mobile(ctx.svc.app) for a service declared with expo().");
+        }
+        const existing = sharedMobiles.get(app.url);
+        if (existing)
+            return existing;
+        const session = newBrowserSession(start, "eval", "mobile", artifactCollector);
+        sessions.push(session);
+        const { mobile, attached, detach, safeAreaInsets } = await openPersistentMobile({
+            url: app.url,
+            recorder: session.recorder,
+            initScript: app.initScript,
+        });
+        if (safeAreaInsets)
+            session.record.safeAreaInsets = safeAreaInsets;
+        if (attached && session.record.initialUrl === undefined) {
+            session.record.initialUrl = mobile.url();
+        }
+        browserDetaches.push(async () => {
+            await detach();
+            session.markClosed();
+        });
+        const innerClose = mobile.close.bind(mobile);
+        mobile.close = async () => {
+            await innerClose();
+            if (sharedMobiles.get(app.url) === mobile)
+                sharedMobiles.delete(app.url);
+        };
+        sharedMobiles.set(app.url, mobile);
+        return mobile;
+    };
+    // Terminal sessions — same shape as runOne, but eval has no active
+    // recorder so we don't emit inline events; the asciicast frames
+    // still ship back on EvalResult.terminalSessions and the web UI
+    // renders the player.
+    const terminalSessions = [];
+    const evalTerminal = async (service, command, opts) => {
+        const timeoutMs = opts?.timeoutMs ?? DEFAULT_TEST_TIMEOUT_MS;
+        const startedAt = Date.now();
+        const term = await openInstrumentedTerminal(service, { ...opts, command, timeoutMs }, start, terminalSessions, false, "eval");
+        const { exitCode } = (await term.exited).unwrap();
+        await term.close();
+        return {
+            output: term.rawOutput(),
+            exitCode,
+            durationMs: Date.now() - startedAt,
+            sessionId: term.sessionId,
+        };
+    };
+    const evalOpenTerminal = async (service, opts) => {
+        return openInstrumentedTerminal(service, opts, start, terminalSessions, false, "eval");
+    };
+    // Convenience handles are best-effort for eval — if the project isn't
+    // loaded yet, fall back to an empty map so quick `await fetch(...)`
+    // snippets don't require a /load round-trip first.
+    const svc = loaded
+        ? await buildServiceHandles(loaded.project.environment)
+        : {};
+    const fakes = loaded ? await buildFakeHandles() : {};
+    const ctx = {
+        // installFetchWrapper swapped globalThis.fetch above, so this captures the
+        // wrapped version — eval results are wrapped just like in a test.
+        fetch: globalThis.fetch,
+        // Wraps its result the same way (no recorder under eval, so no provenance —
+        // but the wrapped type is honest at runtime, so `.unwrap()` works).
+        exec: execInServiceWrapped,
+        terminal: evalTerminal,
+        openTerminal: evalOpenTerminal,
+        browser: trackedOpenBrowser,
+        mobile: trackedOpenMobile,
+        testName: "eval",
+        parent: undefined,
+        svc,
+        fakes,
+        poll: pollCall,
+        dnsName: registerDnsName,
+        certificate: mintCertificate,
+        startService: startRuntimeService,
+        stopService: stopRuntimeService,
+    };
+    // Expose the test context, matchers, and persistent state as globals
+    // so the snippet can use them without an explicit import. The user code
+    // is real ESM, so `import { Client } from "pg"` and top-level `await`
+    // work natively.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const g = globalThis;
+    g.ctx = ctx;
+    g.expect = expect;
+    g.expectRaw = expectRaw;
+    g.assert = assert;
+    g.state = EVAL_STATE;
+    let installed = [];
+    let filePath;
+    let outcome;
+    try {
+        installed = await ensureDeps(code);
+        await fs.mkdir(EVAL_DIR, { recursive: true });
+        filePath = path.join(EVAL_DIR, `${randomUUID()}.ts`);
+        await fs.writeFile(filePath, code);
+        const mod = (await import(pathToFileURL(filePath).href));
+        outcome = { ok: true, result: safeSerialize(mod.default) };
+    }
+    catch (err) {
+        const e = err;
+        const message = e.message ?? String(err);
+        outcome = {
+            ok: false,
+            error: { message: explainEvalExportError(code, message), stack: e.stack },
+        };
+    }
+    finally {
+        clearRecordSecrets();
+        restoreFetch();
+        restoreConsole();
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        process.stdout.write = origStdout;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        process.stderr.write = origStderr;
+        // Detach (final rrweb drain) — the browser itself stays alive; see
+        // the acquire comment above.
+        for (const detach of browserDetaches) {
+            try {
+                await detach();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        for (const s of sessions)
+            s.markClosed();
+        if (filePath) {
+            fs.unlink(filePath).catch(() => {
+                /* best-effort cleanup */
+            });
+        }
+    }
+    // `artifacts` ships on the error branch too — a screenshot captured
+    // before a snippet crash is exactly the evidence the caller wants.
+    return outcome.ok
+        ? {
+            ok: true,
+            durationMs: Date.now() - start,
+            log: chunks.join(""),
+            installed,
+            result: outcome.result,
+            browserSessions: sessions.map((s) => s.record),
+            terminalSessions,
+            artifacts: artifactCollector.artifacts,
+        }
+        : {
+            ok: false,
+            durationMs: Date.now() - start,
+            log: chunks.join(""),
+            installed,
+            browserSessions: sessions.map((s) => s.record),
+            terminalSessions,
+            artifacts: artifactCollector.artifacts,
+            error: outcome.error,
+        };
+}
+// ────────────────────────────────────────────────────────────────────────
+// Typecheck
+//
+// `tsc --noEmit` over the user's spectest/ code (APP_DIR — the only tree the
+// daemon imports; app-under-test source has its own toolchain). Kicked off in
+// the background at /load-tests so it never sits on the start/run critical
+// path; the control plane collects the result via POST /typecheck (which
+// awaits the in-flight run) and attaches it to the SuiteResult as an
+// advisory report. It must never gate a run: the runtime accepts patterns
+// the types reject (e.g. bare global `fetch` is monkey-patched to record,
+// but its *type* stays raw), so a type error is a strong hint, not proof.
+//
+// The compiler is the native tsc baked into the base snapshot at
+// /opt/spectest/typecheck (see base.rs BASE_SETUP_SH); a project that ships
+// its own `typescript` in spectest/package.json wins. A project tsconfig.json
+// wins over the generated one the same way.
+// ────────────────────────────────────────────────────────────────────────
+const TYPECHECK_DIR = "/opt/spectest/typecheck";
+/** Cap on errors shipped in the report; `totalErrors` carries the true count. */
+const TYPECHECK_ERROR_CAP = 50;
+let TYPECHECK = null;
+/** Fire-and-forget kickoff; the promise is parked for POST /typecheck. */
+function startTypecheck() {
+    TYPECHECK = runTypecheck().catch((err) => ({
+        status: "failed",
+        errors: [],
+        totalErrors: 0,
+        durationMs: 0,
+        detail: err instanceof Error ? err.message : String(err),
+    }));
+    // Parked promises must never surface as unhandled rejections.
+    TYPECHECK.catch(() => { });
+}
+/** The tsconfig used when the project doesn't ship its own. `lib` is left to
+ *  the target default (which includes DOM — browser.evaluate callbacks
+ *  reference `document`); `types` pulls Bun's ambient globals from the baked
+ *  install via `typeRoots` (the walk-up from APP_DIR never reaches it). */
+function generatedTsconfig() {
+    return JSON.stringify({
+        compilerOptions: {
+            target: "esnext",
+            module: "esnext",
+            moduleResolution: "bundler",
+            strict: true,
+            noEmit: true,
+            skipLibCheck: true,
+            esModuleInterop: true,
+            resolveJsonModule: true,
+            jsx: "react-jsx",
+            types: ["bun"],
+            typeRoots: [
+                path.join(APP_DIR, "node_modules", "@types"),
+                path.join(TYPECHECK_DIR, "node_modules", "@types"),
+            ],
+        },
+        include: ["**/*.ts", "**/*.tsx"],
+        exclude: ["node_modules"],
+    }, null, 2);
+}
+/** Parse `--pretty false` tsc output: `file(line,col): error TScode: msg`,
+ *  with indented elaboration lines folded into the preceding error. */
+function parseTscOutput(output) {
+    const errors = [];
+    let total = 0;
+    let suppressed = 0;
+    let last = null;
+    for (const line of output.split("\n")) {
+        const m = /^(.+?)\((\d+),(\d+)\): error (TS\d+): (.*)$/.exec(line);
+        if (!m) {
+            // Elaboration lines are indented; fold them into the last kept error.
+            if (last && /^\s+\S/.test(line))
+                last.message += `\n${line.trimEnd()}`;
+            continue;
+        }
+        const [, rawFile, ln, col, code, message] = m;
+        // Keep only diagnostics in the user's files. tsc runs with cwd=APP_DIR
+        // (the daemon's cwd), so project files come out relative ("tests/x.ts")
+        // and anything outside — the SDK at /opt/spectest/sdk, node_modules —
+        // is `../…` or absolute. Errors in our own SDK are ours to fix, not the
+        // user's to read.
+        const abs = path.resolve(APP_DIR, rawFile);
+        const inApp = abs.startsWith(APP_DIR + path.sep) && !abs.includes(`${path.sep}node_modules${path.sep}`);
+        if (!inApp) {
+            suppressed += 1;
+            last = null;
+            continue;
+        }
+        total += 1;
+        const err = {
+            file: path.relative(APP_DIR, abs),
+            line: Number(ln),
+            column: Number(col),
+            code: code,
+            message: message,
+        };
+        if (errors.length < TYPECHECK_ERROR_CAP) {
+            errors.push(err);
+            last = err;
+        }
+        else {
+            last = null;
+        }
+    }
+    return { errors, total, suppressed };
+}
+async function runTypecheck() {
+    const started = Date.now();
+    // The project's own typescript wins over the baked copy.
+    const tsc = [
+        path.join(APP_DIR, "node_modules", "typescript", "bin", "tsc"),
+        path.join(TYPECHECK_DIR, "node_modules", "typescript", "bin", "tsc"),
+    ].find((p) => existsSync(p));
+    if (!tsc) {
+        return {
+            status: "skipped",
+            errors: [],
+            totalErrors: 0,
+            durationMs: 0,
+            detail: "typescript is not installed (base image predates the baked typechecker)",
+        };
+    }
+    let config = path.join(APP_DIR, "tsconfig.json");
+    if (!existsSync(config)) {
+        config = path.join(APP_DIR, ".spectest-tsconfig.json");
+        await fs.writeFile(config, generatedTsconfig());
+    }
+    const res = await shx(process.execPath, [tsc, "--noEmit", "--pretty", "false", "-p", config], 120_000);
+    const durationMs = Date.now() - started;
+    if (res.code === 124) {
+        return { status: "failed", errors: [], totalErrors: 0, durationMs, detail: "typecheck timed out" };
+    }
+    const { errors, total, suppressed } = parseTscOutput(res.stdout + res.stderr);
+    if (errors.length === 0) {
+        // Exit 0 → clean. Non-zero with no *user-file* diagnostics is either
+        // all-suppressed (still ok from the user's perspective) or a compiler
+        // crash (config not found, OOM) — surface the latter.
+        if (res.code !== 0 && suppressed === 0) {
+            const tail = (res.stderr || res.stdout).trim().split("\n").slice(-5).join("\n");
+            return { status: "failed", errors: [], totalErrors: 0, durationMs, detail: tail || `tsc exited ${res.code}` };
+        }
+        if (suppressed > 0) {
+            console.warn(`[typecheck] ${suppressed} diagnostic(s) outside the project suppressed`);
+        }
+        return { status: "ok", errors: [], totalErrors: 0, durationMs };
+    }
+    return { status: "errors", errors, totalErrors: total, durationMs };
+}
+// ────────────────────────────────────────────────────────────────────────
+// HTTP server
+// ────────────────────────────────────────────────────────────────────────
+async function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (c) => chunks.push(c));
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        req.on("error", reject);
+    });
+}
+function jsonResponse(res, status, body) {
+    const payload = Buffer.from(JSON.stringify(body));
+    res.writeHead(status, {
+        "content-type": "application/json",
+        "content-length": payload.length,
+    });
+    res.end(payload);
+}
+async function handle(req, res, state) {
+    const url = req.url ?? "";
+    const method = req.method ?? "GET";
+    if (method === "GET" && url === "/health") {
+        res.writeHead(200, { "content-type": "text/plain" });
+        res.end("ok\n");
+        return;
+    }
+    if (method === "GET" && url === "/progress") {
+        // Live bootstrap progress, polled by the control plane during
+        // /bootstrap and streamed into the test-run row. `{}` before the
+        // first bootstrap() of this daemon.
+        jsonResponse(res, 200, BOOTSTRAP_PROGRESS ?? {});
+        return;
+    }
+    if (method === "GET" && url.startsWith("/env-logs")) {
+        // Live logs for a running environment: the daemon's own boot log
+        // (bootstrap + every `setup` hook's console output) plus each
+        // service's container logs. Unlike the per-case deltas this reads
+        // without touching LOG_MARKERS, so calling it never perturbs a run.
+        const q = new URL(url, "http://daemon").searchParams;
+        const only = q.get("service") ?? undefined;
+        const tail = Math.max(1, Math.min(10_000, Number(q.get("tail") ?? "200") || 200));
+        const l = loaded;
+        const byName = new Map();
+        if (l)
+            for (const s of namedServices(l.project.environment))
+                byName.set(s.name, s);
+        for (const [name, s] of RUNTIME_SERVICES)
+            byName.set(name, s);
+        const names = [...byName.keys()].filter((n) => !only || n === only);
+        if (only && names.length === 0) {
+            jsonResponse(res, 404, {
+                error: `unknown service ${JSON.stringify(only)}; known: ${[...byName.keys()].join(", ") || "(none)"}`,
+            });
+            return;
+        }
+        const services = await Promise.all(names.map(async (name) => {
+            const r = await docker(["logs", "--timestamps", `--tail=${tail}`, name], 30_000);
+            const out = capMiddle(r.stdout, LOG_DELTA_MAX_BYTES);
+            const err = capMiddle(r.code === 0 ? r.stderr : r.stderr || r.stdout, LOG_DELTA_MAX_BYTES);
+            return {
+                service: name,
+                stdout: out.value,
+                stdoutTruncated: out.truncated,
+                stderr: err.value,
+                stderrTruncated: err.truncated,
+            };
+        }));
+        jsonResponse(res, 200, { bootLog: bootLogText(), services });
+        return;
+    }
+    if (method === "POST" && url === "/load") {
+        // Env only — services/fakes/setup. For the legacy single-file layout the
+        // entry also defines the tests, so `cases` is populated here; for the
+        // split layout `cases` is empty until /load-tests runs.
+        const proj = await loadEnv();
+        jsonResponse(res, 200, {
+            environment: proj.environment,
+            cases: casesMetadata(proj.tests),
+            fakes: fakesSummary(proj),
+        });
+        return;
+    }
+    if (method === "POST" && url === "/load-tests") {
+        // Import spectest/tests/** into the already-loaded env and return the
+        // resulting catalogue. Called after the warm snapshot (cold path) or
+        // against a freshly restored VM (warm path).
+        await loadTests();
+        // Background typecheck of the freshly-uploaded app tree — both paths
+        // (cold and warm) funnel through here after the upload, so the check
+        // always sees the current code. Never on the critical path: the reply
+        // doesn't wait, POST /typecheck collects.
+        startTypecheck();
+        const l = requireLoaded();
+        jsonResponse(res, 200, {
+            environment: l.project.environment,
+            cases: casesMetadata(l.project.tests),
+            fakes: fakesSummary(l.project),
+        });
+        return;
+    }
+    if (method === "POST" && url === "/typecheck") {
+        // Await the run kicked off at /load-tests (or start one on demand —
+        // e.g. a legacy single-file project loaded before this daemon shipped
+        // the kickoff, or a direct debug call).
+        if (!TYPECHECK)
+            startTypecheck();
+        jsonResponse(res, 200, await TYPECHECK);
+        return;
+    }
+    if (method === "POST" && url === "/unload") {
+        loaded = null;
+        jsonResponse(res, 200, { unloaded: true });
+        return;
+    }
+    if (method === "POST" && url === "/reload") {
+        // Full reload (debug aid): re-import the env, then the tests.
+        await loadEnv();
+        await loadTests();
+        const l = requireLoaded();
+        jsonResponse(res, 200, {
+            environment: l.project.environment,
+            cases: casesMetadata(l.project.tests),
+            fakes: fakesSummary(l.project),
+        });
+        return;
+    }
+    if (method === "GET" && url === "/env-config") {
+        const l = requireLoaded();
+        jsonResponse(res, 200, l.project.environment);
+        return;
+    }
+    if (method === "GET" && url === "/cases") {
+        const l = requireLoaded();
+        jsonResponse(res, 200, { cases: casesMetadata(l.project.tests) });
+        return;
+    }
+    if (method === "GET" && url === "/record-secret-refs") {
+        // Union of platform secret refs the loaded fakes declare (replayFake's
+        // `secretRefs`). The control plane resolves these server-side and
+        // pushes the values on the eval path only. Empty if nothing's loaded.
+        const refs = new Set();
+        for (const fake of FAKES.values()) {
+            for (const ref of fake.def.secretRefs ?? [])
+                refs.add(ref);
+        }
+        jsonResponse(res, 200, { refs: [...refs] });
+        return;
+    }
+    if (method === "POST" && url === "/bootstrap") {
+        if (state.inFlightBootstrap) {
+            jsonResponse(res, 409, { error: "bootstrap already in progress" });
+            return;
+        }
+        const job = bootstrap();
+        state.inFlightBootstrap = job;
+        try {
+            const timings = await job;
+            jsonResponse(res, 200, { ok: true, timings });
+        }
+        finally {
+            state.inFlightBootstrap = null;
+        }
+        return;
+    }
+    if (method === "POST" && url === "/project-setup") {
+        if (state.inFlightProjectSetup) {
+            jsonResponse(res, 409, { error: "project-setup already in progress" });
+            return;
+        }
+        const job = runProjectSetup();
+        state.inFlightProjectSetup = job;
+        try {
+            const result = await job;
+            jsonResponse(res, 200, result);
+        }
+        finally {
+            state.inFlightProjectSetup = null;
+        }
+        return;
+    }
+    if (method === "POST" && url === "/eval") {
+        if (state.inFlightTest) {
+            jsonResponse(res, 409, { error: "a test or eval is already running" });
+            return;
+        }
+        const body = await readBody(req);
+        let parsed;
+        try {
+            parsed = JSON.parse(body || "{}");
+        }
+        catch {
+            jsonResponse(res, 400, { error: "invalid JSON body" });
+            return;
+        }
+        const code = parsed.code;
+        if (typeof code !== "string" || code.length === 0) {
+            jsonResponse(res, 400, { error: "code (string) is required" });
+            return;
+        }
+        // `secrets` are eval-scoped: the control plane resolves the loaded
+        // project's declared `replayFake` refs and pushes the values here on
+        // the eval path only. Never present on the /run (test) path.
+        const exec = evalCode(code, parsed.secrets);
+        state.inFlightTest = exec;
+        try {
+            const result = await exec;
+            jsonResponse(res, 200, result);
+        }
+        finally {
+            state.inFlightTest = null;
+        }
+        return;
+    }
+    if (method === "POST" && url === "/capture-log-baseline") {
+        // Snapshot each service's log output produced during env bring-up
+        // (container startup + project setup), advancing the log markers so the
+        // subsequent per-test deltas start AFTER setup. The control plane calls
+        // this once, on the main env, before the first test runs — see
+        // tests.rs::capture_log_baseline. Best-effort: on failure the setup lines
+        // simply fold into the first test's delta as before.
+        let serviceLogDeltas = [];
+        try {
+            serviceLogDeltas = await captureServiceLogDeltas();
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn("[service-logs] baseline capture failed:", err);
+        }
+        jsonResponse(res, 200, { serviceLogDeltas });
+        return;
+    }
+    if (method === "POST" && url === "/run") {
+        if (state.inFlightTest) {
+            jsonResponse(res, 409, { error: "another test is already running" });
+            return;
+        }
+        const body = await readBody(req);
+        let parsed;
+        try {
+            parsed = JSON.parse(body || "{}");
+        }
+        catch {
+            jsonResponse(res, 400, { error: "invalid JSON body" });
+            return;
+        }
+        const caseId = parsed.caseId;
+        if (!caseId) {
+            jsonResponse(res, 400, { error: "caseId is required" });
+            return;
+        }
+        const l = requireLoaded();
+        const tc = l.byId.get(caseId);
+        if (!tc) {
+            jsonResponse(res, 404, { error: `unknown caseId: ${caseId}` });
+            return;
+        }
+        const exec = runOne(tc);
+        state.inFlightTest = exec;
+        try {
+            const result = await exec;
+            // Recordings go out-of-band: encode + park the bundle, reply with a
+            // size ref only (see the REPLAY_BUNDLES comment). A bundle-encoding
+            // failure drops the recordings (warn) rather than failing the case —
+            // and never falls back to inlining, which is exactly the >16 MB
+            // response this path exists to avoid.
+            const { browserSessions, ...wire } = result;
+            let replay;
+            if (browserSessions.length > 0) {
+                try {
+                    const gz = encodeReplayBundle(caseId, browserSessions);
+                    stashReplayBundle(caseId, gz);
+                    replay = { bytes: gz.length };
+                }
+                catch (err) {
+                    // eslint-disable-next-line no-console
+                    console.warn("[replay] bundle encode failed; dropping recordings:", err);
+                }
+            }
+            jsonResponse(res, 200, { ...wire, replay });
+        }
+        finally {
+            state.inFlightTest = null;
+        }
+        return;
+    }
+    if (method === "POST" && url === "/replay-chunk") {
+        // One chunk of a parked replay bundle (see REPLAY_BUNDLES). POST with
+        // a JSON body — case ids are arbitrary user strings, and a body dodges
+        // URL-encoding across both providers' daemon_http transports.
+        const body = await readBody(req);
+        let parsed;
+        try {
+            parsed = JSON.parse(body || "{}");
+        }
+        catch {
+            jsonResponse(res, 400, { error: "invalid JSON body" });
+            return;
+        }
+        if (!parsed.caseId) {
+            jsonResponse(res, 400, { error: "caseId is required" });
+            return;
+        }
+        const gz = REPLAY_BUNDLES.get(parsed.caseId);
+        if (!gz) {
+            jsonResponse(res, 404, { error: `no replay bundle for case: ${parsed.caseId}` });
+            return;
+        }
+        jsonResponse(res, 200, replayChunk(gz, parsed.offset, parsed.limit));
+        return;
+    }
+    jsonResponse(res, 404, { error: "not found" });
+}
+async function main() {
+    const state = {
+        inFlightTest: null,
+        inFlightBootstrap: null,
+        inFlightProjectSetup: null,
+    };
+    const server = http.createServer((req, res) => {
+        handle(req, res, state).catch((err) => {
+            const e = err;
+            try {
+                jsonResponse(res, 500, { error: e.message ?? String(err), stack: e.stack });
+            }
+            catch {
+                // headers already sent or socket dead
+            }
+        });
+    });
+    const port = Number(process.env.SPECTEST_DAEMON_PORT ?? DEFAULT_PORT);
+    server.listen(port, "0.0.0.0", () => {
+        // eslint-disable-next-line no-console
+        console.log(`spectest-daemon listening on :${port} (idle; awaiting POST /load)`);
+    });
+}
+main().catch((err) => {
+    // eslint-disable-next-line no-console
+    console.error("spectest-daemon: fatal:", err);
+    process.exit(1);
+});