@pellux/goodvibes-tui 0.28.0 → 0.29.0

package/src/renderer/conversation-overlays.ts

@@ -40,12 +40,21 @@ export function applyConversationOverlays(
   let next = viewport;
   const bottomDockInset = 1 + (input.searchManager.active || input.historySearch.active ? 1 : 0);
 
+  // Overlay posture rule: workspaces (onboarding, model, settings, mcp, help,
+  // shortcuts) claim the full viewport and are mutually exclusive with docked
+  // pickers/modals. Once a fullscreen workspace claims the screen, no docked
+  // overlay is drawn on top of it — enforcing a single visible overlay even if
+  // stray state survives the handler's clearModalStack. The input layer keeps
+  // the modal stack to one entry; this is the renderer-side backstop.
+  let fullscreenClaimed = false;
+
   if (input.onboardingWizard.active) {
     const lines = renderOnboardingWizard(input.onboardingWizard, conversationWidth, viewportHeight);
     next = replaceViewportWithOverlay(lines, conversationWidth, viewportHeight);
+    fullscreenClaimed = true;
   }
 
-  if (input.filePicker.active) {
+  if (!fullscreenClaimed && input.filePicker.active) {
     const lines = renderFilePickerOverlay(input.filePicker, conversationWidth, viewportHeight);
     next = overlayViewportBottom(next, lines, conversationWidth, viewportHeight, bottomDockInset);
   }
@@ -53,9 +62,10 @@ export function applyConversationOverlays(
   if (input.modelPicker.active) {
     const lines = renderModelWorkspace(input.modelPicker, conversationWidth, viewportHeight);
     next = replaceViewportWithOverlay(lines, conversationWidth, viewportHeight);
+    fullscreenClaimed = true;
   }
 
-  if (input.selectionModal.active) {
+  if (!fullscreenClaimed && input.selectionModal.active) {
     const lines = renderSelectionModalOverlay(input.selectionModal, conversationWidth, viewportHeight);
     next = overlayViewportBottom(next, lines, conversationWidth, viewportHeight, bottomDockInset);
   }
@@ -68,22 +78,22 @@ export function applyConversationOverlays(
     next.push(...renderHistorySearchOverlay(input.historySearch, conversationWidth));
   }
 
-  if (input.processModal.active) {
+  if (!fullscreenClaimed && input.processModal.active) {
     const lines = renderProcessModal(input.processModal, conversationWidth, viewportHeight);
     next = overlayViewportBottom(next, lines, conversationWidth, viewportHeight, bottomDockInset);
   }
 
-  if (input.agentDetailModal.active) {
-    const lines = renderAgentDetailModal(input.agentDetailModal, conversationWidth);
+  if (!fullscreenClaimed && input.agentDetailModal.active) {
+    const lines = renderAgentDetailModal(input.agentDetailModal, conversationWidth, viewportHeight);
     next = overlayViewportBottom(next, lines, conversationWidth, viewportHeight, bottomDockInset);
   }
 
-  if (input.liveTailModal.active) {
+  if (!fullscreenClaimed && input.liveTailModal.active) {
     const lines = renderLiveTailModal(input.liveTailModal, conversationWidth, viewportHeight);
     next = overlayViewportBottom(next, lines, conversationWidth, viewportHeight, bottomDockInset);
   }
 
-  if (input.contextInspectorModal.active) {
+  if (!fullscreenClaimed && input.contextInspectorModal.active) {
     const lines = renderContextInspector(conversation, conversationWidth, viewportHeight, contextWindow);
     next = overlayViewportBottom(next, lines, conversationWidth, viewportHeight, bottomDockInset);
   }
@@ -91,24 +101,26 @@ export function applyConversationOverlays(
   if (input.settingsModal.active) {
     const lines = renderSettingsModal(input.settingsModal, conversationWidth, viewportHeight);
     next = replaceViewportWithOverlay(lines, conversationWidth, viewportHeight);
+    fullscreenClaimed = true;
   }
 
   if (input.mcpWorkspace.active) {
     const lines = renderMcpWorkspace(input.mcpWorkspace, conversationWidth, viewportHeight);
     next = replaceViewportWithOverlay(lines, conversationWidth, viewportHeight);
+    fullscreenClaimed = true;
   }
 
-  if (input.sessionPickerModal.active) {
+  if (!fullscreenClaimed && input.sessionPickerModal.active) {
     const lines = renderSessionPickerModal(input.sessionPickerModal, conversationWidth, viewportHeight);
     next = overlayViewportBottom(next, lines, conversationWidth, viewportHeight, bottomDockInset);
   }
 
-  if (input.profilePickerModal.active) {
+  if (!fullscreenClaimed && input.profilePickerModal.active) {
     const lines = renderProfilePickerModal(input.profilePickerModal, conversationWidth, viewportHeight);
     next = overlayViewportBottom(next, lines, conversationWidth, viewportHeight, bottomDockInset);
   }
 
-  if (input.bookmarkModal.active) {
+  if (!fullscreenClaimed && input.bookmarkModal.active) {
     const lines = renderBookmarkModal(input.bookmarkModal, conversationWidth, viewportHeight);
     next = overlayViewportBottom(next, lines, conversationWidth, viewportHeight, bottomDockInset);
   }
@@ -116,14 +128,16 @@ export function applyConversationOverlays(
   if (input.helpOverlayActive) {
     const lines = renderHelpOverlay(conversationWidth, keybindingsManager, commandRegistry.getAll(), input.helpScrollOffset, viewportHeight);
     next = replaceViewportWithOverlay(lines, conversationWidth, viewportHeight);
+    fullscreenClaimed = true;
   }
 
   if (input.shortcutsOverlayActive) {
     const lines = renderShortcutsOverlay(conversationWidth, keybindingsManager, input.shortcutsScrollOffset, viewportHeight);
     next = replaceViewportWithOverlay(lines, conversationWidth, viewportHeight);
+    fullscreenClaimed = true;
   }
 
-  if (input.commandMode && input.autocomplete?.isActive) {
+  if (!fullscreenClaimed && input.commandMode && input.autocomplete?.isActive) {
     const lines = renderAutocompleteOverlay(input.autocomplete, conversationWidth, viewportHeight);
     if (lines.length > 0) {
       next = overlayViewportBottom(next, lines, conversationWidth, viewportHeight, bottomDockInset);

package/src/renderer/footer-tips.ts

@@ -0,0 +1,41 @@
+/**
+ * footer-tips.ts — the persistent discoverability hint shown in the shell
+ * footer's tip slot.
+ *
+ * WO-151: instead of a single frozen "/help for commands" line, the footer
+ * surfaces a rotating set of the highest-value affordances (panels, process
+ * monitor, help, quit). Rotation is *contextual, not timed*: when an agent turn
+ * is actively running, the process-monitor tip is promoted to the front so the
+ * operator can jump to F2 while work is in flight. Selection is a pure function
+ * of context so the footer renders deterministically (golden frames stay
+ * stable) — no wall-clock input.
+ */
+
+export interface FooterTipContext {
+  /** True while an agent turn is actively running (streaming / tools / hooks). */
+  readonly agentActive: boolean;
+}
+
+/** Composer status labels that mean an agent turn is actively in flight. */
+const ACTIVE_TURN_STATUSES = new Set(['preflight', 'streaming', 'tools', 'post-hooks']);
+
+/** Derive agent-active state from the composer status label passed to the footer. */
+export function isAgentActive(composerStatus: string | undefined): boolean {
+  return composerStatus !== undefined && ACTIVE_TURN_STATUSES.has(composerStatus);
+}
+
+const TIP_PANELS = 'Ctrl+P panels';
+const TIP_PROCESSES = 'F2 processes';
+const TIP_HELP = '? help';
+const TIP_QUIT = 'Ctrl+C quit';
+
+/**
+ * Build the footer discoverability tip. Segments join with the shared middle
+ * dot. Agent-active state promotes the process-monitor tip to the front.
+ */
+export function buildFooterTip(ctx: FooterTipContext): string {
+  const lead = ctx.agentActive
+    ? [TIP_PROCESSES, TIP_PANELS, TIP_HELP]
+    : [TIP_PANELS, TIP_PROCESSES, TIP_HELP];
+  return [...lead, TIP_QUIT].join(' · ');
+}

package/src/renderer/fullscreen-primitives.ts

@@ -1,24 +1,30 @@
 import type { Line } from '../types/grid.ts';
 import { createEmptyLine, createStyledCell } from '../types/grid.ts';
 import { getDisplayWidth } from '../utils/terminal-width.ts';
-import { GLYPHS, UI_TONES } from './ui-primitives.ts';
+import { GLYPHS } from './ui-primitives.ts';
+import { resolveUiTones } from './theme.ts';
+
+// FULLSCREEN_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 const FULLSCREEN_PALETTE = {
-  border: '#64748b',
-  title: '#67e8f9',
-  subtitle: '#93c5fd',
-  text: '#e2e8f0',
-  muted: '#94a3b8',
-  dim: '#64748b',
-  selectedBg: '#223049',
-  categoryBg: '#141b25',
-  contextBg: '#121923',
-  controlsBg: '#0f141d',
-  footerBg: '#111827',
-  good: UI_TONES.state.good,
-  warn: UI_TONES.state.warn,
-  bad: UI_TONES.state.bad,
-  info: UI_TONES.state.info,
+  border: TONES.border,
+  title: TONES.accent.browser,
+  subtitle: TONES.accent.conversation,
+  text: TONES.fg.primary,
+  muted: TONES.fg.muted,
+  dim: TONES.border,
+  selectedBg: TONES.bg.selected,
+  categoryBg: TONES.bg.section,
+  contextBg: TONES.bg.surface,
+  controlsBg: TONES.bg.base,
+  footerBg: TONES.bg.footer,
+  good: TONES.state.good,
+  warn: TONES.state.warn,
+  bad: TONES.state.bad,
+  info: TONES.state.info,
 } as const;
 
 export type FullscreenTextStyle = Partial<Omit<Line[number], 'char'>>;

package/src/renderer/help-overlay.ts

@@ -10,6 +10,7 @@ import type { SlashCommand } from '../input/command-registry.ts';
 import type { KeybindingsManager } from '../input/keybindings.ts';
 import { getOverlaySurfaceMetrics } from './overlay-viewport.ts';
 import { getVisibleWindow } from './surface-layout.ts';
+import { formatHints } from './hint-grammar.ts';
 import { logger } from '@pellux/goodvibes-sdk/platform/utils';
 
 function toModalSections(rows: readonly string[]): import('./modal-factory.ts').ModalSection[] {
@@ -40,7 +41,28 @@ export function renderHelpOverlay(
 ): Line[] {
   const kb = (action: Parameters<typeof keybindingsManager.getComboLabel>[0]) => keybindingsManager.getComboLabel(action);
 
-  const hasCommand = (name: string): boolean => Boolean(commands?.some((command) => command.name === name || (command.aliases ?? []).includes(name)));
+  const hasCommand = (name: string): boolean => {
+    if (!commands) return false;
+    for (const command of commands) {
+      // A broken plugin may expose a throwing `aliases` getter; skip it rather
+      // than crash the overlay (mirrors the Quick Start traversal guard below).
+      try {
+        if (command.name === name || (command.aliases ?? []).includes(name)) return true;
+      } catch { /* skip this command */ }
+    }
+    return false;
+  };
+
+  const shortcutLine = (label: string, desc: string): string => `  ${label.padEnd(20)}  ${desc}`;
+
+  // Enumerate EVERY workspace/panel binding straight from the live keybindings
+  // table so each rebindable action (including user overrides) is discoverable
+  // here and stays in lockstep with /keybindings. Any action id prefixed
+  // `panel-` is a workspace affordance.
+  const panelBindingRows: string[] = keybindingsManager
+    .getAll()
+    .filter((entry) => entry.action.startsWith('panel-'))
+    .map((entry) => shortcutLine(keybindingsManager.getComboLabel(entry.action), entry.description));
 
   // Keyboard shortcut sections
   const shortcutRows: string[] = [
@@ -59,9 +81,20 @@ export function renderHelpOverlay(
     '',
     '  Overlays And Panels',
     '  ' + '\u2500'.repeat(40),
-    `  ${'?'.padEnd(20)}  Toggle help`,
-    `  ${'/shortcuts'.padEnd(20)}  Full keyboard shortcuts`,
-    `  ${kb('panel-picker').padEnd(20)}  Open or focus the panel workspace`,
+    shortcutLine('?', 'Toggle help'),
+    shortcutLine('/shortcuts', 'Full keyboard shortcuts'),
+    shortcutLine('Tab', 'Swap focus between input and workspace'),
+    ...panelBindingRows,
+    '',
+    // The shared in-panel contract every workspace panel honors. These are not
+    // rebindable global actions \u2014 they are the common controls a focused panel
+    // interprets \u2014 so they are documented here rather than pulled from getAll().
+    '  In-Panel Controls',
+    '  ' + '\u2500'.repeat(40),
+    shortcutLine('j / k', 'Move selection down / up'),
+    shortcutLine('g / G', 'Jump to top / bottom'),
+    shortcutLine('Enter / Esc', 'Activate / dismiss or leave panel'),
+    shortcutLine('/', 'Filter the list'),
     '',
   ];
 
@@ -109,7 +142,33 @@ export function renderHelpOverlay(
     }
   }
 
+  // Essentials \u2014 the handful of commands worth memorizing, listed first and
+  // filtered to what the live registry actually exposes.
+  const ESSENTIAL_COMMANDS: Array<[name: string, desc: string]> = [
+    ['model',       'Select provider or model'],
+    ['sessions',    'Browse and resume saved sessions'],
+    ['save',        'Save the current session'],
+    ['compact',     'Compact the conversation history'],
+    ['clear',       'Clear the conversation'],
+    ['keybindings', 'List and customize key bindings'],
+    ['panel',       'Open, focus, or manage panels'],
+  ];
+
   const commandRows: string[] = [];
+  // Track command names already surfaced in a curated group so the exhaustive
+  // list below does not repeat them.
+  const seen = new Set<string>();
+
+  const essentialRows: string[] = [];
+  for (const [name, desc] of ESSENTIAL_COMMANDS) {
+    if (!hasCommand(name)) continue;
+    seen.add(name);
+    essentialRows.push(`  ${`/${name}`.padEnd(18)}  ${desc}`);
+  }
+  if (essentialRows.length > 0) {
+    commandRows.push('  Essentials', '  ' + '\u2500'.repeat(40), ...essentialRows, '');
+  }
+
   if (quickStartRows.length > 0) {
     commandRows.push('  Quick Start', '  ' + '\u2500'.repeat(40), ...quickStartRows, '');
   }
@@ -117,18 +176,18 @@ export function renderHelpOverlay(
   if (commands && commands.length > 0) {
     commandRows.push('', '  Available Slash Commands', '  ' + '\u2500'.repeat(40));
     const preferred = ['setup', 'cockpit', 'settings', 'provider', 'subscription', 'marketplace', 'remote', 'sandbox', 'security', 'policy', 'incident', 'knowledge', 'hooks', 'orchestration', 'communication', 'tasks'];
-    const seen = new Set<string>();
     for (const name of preferred) {
       const cmd = commands.find((entry) => entry.name === name);
-      if (!cmd) continue;
+      if (!cmd || seen.has(cmd.name)) continue;
       seen.add(cmd.name);
       const nameCol = `/${cmd.name}`.padEnd(18);
       commandRows.push(`  ${nameCol}  ${cmd.description}`);
     }
+    // No command cap: the overlay windows and scrolls (getVisibleWindow below),
+    // so the full remaining registry is listed rather than truncated at 24.
     const remainder = [...commands]
       .filter((cmd) => !seen.has(cmd.name))
-      .sort((a, b) => a.name.localeCompare(b.name))
-      .slice(0, 24);
+      .sort((a, b) => a.name.localeCompare(b.name));
     if (remainder.length > 0) {
       commandRows.push('', '  More Commands', '  ' + '\u2500'.repeat(40));
       for (const cmd of remainder) {
@@ -163,15 +222,19 @@ export function renderHelpOverlay(
       width: metrics.boxWidth,
       margin: metrics.margin,
       targetContentRows: metrics.contentRows,
-      tabs: [
-        { label: 'Overview', active: true },
-        { label: 'Commands' },
-      ],
+      // Single tab: the old second 'Commands' tab had no switch handler (Left/
+      // Right did nothing), so it was a dead affordance. The overlay is one
+      // scrolling surface, so it advertises exactly one tab.
+      tabs: [{ label: 'Overview', active: true }],
       sections: toModalSections(visibleRows),
       helpers: allRows.length > maxVisible
         ? [{ content: `[${window.start + 1}-${Math.min(allRows.length, clampedOffset + visibleRows.length)} of ${allRows.length}]` }]
         : undefined,
-      hints: ['? or Esc Close', 'Up/Down Scroll'],
+      hints: [formatHints([
+        { key: 'Up/Down', verb: 'Scroll' },
+        { key: '?', verb: 'Help' },
+        { key: 'Esc', verb: 'Close' },
+      ])],
     },
     width,
   );
@@ -236,6 +299,17 @@ export function renderShortcutsOverlay(
     row(kb('panel-picker'), 'Open / focus / hide panel workspace'),
     row(kb('panel-tab-next'), 'Next workspace panel tab'),
     row(kb('panel-tab-prev'), 'Previous workspace panel tab'),
+    row(`${kb('panel-tab-1')}\u2026${kb('panel-tab-9')}`, 'Jump to workspace tab 1-9'),
+    row(kb('panel-focus-toggle'), 'Swap focus between top / bottom pane'),
+    row(kb('panel-close'), 'Close active panel'),
+    row(kb('panel-close-all'), 'Close all panels'),
+    row(kb('panel-ops'), 'Open the Ops Control panel'),
+    '',
+    '  In-Panel Controls',
+    '  ' + '\u2500'.repeat(40),
+    row('j / k', 'Move selection down / up'),
+    row('g / G', 'Jump to top / bottom'),
+    row('/', 'Filter the list'),
     '',
     `  Config: /keybindings to list and customize`,
   ];
@@ -261,7 +335,10 @@ export function renderShortcutsOverlay(
       helpers: allRows.length > maxVisible
         ? [{ content: `[${window.start + 1}-${Math.min(allRows.length, clampedOffset + visibleRows.length)} of ${allRows.length}]` }]
         : undefined,
-      hints: ['Esc Close', 'Up/Down Scroll'],
+      hints: [formatHints([
+        { key: 'Up/Down', verb: 'Scroll' },
+        { key: 'Esc', verb: 'Close' },
+      ])],
     },
     width,
   );

package/src/renderer/hint-grammar.ts

@@ -0,0 +1,52 @@
+/**
+ * hint-grammar.ts — the single hint-bar grammar for every overlay footer.
+ *
+ * WO-151: one grammar across the model picker, settings modal, help/shortcuts
+ * overlays, and ModalFactory variants so footers stop drifting into three
+ * different dialects (verbless brackets, prose sentences, ad-hoc separators).
+ *
+ * The grammar is:
+ *   - each hint renders as `[Key] Verb` (a bracketed key followed by its verb),
+ *   - hints are joined by a middle-dot separator (` · `),
+ *   - any Escape hint is always sorted last (the conventional "way out").
+ *
+ * State segments that are not key hints (e.g. `Filter: All`) can be appended
+ * verbatim via {@link joinHints}; they are never reordered.
+ */
+
+/** A single key hint. `verb` may be omitted for a bare key affordance. */
+export interface HintSpec {
+  key: string;
+  verb?: string;
+}
+
+/** The canonical separator between hint segments. */
+export const HINT_SEPARATOR = ' · ';
+
+function isEscapeHint(spec: HintSpec): boolean {
+  return spec.key.trim().toLowerCase() === 'esc';
+}
+
+/** Render one hint as `[Key] Verb` (or `[Key]` when it has no verb). */
+export function formatHint(spec: HintSpec): string {
+  return spec.verb ? `[${spec.key}] ${spec.verb}` : `[${spec.key}]`;
+}
+
+/**
+ * Format a list of key hints into a single footer string using the shared
+ * grammar. Escape hints are moved to the end (stable for everything else).
+ */
+export function formatHints(specs: readonly HintSpec[]): string {
+  // Stable partition: non-escape hints keep their order, escape hints trail.
+  const ordered = [...specs].sort((a, b) => Number(isEscapeHint(a)) - Number(isEscapeHint(b)));
+  return ordered.map(formatHint).join(HINT_SEPARATOR);
+}
+
+/**
+ * Join already-rendered segments (hint bars, state tags) with the shared
+ * separator, dropping empties. Order is preserved — use this to append state
+ * indicators after a {@link formatHints} bar.
+ */
+export function joinHints(...segments: Array<string | null | undefined>): string {
+  return segments.filter((s): s is string => !!s && s.length > 0).join(HINT_SEPARATOR);
+}

package/src/renderer/layout.ts

@@ -1,4 +1,4 @@
-import { GLYPHS } from './ui-primitives.ts';
+import { GLYPHS, SPINNER_FRAMES, UI_TONES } from './ui-primitives.ts';
 
 /**
  * Layout constants — single source of truth for margins and content width.
@@ -14,19 +14,19 @@ export const LAYOUT = {
 
 export const TOOL_STATUS = {
   SUCCESS_ICON: GLYPHS.status.success,
-  SPINNER_FRAMES: ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'],
+  SPINNER_FRAMES,
   FAIL_ICON: GLYPHS.status.failure,
   PENDING_ICON: GLYPHS.status.pending,
   TOOL_NAME_PAD: 8,
 } as const;
 
 export const COLORS = {
-  DIM_TEXT: '244',
+  DIM_TEXT: UI_TONES.fg.dim,
 } as const;
 
 export const BORDERS = {
-  THINKING: { char: '▌', color: '#9945FF' },
-  ERROR:    { char: '▌', color: '#ef4444' },
-  WARNING:  { char: '▌', color: '#eab308' },
-  INFO:     { char: '▌', color: '#22d3ee' },
+  THINKING: { char: '▌', color: UI_TONES.state.reasoning },
+  ERROR:    { char: '▌', color: UI_TONES.state.bad },
+  WARNING:  { char: '▌', color: UI_TONES.state.warn },
+  INFO:     { char: '▌', color: UI_TONES.state.info },
 } as const;

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

@@ -13,6 +13,7 @@ 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 {
@@ -413,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);

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

@@ -2,11 +2,12 @@ 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.