HTTP transport: drop WS server, offline send queue + dead-stream watchdog

Gateway (docs/19):
- Remove ws_server.py; frame dispatch factored into dispatch.py
- http_server: media upload/pull, pairing over HTTP
- protocol: media frames mirrored; tests + ws_probe updated for HTTP

App:
- HttpGateway: postFrame/uploadMedia/pullMedia no longer throw on
  network failure (PostResult ok=false / Result.failure) — uncaught
  SocketTimeoutException on Dispatchers.Default crashed the app
- GatewayClient: dead-stream watchdog (health probe every 10s, 2
  failures -> redial in ~20s instead of the 45s SSE read timeout);
  state flips to Reconnecting when the stream dies, restored from the
  last hello.ack on long-poll success; poke() + backoff reset on app
  resume (MainActivity.onResume)
- Offline sends: composer enabled while disconnected; a send with no
  response (status 0) stays queued (Pending) and is auto-resent on the
  next (re)connect after a 2s outbox-replay grace; gateway 4xx
  rejections fail the bubble (tap to retry, no auto-loop)
- ChatStore: echo-replace and thread-relocate also match Failed
  bubbles (POST response lost in a network drop); loadHistory dedupes
  local failed bubbles the server already has; failMessage()
- MainActivity: poke() on resume so a backgrounded app reconnects
  promptly instead of waiting out the backoff

app/shared/src/commonMain/kotlin/iris/data/ChatStore.kt

