anima-core 1.2.0 → 1.4.0

data/lib/tui/app.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "time"
+require_relative "settings"
 require_relative "cable_client"
 require_relative "input_buffer"
 require_relative "message_store"
@@ -21,10 +22,7 @@ module TUI
     }.freeze
 
     MENU_LABELS = (COMMAND_KEYS.map { |key, action| "[#{key}] #{action.to_s.tr("_", " ").capitalize}" } +
-      ["[\u2191] Scroll chat", "[\u2193] Return to input"]).freeze
-
-    # HUD occupies 1/3 of screen width, clamped to a usable minimum.
-    HUD_MIN_WIDTH = 24
+      ["[\u2191] Scroll chat", "[\u2193] Return to input", "[\u2192] Sub-agents / HUD"]).freeze
 
     # Picker entry prefix width: "[N]" (3) + marker (1) + space (1) = 5
     PICKER_PREFIX_WIDTH = 5
@@ -38,28 +36,22 @@ module TUI
 
     # Connection status emoji indicators for the info panel.
     # Subscribed (normal state) shows only the emoji; other states add text.
-    STATUS_STYLES = {
-      disconnected: {label: "🔴 Disconnected", color: "red"},
-      connecting: {label: "🟡 Connecting", color: "yellow"},
-      connected: {label: "🟡 Connecting", color: "yellow"},
-      subscribed: {label: "🟢", color: "green"},
-      reconnecting: {label: "🟡 Reconnecting", color: "yellow"}
+    STATUS_LABELS = {
+      disconnected: "🔴 Disconnected",
+      connecting: "🟡 Connecting",
+      connected: "🟡 Connecting",
+      subscribed: "🟢",
+      reconnecting: "🟡 Reconnecting"
     }.freeze
 
-    # Number of leading characters to show unmasked in the token input.
-    # Matches the "sk-ant-oat01-" prefix (13 chars) plus one character of the
-    # secret portion so the user can verify both the token type and start of key.
-    TOKEN_MASK_VISIBLE = 14
-
-    # Maximum stars to show in the masked portion of the token.
-    # Keeps the masked display compact regardless of actual token length.
-    TOKEN_MASK_STARS = 4
-
-    # Token setup popup dimensions. Height accommodates: status line, blank,
-    # 2 instruction lines, blank, "Token:" label, input line, blank,
-    # error/success line, blank, hint line, plus top/bottom borders.
-    POPUP_HEIGHT = 14
-    POPUP_MIN_WIDTH = 44
+    # Maps connection status to semantic theme color.
+    STATUS_COLORS = {
+      disconnected: :theme_color_error,
+      connecting: :theme_color_warning,
+      connected: :theme_color_warning,
+      subscribed: :theme_color_success,
+      reconnecting: :theme_color_warning
+    }.freeze
 
     # Matches a single printable Unicode character (no control codes).
     PRINTABLE_CHAR = /\A[[:print:]]\z/
@@ -67,21 +59,18 @@ module TUI
     # Signals that trigger graceful shutdown when received from the OS.
     SHUTDOWN_SIGNALS = %w[HUP TERM INT].freeze
 
-    # How often the watchdog thread checks if the controlling terminal is alive.
-    # @see #terminal_watchdog_loop
-    TERMINAL_CHECK_INTERVAL = 0.5
-
     # Unix controlling terminal device path.
     # @see #terminal_watchdog_loop
     CONTROLLING_TERMINAL = "/dev/tty"
 
-    # Grace period for watchdog thread to exit before force-killing it.
-    WATCHDOG_SHUTDOWN_TIMEOUT = 1
-
     attr_reader :current_screen, :command_mode, :session_picker_active,
       :view_mode_picker_active
     # @return [Boolean] true when the HUD info panel is visible
     attr_reader :hud_visible
+    # @return [Boolean] true when the HUD pane has keyboard focus for scrolling
+    attr_reader :hud_focused
+    # @return [Integer, nil] index of selected child in HUD navigation, nil when inactive
+    attr_reader :hud_child_index
     # @return [Boolean] true when the token setup popup overlay is visible
     attr_reader :token_setup_active
     # @return [Boolean] true when graceful shutdown has been requested via signal
@@ -102,6 +91,12 @@ module TUI
       @session_picker_mode = :root
       @session_picker_parent_id = nil
       @hud_visible = true
+      @hud_focused = false
+      @hud_child_index = nil
+      @hud_scroll_offset = 0
+      @hud_max_scroll = 0
+      @hud_visible_height = 0
+      @hud_content_area = nil
       @view_mode_picker_active = false
       @view_mode_picker_index = 0
       @token_setup_active = false
@@ -146,7 +141,7 @@ module TUI
       @screens[:chat].hud_hint = !@hud_visible
 
       if @hud_visible
-        hud_width = [frame.area.width / 3, HUD_MIN_WIDTH].max
+        hud_width = [frame.area.width / 3, Settings.hud_min_width].max
         content_area, sidebar = tui.split(
           frame.area,
           direction: :horizontal,
@@ -187,7 +182,7 @@ module TUI
           title: "Command",
           borders: [:all],
           border_type: :rounded,
-          border_style: {fg: "yellow"}
+          border_style: {fg: Settings.theme_border_focused}
         )
       )
       frame.render_widget(menu, area)
@@ -197,35 +192,58 @@ module TUI
     GOAL_ICON_ACTIVE = "\u25CF"       # ●
     GOAL_ICON_IN_PROGRESS = "\u25D0"  # ◐
     GOAL_ICON_COMPLETED = "\u2713"    # ✓
-    CHILD_ICON_RUNNING = "\u25CF"     # ●
-    CHILD_ICON_IDLE = "\u25CC"        # ◌
+
+    # Sub-agent state icons — form communicates type of work,
+    # color communicates status. Work independently.
+    CHILD_ICON_IDLE = "\u25CC"              # ◌ hollow — nothing happening
+    CHILD_ICON_GENERATING = "\u25CF"        # ● filled — LLM thinking
+    CHILD_ICON_TOOL_EXECUTING = "\u25C9"    # ◉ dot-in-circle — tool running
+    CHILD_ICON_INTERRUPTING = "\u25CF"      # ● filled — stopping
 
     def render_info(frame, area, tui)
       session = @screens[:chat].session_info
