From 79ce02319aef3bd33f004c0156aa6e4970a3350e Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Wed, 10 Jun 2026 11:18:37 -0700
Subject: [PATCH] Fix streaming errors through gateway reranker path

---
 frontend/src/lib/components/LearnView.svelte  |  69 ++++++-
 frontend/src/lib/components/LearnView.test.ts |  14 +-
 frontend/src/lib/services/guided.test.ts      |  39 +++-
 frontend/src/lib/services/guided.ts           |  29 +++
 frontend/src/lib/services/sse.ts              |  33 ++++
 .../service/GuidedLearningService.java        |  72 ++++----
 .../service/OpenAIStreamingService.java       |   7 +-
 .../service/OpenAiProviderRoutingService.java |   8 +-
 .../javachat/web/ChatController.java          | 171 +++++++++---------
 .../web/GuidedLearningController.java         | 124 ++++++++-----
 .../service/OpenAIStreamingServiceTest.java   |  44 +++++
 .../web/GuidedSseCitationEventTest.java       |  27 +++
 12 files changed, 451 insertions(+), 186 deletions(-)

diff --git a/frontend/src/lib/components/LearnView.svelte b/frontend/src/lib/components/LearnView.svelte
index dc24eac6..4ba4694a 100644
--- a/frontend/src/lib/components/LearnView.svelte
+++ b/frontend/src/lib/components/LearnView.svelte
@@ -1,8 +1,8 @@
 <script lang="ts">
     import {
         fetchTOC,
-        fetchLessonContent,
         fetchGuidedLessonCitations,
+        streamLessonContent,
         streamGuidedChat,
         type GuidedLesson,
     } from "../services/guided";
@@ -105,6 +105,8 @@
 
     let guidedChatAbortController: AbortController | null = null;
     let guidedChatStreamVersion = 0;
