@intentic/sandbox-contract 1.245.0 → 1.247.0

package/src/model-roles.ts

@@ -0,0 +1,224 @@
+import { z } from "zod";
+
+/* EVERY JOB IN THIS SANDBOX THAT PICKS A MODEL, LISTED BY THE JOB IT IS, one row per answer the owner is
+ * entitled to give differently.
+ *
+ * WHAT THIS REPLACED, and why it had to go. Model settings used to be grouped by how HARD the work was assumed
+ * to be: a "quick model" for the small automatic jobs, an "agent runs" tier for the big ones. Both names
+ * described an intensity rather than a job, and an intensity is a guess somebody else made about work the owner
+ * knows better. A commit message written by a frontier model is not a mistake, it is a preference, and the
+ * grouping made it unsayable: pinning Opus to get better commit subjects also pinned it to session titles, to
+ * every loop verdict, and to the safety judge. One bundled row could not say the thing anyone actually wanted
+ * to say.
+ *
+ * SO THE UNIT IS THE ROLE. Each entry here is one place a model gets chosen, and each gets its own ordered list
+ * in settings.modelRoles. Seventeen rows is more than four, and that is the point rather than a cost being
+ * absorbed: the configuration and the UI both already existed per use-case, and collapsing them was the only
+ * thing standing between the owner and a choice the machinery could already honour. A simpler face over this
+ * (presets: "cheap everywhere", "frontier everywhere") is a thing that can be built ON TOP of a true model, and
+ * cannot be unpicked from a lossy one.
+ *
+ * EVERY LIST IS AN ORDERED LADDER, whatever the role, and for one reason: the interesting failure of a pinned
+ * model is not that it is wrong, it is that it is CONNECTED AND WILL NOT ANSWER TODAY. The account's allowance
+ * went on the chat this morning, and one spent provider takes the role down for hours while three others sit
+ * idle. Written in order, the next entry catches it.
+ *
+ * TWO KINDS, and the only thing that separates them is what an EMPTY list means. That is a real fork rather
+ * than a leftover of the old grouping, and it is declared per role because it is a property of the job:
+ *
+ *   helper — a one-shot. One prompt, no tools, one string back, and it is over. An empty list resolves to the
+ *            AUTO LADDER: every connected provider's cheapest row, best-first (model-pins.ts). Deriving is the
+ *            right default here because the job is small and repeatable, so the cost of a wrong guess is one
+ *            cheap call, and because a derived answer improves by itself when an account is connected tomorrow.
+ *
+ *   run    — a whole session with tools and a worktree, started by a surface rather than by a person at a
+ *            composer. An empty list resolves to NOTHING, and the caller's own floor answers: the model the
+ *            owner picked for their chat. Nothing here can judge whether a job is worth the frontier tier, and
+ *            a wrong guess is billed in whole sessions rather than in tokens, so the honest fallback is a
+ *            choice they made rather than one this table invented.
+ *
+ * EVERY ENTRY IS A FULL PIN (ModelPinSchema): which model, and how it runs — effort, thinking, speed, harness.
+ * The helper roles carry them too, which they did not use to: a one-shot ran with reasoning forcibly off, so
+ * pinning a reasoning model to commit messages bought the price of one and the behaviour of neither. The knobs
+ * now ride through the one-shot path (the daemon's role-model.ts), so an entry means what it says wherever it
+ * is written.
+ *
+ * ADDING A ROLE IS ONE ROW HERE. The settings key, the resolver's floor, the daemon's lookup and the settings
+ * page's row all read this table, so a job that starts picking a model tomorrow becomes configurable by saying
+ * what it is. That is the property the old grouping cost: a new surface inherited "agent runs" by being
+ * unattended, which is how a documentation sweep and a production incident came to share one tier. */
+
+export const ModelRoleKindSchema = z.enum(["helper", "run"]);
+export type ModelRoleKind = z.infer<typeof ModelRoleKindSchema>;
+
+/* The shape of a row. `id` is a bare string HERE and narrowed on the exported type below, because the id union
+ * is derived from this very table: a self-referential `satisfies` would be a type that has to know its own
+ * answer before it can check it. */
+interface ModelRoleRow {
+    readonly id: string;
+    // What the settings row is called. A JOB, in the owner's words, never a tier.
+    readonly label: string;
+    // The row's one line: what this model is asked to do. Read beside the label, so it says what the label
+    // cannot rather than restating it.
+    readonly blurb: string;
+    readonly kind: ModelRoleKind;
+    // The row's glyph, from the shared icon set. Here rather than in a web-side map because the whole value of
+    // this table is that a role is declared ONCE; a second table keyed by the same ids is the drift this
+    // replaced, moved one layer up.
+    readonly icon: string;
+}
+
+/* THE TABLE. Ordered as the settings page draws it, and the order is an argument about reach: the one-shots
+ * first, because nobody chose a model for them and they run constantly; then the runs somebody's click starts;
+ * then the runs that start themselves, which are the ones an owner is least likely to be watching and most
+ * likely to want held to a budget.
+ *
+ * The ids are the wire vocabulary: a turn carries one (AgentTurn.runRole), so they are kebab-case and stable,
+ * and renaming one is a breaking change to the setting rather than a cosmetic edit. */
+export const MODEL_ROLES = [
+    {
+        id: "commit-message",
+        label: "Commit messages",
+        blurb: "The subject written when an agent's work lands, and the release note under it.",
+        kind: "helper",
+        icon: "file-edit",
+    },
+    {
+        id: "session-title",
+        label: "Session titles",
+        blurb: "The name a conversation wears on the board, written a second into its first turn.",
+        kind: "helper",
+        icon: "pencil",
+    },
+    {
+        /* THE ONE HELPER WHOSE INPUT IS ADVERSARIAL, and the reason the old bundling was worst here. Its prompt
+         * contains a command the agent is about to run, which may have arrived from a stranger's web page, and a
+         * small model can be talked round by it. Being wrong is expensive in both directions: a needless card
+         * teaches the owner to click through the next one. */
+        id: "safety-judge",
+        label: "Safety judge",
+        blurb: "Which model reads your safety policy before a flagged command runs.",
+        kind: "helper",
+        icon: "shield",
+    },
+    {
+        id: "loop-verdict",
+        label: "Loop verdicts",
+        blurb: "Whether a loop's iteration met the goal, or the loop goes round again.",
+        kind: "helper",
+        icon: "check-square",
+    },
+    {
+        id: "pipeline-fix",
+        label: "Pipeline fixes",
+        blurb: "The agent started by Fix on a red pipeline.",
+        kind: "run",
+        icon: "wave-pulse",
+    },
+    {
+        id: "deployment-fix",
+        label: "Deployment fixes",
+        blurb: "The agent started by Fix on a deployment that is down.",
+        kind: "run",
+        icon: "server",
+    },
+    {
+        id: "maintenance-chore",
+        label: "Maintenance chores",
+        blurb: "A chore run started from the Maintenance board.",
+        kind: "run",
+        icon: "wrench",
+    },
+    {
+        id: "documentation-run",
+        label: "Documentation runs",
+        blurb: "A pass over a repo's own documentation.",
+        kind: "run",
+        icon: "book",
+    },
+    {
+        id: "acceptance-run",
+        label: "Acceptance runs",
+        blurb: "One session per story in an acceptance fan-out.",
+        kind: "run",
+        icon: "list-check",
+    },
+    {
+        id: "pre-push-fix",
+        label: "Pre-push fixes",
+        blurb: "The fix proposed when a check fails on the way to a push.",
+        kind: "run",
+        icon: "cloud-upload",
+    },
+    {
+        id: "automation-wake",
+        label: "Automation wakes",
+        blurb: "A turn an automation fires: a schedule, a webhook, a message from outside.",
+        kind: "run",
+        icon: "clock",
+    },
+    {
+        id: "approval-queue",
+        label: "Approvals queue",
+        blurb: "The turn that publishes or acts on what you approved.",
+        kind: "run",
+        icon: "check-circle",
+    },
+    {
+        id: "extension-review",
+        label: "Extension update reviews",
+        blurb: "The agent that reads an extension update before it is applied.",
+        kind: "run",
+        icon: "box",
+    },
+    {
+        id: "loop-iteration",
+        label: "Loop iterations",
+        blurb: "Each round of a loop working towards its goal.",
+        kind: "run",
+        icon: "repeat",
+    },
+    {
+        id: "watch-wake",
+        label: "Watch wakes",
+        blurb: "The turn a watch starts when the thing it was watching happens.",
+        kind: "run",
+        icon: "eye",
+    },
+    {
+        id: "verify-nudge",
+        label: "Verify nudges",
+        blurb: "The follow-up turn sent when work was left unverified.",
+        kind: "run",
+        icon: "search",
+    },
+    {
+        /* THE ONE ROLE THAT ANSWERS A CHOICE RATHER THAN FILLING A SILENCE. A spawning agent may name its
+         * child's provider, and when it does that wins, exactly as a caret pick wins on every other run role.
+         * This is what answers when it names none, which used to be a hardcoded "claude". */
+        id: "child-agent",
+        label: "Child agents",
+        blurb: "What an agent's own subagents run on when it names no model for them.",
+        kind: "run",
+        icon: "users",
+    },
+] as const satisfies readonly ModelRoleRow[];
+
+export type ModelRole = (typeof MODEL_ROLES)[number]["id"];
+export type ModelRoleSpec = ModelRoleRow & { readonly id: ModelRole };
+
+export const MODEL_ROLE_IDS = MODEL_ROLES.map((role) => role.id) as readonly ModelRole[];
+
+/* The wire form. An enum rather than a string, unlike most ids in this contract, because there is no case for
+ * an unknown one: a role is a place in THIS codebase where a model gets chosen, so a value outside the table
+ * names nothing, and a settings file or a turn carrying one is a typo worth a clean error rather than a list
+ * silently ignored. */
+export const ModelRoleSchema = z.enum(MODEL_ROLE_IDS as [ModelRole, ...ModelRole[]]);
+
+const BY_ID = new Map<string, ModelRoleSpec>(MODEL_ROLES.map((role) => [role.id, role]));
+
+/** What this role is, or undefined for an id no build of this table declares. */
+export const modelRole = (id: string): ModelRoleSpec | undefined => BY_ID.get(id);
+
+/** The roles of one kind, in table order: the two blocks the settings page draws. */
+export const modelRolesOfKind = (kind: ModelRoleKind): readonly ModelRoleSpec[] => MODEL_ROLES.filter((role) => role.kind === kind);