-
-      # Split into main content area and bottom status bar
-      main_area, status_area = tui.split(
-        area,
-        direction: :vertical,
-        constraints: [
-          tui.constraint_fill(1),
-          tui.constraint_length(3)
-        ]
-      )
-
-      render_hud_content(frame, main_area, tui, session)
+      stats = @screens[:chat].message_store.token_economy
+      has_metrics = stats[:call_count] > 0 || stats[:rate_limits]
+
+      # Split into main content, optional token economy panel, and status bar
+      if has_metrics
+        economy_height = token_economy_line_count(stats) + 1 # +1 for top border
+        main_area, economy_area, status_area = tui.split(
+          area,
+          direction: :vertical,
+          constraints: [
+            tui.constraint_fill(1),
+            tui.constraint_length(economy_height),
+            tui.constraint_length(2)
+          ]
+        )
+        render_hud_content(frame, main_area, tui, session)
+        render_token_economy_panel(frame, economy_area, tui, stats)
+      else
+        main_area, status_area = tui.split(
+          area,
+          direction: :vertical,
+          constraints: [
+            tui.constraint_fill(1),
+            tui.constraint_length(2)
+          ]
+        )
+        render_hud_content(frame, main_area, tui, session)
+      end
       render_hud_status_bar(frame, status_area, tui)
     end
 
     # Renders the main HUD content: session name, goals, skills,
-    # workflow, and sub-agents.
+    # workflow, and sub-agents. Supports vertical scrolling with
+    # a scrollbar when content exceeds the visible area.
     def render_hud_content(frame, area, tui, session)
+      @hud_content_area = area
       session_label = session[:name] || "##{session[:id]}"
 
       lines = [
         tui.line(spans: [
-          tui.span(content: "\u{1F4CB} ", style: tui.style(fg: "dark_gray")),
-          tui.span(content: session_label, style: tui.style(fg: "cyan", modifiers: [:bold]))
+          tui.span(content: "\u{1F4CB} ", style: tui.style(fg: Settings.theme_color_muted)),
+          tui.span(content: session_label, style: tui.style(fg: Settings.theme_color_info, modifiers: [:bold]))
         ]),
         hud_goals_section(tui, session),
         hud_skills_line(tui, session),
@@ -234,51 +252,79 @@ module TUI
         interaction_state_line(tui)
       ].flatten.compact
 
+      @hud_visible_height = [area.height - 2, 0].max
+      inner_width = [area.width - 2, 1].max
+      total_height = tui.paragraph(text: lines, wrap: true).line_count(inner_width)
+      @hud_max_scroll = [total_height - @hud_visible_height, 0].max
+      @hud_scroll_offset = @hud_scroll_offset.clamp(0, @hud_max_scroll)
+
+      border_color = @hud_focused ? Settings.theme_border_focused : Settings.theme_border_normal
+
       content = tui.paragraph(
         text: lines,
         wrap: true,
+        scroll: [@hud_scroll_offset, 0],
         block: tui.block(
           borders: [:left, :top, :right],
           border_type: :rounded,
-          border_style: {fg: "white"}
+          border_style: {fg: border_color}
         )
       )
       frame.render_widget(content, area)
+
+      render_hud_scrollbar(frame, area, tui)
+    end
+
+    # Renders a scrollbar on the right edge of the HUD when content overflows.
+    def render_hud_scrollbar(frame, area, tui)
+      return unless @hud_max_scroll > 0
+
+      scrollbar = tui.scrollbar(
+        content_length: @hud_max_scroll,
+        position: @hud_scroll_offset,
+        orientation: :vertical_right,
+        thumb_style: {fg: Settings.theme_scrollbar_thumb},
+        track_symbol: "\u2502",
+        track_style: {fg: Settings.theme_scrollbar_track}
+      )
+      frame.render_widget(scrollbar, area)
     end
 
     # Renders the bottom status bar: connection state and model name.
     def render_hud_status_bar(frame, area, tui)
       cable_status = @cable_client.status
-      style = STATUS_STYLES.fetch(cable_status, STATUS_STYLES[:disconnected])
+      label = STATUS_LABELS.fetch(cable_status, STATUS_LABELS[:disconnected])
+      status_color = Settings.public_send(STATUS_COLORS.fetch(cable_status, :theme_color_error))
 
       status_label = if cable_status == :reconnecting
         attempt = @cable_client.reconnect_attempt
-        max = CableClient::MAX_RECONNECT_ATTEMPTS
-        "#{style[:label]} (#{attempt}/#{max})"
+        max = Settings.connection_max_reconnect_attempts
+        "#{label} (#{attempt}/#{max})"
       else
-        style[:label]
+        label
       end
 
       view_mode = @screens[:chat].view_mode
       mode_label = view_mode.capitalize
       mode_color = case view_mode
-      when "verbose" then "yellow"
-      when "debug" then "magenta"
-      else "cyan"
+      when "verbose" then Settings.theme_color_warning
+      when "debug" then Settings.theme_color_accent
+      else Settings.theme_color_info
       end
 
       bar = tui.paragraph(
         text: [
           tui.line(spans: [
-            tui.span(content: status_label, style: tui.style(fg: style[:color], modifiers: [:bold])),
-            tui.span(content: " \u2502 ", style: tui.style(fg: "dark_gray")),
+            tui.span(content: "  ", style: tui.style(fg: Settings.theme_color_muted)),
+            tui.span(content: status_label, style: tui.style(fg: status_color, modifiers: [:bold])),
+            tui.span(content: " ", style: tui.style(fg: Settings.theme_color_muted)),
             tui.span(content: mode_label, style: tui.style(fg: mode_color, modifiers: [:bold]))
           ])
         ],
         block: tui.block(
           borders: [:left, :bottom, :right],
           border_type: :rounded,
-          border_style: {fg: "white"}
+          border_style: {fg: Settings.theme_border_normal}
         )
       )
       frame.render_widget(bar, area)
