@specific.dev/spectest 0.109.1 → 0.111.0

package/src/components/replayFake-websocket.test.ts

@@ -0,0 +1,264 @@
+import { afterEach, expect, test } from "bun:test";
+import { once } from "node:events";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import type { FakeContext, FakeWebSocket } from "../index.js";
+import { replayFake, type Cassette, type CassetteWebSocket, type WebSocketKey } from "./index.js";
+import { recordWebSocket, websocketMatcher } from "./replay-websocket.js";
+
+const require = createRequire(import.meta.url);
+const { WebSocketServer } = require(join(dirname(require.resolve("ws/package.json")), "index.js")) as typeof import("ws");
+const ctx = {} as FakeContext;
+const request = { method: "GET", path: "/live", query: {}, headers: {} };
+const cleanup: (() => void)[] = [];
+afterEach(() => { for (const fn of cleanup.splice(0).reverse()) fn(); });
+const tick = (ms = 15) => Bun.sleep(ms);
+const signature = (message: string | Uint8Array) => websocketMatcher()(message)!;
+function cassette(websockets: CassetteWebSocket[]): Cassette {
+  return { version: 1, fake: "voice", host: "voice.test", interactions: [], websockets };
+}
+async function harness<W>(recordings: CassetteWebSocket[], websocketKey?: WebSocketKey<W>, timeout = 1000) {
+  const fake = replayFake({ name: "voice", host: "voice.test", mode: "replay", websocketKey, websocketTimeoutMs: timeout });
+  const state = await fake.state!();
+  const helpers = await fake.helpers!({ name: "voice", state, ctx });
+  helpers.replay(cassette(recordings));
+  const dispose = () => { for (const session of state.websocketSessions) session.cancel(); };
+  cleanup.push(dispose);
+  async function connect(protocol?: string) {
+    const result = await fake.websocket!(new Request("https://voice.test/live", {
+      headers: { upgrade: "websocket", "sec-websocket-key": Math.random().toString(), ...(protocol ? { "sec-websocket-protocol": protocol } : {}) },
+    }), state, ctx);
+    if (result instanceof Response) throw new Error(await result.text());
+    const sent: (string | Uint8Array)[] = [];
+    const closes: { code?: number; reason?: string }[] = [];
+    const socket: FakeWebSocket = {
+      readyState: 1,
+      send(message) { sent.push(typeof message === "string" ? message : new Uint8Array(message)); },
+      close(code, reason) { closes.push({ code, reason }); },
+    };
+    await result.open?.(socket);
+    return { sent, closes, protocol: result.protocol,
+      message: (message: string | Uint8Array) => result.message?.(socket, message),
+      close: (code = 1000, reason = "") => result.close?.(socket, code, reason),
+    };
+  }
+  return { fake, state, helpers, connect, dispose };
+}
+
+test("default hashes type and complete payload; custom keys use canonical hashing", () => {
+  const match = websocketMatcher();
+  expect(match("audio")).not.toBe(match(new TextEncoder().encode("audio")));
+  expect(match("audio")).not.toBe(match("audio!"));
+  expect(websocketMatcher(() => ({ b: 2, a: 1 }))("x")).toBe(websocketMatcher(() => ({ a: 1, b: 2 }))("y"));
+  expect(websocketMatcher(() => [1, 2])("x")).not.toBe(websocketMatcher(() => [2, 1])("x"));
+  expect(websocketMatcher(() => new Uint8Array([1]))("x")).not.toBe(websocketMatcher(() => "\u0001")("x"));
+});
+
+test("barriers delay output; reception continues during playback; repeated keys consume in order", async () => {
+  const h = await harness([{ request, inputs: [signature("go"), signature("go"), signature("tool-result")], messages: [
+    { afterInput: 0, delayMs: 0, type: "text", data: "greeting" },
+    { afterInput: 1, delayMs: 60, type: "text", data: "first" },
+    { afterInput: 2, delayMs: 0, type: "binary", data: "AP8=" },
+    { afterInput: 3, delayMs: 0, type: "text", data: "tool-dependent" },
+  ], close: { afterInput: 3, delayMs: 2, initiator: "server", code: 4001, reason: "done" } }]);
+  const c = await h.connect();
+  await tick(); expect(c.sent).toEqual(["greeting"]);
+  await c.message("go"); await c.message("go");
+  await tick(); expect(c.sent).toEqual(["greeting"]);
+  await tick(70); expect(c.sent).toEqual(["greeting", "first", new Uint8Array([0, 255])]);
+  expect(h.state.websocketSessions.size).toBe(1);
+  await c.message("tool-result"); await tick();
+  expect(c.sent.at(-1)).toBe("tool-dependent");
+  expect(c.closes).toEqual([{ code: 4001, reason: "done" }]);
+  await c.close(4001, "done");
+  expect(h.state.websocketErrors).toEqual([]);
+  expect(h.state.websocketSessions.size).toBe(0);
+});
+
+test("connections consume handshake recordings in order and clone reducer state", async () => {
+  const key: WebSocketKey<{ seen: number }> = { initial: { seen: 0 }, reduce(state) {
+    state.seen++;
+    return { state, key: state.seen === 3 ? "turn" : null };
+  } };
+  const hash = websocketMatcher(() => "turn")("ignored")!;
+  const h = await harness(["one", "two"].map(data => ({ request, protocol: "voice", inputs: [hash], messages: [
+    { afterInput: 1, delayMs: 0, type: "text", data },
+  ] })), key);
+  const a = await h.connect("voice"), b = await h.connect("voice");
+  expect(a.protocol).toBe("voice");
+  await a.message("audio"); await a.message("audio"); await b.message("audio"); await a.message("audio");
+  await tick(); expect(a.sent).toEqual(["one"]); expect(b.sent).toEqual([]);
+  await b.message("audio"); await b.message("audio"); await tick(); expect(b.sent).toEqual(["two"]);
+  expect(key.initial.seen).toBe(0);
+  await a.close(); await b.close(); expect(h.state.websocketErrors).toEqual([]);
+  await expect(h.connect("voice")).rejects.toThrow("exhausted");
+});
+
+test("mixed HTTP and WebSocket cassette uses separate indexes and unchanged HTTP key", async () => {
+  const h = await harness([{ request, inputs: [], messages: [{ afterInput: 0, delayMs: 0, type: "text", data: "ws" }] }]);
+  const recording = h.helpers.dump();
+  recording.interactions.push({ request, response: { status: 200, headers: {}, body: "http", bodyEncoding: "utf8" } });
+  h.helpers.replay(recording);
+  const c = await h.connect();
+  expect(await (await h.fake.handler(new Request("https://voice.test/live"), h.state, ctx)).text()).toBe("http");
+  await tick(); expect(c.sent).toEqual(["ws"]); await c.close();
+  expect(h.state.websocketErrors).toEqual([]);
+  h.helpers.replay({ version: 1, fake: "voice", host: "voice.test", interactions: recording.interactions });
+  expect(await (await h.fake.handler(new Request("https://voice.test/live"), h.state, ctx)).text()).toBe("http");
+});
+
+test("mismatch signatures, missing input deadline, unexpected closure and cleanup are visible", async () => {
+  const r: CassetteWebSocket = { request, inputs: [signature("expected")], messages: [{ afterInput: 1, delayMs: 0, type: "text", data: "dependent" }] };
+  const mismatch = await harness([r]); const a = await mismatch.connect();
+  expect(() => a.message("actual")).toThrow(`expected ${signature("expected")}, actual ${signature("actual")}`);
+  expect(mismatch.state.websocketErrors.join("\n")).toContain("connection #1");
+  const missing = await harness([r], undefined, 20); const b = await missing.connect();
+  await tick(40); expect(b.sent).toEqual([]); expect(b.closes[0].code).toBe(1011);
+  expect(missing.state.websocketErrors.join("\n")).toContain("required input never arrived");
+  const early = await harness([r]); const c = await early.connect(); await c.close();
+  expect(early.state.websocketErrors.join("\n")).toContain("required input never arrived");
+  const cancel = await harness([{ request, inputs: [], messages: [{ afterInput: 0, delayMs: 30, type: "text", data: "late" }] }]);
+  const d = await cancel.connect(); cancel.dispose(); await tick(50);
+  expect(d.sent).toEqual([]); expect(cancel.state.websocketSessions.size).toBe(0);
+});
+
+test("invalid and async matchers fail synchronously", () => {
+  for (const key of [async () => "x", () => undefined, { initial: 0, reduce: async () => ({ state: 1, key: "x" }) }, { initial: 0, reduce: () => ({ key: null }) }]) {
+    expect(() => websocketMatcher(key as any)("input")).toThrow();
+  }
+  expect(() => replayFake({ name: "bad", host: "voice.test", websocketKey: {} as any })).toThrow("websocketKey");
+});
+
+test("cassette validation is atomic and rejects impossible dependencies", async () => {
+  const h = await harness([{ request, inputs: [], messages: [] }]);
+  expect(() => h.helpers.replay(cassette([{ request, inputs: [], messages: [{ type: "text", data: "bad", afterInput: 1, delayMs: 0 }] }]))).toThrow("dependency");
+  const c = await h.connect(); await c.close(); expect(h.state.websocketErrors).toEqual([]);
+});
+
+test("real recording transport collapses 500 audio messages, preserves output types and closure, then replays", async () => {
+  const server = new WebSocketServer({ port: 0, host: "127.0.0.1", handleProtocols: () => "voice" });
+  await once(server, "listening");
+  cleanup.push(() => { for (const c of server.clients) c.terminate(); server.close(); });
+  let incoming = 0;
+  server.on("connection", ws => {
+    ws.send("greeting secret");
+    ws.on("message", (data, binary) => {
+      expect(new Uint8Array(data as Buffer)).toEqual(new Uint8Array([12, 34, 56, 78]));
+      incoming++;
+      expect(binary).toBe(true);
+      if (incoming === 500) { ws.send(new Uint8Array([0, 255, 128])); ws.close(4001, "done"); }
+    });
+  });
+  const key: WebSocketKey<{ count: number }> = { initial: { count: 0 }, reduce(state, message) {
+    if (message instanceof Uint8Array) message[0] = 255; // Must not change forwarding.
+    return { state: { count: state.count + 1 }, key: state.count === 499 ? "caller-turn" : null };
+  } };
+  let recorded: CassetteWebSocket | undefined;
+  let done!: () => void;
+  const closed = new Promise<void>(resolve => done = resolve);
+  const errors: Error[] = [];
+  const r = await recordWebSocket({
+    url: `ws://voice.test:${(server.address() as { port: number }).port}/live`, ip: "127.0.0.1", host: "voice.test", headers: {}, protocols: ["voice"], request,
+    match: websocketMatcher(key), redact: s => s.replaceAll("secret", "<REDACTED>"), secrets: [{ ref: "TOKEN", value: "secret" }], label: "voice connection #1",
+    captured: record => recorded = record,
+    finished(_session, error) { if (error) errors.push(error); done(); },
+  });
+  cleanup.push(() => r.session.cancel());
+  const outputs: (string | Uint8Array | ArrayBuffer)[] = [];
+  const socket: FakeWebSocket = { readyState: 1, send: value => { outputs.push(value); }, close() {} };
+  await r.handlers.open!(socket);
+  for (let i = 0; i < 500; i++) await r.handlers.message!(socket, new Uint8Array([12, 34, 56, 78]));
+  await closed;
+  expect(errors).toEqual([]); expect(incoming).toBe(500);
+  expect(outputs).toEqual(["greeting secret", new Uint8Array([0, 255, 128])]);
+  expect(recorded!.inputs).toHaveLength(1); expect(recorded!.protocol).toBe("voice");
+  expect(recorded!.messages[0]).toMatchObject({ afterInput: 0, data: "greeting <REDACTED>" });
+  expect(recorded!.messages[1]).toMatchObject({ afterInput: 1, type: "binary" });
+  expect(recorded!.close).toMatchObject({ initiator: "server", code: 4001 });
+  expect(JSON.stringify(recorded)).not.toContain("12,34");
+  expect(JSON.stringify(recorded)).not.toContain("secret");
+  expect(JSON.stringify(recorded).length).toBeLessThan(1200);
+  const h = await harness([recorded!], key); const c = await h.connect("voice");
+  for (let i = 0; i < 500; i++) await c.message(new Uint8Array([12, 34, 56, 78]));
+  await tick(60);
+  expect(c.sent).toEqual(["greeting <REDACTED>", new Uint8Array([0, 255, 128])]);
+  await c.close(4001, "done"); expect(h.state.websocketErrors).toEqual([]);
+});
+
+// Compiled by the existing public API typecheck test.
+export function inferredReducer() {
+  return replayFake({ name: "inferred", host: "voice.test", state: () => ({ counter: 0 }),
+    websocketKey: { initial: { heardAudio: false, quietMessages: 0 }, reduce(state, message) {
+      const count: number = state.quietMessages;
+      const heard: boolean = state.heardAudio;
+      const payload: string | Uint8Array = message;
+      // @ts-expect-error reducer state must be inferred from initial
+      const wrong: string = state.quietMessages;
+      return { state: { heardAudio: heard, quietMessages: count + 1 }, key: payload };
+    } },
+  });
+}
+
+test("quiet-message example ignores leading quiet, resets on speech, and keys each control event", async () => {
+  const { quietMessageKey } = await import("../../../examples/replay-fake/spectest/quiet-message-key.js");
+  const match = websocketMatcher(quietMessageKey(3));
+  const audio = (bytes: number[]) => JSON.stringify({ type: "session.input_audio.append", audio: Buffer.from(bytes).toString("base64") });
+  for (let i = 0; i < 10; i++) expect(match(audio([0, 0]))).toBeNull();
+  for (let i = 0; i < 500; i++) expect(match(audio([1, 0]))).toBeNull();
+  expect(match(audio([0, 0]))).toBeNull(); expect(match(audio([0, 0]))).toBeNull();
+  expect(match(audio([1, 0]))).toBeNull();
+  expect(match(audio([0, 0]))).toBeNull(); expect(match(audio([0, 0]))).toBeNull();
+  expect(match(audio([0, 0]))).toBe(websocketMatcher(() => ({ type: "caller-turn" }))(""));
+  expect(match(audio([0, 0]))).toBeNull();
+  expect(match(JSON.stringify({ type: "tool.result", content: "done", event_id: "old" }))).toBe(match(JSON.stringify({ event_id: "new", content: "done", type: "tool.result" })));
+  expect(match(JSON.stringify({ type: "continuation" }))).not.toBeNull();
+  expect(() => match(audio([]))).toThrow("complete PCM16");
+});
+
+test("server close acknowledgments may omit the reason while client close reasons must match", async () => {
+  const h = await harness([{ request, inputs: [], messages: [], close: { initiator: "server", code: 1000, reason: "complete", afterInput: 0, delayMs: 0 } }]);
+  const c = await h.connect();
+  await tick();
+  expect(c.closes).toEqual([{ code: 1000, reason: "complete" }]);
+  await c.close(1000, "");
+  expect(h.state.websocketErrors).toEqual([]);
+  expect(h.state.websocketSessions.size).toBe(0);
+  const client = await harness([{ request, inputs: [], messages: [], close: { initiator: "client", code: 1000, reason: "complete", afterInput: 0, delayMs: 0 } }]);
+  const peer = await client.connect();
+  await peer.close(1000, "");
+  expect(client.state.websocketErrors.join("\n")).toContain('expected reason "complete", actual ""');
+});
+
+test("mismatched close and input exhaustion remain errors; cleanup cancels missing-input deadline", async () => {
+  const h = await harness([{ request, inputs: [], messages: [], close: { initiator: "client", code: 4000, reason: "expected", afterInput: 0, delayMs: 0 } }]);
+  const c = await h.connect(); await c.close(4001, "different");
+  expect(h.state.websocketErrors.join("\n")).toContain("unexpected connection closure");
+  const exhausted = await harness([{ request, inputs: [], messages: [] }]); const a = await exhausted.connect();
+  expect(() => a.message("extra")).toThrow("<exhausted>");
+  const pending = await harness([{ request, inputs: [signature("go")], messages: [] }], undefined, 20);
+  await pending.connect(); pending.dispose(); await tick(40);
+  expect(pending.state.websocketErrors).toEqual([]);
+});
+
+
+test("malformed outputs and closure dependencies are rejected before consumption", async () => {
+  const h = await harness([{ request, inputs: [], messages: [] }]);
+  for (const message of [null, { afterInput: 0, delayMs: 0 }, { type: "binary", data: "!", afterInput: 0, delayMs: 0 }]) {
+    expect(() => h.helpers.replay(cassette([{ request, inputs: [], messages: [message as any] }]))).toThrow();
+  }
+  expect(() => h.helpers.replay(cassette([{ request, inputs: [signature("late")], messages: [], close: {
+    afterInput: 0, delayMs: 0, initiator: "server", code: 1000, reason: "",
+  } }]))).toThrow("closure");
+  const c = await h.connect(); await c.close(); expect(h.state.websocketErrors).toEqual([]);
+});
+
+test("an abandoned handshake cancels the connection before open", async () => {
+  const h = await harness([{ request, inputs: [signature("go")], messages: [] }]);
+  const controller = new AbortController();
+  const handlers = await h.fake.websocket!(new Request("https://voice.test/live", { signal: controller.signal }), h.state, ctx);
+  expect(handlers).not.toBeInstanceOf(Response);
+  expect(h.state.websocketSessions.size).toBe(1);
+  controller.abort();
+  expect(h.state.websocketSessions.size).toBe(0);
+  expect(h.state.websocketErrors).toEqual([]);
+});

