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

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

@@ -2,15 +2,16 @@
 // vars, the optional config.json) into one immutable `Config`, failing
 // loud on malformed values so a typo surfaces at startup rather than
 // deep in `node:net` / at the first token verification. Pure parsing —
-// no backends opened, no crypto keys derived, no side effects beyond
-// `--help` / fail-fast `process.exit`. index.ts destructures the
-// result and does the wiring (backend selection, password HMAC, …).
+// no backends opened or process termination. Invalid configuration throws so
+// embedding hosts can recover; app.ts handles backend selection and wiring.
 
 import { Buffer } from 'node:buffer'
 import { readFileSync } from 'node:fs'
-import { argv, env } from 'node:process'
+import { env } from 'node:process'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
+import { configuredScanServer } from '../server-common/scan-config.ts'
+import { databaseUrls } from '../server-common/database-config.ts'
 
 export type Config = {
   port: number
@@ -26,9 +27,11 @@ export type Config = {
   tokenSecret: Uint8Array<ArrayBuffer> | null
   password: string | null
   trustProxyEnv: string | undefined
+  deepviewScanServer: string | null
+  githubNewIssueLabels?: string
 }
 
-// Parse + range-validate an integer env var, exiting with a clear
+// Parse + range-validate an integer env var, throwing a clear
 // up-front message on a malformed value — a NaN from `Number("abc")`
 // otherwise surfaces as a confusing crash deep inside `node:net`
 // (`WebSocketServer({ port: NaN })`) or a 0-ms `setInterval` loop. An
@@ -39,20 +42,32 @@ function intEnv(name: string, def: number, min: number, max: number, hint = ''):
   const raw = env[name]
   const n = raw == null ? def : Number(raw)
   if (!Number.isSafeInteger(n) || n < min || n > max) {
-    console.error(`Invalid ${name}: ${raw} — must be an integer in [${min}, ${max}].${hint ? ` ${hint}` : ''}`)
-    process.exit(1)
+    throw new Error(`Invalid ${name}: ${raw} — must be an integer in [${min}, ${max}].${hint ? ` ${hint}` : ''}`)
   }
   return n
 }
 
-const HELP = `Usage: node server/index.ts
+export const HELP = `Usage: node server-e2e/index.ts
 Environment:
   PORT                       listen port (default 8765)
   HOST                       bind host (default 127.0.0.1)
-  DB_PATH                    sqlite file (default: server/data/data.db);
-                             ignored when DATABASE_URL is set
-  DATABASE_URL               Neon Postgres connection string; if set,
-                             selects the Neon backend instead of
+  DEEPVIEW_SCAN_SERVER       optional HTTP(S) scan-service URL; advertised
+                             in /api/config and allowed by the UI CSP.
+                             Unset by default (no external scan service).
+  GITHUB_NEW_ISSUE_LABELS    optional comma-separated labels for the client's
+                             prefilled GitHub issue form, in addition to
+                             deepview and security (for security findings).
+                             Advertised in /api/config and sync connections.
+  DB_PATH                    sqlite file (default: server-e2e/data/data.db);
+                             ignored when an e2e database URL is set
+  DATABASE_URL               shared Neon Postgres URL for enabled modes.
+                             Cannot be combined with E2E_DATABASE_URL
+                             or MANAGED_DATABASE_URL.
+  E2E_DATABASE_URL           e2e-only Neon URL, used without DATABASE_URL.
+                             Combined mode also requires
+                             MANAGED_DATABASE_URL; mixing Neon and
+                             SQLite backends is rejected.
+                             Either e2e URL selects Neon instead of
                              SQLite. Requires the optional peer dep
                              @neondatabase/serverless. The Neon
                              pairing additionally requires
@@ -61,12 +76,12 @@ Environment:
                              local-FS bytes cannot back a multi-
                              replica DB plane.
   BLOB_READ_WRITE_TOKEN      Vercel Blob R/W token (private store).
-                             Required when DATABASE_URL is set;
+                             Required when an e2e database URL is set;
                              ignored otherwise. Requires the optional
                              peer dep @vercel/blob.
   OBJSTORE_TOKEN_SECRET      Base64 (32 bytes) HMAC secret for REST