@@ -296,7 +342,7 @@ module TUI
       lines = [
         tui.line(spans: [tui.span(content: "")]),
         tui.line(spans: [
-          tui.span(content: "\u{1F3AF} Goals", style: tui.style(fg: "dark_gray"))
+          tui.span(content: "\u{1F3AF} Goals", style: tui.style(fg: Settings.theme_color_muted))
         ])
       ]
 
@@ -304,7 +350,7 @@ module TUI
         icon, color = goal_icon_and_color(goal)
         lines << tui.line(spans: [
           tui.span(content: "  #{icon} ", style: tui.style(fg: color)),
-          tui.span(content: goal["description"].to_s, style: tui.style(fg: "white"))
+          tui.span(content: goal["description"].to_s, style: tui.style(fg: Settings.theme_color_text))
         ])
       end
 
@@ -318,11 +364,11 @@ module TUI
     # @return [Array(String, String)] icon and color pair
     def goal_icon_and_color(goal)
       if goal["status"] == "completed"
-        [GOAL_ICON_COMPLETED, "green"]
+        [GOAL_ICON_COMPLETED, Settings.theme_color_success]
       elsif goal["sub_goals"]&.any? { |sg| sg["status"] == "completed" }
-        [GOAL_ICON_IN_PROGRESS, "yellow"]
+        [GOAL_ICON_IN_PROGRESS, Settings.theme_color_warning]
       else
-        [GOAL_ICON_ACTIVE, "cyan"]
+        [GOAL_ICON_ACTIVE, Settings.theme_color_info]
       end
     end
 
@@ -335,8 +381,8 @@ module TUI
       [
         tui.line(spans: [tui.span(content: "")]),
         tui.line(spans: [
-          tui.span(content: "\u{1F9E0} ", style: tui.style(fg: "dark_gray")),
-          tui.span(content: skills.join(", "), style: tui.style(fg: "yellow"))
+          tui.span(content: "\u{1F9E0} ", style: tui.style(fg: Settings.theme_color_muted)),
+          tui.span(content: skills.join(", "), style: tui.style(fg: Settings.theme_color_warning))
         ])
       ]
     end
@@ -350,58 +396,273 @@ module TUI
       [
         tui.line(spans: [tui.span(content: "")]),
         tui.line(spans: [
-          tui.span(content: "\u{1F4DC} ", style: tui.style(fg: "dark_gray")),
-          tui.span(content: workflow, style: tui.style(fg: "magenta"))
+          tui.span(content: "\u{1F4DC} ", style: tui.style(fg: Settings.theme_color_muted)),
+          tui.span(content: workflow, style: tui.style(fg: Settings.theme_color_accent))
         ])
       ]
     end
 
     # Builds the sub-agents section with activity indicators.
+    # Highlights the selected child when HUD child navigation is active.
     # @return [Array<RatatuiRuby::Widgets::Line>, nil]
     def hud_children_section(tui, session)
       children = session[:children]
       return if children.nil? || children.empty?
 
+      header_label = @hud_child_index ? "Sub-agents [\u2190 back]" : "Sub-agents"
+
       lines = [
         tui.line(spans: [tui.span(content: "")]),
         tui.line(spans: [
-          tui.span(content: "\u{1F465} Sub-agents", style: tui.style(fg: "dark_gray"))
+          tui.span(content: "\u{1F465} #{header_label}", style: tui.style(fg: Settings.theme_color_muted))
         ])
       ]
 
-      children.each do |child|
+      children.each_with_index do |child, idx|
         icon, color = child_icon_and_color(child)
         name = child["name"] || "sub-agent"
-        lines << tui.line(spans: [
-          tui.span(content: "  #{icon} ", style: tui.style(fg: color)),
-          tui.span(content: "@#{name}", style: tui.style(fg: "white"))
-        ])
+        selected = idx == @hud_child_index
+
+        lines << if selected
+          tui.line(spans: [
+            tui.span(content: "\u25B8 #{icon} ", style: tui.style(fg: Settings.theme_color_info)),
+            tui.span(content: "@#{name}", style: tui.style(fg: Settings.theme_color_info, modifiers: [:bold]))
+          ])
+        else
+          tui.line(spans: [
+            tui.span(content: "  #{icon} ", style: tui.style(fg: color)),
+            tui.span(content: "@#{name}", style: tui.style(fg: Settings.theme_color_text))
+          ])
+        end
       end
 
       lines
     end
 
     # Returns the activity icon and color for a child session.
+    # Form communicates type of work, color communicates status —
+    # they work independently so even without color the shape tells
+    # the story.
     #
-    # @param child [Hash] child session data with "processing" key
+    # @param child [Hash] child session data with "session_state" key
     # @return [Array(String, String)] icon and color pair
     def child_icon_and_color(child)
-      if child["processing"]
-        [CHILD_ICON_RUNNING, "yellow"]
+      case child["session_state"]
+      when "llm_generating"
+        [CHILD_ICON_GENERATING, Settings.theme_color_success]
+      when "tool_executing"
+        [CHILD_ICON_TOOL_EXECUTING, Settings.theme_color_success]
+      when "interrupting"
+        [CHILD_ICON_INTERRUPTING, Settings.theme_color_error]
       else
