@specific.dev/spectest 0.58.0 → 0.59.0

package/dist/coverage.d.ts

@@ -0,0 +1,124 @@
+import type { ServiceConfig } from "./index.js";
+import { COVERAGE_CONTAINER_DIR } from "./harness/coverage.js";
+export { COVERAGE_CONTAINER_DIR };
+/** Where `node()` mounts its hook inside the container. */
+export declare const NODE_COVERAGE_HOOK_PATH = "/spectest/coverage-hook.cjs";
+/** The socket the node hook answers on, relative to the coverage dir. */
+export declare 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 declare function defineAdapter(adapter: CoverageAdapter): CoverageAdapter;
+/** Check one service's `coverage` field. Exported so the daemon applies
+ *  the same rule to a runtime `startService` spec. */
+export declare function validateCoverage(service: string, cov: unknown): void;
+/** The adapters of a `coverage` value (`true` has none). */
+export declare function coverageAdapters(cov: ServiceCoverage | undefined): readonly CoverageAdapter[];
+/**
+ * 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 declare function applyCoverageAdapters<S extends ServiceConfig>(key: string, svc: S): S;
+/** `env` with `value` appended to `name` (space-separated), or set. */
+export declare function appendEnvFlag(env: Readonly<Record<string, string>> | undefined, name: string, value: string): Record<string, string>;
+/**
+ * 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 declare const NODE_COVERAGE_HOOK: string;
+/**
+ * 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 declare function node(): CoverageAdapter;
+/**
+ * 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 declare function browser(): CoverageAdapter;
+/**
+ * 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 declare function command(command: string): CoverageAdapter;

package/dist/coverage.js

@@ -0,0 +1,236 @@
+// 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 { 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";
+/** Type an inline adapter. Identity at runtime. */
+export function defineAdapter(adapter) {
+    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, cov) {
+    if (cov === undefined || cov === true)
+        return;
+    const adapters = cov?.adapters;
+    if (typeof cov === "object" && cov !== null && Array.isArray(adapters)) {
+        for (const a of adapters) {
+            const ok = typeof a === "object" &&
+                a !== null &&
+                typeof a.name === "string" &&
+                a.name.length > 0 &&
+                ["configure", "load", "capture"].every((k) => a[k] === undefined ||
+                    typeof a[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) {
+    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(key, svc) {
+    validateCoverage(key, svc.coverage);
+    const adapters = coverageAdapters(svc.coverage);
+    if (adapters.length === 0)
+        return svc;
+    let out = 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 };
+}
+function withWireName(a) {
+    if (Object.prototype.hasOwnProperty.call(a, "toJSON"))
+        return a;
+    return Object.assign(Object.create(Object.getPrototypeOf(a)), a, {
+        toJSON: () => ({ adapter: a.name }),
+    });
+}
+/** `env` with `value` appended to `name` (space-separated), or set. */
+export function appendEnvFlag(env, name, value) {
+    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() {
+    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((resolve, reject) => {
+                const chunks = [];
+                const c = connect(sock, () => c.write("dump\n"));
+                const onAbort = () => {
+                    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) => chunks.push(b));
+                c.on("error", (err) => {
+                    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() {
+    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) {
+    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/dist/daemon.js

@@ -21,9 +21,10 @@ import { existsSync, promises as fs, readFileSync } from "node:fs";
 import net from "node:net";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard, proxy as makeProxyDecl, validateCoverage, coverageUsesBrowser, coverageUsesContainer, } from "./index.js";
-import { COVERAGE_CONTAINER_DIR, coverageBundleRef, coverageHostDir, encodeCoverageBundle, readCoverageDir, } from "./harness/coverage.js";
-import { browserCoverageReports, configureBrowserCoverage, } from "./browser-coverage.js";
+import { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard, proxy as makeProxyDecl, } from "./index.js";
+import { COVERAGE_CONTAINER_DIR, coverageBundleRef, coverageHostDir, encodeCoverageBundle, isEmptyReport, readCoverageDir, } from "./harness/coverage.js";
+import { configureBrowserCoverage } from "./browser-coverage.js";
+import { applyCoverageAdapters, coverageAdapters, validateCoverage, } from "./coverage.js";
 import { serviceForHost as hostToService } from "./harness/browser-coverage.js";
 import { acquirePersistentBrowser, mobileKey } from "./browser.js";
 import { isMobileApp, openPersistentMobile } from "./mobile.js";
@@ -525,10 +526,6 @@ async function ensureCoverage(svc) {
     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);
@@ -1428,7 +1425,11 @@ function buildIngress(project) {
     // 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)) {
@@ -2313,7 +2314,9 @@ const RUNTIME_SERVICES = new Map();
 // the orchestration helpers want a NamedService, which is the same shape.
 function specToNamedService(spec) {
     const { name, ...rest } = spec;
-    return { name, ...rest };
+    // A runtime spec skipped `defineEnvironment`, so its coverage adapters
+    // get their config-time pass here.
+    return { name, ...applyCoverageAdapters(name, rest) };
 }
 /** Implementation behind `ctx.startService` / a fake's `ctx.startService`.
  *  Prepares the image (pulling on first use through the host cache), runs
@@ -2326,6 +2329,7 @@ async function startRuntimeService(spec) {
     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 {
@@ -2977,33 +2981,50 @@ async function captureServiceLogDeltas() {
     }));
 }
 // ────────────────────────────────────────────────────────────────────────
-// 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) {
-    const env = project.environment;
-    const browserServices = new Set();
-    for (const svc of namedServices(env)) {
-        if (coverageUsesBrowser(svc.coverage))
-            browserServices.add(svc.name);
-    }
-    if (browserServices.size === 0) {
+// 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();
+/** 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) {
+    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);
+                },
+            });
+        }
+    }
+    rebuildBrowserCoverageResolver();
+}
+function rebuildBrowserCoverageResolver() {
+    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,
@@ -3012,10 +3033,66 @@ function configureCoverageAttribution(project) {
     configureBrowserCoverage({
         serviceForHost(host) {
             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, signal) {
+    const reportDir = coverageHostDir(WORKSPACE, svc.name);
+    return {
+        service: svc.name,
+        reportDir,
+        signal,
+        async exec(command) {
+            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, content) {
+            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) {
+    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.capture(ctx),
+                    new Promise((_, 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() {
     const l = loaded;
     if (!l)
@@ -3026,45 +3103,11 @@ async function captureServiceCoverage() {
     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) => {
-        const cov = svc.coverage;
-        const reports = [];
-        // 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));
     }));
 }
 /**
@@ -5070,7 +5113,17 @@ export function harnessMethods(state) {
             // the control plane logs it.
             let coverage;
             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