package/src/peer-dial.test.ts

@@ -0,0 +1,203 @@
+import { expect, test, vi } from "vitest";
+import { dialPeer, type SocketLike } from "./peer-dial.js";
+
+/* The loop every peer runs, over a socket the test plays. What is at stake is the order of the two phases
+ * (handler attached BEFORE the hello goes out), the retry after a drop, the one close that is never retried,
+ * and that a stop reaches a dial still deciding where to go. */
+
+class FakeSocket implements SocketLike {
+    readyState = 0;
+    readonly sent: string[] = [];
+    closed: { readonly code: number | undefined; readonly reason: string | undefined } | undefined;
+    private readonly listeners = new Map<string, Set<(event: { readonly code?: number }) => void>>();
+
+    addEventListener(type: "open" | "close" | "error", listener: (event: { readonly code?: number }) => void): void {
+        const set = this.listeners.get(type) ?? new Set();
+        set.add(listener);
+        this.listeners.set(type, set);
+    }
+    send(data: string): void {
+        this.sent.push(data);
+    }
+    close(code?: number, reason?: string): void {
+        this.closed = { code, reason };
+        this.readyState = 3;
+    }
+    opens(): void {
+        this.readyState = 1;
+        this.emit("open");
+    }
+    drops(code: number): void {
+        this.readyState = 3;
+        this.emit("close", code);
+    }
+    private emit(type: string, code?: number): void {
+        for (const listener of this.listeners.get(type) ?? []) {
+            listener(code === undefined ? {} : { code });
+        }
+    }
+}
+
+// A ladder that answers with a fixed delay and records what it was told, so the test can read the held time.
+const ladder = (delay = 1_000) => {
+    const held: number[] = [];
+    return {
+        held,
+        next: (heldMs: number) => {
+            held.push(heldMs);
+            return delay;
+        },
+    };
+};
+
+const dialling = () => {
+    const sockets: FakeSocket[] = [];
+    const attached: FakeSocket[] = [];
+    const said: string[] = [];
+    const revoked = vi.fn();
+    const link = dialPeer<FakeSocket>({
+        open: async () => {
+            const socket = new FakeSocket();
+            sockets.push(socket);
+            return { socket, said: `connected #${sockets.length}` };
+        },
+        hello: () => ({ type: "hello", token: "iht_test", version: "1.0.0" }),
+        attach: (socket) => void attached.push(socket),
+        backoff: ladder(),
+        log: (message) => void said.push(message),
+        revoked,
+    });
+    return { link, sockets, attached, said, revoked };
+};
+
+test("the handler is attached before the hello goes out, and the hello is the first frame", async () => {
+    const { link, sockets, attached, said } = dialling();
+    await vi.waitFor(() => expect(sockets).toHaveLength(1));
+    expect(link.state()).toBe("connecting");
+    sockets[0]?.opens();
+    await vi.waitFor(() => expect(sockets[0]?.sent).toHaveLength(1));
+    expect(attached).toEqual([sockets[0]]);
+    expect(JSON.parse(sockets[0]?.sent[0] ?? "{}")).toEqual({ type: "hello", token: "iht_test", version: "1.0.0" });
+    expect(said).toEqual(["connected #1"]);
+    expect(link.state()).toBe("open");
+    link.stop();
+    await link.done;
+    expect(sockets[0]?.closed).toEqual({ code: 1000, reason: "stopping" });
+    expect(link.state()).toBe("closed");
+});
+
+test("a drop redials on the ladder, telling it how long the socket held", async () => {
+    vi.useFakeTimers();
+    try {
+        const { link, sockets, said } = dialling();
+        await vi.waitFor(() => expect(sockets).toHaveLength(1));
+        sockets[0]?.opens();
+        await vi.advanceTimersByTimeAsync(5_000);
+        sockets[0]?.drops(1006);
+        expect(link.state()).toBe("connecting");
+        expect(said.at(-1)).toBe("disconnected (1006); reconnecting in 1s");
+        await vi.advanceTimersByTimeAsync(1_000);
+        await vi.waitFor(() => expect(sockets).toHaveLength(2));
+        link.stop();
+        await link.done;
+    } finally {
+        vi.useRealTimers();
+    }
+});
+
+test("a refused enrollment (1008) is never retried and is reported once", async () => {
+    vi.useFakeTimers();
+    try {
+        const { link, sockets, revoked } = dialling();
+        await vi.waitFor(() => expect(sockets).toHaveLength(1));
+        sockets[0]?.opens();
+        sockets[0]?.drops(1008);
+        await link.done;
+        expect(revoked).toHaveBeenCalledTimes(1);
+        await vi.advanceTimersByTimeAsync(60_000);
+        expect(sockets).toHaveLength(1);
+        expect(link.state()).toBe("closed");
+    } finally {
+        vi.useRealTimers();
+    }
+});
+
+// A stop that lands while the address is still being decided has nothing to close and must open nothing after
+// the fact: a socket dialled by a loop that has already reported itself done would be a connection nobody stops.
+test("a stop during resolution opens nothing, and a socket a slow resolver still hands over is closed", async () => {
+    let answer: (() => void) | undefined;
+    const sockets: FakeSocket[] = [];
+    const link = dialPeer<FakeSocket>({
+        open: async (signal) => {
+            await new Promise<void>((resolve) => {
+                answer = resolve;
+            });
+            if (signal.aborted) {
+                return undefined;
+            }
+            const socket = new FakeSocket();
+            sockets.push(socket);
+            return { socket };
+        },
+        hello: () => ({}),
+        attach: () => undefined,
+        backoff: ladder(),
+        log: () => undefined,
+        revoked: () => undefined,
+    });
+    await vi.waitFor(() => expect(answer).toEqual(expect.any(Function)));
+    link.stop();
+    await link.done;
+    answer?.();
+    await new Promise<void>((resolve) => setTimeout(resolve, 0));
+    expect(sockets).toHaveLength(0);
+
+    // The other order: a resolver that ignores the signal and hands a socket over anyway.
+    const late: FakeSocket[] = [];
+    const careless = dialPeer<FakeSocket>({
+        open: async () => {
+            await new Promise<void>((resolve) => {
+                answer = resolve;
+            });
+            const socket = new FakeSocket();
+            late.push(socket);
+            return { socket };
+        },
+        hello: () => ({}),
+        attach: () => undefined,
+        backoff: ladder(),
+        log: () => undefined,
+        revoked: () => undefined,
+    });
+    await vi.waitFor(() => expect(answer).toEqual(expect.any(Function)));
+    careless.stop();
+    answer?.();
+    await vi.waitFor(() => expect(late[0]?.closed).toEqual({ code: 1000, reason: "stopping" }));
+});
+
+test("a pairing that is gone by the next attempt ends the loop rather than dialling nowhere", async () => {
+    let pairings = 1;
+    const sockets: FakeSocket[] = [];
+    const link = dialPeer<FakeSocket>({
+        open: async () => {
+            if (pairings === 0) {
+                return undefined;
+            }
+            pairings -= 1;
+            const socket = new FakeSocket();
+            sockets.push(socket);
+            return { socket };
+        },
+        hello: () => ({}),
+        attach: () => undefined,
+        backoff: ladder(0),
+        log: () => undefined,
+        revoked: () => undefined,
+    });
+    await vi.waitFor(() => expect(sockets).toHaveLength(1));
+    sockets[0]?.opens();
+    sockets[0]?.drops(1006);
+    await link.done;
+    expect(sockets).toHaveLength(1);
+    expect(link.state()).toBe("closed");
+});