-        [CHILD_ICON_IDLE, "green"]
+        [CHILD_ICON_IDLE, Settings.theme_color_muted]
+      end
+    end
+
+    # Renders the Token Economy panel as a fixed section between HUD content
+    # and the status bar.
+    def render_token_economy_panel(frame, area, tui, stats)
+      lines = []
+
+      rate_limits = stats[:rate_limits]
+      lines.concat(build_rate_limit_lines(tui, rate_limits)) if rate_limits
+      lines.concat(build_cache_metrics_lines(tui, stats)) if stats[:call_count] > 0
+
+      panel = tui.paragraph(
+        text: lines,
+        block: tui.block(
+          title: " \u{1F4CA} Token Economy ",
+          borders: [:left, :top, :right],
+          border_type: :rounded,
+          border_style: {fg: Settings.theme_border_normal}
+        )
+      )
+      frame.render_widget(panel, area)
+    end
+
+    # Returns the number of content lines the token economy panel will render.
+    def token_economy_line_count(stats)
+      count = 0
+      if stats[:rate_limits]
+        count += 1 if stats[:rate_limits]["5h_utilization"]
+        count += 1 if stats[:rate_limits]["7d_utilization"]
+      end
+      if stats[:call_count] > 0
+        count += 2 # cache hit bar + saved
+        count += 1 if stats[:cache_history]&.size.to_i > 1 # sparkline
       end
+      count
     end
 
-    # Shows "Scrolling" when chat pane is focused, "Thinking..." during LLM processing.
+    # Builds rate limit display lines with progress bars and pacing.
+    # Compact aligned labels: 5h, 7d (same 2-char width).
+    # @return [Array<RatatuiRuby::Widgets::Line>]
+    def build_rate_limit_lines(tui, rate_limits)
+      lines = []
+
+      # 5-hour window
+      util_5h = rate_limits["5h_utilization"]
+      if util_5h
+        pct = (util_5h * 100).round
+        bar = build_progress_bar(pct, Settings.theme_progress_bar_width)
+        color = rate_limit_color(pct)
+        reset_5h = rate_limits["5h_reset"]
+        reset_label = reset_5h ? " #{format_reset_time(reset_5h)}" : ""
+
+        lines << tui.line(spans: [
+          tui.span(content: "  5h ", style: tui.style(fg: color, modifiers: [:bold])),
+          tui.span(content: bar, style: tui.style(fg: color)),
+          tui.span(content: " #{pct.to_s.rjust(2)}%", style: tui.style(fg: color)),
+          tui.span(content: reset_label, style: tui.style(fg: Settings.theme_color_muted))
+        ])
+      end
+
+      # 7-day window
+      util_7d = rate_limits["7d_utilization"]
+      if util_7d
+        pct = (util_7d * 100).round
+        bar = build_progress_bar(pct, Settings.theme_progress_bar_width)
+        color = rate_limit_color(pct)
+
+        lines << tui.line(spans: [
+          tui.span(content: "  7d ", style: tui.style(fg: color, modifiers: [:bold])),
+          tui.span(content: bar, style: tui.style(fg: color)),
+          tui.span(content: " #{pct.to_s.rjust(2)}%", style: tui.style(fg: color))
+        ])
+      end
+
+      lines
+    end
+
+    # Builds cache efficiency display lines with sparkline graph.
+    # ⚡ for hit rate bar, braille sparkline for per-call history, 💾 for saved.
+    # @return [Array<RatatuiRuby::Widgets::Line>]
+    def build_cache_metrics_lines(tui, stats)
+      hit_rate = (stats[:cache_hit_rate] * 100).round
+      color = cache_hit_color(hit_rate)
+      bar = build_progress_bar(hit_rate, Settings.theme_progress_bar_width)
+
+      total_cached = stats[:cache_read_input_tokens]
+      saved_label = format_token_count(total_cached)
+
+      lines = [
+        tui.line(spans: [
+          tui.span(content: "  \u{26A1} ", style: tui.style(fg: color)),
+          tui.span(content: bar, style: tui.style(fg: color)),
+          tui.span(content: " #{hit_rate.to_s.rjust(2)}%", style: tui.style(fg: color))
+        ]),
+        tui.line(spans: [
+          tui.span(content: "  \u{1F4BE} ", style: tui.style(fg: Settings.theme_color_success)),
+          tui.span(content: saved_label, style: tui.style(fg: Settings.theme_color_success))
+        ])
+      ]
+
+      # Braille sparkline: per-call cache hit history (below icons)
+      history = stats[:cache_history]
+      if history && history.size > 1
+        sparkline = build_braille_sparkline(history)
+        color = cache_hit_color(hit_rate)
+        lines << tui.line(spans: [
+          tui.span(content: "     ", style: tui.style(fg: Settings.theme_color_muted)),
+          tui.span(content: sparkline, style: tui.style(fg: color))
+        ])
+      end
+
+      lines
+    end
+
+    # Builds a braille sparkline from a series of values (0.0-1.0).
+    # Each braille character encodes two adjacent data points using
+    # the left and right dot columns (4 dots each = 5 levels: 0-4).
+    #
+    # @param values [Array<Float>] data points between 0.0 and 1.0
+    # @return [String] braille sparkline string
+    def build_braille_sparkline(values)
+      # Braille dot positions: left column (dots 1,2,3,7), right column (dots 4,5,6,8)
+      # Numbered per Unicode spec: bit 0=dot1, bit 1=dot2, bit 2=dot3,
+      # bit 3=dot4, bit 4=dot5, bit 5=dot6, bit 6=dot7, bit 7=dot8
+      left_dots = [0x01, 0x02, 0x04, 0x40]   # dots 1,2,3,7 (bottom to top)
+      right_dots = [0x08, 0x10, 0x20, 0x80]   # dots 4,5,6,8 (bottom to top)
+
+      chars = []
+      values.each_slice(2) do |pair|
+        code = 0x2800 # braille base
+        # Left column: first value
+        fill_left = (pair[0].clamp(0.0, 1.0) * 4).round
+        fill_left.times { |i| code |= left_dots[i] }
+        # Right column: second value (or repeat first if odd)
+        right_val = pair[1] || pair[0]
+        fill_right = (right_val.clamp(0.0, 1.0) * 4).round
+        fill_right.times { |i| code |= right_dots[i] }
+        chars << code.chr(Encoding::UTF_8)
+      end
+      chars.join
+    end
+
+    # Builds a Unicode progress bar.
+    # @param pct [Integer] percentage (0-100)
+    # @param width [Integer] bar width in characters
+    # @return [String] progress bar string
+    def build_progress_bar(pct, width)
+      filled = (pct.clamp(0, 100) * width / 100.0).round
+      empty = width - filled
+      ("\u2593" * filled) + ("\u2591" * empty)
+    end
+
+    # Color for rate limit percentage: green below warning, yellow below critical, red above.
+    def rate_limit_color(pct)
+      return Settings.theme_color_error if pct >= Settings.theme_rate_limit_critical
+      return Settings.theme_color_warning if pct >= Settings.theme_rate_limit_warning
+      Settings.theme_color_success
+    end
+
+    # Color for cache hit rate: green above good, yellow above low, red below.
+    def cache_hit_color(pct)
+      return Settings.theme_color_success if pct >= Settings.theme_cache_hit_good
+      return Settings.theme_color_warning if pct >= Settings.theme_cache_hit_low
+      Settings.theme_color_error
+    end
+
+    # Formats a reset timestamp as time remaining (e.g., "2h15m").
+    def format_reset_time(epoch_seconds)
+      diff = epoch_seconds - Time.now.to_i
+      return "soon" if diff <= 0
+
+      hours = diff / 3600
+      minutes = (diff % 3600) / 60
+      if hours > 0
+        "\u279E#{hours}h#{minutes.to_s.rjust(2, "0")}m"
+      else
+        "\u279E#{minutes}m"
+      end
+    end
+
+    # Formats a token count for display (e.g., "47.2K").
+    def format_token_count(count)
+      return "0" if count == 0
+      return count.to_s if count < 1000
+      "#{(count / 1000.0).round(1)}K tokens"
+    end
+
+    # Shows focus mode when a pane is focused, or the braille spinner
+    # during active processing.
     def interaction_state_line(tui)
