@specific.dev/spectest 0.59.0 → 0.59.2

package/dist/coverage.d.ts

@@ -3,8 +3,9 @@ import { COVERAGE_CONTAINER_DIR } from "./harness/coverage.js";
 export { COVERAGE_CONTAINER_DIR };
 /** Where `node()` mounts its hook inside the container. */
 export declare const NODE_COVERAGE_HOOK_PATH = "/spectest/coverage-hook.cjs";
-/** The socket the node hook answers on, relative to the coverage dir. */
-export declare const NODE_COVERAGE_SOCKET = ".ctl";
+/** 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-";
 /** What `configure` learns about the service it rewrites. */
 export interface CoverageConfigureInfo {
     /** The services-map key. */
@@ -85,28 +86,57 @@ export declare function applyCoverageAdapters<S extends ServiceConfig>(key: stri
 /** `env` with `value` appended to `name` (space-separated), or set. */
 export declare function appendEnvFlag(env: Readonly<Record<string, string>> | undefined, name: string, value: string): Record<string, string>;
 /**
- * The hook `node()` mounts and `--require`s into every node
- * process of the container. Node writes V8 coverage JSON into
- * `NODE_V8_COVERAGE` when a process exits; a long-lived server never
- * exits, so the hook binds a Unix socket in the coverage directory and
- * calls `v8.takeCoverage()` for each connection. The first process to
- * start owns the socket (a stale socket left by a dead process is
- * reclaimed); a later process — a CLI run by `ctx.exec` — leaves it
- * alone and writes at its own exit. No signal is used: signals are
- * claimed by frameworks (SIGUSR2 stops a Temporal worker, restarts
- * nodemon), a socket is nobody's.
+ * The hook `node()` mounts and `--require`s into every node process of
+ * the container. Node writes V8 coverage JSON into `NODE_V8_COVERAGE`
+ * when a process exits; a long-lived server never exits, so the hook
+ * binds a Unix socket in the coverage directory and calls
+ * `v8.takeCoverage()` on request. **Every** process binds its own socket
+ * (`.ctl-<pid>`) — there is no "first process owns it" rule, because the
+ * first node process is often a wrapper (`pnpm exec`, the `tsx` binary,
+ * `npm run`) whose child is the real server; a single socket on the
+ * 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.
+ * No signal is used: signals are claimed by frameworks (SIGUSR2 stops a
+ * Temporal worker, restarts nodemon), a socket is nobody's.
  */
 export declare const NODE_COVERAGE_HOOK: string;
 /**
  * Coverage for a Node service. Sets `NODE_V8_COVERAGE` to the coverage
  * directory (every node process in the container then writes V8
  * coverage JSON when it exits) and `--require`s a hook that lets spectest
- * ask the long-lived server process for a dump at capture time. Nothing
- * for the app to write. Source maps: with `--enable-source-maps` (or a
+ * 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.
  */
 export declare function node(): CoverageAdapter;
+/**
+ * Ask every node process that holds a hook socket in `dir` for a dump.
+ * A socket nobody answers (its process died without unlinking — SIGKILL,
+ * OOM) is removed. Returns how many processes answered; a process that
+ * answered with an error throws.
+ */
+export declare function dumpAllNodeProcesses(dir: string, signal: AbortSignal): Promise<number>;
+/** A script is the app's own when it is a file outside node_modules. */
+export declare function isAppScriptUrl(url: string): boolean;
+/**
+ * Compact one V8 coverage document to the app's own scripts. What Node
+ * writes is everything the process loaded: `node:` internals, every
+ * `node_modules` file, and — under `--enable-source-maps` — a
+ * `source-map-cache` with each file's full map **and its sources**,
+ * repeated in every dump. Measured on a real project: a 12–20 MiB dump
+ * 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.
+ */
+export declare function compactV8Document(doc: Record<string, unknown>): Record<string, unknown>;
+/** Compact every not-yet-compacted V8 document in `dir`, in place. */
+export declare function compactV8Reports(dir: string): Promise<void>;
 /**
  * Coverage for the frontend a service serves. The code runs in the guest
  * browser — spectest's own process — so no report can be written by the

package/dist/coverage.js

@@ -29,8 +29,9 @@ import { COVERAGE_CONTAINER_DIR } from "./harness/coverage.js";
 export { COVERAGE_CONTAINER_DIR };
 /** Where `node()` mounts its hook inside the container. */
 export const NODE_COVERAGE_HOOK_PATH = "/spectest/coverage-hook.cjs";
-/** The socket the node hook answers on, relative to the coverage dir. */
-export const NODE_COVERAGE_SOCKET = ".ctl";
+/** 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-";
 /** Type an inline adapter. Identity at runtime. */
 export function defineAdapter(adapter) {
     return adapter;
@@ -95,16 +96,19 @@ export function appendEnvFlag(env, name, value) {
 }
 // ── node ──────────────────────────────────────────────────────────
 /**
- * The hook `node()` mounts and `--require`s into every node
- * process of the container. Node writes V8 coverage JSON into
- * `NODE_V8_COVERAGE` when a process exits; a long-lived server never
- * exits, so the hook binds a Unix socket in the coverage directory and
- * calls `v8.takeCoverage()` for each connection. The first process to
- * start owns the socket (a stale socket left by a dead process is
- * reclaimed); a later process — a CLI run by `ctx.exec` — leaves it
- * alone and writes at its own exit. No signal is used: signals are
- * claimed by frameworks (SIGUSR2 stops a Temporal worker, restarts
- * nodemon), a socket is nobody's.
+ * The hook `node()` mounts and `--require`s into every node process of
+ * the container. Node writes V8 coverage JSON into `NODE_V8_COVERAGE`
+ * when a process exits; a long-lived server never exits, so the hook
+ * binds a Unix socket in the coverage directory and calls
+ * `v8.takeCoverage()` on request. **Every** process binds its own socket
+ * (`.ctl-<pid>`) — there is no "first process owns it" rule, because the
+ * first node process is often a wrapper (`pnpm exec`, the `tsx` binary,
+ * `npm run`) whose child is the real server; a single socket on the
+ * 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.
+ * 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\`.
@@ -112,10 +116,9 @@ if (process.env.NODE_V8_COVERAGE) {
   const net = require("node:net");
   const fs = require("node:fs");
   const v8 = require("node:v8");
-  const SOCK = require("node:path").join(process.env.NODE_V8_COVERAGE, ${JSON.stringify(NODE_COVERAGE_SOCKET)});
+  const SOCK = require("node:path").join(process.env.NODE_V8_COVERAGE, ${JSON.stringify(NODE_COVERAGE_SOCKET_PREFIX)} + process.pid);
   const server = net.createServer((conn) => {
-    // A dump is taken only on an explicit "dump" request: a bystander's
-    // liveness probe connects and closes without one.
+    // A dump is taken only on an explicit "dump" request.
     let buf = "";
     conn.on("data", (chunk) => {
       buf += chunk;
@@ -132,26 +135,20 @@ if (process.env.NODE_V8_COVERAGE) {
     });
   });
   server.unref();
-  server.on("error", (err) => {
-    if (err.code !== "EADDRINUSE") return;
-    // Someone holds the socket. If it answers, it is the live server and
-    // this process is a bystander; if not, it is a stale file.
-    const probe = net.connect(SOCK);
-    probe.on("connect", () => probe.destroy());
-    probe.on("error", () => {
-      try { fs.unlinkSync(SOCK); } catch {}
-      server.listen(SOCK);
-    });
-  });
+  server.on("error", () => {});
+  try { fs.unlinkSync(SOCK); } catch {}
   server.listen(SOCK);
+  process.on("exit", () => { try { fs.unlinkSync(SOCK); } catch {} });
 }
 `;
 /**
  * Coverage for a Node service. Sets `NODE_V8_COVERAGE` to the coverage
  * directory (every node process in the container then writes V8
  * coverage JSON when it exits) and `--require`s a hook that lets spectest
- * ask the long-lived server process for a dump at capture time. Nothing
- * for the app to write. Source maps: with `--enable-source-maps` (or a
+ * 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.
  */
@@ -168,34 +165,144 @@ export function node() {
             };
         },
         async capture(ctx) {
-            const { connect } = await import("node:net");
-            const path = await import("node:path");
-            const sock = path.join(ctx.reportDir, NODE_COVERAGE_SOCKET);
-            const reply = await new Promise((resolve, reject) => {
-                const chunks = [];
-                const c = connect(sock, () => c.write("dump\n"));
-                const onAbort = () => {
-                    c.destroy();
-                    reject(new Error("timed out waiting for the node hook to write a report"));
-                };
-                ctx.signal.addEventListener("abort", onAbort, { once: true });
-                c.on("data", (b) => chunks.push(b));
-                c.on("error", (err) => {
-                    ctx.signal.removeEventListener("abort", onAbort);
-                    reject(new Error(err.code === "ENOENT" || err.code === "ECONNREFUSED"
-                        ? `no node process is serving ${COVERAGE_CONTAINER_DIR}/${NODE_COVERAGE_SOCKET} — is the service's main process node, and does it run with the service's env (NODE_OPTIONS)?`
-                        : err.message));
-                });
-                c.on("close", () => {
-                    ctx.signal.removeEventListener("abort", onAbort);
-                    resolve(Buffer.concat(chunks).toString("utf8").trim());
-                });
-            });
-            if (reply !== "ok")
-                throw new Error(`the node hook answered: ${reply || "(nothing)"}`);
+            const live = await dumpAllNodeProcesses(ctx.reportDir, ctx.signal);
+            if (live === 0) {
+                throw new Error(`no node process is serving a ${COVERAGE_CONTAINER_DIR}/${NODE_COVERAGE_SOCKET_PREFIX}<pid> socket — does the service run node with the service's env (NODE_OPTIONS), and is it still alive?`);
+            }
+            await compactV8Reports(ctx.reportDir);
         },
     };
 }
