Dev

.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-session-engine/SKILL.md

@@ -24,6 +24,8 @@ Shared entry records and views live in `lypi-contracts/src/main/java/cn/lypi/con
 - `lypi-session/src/main/java/cn/lypi/session/ForkService.java`
 - `lypi-session/src/main/java/cn/lypi/session/ChildSessionService.java`
 - `lypi-session/src/main/java/cn/lypi/session/SessionResumeQuery.java`
+- `lypi-session/src/main/java/cn/lypi/session/SessionResumeScan.java`
+- `lypi-session/src/main/java/cn/lypi/session/SessionEntryDisplayText.java`
 - `lypi-session/src/main/java/cn/lypi/session/SessionBranchTreeQuery.java`
 - `lypi-session/src/main/java/cn/lypi/session/SessionFileQuery.java`
 - `lypi-session/src/main/java/cn/lypi/session/GitDiffQuery.java`
@@ -48,6 +50,9 @@ Shared entry records and views live in `lypi-contracts/src/main/java/cn/lypi/con
 ## Invariants
 
 - Entries have stable `id` and `parentId`; branching is represented by parent links.
+- JSONL full reads must parse line by line; header/list queries must read only the header line.
+- Resume queries use `JsonlSessionStore.resumeScans()` lightweight metadata scans, bounded by `MAX_CONCURRENT_SESSION_INFO_LOADS`, and must not full replay every session.
+- Header `id` must match the JSONL file name; list/resume paths skip unreadable or mismatched files, while direct reads fail loudly.
 - `switchLeaf()` moves the view only; it does not rewrite transcript.
 - `MessageEntry`, `BranchSummaryEntry`, `CustomMessageEntry`, and `CompactionEntry` can affect model-visible context.
 - Model, thinking, agent mode and permission runtime state are restored from entry history or child session header defaults.
@@ -83,7 +88,7 @@ Shared entry records and views live in `lypi-contracts/src/main/java/cn/lypi/con
 | New entry type | `lypi-contracts/src/main/java/cn/lypi/contracts/session/`, `SessionJsonMapper`, replay tests |
 | Change context reconstruction | `SessionReplayProjector`, `SessionManagerReplayTest` |
 | Change branch selection | `EntryTreeIndex`, `SessionLeafSelector`, branch query tests |
-| Change resume UI data | `SessionResumeQuery`, `SessionBranchTreeQuery`, TUI contract tests |
+| Change resume UI data | `SessionResumeQuery`, `SessionResumeScan`, `SessionEntryDisplayText`, `SessionBranchTreeQuery`, TUI contract tests |
 | Change child session metadata | `ChildSessionService`, subagent runtime tests |
 | Change permission runtime replay | `PermissionRuntimeStateChangeEntry`, `SessionReplayProjector`, contracts serialization tests |
 

.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.