-      if @screens[:chat].chat_focused
+      if @hud_focused
+        tui.line(spans: [
+          tui.span(content: "HUD Scroll", style: tui.style(fg: Settings.theme_color_warning, modifiers: [:bold]))
+        ])
+      elsif @screens[:chat].chat_focused
         tui.line(spans: [
-          tui.span(content: "Scrolling", style: tui.style(fg: "yellow", modifiers: [:bold]))
+          tui.span(content: "Scrolling", style: tui.style(fg: Settings.theme_color_warning, modifiers: [:bold]))
         ])
       elsif chat_loading?
+        chat = @screens[:chat]
+        char = chat.spinner.tick || "\u2800"
+        color = chat.spinner_color
+        label = chat.spinner_label
         tui.line(spans: [
-          tui.span(content: "Thinking...", style: tui.style(fg: "magenta", modifiers: [:bold]))
+          tui.span(content: "#{char} ", style: tui.style(fg: color, modifiers: [:bold])),
+          tui.span(content: label, style: tui.style(fg: color))
         ])
       end
     end
@@ -410,6 +671,52 @@ module TUI
       @screens[:chat].loading?
     end
 
+    # Switches keyboard focus to the HUD pane.
+    # When children exist, enters child navigation mode with the first
+    # child selected; otherwise enters plain scroll mode.
+    #
+    # @return [void]
+    def focus_hud
+      @screens[:chat].unfocus_chat if @screens[:chat].chat_focused
+      @hud_focused = true
+      children = hud_children
+      if children.any?
+        @hud_child_index = 0
+        @hud_scroll_offset = @hud_max_scroll
+      end
+    end
+
+    # Returns keyboard focus from the HUD pane and exits child navigation.
+    #
+    # @return [void]
+    def unfocus_hud
+      @hud_focused = false
+      @hud_child_index = nil
+    end
+
+    # Returns the current session's child sessions (sub-agents).
+    #
+    # @return [Array<Hash>] child session hashes, empty when none
+    def hud_children
+      @screens[:chat].session_info[:children] || []
+    end
+
+    # Scrolls the HUD viewport up, clamping at the top.
+    #
+    # @param lines [Integer] number of lines to scroll
+    # @return [void]
+    def scroll_hud_up(lines)
+      @hud_scroll_offset = [@hud_scroll_offset - lines, 0].max
+    end
+
+    # Scrolls the HUD viewport down, clamping at max_scroll.
+    #
+    # @param lines [Integer] number of lines to scroll
+    # @return [void]
+    def scroll_hud_down(lines)
+      @hud_scroll_offset = [@hud_scroll_offset + lines, @hud_max_scroll].min
+    end
+
     def handle_event(event)
       return nil if event.none?
       return :quit if event.ctrl_c?
@@ -422,6 +729,8 @@ module TUI
         handle_view_mode_picker(event)
       elsif @command_mode
         handle_command_mode(event)
+      elsif @hud_focused
+        handle_hud_focused_event(event)
       else
         handle_normal_mode(event)
       end
@@ -442,6 +751,11 @@ module TUI
         return nil
       end
 
+      if event.right? && @hud_visible
+        focus_hud
+        return nil
+      end
+
       action = COMMAND_KEYS[event.code]
       case action
       when :quit
@@ -451,6 +765,7 @@ module TUI
         nil
       when :toggle_hud
         @hud_visible = !@hud_visible
+        unfocus_hud if !@hud_visible
         nil
       when :new_session
         @screens[:chat].new_session
@@ -466,7 +781,13 @@ module TUI
     end
 
     def handle_normal_mode(event)
-      if event.mouse? || event.paste?
+      if event.paste?
+        delegate_to_screen(event)
+        return nil
+      end
+
+      if event.mouse?
+        return nil if route_mouse_to_hud(event)
         delegate_to_screen(event)
         return nil
       end
@@ -497,6 +818,95 @@ module TUI
       nil
     end
 
