poddrill 0.1.0 → 0.2.0

package/dist/owner.js

@@ -10,7 +10,12 @@ import { embedWeightsPath, openEmbedHost } from "./embed.js";
 import { readPackageIdentity } from "./package-identity.js";
 import { JobQueue } from "./jobs.js";
 import { openWhistleCall } from "./provider.js";
+import { resolvePython } from "./python-env.js";
 import { readConfig } from "./workspace.js";
+export async function pythonForOwner(env, root) {
+    const config = await readConfig(root);
+    return resolvePython(env, config.python);
+}
 /**
  * macOS rejects a unix socket path longer than 104 bytes.
  * A workspace under /var/folders exceeds that, so the socket lives in the temp dir.
@@ -53,6 +58,7 @@ export async function serve(root, mcpOnStdio) {
     const sock = socketPath(root);
     const waiting = [];
     let queue;
+    let requestStop = () => { };
     // allowHalfOpen so a client FIN cannot drop the reply while start is still reading audio.
     const server = createServer({ allowHalfOpen: true }, (connection) => {
         const opened = queue;
@@ -62,7 +68,7 @@ export async function serve(root, mcpOnStdio) {
             waiting.push(connection);
             return;
         }
-        accept(connection, opened, root);
+        accept(connection, opened, root, requestStop);
     });
     let claimed = false;
     try {
@@ -77,6 +83,8 @@ export async function serve(root, mcpOnStdio) {
         return;
     }
     const config = await readConfig(root);
+    const python = await pythonForOwner(process.env, root);
+    process.env["PODDRILL_PYTHON"] = python;
     const hosts = {
         whistle: openWhistleCall(config.provider, {
             fleetLimit: config.fleetLimit,
@@ -113,13 +121,18 @@ export async function serve(root, mcpOnStdio) {
             watcher.stop();
         }
     };
+    const gate = bindStop(server, sock, opened, hosts, stopIdle);
+    requestStop = gate.stop;
     for (const connection of waiting.splice(0, waiting.length)) {
-        accept(connection, opened, root);
+        accept(connection, opened, root, requestStop);
     }
     const version = mcpOnStdio ? (await readPackageIdentity(import.meta.url)).version : undefined;
-    await shutdownOnSignal(server, sock, opened, hosts, stopIdle, version === undefined
-        ? undefined
-        : speakMcp(version, async (name, args) => callTool(opened, root, name, args)));
+    if (version !== undefined) {
+        void speakMcp(version, async (name, args) => callTool(opened, root, name, args)).then(() => {
+            gate.stop();
+        });
+    }
+    await gate.done;
 }
 export async function proxyMcp(root) {
     const identity = await readPackageIdentity(import.meta.url);
@@ -157,7 +170,7 @@ export async function proxyMcp(root) {
         return render({ kind: "error", message: `unknown tool ${name}` });
     });
 }
-function accept(socket, queue, root) {
+function accept(socket, queue, root, requestStop) {
     let buffer = "";
     socket.setEncoding("utf8");
     socket.on("data", (chunk) => {
@@ -170,7 +183,11 @@ function accept(socket, queue, root) {
         buffer = "";
         void handleLine(line, queue, root)
             .then((response) => {
-            socket.end(response);
+            socket.end(response.text, () => {
+                if (response.stop) {
+                    requestStop();
+                }
+            });
         })
             .catch((error) => {
             const message = error instanceof Error ? error.message : String(error);
@@ -179,49 +196,54 @@ function accept(socket, queue, root) {
     });
     socket.resume();
 }
+function answered(text, stop = false) {
+    return { text, stop };
+}
 async function handleLine(line, queue, root) {
     let parsed;
     try {
         parsed = JSON.parse(line);
     }
     catch {
-        return render({ kind: "error", message: "malformed request" });
+        return answered(render({ kind: "error", message: "malformed request" }));
     }
     const request = parseRequest(parsed);
     if (request === undefined) {
-        return render({ kind: "error", message: "unknown request" });
+        return answered(render({ kind: "error", message: "unknown request" }));
     }
     switch (request.op) {
         case "ping":
-            return "{\"op\":\"pong\"}\n";
+            return answered("{\"op\":\"pong\"}\n");
+        case "stop":
+            return answered(render({ kind: "ready", state: "stopped" }), true);
         case "audit":
-            return render(await readAudit(root, request.episodeId));
+            return answered(render(await readAudit(root, request.episodeId)));
         case "start":
-            return finish(root, request, () => queue.start(request.audioPath, request.language ?? "en"));
+            return answered(await finish(root, request, () => queue.start(request.audioPath, request.language ?? "en")));
         case "episode":
-            return finish(root, request, () => queue.episode(request.episodeId));
+            return answered(await finish(root, request, () => queue.episode(request.episodeId)));
         case "cues":
-            return finish(root, request, () => queue.cues(request.episodeId, {
+            return answered(await finish(root, request, () => queue.cues(request.episodeId, {
                 ...(request.limit === undefined ? {} : { limit: request.limit }),
                 ...(request.after === undefined ? {} : { after: request.after }),
                 ...(request.groupId === undefined ? {} : { groupId: request.groupId }),
                 ...(request.hosts === undefined ? {} : { hosts: request.hosts }),
-            }));
+            })));
         case "labelGroups":
-            return finish(root, request, () => queue.labelGroups(request.episodeId, request.groups));
+            return answered(await finish(root, request, () => queue.labelGroups(request.episodeId, request.groups)));
         case "startSummary":
-            return finish(root, request, () => queue.startSummary(request.episodeId));
+            return answered(await finish(root, request, () => queue.startSummary(request.episodeId)));
         case "setSummary":
-            return finish(root, request, () => queue.setSummary(request.episodeId, request.summaryId, request.summary));
+            return answered(await finish(root, request, () => queue.setSummary(request.episodeId, request.summaryId, request.summary)));
         case "putParagraph":
-            return finish(root, request, () => queue.putParagraph(request.episodeId, request.summaryId, request.body));
+            return answered(await finish(root, request, () => queue.putParagraph(request.episodeId, request.summaryId, request.body)));
         case "postParagraph":
-            return finish(root, request, () => queue.postParagraph(request.episodeId, request.summaryId, request.body));
+            return answered(await finish(root, request, () => queue.postParagraph(request.episodeId, request.summaryId, request.body)));
         case "summary":
-            return finish(root, request, () => queue.summary(request.episodeId, request.summaryId));
+            return answered(await finish(root, request, () => queue.summary(request.episodeId, request.summaryId)));
         default: {
             const leftover = request;
-            return render({ kind: "error", message: `unexpected ${JSON.stringify(leftover)}` });
+            return answered(render({ kind: "error", message: `unexpected ${JSON.stringify(leftover)}` }));
         }
     }
 }
@@ -251,6 +273,7 @@ function auditEpisodeId(request, response) {
     switch (request.op) {
         case "ping":
         case "audit":
+        case "stop":
             return undefined;
         case "start":
             return startedEpisodeId(response);
@@ -344,6 +367,9 @@ function parseRequest(value) {
     if (op === "ping") {
         return { op: "ping" };
     }
+    if (op === "stop") {
+        return { op: "stop" };
+    }
     if (op === "start" && typeof record["audioPath"] === "string") {
         const language = record["language"];
         if (language !== undefined && typeof language !== "string") {
@@ -474,24 +500,24 @@ function listen(server, sock) {
         });
     });
 }
-function shutdownOnSignal(server, sock, queue, hosts, stopIdle, mcp) {
-    return new Promise((resolve) => {
-        let stopping = false;
-        const stop = () => {
-            if (stopping) {
-                return;
-            }
-            stopping = true;
-            void closeOwner(server, sock, queue, hosts, stopIdle).then(() => {
-                resolve();
-            });
-        };
-        process.on("SIGTERM", stop);
-        process.on("SIGINT", stop);
-        if (mcp !== undefined) {
-            void mcp.then(stop);
-        }
+function bindStop(server, sock, queue, hosts, stopIdle) {
+    let stopping = false;
+    let resolveDone = () => { };
+    const done = new Promise((resolve) => {
+        resolveDone = resolve;
     });
+    const stop = () => {
+        if (stopping) {
+            return;
+        }
+        stopping = true;
+        void closeOwner(server, sock, queue, hosts, stopIdle).then(() => {
+            resolveDone();
+        });
+    };
+    process.on("SIGTERM", stop);
+    process.on("SIGINT", stop);
+    return { done, stop };
 }
 /** Stop the idle watchers, then the queue, so no lane takes new work. Then the hosts, so worker pipes close before exit. */
 async function closeOwner(server, sock, queue, hosts, stopIdle) {

package/dist/provider.js

@@ -1,6 +1,7 @@
 /**
  * Hosts that run a transcript model. The episode module never imports this file.
- * A new host is a new id in `providerIds` and a `WhistleHost` factory.
+ * A new host is a new id in `providerIds` and a `providerTransport` case.
+ * An `"unwired"` transport is refused by setup and by `openWhistleCall`.
  */
 import { openFleet } from "./fleet.js";
 import { fleetSize, modelForLanguage } from "./models.js";
@@ -26,23 +27,37 @@ export function transcriptRefusal(model, weights) {
         }
     }
 }
