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

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

@@ -8,9 +8,10 @@
 //
 // One route, POSTs only:
 //
-//   POST /api/sync/sse[?id=<sid>]
+//   POST /api/sync/sse
 //       Request body:
-//         { password?: string,                   — cached client password
+//         { id?: string,                         — session continuation token
+//           password?: string,                   — cached client password
 //           frames?:   Array<protocol-frame>     — WS-style JSON frames
 //         }
 //       Response:
@@ -25,14 +26,23 @@
 //         carrying the WS protocol's JSON envelopes.
 //
 // Continuation: each POST replaces the previous POST's response as the
-// session's downstream channel. If the `?id=<sid>` in the URL matches
-// a session this replica knows, the session continues (new outbound
-// stream attached, old one end()ed). If the id is unknown (different
-// replica picked up the POST, or session expired), a fresh session
-// with a new id is created and announced via the first `session`
-// event; the client uses the new id on all subsequent POSTs and re-
-// sends its subscribe frames on the next POST (its `frames` carry the
-// signed subscribes — they always do, see client/sync/sse-transport.ts).
+// session's downstream channel. If the body's `id` matches a session
+// this replica knows, the session continues (new outbound stream
+// attached, old one end()ed). If the id is unknown (different replica
+// picked up the POST, or session expired), a fresh session with a new
+// id is created and announced via the first `session` event; the
+// client uses the new id on all subsequent POSTs and re-sends its
+// subscribe frames on the next POST (its `frames` carry the signed
+// subscribes — they always do, see client/sync/sse-transport.ts).
+//
+// The id rides the JSON body, NOT the URL: the sid is a live bearer
+// capability (whoever presents it attaches to the session's downstream
+// and inherits its operator-auth flag), and a query-string token leaks
+// into proxy / LB access logs — the same reason the objstore bearer
+// tokens ride the Authorization header, never the URL. A legacy
+// `?id=<sid>` query form is still ACCEPTED (older client bundles sent
+// it; rejecting would churn them through a fresh session per POST),
+// but current clients never emit it.
 //
 // Why POSTs only: a long-lived GET pins the client to one replica via
 // TCP affinity, which would mean POSTs from the same client must be
@@ -47,7 +57,7 @@ import { type PeerConnectionDeps, setupPeerConnection } from './ws-server.ts'
 import { SseSession } from './sse-session.ts'
 import { errMsg, randomId } from './util.ts'
 
-// Same prefix the WS upgrade lives under (server/http.ts WS_UPGRADE_PATH
+// Same prefix the WS upgrade lives under (server-e2e/http.ts WS_UPGRADE_PATH
 // = '/api/sync'); subroute keeps the SSE plane sibling to the upgrade
 // path so the same `location` block routes both.
 export const SSE_OPEN_PATH = '/api/sync/sse'
