@preventive/triage 1.0.0-alpha.0 → 1.0.0-alpha.10

package/{server → server-e2e}/index.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // DeepView triage-sync relay server. WebSocket front-end, SQLite
 // backing store. Implements the protocol described in
-// `client/triage-sync.js` (and `server/sign.ts` for the canonical
+// `client/triage-sync.js` (and `server-e2e/sign.ts` for the canonical
 // signature payloads):
 //
 //   server → client  challenge           { nonce } — emitted on every
@@ -73,14 +73,16 @@
 // and would not reject the attaching socket.
 
 import { type WebSocket, WebSocketServer } from 'ws'
-import { errMsg } from './util.ts'
+import { errMsg, errStack } from './util.ts'
 import type { PeerRegistry } from './peer.ts'
-import { LOOPBACK_HOSTS, createOriginGate } from './origin.ts'
+import { LOOPBACK_HOSTS, createOriginGate } from '../server-common/origin.ts'
 import { createHub } from './hub.ts'
 import { createAuth } from './auth.ts'
 import { createSyncHandlers } from './sync-handlers.ts'
 import { WS_UPGRADE_PATH, createHttpServer } from './http.ts'
 import { installWsServer } from './ws-server.ts'
+import { SSE_OPEN_PATH, installSseServer } from './sse-server.ts'
+import type { ServerInfo } from '../common/server-info.ts'
 import { createLifecycle } from './lifecycle.ts'
 import { loadConfig } from './config.ts'
 import { type Handle, openDb } from './db.ts'
@@ -89,22 +91,27 @@ import { initObjstore } from './objstore/init.ts'
 import { type Handle as ObjstoreHandle, listLive, objectMetaWire, openObjstore } from './objstore/store.ts'
 import { openNeonObjstore } from './objstore/store-neon.ts'
 import { openVercelBlobBackend } from './objstore/blob-vercel.ts'
+import {
+  type NeonClientCtor, type PubSub,
+  createNeonPubSub, createNoopPubSub,
+} from './pubsub.ts'
+import { createBusReceiver } from './bus-receiver.ts'
 
 // All external inputs (env vars + optional config.json) are parsed
-// and validated in ./config.ts. Destructure into the existing
-// uppercase names so the rest of this module reads unchanged.
+// and validated in ./config.ts; destructure into the uppercase names
+// the rest of this module uses.
 const config = loadConfig()
 const {
   port: PORT, host: HOST, dbPath: DB_PATH, objstoreDir: OBJSTORE_DIR,
-  reapIntervalMs: OBJSTORE_REAP_INTERVAL_MS,
+  reapIntervalMs: OBJSTORE_REAP_INTERVAL_MS, reapDisabled: OBJSTORE_REAP_DISABLED,
   maxInflightPerSocket: MAX_INFLIGHT_PER_SOCKET, debug: DEBUG,
   neonUrl: NEON_URL, blobToken: BLOB_TOKEN, tokenSecret: TOKEN_SECRET,
   password: CONFIG_PASSWORD, trustProxyEnv: TRUST_PROXY_ENV,
 } = config
 
 // Same-origin gate for the WS upgrade and REST data plane (see
-// ./origin.ts). `TRUST_PROXY_ENV` (from config) also feeds the
-// boot-time misconfiguration fail-fast below.
+// ./origin.ts). `TRUST_PROXY_ENV` also feeds the boot-time
+// misconfiguration fail-fast below.
 const { trustProxy: TRUST_PROXY, isOriginAllowed } = createOriginGate(HOST, TRUST_PROXY_ENV)
 
 // Per-socket buffered-bytes cap. `socket.send` returns synchronously
