@pellux/goodvibes-tui 0.27.0 → 0.29.0

package/src/renderer/modal-factory.ts

@@ -8,7 +8,9 @@ import {
   putOverlayText,
 } from './overlay-box.ts';
 import { getOverlayMaxWidth } from './overlay-viewport.ts';
-import { GLYPHS, UI_TONES } from './ui-primitives.ts';
+import { GLYPHS } from './ui-primitives.ts';
+import { resolveUiTones } from './theme.ts';
+import { HINT_SEPARATOR } from './hint-grammar.ts';
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
@@ -90,19 +92,24 @@ export interface ModalConfig {
 
 // ── Defaults ─────────────────────────────────────────────────────────────────
 
+// DEFAULT_STYLE is built from the mode-resolved chrome tones (resolveUiTones)
+// rather than the static UI_TONES constant — WO-001 single read path. Mode is
+// fixed to 'dark' until the terminal-bg-probe lands.
+const TONES = resolveUiTones('dark');
+
 const DEFAULT_STYLE: Required<ModalStyle> = {
-  titleFg: UI_TONES.fg.primary,
-  borderFg: UI_TONES.fg.dim,
-  hintFg: UI_TONES.fg.muted,
-  selectedFg: UI_TONES.fg.primary,
-  selectedBg: UI_TONES.bg.selected,
-  textFg: UI_TONES.fg.primary,
-  accentFg: UI_TONES.state.info,
-  titleRowFg: UI_TONES.fg.secondary,
-  titleBg: UI_TONES.bg.title,
-  sectionBg: UI_TONES.bg.section,
-  inputBg: UI_TONES.bg.input,
-  surfaceBg: UI_TONES.bg.surface,
+  titleFg: TONES.fg.primary,
+  borderFg: TONES.fg.dim,
+  hintFg: TONES.fg.muted,
+  selectedFg: TONES.fg.primary,
+  selectedBg: TONES.bg.selected,
+  textFg: TONES.fg.primary,
+  accentFg: TONES.state.info,
+  titleRowFg: TONES.fg.secondary,
+  titleBg: TONES.bg.title,
+  sectionBg: TONES.bg.section,
+  inputBg: TONES.bg.input,
+  surfaceBg: TONES.bg.surface,
 };
 
 // ── ModalFactory ─────────────────────────────────────────────────────────────
@@ -182,9 +189,10 @@ export class ModalFactory {
       }
     }
 
-    // Footer / hint bar
+    // Footer / hint bar. Hint segments join with the shared middle-dot grammar
+    // separator (WO-151) so every modal footer reads as one dialect.
     const hintStr = config.hints
-      ? config.hints.join('  ')
+      ? config.hints.join(HINT_SEPARATOR)
       : (config.footer ?? '');
     lines.push(ModalFactory.renderHints(boxW, margin, hintStr, terminalWidth, style));
 

package/src/renderer/model-picker-overlay.ts

@@ -1,5 +1,6 @@
 import { type Line } from '../types/grid.ts';
 import { fitDisplay, getDisplayWidth, truncateDisplay } from '../utils/terminal-width.ts';
+import { abbreviateCount } from '../utils/format-number.ts';
 import type { ModelPickerModal } from '../input/model-picker.ts';
 import { EFFORT_DESCRIPTIONS } from '@pellux/goodvibes-sdk/platform/providers';
 import { getQualityTier, getQualityTierFromScore } from '@pellux/goodvibes-sdk/platform/providers';
@@ -12,12 +13,11 @@ import {
   putOverlayText,
 } from './overlay-box.ts';
 import { getOverlaySurfaceMetrics } from './overlay-viewport.ts';
