@preventive/triage 1.0.0-alpha.3 → 1.0.0-alpha.5

package/server/objstore/rest.ts

@@ -41,7 +41,9 @@ import {
 } from './store.ts'
 import type { LiveReader } from './blob.ts'
 import { type TokenSecret, extractBearer, verifyToken } from './tokens.ts'
-import { errStack } from '../util.ts'
+import { deny, denyConflict } from './rest-deny.ts'
+import { handleRestMint } from './rest-mint.ts'
+import { debugId, debugTag, errMsg, errStack } from '../util.ts'
 
 // Server-side fault codes that should surface as 500 `io-error`
 // rather than 400 `aborted`. `pipeline(req, ws)` rejects with the
@@ -66,6 +68,18 @@ export type ObjstoreRestDeps = {
   // workspace_object for the full metadata (version, hash, length,
   // signature). SQLite mode passes a no-op.
   publishObjPut: (tag: string, resourceTag: string) => void
+  // Cross-instance pub/sub for objstore-deleted — fired alongside the local
+  // `broadcast` after a successful REST delete mint, so peers on OTHER
+  // instances drop the resource in real time. Carries (tag, resourceTag,
+  // version) inline (the row is gone post-delete). SQLite mode passes a no-op.
+  publishObjDeleted: (tag: string, resourceTag: string, version: number) => void
+  // New-workspace operator gate for the REST put-begin mint — the
+  // connection-independent analog of the WS path's `authGate`. Returns
+  // `true` to DENY (a password is configured AND the workspace is
+  // never-before-seen), which routes the client to its in-band WS
+  // put-begin fallback (REST has no socket auth state to consult).
+  // No-config default is open (never deny), matching the WS authGate.
+  restPutGate: (workspaceTag: string) => Promise<boolean>
   debug: boolean
 }
 
@@ -116,34 +130,21 @@ export function matchRoute(url: string | undefined): RouteMatch | null {
   return { tag: tag!, resourceTag: resourceTag! }
 }
 
