[codex] refactor TUI to use native terminal scrollback

.codex/skills/lypi-architecture/SKILL.md

@@ -47,7 +47,8 @@ The root `pom.xml` defines these Maven modules:
 - Transports adapt input/output and display. They should not own durable session or tool state.
 - Session history is append-only JSONL; branch movement changes the leaf, not old entries.
 - Permission runtime changes are represented by session entries and replayed into `SessionContext`; do not mutate historical entries to change permission state.
-- Tool calls, permission decisions, retry, compaction and UI updates flow through contract events where possible.
+- Tool calls, permission decisions, retry, provider fallback, compaction and UI updates flow through contract events where possible.
+- Provider retry and fallback notices are stream control events: agent core maps them to lifecycle events, TUI projects transient state, and neither enters the durable transcript.
 - Permission request/decision events expose approval kind, available decisions and additional permission metadata for TUI/headless rendering.
 - Memory consolidation is driven by `TurnEndEvent` after the main turn completes; `DefaultTurnExecutor` must not synchronously call legacy `MemoryExtractionWorker` on the user-facing path.
 - `TurnEndEvent.leafEntryId` is the stable fork point for background consolidation. Runtime listeners must use this event field instead of the mutable `SessionManagerPort.currentView().leafId()`.

.codex/skills/lypi-transport-tui/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: lypi-transport-tui
+description: Use when changing ly-pi terminal UI, JLine input, TUI event reduction, rendering, slash commands, overlays, permission prompts, diff display, file mentions, or Skill mentions.
+---
+
+# ly-pi Transport TUI
+
+## Core Rule
+
+The TUI adapts input and renders state. Durable behavior belongs in session, agent core, tool runtime, resource runtime or contracts.
+
+## Main Responsibilities
+
+- Open a JLine terminal transport and attach to `AgentEvent`.
+- Convert semantic events into `TuiViewModel`.
+- Route user input, slash commands and compact commands.
+- Parse file and Skill mentions for user input.
+- Render message, thinking, tool, error, permission, diff and status views.
+- Forward submissions to `AgentCorePort` through `TurnRequest`.
+
+## Key Code
+
+- `lypi-transport-tui/src/main/java/cn/lypi/transport/tui/JLineTuiTransport.java`
+- `lypi-transport-tui/src/main/java/cn/lypi/transport/tui/RuntimeTuiSubmitHandler.java`
+- `lypi-transport-tui/src/main/java/cn/lypi/transport/tui/TuiEventReducer.java`
+- `lypi-transport-tui/src/main/java/cn/lypi/transport/tui/TuiTranscriptPartitioner.java`
+- `lypi-transport-tui/src/main/java/cn/lypi/transport/tui/TuiTranscriptCommitLedger.java`
+- `lypi-transport-tui/src/main/java/cn/lypi/transport/tui/TuiRenderBatch.java`
+- `lypi-transport-tui/src/main/java/cn/lypi/transport/tui/TuiLayout.java`
+- `lypi-transport-tui/src/main/java/cn/lypi/transport/tui/TuiRenderer.java`
+- `lypi-transport-tui/src/main/java/cn/lypi/transport/tui/InlineViewport.java`
+- `lypi-transport-tui/src/main/java/cn/lypi/transport/tui/InlineTerminalRenderer.java`
+- `lypi-transport-tui/src/main/java/cn/lypi/transport/tui/TuiStartupBanner.java`
+- `lypi-transport-tui/src/main/java/cn/lypi/transport/tui/TerminalCursorProbe.java`
+- `lypi-transport-tui/src/main/java/cn/lypi/transport/tui/TerminalSession.java`
+- `lypi-transport-tui/src/main/java/cn/lypi/transport/tui/TuiRenderState.java`
+- `lypi-transport-tui/src/main/java/cn/lypi/transport/tui/TuiInputLoop.java`
+- `lypi-transport-tui/src/main/java/cn/lypi/transport/tui/SlashCommandRouter.java`
+- `lypi-transport-tui/src/main/java/cn/lypi/transport/tui/PermissionOverlay.java`
+- `lypi-transport-tui/src/main/java/cn/lypi/transport/tui/DiffOverlay.java`
+- `lypi-transport-tui/src/main/java/cn/lypi/transport/tui/SkillMentionParser.java`
+- `lypi-transport-tui/src/main/java/cn/lypi/transport/tui/FileMentionPicker.java`
+
+## Event Flow
+
+1. `JLineTuiTransport.open()` enters normal-screen interactive modes, probes the cursor with a timeout and replays non-CPR input.
+2. `RuntimeTuiSubmitHandler.submitUserInput()` routes slash commands and resolves Skill mentions.
+3. Normal input becomes `TurnRequest` and executes asynchronously.
+4. `TuiEventReducer.reduce()` projects message, tool, permission, retry, compact, interrupt and session events.
+5. `TuiTranscriptPartitioner` splits the stable prefix from the live tail without storing durable state.
+6. `TuiTranscriptCommitLedger` emits each stable block once per `(sessionId, leafId)` projection.
+7. `TuiRenderer` renders new committed blocks separately from the bounded live/input/overlay/status surface.
+8. On the first real-terminal frame, `InlineTerminalRenderer` prepends `TuiStartupBanner` as a one-time native-scrollback prelude.
+9. `InlineTerminalRenderer` inserts committed lines above the viewport and diffs only the mutable surface in one synchronized terminal transaction.
+
+## Invariants
+
+- Reducers should not invent durable transcript content. They project events into display state.
+- The first streaming, active, pending or running block starts the live tail; only the stable prefix can be committed.
+- A stable block ID is committed at most once per projection key, including after transient stable/live regressions.
+- Committed transcript is terminal-native scrollback. There is no application-side 500-line history window or scroll offset.
+- The startup banner is terminal decoration, not transcript: render it once per transport before initial committed history, then preserve it across redraw, resize, projection changes and close.
+- PageUp, PageDown and mouse wheel never enter an application history model or mutate the draft; scrollback remains terminal/tmux-owned.
+- Historical tools always use their completed collapsed rendering. Ctrl+O affects tools in the live region only.
+- The mutable surface is bounded by `terminalHeight - 1` and contains only live content, input, overlays and status.
+- `TerminalSession` must not enable 1049, 1000 or 1006; close and partial failure restore raw mode, cursor and interactive modes.
+- Resize probes the post-reflow cursor, preserves concurrent input, never replays committed blocks and redraws only the mutable surface.
+- Finalizing a streaming block commits its final text once in the same transaction that removes it from the surface.
+- Close clears the mutable surface while preserving committed transcript and the shell cursor handoff position.
+- A projection-key change opens a new commit epoch without clearing earlier terminal scrollback.
+- Slash commands that change durable state should route through session/runtime contracts, not UI-only variables.
+- Permission prompts display decision context and should clear on decision or interrupt.
+- Skill mentions are resolved from the current `SkillIndex`, then passed into `TurnRequest`.
+- Long-running work should not hold the UI lock while executing core logic.
+
+## Tests To Check
+
+- `lypi-transport-tui/src/test/java/cn/lypi/transport/tui/TerminalSessionTest.java`
+- `lypi-transport-tui/src/test/java/cn/lypi/transport/tui/TerminalCursorProbeTest.java`
+- `lypi-transport-tui/src/test/java/cn/lypi/transport/tui/InlineViewportTest.java`
+- `lypi-transport-tui/src/test/java/cn/lypi/transport/tui/InlineTerminalRendererTest.java`
+- `lypi-transport-tui/src/test/java/cn/lypi/transport/tui/TuiStartupBannerTest.java`
+- `lypi-transport-tui/src/test/java/cn/lypi/transport/tui/TuiTranscriptPartitionerTest.java`
+- `lypi-transport-tui/src/test/java/cn/lypi/transport/tui/TuiTranscriptCommitLedgerTest.java`
+- `lypi-transport-tui/src/test/java/cn/lypi/transport/tui/TuiLayoutTest.java`
+- `lypi-transport-tui/src/test/java/cn/lypi/transport/tui/TuiRendererTest.java`
+- `lypi-transport-tui/src/test/java/cn/lypi/transport/tui/JLineTuiTransportTest.java`
+- `lypi-transport-tui/src/test/java/cn/lypi/transport/tui/JLineTuiTransportConcurrencyTest.java`
+- `lypi-transport-tui/src/test/java/cn/lypi/transport/tui/JLineTuiTransportRenderPipelineTest.java`
+- `lypi-transport-tui/src/test/java/cn/lypi/transport/tui/RuntimeTuiSubmitHandlerTest.java`
+- `lypi-transport-tui/src/test/java/cn/lypi/transport/tui/TuiEventReducerTest.java`
+- `lypi-transport-tui/src/test/java/cn/lypi/transport/tui/PermissionOverlayTest.java`
+- `lypi-transport-tui/src/test/java/cn/lypi/transport/tui/DiffOverlayTest.java`
+- `lypi-transport-tui/src/test/java/cn/lypi/transport/tui/FileMentionPickerTest.java`
+- `lypi-transport-tui/src/test/java/cn/lypi/transport/tui/SlashCommandRouterTest.java`
+- `lypi-transport-tui/src/test/java/cn/lypi/transport/tui/SkillMentionParserTest.java`
+- `lypi-transport-tui/src/test/java/cn/lypi/transport/tui/TuiContractEndToEndTest.java`
+- `lypi-transport-tui/src/test/resources/run-tui-frame-pty.sh`
+- `lypi-transport-tui/src/test/resources/run-tui-interaction-pty.sh`
+- `lypi-transport-tui/src/test/resources/run-tui-smoke.sh`
+
+## Before Editing
+
+- Decide whether the change is view projection, rendering, input handling or runtime behavior.
+- If it changes data shape, update `lypi-contracts` view model records first.
+- Prefer event-driven state updates over querying internals from the UI layer.
+- For rendering changes, test narrow width, multiline input, streaming finalization, resize reflow and surface-height bounds.
+- For terminal lifecycle changes, test partial open failure and real tmux server/client PTYs before relying on control-sequence unit tests alone.
+- For slash commands, test consumed, prompt-rewrite and state-change paths.
+
+After using this Skill, reverse-check that the change did not move business state into TUI classes.

