statewire 0.19.4 → 0.21.0

package/src/host/socket.ts

@@ -1,3 +1,5 @@
+import { contextValue, captureContext } from "../wire/context";
+import { MAX_CONTEXT_BYTES } from "../wire/limits";
 import { encodeDocument } from "../document";
 import {
   DEFAULT_PROTOCOL,
@@ -126,7 +128,10 @@ export type Conn = {
   lease: string | null;
   /** The awaited `authorize` return captured at this attach's authorization. */
   auth: unknown;
+  authorizedAt: number | undefined;
+  leaseTimer: ReturnType<typeof setTimeout> | null;
   lanes: Map<string, Lane>;
+  contexts: Map<string, Statewire.Context>;
   documents: Map<string, StatewireHost.Document>;
   included: Set<string>;
   view: Map<string, { doc: number; value: unknown }>;
@@ -164,7 +169,10 @@ type CmdStatement = {
   meta?: unknown;
 };
 
-export type ParsedFrame = { cmd: CmdStatement[] };
+export type ParsedFrame = {
+  cmd: CmdStatement[];
+  ctx?: { protocol: string; value: Statewire.Context }[];
+};
 
 const isPlainObject = (value: unknown): value is Record<string, unknown> =>
   typeof value === "object" && value !== null && !Array.isArray(value);
@@ -175,12 +183,13 @@ export const parseFrameValue = (frame: unknown): ParsedFrame => {
   if (!isPlainObject(frame)) return violation("malformed frame");
   const keys = Object.keys(frame);
   if (keys.length === 0) return violation("malformed frame");
-  const unknown = keys.filter((key) => key !== "cmd").sort();
+  const unknown = keys.filter((key) => key !== "cmd" && key !== "ctx").sort();
   if (unknown.length > 0)
     return violation(`unknown frame key: '${unknown[0]}'`);
-  const lane = frame["cmd"];
+  const lane = frame["cmd"] ?? [];
   if (!Array.isArray(lane)) return violation("malformed frame");
-  if (lane.length === 0) return violation("empty lane");
+  if (Object.hasOwn(frame, "cmd") && lane.length === 0)
+    return violation("empty lane");
   if (lane.length > MAX_COMMANDS_PER_FRAME)
     return violation("too many commands");
   const prev = new Map<string, number>();
@@ -212,7 +221,47 @@ export const parseFrameValue = (frame: unknown): ParsedFrame => {
       ...(statement["meta"] !== undefined && { meta: statement["meta"] }),
     });
   }
-  return { cmd };
+  const contexts = frame["ctx"];
+  const ctx: NonNullable<ParsedFrame["ctx"]> = [];
+  if (contexts !== undefined) {
+    if (!Array.isArray(contexts) || contexts.length === 0)
+      return violation("empty context lane");
+    const seen = new Set<string>();
+    for (const entry of contexts) {
+      if (
+        !isPlainObject(entry) ||
+        typeof entry["protocol"] !== "string" ||
+        !Object.hasOwn(entry, "value") ||
+        Object.keys(entry).some(
+          (key) => !["protocol", "value", "meta"].includes(key),
+        )
+      )
+        return violation("malformed context");
+      const protocol = entry["protocol"];
+      if (seen.has(protocol)) return violation("duplicate context protocol");
+      seen.add(protocol);
+      if (
+        frameEncoder.encode(JSON.stringify(entry)).byteLength >
+        MAX_CONTEXT_BYTES
+      )
+        return violation("context entry too large");
+      try {
+        ctx.push({
+          protocol,
+          value: contextValue({
+            value: entry["value"],
+            ...(entry["meta"] !== undefined && { meta: entry["meta"] }),
+          }),
+        });
+      } catch (error) {
+        return violation(
+          error instanceof Error ? error.message : "invalid context",
+        );
+      }
+    }
+  }
+  if (cmd.length === 0 && ctx.length === 0) return violation("empty frame");
+  return { cmd, ...(ctx.length > 0 && { ctx }) };
 };
 
 export const parseFrame = (raw: string): ParsedFrame => {
@@ -269,13 +318,11 @@ const cmdOf = (adm: Admission, outcome: CommandsOutcome): Cmd => {
       };
     }
     default:
