@specific.dev/spectest 0.59.3 → 0.60.0

package/src/coverage.test.ts

@@ -4,21 +4,32 @@ import { promises as fs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import {
+  NODE_COVERAGE_C8_BIN,
+  NODE_COVERAGE_DUMPS_SUBDIR,
   NODE_COVERAGE_HOOK,
   NODE_COVERAGE_EMPTY_REPORT,
+  NODE_COVERAGE_LCOV,
+  NODE_COVERAGE_TOOLS_CONTAINER_DIR,
   NODE_COVERAGE_HOOK_PATH,
   NODE_COVERAGE_SOCKET_PREFIX,
+  absoluteLcovPaths,
   applyCoverageAdapters,
   appendEnvFlag,
   browser,
   command,
+  coverageReportsMode,
   compactV8Document,
   compactV8Reports,
+  COVERAGE_CONTAINER_DIR,
   node,
+  nodeCoverageConvertCommand,
+  nodeCoverageToolsAvailable,
+  nodeCoverageToolsDir,
   validateCoverage,
   type CoverageCaptureContext,
 } from "./coverage.js";
 import type { ServiceConfig } from "./index.js";
+import { foldBrowserCoverage } from "./browser-coverage.js";
 
 const base: ServiceConfig = {
   image: { type: "registry", reference: "node:20" },
@@ -36,6 +47,23 @@ describe("validateCoverage", () => {
     expect(() => validateCoverage("a", [node()])).toThrow(/invalid `coverage` value/);
     expect(() => validateCoverage("a", { adapters: [{ name: "" }] })).toThrow(/invalid coverage adapter/);
     expect(() => validateCoverage("a", { adapters: [{ name: "x", capture: 1 }] })).toThrow(/invalid coverage adapter/);
+    validateCoverage("a", { reports: "delta" });
+    validateCoverage("a", { reports: "cumulative", adapters: [] });
+    expect(() => validateCoverage("a", { reports: "sometimes" })).toThrow(/invalid `coverage` value/);
+    expect(() => validateCoverage("a", { adapters: [{ name: "x", reports: "no" }] })).toThrow(/invalid coverage adapter/);
+    expect(() => validateCoverage("a", { adapters: [], extra: 1 })).toThrow(/invalid `coverage` value/);
+    expect(() => validateCoverage("a", {})).toThrow(/invalid `coverage` value/);
+  });
+  test("reports mode: cumulative unless declared; the shipped adapters write deltas", () => {
+    expect(coverageReportsMode(undefined)).toBe("cumulative");
+    expect(coverageReportsMode(true)).toBe("cumulative");
+    expect(coverageReportsMode({ adapters: [] })).toBe("cumulative");
+    expect(coverageReportsMode({ reports: "delta" })).toBe("delta");
+    expect(node().reports).toBe("delta");
+    expect(browser().reports).toBe("delta");
+    expect(command("x").reports).toBeUndefined();
+    const out = applyCoverageAdapters("api", { ...base, coverage: { reports: "delta", adapters: [command("x")] } });
+    expect(JSON.parse(JSON.stringify(out)).coverage).toEqual({ adapters: [{ adapter: "command" }], reports: "delta" });
   });
 });
 
