@specific.dev/spectest 0.39.0 → 0.43.0

package/dist/daemon.js

@@ -15,7 +15,6 @@
 // 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";
@@ -23,8 +22,25 @@ 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 { acquirePersistentBrowser, mobileKey } from "./browser.js";
 import { isMobileApp, openPersistentMobile } from "./mobile.js";
+// Pure ingress hostname matching, ported out of this file (see
+// harness/hostmatch.ts). Keeping ONE implementation is the point: the
+// exact-then-longest-suffix rule and the one-label certificate rule are
+// each easy to restate subtly differently.
+import { buildContentKey as computeBuildContentKey, imageTag, isGeneratedDockerignore, serviceDockerignore as composeServiceDockerignore, unionDockerignore, } from "./harness/build-context.js";
+import { validateServiceGraph as validateGraph } from "./harness/service-graph.js";
+import { summarizeBuildKit } from "./harness/buildkit-progress.js";
+import { LOG_DELTA_MAX_BYTES, capMiddle, streamDelta } from "./harness/log-delta.js";
+import { resolveHostPath as resolveVolumeHostPath, sanitizeSegment, } from "./harness/volume-paths.js";
+import { pollUntilReady } from "./harness/ready-poll.js";
+import { encodeRegistry } from "./harness/names-registry.js";
+import { HOP_BY_HOP_HEADERS, augmentCorsResponse, corsPreflightResponse, isCorsPreflight, } from "./harness/http-proxy.js";
+import { certCovers as hostmatchCertCovers, hostWithoutPort, matchRoute, wildcardSuffix, } from "./harness/hostmatch.js";
+import { INGRESS_HTTPS_PORT, INGRESS_HTTP_PORT, bindRoute, certEntries, clearTables, emptyTables, planBind, registryTarget, routesFor, unbindRoute, } from "./harness/ingress-table.js";
+import { runContainerArgs } from "./harness/container-run.js";
+import { assertAbsolute, certificateHostnames, defaultKeyMode, expandServiceToken, isNoopChown, mountFlag, needsIdTables, numericId, resolveChownIds, } from "./harness/file-mounts.js";
+import { conflict, notFound, requireString, } from "./harness/methods.js";
 import { openTerminal } from "./terminal.js";
 import { recordEnv, recordExec, recordFake, recordHttp, recordTerminal, recordWait, reserveEvent, recorderEventCount, recorderMarkChildren, recorderTruncate, startRecording, stopRecording, truncateUtf8, } from "./recorder.js";
 import { deepUnwrap, wrap, wrapResponse } from "./inspect.js";
@@ -33,7 +49,6 @@ 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";
@@ -422,44 +437,6 @@ async function ensureRemoteBuilder() {
     }
     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)
@@ -469,43 +446,11 @@ async function ensureNetwork() {
         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, "");
-}
+/** Host directory backing one volume mount. Rules (notably which volumes
+ *  survive the delta-restore teardown) live in `harness/volume-paths.ts`. */
 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));
+    return resolveVolumeHostPath(service, vol, WORKSPACE);
 }