+import { formatHints, type HintSpec } from './hint-grammar.ts';
 
 /** Format a context window number into a short human-readable string. */
 function fmtContext(n: number): string {
-  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(0)}M`;
-  if (n >= 1000) return `${Math.round(n / 1000)}k`;
-  return String(n);
+  return abbreviateCount(n, { rounding: 'round', decimals: 0 });
 }
 
 /** Title text per picker mode. */
@@ -360,6 +360,12 @@ export function renderModelPickerOverlay(
     putRowText(promptRow, layout.margin + 2, contentW, fitDisplay(`${promptLabel} ${inputDisplay}`, contentW), '#ffffff');
     lines.push(promptRow);
 
+    if (picker.contextCapError) {
+      const errRow = createOverlayContentLine(width, layout, borderFg, DEFAULT_OVERLAY_PALETTE.bodyBg);
+      putRowText(errRow, layout.margin + 2, contentW, fitDisplay(picker.contextCapError, contentW), '#ff6666');
+      lines.push(errRow);
+    }
+
     lines.push(createOverlayContentLine(width, layout, borderFg, DEFAULT_OVERLAY_PALETTE.bodyBg));
 
     const hintText = `Leave blank to use default (current: ${currentCtx}, source: ${provenance})`;
@@ -408,13 +414,26 @@ export function renderModelPickerOverlay(
   const groupByLabel = picker.groupBy ?? 'provider';
   const selectedModel = picker.mode === 'model' ? picker.getSelected() : null;
   const showContextCapHint = selectedModel != null && selectedModel.contextWindowProvenance !== undefined;
-  const hints = picker.mode === 'model'
-    ? showContextCapHint
-      ? `[Up/Down] [Enter] [/] Search [Space] Ctx [Esc] [Tab] Filter: ${filterLabelFooter} [G] Group: ${groupByLabel}`
-      : `[Up/Down] [Enter] [/] Search [Esc] [Tab] Filter: ${filterLabelFooter} [G] Group: ${groupByLabel}`
-    : picker.mode === 'contextCap'
-    ? '[Enter] Confirm  [Esc] Cancel'
-    : '[Up/Down] Nav  [Enter] Select  [Esc] Cancel';
+  let hints: string;
+  if (picker.mode === 'model') {
+    // The model-picker box caps at 72 cols, so the footer stays compact: the
+    // list nav (Up/Down/Enter) is the obvious interaction and lives in the
+    // /shortcuts overlay; the footer prioritizes the stateful controls. The
+    // live filter/group value is folded into each key's verb so it stays
+    // adjacent to its control and reads inside the width.
+    const modelHints: HintSpec[] = [{ key: '/', verb: 'Search' }];
+    if (showContextCapHint) modelHints.push({ key: 'Space', verb: 'Ctx' });
+    modelHints.push(
+      { key: 'Tab', verb: `Filter: ${filterLabelFooter}` },
+      { key: 'G', verb: `Group: ${groupByLabel}` },
+      { key: 'Esc', verb: 'Close' },
+    );
+    hints = formatHints(modelHints);
+  } else if (picker.mode === 'contextCap') {
+    hints = formatHints([{ key: 'Enter', verb: 'Confirm' }, { key: 'Esc', verb: 'Cancel' }]);
+  } else {
+    hints = formatHints([{ key: 'Up/Down', verb: 'Move' }, { key: 'Enter', verb: 'Select' }, { key: 'Esc', verb: 'Cancel' }]);
+  }
   const footerLine = createOverlayFilledBorderLine(width, layout, OVERLAY_GLYPHS.bottomLeft, OVERLAY_GLYPHS.horizontal, OVERLAY_GLYPHS.bottomRight, borderFg, DEFAULT_OVERLAY_PALETTE.sectionBg);
   putRowText(footerLine, layout.margin + 2, contentW, fitDisplay(truncateDisplay(hints, contentW), contentW), mutedFg, '', false, true);
   lines.push(footerLine);
@@ -458,7 +477,7 @@ function getRenderCacheKey(
   } else if (picker.mode === 'effort') {
     base.push(objectId(picker.effortLevels), picker.effortLevels.join('\u001f'), picker.pendingModel?.registryKey ?? picker.pendingModel?.id ?? '');
   } else if (picker.mode === 'contextCap') {
-    base.push(picker.contextCapQuery, picker.contextCapPendingModel?.registryKey ?? picker.contextCapPendingModel?.id ?? '');
+    base.push(picker.contextCapQuery, picker.contextCapPendingModel?.registryKey ?? picker.contextCapPendingModel?.id ?? '', picker.contextCapError ?? '');
   }
 
   return base.join('\u001e');

package/src/renderer/model-workspace.ts

@@ -11,6 +11,7 @@ import type { ModelPickerTargetInfo } from '../input/model-picker.ts';
 import type { Line } from '../types/grid.ts';
 import { createEmptyLine, createStyledCell } from '../types/grid.ts';
 import { getDisplayWidth, wrapText } from '../utils/terminal-width.ts';
+import { abbreviateCount } from '../utils/format-number.ts';
 import { GLYPHS, UI_TONES } from './ui-primitives.ts';
 
 const PALETTE = {
@@ -129,9 +130,7 @@ function stableWindow(total: number, selected: number, visible: number): { start
 
 function formatContext(value: number | undefined): string {
   if (!value) return '-';
-  if (value >= 1_000_000) return `${Math.round(value / 1_000_000)}M`;
-  if (value >= 1000) return `${Math.round(value / 1000)}k`;
-  return String(value);
+  return abbreviateCount(value, { rounding: 'round', decimals: 0 });
 }
 
 function modelKey(model: ModelDefinition): string {

package/src/renderer/overlay-box.ts

@@ -1,8 +1,14 @@
 import { createStyledCell, type Line } from '../types/grid.ts';
 import { getOverlayMaxWidth } from './overlay-viewport.ts';
-import { GLYPHS, UI_TONES } from './ui-primitives.ts';
+import { GLYPHS } from './ui-primitives.ts';
+import { resolveUiTones } from './theme.ts';
 import { fillWidth, makeLine, writeText } from './fullscreen-primitives.ts';
 
+// DEFAULT_OVERLAY_PALETTE is built from the mode-resolved chrome tones
+// (resolveUiTones) rather than the static UI_TONES constant — WO-001 single
+// read path. Mode is fixed to 'dark' until the terminal-bg-probe lands.
+const TONES = resolveUiTones('dark');
+
 export interface OverlayBoxPalette {
   readonly borderFg: string;
   readonly titleFg: string;
@@ -16,15 +22,15 @@ export interface OverlayBoxPalette {
 }
 
 export const DEFAULT_OVERLAY_PALETTE: Readonly<OverlayBoxPalette> = {
-  borderFg: UI_TONES.fg.secondary,
-  titleFg: UI_TONES.fg.primary,
-  bodyFg: UI_TONES.fg.primary,
-  mutedFg: UI_TONES.fg.dim,
-  selectedBg: UI_TONES.bg.selected,
-  titleBg: UI_TONES.bg.title,
-  sectionBg: UI_TONES.bg.section,
-  inputBg: UI_TONES.bg.input,
-  bodyBg: UI_TONES.bg.surface,
+  borderFg: TONES.fg.secondary,
+  titleFg: TONES.fg.primary,
+  bodyFg: TONES.fg.primary,
+  mutedFg: TONES.fg.dim,
+  selectedBg: TONES.bg.selected,
+  titleBg: TONES.bg.title,
+  sectionBg: TONES.bg.section,
+  inputBg: TONES.bg.input,
+  bodyBg: TONES.bg.surface,
 } as const;
 
 export interface OverlayBoxLayout {

package/src/renderer/panel-composite.ts

@@ -4,7 +4,6 @@ import type { InputHandler } from '../input/handler.ts';
 import type { PanelManager } from '../panels/panel-manager.ts';
 import type { PanelCompositeData } from './compositor.ts';
 import { createSplitPaneLayout } from './layout-engine.ts';
-import { renderPanelTabBar } from './panel-tab-bar.ts';
 import { renderPanelWorkspaceBar } from './panel-workspace-bar.ts';
 
 /**
@@ -108,33 +107,22 @@ export function buildPanelCompositeData(
   const workspaceBar = renderPanelWorkspaceBar(workspaceTabs, panelWidth, input.panelFocused);
 
   let topContent: Line[];
-  let topTabBar: Line | undefined;
-  let bottomTabBar: Line | undefined;
   let bottomContent: Line[] | undefined;
 
   const topActivePanel = topPane.panels[topPane.activeIndex] ?? null;
 
   if (hasBottom) {
-    topTabBar = renderPanelTabBar(
-      topPane.panels,
-      topPane.activeIndex,
-      panelWidth,
-      input.panelFocused && focusedPane === 'top',
-      'top',
-    );
-    const paneLayout = createSplitPaneLayout(Math.max(0, panelHeight - 1), verticalSplitRatio);
+    // Single consolidated workspace bar (1 row) + h-separator (1 row); the rest
+    // splits between the two panes' content.
+    const paneLayout = createSplitPaneLayout(Math.max(0, panelHeight - 1), verticalSplitRatio, {
+      topTabRows: 0,
+      bottomTabRows: 0,
+    });
     const topH = paneLayout.topContentRows;
     const bottomH = paneLayout.bottomContentRows;
     topContent = topActivePanel ? renderPanel(topActivePanel, panelWidth, topH) : [];
 
     const bottomActivePanel = bottomPane.panels[bottomPane.activeIndex] ?? null;
-    bottomTabBar = renderPanelTabBar(
-      bottomPane.panels,
-      bottomPane.activeIndex,
-      panelWidth,
-      input.panelFocused && focusedPane === 'bottom',
-      'bottom',
-    );
     bottomContent = bottomActivePanel ? renderPanel(bottomActivePanel, panelWidth, bottomH) : [];
   } else {
     const topH = Math.max(0, panelHeight - 1);
@@ -144,10 +132,9 @@ export function buildPanelCompositeData(
   return {
     panelData: {
       workspaceBar,
-      topTabBar,
       topContent,
       topFocused: input.panelFocused && focusedPane === 'top',
-      bottomTabBar,
+      hasBottomPane: hasBottom,
       bottomContent,
       bottomFocused: input.panelFocused && focusedPane === 'bottom',
       separator: true,

package/src/renderer/panel-workspace-bar.ts

@@ -1,21 +1,26 @@
 import type { Line } from '../types/grid.ts';
 import type { WorkspaceTab } from '../panels/panel-manager.ts';
-import { renderTabStrip } from './tab-strip.ts';
+import { renderTabStrip, type TabHitRegion } from './tab-strip.ts';
+import { UI_TONES } from './ui-primitives.ts';
 
-const ACTIVE_FG = '#e2e8f0';
-const ACTIVE_BG = '#0f172a';
-const INACTIVE_FG = '#94a3b8';
-const SEPARATOR_FG = '238';
-const LABEL_FG = '#cbd5e1';
-const LABEL_BG = '#1e293b';
+// Theme tokens (no raw hex) — keeps the bar in sync with the shared palette.
+const ACTIVE_FG = UI_TONES.fg.primary;       // selected tab text
+const ACTIVE_BG = UI_TONES.bg.selected;      // selected tab fill (stronger contrast)
+const INACTIVE_FG = UI_TONES.fg.muted;       // unselected tabs
+const SEPARATOR_FG = UI_TONES.fg.dim;        // │ separators
+const LABEL_FG = UI_TONES.fg.secondary;      // PANELS prefix label
+const LABEL_BG = UI_TONES.bg.title;          // prefix label background when focused
+const FOCUS_ACCENT_FG = UI_TONES.state.active; // the one focused tab
 
 export function renderPanelWorkspaceBar(
   tabs: readonly WorkspaceTab[],
   width: number,
   focused: boolean,
+  onLayout?: (regions: readonly TabHitRegion[]) => void,
 ): Line {
   return renderTabStrip({
     width,
+    onLayout,
     tabs: tabs.map((tab) => ({
       // tab.active = selected in its own pane (drives highlighted background).
       // tab.focused = has keyboard focus (drives brighter text / focus indicator).
@@ -32,7 +37,8 @@ export function renderPanelWorkspaceBar(
       activeBold: focused,
       inactiveFg: INACTIVE_FG,
       separatorFg: SEPARATOR_FG,
-      labelFg: LABEL_FG,
+      // Accent the PANELS chip when focused so it ties to the focus border.
+      labelFg: focused ? FOCUS_ACCENT_FG : LABEL_FG,
       labelBg: focused ? LABEL_BG : '',
       labelBold: focused,
       overflowFg: SEPARATOR_FG,

package/src/renderer/process-indicator.ts

@@ -87,8 +87,10 @@ export function renderProcessIndicator(
    */
   const PROGRESS_RESERVED_CHARS = 43;
   const progressMaxLen = Math.max(0, width - PROGRESS_RESERVED_CHARS); // reserve space for count + hint
+  // Truncate by display width (not JS string length) so wide/CJK glyphs in the
+  // agent progress text don't overflow the reserved budget.
   const progressSuffix = agentProgress && progressMaxLen > 10
-    ? ` | ${agentProgress.length > progressMaxLen ? agentProgress.slice(0, Math.max(0, progressMaxLen - 3)) + '...' : agentProgress}`
+    ? ` | ${getDisplayWidth(agentProgress) > progressMaxLen ? truncateToWidth(agentProgress, Math.max(0, progressMaxLen - 3)) + '...' : agentProgress}`
     : '';
   const label = `${parts.join(` ${GLYPHS.navigation.pipeSeparator} `)}${progressSuffix}`;
   const hint = `  ${GLYPHS.status.pending}  Enter to view`;

package/src/renderer/progress.ts

@@ -1,11 +1,13 @@
 import { type Line } from '../types/grid.ts';
 import { UIFactory } from './ui-factory.ts';
 import { getDisplayWidth, padDisplayEnd } from '../utils/terminal-width.ts';
+import { abbreviateCount } from '../utils/format-number.ts';
+import { SPINNER_FRAMES } from './ui-primitives.ts';
 
-// Rich spinner frames (used by progress indicators)
-export const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
-// Braille thinking spinner frames (used by the orchestrator thinking animation)
-export const THINKING_SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+// Rich spinner frames (used by progress indicators) — single source in ui-primitives.ts.
+export { SPINNER_FRAMES };
+// Braille thinking spinner frames (used by the orchestrator thinking animation) — same frame set.
+export const THINKING_SPINNER_FRAMES = SPINNER_FRAMES;
 
 /**
  * renderSpinner - Render a spinner with label as a single Line.
@@ -51,8 +53,8 @@ export function renderTokenBar(
   const lines: Line[] = [];
 
   // Stats row
-  const usedK = used >= 1000 ? `${(used / 1000).toFixed(1)}k` : String(used);
-  const maxK = max >= 1000 ? `${(max / 1000).toFixed(1)}k` : String(max);
+  const usedK = abbreviateCount(used, { noM: true });
+  const maxK = abbreviateCount(max, { noM: true });
   const pct = max > 0 ? Math.min(100, Math.round((used / max) * 100)) : 0;
   const toolStr = toolCount > 0 ? `  tools:${toolCount}` : '';
   const statsText = ` ${model}  in:${usedK}/${maxK} (${pct}%)${toolStr}`;

package/src/renderer/search-overlay.ts

@@ -25,18 +25,39 @@ export function renderSearchOverlay(
   const locked = manager.locked;
   const cursor = locked ? '' : '█';
   const queryDisplay = manager.query + cursor;
-  const hints = locked
+  const label = ' Find: ';
+  const fullHints = locked
     ? '  [n/N] next/prev  [jk] navigate  [Bksp] edit  [Esc] close'
     : '  [Enter/Tab] lock  [Esc] close';
-  const label = ' Find: ';
-  const matchStr = matchCount ? ` ${matchCount}` : '';
+  const shortHints = locked ? '  [n/N]  [Esc]' : '  [Esc]';
 
   // Build left portion: label + query (no match count — that gets separate styling)
   const leftPart = label + queryDisplay;
-  const hintsW = getDisplayWidth(hints);
+
+  // Tiered degradation: as the terminal narrows, first shorten the hints, then
+  // drop them, then drop the match-count segment — so the query area (leftWidth)
+  // never collapses to zero or negative and the overlay never renders garbage.
+  const minLeft = getDisplayWidth(label) + 4; // label + a few query cells
+  let hints = fullHints;
+  let matchStr = matchCount ? ` ${matchCount}` : '';
+  const leftFor = (h: string, m: string) => width - getDisplayWidth(h) - getDisplayWidth(m) - 2;
+  let leftWidth = leftFor(hints, matchStr);
+  if (leftWidth < minLeft) {
+    hints = shortHints;
+    leftWidth = leftFor(hints, matchStr);
+  }
+  if (leftWidth < minLeft) {
+    hints = '';
+    leftWidth = leftFor(hints, matchStr);
+  }
+  if (leftWidth < minLeft && matchStr.length > 0) {
+    matchStr = '';
+    leftWidth = leftFor(hints, matchStr);
+  }
+  // Final clamp: at least one cell, never wider than the bar.
+  leftWidth = Math.max(1, Math.min(width, leftWidth));
+
   const matchStrW = getDisplayWidth(matchStr);
-  // Available width for left content (query area)
-  const leftWidth = width - hintsW - matchStrW - 2;
   const truncatedLeft = fitDisplay(
     getDisplayWidth(leftPart) > leftWidth ? truncateDisplay(leftPart, leftWidth) : leftPart,
     leftWidth,

package/src/renderer/session-picker-modal.ts

@@ -55,10 +55,12 @@ export function renderSessionPickerModal(
       style: { fg: '240', dim: true },
     });
   } else {
-    // Column widths: name(24) | timestamp(16) | messages(remaining)
-    const nameW = 24;
-    const tsW = 16;
-    const msgW = Math.max(4, contentW - nameW - tsW - 4); // 4 = separators/spaces
+    // Proportional column widths that adapt to the modal's content width:
+    // timestamp ~22% (clamped 10..16), messages ~12% (clamped 4..8), and the
+    // name column absorbs the remainder so the row always fills contentW.
+    const tsW = Math.min(16, Math.max(10, Math.floor(contentW * 0.22)));
+    const msgW = Math.min(8, Math.max(4, Math.floor(contentW * 0.12)));
+    const nameW = Math.max(8, contentW - tsW - msgW - 4); // 4 = separators/spaces
 
     // Column header
     const nameHdr = fitDisplay('Name', nameW);

package/src/renderer/settings-modal.ts

@@ -12,6 +12,7 @@ import { getDisplayWidth, wrapText } from '../utils/terminal-width.ts';
 import { CATEGORY_LABELS, describeUiRouting, formatValue, getSettingLabel, inferSubscriptionRouteReason, valueColor } from './settings-modal-helpers.ts';
 import { isSecretConfigKey } from '../config/secret-config.ts';
 import { GLYPHS } from './ui-primitives.ts';
+import { formatHints, joinHints } from './hint-grammar.ts';
 import {
   clamp,
   getFullscreenWorkspaceMetrics,
@@ -540,24 +541,83 @@ function rowColorForSetting(modal: SettingsModal, rowText: string): string {
 }
 
 function footerText(modal: SettingsModal, width: number): string {
+  // Every branch speaks the shared hint grammar: bracketed [Key] Verb segments
+  // joined by the middle dot, with Esc sorted last. Leading words like
+  // "Focus settings" are state labels appended verbatim, not key hints.
   // Armed reset gate takes priority over all other footer states.
   if (modal.resetCategoryConfirm !== null || modal.resetAllConfirm !== null)
-    return 'Reset armed · Enter/y confirm · Esc/n cancel';
-  if (modal.searchFocused) return 'Search · type to filter · Up/Down navigate results · Enter select · Esc exit search';
-  if (modal.editingMode) return 'Enter Confirm edit · Esc Cancel edit · text keys edit the selected field';
-  if (modal.focusPane === 'categories') return 'Focus categories · Up/Down choose · Right/Enter settings · Tab pane · / search · Esc close';
-  if (modal.currentCategory === 'subscriptions') return 'Focus settings · Up/Down provider · Left categories · Tab pane · / search · Enter review/sign out · Esc close';
-  if (modal.currentCategory === 'mcp') return 'Focus settings · Up/Down server · Left categories · Tab pane · / search · Enter edit trust · Esc close';
-  if (modal.currentCategory === 'flags') return 'Focus feature flags · Up/Down flag · Left categories · Tab pane · / search · Enter/Space toggle · Esc close';
+    return joinHints('Reset armed', formatHints([
+      { key: 'Enter/y', verb: 'confirm' },
+      { key: 'Esc/n', verb: 'cancel' },
+    ]));
+  if (modal.searchFocused)
+    return joinHints('Search', 'type to filter', formatHints([
+      { key: 'Up/Down', verb: 'Navigate' },
+      { key: 'Enter', verb: 'Select' },
+      { key: 'Esc', verb: 'Exit search' },
+    ]));
+  if (modal.editingMode)
+    return formatHints([
+      { key: 'Enter', verb: 'Confirm edit' },
+      { key: 'Esc', verb: 'Cancel edit' },
+    ]);
+  if (modal.focusPane === 'categories')
+    return joinHints('Focus categories', formatHints([
+      { key: 'Up/Down', verb: 'Choose' },
+      { key: 'Right/Enter', verb: 'Settings' },
+      { key: 'Tab', verb: 'Pane' },
+      { key: '/', verb: 'Search' },
+      { key: 'Esc', verb: 'Close' },
+    ]));
+  if (modal.currentCategory === 'subscriptions')
+    return joinHints('Focus settings', formatHints([
+      { key: 'Up/Down', verb: 'Provider' },
+      { key: 'Left', verb: 'Categories' },
+      { key: 'Tab', verb: 'Pane' },
+      { key: '/', verb: 'Search' },
+      { key: 'Enter', verb: 'Review/sign out' },
+      { key: 'Esc', verb: 'Close' },
+    ]));
+  if (modal.currentCategory === 'mcp')
+    return joinHints('Focus settings', formatHints([
+      { key: 'Up/Down', verb: 'Server' },
+      { key: 'Left', verb: 'Categories' },
+      { key: 'Tab', verb: 'Pane' },
+      { key: '/', verb: 'Search' },
+      { key: 'Enter', verb: 'Edit trust' },
+      { key: 'Esc', verb: 'Close' },
+    ]));
+  if (modal.currentCategory === 'flags')
+    return joinHints('Focus feature flags', formatHints([
+      { key: 'Up/Down', verb: 'Flag' },
+      { key: 'Left', verb: 'Categories' },
+      { key: 'Tab', verb: 'Pane' },
+      { key: '/', verb: 'Search' },
+      { key: 'Enter/Space', verb: 'Toggle' },
+      { key: 'Esc', verb: 'Close' },
+    ]));
   // Default settings pane: tier the reset affordances by available width.
   // W<80:  minimal — only the most critical action survives.
   // W<160: compact but still shows both reset affordances.
   // W≥160: standard with all navigation tokens.
   if (width < 80)
-    return 'R reset · Esc';
+    return formatHints([{ key: 'R', verb: 'reset' }, { key: 'Esc', verb: 'Close' }]);
   if (width < 160)
-    return 'Up/Down · Enter/Space edit · ⇧R reset cat · ^⇧R reset all · Esc';
-  return 'Focus settings · Up/Down setting · Left · Enter/Space edit/toggle · ⇧R reset cat · ^⇧R reset all · Esc close';
+    return formatHints([
+      { key: 'Up/Down', verb: 'Move' },
+      { key: 'Enter/Space', verb: 'Edit' },
+      { key: '⇧R', verb: 'reset cat' },
+      { key: '^⇧R', verb: 'reset all' },
+      { key: 'Esc', verb: 'Close' },
+    ]);
+  return joinHints('Focus settings', formatHints([
+    { key: 'Up/Down', verb: 'Setting' },
+    { key: 'Left', verb: 'Categories' },
+    { key: 'Enter/Space', verb: 'Edit/toggle' },
+    { key: '⇧R', verb: 'reset cat' },
+    { key: '^⇧R', verb: 'reset all' },
+    { key: 'Esc', verb: 'Close' },
+  ]));
 }
 
 export function renderSettingsModal(

package/src/renderer/shell-surface.ts

@@ -34,6 +34,12 @@ export interface ShellFooterBuildOptions {
    * Rendered as a dim informational line above the prompt when non-null.
    */
   readonly contextStatusHint?: string | null;
+  /**
+   * Compact footer posture for short terminals (~<30 rows). Collapses the
+   * footer to its essentials (prompt box + token/cost line + help) and drops
+   * the process indicator, context bar, context-info line and posture block.
+   */
+  readonly compact?: boolean;
 }
 
 export interface ShellFooterBuildResult {
@@ -41,14 +47,28 @@ export interface ShellFooterBuildResult {
   readonly height: number;
 }
 
-const FOOTER_BASE_ROWS = 9;
-const CONTEXT_PROGRESS_ROWS = 2;
+// Fixed rows that createFooter always emits (non-compact): prompt-box top
+// border, prompt-box bottom border, token-usage line, context-info line, and
+// the help/exit line. The composer posture block and context bar are counted
+// separately (they are conditional).
+const FOOTER_BASE_ROWS = 5;
+const CONTEXT_PROGRESS_ROWS = 1;
 const PROCESS_INDICATOR_ROWS = 1;
 
+/**
+ * Real height of the most recently rendered footer. estimateShellFooterHeight
+ * prefers this so the pre-prompt viewport math accounts for the composer
+ * posture block and context hint that the static formula cannot see. Reset to
+ * null before any footer has rendered (cold start), where the formula is exact
+ * for the common posture-free, hint-free case.
+ */
+let lastRenderedFooterHeight: number | null = null;
+
 export function estimateShellFooterHeight(
   promptLineCount: number,
   contextWindow?: number,
 ): number {
+  if (lastRenderedFooterHeight !== null) return lastRenderedFooterHeight;
   const safePromptLines = Math.max(1, promptLineCount);
   const progressRows = contextWindow && contextWindow > 0 ? CONTEXT_PROGRESS_ROWS : 0;
   return FOOTER_BASE_ROWS + safePromptLines + progressRows + PROCESS_INDICATOR_ROWS;
@@ -79,20 +99,26 @@ export function buildShellFooter(
     options.composerStatus,
     options.composerFlags,
     options.composerPendingRisk,
+    options.compact ?? false,
   );
-  const processIndicator = renderProcessIndicator(
-    options.width,
-    options.runningAgentCount,
-    options.runningProcessCount,
-    options.indicatorFocused,
-    options.runningAgentProgress,
-  );
-  const inputBoxRows = Math.max(1, options.promptLineCount) + 2;
-  lines.splice(inputBoxRows, 0, ...processIndicator);
-  // Passive context status hint — rendered as a dim informational line before the prompt.
-  if (options.contextStatusHint) {
-    const hintLine = UIFactory.stringToLine(options.contextStatusHint, options.width, { fg: '#64748b' });
-    lines.unshift(hintLine);
+  // Compact posture drops the process indicator and context hint entirely so
+  // the footer fits within ~5 rows on short terminals.
+  if (!options.compact) {
+    const processIndicator = renderProcessIndicator(
+      options.width,
+      options.runningAgentCount,
+      options.runningProcessCount,
+      options.indicatorFocused,
+      options.runningAgentProgress,
+    );
+    const inputBoxRows = Math.max(1, options.promptLineCount) + 2;
+    lines.splice(inputBoxRows, 0, ...processIndicator);
+    // Passive context status hint — rendered as a dim informational line before the prompt.
+    if (options.contextStatusHint) {
+      const hintLine = UIFactory.stringToLine(options.contextStatusHint, options.width, { fg: '#64748b' });
+      lines.unshift(hintLine);
+    }
   }
+  lastRenderedFooterHeight = lines.length;
   return { lines, height: lines.length };
 }

package/src/renderer/status-glyphs.ts

@@ -4,18 +4,20 @@
 // Extracted as a neutral module so both status-token.ts and polish.ts can
 // import from here without creating a circular ESM dependency.
 //
-// Glyphs:
-//   good  ✓  (CHECK MARK U+2713)
-//   warn  ⚠  (WARNING SIGN U+26A0)
-//   bad   ✕  (MULTIPLICATION X U+2715)
-//   info  ○  (WHITE CIRCLE U+25CB)
+// STATE_GLYPHS is an alias into GLYPHS.status (ui-primitives.ts) — the single
+// glyph registry. Previously GLYPHS.status.info ('•') collided with
+// GLYPHS.status.pending, and STATE_GLYPHS.info ('○') collided with
+// GLYPHS.status.idle. GLYPHS.status.info is now '○' (this module's historical
+// value) and idle uses a distinct glyph ('◌').
 // ---------------------------------------------------------------------------
 
+import { GLYPHS } from './ui-primitives.ts';
+
 export type StatusState = 'good' | 'warn' | 'bad' | 'info';
 
 export const STATE_GLYPHS: Record<StatusState, string> = {
-  good: '\u2713', // ✓
-  warn: '\u26a0', // ⚠
-  bad:  '\u2715', // ✕
-  info: '\u25cb', // ○
+  good: GLYPHS.status.success, // ✓
+  warn: GLYPHS.status.warn,    // ⚠
+  bad:  GLYPHS.status.failure, // ✕
+  info: GLYPHS.status.info,    // ○
 };