@specific.dev/spectest 0.56.2 → 0.58.0

package/src/browser-coverage.ts

@@ -0,0 +1,209 @@
+// Browser coverage — the collector.
+//
+// One collector per CDP session (i.e. per page view). `attach` turns on
+// V8 precise coverage and tracks parsed scripts; `harvest` takes the
+// counters (which RESETS them — V8 reports nothing for a script that ran
+// nothing since the last take, so the counts are summed here across
+// takes), maps each script the browser loaded from a covered service back
+// to its original sources through the served source map, and folds the
+// result into a per-service total in module memory — which forks with the
+// daemon, so a child test inherits its ancestors' browser coverage exactly
+// as a container's counters are inherited.
+//
+// Harvest runs before every browser step (a click that navigates
+// cross-site replaces the renderer, and the old counters with it) and at
+// every coverage capture. `browserCoverageReports` renders the totals as
+// one lcov per service for the `case-coverage` bundle.
+//
+// Configured by the daemon at /load with the host → service table; a
+// project with no `coverage: { browser: true }` service never attaches
+// anything, so it costs nothing.
+
+import { createHash } from "node:crypto";
+import type { CDPSession } from "playwright-core";
+import {
+  type DecodedSourceMap,
+  type FileCounts,
+  decodeSourceMap,
+  lcovDocument,
+  mapToOriginal,
+  mergeFileCounts,
+  rangesToLineCounts,
+  type V8FunctionCoverage,
+} from "./harness/browser-coverage.js";
+import { rawFetch } from "./harness/raw-fetch.js";
+
+export interface BrowserCoverageConfig {
+  /** Which covered service (if any) serves scripts from this host. */
+  serviceForHost(host: string): string | undefined;
+}
+
+let CONFIG: BrowserCoverageConfig | null = null;
+
+/** Set (or clear, with `null`) at /load. */
+export function configureBrowserCoverage(config: BrowserCoverageConfig | null): void {
+  CONFIG = config;
+}
+
+export function browserCoverageActive(): boolean {
+  return CONFIG !== null;
+}
+
+/** service → file → line → count, summed over every harvest. */
+const TOTALS = new Map<string, FileCounts>();
+
+interface ScriptInfo {
+  url: string;
+  sourceMapURL?: string;
+  source?: string;
+  /** `undefined` = not looked up yet; `null` = none / unusable. */
+  map?: DecodedSourceMap | null;
+}
+
+interface Collector {
+  cdp: CDPSession;
+  scripts: Map<string, ScriptInfo>;
+  inFlight: Promise<void> | null;
+}
+
+const COLLECTORS = new WeakMap<CDPSession, Collector>();
+
+/** Decoded maps by URL (or content hash for inline `data:` maps). */
+const SOURCE_MAPS = new Map<string, DecodedSourceMap | null>();
+
+const SOURCE_MAP_FETCH_TIMEOUT_MS = 10_000;
+
+/** Turn coverage on for a page's CDP session. Idempotent; a no-op when no
+ *  service opted in. */
+export async function attachBrowserCoverage(cdp: CDPSession): Promise<void> {
+  if (!CONFIG || COLLECTORS.has(cdp)) return;
+  const collector: Collector = { cdp, scripts: new Map(), inFlight: null };
+  COLLECTORS.set(cdp, collector);
+  cdp.on("Debugger.scriptParsed", (ev: { scriptId: string; url: string; sourceMapURL?: string }) => {
+    if (!ev.url) return;
+    collector.scripts.set(ev.scriptId, {
+      url: ev.url,
+      sourceMapURL: ev.sourceMapURL || undefined,
+    });
+  });
+  await cdp.send("Debugger.enable");
+  await cdp.send("Profiler.enable");
+  await cdp.send("Profiler.startPreciseCoverage", { callCount: true, detailed: true });
+}
+
+/**
+ * Take the session's counters and fold them into the totals. Concurrent
+ * calls coalesce onto the in-flight one. Errors (a page mid-navigation,
+ * a closed view) are swallowed: the counters then stay in V8 for the next
+ * take, nothing is lost.
+ */
+export async function harvestBrowserCoverage(cdp: CDPSession): Promise<void> {
+  const c = COLLECTORS.get(cdp);
+  if (!c || !CONFIG) return;
+  if (c.inFlight) return c.inFlight;
+  c.inFlight = harvestInner(c, CONFIG).catch(() => {}).finally(() => {
+    c.inFlight = null;
+  });
+  return c.inFlight;
+}
+
+async function harvestInner(c: Collector, config: BrowserCoverageConfig): Promise<void> {
+  const { result } = (await c.cdp.send("Profiler.takePreciseCoverage")) as {
+    result: { scriptId: string; url: string; functions: V8FunctionCoverage[] }[];
+  };
+  for (const script of result) {
+    const info = c.scripts.get(script.scriptId) ?? (script.url ? { url: script.url } : undefined);
+    if (!info) continue;
+    let url: URL;
+    try {
+      url = new URL(info.url);
+    } catch {
+      continue;
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") continue;
+    const service = config.serviceForHost(url.hostname);
+    if (!service) continue;
+    if (info.source === undefined) {
+      try {
+        const r = (await c.cdp.send("Debugger.getScriptSource", {
+          scriptId: script.scriptId,
+        })) as { scriptSource: string };
+        info.source = r.scriptSource;
+      } catch {
+        continue; // script gone with its document
+      }
+      c.scripts.set(script.scriptId, info);
+    }
+    const generated = rangesToLineCounts(info.source, script.functions);
+    if (generated.size === 0) continue;
+    if (info.map === undefined) info.map = await sourceMapFor(info, url);
+    const files: FileCounts = info.map
+      ? mapToOriginal(info.map, generated)
+      : new Map([[url.pathname, generated]]);
+    let totals = TOTALS.get(service);
+    if (!totals) {
+      totals = new Map();
+      TOTALS.set(service, totals);
+    }
+    mergeFileCounts(totals, files);
+  }
+}
+
+/** Resolve, fetch (or inline-decode) and decode a script's source map. */
+async function sourceMapFor(info: ScriptInfo, scriptUrl: URL): Promise<DecodedSourceMap | null> {
+  let ref = info.sourceMapURL;
+  if (!ref && info.source) {
+    const m = /\/\/[#@]\s*sourceMappingURL=(\S+)\s*$/.exec(info.source.slice(-4096));
+    if (m) ref = m[1];
+  }
+  if (!ref) return null;
+  if (ref.startsWith("data:")) {
+    const key = "data:" + createHash("sha1").update(ref).digest("hex");
+    const cached = SOURCE_MAPS.get(key);
+    if (cached !== undefined) return cached;
+    const map = decodeSourceMap(parseDataUrl(ref));
+    SOURCE_MAPS.set(key, map);
+    return map;
+  }
+  let mapUrl: string;
+  try {
+    mapUrl = new URL(ref, scriptUrl).toString();
+  } catch {
+    return null;
+  }
+  const cached = SOURCE_MAPS.get(mapUrl);
+  if (cached !== undefined) return cached;
+  let map: DecodedSourceMap | null = null;
+  try {
+    const res = await rawFetch(mapUrl, { signal: AbortSignal.timeout(SOURCE_MAP_FETCH_TIMEOUT_MS) });
+    if (res.ok) map = decodeSourceMap(await res.json());
+  } catch {
+    map = null;
+  }
+  SOURCE_MAPS.set(mapUrl, map);
+  return map;
+}
+
+function parseDataUrl(ref: string): unknown {
+  const comma = ref.indexOf(",");
+  if (comma < 0) return null;
+  const meta = ref.slice(5, comma);
+  const payload = ref.slice(comma + 1);
+  try {
+    const text = /;base64$/i.test(meta)
+      ? Buffer.from(payload, "base64").toString("utf8")
+      : decodeURIComponent(payload);
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+/** One lcov document per service that has any browser coverage. */
+export function browserCoverageReports(): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const [service, files] of TOTALS) {
+    if (files.size > 0) out.set(service, lcovDocument(files));
+  }
+  return out;
+}

package/src/browser.ts

@@ -38,6 +38,11 @@ import { recordBrowser, reserveBackdated, reserveEvent, truncateUtf8 } from "./r
 import { wrap } from "./inspect.js";
 import type { Wrapped } from "./inspect.js";
 import { describeUrlPattern, matchesUrl } from "./url-match.js";
+import {
+  attachBrowserCoverage,
+  browserCoverageActive,
+  harvestBrowserCoverage,
+} from "./browser-coverage.js";
 import type { UrlPattern } from "./url-match.js";
 export type { UrlPattern } from "./url-match.js";
 import {
@@ -1223,6 +1228,13 @@ async function spawnPage(context: BrowserContext): Promise<SpawnedPage> {
       console.warn("[spectest] failed to install rrweb recorder:", err);
     }
   }
+  // Frontend coverage (opt-in): turn on V8 precise coverage for this page.
+  // A no-op unless a service declared `coverage: { browser: true }`.
+  try {
+    await attachBrowserCoverage(cdp);
+  } catch {
+    /* coverage is best-effort; a page without it still works */
+  }
   return { page, cdp, recordingInstalled };
 }
 
@@ -1558,6 +1570,13 @@ async function rebuildView(holder: ViewHolder): Promise<void> {
   } catch {
     /* page may already be gone */
   }
+  // The old renderer's coverage counters die with its page; harvest what
+  // it had before the swap (rebuild is triggered on a fresh navigation).
+  try {
+    await harvestBrowserCoverage(holder.cdp);
+  } catch {
+    /* best-effort */
+  }
   const fresh = await spawnPage(holder.context);
   holder.page = fresh.page;
   holder.cdp = fresh.cdp;
@@ -1660,6 +1679,16 @@ function buildBackend(
         durationMs: endT - t,
       }, resv);
       await drain(action);