@@ -77,6 +105,7 @@ describe("compactV8Document", () => {
       { scriptId: "1", url: "file:///app/src/a.ts", functions: [] },
       { scriptId: "2", url: "file:///app/node_modules/x/index.js", functions: [] },
       { scriptId: "3", url: "node:fs", functions: [] },
+      { scriptId: "5", url: "file:///root/.cache/node/corepack/v1/pnpm/10.0.0/dist/pnpm.cjs", functions: [] },
       { scriptId: "4", url: "", functions: [] },
     ],
     "source-map-cache": {
@@ -90,6 +119,21 @@ describe("compactV8Document", () => {
     expect(Object.keys(out["source-map-cache"])).toEqual(["file:///app/src/a.ts"]);
     expect(out["source-map-cache"]["file:///app/src/a.ts"].data).toEqual({ mappings: "AAAA", sources: ["a.ts"] });
   });
+  test("keepSourcesContent keeps the sources for the in-container conversion", () => {
+    const out = compactV8Document(doc, { keepSourcesContent: true }) as typeof doc;
+    expect(out["source-map-cache"]["file:///app/src/a.ts"].data).toEqual({
+      mappings: "AAAA",
+      sources: ["a.ts"],
+      sourcesContent: ["x"],
+    });
+  });
+  test("absoluteLcovPaths makes c8's root-relative SF records container paths", () => {
+    expect(absoluteLcovPaths("TN:\nSF:app/src/a.ts\nDA:1,1\nend_of_record\nSF:/abs.js\nend_of_record\n")).toBe(
+      "TN:\nSF:/app/src/a.ts\nDA:1,1\nend_of_record\nSF:/abs.js\nend_of_record\n",
+    );
+    expect(absoluteLcovPaths("")).toBe("TN:\n");
+    expect(absoluteLcovPaths("  \n")).toBe("TN:\n");
+  });
   test("a dump with no app script keeps an empty result and no cache", () => {
     const out = compactV8Document({ result: [doc.result[2]], "source-map-cache": doc["source-map-cache"] });
     expect(out.result).toEqual([]);
@@ -131,6 +175,21 @@ describe("browserCoverage", () => {
     await browser().capture!(fakeCtx(dir));
     expect(await fs.readFile(path.join(dir, "browser.lcov"), "utf8")).toBe("TN:\n");
   });
+  test("capture takes the totals and clears them: the next capture is a delta", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-cov-"));
+    foldBrowserCoverage("api", new Map([["src/a.ts", new Map([[1, 2]])]]));
+    await browser().capture!(fakeCtx(dir));
+    const first = await fs.readFile(path.join(dir, "browser.lcov"), "utf8");
+    expect(first).toContain("SF:src/a.ts");
+    expect(first).toContain("DA:1,2");
+    await browser().capture!(fakeCtx(dir));
+    expect(await fs.readFile(path.join(dir, "browser.lcov"), "utf8")).toBe("TN:\n");
+    foldBrowserCoverage("api", new Map([["src/b.ts", new Map([[3, 1]])]]));
+    await browser().capture!(fakeCtx(dir));
+    const third = await fs.readFile(path.join(dir, "browser.lcov"), "utf8");
+    expect(third).toContain("SF:src/b.ts");
+    expect(third).not.toContain("SF:src/a.ts");
+  });
 });
 
 // The node hook against a real `node` (the box has one; skipped where it
@@ -256,6 +315,34 @@ describe.if(hasNode)("nodeCoverage hook (real node)", () => {
     expect(doc.result.map((x) => x.url)).toEqual([`file://${path.join(dir, "cli.js")}`]); // compacted
   });
 
+  test("a worker thread does not bind the socket; the main thread's dump is the app's", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-covhook-"));
+    const hook = path.join(dir, "coverage-hook.cjs");
+    await fs.writeFile(hook, NODE_COVERAGE_HOOK);
+    await fs.writeFile(
+      path.join(dir, "server.js"),
+      "function appWork() { return 1 } appWork();\n" +
+        "new (require('node:worker_threads').Worker)('setInterval(() => {}, 1000)', { eval: true });\n" +
+        SERVER_JS,
+    );
+    const child = spawn("node", [path.join(dir, "server.js")], {
+      env: { ...process.env, NODE_V8_COVERAGE: dir, NODE_OPTIONS: `--require ${hook}` },
+      stdio: ["ignore", "pipe", "inherit"],
+    });
+    await new Promise<void>((resolve) => child.stdout!.once("data", () => resolve()));
+    try {
+      await new Promise((r) => setTimeout(r, 300)); // let the worker thread start
+      expect((await socketsIn(dir)).length).toBe(1);
+      await node().capture!(fakeCtx(dir));
+      const reports = (await reportsIn(dir)).filter((n) => n !== NODE_COVERAGE_EMPTY_REPORT);
+      expect(reports.length).toBe(1);
+      const doc = JSON.parse(await fs.readFile(path.join(dir, reports[0]!), "utf8")) as { result: { url: string }[] };
+      expect(doc.result.some((s) => s.url.endsWith("/server.js"))).toBe(true);
+    } finally {
+      child.kill("SIGKILL");
+    }
+  });
+
   test("a stale socket left by a killed process is removed at capture", async () => {
     const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-covhook-"));
     const first = await start(dir, "server.js", 1);
@@ -280,3 +367,99 @@ describe.if(hasNode)("nodeCoverage hook (real node)", () => {
     expect(await reportsIn(dir)).toEqual([NODE_COVERAGE_EMPTY_REPORT]);
   });
 });
