@specific.dev/spectest 0.58.0 → 0.59.0

package/dist/harness/coverage.d.ts

@@ -1,7 +1,7 @@
 /** Where the directory is mounted inside an opted-in container. */
 export declare const COVERAGE_CONTAINER_DIR = "/spectest/coverage";
 /** Raw bytes of reports one service may ship per capture. Reports are
- *  cumulative and bounded by code size, so anything past this is a
+ *  bounded by code size times chain depth, so anything past this is a
  *  runaway (a tool writing a new file per request), not coverage. */
 export declare const COVERAGE_MAX_BYTES_PER_SERVICE: number;
 /** Root of the per-service host directories, under the workspace so the
@@ -44,14 +44,33 @@ export interface CoverageBundle {
 }
 /** True when `text` holds at least one lcov `SF:` record. */
 export declare function hasLcovSourceFile(text: string): boolean;
+/** True when `text` is lcov-shaped: at least one line, every non-blank
+ *  line an `XX:` record or `end_of_record`. An lcov with no `SF:` record
+ *  at all (`TN:` alone) is well-formed — it is a report that says
+ *  nothing ran. */
+export declare function isLcovShaped(text: string): boolean;
+/**
+ * True when `text` looks like a V8 coverage JSON document — what
+ * `NODE_V8_COVERAGE` / `v8.takeCoverage()` write: an object with a
+ * `result` array of scripts. A cheap shape check, not a parse (a report
+ * can be megabytes); the control plane parses for real.
+ */
+export declare function isV8CoverageJson(text: string): boolean;
+/** True when `text` is a report spectest stores: lcov or V8 JSON. */
+export declare function isWellFormedReport(text: string): boolean;
+/** True when a well-formed report names no source file at all (an lcov
+ *  with no `SF:`, a V8 document with an empty `result`). */
+export declare function isEmptyReport(text: string): boolean;
 /** Every regular file under `dir`, recursively, as paths relative to it.
  *  Hidden files are skipped (a tool's own bookkeeping — `.seq`, `.lock`,
  *  a tmp file mid-write — is not a report). */
 export declare function listReportFiles(dir: string): Promise<string[]>;
 /**
- * Read every report under `dir`, verbatim. An empty directory, or one with
- * no `SF:` record anywhere, is an error rather than an empty capture: the
- * contract is that an opted-in service always has a report to read.
+ * Read every report under `dir`, verbatim. An empty directory, or a file
+ * that is neither lcov nor V8 JSON, is an error rather than an empty
+ * capture: the contract is that an opted-in service always has a
+ * well-formed report to read. A report that names no file is fine — it
+ * says nothing ran.
  */
 export declare function readCoverageDir(service: string, dir: string): Promise<ServiceCoverageCapture>;
 /** Gzip a case's captures into the bundle `coverageChunk` serves. */

package/dist/harness/coverage.js

@@ -2,12 +2,15 @@
 //
 // A service that opts in (`coverage: true | { command }`) gets a writable
 // directory bind-mounted at `/spectest/coverage/` in its container. The
-// service's own tool writes lcov reports there. The daemon reads the
+// service's own tool, or its coverage adapters, write reports there —
+// lcov, or the V8 coverage JSON that `NODE_V8_COVERAGE` writes. The daemon reads the
 // directory from the VM side (no `docker exec` to fetch) after bring-up
 // and after each test, and ships the reports **verbatim** to the control
 // plane as a gzipped bundle. Nothing is interpreted here beyond the one
-// contract the harness must fail a case on: at least one report, and at
-// least one lcov `SF:` record among them. The server derives whatever it
+// contract the harness must fail a case on: at least one report, every
+// one well-formed. Counters may reset between dumps and a dump may be a
+// new file: the directory forks with the environment, so it accumulates
+// along the ancestor chain by itself. The server derives whatever it
 // needs (today the set of source files; later, finer things) from the
 // stored bytes, so a change in that derivation is a re-read of stored
 // runs, never a hole in the history.