+      // Fold this page's V8 counters into the per-service totals now — a
+      // navigation to another origin replaces the renderer and its
+      // counters, so harvesting per op is what keeps them.
+      if (browserCoverageActive()) {
+        try {
+          await harvestBrowserCoverage(holder.cdp);
+        } catch {
+          /* best-effort */
+        }
+      }
       // Reads (`opts.wrap`) return user-visible JS values someone is likely to
       // assert on — provenance-wrap so `expect(...)` nests under this step.
       // Actions return void/internals; leave them raw to avoid Proxy surprises.
@@ -1688,6 +1717,13 @@ function buildBackend(
     if (recordingEnded) return;
     // Final drain before we stop writing to this recorder.
     await drain("close");
+    if (browserCoverageActive()) {
+      try {
+        await harvestBrowserCoverage(holder.cdp);
+      } catch {
+        /* best-effort */
+      }
+    }
     recordingEnded = true;
   }
 

package/src/daemon.ts

@@ -32,8 +32,26 @@ import {
   dnsName as makeDnsDecl,
   isWildcard,
   proxy as makeProxyDecl,
+  validateCoverage,
+  coverageUsesBrowser,
+  coverageUsesContainer,
 } from "./index.js";
 import type { DnsTarget, LoweredIngress } from "./index.js";