@@ -249,10 +249,14 @@ class ChatStore {
                     )
                 list.toMutableList().also { it[byId] = updated }
             } else if (p.role == ROLE_USER) {
-                // Replace the matching optimistic pending bubble (server echo).
+                // Replace the matching optimistic bubble (server echo). Also
+                // matches a FAILED bubble: the send may have arrived after
+                // its POST response was lost in a network drop — the echo is
+                // the proof of delivery, so reconcile instead of duplicating.
                 val pendingIdx =
                     list.indexOfLast {
-                        it is MessageItem && it.pending && it.role == ROLE_USER && it.text == p.text
+                        it is MessageItem && it.role == ROLE_USER && it.text == p.text &&
+                            (it.pending || it.status == MsgStatus.Failed)
                     }
                 if (pendingIdx >= 0) {
                     list.toMutableList().also {
@@ -315,7 +319,8 @@ class ChatStore {
         val flatList = map[flatLane].orEmpty()
         val idx =
             flatList.indexOfLast {
-                it is MessageItem && it.pending && it.role == ROLE_USER && it.text == p.text
+                it is MessageItem && it.role == ROLE_USER && it.text == p.text &&
+                    (it.pending || it.status == MsgStatus.Failed)
             }
         if (idx < 0) return
         map[flatLane] = flatList.toMutableList().also { it.removeAt(idx) }
@@ -613,6 +618,31 @@ class ChatStore {
         if (changed) _lanes.value = map
     }
 
+    /** M7: mark a single user message as failed (the send never reached the
+     *  gateway — network drop, or the gateway rejected it); tap the bubble
+     *  to retry. */
+    fun failMessage(messageId: String) {
+        val map = _lanes.value.toMutableMap()
+        var changed = false
+        for ((lane, list) in map) {
+            val updated =
+                list.map { item ->
+                    if (item is MessageItem && item.id == messageId && item.role == ROLE_USER &&
+                        item.status != MsgStatus.Failed
+                    ) {
+                        item.copy(pending = false, status = MsgStatus.Failed)
+                    } else {
+                        item
+                    }
+                }
+            if (updated != list) {
+                map[lane] = updated
+                changed = true
+            }
+        }
+        if (changed) _lanes.value = map
+    }
+
     /**
      * Remove messages by id from every lane (a `message.deleted` frame). The
      * server is authoritative: the frame carries no lane, and a message id is
@@ -713,9 +743,24 @@ class ChatStore {
     ) {
         updateLane(lane) { list ->
             val historyIds = messages.map { it.id }.toSet()
+            // A local FAILED bubble whose text+media matches a history user
+            // message was actually delivered (the POST response was lost in
+            // the network drop) — the history copy is authoritative, so drop
+            // the local duplicate instead of showing the message twice.
+            val historyUser = messages.filter { it.role == ROLE_USER }
             val preserved =
                 list.filter { item ->
-                    item !is MessageItem || item.id !in historyIds
+                    if (item !is MessageItem) return@filter true
+                    if (item.id in historyIds) return@filter false
+                    if (item.role == ROLE_USER && item.status == MsgStatus.Failed &&
+                        historyUser.any {
+                            it.text == item.text &&
+                                it.media.map { m -> m.mediaId } == item.media.map { m -> m.mediaId }
+                        }
+                    ) {
+                        return@filter false
+                    }
+                    true
                 }
             // ts of every item in the current lane: ts-less items (commentary,
             // tool cards) inherit the ts of the item before them, so a tool

app/shared/src/commonMain/kotlin/iris/data/SecureStore.kt

@@ -6,10 +6,10 @@ package iris.data
  * SharedPreferences for M1 dev, file on desktop).
  */
 interface SecureStore {
-    /** ws(s)://host:port/ws */
+    /** http(s)://host:port (legacy ws(s):// URLs are still accepted) */
     var serverUrl: String
 
-    /** ANDROID_TOKEN presented in the hello frame. */
+    /** ANDROID_TOKEN presented in the auth header. */
     var token: String
 
     /** Stable app-generated device id (persisted). */

app/shared/src/commonMain/kotlin/iris/net/GatewayClient.kt

@@ -1,34 +1,19 @@
 package iris.net
 
 import iris.data.SecureStore
-import iris.media.FileSource
-import iris.media.Sha256
 import iris.protocol.ChannelInfo
-import iris.protocol.ErrorPayload
 import iris.protocol.Frame
 import iris.protocol.HelloAckPayload
-import iris.protocol.IrisJson
-import iris.protocol.MediaPullEndPayload
-import iris.protocol.MediaUploadAckPayload
 import iris.protocol.ServerCaps
-import iris.protocol.TYPE_ERROR
-import iris.protocol.TYPE_HELLO_ACK
-import iris.protocol.TYPE_MEDIA_PULL_END
-import iris.protocol.TYPE_MEDIA_UPLOAD_ACK
-import iris.protocol.TYPE_PONG
-import iris.protocol.helloFrame
-import iris.protocol.mediaPullFrame
-import iris.protocol.mediaUploadEndFrame
-import iris.protocol.mediaUploadStartFrame
 import iris.protocol.messageSendFrame
-import iris.protocol.pingFrame
 import iris.protocol.syncFrame
 import iris.util.IrisLog
+import kotlinx.coroutines.CancellationException
 import kotlinx.coroutines.CompletableDeferred
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Job
-import kotlinx.coroutines.async
 import kotlinx.coroutines.channels.Channel
+import kotlinx.coroutines.coroutineScope
 import kotlinx.coroutines.currentCoroutineContext
 import kotlinx.coroutines.delay
 import kotlinx.coroutines.flow.MutableSharedFlow
@@ -44,25 +29,19 @@ import kotlinx.coroutines.sync.withLock
 import kotlinx.coroutines.withTimeout
 import kotlinx.coroutines.withTimeoutOrNull
 import okhttp3.OkHttpClient
-import okhttp3.Request
-import okhttp3.Response
-import okhttp3.WebSocket
-import okhttp3.WebSocketListener
-import okio.ByteString
-import okio.ByteString.Companion.toByteString
 import java.util.concurrent.TimeUnit
 import kotlin.random.Random
-import kotlin.time.TimeMark
-import kotlin.time.TimeSource
 
 /**
- * OkHttp WebSocket client for the hermes android gateway (docs/10 §10.3).
+ * HTTP client for the hermes android gateway (docs/19).
  *
- * - connect + hello (real auth leg), hello.ack
+ * HTTP is the only transport: send via `POST /v1/frame`, receive over SSE
+ * `/v1/events` (long-poll fallback), media via `POST/GET /v1/media`.
+ *
+ * - connect: health probe + SSE hello (the HTTP hello.ack)
  * - reconnect: exponential backoff + jitter; re-hello on every (re)connect
- * - heartbeat: app-level ping every 20s; reap after ~60s of silence
- * - events: server frames (minus hello.ack) on [events]
- * - request/response correlation by id (M2+ consumers)
+ * - events: server frames on [events]
+ * - request/response correlation by id
  */
 class GatewayClient(
     private val scope: CoroutineScope,
@@ -73,33 +52,14 @@ class GatewayClient(
 
         data object Connecting : State
 
-        /** Common surface of [Connected] and [HttpFallback]: both carry the
-         *  hello.ack data (caps, channels, push watermark). */
-        interface HelloInfo {
-            val caps: ServerCaps
-            val channels: List<ChannelInfo>
-            val lastPushedCursor: Long
-        }
-
         data class Connected(
-            override val caps: ServerCaps,
-            override val channels: List<ChannelInfo>,
+            val caps: ServerCaps,
+            val channels: List<ChannelInfo>,
             /** M5: highest outbox cursor already pushed to this device
              *  (from hello.ack; 0 = never). Sync-replayed frames at/below
              *  it must not re-post system notifications (docs/08 §8.7). */
-            override val lastPushedCursor: Long = 0,
-        ) : State,
-            HelloInfo
-
-        /** docs/19: the WS is down but the gateway is reachable over the
-         *  HTTP leg — sendable (POST /v1/frame) + receiving (SSE/long-poll).
-         *  Media is unavailable until the WS is back. */
-        data class HttpFallback(
-            override val caps: ServerCaps,
-            override val channels: List<ChannelInfo>,
-            override val lastPushedCursor: Long = 0,
-        ) : State,
-            HelloInfo
+            val lastPushedCursor: Long = 0,
+        ) : State
 
         data object Reconnecting : State
 
@@ -125,53 +85,42 @@ class GatewayClient(
             .build()
 
     private var connectJob: Job? = null
-    private var socket: WebSocket? = null
     private var nextRequestId = 1
     private var attempt = 0
 
+    // Set by poke() (app returned to the foreground): the connect loop's
+    // backoff waits in 500 ms slices and re-probes immediately when set.
+    @Volatile
+    private var wakeRequested = false
+
     // True once a connection has been established this session; reset by
     // start(). Drives Connecting (first dial) vs Reconnecting (redial after a
     // drop) so the UI can show the right status without a blocking screen.
     private var hasConnected = false
-    private var lastLiveness: TimeMark = TimeSource.Monotonic.markNow()
     private val pending = mutableMapOf<Int, CompletableDeferred<Frame>>()
 
-    // docs/19: HTTP fallback leg (the "HTTP leg"). [http] is created lazily
-    // from the stored WS URL; [httpJob] runs the SSE/long-poll receive loop;
-    // [httpCursor] is the resume cursor (SSE id / outbox high-water mark).
+    // HTTP leg: [http] is created lazily from the stored URL; [httpCursor] is
+    // the resume cursor (SSE id / outbox high-water mark).
     private var http: HttpGateway? = null
-    private var httpJob: Job? = null
     private var httpCursor: Long = 0
     private var sseFailures = 0
     private var usingLongPoll = false
-    // Last hello.ack payload (WS or SSE) — used to restore State.Connected
-    // after a fallback/WS state race in the connect loop.
+
+    // Last hello.ack payload — used to restore State.Connected after a
+    // reconnect state race in the connect loop.
     private var lastAck: HelloAckPayload? = null
 
-    // M4: binary frames (media upload chunks / pull stream) have no per-frame
-    // id, so at most one binary session is active per socket. The gateway
-    // allows one upload per connection; pull is request/response.
-    private sealed interface BinarySession {
-        data class Pulling(
-            val requestId: Int,
-            val chunks: Channel<ByteArray>,
-            val end: CompletableDeferred<Frame>,
-        ) : BinarySession
-    }
-
-    private var binarySession: BinarySession? = null
-
     /**
-     * Fired promptly (on the WS thread) the moment `hello.ack` is received —
-     * on every (re)connect. Used for time-critical work that must not wait for
-     * the state collector, which can be starved for seconds during app startup
-     * (Dispatchers.Default) and would push a history request past a flaky
-     * network's window. Set before [start].
+     * Fired promptly the moment the SSE hello (hello.ack) is received — on
+     * every (re)connect. Used for time-critical work that must not wait for
+     * the state collector, which can be starved for seconds during app
+     * startup (Dispatchers.Default) and would push a history request past a
+     * flaky network's window. Set before [start].
      */
-    var onHelloAck: ((State.HelloInfo) -> Unit)? = null
+    var onHelloAck: ((State.Connected) -> Unit)? = null
 
-    // M4: only one pull may be in flight at a time (binarySession is a single
-    // slot). Serialize concurrent offers so their byte streams don't interleave.
+    // Only one pull may be in flight at a time. Serialize concurrent offers so
+    // their byte streams don't interleave.
     private val pullMutex = Mutex()
 
     // ── Lifecycle ─────────────────────────────────────────────────────────
@@ -184,16 +133,25 @@ class GatewayClient(
         connectJob = scope.launch { connectLoop() }
     }
 
-    /** Stop the connect loop and close the socket. */
+    /** Stop the connect loop. */
     fun stop() {
         connectJob?.cancel()
         connectJob = null
-        stopHttpLeg()
-        socket?.close(1000, "client shutdown")
-        socket = null
         _state.value = State.Disconnected
     }
 
+    /**
+     * Call when the app returns to the foreground: if the connect loop is
+     * between attempts (backing off after failed health probes — up to 30 s),
+     * wake it so it re-probes immediately instead of making the user wait out
+     * the backoff with a "Connecting…" banner. No-op while connected.
+     */
+    fun poke() {
+        if (_state.value is State.Connected) return
+        attempt = 0
+        wakeRequested = true
+    }
+
     /** Re-pair: stop, then start fresh (used after saving new settings). */
     fun restart() {
         stop()
@@ -209,105 +167,87 @@ class GatewayClient(
                 return
             }
             _state.value = if (hasConnected) State.Reconnecting else State.Connecting
-            // docs/19: race the WS dial against the HTTP health probe. If the
-            // gateway is alive over HTTP, the app can send immediately
-            // (fallback) without waiting out the WS dial timeout — the key
-            // UX fix (sendable in < 1 s on a dead WS port).
-            val dialDeferred = scope.async { dial(url, token) }
+            val gw = httpGateway() ?: continue
+            // Health probe: if the gateway is alive, open the SSE receive loop
+            // (which delivers the hello.ack). Otherwise back off and retry.
             val healthOk =
-                withTimeoutOrNull(2_000) {
-                    httpHealthy()
-                } ?: false
-            if (healthOk) enterHttpFallback()
-            val dial = dialDeferred.await()
-            when (val result = dial.result) {
-                is DialResult.AuthFailed -> {
-                    stopHttpLeg()
-                    _state.value = State.AuthFailed(result.message)
-                    dial.socket.close(1000, "auth failed")
-                    return
-                }
-
-                DialResult.Connected -> {
-                    hasConnected = true
-                    attempt = 0
-                    // WS is up again: back to WS-only (media available).
-                    stopHttpLeg()
-                    lastLiveness = TimeSource.Monotonic.markNow()
-                    // Restore Connected if the fallback state won the race
-                    // (health landed before hello.ack).
-                    lastAck?.let {
-                        _state.value =
-                            State.Connected(it.serverCaps, it.channels, it.lastPushedCursor)
-                    }
-                    dial.closed.await()
-                    if (!currentCoroutineContext().isActive) return
-                    // WS dropped: fall back to HTTP immediately (no backoff
-                    // gate on the send path), then redial below.
-                    enterHttpFallback()
-                }
-
-                is DialResult.Failed -> {
-                    attempt++
-                    delay(backoffMs(attempt))
+                try {
+                    gw.health()
+                } catch (e: Exception) {
+                    false
                 }
+            if (!healthOk) {
+                attempt++
+                backoffOrWake(backoffMs(attempt))
+                continue
             }
+            attempt = 0
+            hasConnected = true
+            sseFailures = 0
+            usingLongPoll = false
+            httpCursor = store.syncCursor
+            // Provisional Connected state (previous caps/channels) until the
+            // SSE hello arrives with the real ones.
+            val prev = _state.value
+            _state.value =
+                State.Connected(
+                    caps = (prev as? State.Connected)?.caps ?: ServerCaps(),
+                    channels = (prev as? State.Connected)?.channels ?: emptyList(),
+                    lastPushedCursor = (prev as? State.Connected)?.lastPushedCursor ?: 0,
+                )
+            // Run the HTTP receive loop (SSE/long-poll) until cancelled.
+            coroutineScope {
+                val receiveJob = launch { httpReceiveLoop(gw) }
+                // Dead-stream watchdog: the SSE read timeout (45 s) is the
+                // only in-stream dead-connection detector; probe /v1/health
+                // in parallel so a dropped network flips the state to
+                // Reconnecting within ~20 s (2 failed probes) instead of 45,
+                // and a stuck stream can't keep a stale "Connected".
+                var probeFailures = 0
+                while (receiveJob.isActive) {
+                    delay(10_000)
+                    val ok =
+                        try {
+                            gw.health()
+                        } catch (e: Exception) {
+                            false
+                        }
+                    probeFailures = if (ok) 0 else probeFailures + 1
+                    if (probeFailures >= 2) {
+                        receiveJob.cancel()
+                        break
+                    }
+                }
+                receiveJob.join()
+            }
+            // Terminal auth failure: don't redial with the same bad token.
+            if (_state.value is State.AuthFailed) return
         }
     }
 
-    // ── docs/19: HTTP fallback leg ────────────────────────────────────────
+    // ── HTTP receive leg ──────────────────────────────────────────────────
 
-    /** Lazily build the HTTP client from the stored WS URL. */
+    /** Lazily build the HTTP client from the stored URL. */
     private fun httpGateway(): HttpGateway? {
         val url = store.serverUrl.trim()
         val token = store.token
         if (url.isBlank() || token.isBlank()) return null
         return http
-            ?: HttpGateway(client, HttpGateway.deriveHttpUrl(url), token, store.deviceId)
-                .also { http = it }
-    }
-
-    private suspend fun httpHealthy(): Boolean =
-        try {
-            httpGateway()?.health() ?: false
-        } catch (e: Exception) {
-            false
-        }
-
-    /**
-     * Enter [State.HttpFallback]: open the SSE (or long-poll) receive loop
-     * from the saved sync cursor. Idempotent; a no-op while WS-connected.
-     */
-    private fun enterHttpFallback() {
-        if (_state.value is State.Connected) return
-        val gw = httpGateway() ?: return
-        sseFailures = 0
-        usingLongPoll = false
-        httpCursor = store.syncCursor
-        // Provisional state (previous caps/channels) until the SSE hello
-        // arrives with the real ones.
-        val prev = _state.value
-        _state.value =
-            State.HttpFallback(
-                caps = (prev as? State.HelloInfo)?.caps ?: ServerCaps(),
-                channels = (prev as? State.HelloInfo)?.channels ?: emptyList(),
-                lastPushedCursor = (prev as? State.HelloInfo)?.lastPushedCursor ?: 0,
-            )
-        httpJob?.cancel()
-        httpJob = scope.launch { httpReceiveLoop(gw) }
-    }
-
-    private fun stopHttpLeg() {
-        httpJob?.cancel()
-        httpJob = null
-        sseFailures = 0
-        usingLongPoll = false
+            ?: HttpGateway(
+                client,
+                HttpGateway.deriveHttpUrl(url),
+                token,
+                store.deviceId,
+                deviceName = store.deviceName,
+                fcmToken = { store.fcmToken.ifBlank { null } },
+                ntfyTopic = { store.ntfyTopic.ifBlank { null } },
+            ).also { http = it }
     }
 
     /**
      * The HTTP receive loop: SSE by default; after two consecutive SSE open
-     * failures (buffering proxy) it switches to long-poll until the next
-     * full (re)connect (docs/19 §19.6).
+     * failures (buffering proxy) it switches to long-poll until the next full
+     * (re)connect (docs/19 §19.6). Runs until the coroutine is cancelled.
      */
     private suspend fun httpReceiveLoop(gw: HttpGateway) {
         var backoff = 1_000L
@@ -317,7 +257,14 @@ class GatewayClient(
                     val res = gw.poll(httpCursor)
                     res.frames.forEach { emitHttpFrame(it) }
                     if (res.cursor > httpCursor) httpCursor = res.cursor
+                    // The poll answered: the link is back (long-poll has no
+                    // hello — restore the Connected state from the last one).
+                    restoreConnected()
+                } catch (e: HttpGateway.HttpAuthException) {
+                    _state.value = State.AuthFailed("gateway rejected the pairing token (HTTP 401)")
+                    return
                 } catch (e: Exception) {
+                    markStreamLost()
                     IrisLog.w("http poll failed: ${e.message}")
                     delay(backoff)
                     backoff = minOf(backoff * 2, 15_000)
@@ -332,8 +279,12 @@ class GatewayClient(
                     )
                     // Clean EOF: reconnect immediately.
                     backoff = 1_000L
+                } catch (e: HttpGateway.HttpAuthException) {
+                    _state.value = State.AuthFailed("gateway rejected the pairing token (HTTP 401)")
+                    return
                 } catch (e: Exception) {
                     sseFailures++
+                    markStreamLost()
                     if (sseFailures >= 2) {
                         // SSE seems blocked: switch to long-poll.
                         usingLongPoll = true
@@ -350,12 +301,35 @@ class GatewayClient(
     /** The SSE `event: hello` (the HTTP hello.ack). */
     private fun onHttpHello(ack: HelloAckPayload) {
         lastAck = ack
-        val fb = State.HttpFallback(ack.serverCaps, ack.channels, ack.lastPushedCursor)
-        _state.value = fb
-        onHelloAck?.invoke(fb)
+        val connected = State.Connected(ack.serverCaps, ack.channels, ack.lastPushedCursor)
+        _state.value = connected
+        // M5: reconnect catch-up — replay frames parked while offline.
+        val local = store.syncCursor
+        if (local < ack.syncCursor) {
+            val id = nextRequestId++
+            scope.launch { httpGateway()?.postFrame(syncFrame(id, local)) }
+        }
+        // Prompt fast path (before the possibly-starved state collector).
+        onHelloAck?.invoke(connected)
     }
 
-    /** Deliver an HTTP-leg frame to the same sinks as a WS frame. */
+    /** The receive stream just died: don't keep claiming "Connected" while
+     *  between attempts (a stale green dot through a Wi-Fi drop). */
+    private fun markStreamLost() {
+        if (_state.value is State.Connected) _state.value = State.Reconnecting
+    }
+
+    /** The receive stream is open again (long-poll answered): the link is
+     *  back. Long-poll has no hello, so restore the Connected state from the
+     *  last hello.ack (the SSE path gets a fresh one). */
+    private fun restoreConnected() {
+        if (_state.value !is State.Reconnecting) return
+        _state.value =
+            lastAck?.let { State.Connected(it.serverCaps, it.channels, it.lastPushedCursor) }
+                ?: State.Connected(ServerCaps(), emptyList())
+    }
+
+    /** Deliver an HTTP-leg frame to the same sinks as any other frame. */
     private fun emitHttpFrame(frame: Frame) {
         _events.tryEmit(frame)
         frame.id?.let { id ->
@@ -363,207 +337,51 @@ class GatewayClient(
         }
     }
 
-    // ── Dial (one connect + hello) ────────────────────────────────────────
-
-    private sealed interface DialResult {
-        data object Connected : DialResult
-
-        data class AuthFailed(
-            val message: String,
-        ) : DialResult
-
-        data class Failed(
-            val message: String,
-        ) : DialResult
-    }
-
-    private data class Dial(
-        val result: DialResult,
-        val socket: WebSocket,
-        val closed: CompletableDeferred<Unit>,
-    )
-
-    private suspend fun dial(
-        url: String,
-        token: String,
-    ): Dial {
-        val closed = CompletableDeferred<Unit>()
-        val helloAck = CompletableDeferred<HelloAckPayload>()
-        val authError = CompletableDeferred<String>()
-        val fail = CompletableDeferred<String>()
-
-        val request = Request.Builder().url(url).build()
-        val ws =
-            client.newWebSocket(
-                request,
-                object : WebSocketListener() {
-                    override fun onOpen(
-                        webSocket: WebSocket,
-                        response: Response,
-                    ) {
-                        IrisLog.d("ws open (${response.code})")
-                        webSocket.send(
-                            helloFrame(
-                                token = token,
-                                deviceId = store.deviceId,
-                                deviceName = store.deviceName,
-                                fcmToken = store.fcmToken.ifBlank { null },
-                                ntfyTopic = store.ntfyTopic.ifBlank { null },
-                            ).toWire(),
-                        )
-                    }
-
-                    override fun onMessage(
-                        webSocket: WebSocket,
-                        text: String,
-                    ) {
-                        lastLiveness = TimeSource.Monotonic.markNow()
-                        val frame =
-                            try {
-                                IrisJson.instance.decodeFromString(Frame.serializer(), text)
-                            } catch (e: Exception) {
-                                // A dropped frame is silent data loss — log it (the
-                                // first bytes hint at which frame it was).
-                                IrisLog.e("frame decode failed (${text.length}B): $e :: ${text.take(120)}")
-                                return
-                            }
-                        when (frame.type) {
-                            TYPE_HELLO_ACK -> {
-                                val ack = frame.payloadAs<HelloAckPayload>()
-                                if (ack != null) helloAck.complete(ack)
-                            }
-
-                            TYPE_ERROR -> {
-                                val err = frame.payloadAs<ErrorPayload>()
-                                if (!authError.isCompleted) authError.complete(err?.message ?: "auth failed")
-                                // M7: post-connect error frames are app events, not
-                                // auth failures — let the controller react.
-                                _events.tryEmit(frame)
-                            }
-
-                            TYPE_PONG -> {
-                                Unit
-                            }
-
-                            else -> {
-                                _events.tryEmit(frame)
-                                frame.id?.let { id ->
-                                    pending[id]?.complete(frame)
-                                    // M4: terminal frame of a pull stream — close
-                                    // the chunk channel so the pull loop exits.
-                                    if (frame.type == TYPE_MEDIA_PULL_END) {
-                                        (binarySession as? BinarySession.Pulling)?.let {
-                                            it.chunks.close()
-                                            binarySession = null
-                                        }
-                                    }
-                                }
-                            }
-                        }
-                    }
-
-                    override fun onMessage(
-                        webSocket: WebSocket,
-                        bytes: ByteString,
-                    ) {
-                        lastLiveness = TimeSource.Monotonic.markNow()
-                        // M4: binary frames belong to the active pull stream
-                        // (uploads are outbound; stray inbound chunks are dropped).
-                        (binarySession as? BinarySession.Pulling)
-                            ?.chunks
-                            ?.trySend(bytes.toByteArray())
-                    }
-
-                    override fun onClosed(
-                        webSocket: WebSocket,
-                        code: Int,
-                        reason: String,
-                    ) {
-                        IrisLog.w("ws closed code=$code reason=\"$reason\"")
-                        closed.complete(Unit)
-                    }
-
-                    override fun onFailure(
-                        webSocket: WebSocket,
-                        t: Throwable,
-                        response: Response?,
-                    ) {
-                        IrisLog.e("ws failure: ${t.javaClass.simpleName}: ${t.message} (http=${response?.code})")
-                        fail.complete(t.message ?: "connection failed")
-                        closed.complete(Unit)
-                    }
-                },
-            )
-        socket = ws
-
-        val winner = CompletableDeferred<DialResult>()
-        helloAck.invokeOnCompletion { e ->
-            if (e == null) {
-                val ack = helloAck.getCompleted()
-                lastAck = ack
-                val connected = State.Connected(ack.serverCaps, ack.channels, ack.lastPushedCursor)
-                _state.value = connected
-                // M5: reconnect catch-up — replay frames parked while offline.
-                val local = store.syncCursor
-                if (local < ack.syncCursor) {
-                    val id = nextRequestId++
-                    ws.send(syncFrame(id, local).toWire())
-                }
-                // Prompt fast path (before the possibly-starved state collector).
-                onHelloAck?.invoke(connected)
-                winner.complete(DialResult.Connected)
-            }
-        }
-        authError.invokeOnCompletion { e ->
-            if (e == null) winner.complete(DialResult.AuthFailed(authError.getCompleted()))
-        }
-        fail.invokeOnCompletion { e ->
-            if (e == null) winner.complete(DialResult.Failed(fail.getCompleted()))
-        }
-        val result =
-            withTimeoutOrNull(15_000) { winner.await() }
-                ?: DialResult.Failed("timeout waiting for hello.ack")
-        return Dial(result, ws, closed)
-    }
-
     // ── Outbound ──────────────────────────────────────────────────────────
 
     /** Send a text message (fire-and-forget; the server echoes it back).
-     *  M4: [mediaRefs] reference completed uploads (media.upload.ack refs).
+     *  [mediaRefs] reference completed uploads (POST /v1/media refs).
      *  [autoThread] asks the gateway to mint a fresh thread for the message
-     *  (auto-threading, docs/06 §6.3). */
+     *  (auto-threading, docs/06 §6.3).
+     *  [onResult] is called with the POST's HTTP status — 0 means "no
+     *  response" (not connected, or the network failed); 2xx means the
+     *  gateway accepted it; 4xx is a gateway rejection (error frame already
+     *  delivered via [events]). Used to fail the optimistic bubble instead
+     *  of leaving it at "sending…" forever. */
     fun sendMessage(
         chatId: String,
         text: String,
         threadId: String? = null,
         mediaRefs: List<String> = emptyList(),
         autoThread: Boolean = false,
+        onResult: ((Int) -> Unit)? = null,
     ) {
-        val ws = socket
-        if (ws != null && _state.value is State.Connected) {
-            val id = nextRequestId++
-            ws.send(messageSendFrame(id, chatId, text, threadId, mediaRefs, autoThread).toWire())
+        if (_state.value !is State.Connected) {
+            onResult?.invoke(0)
             return
         }
-        // docs/19: WS down — route over the HTTP leg. Media is WS-only in
-        // v1 (uploads need the live connection), so mediaRefs are dropped in
-        // fallback (the UI disables the attach button in that state).
-        if (_state.value is State.HttpFallback) {
-            val id = nextRequestId++
-            scope.launch {
+        val id = nextRequestId++
+        scope.launch {
+            val res =
                 httpGateway()?.postFrame(
-                    messageSendFrame(id, chatId, text, threadId, emptyList(), autoThread),
+                    messageSendFrame(id, chatId, text, threadId, mediaRefs, autoThread),
                 )
+            // The synchronous reply (e.g. the read receipt, or an error frame
+            // on 4xx) comes back in the POST body, not on the event stream —
+            // deliver it or it is lost (docs/19 §19.7).
+            res?.frame?.let { emitHttpFrame(it) }
+            if (res?.status == 401) {
+                _state.value = State.AuthFailed("gateway rejected the pairing token (HTTP 401)")
             }
+            onResult?.invoke(res?.status ?: 0)
         }
     }
 
-    // ── M4: media upload / pull ───────────────────────────────────────────
+    // ── Media upload / pull ───────────────────────────────────────────────
 
     /**
-     * Upload a local file as media (docs/07 §7.2): media.upload.start,
-     * 256 KiB binary chunks, media.upload.end {sha256}. Returns the server's
-     * media_ref (for message.send media_refs) on success.
+     * Upload a local file as media via `POST /v1/media` (docs/19 §19.15, v2).
+     * Returns the server's media_ref (for message.send media_refs) on success.
      */
     suspend fun uploadMedia(
         path: String,
@@ -572,201 +390,132 @@ class GatewayClient(
         filename: String,
         mediaRef: String,
     ): Result<String> {
-        val ws = socket ?: return Result.failure(IllegalStateException("not connected"))
-        val source = FileSource(path)
-        val size = source.size()
-        if (size <= 0) {
-            source.close()
-            return Result.failure(IllegalStateException("empty file"))
-        }
-        val id = nextRequestId++
-        val reply = CompletableDeferred<Frame>()
-        pending[id] = reply
-        try {
-            ws.send(mediaUploadStartFrame(id, mediaRef, kind, mime, filename, size).toWire())
-            val sha = Sha256()
-            source.use {
-                val buf = ByteArray(UPLOAD_CHUNK_BYTES)
-                while (true) {
-                    val n = it.read(buf)
-                    if (n < 0) break
-                    if (n == 0) continue
-                    sha.update(buf, 0, n)
-                    ws.send(buf.copyOfRange(0, n).toByteString())
-                }
-            }
-            ws.send(mediaUploadEndFrame(id, mediaRef, sha.hex()).toWire())
-            val frame = withTimeout(UPLOAD_TIMEOUT_MS) { reply.await() }
-            return when (frame.type) {
-                TYPE_MEDIA_UPLOAD_ACK -> {
-                    val p = frame.payloadAs<MediaUploadAckPayload>()
-                    if (p != null && p.ok) {
-                        Result.success(p.mediaRef)
-                    } else {
-                        Result.failure(IllegalStateException("upload rejected by server"))
-                    }
-                }
-
-                TYPE_ERROR -> {
-                    val e = frame.payloadAs<ErrorPayload>()
-                    Result.failure(IllegalStateException(e?.message ?: "upload failed"))
-                }
-
-                else -> {
-                    Result.failure(IllegalStateException("unexpected reply ${frame.type}"))
-                }
-            }
-        } catch (e: Exception) {
-            return Result.failure(e)
-        } finally {
-            pending.remove(id)
-        }
+        val http = httpGateway() ?: return Result.failure(IllegalStateException("not connected"))
+        return http.uploadMedia(path, mime, kind, filename, mediaRef)
     }
 
     /**
-     * Pull offered media (docs/07 §7.3): media.pull, then binary frames until
-     * media.pull.end. Each chunk is handed to [onChunk] (write to cache).
+     * Pull offered media via `GET /v1/media/{id}` (docs/19 §19.15, v2). Each
+     * chunk is handed to [onChunk] (write to cache).
      */
     suspend fun pullMedia(
         mediaId: String,
         onChunk: suspend (ByteArray) -> Unit,
     ): Result<Unit> =
         pullMutex.withLock {
-            val ws = socket ?: return@withLock Result.failure(IllegalStateException("not connected"))
-            val id = nextRequestId++
-            val chunks = Channel<ByteArray>(Channel.UNLIMITED)
-            val end = CompletableDeferred<Frame>()
-            pending[id] = end
-            binarySession = BinarySession.Pulling(id, chunks, end)
-            try {
-                ws.send(mediaPullFrame(id, mediaId).toWire())
-                val frame =
-                    withTimeout(PULL_TIMEOUT_MS) {
-                        for (chunk in chunks) onChunk(chunk)
-                        end.await()
-                    }
-                when (frame.type) {
-                    TYPE_MEDIA_PULL_END -> {
-                        val p = frame.payloadAs<MediaPullEndPayload>()
-                        if (p != null && p.ok) {
-                            Result.success(Unit)
-                        } else {
-                            Result.failure(IllegalStateException("pull failed"))
-                        }
-                    }
-
-                    TYPE_ERROR -> {
-                        val e = frame.payloadAs<ErrorPayload>()
-                        Result.failure(IllegalStateException(e?.message ?: "pull failed"))
-                    }
-
-                    else -> {
-                        Result.failure(IllegalStateException("unexpected reply ${frame.type}"))
-                    }
-                }
-            } catch (e: Exception) {
-                Result.failure(e)
-            } finally {
-                pending.remove(id)
-                chunks.cancel()
-                val s = binarySession
-                if (s is BinarySession.Pulling && s.requestId == id) binarySession = null
-            }
+            val http = httpGateway() ?: return@withLock Result.failure(IllegalStateException("not connected"))
+            http.pullMedia(mediaId) { chunk -> onChunk(chunk) }
         }
 
     companion object {
-        /** One WS binary frame carries at most this many media bytes (docs/07 §7.5). */
-        const val UPLOAD_CHUNK_BYTES = 256 * 1024
         const val UPLOAD_TIMEOUT_MS = 120_000L
         const val PULL_TIMEOUT_MS = 300_000L
     }
 
     /**
-     * Send an arbitrary frame with a fresh request id (fire-and-forget).
-     * The server replies (or broadcasts) a frame carrying the same id; the
-     * app reconciles from [events]. Returns the id used, or -1 if not connected.
+     * Send an arbitrary frame with a fresh request id (fire-and-forget). The
+     * server replies (or broadcasts) a frame carrying the same id; the app
+     * reconciles from [events]. Returns the id used, or -1 if not connected.
      */
     fun sendFrame(frame: Frame): Int {
+        if (_state.value !is State.Connected) return -1
         val id = nextRequestId++
-        val ws = socket
-        if (ws != null && _state.value is State.Connected) {
-            ws.send(frame.copy(id = id).toWire())
-            return id
-        }
-        // docs/19: WS down — route over the HTTP leg; the response (same id)
-        // arrives on the SSE/long-poll stream via [events].
-        if (_state.value is State.HttpFallback) {
-            scope.launch {
-                httpGateway()?.postFrame(frame.copy(id = id))
+        scope.launch {
+            val res = httpGateway()?.postFrame(frame.copy(id = id))
+            // Single-frame responses (commands.catalog, channel.list, search,
+            // history, sync, errors) come back in the POST body, not on the
+            // event stream — deliver it or it is lost (docs/19 §19.7).
+            res?.frame?.let { emitHttpFrame(it) }
+            if (res?.status == 401) {
+                _state.value = State.AuthFailed("gateway rejected the pairing token (HTTP 401)")
             }
-            return id
-        }
-        return -1
-    }
-
-    /** Send a ping (heartbeat). */
-    fun ping() {
-        socket?.send(pingFrame().toWire())
-    }
-
-    /** True when the socket has been silent for [timeoutMs] (heartbeat reap). */
-    fun isStale(timeoutMs: Long = 60_000): Boolean =
-        _state.value is State.Connected && lastLiveness.elapsedNow().inWholeMilliseconds > timeoutMs
-
-    fun reapStale() {
-        if (isStale()) {
-            socket?.close(1000, "heartbeat timeout")
         }
+        return id
     }
 
     // ── One-shot hello test (Connect screen) ──────────────────────────────
 
     /**
-     * Real `hello` test: dial, wait for hello.ack (or auth error), close.
-     * Exercises the auth leg, not just TCP (docs/10 §10.8).
+     * Real connection test: health probe + SSE open. The auth leg is proven
+     * by the stream being accepted (200 vs 401) — we do NOT wait for the
+     * hello event, because the server replays the outbox (up to 72 h of
+     * frames) before it and a large outbox would time out a healthy gateway
+     * (docs/10 §10.8).
      */
     suspend fun testHello(
         url: String,
         token: String,
     ): Result<Unit> {
-        val dial = dial(url, token)
-        return when (val result = dial.result) {
-            DialResult.Connected -> {
-                dial.socket.close(1000, "test complete")
-                Result.success(Unit)
-            }
-
-            is DialResult.AuthFailed -> {
-                Result.failure(IllegalStateException(result.message))
-            }
-
-            is DialResult.Failed -> {
-                Result.failure(IllegalStateException(result.message))
-            }
-        }
-    }
-
-    // ── Heartbeat job ─────────────────────────────────────────────────────
-
-    fun startHeartbeat() {
-        scope.launch {
-            while (isActive) {
-                delay(20_000)
-                if (_state.value is State.Connected) {
-                    ping()
-                    reapStale()
+        val gw =
+            HttpGateway(
+                client,
+                HttpGateway.deriveHttpUrl(url),
+                token,
+                store.deviceId,
+                deviceName = store.deviceName,
+                fcmToken = { store.fcmToken.ifBlank { null } },
+                ntfyTopic = { store.ntfyTopic.ifBlank { null } },
+            )
+        return try {
+            if (!gw.health()) {
+                Result.failure(IllegalStateException("gateway unreachable"))
+            } else {
+                // Open the SSE stream briefly: 200 = auth leg proven, 401 =
+                // bad token. Don't wait for the hello (outbox replay first).
+                val opened = CompletableDeferred<Unit>()
+                val job =
+                    scope.launch {
+                        try {
+                            gw.events(
+                                cursor = store.syncCursor,
+                                onOpen = { opened.complete(Unit) },
+                                onHello = { },
+                                onFrame = { },
+                                onCursor = { },
+                            )
+                        } catch (e: Exception) {
+                            opened.completeExceptionally(e)
+                        }
+                    }
+                try {
+                    if (withTimeoutOrNull(10_000) { opened.await() } == null) {
+                        Result.failure(IllegalStateException("timeout opening the event stream"))
+                    } else {
+                        Result.success(Unit)
+                    }
+                } catch (e: HttpGateway.HttpAuthException) {
+                    Result.failure(IllegalStateException("unauthorized — check the pairing token"))
+                } catch (e: CancellationException) {
+                    throw e
+                } catch (e: Exception) {
+                    Result.failure(IllegalStateException("connection failed: ${e.message}"))
+                } finally {
+                    job.cancel()
                 }
             }
+        } catch (e: Exception) {
+            Result.failure(e)
         }
     }
 
     // ── Helpers ───────────────────────────────────────────────────────────
 
+    /** Backoff that wakes early when [poke] is called (app foregrounded). */
+    private suspend fun backoffOrWake(ms: Long) {
+        var remaining = ms
+        while (remaining > 0 && currentCoroutineContext().isActive) {
+            delay(minOf(remaining, 500L))
+            if (wakeRequested) {
+                wakeRequested = false
+                return
+            }
+            remaining -= 500L
+        }
+    }
+
     private fun backoffMs(attempt: Int): Long {
         val base = 1_000L * (1L shl minOf(attempt, 5)) // 1s..32s
         val capped = minOf(base, 30_000L)
         return capped + Random.nextLong(0, 500)
     }
 }
-
-private fun Frame.toWire(): String = IrisJson.instance.encodeToString(Frame.serializer(), this)

app/shared/src/commonMain/kotlin/iris/net/HttpGateway.kt

@@ -1,8 +1,11 @@
 package iris.net
 
+import iris.media.Sha256
+import iris.protocol.ErrorPayload
 import iris.protocol.Frame
 import iris.protocol.HelloAckPayload
 import iris.protocol.IrisJson
+import iris.protocol.MediaUploadAckPayload
 import iris.util.IrisLog
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.withContext
@@ -13,17 +16,18 @@ import okhttp3.Headers
 import okhttp3.MediaType.Companion.toMediaType
 import okhttp3.OkHttpClient
 import okhttp3.Request
+import okhttp3.RequestBody.Companion.asRequestBody
 import okhttp3.RequestBody.Companion.toRequestBody
+import java.io.File
 import java.io.IOException
 import java.util.concurrent.TimeUnit
 
 /**
- * HTTP fallback transport client (docs/19): the "HTTP leg".
+ * HTTP transport client (docs/19) — the only transport.
  *
- * When the WS is down (flaky network, NAT timeout, app just relaunched),
- * the app sends over `POST /v1/frame` and receives over SSE
- * `GET /v1/events` (or long-poll `GET /v1/poll` where SSE is blocked).
- * Same frames, same outbox cursor, same token as the WS.
+ * The app sends over `POST /v1/frame` and receives over SSE
+ * `GET /v1/events` (or long-poll `GET /v1/poll` where SSE is blocked);
+ * media travels via `POST/GET /v1/media`.
  *
  * [events] is ONE SSE connection attempt (blocking read on
  * [Dispatchers.IO]); [GatewayClient] wraps it in a retry loop and tracks
@@ -35,13 +39,27 @@ class HttpGateway(
     private val baseUrl: String,
     private val token: String,
     private val deviceId: String,
+    /** Human-readable device name (sent as `X-Iris-Device-Name`; the gateway
+     *  upserts it into the device registry on every SSE open — the HTTP
+     *  equivalent of the old WS hello upsert). */
+    private val deviceName: String? = null,
+    /** Live push-token providers, read per request so a rotated FCM token or
+     *  a fresh ntfy topic is picked up without rebuilding the client. */
+    private val fcmToken: () -> String? = { null },
+    private val ntfyTopic: () -> String? = { null },
 ) {
+    /** The gateway rejected the pairing token (HTTP 401). Terminal: retrying
+     *  with the same token can't succeed. */
+    class HttpAuthException : IOException("unauthorized (HTTP 401)")
+
     // OkHttp's default read timeout (10 s) is shorter than the gateway's SSE
     // heartbeat (15 s) and the long-poll hold (25 s) — per-purpose clients
     // with extended call timeouts (see the *Client() helpers below).
     private val healthClient: OkHttpClient = client.healthClient()
     private val streamClient: OkHttpClient = client.streamClient()
     private val pollClient: OkHttpClient = client.pollClient()
+    private val mediaClient: OkHttpClient = client.mediaClient()
+
     /** POST /v1/frame result. [frame] is the handler's synchronous reply
      *  (error frame on 4xx, e.g. read.receipt on 200) or null for a plain
      *  202 accept-and-ack. */
@@ -64,6 +82,9 @@ class HttpGateway(
         /** Default port of the gateway's HTTP leg (WS default is 8790). */
         const val DEFAULT_PORT = 8791
 
+        /** Media transfer chunk (docs/07 §7.5). */
+        private const val MEDIA_CHUNK_BYTES = 256 * 1024
+
         /**
          * Derive the HTTP base URL from the stored WS URL (docs/19 §19.4):
          * `ws(s)://host[:port]/ws` -> `http(s)://host:8791`. The WS port is
@@ -84,12 +105,38 @@ class HttpGateway(
         }
     }
 
-    private fun authHeaders(): Headers =
-        Headers
-            .Builder()
-            .add("Authorization", "Bearer $token")
-            .add("X-Iris-Device", deviceId)
-            .build()
+    private fun authHeaders(): Headers {
+        val b =
+            Headers
+                .Builder()
+                .add("Authorization", "Bearer $token")
+                .add("X-Iris-Device", deviceId)
+        // Device registration (docs/19): the gateway upserts name + push
+        // tokens from these headers on every SSE open (COALESCE — absent
+        // headers never clobber a newer fcm.register value).
+        deviceName?.takeIf { it.isNotBlank() }?.let { b.add("X-Iris-Device-Name", it) }
+        fcmToken()?.takeIf { !it.isNullOrBlank() }?.let { b.add("X-Iris-Fcm-Token", it) }
+        ntfyTopic()?.takeIf { it.isNotBlank() }?.let { b.add("X-Iris-Ntfy-Topic", it) }
+        return b.build()
+    }
+
+    /** Parse a response body as a protocol frame (null when not a frame,
+     *  e.g. the plain `{"ok":true}` ack). */
+    private fun parseFrame(body: String): Frame? =
+        try {
+            if (body.startsWith("{")) {
+                val obj = IrisJson.instance.parseToJsonElement(body)
+                if (obj.jsonObject.containsKey("type")) {
+                    IrisJson.instance.decodeFromJsonElement(Frame.serializer(), obj)
+                } else {
+                    null
+                }
+            } else {
+                null
+            }
+        } catch (e: Exception) {
+            null
+        }
 
     /** Liveness probe (unauthenticated by design). True on 200. */
     suspend fun health(): Boolean =
@@ -111,7 +158,11 @@ class HttpGateway(
     /**
      * POST /v1/frame (accept-and-ack, docs/19 §19.7). 2xx -> [PostResult.ok]
      * (with the synchronous reply frame when the handler sent one); 4xx ->
-     * the error frame as the body.
+     * the error frame as the body. Network failures (timeout, reset, DNS —
+     * common when mobile Wi-Fi half-sleeps) do NOT throw: they come back as
+     * [PostResult] with [PostResult.status] 0 ("no HTTP response"). The
+     * callers are fire-and-forget coroutines — an uncaught exception here
+     * kills the app process.
      */
     suspend fun postFrame(frame: Frame): PostResult =
         withContext(Dispatchers.IO) {
@@ -123,40 +174,33 @@ class HttpGateway(
                     .headers(authHeaders())
                     .post(wire.toRequestBody(JSON))
                     .build()
-            client
-                .newCall(request)
-                .execute()
-                .use { response ->
-                    val body = response.body?.string().orEmpty()
-                    val parsed =
-                        try {
-                            if (body.startsWith("{")) {
-                                val obj = IrisJson.instance.parseToJsonElement(body)
-                                // 202 {"ok":true} is not a frame; 4xx/200 bodies are.
-                                if (obj.jsonObject.containsKey("type")) {
-                                    IrisJson.instance.decodeFromJsonElement(Frame.serializer(), obj)
-                                } else {
-                                    null
-                                }
-                            } else {
-                                null
-                            }
-                        } catch (e: Exception) {
-                            null
-                        }
-                    PostResult(response.isSuccessful, response.code, parsed)
-                }
+            try {
+                client
+                    .newCall(request)
+                    .execute()
+                    .use { response ->
+                        val body = response.body?.string().orEmpty()
+                        val parsed = parseFrame(body)
+                        PostResult(response.isSuccessful, response.code, parsed)
+                    }
+            } catch (e: Exception) {
+                IrisLog.w("postFrame ${frame.type} failed: ${e.message}")
+                PostResult(ok = false, status = 0, frame = null)
+            }
         }
 
     /**
      * One SSE connection attempt: outbox catch-up from [cursor], then live
-     * frames. [onHello] fires for `event: hello` (the HTTP hello.ack);
+     * frames. [onOpen] fires as soon as the stream is accepted (200 — the auth
+     * leg is proven; the server may still replay a large outbox before the
+     * hello); [onHello] fires for `event: hello` (the HTTP hello.ack);
      * [onFrame] for `event: frame`; [onCursor] with the SSE `id` (outbox
      * cursor) when present. Returns on clean EOF; throws [IOException] on
      * open/read failure. Callbacks run on the IO thread.
      */
     suspend fun events(
         cursor: Long,
+        onOpen: (() -> Unit)? = null,
         onHello: (HelloAckPayload) -> Unit,
         onFrame: (Frame) -> Unit,
         onCursor: (Long) -> Unit,
@@ -168,13 +212,15 @@ class HttpGateway(
                     .url("$baseUrl/v1/events?cursor=$cursor")
                     .headers(authHeaders())
                     .build()
-            client
+            streamClient
                 .newCall(request)
                 .execute()
                 .use { response ->
+                    if (response.code == 401) throw HttpAuthException()
                     if (!response.isSuccessful) {
                         throw IOException("SSE open failed: HTTP ${response.code}")
                     }
+                    onOpen?.invoke()
                     val source = response.body?.source() ?: throw IOException("empty SSE body")
                     var eventId: String? = null
                     val dataLines = mutableListOf<String>()
@@ -248,10 +294,11 @@ class HttpGateway(
                     .url("$baseUrl/v1/poll?cursor=$cursor")
                     .headers(authHeaders())
                     .build()
-            client
+            pollClient
                 .newCall(request)
                 .execute()
                 .use { response ->
+                    if (response.code == 401) throw HttpAuthException()
                     if (!response.isSuccessful) {
                         throw IOException("poll failed: HTTP ${response.code}")
                     }
@@ -271,29 +318,160 @@ class HttpGateway(
                     PollResult(newCursor, frames)
                 }
         }
+
+    /**
+     * Upload a local file as media (docs/19 §19.15, v2): one `POST /v1/media`
+     * with the whole file as the body and the metadata in `X-Iris-Media-*`
+     * headers (sha256 precomputed in a first pass). Returns the server's
+     * media_ref (for message.send media_refs) on success.
+     */
+    suspend fun uploadMedia(
+        path: String,
+        mime: String,
+        kind: String,
+        filename: String,
+        mediaRef: String,
+    ): Result<String> =
+        withContext(Dispatchers.IO) {
+            val file = File(path)
+            if (!file.isFile() || file.length() <= 0) {
+                return@withContext Result.failure(IllegalStateException("empty file"))
+            }
+            val sha = Sha256()
+            file.inputStream().use { ins ->
+                val buf = ByteArray(MEDIA_CHUNK_BYTES)
+                while (true) {
+                    val n = ins.read(buf)
+                    if (n < 0) break
+                    if (n > 0) sha.update(buf, 0, n)
+                }
+            }
+            val request =
+                Request
+                    .Builder()
+                    .url("$baseUrl/v1/media")
+                    .headers(
+                        authHeaders()
+                            .newBuilder()
+                            .add("X-Iris-Media-Ref", mediaRef)
+                            .add("X-Iris-Media-Kind", kind)
+                            .add("X-Iris-Media-Filename", filename)
+                            .add("X-Iris-Media-Sha256", sha.hex())
+                            .build(),
+                    ).post(file.asRequestBody(mime.toMediaType()))
+                    .build()
+            try {
+                mediaClient
+                    .newCall(request)
+                    .execute()
+                    .use { response ->
+                        val body = response.body?.string().orEmpty()
+                        val frame = parseFrame(body)
+                        if (response.isSuccessful) {
+                            val p = frame?.payloadAs<MediaUploadAckPayload>()
+                            if (p != null && p.ok) {
+                                Result.success(p.mediaRef)
+                            } else {
+                                Result.failure(IllegalStateException("upload rejected by server"))
+                            }
+                        } else {
+                            val e = frame?.payloadAs<ErrorPayload>()
+                            Result.failure(
+                                IllegalStateException(e?.message ?: "upload failed: HTTP ${response.code}"),
+                            )
+                        }
+                    }
+            } catch (e: Exception) {
+                // Network failure mid-upload: report, don't throw (the caller
+                // is a fire-and-forget coroutine — an uncaught exception kills
+                // the app process).
+                IrisLog.w("media upload failed: ${e.message}")
+                Result.failure(e)
+            }
+        }
+
+    /**
+     * Pull offered media (docs/19 §19.15, v2): `GET /v1/media/{id}`; the
+     * response body is the file, streamed to [onChunk] (write to cache).
+     */
+    suspend fun pullMedia(
+        mediaId: String,
+        onChunk: suspend (ByteArray) -> Unit,
+    ): Result<Unit> =
+        withContext(Dispatchers.IO) {
+            val request =
+                Request
+                    .Builder()
+                    .url("$baseUrl/v1/media/$mediaId")
+                    .headers(authHeaders())
+                    .build()
+            try {
+                mediaClient
+                    .newCall(request)
+                    .execute()
+                    .use { response ->
+                        if (!response.isSuccessful) {
+                            val e = parseFrame(response.body?.string().orEmpty())?.payloadAs<ErrorPayload>()
+                            Result.failure(
+                                IllegalStateException(e?.message ?: "pull failed: HTTP ${response.code}"),
+                            )
+                        } else {
+                            try {
+                                val source = response.body?.source() ?: throw IOException("empty body")
+                                val buf = ByteArray(MEDIA_CHUNK_BYTES)
+                                while (true) {
+                                    val n = source.read(buf)
+                                    if (n < 0) break
+                                    if (n == 0) continue
+                                    onChunk(buf.copyOfRange(0, n))
+                                }
+                                Result.success(Unit)
+                            } catch (e: Exception) {
+                                Result.failure(e)
+                            }
+                        }
+                    }
+            } catch (e: Exception) {
+                // Network failure before/while opening the pull: report, don't
+                // throw (fire-and-forget caller — uncaught = process death).
+                IrisLog.w("media pull failed: ${e.message}")
+                Result.failure(e)
+            }
+        }
 }
 
 /**
- * OkHttp's default read timeout (10 s) is shorter than the gateway's SSE
- * heartbeat (15 s) and the long-poll hold (25 s) — extend the call timeout
- * for streaming endpoints. Applied via [OkHttpClient] builders in
- * [GatewayClient].
+ * Per-purpose OkHttp clients. The base client's DEFAULT read timeout (10 s)
+ * is shorter than the gateway's SSE heartbeat (15 s) and the long-poll hold
+ * (25 s) — it would kill both receive paths while they are simply waiting
+ * for the next byte, so the streaming clients override it. The read timeout
+ * doubles as the dead-stream detector (a healthy SSE stream gets a heartbeat
+ * comment every 15 s; a healthy poll answers within 25 s).
  */
-internal const val HTTP_STREAM_CALL_TIMEOUT_MS = 60_000L
-internal const val HTTP_POLL_CALL_TIMEOUT_MS = 35_000L
-internal const val HTTP_HEALTH_TIMEOUT_MS = 2_000L
 
+/** SSE: long-lived stream → no call cap; read timeout = 3× the 15 s
+ *  heartbeat (detects a dead connection within 45 s). */
 internal fun OkHttpClient.streamClient(): OkHttpClient =
     newBuilder()
-        .callTimeout(HTTP_STREAM_CALL_TIMEOUT_MS, TimeUnit.MILLISECONDS)
+        .callTimeout(0, TimeUnit.MILLISECONDS)
+        .readTimeout(45_000, TimeUnit.MILLISECONDS)
         .build()
 
+/** Long-poll: the server holds up to 25 s → no call cap; read timeout =
+ *  hold + 15 s margin. */
 internal fun OkHttpClient.pollClient(): OkHttpClient =
     newBuilder()
-        .callTimeout(HTTP_POLL_CALL_TIMEOUT_MS, TimeUnit.MILLISECONDS)
+        .callTimeout(0, TimeUnit.MILLISECONDS)
+        .readTimeout(40_000, TimeUnit.MILLISECONDS)
         .build()
 
 internal fun OkHttpClient.healthClient(): OkHttpClient =
     newBuilder()
-        .callTimeout(HTTP_HEALTH_TIMEOUT_MS, TimeUnit.MILLISECONDS)
+        .callTimeout(2_000, TimeUnit.MILLISECONDS)
+        .build()
+
+/** Media transfers (upload/pull) can take a while on large files. */
+internal fun OkHttpClient.mediaClient(): OkHttpClient =
+    newBuilder()
+        .callTimeout(300_000, TimeUnit.MILLISECONDS)
         .build()

app/shared/src/commonMain/kotlin/iris/protocol/Protocol.kt

@@ -30,13 +30,10 @@ object IrisJson {
 
 // ── Frame type constants ────────────────────────────────────────────────
 
-const val TYPE_HELLO = "hello"
 const val TYPE_HELLO_ACK = "hello.ack"
 const val TYPE_MESSAGE = "message"
 const val TYPE_MESSAGE_SEND = "message.send"
 const val TYPE_ERROR = "error"
-const val TYPE_PING = "ping"
-const val TYPE_PONG = "pong"
 const val TYPE_TYPING = "typing"
 
 // M2 — streaming / tools / commentary
@@ -52,13 +49,9 @@ const val TYPE_TOOL_PROGRESS = "tool.progress"
 const val TYPE_TOOL_END = "tool.end"
 const val TYPE_COMMENTARY = "commentary"
 
-// M4 — media (upload / offer / pull)
-const val TYPE_MEDIA_UPLOAD_START = "media.upload.start"
-const val TYPE_MEDIA_UPLOAD_END = "media.upload.end"
+// M4 — media (offer; upload/pull are HTTP, docs/19 §19.15)
 const val TYPE_MEDIA_UPLOAD_ACK = "media.upload.ack"
 const val TYPE_MEDIA_OFFER = "media.offer"
-const val TYPE_MEDIA_PULL = "media.pull"
-const val TYPE_MEDIA_PULL_END = "media.pull.end"
 
 // M5 — push / notifications / read receipt / gateway status
 const val TYPE_NOTIFICATION = "notification"
@@ -133,18 +126,6 @@ data class Frame(
         }
 }
 
-// ── hello (app -> server) ───────────────────────────────────────────────
-
-@Serializable
-data class HelloPayload(
-    val token: String,
-    @SerialName("device_id") val deviceId: String,
-    @SerialName("device_name") val deviceName: String,
-    val caps: JsonElement = buildJsonObject { put("min_protocol", JsonPrimitive(1)) },
-    @SerialName("fcm_token") val fcmToken: String? = null,
-    @SerialName("ntfy_topic") val ntfyTopic: String? = null,
-)
-
 // ── hello.ack (server -> app) ───────────────────────────────────────────
 
 @Serializable
@@ -241,21 +222,6 @@ data class MediaRef(
     val filename: String,
 )
 
-@Serializable
-data class MediaUploadStartPayload(
-    @SerialName("media_ref") val mediaRef: String,
-    val kind: String,
-    val mime: String,
-    val filename: String,
-    val size: Long,
-)
-
-@Serializable
-data class MediaUploadEndPayload(
-    @SerialName("media_ref") val mediaRef: String,
-    @SerialName("sha256") val sha256: String,
-)
-
 @Serializable
 data class MediaUploadAckPayload(
     val ok: Boolean,
@@ -272,16 +238,6 @@ data class MediaOfferPayload(
     @SerialName("message_id") val messageId: String? = null,
 )
 
-@Serializable
-data class MediaPullPayload(
-    @SerialName("media_id") val mediaId: String,
-)
-
-@Serializable
-data class MediaPullEndPayload(
-    val ok: Boolean,
-)
-
 // ── M2: streaming frames (server -> app) ────────────────────────────────
 
 @Serializable
@@ -353,7 +309,7 @@ data class MessageSendPayload(
     @SerialName("auto_thread") val autoThread: Boolean = false,
 )
 
-// ── typing / error / ping ───────────────────────────────────────────────
+// ── typing / error ──────────────────────────────────────────────────────
 
 @Serializable
 data class TypingPayload(
@@ -366,11 +322,6 @@ data class ErrorPayload(
     val message: String,
 )
 
-@Serializable
-data class PingPayload(
-    val ts: Long? = null,
-)
-
 // ── M3: channel directory (app -> server requests) ──────────────────────
 
 @Serializable
@@ -548,28 +499,6 @@ data class StatusPayload(
 
 // ── Frame builders ──────────────────────────────────────────────────────
 
-fun helloFrame(
-    token: String,
-    deviceId: String,
-    deviceName: String,
-    fcmToken: String? = null,
-    ntfyTopic: String? = null,
-): Frame =
-    Frame(
-        type = TYPE_HELLO,
-        payload =
-            IrisJson.instance.encodeToJsonElement(
-                HelloPayload.serializer(),
-                HelloPayload(
-                    token = token,
-                    deviceId = deviceId,
-                    deviceName = deviceName,
-                    fcmToken = fcmToken,
-                    ntfyTopic = ntfyTopic,
-                ),
-            ),
-    )
-
 fun messageSendFrame(
     id: Int,
     chatId: String,
@@ -590,8 +519,6 @@ fun messageSendFrame(
             ),
     )
 
-fun pingFrame(): Frame = Frame(type = TYPE_PING, payload = IrisJson.instance.encodeToJsonElement(PingPayload.serializer(), PingPayload()))
-
 // ── M3 frame builders ───────────────────────────────────────────────────
 
 fun channelCreateFrame(
@@ -765,55 +692,6 @@ fun messageDeleteFrame(
             },
     )
 
-// ── M4 frame builders ────────────────────────────────────────────────────
-
-fun mediaUploadStartFrame(
-    id: Int,
-    mediaRef: String,
-    kind: String,
-    mime: String,
-    filename: String,
-    size: Long,
-): Frame =
-    Frame(
-        id = id,
-        type = TYPE_MEDIA_UPLOAD_START,
-        payload =
-            IrisJson.instance.encodeToJsonElement(
-                MediaUploadStartPayload.serializer(),
-                MediaUploadStartPayload(mediaRef, kind, mime, filename, size),
-            ),
-    )
-
-fun mediaUploadEndFrame(
-    id: Int,
-    mediaRef: String,
-    sha256: String,
-): Frame =
-    Frame(
-        id = id,
-        type = TYPE_MEDIA_UPLOAD_END,
-        payload =
-            IrisJson.instance.encodeToJsonElement(
-                MediaUploadEndPayload.serializer(),
-                MediaUploadEndPayload(mediaRef, sha256),
-            ),
-    )
-
-fun mediaPullFrame(
-    id: Int,
-    mediaId: String,
-): Frame =
-    Frame(
-        id = id,
-        type = TYPE_MEDIA_PULL,
-        payload =
-            IrisJson.instance.encodeToJsonElement(
-                MediaPullPayload.serializer(),
-                MediaPullPayload(mediaId),
-            ),
-    )
-
 // ── M5 frame builders ───────────────────────────────────────────────────
 
 fun fcmRegisterFrame(

app/shared/src/commonMain/kotlin/iris/state/IrisController.kt

@@ -28,6 +28,7 @@ import iris.protocol.MessagePayload
 import iris.protocol.MessageStopPayload
 import iris.protocol.NotificationPayload
 import iris.protocol.ROLE_ASSISTANT
+import iris.protocol.ROLE_USER
 import iris.protocol.ReadReceiptPayload
 import iris.protocol.SearchHit
 import iris.protocol.SearchResultsPayload
@@ -432,7 +433,7 @@ class IrisController(
     ) {
         if (chatId.isNullOrBlank()) return
         pendingDeepLink = chatId to threadId
-        if (client.state.value is GatewayClient.State.HelloInfo) applyDeepLink()
+        if (client.state.value is GatewayClient.State.Connected) applyDeepLink()
     }
 
     private fun applyDeepLink() {
@@ -605,6 +606,10 @@ class IrisController(
                                     // stays unmarked and the next (re)connect
                                     // retries it.
                                     historyLoaded.add(lane)
+                                    // Offline sends that never arrived go out
+                                    // now (delivered duplicates were dropped by
+                                    // loadHistory's dedupe above).
+                                    reconcileFailedSends(lane)
                                 }
                             }
                         }
@@ -683,13 +688,13 @@ class IrisController(
             client.state.collect { s ->
                 val prev = prevState
                 prevState = s
-                if (s is GatewayClient.State.HelloInfo) {
+                if (s is GatewayClient.State.Connected) {
                     // Clear any stale "restarting" latch from the previous
                     // down phase (the gateway's own status{online} frame
                     // follows on hello.ack and re-asserts the truth).
                     _gatewayStatus.value = "online"
                     // The lane/history fast path runs on [client.onHelloAck]
-                    // (promptly, on the WS thread) — see onConnectedLane. Here
+                    // (promptly, on the SSE thread) — see onConnectedLane. Here
                     // we do the non-time-critical connect work.
                     // M5: refresh the push-dedupe watermark (docs/08 §8.7).
                     lastPushedCursor = s.lastPushedCursor
@@ -729,17 +734,21 @@ class IrisController(
         if (store.ntfyTopic.isBlank()) {
             store.ntfyTopic = "iris-${store.deviceId}-${Random.nextLong(1_000_000_000L, 9_999_999_999L)}"
         }
-        client.startHeartbeat()
-        // Prompt fast path: seed the channel directory + load the active lane's
-        // history the moment hello.ack lands (on the WS thread), not after the
-        // state collector (which can be starved for seconds on startup). This
-        // gets the history request out early so its response lands inside a
-        // flaky network's window.
         client.onHelloAck = { connected ->
             try {
                 onConnectedLane(connected)
+                // Auto-resend offline sends AFTER the outbox replay has been
+                // processed: replayed frames precede the hello on the stream,
+                // but the frame collector may still be draining them — a
+                // delivered message whose POST response was lost must
+                // reconcile (echo replaces the failed bubble) before we
+                // decide to resend it.
+                scope.launch {
+                    delay(2_000)
+                    reconcileAllFailedSends()
+                }
             } catch (e: Exception) {
-                // Must not throw on the WS thread (would break the connection).
+                // Must not throw on the SSE thread (would break the connection).
                 IrisLog.e("onConnectedLane failed: $e")
             }
         }
@@ -755,7 +764,7 @@ class IrisController(
      * after a process death the cached copy may be stale — so history always
      * refreshes (skipped on a plain reconnect via historyLoaded).
      */
-    private fun onConnectedLane(connected: GatewayClient.State.HelloInfo) {
+    private fun onConnectedLane(connected: GatewayClient.State.Connected) {
         channels.setAll(connected.channels)
         val home = connected.channels.firstOrNull { it.isDefault }?.chatId
         _homeChannel.value = home ?: ChatStore.DEFAULT_LANE
@@ -883,7 +892,7 @@ class IrisController(
     /** Request the gateway's slash-command catalog. No-op while disconnected
      *  (sendFrame drops silently); the response lands via [slashCommands]. */
     fun requestCommandsCatalog() {
-        if (client.state.value !is GatewayClient.State.HelloInfo) return
+        if (client.state.value !is GatewayClient.State.Connected) return
         client.sendFrame(commandsCatalogFrame(0))
     }
 
@@ -932,11 +941,36 @@ class IrisController(
                     localPath = it.path,
                 )
             }
-        chat.addPending(trimmed, lane, media)
-        client.sendMessage(chatId, trimmed, threadId, refs, autoThread = wantsAutoThread(trimmed, threadId, chatId))
+        val messageId = chat.addPending(trimmed, lane, media)
+        client.sendMessage(
+            chatId,
+            trimmed,
+            threadId,
+            refs,
+            autoThread = wantsAutoThread(trimmed, threadId, chatId),
+            onResult = { status -> onSendResult(messageId, status) },
+        )
         _attachments.value = emptyList()
     }
 
+    /** POST result for an optimistic send: 2xx = accepted (the echo
+     *  reconciles the bubble); 0 = no response (offline / network failure) —
+     *  keep the bubble QUEUED (Pending) and remember it: it goes out on the
+     *  next (re)connect, so the user can compose and send while the network
+     *  is down; 4xx = gateway rejection — fail the bubble (tap to retry),
+     *  no auto-retry (the gateway said no). */
+    private fun onSendResult(
+        messageId: String,
+        status: Int,
+    ) {
+        if (status in 200..299) return
+        if (status == 0) {
+            networkFailed.add(messageId)
+        } else {
+            chat.failMessage(messageId)
+        }
+    }
+
     /** Auto-threading (Settings → "Threads", docs/06 §6.3): a message in the
      *  default channel's flat lane gets its own fresh thread, AI-named by the
      *  gateway (Telegram topic-mode workflow). Threading is only active on
@@ -966,9 +1000,52 @@ class IrisController(
             threadId,
             item.media.map { it.mediaId },
             autoThread = wantsAutoThread(item.text, threadId, chatId),
+            onResult = { status -> onSendResult(messageId, status) },
         )
     }
 
+    /** User message ids that failed for NETWORK reasons (status 0 — not a
+     *  gateway error frame): queued (Pending) or failed bubbles that go out
+     *  automatically on the next (re)connect. In-memory only — a process
+     *  death leaves them as tap-to-retry (the local cache restore already
+     *  marks pending sends failed). */
+    private val networkFailed = mutableSetOf<String>()
+
+    /** Resend queued/failed user messages of [lane] now that the link is
+     *  back: a message the server already has (the POST response was lost in
+     *  the drop) was reconciled by the echo / loadHistory dedupe, so anything
+     *  still queued or Failed here never arrived — send it. */
+    private fun reconcileFailedSends(lane: String) {
+        val items = chat.lanes.value[lane] ?: return
+        for (item in items) {
+            if (item !is MessageItem || item.role != ROLE_USER || item.id !in networkFailed) {
+                continue
+            }
+            if (item.status != MsgStatus.Pending && item.status != MsgStatus.Failed) {
+                continue
+            }
+            networkFailed.remove(item.id)
+            chat.rearmForRetry(lane, item.id) // no-op for queued (already Pending)
+            val (chatId, threadId) = chat.parseLane(lane)
+            client.sendMessage(
+                chatId,
+                item.text,
+                threadId,
+                item.media.map { it.mediaId },
+                autoThread = wantsAutoThread(item.text, threadId, chatId),
+                onResult = { status -> onSendResult(item.id, status) },
+            )
+        }
+    }
+
+    /** Reconcile every lane (offline sends may sit in any lane). */
+    private fun reconcileAllFailedSends() {
+        if (networkFailed.isEmpty()) return
+        for (lane in chat.lanes.value.keys) {
+            reconcileFailedSends(lane)
+        }
+    }
+
     /** Delete the given message(s) from the current lane (long-press select →
      *  delete). The server removes them from the outbox and broadcasts
      *  `message.deleted`; the local cache drops them on that frame (or

app/shared/src/commonMain/kotlin/iris/ui/screens/ChatScreen.kt

@@ -245,10 +245,8 @@ fun ChatScreen(controller: IrisController) {
     val nonThreadChannels = channels.filter { it.kind != "thread" }
 
     fun doSend() {
-        // No-op while no transport is up (sendMessage drops silently); the
-        // send button is disabled in that state, this guards the IME "Send"
-        // action. docs/19: the HTTP fallback leg counts as sendable.
-        if (state !is GatewayClient.State.HelloInfo) return
+        // Offline sends are allowed: the bubble stays queued (Pending) and is
+        // auto-resent on the next (re)connect (IrisController.onSendResult).
         val ready = attachments.filter { it.mediaRef != null && it.error == null }
         if (input.isBlank() && ready.isEmpty()) return
         val text = input
@@ -312,7 +310,7 @@ fun ChatScreen(controller: IrisController) {
     }
 
     fun onSlashPick(cmd: SlashCommand) {
-        if (state !is GatewayClient.State.HelloInfo) return
+        if (state !is GatewayClient.State.Connected) return
         input = ""
         controller.send(cmd.name)
         focusManager.clearFocus(force = true)
@@ -740,15 +738,15 @@ fun ChatScreen(controller: IrisController) {
                 )
             }
 
-            // Composer (M7: rounded pill + accent circular send button). Sending is gated
-            // on a live socket: sendMessage is a no-op while disconnected, so an
-            // ungated send would show a pending bubble that never resolves.
-            val isConnected = state is GatewayClient.State.HelloInfo
-            // docs/19: media needs the live WS connection; in HTTP fallback
-            // only text is sendable.
-            val wsConnected = state is GatewayClient.State.Connected
-            val canSend =
-                isConnected && (input.isNotBlank() || (wsConnected && attachments.any { it.mediaRef != null && it.error == null }))
+            // Composer (M7: rounded pill + accent circular send button). Sending is
+            // NOT gated on a live connection: an offline send stays queued
+            // (Pending) and is auto-resent on the next (re)connect (see
+            // IrisController.onSendResult / reconcileFailedSends). The
+            // automation lane stays read-only regardless.
+            // docs/19 §19.15 (v2): media works over the HTTP leg too, so
+            // attachments are sendable in both connected states (uploading
+            // still needs a live connection — the picker stays gated).
+            val canSend = input.isNotBlank() || attachments.any { it.mediaRef != null && it.error == null }
             val layoutDensity = LocalDensity.current.density
             var textHeightPx by remember { mutableFloatStateOf(0f) }
             if (isAutomation) {
@@ -1826,7 +1824,6 @@ private fun statusLabel(state: GatewayClient.State): String =
         GatewayClient.State.Connecting -> "connecting…"
         GatewayClient.State.Reconnecting -> "reconnecting…"
         is GatewayClient.State.Connected -> "connected"
-        is GatewayClient.State.HttpFallback -> "connected · http"
         is GatewayClient.State.AuthFailed -> "auth failed"
     }
 
@@ -2109,7 +2106,6 @@ private fun NameDialog(
 private fun statusToastText(state: GatewayClient.State): String =
     when (state) {
         is GatewayClient.State.Connected -> "Connected to Hermes"
-        is GatewayClient.State.HttpFallback -> "Connected to Hermes (HTTP fallback — media paused)"
         GatewayClient.State.Connecting -> "Connecting to Hermes"
         GatewayClient.State.Reconnecting -> "Re-Connecting to Hermes"
         GatewayClient.State.Disconnected -> "Unpaired from Hermes"
@@ -2126,7 +2122,6 @@ private fun StatusBubble(
     val (color, pulsing) =
         when (state) {
             is GatewayClient.State.Connected,
-            is GatewayClient.State.HttpFallback,
             -> IrisColors.statusGreen to false
 
             GatewayClient.State.Connecting,

app/shared/src/commonMain/kotlin/iris/ui/screens/ConnectScreen.kt

@@ -44,18 +44,18 @@ fun ConnectScreen(
 ) {
     val scope = rememberCoroutineScope()
     // Default is a cleartext (non-TLS) URL because the typical gateway is on
-    // the LAN. A TLS gateway is reached by entering a secure (wss) URL instead.
-    // pi-lens-ignore: opengrep:javascript.lang.security.detect-insecure-websocket.detect-insecure-websocket
-    var url by remember { mutableStateOf(prefillUrl.ifBlank { "ws://" }) }
+    // the LAN. A TLS gateway is reached by entering a secure (https) URL instead.
+    var url by remember { mutableStateOf(prefillUrl.ifBlank { "http://" }) }
     var token by remember { mutableStateOf(prefillToken) }
     var busy by remember { mutableStateOf(false) }
     var error by remember { mutableStateOf(initialError) }
 
     Column(
-        modifier = Modifier
-            .fillMaxSize()
-            .verticalScroll(rememberScrollState())
-            .padding(24.dp),
+        modifier =
+            Modifier
+                .fillMaxSize()
+                .verticalScroll(rememberScrollState())
+                .padding(24.dp),
         horizontalAlignment = Alignment.CenterHorizontally,
     ) {
         Spacer(modifier = Modifier.height(48.dp))
@@ -69,19 +69,19 @@ fun ConnectScreen(
         Spacer(modifier = Modifier.height(32.dp))
 
         Column(
-            modifier = Modifier
-                .fillMaxWidth()
-                .clip(RoundedCornerShape(16.dp))
-                .background(IrisColors.surface)
-                .padding(16.dp),
+            modifier =
+                Modifier
+                    .fillMaxWidth()
+                    .clip(RoundedCornerShape(16.dp))
+                    .background(IrisColors.surface)
+                    .padding(16.dp),
         ) {
             OutlinedTextField(
                 value = url,
                 onValueChange = { url = it },
                 label = { Text("Server URL") },
-                // Example LAN URL; wss:// works too for TLS gateways.
-                // pi-lens-ignore: opengrep:javascript.lang.security.detect-insecure-websocket.detect-insecure-websocket
-                placeholder = { Text("ws://192.168.1.10:8790/ws") },
+                // Example LAN URL; https:// works too for TLS gateways.
+                placeholder = { Text("http://192.168.1.10:8791") },
                 singleLine = true,
                 keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Uri),
                 modifier = Modifier.fillMaxWidth(),
@@ -136,4 +136,3 @@ fun ConnectScreen(
         )
     }
 }
-