@specific.dev/spectest 0.79.0 → 0.79.2

package/src/harness/fetch.test.ts

@@ -0,0 +1,253 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { expect as assertValue } from "../index.js";
+import { type WrappedResponse } from "../inspect.js";
+import { recordFake, startRecording, stopRecording } from "../recorder.js";
+import { installFetchWrapper, isTransportError } from "./fetch.js";
+import {
+  bindInstrumentationScope,
+  createInstrumentationScope,
+  runInstrumented,
+  runUninstrumented,
+  type InstrumentationScope,
+} from "./instrumentation-scope.js";
+
+function deferred<T = void>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((done) => { resolve = done; });
+  return { promise, resolve };
+}
+
+describe("fetch execution scopes", () => {
+  let scope: InstrumentationScope;
+  let restore: () => void;
+  let server: ReturnType<typeof Bun.serve>;
+  let handler: (req: Request) => Response | Promise<Response>;
+  const url = (path: string) => new URL(path, server.url).href;
+
+  beforeEach(() => {
+    handler = () => Response.json({ value: 42 });
+    server = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch: (req) => handler(req) });
+    startRecording();
+    scope = createInstrumentationScope();
+    restore = installFetchWrapper();
+  });
+
+  afterEach(() => {
+    scope.active = false;
+    restore();
+    stopRecording();
+    server.stop(true);
+  });
+
+  test("test helpers retain HTTP and assertion provenance across awaits", async () => {
+    await runInstrumented(scope, async () => {
+      const helper = async () => {
+        await Promise.resolve();
+        return await fetch(url("/test")) as unknown as WrappedResponse;
+      };
+      const res = await helper();
+      expect(res.status.unwrap()).toBe(200);
+      assertValue(res.status).toBe(200);
+      assertValue((await res.json<{ value: number }>()).value).toBe(42);
+    });
+    const events = stopRecording();
+    expect(events.map((e) => e.kind)).toEqual(["http", "assertion", "assertion"]);
+    expect(events[1]).toMatchObject({ sourceSeq: events[0]!.seq, path: ["status"] });
+    expect(events[2]).toMatchObject({ sourceSeq: events[0]!.seq, path: ["body", "value"] });
+  });
+
+  test("background fetch is native even while a test recorder is active", async () => {
+    handler = () => Response.json({ error: "missing" }, { status: 404 });
+    const res = await fetch(url("/background"));
+    expect(res.status).toBe(404);
+    expect(res.ok).toBe(false);
+    expect(await res.json()).toEqual({ error: "missing" });
+    expect(stopRecording()).toEqual([]);
+  });
+
+  test("an HTTP fake records only the test's outer request", async () => {
+    handler = (req) => {
+      if (new URL(req.url).pathname === "/fake") {
+        return runUninstrumented(async () => {
+          await Promise.resolve();
+          const res = await fetch(url("/upstream"));
+          // Ordinary HTTP status/error handling must work inside the fake.
+          if (!res.ok) return new Response(await res.text(), { status: res.status });
+          return new Response("unexpected success");
+        });
+      }
+      return new Response("upstream unavailable", { status: 503 });
+    };
+    await runInstrumented(scope, async () => {
+      const res = await fetch(url("/fake")) as unknown as WrappedResponse;
+      expect(res.status.unwrap()).toBe(503);
+      expect((await res.text()).unwrap()).toBe("upstream unavailable");
+    });
+    expect(stopRecording()).toMatchObject([{ kind: "http", url: url("/fake"), status: 503 }]);
+  });
+
+  test("async fake internals do not suppress concurrent test events", async () => {
+    const entered = deferred();
+    const release = deferred();
+    await runInstrumented(scope, async () => {
+      const fake = runUninstrumented(async () => {
+        entered.resolve();
+        await release.promise;
+        const res = await fetch(url("/fake-internal"));
+        expect(res.status).toBe(200);
+        recordFake({ fake: "nested", member: "internal", args: [], durationMs: 0 });
+        return (await res.json()).value;
+      });
+      // Like invokeFakeHelper, the public call's completion is recorded in
+      // its caller's scope; internal operations stay in the fake scope.
+      const completed = fake.then((value) => {
+        recordFake({ fake: "example", member: "read", args: [], result: value, durationMs: 0 });
+      });
+      await entered.promise;
+      try {
+        await fetch(url("/test-during-fake"));
+      } finally {
+        release.resolve();
+      }
+      await completed;
+      await fetch(url("/test-after-fake"));
+    });
+    expect(stopRecording()).toMatchObject([
+      { kind: "http", url: url("/test-during-fake") },
+      { kind: "fake", fake: "example", member: "read", result: 42 },
+      { kind: "http", url: url("/test-after-fake") },
+    ]);
+  });
+
+  test("fake streams are returned without cloning or waiting for the body to end", async () => {
+    let controller!: ReadableStreamDefaultController<Uint8Array>;
+    handler = () => new Response(new ReadableStream<Uint8Array>({
+      start(c) {
+        controller = c;
+        c.enqueue(new TextEncoder().encode("data: first\n\n"));
+      },
+    }), { headers: { "content-type": "text/event-stream" } });
+    await runInstrumented(scope, () => runUninstrumented(async () => {
+      const res = await fetch(url("/stream"));
+      expect(res.status).toBe(200);
+      expect(res.bodyUsed).toBe(false);
+      const reader = res.body!.getReader();
+      try {
+        expect(new TextDecoder().decode((await reader.read()).value)).toBe("data: first\n\n");
+      } finally {
+        controller.close();
+        await reader.cancel();
+      }
+    }));
+    expect(stopRecording()).toEqual([]);
+  }, 2_000);
+
+  test("test-authored ingress callbacks retain their scope but their fake upstream does not", async () => {
+    const callback = runInstrumented(scope, () => bindInstrumentationScope(async () => {
+      const res = await fetch(url("/interceptor")) as unknown as WrappedResponse;
+      expect(res.status.unwrap()).toBe(200);
+      await runUninstrumented(async () => {
+        const upstream = await fetch(url("/fake-upstream"));
+        expect(upstream.status).toBe(200);
+      });
+    }));
+    // Dispatch from outside the test's async call chain, like ingress does.
+    await callback();
+    expect(stopRecording()).toMatchObject([{ kind: "http", url: url("/interceptor") }]);
+  });
+
+  test("fake errors keep native semantics and throwing restores the test scope", async () => {
+    await runInstrumented(scope, async () => {
+      let rawError: unknown;
+      try {
+        await runUninstrumented(async () => {
+          await Promise.resolve();
+          await fetch("http://[invalid");
+        });
+      } catch (err) {
+        rawError = err;
+      }
+      expect(rawError).toBeInstanceOf(Error);
+      expect(isTransportError(rawError)).toBe(false);
+      let recordedError: unknown;
+      try { await fetch("http://[invalid"); } catch (err) { recordedError = err; }
+      expect(isTransportError(recordedError)).toBe(true);
+      await fetch(url("/test"));
+    });
+    expect(stopRecording().map((e) => e.kind)).toEqual(["http", "http"]);
+  });
+
+  test("late responses and detached callbacks cannot record into the next test", async () => {
+    const entered = deferred();
+    const release = deferred();
+    handler = async (req) => {
+      if (new URL(req.url).pathname === "/late") {
+        entered.resolve();
+        await release.promise;
+      }
+      return Response.json({ value: 42 });
+    };
+    const late = runInstrumented(scope, async () => {
+      const res = await fetch(url("/late"));
+      expect(res.status).toBe(200);
+      await fetch(url("/detached"));
+    });
+    await entered.promise;
+    scope.active = false;
+    restore();
+    expect(stopRecording()).toEqual([]);
+    startRecording();
+    restore = installFetchWrapper();
+    const next = createInstrumentationScope();
+    try {
+      release.resolve();
+      await late;
+      await runInstrumented(next, () => fetch(url("/next-test")));
+      expect(stopRecording()).toMatchObject([{ kind: "http", url: url("/next-test"), seq: 0 }]);
+    } finally {
+      next.active = false;
+    }
+  });
+
+  test("a response body finishing after scope closure cannot record into a new test", async () => {
+    let controller!: ReadableStreamDefaultController<Uint8Array>;
+    const reading = deferred();
+    handler = () => new Response(new ReadableStream<Uint8Array>({
+      start(c) { controller = c; },
+      pull(c) {
+        c.enqueue(new TextEncoder().encode("part"));
+        reading.resolve();
+        // Keep the body open until the test closes the scope.
+        return new Promise(() => {});
+      },
+    }), { headers: { "content-type": "text/plain" } });
+    const pending = runInstrumented(scope, () => fetch(url("/body")));
+    await reading.promise;
+    // Yield so the fetch wrapper can start reading its clone.
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    scope.active = false;
+    stopRecording();
+    startRecording();
+    controller.close();
+    const res = await pending;
+    expect(res.status).toBe(200);
+    expect(await res.text()).toBe("part");
+    expect(stopRecording()).toEqual([]);
+  });
+
+  test("setup/eval keep wrapped responses without recording or wrapping fake internals", async () => {
+    const setup = createInstrumentationScope(false);
+    try {
+      await runInstrumented(setup, async () => {
+        const res = await fetch(url("/setup")) as unknown as WrappedResponse;
+        expect(res.status.unwrap()).toBe(200);
+        await runUninstrumented(async () => {
+          expect((await fetch(url("/setup-fake"))).status).toBe(200);
+        });
+      });
+      expect(stopRecording()).toEqual([]);
+    } finally {
+      setup.active = false;
+    }
+  });
+});