+
+// The conversion to lcov against a real `node` and a real `c8` tree.
+// Golden ships the tree at /opt/spectest/coverage-tools; on a dev box
+// point SPECTEST_C8_TEST_DIR at one (`bun install --linker=hoisted` of
+// `c8` in a scratch dir). Skipped where either is missing. The exec here
+// is the container's `sh -c` with the container paths rewritten to this
+// directory: the command is exactly what a container runs.
+const c8TestDir = process.env.SPECTEST_C8_TEST_DIR || "/opt/spectest/coverage-tools";
+const hasC8 = await fs
+  .access(path.join(c8TestDir, NODE_COVERAGE_C8_BIN))
+  .then(() => true)
+  .catch(() => false);
+
+describe.if(hasNode && hasC8)("nodeCoverage → lcov (real node + c8)", () => {
+  function c8Ctx(dir: string): CoverageCaptureContext {
+    return {
+      ...fakeCtx(dir),
+      async exec(command: string) {
+        const local = command
+          .replaceAll(NODE_COVERAGE_TOOLS_CONTAINER_DIR, c8TestDir)
+          .replaceAll(COVERAGE_CONTAINER_DIR, dir);
+        return new Promise((resolve, reject) => {
+          const p = spawn("sh", ["-c", local], { stdio: ["ignore", "pipe", "pipe"] });
+          let out = "";
+          p.stdout!.on("data", (b: Buffer) => (out += b));
+          p.stderr!.on("data", (b: Buffer) => (out += b));
+          p.on("exit", (code) => (code === 0 ? resolve({ stdout: out, stderr: "" }) : reject(new Error(out))));
+        });
+      },
+    };
+  }
+  async function withTools<T>(f: () => Promise<T>): Promise<T> {
+    const prior = process.env.SPECTEST_COVERAGE_TOOLS_DIR;
+    process.env.SPECTEST_COVERAGE_TOOLS_DIR = c8TestDir;
+    try {
+      return await f();
+    } finally {
+      if (prior === undefined) delete process.env.SPECTEST_COVERAGE_TOOLS_DIR;
+      else process.env.SPECTEST_COVERAGE_TOOLS_DIR = prior;
+    }
+  }
+
+  test("the tools dir is found through the override, and the command is the container's", async () => {
+    await withTools(async () => {
+      expect(nodeCoverageToolsDir()).toBe(c8TestDir);
+      expect(await nodeCoverageToolsAvailable()).toBe(true);
+    });
+    expect(nodeCoverageConvertCommand()).toBe(
+      `cd / && env -u NODE_V8_COVERAGE -u NODE_OPTIONS node ${NODE_COVERAGE_TOOLS_CONTAINER_DIR}/${NODE_COVERAGE_C8_BIN} report --temp-directory ${COVERAGE_CONTAINER_DIR}/${NODE_COVERAGE_DUMPS_SUBDIR} --reporter=lcovonly --reports-dir ${COVERAGE_CONTAINER_DIR}/.c8`,
+    );
+  });
+
+  test("dumps are converted to node.lcov, the delta of this capture; the raw dumps never ship", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-covc8-"));
+    const hook = path.join(dir, "coverage-hook.cjs");
+    await fs.writeFile(hook, NODE_COVERAGE_HOOK);
+    await fs.writeFile(path.join(dir, "cli.js"), "function used() { return 1 }\nfunction unused() { return 2 }\nused();\n");
+    await withTools(async () => {
+      // Nothing ran yet: an empty lcov, no exec.
+      await node().capture!(c8Ctx(dir));
+      expect(await fs.readFile(path.join(dir, NODE_COVERAGE_LCOV), "utf8")).toBe("TN:\n");
+      const cli = spawn("node", [path.join(dir, "cli.js")], {
+        env: { ...process.env, NODE_V8_COVERAGE: dir, NODE_OPTIONS: `--require ${hook}` },
+        stdio: "ignore",
+      });
+      expect(await new Promise<number | null>((r) => cli.on("exit", r))).toBe(0);
+      await node().capture!(c8Ctx(dir));
+      const lcov = await fs.readFile(path.join(dir, NODE_COVERAGE_LCOV), "utf8");
+      expect(lcov).toContain(`SF:${path.join(dir, "cli.js")}\n`);
+      expect(lcov).toMatch(/FNDA:1,used/);
+      expect(lcov).toMatch(/FNDA:0,unused/);
+      // The hook itself is not the app's code.
+      expect(lcov).not.toContain("coverage-hook.cjs");
+      // Raw dumps moved under the hidden .v8/ dir: the visible reports
+      // are the lcov alone.
+      const visible = (await fs.readdir(dir)).filter((n) => !n.startsWith(".") && n.startsWith("coverage-") && n.endsWith(".json"));
+      expect(visible).toEqual([]);
+      const dumps = (await fs.readdir(path.join(dir, NODE_COVERAGE_DUMPS_SUBDIR))).filter((n) => n.endsWith(".json"));
+      expect(dumps.length).toBe(1);
+      // Nothing new since: the next capture is an empty report, not the
+      // previous one again — the lcov is a delta.
+      await node().capture!(c8Ctx(dir));
+      expect(await fs.readFile(path.join(dir, NODE_COVERAGE_LCOV), "utf8")).toBe("TN:\n");
+      // A new run is a new delta on its own: counts of 1, not 2.
+      const again = spawn("node", [path.join(dir, "cli.js")], {
+        env: { ...process.env, NODE_V8_COVERAGE: dir, NODE_OPTIONS: `--require ${hook}` },
+        stdio: "ignore",
+      });
+      await new Promise((r) => again.on("exit", r));
+      await node().capture!(c8Ctx(dir));
+      const lcov2 = await fs.readFile(path.join(dir, NODE_COVERAGE_LCOV), "utf8");
+      expect(lcov2).toMatch(/FNDA:1,used/);
+      expect((await fs.readdir(path.join(dir, NODE_COVERAGE_DUMPS_SUBDIR))).filter((n) => n.endsWith(".json")).length).toBe(1);
+    });
+  });
+});