@@ -114,28 +121,27 @@ const { trustProxy: TRUST_PROXY, isOriginAllowed } = createOriginGate(HOST, TRUS
 // MB of fan-out broadcasts in this buffer with no backpressure on
 // the broadcast loop. Drop the message when the buffer crosses the
 // cap; the heartbeat will eventually close a peer that never
-// drains. Transport audit `server/index.ts:225`.
+// drains. Transport audit `server-e2e/index.ts:225`.
 const MAX_BUFFERED_BYTES = 16 * 1024 * 1024
 // Per-socket in-flight async-handler cap (MAX_INFLIGHT_PER_SOCKET,
 // env-validated in config). Each inbound text frame spawns a
 // `track(handler)` IIFE; an authorised peer firing valid frames could
 // otherwise grow the set without bound, stretching SIGTERM drain time.
 // Saves dropped at the cap surface as a typed `busy` NACK. Transport
-// audit `server/index.ts:590`.
+// audit `server-e2e/index.ts:590`.
 
 // Per-connection state registry. One `Peer` per accepted socket holds
 // the challenge nonce, auth flag, heartbeat liveness, in-flight count,
-// and subscribed tags (see ./peer.ts) — replacing what were five
-// parallel per-socket WeakMaps. The connection handler holds the Peer
-// in a closure for the hot paths; cross-function call sites resolve it
-// via `peers.get(socket)`.
+// and subscribed tags (see ./peer.ts). The connection handler holds
+// the Peer in a closure for the hot paths; cross-function call sites
+// resolve it via `peers.get(socket)`.
 const peers: PeerRegistry = new WeakMap()
 
 // REST PUT idle-body timeout. A slow-loris client trickling bytes
 // within the declared Content-Length holds the staging fd and an
 // inFlightSids slot until the global staging TTL reaps it. Aborting
 // the per-chunk-idle period closes that window. Transport audit
-// `server/objstore/rest.ts:218`.
+// `server-e2e/objstore/rest.ts:218`.
 const REST_PUT_IDLE_TIMEOUT_MS = 30_000
 
 // Server-driven WS heartbeat. Every `HEARTBEAT_INTERVAL_MS` we walk
@@ -157,8 +163,8 @@ const REST_PUT_IDLE_TIMEOUT_MS = 30_000
 const HEARTBEAT_INTERVAL_MS = 30_000
 
 // Backend selection. Both planes (workspace_revision DB + the
-// v1.objstore byte store) are picked from config at boot. Two supported
-// pairings:
+// v1.objstore byte store) are picked from config at boot. Two
+// supported pairings:
 //   1. DATABASE_URL set → Neon (workspace_revision + objstore
 //      tables) + Vercel Blob Private Storage (bytes). Requires
 //      BLOB_READ_WRITE_TOKEN — fail fast at boot if missing, since
@@ -168,11 +174,10 @@ const HEARTBEAT_INTERVAL_MS = 30_000
 //      process; the only pairing the SQLite plane supports.
 // The Neon / Vercel files import their peer deps lazily inside the
 // open functions, so static imports here are safe even on a SQLite-
-// only install where the optional peer deps aren't present. Branch
-// out explicitly (rather than via a ternary) so the SQLite path
-// keeps its `SqliteHandle` narrowing — `sqliteHandle.db` is typed
-// as a non-optional `DatabaseSync` and `openObjstore` accepts it
-// without a non-null assertion.
+// only install where the optional peer deps aren't present. Explicit
+// branch (not a ternary) so the SQLite path keeps its `SqliteHandle`
+// narrowing — `sqliteHandle.db` is a non-optional `DatabaseSync` that
+// `openObjstore` accepts without a non-null assertion.
 let handle: Handle
 let objstoreHandle: ObjstoreHandle
 let objstoreBanner: string
@@ -232,24 +237,65 @@ async function workspaceExists(tag: string): Promise<boolean> {
 }
 
 // WS fan-out hub: subscriber registry + backpressure-aware send /
-// broadcast (see ./hub.ts). Destructure into the existing names so the
-// handlers / dispatcher / objstore wiring below read unchanged.
+// broadcast (see ./hub.ts).
 const hub = createHub({ peers, maxBufferedBytes: MAX_BUFFERED_BYTES, debug: DEBUG })
-const { send, broadcast, subscribe, unsubscribeAll } = hub
+const { send, broadcast, subscribe, unsubscribeAll, broadcastLocalRaw } = hub
+
+// Cross-instance pub/sub for live broadcasts (see ./pubsub.ts). SQLite
+// mode is single-process by construction so it gets a no-op; Neon mode
+// uses Postgres LISTEN/NOTIFY on a dedicated long-lived Client
+// connection (separate from the HTTP `neon()` callable the queries flow
+// over — LISTEN needs a session-bound socket, the HTTP path is
+// stateless). The bus carries lookup hints, not the full wire payload:
+// the `workspace-state` broadcast's ciphertext alone can exceed the
+// ~8 KB NOTIFY payload cap, so the receiver re-fetches from the shared
+// DB to construct the wire frame. The bus is best-effort fan-out, not a
+// durability layer — the DB itself is the source of truth, and a
+// dropped publish only means peers on other instances miss the live
+// push (they still catch up via the chain on their next subscribe).
+let pubsub: PubSub = createNoopPubSub()
+if (NEON_URL) {
+  // Dynamic import: the Client export lives in the same optional peer
+  // dep as the HTTP `neon()` callable (see ./neon-driver.ts), but the
+  // dep itself is only present on a Neon-mode deploy. The wrapper path
+  // also lets tests swap in a PGlite-backed shim (`tests/pubsub.test.js`).
+  const mod = (await import('./neon-driver.ts')) as unknown as { Client?: NeonClientCtor }
+  if (!mod.Client) {
+    console.error('DATABASE_URL is set but the @neondatabase/serverless Client export is not available.')
+    console.error('Cross-instance broadcasts require the WebSocket-based Client (the HTTP `neon()` callable cannot LISTEN).')
+    console.error('Reinstall the peer dep: pnpm add @neondatabase/serverless')
+    process.exit(1)
+  }
+  const NeonClientImpl = mod.Client
+  pubsub = createNeonPubSub({
+    newClient: () => new NeonClientImpl(NEON_URL),
+    debug: DEBUG,
+  })
+}
 
 // Password gate (see ./auth.ts) — HMAC derivation + the `authenticate`
-// handshake. Destructure into the existing names for the wiring below.
+// handshake.
 const auth = createAuth({ peers, password: CONFIG_PASSWORD, send, debug: DEBUG })
-const { requiresAuth, handleAuthenticate, sendUnauthorized } = auth
+const { requiresAuth, passwordConfigured, handleAuthenticate, sendUnauthorized } = auth
 
 // Triage-sync protocol handlers (see ./sync-handlers.ts). `getNonce`
 // resolves a socket's challenge nonce and is shared with the objstore
 // wiring below; `sendSaveError` is reused by the dispatcher's `busy`
 // inflight-cap NACK path.
 const getNonce = (socket: WebSocket): string | undefined => peers.get(socket)?.challenge
-const { handleSave, handleSubscribe, sendSaveError } = createSyncHandlers({
-  handle, send, broadcast, subscribe, getNonce,
-  requiresAuth, sendUnauthorized, workspaceExists,
+const publishRevision = (tag: string, revisionId: string): void => {
+  pubsub.publish({ kind: 'rev', tag, id: revisionId })
+}
+const publishObjPut = (tag: string, resourceTag: string): void => {
+  pubsub.publish({ kind: 'objput', tag, res: resourceTag })
+}
+const publishObjDeleted = (tag: string, resourceTag: string, version: number): void => {
+  pubsub.publish({ kind: 'objdel', tag, res: resourceTag, ver: version })
+}
+
+const { handleSave, handleSaveRest, handleSubscribe, sendSaveError } = createSyncHandlers({
+  handle, send, broadcast, publishRevision, subscribe, getNonce,
+  requiresAuth, passwordConfigured, sendUnauthorized, workspaceExists,
   // Folds the objstore inventory into the `workspace-subscribed` ack.
   // The objstore store keeps its own richer `Handle`, so we wire the
   // query here where both handles exist rather than coupling
@@ -260,7 +306,9 @@ const { handleSave, handleSubscribe, sendSaveError } = createSyncHandlers({
 
 const { handlers: objstore, restDeps: objstoreRestDeps, startupReap, stopReaper } = initObjstore({
   handle: objstoreHandle, reapIntervalMs: OBJSTORE_REAP_INTERVAL_MS,
-  send, broadcast, getNonce, debug: DEBUG,
+  reapDisabled: OBJSTORE_REAP_DISABLED,
+  send, broadcast, publishObjPut, publishObjDeleted,
+  getNonce, debug: DEBUG,
   // Auth gate for the FIRST objstore-put-begin against a workspace
   // that doesn't yet exist on the server. Mirrors handleSave's gate
   // below; handlers.ts calls this AFTER sig verify so the
@@ -269,10 +317,15 @@ const { handlers: objstore, restDeps: objstoreRestDeps, startupReap, stopReaper
   // `unauthorized` frame and bails on `true`.
   authGate: async (socket, tag) => requiresAuth(socket) && !await workspaceExists(tag),
   sendUnauthorized,
+  // Socket-less analog of `authGate` for the REST put-begin mint: a REST
+  // request can never be operator-authorized, so the gate collapses to
+  // "password configured AND workspace new". A deny routes the client to
+  // its in-band WS put-begin fallback.
+  restPutGate: async (tag) => passwordConfigured && !await workspaceExists(tag),
   // `tokenSecret` is set only when OBJSTORE_TOKEN_SECRET was
   // provided in env (see TOKEN_SECRET resolution above). Omitted
-  // → initObjstore mints a fresh per-process secret (the pre-PR
-  // behaviour, fine for single-replica).
+  // → initObjstore mints a fresh per-process secret (fine for
+  // single-replica).
   ...(TOKEN_SECRET ? { tokenSecret: TOKEN_SECRET } : {}),
 })
 
@@ -289,13 +342,48 @@ const wss = new WebSocketServer({ noServer: true, maxPayload: 4 * 1024 * 1024 })
 // every server object exists.
 const { track, isShuttingDown, install: installLifecycle } = createLifecycle()
 
-// HTTP plane: REST byte-transfer routing + the WS upgrade gate (see
-// ./http.ts). Built after the lifecycle state above because the REST
-// shutdown gate reads `shuttingDown` and the request drain uses
-// `track`. The WS connection handler is wired on `wss` below.
+// The sync protocol this build advertises — emitted as a `server-info` frame
+// right after the challenge on every connection. This is the e2e boot, so it
+// always advertises e2e.
+const SERVER_INFO: ServerInfo = { mode: 'e2e', managed: null }
+
+// Shared per-connection dispatch surface. Both the WS plane
+// (installWsServer below) and the SSE+POST fallback (installSseServer
+// below) drive `setupPeerConnection` with this; one Peer per accepted
+// connection, one message-handler tree.
+const peerConnectionDeps = {
+  peers, serverInfo: SERVER_INFO, send, unsubscribeAll,
+  handleSave, handleSubscribe, handleAuthenticate, sendSaveError, objstore,
+  track, isShuttingDown,
+  maxInflightPerSocket: MAX_INFLIGHT_PER_SOCKET,
+  debug: DEBUG,
+}
+
+// SSE+POST fallback transport (see ./sse-server.ts). The WS upgrade is
+// the preferred path; clients fall back to SSE when `new WebSocket(…)`
+// fails to open (corporate proxies that strip the Upgrade header,
+// hostile network middleboxes, etc.). Same protocol on the wire — only
+// the byte transport differs.
+const sseServer = installSseServer({
+  peerDeps: peerConnectionDeps, isShuttingDown,
+  // Same cap shape as `wss` (no explicit per-process cap; OS FD limits
+  // are the upstream bound). 1024 leaves room above the typical web
+  // session count without being a soft DoS hammer.
+  maxSessions: 1024,
+  // Mirror the WS `maxPayload` so the SSE plane can't accept frames
+  // the WS plane would reject.
+  maxBodyBytes: 4 * 1024 * 1024,
+  debug: DEBUG,
+})
+
+// HTTP plane: REST byte-transfer routing + SSE fallback + the WS
+// upgrade gate (see ./http.ts). Built after the lifecycle state above
+// because the REST shutdown gate reads `shuttingDown` and the request
+// drain uses `track`. The WS connection handler is wired on `wss`
+// below.
 const httpServer = createHttpServer({
-  wss, restDeps: objstoreRestDeps, isOriginAllowed,
-  isShuttingDown, track,
+  wss, restDeps: objstoreRestDeps, sseServer, serverInfo: SERVER_INFO, isOriginAllowed,
+  isShuttingDown, track, handleSaveRest,
   restPutIdleTimeoutMs: REST_PUT_IDLE_TIMEOUT_MS, debug: DEBUG,
 })
 
@@ -303,11 +391,8 @@ const httpServer = createHttpServer({
 // sweep (see ./ws-server.ts). Returns the heartbeat timer so shutdown
 // can clear it.
 const { heartbeatTimer } = installWsServer({
-  wss, peers, send, unsubscribeAll,
-  handleSave, handleSubscribe, handleAuthenticate, sendSaveError, objstore,
-  track, isShuttingDown,
-  maxInflightPerSocket: MAX_INFLIGHT_PER_SOCKET, heartbeatIntervalMs: HEARTBEAT_INTERVAL_MS,
-  debug: DEBUG,
+  wss, heartbeatIntervalMs: HEARTBEAT_INTERVAL_MS,
+  ...peerConnectionDeps,
 })
 
 httpServer.on('listening', () => {
@@ -323,12 +408,40 @@ httpServer.on('listening', () => {
   // doesn't claim a misleading DB_PATH under Neon, or a misleading
   // OBJSTORE_DIR under Vercel Blob.
   const dbBanner = NEON_URL ? 'db: neon-postgres' : `db: ${DB_PATH}`
-  console.log(`DeepView triage-sync server: ws://${HOST}:${boundPort}${WS_UPGRADE_PATH} http://${HOST}:${boundPort}/api/objstore/{workspaceTag}/{resourceTag} (${dbBanner}, ${objstoreBanner})`)
+  console.log(`DeepView triage-sync server: ws://${HOST}:${boundPort}${WS_UPGRADE_PATH} (sse fallback http://${HOST}:${boundPort}${SSE_OPEN_PATH}) http://${HOST}:${boundPort}/api/objstore/{workspaceTag}/{resourceTag} (${dbBanner}, ${objstoreBanner})`)
+})
+
+// Cross-instance bus receiver (see ./bus-receiver.ts): a remote NOTIFY
+// lands here, we re-fetch any data the bus payload only hinted at,
+// then broadcast to local peers via `broadcastLocalRaw`. Extracted so
+// the rev / objput / objdel mapping (including the keyframe boolean
+// coercion and the `objectMetaWire` shape) is testable without the
+// full server bring-up.
+const onBusMessage = createBusReceiver({
+  handle, objstoreHandle, broadcastLocalRaw, debug: DEBUG,
+})
+
+// Kick off the LISTEN loop in the background. `pubsub.start` resolves
+// only after the FIRST successful connect, and the internal reconnect
+// loop retries indefinitely on transport / LISTEN failure — awaiting
+// it here would convert a transient Neon WS hiccup at boot into a
+// server that never binds (and a `.catch` that never runs). Instead
+// the server binds immediately and the bus comes up async; publishes
+// during the down window drop silently (best-effort semantics
+// documented in pubsub.ts). The SQLite no-op resolves immediately,
+// so the behaviour is identical in that mode.
+void pubsub.start(onBusMessage).catch((err) => {
+  console.warn('pubsub: startup error:', errStack(err))
 })
 
 // App-specific shutdown step (run after the in-flight drain), wired
 // into the lifecycle teardown below.
 const closeDb = async (): Promise<void> => {
+  // Stop the bus first so a publish from a still-draining handler
+  // can't fire into a half-closed Client. The in-flight drain runs
+  // before this (see lifecycle.ts), so by here all `broadcast` →
+  // `publish*` calls are settled.
+  try { await pubsub.stop() } catch (err) { console.warn('pubsub close error:', errMsg(err)) }
   // objstoreHandle has no close(): SQLite shares this DatabaseSync and
   // Neon has no persistent connection; `handle.close()` covers both.
   try { await handle.close() } catch (err) { console.warn('DB close error:', errMsg(err)) }
@@ -338,16 +451,36 @@ const closeDb = async (): Promise<void> => {
 // and the heartbeat timer all exist.
 installLifecycle({
   httpServer, wss, heartbeatTimer, stopReaper,
+  sseSessions: sseServer.sessions,
+  sseKeepaliveTimer: sseServer.keepaliveTimer,
   closeDb,
 })
 
 // Bind only after the startup orphan sweep finishes — otherwise a
 // fresh boot could serve traffic against tags whose on-disk state
-// still has residue from a prior crash. Top-level await is fine
-// for an entry-point ESM module (no other module imports this for
-// its exports — the side effect IS the program). `startupReap`
-// already resolves on any error (the reaper's own catch logs the
-// failure unconditionally and returns void), so no outer `.catch`
-// is needed here.
+// still has residue from a prior crash. `startupReap` already
+// resolves on any error (the reaper's own catch logs the failure
+// unconditionally and returns void), so no outer `.catch` is
+// needed here.
 await startupReap
-httpServer.listen(PORT, HOST)
+
+// Bind the HTTP/WS plane on the configured PORT/HOST. Exported so a
+// launcher (server-e2e/cli.js — the triage-server bin) or any `import`er can
+// start serving. The top-level `await startupReap` above means the server
+// is fully ready — DB open, DDL bootstrapped, objstore reaper swept — by
+// the time the import resolves.
+export function start(): void {
+  httpServer.listen(PORT, HOST)
+}
+
+export { httpServer, wss }
+
+// Library mode: when this module is `import`ed (rather than run as the
+// entry script) skip the auto-start so consumers can own the bind — e.g.
+// wrap CF Access / framework-preset shims around the assembled
+// `httpServer`, or just call `start()` when ready. Direct invocation via
+// `node server-e2e/index.ts` (or the `triage-server` bin) still listens.
+if (import.meta.main) {
+  start()
+}
+

package/{server → server-e2e}/lifecycle.ts

@@ -7,14 +7,24 @@
 
 import type { Server } from 'node:http'
 import type { WebSocketServer } from 'ws'
+import type { SseSession } from './sse-session.ts'
 import { errStack } from './util.ts'
 
 export type ShutdownDeps = {
   httpServer: Server
   wss: WebSocketServer
   heartbeatTimer: ReturnType<typeof setInterval>
+  // The SSE keepalive-sweep timer (server-e2e/sse-server.ts). Cleared on
+  // shutdown alongside `heartbeatTimer` so a tick can't write a keepalive
+  // comment to a session the close loop below is already tearing down.
+  sseKeepaliveTimer: ReturnType<typeof setInterval>
   // Stops the periodic reaper AND awaits any in-flight sweep.
   stopReaper: () => Promise<void>
+  // Live SSE+POST session iterator (mirrors `wss.clients` for the SSE
+  // fallback transport). Walked alongside `wss.clients` to send the
+  // 1001 close frame and apply the terminate-grace timer to both
+  // transports uniformly.
+  sseSessions: () => Iterable<SseSession>
   // App-specific teardown, run AFTER the in-flight drain: close the DB.
   // Swallows its own errors (a failed close shouldn't abort the exit).
   closeDb: () => Promise<void>
@@ -40,7 +50,12 @@ export function createLifecycle(): Lifecycle {
   const inFlight = new Set<Promise<unknown>>()
   function track(promise: Promise<unknown>): void {
     inFlight.add(promise)
-    promise.finally(() => inFlight.delete(promise))
+    // Trailing `.catch(() => {})` swallows the rejection that `.finally`
+    // propagates through its returned promise — without it, a tracked
+    // handler that rejects (or whose caller's catch handler itself
+    // throws) trips the `unhandledRejection` catchall below and crashes
+    // the process via `fireShutdown(1)`.
+    promise.finally(() => inFlight.delete(promise)).catch(() => {})
   }
   let shuttingDown = false
   // Live exit code the in-progress shutdown will pass to `process.exit`.
@@ -51,7 +66,7 @@ export function createLifecycle(): Lifecycle {
   let pendingExitCode = 0
 
   function install(deps: ShutdownDeps): void {
-    const { httpServer, wss, heartbeatTimer, stopReaper, closeDb } = deps
+    const { httpServer, wss, heartbeatTimer, sseKeepaliveTimer, stopReaper, sseSessions, closeDb } = deps
 
     async function shutdown(exitCode: number = 0): Promise<void> {
       // Re-entry: don't restart the teardown, but escalate the pending
@@ -66,9 +81,9 @@ export function createLifecycle(): Lifecycle {
       shuttingDown = true
       pendingExitCode = exitCode
       console.log('Shutting down…')
-      // Stop the heartbeat so a tick can't fire mid-shutdown and ping a
-      // socket the close-loop below already started tearing down.
-      clearInterval(heartbeatTimer)
+      // Stop both periodic timers (WS heartbeat + SSE keepalive) so neither
+      // fires mid-shutdown against a peer the close-loop is tearing down.
+      for (const timer of [heartbeatTimer, sseKeepaliveTimer]) clearInterval(timer)
       // Send a 1001 (going away) close frame to every open socket BEFORE
       // shutting the listener. Lets clients distinguish a server-initiated
       // graceful shutdown from a network drop, so they can skip their
@@ -78,6 +93,13 @@ export function createLifecycle(): Lifecycle {
       for (const socket of wss.clients) {
         try { socket.close(1001, 'Server shutting down') } catch {}
       }
+      // Same close frame on every SSE+POST session — the adapter
+      // translates `close(1001, …)` into a structured `event: close`
+      // record on the SSE stream so the client transport can read the
+      // code and skip its reconnect backoff (parity with the WS path).
+      for (const session of sseSessions()) {
+        try { session.close(1001, 'Server shutting down') } catch {}
+      }
       // Force-terminate any client that doesn't ack the close frame
       // within a short grace window. `wss.close()` waits for every client
       // to emit `'close'`, and `ws` only TCP-RSTs unresponsive peers
@@ -92,6 +114,15 @@ export function createLifecycle(): Lifecycle {
             try { socket.terminate() } catch {}
           }
         }
+        // SSE sessions are tracked separately from `wss.clients`; apply
+        // the same terminate-grace policy so a stranded SSE response
+        // can't pin the HTTP keep-alive shutdown branch below.
+        for (const session of sseSessions()) {
+          const rs = session.readyState
+          if (rs === session.OPEN || rs === session.CLOSING) {
+            try { session.terminate() } catch {}
+          }
+        }
         // Same grace for HTTP keep-alive sockets that didn't respect the
         // `Connection: close` hint, which would otherwise hold
         // `httpServer.close()` until their TCP timeout.