+import {
+  COVERAGE_CONTAINER_DIR,
+  coverageBundleRef,
+  coverageHostDir,
+  encodeCoverageBundle,
+  readCoverageDir,
+  type CoverageBundleRef,
+  type CoverageReport,
+  type ServiceCoverageCapture,
+} from "./harness/coverage.js";
+import {
+  browserCoverageReports,
+  configureBrowserCoverage,
+} from "./browser-coverage.js";
+import { serviceForHost as hostToService } from "./harness/browser-coverage.js";
 import { acquirePersistentBrowser, mobileKey } from "./browser.js";
 import { isMobileApp, openPersistentMobile } from "./mobile.js";
 // Pure ingress hostname matching, ported out of this file (see
@@ -756,6 +774,26 @@ async function ensureVolumes(svc: NamedService): Promise<string[]> {
   return flags;
 }
 
+/**
+ * The coverage directory for an opted-in service: one host dir per service
+ * under the workspace (so the delta-restore teardown wipes it), mounted
+ * writable at `/spectest/coverage/`. World-writable because the container
+ * may run as any user and spectest creates the dir as root. The reports in
+ * it ride snapshots and forks like everything else on the rootfs, which is
+ * what makes each read cumulative along the test's ancestor chain.
+ */
+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);
+  return [`--volume=${host}:${COVERAGE_CONTAINER_DIR}`];
+}
+
 /** A `user`/`group` pair resolved to the numeric ids the kernel wants.
  *  `-1` is chown(2)'s "leave this one alone". */
 interface OwnerIds {
@@ -1775,6 +1813,7 @@ 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);
   if (!project.fakes) return;
   for (const [name, def] of Object.entries(project.fakes)) {
     FAKES.set(name, {
@@ -2780,6 +2819,7 @@ async function startRuntimeService(spec: RuntimeServiceSpec): Promise<RuntimeSer
       ...(await ensureVolumes(svc)),
       ...(await ensureFiles(svc, tag)),
       ...(await ensureCertificates(svc, tag)),
+      ...(await ensureCoverage(svc)),
     ];
     await runContainer(svc, tag, flags, aliases);
     await waitForReady(svc);
@@ -3228,6 +3268,7 @@ async function bootstrapInner(): Promise<BootstrapTimings> {
       ...(await ensureVolumes(svc)),
       ...(await ensureFiles(svc, tag)),
       ...(await ensureCertificates(svc, tag)),
+      ...(await ensureCoverage(svc)),
     ];
     const tRun = Date.now();
     progressService(svc.name, { status: "starting", detail: undefined });
@@ -3369,6 +3410,16 @@ interface RunResult {
    * failing case's own delta. See {captureServiceLogDeltas}.
    */
   serviceLogDeltas: ServiceLogDelta[];
+  /**
+   * Per-service coverage for the services that opted in (`coverage` on
+   * the service): their lcov reports, verbatim, read after this case.
+   * Cumulative along the ancestor chain by construction. Like
+   * `browserSessions` this never rides the `run` reply — the handler
+   * parks a gzipped bundle and replies with a ref the control plane pulls
+   * through `coverageChunk`. An entry with `error` fails the case. See
+   * {captureServiceCoverage}.
+   */
+  coverageCaptures: ServiceCoverageCapture[];
   error?: { message: string; stack?: string };
 }
 
@@ -3391,19 +3442,42 @@ interface RunResult {
 // bundle in guest RAM — entries older than the last few are always
 // already-fetched leftovers frozen into some snapshot.
 const REPLAY_BUNDLES = new Map<string, Buffer>();
-const REPLAY_BUNDLES_MAX = 8;
-
-function stashReplayBundle(caseId: string, gz: Buffer): void {
+/** Coverage bundles, same side-channel and same lifetime rules; pulled
+ *  through `coverageChunk`. The env-setup baseline parks under the
+ *  control plane's synthetic `__setup__` case id. */
+const COVERAGE_BUNDLES = new Map<string, Buffer>();
+const PARKED_BUNDLES_MAX = 8;
+/** The control plane's synthetic case id for env-setup captures
+ *  (`storage::SETUP_CASE_ID`). Not a real case id — those are kebab slugs. */
+const SETUP_CASE_ID = "__setup__";
+
+function stashBundle(map: Map<string, Buffer>, caseId: string, gz: Buffer): void {
   // Re-insert to refresh recency (Map iterates in insertion order).
-  REPLAY_BUNDLES.delete(caseId);
-  REPLAY_BUNDLES.set(caseId, gz);
-  while (REPLAY_BUNDLES.size > REPLAY_BUNDLES_MAX) {
-    const oldest = REPLAY_BUNDLES.keys().next().value;
+  map.delete(caseId);
+  map.set(caseId, gz);
+  while (map.size > PARKED_BUNDLES_MAX) {
+    const oldest = map.keys().next().value;
     if (oldest === undefined) break;
-    REPLAY_BUNDLES.delete(oldest);
+    map.delete(oldest);
   }
 }
 
+function stashReplayBundle(caseId: string, gz: Buffer): void {
+  stashBundle(REPLAY_BUNDLES, caseId, gz);
+}
+
+/** Encode + park a case's coverage captures; returns the ref for the reply.
+ *  `undefined` when no service opted in, so uncovered projects ship nothing. */
+function parkCoverageBundle(
+  caseId: string,
+  captures: ServiceCoverageCapture[],
+): CoverageBundleRef | undefined {
+  if (captures.length === 0) return undefined;
+  const gz = encodeCoverageBundle(caseId, captures);
+  stashBundle(COVERAGE_BUNDLES, caseId, gz);
+  return coverageBundleRef(gz, captures);
+}
+
 // ────────────────────────────────────────────────────────────────────────
 // Cumulative service logs (per-case deltas → S3, reconstructed on the web)
 // ────────────────────────────────────────────────────────────────────────
@@ -3526,6 +3600,101 @@ async function captureServiceLogDeltas(): Promise<ServiceLogDelta[]> {
   );
 }
 
+// ────────────────────────────────────────────────────────────────────────
+// Coverage capture (opt-in per service; see 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);
+  }
+  if (browserServices.size === 0) {
+    configureBrowserCoverage(null);
+    return;
+  }
+  const all = namedServices(env).map((s) => s.name);
+  const table = {
+    proxies: LOWERED.proxies,
+    aliasesByService: LOWERED.aliasesByService,
+    wildcards: LOWERED.wildcards,
+  };
+  configureBrowserCoverage({
+    serviceForHost(host: string): string | undefined {
+      const svc = hostToService(host, all, table);
+      return svc && browserServices.has(svc) ? svc : undefined;
+    },
+  });
+}
+
+async function captureServiceCoverage(): Promise<ServiceCoverageCapture[]> {
+  const l = loaded;
+  if (!l) return [];
+  const byName = new Map<string, NamedService>();
+  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 };
+    }),
+  );
+}
+
 /** Per-Browser rrweb session shipped to the control plane. */
 interface BrowserSessionRecord {
   sessionId: string;
@@ -5020,6 +5189,32 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
     // eslint-disable-next-line no-console
     console.warn("[service-logs] delta capture failed:", err);
   }