@@ -19,7 +22,7 @@ import { gzipSync } from "node:zlib";
 /** Where the directory is mounted inside an opted-in container. */
 export const COVERAGE_CONTAINER_DIR = "/spectest/coverage";
 /** Raw bytes of reports one service may ship per capture. Reports are
- *  cumulative and bounded by code size, so anything past this is a
+ *  bounded by code size times chain depth, so anything past this is a
  *  runaway (a tool writing a new file per request), not coverage. */
 export const COVERAGE_MAX_BYTES_PER_SERVICE = 64 * 1024 * 1024;
 /** Root of the per-service host directories, under the workspace so the
@@ -31,6 +34,34 @@ export function coverageHostDir(workspace, service) {
 export function hasLcovSourceFile(text) {
     return /^SF:\S/m.test(text);
 }
+/** True when `text` is lcov-shaped: at least one line, every non-blank
+ *  line an `XX:` record or `end_of_record`. An lcov with no `SF:` record
+ *  at all (`TN:` alone) is well-formed — it is a report that says
+ *  nothing ran. */
+export function isLcovShaped(text) {
+    const lines = text.split(/\r?\n/).filter((l) => l.trim().length > 0);
+    return lines.length > 0 && lines.every((l) => /^[A-Z]{2,5}:/.test(l) || l.trim() === "end_of_record");
+}
+/**
+ * True when `text` looks like a V8 coverage JSON document — what
+ * `NODE_V8_COVERAGE` / `v8.takeCoverage()` write: an object with a
+ * `result` array of scripts. A cheap shape check, not a parse (a report
+ * can be megabytes); the control plane parses for real.
+ */
+export function isV8CoverageJson(text) {
+    return /^\s*\{/.test(text) && /"result"\s*:\s*\[/.test(text);
+}
+/** True when `text` is a report spectest stores: lcov or V8 JSON. */
+export function isWellFormedReport(text) {
+    return isLcovShaped(text) || isV8CoverageJson(text);
+}
+/** True when a well-formed report names no source file at all (an lcov
+ *  with no `SF:`, a V8 document with an empty `result`). */
+export function isEmptyReport(text) {
+    if (isV8CoverageJson(text))
+        return /"result"\s*:\s*\[\s*\]/.test(text);
+    return !hasLcovSourceFile(text);
+}
 /** Every regular file under `dir`, recursively, as paths relative to it.
  *  Hidden files are skipped (a tool's own bookkeeping — `.seq`, `.lock`,
  *  a tmp file mid-write — is not a report). */
@@ -58,9 +89,11 @@ export async function listReportFiles(dir) {
     return out.sort();
 }
 /**
- * Read every report under `dir`, verbatim. An empty directory, or one with
- * no `SF:` record anywhere, is an error rather than an empty capture: the
- * contract is that an opted-in service always has a report to read.
+ * Read every report under `dir`, verbatim. An empty directory, or a file
+ * that is neither lcov nor V8 JSON, is an error rather than an empty
+ * capture: the contract is that an opted-in service always has a
+ * well-formed report to read. A report that names no file is fine — it
+ * says nothing ran.
  */
 export async function readCoverageDir(service, dir) {
     const names = await listReportFiles(dir);
@@ -68,12 +101,13 @@ export async function readCoverageDir(service, dir) {
         return {
             service,
             reports: [],
-            error: `service "${service}" opted in to coverage but ${COVERAGE_CONTAINER_DIR}/ holds no report — the service (or its coverage command) must write an lcov file there`,
+            error: `service "${service}" opted in to coverage but ${COVERAGE_CONTAINER_DIR}/ holds no report — the service (or its coverage command) must write an lcov or V8 coverage JSON file there`,
         };
     }
     const reports = [];
     let total = 0;
-    let anyLcov = false;
+    let anyReport = false;
+    const malformed = [];
     for (const name of names) {
         let content;
         try {
@@ -87,18 +121,20 @@ export async function readCoverageDir(service, dir) {
             return {
                 service,
                 reports: [],
-                error: `service "${service}" has more than ${COVERAGE_MAX_BYTES_PER_SERVICE >> 20} MiB of reports in ${COVERAGE_CONTAINER_DIR}/ — reports must be cumulative, not one file per dump`,
+                error: `service "${service}" has more than ${COVERAGE_MAX_BYTES_PER_SERVICE >> 20} MiB of reports in ${COVERAGE_CONTAINER_DIR}/ — that is a runaway, not coverage`,
             };
         }
-        if (hasLcovSourceFile(content))
-            anyLcov = true;
+        if (isWellFormedReport(content))
+            anyReport = true;
+        else
+            malformed.push(name);
         reports.push({ name, content });
     }
-    if (!anyLcov) {
+    if (!anyReport || malformed.length > 0) {
         return {
             service,
             reports,
-            error: `service "${service}" wrote ${reports.length} file(s) to ${COVERAGE_CONTAINER_DIR}/ but none holds an lcov \`SF:\` record — only lcov reports are read`,
+            error: `service "${service}" wrote ${reports.length} file(s) to ${COVERAGE_CONTAINER_DIR}/ but ${anyReport ? `${malformed.slice(0, 5).join(", ")} ${malformed.length === 1 ? "is" : "are"} neither` : "none is"} an lcov report or a V8 coverage JSON document — only those two formats are read`,
         };
     }
     return { service, reports };

package/dist/index.d.ts

@@ -20,6 +20,8 @@ export type { Mobile, MobileApp } from "./mobile.js";
 import type { Mobile, MobileApp } from "./mobile.js";
 export type { Terminal, TerminalOpts, TerminalResult } from "./terminal.js";
 import type { Terminal, TerminalOpts, TerminalResult } from "./terminal.js";
+export { type CoverageAdapter, type CoverageCaptureContext, type CoverageConfigureInfo, type CoverageLoadContext, type ServiceCoverage, } from "./coverage.js";
+import { type ServiceCoverage } from "./coverage.js";
 export { certificate, dnsName, proxy, provides, lowerIngress, isWildcard, SELF_SERVICE_TOKEN, } from "./ingress.js";
 export type { CertificateDecl, DnsDecl, ProxyDecl, IngressDecl, DnsTarget, LoweredIngress, } from "./ingress.js";
 import type { DnsTarget } from "./ingress.js";
@@ -119,20 +121,24 @@ export interface ServiceConfig {
      * Opt this service in to **code coverage collection** (experimental).
      *
      * The service gets a writable directory bind-mounted at
-     * `/spectest/coverage/`. The service's own coverage tool writes **lcov**
-     * reports there — cumulative from process start, never reset. After
-     * bring-up and after every test, spectest runs `command` (if given) inside
-     * the container, then reads every file in the directory and records the
-     * set of source files that ran. Only the `SF:` records are read.
+     * `/spectest/coverage/`. After bring-up and after every test, spectest
+     * reads every file in it — **lcov** or **V8 coverage JSON**, verbatim —
+     * and stores them with the test; the control plane derives what ran.
      *
-     * - `true`: the service writes its reports by itself (a dump on a timer,
-     *   an exit-time dump for short-lived processes).
-     * - `{ command }`: run this (via `sh -c`) in the container to make the
-     *   service write a report, before the directory is read.
+     * - `true`: the program writes its own reports there (an exit-time dump
+     *   for a short-lived process, a dump on a timer, its own hook).
+     * - `{ adapters: [...] }`: spectest gets the reports out. From
+     *   `@specific.dev/spectest/coverage`: `node()` (V8 JSON from a node
+     *   service, through a hook spectest mounts), `browser()` (the frontend
+     *   this service serves, collected from the guest browser),
+     *   `command(cmd)` (run a command in the container first), or your own
+     *   via `defineAdapter`.
      *
-     * The directory must hold at least one lcov report each time it is read;
-     * an empty directory or a failed command fails the test with a clear
-     * error, so a hole in the coverage data is never silent. See
+     * The directory must hold at least one well-formed report each time it
+     * is read; an empty directory or a failing adapter fails the test with a
+     * clear error, so a hole in the coverage data is never silent. Reports
+     * accumulate along the test's ancestor chain by themselves (the
+     * directory forks with the environment). See
      * `spectest docs /services/coverage`.
      */
     coverage?: ServiceCoverage;
@@ -663,29 +669,6 @@ export type ServiceImage = {
     /** Extra glob patterns to exclude from the build context. */
     exclude?: readonly string[];
 };
-/**
- * A service's opt-in to coverage collection — see `ServiceConfig.coverage`.
- * `true` when the service writes its own reports; `{ command }` when
- * spectest must run a command in the container to produce one.
- */
-export type ServiceCoverage = true | {
-    /** Run this (via `sh -c`) in the container before the coverage
-     *  directory is read, so the service writes a fresh lcov report. */
-    command?: string;
-    /**
-     * Collect **frontend** coverage for the app this service serves.
-     * The code runs in the guest browser — spectest's own process — so
-     * the user cannot write a report for it: spectest turns on V8
-     * coverage for every script `ctx.browser()`/`ctx.mobile()` loads
-     * from this service's origin, maps it back to original sources
-     * through the served source maps, and adds one lcov report to this
-     * service's capture. Scripts a source map can't resolve are
-     * attributed to their served path (which the repo mapping then
-     * treats as unknown — the safe answer). Needs the app to serve
-     * source maps to the test environment.
-     */
-    browser?: boolean;
-};
 export interface VolumeMount {
     /**
      * Named shared volume. Two services mounting the same `name` share one
@@ -898,17 +881,6 @@ export interface FakeContext {
      *  for a TLS-provisioning provider hands back to the app under test. */
     certificate(hostnames: readonly string[]): Promise<CertificateMaterial>;
 }
-/**
- * Check one service's `coverage` field. Exported so the daemon applies the
- * same rule to a runtime `startService` spec.
- */
-export declare function validateCoverage(service: string, cov: unknown): void;
-/** Whether a `coverage` value collects reports from the container's own
- *  filesystem (`/spectest/coverage/`). True for `true`, `{ command }`, and
- *  any object that isn't browser-only. */
-export declare function coverageUsesContainer(cov: ServiceCoverage | undefined): boolean;
-/** Whether a `coverage` value collects frontend (browser) coverage. */
-export declare function coverageUsesBrowser(cov: ServiceCoverage | undefined): boolean;
 /**
  * A single test step. Created via `test(...)` or `createTest(services)`.
  * Tests are referenced (not named by string) when one test depends on

package/dist/index.js

@@ -40,6 +40,7 @@ export { McpHttpError, McpRpcError, McpAuthDeniedError, } from "./mcp.js";
 import { isLocator, getLocatorProbe, isBrowserSession, getBrowserProbe, DEFAULT_ACTION_TIMEOUT_MS, } from "./locator.js";
 import { formatWaited, locatorFailureMessage } from "./locator-errors.js";
 import { describeUrlPattern, matchesUrl } from "./url-match.js";
+import { applyCoverageAdapters, validateCoverage } from "./coverage.js";
 // Low-level ingress primitives + the framework lowering that the friendly
 // `tls` / `hostnames` fields and `defineFake(...)` are built on. See
 // `ingress.ts`.
@@ -215,37 +216,6 @@ function expandServiceGroups(input) {
     }
     return out;
 }
-/**
- * Check one service's `coverage` field. Exported so the daemon applies the
- * same rule to a runtime `startService` spec.
- */
-export function validateCoverage(service, cov) {
-    if (cov === undefined || cov === true)
-        return;
-    if (typeof cov === "object" && cov !== null) {
-        const o = cov;
-        const cmdOk = o.command === undefined ||
-            (typeof o.command === "string" && o.command.trim().length > 0);
-        const browserOk = o.browser === undefined || typeof o.browser === "boolean";
-        if (cmdOk && browserOk && (o.command !== undefined || o.browser === true))
-            return;
-    }
-    throw new Error(`service "${service}" has an invalid \`coverage\` value — use \`true\`, \`{ command: "<shell command>" }\`, or \`{ browser: true }\``);
-}
-/** Whether a `coverage` value collects reports from the container's own
- *  filesystem (`/spectest/coverage/`). True for `true`, `{ command }`, and
- *  any object that isn't browser-only. */
-export function coverageUsesContainer(cov) {
-    if (cov === undefined)
-        return false;
-    if (cov === true)
-        return true;
-    return cov.command !== undefined || cov.browser !== true;
-}
-/** Whether a `coverage` value collects frontend (browser) coverage. */
-export function coverageUsesBrowser(cov) {
-    return typeof cov === "object" && cov.browser === true;
-}
 function validateEnvironmentConfig(config) {
     const entries = Object.entries(config.services);
     const serviceNames = new Set(entries.map(([n]) => n));
@@ -353,9 +323,13 @@ export function defineEnvironment(input) {
     // { name, services, timeoutSecs } — with plain, fully-expanded services —
     // is stored as `config` and shipped to the control plane.
     const { fakes, services: rawServices, ...rest } = input;
+    const expanded = expandServiceGroups(rawServices);
+    for (const [key, svc] of Object.entries(expanded)) {
+        expanded[key] = applyCoverageAdapters(key, svc);
+    }
     const config = {
         ...rest,
-        services: expandServiceGroups(rawServices),
+        services: expanded,
     };
     validateEnvironmentConfig(config);
     if (fakes)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.58.0",
+  "version": "0.59.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,6 +16,11 @@
       "bun": "./src/components/index.ts",
       "default": "./dist/components/index.js"
     },
+    "./coverage": {
+      "types": "./dist/coverage.d.ts",
+      "bun": "./src/coverage.ts",
+      "default": "./dist/coverage.js"
+    },
     "./browser": {
       "types": "./dist/browser.d.ts",
       "bun": "./src/browser.ts",

package/src/coverage.test.ts

@@ -0,0 +1,192 @@
+import { describe, expect, test } from "bun:test";
+import { spawn, type ChildProcess } from "node:child_process";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  NODE_COVERAGE_HOOK,
+  NODE_COVERAGE_HOOK_PATH,
+  NODE_COVERAGE_SOCKET,
+  applyCoverageAdapters,
+  appendEnvFlag,
+  browser,
+  command,
+  node,
+  validateCoverage,
+  type CoverageCaptureContext,
+} from "./coverage.js";
+import type { ServiceConfig } from "./index.js";
+
+const base: ServiceConfig = {
+  image: { type: "registry", reference: "node:20" },
+  command: "node server.js",
+  env: { NODE_OPTIONS: "--max-old-space-size=512" },
+};
+
+describe("validateCoverage", () => {
+  test("accepts true, a list of adapters, nothing else", () => {
+    validateCoverage("a", undefined);
+    validateCoverage("a", true);
+    validateCoverage("a", { adapters: [node(), { name: "x" }] });
+    expect(() => validateCoverage("a", false)).toThrow(/invalid `coverage` value/);
+    expect(() => validateCoverage("a", { command: "x" })).toThrow(/invalid `coverage` value/);
+    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/);
+  });
+});
+
+describe("applyCoverageAdapters", () => {
+  test("node: appends NODE_OPTIONS, sets NODE_V8_COVERAGE, mounts the hook", () => {
+    const out = applyCoverageAdapters("api", { ...base, coverage: { adapters: [node()] } });
+    expect(out.env?.NODE_OPTIONS).toBe(`--max-old-space-size=512 --require ${NODE_COVERAGE_HOOK_PATH}`);
+    expect(out.env?.NODE_V8_COVERAGE).toBe("/spectest/coverage");
+    expect(out.files?.map((f) => f.path)).toEqual([NODE_COVERAGE_HOOK_PATH]);
+    expect(out.files?.[0]?.content).toBe(NODE_COVERAGE_HOOK);
+  });
+  test("the adapters stay on the config for the harness, and serialize as names", () => {
+    const out = applyCoverageAdapters("api", { ...base, coverage: { adapters: [node(), browser()] } });
+    const list = (out.coverage as { adapters: readonly { name: string; capture?: unknown; load?: unknown }[] }).adapters;
+    expect(list.map((a) => a.name)).toEqual(["node", "browser"]);
+    expect(typeof list[0]?.capture).toBe("function");
+    expect(typeof list[1]?.load).toBe("function");
+    expect(JSON.parse(JSON.stringify(out)).coverage).toEqual({
+      adapters: [{ adapter: "node" }, { adapter: "browser" }],
+    });
+  });
+  test("true and undefined pass through untouched", () => {
+    const t = { ...base, coverage: true as const };
+    expect(applyCoverageAdapters("api", t)).toBe(t);
+    expect(applyCoverageAdapters("api", base)).toBe(base);
+  });
+  test("appendEnvFlag sets when absent", () => {
+    expect(appendEnvFlag(undefined, "X", "a")).toEqual({ X: "a" });
+    expect(appendEnvFlag({ X: " b " }, "X", "a")).toEqual({ X: "b a" });
+  });
+  test("coverage.command refuses an empty command", () => {
+    expect(() => command("  ")).toThrow(/non-empty/);
+  });
+});
+
+/** A capture context over a real directory, no container. */
+function fakeCtx(dir: string, signal = new AbortController().signal): CoverageCaptureContext {
+  return {
+    service: "api",
+    reportDir: dir,
+    signal,
+    async exec() {
+      throw new Error("no container");
+    },
+    async writeReport(name, content) {
+      await fs.writeFile(path.join(dir, name), content);
+    },
+  };
+}
+
+describe("browserCoverage", () => {
+  test("writes an empty lcov when nothing ran for the service", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-cov-"));
+    await browser().capture!(fakeCtx(dir));
+    expect(await fs.readFile(path.join(dir, "browser.lcov"), "utf8")).toBe("TN:\n");
+  });
+});
+
+// The node hook against a real `node` (the box has one; skipped where it
+// does not). A long-lived process armed with the hook must answer the
+// socket with a fresh V8 report; a second process must stay a bystander
+// and exit on its own; the socket path must work across a bind mount —
+// which is what a plain directory path stands in for here.
+const hasNode = await new Promise<boolean>((resolve) => {
+  const p = spawn("node", ["--version"]);
+  p.on("error", () => resolve(false));
+  p.on("exit", (code) => resolve(code === 0));
+});
+
+describe.if(hasNode)("nodeCoverage hook (real node)", () => {
+  async function startServer(dir: string): Promise<ChildProcess> {
+    const hook = path.join(dir, "hook.cjs");
+    await fs.writeFile(hook, NODE_COVERAGE_HOOK);
+    const server = path.join(dir, "server.js");
+    await fs.writeFile(server, "setInterval(() => {}, 1000); process.stdout.write('up\\n');\n");
+    const child = spawn("node", ["--require", hook, server], {
+      env: { ...process.env, NODE_V8_COVERAGE: dir },
+      stdio: ["ignore", "pipe", "inherit"],
+    });
+    await new Promise<void>((resolve) => child.stdout!.once("data", () => resolve()));
+    // The socket is bound after the module graph runs; wait for it.
+    const sock = path.join(dir, NODE_COVERAGE_SOCKET);
+    for (let i = 0; i < 100; i++) {
+      try {
+        await fs.stat(sock);
+        break;
+      } catch {
+        await new Promise((r) => setTimeout(r, 20));
+      }
+    }
+    return child;
+  }
+
+  test("capture asks the live server for a dump; a bystander exits on its own", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-covhook-"));
+    const server = await startServer(dir);
+    try {
+      const reportsBefore = (await fs.readdir(dir)).filter((n) => n.startsWith("coverage-"));
+      expect(reportsBefore).toEqual([]);
+      await node().capture!(fakeCtx(dir));
+      const reports = (await fs.readdir(dir)).filter((n) => n.startsWith("coverage-"));
+      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);
+
+      // A second process with the same env: the socket is held, so it must
+      // not try to serve, and it must exit (the server's socket is unref'd,
+      // so a bystander is never kept alive by it).
+      const bystander = spawn("node", ["--require", path.join(dir, "hook.cjs"), "-e", "1"], {
+        env: { ...process.env, NODE_V8_COVERAGE: dir },
+        stdio: "ignore",
+      });
+      const code = await new Promise<number | null>((resolve) => bystander.on("exit", resolve));
+      expect(code).toBe(0);
+      // …and it wrote its own exit-time report, as every node process does.
+      const after = (await fs.readdir(dir)).filter((n) => n.startsWith("coverage-"));
+      expect(after.length).toBe(2);
+
+      // The live server still answers.
+      await node().capture!(fakeCtx(dir));
+      expect((await fs.readdir(dir)).filter((n) => n.startsWith("coverage-")).length).toBe(3);
+    } finally {
+      server.kill("SIGKILL");
+    }
+  });
+
+  test("a stale socket left by a dead process is reclaimed", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-covhook-"));
+    const first = await startServer(dir);
+    first.kill("SIGKILL");
+    await new Promise<void>((resolve) => first.on("exit", () => resolve()));
+    expect(await fs.stat(path.join(dir, NODE_COVERAGE_SOCKET))).toBeTruthy(); // stale file
+    const second = await startServer(dir);
+    try {
+      // Give the EADDRINUSE → probe → unlink → listen dance a moment.
+      let ok = false;
+      for (let i = 0; i < 50 && !ok; i++) {
+        try {
+          await node().capture!(fakeCtx(dir));
+          ok = true;
+        } catch {
+          await new Promise((r) => setTimeout(r, 50));
+        }
+      }
+      expect(ok).toBe(true);
+    } finally {
+      second.kill("SIGKILL");
+    }
+  });
+
+  test("no server: capture fails naming the socket", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-covhook-"));
+    await expect(node().capture!(fakeCtx(dir))).rejects.toThrow(/no node process is serving/);
+  });
+});