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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@preventive/triage",
-  "version": "1.0.0-alpha.0",
+  "version": "1.0.0-alpha.1",
   "description": "Client & relay server for triaging of automated reports",
   "license": "MIT",
   "author": {
@@ -33,6 +33,7 @@
   },
   "files": [
     "server/auth.ts",
+    "server/bus-receiver.ts",
     "server/config.ts",
     "server/db-neon.ts",
     "server/db-revision-sql.ts",
@@ -43,6 +44,7 @@
     "server/index.ts",
     "server/lifecycle.ts",
     "server/neon-driver.ts",
+    "server/npm-proxy.ts",
     "server/objstore/blob-fs.ts",
     "server/objstore/blob-vercel.ts",
     "server/objstore/blob.ts",
@@ -57,7 +59,10 @@
     "server/objstore/tokens.ts",
     "server/origin.ts",
     "server/peer.ts",
+    "server/pubsub.ts",
     "server/sign.ts",
+    "server/sse-server.ts",
+    "server/sse-session.ts",
     "server/static.ts",
     "server/sync-handlers.ts",
     "server/util.ts",

package/server/auth.ts

@@ -76,6 +76,17 @@ export function createAuth(deps: {
   }
   function handleAuthenticate(socket: WebSocket, msg: AuthenticateMsg): void {
     if (typeof msg.password !== 'string' || msg.password.length === 0 || msg.password.length > MAX_AUTH_PASSWORD_LEN) return
+    // Already-authorized short-circuit. The SSE plane carries
+    // `body.password` on every POST (sse-server.ts:dispatchBody
+    // synthesises a fresh `authenticate` frame each time), so re-
+    // emitting `authenticated` per POST would chatter the wire AND
+    // re-fire triage-sync's `authenticated` consumer hook (its "kick
+    // deferred sends" path) on every flush. The wire signal is needed
+    // exactly once per `unauthorized → authorized` transition; after
+    // that, the client already knows. WS plane unaffected (sends
+    // authenticate at most once per socket per the runAuthFlow guard
+    // in client/sync/socket-transport.ts).
+    if (isAuthorized(socket)) return
     // No-config short-circuit: when not gating, treat any authenticate
     // as success so a client can cache + replay its password on
     // reconnect even against an un-gated server (wire shape stays

package/server/bus-receiver.ts

@@ -0,0 +1,95 @@
+// Cross-instance bus receiver: maps a `BusMessage` envelope (lookup
+// hint + sender from the Postgres LISTEN/NOTIFY channel) into a local
+// wire broadcast. Pulled out of `server/index.ts` so the rev / objput /
+// objdel branches — including the keyframe boolean coercion and the
+// `objectMetaWire` shape — are testable without bringing up the whole
+// server.
+//
+// The receiver mirrors the publisher's commit→broadcast→publish
+// ordering, just shifted by the bus round-trip:
+//   1. NOTIFY lands → bus envelope arrives here.
+//   2. For hint-only kinds (rev, objput) re-fetch the row from the
+//      shared DB; for self-contained kinds (objdel) skip the fetch.
+//   3. Broadcast to LOCAL subscribers via `broadcastLocalRaw` with no
+//      `except` — the originator is on a DIFFERENT instance by
+//      construction, so it must NOT be filtered out (the symmetric
+//      same-instance broadcast already happened on the publisher).
+
+import type { Handle as DbHandle } from './db.ts'
+import { type Handle as ObjstoreHandle, getLive, objectMetaWire } from './objstore/store.ts'
+import type { BusMessage } from './pubsub.ts'
+
+export type BusReceiverDeps = {
+  // Read-side of the workspace_revision Handle (the bus uses only
+  // `revisionById`; the publisher path uses the full Handle). Typed
+  // as the broader Handle for ease of wiring at the call site.
+  handle: DbHandle
+  // Read-side of the objstore Handle (used for `getLive` on objput).
+  objstoreHandle: ObjstoreHandle
+  // Local-only fan-out into this instance's subscriber map. The
+  // payload is pre-serialised so the hub can stringify once for N
+  // subscribers (mirrors the existing `broadcast` fast path).
+  broadcastLocalRaw: (tag: string, payload: string) => void
+  debug: boolean
+}
+
+export function createBusReceiver(deps: BusReceiverDeps): (msg: BusMessage) => Promise<void> {
+  const { handle, objstoreHandle, broadcastLocalRaw, debug } = deps
+  return async (msg) => {
+    if (msg.kind === 'rev') {
+      const row = await handle.revisionById.get(msg.tag, msg.id)
+      if (!row) {
+        // Not found is expected when a peer instance published a
+        // revision id that hasn't replicated to this instance yet —
+        // shouldn't happen on a single-primary Neon endpoint, but a
+        // future read-replica deployment could see it transiently.
+        // Drop the broadcast; the client will reconcile via chain
+        // re-pull on its next subscribe.
+        if (debug) console.warn(`pubsub: revision ${msg.id.slice(0, 8)}… not found for ${msg.tag.slice(0, 12)}…`)
+        return
+      }
+      broadcastLocalRaw(msg.tag, JSON.stringify({
+        type: 'workspace-state',
+        workspaceTag: msg.tag,
+        // Mirror `chainForWire`'s strict-boolean coercion in
+        // ./sync-handlers.ts — the DB stores `keyframe` as an integer
+        // (0/1) but the wire contract uses strict `=== true`.
+        revisions: [{ ...row, keyframe: row.keyframe === 1 }],
+      }))
+      return
+    }
+    if (msg.kind === 'objput') {
+      const row = await getLive(objstoreHandle, msg.tag, msg.res)
+      if (!row) {
+        // Possible after a remote put → remote delete sequence where
+        // both NOTIFYs landed by the time we processed the put. The
+        // subsequent objdel NOTIFY will (or has) drive the right
+        // broadcast — skip silently. Also possible under a future
+        // read-replica deployment with replication lag.
+        if (debug) console.warn(`pubsub: objput ${msg.res.slice(0, 8)}… missing for ${msg.tag.slice(0, 12)}…`)
+        return
+      }
+      // Note: `getLive` returns the CURRENT live row, which may be a
+      // strictly NEWER version than the NOTIFY referred to (two
+      // closely-spaced puts on one resourceTag arrive at the receiver
+      // with the DB already showing v2 for both). Broadcasting v2 twice
+      // is sound — client `putHandlers` already absorb same-instance
+      // PUT echoes (rest.ts uses `except: null`), so handlers must be
+      // idempotent on (resourceTag, version) anyway.
+      broadcastLocalRaw(msg.tag, JSON.stringify({
+        type: 'objstore-put',
+        workspaceTag: msg.tag,
+        ...objectMetaWire(row),
+      }))
+      return
+    }
+    // 'objdel' — the row is gone from workspace_object post-commit, so
+    // the bus payload itself IS the wire data; no DB lookup.
+    broadcastLocalRaw(msg.tag, JSON.stringify({
+      type: 'objstore-deleted',
+      workspaceTag: msg.tag,
+      resourceTag: msg.res,
+      version: msg.ver,
+    }))
+  }
+}

package/server/db-neon.ts

@@ -46,7 +46,8 @@ import type { AllStmt, GetStmt, RunStmt } from './db-stmt.ts'
 import { type CommitResult, type Handle, type RevisionInsert, type RevisionRow, isUniqueViolation } from './db.ts'
 import {
   CHAIN_AFTER_SQL, CHAIN_ALL_SQL, CHAIN_FROM_SQL, GATED_INSERT_SQL_PG, HEAD_FOR_SQL,
-  LAST_KEYFRAME_SEQ_SQL, REVISION_EXISTS_SQL, SEQ_OF_ID_SQL, mapRevisionRow, num, numOrNull,
+  LAST_KEYFRAME_SEQ_SQL, REVISION_BY_ID_SQL, REVISION_EXISTS_SQL, SEQ_OF_ID_SQL,
+  mapRevisionRow, num, numOrNull,
 } from './db-revision-sql.ts'
 
 // `num` / `numOrNull` (safe-integer BIGINT coercion) live in the shared
@@ -218,6 +219,14 @@ function buildRevisionExists(sql: NeonSql): GetStmt<[string, string], unknown> {
   return getRowStmt(sql, REVISION_EXISTS_SQL)
 }
 
+function buildRevisionById(sql: NeonSql): GetStmt<[string, string], RevisionRow> {
+  return { get: async (tag, id) => {
+    const rows = await sql(REVISION_BY_ID_SQL, [tag, id]) as Array<Record<string, unknown>>
+    const r = rows[0]
+    return r ? mapRevisionRow(r) : undefined
+  } }
+}
+
 // Atomic commit of a single revision (Neon backend). Wraps the
 // dup-check, head-check and gated INSERT in one pipelined
 // transaction — NO commit-time advisory lock. Cross-replica
@@ -359,6 +368,7 @@ export async function openNeonDb(connectionString: string): Promise<Handle> {
     chainAfterSeq: buildChainSeq(sql, CHAIN_AFTER_SQL),
     chainFromSeq: buildChainSeq(sql, CHAIN_FROM_SQL),
     revisionExists: buildRevisionExists(sql),
+    revisionById: buildRevisionById(sql),
     tryCommit: tryCommitNeon(sql),
     // The serverless HTTP client is stateless — no socket to close.
     // Async no-op so shutdown's `handle.close()` works uniformly

package/server/db-revision-sql.ts

@@ -108,6 +108,15 @@ export const CHAIN_FROM_SQL =
   FROM workspace_revision WHERE workspace_tag = $1 AND seq >= $2 ORDER BY seq ASC`
 export const REVISION_EXISTS_SQL =
   `SELECT 1 AS one FROM workspace_revision WHERE workspace_tag = $1 AND id = $2`
+// Fetch a single revision row by content-addressed id. The cross-instance
+// pubsub (server/pubsub.ts) NOTIFY payload carries only `(tag, revisionId)`
+// because the full `workspace-state` broadcast envelope is bounded by
+// `MAX_CIPHERTEXT_LEN` (2 MiB) and Postgres NOTIFY caps payloads at ~8 KB.
+// The receiver re-fetches the row from this shared table to construct the
+// wire broadcast for its local peers.
+export const REVISION_BY_ID_SQL =
+  `SELECT base, id, keyframe, nonce, ciphertext, signature
+  FROM workspace_revision WHERE workspace_tag = $1 AND id = $2`
 
 // The gated commit INSERT, in `$N` form. One statement folds the
 // dup-check, the head-equals-base check, the server-assigned seq

package/server/db.ts

@@ -60,7 +60,8 @@ import { dirname } from 'node:path'
 import { type AllStmt, type GetStmt, wrapAll, wrapGet } from './db-stmt.ts'
 import {
   CHAIN_AFTER_SQL, CHAIN_ALL_SQL, CHAIN_FROM_SQL, GATED_INSERT_SQL_SQLITE, HEAD_FOR_SQL,
-  LAST_KEYFRAME_SEQ_SQL, REVISION_EXISTS_SQL, SEQ_OF_ID_SQL, mapRevisionRow, toSqlitePlaceholders,
+  LAST_KEYFRAME_SEQ_SQL, REVISION_BY_ID_SQL, REVISION_EXISTS_SQL, SEQ_OF_ID_SQL,
+  mapRevisionRow, toSqlitePlaceholders,
 } from './db-revision-sql.ts'
 
 // `CHECK (keyframe IN (0, 1))` is the value-domain guard on the
@@ -181,6 +182,10 @@ export type Handle = {
   chainAfterSeq: AllStmt<[string, number], RevisionRow>
   chainFromSeq: AllStmt<[string, number], RevisionRow>
   revisionExists: GetStmt<[string, string], unknown>
+  // Single-revision fetch by content-addressed id. The cross-instance
+  // pubsub receiver uses this to assemble a `workspace-state` from a
+  // NOTIFY hint (see `server/pubsub.ts`).
+  revisionById: GetStmt<[string, string], RevisionRow>
   gatedInsert?: GetStmt<[string, string, string | null, number, string, string, string, number], { seq: number }>
   tryCommit: (input: RevisionInsert) => Promise<CommitResult>
   close: () => Promise<void>
@@ -288,6 +293,17 @@ function openDbInner(db: DatabaseSync): SqliteHandle {
     const raw = wrapAll<P, Record<string, unknown>>(db.prepare(toSqlitePlaceholders(query)))
     return { all: async (...args: P) => (await raw.all(...args)).map(mapRevisionRow) }
   }
+  // Reuses `wrapGet` for the prepared statement, then maps the row
+  // through the shared coercion so the returned shape matches `chainFrom`.
+  const revisionByIdStmt: GetStmt<[string, string], RevisionRow> = (() => {
+    const raw = wrapGet<[string, string], Record<string, unknown>>(
+      db.prepare(toSqlitePlaceholders(REVISION_BY_ID_SQL)),
+    )
+    return { get: async (tag, id) => {
+      const row = await raw.get(tag, id)
+      return row ? mapRevisionRow(row) : undefined
+    } }
+  })()
   const handle: SqliteHandle = {
     db,
     headFor: wrapGet<[string], { id: string }>(db.prepare(toSqlitePlaceholders(HEAD_FOR_SQL))),
@@ -297,6 +313,7 @@ function openDbInner(db: DatabaseSync): SqliteHandle {
     chainAfterSeq: chainStmt<[string, number]>(CHAIN_AFTER_SQL),
     chainFromSeq: chainStmt<[string, number]>(CHAIN_FROM_SQL),
     revisionExists: wrapGet<[string, string], unknown>(db.prepare(toSqlitePlaceholders(REVISION_EXISTS_SQL))),
+    revisionById: revisionByIdStmt,
     // SQLite null-safe equality is `IS`; the numbered `?N` form (with
     // reuse) maps `$1`/`$2`/`$3` to repeated positional binds. `RETURNING
     // seq` works in node:sqlite (see objstore's `insertLiveIfAbsent`).

package/server/http.ts

@@ -1,8 +1,9 @@
 // HTTP plane: the REST byte-transfer routing (`/api/objstore/...`), the
-// static UI bundle, and the WebSocket upgrade gate. Built once at boot
-// with the WS server plus the lifecycle hooks it needs (`track` to
-// drain in-flight requests on shutdown, `isShuttingDown` to gate new
-// ones). The WS *connection* handler is wired on `wss` separately in
+// static UI bundle, the SSE+POST fallback transport for the sync
+// protocol, and the WebSocket upgrade gate. Built once at boot with
+// the WS server plus the lifecycle hooks it needs (`track` to drain
+// in-flight requests on shutdown, `isShuttingDown` to gate new ones).
+// The WS *connection* handler is wired on `wss` separately in
 // index.ts; this module only owns the upgrade handshake.
 
 import { type IncomingMessage as HttpRequest, type Server, type ServerResponse, createServer } from 'node:http'
@@ -10,6 +11,8 @@ import { Buffer } from 'node:buffer'
 import { fileURLToPath } from 'node:url'
 import type { WebSocketServer } from 'ws'
 import { type ObjstoreRestDeps, handleRest, matchRoute } from './objstore/rest.ts'
+import { SSE_OPEN_PATH, type SseServer } from './sse-server.ts'
+import { dispatchNpmAdvisories } from './npm-proxy.ts'
 import { loadStatic } from './static.ts'
 import { errStack } from './util.ts'
 
@@ -31,6 +34,11 @@ type HasHeaders = { headers: HttpRequest['headers'] }
 export type HttpServerDeps = {
   wss: WebSocketServer
   restDeps: ObjstoreRestDeps
+  // SSE+POST fallback. Owns its own session map + lifecycle; we just
+  // give it first crack at requests that match `SSE_OPEN_PATH`. Same
+  // same-origin / shutdown gates run BEFORE the dispatch so the SSE
+  // plane inherits them.
+  sseServer: SseServer
   isOriginAllowed: (req: HasHeaders) => boolean
   isShuttingDown: () => boolean
   track: (promise: Promise<unknown>) => void
@@ -39,7 +47,7 @@ export type HttpServerDeps = {
 }
 
 export function createHttpServer(deps: HttpServerDeps): Server {
-  const { wss, restDeps, isOriginAllowed, isShuttingDown, track, restPutIdleTimeoutMs, debug } = deps
+  const { wss, restDeps, sseServer, isOriginAllowed, isShuttingDown, track, restPutIdleTimeoutMs, debug } = deps
   // Static-file plane (see ./static.ts). The directory is the
   // `build.js build` output sibling to this file; the loader handles
   // enumeration, pre-compression, and ETag derivation. Plugged in after
@@ -47,6 +55,34 @@ export function createHttpServer(deps: HttpServerDeps): Server {
   const handleStatic = loadStatic(fileURLToPath(new URL('../out', import.meta.url)))
 
   const httpServer = createServer((req: HttpRequest, res: ServerResponse) => {
+    // SSE+POST fallback plane. Same-origin gate first (Origin header
+    // is set by the browser on cross-origin EventSource + fetch, so
+    // a hostile origin would surface here just like it does on the
+    // WS upgrade and REST plane). The sseServer.handle() function
+    // returns true iff it matched and consumed the request; on false
+    // we fall through to the REST / static / 404 ladder below.
+    if (typeof req.url === 'string' && req.url.split('?', 1)[0] === SSE_OPEN_PATH) {
+      if (!isOriginAllowed(req)) {
+        res.writeHead(403, { 'content-type': 'application/json' })
+        res.end(JSON.stringify({ error: 'origin-denied' }))
+        return
+      }
+      // sseServer.handle owns its own shutdown / cap / 503 ladder.
+      // Each POST's response stays open as the session's downstream
+      // channel until the next POST takes over — the response is
+      // long-lived even though the request is one-shot — and the
+      // shutdown gate inside sseServer prevents accepting new POSTs
+      // once shuttingDown latches, so outstanding sessions drain via
+      // the lifecycle's sseSessions() close loop.
+      if (sseServer.handle(req, res)) return
+    }
+    // npm advisories proxy — same-origin + shutdown gates live in the
+    // helper so this dispatcher stays compact. `dispatchNpmAdvisories`
+    // returns the in-flight promise (or null when the route didn't
+    // match); the lifecycle's `track` awaits it so SIGTERM drains
+    // outstanding upstream fetches.
+    const npmP = dispatchNpmAdvisories(req, res, { isOriginAllowed, isShuttingDown, debug })
+    if (npmP) { track(npmP); return }
     if (matchRoute(req.url) != null) {
       // Shutdown gate. The WS plane gates new messages on `shuttingDown`;
       // REST handlers go through a separate path and must mirror it.

package/server/hub.ts

@@ -19,8 +19,18 @@ export type Hub = {
   // `except: null` is the REST-originated path — byte transfer landed
   // via HTTP, not a particular WS socket, so it hits every subscriber.
   // WS-originated broadcasts pass the originator so it doesn't see its
-  // own message echoed back.
+  // own message echoed back. Local-only: callers that ALSO want a
+  // cross-instance fan-out are expected to publish to the pubsub bus
+  // alongside this call (server/pubsub.ts). The hub deliberately stays
+  // ignorant of the bus so its transport invariants (backpressure cap,
+  // stringify-once, terminate-on-overflow) are unchanged.
   broadcast(tag: string, msg: object, except: WebSocket | null): void
+  // Broadcasts an ALREADY-SERIALISED payload to every local subscriber
+  // for `tag`. Used by the pubsub bus receiver
+  // (server/bus-receiver.ts, wired up from server/index.ts) to relay
+  // a remote-instance event into this instance's fan-out. No `except`:
+  // the originator is on a different instance by construction.
+  broadcastLocalRaw(tag: string, payload: string): void
 }
 
 export function createHub(deps: { peers: PeerRegistry; maxBufferedBytes: number; debug: boolean }): Hub {
@@ -82,6 +92,16 @@ export function createHub(deps: { peers: PeerRegistry; maxBufferedBytes: number;
     // catch-up with a multi-MB ciphertext × N subscribers, per-recipient
     // JSON.stringify would dominate CPU; this is the cheap win.
     const payload = JSON.stringify(msg)
+    fanOut(set, payload, except)
+  }
+
+  function broadcastLocalRaw(tag: string, payload: string): void {
+    const set = subscribers.get(tag)
+    if (!set) return
+    fanOut(set, payload, null)
+  }
+
+  function fanOut(set: Set<WebSocket>, payload: string, except: WebSocket | null): void {
     // Snapshot before iterating — `send`'s try/catch swallows
     // socket.send errors, but a socket transitioning to CLOSED
     // mid-broadcast triggers `unsubscribeAll` from the 'close' handler,
@@ -94,5 +114,5 @@ export function createHub(deps: { peers: PeerRegistry; maxBufferedBytes: number;
     }
   }
 
-  return { subscribe, unsubscribeAll, send, sendRaw, broadcast }
+  return { subscribe, unsubscribeAll, send, sendRaw, broadcast, broadcastLocalRaw }
 }

package/server/index.ts

@@ -73,7 +73,7 @@
 // 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 { createHub } from './hub.ts'
@@ -81,6 +81,7 @@ 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 { createLifecycle } from './lifecycle.ts'
 import { loadConfig } from './config.ts'
 import { type Handle, openDb } from './db.ts'
@@ -89,6 +90,11 @@ 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
@@ -235,7 +241,39 @@ async function workspaceExists(tag: string): Promise<boolean> {
 // broadcast (see ./hub.ts). Destructure into the existing names so the
 // handlers / dispatcher / objstore wiring below read unchanged.
 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.
@@ -247,8 +285,18 @@ const { requiresAuth, handleAuthenticate, sendUnauthorized } = auth
 // 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 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, handleSubscribe, sendSaveError } = createSyncHandlers({
-  handle, send, broadcast, subscribe, getNonce,
+  handle, send, broadcast, publishRevision, subscribe, getNonce,
   requiresAuth, sendUnauthorized, workspaceExists,
   // Folds the objstore inventory into the `workspace-subscribed` ack.
   // The objstore store keeps its own richer `Handle`, so we wire the
@@ -260,7 +308,8 @@ 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,
+  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
@@ -289,12 +338,46 @@ 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.
+// 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, 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,
+  // 90s idle ceiling. The client's JSON ping/pong is 15s; this is ~6
+  // missed pings before we close — well past any transient network
+  // hiccup, much shorter than the kernel's hours-long TCP keepalive.
+  sessionIdleMs: 90_000,
+  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,
+  wss, restDeps: objstoreRestDeps, sseServer, isOriginAllowed,
   isShuttingDown, track,
   restPutIdleTimeoutMs: REST_PUT_IDLE_TIMEOUT_MS, debug: DEBUG,
 })
@@ -303,11 +386,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 +403,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,6 +446,7 @@ const closeDb = async (): Promise<void> => {
 // and the heartbeat timer all exist.
 installLifecycle({
   httpServer, wss, heartbeatTimer, stopReaper,
+  sseSessions: sseServer.sessions,
   closeDb,
 })
 

package/server/lifecycle.ts

@@ -7,6 +7,7 @@
 
 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 = {
@@ -15,6 +16,11 @@ export type ShutdownDeps = {
   heartbeatTimer: 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>
@@ -51,7 +57,7 @@ export function createLifecycle(): Lifecycle {
   let pendingExitCode = 0
 
   function install(deps: ShutdownDeps): void {
-    const { httpServer, wss, heartbeatTimer, stopReaper, closeDb } = deps
+    const { httpServer, wss, heartbeatTimer, stopReaper, sseSessions, closeDb } = deps
 
     async function shutdown(exitCode: number = 0): Promise<void> {
       // Re-entry: don't restart the teardown, but escalate the pending
@@ -78,6 +84,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 +105,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.