-/**
- * Mac runs one warm pool per model id. Nothing spawns until that id's first slice.
- * Grok Bot's computer and Cursor's cloud computer are not wired yet.
- */
-const factories = {
-    localhost: (config, whistleSpawn, moonshineSpawn) => openMacHost(config, whistleSpawn, moonshineSpawn),
-    "grok-bot": () => unwiredHost("grok-bot"),
-    "cursor-cloud": () => unwiredHost("cursor-cloud"),
-};
+/** `localhost`, `grok-bot`, and `cursor-cloud` all run the local Python host. */
+export function providerTransport(id) {
+    switch (id) {
+        case "localhost":
+        case "grok-bot":
+        case "cursor-cloud":
+            return "local";
+        default: {
+            const leftover = id;
+            throw new Error(`unexpected provider ${JSON.stringify(leftover)}`);
+        }
+    }
+}
+export function unwiredProviderMessage(id) {
+    return `${id} provider transport is not wired. poddrill setup refuses a provider that cannot transcribe.`;
+}
+/** Setup and `openWhistleCall` both call this before a worker can start. */
+export function refuseUnwiredTransport(id, transport) {
+    if (transport === "unwired") {
+        throw new Error(unwiredProviderMessage(id));
+    }
+}
 /** Open the host selected at setup. Spawns nothing until the first slice of a model. */
 export function openWhistleCall(providerId, config, whistleSpawn = spawnNeedleWorker, moonshineSpawn = spawnMoonshineWorker) {
+    refuseUnwiredTransport(providerId, providerTransport(providerId));
     if (!Number.isInteger(config.fleetLimit) || config.fleetLimit < 1) {
         throw new Error(`fleet limit must be a positive integer, got ${config.fleetLimit}`);
     }
-    return factories[providerId](config, whistleSpawn, moonshineSpawn);
+    return openLocalHost(config, whistleSpawn, moonshineSpawn);
 }
