fix(tui): move ACP session usage into footer context (#441)

## Summary
- route ACP `SessionUpdateInfo::Usage` updates into the footer context
segment instead of rendering the verbose `Session usage: ...` history
line
- use structured ACP session usage as the primary context source and
only fall back to provider-specific transcript parsing when no ACP usage
updates have arrived
- update transcript replay, view-only transcript behavior, docs, and
snapshots so the footer shows values like `Context 16% (42.6K)`
consistently

## Why
The new ACP usage history render was technically correct but too noisy
in the transcript and interrupted more important output. The footer
already has a dedicated context surface, so this change keeps the usage
signal visible without adding extra transcript clutter.

## Impact
Users on the ACP-backed Nori CLI now see context usage in the footer
instead of as a standalone history item, and replayed sessions restore
that footer state through the structured protocol path.

## Test Plan
- `just fmt`
- `cargo test -p nori-protocol`
- `cargo test -p codex-acp`
- `cargo test -p nori-tui`
- `cargo test`
- `cargo build --bin nori`
- `cargo test -p tui-pty-e2e`
- manual tmux verification with `elizacp`: launch `nori`, assert prompt
appears, submit `hello`, assert prompt returns

## Notes
- originally developed as a short stacked follow-up, then rebased onto
the latest `main` after the parent work landed

Author: CSRessel

codex-rs/acp/docs.md

@@ -89,7 +89,7 @@ The live backend path in `user_input.rs`, `submit_and_ops.rs`, `spawn_and_relay.
 
 Metadata notifications that ACP permits while idle are treated as session-owned rather than request-owned. `AvailableCommandsUpdate`, `CurrentModeUpdate`, `ConfigOptionUpdate`, `SessionInfoUpdate`, and `UsageUpdate` no longer produce "no request is active" warnings; instead the reducer persists the latest values and forwards normalized `ClientEvent`s downstream.
 
-`session/load` replay also preserves more session context than before. User-side `MessageDelta { stream: User, .. }` values are reassembled into `ReplayEntry::UserMessage`, while `SessionUpdateInfo` notes pass through unchanged so restored transcripts can show lightweight session metadata alongside the loaded conversation.
+`session/load` replay also preserves more session context than before. User-side `MessageDelta { stream: User, .. }` values are reassembled into `ReplayEntry::UserMessage`, while `SessionUpdateInfo` notes pass through unchanged. For usage updates, that replay path now restores the structured footer context state without needing to re-render the verbose message in history.
 
 **Custom Agent TOML Schema** (`config/types/mod.rs`):
 
@@ -494,9 +494,9 @@ Codex `token_count` events contain two token usage objects with different semant
 | Object | Meaning | Used For |
 |--------|---------|----------|
 | `total_token_usage` | Cumulative billing counter across ALL API calls in the session; grows unboundedly | `input_tokens`, `output_tokens`, `cached_tokens` fields (the "Tokens" footer segment) |
-| `last_token_usage` | Tokens from the most recent API call only; represents actual context window fill | `last_context_tokens` field (the "Context: XK (Y%)" footer segment) |
+| `last_token_usage` | Tokens from the most recent API call only; represents actual context window fill | `last_context_tokens` field used by transcript-discovery fallback for the "Context Y% (XK)" footer segment |
 
-Using `total_token_usage.input_tokens` for context window percentage would produce nonsensical results (e.g., 995K tokens for a 258K context window) because the cumulative counter sums across all turns. The `last_token_usage.input_tokens` correctly reflects how full the context window is for the current turn. When `last_token_usage` is absent (older transcript formats), `last_context_tokens` is `None` and the context percentage is not displayed.
+Using `total_token_usage.input_tokens` for context window percentage would produce nonsensical results (e.g., 995K tokens for a 258K context window) because the cumulative counter sums across all turns. The `last_token_usage.input_tokens` correctly reflects how full the context window is for the current turn. When ACP `UsageUpdate` events are present, the TUI prefers those live session values for the footer; transcript parsing remains a fallback for older agents/sessions where `UsageUpdate` is absent. When `last_token_usage` is absent (older transcript formats), `last_context_tokens` is `None` and the transcript fallback does not display a context percentage.
 
 **Claude Code Streaming Deduplication:**
 

codex-rs/acp/src/backend/transcript.rs

@@ -357,6 +357,7 @@ mod tests {
                 kind: nori_protocol::SessionUpdateKind::SessionInfo,
                 message: "Session info updated: title=\"Resume chat\"".into(),
                 hint: None,
+                usage: None,
             }),
             nori_protocol::ClientEvent::MessageDelta(nori_protocol::MessageDelta {
                 stream: nori_protocol::MessageStream::Answer,
@@ -374,6 +375,7 @@ mod tests {
                     kind: nori_protocol::SessionUpdateKind::SessionInfo,
                     message: "Session info updated: title=\"Resume chat\"".into(),
                     hint: None,
+                    usage: None,
                 }),
                 nori_protocol::ClientEvent::ReplayEntry(
                     nori_protocol::ReplayEntry::AssistantMessage {
@@ -392,6 +394,11 @@ mod tests {
                     kind: nori_protocol::SessionUpdateKind::Usage,
                     message: "Session usage: 128 / 4096 tokens".into(),
                     hint: None,
+                    usage: Some(nori_protocol::session_runtime::SessionUsageState {
+                        used_tokens: 128,
+                        total_tokens: 4096,
+                        cost_display: None,
+                    }),
                 },
             ),
         })]);
@@ -405,6 +412,11 @@ mod tests {
                     kind: nori_protocol::SessionUpdateKind::Usage,
                     message: "Session usage: 128 / 4096 tokens".into(),
                     hint: None,
+                    usage: Some(nori_protocol::session_runtime::SessionUsageState {
+                        used_tokens: 128,
+                        total_tokens: 4096,
+                        cost_display: None,
+                    }),
                 },
             )]
         );

codex-rs/nori-protocol/docs.md

@@ -6,7 +6,7 @@ Path: @/codex-rs/nori-protocol
 
 - Defines the normalized `ClientEvent` protocol that sits between raw ACP session updates (from `agent-client-protocol-schema`) and the TUI rendering layer. All ACP tool calls, messages, plans, approvals, and replay entries are transformed into this crate's types before reaching the TUI.
 - The `ClientEventNormalizer` is the stateful entry point: it accepts `acp::SessionUpdate` and `acp::RequestPermissionRequest` values and emits `Vec<ClientEvent>`.
-- Session-scoped ACP metadata that does not deserve bespoke widgets yet is normalized into `ClientEvent::SessionUpdateInfo`, giving the rest of the stack one minimal rendering/replay path for mode, config, session-info, and usage updates.
+- Session-scoped ACP metadata is normalized into `ClientEvent::SessionUpdateInfo`, giving the rest of the stack one minimal rendering/replay path for mode, config, and session-info updates while still letting usage updates carry structured footer state.
 - Single-file crate (`lib.rs`) with no submodules.
 
 ### How it fits into the larger codebase
@@ -29,7 +29,8 @@ agent_client_protocol_schema::SessionUpdate
 - **`SessionRuntime` support types** in `session_runtime.rs` define the reducer-owned ACP runtime model used by `codex-acp`: `SessionPhase`, `PersistedSessionState`, `ActiveRequestState`, `OpenMessage`, and `QueuedPrompt`. These types let the backend treat prompt turns, `session/load`, queued prompts, and ownership of tool/approval updates as one ordered state machine instead of reconstructing turn state from racing tasks.
 - **Session update normalization** keeps the first pass intentionally small:
   - `UserMessageChunk` becomes `MessageDelta { stream: User, .. }`, which lets replay paths reconstruct visible user history during `session/load`.
-  - `CurrentModeUpdate`, `ConfigOptionUpdate`, `SessionInfoUpdate`, and `UsageUpdate` become `SessionUpdateInfo`, a display-oriented summary with a stable `kind`.
+  - `CurrentModeUpdate`, `ConfigOptionUpdate`, and `SessionInfoUpdate` become lightweight `SessionUpdateInfo` summaries.
+  - `UsageUpdate` also becomes `SessionUpdateInfo`, but the usage variant additionally carries `SessionUsageState` so the TUI can update footer context without reparsing the display string.
 - **Persisted session metadata** now includes `session_info` and `session_usage` alongside available commands, current mode, and config options. `codex-acp` owns persistence, but these structs live here so the reducer and replay pipeline share one runtime model.
 - **`is_generic_tool_call()`** gates initial `ToolCall` emission: tool calls with no `raw_input`, no `locations`, empty `content`, and no `/` in the title are suppressed (return empty `Vec`). The normalizer still records them internally so that later attributed `ToolCallUpdate` messages can refine the existing call without forcing the TUI to render a placeholder cell first.
 - **Invocation priority cascade** in `invocation_from_tool_call()` resolves what the tool is doing, in priority order:
@@ -48,7 +49,7 @@ agent_client_protocol_schema::SessionUpdate
 ### Things to Know
 
 - The `is_generic_tool_call()` filter means the normalizer is not 1:1 with incoming events. Initial `ToolCall` messages that are sufficiently sparse are silently dropped, but later `ToolCallUpdate` messages still become visible `ToolSnapshot`s even if no initial `ToolCall` ever arrived.
-- `SessionUpdateInfo` is intentionally lossy. It exists to stop valid ACP session updates from disappearing while the UI remains lightweight; richer dedicated widgets can still be layered on later without changing ACP reducer semantics.
+- `SessionUpdateInfo` stays intentionally lightweight, but it is no longer fully lossy: the `Usage` variant also carries structured `SessionUsageState` so replay and live footer updates can share the same path.
 - The location fallback (tier 4) only handles `Read` and `Search` kinds. Edit/Delete/Move with locations but no `raw_input` return `None` from the normalizer and fall through to the TUI's location-path display fallback, avoiding creation of empty-diff `FileOperations` that would route to `PatchHistoryCell`.
 - `sanitize_title()` is a two-pass operation: first strips the `[current working directory ...]` bracket, then strips trailing `(description)` parenthetical. The parenthetical strip only fires after a cwd bracket was found, because Gemini appends descriptions after the cwd metadata.
 - Shell wrapper detection (`is_shell_wrapper()`) recognizes `bash`, `sh`, `zsh`, `fish`, `pwsh`, and `powershell` with `-c` or `-lc` flags. When a 3-element command array matches this pattern, only the script portion is extracted as the command string.

codex-rs/nori-protocol/src/lib.rs

@@ -76,6 +76,8 @@ pub struct SessionUpdateInfo {
     pub kind: SessionUpdateKind,
     pub message: String,
     pub hint: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub usage: Option<session_runtime::SessionUsageState>,
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
@@ -959,6 +961,7 @@ fn session_update_info_from_current_mode(update: &acp::CurrentModeUpdate) -> Ses
         kind: SessionUpdateKind::CurrentMode,
         message: format!("ACP mode changed to {}", update.current_mode_id),
         hint: None,
+        usage: None,
     }
 }
 
@@ -978,6 +981,7 @@ fn session_update_info_from_config_options(update: &acp::ConfigOptionUpdate) ->
         kind: SessionUpdateKind::ConfigOptions,
         message,
         hint: None,
+        usage: None,
     }
 }
 
@@ -1001,6 +1005,7 @@ fn session_update_info_from_session_info(update: &acp::SessionInfoUpdate) -> Ses
         kind: SessionUpdateKind::SessionInfo,
         message,
         hint: None,
+        usage: None,
     }
 }
 
@@ -1028,6 +1033,14 @@ fn session_update_info_from_usage(update: &acp::UsageUpdate) -> SessionUpdateInf
         kind: SessionUpdateKind::Usage,
         message,
         hint: None,
+        usage: Some(session_runtime::SessionUsageState {
+            used_tokens: update.used as i64,
+            total_tokens: update.size as i64,
+            cost_display: update
+                .cost
+                .as_ref()
+                .map(|cost| format!("{:.2} {}", cost.amount, cost.currency)),
+        }),
     }
 }
 
@@ -2168,6 +2181,14 @@ mod tests {
         };
 
         assert_eq!(info.kind, SessionUpdateKind::Usage);
+        assert_eq!(
+            info.usage,
+            Some(session_runtime::SessionUsageState {
+                used_tokens: 128,
+                total_tokens: 4096,
+                cost_display: Some("0.42 USD".to_string()),
+            })
+        );
         assert_eq!(
             info.message,
             "Session usage: 128 / 4096 tokens, cost 0.42 USD"

codex-rs/nori-protocol/src/session_runtime.rs

@@ -9,6 +9,8 @@ use std::collections::HashSet;
 use std::collections::VecDeque;
 
 use agent_client_protocol_schema as acp;
+use serde::Deserialize;
+use serde::Serialize;
 
 use crate::AgentCommandInfo;
 use crate::PlanSnapshot;
@@ -163,7 +165,7 @@ pub struct SessionInfoState {
     pub updated_at: Option<String>,
 }
 
-#[derive(Debug, Clone, PartialEq, Eq)]
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct SessionUsageState {
     pub used_tokens: i64,
     pub total_tokens: i64,

codex-rs/tui/docs.md

@@ -47,7 +47,7 @@ The main event loop in `app/mod.rs` processes:
 2. **Backend events** from ACP: `BackendEvent::Client` carries normalized `nori_protocol::ClientEvent` session data, while `BackendEvent::Control` carries shared control-plane events
 3. **App events** for state changes (agent selection, config updates)
 
-The client-event stream now also includes lightweight ACP session metadata summaries. Rather than adding dedicated UI chrome for every ACP session update, the first-pass TUI behavior renders `ClientEvent::SessionUpdateInfo` as ordinary info/history cells and includes the same text in the view-only transcript.
+The client-event stream now also includes lightweight ACP session metadata summaries. Most `ClientEvent::SessionUpdateInfo` values still render as ordinary info/history cells, but usage updates are handled specially: they update the footer context segment and are omitted from both live history cells and the view-only transcript.
 
 The chat interface is managed by the `chatwidget/` module (`chatwidget/mod.rs` + submodules), which handles:
 - User input composition with multi-line editing
@@ -415,7 +415,7 @@ The card always shows: version, directory, agent, skillset (Nori profile). Optio
 |---------|-----------|---------|
 | Task summary | `prompt_summary` present | "Task: Fix auth bug" |
 | Approval mode | `approval_mode_label` present | "approvals: Agent" |
-| Context line | `context_window_percent` present, with or without token data | "Context: 77.0K (27%)" or just "42%" |
+| Context line | `context_window_percent` present, with or without token data | "Context 27% (77.0K)" or just "Context 42%" |
 | Token totals | `token_breakdown` has non-zero total | "Tokens: 123K total (32.0K cached)" |
 
 The Tokens section renders if either `token_breakdown` has a non-zero total OR `context_window_percent` is present. This means context window percentage from the live API (`TokenUsageInfo`) can appear even before transcript token data is available.
@@ -598,7 +598,7 @@ The footer displays configurable segments, each of which can be enabled/disabled
 | Git Branch | `git_branch` | Current branch name with ⎇ symbol (yellow for main repo, orange for worktree) |
 | Worktree Name | `worktree_name` | "Worktree: {name}" (light red) when running in an auto-worktree session -- the immutable directory name, distinct from the git branch which gets renamed after the first prompt |
 | Git Stats | `git_stats` | Lines added/removed in current session |
-| Context Window | `context` | "Context: 34K (27%)" when running within an agent environment |
+| Context Window | `context` | "Context 27% (34K)" when running within an agent environment |
 | Approval Mode | `approval_mode` | "Approvals: Agent/Full Access/Read Only" |
 | Nori Profile | `nori_profile` | "Skillset: name" for one active skillset, "Skillsets: a, b" for multiple, hidden when none are active. Uses `active_skillsets` from `SystemInfo` (populated by `nori-skillsets list-active`). |
 | Nori Version | `nori_version` | "Skillsets v<version>" |
@@ -614,6 +614,7 @@ git_stats = false
 All segments are enabled by default. The order of segments in the footer is fixed (cannot be reordered via config).
 
 Token data flows from `TranscriptLocation.token_breakdown` (provided by `codex_acp::discover_transcript_for_agent_with_message()`) through `FooterProps` to the footer renderer. The breakdown includes separate input, output, and cached token counts for accurate usage reporting.
+Footer context usage is sourced in priority order: ACP `SessionUpdateInfo { kind: Usage, usage: Some(..) }` updates drive the footer when available, while `TranscriptLocation.token_breakdown` remains the provider-specific fallback for older sessions or agents that do not emit ACP usage updates.
 
 The prompt summary flows from the ACP backend as an `EventMsg::PromptSummary` event, handled by `ChatWidget::on_prompt_summary()`, which propagates it down: `ChatWidget` -> `BottomPane::set_prompt_summary()` -> `ChatComposer::set_prompt_summary()` -> `FooterProps.prompt_summary` -> `footer_segments()` renderer.
 

codex-rs/tui/src/bottom_pane/chat_composer/mod.rs

@@ -120,6 +120,7 @@ pub(crate) struct ChatComposer {
     footer_mode: FooterMode,
     footer_hint_override: Option<Vec<(String, String)>>,
     context_window_percent: Option<i64>,
+    session_usage: Option<nori_protocol::session_runtime::SessionUsageState>,
     system_info: Option<crate::system_info::SystemInfo>,
     /// The approval mode label to display in the footer (e.g., "Read Only", "Agent", "Full Access").
     approval_mode_label: Option<String>,
@@ -179,6 +180,7 @@ impl ChatComposer {
             footer_mode: FooterMode::ShortcutSummary,
             footer_hint_override: None,
             context_window_percent: None,
+            session_usage: None,
             system_info: None,
             approval_mode_label: None,
             vim_enter_behavior: codex_acp::config::VimEnterBehavior::Off,
@@ -369,6 +371,13 @@ impl ChatComposer {
         }
     }
 
+    pub(crate) fn set_session_usage(
+        &mut self,
+        usage: Option<nori_protocol::session_runtime::SessionUsageState>,
+    ) {
+        self.session_usage = usage;
+    }
+
     pub(crate) fn set_system_info(&mut self, info: crate::system_info::SystemInfo) {
         self.system_info = Some(info);
     }

codex-rs/tui/src/bottom_pane/chat_composer/rendering.rs

@@ -79,6 +79,21 @@ impl ChatComposer {
                 })
             })
         });
+        let (context_tokens, context_window_percent) =
+            if let Some(session_usage) = &self.session_usage {
+                (
+                    Some(session_usage.used_tokens).filter(|&tokens| tokens > 0),
+                    (session_usage.total_tokens > 0).then(|| {
+                        session_usage
+                            .used_tokens
+                            .saturating_mul(100)
+                            .saturating_div(session_usage.total_tokens)
+                            .clamp(0, 100)
+                    }),
+                )
+            } else {
+                (context_tokens, context_window_percent)
+            };
 
         FooterProps {
             mode: self.footer_mode(),