+  // Coverage for the opted-in services, read after the clock stops like
+  // the log deltas. Unlike them it is NOT best-effort: a service that opted
+  // in and produced nothing readable fails the case, so a hole in the
+  // coverage data is visible where it happened rather than silently
+  // widening every later subset run.
+  let coverageCaptures: ServiceCoverageCapture[] = [];
+  try {
+    coverageCaptures = await captureServiceCoverage();
+  } catch (err) {
+    coverageCaptures = [
+      {
+        service: "*",
+        reports: [],
+        error: `coverage capture failed: ${err instanceof Error ? err.message : String(err)}`,
+      },
+    ];
+  }
+  const coverageErrors = coverageCaptures
+    .filter((c) => c.error)
+    .map((c) => c.error as string);
+  if (coverageErrors.length > 0 && outcome.status === "passed") {
+    outcome = {
+      status: "failed",
+      error: { message: coverageErrors.join("\n") },
+    };
+  }
   const events = stopRecording();
   // Drop sessions whose linking event didn't survive — an exec/terminal
   // inside a failed `ctx.poll` iteration has its events removed by
@@ -5038,6 +5233,7 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
     browserSessions: sessions.map((s) => s.record),
     terminalSessions: terminalSessions.filter((s) => referencedSessions.has(s.sessionId)),
     serviceLogDeltas,