-function openMacHost(config, whistleSpawn, moonshineSpawn) {
+function openLocalHost(config, whistleSpawn, moonshineSpawn) {
     const pools = new Map();
     const poolFor = (model) => {
         const existing = pools.get(model.id);
@@ -110,14 +125,3 @@ function spawnFor(model, weights, whistleSpawn, moonshineSpawn) {
         }
     }
 }
-function unwiredHost(providerId) {
-    return {
-        async transcribeSlice() {
-            throw new Error(`${providerId} provider transport is not wired`);
-        },
-        async close() { },
-        release() {
-            return true;
-        },
-    };
-}

package/dist/python-env.js

@@ -0,0 +1,222 @@
+/**
+ * The interpreter PodDrill spawns, and the venv that holds its pinned imports.
+ * `PODDRILL_PYTHON` wins, then `poddrill.json`, then `~/.cache/poddrill/venv`, then `python3`.
+ */
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { errorCode, pathExists } from "./disk.js";
+import { readPackageIdentity } from "./package-identity.js";
+export const NUMPY_PIN = "2.5.4";
+export const ONNXRUNTIME_PIN = "1.31.0";
+export const INSTALL_PYTHON_FIX = "poddrill install-python";
+/** `HOME` from the env when it is absolute, otherwise the process home. */
+export function homeFromEnv(env) {
+    const home = env["HOME"];
+    if (home !== undefined && home !== "" && isAbsolute(home)) {
+        return home;
+    }
+    return homedir();
+}
+export function defaultVenvDir(env) {
+    return join(homeFromEnv(env), ".cache", "poddrill", "venv");
+}
+export function defaultVenvPython(env) {
+    return join(defaultVenvDir(env), "bin", "python");
+}
+/** Sync lookup for workers. The owner has already resolved a venv into `PODDRILL_PYTHON`. */
+export function pythonFromEnv(env) {
+    const configured = env["PODDRILL_PYTHON"];
+    if (configured !== undefined && configured !== "") {
+        return configured;
+    }
+    return "python3";
+}
+export async function resolvePython(env, configured) {
+    const fromEnv = env["PODDRILL_PYTHON"];
+    if (fromEnv !== undefined && fromEnv !== "") {
+        return fromEnv;
+    }
+    if (configured !== undefined && configured !== "") {
+        return configured;
+    }
+    const venvPython = defaultVenvPython(env);
+    if (await pathExists(venvPython)) {
+        return venvPython;
+    }
+    return "python3";
+}
+export async function pythonPins(moduleUrl) {
+    const identity = await readPackageIdentity(moduleUrl);
+    return {
+        "cactus-needle": identity.cactusNeedle,
+        numpy: NUMPY_PIN,
+        onnxruntime: ONNXRUNTIME_PIN,
+    };
+}
+export function ytDlpFix(python) {
+    return `${shellWord(python)} -m pip install --upgrade yt-dlp`;
+}
+export function moonshineInstallLine() {
+    return 'Install moonshine-voice into the PodDrill Python: "$PODDRILL_PYTHON" -m pip install moonshine-voice';
+}
+/**
+ * Create `~/.cache/poddrill/venv` when the pins are missing and install them there.
+ * Uses `uv` when it is on PATH. Otherwise `python3 -m venv`. A second call with the pins present does nothing.
+ */
+export async function installPython(env, moduleUrl) {
+    const pins = await pythonPins(moduleUrl);
+    const python = defaultVenvPython(env);
+    if (await pinsMatch(python, pins, env)) {
+        return { python, created: false, installer: "cached", pins };
+    }
+    const spawnEnv = commandEnv(env);
+    const uv = await commandWorks("uv", ["--version"], spawnEnv);
+    if (uv) {
+        await installWithUv(python, defaultVenvDir(env), pins, spawnEnv);
+        await assertPins(python, pins, env);
+        return { python, created: true, installer: "uv", pins };
+    }
+    await installWithVenv(python, defaultVenvDir(env), pins, env, spawnEnv);
+    await assertPins(python, pins, env);
+    return { python, created: true, installer: "venv", pins };
+}
+export function chooseInstaller(uvAvailable) {
+    return uvAvailable ? "uv" : "venv";
+}
+async function installWithUv(python, dest, pins, spawnEnv) {
+    if (!(await pathExists(python))) {
+        const created = await runProcess("uv", ["venv", dest], spawnEnv);
+        if (created.code !== 0) {
+            throw new Error(`uv venv failed: ${tail(created.stderr)}`);
+        }
+    }
+    const installed = await runProcess("uv", ["pip", "install", "--python", python, ...pinArgs(pins)], spawnEnv);
+    if (installed.code !== 0) {
+        throw new Error(`uv pip install failed: ${tail(`${installed.stdout}\n${installed.stderr}`)}`);
+    }
+}
+async function installWithVenv(python, dest, pins, env, spawnEnv) {
+    if (!(await pathExists(python))) {
+        const base = venvBase(env, dest);
+        const created = await runProcess(base, ["-m", "venv", dest], spawnEnv);
+        if (created.code !== 0) {
+            throw new Error([
+                `python -m venv failed: ${tail(`${created.stdout}\n${created.stderr}`)}`,
+                "Install the python3-venv package, or install uv and run poddrill install-python again.",
+            ].join(" "));
+        }
+    }
+    const installed = await runProcess(python, ["-m", "pip", "install", "--disable-pip-version-check", ...pinArgs(pins)], spawnEnv);
+    if (installed.code !== 0) {
+        throw new Error(`pip install failed: ${tail(`${installed.stdout}\n${installed.stderr}`)}`);
+    }
+}
+function venvBase(env, dest) {
+    const configured = pythonFromEnv(env);
+    if (configured === "python3" || configured.startsWith(`${dest}/`)) {
+        return "python3";
+    }
+    return configured;
+}
+function pinArgs(pins) {
+    return [
+        `cactus-needle==${pins["cactus-needle"]}`,
+        `numpy==${pins.numpy}`,
+        `onnxruntime==${pins.onnxruntime}`,
+    ];
+}
+async function assertPins(python, pins, env) {
+    if (!(await pinsMatch(python, pins, env))) {
+        throw new Error(`PodDrill Python at ${python} does not import the pinned packages`);
+    }
+}
+async function pinsMatch(python, pins, env) {
+    if (!(await pathExists(python))) {
+        return false;
+    }
+    const result = await runProcess(python, ["-c", PIN_PROBE], commandEnv(env));
+    if (result.code !== 0) {
+        return false;
+    }
+    const found = new Map();
+    for (const line of result.stdout.split("\n")) {
+        const index = line.indexOf("==");
+        if (index <= 0) {
+            continue;
+        }
+        found.set(line.slice(0, index), line.slice(index + 2).trim());
+    }
+    return (found.get("cactus-needle") === pins["cactus-needle"] &&
+        found.get("numpy") === pins.numpy &&
+        found.get("onnxruntime") === pins.onnxruntime);
+}
+const PIN_PROBE = [
+    "import importlib.metadata as meta",
+    "for name in ('cactus-needle', 'numpy', 'onnxruntime'):",
+    "    print(name + '==' + meta.version(name))",
+].join("\n");
+function commandEnv(env) {
+    const copy = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (value !== undefined) {
+            copy[key] = value;
+        }
+    }
+    if (copy["PATH"] === undefined && process.env["PATH"] !== undefined) {
+        copy["PATH"] = process.env["PATH"];
+    }
+    return copy;
+}
+async function commandWorks(command, args, env) {
+    const result = await runProcess(command, args, env);
+    return result.code === 0;
+}
+function runProcess(command, args, env) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, [...args], { env, stdio: ["ignore", "pipe", "pipe"] });
+        const out = [];
+        const err = [];
+        let settled = false;
+        const finish = (result) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            resolve(result);
+        };
+        child.stdout.on("data", (chunk) => {
+            out.push(chunk);
+        });
+        child.stderr.on("data", (chunk) => {
+            err.push(chunk);
+        });
+        child.on("error", (error) => {
+            if (errorCode(error) === "ENOENT") {
+                finish({ code: null, stdout: "", stderr: error.message });
+                return;
+            }
+            reject(error);
+        });
+        child.on("close", (code) => {
+            finish({
+                code,
+                stdout: Buffer.concat(out).toString("utf8"),
+                stderr: Buffer.concat(err).toString("utf8"),
+            });
+        });
+    });
+}
+function tail(text) {
+    const trimmed = text.trim();
+    if (trimmed.length <= 1500) {
+        return trimmed === "" ? "no output" : trimmed;
+    }
+    return trimmed.slice(-1500);
+}
+function shellWord(value) {
+    if (/^[A-Za-z0-9_./:-]+$/.test(value)) {
+        return value;
+    }
+    return `"${value.replaceAll("\"", "\\\"")}"`;
+}