+    # Handles keyboard events when the HUD pane has focus.
+    # When a child is selected (child navigation mode), arrow keys move
+    # between sub-agents and Enter switches to the selected session.
+    # Otherwise, arrow keys and Page Up/Down scroll the HUD content.
+    # Escape and Ctrl+A always exit HUD focus.
+    def handle_hud_focused_event(event)
+      return nil if event.none?
+      return :quit if event.ctrl_c?
+
+      if event.mouse?
+        return nil if route_mouse_to_hud(event)
+        delegate_to_screen(event)
+        return nil
+      end
+
+      return nil unless event.key?
+
+      if event.esc? || ctrl_a?(event)
+        unfocus_hud
+        return nil
+      end
+
+      if @hud_child_index
+        handle_hud_child_navigation(event)
+      else
+        handle_hud_scroll(event)
+      end
+      nil
+    end
+
+    # Navigates between sub-agent entries in the HUD.
+    # Up/Down move selection, Enter switches to the selected session,
+    # Left exits child navigation back to scroll mode.
+    def handle_hud_child_navigation(event)
+      children = hud_children
+      return if children.empty?
+
+      if event.up?
+        @hud_child_index = [@hud_child_index - 1, 0].max
+      elsif event.down?
+        @hud_child_index = [@hud_child_index + 1, children.size - 1].min
+      elsif event.left?
+        @hud_child_index = nil
+      elsif event.enter?
+        child = children[@hud_child_index]
+        @screens[:chat].switch_session(child["id"]) if child
+        unfocus_hud
+      end
+    end
+
+    # Scrolls the HUD viewport with arrow/page keys.
+    def handle_hud_scroll(event)
+      if event.up?
+        scroll_hud_up(Settings.hud_scroll_step)
+      elsif event.down?
+        scroll_hud_down(Settings.hud_scroll_step)
+      elsif event.page_up?
+        scroll_hud_up(@hud_visible_height)
+      elsif event.page_down?
+        scroll_hud_down(@hud_visible_height)
+      elsif event.home?
+        scroll_hud_up(@hud_max_scroll)
+      elsif event.end?
+        scroll_hud_down(@hud_max_scroll)
+      end
+    end
+
+    # Routes mouse scroll events to the HUD when the cursor is over the HUD area.
+    # @return [Boolean] true if the event was handled by the HUD
+    def route_mouse_to_hud(event)
+      return false if !@hud_visible || !@hud_content_area
+      return false unless mouse_over_hud?(event)
+      return false unless event.scroll_up? || event.scroll_down?
+
+      if event.scroll_up?
+        scroll_hud_up(Settings.hud_mouse_scroll_step)
+      else
+        scroll_hud_down(Settings.hud_mouse_scroll_step)
+      end
+      true
+    end
+
+    # Checks whether a mouse event's coordinates fall within the HUD content area.
+    def mouse_over_hud?(event)
+      area = @hud_content_area
+      event.x >= area.x && event.x < area.x + area.width &&
+        event.y >= area.y && event.y < area.y + area.height
+    end
+
     # Switches to the parent session when viewing a child (sub-agent) session.
     # No-op if the current session is a root session.
     #
@@ -584,12 +994,10 @@ module TUI
     CHILD_STATUS_DONE = "\u2713"      # ✓
     CHILDREN_ARROW = "\u25B8"         # ▸ shown next to sessions with children
     UNNAMED_SUBAGENT_LABEL = "sub-agent"
-    SESSION_PICKER_PAGE_SIZE = 9
-    SESSION_PICKER_FETCH_LIMIT = 50
     BACK_ARROW = "\u2190"             # ←
 
     # Requests the session list from the brain and opens the picker overlay.
-    # Fetches up to SESSION_PICKER_FETCH_LIMIT sessions for client-side pagination.
+    # Fetches up to Settings.session_picker_fetch_limit sessions for client-side pagination.
     # @return [void]
     def activate_session_picker
       @session_picker_active = true
@@ -597,7 +1005,7 @@ module TUI
       @session_picker_page = 0
       @session_picker_mode = :root
       @session_picker_parent_id = nil
-      @cable_client.list_sessions(limit: SESSION_PICKER_FETCH_LIMIT)
+      @cable_client.list_sessions(limit: Settings.session_picker_fetch_limit)
     end
 
     # Dispatches keyboard events while the session picker overlay is open.
@@ -661,8 +1069,8 @@ module TUI
     # @return [Array<Hash>] visible items for the current page
     def session_picker_visible_items
       all = session_picker_all_items_for_mode
-      start = @session_picker_page * SESSION_PICKER_PAGE_SIZE
-      page = all[start, SESSION_PICKER_PAGE_SIZE] || []
+      start = @session_picker_page * Settings.session_picker_page_size
+      page = all[start, Settings.session_picker_page_size] || []
 
       page.map do |item|
         case @session_picker_mode
@@ -677,13 +1085,13 @@ module TUI
     # @return [Boolean] true when more items exist beyond the current page
     def session_picker_has_more?
       total = session_picker_all_items_for_mode.size
-      ((@session_picker_page + 1) * SESSION_PICKER_PAGE_SIZE) < total
+      ((@session_picker_page + 1) * Settings.session_picker_page_size) < total
     end
 
     # @return [Integer] number of items beyond the current page
     def session_picker_remaining_count
       total = session_picker_all_items_for_mode.size
-      [total - ((@session_picker_page + 1) * SESSION_PICKER_PAGE_SIZE), 0].max
+      [total - ((@session_picker_page + 1) * Settings.session_picker_page_size), 0].max
     end
 
     # Handles Escape in the session picker. In children mode, returns to root.
@@ -760,7 +1168,7 @@ module TUI
 
       if sessions.nil?
         lines = [tui.line(spans: [
-          tui.span(content: "Loading...", style: tui.style(fg: "yellow"))
+          tui.span(content: "Loading...", style: tui.style(fg: Settings.theme_color_warning))
         ])]
       else
         visible = session_picker_visible_items
@@ -778,7 +1186,7 @@ module TUI
 
         if lines.empty?
           lines = [tui.line(spans: [
-            tui.span(content: "No sessions", style: tui.style(fg: "dark_gray"))
+            tui.span(content: "No sessions", style: tui.style(fg: Settings.theme_color_muted))
           ])]
         end
       end