+    coverageCaptures,
     error: outcome.error,
   };
 }
@@ -5940,7 +6136,19 @@ export function harnessMethods(state: RouteState): MethodTable {
         // eslint-disable-next-line no-console
         console.warn("[service-logs] baseline capture failed:", err);
       }
-      return { serviceLogDeltas };
+      // The coverage baseline rides the same call: what the opted-in
+      // services ran during bring-up + project setup, parked under the
+      // synthetic `__setup__` case for `coverageChunk`. A capture error is
+      // reported in the ref, not thrown — there is no case to fail here,
+      // the control plane logs it.
+      let coverage: CoverageBundleRef | undefined;
+      try {
+        coverage = parkCoverageBundle(SETUP_CASE_ID, await captureServiceCoverage());
+      } catch (err) {
+        // eslint-disable-next-line no-console
+        console.warn("[coverage] baseline capture failed:", err);
+      }
+      return { serviceLogDeltas, coverage };
     },
 
     run: async (params) => {
@@ -5954,7 +6162,10 @@ export function harnessMethods(state: RouteState): MethodTable {
         // (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;
+        const { browserSessions, coverageCaptures, ...wire } = result;
+        // Coverage reports take the same side channel: park, reply with a
+        // ref, let the control plane pull through `coverageChunk`.
+        const coverage = parkCoverageBundle(caseId, coverageCaptures);
         let replay: { bytes: number } | undefined;
         if (browserSessions.length > 0) {
           try {
@@ -5966,7 +6177,7 @@ export function harnessMethods(state: RouteState): MethodTable {
             console.warn("[replay] bundle encode failed; dropping recordings:", err);
           }
         }
-        return { ...wire, replay };
+        return { ...wire, replay, coverage };
       });
     },
 
@@ -5978,6 +6189,14 @@ export function harnessMethods(state: RouteState): MethodTable {
       if (!gz) throw notFound(`no replay bundle for case: ${caseId}`);
       return replayChunk(gz, params.offset as number | undefined, params.limit as number | undefined);
     },
+
+    // One chunk of a parked coverage bundle (same shape as replayChunk).
+    coverageChunk: async (params) => {
+      const caseId = requireString(params, "caseId", "caseId");
+      const gz = COVERAGE_BUNDLES.get(caseId);
+      if (!gz) throw notFound(`no coverage bundle for case: ${caseId}`);
+      return replayChunk(gz, params.offset as number | undefined, params.limit as number | undefined);
+    },
   };
 }