package/dist/weights.js

@@ -0,0 +1,88 @@
+/**
+ * Pinned WeSpeaker ECAPA-TDNN512 weights.
+ * The model card has no license field. WeSpeaker docs say pretrained models follow
+ * the dataset license, and VoxCeleb is CC BY 4.0, so attribution stays with the file.
+ */
+import { createHash } from "node:crypto";
+import { createReadStream, createWriteStream } from "node:fs";
+import { mkdir, rename, rm, stat } from "node:fs/promises";
+import { dirname } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { errorCode } from "./disk.js";
+export const ECAPA_FILE = "voxceleb_ECAPA512.onnx";
+export const ECAPA_URL = "https://huggingface.co/Wespeaker/wespeaker-voxceleb-ecapa-tdnn512/resolve/89426e111abc9ffcc40279baf808e087693c6e9b/voxceleb_ECAPA512.onnx";
+export const ECAPA_BYTES = 24_861_931;
+export const ECAPA_SHA256 = "f901ae3571912bad4e11e157744cb8b7d77a0b46923b83c410bdbb6c77d69736";
+export const ECAPA_LICENSE = "CC BY 4.0";
+export const ECAPA_ATTRIBUTION = "WeSpeaker ECAPA-TDNN512 pretrained on VoxCeleb. VoxCeleb is used under CC BY 4.0.";
+export const FETCH_WEIGHTS_FIX = "poddrill fetch-weights";
+export const ecapaSpec = { bytes: ECAPA_BYTES, sha256: ECAPA_SHA256 };
+export async function digestStatus(path, spec) {
+    let info;
+    try {
+        info = await stat(path);
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT") {
+            return "missing";
+        }
+        throw error;
+    }
+    if (!info.isFile() || info.size !== spec.bytes) {
+        return "mismatch";
+    }
+    const sha256 = await sha256File(path);
+    return sha256 === spec.sha256 ? "match" : "mismatch";
+}
+export async function sha256File(path) {
+    const hash = createHash("sha256");
+    const stream = createReadStream(path);
+    for await (const chunk of stream) {
+        hash.update(chunk);
+    }
+    return hash.digest("hex");
+}
+/** Download the pinned file when the destination is missing or does not match. Idempotent. */
+export async function fetchEcapa(destination) {
+    const status = await digestStatus(destination, ecapaSpec);
+    if (status === "match") {
+        return weightsResult(destination, false);
+    }
+    await mkdir(dirname(destination), { recursive: true });
+    const partial = `${destination}.partial`;
+    try {
+        const response = await fetch(ECAPA_URL, { headers: { "user-agent": "poddrill" } });
+        if (!response.ok) {
+            throw new Error(`ECAPA download failed with HTTP ${response.status}`);
+        }
+        if (response.body === null) {
+            throw new Error("ECAPA download failed with an empty body");
+        }
+        await pipeline(Readable.fromWeb(response.body), createWriteStream(partial));
+        const written = await stat(partial);
+        if (written.size !== ECAPA_BYTES) {
+            throw new Error(`ECAPA download expected ${ECAPA_BYTES} bytes, got ${written.size}`);
+        }
+        const sha256 = await sha256File(partial);
+        if (sha256 !== ECAPA_SHA256) {
+            throw new Error(`ECAPA download sha256 ${sha256} does not match ${ECAPA_SHA256}`);
+        }
+        await rename(partial, destination);
+    }
+    catch (error) {
+        await rm(partial, { force: true });
+        throw error;
+    }
+    return weightsResult(destination, true);
+}
+function weightsResult(path, created) {
+    return {
+        path,
+        created,
+        bytes: ECAPA_BYTES,
+        sha256: ECAPA_SHA256,
+        license: ECAPA_LICENSE,
+        attribution: ECAPA_ATTRIBUTION,
+    };
+}