package/src/harness/fetch.ts

@@ -0,0 +1,174 @@
+import { wrapResponse, type WrappedResponse } from "../inspect.js";
+import { recordHttp, reserveEvent, truncateUtf8, type OmittedBody } 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: Parameters<typeof fetch>[0]): {
+  url: string;
+  methodFromInput?: string;
+} {
+  if (typeof input === "string") return { url: input };
+  if (input instanceof URL) return { url: input.toString() };
+  // Request instance
+  const req = input as Request;
+  return { url: req.url, methodFromInput: req.method };
+}
+
+function describeRequestBody(
+  input: Parameters<typeof fetch>[0],
+  init: Parameters<typeof fetch>[1],
+): { body?: string; truncated?: boolean } {
+  // 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: unknown): boolean {
+  return (
+    typeof err === "object" &&
+    err !== null &&
+    (err as Record<symbol, unknown>)[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(): () => void {
+  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: Parameters<typeof fetch>[0],
+    init?: Parameters<typeof fetch>[1],
+  ): Promise<Response | WrappedResponse> => {
+    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 as RequestInfo, init);
+      if (!scope.active) return res;
+      let responseBody: string | OmittedBody | undefined;
+      let responseBodyTruncated: boolean | undefined;
+      // 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 as Error;
+      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 as Record<symbol, unknown>)[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 as unknown as typeof fetch;
+  for (const key of Object.keys(original) as (keyof typeof original)[]) {
+    (wrapped as unknown as Record<string, unknown>)[key as string] = (
+      original as unknown as Record<string, unknown>
+    )[key as string];
+  }
+  globalThis.fetch = wrapped;
+  return () => {
+    globalThis.fetch = original;
+  };
+}

package/src/harness/instrumentation-scope.ts

@@ -0,0 +1,46 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/** 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;
+}
+
+// No scope means native fetch. `null` explicitly isolates fake execution,
+// including helpers called directly from an instrumented test.
+const scopes = new AsyncLocalStorage<InstrumentationScope | null>();
+
+export function createInstrumentationScope(recording = true): InstrumentationScope {
+  return { active: true, recording };
+}
+
+export function currentInstrumentationScope(): InstrumentationScope | null | undefined {
+  return scopes.getStore();
+}
+
+export function runInstrumented<T>(scope: InstrumentationScope, fn: () => T): T {
+  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<T>(fn: () => T): T {
+  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<A extends unknown[], R>(fn: (...args: A) => R): (...args: A) => R {
+  const scope = scopes.getStore();
+  return function (this: unknown, ...args: A): R {
+    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(): boolean {
+  const scope = scopes.getStore();
+  return scope === undefined || (scope !== null && scope.active && scope.recording);
+}

package/src/harness/main.ts

@@ -40,6 +40,7 @@ import { codeOf } from "./methods";
 import {
   PROTOCOL_VERSION,
   decodeFrame,
+  describeThrow,
   encodeFrame,
   fail,
   ok,
@@ -115,12 +116,11 @@ export function serve(
       //
       // 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 as Error;
       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/src/harness/protocol.test.ts

@@ -18,6 +18,7 @@ import {
   KNOWN_METHODS,
   PROTOCOL_VERSION,
   decodeFrame,
+  describeThrow,
   encodeFrame,
   fail,
   ok,
@@ -146,3 +147,44 @@ describe("replies", () => {
     expect(fail("7", "boom", "c")!.error!.code).toBe("c");
   });
 });
+
+describe("describeThrow", () => {
+  test("an ordinary stack, which already opens with the message, is untouched", () => {
+    const err = new Error("docker build for web failed:\nCOPY: not found");
+    expect(describeThrow(err)).toBe(err.stack);
+  });
+
+  /**
+   * The shape this function exists for, produced rather than written by
+   * hand: a promise that rejects while nobody awaits it yet and is
+   * observed a turn later comes back with a headerless stack. That is a
+   * bootstrap image build (`daemon.ts` starts every build at once and a
+   * service awaits its own prep when the DAG reaches it), and the build
+   * log lives in the message it drops.
+   */
+  test("a headerless stack gets its message back", async () => {
+    const message = "docker build for client-app failed:\n#12 ERROR: killed";
+    const rejected = (async () => {
+      throw new Error(message);
+    })();
+    rejected.catch(() => undefined);
+    await new Promise((r) => setTimeout(r, 5));
+    let caught: unknown;
+    try {
+      await rejected;
+    } catch (e) {
+      caught = e;
+    }
+    const described = describeThrow(caught);
+    expect(described).toContain(message);
+    expect(described.startsWith(`Error: ${message}`)).toBe(true);
+    // The frames survive, and the bare `Error` line they hung under does not.
+    expect(described).toContain("    at ");
+    expect(described).not.toContain("\nError\n");
+  });
+
+  test("a non-Error keeps whatever it can say for itself", () => {
+    expect(describeThrow("plain string")).toBe("plain string");
+    expect(describeThrow({ message: "no stack here" })).toBe("Error: no stack here");
+  });
+});

package/src/harness/protocol.ts

@@ -161,3 +161,36 @@ export function ok(id: string, result: Record<string, unknown> = {}): ResponseFr
 export function fail(id: string, message: string, code?: string): ResponseFrame {
   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: unknown): string {
+  const e = err as { message?: unknown; stack?: unknown; name?: unknown } | null | undefined;
+  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}`;
+}

package/src/harness/raw-fetch.ts

@@ -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: typeof fetch | undefined;
 

package/src/index.ts

@@ -2053,6 +2053,9 @@ export interface FakeDefinition<
    * 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>;
   /**
@@ -2068,6 +2071,8 @@ export interface FakeDefinition<
    * 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/src/recorder.ts

@@ -9,6 +9,7 @@
 // callers can invoke them unconditionally.
 
 import { clearPendingNullish } from "./inspect.js";
+import { scopeAllowsRecording } from "./harness/instrumentation-scope.js";
 
 const OUTPUT_SNIPPET_BYTES = 256 * 1024;
 
@@ -747,7 +748,7 @@ export function resumeRecording(): void {
 }
 
 function active(): boolean {
-  return current !== null && paused === 0;
+  return current !== null && paused === 0 && scopeAllowsRecording();
 }
 
 export function startRecording(): void {