lypi-agent-core/src/main/java/cn/lypi/agent/AssistantStreamAccumulator.java

@@ -11,6 +11,7 @@
 import cn.lypi.contracts.model.AssistantError;
 import cn.lypi.contracts.model.AssistantStart;
 import cn.lypi.contracts.model.AssistantStreamEvent;
+import cn.lypi.contracts.model.ProviderFallbackNotice;
 import cn.lypi.contracts.model.ProviderRetryNotice;
 import cn.lypi.contracts.model.TextDelta;
 import cn.lypi.contracts.model.ThinkingDelta;
@@ -59,6 +60,8 @@ public void accept(AssistantStreamEvent event) {
             }
             case ProviderRetryNotice ignored -> {
             }
+            case ProviderFallbackNotice ignored -> {
+            }
         }
     }
 

lypi-agent-core/src/main/java/cn/lypi/agent/DefaultTurnExecutor.java

@@ -15,10 +15,12 @@
 import cn.lypi.contracts.context.ToolCallContentBlock;
 import cn.lypi.contracts.event.ErrorEvent;
 import cn.lypi.contracts.event.TurnStartEvent;
+import cn.lypi.contracts.model.AssistantDone;
 import cn.lypi.contracts.model.AssistantEventStream;
 import cn.lypi.contracts.model.AssistantError;
 import cn.lypi.contracts.model.AssistantStart;
 import cn.lypi.contracts.model.AssistantStreamEvent;