package/src/coverage.ts

@@ -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()`
@@ -26,10 +29,10 @@
 //   coverage: { adapters: [coverage.node(), coverage.browser()] }
 
 import type { ServiceConfig } from "./index.js";
-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 };
+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 const NODE_COVERAGE_HOOK_PATH = "/spectest/coverage-hook.cjs";
@@ -41,6 +44,27 @@ export const NODE_COVERAGE_EMPTY_REPORT = "coverage-spectest-empty.json";
  *  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";
+
 /** What `configure` learns about the service it rewrites. */
 export interface CoverageConfigureInfo {
   /** The services-map key. */
@@ -87,6 +111,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**
@@ -99,9 +132,18 @@ export interface CoverageAdapter {
   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[] };
+/** `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[]; reports?: CoverageReportsMode };
+
+/** The `reports` mode of a `coverage` value, for the reports no adapter
+ *  wrote (the program's own, a `command`'s). */
+export function coverageReportsMode(cov: ServiceCoverage | undefined): CoverageReportsMode {
+  return typeof cov === "object" && cov !== null && cov.reports ? cov.reports : "cumulative";
+}
 
 /** Type an inline adapter. Identity at runtime. */
 export function defineAdapter(adapter: CoverageAdapter): CoverageAdapter {
@@ -112,14 +154,22 @@ export function defineAdapter(adapter: CoverageAdapter): CoverageAdapter {
  *  the same rule to a runtime `startService` spec. */
 export function validateCoverage(service: string, cov: unknown): void {
   if (cov === undefined || cov === true) return;
-  const adapters = (cov as { adapters?: unknown } | null)?.adapters;
-  if (typeof cov === "object" && cov !== null && Array.isArray(adapters)) {
-    for (const a of adapters) {
+  const obj = typeof cov === "object" && cov !== null ? (cov as Record<string, unknown>) : 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 as unknown[] | undefined) ?? []) {
       const ok =
         typeof a === "object" &&
         a !== null &&
         typeof (a as CoverageAdapter).name === "string" &&
         (a as CoverageAdapter).name.length > 0 &&
+        ((a as CoverageAdapter).reports === undefined ||
+          (a as CoverageAdapter).reports === "delta" ||
+          (a as CoverageAdapter).reports === "cumulative") &&
         ["configure", "load", "capture"].every(
           (k) =>
             (a as Record<string, unknown>)[k] === undefined ||
@@ -127,20 +177,20 @@ export function validateCoverage(service: string, cov: unknown): void {
         );
       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)`,
+          `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("…")\`)`,
+    `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: ServiceCoverage | undefined): readonly CoverageAdapter[] {
-  return typeof cov === "object" && cov !== null ? cov.adapters : [];
+  return typeof cov === "object" && cov !== null ? (cov.adapters ?? []) : [];
 }
 
 /**
@@ -158,7 +208,8 @@ export function applyCoverageAdapters<S extends ServiceConfig>(key: string, svc:
   for (const a of adapters) {
     if (a.configure) out = a.configure(out, { key });
   }
-  const wire = { adapters: adapters.map((a) => withWireName(a)) };
+  const mode = (svc.coverage as { reports?: CoverageReportsMode }).reports;
+  const wire = { adapters: adapters.map((a) => withWireName(a)), ...(mode ? { reports: mode } : {}) };
   return { ...out, coverage: wire } as unknown as S;
 }
 
@@ -193,12 +244,20 @@ export function appendEnvFlag(
  * 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");
@@ -235,15 +294,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(): CoverageAdapter {
   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;
@@ -258,12 +332,16 @@ export function node(): CoverageAdapter {
       // 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');
@@ -272,6 +350,101 @@ export function node(): CoverageAdapter {
   };
 }
 
+/** The VM-side tools dir, after the test override. */
+export function nodeCoverageToolsDir(): string {
+  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(): Promise<boolean> {
+  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(): string {
+  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: CoverageCaptureContext): Promise<void> {
+  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: Record<string, unknown>;
+    try {
+      doc = JSON.parse(await fs.readFile(file, "utf8")) as Record<string, unknown>;
+    } 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: string;
+  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: string): string {
+  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,
@@ -345,6 +518,9 @@ export function isAppScriptUrl(url: string): boolean {
   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())
   );
 }
@@ -358,10 +534,14 @@ export 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 function compactV8Document(doc: Record<string, unknown>): Record<string, unknown> {
+export function compactV8Document(
+  doc: Record<string, unknown>,
+  opts: { keepSourcesContent?: boolean } = {},
+): Record<string, unknown> {
   const result = Array.isArray(doc.result) ? (doc.result as { url?: unknown }[]) : [];
   const kept = result.filter((s) => typeof s.url === "string" && isAppScriptUrl(s.url));
   const out: Record<string, unknown> = { ...doc, result: kept };
@@ -372,7 +552,7 @@ export function compactV8Document(doc: Record<string, unknown>): Record<string,
     for (const [url, entry] of Object.entries(cache as Record<string, unknown>)) {
       if (!urls.has(url) || !entry || typeof entry !== "object") continue;
       const e = { ...(entry as Record<string, unknown>) };
-      if (e.data && typeof e.data === "object") {
+      if (!opts.keepSourcesContent && e.data && typeof e.data === "object") {
         const { sourcesContent: _dropped, ...data } = e.data as Record<string, unknown>;
         e.data = data;
       }
@@ -419,17 +599,21 @@ export async 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 function browser(): CoverageAdapter {
   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);
     },
   };
@@ -440,7 +624,10 @@ export 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 function command(command: string): CoverageAdapter {
   if (typeof command !== "string" || command.trim().length === 0) {