@@ -75,7 +85,7 @@ export type SseServerDeps = {
   // transport into it. Closure over the same handler / hub / objstore
   // / track / debug surface the WS path uses.
   peerDeps: PeerConnectionDeps
-  // Shutdown gate. Mirror of the REST + WS branches in server/http.ts:
+  // Shutdown gate. Mirror of the REST + WS branches in server-e2e/http.ts:
   // an SSE POST arriving on an existing keep-alive socket after
   // SIGTERM should be rejected, not dispatched against a draining DB.
   isShuttingDown: () => boolean
@@ -83,7 +93,7 @@ export type SseServerDeps = {
   // 503 the open request. Caps the SSE-side equivalent of `wss.clients`.
   maxSessions: number
   // Max body size for one POST. Matches the WS `maxPayload` in
-  // server/index.ts so the SSE plane can't accept frames the WS plane
+  // server-e2e/index.ts so the SSE plane can't accept frames the WS plane
   // would reject. The POST body envelope can hold multiple frames so
   // the per-frame budget is the same as the WS plane after the
   // dispatcher splits them.
@@ -106,8 +116,10 @@ export type SseServer = {
 // Inbound POST body. Every field optional — an empty-body POST is a
 // valid "wake the session" probe (the response stream rides on every
 // POST), and a body that carries only `password` or only `frames` is
-// a normal partial update.
+// a normal partial update. `id` is the session continuation token
+// (see the header's "Continuation" note for why it rides the body).
 type SseBody = {
+  id?: unknown
   password?: unknown
   frames?: unknown
 }
@@ -116,12 +128,13 @@ export function installSseServer(deps: SseServerDeps): SseServer {
   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
-  // replica doesn't recognise) and that subsequent POSTs echo back to
-  // continue the session. Bounded by `maxSessions` — over the cap, new
-  // POSTs get a 503. POSTs against an unknown id are NOT 404'd — they
-  // mint a fresh session instead, so a multi-replica deployment doesn't
-  // require sticky LB routing to recover.
+  // mints on the first POST that carries no continuation id (or whose
+  // id this replica doesn't recognise) and that subsequent POSTs echo
+  // back (body `id` field) to continue the session. Bounded by
+  // `maxSessions` — over the cap, new POSTs get a 503. POSTs against an
+  // unknown id are NOT 404'd — they mint a fresh session instead, so a
+  // multi-replica deployment doesn't require sticky LB routing to
+  // recover.
   const sessions = new Map<string, SseSession>()
 
   function dropSession(sid: string): void {
@@ -251,6 +264,12 @@ export function installSseServer(deps: SseServerDeps): SseServer {
           return
         }
       }
+      // Resolve the continuation token: the JSON body's `id` is the
+      // canonical carrier; the `?id=` query form is the legacy
+      // fallback for older client bundles (see the header note — a
+      // query sid leaks into access logs). Body wins when both are
+      // present (current clients only ever send one).
+      const sid = parseSid(body.id) ?? sidFromUrl
       // Look up the session by id (if the client sent one). If found
       // and alive, attach the new response and dispatch. If not (or
       // session is closed), mint a fresh one — the response stream
@@ -265,8 +284,8 @@ 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
-      if (sidFromUrl) {
-        const existing = sessions.get(sidFromUrl)
+      if (sid) {
+        const existing = sessions.get(sid)
         if (existing && existing.readyState === existing.OPEN && existing.attachResponse(res)) {
           writeSseHeaders(res)
           session = existing
@@ -333,25 +352,33 @@ export function installSseServer(deps: SseServerDeps): SseServer {
   return { handle, sessions: () => sessions.values(), keepaliveTimer }
 }
 
-// Bare-bones query parse for `id=<base64url>`. Avoids URLSearchParams
+// Shape gate for a continuation token from either carrier (body `id`
+// field or the legacy `?id=` query). The {1,64} bound is a
+// deliberately lenient sanity gate: anything outside the base64url
+// alphabet is rejected; an unrecognised sid just gets a fresh session
+// from createSession (no failure mode), and the wide length window
+// keeps a future randomId-length change from silently breaking old
+// clients that round-trip a longer/shorter token. Returns null on
+// missing / non-string / malformed.
+function parseSid(v: unknown): string | null {
+  if (typeof v !== 'string') return null
+  if (!/^[A-Za-z0-9_-]{1,64}$/u.test(v)) return null
+  return v
+}
+
+// Bare-bones query parse for the LEGACY `id=<base64url>` carrier
+// (older client bundles; current clients send the sid in the POST
+// body — see the header's "Continuation" note). Avoids URLSearchParams
 // (which decodes percent-escapes) — `randomId()` mints a 22-char
 // base64url string echoed back unchanged, so no escapes are possible
-// on the legitimate path. The {1,64} bound is a deliberately lenient
-// sanity gate: anything outside the base64url alphabet is rejected; an
-// unrecognised sid just gets a fresh session from createSession (no
-// failure mode), and the wide length window keeps a future
-// randomId-length change from silently breaking old clients that
-// round-trip a longer/shorter token. Returns null on missing /
-// malformed.
+// on the legitimate path.
 function parseSidQuery(query: string | undefined): string | null {
   if (typeof query !== 'string') return null
   for (const part of query.split('&')) {
     const eq = part.indexOf('=')
     if (eq <= 0) continue
     if (part.slice(0, eq) !== 'id') continue
-    const v = part.slice(eq + 1)
-    if (!/^[A-Za-z0-9_-]{1,64}$/u.test(v)) return null
-    return v
+    return parseSid(part.slice(eq + 1))
   }
   return null
 }

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

@@ -6,8 +6,8 @@
 // `join(staticDir, dirent.name)` from `readdirSync` at boot — the
 // request URL is only used as a Map key, never joined with the
 // filesystem — so the handler has no path-traversal surface at all:
-// `..`, percent-encoded slashes, nested subpaths and absolute-form
-// URIs all just produce a key that isn't in the map and 404.
+// `..`, percent-encoded slashes and absolute-form URIs all just
+// produce a key that isn't in the map and 404.
 //
 // Compression: every entry whose extension is in COMPRESSIBLE gets
 // pre-computed brotli + gzip at boot. The handler picks brotli over
@@ -38,6 +38,7 @@ import { readFileSync, readdirSync } from 'node:fs'
 import { createHash } from 'node:crypto'
 import { brotliCompressSync, gzipSync, constants as zlibConstants } from 'node:zlib'
 import { extname, join } from 'node:path'
+import { scanServerHtml } from '../server-common/scan-config.ts'
 
 // MIME types for extensions the production UI bundle currently
 // emits. Anything else falls through to `application/octet-stream`
@@ -64,15 +65,24 @@ const COMPRESSIBLE = new Set(['.html', '.css', '.js', '.svg', '.webmanifest'])
 // navigated `image/svg+xml` icon into something script-executable.
 // `no-referrer` keeps URLs of this (potentially sensitive) viewer out
 // of outbound Referer headers, and `same-origin` CORP stops other
-// origins embedding these bytes. CSP is deliberately NOT here: the
-// HTML documents carry their own per-page `<meta http-equiv>` policy
-// (and the three pages differ), so a blanket header CSP would just AND
-// against the meta one and risk breaking a page — non-document assets
-// get their own flat CSP via `StaticEntry.csp` instead.
+// origins embedding these bytes. COOP `same-origin` severs the
+// window.opener link to any cross-origin opener/popup (so an external
+// `target=_blank` GitHub/Claude link can't reach back into this context),
+// and COEP `require-corp` bars the document from loading any cross-origin
+// subresource that doesn't opt in via CORP/CORS. Together they also make
+// the page cross-origin-isolated. Safe here because the bundle is fully
+// same-origin (no external scripts/images/fonts/iframes) — switch COEP to
+// `credentialless` if a cross-origin resource is ever added. CSP is
+// deliberately NOT here: the HTML documents carry their own per-page
+// `<meta http-equiv>` policy (and the three pages differ), so a blanket
+// header CSP would just AND against the meta one and risk breaking a page
+// — non-document assets get their own flat CSP via `StaticEntry.csp`.
 const SECURITY_HEADERS = {
   'x-content-type-options': 'nosniff',
   'referrer-policy': 'no-referrer',
   'cross-origin-resource-policy': 'same-origin',
+  'cross-origin-opener-policy': 'same-origin',
+  'cross-origin-embedder-policy': 'require-corp',
 } as const
 
 type StaticEntry = {
@@ -93,8 +103,10 @@ export type StaticHandler = (req: HttpRequest, res: ServerResponse) => boolean
 // caller falls through to its next route. Missing `staticDir`
 // (pre-build case) logs a warning and returns a handler that always
 // answers false; the API/WS planes are unaffected.
-export function loadStatic(staticDir: string): StaticHandler {
-  const files = readStaticFiles(staticDir)
+type StaticOptions = { transformIndex?: (html: string) => string, indexOnly?: boolean }
+
+export function loadStatic(staticDir: string, deepviewScanServer: string | null = null, options: StaticOptions = {}): StaticHandler {
+  const files = readStaticFiles(staticDir, deepviewScanServer, options)
   return function handleStatic(req: HttpRequest, res: ServerResponse): boolean {
     if (req.method !== 'GET' && req.method !== 'HEAD') return false
     if (typeof req.url !== 'string') return false
@@ -142,7 +154,7 @@ export function loadStatic(staticDir: string): StaticHandler {
   }
 }
 
-function readStaticFiles(staticDir: string): ReadonlyMap<string, StaticEntry> {
+function readStaticFiles(staticDir: string, deepviewScanServer: string | null, options: StaticOptions): ReadonlyMap<string, StaticEntry> {
   const files = new Map<string, StaticEntry>()
   let entries
   try { entries = readdirSync(staticDir, { withFileTypes: true }) } catch (err) {
@@ -156,18 +168,17 @@ function readStaticFiles(staticDir: string): ReadonlyMap<string, StaticEntry> {
     throw err
   }
   for (const entry of entries) {
-    // `isFile()` filters subdirectories, symlinks, FIFOs etc. The
-    // build emits a flat tree; dropping anything else keeps the
-    // surface minimal even if a stray non-file sneaks in.
-    if (!entry.isFile()) continue
-    files.set(entry.name, buildEntry(staticDir, entry.name))
+    // Exclude subdirectories, symlinks and non-file entries.
+    if (!entry.isFile() || (options.indexOnly && entry.name !== 'index.html')) continue
+    files.set(entry.name, buildEntry(staticDir, entry.name, deepviewScanServer, options.transformIndex))
   }
   return files
 }
 
-function buildEntry(staticDir: string, name: string): StaticEntry {
+function buildEntry(staticDir: string, name: string, deepviewScanServer: string | null = null, transformIndex: (html: string) => string = html => html): StaticEntry {
   const ext = extname(name)
-  const raw = readFileSync(join(staticDir, name))
+  const source = readFileSync(join(staticDir, name))
+  const raw = name === 'index.html' ? Buffer.from(transformIndex(scanServerHtml(source.toString('utf8'), deepviewScanServer))) : source
   const type = CONTENT_TYPE[ext] ?? 'application/octet-stream'
   // HTML: lift `<link rel="(module)preload" …>` into a Link header and
   // drop the tags from the served body. ETag + compression run against
@@ -183,13 +194,12 @@ function buildEntry(staticDir: string, name: string): StaticEntry {
   // collision-resistance against the ~tens of files we load.
   const etag = `"${createHash('sha256').update(identity).digest('hex').slice(0, 32)}"`
   const isCompressible = COMPRESSIBLE.has(ext)
-  // Brotli quality 11 is the maximum — slow at compress time but
-  // we pay it once at boot and ship the smaller bytes on every
-  // request thereafter. text mode tells the encoder we're working
+  // Brotli quality 9 limits boot-time compression work, including on
+  // serverless cold starts. Text mode tells the encoder we're working
   // on UTF-8 text (every COMPRESSIBLE entry is text-shaped).
   const br = isCompressible ? brotliCompressSync(identity, {
     params: {
-      [zlibConstants.BROTLI_PARAM_QUALITY]: 11,
+      [zlibConstants.BROTLI_PARAM_QUALITY]: 9,
       [zlibConstants.BROTLI_PARAM_MODE]: zlibConstants.BROTLI_MODE_TEXT,
     },
   }) : null

package/{server → server-e2e}/sync-handlers.ts

@@ -26,6 +26,8 @@ type WireRevision = {
   signature: string
 }
 
+type SubscriptionLookup = { resume: () => void }
+
 // Structured result of the shared save pipeline (`commitSave`), rendered
 // per transport: WS → protocol frames; REST → JSON + HTTP status.
 type SaveOutcome =
@@ -79,6 +81,7 @@ export type SyncHandlersDeps = {
   // payload budget. Optional: a SQLite deployment passes a no-op.
   publishRevision: (tag: string, revisionId: string) => void
   subscribe: (socket: WebSocket, tag: string) => void
+  pauseBroadcasts: (socket: WebSocket) => () => void
   getNonce: (socket: WebSocket) => string | undefined
   requiresAuth: (socket: WebSocket) => boolean
   // Whether an operator password is configured. The REST save plane's
@@ -101,7 +104,7 @@ export type SyncHandlersDeps = {
 export type SyncHandlers = {
   handleSave: (socket: WebSocket, msg: SaveMsg) => Promise<void>
   // Session-independent REST save plane (`POST /api/sync/save`), wired into
-  // the HTTP dispatcher in server/http.ts. Runs the same pipeline as
+  // the HTTP dispatcher in server-e2e/http.ts. Runs the same pipeline as
   // `handleSave` and renders the outcome as a JSON response.
   handleSaveRest: (req: IncomingMessage, res: ServerResponse) => Promise<void>
   handleSubscribe: (socket: WebSocket, msg: SubscribeMsg) => Promise<void>
@@ -112,6 +115,9 @@ export type SyncHandlers = {
 
 export function createSyncHandlers(deps: SyncHandlersDeps): SyncHandlers {
   const { handle, send, broadcast, publishRevision, subscribe, getNonce, requiresAuth, passwordConfigured, sendUnauthorized, workspaceExists, objstoreResources, debug } = deps
+  // Only the newest lookup for a socket/tag may publish a snapshot.
+  // Versions cannot order different object incarnations (or deletions).
+  const subscriptionLookups = new WeakMap<WebSocket, Map<string, SubscriptionLookup>>()
 
   // Typed wrapper for the three `workspace-save-error` emit sites
   // (too-large at handleSave, stale-base after the catch-up, busy at
@@ -238,6 +244,14 @@ export function createSyncHandlers(deps: SyncHandlersDeps): SyncHandlers {
       // chain in the 409 body. Either way the catch-up clears the client's
       // pending and the error is a no-op on the now-missing pending (a
       // recoverable race — client rebases + re-saves).
+      //
+      // The catch-up CAN be empty: a client holding a base from a chain
+      // this deployment no longer has (wiped / moved DB, SQLite→Neon
+      // migration — head=null, no keyframe, no rows) gets `revisions: []`.
+      // The client detects that shape (pending survives the catch-up) and
+      // answers with a full-state push re-anchored at base=null, which
+      // commits as the new chain root — see the client's
+      // `handleSaveError` stale-base branch.
       const revisions = chainForWire(await chainFrom(handle, tag, baseNorm))
       if (debug) console.log(`save (stale base ${baseNorm} vs head ${commit.head}) → chain ${revisions.length}`)
       return { kind: 'stale-base', base: baseNorm, revisions }
@@ -291,7 +305,7 @@ export function createSyncHandlers(deps: SyncHandlersDeps): SyncHandlers {
   // maps the outcome to a JSON + HTTP status the client switches on. SSE-mode
   // clients POST here so a save doesn't take over their event-stream; a 401
   // routes them to the in-band frame (which runs the operator auth flow).
-  // Mounted + gated (same-origin, shutdown, idle-timeout) in server/http.ts.
+  // Mounted + gated (same-origin, shutdown, idle-timeout) in server-e2e/http.ts.
   async function handleSaveRest(req: IncomingMessage, res: ServerResponse): Promise<void> {
     const body = await readSaveBody(req)
     if (!body || typeof body !== 'object') { respondJson(res, 400, { reason: 'bad-request' }); return }
@@ -340,34 +354,54 @@ export function createSyncHandlers(deps: SyncHandlersDeps): SyncHandlers {
       return
     }
     const tag = msg.workspaceTag
-    subscribe(socket, tag)
-    // Explicit ack — distinguishes "the server processed my subscribe
-    // and registered me as a peer" from "the WebSocket is open". A
-    // client that sent a malformed / bad-sig subscribe never gets this;
-    // a client that did gets one before the chain arrives. Lets the UI
-    // surface a `connecting → online` transition based on real handshake
-    // completion, not just socket state.
-    //
-    // The ack also carries the objstore inventory snapshot: the same
-    // subscribe that registers this socket for objstore-put / -deleted
-    // broadcasts seeds the client's initial inventory in one handshake.
-    // The client keeps it live thereafter from those broadcasts.
-    // Returns [] for a triage-only workspace. A failing inventory
-    // lookup must NOT sink the subscribe — degrade to an empty snapshot
-    // (broadcasts will fill it in) so the ack + chain still go out.
-    let resources: object[] = []
-    try { resources = await objstoreResources(tag) }
-    catch (err) { if (debug) console.warn('subscribe: objstore inventory lookup failed', debugTag(tag), err) }
-    send(socket, { type: 'workspace-subscribed', workspaceTag: tag, resources })
-    // `from` is the last revision id the client claims to have applied —
-    // now a base64url string, not an integer. We send only revisions
-    // after that. Client lying about `from` just means they get a
-    // smaller catch-up — their subsequent saves will reveal stale state
-    // on the usual base-mismatch path. Null / missing → full chain.
-    const fromId = typeof msg.from === 'string' ? msg.from : null
-    const revisions = chainForWire(await chainFrom(handle, tag, fromId))
-    if (debug) console.log(`subscribe ${debugTag(tag)} from=${fromId?.slice(0, 8) ?? 'null'} → chain ${revisions.length}`)
-    send(socket, { type: 'workspace-state', workspaceTag: tag, revisions })
+    const lookups = subscriptionLookups.get(socket) ?? new Map<string, SubscriptionLookup>()
+    subscriptionLookups.set(socket, lookups)
+    const previous = lookups.get(tag)
+    const resume = deps.pauseBroadcasts(socket)
+    const lookup = { resume }
+    lookups.set(tag, lookup)
+    // Acquire the replacement's pause before releasing its predecessor so
+    // buffered broadcasts cannot overtake the replacement snapshot. A hung
+    // obsolete read must not keep the whole socket paused. The hub's release
+    // is idempotent, so the old finally can still call it when the read ends.
+    previous?.resume()
+    try {
+      subscribe(socket, tag)
+      // Explicit ack — distinguishes "the server processed my subscribe
+      // and registered me as a peer" from "the WebSocket is open". A
+      // client that sent a malformed / bad-sig subscribe never gets this;
+      // a client that did gets one before the chain arrives. Lets the UI
+      // surface a `connecting → online` transition based on real handshake
+      // completion, not just socket state.
+      //
+      // The ack also carries the objstore inventory snapshot: the same
+      // subscribe that registers this socket for objstore-put / -deleted
+      // broadcasts seeds the client's initial inventory in one handshake.
+      // The client keeps it live thereafter from those broadcasts.
+      // Returns [] for a triage-only workspace. A lookup failure is NOT an
+      // empty inventory: clients interpret absent resources as deletions.
+      // Reconnect to retry the complete handshake on either transport.
+      const resources = await objstoreResources(tag)
+      if (socket.readyState !== socket.OPEN || lookups.get(tag) !== lookup) return
+      // `from` is the last revision id the client claims to have applied —
+      // now a base64url string, not an integer. We send only revisions
+      // after that. Client lying about `from` just means they get a
+      // smaller catch-up — their subsequent saves will reveal stale state
+      // on the usual base-mismatch path. Null / missing → full chain.
+      const fromId = typeof msg.from === 'string' ? msg.from : null
+      const revisions = chainForWire(await chainFrom(handle, tag, fromId))
+      if (socket.readyState !== socket.OPEN || lookups.get(tag) !== lookup) return
+      if (debug) console.log(`subscribe ${debugTag(tag)} from=${fromId?.slice(0, 8) ?? 'null'} → chain ${revisions.length}`)
+      send(socket, { type: 'workspace-subscribed', workspaceTag: tag, resources })
+      send(socket, { type: 'workspace-state', workspaceTag: tag, revisions })
+    } catch (err) {
+      if (lookups.get(tag) !== lookup) return
+      if (debug) console.warn('subscribe: snapshot lookup failed', debugTag(tag), err)
+      socket.close(1011, 'subscription unavailable')
+    } finally {
+      if (lookups.get(tag) === lookup) lookups.delete(tag)
+      resume()
+    }
   }
 
   return { handleSave, handleSaveRest, handleSubscribe, sendSaveError }

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

@@ -16,6 +16,7 @@ import { Buffer } from 'node:buffer'
 import type { IncomingMessage as HttpRequest } from 'node:http'
 import { decodeUtf8 } from '../common/utf8.js'
 import type { SaveErrorReason } from '../common/save-error-reason.ts'
+import type { ServerInfo } from '../common/server-info.ts'
 import { Peer, type PeerRegistry } from './peer.ts'
 import { errMsg, errStack, randomId } from './util.ts'
 import type { SaveMsg, SubscribeMsg } from './sign.ts'
@@ -36,6 +37,9 @@ type IncomingMessage = {
 // SSE path doesn't need them.
 export type PeerConnectionDeps = {
   peers: PeerRegistry
+  // The mode this server advertises, emitted as the first `server-info`
+  // frame on every connection (see setupPeerConnection).
+  serverInfo: ServerInfo
   send: (socket: WebSocket, msg: object) => void
   unsubscribeAll: (socket: WebSocket) => void
   handleSave: (socket: WebSocket, msg: SaveMsg) => Promise<void>
@@ -60,7 +64,7 @@ export type WsServerDeps = PeerConnectionDeps & {
 // `as unknown as WebSocket`; only the subset both expose is used.
 export function setupPeerConnection(socket: WebSocket, req: HttpRequest, deps: PeerConnectionDeps): void {
   const {
-    peers, send, unsubscribeAll, handleSave, handleSubscribe, handleAuthenticate,
+    peers, serverInfo, send, unsubscribeAll, handleSave, handleSubscribe, handleAuthenticate,
     sendSaveError, objstore, track, isShuttingDown, maxInflightPerSocket, debug,
   } = deps
   if (debug) console.log(`connect from ${req.socket.remoteAddress}`)
@@ -71,13 +75,20 @@ export function setupPeerConnection(socket: WebSocket, req: HttpRequest, deps: P
   const peer = new Peer(randomId())
   peers.set(socket, peer)
   socket.on('pong', () => { peer.alive = true })
-  // Issue the per-connection challenge nonce BEFORE the client can
-  // send anything that needs it. The client signs it into every
-  // `workspace-subscribe` (see canonicalSubscribe in server/sign.ts);
-  // a captured subscribe frame can't be replayed from a different
-  // connection because that connection's nonce differs and the
+  // Issue the per-connection challenge nonce FIRST — before the client can
+  // send anything that needs it, AND as frame #0 so clients/tests that
+  // positionally read the first frame as the challenge keep working. The
+  // client signs it into every `workspace-subscribe` (see canonicalSubscribe
+  // in server-e2e/sign.ts); a captured subscribe frame can't be replayed from
+  // a different connection because that connection's nonce differs and the
   // signature won't verify against the new canonical bytes. Round-9 H2.
   send(socket, { type: 'challenge', nonce: peer.challenge })
+  // Then advertise the sync protocol (the mode probe), right after the
+  // challenge — the WS plane and the SSE fallback share this path. A client
+  // uses it to detect the mode, cache it, and refuse a cross-mode switch.
+  // Unauthenticated + mode-agnostic; an older client ignores it (predicate
+  // readers skip it; the workspaceTag demux drops it).
+  send(socket, { type: 'server-info', ...serverInfo })
   // Per-socket handlers are DELIBERATELY NOT serialized (vs the
   // client-side `messageQueue = messageQueue.then(...)` Promise
   // chain inside `client/triage-sync.ts:onTransportMessage`).
@@ -86,10 +97,10 @@ export function setupPeerConnection(socket: WebSocket, req: HttpRequest, deps: P
   // boundaries inside the handlers. Per-resource correctness needs
   // no in-process lock: `commitRevision` resolves concurrent saves
   // via its single gated INSERT (one snapshot + the
-  // `UNIQUE(workspace_tag, seq)` PK — see `server/db.ts`), and the
+  // `UNIQUE(workspace_tag, seq)` PK — see `server-e2e/db.ts`), and the
   // objstore handlers (`commitPut` / `beginPut` / `deleteObject`)
   // via the version compare-and-set + content-addressing (see
-  // `server/objstore/store.ts`), backed by post-await
+  // `server-e2e/objstore/store.ts`), backed by post-await
   // `readyState === OPEN` rechecks in every objstore handler. The
   // unbounded fan-out is capped by `maxInflightPerSocket` (see
   // also the `'busy'` NACK at the cap below). Concurrent dispatch
@@ -129,7 +140,7 @@ export function setupPeerConnection(socket: WebSocket, req: HttpRequest, deps: P
     // shedding load. Pings go through a fast inline `send(pong)`
     // path BELOW that doesn't bump the per-socket inflight counter,
     // so a ping-spam at the cap can't outrun the gate. Transport
-    // audit `server/index.ts:590` + post-#58 audit follow-up.
+    // audit `server-e2e/index.ts:590` + post-#58 audit follow-up.
     if (parsed.type === 'ping') {
       send(socket, { type: 'pong' })
       return