+/**
+ * Ask every node process that holds a hook socket in `dir` for a dump.
+ * A socket nobody answers (its process died without unlinking — SIGKILL,
+ * OOM) is removed. Returns how many processes answered; a process that
+ * answered with an error throws.
+ */
+export async function dumpAllNodeProcesses(dir, signal) {
+    const fs = await import("node:fs/promises");
+    const path = await import("node:path");
+    const { connect } = await import("node:net");
+    let names;
+    try {
+        names = (await fs.readdir(dir)).filter((n) => n.startsWith(NODE_COVERAGE_SOCKET_PREFIX));
+    }
+    catch {
+        return 0;
+    }
+    let live = 0;
+    for (const name of names) {
+        const sock = path.join(dir, name);
+        const reply = await new Promise((resolve, reject) => {
+            const chunks = [];
+            const c = connect(sock, () => c.write("dump\n"));
+            const onAbort = () => {
+                c.destroy();
+                reject(new Error(`timed out waiting for the node hook (${name}) to write a report`));
+            };
+            signal.addEventListener("abort", onAbort, { once: true });
+            c.on("data", (b) => chunks.push(b));
+            c.on("error", (err) => {
+                signal.removeEventListener("abort", onAbort);
+                if (err.code === "ENOENT" || err.code === "ECONNREFUSED")
+                    resolve(null);
+                else
+                    reject(err);
+            });
+            c.on("close", (hadError) => {
+                signal.removeEventListener("abort", onAbort);
+                if (!hadError)
+                    resolve(Buffer.concat(chunks).toString("utf8").trim());
+            });
+        });
+        if (reply === null) {
+            // Nobody home: the process is gone. Clean up so the next capture
+            // does not knock again.
+            await fs.unlink(sock).catch(() => { });
+            continue;
+        }
+        if (reply !== "ok")
+            throw new Error(`the node hook (${name}) answered: ${reply || "(nothing)"}`);
+        live++;
+    }
+    return live;
+}
+/** V8 files already compacted, by path. Module memory: forks with the
+ *  environment, so a child never re-parses its ancestors' dumps. */
+const COMPACTED_V8_REPORTS = new Set();
+/** A script is the app's own when it is a file outside node_modules. */
+export function isAppScriptUrl(url) {
+    return url.startsWith("file://") && !url.includes("/node_modules/");
+}
+/**
+ * Compact one V8 coverage document to the app's own scripts. What Node
+ * writes is everything the process loaded: `node:` internals, every
+ * `node_modules` file, and — under `--enable-source-maps` — a
+ * `source-map-cache` with each file's full map **and its sources**,
+ * repeated in every dump. Measured on a real project: a 12–20 MiB dump
+ * 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.
+ */
+export function compactV8Document(doc) {
+    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 };
+    const cache = doc["source-map-cache"];
+    if (cache && typeof cache === "object") {
+        const urls = new Set(kept.map((s) => s.url));
+        const slim = {};
+        for (const [url, entry] of Object.entries(cache)) {
+            if (!urls.has(url) || !entry || typeof entry !== "object")
+                continue;
+            const e = { ...entry };
+            if (e.data && typeof e.data === "object") {
+                const { sourcesContent: _dropped, ...data } = e.data;
+                e.data = data;
+            }
+            slim[url] = e;
+        }
+        if (Object.keys(slim).length > 0)
+            out["source-map-cache"] = slim;
+        else
+            delete out["source-map-cache"];
+    }
+    return out;
+}
+/** Compact every not-yet-compacted V8 document in `dir`, in place. */
+export async function compactV8Reports(dir) {
+    const fs = await import("node:fs/promises");
+    const path = await import("node:path");
+    let names;
+    try {
+        names = await fs.readdir(dir);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        if (!name.startsWith("coverage-") || !name.endsWith(".json"))
+            continue;
+        const file = path.join(dir, name);
+        if (COMPACTED_V8_REPORTS.has(file))
+            continue;
+        let doc;
+        try {
+            doc = JSON.parse(await fs.readFile(file, "utf8"));
+        }
+        catch {
+            continue; // a dump mid-write, or not ours; the read path judges it
+        }
+        if (!Array.isArray(doc.result))
+            continue;
+        const tmp = path.join(dir, `.${name}.compact`);
+        await fs.writeFile(tmp, JSON.stringify(compactV8Document(doc)));
+        await fs.rename(tmp, file);
+        COMPACTED_V8_REPORTS.add(file);
+    }
+}
 // ── browser ───────────────────────────────────────────────────────
 /**
  * Coverage for the frontend a service serves. The code runs in the guest

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.59.0",
+  "version": "0.59.2",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/coverage.test.ts

@@ -6,11 +6,13 @@ import path from "node:path";
 import {
   NODE_COVERAGE_HOOK,
   NODE_COVERAGE_HOOK_PATH,
-  NODE_COVERAGE_SOCKET,
+  NODE_COVERAGE_SOCKET_PREFIX,
   applyCoverageAdapters,
   appendEnvFlag,
   browser,
   command,
+  compactV8Document,
+  compactV8Reports,
   node,
   validateCoverage,
   type CoverageCaptureContext,
@@ -68,6 +70,45 @@ describe("applyCoverageAdapters", () => {
   });
 });
 
+describe("compactV8Document", () => {
+  const doc = {
+    result: [
+      { 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: "4", url: "", functions: [] },
+    ],
+    "source-map-cache": {
+      "file:///app/src/a.ts": { lineLengths: [1], data: { mappings: "AAAA", sources: ["a.ts"], sourcesContent: ["x"] }, url: null },
+      "file:///app/node_modules/x/index.js": { lineLengths: [1], data: { mappings: "AAAA" }, url: null },
+    },
+  };
+  test("keeps app scripts and their maps, drops the rest and sourcesContent", () => {
+    const out = compactV8Document(doc) as typeof doc;
+    expect(out.result.map((s) => s.url)).toEqual(["file:///app/src/a.ts"]);
+    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("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([]);
+    expect("source-map-cache" in out).toBe(false);
+  });
+  test("compactV8Reports rewrites coverage-*.json once and leaves other files alone", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-cov-"));
+    await fs.writeFile(path.join(dir, "coverage-1-2-0.json"), JSON.stringify(doc));
+    await fs.writeFile(path.join(dir, "browser.lcov"), "TN:\n");
+    await compactV8Reports(dir);
+    const back = JSON.parse(await fs.readFile(path.join(dir, "coverage-1-2-0.json"), "utf8")) as { result: unknown[] };
+    expect(back.result.length).toBe(1);
+    expect(await fs.readFile(path.join(dir, "browser.lcov"), "utf8")).toBe("TN:\n");
+    // Idempotent and cheap: a second pass is a no-op on the same file.
+    await fs.writeFile(path.join(dir, "coverage-1-2-0.json"), "not json");
+    await compactV8Reports(dir);
+    expect(await fs.readFile(path.join(dir, "coverage-1-2-0.json"), "utf8")).toBe("not json");
+  });
+});
+
 /** A capture context over a real directory, no container. */
 function fakeCtx(dir: string, signal = new AbortController().signal): CoverageCaptureContext {
   return {
@@ -92,94 +133,116 @@ describe("browserCoverage", () => {
 });
 
 // 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.
+// does not). Every process armed with the hook must answer its own
+// socket with a fresh V8 report — including a server that sits behind a
+// wrapper process, the pnpm/tsx shape; stale sockets must be cleaned up;
+// 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));
 });
 