package/src/components/replayFake.ts

@@ -31,10 +31,9 @@
 // with our in-VM-CA leaf; the upstream leg is a genuine public-cert TLS
 // handshake to the real host.
 //
-// Mode is chosen by `isRecording()`: it is true only inside an active
-// recorder (a `spectest test` case), false in eval/manual. So `auto`
-// (the default) replays under test and records during manual use — no new
-// control-plane mode flag. `mode: "record" | "replay"` overrides it.
+// Mode belongs to the environment, not the per-case event recorder. Tests
+// and shared baselines always replay, including startup and between cases.
+// Interactive environments record unless `mode: "replay"` is requested.
 // An optional custom handler can return scripted responses or explicitly
 // delegate with ctx.replay(request). Only delegated traffic uses this engine.
 //
@@ -65,8 +64,15 @@ import { brotliDecompressSync, gunzipSync, inflateSync } from "node:zlib";
 import * as dnsPacket from "dns-packet";
 
 import type { FakeContext, FakeDefinition } from "../index.js";
-import { isRecording } from "../recorder.js";
+import { resolveReplayMode } from "../replay-mode.js";
+import { getWebSocketLifetime } from "../harness/fake-websocket-lifetime.js";
+import { reportBackgroundFailure } from "../harness/background-failures.js";
 import { getRecordSecret } from "../record-secrets.js";