package/dist/worker.js

@@ -1,5 +1,5 @@
 /**
- * One long-lived python3 process that answers one framed request at a time on stdin/stdout.
+ * One long-lived Python process that answers one framed request at a time on stdin/stdout.
  * Frame: 8-byte big-endian body length, then UTF-8 JSON.
  * Shared request: { "wavPath": string }. A Whistle request also sends "language".
  * Replies: { "kind": "ready", ... } once, then per request
@@ -8,6 +8,7 @@
  */
 import { spawn } from "node:child_process";
 import { asRecord } from "./disk.js";
+import { pythonFromEnv } from "./python-env.js";
 const MAX_FRAME_BYTES = 64 * 1024 * 1024;
 const STDERR_TAIL_BYTES = 8 * 1024;
 /**
@@ -48,7 +49,8 @@ export const PYTHON_FRAMES = [
 ].join("\n");
 export function spawnFramedWorker(worker, events) {
     const label = worker.label;
-    const child = spawn("python3", [...worker.args], { stdio: ["pipe", "pipe", "pipe"] });
+    const command = worker.command ?? pythonFromEnv(process.env);
+    const child = spawn(command, [...worker.args], { stdio: ["pipe", "pipe", "pipe"] });
     let state = "booting";
     let pending;
     let stdout = Buffer.alloc(0);
@@ -139,7 +141,8 @@ export function spawnFramedWorker(worker, events) {
     });
     child.on("close", (code) => {
         const tail = stderrTail.toString("utf8").trim();
-        exitOnce(tail === "" ? `${label} exited with code ${code === null ? "null" : String(code)}` : tail);
+        const raw = tail === "" ? `${label} exited with code ${code === null ? "null" : String(code)}` : tail;
+        exitOnce(worker.explainExit === undefined ? raw : worker.explainExit(raw));
     });
     return {
         request(frame) {