@specific.dev/spectest 0.59.1 → 0.59.3

package/dist/coverage.d.ts

@@ -3,8 +3,11 @@ 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";
+/** The report `node()` writes when nothing has run yet on a branch. */
+export declare const NODE_COVERAGE_EMPTY_REPORT = "coverage-spectest-empty.json";
+/** Prefix of the per-process sockets the node hook answers on, relative
+ *  to the coverage dir: `.ctl-<pid>`. */
+export declare const NODE_COVERAGE_SOCKET_PREFIX = ".ctl-";
 /** What `configure` learns about the service it rewrites. */
 export interface CoverageConfigureInfo {
     /** The services-map key. */
@@ -85,30 +88,44 @@ 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
+ * Coverage for a Node service — a long-lived server, or a container whose
+ * node processes are short-lived CLIs run by `ctx.exec`. 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 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;
-/** A script is the app's own when it is a file outside node_modules. */
+/**
+ * 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 —
+ *  and not our hook, which every dump would otherwise carry. */
 export declare function isAppScriptUrl(url: string): boolean;
 /**
  * Compact one V8 coverage document to the app's own scripts. What Node

package/dist/coverage.js

@@ -29,8 +29,11 @@ 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";
+/** The report `node()` writes when nothing has run yet on a branch. */
+export const NODE_COVERAGE_EMPTY_REPORT = "coverage-spectest-empty.json";
+/** Prefix of the per-process sockets the node hook answers on, relative
+ *  to the coverage dir: `.ctl-<pid>`. */
+export const NODE_COVERAGE_SOCKET_PREFIX = ".ctl-";
 /** Type an inline adapter. Identity at runtime. */
 export function defineAdapter(adapter) {
     return adapter;
@@ -95,16 +98,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 +118,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,25 +137,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
+ * Coverage for a Node service — a long-lived server, or a container whose
+ * node processes are short-lived CLIs run by `ctx.exec`. 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 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
@@ -169,41 +169,97 @@ 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)"}`);
+            // Two shapes, one adapter: a long-lived server answers its socket
+            // 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
+            // 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);
             await compactV8Reports(ctx.reportDir);
+            if (!(await hasV8Reports(ctx.reportDir))) {
+                await ctx.writeReport(NODE_COVERAGE_EMPTY_REPORT, '{"result":[]}\n');
+            }
         },
     };
 }
+/**
+ * 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;
+}
+/** True when `dir` holds at least one `coverage-*.json` other than the
+ *  empty placeholder. */
+async function hasV8Reports(dir) {
+    const fs = await import("node:fs/promises");
+    try {
+        return (await fs.readdir(dir)).some((n) => n.startsWith("coverage-") && n.endsWith(".json") && n !== NODE_COVERAGE_EMPTY_REPORT);
+    }
+    catch {
+        return false;
+    }
+}
 /** 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. */
