@specific.dev/spectest 0.58.0 → 0.59.0

package/src/coverage.ts

@@ -0,0 +1,327 @@
+// Coverage adapters — how spectest gets a coverage report out of a service.
+//
+// A service opts in with `coverage: true` (the program writes its own
+// reports into `/spectest/coverage/`) or `coverage: { adapters: [...] }`
+// (spectest gets the reports out). An adapter has three optional moments:
+//
+//   configure  — config time, inside `defineEnvironment`. Rewrites the
+//                service (env, files, command). Pure: its output is part
+//                of the wire config and of the warm-template hash.
+//   load       — harness, at /load. Asks the harness for capabilities a
+//                container cannot supply itself (browser scripts).
+//   capture    — harness, after bring-up and after every test. Must leave
+//                a report in the directory.
+//
+// After every adapter ran, the harness reads the directory the same way
+// it does for `coverage: true`: at least one well-formed report (lcov or
+// V8 JSON), shipped verbatim. Adapters convert nothing — the control
+// plane derives what it needs from the stored bytes.
+//
+// Imported from `@specific.dev/spectest/coverage`. The three shipped
+// adapters: `node()` (V8 JSON through a hook spectest mounts), `browser()`
+// (scripts the guest browser loads from the service), `command(cmd)` (run
+// a command, then read). A project writes its own with `defineAdapter`.
+//
+//   import * as coverage from "@specific.dev/spectest/coverage";
+//   coverage: { adapters: [coverage.node(), coverage.browser()] }
+
+import type { ServiceConfig } from "./index.js";
+import { browserCoverageReports } from "./browser-coverage.js";
+
+import { COVERAGE_CONTAINER_DIR } from "./harness/coverage.js";
+export { COVERAGE_CONTAINER_DIR };
+
+/** Where `node()` mounts its hook inside the container. */
+export const NODE_COVERAGE_HOOK_PATH = "/spectest/coverage-hook.cjs";
+
+/** The socket the node hook answers on, relative to the coverage dir. */
+export const NODE_COVERAGE_SOCKET = ".ctl";
+
+/** What `configure` learns about the service it rewrites. */
+export interface CoverageConfigureInfo {
+  /** The services-map key. */
+  key: string;
+}
+
+/** The harness capabilities an adapter can ask for at `/load`. */
+export interface CoverageLoadContext {
+  /** The services-map key. */
+  service: string;
+  /**
+   * Collect V8 coverage for every script the guest browser
+   * (`ctx.browser()` / `ctx.mobile()`) loads from this service's origins:
+   * its key, `<key>.internal`, its `hostnames`/`dnsName` aliases, its
+   * `tls`/`proxy` hostnames and any service-targeted wildcard. The
+   * harness maps each script back to source through the served source
+   * map and keeps per-service totals in memory (they fork with the
+   * environment). `browser()` calls this and writes the totals
+   * at capture.
+   */
+  collectBrowserScripts(): void;
+}
+
+/** What one adapter's `capture` runs against. */
+export interface CoverageCaptureContext {
+  /** The services-map key. */
+  service: string;
+  /**
+   * The coverage directory, seen from the harness. It is the same
+   * directory the container sees at `/spectest/coverage/` (a bind
+   * mount), so a file written here is in the container and a socket the
+   * container bound here is reachable.
+   */
+  reportDir: string;
+  /** Run a shell command (`sh -c`) inside the container. Rejects on a
+   *  non-zero exit with the command's output in the message. */
+  exec(command: string): Promise<{ stdout: string; stderr: string }>;
+  /** Write one report file (name relative to the directory). */
+  writeReport(name: string, content: string): Promise<void>;
+  /** Aborts when the per-service capture budget runs out. */
+  signal: AbortSignal;
+}
+
+export interface CoverageAdapter {
+  /** Names the adapter in errors (`coverage adapter "node" on service …`). */
+  name: string;
+  /**
+   * Rewrite the service at config time. Must be pure and deterministic
+   * (the result is hashed into the warm-template key) and must **append**
+   * to `env` values like `NODE_OPTIONS` rather than replace them.
+   */
+  configure?(service: ServiceConfig, info: CoverageConfigureInfo): ServiceConfig;
+  /** Ask the harness for capabilities, at `/load`. */
+  load?(ctx: CoverageLoadContext): void | Promise<void>;
+  /** Make the report appear in the directory. A throw fails the test. */
+  capture?(ctx: CoverageCaptureContext): void | Promise<void>;
+}
+
+/** `ServiceConfig.coverage`: the program writes its own reports, or a
+ *  list of adapters gets them out. */
+export type ServiceCoverage = true | { adapters: readonly CoverageAdapter[] };
+
+/** Type an inline adapter. Identity at runtime. */
+export function defineAdapter(adapter: CoverageAdapter): CoverageAdapter {
+  return adapter;
+}
+
+/** Check one service's `coverage` field. Exported so the daemon applies
+ *  the same rule to a runtime `startService` spec. */
+export function validateCoverage(service: string, cov: unknown): void {
+  if (cov === undefined || cov === true) return;
+  const adapters = (cov as { adapters?: unknown } | null)?.adapters;
+  if (typeof cov === "object" && cov !== null && Array.isArray(adapters)) {
+    for (const a of adapters) {
+      const ok =
+        typeof a === "object" &&
+        a !== null &&
+        typeof (a as CoverageAdapter).name === "string" &&
+        (a as CoverageAdapter).name.length > 0 &&
+        ["configure", "load", "capture"].every(
+          (k) =>
+            (a as Record<string, unknown>)[k] === undefined ||
+            typeof (a as Record<string, unknown>)[k] === "function",
+        );
+      if (!ok) {
+        throw new Error(
+          `service "${service}" has an invalid coverage adapter — an adapter is \`{ name, configure?, load?, capture? }\` (see \`defineAdapter\` in @specific.dev/spectest/coverage)`,
+        );
+      }
+    }
+    return;
+  }
+  throw new Error(
+    `service "${service}" has an invalid \`coverage\` value — use \`true\` (the program writes its own reports) or \`{ adapters: [...] }\` from @specific.dev/spectest/coverage (\`node()\`, \`browser()\`, \`command("…")\`)`,
+  );
+}
+
+/** The adapters of a `coverage` value (`true` has none). */
+export function coverageAdapters(cov: ServiceCoverage | undefined): readonly CoverageAdapter[] {
+  return typeof cov === "object" && cov !== null ? cov.adapters : [];
+}
+
+/**
+ * Apply every adapter's `configure` to a service, in list order. Called by
+ * `defineEnvironment` (after group expansion, before validation) and by
+ * the daemon for a runtime `startService` spec. The adapter list stays on
+ * the returned config for the harness; on the wire it serializes as the
+ * adapter names (`toJSON`), never as functions.
+ */
+export function applyCoverageAdapters<S extends ServiceConfig>(key: string, svc: S): S {
+  validateCoverage(key, svc.coverage);
+  const adapters = coverageAdapters(svc.coverage);
+  if (adapters.length === 0) return svc;
+  let out: ServiceConfig = svc;
+  for (const a of adapters) {
+    if (a.configure) out = a.configure(out, { key });
+  }
+  const wire = { adapters: adapters.map((a) => withWireName(a)) };
+  return { ...out, coverage: wire } as unknown as S;
+}
+
+function withWireName(a: CoverageAdapter): CoverageAdapter {
+  if (Object.prototype.hasOwnProperty.call(a, "toJSON")) return a;
+  return Object.assign(Object.create(Object.getPrototypeOf(a) as object | null), a, {
+    toJSON: () => ({ adapter: a.name }),
+  }) as CoverageAdapter;
+}
+
+/** `env` with `value` appended to `name` (space-separated), or set. */
+export function appendEnvFlag(
+  env: Readonly<Record<string, string>> | undefined,
+  name: string,
+  value: string,
+): Record<string, string> {
+  const prior = env?.[name]?.trim();
+  return { ...env, [name]: prior ? `${prior} ${value}` : value };
+}
+
+// ── node ──────────────────────────────────────────────────────────
+
+/**
+ * The hook `node()` mounts and `--require`s into every node
+ * process of the container. Node writes V8 coverage JSON into
+ * `NODE_V8_COVERAGE` when a process exits; a long-lived server never
+ * exits, so the hook binds a Unix socket in the coverage directory and
+ * calls `v8.takeCoverage()` for each connection. The first process to
+ * start owns the socket (a stale socket left by a dead process is
+ * reclaimed); a later process — a CLI run by `ctx.exec` — leaves it
+ * alone and writes at its own exit. No signal is used: signals are
+ * claimed by frameworks (SIGUSR2 stops a Temporal worker, restarts
+ * nodemon), a socket is nobody's.
+ */
+export const NODE_COVERAGE_HOOK = `"use strict";
+// spectest coverage hook (coverage.node() adapter). See \`spectest docs /services/coverage\`.
+if (process.env.NODE_V8_COVERAGE) {
+  const net = require("node:net");
+  const fs = require("node:fs");
+  const v8 = require("node:v8");
+  const SOCK = require("node:path").join(process.env.NODE_V8_COVERAGE, ${JSON.stringify(NODE_COVERAGE_SOCKET)});
+  const server = net.createServer((conn) => {
+    // A dump is taken only on an explicit "dump" request: a bystander's
+    // liveness probe connects and closes without one.
+    let buf = "";
+    conn.on("data", (chunk) => {
+      buf += chunk;
+      if (!buf.includes("\\n")) return;
+      let reply;
+      try {
+        if (!buf.startsWith("dump")) throw new Error("unknown request");
+        v8.takeCoverage();
+        reply = "ok\\n";
+      } catch (err) {
+        reply = "error " + (err && err.message ? err.message : String(err)) + "\\n";
+      }
+      conn.end(reply);
+    });
+  });
+  server.unref();
+  server.on("error", (err) => {
+    if (err.code !== "EADDRINUSE") return;
+    // Someone holds the socket. If it answers, it is the live server and
+    // this process is a bystander; if not, it is a stale file.
+    const probe = net.connect(SOCK);
+    probe.on("connect", () => probe.destroy());
+    probe.on("error", () => {
+      try { fs.unlinkSync(SOCK); } catch {}
+      server.listen(SOCK);
+    });
+  });
+  server.listen(SOCK);
+}
+`;
+
+/**
+ * Coverage for a Node service. Sets `NODE_V8_COVERAGE` to the coverage
+ * directory (every node process in the container then writes V8
+ * coverage JSON when it exits) and `--require`s a hook that lets spectest
+ * ask the long-lived server process for a dump at capture time. Nothing
+ * for the app to write. Source maps: with `--enable-source-maps` (or a
+ * `sourceMappingURL` next to the file) Node records the map in the
+ * report, which is what maps a TypeScript service back to its sources.
+ */
+export function node(): CoverageAdapter {
+  return {
+    name: "node",
+    configure(svc) {
+      const env = appendEnvFlag(svc.env, "NODE_OPTIONS", `--require ${NODE_COVERAGE_HOOK_PATH}`);
+      env.NODE_V8_COVERAGE = COVERAGE_CONTAINER_DIR;
+      return {
+        ...svc,
+        env,
+        files: [...(svc.files ?? []), { path: NODE_COVERAGE_HOOK_PATH, content: NODE_COVERAGE_HOOK }],
+      };
+    },
+    async capture(ctx) {
+      const { connect } = await import("node:net");
+      const path = await import("node:path");
+      const sock = path.join(ctx.reportDir, NODE_COVERAGE_SOCKET);
+      const reply = await new Promise<string>((resolve, reject) => {
+        const chunks: Buffer[] = [];
+        const c = connect(sock, () => c.write("dump\n"));
+        const onAbort = (): void => {
+          c.destroy();
+          reject(new Error("timed out waiting for the node hook to write a report"));
+        };
+        ctx.signal.addEventListener("abort", onAbort, { once: true });
+        c.on("data", (b: Buffer) => chunks.push(b));
+        c.on("error", (err: NodeJS.ErrnoException) => {
+          ctx.signal.removeEventListener("abort", onAbort);
+          reject(
+            new Error(
+              err.code === "ENOENT" || err.code === "ECONNREFUSED"
+                ? `no node process is serving ${COVERAGE_CONTAINER_DIR}/${NODE_COVERAGE_SOCKET} — is the service's main process node, and does it run with the service's env (NODE_OPTIONS)?`
+                : err.message,
+            ),
+          );
+        });
+        c.on("close", () => {
+          ctx.signal.removeEventListener("abort", onAbort);
+          resolve(Buffer.concat(chunks).toString("utf8").trim());
+        });
+      });
+      if (reply !== "ok") throw new Error(`the node hook answered: ${reply || "(nothing)"}`);
+    },
+  };
+}
+
+// ── browser ───────────────────────────────────────────────────────
+
+/**
+ * Coverage for the frontend a service serves. The code runs in the guest
+ * browser — spectest's own process — so no report can be written by the
+ * container; spectest collects V8 coverage for every script the browser
+ * loads from this service's origins, maps it back to source through the
+ * served source map, and writes one lcov per capture. Nothing ran yet on
+ * this branch ⇒ an lcov with no records, which is a report saying so.
+ */
+export function browser(): CoverageAdapter {
+  return {
+    name: "browser",
+    load(ctx) {
+      ctx.collectBrowserScripts();
+    },
+    async capture(ctx) {
+      const lcov = browserCoverageReports().get(ctx.service) ?? "TN:\n";
+      await ctx.writeReport("browser.lcov", lcov);
+    },
+  };
+}
+
+// ── command ───────────────────────────────────────────────────────
+
+/**
+ * Run `command` (via `sh -c`) in the container at every capture, so the
+ * service writes a fresh report into `/spectest/coverage/`. The escape
+ * hatch for a runtime with no shipped adapter.
+ */
+export function command(command: string): CoverageAdapter {
+  if (typeof command !== "string" || command.trim().length === 0) {
+    throw new Error("coverage.command: `command` must be a non-empty shell command");
+  }
+  return {
+    name: "command",
+    async capture(ctx) {
+      await ctx.exec(command);
+    },
+  };
+}