+      console.error("statewire command failed", outcome.error);
       return {
         ...at,
         type: "failed",
-        message:
-          outcome.error instanceof Error
-            ? outcome.error.message
-            : String(outcome.error),
+        message: "the command failed",
       };
   }
 };
@@ -309,6 +356,7 @@ export type SocketHostState = {
   key: readonly string[] | undefined;
   wireVersion: StatewireProtocol.Range;
   heartbeatMs: number;
+  maxLeaseLifetimeMs: number | null;
   wsInitTimeoutMs: number;
   maxSubscribers: number;
   maxInflightCommands: number;
@@ -404,6 +452,10 @@ export const closeConn = (
   if (!conn.open) return;
   conn.open = false;
   h.conns.delete(conn);
+  if (conn.leaseTimer !== null) {
+    clearTimeout(conn.leaseTimer);
+    conn.leaseTimer = null;
+  }
   try {
     conn.socket.close(code, reason);
   } catch {
@@ -426,6 +478,49 @@ export const sendTo = (h: SocketHostState, conn: Conn, data: string) => {
   }
 };
 
+const expiredAt = (h: SocketHostState, authorizedAt: number | undefined) => {
+  const now = Date.now();
+  return (
+    authorizedAt === undefined ||
+    !Number.isFinite(authorizedAt) ||
+    authorizedAt < 0 ||
+    authorizedAt > now ||
+    (h.maxLeaseLifetimeMs !== null &&
+      now - authorizedAt >= h.maxLeaseLifetimeMs)
+  );
+};
+
+const leaseExpiredFin = JSON.stringify({
+  fin: { reason: "reconnect", code: "lease-expired" },
+});
+
+export const expireLease = (h: SocketHostState, conn: Conn): boolean => {
+  if (!conn.open || expiredAt(h, conn.authorizedAt)) {
+    if (conn.open) {
+      sendTo(h, conn, leaseExpiredFin);
+      closeConn(h, conn, 1000, "lease-expired");
+    }
+    return true;
+  }
+  return false;
+};
+
+const armLeaseTimer = (h: SocketHostState, conn: Conn) => {
+  if (conn.leaseTimer !== null) clearTimeout(conn.leaseTimer);
+  conn.leaseTimer = null;
+  if (h.disposed || h.maxLeaseLifetimeMs === null || expireLease(h, conn))
+    return;
+  const delay = h.maxLeaseLifetimeMs - (Date.now() - conn.authorizedAt!);
+  conn.leaseTimer = setTimeout(
+    () => {
+      conn.leaseTimer = null;
+      if (!expireLease(h, conn)) armLeaseTimer(h, conn);
+    },
+    Math.min(delay, 2_147_483_647),
+  );
+  (conn.leaseTimer as unknown as { unref?: () => void }).unref?.();
+};
+
 const violate = (h: SocketHostState, conn: Conn, reason: string) => {
   sendTo(
     h,
@@ -554,6 +649,13 @@ const attachOf = (h: SocketHostState, conn: Conn): StatewireHost.Attach => {
     return entry;
   };
   return {
+    get caller() {
+      return callerOf(h, h.clients.get(conn.clientId)!, conn);
+    },
+    context: (protocol) => {
+      requireSelected(protocol);
+      return captureContext(conn.contexts.get(protocol) ?? {});
+    },
     document: (protocol, key) => {
       if (key === undefined && protocol === h.protocol.name)
         return h.stateHost!.snapshot();
@@ -916,6 +1018,7 @@ const admitCmd = (
     clientId: rec.id,
     caller: callerOf(h, rec, conn),
     attach: conn.attach,
+    context: captureContext(conn.contexts.get(statement.protocol) ?? {}),
     onApplied: () => {
       if (adm.settled || adm.applied) return;
       adm.applied = true;
@@ -935,6 +1038,7 @@ const admitCmd = (
 // never a close; an ephemeral gap is a violation (the lane has no replay).
 export type FrameAdmission =
   | { type: "ok" }
+  | { type: "expired" }
   | {
       type: "refused";
       syn: {
@@ -959,11 +1063,66 @@ const refusal = (
   },
 });
 
+const validateContexts = (
+  h: SocketHostState,
+  conn: Conn,
+  frame: ParsedFrame,
+) => {
+  for (const statement of frame.cmd) {
+    if (!selects(conn, statement.protocol))
+      return violation("unsupported protocol");
+    const selected = conn.selection.protocols.find(
+      (p) => p.name === statement.protocol,
+    )!;
+    if (selected.record === "ephemeral") {
+      const through = watermark(h, conn, statement.protocol);
+      const first = frame.cmd.find(
+        (s) => s.protocol === statement.protocol && s.seq > through,
+      );
+      if (first && first.seq !== through + 1)
+        return violation("ephemeral lane gap");
+    }
+  }
+  for (const entry of frame.ctx ?? []) {
+    if (!selects(conn, entry.protocol))
+      return violation("unsupported context protocol");
+    try {
+      h.current?.validateContext?.(
+        entry.protocol,
+        captureContext(entry.value),
+        conn.attach,
+      );
+    } catch (error) {
+      return violation(
+        error instanceof Error ? error.message : "invalid context",
+      );
+    }
+  }
+};
+
+const installContexts = (
+  h: SocketHostState,
+  conn: Conn,
+  frame: ParsedFrame,
+) => {
+  for (const entry of frame.ctx ?? [])
+    conn.contexts.set(entry.protocol, captureContext(entry.value));
+  for (const entry of frame.ctx ?? [])
+    h.current?.contextChanged?.(
+      entry.protocol,
+      captureContext(entry.value),
+      conn.attach,
+    );
+};
+
 export const admitFrame = (
   h: SocketHostState,
   conn: Conn,
   frame: ParsedFrame,
 ): FrameAdmission => {
+  if (expireLease(h, conn)) return { type: "expired" };
+  validateContexts(h, conn, frame);
+  installContexts(h, conn, frame);
   const rec = h.clients.get(conn.clientId)!;
   rec.touched = Date.now();
   const lanes = new Map(
@@ -1011,6 +1170,7 @@ export const admitFrame = (
       return refusal(h, conn, retry);
     }
   }
+  if (expireLease(h, conn)) return { type: "expired" };
   for (const s of fresh) admitCmd(h, lanes.get(s.protocol)!, conn, s);
   for (const [protocol, lane] of lanes) {
     const last = fresh.findLast((s) => s.protocol === protocol);
@@ -1024,7 +1184,8 @@ export const admitFrame = (
 };
 
 const message = (h: SocketHostState, conn: Conn, data: string) => {
-  if (!conn.open || h.disposed || h.finished !== null) return;
+  if (!conn.open || h.disposed || h.finished !== null || expireLease(h, conn))
+    return;
   if (frameIsOversized(data)) {
     sendTo(
       h,
@@ -1048,7 +1209,7 @@ const message = (h: SocketHostState, conn: Conn, data: string) => {
   let admission: ReturnType<typeof admitFrame>;
   try {
     const frame = first ? parseInitialFrame(data).frame : parseFrame(data);
-    if (frame.cmd.length === 0) return;
+    if (frame.cmd.length === 0 && !frame.ctx?.length) return;
     admission = admitFrame(h, conn, frame);
   } catch (error) {
     const reason = violationReason(error);
@@ -1160,6 +1321,19 @@ const connectAuthorized = (
 ): StatewireHostInternal.SocketConnection | null => {
   const authorize = h.authorize;
   if (options.authorized === true) {
+    if (expiredAt(h, options.authorizedAt)) {
+      try {
+        socket.send(leaseExpiredFin);
+      } catch {
+        /* peer already gone */
+      }
+      try {
+        socket.close(1000, "lease-expired");
+      } catch {
+        /* peer already gone */
+      }
+      return null;
+    }
     const registration = register(
       h,
       clientId,
@@ -1167,6 +1341,8 @@ const connectAuthorized = (
       options.authorized === true,
       options.auth,
       options.selection,
+      undefined,
+      options.authorizedAt,
     );
     return registration?.connection ?? null;
   }
@@ -1294,6 +1470,7 @@ const connectAuthorized = (
         .then(() => authorize?.({ headers }))
         .then((auth) => {
           if (!pending.open || h.disposed || h.finished !== null) return;
+          const authorizedAt = Date.now();
           const selection = negotiateProtocols(
             new Headers(headers),
             h.wireVersion,
@@ -1304,7 +1481,7 @@ const connectAuthorized = (
             closePending(h, pending, 1008, selection.fin.message);
             return;
           }
-          options.onAuthorized?.(auth, selection);
+          options.onAuthorized?.(auth, selection, authorizedAt);
           pending.open = false;
           h.pendingConns.delete(pending);
           if (pending.timer !== null) clearTimeout(pending.timer);
@@ -1318,6 +1495,7 @@ const connectAuthorized = (
               auth,
               selection,
               frame,
+              authorizedAt,
             );
           } catch (error) {
             if (violationReason(error) === null) throw error;
@@ -1380,6 +1558,7 @@ export const register = (
     protocols: [{ name: h.protocol.name, version: h.protocol.version }],
   },
   frame: ParsedFrame = { cmd: [] },
+  authorizedAt?: number,
 ): Registration | null => {
   const refuse = (code: number, reason: string) => {
     try {
@@ -1404,6 +1583,14 @@ export const register = (
   if (atSubscriberLimit(h)) {
     return refuseSubscriberLimit(socket);
   }
+  if (expiredAt(h, authorizedAt)) {
+    try {
+      socket.send(leaseExpiredFin);
+    } catch {
+      /* peer already gone */
+    }
+    return refuse(1000, "lease-expired");
+  }
   const known = h.clients.get(clientId);
   if (known !== undefined && !authEquals(known.principal, auth)) {
     try {
@@ -1444,7 +1631,10 @@ export const register = (
     lastSentAt: 0,
     lease: null,
     auth,
+    authorizedAt,
+    leaseTimer: null,
     lanes: new Map(),
+    contexts: new Map(),
     documents: new Map(),
     included: new Set(),
     view: new Map(),
@@ -1456,13 +1646,19 @@ export const register = (
   conn.attach = attachOf(h, conn);
   h.conns.add(conn);
   try {
+    validateContexts(h, conn, frame);
+    installContexts(h, conn, frame);
     h.current?.attaching?.(conn.attach);
   } catch (error) {
-    closeConn(h, conn, 1011, "attach failed");
+    const reason = violationReason(error);
+    if (reason !== null) violate(h, conn, reason);
+    else closeConn(h, conn, 1011, "attach failed");
     throw error;
   }
   gcClients(h);
   ensureHeartbeat(h);
+  armLeaseTimer(h, conn);
+  if (!conn.open) return null;
   const isEphemeral = (s: CmdStatement) =>
     selection.protocols.find((p) => p.name === s.protocol)?.record ===
     "ephemeral";
@@ -1482,6 +1678,7 @@ export const register = (
   const earlyAdmission = admit(early);
   if (early.length > 0) flush(h);
   notifyClientRecords(h);
+  if (expireLease(h, conn)) return null;
   const ops: WireOp[] = [];
   if (selects(conn, h.protocol.name)) {
     const { value, meta } = encodeDocument(h.stateHost!.snapshot());
@@ -1556,10 +1753,15 @@ const resume = (h: SocketHostState) => {
   h.disposed = false;
   h.stateHost?.setOnOp((op) => recordOp(h, op));
   h.stateHost?.setOnDocuments(() => markViews(h));
+  for (const conn of h.conns) armLeaseTimer(h, conn);
 };
 
 const suspend = (h: SocketHostState) => {
   h.disposed = true;
+  for (const conn of h.conns) {
+    if (conn.leaseTimer !== null) clearTimeout(conn.leaseTimer);
+    conn.leaseTimer = null;
+  }
   if (h.heartbeatTimer !== null) {
     clearInterval(h.heartbeatTimer);
     h.heartbeatTimer = null;
@@ -1611,6 +1813,7 @@ const useSocketHost = (
       key: undefined,
       wireVersion: { version: WIRE_VERSION },
       heartbeatMs: 15_000,
+      maxLeaseLifetimeMs: 86_400_000,
       wsInitTimeoutMs: 5_000,
       maxSubscribers: MAX_SUBSCRIBERS,
       maxInflightCommands: MAX_INFLIGHT_COMMANDS_PER_HOST,
@@ -1654,6 +1857,22 @@ const useSocketHost = (
   h.key = options?.key;
   h.wireVersion = options?.wireVersion ?? { version: WIRE_VERSION };
   setHeartbeatMs(h, options?.heartbeatIntervalMs ?? 15_000);
+  const maxLeaseLifetimeMs =
+    options?.maxLeaseLifetimeMs === undefined
+      ? 86_400_000
+      : options.maxLeaseLifetimeMs;
+  if (
+    maxLeaseLifetimeMs !== null &&
+    (!Number.isFinite(maxLeaseLifetimeMs) || maxLeaseLifetimeMs <= 0)
+  ) {
+    throw new TypeError(
+      "maxLeaseLifetimeMs must be finite and positive or null",
+    );
+  }
+  if (h.maxLeaseLifetimeMs !== maxLeaseLifetimeMs) {
+    h.maxLeaseLifetimeMs = maxLeaseLifetimeMs;
+    for (const conn of [...h.conns]) armLeaseTimer(h, conn);
+  }
   h.pushback = options?.pushback;
   h.wsInitTimeoutMs = options?.wsInitTimeoutMs ?? 5_000;
   const maxSubscribers =

package/src/host-internal.ts

@@ -21,6 +21,7 @@ export namespace StatewireHostInternal {
     headers?: Record<string, string>;
     /** The adapter restored this socket from an already-authorized session. */
     authorized?: boolean;
+    authorizedAt?: number;
     selection?: StatewireProtocol.Selection;
     /** The restored session's captured auth value; it must satisfy the client record's principal binding. */
     auth?: unknown;
@@ -28,6 +29,7 @@ export namespace StatewireHostInternal {
     onAuthorized?: (
       auth: unknown,
       selection: StatewireProtocol.Selection,
+      authorizedAt: number,
     ) => void;
   };
 
@@ -88,6 +90,8 @@ export namespace StatewireHostInternal {
     /** Time allowed to complete WebSocket initialization and authorization. */
     wsInitTimeoutMs?: number;
     heartbeatIntervalMs?: number;
+    /** Maximum attach lifetime in milliseconds; defaults to 24 hours, null disables expiry. */
+    maxLeaseLifetimeMs?: number | null;
     /** Maximum number of concurrently attached WebSocket and SSE streams. */
     maxSubscribers?: number;
     /** Maximum number of admitted commands still running across all clients. */

package/src/host.ts

@@ -53,8 +53,11 @@ export namespace StatewireHost {
    * optimistic overlay — before the handler settles (idempotent, a no-op after
    * settle). The command settles when the handler's returned promise does.
    */
+  export type CommandsOptions = { context?: () => Statewire.Context };
+
   export type Ctx = {
     readonly caller: Caller;
+    readonly context: Statewire.Context;
     readonly attach: Attach;
     readonly signal: AbortSignal;
     readonly applied: () => void;
@@ -76,6 +79,8 @@ export namespace StatewireHost {
 
   /** The admitting attach's view: its ephemeral documents plus the shared documents included for it. */
   export type Attach = {
+    readonly caller: Caller;
+    context: (protocol: string) => Statewire.Context;
     document: (protocol: string, key?: readonly string[]) => unknown;
     /** `protocol` must be ephemeral; the encoded value is bounded by `MAX_EPHEMERAL_DOCUMENT_BYTES`. */
     mount: (

package/src/statewire.ts

@@ -40,7 +40,10 @@ const useSessionTransport = ({
   session: StatewireClient.SessionStorage | undefined;
   documents: StatewireDocuments.Storage | undefined;
   protocol: StatewireProtocol.Options;
-  link: { isNew?: boolean | undefined };
+  link: {
+    isNew?: boolean | undefined;
+    context?: Readonly<Record<string, Statewire.Context>> | undefined;
+  };
 }): Statewire<unknown> =>
   useContextProvider(SessionStorageContext, session, () =>
     // oxlint-disable-next-line react-hooks/rules-of-hooks
@@ -92,8 +95,11 @@ export const useStatewire = <
     }),
   };
   const link = useMemo(
-    () => (options.isNew === undefined ? {} : { isNew: options.isNew }),
-    [options.isNew],
+    () => ({
+      ...(options.isNew === undefined ? {} : { isNew: options.isNew }),
+      ...(options.context === undefined ? {} : { context: options.context }),
+    }),
+    [options.isNew, options.context],
   );
   const value = useResource(
     SessionTransport({
@@ -104,6 +110,14 @@ export const useStatewire = <
       link,
     }),
   );
+  const localContext =
+    value.connection === undefined ? value.setContext : undefined;
+  useEffect(() => {
+    const current = latest.current;
+    if (localContext === undefined || current.context === undefined) return;
+    for (const [protocol, context] of Object.entries(current.context))
+      localContext(protocol, context);
+  }, [options.context, localContext]);
   const core = useStatewireCore(() => latest.current, value);
   useEffect(() => core.rematerialize(), [core, options.materializeKey]);
   const [subscribe] = useState(
@@ -127,6 +141,7 @@ export const useStatewire = <
     documents: source,
     selection,
     invoke: transportInvoke,
+    setContext: transportSetContext,
     failures: transportFailures,
   } = value;
 
@@ -141,6 +156,15 @@ export const useStatewire = <
     [transportInvoke],
   );
 
+  const setContext = useCallback(
+    (protocol: string, value: Statewire.Context) => {
+      if (!transportSetContext)
+        throw new Error("statewire: transport does not support context");
+      transportSetContext(protocol, value);
+    },
+    [transportSetContext],
+  );
+
   return useMemo(() => {
     const failures = (): NonNullable<typeof transportFailures> => {
       if (!transportFailures) {
@@ -153,6 +177,7 @@ export const useStatewire = <
       documents: source,
       selection,
       invoke,
+      setContext,
       getState: core.getState as () => TState,
       connection,
       commands: core.commands as Statewire.CommandsProxy<TCommands>,
@@ -173,6 +198,7 @@ export const useStatewire = <
     selection,
     invoke,
     transportFailures,
+    setContext,
   ]);
 };
 
@@ -221,6 +247,9 @@ export class StatewireClient<
   ): Promise<unknown> {
     return this.root.getValue().invoke(protocol, method, params);
   }
+  setContext(protocol: string, value: Statewire.Context): void {
+    this.root.getValue().setContext(protocol, value);
+  }
   get isBusy(): boolean {
     return this.root.getValue().isBusy;
   }
@@ -254,6 +283,7 @@ export namespace StatewireClient {
     TCommands extends Statewire.Commands = Statewire.Commands,
   > = {
     protocol?: string;
+    context?: Readonly<Record<string, Statewire.Context>>;
     keyPrefixes?: Readonly<Record<string, readonly string[]>>;
     wireVersion?: StatewireProtocol.Range;
     applicationProtocols?: readonly StatewireProtocol.Offer[] | "*";
@@ -298,6 +328,7 @@ export namespace StatewireClient {
     state: TState;
     documents: StatewireDocuments.Source | undefined;
     selection: StatewireProtocol.Selection | undefined;
+    setContext: (protocol: string, value: Statewire.Context) => void;
     invoke: (
       protocol: string,
       method: string,

package/src/transports/remote.ts

@@ -9,6 +9,7 @@ import {
   retryFailed,
   setTransport,
   useStatewireSession,
+  setContext,
 } from "../client/session";
 import type { StatewireSessionOptions } from "../client/session";
 import type { StatewireClient } from "../statewire";
@@ -35,6 +36,8 @@ export const useStatewireRemote = <
   const lanes = useMemo(
     () => ({
       documents: documentSource(s),
+      setContext: (protocol: string, value: Statewire.Context) =>
+        setContext(s, protocol, value),
       invoke: (protocol: string, method: string, params: readonly unknown[]) =>
         invokeProtocol(s, protocol, method, params),
       failures: {

package/src/transports/sse.ts

@@ -1,3 +1,4 @@
+import type { StatewireDocument } from "../document";
 import { flushTapSync, resource } from "@assistant-ui/tap";
 import type { ResourceElement } from "@assistant-ui/tap";
 import { createSseParser } from "./sse-parser";
@@ -25,6 +26,7 @@ import { negotiationHeaders, parseNegotiation } from "../wire/protocol";
 
 /** A client frame's lanes: stamped statements, strictly consecutive per lane. */
 export type StatewireFrame = {
+  ctx?: ({ protocol: string } & StatewireDocument.Encoded)[];
   cmd?: {
     protocol: string;
     method: string;
@@ -59,6 +61,7 @@ export type ConnectionState = StatewireClient.ConnectionState;
 /** The live wire a remote session drives: connection status plus frame submission. */
 export type RemoteLink = {
   storageFailed: (error: Error) => void;
+  protocolFailed: (error: Error) => void;
   connection: StatewireClient.Connection;
   /** A deferred first attach still waiting; `reconnect()` releases it. */
   parked: boolean;
@@ -67,6 +70,16 @@ export type RemoteLink = {
 
 const LEASE_HEADER = "Statewire-Lease";
 
+let warnedNoLease = false;
+
+const warnNoLease = () => {
+  if (warnedNoLease) return;
+  warnedNoLease = true;
+  console.warn(
+    "statewire: SSE attach returned no readable Statewire-Lease header; commands will re-attach the stream. Cross-origin hosts must expose it (Access-Control-Expose-Headers: Statewire-Lease).",
+  );
+};
+
 const baseUrl = (options: StatewireClient.HttpOptions) =>
   options.url.replace(/\/$/, "");
 
@@ -179,10 +192,16 @@ const attemptStream = async (
   if (!res.body)
     throw new Error("statewire: protocol error: stream response has no body");
   c.lease = res.headers.get(LEASE_HEADER);
+  if (c.lease === null) warnNoLease();
   const reader = res.body.getReader();
+  const cancel = () => {
+    void reader.cancel().catch(() => {});
+  };
+  abort.signal.addEventListener("abort", cancel, { once: true });
   try {
     return await consume(c, reader, heartbeat, () => abort.signal.aborted);
   } finally {
+    abort.signal.removeEventListener("abort", cancel);
     reader.cancel().catch(() => {});
   }
 };