+const SERVER_JS = "setInterval(() => {}, 1000); process.stdout.write('up\\n');\n";
+// A wrapper that spawns the real server as a child node process and
+// waits on it — what `pnpm exec`, `npm run` and the `tsx` binary do.
+const WRAPPER_JS =
+  "const { spawn } = require('node:child_process');\n" +
+  "const c = spawn(process.execPath, [require('node:path').join(__dirname, 'server.js')], { stdio: 'inherit' });\n" +
+  "c.on('exit', (code) => process.exit(code ?? 1));\n";
+
 describe.if(hasNode)("nodeCoverage hook (real node)", () => {
-  async function startServer(dir: string): Promise<ChildProcess> {
+  async function socketsIn(dir: string): Promise<string[]> {
+    return (await fs.readdir(dir)).filter((n) => n.startsWith(NODE_COVERAGE_SOCKET_PREFIX)).sort();
+  }
+  async function reportsIn(dir: string): Promise<string[]> {
+    return (await fs.readdir(dir)).filter((n) => n.startsWith("coverage-"));
+  }
+  async function start(dir: string, entry: string, expectSockets: number): 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 },
+    await fs.writeFile(path.join(dir, "server.js"), SERVER_JS);
+    await fs.writeFile(path.join(dir, "wrapper.js"), WRAPPER_JS);
+    const child = spawn("node", [path.join(dir, entry)], {
+      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()));
-    // 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));
-      }
+    for (let i = 0; i < 100 && (await socketsIn(dir)).length < expectSockets; i++) {
+      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 () => {
+  test("capture asks the live server; a short-lived process exits and unlinks its socket", async () => {
     const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-covhook-"));
-    const server = await startServer(dir);
+    const server = await start(dir, "server.js", 1);
     try {
-      const reportsBefore = (await fs.readdir(dir)).filter((n) => n.startsWith("coverage-"));
-      expect(reportsBefore).toEqual([]);
+      expect(await reportsIn(dir)).toEqual([]);
       await node().capture!(fakeCtx(dir));
-      const reports = (await fs.readdir(dir)).filter((n) => n.startsWith("coverage-"));
+      const reports = await reportsIn(dir);
       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 },
+      const short = spawn("node", ["-e", "1"], {
+        env: { ...process.env, NODE_V8_COVERAGE: dir, NODE_OPTIONS: `--require ${path.join(dir, "hook.cjs")}` },
         stdio: "ignore",
       });
-      const code = await new Promise<number | null>((resolve) => bystander.on("exit", resolve));
+      const code = await new Promise<number | null>((resolve) => short.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);
+      expect((await socketsIn(dir)).length).toBe(1); // its socket is gone with it
+      expect((await reportsIn(dir)).length).toBe(2); // its exit-time report is there
 
-      // The live server still answers.
       await node().capture!(fakeCtx(dir));
-      expect((await fs.readdir(dir)).filter((n) => n.startsWith("coverage-")).length).toBe(3);
+      expect((await reportsIn(dir)).length).toBe(3);
     } finally {
       server.kill("SIGKILL");
     }
   });
 
-  test("a stale socket left by a dead process is reclaimed", async () => {
+  test("a server behind a wrapper process is dumped too (pnpm exec / tsx shape)", 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);
+    const wrapper = await start(dir, "wrapper.js", 2);
     try {
-      // Give the EADDRINUSE → probe → unlink → listen dance a moment.
-      let ok = false;
-      for (let i = 0; i < 50 && !ok; i++) {
+      expect((await socketsIn(dir)).length).toBe(2);
+      await node().capture!(fakeCtx(dir));
+      const reports = await reportsIn(dir);
+      expect(reports.length).toBe(2);
+      const urls = new Set<string>();
+      for (const r of reports) {
+        const doc = JSON.parse(await fs.readFile(path.join(dir, r), "utf8")) as { result: { url: string }[] };
+        for (const s of doc.result) urls.add(s.url);
+      }
+      expect([...urls].some((u) => u.endsWith("/server.js"))).toBe(true);
+      expect([...urls].some((u) => u.endsWith("/wrapper.js"))).toBe(true);
+    } finally {
+      wrapper.kill("SIGKILL");
+      // The wrapper's child is orphaned by SIGKILL; find and kill it too.
+      const pids = (await socketsIn(dir)).map((n) => Number(n.slice(NODE_COVERAGE_SOCKET_PREFIX.length)));
+      for (const pid of pids) {
         try {
-          await node().capture!(fakeCtx(dir));
-          ok = true;
-        } catch {
-          await new Promise((r) => setTimeout(r, 50));
-        }
+          process.kill(pid, "SIGKILL");
+        } catch {}
       }
-      expect(ok).toBe(true);
+    }
+  });
+
+  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);
+    first.kill("SIGKILL");
+    await new Promise<void>((resolve) => first.on("exit", () => resolve()));
+    expect((await socketsIn(dir)).length).toBe(1); // stale
+    await expect(node().capture!(fakeCtx(dir))).rejects.toThrow(/no node process is serving/);
+    expect((await socketsIn(dir)).length).toBe(0); // cleaned up
+    const second = await start(dir, "server.js", 1);
+    try {
+      await node().capture!(fakeCtx(dir));
+      expect((await reportsIn(dir)).length).toBe(1);
     } finally {
       second.kill("SIGKILL");
     }

package/src/coverage.ts

@@ -34,8 +34,9 @@ export { COVERAGE_CONTAINER_DIR };
 /** Where `node()` mounts its hook inside the container. */
 export const NODE_COVERAGE_HOOK_PATH = "/spectest/coverage-hook.cjs";
 
-/** The socket the node hook answers on, relative to the coverage dir. */
-export const NODE_COVERAGE_SOCKET = ".ctl";
+/** 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-";
 
 /** What `configure` learns about the service it rewrites. */
 export interface CoverageConfigureInfo {
@@ -178,16 +179,19 @@ export function appendEnvFlag(
 // ── node ──────────────────────────────────────────────────────────
 
 /**
- * The hook `node()` mounts and `--require`s into every node
- * process of the container. Node writes V8 coverage JSON into
- * `NODE_V8_COVERAGE` when a process exits; a long-lived server never
- * exits, so the hook binds a Unix socket in the coverage directory and
- * calls `v8.takeCoverage()` for each connection. The first process to
- * start owns the socket (a stale socket left by a dead process is
- * reclaimed); a later process — a CLI run by `ctx.exec` — leaves it
- * alone and writes at its own exit. No signal is used: signals are
- * claimed by frameworks (SIGUSR2 stops a Temporal worker, restarts
- * nodemon), a socket is nobody's.
+ * The hook `node()` mounts and `--require`s into every node process of
+ * the container. Node writes V8 coverage JSON into `NODE_V8_COVERAGE`
+ * when a process exits; a long-lived server never exits, so the hook
+ * binds a Unix socket in the coverage directory and calls
+ * `v8.takeCoverage()` on request. **Every** process binds its own socket
+ * (`.ctl-<pid>`) — there is no "first process owns it" rule, because the
+ * first node process is often a wrapper (`pnpm exec`, the `tsx` binary,
+ * `npm run`) whose child is the real server; a single socket on the
+ * 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.
+ * 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\`.
@@ -195,10 +199,9 @@ if (process.env.NODE_V8_COVERAGE) {
   const net = require("node:net");
   const fs = require("node:fs");
   const v8 = require("node:v8");
-  const SOCK = require("node:path").join(process.env.NODE_V8_COVERAGE, ${JSON.stringify(NODE_COVERAGE_SOCKET)});
+  const SOCK = require("node:path").join(process.env.NODE_V8_COVERAGE, ${JSON.stringify(NODE_COVERAGE_SOCKET_PREFIX)} + process.pid);
   const server = net.createServer((conn) => {
-    // A dump is taken only on an explicit "dump" request: a bystander's
-    // liveness probe connects and closes without one.
+    // A dump is taken only on an explicit "dump" request.
     let buf = "";
     conn.on("data", (chunk) => {
       buf += chunk;
@@ -215,18 +218,10 @@ if (process.env.NODE_V8_COVERAGE) {
     });
   });
   server.unref();
-  server.on("error", (err) => {
-    if (err.code !== "EADDRINUSE") return;
-    // Someone holds the socket. If it answers, it is the live server and
-    // this process is a bystander; if not, it is a stale file.
-    const probe = net.connect(SOCK);
-    probe.on("connect", () => probe.destroy());
-    probe.on("error", () => {
-      try { fs.unlinkSync(SOCK); } catch {}
-      server.listen(SOCK);
-    });
-  });
+  server.on("error", () => {});
+  try { fs.unlinkSync(SOCK); } catch {}
   server.listen(SOCK);
+  process.on("exit", () => { try { fs.unlinkSync(SOCK); } catch {} });
 }
 `;
 
@@ -234,8 +229,10 @@ if (process.env.NODE_V8_COVERAGE) {
  * Coverage for a Node service. Sets `NODE_V8_COVERAGE` to the coverage
  * directory (every node process in the container then writes V8
  * coverage JSON when it exits) and `--require`s a hook that lets spectest
- * ask the long-lived server process for a dump at capture time. Nothing
- * for the app to write. Source maps: with `--enable-source-maps` (or a
+ * 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.
  */
@@ -252,38 +249,139 @@ export function node(): CoverageAdapter {
       };
     },
     async capture(ctx) {
-      const { connect } = await import("node:net");
-      const path = await import("node:path");
-      const sock = path.join(ctx.reportDir, NODE_COVERAGE_SOCKET);
-      const reply = await new Promise<string>((resolve, reject) => {
-        const chunks: Buffer[] = [];
-        const c = connect(sock, () => c.write("dump\n"));
-        const onAbort = (): void => {
-          c.destroy();
-          reject(new Error("timed out waiting for the node hook to write a report"));
-        };
-        ctx.signal.addEventListener("abort", onAbort, { once: true });
-        c.on("data", (b: Buffer) => chunks.push(b));
-        c.on("error", (err: NodeJS.ErrnoException) => {
-          ctx.signal.removeEventListener("abort", onAbort);
-          reject(
-            new Error(
-              err.code === "ENOENT" || err.code === "ECONNREFUSED"
-                ? `no node process is serving ${COVERAGE_CONTAINER_DIR}/${NODE_COVERAGE_SOCKET} — is the service's main process node, and does it run with the service's env (NODE_OPTIONS)?`
-                : err.message,
-            ),
-          );
-        });
-        c.on("close", () => {
-          ctx.signal.removeEventListener("abort", onAbort);
-          resolve(Buffer.concat(chunks).toString("utf8").trim());
-        });
-      });
-      if (reply !== "ok") throw new Error(`the node hook answered: ${reply || "(nothing)"}`);
+      const live = await dumpAllNodeProcesses(ctx.reportDir, ctx.signal);
+      if (live === 0) {
+        throw new Error(
+          `no node process is serving a ${COVERAGE_CONTAINER_DIR}/${NODE_COVERAGE_SOCKET_PREFIX}<pid> socket — does the service run node with the service's env (NODE_OPTIONS), and is it still alive?`,
+        );
+      }
+      await compactV8Reports(ctx.reportDir);
     },
   };
 }
 