-                             bearer tokens. REQUIRED when DATABASE_URL
-                             is set (multi-replica deployments: a
+                             bearer tokens. REQUIRED in Neon mode
+                             (multi-replica deployments: a
                              token minted on one replica's WS plane
                              must validate on another replica's REST
                              plane). Optional under SQLite (a fresh
@@ -76,16 +91,15 @@ Environment:
   OBJSTORE_DIR               object store root (default: ./objstore
                              next to DB_PATH). Used by the local-FS
                              byte plane only; ignored when
-                             DATABASE_URL + BLOB_READ_WRITE_TOKEN
-                             are set (bytes live in Vercel Blob).
+                             an e2e database URL selects Neon
+                             (bytes live in Vercel Blob).
   OBJSTORE_REAP_INTERVAL_MS  orphan reaper period (default 600000)
-  OBJSTORE_REAP_DISABLED     set '1' / 'true' to disable the orphan
-                             reaper ENTIRELY — no boot sweep, no
-                             periodic GC. Orphaned/superseded blobs and
-                             stale staging rows then accumulate
-                             unbounded; only set this if an external job
-                             handles GC (e.g. a cron calling reapOrphans).
-                             Default OFF (reaper runs).
+  OBJSTORE_REAP_DISABLED     set '1' / 'true' to disable automatic orphan
+                             sweeps (boot and periodic). Explicit /api/reap
+                             remains available. Schedule cleanup externally
+                             to avoid accumulating orphaned bytes.
+  CRON_SECRET               bearer secret for GET /api/reap (fails closed
+                             when unset). Runs cleanup for enabled modes.
   TRUST_PROXY                set '1' / 'true' to honour X-Forwarded-
                              Host / X-Forwarded-Proto when computing
                              the same-origin gate's expected origin.
@@ -103,7 +117,7 @@ Environment:
                              that need to deterministically
                              exercise the cap.
   CONFIG_PATH                operator config JSON path (default:
-                             server/config.json). Currently the
+                             server-e2e/config.json). Currently the
                              only field is { "password": "..." }
                              which gates first-action creation of
                              a new workspace on the
@@ -121,11 +135,11 @@ function readServerConfigFile(path: string): ServerConfigFile {
   let raw: string
   try { raw = readFileSync(path, 'utf8') } catch (err) {
     if ((err as NodeJS.ErrnoException)?.code === 'ENOENT') return {}
-    console.error(`Failed to read ${path}:`, (err as Error)?.message ?? err); process.exit(1)
+    throw new Error(`Failed to read ${path}: ${(err as Error)?.message ?? err}`, { cause: err })
   }
   try { return JSON.parse(raw) as ServerConfigFile }
   catch (err) {
-    console.error(`Failed to parse ${path} as JSON:`, (err as Error)?.message ?? err); process.exit(1)
+    throw new Error(`Failed to parse ${path} as JSON: ${(err as Error)?.message ?? err}`, { cause: err })
   }
 }
 
@@ -140,20 +154,17 @@ function decodeTokenSecret(raw: string): Uint8Array<ArrayBuffer> {
   // typo-detector below would fail with a misleading message.
   const trimmed = raw.trim()
   if (trimmed.length === 0) {
-    console.error('OBJSTORE_TOKEN_SECRET is empty after trimming whitespace')
-    process.exit(1)
+    throw new Error('OBJSTORE_TOKEN_SECRET is empty after trimming whitespace')
   }
   const decoded = Buffer.from(trimmed, 'base64')
   const reencoded = decoded.toString('base64')
   const norm = (s: string): string => s.replace(/=+$/u, '')
   if (norm(reencoded) !== norm(trimmed)) {
-    console.error('OBJSTORE_TOKEN_SECRET contains non-base64 characters (likely a typo, e.g. base64url chars in a base64 secret).')
-    console.error('Regenerate with: node -e \'console.log(require("crypto").randomBytes(32).toString("base64"))\'')
-    process.exit(1)
+    throw new Error('OBJSTORE_TOKEN_SECRET contains non-base64 characters (likely a typo, e.g. base64url chars in a base64 secret).\n' +
+      'Regenerate with: node -e \'console.log(require("crypto").randomBytes(32).toString("base64"))\'')
   }
   if (decoded.byteLength !== 32) {
-    console.error(`OBJSTORE_TOKEN_SECRET must decode to 32 bytes (got ${decoded.byteLength})`)
-    process.exit(1)
+    throw new Error(`OBJSTORE_TOKEN_SECRET must decode to 32 bytes (got ${decoded.byteLength})`)
   }
   // Copy into a fresh ArrayBuffer so the type matches
   // `Uint8Array<ArrayBuffer>` (Buffer may be SharedArrayBuffer-backed).
@@ -171,7 +182,7 @@ export function loadConfig(): Config {
   const objstoreDir = env['OBJSTORE_DIR'] ?? join(dirname(dbPath), 'objstore')
   // No practical upper bound beyond the safe-integer range.
   const reapIntervalMs = intEnv('OBJSTORE_REAP_INTERVAL_MS', 10 * 60 * 1000, 1, Number.MAX_SAFE_INTEGER)
-  // Hard off-switch for the orphan reaper (both the boot sweep AND the
+  // Off-switch for automatic orphan reaping (both the boot sweep AND the
   // periodic timer). '1' / 'true' (case-insensitive) → disabled; anything
   // else, including unset, leaves it ON. Same boolean shape as TRUST_PROXY.
   const reapDisabledEnv = env['OBJSTORE_REAP_DISABLED']
@@ -182,7 +193,7 @@ export function loadConfig(): Config {
   const serverConfig = readServerConfigFile(configPath)
   const rawPassword = serverConfig.password
   if (rawPassword != null && typeof rawPassword !== 'string') {
-    console.error(`Invalid ${configPath}: "password" must be a string or null`); process.exit(1)
+    throw new Error(`Invalid ${configPath}: "password" must be a string or null`)
   }
   const password = rawPassword ?? null
   // Upper bound 65_536 — bounds memory under hostile load; a deployer
@@ -191,12 +202,7 @@ export function loadConfig(): Config {
   // error-precedence order.
   const maxInflightPerSocket = intEnv('MAX_INFLIGHT_PER_SOCKET', 64, 1, 65_536)
 
-  if (argv.includes('--help') || argv.includes('-h')) {
-    console.log(HELP)
-    process.exit(0)
-  }
-
-  const neonUrl = env['DATABASE_URL'] ?? null
+  const neonUrl = databaseUrls().e2e
   const blobToken = env['BLOB_READ_WRITE_TOKEN'] ?? null
   const tokenSecretB64 = env['OBJSTORE_TOKEN_SECRET'] ?? null
   const tokenSecret = tokenSecretB64 ? decodeTokenSecret(tokenSecretB64) : null
@@ -205,5 +211,7 @@ export function loadConfig(): Config {
     port, host, dbPath, objstoreDir, reapIntervalMs, reapDisabled, maxInflightPerSocket,
     debug, neonUrl, blobToken, tokenSecret, password,
     trustProxyEnv: env['TRUST_PROXY'],
+    deepviewScanServer: configuredScanServer(env['DEEPVIEW_SCAN_SERVER']),
+    githubNewIssueLabels: env['GITHUB_NEW_ISSUE_LABELS'] ?? '',
   }
 }

package/{server → server-e2e}/db-neon.ts

@@ -4,7 +4,7 @@
 // dialect on the wire.
 //
 // `@neondatabase/serverless` is an OPTIONAL peer dep — selected by
-// the `DATABASE_URL` branch in `server/index.ts`. The peer dep
+// the configured database URL branch in `server-e2e/index.ts`. The peer dep
 // itself is loaded lazily via the dynamic `import()` inside
 // `openNeonDb` below, so a SQLite-only deployment never installs it
 // (`autoInstallPeers: false` in `pnpm-workspace.yaml`) and never
@@ -340,7 +340,7 @@ export async function openNeonDb(connectionString: string): Promise<Handle> {
   // in-process Postgres (PGlite) via `mock.module`: that hook can only
   // intercept a specifier it can RESOLVE, and the optional peer dep
   // isn't installed in a SQLite-only checkout. The wrapper path always
-  // resolves — see `server/neon-driver.ts`. Cast through `unknown`
+  // resolves — see `server-e2e/neon-driver.ts`. Cast through `unknown`
   // because the wrapper's `export *` re-exports a `@ts-ignore`'d
   // (possibly-absent) module, so tsc can't see `neon`'s type here.
   const mod = (await import('./neon-driver.ts')) as unknown as { neon: (url: string) => NeonSql }

package/{server → server-e2e}/db-revision-sql.ts

@@ -106,7 +106,7 @@ export const CHAIN_FROM_SQL =
 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)`
+// pubsub (server-e2e/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

package/{server → server-e2e}/db-stmt.ts

@@ -1,5 +1,5 @@
-// Shared async-statement primitives. Both `server/db.ts` (workspace_revision
-// chain) and `server/objstore/store.ts` (objstore tables) expose Handles
+// Shared async-statement primitives. Both `server-e2e/db.ts` (workspace_revision
+// chain) and `server-e2e/objstore/store.ts` (objstore tables) expose Handles
 // whose statements look like `{ get(...) → Promise<…>, all(...) → Promise<[…]>,
 // run(...) → Promise<void> }`. The underlying `node:sqlite` driver is
 // synchronous; the wrappers below catch sync errors and route them through

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

@@ -13,7 +13,7 @@
 // `keyframe` is `1` for a revision the client emits with full state
 // baked in (rather than a delta). The wire flag is covered by the
 // signature, so the column value MUST match the signed canonical
-// bytes: `canonicalSave` (server/sign.ts, via `handleSave`) encodes
+// bytes: `canonicalSave` (server-e2e/sign.ts, via `handleSave`) encodes
 // `keyframe ? '1' : ''` into the bytes `verifyEd25519` checks, so a
 // mismatched wire flag fails verify and never reaches this column.
 // Client-driven: the server stores what the client sent and treats
@@ -84,7 +84,7 @@ const SCHEMA = `
 
 // Row shape from the chain queries. `keyframe` is stored as INTEGER
 // (0 / 1); the raw row carries the integer — `chainForWire` in
-// server/index.ts normalises to a strict boolean before broadcasting.
+// server-e2e/index.ts normalises to a strict boolean before broadcasting.
 // `base` is nullable on the very first revision.
 export type RevisionRow = {
   base: string | null
@@ -125,8 +125,8 @@ export type CommitResult =
 // (`./db-neon.ts`) constructs a Handle with `db` unset. Callers that
 // reach into `db` directly (e.g. `openObjstore`, test-only fixture
 // SQL) are SQLite-coupled by construction; passing them a Neon-backed
-// Handle is the operator's mistake to catch at the `if (DATABASE_URL)`
-// switch in `server/index.ts`.
+// Handle is the operator's mistake to catch at the database URL
+// switch in `server-e2e/index.ts`.
 //
 // `tryCommit` is the backend-specific atomic-commit primitive
 // `commitRevision` dispatches through. SQLite runs one synchronous
@@ -154,7 +154,7 @@ export type Handle = {
   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`).
+  // NOTIFY hint (see `server-e2e/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>
@@ -164,11 +164,11 @@ export type Handle = {
 // Narrowing alias for the SQLite-backed Handle: `db` is guaranteed
 // set. `openDb` returns this so call sites needing direct
 // `DatabaseSync` access (e.g. `openObjstore(handle.db, …)` in
-// `server/index.ts`'s SQLite branch) reach `handle.db` without an
+// `server-e2e/index.ts`'s SQLite branch) reach `handle.db` without an
 // optional-chain or non-null assertion. A Neon-backed Handle
 // (`openNeonDb`) keeps the wider `db?: DatabaseSync` shape, so routing
 // one into a SQLite-coupled call site is a compile-time error. Mirrors
-// `server/objstore/store.ts`.
+// `server-e2e/objstore/store.ts`.
 export type SqliteHandle = Handle & { db: DatabaseSync }
 
 export function openDb(path: string): SqliteHandle {

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

@@ -10,6 +10,7 @@ import { type IncomingMessage as HttpRequest, type Server, type ServerResponse,
 import { Buffer } from 'node:buffer'
 import { fileURLToPath } from 'node:url'
 import type { WebSocketServer } from 'ws'
+import { CONFIG_PATH, type ServerInfo } from '../common/server-info.ts'
 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'
@@ -25,7 +26,7 @@ export const WS_UPGRADE_PATH = '/api/sync'
 // here commits + broadcasts WITHOUT taking over the client's SSE event-stream
 // (each in-band POST forces a stream takeover; see sse-server.ts). Sibling of
 // the WS upgrade path so one nginx `/api/*` block routes both.
-export const SAVE_REST_PATH = '/api/sync/save'
+const SAVE_REST_PATH = '/api/sync/save'
 function isUpgradePath(url: string | undefined): boolean {
   if (typeof url !== 'string') return false
   // Strip `?…` so clients can carry build / debug tags. Exact match
@@ -40,6 +41,10 @@ type HasHeaders = { headers: HttpRequest['headers'] }
 export type HttpServerDeps = {
   wss: WebSocketServer
   restDeps: ObjstoreRestDeps
+  // This server's `server-info` (mode advertisement), served as JSON at
+  // GET /api/config so a client can detect the protocol without a sync
+  // connection (the WS connect frame stays the source of truth).
+  serverInfo: ServerInfo
   // 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
@@ -54,6 +59,9 @@ export type HttpServerDeps = {
   handleSaveRest: (req: HttpRequest, res: ServerResponse) => Promise<void>
   restPutIdleTimeoutMs: number
   debug: boolean
+  // Serve the static UI bundle (default). False serves only the API and
+  // never reads `out/`, for hosts that serve the UI themselves.
+  ui?: boolean
 }
 
 // `POST /api/sync/save` dispatch. Returns the in-flight handler promise when
@@ -109,14 +117,27 @@ function dispatchSaveRest(
 }
 
 export function createHttpServer(deps: HttpServerDeps): Server {
-  const { wss, restDeps, sseServer, isOriginAllowed, isShuttingDown, track, handleSaveRest, restPutIdleTimeoutMs, debug } = deps
+  const { wss, restDeps, sseServer, serverInfo, isOriginAllowed, isShuttingDown, track, handleSaveRest, restPutIdleTimeoutMs, debug, ui = true } = 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
   // the `/api/objstore/...` REST branch.
-  const handleStatic = loadStatic(fileURLToPath(new URL('../out', import.meta.url)))
+  const handleStatic = ui ? loadStatic(fileURLToPath(new URL('../out', import.meta.url)), serverInfo.deepviewScanServer ?? null) : () => false
 
   const httpServer = createServer((req: HttpRequest, res: ServerResponse) => {
+    // Static mode probe: GET /api/config → this server's `server-info` as JSON.
+    // A client uses it to detect the protocol up front; the WS connect frame
+    // stays the source of truth and catches a later mode change. Public, no body.
+    if (typeof req.url === 'string' && req.url.split('?', 1)[0] === CONFIG_PATH) {
+      if (req.method !== 'GET') {
+        res.writeHead(405, { 'content-type': 'application/json', allow: 'GET' })
+        res.end(JSON.stringify({ error: 'method-not-allowed' }))
+        return
+      }
+      res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store' })
+      res.end(JSON.stringify(serverInfo))
+      return
+    }
     // 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
@@ -156,12 +177,12 @@ export function createHttpServer(deps: HttpServerDeps): Server {
       // REST handlers go through a separate path and must mirror it.
       // Without this, a REST PUT arriving on an existing keep-alive
       // socket AFTER SIGTERM but BEFORE `httpServer.close()` finishes
-      // draining could land in `withCommitLock`, acquire a lease, and
-      // finish its `finally { release() }` AFTER the shutdown's
-      // `heldLeaseCount` snapshot — leaving an orphan lock row that pins
-      // the key until TTL expiry. The 503 + `shutting-down` reason tells
-      // the client to retry against a different replica. Transport
-      // audit + multi-replica shutdown ordering review.
+      // draining could start a fresh upload + commit for the drain to
+      // outwait — or, landing after the drain's in-flight snapshot
+      // (lifecycle.ts `drain`), run on against the closed DB, the race
+      // ws-server.ts gates on the WS plane. The 503 + `shutting-down`
+      // reason tells the client to retry against a different replica.
+      // Transport audit + multi-replica shutdown ordering review.
       if (isShuttingDown()) {
         res.writeHead(503, { 'content-type': 'application/json', 'connection': 'close' })
         res.end(JSON.stringify({ error: 'shutting-down' }))
@@ -171,7 +192,7 @@ export function createHttpServer(deps: HttpServerDeps): Server {
       // that holds a valid token (e.g. via XSS that read a freshly-minted
       // one) would PUT with its own Origin header — caught here.
       // Same-origin XHR/fetch may omit Origin; that path is allowed (see
-      // `isOriginAllowed`). Transport audit `server/objstore/rest.ts:103`.
+      // `isOriginAllowed`). Transport audit `server-e2e/objstore/rest.ts:103`.
       if (!isOriginAllowed(req)) {
         res.writeHead(403, { 'content-type': 'application/json' })
         res.end(JSON.stringify({ error: 'origin-denied' }))
@@ -183,7 +204,7 @@ export function createHttpServer(deps: HttpServerDeps): Server {
       // blob within its declared Content-Length; POST carries the small
       // fetch-mint JSON body. `req.setTimeout` fires on inactivity; we
       // destroy the request, aborting the body pipeline.
-      // Transport audit `server/objstore/rest.ts:218`.
+      // Transport audit `server-e2e/objstore/rest.ts:218`.
       if (req.method === 'PUT' || req.method === 'POST') {
         req.setTimeout(restPutIdleTimeoutMs, () => {
           if (debug) console.warn(`REST ${req.method} idle ${restPutIdleTimeoutMs}ms → abort`)
@@ -212,7 +233,19 @@ export function createHttpServer(deps: HttpServerDeps): Server {
     res.end(NOT_FOUND_BODY)
   })
 
+  installUpgradeHandler(httpServer, wss, isOriginAllowed)
+
+  return httpServer
+}
+
+function installUpgradeHandler(httpServer: Server, wss: WebSocketServer, isOriginAllowed: HttpServerDeps['isOriginAllowed']): void {
   httpServer.on('upgrade', (req, socket, head) => {
+    // Combined deployments must not let a managed share capability enter the
+    // unscoped sync transport, which bypasses the normal HTTP router.
+    if (req.headers['x-deepview-share'] !== undefined) {
+      socket.end('HTTP/1.1 403 Forbidden\r\nContent-Length: 0\r\nConnection: close\r\n\r\n')
+      return
+    }
     // RFC 6455: the WS upgrade IS an HTTP request; reject with a normal
     // HTTP response so a misconfigured client sees the JSON body instead
     // of ECONNRESET. `socket.end(body)` flushes before sending FIN.
@@ -243,6 +276,4 @@ export function createHttpServer(deps: HttpServerDeps): Server {
     }
     wss.handleUpgrade(req, socket, head, (ws) => { wss.emit('connection', ws, req) })
   })
-
-  return httpServer
 }

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

@@ -7,9 +7,13 @@
 // testable and reasoned about on its own.
 
 import type { WebSocket } from 'ws'
+import { Buffer } from 'node:buffer'
 import type { PeerRegistry } from './peer.ts'
 
 export type Hub = {
+  // Buffer broadcasts during async subscription snapshots. The returned
+  // release flushes them after the snapshot/chain replies, preserving order.
+  pauseBroadcasts(socket: WebSocket): () => void
   subscribe(socket: WebSocket, tag: string): void
   unsubscribeAll(socket: WebSocket): void
   send(socket: WebSocket, msg: object): void
@@ -21,13 +25,13 @@ export type Hub = {
   // WS-originated broadcasts pass the originator so it doesn't see its
   // 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
+  // alongside this call (server-e2e/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
+  // (server-e2e/bus-receiver.ts, wired up from server-e2e/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
@@ -38,18 +42,34 @@ export function createHub(deps: { peers: PeerRegistry; maxBufferedBytes: number;
   // workspaceTag → Set<WebSocket>. The per-socket reverse index lives on
   // `Peer.tags` (see ./peer.ts) and is read by `unsubscribeAll` on close.
   const subscribers = new Map<string, Set<WebSocket>>()
+  const paused = new WeakMap<WebSocket, { depth: number; payloads: string[]; bytes: number }>()
+
+  function pauseBroadcasts(socket: WebSocket): () => void {
+    const pending = paused.get(socket) ?? { depth: 0, payloads: [], bytes: 0 }
+    pending.depth++
+    paused.set(socket, pending)
+    let released = false
+    return () => {
+      if (released) return
+      released = true
+      if (--pending.depth > 0 || paused.get(socket) !== pending) return
+      paused.delete(socket)
+      for (const payload of pending.payloads) sendRaw(socket, payload)
+      pending.payloads.length = 0
+    }
+  }
 
   function subscribe(socket: WebSocket, tag: string): void {
     let set = subscribers.get(tag)
-    if (!set) {
-      set = new Set()
-      subscribers.set(tag, set)
-    }
+    if (!set) { set = new Set(); subscribers.set(tag, set) }
     set.add(socket)
     peers.get(socket)?.tags.add(tag)
   }
 
   function unsubscribeAll(socket: WebSocket): void {
+    const pending = paused.get(socket)
+    if (pending) pending.payloads.length = 0
+    paused.delete(socket)
     const tags = peers.get(socket)?.tags
     if (!tags) return
     for (const tag of tags) {
@@ -71,7 +91,7 @@ export function createHub(deps: { peers: PeerRegistry; maxBufferedBytes: number;
     // kernel yet — a slow / blackholed peer accumulates them unboundedly
     // during fan-out broadcasts. Drop above the cap and terminate the
     // socket so the heartbeat doesn't keep it alive on ping/pong while
-    // every broadcast piles up. Transport audit `server/index.ts:225`.
+    // every broadcast piles up. Transport audit `server-e2e/index.ts:225`.
     if (socket.bufferedAmount > maxBufferedBytes) {
       if (debug) console.warn(`drop broadcast: socket buffered ${socket.bufferedAmount}B > cap`)
       try { socket.terminate() } catch {}
@@ -102,6 +122,7 @@ export function createHub(deps: { peers: PeerRegistry; maxBufferedBytes: number;
   }
 
   function fanOut(set: Set<WebSocket>, payload: string, except: WebSocket | null): void {
+    const payloadBytes = Buffer.byteLength(payload)
     // Snapshot before iterating — a socket transitioning to CLOSED
     // mid-broadcast triggers `unsubscribeAll` from the 'close' handler,
     // mutating `set` while we walk it. The snapshot also keeps a future
@@ -109,9 +130,19 @@ export function createHub(deps: { peers: PeerRegistry; maxBufferedBytes: number;
     // subscribers. Audit M4 round-3.
     for (const s of [...set]) {
       if (s === except) continue
-      sendRaw(s, payload)
+      const pending = paused.get(s)
+      if (!pending) { sendRaw(s, payload); continue }
+      pending.bytes += payloadBytes
+      if (pending.bytes > maxBufferedBytes) {
+        // Snapshot waits must obey the same memory bound as socket writes.
+        pending.payloads.length = 0
+        paused.delete(s)
+        try { s.terminate() } catch {}
+        continue
+      }
+      pending.payloads.push(payload)
     }
   }
 
-  return { subscribe, unsubscribeAll, send, sendRaw, broadcast, broadcastLocalRaw }
+  return { pauseBroadcasts, subscribe, unsubscribeAll, send, sendRaw, broadcast, broadcastLocalRaw }
 }

package/server-e2e/index.ts

@@ -0,0 +1,17 @@
+// Compatibility entry point for the published e2e server. Importing exposes
+// one unbound instance; the combined launcher uses the factory directly.
+import { startServer } from '../server-common/standalone.ts'
+import { createE2eApp } from './app.ts'
+import { HELP, loadConfig } from './config.ts'
+
+if (import.meta.main && (process.argv.includes('--help') || process.argv.includes('-h'))) {
+  console.log(HELP)
+  process.exit(0)
+}
+
+const config = loadConfig()
+export const { httpServer, wss, isShuttingDown, reap, handleRequest, onShutdown } = await createE2eApp(config)
+
+export function start(): void { startServer(httpServer, config) }
+
+if (import.meta.main) start()

package/server-e2e/lifecycle.ts

@@ -0,0 +1,95 @@
+// Per-instance request tracking and graceful disposal. Process shutdown belongs
+// to the standalone launcher; embedded hosts retain their signals and errors.
+import type { Server } from 'node:http'
+import type { WebSocketServer } from 'ws'
+import type { SseSession } from './sse-session.ts'
+
+export type ShutdownDeps = {
+  httpServer: Server
+  wss: WebSocketServer
+  heartbeatTimer: ReturnType<typeof setInterval>
+  sseKeepaliveTimer: ReturnType<typeof setInterval>
+  stopReaper: () => Promise<void>
+  sseSessions: () => Iterable<SseSession>
+  closeDb: () => Promise<void>
+}
+
+export type Lifecycle = {
+  track: (promise: Promise<unknown>) => void
+  isShuttingDown: () => boolean
+  install: (deps: ShutdownDeps) => void
+}
+
+function closePeers({ wss, sseSessions }: ShutdownDeps): void {
+  for (const peer of [...wss.clients, ...sseSessions()]) {
+    try { peer.close(1001, 'Server shutting down') } catch {}
+  }
+}
+
+function terminatePeers({ httpServer, wss, sseSessions }: ShutdownDeps): void {
+  for (const peer of [...wss.clients, ...sseSessions()]) {
+    if (peer.readyState === peer.OPEN || peer.readyState === peer.CLOSING) {
+      try { peer.terminate() } catch {}
+    }
+  }
+  httpServer.closeAllConnections()
+}
+
+async function drain(deps: ShutdownDeps, inFlight: Set<Promise<unknown>>): Promise<void> {
+  const { httpServer, wss, stopReaper, closeDb } = deps
+  // Bound unresponsive WS/SSE peers and HTTP keep-alives to a one-second
+  // grace period. Also works when the listeners are mounted on another host.
+  const terminateTimer = setTimeout(() => terminatePeers(deps), 1000)
+  terminateTimer.unref()
+  try {
+    await stopReaper()
+    httpServer.closeIdleConnections()
+    if (httpServer.listening) {
+      await new Promise<void>(resolve => { httpServer.close(() => resolve()) })
+    }
+    await new Promise<void>(resolve => { wss.close(() => resolve()) })
+    if (inFlight.size > 0) await Promise.allSettled([...inFlight])
+  } finally {
+    clearTimeout(terminateTimer)
+    await closeDb()
+  }
+}
+
+export function createLifecycle(): Lifecycle {
+  const inFlight = new Set<Promise<unknown>>()
+  function track(promise: Promise<unknown>): void {
+    inFlight.add(promise)
+    promise.finally(() => inFlight.delete(promise)).catch(() => {})
+  }
+  let shuttingDown = false
+
+  function install(deps: ShutdownDeps): void {
+    const { httpServer, wss, heartbeatTimer, sseKeepaliveTimer } = deps
+    let disposal: Promise<void> | undefined
+    function dispose(): Promise<void> {
+      if (!disposal) {
+        shuttingDown = true
+        clearInterval(heartbeatTimer)
+        clearInterval(sseKeepaliveTimer)
+        // Store the promise before any close/error callback can re-enter.
+        disposal = Promise.resolve().then(() => drain(deps, inFlight)).finally(() => {
+          httpServer.off('close', onClose)
+          httpServer.off('error', onClose)
+          wss.off('error', onWsError)
+        })
+        closePeers(deps)
+      }
+      return disposal
+    }
+    function onClose(): void {
+      void dispose().catch(err => { console.error('Server cleanup failed:', err) })
+    }
+    function onWsError(err: Error): void { httpServer.emit('error', err) }
+    httpServer[Symbol.asyncDispose] = dispose
+    httpServer.once('close', onClose)
+    httpServer.on('error', onClose)
+    wss.on('error', onWsError)
+  }
+
+  return { track, isShuttingDown: () => shuttingDown, install }
+}