package/src/peer-dial.ts

@@ -0,0 +1,163 @@
+/* THE ONE SOCKET a peer holds to its sandbox, written once for the three things that hold one: the machine
+ * agent (@intentic/machine), the browser extension (@intentic/webext) and a runner (the daemon itself, in
+ * runner mode). Each dials OUT, sends a plain-JSON hello carrying its enrollment token (host-protocol.ts,
+ * webext-protocol.ts, runner-protocol.ts), and from then on everything the sandbox asks arrives on the socket
+ * as oRPC against the door's contract, with the PEER serving.
+ *
+ * OUTBOUND ONLY, and that is the entire networking story: no port is opened, no router configured, no VPN
+ * joined. A laptop on hotel wifi behind a corporate proxy holds this connection because it is an ordinary
+ * outbound wss://, the same thing every chat app on the machine is already doing.
+ *
+ * The socket has exactly two phases. First the hello, plain JSON, because the sandbox has nothing to call until
+ * it knows whose socket this is (the token rides the FRAME, never the URL, which would write a durable key into
+ * every proxy log between the peer and the sandbox). Then the sandbox attaches its client and the socket is pure
+ * oRPC: request/response correlation, argument validation and error shape all belong to the link from that
+ * point on, which is why there is no message plumbing here.
+ *
+ * THE HANDLER IS ATTACHED BEFORE THE HELLO GOES OUT: the sandbox may call the moment it has verified the token,
+ * and a race there would drop the first `setScopes`, the one call whose loss would leave a device enforcing a
+ * stale grant.
+ *
+ * RECONNECTION IS THE NORMAL CASE, not the failure case. Lids close, wifi changes, tunnels idle out, sandboxes
+ * restart on every rebuild. So a dropped socket is routine and comes back on an exponential ladder the caller
+ * supplies (@intentic/base's createBackoff, over PEER_LINK_BACKOFF): a link that held for a minute was working
+ * and its drop redials at the floor; one that opened and died at once keeps climbing. The one thing that is NOT
+ * retried is a refused enrollment (close code 1008): the owner revoked this peer, that never heals on its own,
+ * and hammering a door that has been locked is how an agent turns a revocation into a support ticket.
+ *
+ * Here, in the contract, beside the hello schemas it sends and the URL builders it dials, rather than in a
+ * package of its own: every peer already depends on this one, and the loop is the far end of the same wire. */
+
+// Backoff bounds. The first retry is fast because the overwhelmingly common cause is a sandbox restart, which
+// takes seconds; the ceiling is low enough that a laptop opened after a night asleep is back within a minute.
+export const PEER_LINK_BACKOFF = { floorMs: 1_000, capMs: 30_000, stableMs: 60_000 } as const;
+
+// The sandbox closes with this when the token is not enrolled: a decision, not a fault, and one that never heals.
+const UNAUTHORIZED = 1008;
+
+// A socket's readyState value for "open", per the WebSocket spec, named so a caller's fake need not import a class.
+const OPEN = 1;
+
+// What the two runtimes' sockets have in common, taken structurally: a browser's WebSocket, node's global one,
+// and a test's fake all satisfy it without a cast.
+export interface SocketLike {
+    readonly readyState: number;
+    addEventListener(type: "open" | "close" | "error", listener: (event: { readonly code?: number }) => void): void;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+}
+
+export interface PeerDialSpec<S extends SocketLike> {
+    /* ONE ATTEMPT'S SOCKET, dialled at whatever address the caller resolves for THIS attempt: a sandbox on the
+     * same machine is a loopback hop away on one attempt and behind its tunnel on the next, and asking on every
+     * attempt rather than once at startup is exactly what a reconnect is about. `said` is the line the log gets
+     * once the socket is open. Undefined ⇒ there is nothing to dial any more (the pairing was forgotten), and
+     * the loop ends. `signal` is aborted by `stop`, so a resolution that outlives the stop opens nothing. */
+    readonly open: (signal: AbortSignal) => Promise<{ readonly socket: S; readonly said?: string } | undefined>;
+    // The first frame, carrying the enrollment token and whatever the door's hello schema asks for.
+    readonly hello: () => Promise<Record<string, unknown>> | Record<string, unknown>;
+    // Hand the open socket to the oRPC handler serving the door's contract.
+    readonly attach: (socket: S) => void;
+    // The retry ladder: how long to wait after a drop, given how long the socket had held.
+    readonly backoff: { readonly next: (heldMs: number) => number };
+    readonly log: (message: string) => void;
+    // The sandbox refused the enrollment (1008). The loop has already stopped; this is where the peer says so.
+    readonly revoked: () => void;
+}
+
+export interface PeerLink {
+    // Resolves when the loop is asked to stop or refused for good; never rejects, a connection error is a retry.
+    readonly done: Promise<void>;
+    readonly stop: (reason?: string) => void;
+    // "connecting" covers a dial in flight AND a retry waiting on the ladder: both mean nobody should start another.
+    readonly state: () => "open" | "connecting" | "closed";
+}
+
+export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink => {
+    const stopping = new AbortController();
+    let socket: S | undefined;
+    let waiting = false;
+    let openedAt: number | undefined;
+    let resolveDone: () => void = () => undefined;
+    const done = new Promise<void>((resolve) => {
+        resolveDone = resolve;
+    });
+
+    const open = async (): Promise<void> => {
+        waiting = true;
+        const attempt = await spec.open(stopping.signal);
+        waiting = false;
+        // Stopped while the address was still being decided: there is nothing to open, and `stop` has already
+        // settled `done`. A socket a slow resolver still handed over is closed rather than left dialling.
+        if (stopping.signal.aborted) {
+            attempt?.socket.close(1000, "stopping");
+            return;
+        }
+        if (attempt === undefined) {
+            stopping.abort();
+            resolveDone();
+            return;
+        }
+        const ws = attempt.socket;
+        socket = ws;
+
+        ws.addEventListener("open", () => {
+            openedAt = Date.now();
+            spec.attach(ws);
+            const send = (hello: Record<string, unknown>): void => {
+                ws.send(JSON.stringify(hello));
+                if (attempt.said !== undefined) {
+                    spec.log(attempt.said);
+                }
+            };
+            // Sent in the open handler's own tick where the hello is already in hand: the sandbox's auth
+            // deadline is generous, but a frame that could go now and waits a tick is a frame a test cannot
+            // read, and a hello that needs a read first (a runner's settings claim) simply follows it.
+            const hello = spec.hello();
+            if (hello instanceof Promise) {
+                void hello.then(send);
+            } else {
+                send(hello);
+            }
+        });
+
+        ws.addEventListener("close", (event) => {
+            socket = undefined;
+            if (stopping.signal.aborted) {
+                resolveDone();
+                return;
+            }
+            if (event.code === UNAUTHORIZED) {
+                stopping.abort();
+                resolveDone();
+                spec.revoked();
+                return;
+            }
+            const delay = spec.backoff.next(openedAt === undefined ? 0 : Date.now() - openedAt);
+            openedAt = undefined;
+            spec.log(`disconnected (${event.code ?? "no code"}); reconnecting in ${Math.round(delay / 1000)}s`);
+            waiting = true;
+            setTimeout(() => void open(), delay);
+        });
+
+        // A socket error is always followed by a close event, which owns the retry; this only records the cause,
+        // which the close code alone never carries.
+        ws.addEventListener("error", () => spec.log("connection error"));
+    };
+
+    void open();
+
+    return {
+        done,
+        stop: (reason = "stopping") => {
+            stopping.abort();
+            waiting = false;
+            // Forgotten before the close frame arrives, so `state` reads closed the moment the peer asked.
+            const held = socket;
+            socket = undefined;
+            held?.close(1000, reason);
+            resolveDone();
+        },
+        state: () => (socket?.readyState === OPEN ? "open" : socket !== undefined || waiting ? "connecting" : "closed"),
+    };
+};