@specific.dev/spectest 0.88.3 → 0.89.1

package/src/components/electron.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test';
-import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { electron } from './electron.js';
@@ -36,3 +36,86 @@ describe('Electron component contract', () => {
     expect(isDesktopApp(null)).toBe(false);
   });
 });
+
+describe('Electron component in a monorepo', () => {
+  function monorepo(run: (root: string) => void) {
+    const root = mkdtempSync(join(tmpdir(), 'spectest-electron-mono-'));
+    try {
+      mkdirSync(join(root, 'apps', 'desktop'), { recursive: true });
+      writeFileSync(join(root, 'package.json'), JSON.stringify({ workspaces: ['apps/*'], devDependencies: { electron: '44.0.0' } }));
+      writeFileSync(join(root, 'package-lock.json'), '{}');
+      writeFileSync(join(root, 'apps', 'desktop', 'package.json'), JSON.stringify({ name: '@acme/desktop' }));
+      run(root);
+    } finally { rmSync(root, { recursive: true, force: true }); }
+  }
+  test('builds from the context root and runs the app from its workspace', () => monorepo(root => {
+    const service = electron({ appDir: join(root, 'apps/desktop'), context: root });
+    expect(service.image).toMatchObject({ context: root });
+    const content = (service.image as { content: string }).content;
+    expect(content).toContain('COPY . .\nRUN npm ci\n');
+    expect(content).toContain("RUN cd apps/desktop && node \"$(node -p \"require.resolve('electron/install.js')\")\"\n");
+    expect(content).toContain('RUN cd apps/desktop && npm run build\n');
+    expect(service.env?.SPECTEST_ELECTRON_APP_DIR).toBe('/app/apps/desktop');
+  }));
+  test('accepts electron declared at the context root only', () => monorepo(root => {
+    expect(() => electron({ appDir: join(root, 'apps/desktop'), context: root })).not.toThrow();
+    writeFileSync(join(root, 'package.json'), JSON.stringify({ workspaces: ['apps/*'] }));
+    expect(() => electron({ appDir: join(root, 'apps/desktop'), context: root })).toThrow('declare electron');
+  }));
+  test('rejects an app directory outside the context', () => monorepo(root => {
+    expect(() => electron({ appDir: root, context: join(root, 'apps/desktop') })).toThrow('must be inside context');
+  }));
+  test('the default context keeps the single-app image shape', () => fixture(appDir => {
+    const content = (electron({ appDir }).image as { content: string }).content;
+    expect(content).toContain('RUN node "$(node -p "require.resolve(\'electron/install.js\')")"\nRUN npm run build\n');
+    expect(electron({ appDir }).env?.SPECTEST_ELECTRON_APP_DIR).toBe('/app');
+  }));
+});
+
+describe('Electron environment-CA trust', () => {
+  const { ELECTRON_CA_TRUST } = require('./electron-chrome.js');
+  const { execFileSync } = require('node:child_process');
+  const { readFileSync: read } = require('node:fs');
+  function pki(run: (dir: string) => void) {
+    const dir = mkdtempSync(join(tmpdir(), 'spectest-electron-ca-'));
+    const sh = (cmd: string) => execFileSync('sh', ['-c', cmd], { cwd: dir, stdio: 'pipe' });
+    try {
+      sh('openssl req -x509 -newkey rsa:2048 -nodes -keyout ca.key -out ca.pem -days 2 -subj /CN=env-ca 2>/dev/null');
+      sh('openssl req -x509 -newkey rsa:2048 -nodes -keyout other.key -out other.pem -days 2 -subj /CN=other-ca 2>/dev/null');
+      sh('printf "subjectAltName=DNS:api.example.test\\nbasicConstraints=CA:FALSE\\n" > ext.cnf');
+      sh('openssl req -newkey rsa:2048 -nodes -keyout leaf.key -out leaf.csr -subj /CN=api.example.test 2>/dev/null');
+      sh('openssl x509 -req -in leaf.csr -CA ca.pem -CAkey ca.key -CAcreateserial -out leaf.pem -days 2 -extfile ext.cnf 2>/dev/null');
+      sh('openssl x509 -req -in leaf.csr -CA other.pem -CAkey other.key -CAcreateserial -out stranger.pem -days 2 -extfile ext.cnf 2>/dev/null');
+      sh('printf "basicConstraints=CA:TRUE\\nkeyUsage=keyCertSign\\n" > ica.cnf');
+      sh('openssl req -newkey rsa:2048 -nodes -keyout ica.key -out ica.csr -subj /CN=env-intermediate 2>/dev/null');
+      sh('openssl x509 -req -in ica.csr -CA ca.pem -CAkey ca.key -CAcreateserial -out ica.pem -days 2 -extfile ica.cnf 2>/dev/null');
+      sh('openssl x509 -req -in leaf.csr -CA ica.pem -CAkey ica.key -CAcreateserial -out leaf2.pem -days 2 -extfile ext.cnf 2>/dev/null');
+      run(dir);
+    } finally { rmSync(dir, { recursive: true, force: true }); }
+  }
+  // The hook's source, evaluated the way Electron evaluates it: plain CommonJS.
+  const trust = new Function('require', `${ELECTRON_CA_TRUST}; return { loadEnvironmentCa, issuedByEnvironmentCa };`)(require);
+  const request = (leafPath: string, hostname: string, issuers: string[] = []) => {
+    let cert: any = undefined;
+    for (const p of [...issuers].reverse()) cert = { data: read(p, 'utf8'), issuerCert: cert };
+    return { hostname, errorCode: -202, certificate: { data: read(leafPath, 'utf8'), issuerCert: cert } };
+  };
+  test('accepts a leaf the environment CA issued for the requested host', () => pki(dir => {
+    const ca = trust.loadEnvironmentCa(join(dir, 'ca.pem'));
+    expect(ca).not.toBeNull();
+    expect(trust.issuedByEnvironmentCa(ca, request(join(dir, 'leaf.pem'), 'api.example.test'))).toBe(true);
+    expect(trust.issuedByEnvironmentCa(ca, request(join(dir, 'leaf2.pem'), 'api.example.test', [join(dir, 'ica.pem')]))).toBe(true);
+    expect(trust.issuedByEnvironmentCa(ca, request(join(dir, 'leaf2.pem'), 'api.example.test', [join(dir, 'ica.pem'), join(dir, 'ca.pem')]))).toBe(true);
+  }));
+  test('rejects other issuers, other hosts, a bare intermediate, and the CA itself', () => pki(dir => {
+    const ca = trust.loadEnvironmentCa(join(dir, 'ca.pem'));
+    expect(trust.issuedByEnvironmentCa(ca, request(join(dir, 'stranger.pem'), 'api.example.test'))).toBe(false);
+    expect(trust.issuedByEnvironmentCa(ca, request(join(dir, 'leaf.pem'), 'evil.example.test'))).toBe(false);
+    expect(trust.issuedByEnvironmentCa(ca, request(join(dir, 'leaf2.pem'), 'api.example.test'))).toBe(false);
+    expect(trust.issuedByEnvironmentCa(ca, request(join(dir, 'ca.pem'), 'api.example.test'))).toBe(false);
+  }));
+  test('no CA file means no trust hook', () => {
+    expect(trust.loadEnvironmentCa(undefined)).toBeNull();
+    expect(trust.loadEnvironmentCa('/nonexistent/ca.pem')).toBeNull();
+  });
+});