@@ -789,7 +1197,7 @@ module TUI
           title: session_picker_title,
           borders: [:all],
           border_type: :rounded,
-          border_style: {fg: "cyan"}
+          border_style: {fg: Settings.theme_color_info}
         )
       )
       frame.render_widget(picker, area)
@@ -830,11 +1238,11 @@ module TUI
       label = "#{prefix}#{marker}#{arrow}#{display_name} #{count}#{child_info} #{time}"
 
       style = if selected
-        tui.style(fg: "black", bg: "cyan")
+        tui.style(fg: Settings.theme_highlight_fg, bg: Settings.theme_highlight_bg)
       elsif is_current
-        tui.style(fg: "cyan", modifiers: [:bold])
+        tui.style(fg: Settings.theme_color_info, modifiers: [:bold])
       else
-        tui.style(fg: "white")
+        tui.style(fg: Settings.theme_color_text)
       end
 
       [tui.line(spans: [tui.span(content: label, style: style)])]
@@ -855,15 +1263,15 @@ module TUI
       prefix = hotkey ? "[#{hotkey}]" : "   "
       marker = is_current ? "*" : " "
       status = child["processing"] ? CHILD_STATUS_RUNNING : CHILD_STATUS_DONE
-      status_color = child["processing"] ? "yellow" : "green"
+      status_color = child["processing"] ? Settings.theme_color_warning : Settings.theme_color_success
       display_name = child["name"] || UNNAMED_SUBAGENT_LABEL
 
       label = "#{prefix}#{marker}#{status} #{display_name}"
 
       style = if selected
-        tui.style(fg: "black", bg: "cyan")
+        tui.style(fg: Settings.theme_highlight_fg, bg: Settings.theme_highlight_bg)
       elsif is_current
-        tui.style(fg: "cyan", modifiers: [:bold])
+        tui.style(fg: Settings.theme_color_info, modifiers: [:bold])
       else
         tui.style(fg: status_color)
       end
@@ -878,7 +1286,7 @@ module TUI
     def format_load_more_entry(tui)
       remaining = session_picker_remaining_count
       label = "[0]  Load more (#{remaining})"
-      [tui.line(spans: [tui.span(content: label, style: tui.style(fg: "dark_gray"))])]
+      [tui.line(spans: [tui.span(content: label, style: tui.style(fg: Settings.theme_color_muted))])]
     end
 
     # -- View mode picker ----------------------------------------------
@@ -935,7 +1343,7 @@ module TUI
           title: "View Mode",
           borders: [:all],
           border_type: :rounded,
-          border_style: {fg: "cyan"}
+          border_style: {fg: Settings.theme_color_info}
         )
       )
       frame.render_widget(picker, area)
@@ -957,17 +1365,17 @@ module TUI
       prefix = hotkey ? "[#{hotkey}]" : "   "
       marker = is_current ? "*" : " "
 
-      selected_style = tui.style(fg: "black", bg: "cyan")
+      selected_style = tui.style(fg: Settings.theme_highlight_fg, bg: Settings.theme_highlight_bg)
 
       name_style = if selected
         selected_style
       elsif is_current
-        tui.style(fg: "cyan", modifiers: [:bold])
+        tui.style(fg: Settings.theme_color_info, modifiers: [:bold])
       else
-        tui.style(fg: "white")
+        tui.style(fg: Settings.theme_color_text)
       end
 
