@pellux/goodvibes-tui 1.20.0 → 1.21.0

package/src/providers/reasoning-effort-surface.ts

@@ -0,0 +1,399 @@
+/**
+ * reasoning-effort-surface.ts — the TUI's single reading of the SDK's
+ * per-model reasoning-effort spec.
+ *
+ * Every effort-shaped surface (the `/effort` command, the model picker's
+ * effort step, the model-switch and failover notices) asks this module what a
+ * specific model offers, instead of each one carrying its own list. The list
+ * used to be the hardcoded four levels `instant, low, medium, high`, which was
+ * wrong in both directions: it offered `instant` to models that reject it and
+ * hid `xhigh`/`max`/`none` from models that accept them.
+ *
+ * The honest presentation differs per spec kind, so the wording is generated
+ * here rather than templated at each call site:
+ *
+ *   - `effort`        — the model names its levels; offer exactly those.
+ *   - `budget_tokens` — the model takes a thinking-token budget, so each level
+ *                       is shown with the budget it sends.
+ *   - `toggle`        — reasoning is on or off only; say so, and do not imply
+ *                       that the levels in between mean anything.
+ *   - `unavailable`   — nothing is configurable; the picker says that instead
+ *                       of presenting an empty list.
+ *
+ * A `fallback`-sourced spec is a labelled guess: neither the live catalog nor
+ * the curated family table recognised the model. The SDK's OpenAI and Gemini
+ * adapters send nothing at all for such a model (silence beats a guess on an
+ * endpoint that also serves non-reasoning models), so surfaces built here say
+ * that outright rather than implying the choice takes effect.
+ */
+
+import {
+  EFFORT_DESCRIPTIONS,
+  budgetTokensForLevel,
+  describeReasoningWire,
+  reasoningEffortLevels,
+  resolveEffortForModel,
+  resolveReasoningEffortSpec,
+  setActiveReasoningEffortOptions,
+  type ReasoningEffortSpec,
+  type ResolvedReasoningEffort,
+} from '@pellux/goodvibes-sdk/platform/providers';
+
+/** The subset of a model this module needs; `ModelDefinition` satisfies it. */
+export interface EffortModelLike {
+  readonly id: string;
+  readonly provider?: string | undefined;
+  readonly displayName?: string | undefined;
+  readonly reasoningEffort?: ReasoningEffortSpec | undefined;
+}
+
+/** Sentence appended wherever a best-guess spec is presented as choices. */
+const FALLBACK_EFFORT_CAVEAT =
+  'Best guess: this model is not in the model catalog, so these levels are unverified and some providers send nothing at all for it.';
+
+/**
+ * Whether a value really is a ReasoningEffortSpec.
+ *
+ * `ModelDefinition.reasoningEffort` used to be a bare `string[]`. A definition
+ * built by older code, restored from an older cache, or supplied by a plugin
+ * can still arrive in that shape, and passing it through as a spec would make
+ * every surface read `.values` off an array and crash. A value that fails this
+ * check is treated as "the model said nothing", which falls through to the
+ * curated family table and then to the labelled best guess.
+ */
+function isReasoningEffortSpec(value: unknown): value is ReasoningEffortSpec {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const record = value as { kind?: unknown; values?: unknown };
+  return typeof record.kind === 'string' && Array.isArray(record.values);
+}
+
+/**
+ * The spec that governs one model, applying the SDK's source precedence
+ * (live catalog, then curated family table, then the labelled best guess).
+ */
+export function effortSpecForModel(model: EffortModelLike): ReasoningEffortSpec {
+  const declared = isReasoningEffortSpec(model.reasoningEffort) ? model.reasoningEffort : undefined;
+  return resolveReasoningEffortSpec({
+    modelId: model.id,
+    ...(declared ? { spec: declared } : {}),
+  });
+}
+
+/** The levels a model actually offers, in severity order. */
+export function effortLevelsForModel(model: EffortModelLike): readonly string[] {
+  return reasoningEffortLevels(effortSpecForModel(model));
+}
+
+/**
+ * Whether a surface should offer an effort CHOICE for this model.
+ *
+ * Stricter than "has levels": a `fallback`-sourced spec is a labelled guess at
+ * a model nothing recognises, and the SDK's OpenAI and Gemini adapters send
+ * nothing at all for such a model. Putting a picker step in front of a choice
+ * that will be discarded is worse than not offering it, so an automatic step
+ * (the model picker's effort stage) is skipped. `/effort`, which the user asked
+ * for explicitly, still lists the guessed levels with their caveat attached.
+ */
+export function offersConfigurableEffort(model: EffortModelLike): boolean {
+  const spec = effortSpecForModel(model);
+  return spec.values.length > 0 && spec.source !== 'fallback';
+}
+
+/**
+ * Publish the current model's real levels to the SDK so a
+ * `provider.reasoningEffort` write is validated against them rather than
+ * against a fixed list. Pass no model to clear.
+ */
+export function publishActiveEffortOptions(model: EffortModelLike | null | undefined): void {
+  if (!model) {
+    setActiveReasoningEffortOptions(null);
+    return;
+  }
+  setActiveReasoningEffortOptions(effortLevelsForModel(model));
+}
+
+/** Map a requested level onto what a model accepts (snapping down, never up). */
+export function resolveEffortForModelSurface(
+  requested: string | undefined,
+  model: EffortModelLike,
+): ResolvedReasoningEffort {
+  return resolveEffortForModel(requested, {
+    id: model.id,
+    ...(model.displayName ? { displayName: model.displayName } : {}),
+    reasoningEffort: effortSpecForModel(model),
+  });
+}
+
+/** One level plus the line describing what choosing it does on this model. */
+export interface EffortChoice {
+  readonly level: string;
+  readonly description: string;
+}
+
+/**
+ * A level's description under a specific spec. Budget-typed models get the
+ * token budget the level actually sends, because "medium" means nothing to a
+ * user comparing it against a `thinking.budget_tokens` figure.
+ */
+function describeEffortLevel(level: string, spec: ReasoningEffortSpec): string {
+  const base = EFFORT_DESCRIPTIONS[level] ?? '';
+  if (spec.kind === 'budget_tokens') {
+    const budget = budgetTokensForLevel(level, spec);
+    const budgetText = budget > 0 ? `${budget.toLocaleString()} thinking tokens` : 'thinking off';
+    return base ? `${base} (${budgetText})` : budgetText;
+  }
+  if (spec.kind === 'toggle') {
+    return level === 'none' ? 'Reasoning off' : 'Reasoning on, at the model\'s own depth';
+  }
+  return base;
+}
+
+/** What a surface needs to present one model's effort options honestly. */
+export interface EffortPresentation {
+  readonly spec: ReasoningEffortSpec;
+  readonly choices: readonly EffortChoice[];
+  /** True when there is nothing to choose and the surface must say so. */
+  readonly configurable: boolean;
+  /** One line stating what this model does with the setting; always present. */
+  readonly headline: string;
+  /** Caveat to show beneath the choices, when the spec carries one. */
+  readonly caveat?: string | undefined;
+}
+
+/** Build the full presentation for a model's effort options. */
+export function effortPresentationForModel(model: EffortModelLike): EffortPresentation {
+  const spec = effortSpecForModel(model);
+  const name = model.displayName ?? model.id;
+  const choices = spec.values.map((level) => ({ level, description: describeEffortLevel(level, spec) }));
+  const caveat = spec.source === 'fallback' ? FALLBACK_EFFORT_CAVEAT : spec.note;
+
+  let headline: string;
+  switch (spec.kind) {
+    case 'effort':
+      headline = `${name} accepts these reasoning levels.`;
+      break;
+    case 'budget_tokens':
+      headline = `${name} takes a thinking-token budget; each level below sends the budget shown.`;
+      break;
+    case 'toggle':
+      headline = `${name} only exposes reasoning on or off — there is no depth to choose.`;
+      break;
+    case 'unavailable':
+      headline = `${name} has no configurable reasoning level; it runs at its own fixed depth.`;
+      break;
+  }
+
+  return {
+    spec,
+    choices,
+    configurable: choices.length > 0,
+    headline,
+    ...(caveat ? { caveat } : {}),
+  };
+}
+
+/**
+ * The `/effort` explainer lines for one model, generated from the resolved
+ * spec. Replaces the old fixed block that named Mercury-2, Claude, Gemini and
+ * GPT-5 for every model regardless of which one was actually serving.
+ */
+export function describeEffortForModel(model: EffortModelLike, current: string | undefined): string[] {
+  const presentation = effortPresentationForModel(model);
+  const { spec } = presentation;
+  const wire = describeReasoningWire(spec, model.provider);
+  const resolved = resolveEffortForModelSurface(current, model);
+
+  const lines = [`Reasoning effort: ${current ?? '(not set)'}`, presentation.headline];
+
+  if (spec.kind === 'unavailable') {
+    lines.push(`  Sent on the wire: ${wire}`);
+    if (presentation.caveat) lines.push(`  ${presentation.caveat}`);
+    return lines;
+  }
+
+  if (resolved.value === undefined) {
+    lines.push(`  Sent on the wire: nothing — ${model.displayName ?? model.id} runs at its own default.`);
+  } else if (spec.kind === 'budget_tokens') {
+    lines.push(`  Sent on the wire: ${wire} = ${budgetTokensForLevel(resolved.value, spec).toLocaleString()}`);
+  } else {
+    lines.push(`  Sent on the wire: ${wire} = '${resolved.value}'`);
+  }
+
+  if (resolved.note) lines.push(`  ${resolved.note}`);
+  lines.push('');
+  for (const choice of presentation.choices) {
+    const marker = choice.level === resolved.value ? '◉' : ' ';
+    lines.push(`  ${marker} ${choice.level.padEnd(8)}${choice.description}`);
+  }
+  if (presentation.caveat && spec.source === 'fallback') {
+    lines.push('');
+    lines.push(`  ${presentation.caveat}`);
+  }
+  return lines;
+}
+
+/**
+ * One line for a non-interactive surface (`goodvibes status`, `goodvibes
+ * doctor`) saying what the configured level becomes on the configured model.
+ *
+ * Printing the raw config value alone was misleading in three separate ways:
+ * a model that does not offer the level receives the next one down, a model
+ * with no configurable reasoning receives nothing, and a model the catalog
+ * does not carry may have the field dropped entirely.
+ *
+ * `registryKey` is the `provider:model` form stored in `provider.model`; a
+ * value without a colon is treated as a bare model id.
+ */
+export function describeConfiguredEffort(registryKey: string, configured: string): string {
+  const trimmed = registryKey.trim();
+  if (trimmed === '') return 'no model configured';
+  const colon = trimmed.indexOf(':');
+  const providerId = colon === -1 ? '' : trimmed.slice(0, colon);
+  const modelId = colon === -1 ? trimmed : trimmed.slice(colon + 1);
+  const model: EffortModelLike = { id: modelId, ...(providerId ? { provider: providerId } : {}) };
+
+  const spec = effortSpecForModel(model);
+  const resolved = resolveEffortForModelSurface(configured === '' ? undefined : configured, model);
+  const wire = describeReasoningWire(spec, providerId);
+
+  if (spec.kind === 'unavailable') return `not sent — ${modelId} has no configurable reasoning level`;
+  if (spec.source === 'fallback') {
+    return `${resolved.value ?? '(model default)'} — unverified: ${modelId} is not in the model catalog, so some providers send nothing for it`;
+  }
+  if (resolved.value === undefined) return `not sent — ${modelId} applies its own default`;
+  if (spec.kind === 'budget_tokens') {
+    return `${resolved.value} (${wire} = ${budgetTokensForLevel(resolved.value, spec).toLocaleString()})`;
+  }
+  if (resolved.value !== configured && configured !== '') {
+    return `${resolved.value} (${wire}) — '${configured}' is not available on ${modelId}`;
+  }
+  return `${resolved.value} (${wire})`;
+}
+
+/**
+ * Re-resolve a configured level against a model that is about to serve, for
+ * the model-switch and failover paths. Returns the level to use and, when it
+ * had to change, the SDK's own sentence explaining why — printed verbatim so
+ * the wording cannot drift from the resolution that produced it.
+ */
+export function remapEffortForServingModel(
+  configured: string | undefined,
+  servingModel: EffortModelLike,
+): { readonly value: string | undefined; readonly note?: string | undefined } {
+  const resolved = resolveEffortForModelSurface(configured, servingModel);
+  const changed = resolved.value !== configured;
+  return {
+    value: resolved.value,
+    ...(changed && resolved.note ? { note: resolved.note } : {}),
+  };
+}
+
+/**
+ * The two levels every effort surface has to keep apart.
+ *
+ * `requested` is what the user asked for and what config `provider.reasoningEffort`
+ * holds. `effective` is what the model now serving will actually receive, which
+ * is `requested` snapped DOWN to that model's own levels (or `undefined` when the
+ * model takes no reasoning parameter at all).
+ */
+export interface ServingEffort {
+  /** The user's stored preference; '' when nothing has ever been chosen. */
+  readonly requested: string;
+  /** What this model receives; undefined means the field is not sent at all. */
+  readonly effective: string | undefined;
+  /** True when the serving model could not honour the requested level. */
+  readonly capped: boolean;
+  /** The SDK's own sentence explaining the snap, when there was one. */
+  readonly note?: string | undefined;
+}
+
+/**
+ * Minimal reader shape for config `provider.reasoningEffort`. A real
+ * ConfigManager satisfies it; a test double can be a one-method object.
+ */
+export interface RequestedEffortReader {
+  get(key: 'provider.reasoningEffort'): unknown;
+}
+
+/**
+ * Read the user's REQUESTED reasoning level.
+ *
+ * This is the ONE place any automatic (model-driven) resolution is allowed to
+ * get its input from, and it deliberately does not consult the session's
+ * effective level. Reading the effective level back as the next resolution's
+ * baseline is what used to make a downgrade permanent: switching to a model
+ * that caps at 'medium' stored 'medium' as the preference, so switching back to
+ * a model that accepts 'xhigh' had nothing left to restore. Config holds what
+ * was asked for; only an explicit user choice writes it.
+ */
+export function requestedEffortLevel(config: RequestedEffortReader): string {
+  const raw = config.get('provider.reasoningEffort');
+  return typeof raw === 'string' ? raw.trim() : '';
+}
+
+/** Resolve an explicit level against the model now serving. */
+export function servingEffortForLevel(requested: string, model: EffortModelLike): ServingEffort {
+  if (requested === '') return { requested, effective: undefined, capped: false };
+  const remapped = remapEffortForServingModel(requested, model);
+  return {
+    requested,
+    effective: remapped.value,
+    capped: remapped.value !== requested,
+    ...(remapped.note ? { note: remapped.note } : {}),
+  };
+}
+
+/**
+ * Resolve the user's REQUESTED level against the model now serving. Every
+ * automatic model-switch path goes through this, so none of them can
+ * accidentally resolve from a previously snapped value.
+ */
+export function resolveRequestedEffortForServingModel(
+  config: RequestedEffortReader,
+  model: EffortModelLike,
+): ServingEffort {
+  return servingEffortForLevel(requestedEffortLevel(config), model);
+}
+
+/**
+ * How an effort level is shown once the requested and effective levels can
+ * differ.
+ *
+ * The stored preference is no longer overwritten with the snapped value, so a
+ * surface that printed the stored level alone would claim 'xhigh' while 'high'
+ * went on the wire. Instead of corrupting the preference to keep the display
+ * honest, the display carries both values and names the model that caps it.
+ * When the two agree, the single value is printed exactly as before.
+ */
+export function describeServingEffort(state: ServingEffort, model: EffortModelLike): string {
+  const name = model.displayName ?? model.id;
+  if (state.requested === '') return '(not set)';
+  if (!state.capped) return state.requested;
+  if (state.effective === undefined) {
+    // Two different reasons the field is dropped, and they must not be
+    // conflated: the model takes no reasoning parameter at all, or it takes one
+    // but offers nothing at or below the requested level (resolution snaps DOWN
+    // only, never up to a costlier level).
+    const reason = effortLevelsForModel(model).length === 0
+      ? `${name} has no configurable reasoning level`
+      : `${name} offers nothing at or below ${state.requested}`;
+    return `(not sent) (requested ${state.requested}; ${reason})`;
+  }
+  return `${state.effective} (requested ${state.requested}; ${name} caps at ${state.effective})`;
+}
+
+/**
+ * Normalize any model-shaped record to what this module consumes.
+ *
+ * Deliberately structural rather than `ModelDefinition`: the model-selection
+ * callback carries a lighter record (id, provider, displayName, registryKey)
+ * and still needs the same resolution.
+ */
+export function toEffortModel(model: EffortModelLike): EffortModelLike {
+  return {
+    id: model.id,
+    provider: model.provider,
+    displayName: model.displayName,
+    ...(model.reasoningEffort ? { reasoningEffort: model.reasoningEffort } : {}),
+  };
+}

