@specific.dev/spectest 0.59.3 → 0.60.0

package/dist/browser-coverage.d.ts

@@ -1,4 +1,5 @@
 import type { CDPSession } from "playwright-core";
+import { type FileCounts } from "./harness/browser-coverage.js";
 export interface BrowserCoverageConfig {
     /** Which covered service (if any) serves scripts from this host. */
     serviceForHost(host: string): string | undefined;
@@ -16,5 +17,15 @@ export declare function attachBrowserCoverage(cdp: CDPSession): Promise<void>;
  * take, nothing is lost.
  */
 export declare function harvestBrowserCoverage(cdp: CDPSession): Promise<void>;
-/** One lcov document per service that has any browser coverage. */
+/** Fold one script's per-file counts into a service's totals. */
+export declare function foldBrowserCoverage(service: string, files: FileCounts): void;
+/** Harvest every live session, so a capture sees the counters of code
+ *  that ran since the last browser op. */
+export declare function harvestAllBrowserCoverage(): Promise<void>;
+/** One lcov document per service that has any browser coverage — and
+ *  the totals are cleared, so the next capture holds only what runs
+ *  from now on. Module memory forks with the environment, so a forked
+ *  child starts from its parent's last capture, empty. */
+export declare function takeBrowserCoverageReports(): Map<string, string>;
+/** The current totals, without clearing them (tests). */
 export declare function browserCoverageReports(): Map<string, string>;

package/dist/browser-coverage.js

@@ -19,7 +19,7 @@
 // project with no `coverage: { browser: true }` service never attaches
 // anything, so it costs nothing.
 import { createHash } from "node:crypto";
-import { decodeSourceMap, lcovDocument, mapToOriginal, mergeFileCounts, rangesToLineCounts, } from "./harness/browser-coverage.js";
+import { decodeSourceMap, isDocumentScriptPath, lcovDocument, mapToOriginal, mergeFileCounts, rangesToLineCounts, } from "./harness/browser-coverage.js";
 import { rawFetch } from "./harness/raw-fetch.js";
 let CONFIG = null;
 /** Set (or clear, with `null`) at /load. */
@@ -32,6 +32,9 @@ export function browserCoverageActive() {
 /** service → file → line → count, summed over every harvest. */
 const TOTALS = new Map();
 const COLLECTORS = new WeakMap();
+/** The collectors of every session attached so far, for the harvest at
+ *  capture; a closed session's take fails and is dropped there. */
+const LIVE_COLLECTORS = new Set();
 /** Decoded maps by URL (or content hash for inline `data:` maps). */
 const SOURCE_MAPS = new Map();
 const SOURCE_MAP_FETCH_TIMEOUT_MS = 10_000;
@@ -42,6 +45,7 @@ export async function attachBrowserCoverage(cdp) {
         return;
     const collector = { cdp, scripts: new Map(), inFlight: null };
     COLLECTORS.set(cdp, collector);
+    LIVE_COLLECTORS.add(collector);
     cdp.on("Debugger.scriptParsed", (ev) => {
         if (!ev.url)
             return;
@@ -72,7 +76,14 @@ export async function harvestBrowserCoverage(cdp) {
     return c.inFlight;
 }
 async function harvestInner(c, config) {
-    const { result } = (await c.cdp.send("Profiler.takePreciseCoverage"));
+    let result;
+    try {
+        ({ result } = (await c.cdp.send("Profiler.takePreciseCoverage")));
+    }
+    catch (err) {
+        LIVE_COLLECTORS.delete(c); // the session is gone
+        throw err;
+    }
     for (const script of result) {
         const info = c.scripts.get(script.scriptId) ?? (script.url ? { url: script.url } : undefined);
         if (!info)
@@ -106,17 +117,23 @@ async function harvestInner(c, config) {
             continue;
         if (info.map === undefined)
             info.map = await sourceMapFor(info, url);
+        if (!info.map && isDocumentScriptPath(url.pathname))
+            continue; // inline script in a page
         const files = 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);
+        foldBrowserCoverage(service, files);
     }
 }
+/** Fold one script's per-file counts into a service's totals. */
+export function foldBrowserCoverage(service, files) {
+    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, scriptUrl) {
     let ref = info.sourceMapURL;
@@ -174,7 +191,25 @@ function parseDataUrl(ref) {
         return null;
     }
 }
-/** One lcov document per service that has any browser coverage. */
+/** Harvest every live session, so a capture sees the counters of code
+ *  that ran since the last browser op. */
+export async function harvestAllBrowserCoverage() {
+    await Promise.all([...LIVE_COLLECTORS].map((c) => harvestBrowserCoverage(c.cdp)));
+}
+/** One lcov document per service that has any browser coverage — and
+ *  the totals are cleared, so the next capture holds only what runs
+ *  from now on. Module memory forks with the environment, so a forked
+ *  child starts from its parent's last capture, empty. */
+export function takeBrowserCoverageReports() {
+    const out = new Map();
+    for (const [service, files] of TOTALS) {
+        if (files.size > 0)
+            out.set(service, lcovDocument(files));
+    }
+    TOTALS.clear();
+    return out;
+}
+/** The current totals, without clearing them (tests). */
 export function browserCoverageReports() {
     const out = new Map();
     for (const [service, files] of TOTALS) {

package/dist/coverage.d.ts

@@ -1,6 +1,6 @@
 import type { ServiceConfig } from "./index.js";
-import { COVERAGE_CONTAINER_DIR } from "./harness/coverage.js";
-export { COVERAGE_CONTAINER_DIR };
+import { COVERAGE_CONTAINER_DIR, type CoverageReportsMode } from "./harness/coverage.js";
+export { COVERAGE_CONTAINER_DIR, type CoverageReportsMode };
 /** Where `node()` mounts its hook inside the container. */
 export declare const NODE_COVERAGE_HOOK_PATH = "/spectest/coverage-hook.cjs";
 /** The report `node()` writes when nothing has run yet on a branch. */
@@ -8,6 +8,22 @@ export declare const NODE_COVERAGE_EMPTY_REPORT = "coverage-spectest-empty.json"
 /** Prefix of the per-process sockets the node hook answers on, relative
  *  to the coverage dir: `.ctl-<pid>`. */
 export declare const NODE_COVERAGE_SOCKET_PREFIX = ".ctl-";
+/** Where golden keeps the conversion tools (`c8` and its dependencies),
+ *  seen from the VM. `SPECTEST_COVERAGE_TOOLS_DIR` overrides it (tests).
+ *  The daemon bind-mounts it read-only into every covered container at
+ *  {@link NODE_COVERAGE_TOOLS_CONTAINER_DIR} when it exists. */
+export declare const NODE_COVERAGE_TOOLS_DIR = "/opt/spectest/coverage-tools";
+/** Where the container sees {@link NODE_COVERAGE_TOOLS_DIR}. */
+export declare const NODE_COVERAGE_TOOLS_CONTAINER_DIR = "/spectest/coverage-tools";
+/** The `c8` entry point, relative to the tools dir. */
+export declare const NODE_COVERAGE_C8_BIN = "node_modules/c8/bin/c8.js";
+/** The hidden subdirectory of the coverage dir where `node()` parks the
+ *  V8 dumps it converts at one capture. Hidden, so the harness never
+ *  ships them: the lcov is the report. Emptied at every capture — the
+ *  lcov is this capture's delta, see {@link convertV8ReportsToLcov}. */
+export declare const NODE_COVERAGE_DUMPS_SUBDIR = ".v8";
+/** The lcov `node()` writes: the dumps of this capture, merged. */
+export declare const NODE_COVERAGE_LCOV = "node.lcov";
 /** What `configure` learns about the service it rewrites. */
 export interface CoverageConfigureInfo {
     /** The services-map key. */
@@ -54,6 +70,15 @@ export interface CoverageCaptureContext {
 export interface CoverageAdapter {
     /** Names the adapter in errors (`coverage adapter "node" on service …`). */
     name: string;
+    /**
+     * How the reports this adapter writes (through `ctx.writeReport`)
+     * count: `"delta"` — what ran since the previous capture, the tool
+     * resets its own counters; `"cumulative"` (the default) — since
+     * process start, and spectest subtracts the previous capture. Reports
+     * the adapter makes appear some other way (`command`) follow the
+     * service's own `reports`.
+     */
+    reports?: CoverageReportsMode;
     /**
      * Rewrite the service at config time. Must be pure and deterministic
      * (the result is hashed into the warm-template key) and must **append**
@@ -65,11 +90,16 @@ export interface CoverageAdapter {
     /** 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. */
+/** `ServiceConfig.coverage`: the program writes its own reports (`true`),
+ *  or a list of adapters gets them out, and/or how the reports the
+ *  program itself writes count (`reports`, default `"cumulative"`). */
 export type ServiceCoverage = true | {
-    adapters: readonly CoverageAdapter[];
+    adapters?: readonly CoverageAdapter[];
+    reports?: CoverageReportsMode;
 };
+/** The `reports` mode of a `coverage` value, for the reports no adapter
+ *  wrote (the program's own, a `command`'s). */
+export declare function coverageReportsMode(cov: ServiceCoverage | undefined): CoverageReportsMode;
 /** 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
@@ -99,6 +129,10 @@ export declare function appendEnvFlag(env: Readonly<Record<string, string>> | un
  * wrapper dumped the wrapper and silently never the server (reported by
  * a user 2026-08-27). At capture spectest asks every live socket and
  * unlinks the stale ones. Unref'd, so a short-lived process still exits.
+ * Main thread only: a worker thread inherits `NODE_OPTIONS`, and tsx's
+ * ESM loader thread bound the shared per-pid path last, so every
+ * `--import tsx` server answered with the loader's coverage — the app's
+ * main thread was never dumped (found in the same user's first full run).
  * No signal is used: signals are claimed by frameworks (SIGUSR2 stops a
  * Temporal worker, restarts nodemon), a socket is nobody's.
  */
@@ -110,13 +144,52 @@ export declare const NODE_COVERAGE_HOOK: string;
  * container then writes V8 coverage JSON when it exits) and `--require`s
  * a hook that lets spectest ask every live node process for a dump at
  * capture time — the server, and any wrapper it sits behind (`pnpm exec`,
- * `tsx`). Nothing
- * for the app to write. Each dump is compacted to the app's own scripts
- * at capture ({@link compactV8Document}). 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.
+ * `tsx`). Nothing for the app to write.
+ *
+ * At capture the dumps are **converted to lcov inside the container**
+ * with `c8` (`c8 report`), and `node.lcov` is the one report that
+ * ships. It holds **what ran since the previous capture**: V8 resets its
+ * counters at every `takeCoverage()`, so a live server's dump after a
+ * test is that test's own execution — the boot dump (everything loaded,
+ * which at file level is everything "ran") lands in the bring-up
+ * capture and nowhere else. A run's total is the union over its cases
+ * on the server; a test's set is the test's own. Merging every dump on
+ * the branch instead was tried first and would have made a long-lived
+ * server's per-test set the boot set, every time. The conversion runs
+ * in the container, not in the harness, because `v8-to-istanbul` needs
+ * the script text (for byte offsets → lines) and the source maps
+ * (`--enable-source-maps`, or a `sourceMappingURL` next to each file),
+ * and only the container has them. `c8` comes from golden
+ * ({@link NODE_COVERAGE_TOOLS_DIR}); on a guest without it the raw V8
+ * documents ship instead, compacted ({@link compactV8Document}), as they
+ * did before SDK 0.60.
  */
 export declare function node(): CoverageAdapter;
+/** The VM-side tools dir, after the test override. */
+export declare function nodeCoverageToolsDir(): string;
+/** True when golden (or the override) ships `c8`. The daemon mounts the
+ *  directory into covered containers on the same check, so what the VM
+ *  has is what the container sees. */
+export declare function nodeCoverageToolsAvailable(): Promise<boolean>;
+/** The command `convertV8ReportsToLcov` runs in the container. From `/`,
+ *  so lcov paths come out relative to the root (made absolute after). */
+export declare function nodeCoverageConvertCommand(): string;
+/**
+ * Convert the V8 dumps written since the previous capture to one lcov,
+ * `node.lcov`. New dumps at the root of the dir are compacted to the
+ * app's scripts (their maps and `sourcesContent` kept — `v8-to-istanbul`
+ * reads the original sources from there when they are not on disk, the
+ * usual shape of a multi-stage image) and moved into `.v8/`, which is
+ * emptied first; `c8 report` merges that directory. So the lcov is this
+ * capture's delta: what the live processes ran since their last take,
+ * plus every process that exited since. No new dump ⇒ `TN:` alone,
+ * nothing ran. The `SF:` paths come out relative to `/` and are made
+ * absolute, so they read as container paths like every other tool's.
+ */
+export declare function convertV8ReportsToLcov(ctx: CoverageCaptureContext): Promise<void>;
+/** `SF:` records relative to `/` (what `c8` run from `/` writes) made
+ *  absolute. An lcov with nothing in it becomes the empty report. */
+export declare function absoluteLcovPaths(lcov: string): string;
 /**
  * Ask every node process that holds a hook socket in `dir` for a dump.
  * A socket nobody answers (its process died without unlinking — SIGKILL,
@@ -136,10 +209,13 @@ export declare function isAppScriptUrl(url: string): boolean;
  * per capture, of which the app's own coverage was under 0.5 MiB, and a
  * suite that hit the 64 MiB cap on its third test. Kept: `file://`
  * scripts outside `node_modules`, the map entries of exactly those
- * scripts, minus `sourcesContent` (the sources are the repo). Still a V8
- * document — nothing is converted.
+ * scripts, minus `sourcesContent` (the sources are the repo) unless
+ * `keepSourcesContent` — the lcov conversion reads original sources from
+ * there. Still a V8 document — nothing is converted here.
  */
-export declare function compactV8Document(doc: Record<string, unknown>): Record<string, unknown>;
+export declare function compactV8Document(doc: Record<string, unknown>, opts?: {
+    keepSourcesContent?: boolean;
+}): Record<string, unknown>;
 /** Compact every not-yet-compacted V8 document in `dir`, in place. */
 export declare function compactV8Reports(dir: string): Promise<void>;
 /**
@@ -147,13 +223,18 @@ export declare function compactV8Reports(dir: string): Promise<void>;
  * 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.
+ * served source map, and writes one lcov per capture (`browser.lcov`)
+ * holding what ran since the previous capture: every live session is
+ * harvested first, and the totals are taken and cleared. Nothing ran ⇒
+ * 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.
+ * hatch for a runtime with no shipped adapter. The reports it makes
+ * appear follow the service's `reports` mode (cumulative by default —
+ * spectest subtracts the previous capture; `{ reports: "delta" }` when
+ * the tool resets its own counters).
  */
 export declare function command(command: string): CoverageAdapter;

package/dist/coverage.js

@@ -14,8 +14,11 @@
 //
 // 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.
+// V8 JSON), shipped verbatim. The control plane derives what it needs
+// from the stored bytes. One adapter converts: `node()` turns the V8
+// dumps into lcov inside the container (with `c8`, which golden ships),
+// because the conversion needs the sources and the source maps, which
+// only the container has.
 //
 // Imported from `@specific.dev/spectest/coverage`. The three shipped
 // adapters: `node()` (V8 JSON through a hook spectest mounts), `browser()`
@@ -24,7 +27,7 @@
 //
 //   import * as coverage from "@specific.dev/spectest/coverage";
 //   coverage: { adapters: [coverage.node(), coverage.browser()] }
-import { browserCoverageReports } from "./browser-coverage.js";
+import { harvestAllBrowserCoverage, takeBrowserCoverageReports } from "./browser-coverage.js";
 import { COVERAGE_CONTAINER_DIR } from "./harness/coverage.js";
 export { COVERAGE_CONTAINER_DIR };
 /** Where `node()` mounts its hook inside the container. */
@@ -34,6 +37,27 @@ export const NODE_COVERAGE_EMPTY_REPORT = "coverage-spectest-empty.json";
 /** Prefix of the per-process sockets the node hook answers on, relative
  *  to the coverage dir: `.ctl-<pid>`. */
 export const NODE_COVERAGE_SOCKET_PREFIX = ".ctl-";
+/** Where golden keeps the conversion tools (`c8` and its dependencies),
+ *  seen from the VM. `SPECTEST_COVERAGE_TOOLS_DIR` overrides it (tests).
+ *  The daemon bind-mounts it read-only into every covered container at
+ *  {@link NODE_COVERAGE_TOOLS_CONTAINER_DIR} when it exists. */
+export const NODE_COVERAGE_TOOLS_DIR = "/opt/spectest/coverage-tools";
+/** Where the container sees {@link NODE_COVERAGE_TOOLS_DIR}. */
+export const NODE_COVERAGE_TOOLS_CONTAINER_DIR = "/spectest/coverage-tools";
+/** The `c8` entry point, relative to the tools dir. */
+export const NODE_COVERAGE_C8_BIN = "node_modules/c8/bin/c8.js";
+/** The hidden subdirectory of the coverage dir where `node()` parks the
+ *  V8 dumps it converts at one capture. Hidden, so the harness never
+ *  ships them: the lcov is the report. Emptied at every capture — the
+ *  lcov is this capture's delta, see {@link convertV8ReportsToLcov}. */
+export const NODE_COVERAGE_DUMPS_SUBDIR = ".v8";
+/** The lcov `node()` writes: the dumps of this capture, merged. */
+export const NODE_COVERAGE_LCOV = "node.lcov";
+/** The `reports` mode of a `coverage` value, for the reports no adapter
+ *  wrote (the program's own, a `command`'s). */
+export function coverageReportsMode(cov) {
+    return typeof cov === "object" && cov !== null && cov.reports ? cov.reports : "cumulative";
+}
 /** Type an inline adapter. Identity at runtime. */
 export function defineAdapter(adapter) {
     return adapter;
@@ -43,26 +67,34 @@ export function defineAdapter(adapter) {
 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 obj = typeof cov === "object" && cov !== null ? cov : null;
+    const adapters = obj?.adapters;
+    const reports = obj?.reports;
+    const knownKeys = obj !== null && Object.keys(obj).every((k) => k === "adapters" || k === "reports");
+    const okReports = reports === undefined || reports === "delta" || reports === "cumulative";
+    const okAdapters = adapters === undefined || Array.isArray(adapters);
+    if (obj !== null && knownKeys && okReports && okAdapters && (adapters !== undefined || reports !== undefined)) {
+        for (const a of adapters ?? []) {
             const ok = typeof a === "object" &&
                 a !== null &&
                 typeof a.name === "string" &&
                 a.name.length > 0 &&
+                (a.reports === undefined ||
+                    a.reports === "delta" ||
+                    a.reports === "cumulative") &&
                 ["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)`);
+                throw new Error(`service "${service}" has an invalid coverage adapter — an adapter is \`{ name, reports?, 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("…")\`)`);
+    throw new Error(`service "${service}" has an invalid \`coverage\` value — use \`true\` (the program writes its own reports), \`{ adapters: [...] }\` from @specific.dev/spectest/coverage (\`node()\`, \`browser()\`, \`command("…")\`), and/or \`{ reports: "delta" | "cumulative" }\``);
 }
 /** The adapters of a `coverage` value (`true` has none). */
 export function coverageAdapters(cov) {
-    return typeof cov === "object" && cov !== null ? cov.adapters : [];
+    return typeof cov === "object" && cov !== null ? (cov.adapters ?? []) : [];
 }
 /**
  * Apply every adapter's `configure` to a service, in list order. Called by
@@ -81,7 +113,8 @@ export function applyCoverageAdapters(key, svc) {
         if (a.configure)
             out = a.configure(out, { key });
     }
-    const wire = { adapters: adapters.map((a) => withWireName(a)) };
+    const mode = svc.coverage.reports;
+    const wire = { adapters: adapters.map((a) => withWireName(a)), ...(mode ? { reports: mode } : {}) };
     return { ...out, coverage: wire };
 }
 function withWireName(a) {
@@ -109,12 +142,20 @@ export function appendEnvFlag(env, name, value) {
  * wrapper dumped the wrapper and silently never the server (reported by
  * a user 2026-08-27). At capture spectest asks every live socket and
  * unlinks the stale ones. Unref'd, so a short-lived process still exits.
+ * Main thread only: a worker thread inherits `NODE_OPTIONS`, and tsx's
+ * ESM loader thread bound the shared per-pid path last, so every
+ * `--import tsx` server answered with the loader's coverage — the app's
+ * main thread was never dumped (found in the same user's first full run).
  * 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) {
+// Main thread only: worker threads inherit NODE_OPTIONS and would bind
+// the same per-pid socket last — tsx's ESM loader runs on one, and it
+// stole the socket from every \`--import tsx\` server, so a dump was the
+// loader's isolate and never the app's.
+if (process.env.NODE_V8_COVERAGE && require("node:worker_threads").isMainThread) {
   const net = require("node:net");
   const fs = require("node:fs");
   const v8 = require("node:v8");
@@ -150,15 +191,30 @@ if (process.env.NODE_V8_COVERAGE) {
  * container then writes V8 coverage JSON when it exits) and `--require`s
  * a hook that lets spectest ask every live node process for a dump at
  * capture time — the server, and any wrapper it sits behind (`pnpm exec`,
- * `tsx`). Nothing
- * for the app to write. Each dump is compacted to the app's own scripts
- * at capture ({@link compactV8Document}). 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.
+ * `tsx`). Nothing for the app to write.
+ *
+ * At capture the dumps are **converted to lcov inside the container**
+ * with `c8` (`c8 report`), and `node.lcov` is the one report that
+ * ships. It holds **what ran since the previous capture**: V8 resets its
+ * counters at every `takeCoverage()`, so a live server's dump after a
+ * test is that test's own execution — the boot dump (everything loaded,
+ * which at file level is everything "ran") lands in the bring-up
+ * capture and nowhere else. A run's total is the union over its cases
+ * on the server; a test's set is the test's own. Merging every dump on
+ * the branch instead was tried first and would have made a long-lived
+ * server's per-test set the boot set, every time. The conversion runs
+ * in the container, not in the harness, because `v8-to-istanbul` needs
+ * the script text (for byte offsets → lines) and the source maps
+ * (`--enable-source-maps`, or a `sourceMappingURL` next to each file),
+ * and only the container has them. `c8` comes from golden
+ * ({@link NODE_COVERAGE_TOOLS_DIR}); on a guest without it the raw V8
+ * documents ship instead, compacted ({@link compactV8Document}), as they
+ * did before SDK 0.60.
  */
 export function node() {
     return {
         name: "node",
+        reports: "delta",
         configure(svc) {
             const env = appendEnvFlag(svc.env, "NODE_OPTIONS", `--require ${NODE_COVERAGE_HOOK_PATH}`);
             env.NODE_V8_COVERAGE = COVERAGE_CONTAINER_DIR;
@@ -173,12 +229,16 @@ export function node() {
             // here; a service whose node processes are short-lived (a CLI run
             // by `ctx.exec` from a `sleep infinity` container) has no socket to
             // answer and its coverage is the exit-time dumps already on disk.
-            // So no live process is not an error. No report at all — nothing
-            // has run yet on this branch — is recorded as an empty document
+            // So no live process is not an error. No dump at all — nothing
+            // has run yet on this branch — is recorded as an empty report
             // rather than failed: an empty report is a report. A server whose
             // hook never loaded (NODE_OPTIONS not reaching it) then shows as
             // empty reports after bring-up, which the boot log warns about.
             await dumpAllNodeProcesses(ctx.reportDir, ctx.signal);
+            if (await nodeCoverageToolsAvailable()) {
+                await convertV8ReportsToLcov(ctx);
+                return;
+            }
             await compactV8Reports(ctx.reportDir);
             if (!(await hasV8Reports(ctx.reportDir))) {
                 await ctx.writeReport(NODE_COVERAGE_EMPTY_REPORT, '{"result":[]}\n');
@@ -186,6 +246,102 @@ export function node() {
         },
     };
 }
+/** The VM-side tools dir, after the test override. */
+export function nodeCoverageToolsDir() {
+    return process.env.SPECTEST_COVERAGE_TOOLS_DIR || NODE_COVERAGE_TOOLS_DIR;
+}
+/** True when golden (or the override) ships `c8`. The daemon mounts the
+ *  directory into covered containers on the same check, so what the VM
+ *  has is what the container sees. */
+export async function nodeCoverageToolsAvailable() {
+    const fs = await import("node:fs/promises");
+    const path = await import("node:path");
+    try {
+        await fs.access(path.join(nodeCoverageToolsDir(), NODE_COVERAGE_C8_BIN));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The command `convertV8ReportsToLcov` runs in the container. From `/`,
+ *  so lcov paths come out relative to the root (made absolute after). */
+export function nodeCoverageConvertCommand() {
+    const c8 = `${NODE_COVERAGE_TOOLS_CONTAINER_DIR}/${NODE_COVERAGE_C8_BIN}`;
+    const dumps = `${COVERAGE_CONTAINER_DIR}/${NODE_COVERAGE_DUMPS_SUBDIR}`;
+    const out = `${COVERAGE_CONTAINER_DIR}/.c8`;
+    // `env -u`: the converter is a node process in a container whose env
+    // carries NODE_V8_COVERAGE and the `--require` hook, so without this it
+    // would load the hook and write a dump of itself at exit — a raw V8
+    // document at the root of the dir, shipped as a report (seen on the
+    // first run of hello-node under 0.60).
+    return `cd / && env -u NODE_V8_COVERAGE -u NODE_OPTIONS node ${c8} report --temp-directory ${dumps} --reporter=lcovonly --reports-dir ${out}`;
+}
+/**
+ * Convert the V8 dumps written since the previous capture to one lcov,
+ * `node.lcov`. New dumps at the root of the dir are compacted to the
+ * app's scripts (their maps and `sourcesContent` kept — `v8-to-istanbul`
+ * reads the original sources from there when they are not on disk, the
+ * usual shape of a multi-stage image) and moved into `.v8/`, which is
+ * emptied first; `c8 report` merges that directory. So the lcov is this
+ * capture's delta: what the live processes ran since their last take,
+ * plus every process that exited since. No new dump ⇒ `TN:` alone,
+ * nothing ran. The `SF:` paths come out relative to `/` and are made
+ * absolute, so they read as container paths like every other tool's.
+ */
+export async function convertV8ReportsToLcov(ctx) {
+    const fs = await import("node:fs/promises");
+    const path = await import("node:path");
+    const dumpsDir = path.join(ctx.reportDir, NODE_COVERAGE_DUMPS_SUBDIR);
+    await fs.rm(dumpsDir, { recursive: true, force: true });
+    await fs.mkdir(dumpsDir, { recursive: true });
+    await fs.chmod(dumpsDir, 0o755);
+    let dumps = 0;
+    for (const name of await fs.readdir(ctx.reportDir)) {
+        if (!name.startsWith("coverage-") || !name.endsWith(".json"))
+            continue;
+        const file = path.join(ctx.reportDir, name);
+        if (name === NODE_COVERAGE_EMPTY_REPORT) {
+            await fs.unlink(file).catch(() => { }); // a pre-0.60 placeholder
+            continue;
+        }
+        let doc;
+        try {
+            doc = JSON.parse(await fs.readFile(file, "utf8"));
+        }
+        catch {
+            continue; // a dump mid-write; the next capture takes it
+        }
+        if (!Array.isArray(doc.result))
+            continue;
+        const target = path.join(dumpsDir, name);
+        await fs.writeFile(`${target}.tmp`, JSON.stringify(compactV8Document(doc, { keepSourcesContent: true })));
+        await fs.chmod(`${target}.tmp`, 0o644);
+        await fs.rename(`${target}.tmp`, target);
+        await fs.unlink(file);
+        dumps++;
+    }
+    if (dumps === 0) {
+        await ctx.writeReport(NODE_COVERAGE_LCOV, "TN:\n");
+        return;
+    }
+    await ctx.exec(nodeCoverageConvertCommand());
+    let lcov;
+    try {
+        lcov = await fs.readFile(path.join(ctx.reportDir, ".c8", "lcov.info"), "utf8");
+    }
+    catch (err) {
+        throw new Error(`c8 wrote no lcov.info: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    await ctx.writeReport(NODE_COVERAGE_LCOV, absoluteLcovPaths(lcov));
+}
+/** `SF:` records relative to `/` (what `c8` run from `/` writes) made
+ *  absolute. An lcov with nothing in it becomes the empty report. */
+export function absoluteLcovPaths(lcov) {
+    if (lcov.trim().length === 0)
+        return "TN:\n";
+    return lcov.replace(/^SF:(?!\/)/gm, "SF:/");
+}
 /**
  * Ask every node process that holds a hook socket in `dir` for a dump.
  * A socket nobody answers (its process died without unlinking — SIGKILL,
@@ -259,6 +415,9 @@ const COMPACTED_V8_REPORTS = new Set();
 export function isAppScriptUrl(url) {
     return (url.startsWith("file://") &&
         !url.includes("/node_modules/") &&
+        // Package managers run from a cache, not node_modules: corepack's pnpm
+        // is `/root/.cache/node/corepack/…`, 2 MiB of dump per `pnpm run`.
+        !url.includes("/.cache/") &&
         !url.endsWith("/" + NODE_COVERAGE_HOOK_PATH.split("/").pop()));
 }
 /**
@@ -270,10 +429,11 @@ export function isAppScriptUrl(url) {
  * per capture, of which the app's own coverage was under 0.5 MiB, and a
  * suite that hit the 64 MiB cap on its third test. Kept: `file://`
  * scripts outside `node_modules`, the map entries of exactly those
- * scripts, minus `sourcesContent` (the sources are the repo). Still a V8
- * document — nothing is converted.
+ * scripts, minus `sourcesContent` (the sources are the repo) unless
+ * `keepSourcesContent` — the lcov conversion reads original sources from
+ * there. Still a V8 document — nothing is converted here.
  */
-export function compactV8Document(doc) {
+export function compactV8Document(doc, opts = {}) {
     const result = Array.isArray(doc.result) ? doc.result : [];
     const kept = result.filter((s) => typeof s.url === "string" && isAppScriptUrl(s.url));
     const out = { ...doc, result: kept };
@@ -285,7 +445,7 @@ export function compactV8Document(doc) {
             if (!urls.has(url) || !entry || typeof entry !== "object")
                 continue;
             const e = { ...entry };
-            if (e.data && typeof e.data === "object") {
+            if (!opts.keepSourcesContent && e.data && typeof e.data === "object") {
                 const { sourcesContent: _dropped, ...data } = e.data;
                 e.data = data;
             }
@@ -336,17 +496,21 @@ export async function compactV8Reports(dir) {
  * 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.
+ * served source map, and writes one lcov per capture (`browser.lcov`)
+ * holding what ran since the previous capture: every live session is
+ * harvested first, and the totals are taken and cleared. Nothing ran ⇒
+ * an lcov with no records, which is a report saying so.
  */
 export function browser() {
     return {
         name: "browser",
+        reports: "delta",
         load(ctx) {
             ctx.collectBrowserScripts();
         },
         async capture(ctx) {
-            const lcov = browserCoverageReports().get(ctx.service) ?? "TN:\n";
+            await harvestAllBrowserCoverage();
+            const lcov = takeBrowserCoverageReports().get(ctx.service) ?? "TN:\n";
             await ctx.writeReport("browser.lcov", lcov);
         },
     };
@@ -355,7 +519,10 @@ export function browser() {
 /**
  * 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.
+ * hatch for a runtime with no shipped adapter. The reports it makes
+ * appear follow the service's `reports` mode (cumulative by default —
+ * spectest subtracts the previous capture; `{ reports: "delta" }` when
+ * the tool resets its own counters).
  */
 export function command(command) {
     if (typeof command !== "string" || command.trim().length === 0) {