+/** A script is the app's own when it is a file outside node_modules —
+ *  and not our hook, which every dump would otherwise carry. */
 export function isAppScriptUrl(url) {
-    return url.startsWith("file://") && !url.includes("/node_modules/");
+    return (url.startsWith("file://") &&
+        !url.includes("/node_modules/") &&
+        !url.endsWith("/" + NODE_COVERAGE_HOOK_PATH.split("/").pop()));
 }
 /**
  * Compact one V8 coverage document to the app's own scripts. What Node

package/package.json

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

package/src/coverage.test.ts

@@ -5,8 +5,9 @@ import os from "node:os";
 import path from "node:path";
 import {
   NODE_COVERAGE_HOOK,
+  NODE_COVERAGE_EMPTY_REPORT,
   NODE_COVERAGE_HOOK_PATH,
-  NODE_COVERAGE_SOCKET,
+  NODE_COVERAGE_SOCKET_PREFIX,
   applyCoverageAdapters,
   appendEnvFlag,
   browser,
@@ -133,101 +134,149 @@ 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-") && n.endsWith(".json"));
+  }
+  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("short-lived CLI processes: exit dumps are the coverage, no live process needed", 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, "cli.js"), "process.stdout.write('v1');\n");
+    // Nothing has run yet: an empty report, not a failure.
+    await node().capture!(fakeCtx(dir));
+    expect(await reportsIn(dir)).toEqual([NODE_COVERAGE_EMPTY_REPORT]);
+    // Two CLI runs, each its own process, each dumping at exit.
+    for (let i = 0; i < 2; i++) {
+      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);
+    }
+    expect((await socketsIn(dir)).length).toBe(0);
+    await node().capture!(fakeCtx(dir));
+    const reports = (await reportsIn(dir)).filter((n) => n !== NODE_COVERAGE_EMPTY_REPORT);
+    expect(reports.length).toBe(2);
+    const doc = JSON.parse(await fs.readFile(path.join(dir, reports[0]!), "utf8")) as { result: { url: string }[] };
+    expect(doc.result.map((x) => x.url)).toEqual([`file://${path.join(dir, "cli.js")}`]); // compacted
+  });
+
+  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 node().capture!(fakeCtx(dir));
+    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)).filter((n) => n !== NODE_COVERAGE_EMPTY_REPORT).length).toBe(1);
     } finally {
       second.kill("SIGKILL");
     }
   });
 
-  test("no server: capture fails naming the socket", async () => {
+  test("no process and no dump: an empty report is written, once", 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/);
+    await node().capture!(fakeCtx(dir));
+    await node().capture!(fakeCtx(dir));
+    expect(await reportsIn(dir)).toEqual([NODE_COVERAGE_EMPTY_REPORT]);
   });
 });

package/src/coverage.ts

@@ -34,8 +34,12 @@ 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";
+/** The report `node()` writes when nothing has run yet on a branch. */
+export const NODE_COVERAGE_EMPTY_REPORT = "coverage-spectest-empty.json";
+
+/** Prefix of the per-process sockets the node hook answers on, relative
+ *  to the coverage dir: `.ctl-<pid>`. */
+export const NODE_COVERAGE_SOCKET_PREFIX = ".ctl-";
 
 /** What `configure` learns about the service it rewrites. */
 export interface CoverageConfigureInfo {
@@ -178,16 +182,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 +202,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,26 +221,21 @@ 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
+ * Coverage for a Node service — a long-lived server, or a container whose
+ * node processes are short-lived CLIs run by `ctx.exec`. 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 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
@@ -253,46 +254,99 @@ 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)"}`);
+      // Two shapes, one adapter: a long-lived server answers its socket
+      // 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
+      // 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);
       await compactV8Reports(ctx.reportDir);
+      if (!(await hasV8Reports(ctx.reportDir))) {
+        await ctx.writeReport(NODE_COVERAGE_EMPTY_REPORT, '{"result":[]}\n');
+      }
     },
   };
 }
 
+/**
+ * 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;
+}
+
+/** True when `dir` holds at least one `coverage-*.json` other than the
+ *  empty placeholder. */
+async function hasV8Reports(dir: string): Promise<boolean> {
+  const fs = await import("node:fs/promises");
+  try {
+    return (await fs.readdir(dir)).some(
+      (n) => n.startsWith("coverage-") && n.endsWith(".json") && n !== NODE_COVERAGE_EMPTY_REPORT,
+    );
+  } catch {
+    return false;
+  }
+}
+
 /** 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. */
+/** A script is the app's own when it is a file outside node_modules —
+ *  and not our hook, which every dump would otherwise carry. */
 export function isAppScriptUrl(url: string): boolean {
-  return url.startsWith("file://") && !url.includes("/node_modules/");
+  return (
+    url.startsWith("file://") &&
+    !url.includes("/node_modules/") &&
+    !url.endsWith("/" + NODE_COVERAGE_HOOK_PATH.split("/").pop())
+  );
 }
 
 /**