package/src/components/electron.ts

@@ -1,12 +1,22 @@
 import { existsSync, readFileSync } from "node:fs";
+import { posix } from "node:path";
 import type { ServiceDefinition } from "../index.js";
 import { resolveProjectPath } from "../project-files.js";
 import { desktopApp, type DesktopApp } from "../desktop.js";
 import { ELECTRON_CHROME_HOOK } from "./electron-chrome.js";
 
 export interface ElectronOptions {
-  /** Project-relative app directory; must contain package.json and Electron. */
+  /** Project-relative app directory; must contain package.json. Electron must
+   * be declared here or in the context's package.json. */
   appDir?: string;
+  /**
+   * Image build context, relative to the project root. Default `appDir`.
+   * Set it to the repository root when the app is one workspace of a
+   * monorepo and resolves packages from above its own directory. The
+   * context is copied to `/app`; `installCommand` runs at the context root,
+   * `buildCommand` and Electron run in the app directory below it.
+   */
+  context?: string;
   /** Debian Node image tag, default 24-bookworm-slim. */
   nodeVersion?: string;
   /** Build the main/preload/renderer output; default npm run build. */
@@ -26,13 +36,14 @@ export const ELECTRON_LAUNCHER = String.raw`
 import http from 'node:http';
 import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
-const require = createRequire('/app/package.json');
+const appDir = process.env.SPECTEST_ELECTRON_APP_DIR || '/app';
+const require = createRequire(appDir + '/package.json');
 const child = spawn(require('electron'), [
   ...(process.getuid?.() === 0 ? ['--no-sandbox'] : []),
   '--disable-dev-shm-usage', '--remote-debugging-port=9222',
   '-r', '/spectest-electron-chrome.cjs',
   process.env.SPECTEST_ELECTRON_ENTRY || '.',
-], { cwd: '/app', stdio: 'inherit', env: process.env });
+], { cwd: appDir, stdio: 'inherit', env: process.env });
 const upstream = req => ({
   host: '127.0.0.1', port: 9222, path: req.url, method: req.method,
   headers: { ...req.headers, host: '127.0.0.1:9222' },
@@ -68,18 +79,42 @@ child.on('exit', code => process.exit(code ?? 1));
 for (const signal of ['SIGTERM', 'SIGINT']) process.on(signal, () => child.kill(signal));
 `;
 
+/** Read a package.json and tell whether it declares electron. */
+function declaresElectron(manifest: string): boolean {
+  if (!existsSync(manifest)) return false;
+  const pkg = JSON.parse(readFileSync(manifest, "utf8"));
+  return Boolean(pkg.dependencies?.electron || pkg.devDependencies?.electron);
+}
+
+/** The app directory as a path inside the build context: "." or "a/b". */
+function appPathInContext(appDir: string, context: string): string {
+  const rel = posix.relative(posix.normalize(context), posix.normalize(appDir));
+  if (rel === "") return ".";
+  if (rel.startsWith("..") || posix.isAbsolute(rel)) {
+    throw new Error(`electron(): appDir ${JSON.stringify(appDir)} must be inside context ${JSON.stringify(context)}`);
+  }
+  return rel;
+}
+
 /** Real Linux Electron under Xvfb, with a generated image and graphical replay.
  * Like expo(), returns an app handle for the matching context method.
  * Requires Linux-compatible application dependencies and binaries. */
 export function electron(options: ElectronOptions = {}) {
   const appDir = options.appDir ?? ".";
+  const context = options.context ?? appDir;
+  const appPath = appPathInContext(appDir, context);
   const manifest = resolveProjectPath(`${appDir}/package.json`);
   if (!existsSync(manifest)) throw new Error(`electron(): no package.json in ${appDir}`);
-  const pkg = JSON.parse(readFileSync(manifest, "utf8"));
-  if (!pkg.dependencies?.electron && !pkg.devDependencies?.electron) {
-    throw new Error("electron(): declare electron in the app's dependencies or devDependencies");
+  // A monorepo declares electron in the workspace or at the root; both work
+  // because the app resolves `electron` upward from its own directory.
+  if (!declaresElectron(manifest) && !declaresElectron(resolveProjectPath(`${context}/package.json`))) {
+    throw new Error(
+      "electron(): declare electron in the app's dependencies or devDependencies" +
+        (context === appDir ? "" : ` (in ${appDir} or in the context ${context})`),
+    );
   }
-  const locked = existsSync(resolveProjectPath(`${appDir}/package-lock.json`));
+  // The install runs at the context root, so that is where the lockfile counts.
+  const locked = existsSync(resolveProjectPath(`${context}/package-lock.json`));
   const node = options.nodeVersion ?? "24-bookworm-slim";
   if (!/^[\w.-]+$/.test(node)) throw new Error("electron(): invalid Node image tag");
   const install = options.installCommand ?? (locked ? "npm ci" : "npm install");
@@ -87,18 +122,22 @@ export function electron(options: ElectronOptions = {}) {
   if ([install, build].some(command => /[\r\n]/.test(command))) {
     throw new Error("electron(): build/install commands must be single-line shell commands");
   }
+  // Electron can be hoisted to the context root, so find its install script
+  // through Node's resolution from the app directory instead of a fixed path.
+  const inApp = appPath === "." ? "" : `cd ${appPath} && `;
+  const fetchElectron = `${inApp}node "$(node -p "require.resolve('electron/install.js')")"`;
   return {
     image: {
       type: "dockerfile",
-      context: appDir,
+      context,
       exclude: ["node_modules", "**/node_modules", "out", "test-results", ".data"],
       content: `FROM node:${node}
 RUN apt-get update && apt-get install -y --no-install-recommends xvfb xauth libgtk-3-0 libnss3 libgbm1 libasound2 fonts-liberation ca-certificates && rm -rf /var/lib/apt/lists/*
 WORKDIR /app
 COPY . .
 RUN ${install}
-RUN node node_modules/electron/install.js
-RUN ${build}
+RUN ${fetchElectron}
+RUN ${inApp}${build}
 `,
     },
     files: [
@@ -106,7 +145,11 @@ RUN ${build}
       { path: "/spectest-electron-chrome.cjs", content: ELECTRON_CHROME_HOOK },
     ],
     command: "xvfb-run -a node /spectest-electron.mjs",
-    env: { ...options.env, SPECTEST_ELECTRON_ENTRY: options.entry ?? "." },
+    env: {
+      ...options.env,
+      SPECTEST_ELECTRON_ENTRY: options.entry ?? ".",
+      SPECTEST_ELECTRON_APP_DIR: appPath === "." ? "/app" : `/app/${appPath}`,
+    },
     dependsOn: options.dependsOn,
     ports: [9223],
     readyCheck: { type: "http", port: 9223, path: "/json/version", timeoutSecs: 60 },

package/src/daemon.ts

@@ -124,6 +124,13 @@ import {
   corsPreflightResponse,
   isCorsPreflight,
 } from "./harness/http-proxy.js";
+import {
+  WS_BRIDGE_HANDLERS,
+  openUpstreamWebSocket,
+  parseSubprotocols,
+  upstreamHandshakeHeaders,
+  type WsBridgeData,
+} from "./harness/ws-bridge.js";
 import {
   certCovers as hostmatchCertCovers,
   hostWithoutPort,
@@ -2112,14 +2119,6 @@ async function bridgeGatewayIp(): Promise<string> {
  *  The shape is `harness/ingress-table.ts`'s, generic over that record. */
 type Route = IngressRoute<FakeRuntime>;
 
-/** Per-WS-upgrade context: the upstream URL we'll open in `open()` and
- * keep the bridge in `message()`/`close()`. Stored on `ws.data`. */
-interface WsBridgeData {
-  upstreamUrl: string;
-  upstream: WebSocket | null;
-  pending: Array<string | ArrayBuffer | Uint8Array>;
-}
-
 /**
  * Pristine `fetch` captured at module load, before any test-scoped
  * fetch wrapper can monkey-patch `globalThis.fetch`. The reverse-proxy
@@ -2440,8 +2439,8 @@ async function unbindRuntimeTls(hostname: string): Promise<void> {
  * Spin up one Bun.serve listener bound to (port, optional TLS) that
  * dispatches every request to the matching Route by Host header.
  *
- * Shared by the HTTP and HTTPS branches. Also exports a `websocket`
- * handler so reverse-proxy targets can transparently bridge WS
+ * Shared by the HTTP and HTTPS branches. Also carries the `websocket`
+ * handler set so reverse-proxy targets can transparently bridge WS
  * upgrades through to their upstream service.
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -2485,74 +2484,9 @@ function bindIngressServer(
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     fetch: (req: Request, server: any): Response | Promise<Response> =>
       dispatchIngress(req, server, byHost, listenerLabel, proto),
-    websocket: {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      async open(ws: any) {
-        const data = ws.data as WsBridgeData;
-        try {
-          const upstream = new WebSocket(data.upstreamUrl);
-          // ArrayBuffer so binary frames can be ws.send()'d to the
-          // downstream client verbatim — Blob would need an extra
-          // .arrayBuffer() round-trip on every message.
-          upstream.binaryType = "arraybuffer";
-          data.upstream = upstream;
-          upstream.addEventListener("open", () => {
-            for (const m of data.pending) upstream.send(m);
-            data.pending = [];
-          });
-          upstream.addEventListener("message", (ev: MessageEvent) => {
-            try {
-              ws.send(ev.data);
-            } catch {
-              /* client gone */
-            }
-          });
-          upstream.addEventListener("close", (ev: CloseEvent) => {
-            try {
-              ws.close(ev.code, ev.reason);
-            } catch {
-              /* already closed */
-            }
-          });
-          upstream.addEventListener("error", () => {
-            try {
-              ws.close(1011, "upstream error");
-            } catch {
-              /* already closed */
-            }
-          });
-        } catch (err) {
-          // eslint-disable-next-line no-console
-          console.warn(`[ingress] ws upstream open failed for ${data.upstreamUrl}:`, err);
-          try {
-            ws.close(1011, "upstream open failed");
-          } catch {
-            /* ignore */
-          }
-        }
-      },
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      message(ws: any, message: string | Buffer) {
-        const data = ws.data as WsBridgeData;
-        const payload =
-          typeof message === "string" ? message : new Uint8Array(message);
-        if (data.upstream && data.upstream.readyState === WebSocket.OPEN) {
-          data.upstream.send(payload);
-        } else {
-          // Buffer until the upstream finishes its handshake.
-          data.pending.push(payload);
-        }
-      },
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      close(ws: any, code: number, reason: string) {
-        const data = ws.data as WsBridgeData;
-        try {
-          data.upstream?.close(code, reason);
-        } catch {
-          /* ignore */
-        }
-      },
-    },
+    // The frame relay for bridged WebSocket upgrades; `proxyToService`
+    // opens the upstream before it upgrades the client (harness/ws-bridge.ts).
+    websocket: WS_BRIDGE_HANDLERS,
   };
   return Bun.serve(opts);
 }
