@pellux/goodvibes-agent 1.5.5 → 1.5.6

package/src/renderer/terminal-escapes.ts

@@ -0,0 +1,24 @@
+/**
+ * terminal-escapes — the raw control sequences main.ts writes to enter/leave the
+ * TUI's terminal mode (alt screen, mouse, cursor, keyboard-extension, paste, and
+ * focus reporting). Extracted as plain constants so callers share one definition
+ * and the entry file stays within the source-file line-count gate.
+ *
+ * FOCUS_ENABLE / FOCUS_DISABLE (DECSET ?1004) are the shared home for the OS
+ * window-focus reporting mode consumed by the focus-tracker (W4-R3): R3 imports
+ * FOCUS_ENABLE from here rather than redefining it.
+ */
+
+export const ALT_SCREEN_ENTER = '\x1b[?1049h';
+export const ALT_SCREEN_EXIT = '\x1b[?1049l';
+export const MOUSE_ENABLE = '\x1b[?1000h\x1b[?1002h\x1b[?1006h';
+export const MOUSE_DISABLE = '\x1b[?1006l\x1b[?1002l\x1b[?1000l';
+export const CURSOR_HIDE = '\x1b[?25l';
+export const CURSOR_SHOW = '\x1b[?25h';
+export const CLEAR_SCREEN = '\x1b[2J\x1b[3J\x1b[H';
+export const KEYBOARD_EXT_ENABLE = '\x1b[>4;2m' + '\x1b[?1u';
+export const KEYBOARD_EXT_DISABLE = '\x1b[>4;0m' + '\x1b[?1l';
+export const PASTE_ENABLE = '\x1b[?2004h';
+export const PASTE_DISABLE = '\x1b[?2004l';
+export const FOCUS_ENABLE = '\x1b[?1004h';
+export const FOCUS_DISABLE = '\x1b[?1004l';

package/src/renderer/theme-mode-config.ts

@@ -0,0 +1,87 @@
+/**
+ * theme-mode-config — the appearance/theme-mode preference surface (W4-R4).
+ *
+ * The preference lives at the config key `display.themeMode` (auto | dark |
+ * light, default auto). It is stored under the existing SDK `display` section
+ * (which exists in DEFAULT_CONFIG) as a TUI-local synthetic setting — no SDK
+ * schema change — the same pattern the config already uses for other
+ * display.* toggles.
+ *
+ * DIVERGENCE FROM THE W4 BRIEF (recorded): the brief listed theme-mode-config.ts
+ * as the NEW home for the config-read helpers, but W4-R2 landed FIRST and
+ * inlined resolveConfiguredThemeMode / coerceThemeModeSetting /
+ * THEME_MODE_CONFIG_KEY / ThemeModeSetting into terminal-bg-probe.ts (so R2
+ * could ship the probe before this file existed). Rather than duplicate those
+ * (which would let the two copies drift — the exact failure S1 exists to
+ * prevent), this module RE-EXPORTS them from terminal-bg-probe as the single
+ * source, and adds only the settings-modal-facing metadata (the value list,
+ * default, and human description) that R2 did not need.
+ *
+ * Deliberately free of terminal/probe state so the settings-modal data layer
+ * can import it without pulling in the stateful probe class.
+ */
+
+import { setActiveThemeMode, type ThemeModeSetting } from './theme.ts';
+import { coerceThemeModeSetting, THEME_MODE_CONFIG_KEY, THEME_MODE_DEFAULT } from './terminal-bg-probe.ts';
+import type { ConfigKey, ConfigSetting } from '@pellux/goodvibes-sdk/platform/config';
+
+export {
+  THEME_MODE_CONFIG_KEY,
+  THEME_MODE_DEFAULT,
+  coerceThemeModeSetting,
+  resolveConfiguredThemeMode,
+} from './terminal-bg-probe.ts';
+
+/** The three valid preference values, in settings-cycle order. */
+export const THEME_MODE_VALUES: readonly ThemeModeSetting[] = ['auto', 'dark', 'light'];
+
+/**
+ * Human-facing description for the settings-modal entry. States the honest
+ * timing contract: forced modes apply on the next full paint immediately;
+ * `auto` only re-probes at startup, so switching TO auto takes effect next
+ * launch.
+ */
+export const THEME_MODE_DESCRIPTION =
+  'Terminal background theme. auto probes the terminal background colour once at '
+  + 'startup (OSC 11) and picks light or dark; dark/light force a fixed theme. '
+  + 'Forced modes take effect immediately; auto is only evaluated at startup, so '
+  + 'selecting auto takes effect on the next launch. Unreadable/unsupported '
+  + 'terminals fall back to dark. Scope (honest): transcript markdown, tool-call '
+  + 'and system-message accents, and the header/footer/thinking chrome all flip '
+  + 'with this setting; only the background colour itself follows your terminal.';
+
+/**
+ * The synthetic ConfigSetting descriptor for display.themeMode (the TUI's
+ * settings-modal-data.ts pattern). Agent-local — the key is NOT in the SDK
+ * ConfigKey union, so it is cast; safe because the `display` section exists in
+ * DEFAULT_CONFIG and ConfigManager.setDynamic/get round-trip unknown fields
+ * under an existing section. Injected into the settings modal's display group
+ * so the preference is discoverable and cycles like any other enum setting.
+ */
+export const THEME_MODE_SYNTHETIC_SETTING: ConfigSetting = {
+  key: THEME_MODE_CONFIG_KEY as ConfigKey,
+  type: 'enum',
+  default: THEME_MODE_DEFAULT,
+  enumValues: [...THEME_MODE_VALUES],
+  description: THEME_MODE_DESCRIPTION,
+};
+
+/**
+ * Apply a display.themeMode settings change with the honest timing contract:
+ * forced dark/light flip the active mode NOW (caller passes its full-repaint
+ * hook); auto is only evaluated by the startup probe, so it takes effect on the
+ * next launch — the returned message states which happened. Called by the
+ * settings-modal onSettingApplied hook (ui-openers).
+ */
+export function applyThemeModeSettingChange(
+  value: unknown,
+  requestFullRepaint?: () => void,
+): { message: string } {
+  const next = coerceThemeModeSetting(value);
+  if (next === 'dark' || next === 'light') {
+    setActiveThemeMode(next);
+    requestFullRepaint?.();
+    return { message: `Theme mode: ${next} (applied now)` };
+  }
+  return { message: 'Theme mode: auto (probes terminal on next startup)' };
+}