+import {
+  recordWebSocket, replayWebSocket, validateWebSocketKey, validateWebSocketRecording,
+  websocketMatcher, type WebSocketKey, type CassetteWebSocket, type WebSocketSession,
+} from "./replay-websocket.js";
+export type { WebSocketKey, ReplayWebSocketMessage, CassetteWebSocket, CassetteWebSocketMessage, WebSocketTiming } from "./replay-websocket.js";
 import { replaySignature, type ReplayKey } from "./replay-key.js";
 export type { JsonValue, MatchKey, ReplayRequest, ReplayKey } from "./replay-key.js";
 import {
@@ -152,6 +158,7 @@ export type ReplayHandler<S> = (
 export interface ReplayFakeOptions<
   S = undefined,
   H extends Record<string, unknown> = {},
+  W = unknown,
 > {
   /** Stable name — the `ctx.fakes` key. */
   name: string;
@@ -169,6 +176,13 @@ export interface ReplayFakeOptions<
    *  bytes; objects compare independently of property order. No implicit
    *  matching dimensions or fallback apply when a key is supplied. */
   key?: ReplayKey;
+  /** Complete messages (string or Uint8Array), synchronously reduced per connection.
+   * Return null to emit no input. Raw inputs are never stored; changing this
+   * matcher can require re-recording. Defaults to SHA-256(type + bytes). */
+  websocketKey?: WebSocketKey<W>;
+  /** Maximum wait for each required input key; null-producing messages do not
+   * extend it. Defaults to 30 seconds. */
+  websocketTimeoutMs?: number;
   /** Per-fake credential brokering. Rules are evaluated in
    *  order; the first whose `match` matches wins (a rule without `match`
    *  matches everything and shadows later rules). Applied at the
@@ -184,8 +198,9 @@ export interface ReplayFakeOptions<
   /** Extra substrings/patterns to scrub from stored request/response
    *  bodies and queries (every injected secret value is always scrubbed). */
   redactPatterns?: (string | RegExp)[];
-  /** `"auto"` (default) records under eval and replays under test;
-   *  `"record"` / `"replay"` force a mode. */
+  /** `"auto"` (default) records in interactive environments and replays in
+   *  tests. `"replay"` always replays; `"record"` requires an interactive
+   *  environment. Test environments always replay, even between cases. */
   mode?: "auto" | "record" | "replay";
   /** Custom state, with the same lifecycle as a normal fake's state. Kept
    *  separate from cassette internals; helpers and handler see only S. */
@@ -233,6 +248,7 @@ export interface Cassette {
   /** The real host this cassette mirrors (e.g. `api.stripe.com`). */
   host: string;
   interactions: CassetteInteraction[];
+  websockets?: CassetteWebSocket[];
 }
 
 /** Forked-per-test state for one replay fake. */
@@ -245,6 +261,11 @@ export interface CassetteState {
   /** Interactions captured this record session. */
   recorded: CassetteInteraction[];
   dirty: boolean;
+  websocketIndex: Map<string, number[]>;
+  websocketCursor: Map<string, number>;
+  recordedWebSockets: CassetteWebSocket[];
+  websocketSessions: Set<WebSocketSession>;
+  websocketErrors: string[];
 }
 
 /** What `replay(...)` returns — a small summary that surfaces in the test
@@ -257,6 +278,7 @@ export interface ReplaySummary {
   host: string;
   /** Number of interactions now available for replay. */
   interactions: number;
+  websockets?: number;
 }
 
 export interface ReplayHelpers extends Record<string, unknown> {
@@ -382,6 +404,7 @@ function coerceCassette(parsed: Cassette, name: string, host: string): Cassette
     fake: parsed.fake ?? name,
     host: parsed.host ?? host,
     interactions: structuredClone(parsed.interactions),
+    ...(parsed.websockets !== undefined ? { websockets: structuredClone(parsed.websockets) } : {}),
   };
 }
 
@@ -658,8 +681,8 @@ function forwardToRealUpstream(args: {
 // replayFake
 // ────────────────────────────────────────────────────────────────────────
 
-export function replayFake<S = undefined, H extends Record<string, unknown> = {}>(
-  opts: ReplayFakeOptions<S, H>,
+export function replayFake<S = undefined, H extends Record<string, unknown> = {}, W = unknown>(
+  opts: ReplayFakeOptions<S, H, W>,
 ): FakeDefinition<CassetteState & { custom: S }, ReplayHelpers & H> {
   if (!opts.name) throw new Error("replayFake: `name` is required");
   if (!opts.host || typeof opts.host !== "string") {
@@ -672,17 +695,18 @@ export function replayFake<S = undefined, H extends Record<string, unknown> = {}
   if (opts.key !== undefined && typeof opts.key !== "function") {
     throw new Error(`replayFake(${opts.name}): \`key\` must be a synchronous function`);
   }
+  validateWebSocketKey(opts.websocketKey);
+  const websocketTimeoutMs = opts.websocketTimeoutMs ?? 30_000;
+  if (!Number.isFinite(websocketTimeoutMs) || websocketTimeoutMs <= 0 || websocketTimeoutMs > 2_147_483_647) {
+    throw new Error(`replayFake(${opts.name}): websocketTimeoutMs must be positive and at most 2147483647`);
+  }
   const injectRules = opts.inject ?? [];
   // Refs every header template references — the control plane resolves these
   // server-side and pushes them for the environment lifetime (see the daemon's
   // /record-secret-refs endpoint, which reads `def.secretRefs`).
   const secretRefs = collectSecretRefs(injectRules, opts.sign);
 
-  const resolveMode = (): "record" | "replay" => {
-    if (opts.mode === "record") return "record";
-    if (opts.mode === "replay") return "replay";
-    return isRecording() ? "replay" : "record";
-  };
+  const resolveMode = () => resolveReplayMode(opts.mode);
 
   // ── REPLAY ──────────────────────────────────────────────────────────
   function signature(request: CassetteRequest, location: string): string {
@@ -974,6 +998,74 @@ export function replayFake<S = undefined, H extends Record<string, unknown> = {}
     return record(req, url, reqLike, bodyBytes, state);
   };
 
+  const websocket: NonNullable<FakeDefinition<CassetteState>["websocket"]> = async (req, state) => {
+    const url = new URL(req.url);
+    const request: CassetteRequest = {
+      method: req.method.toUpperCase(), path: url.pathname,
+      query: normalizeQuery(url.searchParams, opts.sign !== undefined),
+      headers: recordable(req.headers, [...req.headers.keys()].filter(k => !["sec-websocket-key", "sec-websocket-accept"].includes(k))),
+    };
+    const sig = signature(request, "WebSocket handshake");
+    const match = websocketMatcher(opts.websocketKey);
+    const lifetime = getWebSocketLifetime(req);
+    const track = (session: WebSocketSession) => {
+      if (!lifetime.ended) state.websocketSessions.add(session);
+    };
+    const finished = (session: WebSocketSession, error?: Error) => {
+      state.websocketSessions.delete(session);
+      if (error) { state.websocketErrors.push(error.message); reportBackgroundFailure(error); }
+    };
+    const offered = (req.headers.get("sec-websocket-protocol") ?? "").split(",").map(p => p.trim()).filter(Boolean);
+    if (resolveMode() === "replay") {
+      const position = state.websocketCursor.get(sig) ?? 0;
+      const index = state.websocketIndex.get(sig)?.[position];
+      const label = `replayFake(${opts.name}) WebSocket ${sig} connection #${position + 1}`;
+      if (index === undefined) {
+        const error = `${label}: no recording available (handshake unmatched or exhausted)`;
+        state.websocketErrors.push(error);
+        reportBackgroundFailure(new Error(error));
+        return new Response(error, { status: 599 });
+      }
+      const recording = state.cassette.websockets![index];
+      if (recording.protocol && !offered.includes(recording.protocol)) {
+        throw new Error(`${label}: client did not offer recorded subprotocol`);
+      }
+      const { handlers, session } = replayWebSocket({ recording, match, label, timeoutMs: websocketTimeoutMs, lifetime, finished });
+      state.websocketCursor.set(sig, position + 1);
+      track(session);
+      return handlers;
+    }
+    if (opts.sign) throw new Error(`replayFake(${opts.name}): SigV4 WebSocket signing is not supported`);
+    const rule = injectRules.find(r => ruleMatches(r.match, {
+      method: request.method, path: request.path, query: url.searchParams, headers: req.headers,
+    }));
+    const brokered = rule ? brokerHeaders(rule) : { headers: {}, secrets: [], missing: [] };
+    if (brokered.missing.length) throw new Error(`replayFake(${opts.name}): missing WebSocket secrets ${brokered.missing.join(", ")}`);
+    const redact = makeRedactor(brokered.secrets, opts.redactPatterns);
+    const storedRequest: CassetteRequest = {
+      ...request,
+      query: Object.fromEntries(Object.entries(request.query).map(([k, v]) => [k, v.map(redact)])),
+      headers: Object.fromEntries(Object.entries(request.headers).map(([k, v]) => [k, redact(v)])),
+    };
+    for (const { ref, value } of brokered.secrets) if (value && JSON.stringify(storedRequest).includes(value)) throw new Error(`replayFake(${opts.name}): secret ${ref} survived WebSocket handshake redaction`);
+    const ips = await resolveExternalA(new URL(`https://${host}`).hostname);
+    if (!ips.length) throw new Error(`replayFake(${opts.name}): could not resolve real upstream ${host}`);
+    const headers: Record<string, string> = {};
+    req.headers.forEach((v, k) => {
+      if (!STRIP_FORWARD_HEADERS.has(k) && !k.startsWith("sec-websocket-")) headers[k] = v;
+    });
+    Object.assign(headers, brokered.headers);
+    const { handlers, session } = await recordWebSocket({
+      url: `wss://${host}${url.pathname}${url.search}`, ip: ips[0], host, headers, protocols: offered,
+      request: storedRequest, match, redact, secrets: brokered.secrets,
+      label: `replayFake(${opts.name}) WebSocket ${sig} connection #${state.recordedWebSockets.length + 1}`,
+      captured(recording) { state.recordedWebSockets.push(recording); state.dirty = true; },
+      lifetime, finished,
+    });
+    track(session);
+    return handlers;
+  };
+
   const replayHelpers = (state: CassetteState): ReplayHelpers => ({
     replay(file: string | Cassette): ReplaySummary {
       let loaded: Cassette;
@@ -999,12 +1091,24 @@ export function replayFake<S = undefined, H extends Record<string, unknown> = {}
         if (queue) queue.push(i);
         else index.set(sig, [i]);
       }
+      const websocketIndex = new Map<string, number[]>();
+      if (loaded.websockets !== undefined && !Array.isArray(loaded.websockets)) throw new Error("cassette websockets must be an array");
+      for (const [i, recording] of (loaded.websockets ?? []).entries()) {
+        validateWebSocketRecording(recording);
+        const sig = signature(recording.request, `WebSocket connection #${i + 1}`);
+        const queue = websocketIndex.get(sig);
+        if (queue) queue.push(i); else websocketIndex.set(sig, [i]);
+      }
+      if (state.websocketSessions.size) throw new Error("close active WebSockets before loading a cassette");
+      state.websocketIndex = websocketIndex;
+      state.websocketCursor = new Map();
+      state.websocketErrors = [];
       // Mutate the live state object (the handler reads the same
       // reference); reset the cursor so replay starts from the top.
       state.cassette = loaded;
       state.index = index;
       state.cursor = new Map();
-      return { cassette: label, host: loaded.host, interactions: loaded.interactions.length };
+      return { cassette: label, host: loaded.host, interactions: loaded.interactions.length, ...(loaded.websockets ? { websockets: loaded.websockets.length } : {}) };
     },
     dump(): Cassette {
       return structuredClone({
@@ -1012,6 +1116,9 @@ export function replayFake<S = undefined, H extends Record<string, unknown> = {}
         fake: opts.name,
         host,
         interactions: [...state.cassette.interactions, ...state.recorded],
+        ...((state.cassette.websockets?.length || state.recordedWebSockets.length) ? {
+          websockets: [...(state.cassette.websockets ?? []), ...state.recordedWebSockets],
+        } : {}),
       });
     },
     recorded(): CassetteInteraction[] {
@@ -1028,6 +1135,8 @@ export function replayFake<S = undefined, H extends Record<string, unknown> = {}
     cursor: new Map(),
     recorded: [],
     dirty: false,
+    websocketIndex: new Map(), websocketCursor: new Map(), recordedWebSockets: [],
+    websocketSessions: new Set(), websocketErrors: [],
     custom,
   });
 
@@ -1035,6 +1144,7 @@ export function replayFake<S = undefined, H extends Record<string, unknown> = {}
     name: opts.name,
     hostnames: [host],
     secretRefs,
+    websocket,
     state: () => opts.state
       ? Promise.resolve(opts.state()).then(initialState)
       : initialState(undefined as S),

package/src/daemon.ts

@@ -1,3 +1,4 @@
+import { runWithBackgroundFailures } from "./harness/background-failures.js";
 import { generateHostCert as mintHostCert } from "./harness/certificate.js";
 import { componentBuildTasks, COMPONENT_RUNTIME } from "./harness/component-images.js";
 import { waitForAll } from "./harness/concurrency.js";
@@ -217,6 +218,7 @@ import {
 import { readRaw, wrap } from "./inspect.js";
 import type { Wrapped } from "./inspect.js";
 import { setRecordSecrets } from "./record-secrets.js";
+import { setReplayEnvironmentMode } from "./replay-mode.js";
 import { generateId } from "./ids.js";
 import { encodeReplayBundle, replayChunk } from "./replay-bundle.js";
 
@@ -3479,7 +3481,7 @@ let interactiveSetupCompleted = false;
 
 /**
  * Run a project setup hook. Normal `setup` runs before the shared warm
- * snapshot; `setupInteractive` runs only after it, in a fresh user start.
+ * snapshot; `interactive.seed` runs only after it, in a fresh user start.
  * Both use the same context and boot-log capture.
  *
  * Unlike test runs, this is NOT instrumented — no recorder, no event
@@ -3498,7 +3500,8 @@ async function runProjectSetup(hook: "setup" | "setupInteractive" = "setup"): Pr
 }
 
 async function runProjectSetupInner(hook: "setup" | "setupInteractive"): Promise<ProjectSetupResult> {
-  const setup = requireLoaded().project[hook];
+  const project = requireLoaded().project;
+  const setup = hook === "setup" ? project.setup : project.interactive?.seed;
   if (!setup || (hook === "setupInteractive" && interactiveSetupCompleted)) {
     return { ran: false, durationMs: 0 };
   }
@@ -5396,10 +5399,10 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
   // drains) so we hoist these out of the try/catch.
   let outcome: { status: "passed" | "failed"; error?: RunResult["error"] } = { status: "passed" };
   try {
-    const value = await Promise.race([
+    const value = await runWithBackgroundFailures(() => Promise.race([
       Promise.resolve(runInstrumented(fetchScope, async () => { await nativeAndroid.begin(Object.values(base.svc).filter(isAndroidApp)); return testCase.run(ctx); })),
       timedOut,
-    ]);
+    ]));
     // Stash the return value so child cases — which fork from the snapshot
     // we're about to capture — can read it off ctx.parent.
     TEST_DATA.set(testCase.id, value);
@@ -6159,7 +6162,8 @@ export function harnessMethods(state: RouteState): MethodTable {
       capabilities: ["prepared-images-v1"],
       // Optional discovery: old SDKs omit this field and are never sent the
       // new method. Check the loaded project, including after warm restore.
-      setupInteractive: typeof loaded?.project.setupInteractive === "function",
+      setupInteractive: typeof loaded?.project.interactive?.seed === "function",
+      replayEnvironmentMode: true,
     }),
 
     // Live bootstrap progress, polled by the control plane during
@@ -6269,6 +6273,17 @@ export function harnessMethods(state: RouteState): MethodTable {
       return { refs: [...refs], environmentScoped: true };
     },
 
+    setReplayEnvironmentMode: async (params) => {
+      if (params.mode !== "test" && params.mode !== "interactive") {
+        throw badRequest("mode must be test or interactive");
+      }
+      if (state.inFlightTest || state.inFlightBootstrap || state.inFlightProjectSetup) {
+        throw conflict("cannot change replay mode while work is in progress");
+      }
+      setReplayEnvironmentMode(params.mode);
+      return { ok: true };
+    },
+
     setRecordSecrets: async (params) => {
       configureSecrets(params);
       return { ok: true };
@@ -6364,6 +6379,8 @@ export function harnessMethods(state: RouteState): MethodTable {
       const tc = requireLoaded().byId.get(caseId);
       if (!tc) throw notFound(`unknown caseId: ${caseId}`);
       return exclusive(state, "inFlightTest", "another test is already running", async () => {
+        // A manually invoked case also stays in replay after its recorder stops.
+        setReplayEnvironmentMode("test");
         const result = await runOne(tc);
         // Recordings go out-of-band: encode and park the bundle, reply with
         // a size ref only. A bundle-encoding failure drops the recordings

package/src/fake-websocket.ts

@@ -3,6 +3,8 @@ export interface FakeWebSocket {
   readonly readyState: number;
   send(message: string | Uint8Array | ArrayBuffer): void;
   close(code?: number, reason?: string): void;
+  /** Abrupt transport closure (no close frame), used for recorded disconnects. */
+  terminate?(): void;
 }
 
 /** Returned by a fake's websocket handshake callback to accept a connection.

package/src/harness/background-failures.ts

@@ -0,0 +1,19 @@
+// The harness runs one test at a time. Transport callbacks run outside the
+// test's async stack, so report their failures through its existing race.
+let rejectActiveTest: ((error: Error) => void) | undefined;
+
+export function reportBackgroundFailure(error: unknown): void {
+  const failure = error instanceof Error ? error : new Error(String(error));
+  console.error("[spectest] background callback failed:", failure);
+  rejectActiveTest?.(failure);
+}
+
+export async function runWithBackgroundFailures<T>(run: () => Promise<T>): Promise<T> {
+  if (rejectActiveTest) throw new Error("A test is already handling background failures");
+  const failed = new Promise<never>((_resolve, reject) => { rejectActiveTest = reject; });
+  try {
+    return await Promise.race([failed, Promise.resolve().then(run)]);
+  } finally {
+    rejectActiveTest = undefined;
+  }
+}