@@ -2657,8 +2591,12 @@ function ingressClientIp(server: any, req: Request, proto: string): string | und
  * Reverse-proxy a request to `http://<service>:<port>` on
  * `spectest-net`. Handles plain HTTP/1.1 + 2 and WebSocket upgrades:
  *
- *   - WS upgrade requests get routed through `server.upgrade()`, with
- *     the upstream URL stashed on `ws.data`. The shared `websocket`
+ *   - WS upgrade requests open the upstream WebSocket first, with the
+ *     client's full `Sec-WebSocket-Protocol` list and its forwardable
+ *     headers (cookies, authorization, origin, x-forwarded-*). Only after
+ *     that handshake succeeds is the client upgraded, with the protocol
+ *     the upstream selected; a refused upstream handshake is a 502, not a
+ *     101 followed by a close. The open upstream rides on `ws.data`; the shared `websocket`
  *     handler opens the upstream and bridges frames both ways.
  *   - Plain requests pass through via `fetch()` with hop-by-hop
  *     headers stripped; the response body is a ReadableStream returned
@@ -2688,16 +2626,40 @@ async function proxyToService(
   const upgrade = req.headers.get("upgrade")?.toLowerCase() ?? "";
   if (upgrade === "websocket") {
     const upstreamUrl = `ws://${await proxyUpstreamHost(service)}:${port}${upstreamPath}`;
-    const wsData: WsBridgeData = {
-      upstreamUrl,
-      upstream: null,
-      pending: [],
-    };
-    const ok = server.upgrade(req, { data: wsData });
+    // The upstream handshake carries what the client's did: the whole
+    // subprotocol list (a console ticket often rides as the second entry)
+    // and the forwardable headers. Same provenance stamps as the HTTP path.
+    const protocols = parseSubprotocols(req.headers.get("sec-websocket-protocol"));
+    const headers = upstreamHandshakeHeaders(req.headers, {
+      service,
+      port,
+      proto,
+      clientIp: ingressClientIp(server, req, proto),
+    });
+    const opened = await openUpstreamWebSocket(upstreamUrl, { protocols, headers });
+    if (!opened.ok) {
+      return new Response(
+        `spectest-daemon: ${opened.reason} (${upstreamUrl}) on ${listenerLabel}\n`,
+        { status: 502, headers: { "content-type": "text/plain" } },
+      );
+    }
+    const wsData: WsBridgeData = { upstreamUrl, upstream: opened.socket };
+    // Echo the protocol the upstream selected; Bun would otherwise pick
+    // the client's first entry by itself, which can differ.
+    const selected = opened.socket.protocol;
+    const ok = server.upgrade(req, {
+      data: wsData,
+      headers: selected ? { "sec-websocket-protocol": selected } : undefined,
+    });
     if (ok) {
       // Bun has already taken over the response — return a stub.
       return new Response(null, { status: 101 });
     }
+    try {
+      opened.socket.close(1011, "client upgrade refused");
+    } catch {
+      /* ignore */
+    }
     return new Response(
       `spectest-daemon: ws upgrade refused on ${listenerLabel}\n`,
       { status: 426, headers: { "content-type": "text/plain" } },

package/src/harness/fetch.test.ts

@@ -1,7 +1,7 @@
 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 { readRaw, readTag, type SpectestFetch, type WrappedResponse } from "../inspect.js";
+import { recordFake, startRecording, stopRecording, type HttpEvent } from "../recorder.js";
 import { installFetchWrapper, isTransportError } from "./fetch.js";
 import {
   bindInstrumentationScope,
@@ -65,6 +65,72 @@ describe("fetch execution scopes", () => {
     expect(stopRecording()).toEqual([]);
   });
 
+  test("header assertions retain HTTP provenance, including missing headers and cookies", async () => {
+    handler = () => new Response("ok", { headers: [
+      ["content-type", "text/plain"],
+      ["set-cookie", "a=1; Path=/"],
+      ["set-cookie", "b=2; Path=/"],
+    ] });
+    await runInstrumented(scope, async () => {
+      const res = await fetch(url("/headers")) as unknown as WrappedResponse;
+      assertValue(res.headers.get("Content-Type")).toBe("text/plain");
+      assertValue(res.headers.get("x-missing")).toBe(null);
+      assertValue(res.headers.has("CONTENT-TYPE")).toBe(true);
+      assertValue(res.headers.has("x-missing")).toBe(false);
+      assertValue(res.headers.getSetCookie()).toEqual(["a=1; Path=/", "b=2; Path=/"]);
+      assertValue(res.headers.getSetCookie()[1]).toBe("b=2; Path=/");
+    });
+    const events = stopRecording();
+    expect(events.map((e) => e.kind)).toEqual(["http", ...Array(6).fill("assertion")]);
+    expect(events.slice(1)).toMatchObject([
+      { sourceSeq: events[0]!.seq, path: ["headers", "content-type"] },
+      { sourceSeq: events[0]!.seq, path: ["headers", "x-missing"] },
+      { sourceSeq: events[0]!.seq, path: ["headers", "content-type", "<has>"] },
+      { sourceSeq: events[0]!.seq, path: ["headers", "x-missing", "<has>"] },
+      { sourceSeq: events[0]!.seq, path: ["headers", "set-cookie"] },
+      { sourceSeq: events[0]!.seq, path: ["headers", "set-cookie", "1"] },
+    ]);
+  });
+
+  test("wrapped headers keep native iteration and expose raw headers for ordinary APIs", async () => {
+    await runInstrumented(scope, async () => {
+      const res = await fetch(url("/headers")) as unknown as WrappedResponse;
+      const headers = res.headers;
+      const raw = res.unwrap().headers;
+      expect(res.headers).toBe(headers);
+      expect(headers.unwrap()).toBe(raw);
+      expect<unknown>(readRaw(headers)).toBe(raw);
+      expect(headers.get("content-type")?.unwrap() ?? null).toBe(raw.get("content-type"));
+      expect(headers.get("missing")).toBe(null);
+      expect(headers.has("missing").unwrap()).toBe(false);
+      expect([...headers]).toEqual([...raw]);
+      expect([...headers.entries()]).toEqual([...raw.entries()]);
+      expect([...headers.keys()]).toEqual([...raw.keys()]);
+      expect([...headers.values()]).toEqual([...raw.values()]);
+      const entries: [string, string][] = [];
+      headers.forEach((value, key) => entries.push([key, value]));
+      expect(entries).toEqual([...raw]);
+      assertValue(headers.transform("entries", (h) => Object.fromEntries(h))["content-type"])
+        .toBe(raw.get("content-type"));
+    });
+  });
+
+  test("cloned responses keep header provenance and independent bodies", async () => {
+    await runInstrumented(scope, async () => {
+      const res = await fetch(url("/clone")) as unknown as WrappedResponse;
+      const clone = res.clone();
+      assertValue(clone.headers.get("content-type")).toBe("application/json;charset=utf-8");
+      expect(clone.unwrap()).not.toBe(res.unwrap());
+      expect((await clone.text()).unwrap()).toBe('{"value":42}');
+      expect((await res.json<{ value: number }>()).value.unwrap()).toBe(42);
+    });
+    const events = stopRecording();
+    expect(events).toMatchObject([
+      { kind: "http" },
+      { kind: "assertion", sourceSeq: events[0]!.seq, path: ["headers", "content-type"] },
+    ]);
+  });
+
   test("an HTTP fake records only the test's outer request", async () => {
     handler = (req) => {
       if (new URL(req.url).pathname === "/fake") {
@@ -142,6 +208,42 @@ describe("fetch execution scopes", () => {
     expect(stopRecording()).toEqual([]);
   }, 2_000);
 
+  test.each([
+    { contentType: "text/event-stream; charset=utf-8", captureBody: undefined },
+    { contentType: "text/plain", captureBody: false },
+  ])("instrumented streams return before closing: %j", async ({ contentType, captureBody }) => {
+    let controller!: ReadableStreamDefaultController<Uint8Array>;
+    handler = () => new Response(new ReadableStream<Uint8Array>({
+      start(c) {
+        controller = c;
+        c.enqueue(new TextEncoder().encode("first chunk"));
+      },
+    }), { headers: { "content-type": contentType } });
+    try {
+      await runInstrumented(scope, async () => {
+        const res = await (fetch as unknown as SpectestFetch)(url("/stream"), {
+          captureBody, signal: AbortSignal.timeout(1_000),
+        });
+        assertValue(res.bodyUsed).toBe(false);
+        const reader = res.body!.getReader();
+        try {
+          const chunk = await reader.read();
+          expect(chunk.done).toBe(false);
+          assertValue(chunk.value!.transform("text", (bytes) => new TextDecoder().decode(bytes)))
+            .toBe("first chunk");
+        } finally { reader.releaseLock(); }
+      });
+    } finally { controller?.close(); }
+    const events = stopRecording();
+    expect(events).toMatchObject([
+      { kind: "http", status: 200 },
+      { kind: "assertion", sourceSeq: events[0]!.seq, path: ["bodyUsed"] },
+      { kind: "assertion", sourceSeq: events[0]!.seq, path: ["body", "<read>", "0", "<text>"] },
+    ]);
+    if (events[0]?.kind !== "http") throw new Error("Missing HTTP event");
+    expect((events[0] as HttpEvent).responseBody).toBeUndefined();
+  }, 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;
@@ -241,6 +343,10 @@ describe("fetch execution scopes", () => {
       await runInstrumented(setup, async () => {
         const res = await fetch(url("/setup")) as unknown as WrappedResponse;
         expect(res.status.unwrap()).toBe(200);
+        expect(res.headers.get("content-type")?.unwrap()).toBe("application/json;charset=utf-8");
+        expect(readTag(res.headers.get("content-type"))).toEqual({
+          sourceSeq: undefined, path: ["headers", "content-type"],
+        });
         await runUninstrumented(async () => {
           expect((await fetch(url("/setup-fake"))).status).toBe(200);
         });

package/src/harness/fetch.ts

@@ -1,4 +1,4 @@
-import { wrapResponse, type WrappedResponse } from "../inspect.js";
+import { wrapResponse, type SpectestRequestInit, 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";
@@ -72,12 +72,11 @@ export function isTransportError(err: unknown): boolean {
 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.
+  // wrapper: its response properties and body readers return wrapped values.
   setRawFetch(original);
   const wrappedFn = async (
     input: Parameters<typeof fetch>[0],
-    init?: Parameters<typeof fetch>[1],
+    init?: SpectestRequestInit,
   ): Promise<Response | WrappedResponse> => {
     const scope = currentInstrumentationScope();
     if (!scope?.active) return original(input, init);
@@ -97,7 +96,11 @@ export function installFetchWrapper(): () => void {
       const contentType = res.headers.get("content-type");
       const contentLength = () => parseContentLength(res.headers.get("content-length"));
       const textual = isTextualContentType(contentType);
-      if (textual === false) {
+      const streaming = contentType?.split(";")[0]?.trim().toLowerCase() === "text/event-stream";
+      if (init?.captureBody === false || streaming) {
+        // Return on headers: an open-ended stream must not be drained (or
+        // cloned into an unbounded background buffer) by the recorder.
+      } else if (textual === false) {
         responseBody = omittedBody("binary", contentType, contentLength());
       } else {
         try {