-function deny(res: ServerResponse, status: number, body: string): void {
-  // Uniform `{ error: <reason> }` JSON envelope for every failure so
-  // clients parse one shape. Status + reason are NOT intentionally
-  // indistinguishable across causes — 401/404/405/410/411/500 each map
-  // to a documented reason in server/README.md and the client decides
-  // recovery from the code. Probe-distinguishing defense isn't a goal:
-  // every reason is reachable only after the route + bearer-token check
-  // passes (or as 401/404 from the public surface), so a probe gains no
-  // signal it couldn't otherwise enumerate.
-  res.writeHead(status, { 'content-type': 'application/json' })
-  res.end(JSON.stringify({ error: body }))
-}
-
-// Variant of `deny` that augments the JSON envelope with the live
-// row's `currentVersion` + `currentIncarnation` so a REST PUT 409 lets
-// the caller rebase onto the right precondition token. Without this the
-// client only learns the slot is occupied — not at what (version,
-// incarnation) — and retries blindly against a non-empty slot, looping
-// indefinitely against a live row. Symmetric with the WS plane's
-// `objstore-conflict` envelope.
-function denyConflict(res: ServerResponse, currentVersion: number | null, currentIncarnation: string | null): void {
-  res.writeHead(409, { 'content-type': 'application/json' })
-  res.end(JSON.stringify({ error: 'conflict', currentVersion, currentIncarnation }))
-}
-
 export async function handleRest(deps: ObjstoreRestDeps, req: IncomingMessage, res: ServerResponse): Promise<void> {
   const route = matchRoute(req.url)
   if (!route) { deny(res, 404, 'not-found'); return }
+  // POST = REST mint (fetch or put-begin, by body `op`; signature-authed
+  // via the JSON body, no bearer token). Dispatched before the bearer-token
+  // gate below, which guards the token-authed GET/PUT byte transfers.
+  if (req.method === 'POST') {
+    try { await handleRestMint(deps, req, res, route) }
+    catch (err: unknown) {
+      if (deps.debug) console.warn('objstore POST error:', errStack(err))
+      if (res.headersSent) res.destroy()
+      else deny(res, 500, 'internal')
+    }
+    return
+  }
   const token = extractBearer(req.headers['authorization'])
   if (!token) { deny(res, 401, 'unauthorized'); return }
   const payload = verifyToken(deps.secret, token)
@@ -431,7 +432,10 @@ async function runUploadAndCommit(
 type GetOpened =
   | { reason: 'ok'; reader: LiveReader }
   | { reason: 'not-found' }
-  | { reason: 'unavailable' }
+  // `detail` is a short non-sensitive cause tag (backend sub-reason +
+  // content-hash prefix) the GET handler logs so a 503 is diagnosable —
+  // every byte-side failure collapses to the same wire 503 otherwise.
+  | { reason: 'unavailable'; detail: string }
 
 async function openLiveSnapshot(
   deps: ObjstoreRestDeps, route: RouteMatch, payload: { ver: number; inc: string },
@@ -448,17 +452,27 @@ async function openLiveSnapshot(
   // returns a pinned fd; for the Vercel backend a fetch-backed stream.)
   const live = await deps.handle.selectLiveOne.get(route.tag, route.resourceTag)
   if (!live || live.version !== payload.ver || live.incarnation !== payload.inc) return { reason: 'not-found' }
+  // Tag the content hash into every `unavailable` detail so an operator
+  // can go check the byte store directly for THIS blob (gone → reaper /
+  // deletion; present → transient read fault).
+  const hashTag = `hash=${debugId(live.content_hash)}`
   let opened
   try { opened = await deps.handle.blob.openLiveReader(route.tag, live.content_hash) }
-  catch { return { reason: 'unavailable' } }
-  if (!opened.ok) return { reason: opened.reason }
+  // Length-cap the thrown error text: today a non-BlobNotFound SDK throw
+  // (BlobServiceNotAvailable / store-not-found) carries no credential
+  // (the RW token rides the Authorization header, never `.message`), but
+  // a future SDK could embed a signed URL / token fragment — bound the
+  // log line so it can't dump one verbatim. Mirrors the `.slice(0, 200)`
+  // cap used on SDK error text in blob-vercel.ts.
+  catch (err) { return { reason: 'unavailable', detail: `open-threw ${hashTag} ${String(errMsg(err)).slice(0, 200)}` } }
+  if (!opened.ok) return { reason: 'unavailable', detail: `${opened.detail ?? 'backend'} ${hashTag}` }
   // Size mismatch between the live row and the on-storage bytes
   // is a transient inconsistency — reaper will reconcile. Close
   // the reader before returning so we don't leak the fd / fetch
   // reader. PR #4 review H8.
   if (opened.reader.size !== live.content_length) {
     await opened.reader.close().catch(() => {})
-    return { reason: 'unavailable' }
+    return { reason: 'unavailable', detail: `size-mismatch row=${live.content_length} blob=${opened.reader.size} ${hashTag}` }
   }
   return { reason: 'ok', reader: opened.reader }
 }
@@ -478,8 +492,19 @@ async function handleRestGet(
   // If the live row is there but the bytes are missing / wrong size,
   // it's a transient inconsistency the reaper will sort out — 503
   // (vs 404) tells the client this is a server-side state, not a
-  // "the resource truly isn't there" answer.
-  if (opened.reason === 'unavailable') { deny(res, 503, 'unavailable'); return }
+  // "the resource truly isn't there" answer. Log the cause
+  // UNCONDITIONALLY (not behind `debug`): a 503 means a live row whose
+  // bytes can't be served, and the wire response can't distinguish a
+  // permanent loss (reaper GC'd referenced bytes) from a transient read
+  // fault. `detail` carries the backend sub-reason + content-hash prefix
+  // so an operator can tell which — the only server-side breadcrumb for
+  // the "all data turned into 503" failure. (Volume is bounded: a 503 is
+  // an error path; a workspace-wide outage is exactly when these are
+  // wanted.)
+  if (opened.reason === 'unavailable') {
+    console.warn(`objstore-get: 503 unavailable ${debugTag(route.tag)}/${route.resourceTag.slice(0, 8)}… v${payload.ver} ${opened.detail}`)
+    deny(res, 503, 'unavailable'); return
+  }
   res.writeHead(200, {
     'content-type': 'application/octet-stream',
     'content-length': String(opened.reader.size),

package/server/objstore/sign.ts

@@ -10,6 +10,18 @@ import { isValidIncarnation } from './store.ts'
 const OBJSTORE_PUT_DOMAIN = 'deepview-objstore.v1.put'
 const OBJSTORE_DELETE_DOMAIN = 'deepview-objstore.v1.delete'
 const OBJSTORE_FETCH_DOMAIN = 'deepview-objstore.v1.fetch'
+// REST fetch-mint domain — MUST match the client's FETCH_REST_DOMAIN
+// (client/sync/objstore-crypto.ts). Distinct from OBJSTORE_FETCH_DOMAIN so
+// a WS-fetch signature can't be replayed against the REST mint endpoint.
+const OBJSTORE_FETCH_REST_DOMAIN = 'deepview-objstore.v1.fetch-rest'
+// REST put-begin domain — MUST match the client's PUT_REST_DOMAIN. Distinct
+// from OBJSTORE_PUT_DOMAIN so a WS put-begin signature can't be replayed
+// against the REST mint endpoint.
+const OBJSTORE_PUT_REST_DOMAIN = 'deepview-objstore.v1.put-rest'
+// REST delete domain — MUST match the client's DELETE_REST_DOMAIN. Distinct
+// from OBJSTORE_DELETE_DOMAIN so a WS delete signature can't be replayed
+// against the REST mint endpoint.
+const OBJSTORE_DELETE_REST_DOMAIN = 'deepview-objstore.v1.delete-rest'
 
 // Wire shapes the verifiers accept. Fields land here post-
 // `JSON.parse`, so every value starts life as `unknown` — strict
@@ -95,6 +107,38 @@ function canonicalObjstoreFetch(msg: ObjstoreFetchMsg, connectionNonce: string):
   ].join('\n'))
 }
 
+// REST fetch-mint canonical. Binds a client epoch-ms timestamp (string-
+// encoded to match the client) in place of the connection nonce; the REST
+// handler enforces the freshness window + replay dedup.
+function canonicalObjstoreFetchRest(workspaceTag: string, resourceTag: string, ts: number): Uint8Array<ArrayBuffer> {
+  return encodeUtf8([
+    OBJSTORE_FETCH_REST_DOMAIN,
+    workspaceTag,
+    resourceTag,
+    String(ts),
+  ].join('\n'))
+}
+
+// REST put-begin canonical — the WS `canonicalObjstorePut` fields in the
+// same order/coercion (intOrEmpty / strOrEmpty), under the put-rest domain
+// and binding the client `ts` in place of the connection nonce.
+function canonicalObjstorePutRest(
+  workspaceTag: string, resourceTag: string,
+  prevVersion: number | null, prevIncarnation: string | null,
+  contentHash: string, expectedLength: number, ts: number,
+): Uint8Array<ArrayBuffer> {
+  return encodeUtf8([
+    OBJSTORE_PUT_REST_DOMAIN,
+    workspaceTag,
+    resourceTag,
+    intOrEmpty(prevVersion),
+    strOrEmpty(prevIncarnation),
+    contentHash,
+    String(expectedLength),
+    String(ts),
+  ].join('\n'))
+}
+
 // `Number.isSafeInteger` rather than `Number.isInteger`: JSON numbers
 // are IEEE-754 and integers above 2^53-1 aren't precisely
 // representable. Accepting non-safe integers would let a signed
@@ -162,3 +206,64 @@ export function verifyObjstoreFetchSig(msg: ObjstoreFetchMsg, connectionNonce: u
   if (typeof msg.resourceTag !== 'string') return Promise.resolve(false)
   return verifyObjstoreSig(msg, connectionNonce, (nonce) => canonicalObjstoreFetch(msg, nonce))
 }
+
+// Verify a REST fetch-mint signature. Unlike the WS verifiers this takes
+// the already-validated fields directly (the REST handler parsed +
+// range-checked `ts` and `signature`) rather than a wire `msg` + socket
+// nonce. The workspaceTag IS the Ed25519 public key, so verification is
+// fully self-contained — no session or stored key needed. A throw from
+// the canonical build (lone surrogate, etc.) is treated as a verify
+// failure, never an escaping exception.
+export function verifyObjstoreFetchRestSig(
+  workspaceTag: string, resourceTag: string, ts: number, signature: string,
+): Promise<boolean> {
+  let payload: Uint8Array<ArrayBuffer>
+  try { payload = canonicalObjstoreFetchRest(workspaceTag, resourceTag, ts) }
+  catch { return Promise.resolve(false) }
+  return verifyEd25519(workspaceTag, payload, signature)
+}
+
+// Verify a REST put-begin signature. Same self-contained shape as
+// `verifyObjstoreFetchRestSig` — the caller (rest.ts) has already
+// range-checked the put fields + `ts`. The workspaceTag IS the pubkey.
+export function verifyObjstorePutBeginRestSig(
+  fields: { workspaceTag: string; resourceTag: string; prevVersion: number | null; prevIncarnation: string | null; contentHash: string; expectedLength: number },
+  ts: number, signature: string,
+): Promise<boolean> {
+  let payload: Uint8Array<ArrayBuffer>
+  try {
+    payload = canonicalObjstorePutRest(
+      fields.workspaceTag, fields.resourceTag, fields.prevVersion, fields.prevIncarnation,
+      fields.contentHash, fields.expectedLength, ts,
+    )
+  } catch { return Promise.resolve(false) }
+  return verifyEd25519(fields.workspaceTag, payload, signature)
+}
+
+// REST delete-mint canonical. WS `canonicalObjstoreDelete` fields, under the
+// delete-rest domain, binding the client `ts` in place of the nonce.
+function canonicalObjstoreDeleteRest(
+  workspaceTag: string, resourceTag: string,
+  prevVersion: number | null, prevIncarnation: string | null, ts: number,
+): Uint8Array<ArrayBuffer> {
+  return encodeUtf8([
+    OBJSTORE_DELETE_REST_DOMAIN,
+    workspaceTag,
+    resourceTag,
+    intOrEmpty(prevVersion),
+    strOrEmpty(prevIncarnation),
+    String(ts),
+  ].join('\n'))
+}
+
+// Verify a REST delete-mint signature. Self-contained (workspaceTag IS the
+// pubkey); the caller (rest.ts) has range-checked `ts` + the prev pair.
+export function verifyObjstoreDeleteRestSig(
+  fields: { workspaceTag: string; resourceTag: string; prevVersion: number | null; prevIncarnation: string | null },
+  ts: number, signature: string,
+): Promise<boolean> {
+  let payload: Uint8Array<ArrayBuffer>
+  try { payload = canonicalObjstoreDeleteRest(fields.workspaceTag, fields.resourceTag, fields.prevVersion, fields.prevIncarnation, ts) }
+  catch { return Promise.resolve(false) }
+  return verifyEd25519(fields.workspaceTag, payload, signature)
+}

package/server/sse-server.ts

@@ -52,6 +52,24 @@ import { errMsg, randomId } from './util.ts'
 // path so the same `location` block routes both.
 export const SSE_OPEN_PATH = '/api/sync/sse'
 
+// Cadence of the server-driven keepalive sweep: every tick we write a `:`
+// comment to each open session's downstream so intermediary proxies don't
+// idle-close it (nginx et al. default to a ~60s read timeout). This is the
+// server's own liveness upkeep — the client no longer POSTs a periodic ping
+// (which forced a stream takeover every tick).
+//
+// Reaping model (replaces the old POST-driven idle timer): a session is
+// dropped on its downstream response `close` — clean disconnect, or a
+// half-open socket the per-session TCP keepalive forces closed (see
+// SseSession.SOCKET_KEEPALIVE_MS) — NOT by this sweep. We intentionally
+// trust connection-level liveness. The one topology this can't see is a
+// buffering / TLS-terminating proxy that holds the upstream open after the
+// real client vanished (keepalive then probes the proxy hop, not the
+// client); such a session lingers until `maxSessions`, the hard backstop.
+// This is the same exposure the WS heartbeat already has (its ping only
+// proves the proxy↔server hop too), not a new class of leak.
+const KEEPALIVE_SWEEP_MS = 30_000
+
 export type SseServerDeps = {
   // The WS dispatch is the cohesive unit; SSE just provides another
   // transport into it. Closure over the same handler / hub / objstore
@@ -70,12 +88,6 @@ export type SseServerDeps = {
   // the per-frame budget is the same as the WS plane after the
   // dispatcher splits them.
   maxBodyBytes: number
-  // Idle timeout for a session with no inbound POSTs. Detects the
-  // wandered-off browser tab the WS heartbeat sweep handles via
-  // ping/pong on real sockets. The client's JSON ping/pong heartbeat
-  // (every 15s) is the steady-state liveness signal; this is the
-  // hard ceiling.
-  sessionIdleMs: number
   debug: boolean
 }
 
@@ -86,6 +98,9 @@ export type SseServer = {
   // Iterates active sessions. Lifecycle's graceful-shutdown loop
   // reads this to close SSE sessions alongside WS clients.
   sessions: () => Iterable<SseSession>
+  // The keepalive-sweep timer. Lifecycle clears it on shutdown (parity
+  // with the WS heartbeat timer) so a tick can't fire mid-teardown.
+  keepaliveTimer: ReturnType<typeof setInterval>
 }
 
 // Inbound POST body. Every field optional — an empty-body POST is a
@@ -98,7 +113,7 @@ type SseBody = {
 }
 
 export function installSseServer(deps: SseServerDeps): SseServer {
-  const { peerDeps, isShuttingDown, maxSessions, maxBodyBytes, sessionIdleMs, debug } = deps
+  const { peerDeps, isShuttingDown, maxSessions, maxBodyBytes, debug } = deps
 
   // Active SSE sessions, keyed by the random session id `createSession`
   // mints on the first POST that lacks a `?id=` (or whose id this
@@ -108,26 +123,9 @@ export function installSseServer(deps: SseServerDeps): SseServer {
   // mint a fresh session instead, so a multi-replica deployment doesn't
   // require sticky LB routing to recover.
   const sessions = new Map<string, SseSession>()
-  // Per-session idle timer handle. Reset on every inbound POST; fires
-  // after `sessionIdleMs` of silence to close a stranded session.
-  const idleTimers = new Map<string, ReturnType<typeof setTimeout>>()
-
-  function armIdleTimer(sid: string, session: SseSession): void {
-    clearTimeout(idleTimers.get(sid))
-    if (sessionIdleMs <= 0) return
-    const t = setTimeout(() => {
-      if (debug) console.warn(`sse: session ${sid.slice(0, 8)}… idle ${sessionIdleMs}ms → close`)
-      try { session.terminate() } catch {}
-    }, sessionIdleMs)
-    t.unref?.()
-    idleTimers.set(sid, t)
-  }
 
   function dropSession(sid: string): void {
     sessions.delete(sid)
-    const t = idleTimers.get(sid)
-    if (t) clearTimeout(t)
-    idleTimers.delete(sid)
   }
 
   function writeSseHeaders(res: ServerResponse): void {
@@ -149,7 +147,7 @@ export function installSseServer(deps: SseServerDeps): SseServer {
     res.write('retry: 1000\n\n')
   }
 
-  function createSession(res: ServerResponse, req: HttpRequest): { sid: string; session: SseSession } | null {
+  function createSession(res: ServerResponse, req: HttpRequest): SseSession | null {
     if (sessions.size >= maxSessions) {
       if (debug) console.warn(`sse: refused open — sessions ${sessions.size} >= ${maxSessions}`)
       return null
@@ -158,7 +156,6 @@ export function installSseServer(deps: SseServerDeps): SseServer {
     const sid = randomId()
     const session = new SseSession(res)
     sessions.set(sid, session)
-    armIdleTimer(sid, session)
     session.on('close', () => { dropSession(sid) })
     // Announce the continuation token BEFORE the dispatcher emits its
     // `challenge` frame so the client latches the id first and the
@@ -171,7 +168,7 @@ export function installSseServer(deps: SseServerDeps): SseServer {
     // `setupPeerConnection`'s first action is the protocol `challenge`
     // frame, on the default-named SSE channel.
     setupPeerConnection(session as unknown as WebSocket, req, peerDeps)
-    return { sid, session }
+    return session
   }
 
   // Drives a POST body's `password` and `frames` through the shared
@@ -268,19 +265,16 @@ export function installSseServer(deps: SseServerDeps): SseServer {
       // through to createSession with `res` still header-virgin, so
       // the new session can writeSseHeaders without ERR_HTTP_HEADERS_SENT.
       let session: SseSession | null = null
-      let sid: string | null = null
       if (sidFromUrl) {
         const existing = sessions.get(sidFromUrl)
         if (existing && existing.readyState === existing.OPEN && existing.attachResponse(res)) {
           writeSseHeaders(res)
           session = existing
-          sid = sidFromUrl
-          armIdleTimer(sid, session)
         }
       }
       if (!session) {
-        const created = createSession(res, req)
-        if (!created) {
+        session = createSession(res, req)
+        if (!session) {
           // Cap exceeded; createSession already logged. Response
           // headers not yet written by writeSseHeaders, so send a
           // 503 JSON instead.
@@ -288,8 +282,6 @@ export function installSseServer(deps: SseServerDeps): SseServer {
           res.end(JSON.stringify({ error: 'too-many-sessions' }))
           return
         }
-        session = created.session
-        sid = created.sid
       }
       dispatchBody(session, body)
       // Do NOT res.end() — the response stays open as the session's
@@ -323,7 +315,22 @@ export function installSseServer(deps: SseServerDeps): SseServer {
     return true
   }
 
-  return { handle, sessions: () => sessions.values() }
+  // Server-driven keepalive sweep. Writes a `:` comment to every open
+  // session's downstream so proxies don't idle-close it. `unref` so it can't
+  // by itself hold the event loop open (parity with the WS heartbeat timer);
+  // skipped during shutdown so a tick can't write to a session the close
+  // loop is tearing down. Dead-session reaping is the response `close` event
+  // (see SseSession.wireResponse + the per-session TCP keepalive), NOT this
+  // sweep — so a half-open client is dropped without ever POSTing.
+  const keepaliveTimer = setInterval(() => {
+    if (isShuttingDown()) return
+    for (const session of sessions.values()) {
+      try { session.ping() } catch {}
+    }
+  }, KEEPALIVE_SWEEP_MS)
+  keepaliveTimer.unref?.()
+
+  return { handle, sessions: () => sessions.values(), keepaliveTimer }
 }
 
 // Bare-bones query parse for `id=<base64url>`. Avoids URLSearchParams

package/server/sse-session.ts

@@ -28,6 +28,20 @@ import { EventEmitter } from 'node:events'
 import type { Buffer } from 'node:buffer'
 import type { ServerResponse } from 'node:http'
 
+// TCP keepalive idle delay for the downstream socket. With the client no
+// longer POSTing a periodic ping (see client/sync/socket-transport.ts), a
+// QUIET session whose client vanished without a FIN (crash, NAT/idle drop)
+// has no application-level liveness signal — so we lean on the kernel:
+// after this much idle the kernel starts probing, and a dead half-open
+// socket surfaces as a `close`/`error` here. Node's `setKeepAlive` sets
+// only TCP_KEEPIDLE (the delay to the FIRST probe), not the probe
+// interval/count — so full teardown is this delay PLUS the OS's
+// TCP_KEEPINTVL × TCP_KEEPCNT (~minutes on Linux defaults), still bounded
+// and far below the kernel's hours-long default-off behaviour. `maxSessions`
+// is the hard backstop. Behind a TLS-terminating / buffering proxy this
+// probes the proxy hop, not the client — see the reaping note in sse-server.ts.
+const SOCKET_KEEPALIVE_MS = 30_000
+
 export class SseSession extends EventEmitter {
   static readonly CONNECTING = 0
   static readonly OPEN = 1
@@ -62,6 +76,10 @@ export class SseSession extends EventEmitter {
   // spurious session 'error' that operators read as a real transport
   // failure on a healthy session.
   private wireResponse(res: ServerResponse): void {
+    // Probe half-open downstreams at the kernel level (see SOCKET_KEEPALIVE_MS).
+    // A failed probe trips the `close`/`error` handlers below, which is how a
+    // dead-but-quiet SSE client is reaped now that there's no client ping.
+    try { res.socket?.setKeepAlive(true, SOCKET_KEEPALIVE_MS) } catch {}
     res.on('close', () => {
       if (res !== this.currentRes) return  // current-response guard (see above)
       if (this.readyState === SseSession.CLOSED) return
@@ -142,9 +160,8 @@ export class SseSession extends EventEmitter {
   // double-emit), which means without the explicit emit here neither
   // sse-server's dropSession cleanup nor setupPeerConnection's
   // unsubscribeAll/peers.delete would run on any server-initiated
-  // teardown — sessions / hub.subscribers / idleTimers would leak per
-  // close. The wireResponse guard then ensures the later async fire
-  // is a no-op.
+  // teardown — the sessions map / hub.subscribers would leak per close.
+  // The wireResponse guard then ensures the later async fire is a no-op.
   close(code?: number, reason?: string): void {
     if (this.readyState === SseSession.CLOSED) return
     const res = this.currentRes
@@ -173,11 +190,14 @@ export class SseSession extends EventEmitter {
     this.emit('close')
   }
 
-  // The heartbeat sweep ping()s every WS client to detect dead sockets
-  // via the unanswered-pong path. SSE has no `pong` equivalent, so we
-  // write a comment line that keeps the channel alive across proxies
-  // without expecting a reply. The per-session idle timeout in
-  // sse-server.ts owns the dead-client detection.
+  // Server-driven keepalive, called on the SSE keepalive sweep in
+  // sse-server.ts. SSE has no `pong` equivalent, so we write a `:` comment
+  // line — ignored by the client parser — that keeps the downstream from
+  // being idle-closed by intermediary proxies (nginx et al. default to a
+  // ~60s read timeout). Dead-client detection is the response `close` event
+  // (clean disconnect, or a half-open socket the TCP keepalive in
+  // `wireResponse` forces closed), NOT this write: a `:`-comment write to a
+  // half-open socket just buffers, it doesn't synchronously throw.
   ping(): void {
     if (this.readyState !== SseSession.OPEN) return
     const res = this.currentRes