package/src/daemon.ts

@@ -32,9 +32,6 @@ import {
   dnsName as makeDnsDecl,
   isWildcard,
   proxy as makeProxyDecl,
-  validateCoverage,
-  coverageUsesBrowser,
-  coverageUsesContainer,
 } from "./index.js";
 import type { DnsTarget, LoweredIngress } from "./index.js";
 import {
@@ -42,15 +39,20 @@ import {
   coverageBundleRef,
   coverageHostDir,
   encodeCoverageBundle,
+  isEmptyReport,
   readCoverageDir,
   type CoverageBundleRef,
   type CoverageReport,
   type ServiceCoverageCapture,
 } from "./harness/coverage.js";
+import { configureBrowserCoverage } from "./browser-coverage.js";
 import {
-  browserCoverageReports,
-  configureBrowserCoverage,
-} from "./browser-coverage.js";
+  applyCoverageAdapters,
+  coverageAdapters,
+  validateCoverage,
+  type CoverageAdapter,
+  type CoverageCaptureContext,
+} from "./coverage.js";
 import { serviceForHost as hostToService } from "./harness/browser-coverage.js";
 import { acquirePersistentBrowser, mobileKey } from "./browser.js";
 import { isMobileApp, openPersistentMobile } from "./mobile.js";
@@ -785,9 +787,6 @@ async function ensureVolumes(svc: NamedService): Promise<string[]> {
 async function ensureCoverage(svc: NamedService): Promise<string[]> {
   if (svc.coverage === undefined) return [];
   validateCoverage(svc.name, svc.coverage);
-  // A browser-only opt-in has no container process to write reports, so it
-  // gets no mount — its coverage comes from the guest browser.
-  if (!coverageUsesContainer(svc.coverage)) return [];
   const host = coverageHostDir(WORKSPACE, svc.name);
   await fs.mkdir(host, { recursive: true });
   await fs.chmod(host, 0o777);
@@ -1813,7 +1812,11 @@ function buildIngress(project: Project): void {
   // generic decl set the daemon executes. The special-casing lives in the
   // SDK's lowerIngress, not here.
   LOWERED = lowerIngress(project);
-  configureCoverageAttribution(project);
+  BROWSER_COVERAGE_SERVICES.clear();
+  void runCoverageLoadHooks(namedServices(project.environment)).catch((err) => {
+    // eslint-disable-next-line no-console
+    console.warn("[coverage] load hook failed:", err);
+  });
   if (!project.fakes) return;
   for (const [name, def] of Object.entries(project.fakes)) {
     FAKES.set(name, {
@@ -2797,7 +2800,9 @@ const RUNTIME_SERVICES = new Map<string, NamedService>();
 // the orchestration helpers want a NamedService, which is the same shape.
 function specToNamedService(spec: RuntimeServiceSpec): NamedService {
   const { name, ...rest } = spec;
-  return { name, ...(rest as ServiceConfig) };
+  // A runtime spec skipped `defineEnvironment`, so its coverage adapters
+  // get their config-time pass here.
+  return { name, ...applyCoverageAdapters(name, rest as ServiceConfig) };
 }
 
 /** Implementation behind `ctx.startService` / a fake's `ctx.startService`.
@@ -2811,6 +2816,7 @@ async function startRuntimeService(spec: RuntimeServiceSpec): Promise<RuntimeSer
   const t0 = Date.now();
   const resv = reserveEvent();
   const svc = specToNamedService(spec);
+  await runCoverageLoadHooks([svc]);
   const aliases = (spec.hostnames ?? []).map((h) => h.toLowerCase());
   const imageRef = svc.image.type === "registry" ? svc.image.reference : "(dockerfile)";
   try {
@@ -3601,34 +3607,53 @@ async function captureServiceLogDeltas(): Promise<ServiceLogDelta[]> {
 }
 
 // ────────────────────────────────────────────────────────────────────────
-// Coverage capture (opt-in per service; see harness/coverage.ts)
+// Coverage capture (opt-in per service; see coverage.ts + harness/coverage.ts)
 // ────────────────────────────────────────────────────────────────────────
 //
-// Read after bring-up and after every test, on every case. The reports are
-// cumulative from process start and live on the rootfs, so what a child
-// fork reads already includes everything its ancestors ran — no markers,
-// no deltas (unlike the service logs above). A `command` runs in the
-// container first so the service writes a fresh report. The reports ship
-// verbatim; the server derives what it needs from the stored bytes.
-
-const COVERAGE_COMMAND_TIMEOUT_MS = 60_000;
-
-/** Set the browser-coverage host→service attribution from the loaded
- *  project: only services that opted in to `coverage: { browser: true }`
- *  are attributed, so a script from an uncovered service is ignored. Null
- *  when no service opted in — coverage then attaches nothing. Called on
- *  every /load. */
-function configureCoverageAttribution(project: Project): void {
-  const env = project.environment;
-  const browserServices = new Set<string>();
-  for (const svc of namedServices(env)) {
-    if (coverageUsesBrowser(svc.coverage)) browserServices.add(svc.name);
+// Read after bring-up and after every test, on every case. A service's
+// adapters run first (each makes its report appear in the directory —
+// `nodeCoverage` asks the hook for a dump, `browserCoverage` writes the
+// harness's totals, `commandCoverage` runs the command), then the
+// directory is read the same way for every service, `coverage: true`
+// included. The reports live on the rootfs, so what a child fork reads
+// already includes everything its ancestors ran — no markers, no deltas
+// (unlike the service logs above). The reports ship verbatim; the server
+// derives what it needs from the stored bytes.
+
+/** Budget for one service's adapters at one capture, all of them. */
+const COVERAGE_CAPTURE_TIMEOUT_MS = 60_000;
+
+/** Services whose adapters asked for browser scripts at /load
+ *  (`CoverageLoadContext.collectBrowserScripts`). Cleared on every /load;
+ *  a runtime service's adapters add to it when it starts. */
+const BROWSER_COVERAGE_SERVICES = new Set<string>();
+
+/** Run every adapter's `load` hook for `services`, then rebuild the
+ *  browser-coverage attribution from whoever asked. The attribution is a
+ *  host → service resolver over the lowered ingress, restricted to those
+ *  services, so a script from an uncovered service is ignored; null when
+ *  nobody asked, which costs nothing. */
+async function runCoverageLoadHooks(services: NamedService[]): Promise<void> {
+  for (const svc of services) {
+    for (const a of coverageAdapters(svc.coverage)) {
+      if (!a.load) continue;
+      await a.load({
+        service: svc.name,
+        collectBrowserScripts: () => {
+          BROWSER_COVERAGE_SERVICES.add(svc.name);
+        },
+      });
+    }
   }
-  if (browserServices.size === 0) {
+  rebuildBrowserCoverageResolver();
+}
+
+function rebuildBrowserCoverageResolver(): void {
+  if (BROWSER_COVERAGE_SERVICES.size === 0 || !loaded) {
     configureBrowserCoverage(null);
     return;
   }
-  const all = namedServices(env).map((s) => s.name);
+  const all = [...namedServices(loaded.project.environment).map((s) => s.name), ...RUNTIME_SERVICES.keys()];
   const table = {
     proxies: LOWERED.proxies,
     aliasesByService: LOWERED.aliasesByService,
@@ -3637,11 +3662,72 @@ function configureCoverageAttribution(project: Project): void {
   configureBrowserCoverage({
     serviceForHost(host: string): string | undefined {
       const svc = hostToService(host, all, table);
-      return svc && browserServices.has(svc) ? svc : undefined;
+      return svc && BROWSER_COVERAGE_SERVICES.has(svc) ? svc : undefined;
     },
   });
 }
 
+/** The context one adapter's `capture` runs against. */
+function coverageCaptureContext(svc: NamedService, signal: AbortSignal): CoverageCaptureContext {
+  const reportDir = coverageHostDir(WORKSPACE, svc.name);
+  return {
+    service: svc.name,
+    reportDir,
+    signal,
+    async exec(command: string) {
+      const r = await docker(["exec", svc.name, "sh", "-c", command], COVERAGE_CAPTURE_TIMEOUT_MS);
+      if (r.code !== 0) {
+        const tail = capMiddle((r.stderr || r.stdout).trim(), 2000).value;
+        throw new Error(`${JSON.stringify(command)} exited ${r.code}${tail ? `\n${tail}` : ""}`);
+      }
+      return { stdout: r.stdout, stderr: r.stderr };
+    },
+    async writeReport(name: string, content: string) {
+      const file = path.join(reportDir, name);
+      if (path.relative(reportDir, file).startsWith("..")) {
+        throw new Error(`writeReport: ${JSON.stringify(name)} leaves the coverage directory`);
+      }
+      await fs.mkdir(path.dirname(file), { recursive: true });
+      const tmp = path.join(path.dirname(file), `.${path.basename(file)}.tmp`);
+      await fs.writeFile(tmp, content);
+      await fs.rename(tmp, file);
+    },
+  };
+}
+
+/** Run one service's adapters in order under one budget. Returns the
+ *  error to fail the capture with, naming the adapter. */
+async function runCoverageAdapters(svc: NamedService): Promise<string | undefined> {
+  const adapters = coverageAdapters(svc.coverage).filter((a) => a.capture);
+  if (adapters.length === 0) return undefined;
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), COVERAGE_CAPTURE_TIMEOUT_MS);
+  const ctx = coverageCaptureContext(svc, ac.signal);
+  try {
+    for (const a of adapters) {
+      try {
+        await Promise.race([
+          (a as Required<Pick<CoverageAdapter, "capture">>).capture(ctx),
+          new Promise<never>((_, reject) => {
+            ac.signal.addEventListener(
+              "abort",
+              () => reject(new Error(`no report within ${COVERAGE_CAPTURE_TIMEOUT_MS / 1000}s`)),
+              { once: true },
+            );
+          }),
+        ]);
+      } catch (err) {
+        return `coverage adapter "${a.name}" on service "${svc.name}" failed: ${
+          err instanceof Error ? err.message : String(err)
+        }`;
+      }
+    }
+    return undefined;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 async function captureServiceCoverage(): Promise<ServiceCoverageCapture[]> {
   const l = loaded;
   if (!l) return [];
@@ -3649,48 +3735,11 @@ async function captureServiceCoverage(): Promise<ServiceCoverageCapture[]> {
   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()].filter((s) => s.coverage !== undefined);
-  // Browser coverage is per-service lcov, accumulated in module memory
-  // (browser-coverage.ts) across every harvest; read it once here.
-  const browser = browserCoverageReports();
   return Promise.all(
     services.map(async (svc): Promise<ServiceCoverageCapture> => {
-      const cov = svc.coverage;
-      const reports: CoverageReport[] = [];
-      // Container reports (a `command` runs first to flush a fresh dump).
-      if (coverageUsesContainer(cov)) {
-        if (typeof cov === "object" && cov !== null && cov.command) {
-          const r = await docker(
-            ["exec", svc.name, "sh", "-c", cov.command],
-            COVERAGE_COMMAND_TIMEOUT_MS,
-          );
-          if (r.code !== 0) {
-            const tail = capMiddle((r.stderr || r.stdout).trim(), 2000).value;
-            return {
-              service: svc.name,
-              reports: [],
-              error: `coverage command for service "${svc.name}" failed (exit ${r.code}): ${JSON.stringify(cov.command)}${tail ? `\n${tail}` : ""}`,
-            };
-          }
-        }
-        const dir = await readCoverageDir(svc.name, coverageHostDir(WORKSPACE, svc.name));
-        // A service that ALSO does browser coverage may legitimately have
-        // an empty container dir for a test — don't fail if the browser
-        // side has something. Otherwise the container contract stands.
-        if (dir.error && !(coverageUsesBrowser(cov) && browser.has(svc.name))) {
-          return dir;
-        }
-        reports.push(...dir.reports);
-      }
-      // Browser report for this service, when any script it served ran.
-      const lcov = browser.get(svc.name);
-      if (lcov) reports.push({ name: "browser.lcov", content: lcov });
-      if (reports.length === 0 && coverageUsesBrowser(cov) && !coverageUsesContainer(cov)) {
-        // Browser-only service, no browser activity yet this branch. Not an
-        // error — a test needn't open a browser; the report appears once
-        // one does (and forks to descendants from there).
-        return { service: svc.name, reports: [] };
-      }
-      return { service: svc.name, reports };
+      const error = await runCoverageAdapters(svc);
+      if (error) return { service: svc.name, reports: [], error };
+      return readCoverageDir(svc.name, coverageHostDir(WORKSPACE, svc.name));
     }),
   );
 }
@@ -6143,7 +6192,19 @@ export function harnessMethods(state: RouteState): MethodTable {
       // the control plane logs it.
       let coverage: CoverageBundleRef | undefined;
       try {
-        coverage = parkCoverageBundle(SETUP_CASE_ID, await captureServiceCoverage());
+        const captures = await captureServiceCoverage();
+        for (const c of captures) {
+          // After bring-up the code that started the service has run, so a
+          // report set that names no file at all is a misconfigured tool —
+          // visible in the boot log, never a failure (there is no case).
+          if (!c.error && c.reports.length > 0 && c.reports.every((r) => isEmptyReport(r.content))) {
+            // eslint-disable-next-line no-console
+            console.warn(
+              `[coverage] service "${c.service}": every report is empty after bring-up — is coverage enabled at process start?`,
+            );
+          }
+        }
+        coverage = parkCoverageBundle(SETUP_CASE_ID, captures);
       } catch (err) {
         // eslint-disable-next-line no-console
         console.warn("[coverage] baseline capture failed:", err);