package/src/renderer/compositor.ts

@@ -1,6 +1,6 @@
 import { TerminalBuffer } from './buffer.ts';
 import { DiffEngine } from './diff.ts';
-import { type Line, createEmptyCell, createStyledCell } from '../types/grid.ts';
+import { type Line, createEmptyCell, createEmptyLine, createStyledCell } from '../types/grid.ts';
 import { getDisplayWidth } from '../utils/terminal-width.ts';
 import type { SearchManager } from '../input/search.ts';
 import { allowTerminalWrite } from '../runtime/terminal-output-guard.ts';
@@ -70,6 +70,22 @@ export class Compositor {
   private backBuffer: TerminalBuffer | null = null;
   private readonly caps: TermColorCaps;
   private diffEngine: DiffEngine;
+  /**
+   * When true the next composite() repaints the WHOLE screen instead of
+   * diffing against the last frame: erase display, then emit every cell.
+   *
+   * The incremental path is correct only while the front buffer still
+   * describes what is physically on screen. Two things break that assumption:
+   * a buffer reallocation (resize) makes the compositor forget the old frame,
+   * and anything that writes to the terminal outside composite() moves content
+   * the compositor never wrote. After either, a row the model believes is
+   * already blank is never re-emitted, so whatever the terminal is showing
+   * there — splash art, a stale rule line — survives every later frame. The
+   * erase is what clears cells the diff structurally skips (wide-glyph
+   * continuation cells, see DiffEngine.diff), which a diff against a null
+   * front buffer alone cannot do.
+   */
+  private fullRepaintPending = false;
 
   constructor(private stdout: NodeJS.WriteStream) {
     // Probe terminal capabilities once at construction time.
@@ -91,15 +107,40 @@ export class Compositor {
     this.diffEngine.reset();
     this.frontBuffer = null;
     this.backBuffer = null;
+    this.fullRepaintPending = true;
+  }
+
+  /**
+   * Force the next frame to repaint the entire screen exactly once.
+   *
+   * Called at a state transition that replaces one full-screen composition
+   * with another (the splash giving way to the transcript), where any cell the
+   * incremental path leaves behind reads as corruption rather than as a stale
+   * pixel. Unlike resetDiff() this keeps the buffers, so the frame after the
+   * repaint resumes normal differential rendering.
+   */
+  public requestFullRepaint(): void {
+    this.fullRepaintPending = true;
   }
 
   public composite(params: CompositeRequest): void {
     const { width, height, header, viewport, footer, selection, search, panel, panelWidth } = params;
-    // Reuse back-buffer instead of allocating each frame
+    // A size change reallocates the buffer, which drops every record of what
+    // the terminal is currently showing — repaint in full rather than diff
+    // against a model that no longer describes the screen.
+    const resized = this.frontBuffer !== null
+      && (this.frontBuffer.width !== width || this.frontBuffer.height !== height);
+    const fullRepaint = this.fullRepaintPending || resized;
+    this.fullRepaintPending = false;
+    // Reuse back-buffer instead of allocating each frame. A freshly allocated
+    // back buffer is seeded from the front buffer for the same reason reset()
+    // is: rows this frame does not write must keep describing what is on
+    // screen, or the diff will skip them forever.
     if (!this.backBuffer) {
       this.backBuffer = new TerminalBuffer(width, height);
+      if (!fullRepaint) this.backBuffer.reset(width, height, this.frontBuffer);
     } else {
-      this.backBuffer.reset(width, height, this.frontBuffer);
+      this.backBuffer.reset(width, height, fullRepaint ? null : this.frontBuffer);
     }
     const newBuffer = this.backBuffer;
 
@@ -145,9 +186,20 @@ export class Compositor {
       return panel!.bottomFocused ? PANEL_FOCUS_ACCENT : PANEL_BORDER_DIM;
     };
 
-    viewport.forEach((line, i) => {
+    // Every body row is written every frame, including rows the caller did not
+    // supply a line for. A viewport array shorter than the body (a docked
+    // overlay reserves a bottom inset, an overlay-row reservation overshoots
+    // what actually rendered) used to leave those rows untouched: the buffer
+    // then described them as blank while the terminal still showed the
+    // previous composition there, and since a blank-over-blank blit is a no-op
+    // no later frame ever repainted them. Supplying a blank line keeps the
+    // model and the screen in agreement.
+    const blankRow = createEmptyLine(width);
+    const bodyRows = Math.max(viewport.length, vHeight);
+    for (let i = 0; i < bodyRows; i++) {
+      const line = viewport[i] ?? blankRow;
       const screenY = viewportStartY + i;
-      if (screenY >= height) return;
+      if (screenY >= height) break;
 
       if (!hasPanel) {
         // No panel: existing fast path
@@ -264,16 +316,9 @@ export class Compositor {
           }
         }
       }
-    });
-
-    // Draw separator on remaining viewport rows past content (when panel is active)
-    if (hasPanel && panel!.separator) {
-      for (let i = viewport.length; i < vHeight; i++) {
-        const screenY = viewportStartY + i;
-        if (screenY >= height) break;
-        newBuffer.setCell(sepX, screenY, createStyledCell('│', { fg: borderFgForRow(i) }));
-      }
     }
+    // (rows past the supplied viewport lines are covered by the loop above,
+    // separator column included, so they can no longer keep a stale frame.)
 
     // 3. Draw Footer (Pinned to Bottom) — always full width
     const footerStart = height - footer.length;
@@ -284,10 +329,15 @@ export class Compositor {
     });
 
     // 4. Diff and Render
-    // Diff against front-buffer (last-rendered), then swap front/back — no clone() needed
-    const diff = this.diffEngine.diff(this.frontBuffer, newBuffer);
-    if (diff) {
-      allowTerminalWrite(() => this.stdout.write(diff));
+    // Diff against front-buffer (last-rendered), then swap front/back — no clone() needed.
+    // On a full repaint the SGR run-state is reset (the erase below leaves the
+    // terminal's attributes unknown) and the diff runs against no previous
+    // frame, so every cell of the grid is emitted.
+    if (fullRepaint) this.diffEngine.reset();
+    const diff = this.diffEngine.diff(fullRepaint ? null : this.frontBuffer, newBuffer);
+    const payload = fullRepaint ? `\x1b[H\x1b[2J${diff}` : diff;
+    if (payload) {
+      allowTerminalWrite(() => this.stdout.write(payload));
     }
 
     // Swap: back (just written) becomes the new front reference; old front becomes the next back

package/src/renderer/header-line.ts

@@ -0,0 +1,146 @@
+/**
+ * header-line.ts — the top-of-screen header row: brand, version, optional
+ * conversation title, optional git segment, and the right-hand model/provider
+ * pair.
+ *
+ * Extracted from ui-factory.ts (which sits on the 800-line source gate) when
+ * the header gained the failover divergence marker. `UIFactory.createHeader`
+ * remains the call name everywhere and delegates here.
+ *
+ * The model/provider pair rendered here is the SERVING backend, resolved by
+ * core/active-model-identity.ts — the same resolution the footer uses, so the
+ * two surfaces can no longer disagree about who is answering. `note` carries
+ * the divergence marker naming the user's configured selection when serving
+ * has moved off it.
+ */
+
+import { type Line, createEmptyLine } from '../types/grid.ts';
+import { VERSION } from '../version.ts';
+import { getDisplayWidth } from '../utils/terminal-width.ts';
+import type { GitHeaderInfo } from './git-status.ts';
+import { activeUiTones } from './theme.ts';
+
+/** Build the git segment string and its display width. Single source of truth for header layout. */
+function buildGitSegment(gitInfo: GitHeaderInfo): { text: string; width: number } {
+  const branch = ` git:${gitInfo.branch}`;
+  if (gitInfo.dirty) {
+    const text = `${branch} * `;
+    return { text, width: getDisplayWidth(text) };
+  }
+  if (gitInfo.ahead > 0 || gitInfo.behind > 0) {
+    const arrows = (gitInfo.ahead > 0 ? ` +${gitInfo.ahead}` : '') + (gitInfo.behind > 0 ? ` -${gitInfo.behind}` : '');
+    const text = `${branch}${arrows} `;
+    return { text, width: getDisplayWidth(text) };
+  }
+  const text = `${branch} `;
+  return { text, width: getDisplayWidth(text) };
+}
+
+/**
+ * Pick the widest divergence marker that still fits beside the brand and the
+ * model/provider pair.
+ *
+ * Graded, never truncated mid-word: the full marker (which names the
+ * configured selection) is preferred; a bare "divergent" keyword is the
+ * fallback on a narrow terminal; on a very narrow terminal the marker is
+ * dropped entirely. Dropping it is safe — what remains is still the SERVING
+ * backend, so the header never claims the configured backend is answering.
+ * The footer carries the full marker with far more room (see ui-factory's
+ * prioritized context segments).
+ */
+function fitHeaderNote(note: string, usedWidth: number, width: number): string {
+  if (!note) return '';
+  const full = `· ${note} `;
+  if (usedWidth + getDisplayWidth(full) <= width) return full;
+  const short = '· divergent ';
+  return usedWidth + getDisplayWidth(short) <= width ? short : '';
+}
+
+/**
+ * Render the header row plus its underline.
+ *
+ * @param width    - Terminal columns.
+ * @param model    - Serving model id (already resolved; see file doc).
+ * @param provider - Serving provider id.
+ * @param title    - Optional conversation title, truncated to fit.
+ * @param gitInfo  - Optional git branch/dirty/ahead-behind segment.
+ * @param version  - Defaults to the live build VERSION; tests pass a pinned
+ *                   fixture so golden snapshots survive release bumps.
+ * @param note     - Divergence marker naming the configured selection when the
+ *                   serving backend is not the one the user chose; '' otherwise.
+ */
+export function renderHeaderLine(
+  width: number,
+  model: string,
+  provider: string,
+  title?: string,
+  gitInfo?: GitHeaderInfo,
+  version: string = VERSION,
+  note: string = '',
+): Line[] {
+  const lines: Line[] = [];
+  // Header/footer/thinking paint on the transparent terminal background, so
+  // they read chrome.* (light-terminal-aware) — NOT fg.*/state.*, which stay
+  // tuned for the opaque dark modal/panel boxes. Read live per render so a
+  // mode flip re-resolves without any module reload (see theme.ts).
+  const t = activeUiTones();
+  const CYAN = t.accent.brand;
+  const GREY = t.chrome.faint;
+  const TITLE_COLOR = t.chrome.label;
+  const brand = ` GoodVibes `;
+  const ver = `v${version} `;
+  const stats = ` ${model} `;
+  const prov = `(${provider}) `;
+  const gitWidth = gitInfo ? buildGitSegment(gitInfo).width : 0;
+  // Resolve the marker before the title so the title's fit calculation
+  // reserves room for it too.
+  const noteStr = fitHeaderNote(note, getDisplayWidth(brand + ver + stats + prov) + gitWidth, width);
+  const line = createEmptyLine(width);
+  let curX = 0;
+  for (const char of brand) { line[curX++] = { char, fg: CYAN, bg: '', bold: true, dim: false, underline: false, italic: false, strikethrough: false }; }
+  for (const char of ver) { line[curX++] = { char, fg: GREY, bg: '', bold: false, dim: true, underline: false, italic: false, strikethrough: false }; }
+  // Optional conversation title — shown after brand/ver, truncated to fit
+  if (title) {
+    const titleStr = `│ ${title} `;
+    // Reserve space for git info (if present) + model/provider + marker on the right
+    const rightReserved = getDisplayWidth(stats + prov + noteStr) + gitWidth;
+    const maxTitleW = width - curX - rightReserved - 1;
+    let displayTitle: string;
+    if (getDisplayWidth(titleStr) <= maxTitleW) {
+      displayTitle = titleStr;
+    } else {
+      let truncated = '';
+      let w = 0;
+      for (const ch of titleStr) {
+        const cw = getDisplayWidth(ch);
+        if (w + cw > maxTitleW - 3) { truncated += '...'; break; }
+        truncated += ch;
+        w += cw;
+      }
+      displayTitle = truncated;
+    }
+    for (const char of displayTitle) { if (curX < width) line[curX++] = { char, fg: TITLE_COLOR, bg: '', bold: false, dim: true, underline: false, italic: false, strikethrough: false }; }
+  }
+  // Build git info segment
+  let gitStr = '';
+  let gitFg: string = t.chrome.faint;
+  if (gitInfo) {
+    gitStr = buildGitSegment(gitInfo).text;
+    if (gitInfo.dirty || gitInfo.ahead > 0 || gitInfo.behind > 0) {
+      gitFg = t.chrome.warn; // yellow when dirty or out-of-sync
+    }
+  }
+  const rightSideW = getDisplayWidth(stats + prov + noteStr) + getDisplayWidth(gitStr);
+  let rightX = width - rightSideW;
+  for (const char of gitStr) { if (rightX >= 0 && rightX < width) line[rightX++] = { char, fg: gitFg, bg: '', bold: false, dim: !gitInfo?.dirty && !(gitInfo?.ahead || gitInfo?.behind), underline: false, italic: false, strikethrough: false }; }
+  for (const char of stats) { if (rightX < width) line[rightX++] = { char, fg: CYAN, bg: '', bold: true, dim: false, underline: false, italic: false, strikethrough: false }; }
+  for (const char of prov) { if (rightX < width) line[rightX++] = { char, fg: GREY, bg: '', bold: false, dim: true, underline: false, italic: false, strikethrough: false }; }
+  // The marker reads as a warning, not as chrome: serving has left the
+  // selection the user made and that is worth noticing.
+  for (const char of noteStr) { if (rightX >= 0 && rightX < width) line[rightX++] = { char, fg: t.chrome.warn, bg: '', bold: false, dim: false, underline: false, italic: false, strikethrough: false }; }
+  lines.push(line);
+  const underline = createEmptyLine(width);
+  for (let x = 0; x < width; x++) underline[x] = { char: '━', fg: t.chrome.faint, bg: '', bold: false, dim: false, underline: false, italic: false, strikethrough: false };
+  lines.push(underline);
+  return lines;
+}