+    let lessonContentAbortController: AbortController | null = null;
+    let lessonContentStreamVersion = 0;
 
     /**
      * Gets or creates a session ID for a specific lesson.
@@ -129,6 +131,14 @@
         activeStreamingMessageId = null;
     }
 
+    function cancelInFlightLessonContentStream(): void {
+        lessonContentStreamVersion++;
+        if (lessonContentAbortController) {
+            lessonContentAbortController.abort();
+            lessonContentAbortController = null;
+        }
+    }
+
     // Rendered lesson content - SSR-safe parsing without DOM operations
     let renderedLesson = $derived(
         lessonMarkdown ? parseMarkdown(lessonMarkdown) : "",
@@ -158,6 +168,10 @@
 
     async function selectLesson(lesson: GuidedLesson): Promise<void> {
         const targetSlug = lesson.slug;
+        cancelInFlightLessonContentStream();
+        const activeLessonContentStreamVersion = lessonContentStreamVersion;
+        lessonContentAbortController = new AbortController();
+        const lessonContentAbortSignal = lessonContentAbortController.signal;
 
         // Save current chat history before switching lessons
         if (selectedLesson && messages.length > 0) {
@@ -178,10 +192,41 @@
         messages = chatHistoryByLesson.get(lesson.slug) ?? [];
 
         try {
-            const response = await fetchLessonContent(lesson.slug);
-            // Guard against stale response if user switched lessons
+            let hasReceivedLessonChunk = false;
+            await streamLessonContent(lesson.slug, {
+                signal: lessonContentAbortSignal,
+                onChunk: (lessonChunk) => {
+                    if (selectedLesson?.slug !== targetSlug) return;
+                    if (
+                        lessonContentStreamVersion !==
+                        activeLessonContentStreamVersion
+                    )
+                        return;
+                    if (lessonContentAbortSignal.aborted) return;
+                    lessonMarkdown += lessonChunk;
+                    if (!hasReceivedLessonChunk) {
+                        hasReceivedLessonChunk = true;
+                        loadingLesson = false;
+                    }
+                },
+                onError: (streamError) => {
+                    if (selectedLesson?.slug !== targetSlug) return;
+                    if (
+                        lessonContentStreamVersion !==
+                        activeLessonContentStreamVersion
+                    )
+                        return;
+                    if (lessonContentAbortSignal.aborted) return;
+                    lessonError = streamError.message;
+                },
+            });
+
             if (selectedLesson?.slug !== targetSlug) return;
-            lessonMarkdown = response.markdown;
+            if (
+                lessonContentStreamVersion !== activeLessonContentStreamVersion
+            )
+                return;
+            if (lessonContentAbortSignal.aborted) return;
 
             // Fetch citations for the lesson topic (Think Java-only, with explicit error tracking)
             fetchGuidedLessonCitations(lesson.slug)
@@ -219,15 +264,26 @@
                 });
         } catch (error) {
             if (selectedLesson?.slug !== targetSlug) return;
+            if (
+                lessonContentStreamVersion !== activeLessonContentStreamVersion
+            )
+                return;
+            if (lessonContentAbortSignal.aborted) return;
             lessonError =
                 error instanceof Error
                     ? error.message
                     : "Failed to load lesson";
             lessonMarkdown = "";
         } finally {
-            if (selectedLesson?.slug === targetSlug) {
+            if (
+                selectedLesson?.slug === targetSlug &&
+                lessonContentStreamVersion === activeLessonContentStreamVersion
+            ) {
                 loadingLesson = false;
             }
+            if (lessonContentStreamVersion === activeLessonContentStreamVersion) {
+                lessonContentAbortController = null;
+            }
         }
     }
 
@@ -239,6 +295,7 @@
 
         // Cancel any in-flight stream
         cancelInFlightGuidedChatStream();
+        cancelInFlightLessonContentStream();
         isChatDrawerOpen = false;
         selectedLesson = null;
         lessonMarkdown = "";
@@ -514,7 +571,7 @@
                     </div>
                 {:else}
                     <div class="lessons-grid">
-                        {#each lessons as lesson, index}
+                        {#each lessons as lesson, index (lesson.slug)}
                             <button
                                 type="button"
                                 class="lesson-card"
diff --git a/frontend/src/lib/components/LearnView.test.ts b/frontend/src/lib/components/LearnView.test.ts
index 326218c0..5974c2d5 100644
--- a/frontend/src/lib/components/LearnView.test.ts
+++ b/frontend/src/lib/components/LearnView.test.ts
@@ -3,7 +3,7 @@ import { render, fireEvent } from "@testing-library/svelte";
 import { tick } from "svelte";
 
 const fetchTocMock = vi.fn();
-const fetchLessonContentMock = vi.fn();
+const streamLessonContentMock = vi.fn();
 const fetchGuidedLessonCitationsMock = vi.fn();
 const streamGuidedChatMock = vi.fn();
 
@@ -13,7 +13,7 @@ vi.mock("../services/guided", async () => {
   return {
     ...actualGuidedService,
     fetchTOC: fetchTocMock,
-    fetchLessonContent: fetchLessonContentMock,
+    streamLessonContent: streamLessonContentMock,
     fetchGuidedLessonCitations: fetchGuidedLessonCitationsMock,
     streamGuidedChat: streamGuidedChatMock,
   };
@@ -27,7 +27,7 @@ async function renderLearnView() {
 describe("LearnView guided chat streaming stability", () => {
   beforeEach(() => {
     fetchTocMock.mockReset();
-    fetchLessonContentMock.mockReset();
+    streamLessonContentMock.mockReset();
     fetchGuidedLessonCitationsMock.mockReset();
     streamGuidedChatMock.mockReset();
   });
@@ -41,7 +41,9 @@ describe("LearnView guided chat streaming stability", () => {
       { slug: "intro", title: "Test Lesson", summary: "Lesson summary", keywords: [] },
     ]);
 
-    fetchLessonContentMock.mockResolvedValue({ markdown: "# Lesson", cached: false });
+    streamLessonContentMock.mockImplementation(async (_slug, callbacks) => {
+      callbacks.onChunk("# Lesson");
+    });
     fetchGuidedLessonCitationsMock.mockResolvedValue({ success: true, citations: [] });
 
     let completeStream: () => void = () => {
@@ -107,7 +109,9 @@ describe("LearnView guided chat streaming stability", () => {
       { slug: "intro", title: "Test Lesson", summary: "Lesson summary", keywords: [] },
     ]);
 
-    fetchLessonContentMock.mockResolvedValue({ markdown: "# Lesson", cached: false });
+    streamLessonContentMock.mockImplementation(async (_slug, callbacks) => {
+      callbacks.onChunk("# Lesson");
+    });
     fetchGuidedLessonCitationsMock.mockResolvedValue({ success: true, citations: [] });
 
     const fetchMock = vi.fn().mockResolvedValue({
diff --git a/frontend/src/lib/services/guided.test.ts b/frontend/src/lib/services/guided.test.ts
index 8e8369d0..42a4a36a 100644
--- a/frontend/src/lib/services/guided.test.ts
+++ b/frontend/src/lib/services/guided.test.ts
@@ -1,18 +1,19 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
-const { streamSseMock } = vi.hoisted(() => {
-  return { streamSseMock: vi.fn() };
+const { streamSseMock, streamSseGetMock } = vi.hoisted(() => {
+  return { streamSseMock: vi.fn(), streamSseGetMock: vi.fn() };
 });
 
 vi.mock("./sse", () => {
-  return { streamSse: streamSseMock };
+  return { streamSse: streamSseMock, streamSseGet: streamSseGetMock };
 });
 
-import { streamGuidedChat } from "./guided";
+import { streamGuidedChat, streamLessonContent } from "./guided";
 
 describe("streamGuidedChat recovery", () => {
   beforeEach(() => {
     streamSseMock.mockReset();
+    streamSseGetMock.mockReset();
   });
 
   it("retries once for recoverable invalid stream errors before any chunk", async () => {
@@ -111,4 +112,34 @@ describe("streamGuidedChat recovery", () => {
       }),
     );
   });
+
+  it("streams lesson content from the guided content stream endpoint", async () => {
+    streamSseGetMock.mockImplementationOnce(async (_url, callbacks) => {
+      callbacks.onText("# Lesson");
+    });
+
+    const onChunk = vi.fn();
+    const onStatus = vi.fn();
+    const onError = vi.fn();
+
+    await expect(
+      streamLessonContent("intro", {
+        onChunk,
+        onStatus,
+        onError,
+      }),
+    ).resolves.toBeUndefined();
+
+    expect(streamSseGetMock).toHaveBeenCalledWith(
+      "/api/guided/content/stream?slug=intro",
+      expect.objectContaining({
+        onText: expect.any(Function),
+        onStatus,
+        onError,
+      }),
+      "guided.lesson-content.ts",
+      { signal: undefined },
+    );
+    expect(onChunk).toHaveBeenCalledWith("# Lesson");
+  });
 });
diff --git a/frontend/src/lib/services/guided.ts b/frontend/src/lib/services/guided.ts
index f4a58b03..f9be3b86 100644
--- a/frontend/src/lib/services/guided.ts
+++ b/frontend/src/lib/services/guided.ts
@@ -17,6 +17,7 @@ import {
 } from "../validation/schemas";
 import { validateFetchJson } from "../validation/validate";
 import { fetchCitationsByEndpoint, type CitationFetchResult } from "./chat";
+import { streamSseGet } from "./sse";
 import { streamWithRetry } from "./streamRecovery";
 
 export type { StreamStatus, GuidedLesson, LessonContentResponse };
@@ -30,6 +31,14 @@ export interface GuidedStreamCallbacks {
   signal?: AbortSignal;
 }
 
+/** Callbacks for streaming guided lesson markdown. */
+export interface GuidedLessonContentCallbacks {
+  onChunk: (chunk: string) => void;
+  onStatus?: (status: StreamStatus) => void;
+  onError?: (error: StreamError) => void;
+  signal?: AbortSignal;
+}
+
 /**
  * Fetch the table of contents for guided learning.
  * Validates response structure via Zod schema.
@@ -104,6 +113,26 @@ export async function fetchGuidedLessonCitations(slug: string): Promise<Citation
   );
 }
 
+/**
+ * Stream lesson markdown for a guided lesson slug.
+ * Uses the same SSE parser as chat so server-side dependency failures arrive as structured stream errors.
+ */
+export async function streamLessonContent(
+  slug: string,
+  callbacks: GuidedLessonContentCallbacks,
+): Promise<void> {
+  return streamSseGet(
+    `/api/guided/content/stream?slug=${encodeURIComponent(slug)}`,
+    {
+      onText: callbacks.onChunk,
+      onStatus: callbacks.onStatus,
+      onError: callbacks.onError,
+    },
+    "guided.lesson-content.ts",
+    { signal: callbacks.signal },
+  );
+}
+
 /**
  * Stream a chat response within the guided lesson context.
  * Uses the same JSON-wrapped SSE format as the main chat for consistent whitespace handling.
diff --git a/frontend/src/lib/services/sse.ts b/frontend/src/lib/services/sse.ts
index a0ff5158..4ab61f15 100644
--- a/frontend/src/lib/services/sse.ts
+++ b/frontend/src/lib/services/sse.ts
@@ -174,6 +174,39 @@ export async function streamSse(
     throw fetchError;
   }
 
+  await consumeSseResponse(response, callbacks, source, abortSignal);
+}
+
+/**
+ * Streams SSE responses from a GET endpoint with the same parser used for POST streams.
+ */
+export async function streamSseGet(
+  url: string,
+  callbacks: SseCallbacks,
+  source: string,
+  options: StreamSseRequestOptions = {},
+): Promise<void> {
+  const abortSignal = options.signal;
+  let response: Response;
+
+  try {
+    response = await fetch(url, { method: "GET", signal: abortSignal });
+  } catch (fetchError) {
+    if (abortSignal?.aborted || isAbortError(fetchError)) {
+      return;
+    }
+    throw fetchError;
+  }
+
+  await consumeSseResponse(response, callbacks, source, abortSignal);
+}
+
+async function consumeSseResponse(
+  response: Response,
+  callbacks: SseCallbacks,
+  source: string,
+  abortSignal?: AbortSignal,
+): Promise<void> {
   if (!response.ok) {
     const apiMessage = await extractApiErrorMessage(response, `streamSse:${source}`);
     const errorMessage =
diff --git a/src/main/java/com/williamcallahan/javachat/service/GuidedLearningService.java b/src/main/java/com/williamcallahan/javachat/service/GuidedLearningService.java
index d2ddd95b..cad006b9 100644
--- a/src/main/java/com/williamcallahan/javachat/service/GuidedLearningService.java
+++ b/src/main/java/com/williamcallahan/javachat/service/GuidedLearningService.java
@@ -234,42 +234,44 @@ public record GuidedChatPromptOutcome(StructuredPrompt structuredPrompt, List<Do
      * Produces markdown with headings, paragraphs, lists, and an example code block.
      */
     public Flux<String> streamLessonContent(String slug) {
-        // Curated lessons override AI generation for slugs where the model produces unreliable formatting.
-        Optional<String> curatedMarkdown = loadCuratedLessonMarkdown(slug);
-        if (curatedMarkdown.isPresent()) {
-            return Flux.just(curatedMarkdown.get());
-        }
-
-        Optional<GuidedLesson> lessonOptional = tocProvider.findBySlug(slug);
-        String title = lessonOptional.map(GuidedLesson::getTitle).orElse(slug);
-        String query = lessonOptional.map(this::buildLessonQuery).orElse(slug);
-
-        // Retrieve Think Java-only context
-        List<Document> retrievedDocuments = retrievalService.retrieve(query);
-        List<Document> bookDocuments = filterToBook(retrievedDocuments);
+        return Flux.defer(() -> {
+            // Curated lessons override AI generation for slugs where the model produces unreliable formatting.
+            Optional<String> curatedMarkdown = loadCuratedLessonMarkdown(slug);
+            if (curatedMarkdown.isPresent()) {
+                return Flux.just(curatedMarkdown.get());
+            }
 
-        // Guidance: produce a clean, layered markdown lesson body
-        String guidance = String.join(
-                " ",
-                "Create a concise, beautifully formatted Java lesson using markdown only.",
-                "Do NOT include any heading at the top; the UI provides the title.",
-                "Then 1-2 short paragraphs that define and motivate the topic.",
-                "Add a bullet list of 3-5 key points or rules.",
-                "Include one short Java example in a fenced ```java code block with comments.",
-                "Add a small numbered list (1-3 steps) when it helps understanding.",
-                "Do NOT include footnote references like [1] or a citations section; the UI shows sources separately.",
-                "Do NOT include enrichment markers like {{hint:...}}; they are handled separately.",
-                "Do NOT include a conclusion section; keep it compact and practical.",
-                "If context is insufficient, state what is missing briefly.");
-
-        // We pass a synthetic latestUserMessage that instructs the model to write the lesson
-        String latestUserMessage = "Write the lesson for: " + title + "\nFocus on: " + query;
-        List<Message> emptyHistory = List.of();
-        StringBuilder lessonMarkdownBuilder = new StringBuilder();
-        return chatService
-                .streamAnswerWithContext(emptyHistory, latestUserMessage, bookDocuments, guidance)
-                .doOnNext(lessonMarkdownBuilder::append)
-                .doOnComplete(() -> putLessonCache(slug, lessonMarkdownBuilder.toString()));
+            Optional<GuidedLesson> lessonOptional = tocProvider.findBySlug(slug);
+            String title = lessonOptional.map(GuidedLesson::getTitle).orElse(slug);
+            String query = lessonOptional.map(this::buildLessonQuery).orElse(slug);
+
+            // Retrieve Think Java-only context
+            List<Document> retrievedDocuments = retrievalService.retrieve(query);
+            List<Document> bookDocuments = filterToBook(retrievedDocuments);
+
+            // Guidance: produce a clean, layered markdown lesson body
+            String guidance = String.join(
+                    " ",
+                    "Create a concise, beautifully formatted Java lesson using markdown only.",
+                    "Do NOT include any heading at the top; the UI provides the title.",
+                    "Then 1-2 short paragraphs that define and motivate the topic.",
+                    "Add a bullet list of 3-5 key points or rules.",
+                    "Include one short Java example in a fenced ```java code block with comments.",
+                    "Add a small numbered list (1-3 steps) when it helps understanding.",
+                    "Do NOT include footnote references like [1] or a citations section; the UI shows sources separately.",
+                    "Do NOT include enrichment markers like {{hint:...}}; they are handled separately.",
+                    "Do NOT include a conclusion section; keep it compact and practical.",
+                    "If context is insufficient, state what is missing briefly.");
+
+            // We pass a synthetic latestUserMessage that instructs the model to write the lesson
+            String latestUserMessage = "Write the lesson for: " + title + "\nFocus on: " + query;
+            List<Message> emptyHistory = List.of();
+            StringBuilder lessonMarkdownBuilder = new StringBuilder();
+            return chatService
+                    .streamAnswerWithContext(emptyHistory, latestUserMessage, bookDocuments, guidance)
+                    .doOnNext(lessonMarkdownBuilder::append)
+                    .doOnComplete(() -> putLessonCache(slug, lessonMarkdownBuilder.toString()));
+        });
     }
 
     // ===== In-memory cache for lesson markdown =====
diff --git a/src/main/java/com/williamcallahan/javachat/service/OpenAIStreamingService.java b/src/main/java/com/williamcallahan/javachat/service/OpenAIStreamingService.java
index d16b7bec..35f2c409 100644
--- a/src/main/java/com/williamcallahan/javachat/service/OpenAIStreamingService.java
+++ b/src/main/java/com/williamcallahan/javachat/service/OpenAIStreamingService.java
@@ -42,6 +42,7 @@ public class OpenAIStreamingService {
     private static final Logger log = LoggerFactory.getLogger(OpenAIStreamingService.class);
 
     private static final int COMPLETE_REQUEST_TIMEOUT_SECONDS = 30;
+    private static final String LLM_GATEWAY_TIER_LIVE = "production-z";
     private static final String STREAM_STATUS_CODE_PROVIDER_FALLBACK =
             SseConstants.STATUS_CODE_STREAM_PROVIDER_FALLBACK;
     private static final String STREAM_STAGE_STREAM = SseConstants.STATUS_STAGE_STREAM;
@@ -337,13 +338,17 @@ private OpenAIClient createClient(String apiKey, String baseUrl) {
         return OpenAIOkHttpClient.builder()
                 .apiKey(apiKey)
                 .baseUrl(OpenAiSdkUrlNormalizer.normalize(baseUrl))
-                .putHeader("X-Tier", llmGatewayTier)
+                .putHeader("X-Tier", resolvedLlmGatewayTier())
                 // Disable SDK-level retries: Reactor timeout and onErrorResume handle failures.
                 // Retries cause InterruptedException when Reactor cancels a sleeping retry.
                 .maxRetries(0)
                 .build();
     }
 
+    private String resolvedLlmGatewayTier() {
+        return llmGatewayTier == null || llmGatewayTier.isBlank() ? LLM_GATEWAY_TIER_LIVE : llmGatewayTier.trim();
+    }
+
     private void closeClientSafely(OpenAIClient client, String clientName) {
         if (client == null) {
             return;
diff --git a/src/main/java/com/williamcallahan/javachat/service/OpenAiProviderRoutingService.java b/src/main/java/com/williamcallahan/javachat/service/OpenAiProviderRoutingService.java
index 30f354cd..bade83d0 100644
--- a/src/main/java/com/williamcallahan/javachat/service/OpenAiProviderRoutingService.java
+++ b/src/main/java/com/williamcallahan/javachat/service/OpenAiProviderRoutingService.java
@@ -75,8 +75,9 @@ public List<OpenAiProviderCandidate> selectAvailableProviderCandidates(
             OpenAIClient primaryClient, OpenAIClient secondaryClient) {
         List<OpenAiProviderCandidate> orderedCandidates = orderedProviderCandidates(primaryClient, secondaryClient);
         List<OpenAiProviderCandidate> availableCandidates = new ArrayList<>(orderedCandidates.size());
+        boolean hasAlternateProvider = orderedCandidates.size() > 1;
         for (OpenAiProviderCandidate providerCandidate : orderedCandidates) {
-            if (isProviderCandidateAvailable(providerCandidate)) {
+            if (isProviderCandidateAvailable(providerCandidate, hasAlternateProvider)) {
                 availableCandidates.add(providerCandidate);
             }
         }
@@ -236,9 +237,10 @@ private OpenAIClient providerClient(
         };
     }
 
-    private boolean isProviderCandidateAvailable(OpenAiProviderCandidate providerCandidate) {
+    private boolean isProviderCandidateAvailable(
+            OpenAiProviderCandidate providerCandidate, boolean hasAlternateProvider) {
         RateLimitService.ApiProvider provider = providerCandidate.provider();
-        if (provider == configuredPrimaryProvider() && isPrimaryInBackoff()) {
+        if (provider == configuredPrimaryProvider() && isPrimaryInBackoff() && hasAlternateProvider) {
             log.warn("Primary provider unavailable (backoff active, providerId={})", provider.ordinal());
             return false;
         }
diff --git a/src/main/java/com/williamcallahan/javachat/web/ChatController.java b/src/main/java/com/williamcallahan/javachat/web/ChatController.java
index fa29104a..55ffc755 100644
--- a/src/main/java/com/williamcallahan/javachat/web/ChatController.java
+++ b/src/main/java/com/williamcallahan/javachat/web/ChatController.java
@@ -118,88 +118,95 @@ public Flux<ServerSentEvent<String>> stream(@RequestBody ChatStreamRequest reque
 
         chatMemory.addUser(sessionId, userQuery);
 
-        // Build structured prompt for intelligent truncation
-        // Pass model hint to optimize RAG for token-constrained models
-        ChatService.StructuredPromptOutcome promptOutcome = chatService.buildStructuredPromptWithContextOutcome(
-                history, userQuery, ModelConfiguration.DEFAULT_MODEL);
-
-        // Use OpenAI streaming only (legacy fallback removed)
-        if (openAIStreamingService.isAvailable()) {
-            StringBuilder fullResponse = new StringBuilder();
-            AtomicInteger chunkCount = new AtomicInteger(0);
-            PIPELINE_LOG.info("[{}] Using OpenAI Java SDK for streaming (structured prompt)", requestToken);
-
-            // Emit citations inline at stream end - compute before streaming starts
-            // Citation conversion failures are surfaced to UI via status event
-            RetrievalService.CitationOutcome citationOutcome = retrievalService.toCitations(promptOutcome.documents());
-            final List<Citation> finalCitations = citationOutcome.citations();
-            final String finalCitationWarning = citationOutcome.failedConversionCount() > 0
-                    ? "Some citations could not be loaded (" + citationOutcome.failedConversionCount() + " failed)"
-                    : null;
-
-            // Stream with provider transparency - surfaces which LLM is responding
-            return openAIStreamingService
-                    .streamResponse(
-                            promptOutcome.structuredPrompt(),
-                            appProperties.getLlm().getTemperature())
-                    .flatMapMany(streamingResult -> {
-                        // Provider event first - surfaces which LLM is handling this request
-                        ServerSentEvent<String> providerEvent =
-                                sseSupport.providerEvent(streamingResult.providerDisplayName());
-
-                        // Stream with structure-aware truncation - preserves semantic boundaries
-                        Flux<String> dataStream = sseSupport.prepareDataStream(streamingResult.textChunks(), chunk -> {
-                            fullResponse.append(chunk);
-                            chunkCount.incrementAndGet();
-                        });
-
-                        // Heartbeats terminate when data stream completes (success or error)
-                        Flux<ServerSentEvent<String>> heartbeats = sseSupport.heartbeats(dataStream);
-
-                        // Combine retrieval notices with citation warning if present
-                        Flux<ServerSentEvent<String>> statusEvents = Flux.fromIterable(promptOutcome.notices())
-                                .map(notice -> sseSupport.statusEvent(notice.summary(), notice.details()));
-                        statusEvents =
-                                statusEvents.concatWith(sseSupport.citationWarningStatusFlux(finalCitationWarning));
-
-                        Flux<ServerSentEvent<String>> runtimeStreamingStatusEvents =
-                                sseSupport.streamingNoticeEvents(streamingResult.notices());
-
-                        // Wrap chunks in JSON to preserve whitespace
-                        Flux<ServerSentEvent<String>> dataEvents = dataStream.map(sseSupport::textEvent);
-
-                        Flux<ServerSentEvent<String>> citationEvent =
-                                Flux.just(sseSupport.citationEvent(finalCitations));
-
-                        return Flux.concat(
-                                Flux.just(providerEvent),
-                                statusEvents,
-                                Flux.merge(dataEvents, heartbeats, runtimeStreamingStatusEvents),
-                                citationEvent);
-                    })
-                    .doOnComplete(() -> {
-                        chatMemory.addAssistant(sessionId, fullResponse.toString());
-                        PIPELINE_LOG.info("[{}] STREAMING COMPLETE", requestToken);
-                    })
-                    .onErrorResume(error -> {
-                        String errorDetail = buildUserFacingErrorMessage(error);
-                        String diagnostics =
-                                error instanceof Exception exception ? describeException(exception) : error.toString();
-                        PIPELINE_LOG.error(
-                                "[{}] STREAMING ERROR (sessionId={}, exceptionType={})",
-                                requestToken,
-                                sessionId,
-                                error.getClass().getSimpleName(),
-                                error);
-                        boolean retryable = openAIStreamingService.isRecoverableStreamingFailure(error);
-                        return sseSupport.streamErrorEvent(errorDetail, diagnostics, retryable);
-                    });
-
-        } else {
-            // Service unavailable - send structured error event so client can handle appropriately
-            PIPELINE_LOG.warn("[{}] OpenAI streaming service unavailable", requestToken);
-            return sseSupport.sseError("Streaming service unavailable", "OpenAI streaming service is not ready");
-        }
+        return Flux.defer(() -> {
+                    // Build structured prompt for intelligent truncation
+                    // Pass model hint to optimize RAG for token-constrained models
+                    ChatService.StructuredPromptOutcome promptOutcome =
+                            chatService.buildStructuredPromptWithContextOutcome(
+                                    history, userQuery, ModelConfiguration.DEFAULT_MODEL);
+
+                    // Use OpenAI streaming only (legacy fallback removed)
+                    if (openAIStreamingService.isAvailable()) {
+                        StringBuilder fullResponse = new StringBuilder();
+                        AtomicInteger chunkCount = new AtomicInteger(0);
+                        PIPELINE_LOG.info("[{}] Using OpenAI Java SDK for streaming (structured prompt)", requestToken);
+
+                        // Emit citations inline at stream end - compute before streaming starts
+                        // Citation conversion failures are surfaced to UI via status event
+                        RetrievalService.CitationOutcome citationOutcome =
+                                retrievalService.toCitations(promptOutcome.documents());
+                        final List<Citation> finalCitations = citationOutcome.citations();
+                        final String finalCitationWarning = citationOutcome.failedConversionCount() > 0
+                                ? "Some citations could not be loaded (" + citationOutcome.failedConversionCount()
+                                        + " failed)"
+                                : null;
+
+                        // Stream with provider transparency - surfaces which LLM is responding
+                        return openAIStreamingService
+                                .streamResponse(
+                                        promptOutcome.structuredPrompt(),
+                                        appProperties.getLlm().getTemperature())
+                                .flatMapMany(streamingResult -> {
+                                    // Provider event first - surfaces which LLM is handling this request
+                                    ServerSentEvent<String> providerEvent =
+                                            sseSupport.providerEvent(streamingResult.providerDisplayName());
+
+                                    // Stream with structure-aware truncation - preserves semantic boundaries
+                                    Flux<String> dataStream =
+                                            sseSupport.prepareDataStream(streamingResult.textChunks(), chunk -> {
+                                                fullResponse.append(chunk);
+                                                chunkCount.incrementAndGet();
+                                            });
+
+                                    // Heartbeats terminate when data stream completes (success or error)
+                                    Flux<ServerSentEvent<String>> heartbeats = sseSupport.heartbeats(dataStream);
+
+                                    // Combine retrieval notices with citation warning if present
+                                    Flux<ServerSentEvent<String>> statusEvents = Flux.fromIterable(
+                                                    promptOutcome.notices())
+                                            .map(notice -> sseSupport.statusEvent(notice.summary(), notice.details()));
+                                    statusEvents = statusEvents.concatWith(
+                                            sseSupport.citationWarningStatusFlux(finalCitationWarning));
+
+                                    Flux<ServerSentEvent<String>> runtimeStreamingStatusEvents =
+                                            sseSupport.streamingNoticeEvents(streamingResult.notices());
+
+                                    // Wrap chunks in JSON to preserve whitespace
+                                    Flux<ServerSentEvent<String>> dataEvents = dataStream.map(sseSupport::textEvent);
+
+                                    Flux<ServerSentEvent<String>> citationEvent =
+                                            Flux.just(sseSupport.citationEvent(finalCitations));
+
+                                    return Flux.concat(
+                                            Flux.just(providerEvent),
+                                            statusEvents,
+                                            Flux.merge(dataEvents, heartbeats, runtimeStreamingStatusEvents),
+                                            citationEvent);
+                                })
+                                .doOnComplete(() -> {
+                                    chatMemory.addAssistant(sessionId, fullResponse.toString());
+                                    PIPELINE_LOG.info("[{}] STREAMING COMPLETE", requestToken);
+                                });
+                    }
+
+                    // Service unavailable - send structured error event so client can handle appropriately
+                    PIPELINE_LOG.warn("[{}] OpenAI streaming service unavailable", requestToken);
+                    return sseSupport.sseError(
+                            "Streaming service unavailable", "OpenAI streaming service is not ready");
+                })
+                .onErrorResume(error -> {
+                    String errorDetail = buildUserFacingErrorMessage(error);
+                    String diagnostics =
+                            error instanceof Exception exception ? describeException(exception) : error.toString();
+                    PIPELINE_LOG.error(
+                            "[{}] STREAMING ERROR (sessionId={}, exceptionType={})",
+                            requestToken,
+                            sessionId,
+                            error.getClass().getSimpleName(),
+                            error);
+                    boolean retryable = openAIStreamingService.isRecoverableStreamingFailure(error);
+                    return sseSupport.streamErrorEvent(errorDetail, diagnostics, retryable);
+                });
     }
 
     /**
diff --git a/src/main/java/com/williamcallahan/javachat/web/GuidedLearningController.java b/src/main/java/com/williamcallahan/javachat/web/GuidedLearningController.java
index 7ff2d08e..871a85c0 100644
--- a/src/main/java/com/williamcallahan/javachat/web/GuidedLearningController.java
+++ b/src/main/java/com/williamcallahan/javachat/web/GuidedLearningController.java
@@ -125,15 +125,33 @@ public Enrichment enrich(@RequestParam("slug") String slug) {
      * This endpoint is designed for dynamically loading lesson text into the UI.
      *
      * @param slug The unique identifier for the lesson.
-     * @return A {@link Flux} of strings sending the markdown content as SSE data events.
+     * @param response servlet response used to disable proxy buffering.
+     * @return A {@link Flux} of SSE text events carrying lesson markdown chunks.
      */
     @GetMapping(value = "/content/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
-    public Flux<String> streamLesson(@RequestParam("slug") String slug) {
-        // If cached, emit immediately as a single-frame stream with proper SSE formatting
-        return guidedService
-                .getCachedLessonMarkdown(slug)
-                .map(cachedMarkdown -> Flux.just(cachedMarkdown.replace("\r", "")))
-                .orElseGet(() -> guidedService.streamLessonContent(slug));
+    public Flux<ServerSentEvent<String>> streamLesson(@RequestParam("slug") String slug, HttpServletResponse response) {
+        sseSupport.configureStreamingHeaders(response);
+        return Flux.defer(() -> {
+                    // If cached, emit immediately as a single-frame stream with proper SSE formatting
+                    Flux<String> lessonContentStream = guidedService
+                            .getCachedLessonMarkdown(slug)
+                            .map(cachedMarkdown -> Flux.just(cachedMarkdown.replace("\r", "")))
+                            .orElseGet(() -> guidedService.streamLessonContent(slug));
+                    Flux<String> dataStream = sseSupport.prepareDataStream(lessonContentStream, ignoredChunk -> {});
+                    return Flux.merge(dataStream.map(sseSupport::textEvent), sseSupport.heartbeats(dataStream));
+                })
+                .onErrorResume(error -> {
+                    log.error(
+                            "Guided lesson content stream error (lessonSlug={}, exceptionType={})",
+                            slug,
+                            error.getClass().getSimpleName(),
+                            error);
+                    boolean retryable = openAIStreamingService.isRecoverableStreamingFailure(error);
+                    return sseSupport.streamErrorEvent(
+                            "Lesson content stream failed",
+                            "The lesson content stream encountered an error. Please try again.",
+                            retryable);
+                });
     }
 
     /**
@@ -221,57 +239,63 @@ public Flux<ServerSentEvent<String>> stream(
     private Flux<ServerSentEvent<String>> streamGuidedResponse(String sessionId, String userQuery, String lessonSlug) {
         List<org.springframework.ai.chat.messages.Message> history = new ArrayList<>(chatMemory.getHistory(sessionId));
         chatMemory.addUser(sessionId, userQuery);
-        StringBuilder fullResponse = new StringBuilder();
+        return Flux.defer(() -> {
+                    StringBuilder fullResponse = new StringBuilder();
 
-        GuidedLearningService.GuidedChatPromptOutcome promptOutcome =
-                guidedService.buildStructuredGuidedPromptWithContext(history, lessonSlug, userQuery);
+                    GuidedLearningService.GuidedChatPromptOutcome promptOutcome =
+                            guidedService.buildStructuredGuidedPromptWithContext(history, lessonSlug, userQuery);
 
-        // Compute citations before streaming starts - page-anchor failures surfaced to UI via status event
-        List<Citation> computedCitations;
-        String citationWarning;
-        try {
-            computedCitations = guidedService.citationsForBookDocuments(promptOutcome.bookContextDocuments());
-            citationWarning = null;
-        } catch (RuntimeException citationEnhancementFailure) {
-            log.warn(
-                    "PDF page-anchor enhancement failed; returning base citations (exceptionType={})",
-                    citationEnhancementFailure.getClass().getSimpleName());
-            computedCitations = retrievalService
-                    .toCitations(promptOutcome.bookContextDocuments())
-                    .citations();
-            citationWarning = "PDF page-anchor enhancement failed; using base citations without page anchors";
-        }
-        final List<Citation> finalCitations = computedCitations;
-        final String finalCitationWarning = citationWarning;
+                    // Compute citations before streaming starts - page-anchor failures surfaced to UI via status event
+                    List<Citation> computedCitations;
+                    String citationWarning;
+                    try {
+                        computedCitations =
+                                guidedService.citationsForBookDocuments(promptOutcome.bookContextDocuments());
+                        citationWarning = null;
+                    } catch (RuntimeException citationEnhancementFailure) {
+                        log.warn(
+                                "PDF page-anchor enhancement failed; returning base citations (exceptionType={})",
+                                citationEnhancementFailure.getClass().getSimpleName());
+                        computedCitations = retrievalService
+                                .toCitations(promptOutcome.bookContextDocuments())
+                                .citations();
+                        citationWarning =
+                                "PDF page-anchor enhancement failed; using base citations without page anchors";
+                    }
+                    final List<Citation> finalCitations = computedCitations;
+                    final String finalCitationWarning = citationWarning;
 
-        // Stream with provider transparency - surfaces which LLM is responding
-        return openAIStreamingService
-                .streamResponse(
-                        promptOutcome.structuredPrompt(), appProperties.getLlm().getTemperature())
-                .flatMapMany(streamingResult -> {
-                    // Provider event first - surfaces which LLM is handling this request
-                    ServerSentEvent<String> providerEvent =
-                            sseSupport.providerEvent(streamingResult.providerDisplayName());
+                    // Stream with provider transparency - surfaces which LLM is responding
+                    return openAIStreamingService
+                            .streamResponse(
+                                    promptOutcome.structuredPrompt(),
+                                    appProperties.getLlm().getTemperature())
+                            .flatMapMany(streamingResult -> {
+                                // Provider event first - surfaces which LLM is handling this request
+                                ServerSentEvent<String> providerEvent =
+                                        sseSupport.providerEvent(streamingResult.providerDisplayName());
 
-                    Flux<String> dataStream =
-                            sseSupport.prepareDataStream(streamingResult.textChunks(), fullResponse::append);
+                                Flux<String> dataStream = sseSupport.prepareDataStream(
+                                        streamingResult.textChunks(), fullResponse::append);
 
-                    Flux<ServerSentEvent<String>> heartbeats = sseSupport.heartbeats(dataStream);
-                    Flux<ServerSentEvent<String>> dataEvents = dataStream.map(sseSupport::textEvent);
-                    Flux<ServerSentEvent<String>> citationEvent = Flux.just(sseSupport.citationEvent(finalCitations));
+                                Flux<ServerSentEvent<String>> heartbeats = sseSupport.heartbeats(dataStream);
+                                Flux<ServerSentEvent<String>> dataEvents = dataStream.map(sseSupport::textEvent);
+                                Flux<ServerSentEvent<String>> citationEvent =
+                                        Flux.just(sseSupport.citationEvent(finalCitations));
 
-                    Flux<ServerSentEvent<String>> statusEvents =
-                            sseSupport.citationWarningStatusFlux(finalCitationWarning);
-                    Flux<ServerSentEvent<String>> runtimeStreamingStatusEvents =
-                            sseSupport.streamingNoticeEvents(streamingResult.notices());
+                                Flux<ServerSentEvent<String>> statusEvents =
+                                        sseSupport.citationWarningStatusFlux(finalCitationWarning);
+                                Flux<ServerSentEvent<String>> runtimeStreamingStatusEvents =
+                                        sseSupport.streamingNoticeEvents(streamingResult.notices());
 
-                    return Flux.concat(
-                            Flux.just(providerEvent),
-                            statusEvents,
-                            Flux.merge(dataEvents, heartbeats, runtimeStreamingStatusEvents),
-                            citationEvent);
+                                return Flux.concat(
+                                        Flux.just(providerEvent),
+                                        statusEvents,
+                                        Flux.merge(dataEvents, heartbeats, runtimeStreamingStatusEvents),
+                                        citationEvent);
+                            })
+                            .doOnComplete(() -> chatMemory.addAssistant(sessionId, fullResponse.toString()));
                 })
-                .doOnComplete(() -> chatMemory.addAssistant(sessionId, fullResponse.toString()))
                 .onErrorResume(error -> {
                     log.error(
                             "Guided streaming error (sessionId={}, lessonSlug={}, exceptionType={})",
diff --git a/src/test/java/com/williamcallahan/javachat/service/OpenAIStreamingServiceTest.java b/src/test/java/com/williamcallahan/javachat/service/OpenAIStreamingServiceTest.java
index 596c981b..e523a562 100644
--- a/src/test/java/com/williamcallahan/javachat/service/OpenAIStreamingServiceTest.java
+++ b/src/test/java/com/williamcallahan/javachat/service/OpenAIStreamingServiceTest.java
@@ -1,15 +1,19 @@
 package com.williamcallahan.javachat.service;
 
+import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
 
+import com.openai.client.OpenAIClient;
 import com.openai.core.http.Headers;
 import com.openai.errors.NotFoundException;
 import com.openai.errors.OpenAIIoException;
 import com.openai.errors.RateLimitException;
 import com.openai.errors.UnauthorizedException;
 import com.williamcallahan.javachat.application.prompt.PromptTruncator;
+import java.util.List;
 import org.junit.jupiter.api.Test;
 import reactor.core.Exceptions;
 
@@ -97,4 +101,44 @@ void recoverableStreamingFailureTreatsNotFoundAsRetryable() {
                 NotFoundException.builder().headers(headers).build();
         assertTrue(streamingService.isRecoverableStreamingFailure(notFoundException));
     }
+
+    @Test
+    void primaryBackoffDoesNotHideOnlyConfiguredProvider() {
+        RateLimitService rateLimitService = mock(RateLimitService.class);
+        when(rateLimitService.isProviderAvailable(RateLimitService.ApiProvider.OPENAI))
+                .thenReturn(true);
+        OpenAiProviderRoutingService routingService = new OpenAiProviderRoutingService(rateLimitService, 600, "openai");
+        OpenAIClient openAiClient = mock(OpenAIClient.class);
+
+        routingService.recordProviderFailure(RateLimitService.ApiProvider.OPENAI, new OpenAIIoException("io"));
+
+        List<OpenAiProviderCandidate> availableProviders =
+                routingService.selectAvailableProviderCandidates(null, openAiClient);
+
+        assertEquals(1, availableProviders.size());
+        assertEquals(
+                RateLimitService.ApiProvider.OPENAI, availableProviders.get(0).provider());
+    }
+
+    @Test
+    void primaryBackoffUsesConfiguredAlternateProviderWhenAvailable() {
+        RateLimitService rateLimitService = mock(RateLimitService.class);
+        when(rateLimitService.isProviderAvailable(RateLimitService.ApiProvider.OPENAI))
+                .thenReturn(true);
+        when(rateLimitService.isProviderAvailable(RateLimitService.ApiProvider.GITHUB_MODELS))
+                .thenReturn(true);
+        OpenAiProviderRoutingService routingService = new OpenAiProviderRoutingService(rateLimitService, 600, "openai");
+        OpenAIClient openAiClient = mock(OpenAIClient.class);
+        OpenAIClient githubModelsClient = mock(OpenAIClient.class);
+
+        routingService.recordProviderFailure(RateLimitService.ApiProvider.OPENAI, new OpenAIIoException("io"));
+
+        List<OpenAiProviderCandidate> availableProviders =
+                routingService.selectAvailableProviderCandidates(githubModelsClient, openAiClient);
+
+        assertEquals(1, availableProviders.size());
+        assertEquals(
+                RateLimitService.ApiProvider.GITHUB_MODELS,
+                availableProviders.get(0).provider());
+    }
 }
diff --git a/src/test/java/com/williamcallahan/javachat/web/GuidedSseCitationEventTest.java b/src/test/java/com/williamcallahan/javachat/web/GuidedSseCitationEventTest.java
index ca62b4a9..4d0257f0 100644
--- a/src/test/java/com/williamcallahan/javachat/web/GuidedSseCitationEventTest.java
+++ b/src/test/java/com/williamcallahan/javachat/web/GuidedSseCitationEventTest.java
@@ -1,6 +1,7 @@
 package com.williamcallahan.javachat.web;
 
 import static com.williamcallahan.javachat.web.SseConstants.EVENT_CITATION;
+import static com.williamcallahan.javachat.web.SseConstants.EVENT_ERROR;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.anyDouble;
@@ -9,6 +10,7 @@
 import static org.mockito.BDDMockito.given;
 import static org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestPostProcessors.csrf;
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.asyncDispatch;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.request;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
@@ -25,6 +27,7 @@
 import com.williamcallahan.javachat.service.RetrievalService;
 import com.williamcallahan.javachat.service.StreamingResult;
 import java.util.List;
+import java.util.Optional;
 import org.junit.jupiter.api.Test;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
@@ -100,4 +103,28 @@ void guidedStreamEmitsCitationEvent() throws Exception {
                 aggregated.contains("https://example.com"),
                 "Citation payload should include the citation URL. Response was:\n" + aggregated);
     }
+
+    @Test
+    void guidedContentStreamEmitsSseErrorWhenLessonGenerationFails() throws Exception {
+        given(guidedLearningService.getCachedLessonMarkdown(anyString())).willReturn(Optional.empty());
+        given(guidedLearningService.streamLessonContent(anyString()))
+                .willReturn(Flux.error(new IllegalStateException("Reranking request failed")));
+
+        var asyncResult = mockMvc.perform(get("/api/guided/content/stream").param("slug", "intro"))
+                .andExpect(request().asyncStarted())
+                .andReturn();
+
+        String aggregated = mockMvc.perform(asyncDispatch(asyncResult))
+                .andExpect(status().isOk())
+                .andReturn()
+                .getResponse()
+                .getContentAsString();
+
+        assertTrue(
+                aggregated.contains("event:" + EVENT_ERROR) || aggregated.contains("event: " + EVENT_ERROR),
+                "SSE stream should include an error event. Response was:\n" + aggregated);
+        assertTrue(
+                aggregated.contains("Lesson content stream failed"),
+                "Error payload should identify lesson content stream failure. Response was:\n" + aggregated);
+    }
 }