-      desc_style = selected ? selected_style : tui.style(fg: "dark_gray")
+      desc_style = selected ? selected_style : tui.style(fg: Settings.theme_color_muted)
 
       [
         tui.line(spans: [tui.span(content: "#{prefix}#{marker}#{mode.capitalize}", style: name_style)]),
@@ -1112,9 +1520,9 @@ module TUI
       frame.render_widget(tui.clear, popup_area)
 
       border_color = case @token_setup_status
-      when :success then "green"
-      when :error then "red"
-      else "yellow"
+      when :success then Settings.theme_color_success
+      when :error then Settings.theme_color_error
+      else Settings.theme_color_warning
       end
 
       lines = build_token_setup_lines(tui)
@@ -1143,36 +1551,36 @@ module TUI
       # Status
       status_text, status_color = token_status_display
       lines << tui.line(spans: [
-        tui.span(content: "Status: ", style: tui.style(fg: "dark_gray")),
+        tui.span(content: "Status: ", style: tui.style(fg: Settings.theme_color_muted)),
         tui.span(content: status_text, style: tui.style(fg: status_color, modifiers: [:bold]))
       ])
       lines << tui.line(spans: [tui.span(content: "")])
 
       # Instructions
       lines << tui.line(spans: [
-        tui.span(content: "Run ", style: tui.style(fg: "white")),
-        tui.span(content: "claude setup-token", style: tui.style(fg: "cyan", modifiers: [:bold])),
-        tui.span(content: " to get", style: tui.style(fg: "white"))
+        tui.span(content: "Run ", style: tui.style(fg: Settings.theme_color_text)),
+        tui.span(content: "claude setup-token", style: tui.style(fg: Settings.theme_color_info, modifiers: [:bold])),
+        tui.span(content: " to get", style: tui.style(fg: Settings.theme_color_text))
       ])
       lines << tui.line(spans: [
-        tui.span(content: "your token, then paste it here.", style: tui.style(fg: "white"))
+        tui.span(content: "your token, then paste it here.", style: tui.style(fg: Settings.theme_color_text))
       ])
       lines << tui.line(spans: [tui.span(content: "")])
 
       # Token input
       masked = mask_token(@token_input_buffer.text)
       lines << tui.line(spans: [
-        tui.span(content: "Token:", style: tui.style(fg: "white", modifiers: [:bold]))
+        tui.span(content: "Token:", style: tui.style(fg: Settings.theme_color_text, modifiers: [:bold]))
       ])
       lines << tui.line(spans: [
-        tui.span(content: "> #{masked}", style: tui.style(fg: "white"))
+        tui.span(content: "> #{masked}", style: tui.style(fg: Settings.theme_color_text))
       ])
       lines << tui.line(spans: [tui.span(content: "")])
 
       # Error or success message
       if @token_setup_error
         lines << tui.line(spans: [
-          tui.span(content: @token_setup_error, style: tui.style(fg: "red"))
+          tui.span(content: @token_setup_error, style: tui.style(fg: Settings.theme_color_error))
         ])
         lines << tui.line(spans: [tui.span(content: "")])
       end
@@ -1180,11 +1588,11 @@ module TUI
       if @token_setup_status == :success
         lines << if @token_setup_warning
           tui.line(spans: [
-            tui.span(content: "Token saved (API unavailable, validation skipped)", style: tui.style(fg: "yellow", modifiers: [:bold]))
+            tui.span(content: "Token saved (API unavailable, validation skipped)", style: tui.style(fg: Settings.theme_color_warning, modifiers: [:bold]))
           ])
         else
           tui.line(spans: [
-            tui.span(content: "Token saved and validated!", style: tui.style(fg: "green", modifiers: [:bold]))
+            tui.span(content: "Token saved and validated!", style: tui.style(fg: Settings.theme_color_success, modifiers: [:bold]))
           ])
         end
         lines << tui.line(spans: [tui.span(content: "")])
@@ -1197,7 +1605,7 @@ module TUI
       else "[Enter] Save  [Esc] Cancel"
       end
       lines << tui.line(spans: [
-        tui.span(content: hint, style: tui.style(fg: "dark_gray"))
+        tui.span(content: hint, style: tui.style(fg: Settings.theme_color_muted))
       ])
 
       lines
@@ -1207,31 +1615,31 @@ module TUI
     def token_status_display
       case @token_setup_status
       when :success
-        @token_setup_warning ? ["Saved (unverified)", "yellow"] : ["Valid", "green"]
+        @token_setup_warning ? ["Saved (unverified)", Settings.theme_color_warning] : ["Valid", Settings.theme_color_success]
       when :validating
-        ["Validating...", "yellow"]
+        ["Validating...", Settings.theme_color_warning]
       when :error
-        ["Invalid", "red"]
+        ["Invalid", Settings.theme_color_error]
       else
         if @token_input_buffer.text.empty?
-          ["Not configured", "dark_gray"]
+          ["Not configured", Settings.theme_color_muted]
         else
-          ["Ready to save", "cyan"]
+          ["Ready to save", Settings.theme_color_info]
         end
       end
     end
 
-    # Masks an Anthropic token for display: shows the first TOKEN_MASK_VISIBLE
+    # Masks an Anthropic token for display: shows the first Settings.token_dialog_mask_visible
     # characters (the prefix) and replaces the rest with stars.
     #
     # @param token [String] raw token text
     # @return [String] masked display text
     def mask_token(token)
       return "" if token.empty?
-      return token if token.length <= TOKEN_MASK_VISIBLE
+      return token if token.length <= Settings.token_dialog_mask_visible
 
-      visible = token[0...TOKEN_MASK_VISIBLE]
-      hidden_count = [token.length - TOKEN_MASK_VISIBLE, TOKEN_MASK_STARS].min
+      visible = token[0...Settings.token_dialog_mask_visible]
+      hidden_count = [token.length - Settings.token_dialog_mask_visible, Settings.token_dialog_mask_stars].min
       "#{visible}#{"*" * hidden_count}..."
     end
 
@@ -1269,7 +1677,7 @@ module TUI
     # @param area [RatatuiRuby::Rect] full terminal area
     # @return [RatatuiRuby::Rect] centered popup area
     def centered_popup_area(tui, area)
-      popup_height = [POPUP_HEIGHT, area.height - 2].min
+      popup_height = [Settings.token_dialog_popup_height, area.height - 2].min
       v_margin = [(area.height - popup_height) / 2, 0].max
 
       _, center_v, _ = tui.split(
@@ -1282,7 +1690,7 @@ module TUI
         ]
       )
 
-      popup_width = (area.width * 60 / 100).clamp(POPUP_MIN_WIDTH, area.width - 2)
+      popup_width = (area.width * 60 / 100).clamp(Settings.token_dialog_popup_min_width, area.width - 2)
       h_margin = [(area.width - popup_width) / 2, 0].max
 
       _, center, _ = tui.split(
@@ -1362,18 +1770,18 @@ module TUI
     def stop_terminal_watchdog
       return unless @watchdog_thread
 
-      @watchdog_thread.join(WATCHDOG_SHUTDOWN_TIMEOUT)
+      @watchdog_thread.join(Settings.terminal_shutdown_timeout)
       @watchdog_thread.kill if @watchdog_thread.alive?
       @watchdog_thread = nil
     end
 
-    # Opens {CONTROLLING_TERMINAL} every {TERMINAL_CHECK_INTERVAL} seconds.
+    # Opens {CONTROLLING_TERMINAL} every +terminal.check_interval+ seconds.
     # File.open (not File.stat) is required because stat only checks the
     # filesystem entry which always exists; open actually probes the device.
     # When the terminal disappears, calls {#handle_terminal_loss}.
     # Exits silently in non-TTY environments (CI, test suites).
     # @see CONTROLLING_TERMINAL
-    # @see TERMINAL_CHECK_INTERVAL
+    # @see TUI::Settings.terminal_check_interval
     # @return [void]
     def terminal_watchdog_loop
       # Empty block triggers open syscall to probe the device, then immediately closes the FD.
@@ -1386,7 +1794,7 @@ module TUI
         rescue Errno::ENXIO, Errno::EIO, Errno::ENOENT
           handle_terminal_loss
         end
-        sleep TERMINAL_CHECK_INTERVAL
+        sleep Settings.terminal_check_interval
       end
     rescue SystemCallError
       # No controlling terminal — nothing to watch (ENXIO, EIO, ENOENT, EACCES, etc.)