fix(ws): WebSocket durable-delivery resilience — reconnect, per-client scoping, ACK re-drive

src/web/public/constants.js

@@ -126,12 +126,39 @@ function shouldAutoWrapTabs(input) {
   return scrollWidth > clientWidth + 1;
 }
 
+// COD-134 — Terminal WebSocket reconnect policy.
+//
+// Decide what to do after a terminal WebSocket closes, given the close `code`
+// and `attempt` (0-based count of consecutive reconnects already made):
+//   - transient closes (code < 4004: 1000/1001/1005/1006/etc.) → 'reconnect'
+//     with exponential backoff (0 on the first attempt; the caller adds jitter),
+//     250ms → 500 → 1000 → ... capped at 10s.
+//   - 4004 (session not found) / 4009 (session terminated) → 'give-up': the
+//     session is gone, retrying only wastes connections.
+//   - 4008 (too many connections) and any other code >= 4004 → 'retry-fallback':
+//     show the HTTP fallback but keep retrying on a bounded 5s timer so the
+//     transport returns to WS once the transient condition clears (un-stick).
+// Pure: no DOM, no side effects.
+function planWsReconnect(code, attempt) {
+  if (code === 4004 || code === 4009) {
+    return { action: 'give-up', delayMs: 0 };
+  }
+  if (code >= 4004) {
+    return { action: 'retry-fallback', delayMs: 5000 };
+  }
+  const delayMs = attempt <= 0 ? 0 : Math.min(250 * Math.pow(2, attempt - 1), 10000);
+  return { action: 'reconnect', delayMs };
+}
+
 if (typeof window !== 'undefined') {
   window.WEBGL_FALLBACK = WEBGL_FALLBACK;
   window.evaluateWebGLLongTaskTrip = evaluateWebGLLongTaskTrip;
   window.CodemanTabOverflow = {
     shouldAutoWrapTabs,
   };
+  window.CodemanWsReconnect = {
+    plan: planWsReconnect,
+  };
 }
 
 // Scheduler API — prioritize terminal writes over background UI updates.

src/web/public/styles.css

@@ -626,6 +626,15 @@ body {
   flex-shrink: 0;
 }
 
+.connection-dot.connected {
+  background: var(--green);
+}
+
+.connection-dot.fallback {
+  background: var(--yellow);
+  box-shadow: 0 0 6px var(--yellow);
+}
+
 .connection-dot.offline {
   background: var(--red);
   box-shadow: 0 0 6px var(--red);

src/web/public/terminal-ui.js

@@ -1925,11 +1925,25 @@ Object.assign(CodemanApp.prototype, {
    * Complete a buffer load: unblock live SSE writes.
    * Called when chunkedTerminalWrite finishes (or is skipped for empty buffers).
    *
-   * Queued SSE events are DISCARDED, not flushed. The loaded buffer from the API
-   * is the source of truth up to the response timestamp. SSE events queued during
-   * the fetch+write overlap with the buffer — flushing them writes duplicate data
-   * (especially Ink cursor-up redraws), corrupting the terminal display.
+   * By default queued SSE events are DISCARDED, not flushed. For an established
+   * session the loaded buffer from the API is the source of truth up to the
+   * response timestamp; SSE events queued during the fetch+write overlap already
+   * appear in that buffer, so flushing them writes duplicate data (especially Ink
+   * cursor-up redraws), corrupting the terminal display.
+   *
+   * COD-144: a brand-new session is the exception. Its terminal fetch can resolve
+   * BEFORE the PTY emits its first prompt, so the fetched buffer is empty and the
+   * prompt arrives only as a queued SSE event. Discarding it leaves the terminal
+   * blank until a tab-switch re-fetches a now-populated buffer. When the caller
+   * knows the load painted nothing (empty fetch + no cache), it passes
+   * `{ flushQueued: true }` so the queued events are REPLAYED through
+   * `batchTerminalWrite()` instead of dropped. Replay runs after `_isLoadingBuffer`
+   * is cleared, so the events write through normally and are not re-queued.
+   *
    * After unblocking, new SSE/WS events deliver subsequent output normally.
+   *
+   * @param {string} [owner] Load token from `_beginBufferLoad`; a stale owner is a no-op.
+   * @param {{ flushQueued?: boolean }} [opts] When `flushQueued` is true, replay any queued events.
    */
   _beginBufferLoad(owner) {
     if (this._bufferLoadSeq === undefined) this._bufferLoadSeq = 0;
@@ -1940,13 +1954,21 @@ Object.assign(CodemanApp.prototype, {
     return loadOwner;
   },
 
-  _finishBufferLoad(owner) {
+  _finishBufferLoad(owner, opts) {
     if (owner !== undefined && this._bufferLoadOwner !== owner) {
       return false;
     }
+    const queued = this._loadBufferQueue;
     this._isLoadingBuffer = false;
     this._loadBufferQueue = null;
     this._bufferLoadOwner = null;
+    // COD-144: replay (rather than discard) queued live events when the load
+    // painted nothing — the queued prompt is the only content a new session has.
+    if (opts?.flushQueued && queued && queued.length) {
+      for (const data of queued) {
+        this.batchTerminalWrite(data);
+      }
+    }
     return true;
   },