package/src/renderer/theme.ts

@@ -0,0 +1,241 @@
+/**
+ * theme.ts — Semantic colour token layer (W4-R4 port of the TUI theme system).
+ *
+ * Two token layers, resolved per background mode:
+ *
+ *   - ThemeTokens (transcript): every colour decision in the markdown /
+ *     conversation-rendering / tool-call / system-message pipeline. Agent-local
+ *     (the SDK presentation contract hoisted only the CHROME tone table, not
+ *     these transcript-semantic tokens). Read live per render via activeTheme()
+ *     so a dark→light repaint re-resolves with no module reload.
+ *
+ *   - UiToneTokens (chrome): the panel/modal/overlay/header/footer/thinking tone
+ *     table. This IS the SDK presentation contract — resolveUiTones() / and
+ *     activeUiTones() compose the ThemeMode dimension over the SDK's
+ *     resolveTones(), so the agent never mints its own light chrome variant.
+ *
+ * Dark mode values are the historically used colours. Light mode values exist
+ * for correctness parity and are consumed once the terminal-bg-probe
+ * (terminal-escapes / OSC 11, W4-R2) resolves the mode and setActiveThemeMode
+ * is called. Callers that do not yet have mode detection get 'dark' — the safe
+ * default (activeMode starts dark).
+ *
+ * IMPORTANT: inline code has NO background token. The bg:#1a1a1a hardcode that
+ * previously existed caused a near-black box on light terminals. Differentiate
+ * inline code via inlineCodeFg + bold only; bg inherits the terminal.
+ */
+
+import { UI_TONES } from './ui-primitives.ts';
+import { resolveTones, type ThemeMode, type ToneTokens } from '@pellux/goodvibes-sdk/platform/presentation';
+
+/** Background mode — dark is the safe default until the bg-probe resolves. */
+export type { ThemeMode };
+
+/** Resolved semantic colour tokens (concrete hex strings or ANSI-256 indices). */
+export interface ThemeTokens {
+  /** H1 heading foreground + table header accent */
+  heading1: string;
+  /** H2 heading foreground */
+  heading2: string;
+  /** H3 heading foreground (ANSI-256 — falls back to nearest on ansi256 terminals) */
+  heading3: string;
+  /** Inline code foreground (bold is applied separately by caller) */
+  inlineCodeFg: string;
+  /** Hyperlink and bare-URL foreground */
+  link: string;
+  /** Non-current search match background */
+  searchMatchBg: string;
+  /** Non-current search match foreground */
+  searchMatchFg: string;
+  /** Current (focused) search match background */
+  searchCurrentBg: string;
+  /** Current (focused) search match foreground */
+  searchCurrentFg: string;
+  /** Strikethrough / muted text foreground */
+  strikethrough: string;
+  /** Blockquote / dim text foreground */
+  blockquote: string;
+  /** Assistant event-line marker + label accent */
+  assistantHeader: string;
+  /** Reasoning / thinking block accent */
+  reasoningAccent: string;
+  /** Tool call / active status accent (also diff/tool result label) */
+  toolAccent: string;
+  /** Collapsed-fragment body background (tool result preview bg) */
+  collapsedBodyBg: string;
+  /** Checked task-list checkbox foreground (✓ in green) */
+  checkboxChecked: string;
+  /** Error / cancelled message bar background */
+  errorBarBg: string;
+  /** Model name / provider dim label foreground */
+  modelNameDim: string;
+  /** Tool name foreground in tool-result event line */
+  toolNameFg: string;
+  /** Diff block accent — marker, label, and collapsed-prefix foreground */
+  diffAccent: string;
+}
+
+// ---------------------------------------------------------------------------
+// Dark palette (byte-identical to the agent's prior static reads).
+// ---------------------------------------------------------------------------
+const DARK: ThemeTokens = {
+  heading1:        '#00ffff',
+  heading2:        '#00ffff',
+  heading3:        '111',
+  inlineCodeFg:    '#ffcc00',
+  link:            '#00aaff',
+  searchMatchBg:   '#806600',
+  searchMatchFg:   '#ffffff',
+  searchCurrentBg: '#ffff00',
+  searchCurrentFg: '#000000',
+  strikethrough:   '244',
+  blockquote:      '244',
+  assistantHeader: UI_TONES.accent.control,
+  reasoningAccent: UI_TONES.state.reasoning,
+  toolAccent:      UI_TONES.state.info,
+  collapsedBodyBg: '#1a1a1a',
+  checkboxChecked: '#22c55e',
+  errorBarBg:      '#3a1a1a',
+  modelNameDim:    '#94a3b8',
+  toolNameFg:      '#e2e8f0',
+  diffAccent:      '#f59e0b',
+};
+
+// ---------------------------------------------------------------------------
+// Light palette — dark-on-light legibility (contrast ratios against #ffffff):
+//   heading1/2:      Deep teal (#0077aa) — readable on white/cream terminals
+//   heading3:        ANSI-256 24 (dark cyan) — the light equivalent of 111
+//   inlineCodeFg:    Dark orange (#b45309) — distinguishable without a box bg
+//   link:            Standard blue (#0055cc) — browser-link convention
+//   searchMatchBg:   Muted yellow (#ffe066) on black fg — visible on light bg
+//   searchCurrentBg: Strong amber (#f59e0b) — current match is more vivid
+//   blockquote:      Dim blue-gray (ANSI-256 67)
+//   assistantHeader: Dark cyan (#0e7490)
+//   reasoningAccent: Dark purple (#7c3aed)
+//   toolAccent:      Dark sky (#0369a1)
+//   collapsedBodyBg: Very light gray (#f3f4f6)
+//   checkboxChecked: Forest green (#15803d) — ~5.2:1 on #fff
+//   errorBarBg:      Soft rose (#fee2e2) — legible text on top
+//   modelNameDim:    Slate-500 (#64748b) — ~4.6:1 on #fff
+//   toolNameFg:      Slate-800 (#334155) — strong enough for tool names
+//   diffAccent:      Amber-700 (#b45309) — ~4.7:1 on #fff
+// ---------------------------------------------------------------------------
+const LIGHT: ThemeTokens = {
+  heading1:        '#0077aa',
+  heading2:        '#0077aa',
+  heading3:        '24',
+  inlineCodeFg:    '#b45309',
+  link:            '#0055cc',
+  searchMatchBg:   '#ffe066',
+  searchMatchFg:   '#000000',
+  searchCurrentBg: '#f59e0b',
+  searchCurrentFg: '#000000',
+  strikethrough:   '244',
+  blockquote:      '67',
+  assistantHeader: '#0e7490',
+  reasoningAccent: '#7c3aed',
+  toolAccent:      '#0369a1',
+  collapsedBodyBg: '#f3f4f6',
+  checkboxChecked: '#15803d',
+  errorBarBg:      '#fee2e2',
+  modelNameDim:    '#64748b',
+  toolNameFg:      '#334155',
+  diffAccent:      '#b45309',
+};
+
+Object.freeze(DARK);
+Object.freeze(LIGHT);
+
+/**
+ * resolveTheme — Return the transcript token set for the given background mode.
+ * The returned object is frozen; callers should not mutate it.
+ */
+export function resolveTheme(mode: ThemeMode): Readonly<ThemeTokens> {
+  return mode === 'light' ? LIGHT : DARK;
+}
+
+/** Default dark-mode token set, exported for convenience. Frozen. */
+export const DARK_THEME: Readonly<ThemeTokens> = DARK;
+
+// ---------------------------------------------------------------------------
+// Chrome tokens (UiToneTokens) — the SDK presentation contract, mode-resolved.
+//
+// The dark table is the SDK's TONE_TOKENS (re-exported here as UI_TONES); the
+// light variant is the SDK's resolveTones('light'). The agent does NOT mint its
+// own light chrome variant — that duplication is exactly what W4-S1 ended.
+// ---------------------------------------------------------------------------
+
+/** The chrome tone-token shape (the SDK ToneTokens contract). */
+export type UiToneTokens = ToneTokens;
+
+/**
+ * resolveUiTones — chrome token set for the given mode. Single read path;
+ * 'dark' is byte-identical to the UI_TONES constant (same SDK object).
+ * Prefer activeUiTones() at call sites.
+ */
+export function resolveUiTones(mode: ThemeMode): Readonly<UiToneTokens> {
+  return resolveTones(mode);
+}
+
+// ===========================================================================
+// Active-mode runtime.
+//
+// The mode is decided ONCE at startup — from appearance config
+// (display.themeMode forced dark/light) or the terminal-background probe
+// (auto) — and is then stable for the session. Transcript tokens (activeTheme)
+// and chrome tokens (activeUiTones) are both read live per render, so a
+// dark→light repaint (auto mode, light wins within the probe window)
+// re-resolves without any module reload.
+//
+// registerThemeRefresh exists for owners that BAKE tone values into
+// module-level constants (which cannot be re-resolved per call). Nothing
+// registers this wave — the agent's opaque panel palettes (polish.ts
+// DEFAULT_PANEL_PALETTE and the modal/overlay/fullscreen surfaces built from
+// it) paint OPAQUE dark boxes whose fg/state tokens stay dark in both modes, so
+// they need no rebuild for dark parity (the opaque-surface trio deferral). The
+// hook is kept at parity with the TUI so those surfaces can register when full
+// light-chrome coherence lands.
+// ===========================================================================
+
+/** User-facing appearance preference: auto probes the terminal; dark/light force. */
+export type ThemeModeSetting = 'auto' | ThemeMode;
+
+/** The resolved mode in effect for the current session. Dark is the safe default. */
+let activeMode: ThemeMode = 'dark';
+
+/** In-place palette rebuilders, run (in registration order) on every mode flip. */
+const themeRefreshers: Array<() => void> = [];
+
+/** The active mode, for diagnostics / tests. */
+export function getActiveThemeMode(): ThemeMode {
+  return activeMode;
+}
+
+/**
+ * Register an in-place palette rebuild to run whenever the active mode changes.
+ * Base-palette owners register at their own module-eval time (before any
+ * derived palette), so refreshers run base-first.
+ */
+export function registerThemeRefresh(rebuild: () => void): void {
+  themeRefreshers.push(rebuild);
+}
+
+/**
+ * Set the active background mode and rebuild every registered chrome palette in
+ * place. Idempotent and reversible. Callers: startup (forced mode or probe
+ * result, wired via installBackgroundThemeProbe's applyThemeMode injection).
+ */
+export function setActiveThemeMode(mode: ThemeMode): void {
+  activeMode = mode;
+  for (const rebuild of themeRefreshers) rebuild();
+}
+
+/** Transcript tokens for the active mode — read live, per render. */
+export function activeTheme(): Readonly<ThemeTokens> {
+  return resolveTheme(activeMode);
+}
+
+/** Chrome tokens for the active mode — read live, per render. */
+export function activeUiTones(): Readonly<UiToneTokens> {
+  return resolveUiTones(activeMode);
+}