+import cn.lypi.contracts.model.ProviderFallbackNotice;
 import cn.lypi.contracts.model.ProviderRetryNotice;
 import cn.lypi.contracts.model.TextDelta;
 import cn.lypi.contracts.model.ThinkingDelta;
@@ -262,7 +264,7 @@ private AgentMessage runModel(TurnRequest request, ContextSnapshot context) {
         String sessionId = request.sessionId();
         final boolean[] assistantStarted = {false};
         final MessageKind[] startedKind = {MessageKind.TEXT};
-        Optional<ProviderRetryNotice> pendingRetry = Optional.empty();
+        ProviderAttemptLifecycles providerLifecycles = new ProviderAttemptLifecycles(sessionId);
         ProviderConversationStateHolder providerConversationState = new ProviderConversationStateHolder();
         try (AssistantEventStream stream = ports.aiProvider().stream(
             context,
@@ -271,18 +273,21 @@ private AgentMessage runModel(TurnRequest request, ContextSnapshot context) {
             request.abortSignal()
         )) {
             for (AssistantStreamEvent event : stream) {
-                if (event instanceof ProviderRetryNotice notice) {
-                    pendingRetry.ifPresent(previous -> eventPublisher.publishRetryEnd(request.sessionId(), previous, false));
-                    eventPublisher.publishRetryStart(request.sessionId(), notice);
-                    pendingRetry = Optional.of(notice);
+                if (event instanceof ProviderFallbackNotice notice) {
+                    providerLifecycles.startFallback(notice);
                     continue;
                 }
-                if (pendingRetry.isPresent()) {
-                    ProviderRetryNotice notice = pendingRetry.get();
-                    eventPublisher.publishRetryEnd(request.sessionId(), notice, !(event instanceof cn.lypi.contracts.model.AssistantError));
-                    pendingRetry = Optional.empty();
+                if (event instanceof ProviderRetryNotice notice) {
+                    providerLifecycles.startRetry(notice);
+                    continue;
                 }
                 accumulator.accept(event);
+                boolean abortRequested = request.abortSignal().aborted();
+                if (abortRequested || event instanceof AssistantError) {
+                    providerLifecycles.close(false);
+                } else if (completesProviderLifecycleSuccessfully(event)) {
+                    providerLifecycles.close(true);
+                }
                 if (event instanceof TextDelta delta) {
                     String messageId = currentAssistantId(accumulator);
                     ensureAssistantMessageStart(sessionId, messageId, MessageKind.TEXT, assistantStarted, startedKind);
@@ -339,23 +344,21 @@ private AgentMessage runModel(TurnRequest request, ContextSnapshot context) {
                         Map.of("errorId", error.errorId())
                     ));
                 }
-                if (request.abortSignal().aborted()) {
-                    pendingRetry.ifPresent(notice -> eventPublisher.publishRetryEnd(request.sessionId(), notice, false));
-                    pendingRetry = Optional.empty();
+                if (abortRequested) {
                     break;
                 }
             }
             providerConversationState.value = stream.result().providerConversationState();
         } catch (RuntimeException failure) {
-            pendingRetry.ifPresent(notice -> eventPublisher.publishRetryEnd(sessionId, notice, false));
+            providerLifecycles.close(false);
             accumulator.messageId()
                 .ifPresent(messageId -> {
                     ensureAssistantMessageStart(sessionId, messageId, MessageKind.TEXT, assistantStarted, startedKind);
                     eventPublisher.publishAssistantMessageEnd(sessionId, messageId, startedKind[0]);
                 });
             throw failure;
         }
-        pendingRetry.ifPresent(notice -> eventPublisher.publishRetryEnd(request.sessionId(), notice, false));
+        providerLifecycles.close(false);
 
         AgentMessage message = accumulator.toMessage(
             ids.newMessageId(),
@@ -366,6 +369,16 @@ private AgentMessage runModel(TurnRequest request, ContextSnapshot context) {
         return message;
     }
 
+    private boolean completesProviderLifecycleSuccessfully(AssistantStreamEvent event) {
+        return switch (event) {
+            case TextDelta delta -> delta.text() != null && !delta.text().isEmpty();
+            case ThinkingDelta delta -> delta.text() != null && !delta.text().isEmpty();
+            case ToolCallDelta ignored -> true;
+            case AssistantDone ignored -> true;
+            default -> false;
+        };
+    }
+
     private List<ToolResult<?>> executeTools(
         String sessionId,
         String turnId,
@@ -437,4 +450,42 @@ private void ensureAssistantMessageStart(
     private static final class ProviderConversationStateHolder {
         private Optional<cn.lypi.contracts.model.ProviderConversationState> value = Optional.empty();
     }
+
+    private final class ProviderAttemptLifecycles {
+        private final String sessionId;
+        private Optional<ProviderRetryNotice> pendingRetry = Optional.empty();
+        private Optional<ProviderFallbackNotice> pendingFallback = Optional.empty();
+
+        private ProviderAttemptLifecycles(String sessionId) {
+            this.sessionId = sessionId;
+        }
+
+        private void startRetry(ProviderRetryNotice notice) {
+            closeRetry(false);
+            eventPublisher.publishRetryStart(sessionId, notice);
+            pendingRetry = Optional.of(notice);
+        }
+
+        private void startFallback(ProviderFallbackNotice notice) {
+            closeRetry(false);
+            closeFallback(false);
+            eventPublisher.publishProviderFallbackStart(sessionId, notice);
+            pendingFallback = Optional.of(notice);
+        }
+
+        private void close(boolean success) {
+            closeRetry(success);
+            closeFallback(success);
+        }
+
+        private void closeRetry(boolean success) {
+            pendingRetry.ifPresent(notice -> eventPublisher.publishRetryEnd(sessionId, notice, success));
+            pendingRetry = Optional.empty();
+        }
+
+        private void closeFallback(boolean success) {
+            pendingFallback.ifPresent(notice -> eventPublisher.publishProviderFallbackEnd(sessionId, notice, success));
+            pendingFallback = Optional.empty();
+        }
+    }
 }

lypi-agent-core/src/main/java/cn/lypi/agent/TurnEventPublisher.java

@@ -11,9 +11,12 @@
 import cn.lypi.contracts.event.MessageDeltaEvent;
 import cn.lypi.contracts.event.MessageEndEvent;
 import cn.lypi.contracts.event.MessageStartEvent;
+import cn.lypi.contracts.event.ProviderFallbackEndEvent;
+import cn.lypi.contracts.event.ProviderFallbackStartEvent;
 import cn.lypi.contracts.event.RetryEndEvent;
 import cn.lypi.contracts.event.RetryStartEvent;
 import cn.lypi.contracts.event.TurnEndEvent;
+import cn.lypi.contracts.model.ProviderFallbackNotice;
 import cn.lypi.contracts.model.ProviderRetryNotice;
 import cn.lypi.contracts.model.ToolCallDelta;
 import java.time.Clock;
@@ -69,6 +72,25 @@ void publishRetryEnd(String sessionId, ProviderRetryNotice notice, boolean succe
         ));
     }
 
+    void publishProviderFallbackStart(String sessionId, ProviderFallbackNotice notice) {
+        eventBus.publish(new ProviderFallbackStartEvent(
+            sessionId,
+            notice.fromMode(),
+            notice.toMode(),
+            notice.reason(),
+            clock.instant()
+        ));
+    }
+
+    void publishProviderFallbackEnd(String sessionId, ProviderFallbackNotice notice, boolean success) {
+        eventBus.publish(new ProviderFallbackEndEvent(
+            sessionId,
+            notice.toMode(),
+            success,
+            clock.instant()
+        ));
+    }
+
     void publishAssistantMessageStart(String sessionId, String messageId, MessageKind kind) {
         eventBus.publish(new MessageStartEvent(
             sessionId,

lypi-agent-core/src/test/java/cn/lypi/agent/AssistantStreamAccumulatorTest.java

@@ -5,6 +5,7 @@
 import cn.lypi.contracts.context.MessageKind;
 import cn.lypi.contracts.model.AssistantDone;
 import cn.lypi.contracts.model.AssistantStart;
+import cn.lypi.contracts.model.ProviderFallbackNotice;
 import cn.lypi.contracts.model.TextDelta;
 import cn.lypi.contracts.model.ThinkingDelta;
 import cn.lypi.contracts.model.TokenUsage;
@@ -118,4 +119,32 @@ void returnsPartialAssistantWhenAbortedBeforeDone() {
         assertThat(message.content().getFirst().text()).isEqualTo("partial");
         assertThat(message.stopReason()).contains("aborted");
     }
+
+    @Test
+    void ignoresProviderFallbackNoticeWhenBuildingAssistantMessage() {
+        AssistantStreamAccumulator accumulator = new AssistantStreamAccumulator(clock);
+
+        accumulator.accept(new AssistantStart("msg-a"));
+        accumulator.accept(new ProviderFallbackNotice(
+            "openai",
+            1,
+            2,
+            "responses/websocket",
+            "responses/sse",
+            "fallback_candidate",
+            "provider.fallback_candidate",
+            "WebSocket handshake failed"
+        ));
+        accumulator.accept(new TextDelta("fallback ok"));
+        accumulator.accept(new AssistantDone(Optional.empty(), Optional.of("end_turn")));
+
+        AgentMessage message = accumulator.toMessage("fallback", false);
+
+        assertThat(message.id()).isEqualTo("msg-a");
+        assertThat(message.content()).singleElement().satisfies(block -> {
+            assertThat(block.kind()).isEqualTo(ContentBlockKind.TEXT);
+            assertThat(block.text()).isEqualTo("fallback ok");
+        });
+        assertThat(message.stopReason()).contains("end_turn");
+    }
 }