-/// 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) {
@@ -628,12 +573,9 @@ async function imageIdTables(tag) {
 async function resolveOwner(svc, tag, what, user, group) {
     if (user === undefined && group === undefined)
         return undefined;
-    const numeric = (v) => v !== undefined && /^[0-9]+$/.test(v) ? Number(v) : undefined;
-    let uid = numeric(user);
-    let gid = numeric(group);
-    const needsTables = (user !== undefined && uid === undefined) ||
-        (group !== undefined && gid === undefined);
-    if (needsTables) {
+    let uid = numericId(user);
+    let gid = numericId(group);
+    if (needsIdTables(user, group)) {
         const tables = await imageIdTables(tag);
         if (user !== undefined && uid === undefined) {
             uid = tables.users.get(user);
@@ -665,16 +607,12 @@ async function resolveOwner(svc, tag, what, user, group) {
 async function applyFileOwnership(file, mode, owner) {
     if (mode)
         await fs.chmod(file, parseInt(mode, 8));
-    if (!owner)
+    if (!owner || isNoopChown(owner))
         return;
-    let { uid, gid } = owner;
-    if (uid < 0 || gid < 0) {
-        const st = await fs.stat(file);
-        if (uid < 0)
-            uid = st.uid;
-        if (gid < 0)
-            gid = st.gid;
-    }
+    // Bun rejects the `-1` halves, so fill them from the file's current
+    // owner — see `harness/file-mounts.ts` for the rule and its test.
+    const st = await fs.stat(file);
+    const { uid, gid } = resolveChownIds(owner, { uid: st.uid, gid: st.gid });
     await fs.chown(file, uid, gid);
 }
 // Materialize `svc.files` onto the VM host and return `--volume` flags
@@ -691,14 +629,12 @@ async function ensureFiles(svc, tag) {
     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`);
-        }
+        assertAbsolute(svc.name, "file path", f.path);
         // `{{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 content = expandServiceToken(f.content, svc.name);
         const host = path.join(dir, sanitizeSegment(f.path));
         await fs.writeFile(host, content);
         // A bind mount carries this inode's mode and ownership into the
@@ -707,7 +643,7 @@ async function ensureFiles(svc, tag) {
         // whoever the container actually runs as.
         const owner = await resolveOwner(svc, tag, `file ${f.path}`, f.user, f.group);
         await applyFileOwnership(host, f.mode, owner);
-        flags.push(`--volume=${host}:${f.path}:ro`);
+        flags.push(mountFlag(host, f.path));
     }
     return flags;
 }
@@ -742,14 +678,9 @@ async function ensureCertificates(svc, tag) {
             ["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`);
+            assertAbsolute(svc.name, `certificate ${label}`, p);
         }
+        const hostnames = certificateHostnames(svc.name, i, c.hostnames);
         const { cert, key } = await generateHostCert(`${svc.name}-${i}`, hostnames);
         const certHost = path.join(dir, `${i}.crt`);
         const keyHost = path.join(dir, `${i}.key`);
@@ -765,43 +696,19 @@ async function ensureCertificates(svc, tag) {
         // Declaring who reads the key also says what mode it wants: the
         // strictest one that owner can still open. Only reached when
         // `user`/`group` is set, so no existing environment changes.
-        const keyMode = c.mode ?? (owner ? (owner.uid === -1 ? "0640" : "0600") : undefined);
+        const keyMode = defaultKeyMode(c.mode, owner);
         await applyFileOwnership(keyHost, keyMode, owner);
         // The certificate is public, but it follows the key's owner so a
         // server that insists on owning its whole TLS directory is happy.
         await applyFileOwnership(certHost, undefined, owner);
-        flags.push(`--volume=${certHost}:${c.certPath}:ro`);
-        flags.push(`--volume=${keyHost}:${c.keyPath}:ro`);
+        flags.push(mountFlag(certHost, c.certPath));
+        flags.push(mountFlag(keyHost, c.keyPath));
         if (c.caPath)
-            flags.push(`--volume=${CA_PATH}:${c.caPath}:ro`);
+            flags.push(mountFlag(CA_PATH, c.caPath));
         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.
@@ -819,7 +726,7 @@ 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))
+        if (isGeneratedDockerignore(text))
             return null;
         return text;
     }
@@ -827,39 +734,11 @@ async function readProjectDockerignore() {
         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.
- */
+/** Ignore rules for one dockerfile build. Composition (and the reason the
+ *  order matters) lives in `harness/build-context.ts`; this supplies the
+ *  project's own file, read once per bootstrap. */
 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");
+    return composeServiceDockerignore(PROJECT_DOCKERIGNORE, exclude);
 }
 /// In-flight/finished dockerfile builds of this bootstrap, keyed by
 /// sha256(dockerfile content + exclude list). Services that share an
@@ -870,11 +749,7 @@ function unionDockerignore(services) {
 /// 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");
+    return computeBuildContentKey(() => new Bun.CryptoHasher("sha256"), image);
 }
 async function prepareServiceImage(svc, opts) {
     const tag = imageTag(svc.name);
@@ -1121,106 +996,21 @@ async function runContainer(svc, tag, volumeFlags,
 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`);
-    // Appends to the image's roots, so it takes the bare CA.
-    args.push("-e", `NODE_EXTRA_CA_CERTS=${CA_PATH}`);
-    // These three REPLACE the roots — they must get the combined bundle or
-    // the container loses every public CA (see CA_BUNDLE_PATH).
-    const caBundle = await ensureCaBundle();
-    if (caBundle) {
-        if (caBundle !== CA_PATH)
-            args.push(`--volume=${caBundle}:${caBundle}:ro`);
-        args.push("-e", `SSL_CERT_FILE=${caBundle}`);
-        args.push("-e", `REQUESTS_CA_BUNDLE=${caBundle}`);
-        args.push("-e", `AWS_CA_BUNDLE=${caBundle}`);
-    }
-    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);
+    // The argv, and every rule shaping it, lives in `harness/container-run.ts`
+    // so it can be asserted without starting a container.
+    const args = runContainerArgs({
+        svc,
+        tag,
+        network: NETWORK_NAME,
+        aliases: [...(LOWERED.aliasesByService[svc.name] ?? []), ...extraAliases],
+        volumeFlags,
+        ingressHosts: LOWERED.ingressHosts,
+        gatewayIp: cachedGatewayIp,
+        hostCacheGateway: hostCacheGateway(),
+        hostCacheName: SPECTEST_HOST_NAME,
+        caPath: CA_PATH,
+        caBundle: await ensureCaBundle(),
+    });
     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()}`);
@@ -1274,78 +1064,27 @@ async function waitForReady(svc) {
     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);
+    const probe = async () => {
+        if (check.type === "tcp")
+            return probeTcp(svc.name, check.port);
+        if (check.type === "http") {
+            return 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));
-    }
+        return probeExec(svc.name, check.command);
+    };
+    // Scheduling (the ramp, and not sleeping past the deadline) lives in
+    // `harness/ready-poll.ts`; this supplies the probe and the diagnosis.
+    const { ready } = await pollUntilReady(probe, { kind: check.type, timeoutSecs });
+    if (ready)
+        return;
     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.
- */
+/** Validate the `dependsOn` graph and return the name→service map used to
+ *  walk it. Rules live in `harness/service-graph.ts`. */
 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;
+    return validateGraph(services);
 }
-/**
- * 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();
@@ -1390,11 +1129,6 @@ async function startServices(services, startOne) {
 // ────────────────────────────────────────────────────────────────────────
 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`. */
@@ -1416,31 +1150,36 @@ const INGRESS_HTTP_SERVERS = new Map();
 // 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.
+ * The live ingress tables — per-port routes and the :443 SNI cert table.
+ *
+ * The shape, the lookup rules and the "does this bind cost a rebind?"
+ * decision live in `harness/ingress-table.ts`; this is the one instance the
+ * daemon process owns. It is module state on purpose: it forks with the
+ * snapshot, exactly like fake state and the names REGISTRY, which is what
+ * lets a route bound mid-test be inherited by a `dependsOn` child and stay
+ * invisible to its siblings. Rebuilt on /load (see {@link stopIngressServers}).
  */
-const HTTPS_CERT_BY_HOST = new Map();
+const INGRESS = emptyTables();
 /**
  * Tear down listener servers between /load calls so the new project's
  * routes can rebind cleanly.
  */
+/**
+ * Tear the listeners down between `/load` calls.
+ *
+ * Force-closes rather than draining, deliberately. Every listener now sets
+ * SO_REUSEPORT so a replacement can overlap the original during a cert
+ * rebind ({@link rebindHttpsListener}) — but that also means a listener
+ * left half-alive here would no longer collide with the next project's
+ * bind. It would quietly share the port instead, and the kernel would hand
+ * some connections to the old project's route table. A drain is right for a
+ * rebind, where both listeners serve the same environment; it is wrong
+ * here, where the containers behind those routes are being removed anyway.
+ */
 function stopIngressServers() {
     for (const [port, srv] of INGRESS_HTTP_SERVERS) {
         try {
-            srv.stop?.();
+            srv.stop?.(true);
         }
         catch (err) {
             // eslint-disable-next-line no-console
@@ -1450,7 +1189,7 @@ function stopIngressServers() {
     INGRESS_HTTP_SERVERS.clear();
     for (const [port, srv] of INGRESS_HTTPS_SERVERS) {
         try {
-            srv.stop?.();
+            srv.stop?.(true);
         }
         catch (err) {
             // eslint-disable-next-line no-console
@@ -1458,8 +1197,7 @@ function stopIngressServers() {
         }
     }
     INGRESS_HTTPS_SERVERS.clear();
-    INGRESS_ROUTES_BY_PORT.clear();
-    HTTPS_CERT_BY_HOST.clear();
+    clearTables(INGRESS);
 }
 function buildIngress(project) {
     stopIngressServers();
@@ -1574,98 +1312,6 @@ async function bridgeGatewayIp() {
  */
 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 ||
@@ -1706,7 +1352,7 @@ async function startIngress() {
                 continue;
             const leaf = await generateHostCert(group.hostnames[0], group.hostnames);
             for (const h of group.hostnames)
-                HTTPS_CERT_BY_HOST.set(h, leaf);
+                INGRESS.certByHost.set(h, leaf);
         }
     }
     else if (LOWERED.certificates.length > 0) {
@@ -1718,11 +1364,7 @@ async function startIngress() {
     // 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;
-    };
+    const ensurePort = (port) => routesFor(INGRESS, port);
     for (const fake of FAKES.values()) {
         if (fake.port === INGRESS_HTTPS_PORT)
             continue;
@@ -1740,7 +1382,7 @@ async function startIngress() {
     // covers — exactly, or through a wildcard SAN, so `*.example.com` in a
     // service's `tls` also puts an unrelated exact `api.example.com` route on
     // HTTPS. Proxies are applied after fakes so a proxy wins a shared host.
-    if (HTTPS_CERT_BY_HOST.size > 0) {
+    if (INGRESS.certByHost.size > 0) {
         const httpsRoutes = ensurePort(INGRESS_HTTPS_PORT);
         for (const fake of FAKES.values()) {
             for (const h of fake.hostnames) {
@@ -1755,7 +1397,7 @@ async function startIngress() {
         }
     }
     // ── HTTP listeners (one per non-443 port).
-    for (const [port, byHost] of INGRESS_ROUTES_BY_PORT) {
+    for (const [port, byHost] of INGRESS.routesByPort) {
         if (port === INGRESS_HTTPS_PORT)
             continue;
         INGRESS_HTTP_SERVERS.set(port, bindIngressServer(Bun, port, byHost, `port ${port}`));
@@ -1763,7 +1405,7 @@ async function startIngress() {
         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)
+    if (INGRESS.certByHost.size > 0)
         rebindHttpsListener(Bun);
     // Seed the resolver's names registry: ingress hostnames (fakes, TLS
     // proxies, dnsName(→ingress)) → bridge gateway, plus ingress-targeted
@@ -1780,37 +1422,61 @@ function requireBun() {
     }
     return Bun;
 }
-/** Flatten {@link HTTPS_CERT_BY_HOST} into Bun's TLS-entry SNI array. */
+/** Flatten the live SNI cert table into Bun's TLS-entry array. */
 function tlsEntriesFromCerts() {
-    return [...HTTPS_CERT_BY_HOST].map(([serverName, leaf]) => ({
-        cert: leaf.cert,
-        key: leaf.key,
-        serverName,
-    }));
+    return certEntries(INGRESS);
 }
 /**
- * (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.
+ * (Re)bind the :443 listener from the current cert table + route map.
+ *
+ * Bun fixes a server's TLS config at `Bun.serve` time — `reload()` accepts a
+ * new `tls` option and silently keeps serving the old certificates (measured
+ * on Bun 1.3.14: after reloading with a second SNI entry, the new hostname
+ * still gets the first one's leaf). So adding a certificate really does mean
+ * a second listener.
+ *
+ * **Bind the new one before stopping the old one.** Doing it the other way
+ * round — which is what this used to do, with `stop(true)` — has two teeth:
+ * the force-close kills every established connection on :443, and the gap
+ * before the new listener binds refuses new ones. Neither is limited to the
+ * hostname being added; they hit all the unrelated traffic the listener is
+ * carrying. On a project that mints a certificate per provisioned database
+ * while deploys stream through the same port, that surfaced as the app under
+ * test dying with `SocketError: other side closed` or `ECONNREFUSED
+ * <gateway>:443` — a different test each run, and nothing pointing at
+ * ingress.
+ *
+ * Overlapping the two needs SO_REUSEPORT on both sockets ({@link
+ * bindIngressServer} sets it unconditionally for that reason), after which
+ * the old listener is drained with `stop(false)` so requests in flight
+ * finish. During the overlap the kernel may hand a new connection to either
+ * socket, which is safe: the only hostname the two disagree about is the one
+ * being added, and it does not resolve until the caller writes the names
+ * registry after this returns.
+ *
+ * The route Map is the persistent module object, so the new listener closes
+ * over the same table and later route additions need no rebind at all.
  */
 // 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);
+    // The *same* table object the previous listener closed over: the new
+    // listener must serve the routes bound since, and any bound later.
+    const routes = routesFor(INGRESS, INGRESS_HTTPS_PORT);
     const old = INGRESS_HTTPS_SERVERS.get(INGRESS_HTTPS_PORT);
+    const server = bindIngressServer(Bun, INGRESS_HTTPS_PORT, routes, `https :${INGRESS_HTTPS_PORT}`, tlsEntriesFromCerts());
     if (old) {
         try {
-            old.stop(true);
+            // Graceful: stop accepting, let in-flight requests finish. The old
+            // server stays alive until they do, which is the point — a long
+            // upload through ingress must not be collateral damage of another
+            // service being provisioned.
+            old.stop(false);
         }
         catch (err) {
             // eslint-disable-next-line no-console
-            console.warn("[ingress] failed to stop https listener for rebind:", err);
+            console.warn("[ingress] failed to drain the previous https listener:", 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(", ")}`);
@@ -1822,23 +1488,11 @@ function rebindHttpsListener(Bun) {
  * client stops at one label. Claiming a deeper name is covered would skip
  * minting the leaf it actually needs and hand it a cert it rejects.
  */
-function wildcardCoversHost(pattern, hostname) {
-    const suffix = wildcardSuffix(pattern); // "*.example.com" → ".example.com"
-    if (!hostname.endsWith(suffix))
-        return false;
-    const label = hostname.slice(0, -suffix.length);
-    return label.length > 0 && !label.includes(".");
-}
-/** True if an exact or wildcard cert already covers `hostname` for SNI. */
+/** True if an exact or wildcard cert already covers `hostname` for SNI.
+ *  The matching rules live in `harness/hostmatch.ts`; this just supplies
+ *  the live cert table. */
 function certCovers(hostname) {
-    if (HTTPS_CERT_BY_HOST.has(hostname))
-        return true;
-    for (const serverName of HTTPS_CERT_BY_HOST.keys()) {
-        if (isWildcard(serverName) && wildcardCoversHost(serverName, hostname)) {
-            return true;
-        }
-    }
-    return false;
+    return hostmatchCertCovers(INGRESS.certByHost.keys(), hostname);
 }
 /**
  * Bind a runtime ingress route for one `tls: [{ hostname, port }]` entry on a
@@ -1863,38 +1517,37 @@ async function bindRuntimeTls(hostname, service, port) {
     }
     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);
+    // Decide the cost before mutating anything: an already-covered hostname
+    // (an exact duplicate, or one under a boot wildcard) needs only a route.
+    const plan = planBind(INGRESS, host, {
+        httpsListening: INGRESS_HTTPS_SERVERS.has(INGRESS_HTTPS_PORT),
+    });
+    // Routes go in before the certificate is minted, not after. Minting
+    // shells out to openssl and takes on the order of a second, and both
+    // schemes are already serving other hosts — so binding first means
+    // `http://<host>/` starts working immediately instead of 404ing for the
+    // length of an RSA keygen. Nothing here can observe a half-bound state:
+    // the route is only reachable once the hostname resolves, which is the
+    // registry write at the end.
+    bindRoute(INGRESS, 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}`));
+        INGRESS_HTTP_SERVERS.set(INGRESS_HTTP_PORT, bindIngressServer(Bun, INGRESS_HTTP_PORT, routesFor(INGRESS, INGRESS_HTTP_PORT), `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]));
+    if (plan.needsCert) {
+        INGRESS.certByHost.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)) {
+    if (plan.needsHttpsRebind)
         rebindHttpsListener(Bun);
-    }
     // Resolve the hostname to the daemon gateway (where :443/:80 listen).
     // A wildcard can only live in the resolver's suffix table.
     const gw = await bridgeGatewayIp();
-    if (isWildcard(host)) {
-        const suffix = wildcardSuffix(host);
-        REGISTRY.wildcards = REGISTRY.wildcards.filter((w) => w.suffix !== suffix);
-        REGISTRY.wildcards.push({ suffix, ip: gw });
+    const target = registryTarget(host);
+    if (target.wildcard) {
+        REGISTRY.wildcards = REGISTRY.wildcards.filter((w) => w.suffix !== target.suffix);
+        REGISTRY.wildcards.push({ suffix: target.suffix, ip: gw });
     }
     else {
-        REGISTRY.hosts[host] = gw;
+        REGISTRY.hosts[target.host] = gw;
     }
     await writeRegistry();
     // eslint-disable-next-line no-console
@@ -1908,17 +1561,16 @@ async function bindRuntimeTls(hostname, service, port) {
  */
 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 (isWildcard(host)) {
-        const suffix = wildcardSuffix(host);
+    unbindRoute(INGRESS, host);
+    const target = registryTarget(host);
+    if (target.wildcard) {
         const before = REGISTRY.wildcards.length;
-        REGISTRY.wildcards = REGISTRY.wildcards.filter((w) => w.suffix !== suffix);
+        REGISTRY.wildcards = REGISTRY.wildcards.filter((w) => w.suffix !== target.suffix);
         if (REGISTRY.wildcards.length !== before)
             await writeRegistry();
     }
-    else if (host in REGISTRY.hosts) {
-        delete REGISTRY.hosts[host];
+    else if (target.host in REGISTRY.hosts) {
+        delete REGISTRY.hosts[target.host];
         await writeRegistry();
     }
 }
@@ -1942,6 +1594,12 @@ Bun, port, byHost, listenerLabel, tlsEntries) {
     const opts = {
         port,
         hostname: "0.0.0.0",
+        // SO_REUSEPORT on every ingress listener, so a replacement can be bound
+        // while the old one is still serving. That overlap is the only way to
+        // add an SNI certificate without a gap — see {@link rebindHttpsListener}
+        // — and it only works if *both* sockets opt in: a second plain bind
+        // fails with "Is port 443 in use?".
+        reusePort: true,
         // 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
@@ -2046,21 +1704,7 @@ Bun, port, byHost, listenerLabel, tlsEntries) {
  * present a valid cert over `https://`.
  */
 function matchIngressRoute(byHost, host) {
-    const exact = byHost.get(host);
-    if (exact)
-        return exact;
-    let best;
-    let bestLen = -1;
-    for (const [pattern, route] of byHost) {
-        if (!isWildcard(pattern))
-            continue;
-        const suffix = wildcardSuffix(pattern);
-        if (host.endsWith(suffix) && suffix.length > bestLen) {
-            best = route;
-            bestLen = suffix.length;
-        }
-    }
-    return best;
+    return matchRoute(byHost, host);
 }
 /**
  * Per-request dispatch shared by every ingress listener. Looks up the
@@ -2072,10 +1716,9 @@ function matchIngressRoute(byHost, host) {
 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();
+    // `hostWithoutPort` rather than split(":")[0]: the naive form turns an
+    // IPv6 literal Host (`[::1]:8080`) into "[".
+    const host = hostWithoutPort((req.headers.get("host") ?? "").toLowerCase());
     const route = matchIngressRoute(byHost, 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" } });
@@ -2262,11 +1905,9 @@ server, service, port, listenerLabel, proto) {
  */
 const REGISTRY = { hosts: {}, wildcards: [] };
 async function writeRegistry() {
-    const body = JSON.stringify({
-        hosts: REGISTRY.hosts,
-        wildcards: REGISTRY.wildcards,
-        updatedAt: Date.now(),
-    });
+    // Format + lookup semantics live in `harness/names-registry.ts`, shared
+    // with the resolver that reads this file.
+    const body = encodeRegistry(REGISTRY, Date.now());
     try {
         await fs.mkdir(path.dirname(FAKES_REGISTRY_PATH), { recursive: true });
         await fs.writeFile(FAKES_REGISTRY_PATH, body);
@@ -2278,9 +1919,6 @@ async function writeRegistry() {
     }
 }
 /** `*.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) {
@@ -2937,11 +2575,6 @@ function stashReplayBundle(caseId, gz) {
  * 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
@@ -2961,68 +2594,6 @@ async function containerStopState(name) {
  *  `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)
@@ -3115,6 +2686,19 @@ function newArtifactCollector() {
         },
     };
 }
+/**
+ * Normalise `ctx.browser(...)`'s two call shapes — `(opts?)` for the
+ * default session and `(name, opts?)` for a named one — into the
+ * `(name, opts)` pair the session registry keys on. The overloads make
+ * these the only two shapes that typecheck, but the implementation still
+ * has to tell them apart at runtime: an untyped caller (`eval`, plain JS)
+ * reaches the same function.
+ */
+function browserArgs(nameOrOpts, opts) {
+    return typeof nameOrOpts === "string"
+        ? { name: nameOrOpts, opts }
+        : { name: "", opts: nameOrOpts };
+}
 /**
  * Build the recorder sink + bookkeeping for a single Browser session.
  * The returned `recorder` is what `openBrowser` writes into; the
@@ -3123,11 +2707,15 @@ function newArtifactCollector() {
  * test-run sessions don't pass it, which is exactly what makes
  * `screenshot()` throw outside eval.
  */
-function newBrowserSession(testStart, idScope, frame = "browser", artifacts) {
+function newBrowserSession(testStart, idScope, frame = "browser", artifacts, name = "") {
     const record = {
         sessionId: newSessionId(idScope),
         openedAtMs: Date.now() - testStart,
         frame,
+        // Omit the key entirely for the default session rather than storing
+        // `""` — every consumer treats "no name" as "don't render a label",
+        // and an empty string would have to be special-cased in each of them.
+        ...(name ? { name } : {}),
         steps: [],
     };
     let closed = false;
@@ -3135,6 +2723,7 @@ function newBrowserSession(testStart, idScope, frame = "browser", artifacts) {
         record,
         recorder: {
             sessionId: record.sessionId,
+            ...(name ? { sessionName: name } : {}),
             recordStep(step) {
                 if (closed)
                     return;
@@ -3966,31 +3555,37 @@ async function runOne(testCase) {
     // 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
+    // Browser/mobile sessions are PERSISTENT and keyed by NAME:
+    // `ctx.browser(name?)` acquires the desktop browser called `name` and
+    // `ctx.mobile(app, name?)` that name's session for that app (browser.ts's
+    // module-scoped registry, which forks with the snapshot like fake state).
+    // The default name is `""`, so an unnamed project has exactly the one
+    // session per device it always had. 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.
+    // children resume the live pages (cookies, localStorage, signed-in SPA
+    // state) instead of re-navigating; that inheritance is per name, so a
+    // parent that signed "alice" and "bob" in hands both down. Each test
+    // still gets its own session record per name (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
+    // calls for the SAME name return the same handle (memoized below) so one
+    // test = one session per (device, name). An explicit `.close()` destroys
+    // that name's instance — its memo entry is cleared so a later call for
+    // the same name starts fresh, and other names are untouched.
     const browserDetaches = [];
     const sessions = [];
-    let sharedBrowser = null;
+    const sharedBrowsers = new Map();
     const sharedMobiles = new Map();
-    const trackedOpenBrowser = async (opts) => {
-        if (sharedBrowser)
-            return sharedBrowser;
-        const session = newBrowserSession(start, testCase.id);
+    const trackedOpenBrowser = async (nameOrOpts, maybeOpts) => {
+        const { name, opts } = browserArgs(nameOrOpts, maybeOpts);
+        const memo = sharedBrowsers.get(name);
+        if (memo)
+            return memo;
+        const session = newBrowserSession(start, testCase.id, "browser", undefined, name);
         sessions.push(session);
-        const { browser, attached, detach } = await acquirePersistentBrowser({
+        const { browser, attached, detach } = await acquirePersistentBrowser(name, {
             ...(opts ?? {}),
             recorder: session.recorder,
         });
@@ -4009,23 +3604,25 @@ async function runOne(testCase) {
         const innerClose = browser.close.bind(browser);
         browser.close = async () => {
             await innerClose();
-            if (sharedBrowser === browser)
-                sharedBrowser = null;
+            if (sharedBrowsers.get(name) === browser)
+                sharedBrowsers.delete(name);
         };
-        sharedBrowser = browser;
+        sharedBrowsers.set(name, browser);
         return browser;
     };
-    const trackedOpenMobile = async (app) => {
+    const trackedOpenMobile = async (app, name = "") => {
         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);
+        const key = mobileKey(name, app.url);
+        const existing = sharedMobiles.get(key);
         if (existing)
             return existing;
-        const session = newBrowserSession(start, testCase.id, "mobile");
+        const session = newBrowserSession(start, testCase.id, "mobile", undefined, name);
         sessions.push(session);
         const { mobile, attached, detach, safeAreaInsets } = await openPersistentMobile({
             url: app.url,
+            name,
             recorder: session.recorder,
             initScript: app.initScript,
         });
@@ -4041,10 +3638,10 @@ async function runOne(testCase) {
         const innerClose = mobile.close.bind(mobile);
         mobile.close = async () => {
             await innerClose();
-            if (sharedMobiles.get(app.url) === mobile)
-                sharedMobiles.delete(app.url);
+            if (sharedMobiles.get(key) === mobile)
+                sharedMobiles.delete(key);
         };
-        sharedMobiles.set(app.url, mobile);
+        sharedMobiles.set(key, mobile);
         return mobile;
     };
     // The shared context (svc/fakes handles, poll, project files, dnsName,
@@ -4404,14 +4001,16 @@ async function evalCode(code, secrets) {
     // 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 sharedBrowsers = new Map();
     const sharedMobiles = new Map();
-    const trackedOpenBrowser = async (opts) => {
-        if (sharedBrowser)
-            return sharedBrowser;
-        const session = newBrowserSession(start, "eval", "browser", artifactCollector);
+    const trackedOpenBrowser = async (nameOrOpts, maybeOpts) => {
+        const { name, opts } = browserArgs(nameOrOpts, maybeOpts);
+        const memo = sharedBrowsers.get(name);
+        if (memo)
+            return memo;
+        const session = newBrowserSession(start, "eval", "browser", artifactCollector, name);
         sessions.push(session);
-        const { browser, attached, detach } = await acquirePersistentBrowser({
+        const { browser, attached, detach } = await acquirePersistentBrowser(name, {
             ...(opts ?? {}),
             recorder: session.recorder,
         });
@@ -4428,23 +4027,25 @@ async function evalCode(code, secrets) {
         const innerClose = browser.close.bind(browser);
         browser.close = async () => {
             await innerClose();
-            if (sharedBrowser === browser)
-                sharedBrowser = null;
+            if (sharedBrowsers.get(name) === browser)
+                sharedBrowsers.delete(name);
         };
-        sharedBrowser = browser;
+        sharedBrowsers.set(name, browser);
         return browser;
     };
-    const trackedOpenMobile = async (app) => {
+    const trackedOpenMobile = async (app, name = "") => {
         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);
+        const key = mobileKey(name, app.url);
+        const existing = sharedMobiles.get(key);
         if (existing)
             return existing;
-        const session = newBrowserSession(start, "eval", "mobile", artifactCollector);
+        const session = newBrowserSession(start, "eval", "mobile", artifactCollector, name);
         sessions.push(session);
         const { mobile, attached, detach, safeAreaInsets } = await openPersistentMobile({
             url: app.url,
+            name,
             recorder: session.recorder,
             initScript: app.initScript,
         });
@@ -4460,10 +4061,10 @@ async function evalCode(code, secrets) {
         const innerClose = mobile.close.bind(mobile);
         mobile.close = async () => {
             await innerClose();
-            if (sharedMobiles.get(app.url) === mobile)
-                sharedMobiles.delete(app.url);
+            if (sharedMobiles.get(key) === mobile)
+                sharedMobiles.delete(key);
         };
-        sharedMobiles.set(app.url, mobile);
+        sharedMobiles.set(key, mobile);
         return mobile;
     };
     // Terminal sessions — same shape as runOne, but eval has no active
@@ -4734,344 +4335,220 @@ async function runTypecheck() {
     }
     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);
-    });
+/** Run `job` under a mutual-exclusion slot, refusing if one is held. */
+async function exclusive(state, slot, busy, job) {
+    if (state[slot])
+        throw conflict(busy);
+    const p = job();
+    state[slot] = p;
+    try {
+        return await p;
+    }
+    finally {
+        state[slot] = null;
+    }
 }
-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);
+/** The environment's current catalogue, the shape three methods return. */
+function loadedSummary(l) {
+    return {
+        environment: l.project.environment,
+        cases: casesMetadata(l.project.tests),
+        fakes: fakesSummary(l.project),
+    };
 }
-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") {
+/**
+ * Everything the harness can be asked to do.
+ *
+ * Transport-neutral by construction: params in, plain result out, failures
+ * as {@link HarnessError}. The HTTP router below and the supervisor's frame
+ * dispatcher both drive this same table, so a change reaches both — which
+ * is the property that makes it safe to run the two side by side during the
+ * cutover.
+ */
+export function harnessMethods(state) {
+    return {
+        health: async () => ({ ok: true }),
         // 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") {
+        // `bootstrap` and streamed into the test-run row. `{}` before the
+        // first bootstrap of this harness process.
+        progress: async () => BOOTSTRAP_PROGRESS ?? {},
+        /**
+         * Live logs for a running environment: the harness's own boot log
+         * (bootstrap plus every `setup` hook's console output) and each
+         * service's container logs.
+         *
+         * Reads without touching LOG_MARKERS, unlike the per-case deltas, so
+         * watching an environment can never perturb a run in progress.
+         */
+        envLogs: async (params) => {
+            const only = typeof params.service === "string" ? params.service : undefined;
+            const tail = Math.max(1, Math.min(10_000, Number(params.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) {
+                throw notFound(`unknown service ${JSON.stringify(only)}; known: ${[...byName.keys()].join(", ") || "(none)"}`);
+            }
+            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,
+                };
+            }));
+            return { bootLog: bootLogText(), services };
+        },
         // 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") {
+        // split layout it stays empty until `loadTests`.
+        load: async () => {
+            const proj = await loadEnv();
+            return {
+                environment: proj.environment,
+                cases: casesMetadata(proj.tests),
+                fakes: fakesSummary(proj),
+            };
+        },
         // 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)
+        loadTests: async () => {
+            await loadTests();
+            // Background typecheck of the freshly-uploaded app tree — both paths
+            // funnel through here after the upload, so the check always sees the
+            // current code. Never on the critical path: this reply doesn't wait,
+            // `typecheck` collects.
             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") {
+            return loadedSummary(requireLoaded());
+        },
+        // Await the run kicked off at loadTests, or start one on demand — a
+        // legacy single-file project loaded before the kickoff shipped, or a
+        // direct debug call.
+        typecheck: async () => {
+            if (!TYPECHECK)
+                startTypecheck();
+            return await TYPECHECK;
+        },
+        unload: async () => {
+            loaded = null;
+            return { unloaded: true };
+        },
         // 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") {
+        reload: async () => {
+            await loadEnv();
+            await loadTests();
+            return loadedSummary(requireLoaded());
+        },
+        envConfig: async () => requireLoaded().project.environment,
+        cases: async () => ({ cases: casesMetadata(requireLoaded().project.tests) }),
         // 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);
-                }
+        // `secretRefs`). The control plane resolves these server-side and pushes
+        // the values on the eval path only. Empty if nothing's loaded.
+        recordSecretRefs: async () => {
+            const refs = new Set();
+            for (const fake of FAKES.values()) {
+                for (const ref of fake.def.secretRefs ?? [])
+                    refs.add(ref);
             }
-            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;
+            return { refs: [...refs] };
+        },
+        bootstrap: async () => exclusive(state, "inFlightBootstrap", "bootstrap already in progress", async () => ({
+            ok: true,
+            timings: await bootstrap(),
+        })),
+        projectSetup: async () => exclusive(state, "inFlightProjectSetup", "project-setup already in progress", () => runProjectSetup()),
+        eval: async (params) => {
+            const code = requireString(params, "code");
+            // `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 test path.
+            const secrets = params.secrets;
+            return exclusive(state, "inFlightTest", "a test or eval is already running", () => evalCode(code, secrets));
+        },
+        /**
+         * Snapshot each service's log output produced during env bring-up
+         * (container startup plus project setup), advancing the log markers so
+         * the per-test deltas start *after* setup. The control plane calls this
+         * once, on the main env, before the first test runs.
+         *
+         * Best-effort: on failure the setup lines simply fold into the first
+         * test's delta, as they did before this existed.
+         */
+        captureLogBaseline: async () => {
+            let serviceLogDeltas = [];
             try {
-                jsonResponse(res, 500, { error: e.message ?? String(err), stack: e.stack });
+                serviceLogDeltas = await captureServiceLogDeltas();
             }
-            catch {
-                // headers already sent or socket dead
+            catch (err) {
+                // eslint-disable-next-line no-console
+                console.warn("[service-logs] baseline capture failed:", err);
             }
-        });
-    });
-    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)`);
-    });
+            return { serviceLogDeltas };
+        },
+        run: async (params) => {
+            const caseId = requireString(params, "caseId", "caseId");
+            const tc = requireLoaded().byId.get(caseId);
+            if (!tc)
+                throw notFound(`unknown caseId: ${caseId}`);
+            return exclusive(state, "inFlightTest", "another test is already running", async () => {
+                const result = await runOne(tc);
+                // Recordings go out-of-band: encode and park the bundle, reply with
+                // a size ref only. A bundle-encoding failure drops the recordings
+                // (with a warning) rather than failing the case — and never falls
+                // back to inlining, which is exactly the oversized reply 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);
+                    }
+                }
+                return { ...wire, replay };
+            });
+        },
+        // One chunk of a parked replay bundle. Case ids are arbitrary user
+        // strings, so they travel in params rather than a URL path.
+        replayChunk: async (params) => {
+            const caseId = requireString(params, "caseId", "caseId");
+            const gz = REPLAY_BUNDLES.get(caseId);
+            if (!gz)
+                throw notFound(`no replay bundle for case: ${caseId}`);
+            return replayChunk(gz, params.offset, params.limit);
+        },
+    };
 }
-main().catch((err) => {
-    // eslint-disable-next-line no-console
-    console.error("spectest-daemon: fatal:", err);
-    process.exit(1);
+/**
+ * The method table for this process.
+ *
+ * Built once, so the mutual-exclusion slots are process-wide: `run` refuses
+ * a second case while one is in flight, and that guarantee has to hold for
+ * the process, not per caller. Two tables would each enforce the rule and
+ * together break it — which is why this is a value and not a factory the
+ * caller invokes.
+ *
+ * The harness (`sdk/src/harness/main.ts`) serves this over frames. It used
+ * to be served over HTTP as well, by a listener in this file; that was the
+ * in-VM daemon, and it is gone.
+ */
+export const METHODS = harnessMethods({
+    inFlightTest: null,
+    inFlightBootstrap: null,
+    inFlightProjectSetup: null,
 });