@specific.dev/spectest 0.79.0 → 0.79.2

package/dist/daemon.js

@@ -42,7 +42,8 @@ import { pollUntilReady } from "./harness/ready-poll.js";
 import { runWrapperRules } from "./harness/wrapper-rules.js";
 import { cpus } from "node:os";
 import { APP_DIR, WORKSPACE, resolveExistingProjectPath, resolveProjectPath } from "./project-files.js";
-import { isTextualContentType, looksBinary, omittedBody, parseContentLength, } from "./harness/http-body.js";
+import { installFetchWrapper, isTransportError } from "./harness/fetch.js";
+import { bindInstrumentationScope, createInstrumentationScope, runInstrumented, runUninstrumented, } from "./harness/instrumentation-scope.js";
 import { encodeRegistry } from "./harness/names-registry.js";
 import { InterceptRegistry, parseTarget, runChain, } from "./harness/intercept.js";
 import { HOP_BY_HOP_HEADERS, augmentCorsResponse, corsPreflightResponse, isCorsPreflight, } from "./harness/http-proxy.js";
@@ -57,10 +58,9 @@ import { openTerminal } from "./terminal.js";
 // `ctx.mcp(url)`. One client per call, no registry: an authenticated
 // client is passed to descendants as a test's return value.
 import { openMcp } from "./mcp.js";
-import { setRawFetch } from "./harness/raw-fetch.js";
 import { readAnnotation } from "./annotate.js";