package/src/renderer/thinking.ts

@@ -1,14 +1,23 @@
 import { type Line } from '../types/grid.ts';
-import { BORDERS, COLORS } from './layout.ts';
+import { BORDERS } from './layout.ts';
 import { renderConversationNotice } from './conversation-surface.ts';
+import { activeUiTones } from './theme.ts';
 
 export function renderThinkingBlock(text: string, width: number): Line[] {
+  // Thinking notices paint the ▌ marker and italic body on the TRANSPARENT
+  // terminal background (renderConversationNotice passes no bodyBg), so both
+  // colours resolve per-render through activeUiTones() to stay legible on a
+  // light terminal. In dark mode the accent adopts the shared reasoning purple
+  // (state.reasoning) and the body adopts chrome.faint (== fg.dim) — a small,
+  // deliberate convergence to the reference tokens from the agent's prior local
+  // BORDERS.THINKING.color / COLORS.DIM_TEXT (see the W4-R4 visible-changes note).
+  const t = activeUiTones();
   return renderConversationNotice(
     text,
     width,
     {
-      accent: BORDERS.THINKING.color,
-      text: COLORS.DIM_TEXT,
+      accent: t.state.reasoning,
+      text: t.chrome.faint,
       dim: true,
       italic: true,
     },

package/src/renderer/tool-call.ts

@@ -4,6 +4,7 @@ import { getDisplayWidth, truncateDisplay } from '../utils/terminal-width.ts';
 import type { ToolCall } from '@pellux/goodvibes-sdk/platform/types';
 import { stripDangerousAnsi } from './ansi-sanitize.ts';
 import { friendlyToolLabel } from './tool-labels.ts';
+import { activeUiTones } from './theme.ts';
 
 const TOOL_NAME_MIN_WIDTH = 8;
 const TOOL_NAME_MAX_WIDTH = 30;
@@ -55,6 +56,9 @@ function buildLeftSegments(
 ): Array<{ text: string; fg: string; bold?: boolean; dim?: boolean }> {
   if (leftBudget <= 0) return [];
 
+  // Read live tones so the tool-call row is legible in light mode. Dark values
+  // are byte-identical (t.fg.primary == #e2e8f0, t.chrome.bad == #ef4444).
+  const t = activeUiTones();
   const segments: Array<{ text: string; fg: string; bold?: boolean; dim?: boolean }> = [];
   const suffixBudget = suffixText ? Math.min(Math.max(12, Math.floor(leftBudget * 0.3)), 20) : 0;
   const suffixDisplay = suffixBudget > 0 ? truncateDisplay(suffixText, suffixBudget) : '';
@@ -83,14 +87,14 @@ function buildLeftSegments(
     segments.push({ text: toolNameDisplay, fg: '#00ffcc', bold: true });
   }
   if (keyArgDisplay) {
-    segments.push({ text: '  ', fg: '#e2e8f0' });
+    segments.push({ text: '  ', fg: t.fg.primary });
     segments.push({ text: keyArgDisplay, fg: '252' });
   }
   if (suffixDisplay) {
-    segments.push({ text: '  ', fg: '#e2e8f0' });
+    segments.push({ text: '  ', fg: t.fg.primary });
     segments.push({
       text: suffixDisplay,
-      fg: suffixText.startsWith('- ') ? '#ef4444' : '244',
+      fg: suffixText.startsWith('- ') ? t.chrome.bad : '244',
       dim: true,
     });
   }

package/src/renderer/ui-factory.ts

@@ -4,11 +4,34 @@ import { VERSION } from '../version.ts';
 import { fitDisplay, getDisplayWidth, truncateDisplay, wrapText, interpolateColor } from '../utils/terminal-width.ts';
 import { renderConversationFragment, renderConversationStatusLine, type ConversationStatusSegment } from './conversation-surface.ts';
 import { GLYPHS } from './ui-primitives.ts';
+import { activeUiTones } from './theme.ts';
+import {
+  THINKING_PHRASES,
+  waitingPhrase,
+  type WaitingState,
+} from '@pellux/goodvibes-sdk/platform/presentation';
 
 /** Number of frames before the animated gradient completes one full cycle. */
 const GRADIENT_CYCLE_FRAMES = 50;
 /** Number of frames before rotating to the next thinking phrase (~30 seconds at 80ms/frame). */
 const PHRASE_ROTATION_FRAMES = 375;
+/**
+ * Silence threshold before the whimsical phrase rotation freezes and an honest
+ * label (Waiting for model Ns / Stalled Ns) takes over. Matches the TUI.
+ */
+const THINKING_STALL_FREEZE_MS = 2_500;
+
+/**
+ * Per-turn stall signal derived from stream metrics — computed from the last
+ * delta clock every render (not from any event), so it degrades gracefully with
+ * zero new SDK events. `reconnect` is set only when the transport surfaces retry
+ * counters (the agent's SDK orchestrator does not today — see computeStallInfo).
+ */
+export interface ThinkingStallInfo {
+  /** Ms since the last output-token advance (or the turn start if none yet). */
+  readonly msSinceLastDelta: number;
+  readonly reconnect?: { readonly attempt: number; readonly maxAttempts: number };
+}
 
 /** Format a number: up to 999, then 1.0k, 1.0M, 1.0B, 1.0T */
 function fmtNum(n: number): string {
@@ -236,9 +259,12 @@ export class UIFactory {
     if (inp > 0 || out > 0) {
       statusTokens.push({ text: `↑${fmtNum(inp)} ↓${fmtNum(out)}`, fg: '240' });
     }
-    if (composerPendingRisk === 'approval-wait') {
-      statusTokens.push({ text: 'waiting for your approval', fg: '#f59e0b', bold: true });
-    }
+    // W4-R4: the disconnected footer 'waiting for your approval' token is retired
+    // here — the approval-wait truth now lives in the unified waiting state of the
+    // thinking indicator (createThinkingFragment's approvalPending path) and in the
+    // permission prompt itself, so the footer no longer carries a separate,
+    // easily-desynced copy. composerPendingRisk stays in the signature for the
+    // composer flags row; it just no longer mints its own status token.
     const rightNotice = isRecentlyCopied
       ? { text: `copied ${GLYPHS.status.success} `, fg: '81', bold: true }
       : dangerMode
@@ -277,39 +303,69 @@ export class UIFactory {
     return lines;
   }
 
-  /** Rotating thinking phrases — vaporwave / good vibes themed. */
-  private static readonly THINKING_PHRASES = [
-    'Thinking...',
-    'Vibing...',
-    'Manifesting...',
-    'Channeling energy...',
-    'Tuning frequencies...',
-    'Riding the wave...',
-    'Aligning chakras...',
-    'Entering flow state...',
-    'Consulting the void...',
-    'Absorbing aesthetics...',
-    'Synthesizing vibes...',
-    'Transcending...',
-    'Dreaming in neon...',
-    'Parsing the cosmos...',
-    'Loading good vibes...',
-    'Meditating...',
-    'Catching a vibe...',
-    'Harmonizing...',
-    'Feeling it...',
-    'In the zone...',
-  ];
+  /**
+   * Per-frame stall info from stream metrics — computed from a last-delta clock
+   * every render (not from any event) so it degrades gracefully with zero new
+   * SDK events. Undefined until a delta clock exists this turn. Renderer-local
+   * by design (per the S1 decision record: the SDK owns state->wording; deriving
+   * WHICH state applies stays with each renderer's own stream-metrics shape).
+   */
+  public static computeStallInfo(
+    lastDeltaAtMs: number | undefined,
+    reconnectAttempt: number | undefined,
+    reconnectMaxAttempts: number | undefined,
+    nowMs: number,
+  ): ThinkingStallInfo | undefined {
+    if (lastDeltaAtMs === undefined) return undefined;
+    const reconnect = reconnectAttempt !== undefined && reconnectMaxAttempts !== undefined
+      ? { attempt: reconnectAttempt, maxAttempts: reconnectMaxAttempts }
+      : undefined;
+    return { msSinceLastDelta: nowMs - lastDeltaAtMs, reconnect };
+  }
 
-  /** Gradient colors for thinking text — cyan to purple (matches splash). */
-  private static readonly THINK_GRADIENT_START = '#00ffff';
-  private static readonly THINK_GRADIENT_END = '#d000ff';
+  /**
+   * Render-loop stall decision: suppress stall detection entirely while a tool
+   * is actively executing. The last-delta clock only advances on output-token
+   * deltas and is never advanced during tool execution (the model isn't
+   * producing tokens then), so without this gate any tool call longer than
+   * THINKING_STALL_FREEZE_MS would print "Stalled Ns..." above a ticking tool
+   * row — a false positive. Genuine no-delta silence while waiting on the
+   * provider (including pre-first-token) still stall-detects here, since no tool
+   * is active then — the honest stall case this indicator exists for.
+   */
+  public static computeRenderStallInfo(
+    metrics: { toolActive: boolean; lastDeltaAtMs: number | undefined; nowMs: number },
+  ): ThinkingStallInfo | undefined {
+    return metrics.toolActive
+      ? undefined
+      : this.computeStallInfo(metrics.lastDeltaAtMs, undefined, undefined, metrics.nowMs);
+  }
 
-  public static createThinkingFragment(width: number, spinner: string, frame: number = 0, tokenSpeed?: number, toolPreview?: string, inputTokens?: number, outputTokens?: number): Line[] {
-    // Rotate phrase every ~30 seconds (frame ticks at 80ms, so ~375 frames)
-    const phraseIndex = Math.floor(frame / PHRASE_ROTATION_FRAMES) % this.THINKING_PHRASES.length;
-    const phrase = this.THINKING_PHRASES[phraseIndex];
-    const speedSuffix = (tokenSpeed !== undefined && tokenSpeed > 0) ? ` (${Math.round(tokenSpeed)} tok/s)` : '';
+  public static createThinkingFragment(width: number, spinner: string, frame: number = 0, tokenSpeed?: number, toolPreview?: string, inputTokens?: number, outputTokens?: number, stallInfo?: ThinkingStallInfo, approvalPending?: boolean): Line[] {
+    // Live thinking row paints on the transparent terminal bg → read the
+    // mode-resolved chrome tones per render (gradient/brand flip in light mode).
+    const tones = activeUiTones();
+    // Decide WHICH honest waiting state applies (renderer-local), then defer the
+    // exact wording to the SDK presentation contract's waitingPhrase(). Precedence
+    // matches the contract: approval > reconnecting > pre-first-token > stalled >
+    // thinking. Pre-first-token silence reads "Waiting for model Ns..." (blame-free
+    // for reasoning models that think before emitting), NOT "Stalled".
+    const isStalled = stallInfo !== undefined && stallInfo.msSinceLastDelta >= THINKING_STALL_FREEZE_MS;
+    let state: WaitingState;
+    if (approvalPending) state = 'approval';
+    else if (stallInfo?.reconnect) state = 'reconnecting';
+    else if (isStalled && (outputTokens ?? 0) === 0) state = 'pre-first-token';
+    else if (isStalled) state = 'stalled';
+    else state = 'thinking';
+    const phrase = waitingPhrase(state, {
+      reconnectAttempt: stallInfo?.reconnect?.attempt,
+      reconnectMaxAttempts: stallInfo?.reconnect?.maxAttempts,
+      msSinceLastDelta: stallInfo?.msSinceLastDelta,
+      frame,
+    });
+    // A tok/s figure next to an approval prompt reads as if the model were still
+    // working — suppress it while waiting on the user.
+    const speedSuffix = (!approvalPending && tokenSpeed !== undefined && tokenSpeed > 0) ? ` (${Math.round(tokenSpeed)} tok/s)` : '';
     const text = `  ${spinner} ${phrase}${speedSuffix} `;
 
     const textWidth = Math.max(1, getDisplayWidth(text) - 1);
@@ -319,7 +375,7 @@ export class UIFactory {
       const gradientPos = raw <= 0.5 ? raw * 2 : (1 - raw) * 2;
       return {
         text: char,
-        fg: interpolateColor(this.THINK_GRADIENT_START, this.THINK_GRADIENT_END, gradientPos),
+        fg: interpolateColor(tones.accent.gradientStart, tones.accent.gradientEnd, gradientPos),
         bold: true,
       };
     });
@@ -327,7 +383,7 @@ export class UIFactory {
       const inTok = inputTokens ?? 0;
       const outTok = outputTokens ?? 0;
       segments.push({ text: ` in ${fmtNum(inTok)} `, fg: '243', dim: true });
-      segments.push({ text: `out ${fmtNum(outTok)}`, fg: '#00ffff' });
+      segments.push({ text: `out ${fmtNum(outTok)}`, fg: tones.accent.brand });
     }
     const line = createEmptyLine(width);
     let col = 1;