@specific.dev/spectest 0.79.1 → 0.80.0

package/dist/daemon.js

@@ -24,7 +24,7 @@ import { pathToFileURL } from "node:url";
 import { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard, validateServiceImage, proxy as makeProxyDecl, } from "./index.js";
 import { COVERAGE_CONTAINER_DIR, coverageBundleRef, coverageHostDir, encodeCoverageBundle, isEmptyReport, readCoverageDir, applyCoverageDelta, } from "./harness/coverage.js";
 import { configureBrowserCoverage } from "./browser-coverage.js";
-import { applyCoverageAdapters, coverageAdapters, coverageReportsMode, validateCoverage, nodeCoverageToolsAvailable, nodeCoverageToolsDir, NODE_COVERAGE_TOOLS_CONTAINER_DIR, } from "./coverage.js";
+import { applyCoverageAdapters, coverageAdapters, coverageReportsMode, validateCoverage, } from "./coverage.js";
 import { serviceForHost as hostToService } from "./harness/browser-coverage.js";
 import { acquirePersistentBrowser, mobileKey } from "./browser.js";
 import { isMobileApp, openPersistentMobile } from "./mobile.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) {
@@ -690,16 +690,9 @@ async function ensureCoverage(svc) {
     const host = coverageHostDir(WORKSPACE, svc.name);
     await fs.mkdir(host, { recursive: true });
     await fs.chmod(host, 0o777);
-    const flags = [`--volume=${host}:${COVERAGE_CONTAINER_DIR}`];
-    // The conversion tools golden ships (`c8` for `coverage.node()`),
-    // read-only, on the same existence check the adapter makes at capture
-    // — so the VM and the container agree on whether they are there. A
-    // plain `--volume`, never a config `volumes` entry: an absolute-source
-    // volume dir is listed in the delta-restore manifest and wiped.
-    if (await nodeCoverageToolsAvailable()) {
-        flags.push(`--volume=${nodeCoverageToolsDir()}:${NODE_COVERAGE_TOOLS_CONTAINER_DIR}:ro`);
-    }
-    return flags;
+    // Nothing else is mounted: no conversion runs in the container (the
+    // c8 tools mount went with SDK 0.80).
+    return [`--volume=${host}:${COVERAGE_CONTAINER_DIR}`];
 }
 /** Keyed by image ID, not tag: `spectest/<svc>:latest` is retagged onto
  *  new content every rebuild, and a stale uid is silently wrong. */
@@ -1705,7 +1698,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 +2128,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 +2538,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 +2756,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 +2842,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 +3152,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 +3884,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 +4346,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 +4478,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 +4498,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 +4830,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 +4966,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 +4980,7 @@ async function evalCode(code, secrets) {
     }
     finally {
         clearRecordSecrets();
+        fetchScope.active = false;
         restoreFetch();
         restoreConsole();
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -5219,8 +5048,7 @@ async function evalCode(code, secrets) {
 // ────────────────────────────────────────────────────────────────────────
 /** Where the baked compiler lives. Overridable so the typecheck — and the
  *  blocking rules, which always use THIS copy rather than the project's own —
- *  can be driven outside a VM (same convention as
- *  `SPECTEST_COVERAGE_TOOLS_DIR`). */
+ *  can be driven outside a VM. */
 const TYPECHECK_DIR = process.env.SPECTEST_TYPECHECK_DIR ?? "/opt/spectest/typecheck";
 /** Cap on errors shipped in the report; `totalErrors` carries the true count. */
 const TYPECHECK_ERROR_CAP = 50;

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/raw-fetch.js

@@ -1,8 +1,8 @@
 // The real `fetch`, for SDK internals that must not go through the test
 // recorder's wrapper.
 //
-// While a test (or an eval) runs, the daemon replaces `globalThis.fetch`
-// with an instrumented one: it records an `http` event, and it hands back
+// The daemon's `globalThis.fetch` dispatcher instruments calls in the async
+// scope of a test (or setup/eval): it records an `http` event, and hands back
 // a WRAPPED response whose `ok` / `status` are provenance handles rather
 // than a boolean and a number. That is exactly right for a test's own
 // calls, and exactly wrong inside the SDK, in two ways:
@@ -17,8 +17,9 @@
 //      handed its response only after the stream it was waiting to read
 //      has already ended. A long-lived stream deadlocks.
 //
-// So SDK-internal HTTP goes through `rawFetch`. The daemon publishes the
-// original here when it installs its wrapper.
+// Fake execution is explicitly outside that scope. SDK-internal HTTP that
+// runs WITHIN a test's scope goes through `rawFetch` instead. The daemon
+// publishes the original here when it installs its wrapper.
 let original;
 /** Called by the daemon with the real `fetch`, before it installs its
  *  instrumented one. */

package/dist/index.d.ts

@@ -1405,6 +1405,9 @@ export interface FakeDefinition<S = any, H extends Record<string, unknown> = Rec
      * real backing instance, `ctx.dnsName(...)` to name it). Return any
      * `Response`. Thrown errors surface as 500s. The request URL is the
      * absolute URL the client used — useful for routing on the path.
+     * Fake code uses native `fetch`: responses are ordinary `Response` objects
+     * and internal requests are not added to a running test's timeline. This
+     * also applies to state/helper factories and helper implementations.
      */
     handler: (req: Request, state: S, ctx: FakeContext) => Response | Promise<Response>;
     /**
@@ -1420,6 +1423,8 @@ export interface FakeDefinition<S = any, H extends Record<string, unknown> = Rec
      * Every call is tracked in the test timeline: it records a `fake` step
      * and the return value is tagged so a later `expect(...)` on it nests
      * under that step in the UI (same provenance as `fetch`/db results).
+     * Operations inside the helper are uninstrumented, including across awaits;
+     * concurrent operations in test code continue to record normally.
      * The step renders the return value as JSON; wrap it in {@link annotate}
      * to add a richer view (an email, today) that the step's panel leads with,
      * the JSON one tab away — the test still receives the raw value, unchanged

package/dist/recorder.js

@@ -8,6 +8,7 @@
 // current recorder is `null` and the `record*` helpers are no-ops, so
 // callers can invoke them unconditionally.
 import { clearPendingNullish } from "./inspect.js";
+import { scopeAllowsRecording } from "./harness/instrumentation-scope.js";
 const OUTPUT_SNIPPET_BYTES = 256 * 1024;
 class Recorder {
     events = [];
@@ -117,7 +118,7 @@ export function resumeRecording() {
     paused = Math.max(0, paused - 1);
 }
 function active() {
-    return current !== null && paused === 0;
+    return current !== null && paused === 0 && scopeAllowsRecording();
 }
 export function startRecording() {
     current = new Recorder();