-import { isRecording, pauseRecording, recordEmail, recordEnv, recordExec, recordFake, recordHttp, recordStep, recordTerminal, recordWait, reserveEvent, recorderEventCount, recorderMarkChildren, recorderTruncate, resumeRecording, startRecording, stopRecording, truncateUtf8, } from "./recorder.js";
-import { deepUnwrap, readRaw, wrap, wrapResponse } from "./inspect.js";
+import { isRecording, recordEmail, recordEnv, recordExec, recordFake, recordStep, recordTerminal, recordWait, reserveEvent, recorderEventCount, recorderMarkChildren, recorderTruncate, startRecording, stopRecording, truncateUtf8, } from "./recorder.js";
+import { deepUnwrap, readRaw, wrap } from "./inspect.js";
 import { clearRecordSecrets, setRecordSecrets } from "./record-secrets.js";
 import { encodeReplayBundle, replayChunk } from "./replay-bundle.js";
 function namedServices(cfg) {
@@ -1705,7 +1705,7 @@ async function startIngress() {
     for (const [name, fake] of FAKES) {
         if (fake.def.state) {
             try {
-                fake.state = await fake.def.state();
+                fake.state = await runUninstrumented(() => fake.def.state());
             }
             catch (err) {
                 throw new Error(`fake ${JSON.stringify(name)} state() factory threw: ${err.message}`);
@@ -2135,7 +2135,7 @@ server, byHost, listenerLabel, proto) {
     const upstream = async (current) => {
         if (route.kind === "fake") {
             try {
-                return await route.fake.def.handler(current, route.fake.state, FAKE_CTX);
+                return await runUninstrumented(() => route.fake.def.handler(current, route.fake.state, FAKE_CTX));
             }
             catch (err) {
                 const e = err;
@@ -2545,7 +2545,7 @@ function registerInterceptor(target, description, handler) {
             `(\`http://<service>:<port>\`) is container-to-container traffic and never passes through here.`);
     }
     const resv = reserveEvent();
-    const it = INTERCEPTORS.register(host, path, handler);
+    const it = INTERCEPTORS.register(host, path, bindInstrumentationScope(handler));
     const where = `${host}${it.path === "/" ? "" : it.path}`;
     const seq = recordStep({
         kind: "intercept",
@@ -2763,11 +2763,11 @@ async function ensureFakeHelpers(name) {
     if (fake.trackedHelpers)
         return fake.trackedHelpers;
     fake.helpers = fake.def.helpers
-        ? (await fake.def.helpers({
+        ? (await runUninstrumented(() => fake.def.helpers({
             name,
             state: fake.state,
             ctx: FAKE_CTX,
-        }))
+        })))
         : {};
     fake.trackedHelpers = trackFakeHelpers(name, fake.helpers);
     return fake.trackedHelpers;
@@ -2849,39 +2849,22 @@ function invokeFakeHelper(fakeName, member, fn, thisArg, callArgs) {
             error: errMessage(err),
         }, resv);
     };
-    // A helper call is ONE step. Whatever the fake does inside it — a fetch to
-    // deliver a webhook, a call to its own API — is the fake's plumbing, not
-    // something the test did, and it would otherwise land on the timeline as
-    // an `http` step the test never made. The built-in `email()` helpers
-    // already pause around their internal polls by hand for exactly this
-    // reason (`components/email.ts`); doing it here gives every user-authored
-    // fake the same contract without having to know about it.
-    //
-    // The pause spans the helper's `await`s, so genuinely concurrent test work
-    // (`Promise.all([helper(), ctx.fetch(…)])`) loses its events too. That is
-    // the same trade `email()` has always made, and sequential test code — all
-    // of it, in practice — is unaffected.
-    pauseRecording();
+    // Record the public helper call in the caller's scope, while its body
+    // and async descendants use native fetch and emit no internal events.
     let result;
     try {
-        result = fn.apply(thisArg, args);
+        result = runUninstrumented(() => fn.apply(thisArg, args));
     }
     catch (err) {
-        resumeRecording();
         recordError(err);
         throw err;
     }
     if (result instanceof Promise) {
-        return result.then((value) => {
-            resumeRecording();
-            return recordResult(value);
-        }, (err) => {
-            resumeRecording();
+        return result.then(recordResult, (err) => {
             recordError(err);
             throw err;
         });
     }
-    resumeRecording();
     return recordResult(result);
 }
 /** Record a fake-helper call's render annotation as a child of the call's
@@ -3176,14 +3159,16 @@ async function runProjectSetupInner() {
     // as in a test. No recorder is active here, so it wraps without provenance —
     // but the wrapped type stays honest at runtime (`.unwrap()` works).
     const restoreFetch = installFetchWrapper();
+    const fetchScope = createInstrumentationScope(false);
     // The full context, unscoped: every service is up by project-setup time,
     // so `ctx.svc` is the same map tests see (and shares helper instances with
     // them — a Bun.SQL pool created here is reused later).
     const ctx = await spectestContext();
     try {
-        await proj.setup(ctx);
+        await runInstrumented(fetchScope, () => proj.setup(ctx));
     }
     finally {
+        fetchScope.active = false;
         restoreFetch();
     }
     return { ran: true, durationMs: Date.now() - start };
@@ -3906,160 +3891,6 @@ async function buildServiceHandles(cfg) {
 // ────────────────────────────────────────────────────────────────────────
 // Instrumentation helpers
 // ────────────────────────────────────────────────────────────────────────
-function describeFetchInput(input) {
-    if (typeof input === "string")
-        return { url: input };
-    if (input instanceof URL)
-        return { url: input.toString() };
-    // Request instance
-    const req = input;
-    return { url: req.url, methodFromInput: req.method };
-}
-function describeRequestBody(input, init) {
-    // For Request objects, body has already been consumed into the request;
-    // we can't read it back without cloning, which costs. Skip unless init.body
-    // is provided directly.
-    const body = init?.body;
-    if (body === undefined || body === null) {
-        if (input instanceof Request && input.bodyUsed === false) {
-            // Don't drain the request's body here — leaving it for the actual
-            // fetch. Return a marker.
-            return { body: "[Request body not captured]", truncated: false };
-        }
-        return {};
-    }
-    if (typeof body === "string") {
-        const t = truncateUtf8(body);
-        return { body: t.value, truncated: t.truncated };
-    }
-    if (body instanceof URLSearchParams) {
-        const t = truncateUtf8(body.toString());
-        return { body: t.value, truncated: t.truncated };
-    }
-    return { body: `[non-text body: ${body.constructor?.name ?? typeof body}]` };
-}
-/**
- * Marks an error thrown by the instrumented fetch as *transport-level* —
- * the connection itself failed (refused, unresolvable, reset) before any
- * HTTP reply existed. `fetch` never rejects for an HTTP status, so every
- * rejection short of an abort is transport. `Symbol.for` so a duplicated
- * SDK module instance (the bun hardlink landmine) still recognises it.
- *
- * Why it exists: `ctx.poll` waits for convergence, and right after a fork
- * restore the guest can serve a ~10 s window where a connect or a DNS
- * lookup fails once and then heals (measured 2026-08-21: a poll's first
- * fetch hung 12 s in resolution, threw, and killed a 60 s poll on attempt
- * 1 while attempt 2 would have passed). During a poll, a dead connection
- * is just "not ready yet"; outside one it stays a hard error.
- */
-const TRANSPORT_ERROR = Symbol.for("spectest.transportError");
-function isTransportError(err) {
-    return (typeof err === "object" &&
-        err !== null &&
-        err[TRANSPORT_ERROR] === true);
-}
-/**
- * Install a fetch wrapper on `globalThis` that emits HTTP events into the
- * active recorder. Returns a restore function. Calls outside of a running
- * test still hit the original fetch (the recorder is null then; the
- * wrapper just adds a tiny amount of overhead — but we restore after each
- * test anyway, so this only matters mid-test).
- */
-function installFetchWrapper() {
-    const original = globalThis.fetch;
-    // SDK internals (the MCP client, its OAuth flow) must not see the
-    // wrapper: a wrapped `res.ok` is an object, and the wrapper reads every
-    // body to the end, which never finishes for an SSE stream.
-    setRawFetch(original);
-    const wrappedFn = async (input, init) => {
-        const start = Date.now();
-        const resv = reserveEvent();
-        const { url, methodFromInput } = describeFetchInput(input);
-        const method = (init?.method ?? methodFromInput ?? "GET").toUpperCase();
-        const reqBody = describeRequestBody(input, init);
-        try {
-            const res = await original(input, init);
-            let responseBody;
-            let responseBodyTruncated;
-            // The reply the test gets is untouched: everything here reads a clone,
-            // and a body known to be binary is not read at all. See
-            // ./harness/http-body.ts for why a blanket `.text()` was wrong.
-            const contentType = res.headers.get("content-type");
-            const contentLength = () => parseContentLength(res.headers.get("content-length"));
-            const textual = isTextualContentType(contentType);
-            if (textual === false) {
-                responseBody = omittedBody("binary", contentType, contentLength());
-            }
-            else {
-                try {
-                    const cloned = res.clone();
-                    const text = await cloned.text();
-                    if (textual === undefined && looksBinary(text)) {
-                        // No content type (or a multipart one), and the bytes say this
-                        // was never text.
-                        responseBody = omittedBody("binary", contentType, contentLength());
-                    }
-                    else {
-                        const t = truncateUtf8(text);
-                        responseBody = t.value;
-                        responseBodyTruncated = t.truncated;
-                    }
-                }
-                catch {
-                    // The stream failed, or something had already consumed the body.
-                    responseBody = omittedBody("unreadable", contentType, contentLength());
-                }
-            }
-            const seq = recordHttp({
-                method,
-                url,
-                requestBody: reqBody.body,
-                requestBodyTruncated: reqBody.truncated,
-                status: res.status,
-                responseBody,
-                responseBodyTruncated,
-                durationMs: Date.now() - start,
-            }, resv);
-            return wrapResponse(res, seq);
-        }
-        catch (err) {
-            const e = err;
-            recordHttp({
-                method,
-                url,
-                requestBody: reqBody.body,
-                requestBodyTruncated: reqBody.truncated,
-                durationMs: Date.now() - start,
-                error: e?.message ?? String(err),
-            }, resv);
-            // Tag transport failures for ctx.poll (see TRANSPORT_ERROR). An abort
-            // is the caller's own signal (their AbortController or their
-            // AbortSignal.timeout) — their semantics, never retried for them.
-            if (typeof err === "object" &&
-                err !== null &&
-                e?.name !== "AbortError" &&
-                e?.name !== "TimeoutError") {
-                try {
-                    err[TRANSPORT_ERROR] = true;
-                }
-                catch {
-                    /* frozen error object — stays a hard error */
-                }
-            }
-            throw err;
-        }
-    };
-    // Preserve any provider-specific statics on `fetch` (e.g. Bun's
-    // `fetch.preconnect`) so consumers that touch them keep working.
-    const wrapped = wrappedFn;
-    for (const key of Object.keys(original)) {
-        wrapped[key] = original[key];
-    }
-    globalThis.fetch = wrapped;
-    return () => {
-        globalThis.fetch = original;
-    };
-}
 /** Build the `docker exec` argv for a service command. A string command runs
  *  through `sh -lc`; an array is exact argv with no shell (the
  *  `["psql", "-f", "-"]` shape). An optional `cwd` becomes `-w <cwd>` (the
@@ -4522,6 +4353,7 @@ async function runOne(testCase) {
     };
     startRecording();
     const restoreFetch = installFetchWrapper();
+    const fetchScope = createInstrumentationScope();
     // Look up the parent's stored return value (if any). The parent ran in
     // an ancestor fork; its TEST_DATA entry travels with the snapshot.
     const parentId = testCase.dependsOn?.id;
@@ -4653,7 +4485,7 @@ async function runOne(testCase) {
     let outcome;
     try {
         const value = await Promise.race([
-            Promise.resolve(testCase.run(ctx)),
+            Promise.resolve(runInstrumented(fetchScope, () => testCase.run(ctx))),
             timedOut,
         ]);
         // Stash the return value so child cases — which fork from the snapshot
@@ -4673,6 +4505,7 @@ async function runOne(testCase) {
             clearTimeout(timer);
         RECORDING_EXEC = undefined;
         INTERCEPTORS.endScope();
+        fetchScope.active = false;
         restoreFetch();
         restoreConsole();
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -5004,6 +4837,7 @@ async function evalCode(code, secrets) {
     // Response just like in a test (no recorder here, so no provenance — but the
     // wrapped type is honest at runtime). Restored in the `finally` below.
     const restoreFetch = installFetchWrapper();
+    const fetchScope = createInstrumentationScope(false);
     // Same persistent acquire/detach as a test run (see runOne): the browser
     // survives the eval, so successive `spectest env eval` calls continue one
     // live session — and a snapshot taken afterwards carries it.
@@ -5139,7 +4973,8 @@ async function evalCode(code, secrets) {
         await fs.mkdir(EVAL_DIR, { recursive: true });
         filePath = path.join(EVAL_DIR, `${randomUUID()}.ts`);
         await fs.writeFile(filePath, prepared.code);
-        const mod = (await import(pathToFileURL(filePath).href));
+        const moduleUrl = pathToFileURL(filePath).href;
+        const mod = (await runInstrumented(fetchScope, () => import(moduleUrl)));
         outcome = { ok: true, result: safeSerialize(mod.default) };
     }
     catch (err) {
@@ -5152,6 +4987,7 @@ async function evalCode(code, secrets) {
     }
     finally {
         clearRecordSecrets();
+        fetchScope.active = false;
         restoreFetch();
         restoreConsole();
         // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/dist/harness/fetch.d.ts

@@ -0,0 +1,5 @@
+export declare function isTransportError(err: unknown): boolean;
+/** Install a dispatcher: only code in an active test/setup/eval scope gets
+ * wrapped responses. Fake handlers and background tasks use native fetch,
+ * without cloning bodies, tagging errors, or touching the recorder. */
+export declare function installFetchWrapper(): () => void;

package/dist/harness/fetch.js

@@ -0,0 +1,165 @@
+import { wrapResponse } from "../inspect.js";
+import { recordHttp, reserveEvent, truncateUtf8 } from "../recorder.js";
+import { isTextualContentType, looksBinary, omittedBody, parseContentLength } from "./http-body.js";
+import { currentInstrumentationScope } from "./instrumentation-scope.js";
+import { setRawFetch } from "./raw-fetch.js";
+function describeFetchInput(input) {
+    if (typeof input === "string")
+        return { url: input };
+    if (input instanceof URL)
+        return { url: input.toString() };
+    // Request instance
+    const req = input;
+    return { url: req.url, methodFromInput: req.method };
+}
+function describeRequestBody(input, init) {
+    // For Request objects, body has already been consumed into the request;
+    // we can't read it back without cloning, which costs. Skip unless init.body
+    // is provided directly.
+    const body = init?.body;
+    if (body === undefined || body === null) {
+        if (input instanceof Request && input.bodyUsed === false) {
+            // Don't drain the request's body here — leaving it for the actual
+            // fetch. Return a marker.
+            return { body: "[Request body not captured]", truncated: false };
+        }
+        return {};
+    }
+    if (typeof body === "string") {
+        const t = truncateUtf8(body);
+        return { body: t.value, truncated: t.truncated };
+    }
+    if (body instanceof URLSearchParams) {
+        const t = truncateUtf8(body.toString());
+        return { body: t.value, truncated: t.truncated };
+    }
+    return { body: `[non-text body: ${body.constructor?.name ?? typeof body}]` };
+}
+/**
+ * Marks an error thrown by the instrumented fetch as *transport-level* —
+ * the connection itself failed (refused, unresolvable, reset) before any
+ * HTTP reply existed. `fetch` never rejects for an HTTP status, so every
+ * rejection short of an abort is transport. `Symbol.for` so a duplicated
+ * SDK module instance (the bun hardlink landmine) still recognises it.
+ *
+ * Why it exists: `ctx.poll` waits for convergence, and right after a fork
+ * restore the guest can serve a ~10 s window where a connect or a DNS
+ * lookup fails once and then heals (measured 2026-08-21: a poll's first
+ * fetch hung 12 s in resolution, threw, and killed a 60 s poll on attempt
+ * 1 while attempt 2 would have passed). During a poll, a dead connection
+ * is just "not ready yet"; outside one it stays a hard error.
+ */
+const TRANSPORT_ERROR = Symbol.for("spectest.transportError");
+export function isTransportError(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        err[TRANSPORT_ERROR] === true);
+}
+/** Install a dispatcher: only code in an active test/setup/eval scope gets
+ * wrapped responses. Fake handlers and background tasks use native fetch,
+ * without cloning bodies, tagging errors, or touching the recorder. */
+export function installFetchWrapper() {
+    const original = globalThis.fetch;
+    // SDK internals (the MCP client, its OAuth flow) must not see the
+    // wrapper: a wrapped `res.ok` is an object, and the wrapper reads every
+    // body to the end, which never finishes for an SSE stream.
+    setRawFetch(original);
+    const wrappedFn = async (input, init) => {
+        const scope = currentInstrumentationScope();
+        if (!scope?.active)
+            return original(input, init);
+        const start = Date.now();
+        const resv = reserveEvent();
+        const { url, methodFromInput } = describeFetchInput(input);
+        const method = (init?.method ?? methodFromInput ?? "GET").toUpperCase();
+        const reqBody = describeRequestBody(input, init);
+        try {
+            const res = await original(input, init);
+            if (!scope.active)
+                return res;
+            let responseBody;
+            let responseBodyTruncated;
+            // The reply the test gets is untouched: everything here reads a clone,
+            // and a body known to be binary is not read at all. See
+            // ./http-body.ts for why a blanket `.text()` was wrong.
+            const contentType = res.headers.get("content-type");
+            const contentLength = () => parseContentLength(res.headers.get("content-length"));
+            const textual = isTextualContentType(contentType);
+            if (textual === false) {
+                responseBody = omittedBody("binary", contentType, contentLength());
+            }
+            else {
+                try {
+                    const cloned = res.clone();
+                    const text = await cloned.text();
+                    if (textual === undefined && looksBinary(text)) {
+                        // No content type (or a multipart one), and the bytes say this
+                        // was never text.
+                        responseBody = omittedBody("binary", contentType, contentLength());
+                    }
+                    else {
+                        const t = truncateUtf8(text);
+                        responseBody = t.value;
+                        responseBodyTruncated = t.truncated;
+                    }
+                }
+                catch {
+                    // The stream failed, or something had already consumed the body.
+                    responseBody = omittedBody("unreadable", contentType, contentLength());
+                }
+            }
+            // The test may have timed out while we awaited the response body.
+            if (!scope.active)
+                return res;
+            const seq = recordHttp({
+                method,
+                url,
+                requestBody: reqBody.body,
+                requestBodyTruncated: reqBody.truncated,
+                status: res.status,
+                responseBody,
+                responseBodyTruncated,
+                durationMs: Date.now() - start,
+            }, resv);
+            return wrapResponse(res, seq);
+        }
+        catch (err) {
+            if (!scope.active)
+                throw err;
+            const e = err;
+            recordHttp({
+                method,
+                url,
+                requestBody: reqBody.body,
+                requestBodyTruncated: reqBody.truncated,
+                durationMs: Date.now() - start,
+                error: e?.message ?? String(err),
+            }, resv);
+            // Tag transport failures for ctx.poll (see TRANSPORT_ERROR). An abort
+            // is the caller's own signal (their AbortController or their
+            // AbortSignal.timeout) — their semantics, never retried for them.
+            if (typeof err === "object" &&
+                err !== null &&
+                e?.name !== "AbortError" &&
+                e?.name !== "TimeoutError") {
+                try {
+                    err[TRANSPORT_ERROR] = true;
+                }
+                catch {
+                    /* frozen error object — stays a hard error */
+                }
+            }
+            throw err;
+        }
+    };
+    // Preserve any provider-specific statics on `fetch` (e.g. Bun's
+    // `fetch.preconnect`) so consumers that touch them keep working.
+    const wrapped = wrappedFn;
+    for (const key of Object.keys(original)) {
+        wrapped[key] = original[key];
+    }
+    globalThis.fetch = wrapped;
+    return () => {
+        globalThis.fetch = original;
+    };
+}

package/dist/harness/instrumentation-scope.d.ts

@@ -0,0 +1,18 @@
+/** One test (or setup/eval invocation). Close it even on timeout: detached
+ * work retains its async context and must not write into the next test. */
+export interface InstrumentationScope {
+    active: boolean;
+    recording: boolean;
+}
+export declare function createInstrumentationScope(recording?: boolean): InstrumentationScope;
+export declare function currentInstrumentationScope(): InstrumentationScope | null | undefined;
+export declare function runInstrumented<T>(scope: InstrumentationScope, fn: () => T): T;
+/** Preserve native behavior through awaits, timers, and nested helpers without
+ * changing the instrumentation of concurrent test work. */
+export declare function runUninstrumented<T>(fn: () => T): T;
+/** Test-authored callbacks invoked later by ingress (ctx.intercept) keep
+ * their registration scope, even though the incoming request has none. */
+export declare function bindInstrumentationScope<A extends unknown[], R>(fn: (...args: A) => R): (...args: A) => R;
+/** Unscoped SDK sites (browser/interceptor callbacks, final drains) still use
+ * the active recorder. Fake internals and expired test contexts cannot. */
+export declare function scopeAllowsRecording(): boolean;

package/dist/harness/instrumentation-scope.js

@@ -0,0 +1,32 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+// No scope means native fetch. `null` explicitly isolates fake execution,
+// including helpers called directly from an instrumented test.
+const scopes = new AsyncLocalStorage();
+export function createInstrumentationScope(recording = true) {
+    return { active: true, recording };
+}
+export function currentInstrumentationScope() {
+    return scopes.getStore();
+}
+export function runInstrumented(scope, fn) {
+    return scopes.run(scope, fn);
+}
+/** Preserve native behavior through awaits, timers, and nested helpers without
+ * changing the instrumentation of concurrent test work. */
+export function runUninstrumented(fn) {
+    return scopes.run(null, fn);
+}
+/** Test-authored callbacks invoked later by ingress (ctx.intercept) keep
+ * their registration scope, even though the incoming request has none. */
+export function bindInstrumentationScope(fn) {
+    const scope = scopes.getStore();
+    return function (...args) {
+        return scopes.run(scope ?? null, () => fn.apply(this, args));
+    };
+}
+/** Unscoped SDK sites (browser/interceptor callbacks, final drains) still use
+ * the active recorder. Fake internals and expired test contexts cannot. */
+export function scopeAllowsRecording() {
+    const scope = scopes.getStore();
+    return scope === undefined || (scope !== null && scope.active && scope.recording);
+}

package/dist/harness/main.js

@@ -35,7 +35,7 @@
 import net from "node:net";
 import { METHODS } from "../daemon";
 import { codeOf } from "./methods";
-import { PROTOCOL_VERSION, decodeFrame, encodeFrame, fail, ok, } from "./protocol";
+import { PROTOCOL_VERSION, decodeFrame, describeThrow, encodeFrame, fail, ok, } from "./protocol";
 /** Capabilities this build announces. Empty is fine — the slot is what
  *  matters, so a later release has something to negotiate against. */
 const CAPABILITIES = [];
@@ -87,11 +87,11 @@ export function serve(socket, registry) {
             //
             // A refusal the method meant to make (an unknown case, a second test
             // while one is running) reports its own kind and just its message. An
-            // unexpected throw is a bug in the method and carries the stack,
-            // which is the only place that information exists.
+            // unexpected throw carries its message AND its stack — in that order,
+            // because a stack alone is sometimes headerless (`describeThrow`).
             const e = err;
             const code = codeOf(err);
-            const detail = code === "handler_error" ? (e?.stack ?? e?.message ?? String(err)) : e.message;
+            const detail = code === "handler_error" ? describeThrow(err) : e.message;
             send(fail(req.id, detail, code));
         }
     };

package/dist/harness/protocol.d.ts

@@ -86,3 +86,23 @@ export declare function ok(id: string, result?: Record<string, unknown>): Respon
 /** A failed reply to `id`. Always carries the id: a request that failed must
  *  never leave its caller waiting. */
 export declare function fail(id: string, message: string, code?: string): ResponseFrame;
+/**
+ * Describe a thrown value for the wire: the **message first**, then the
+ * frames — never the stack on its own.
+ *
+ * `error.stack` normally opens with `Error: <message>`, which is why it
+ * looked like the richer of the two. It is not always: Bun drops that
+ * header when the rejection is observed a turn later than it settled —
+ * a promise that rejected while nobody was awaiting it yet, which is
+ * exactly what a bootstrap image build is (`daemon.ts` starts every
+ * build at once and each service awaits its own prep when the DAG
+ * reaches it). The whole diagnosis of a failed build IS the message
+ * there: `docker build for <svc> failed:` plus the build log. Sending
+ * the stack alone published four frames and nothing else — no docker,
+ * no BuildKit, no compiler error (reported by the Harmony project,
+ * 2026-09-09; the same run's log had the message intact).
+ *
+ * A stack that already carries the message is returned as it stands, so
+ * the ordinary case is unchanged.
+ */
+export declare function describeThrow(err: unknown): string;

package/dist/harness/protocol.js

@@ -94,3 +94,37 @@ export function ok(id, result = {}) {
 export function fail(id, message, code) {
     return { kind: "response", id, ok: false, error: code ? { message, code } : { message } };
 }
+/**
+ * Describe a thrown value for the wire: the **message first**, then the
+ * frames — never the stack on its own.
+ *
+ * `error.stack` normally opens with `Error: <message>`, which is why it
+ * looked like the richer of the two. It is not always: Bun drops that
+ * header when the rejection is observed a turn later than it settled —
+ * a promise that rejected while nobody was awaiting it yet, which is
+ * exactly what a bootstrap image build is (`daemon.ts` starts every
+ * build at once and each service awaits its own prep when the DAG
+ * reaches it). The whole diagnosis of a failed build IS the message
+ * there: `docker build for <svc> failed:` plus the build log. Sending
+ * the stack alone published four frames and nothing else — no docker,
+ * no BuildKit, no compiler error (reported by the Harmony project,
+ * 2026-09-09; the same run's log had the message intact).
+ *
+ * A stack that already carries the message is returned as it stands, so
+ * the ordinary case is unchanged.
+ */
+export function describeThrow(err) {
+    const e = err;
+    const message = typeof e?.message === "string" ? e.message : "";
+    const stack = typeof e?.stack === "string" ? e.stack : "";
+    if (!message)
+        return stack || String(err);
+    if (stack.includes(message))
+        return stack;
+    const name = typeof e?.name === "string" && e.name.length > 0 ? e.name : "Error";
+    // The headerless form is `<Name>\n    at …`. Drop that bare first line
+    // and write the header ourselves, so the result reads like the stack a
+    // reader expects rather than a message with a stray `Error` in it.
+    const frames = stack.startsWith(`${name}\n`) ? stack.slice(name.length + 1) : stack;
+    return frames.length > 0 ? `${name}: ${message}\n${frames}` : `${name}: ${message}`;
+}