+/**
+ * Ask every node process that holds a hook socket in `dir` for a dump.
+ * A socket nobody answers (its process died without unlinking — SIGKILL,
+ * OOM) is removed. Returns how many processes answered; a process that
+ * answered with an error throws.
+ */
+export async function dumpAllNodeProcesses(dir: string, signal: AbortSignal): Promise<number> {
+  const fs = await import("node:fs/promises");
+  const path = await import("node:path");
+  const { connect } = await import("node:net");
+  let names: string[];
+  try {
+    names = (await fs.readdir(dir)).filter((n) => n.startsWith(NODE_COVERAGE_SOCKET_PREFIX));
+  } catch {
+    return 0;
+  }
+  let live = 0;
+  for (const name of names) {
+    const sock = path.join(dir, name);
+    const reply = await new Promise<string | null>((resolve, reject) => {
+      const chunks: Buffer[] = [];
+      const c = connect(sock, () => c.write("dump\n"));
+      const onAbort = (): void => {
+        c.destroy();
+        reject(new Error(`timed out waiting for the node hook (${name}) to write a report`));
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+      c.on("data", (b: Buffer) => chunks.push(b));
+      c.on("error", (err: NodeJS.ErrnoException) => {
+        signal.removeEventListener("abort", onAbort);
+        if (err.code === "ENOENT" || err.code === "ECONNREFUSED") resolve(null);
+        else reject(err);
+      });
+      c.on("close", (hadError: boolean) => {
+        signal.removeEventListener("abort", onAbort);
+        if (!hadError) resolve(Buffer.concat(chunks).toString("utf8").trim());
+      });
+    });
+    if (reply === null) {
+      // Nobody home: the process is gone. Clean up so the next capture
+      // does not knock again.
+      await fs.unlink(sock).catch(() => {});
+      continue;
+    }
+    if (reply !== "ok") throw new Error(`the node hook (${name}) answered: ${reply || "(nothing)"}`);
+    live++;
+  }
+  return live;
+}
+
+/** V8 files already compacted, by path. Module memory: forks with the
+ *  environment, so a child never re-parses its ancestors' dumps. */
+const COMPACTED_V8_REPORTS = new Set<string>();
+
+/** A script is the app's own when it is a file outside node_modules. */
+export function isAppScriptUrl(url: string): boolean {
+  return url.startsWith("file://") && !url.includes("/node_modules/");
+}
+
+/**
+ * Compact one V8 coverage document to the app's own scripts. What Node
+ * writes is everything the process loaded: `node:` internals, every
+ * `node_modules` file, and — under `--enable-source-maps` — a
+ * `source-map-cache` with each file's full map **and its sources**,
+ * repeated in every dump. Measured on a real project: a 12–20 MiB dump
+ * 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.
+ */
+export function compactV8Document(doc: Record<string, unknown>): 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 };
+  const cache = doc["source-map-cache"];
+  if (cache && typeof cache === "object") {
+    const urls = new Set(kept.map((s) => s.url as string));
+    const slim: Record<string, unknown> = {};
+    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") {
+        const { sourcesContent: _dropped, ...data } = e.data as Record<string, unknown>;
+        e.data = data;
+      }
+      slim[url] = e;
+    }
+    if (Object.keys(slim).length > 0) out["source-map-cache"] = slim;
+    else delete out["source-map-cache"];
+  }
+  return out;
+}
+
+/** Compact every not-yet-compacted V8 document in `dir`, in place. */
+export async function compactV8Reports(dir: string): Promise<void> {
+  const fs = await import("node:fs/promises");
+  const path = await import("node:path");
+  let names: string[];
+  try {
+    names = await fs.readdir(dir);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    if (!name.startsWith("coverage-") || !name.endsWith(".json")) continue;
+    const file = path.join(dir, name);
+    if (COMPACTED_V8_REPORTS.has(file)) 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, or not ours; the read path judges it
+    }
+    if (!Array.isArray(doc.result)) continue;
+    const tmp = path.join(dir, `.${name}.compact`);
+    await fs.writeFile(tmp, JSON.stringify(compactV8Document(doc)));
+    await fs.rename(tmp, file);
+    COMPACTED_V8_REPORTS.add(file);
+  }
+}
+
 // ── browser ───────────────────────────────────────────────────────
 
 /**