@pellux/goodvibes-tui 1.20.0 → 1.20.1

package/src/core/stream-event-wiring.ts

@@ -2,6 +2,8 @@ import type { UiRuntimeEvents } from '@/runtime/index.ts';
 import { createStreamStallWatchdog } from './stream-stall-watchdog.ts';
 import { buildRoutingChip } from './model-routing-chip.ts';
 import { formatUserFacingErrorLine } from './format-user-error.ts';
+import { classifyProviderSetup } from '../providers/provider-classification.ts';
+import type { FailoverTurnState } from './active-model-identity.ts';
 import { logger } from '@pellux/goodvibes-sdk/platform/utils';
 
 /**
@@ -101,6 +103,14 @@ interface FailoverOptimizer {
 interface StreamSystemMessageRouter {
   high(message: string): void;
   low(message: string): void;
+  /**
+   * Unconditional conversation delivery (see system-message-router.ts). Used
+   * for provider-switch notices: which backend serves a turn — and therefore
+   * who bills for it — is never ambient chatter that a routing preference or
+   * the noise gate may filter out. Optional so bare test doubles that supply
+   * only high/low still type-check; announce() below falls back to high().
+   */
+  userReceipt?(message: string): void;
 }
 
 /**
@@ -166,8 +176,15 @@ export interface WireStreamEventMetricsOptions {
    * Callback the caller provides to re-submit the last user turn on a
    * different provider after a successful failover switch.  Called only when
    * the optimizer is enabled and a viable next provider exists in the chain.
+   *
+   * The re-submission rolls the conversation back to its pre-submission
+   * message count, which deletes everything the failed turn added — including
+   * a failover notice appended before the call. So the notice is passed IN
+   * rather than emitted before: the caller re-posts it after its rollback, and
+   * it survives to be read. Implementations that do not roll back may ignore
+   * the argument, but must then post the notice themselves.
    */
-  readonly retryTurn?: () => void;
+  readonly retryTurn?: (notice?: string) => void;
   /**
    * Optional cost catalog for attaching per-1M-token cost information to
    * the failover notice.  When provided and both models have non-zero pricing,
@@ -189,6 +206,22 @@ export interface WireStreamEventMetricsOptions {
    * callers omit it.
    */
   readonly stallThresholdMs?: number | undefined;
+  /**
+   * Shared holder for the live failover record (core/active-model-identity.ts).
+   * Set when failover switches the registry off the user's configured
+   * selection, cleared once serving is restored to it. The render frame reads
+   * the same object, so the header and footer describe the switch while it is
+   * in effect. Omitted by unit tests that only exercise notice content.
+   */
+  readonly failoverState?: FailoverTurnState;
+  /**
+   * The user's configured model selection (config `provider.model`) as a
+   * registry key. Read at the moment of a failover switch so the turn-end
+   * restore targets what the user actually chose — not whatever the registry
+   * happened to hold. Without it, failover still works but no restore or
+   * divergence marker is possible, so both are skipped rather than guessed at.
+   */
+  readonly getConfiguredRegistryKey?: () => string | undefined;
 }
 
 /** Result of wireStreamEventMetrics. */
@@ -196,10 +229,12 @@ export interface WireStreamEventMetricsResult {
   /** Unsubscribe functions; push into the parent unsubs array for cleanup on exit. */
   readonly unsubs: ReadonlyArray<() => void>;
   /**
-   * Clear the per-turn failover visited-provider set.
-   * Call this on every new user submission so the visited set does not bleed
-   * across independent turns (the set is also cleared automatically on
-   * TURN_COMPLETED, but a new submission may arrive before TURN_COMPLETED fires).
+   * Clear the per-turn failover visited-provider set AND restore the user's
+   * configured model selection if a failover left serving somewhere else.
+   * Call this on every new user submission so neither the visited set nor a
+   * per-turn provider switch bleeds across independent turns (both are also
+   * handled on TURN_COMPLETED/TURN_CANCEL, but a new submission may arrive
+   * before either fires).
    */
   readonly clearFailoverVisited: () => void;
   /**
@@ -253,6 +288,33 @@ function buildCostDeltaSuffix(
   return ` [cost/1M: input ${fmt(fromCost.input)}→${fmt(toCost.input)}, output ${fmt(fromCost.output)}→${fmt(toCost.output)}]`;
 }
 
+/**
+ * Build the billing-class segment of a failover notice, e.g.
+ * ` [billing: API key → Subscription — billing class changed]`.
+ *
+ * This path is NOT the synthetic provider's tier-isolated failover, which is
+ * where the documented "free, paid and subscription tiers never mix" contract
+ * lives (docs/providers-and-routing.md:77-128, enforced in the SDK's
+ * synthetic.ts by CanonicalModel.tier). The optimizer chain consumed here
+ * carries no tier metadata at all — its nodes are
+ * `{ position, providerId, modelId, capable, explanation }` and `explanation`
+ * describes functional capability (streaming, tool calling, context size),
+ * never billing. So the switch cannot be constrained by a tier it cannot see;
+ * what it CAN do is say out loud which billing class it moved to, so a user
+ * who does not want their subscription spent on an automatic retry can object
+ * and turn the optimizer off.
+ *
+ * Classification comes from providers/provider-classification.ts, which is
+ * honest about ignorance: an unrecognised provider id reports "Unknown" rather
+ * than being quietly assumed safe.
+ */
+function buildBillingSuffix(fromProviderId: string, toProviderId: string): string {
+  const from = classifyProviderSetup({ providerId: fromProviderId }).setupLabel;
+  const to = classifyProviderSetup({ providerId: toProviderId }).setupLabel;
+  const changed = from !== to ? ' — billing class changed' : '';
+  return ` [billing: ${from} → ${to}${changed}]`;
+}
+
 /**
  * Wire STREAM_* and TOOL_* runtime events to the provided StreamMetrics object
  * and install the stream-stall watchdog.  The caller owns the metrics object
@@ -273,11 +335,73 @@ export function wireStreamEventMetrics(
   const {
     events, metrics, orchestrator, providerRegistry,
     systemMessageRouter, render, providerOptimizer, retryTurn, costLookup,
-    isApprovalPending, stallThresholdMs,
+    isApprovalPending, stallThresholdMs, failoverState, getConfiguredRegistryKey,
   } = options;
 
   const unsubs: Array<() => void> = [];
 
+  /**
+   * Deliver a provider-switch notice to the conversation unconditionally.
+   * Prefers the router's userReceipt channel, which skips the noise gate and
+   * the ui.operationalMessages routing target entirely, so the line cannot be
+   * filtered away by a preference and is treated as real content even while
+   * the splash still owns the screen. Falls back to high() for bare doubles.
+   */
+  const announce = (message: string): void => {
+    if (systemMessageRouter.userReceipt) systemMessageRouter.userReceipt(message);
+    else systemMessageRouter.high(message);
+  };
+
+  /**
+   * Put serving back on the user's configured selection after a failed-over
+   * turn ends.
+   *
+   * Failover is per-turn recovery, not a permanent re-selection. Without this,
+   * the one setCurrentModel() call that rescued a single failed turn stayed in
+   * force for the rest of the session: every later turn ran on the fallback
+   * backend while nothing in the session state or the footer had changed to
+   * say so. The user's configured selection is authoritative, so the NEXT turn
+   * starts from it again. If that backend is still unhealthy, the normal
+   * per-turn failover handles it again — visibly, with a fresh notice — which
+   * is exactly the behaviour a sticky override was hiding.
+   *
+   * The record is kept (not cleared) when the restore itself fails, so the
+   * header and footer keep reporting the real serving backend rather than
+   * claiming a revert that did not happen.
+   */
+  /**
+   * The registry key the restore below is switching back to, held only across
+   * that one setCurrentModel call. The MODEL_CHANGED listener reads it to keep
+   * the routing chip quiet for this change: the chip's copy is "reason
+   * unknown", which would be false here — the reason is known and the
+   * `[Failover] Restored …` line states it.
+   */
+  let pendingRestoreKey: string | null = null;
+
+  const restoreConfiguredSelection = (): void => {
+    const record = failoverState?.current();
+    if (!record || !failoverState) return;
+    if (providerRegistry.getCurrentModel().registryKey === record.configuredRegistryKey) {
+      failoverState.clear();
+      return;
+    }
+    try {
+      pendingRestoreKey = record.configuredRegistryKey;
+      providerRegistry.setCurrentModel(record.configuredRegistryKey);
+      failoverState.clear();
+      announce(`[Failover] Restored ${record.configuredRegistryKey} for the next turn.`);
+    } catch (restoreErr) {
+      pendingRestoreKey = null;
+      logger.debug('failover restore failed', {
+        configuredRegistryKey: record.configuredRegistryKey, error: String(restoreErr),
+      });
+      announce(
+        `[Failover] Could not switch back to ${record.configuredRegistryKey}; still serving ${record.servingRegistryKey}.`,
+      );
+    }
+    render();
+  };
+
   unsubs.push(events.turns.on('STREAM_START', () => {
     metrics.startTime = Date.now();
     metrics.deltaCount = 0;
@@ -318,8 +442,20 @@ export function wireStreamEventMetrics(
   // (caller clears via clearFailoverVisited(), wired in main.ts).
   const failoverVisited = new Set<string>();
 
+  // Both terminal turn outcomes end the failover's authority over the
+  // registry: a completed turn got its answer, a cancelled one will not.
+  // (TURN_COMPLETED and TURN_ERROR are mutually exclusive per turn in the SDK
+  // — TURN_COMPLETED is emitted only on the success path in
+  // orchestrator-turn-helpers, TURN_ERROR only from the orchestrator's catch —
+  // so restoring here can never undo a switch whose retry has not run yet.)
   unsubs.push(events.turns.on('TURN_COMPLETED', () => {
     failoverVisited.clear();
+    restoreConfiguredSelection();
+  }));
+
+  unsubs.push(events.turns.on('TURN_CANCEL', () => {
+    failoverVisited.clear();
+    restoreConfiguredSelection();
   }));
 
   // Routing chip (never-silent model change): every MODEL_CHANGED that is not
@@ -330,6 +466,11 @@ export function wireStreamEventMetrics(
   // Degrade gracefully when a bare test double omits the providers feed.
   if (events.providers) {
     unsubs.push(events.providers.on('MODEL_CHANGED', (change) => {
+      // Listeners run synchronously inside setCurrentModel, so this reads the
+      // restore flag before anything else can touch it.
+      const wasRestore = pendingRestoreKey !== null && change.registryKey === pendingRestoreKey;
+      pendingRestoreKey = null;
+      if (wasRestore) return;
       queueMicrotask(() => {
         const chip = buildRoutingChip(change, providerOptimizer?.fallbackLog ?? [], Date.now());
         if (chip === null) return;
@@ -373,30 +514,45 @@ export function wireStreamEventMetrics(
         try {
           providerRegistry.setCurrentModel(toRegistryKey);
         } catch (switchErr) {
-          // Switch failed — fall through to honest error display.
+          // Switch failed — fall through to honest error display. This ends the
+          // turn, so an EARLIER hop's switch (if this is a second failover
+          // within the same turn) loses its authority here just as it would on
+          // any other terminal outcome.
           logger.debug('failover setCurrentModel failed', { toRegistryKey, error: String(switchErr) });
           systemMessageRouter.high(`[Error] ${errorClass}`);
+          restoreConfiguredSelection();
           render();
           return;
         }
         // Record the selected provider as visited before the retry fires so
         // a subsequent TURN_ERROR from that provider also skips it.
         failoverVisited.add(next.providerId);
+        // Remember the user's configured selection so the turn-end restore
+        // targets it, and so both shell surfaces can name it while the switch
+        // is in force. Sticky across a second hop within the same turn.
+        const configuredRegistryKey = getConfiguredRegistryKey?.();
+        if (configuredRegistryKey) {
+          failoverState?.begin({ configuredRegistryKey, servingRegistryKey: toRegistryKey });
+        }
         providerOptimizer.recordFallbackTransition(fromProvider, next.providerId, errorClass);
         const costSuffix = buildCostDeltaSuffix(costLookup, fromRegistryKey, toRegistryKey);
-        systemMessageRouter.high(
-          `[Failover] ${fromProvider} -> ${next.providerId} (${errorClass})${costSuffix}`,
-        );
+        const billingSuffix = buildBillingSuffix(fromProvider, next.providerId);
+        // Re-submit the last user turn on the new provider, handing the notice
+        // to retryTurn so it outlives that call's transcript rollback (see the
+        // retryTurn option doc). Emitting it here instead would delete it.
+        retryTurn(`[Failover] ${fromProvider} -> ${next.providerId} (${errorClass})${billingSuffix}${costSuffix}`);
         render();
-        // Re-submit the last user turn on the new provider.
-        retryTurn();
         return;
       }
 
       // Chain exhausted — all capable candidates have been visited or none exist.
-      systemMessageRouter.high(
+      // The turn is over, so any switch made earlier in it loses its authority:
+      // restore the configured selection before surfacing the error, or the
+      // user's next turn would silently start on the last fallback tried.
+      announce(
         `[Failover] Chain exhausted — no alternative provider available. Original error: ${formatUserFacingErrorLine(errVal)}`,
       );
+      restoreConfiguredSelection();
       notifyErrorSurfaced(true);
       render();
       return;
@@ -494,7 +650,11 @@ export function wireStreamEventMetrics(
   function notifyErrorSurfaced(exhausted: boolean) { _errorSurfacedCb?.(exhausted); }
   return {
     unsubs,
-    clearFailoverVisited: () => failoverVisited.clear(),
+    // A new user submission is also a turn boundary: restore here too, so a
+    // turn that ended without any terminal event (an aborted stream that
+    // emitted neither TURN_COMPLETED nor TURN_CANCEL) still cannot leave the
+    // next turn silently pinned to a fallback backend.
+    clearFailoverVisited: () => { failoverVisited.clear(); restoreConfiguredSelection(); },
     onErrorSurfaced: (cb: (exhausted: boolean) => void) => { _errorSurfacedCb = cb; },
   };
 }

package/src/core/system-message-router.ts

@@ -224,6 +224,28 @@ export class SystemMessageRouter {
   wrfc(message: string, priority: SystemMessagePriority = 'high'): void {
     this.routeTypedSystemMessage(message, priority, 'wrfc');
   }
+
+  /**
+   * Route a message that must reach the conversation unconditionally. Skips
+   * the noise gate and the configured routing target, and marks the message
+   * `isUserReceipt` so the splash check in
+   * ConversationManager.rebuildHistory() treats it as real visible content —
+   * otherwise it would be invisible while the splash still owns the screen.
+   *
+   * Two callers qualify today:
+   *   - a receipt for an explicit user action at this shell (answering the
+   *     startup recovery modal's Resume/Keep/Remove choice): the answer to a
+   *     question the user was just asked, never ambient chatter;
+   *   - an automatic provider failover switch (stream-event-wiring.ts):
+   *     which backend serves a turn decides who bills for it, so it must not
+   *     be filterable by a routing preference. `[Failover]` is also in
+   *     FORCE_CONVERSATION_PREFIXES, but that list is a per-prefix opt-in
+   *     applied AFTER the noise gate; this channel is the structural
+   *     guarantee rather than a second string match.
+   */
+  userReceipt(message: string): void {
+    this.conversation.addTypedSystemMessage(message, classifySystemMessageKind(message), { isUserReceipt: true });
+  }
 }
 
 // ---------------------------------------------------------------------------

package/src/main.ts

@@ -24,7 +24,8 @@ import { getTierPromptSupplement, getTierForContextWindow } from '@pellux/goodvi
 import { GitStatusProvider } from './renderer/git-status.ts';
 import type { GitHeaderInfo } from './renderer/git-status.ts';
 import { createShellLayout } from './renderer/layout-engine.ts';
-import { buildShellFooter, estimateShellFooterHeight } from './renderer/shell-surface.ts';
+import { buildShellFooter, estimateShellFooterHeight, promptCursorOffset } from './renderer/shell-surface.ts';
+import { createFailoverTurnState, resolveActiveModelDisplay } from './core/active-model-identity.ts';
 import { computePromptContentWidth } from './renderer/prompt-content-width.ts';
 import { buildConversationViewport } from './renderer/conversation-layout.ts';
 import { applyConversationOverlays } from './renderer/conversation-overlays.ts';
@@ -178,6 +179,8 @@ async function main() {
   let lastMaxScroll: number | null = null;
   // Stream and tool-timer state; mutated by wireStreamEventMetrics handlers, read during render.
   const streamMetrics: StreamMetrics = createStreamMetrics();
+  // Live failover record — written by the failover path, read every frame so the header and footer agree.
+  const failoverState = createFailoverTurnState();
 
   const getPromptContentWidth = () => computePromptContentWidth(stdout.columns);
 
@@ -454,10 +457,9 @@ async function main() {
     const sessionSnapshot = uiServices.readModels.session.getSnapshot();
     const agentSnapshot = uiServices.readModels.agents.getSnapshot();
 
-    const headerLines = UIFactory.createHeader(width, currentModel.id, currentModel.provider, conversation.title || undefined, lastGitInfoRef.value);
-    const managerAgents = agentManager.list().filter(
-      (a) => a.status === 'running' || a.status === 'pending',
-    );
+    const activeModel = resolveActiveModelDisplay({ serving: currentModel, configuredRegistryKey: configManager.get('provider.model') as string, configuredLabel: runtime.model, configuredProvider: runtime.provider, failover: failoverState.current() });
+    const headerLines = UIFactory.createHeader(width, activeModel.headerModel, activeModel.headerProvider, conversation.title || undefined, lastGitInfoRef.value, undefined, activeModel.divergenceNote);
+    const managerAgents = agentManager.list().filter((a) => a.status === 'running' || a.status === 'pending');
     const runtimeAgents = agentSnapshot.active;
     const runningAgentSummary = summarizeRunningAgents(managerAgents, runtimeAgents, ctx.services.wrfcController.listChains());
     const runningAgentCount = runningAgentSummary.count;
@@ -470,30 +472,24 @@ async function main() {
       commandMode: input.commandMode,
       panelFocused: input.panelFocused,
       pendingApproval: pendingPermission !== null,
-      hasAttachments: input.getImageAttachments().size > 0,
-      turnState: sessionSnapshot.turnState,
+      hasAttachments: input.getImageAttachments().size > 0, turnState: sessionSnapshot.turnState,
     });
     const contextStatusHint = resolveContextStatusHint({
       evaluate: (args) => evaluateSessionMaintenance({ configManager, ...args, sessionMemoryCount: ctx.services.sessionMemoryStore.list().length }),
-      currentTokens: orchestrator.lastInputTokens,
-      contextWindow,
+      currentTokens: orchestrator.lastInputTokens, contextWindow,
     });
     const footerLines = buildShellFooter({
       width,
       promptText: promptInfo.visibleLines.join('\n'),
       promptLineCount: promptInfo.visibleLines.length,
-      promptCursorPos: promptInfo.visibleCursorLine >= 0
-        ? promptInfo.visibleLines
-          .slice(0, promptInfo.visibleCursorLine)
-          .reduce((sum: number, line: string) => sum + line.length + 1, 0) + promptInfo.visibleCursorCol
-        : undefined,
+      promptCursorPos: promptCursorOffset(promptInfo),
       usage: { up: orchestrator.usage.input, down: orchestrator.usage.output, fleetCostUsd: footerFleetCost(() => ctx.services.processRegistry.query().nodes, runningAgentCount > 0) },
       showExitNotice: input.showExitNotice,
       lastCopyTime: input.lastCopyTime,
-      model: runtime.model,
+      model: activeModel.footerModel, modelNote: activeModel.divergenceNote,
       toolCount: toolRegistry.list().length,
       workingDir,
-      provider: runtime.provider,
+      provider: activeModel.footerProvider,
       contextWindow,
       contextStatusHint,
       retryHint: retryAffordanceHint(retryAffordance),
@@ -709,17 +705,22 @@ async function main() {
   // Time-bounded: onExpire repaints once the 60s disarm timer fires, so a stray keypress hours
   // later can never trigger a real retry — see retry-affordance.ts.
   const retryAffordance = createRetryAffordanceState({ onExpire: render });
-  const retryTurn = (): void => {
+  const retryTurn = (notice?: string): void => {
     if (!retryCtx) return;
     const { count, text, content: rContent, opts: rOpts } = retryCtx;
     // Roll back to pre-submission count, then re-submit. SDK gap — no retry-in-place (see handoff).
+    // The rollback erases the failed turn's transcript — the failover notice included, which is how
+    // that notice used to vanish before anyone could read it. The caller hands it over instead, and
+    // it is posted here: after the rollback, above the prompt it explains.
     conversation.removeMessagesAfter(count);
+    if (notice) systemMessageRouter.userReceipt(notice);
     void refreshMemoryRecallSnapshot(ctx.services).then(() => orchestrator.handleUserInput(text, rContent, rOpts)).catch((e: unknown) => logger.debug('retryTurn', { error: summarizeError(e) }));
   };
   const streamResult: WireStreamEventMetricsResult = wireStreamEventMetrics({
     events: uiServices.events, orchestrator, providerRegistry,
     systemMessageRouter, render, metrics: streamMetrics,
     providerOptimizer: ctx.services.providerOptimizer, costLookup: providerRegistry, retryTurn,
+    failoverState, getConfiguredRegistryKey: () => configManager.get('provider.model') as string | undefined,
     isApprovalPending: () => pendingPermission !== null,
   });
   unsubs.push(...streamResult.unsubs);
@@ -743,7 +744,7 @@ async function main() {
   const themeProbe = installBackgroundThemeProbe({ configManager, isTTY: Boolean(stdout.isTTY), env: process.env, writeQuery: (b) => allowTerminalWrite(() => stdout.write(b)), requestRepaint: () => { compositor.resetDiff(); render(); } });
 
   // continueRecovery lets --continue/bare --resume check the target session for a live crash snapshot newer than its store before resuming (see tui-startup.ts).
-  applyInitialTuiCliState({ cli, input, commandRegistry, commandContext, shellPaths: ctx.services.shellPaths, surface: ctx.services.surface, render, continueRecovery: { sessionManager: ctx.services.sessionManager, runtime, conversation, writeLastSessionPointer, receipt: (line) => systemMessageRouter.high(line) } });
+  applyInitialTuiCliState({ cli, input, commandRegistry, commandContext, shellPaths: ctx.services.shellPaths, surface: ctx.services.surface, render, continueRecovery: { sessionManager: ctx.services.sessionManager, runtime, conversation, writeLastSessionPointer, receipt: (line) => systemMessageRouter.userReceipt(line) } });
 
   stdin.on('data', (raw: string) => {
     const data = themeProbe.filterInput(raw); if (data.length === 0) return;
@@ -788,7 +789,7 @@ async function main() {
   // frame so the question is drawn rather than posed at a blank terminal.
   scheduleRecoveryOffer(buildRecoveryOfferWiring({
     surface: ctx.services.surface, sessionManager: ctx.services.sessionManager, runtime, conversation, commandContext,
-    writeLastSessionPointer, receipt: (line) => systemMessageRouter.high(line), render,
+    writeLastSessionPointer, receipt: (line) => systemMessageRouter.userReceipt(line), render,
   }));
 
   // Auto-save to recovery file every 60s + multi-instance liveness-marker

package/src/{cli → providers}/provider-classification.ts

@@ -1,3 +1,15 @@
+/**
+ * provider-classification.ts — how a provider is paid for: a raw API key, a
+ * cloud account, a stored subscription/OAuth session, a local runtime, or
+ * honestly unknown.
+ *
+ * Lives in the foundation `providers` layer (it imports nothing) because both
+ * the CLI management surfaces and the in-session failover notice need it: when
+ * automatic failover moves a turn onto a different backend, the notice names
+ * the billing class it moved from and to, so a switch from a metered API key
+ * onto the user's own subscription is something the user can see and object to
+ * rather than discover on an invoice.
+ */
 export type ProviderSetupClass =
   | 'api-key'
   | 'cloud-account'

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;
+}

package/src/renderer/shell-surface.ts

@@ -19,6 +19,13 @@ export interface ShellFooterBuildOptions {
   readonly showExitNotice: boolean;
   readonly lastCopyTime: number;
   readonly model?: string;
+  /**
+   * Divergence marker appended to the model segment while the serving backend
+   * is not the user's configured selection (core/active-model-identity.ts),
+   * e.g. "failover from abacusai:route-llm". Absent/empty in the normal case,
+   * where the context-info line renders exactly as it always has.
+   */
+  readonly modelNote?: string;
   readonly toolCount?: number;
   readonly workingDir?: string;
   readonly provider?: string;
@@ -112,6 +119,34 @@ const DIM_STATUS_FG = '#64748b';
  */
 let lastRenderedFooterHeight: { compact: boolean; height: number } | null = null;
 
+/**
+ * The wrapped-prompt shape the composer reports each frame — the subset
+ * promptCursorOffset needs (see InputHandler.getWrappedPromptInfo).
+ */
+export interface WrappedPromptCursorInfo {
+  readonly visibleLines: readonly string[];
+  readonly visibleCursorLine: number;
+  readonly visibleCursorCol: number;
+}
+
+/**
+ * Flatten a wrapped-prompt cursor position (line + column) into the single
+ * character offset createFooter's `cursorPos` expects, counting one separator
+ * per wrapped line. Returns undefined when the cursor is not on a visible line
+ * (scrolled out of the composer's window), which suppresses the cursor overlay
+ * rather than drawing it in the wrong place.
+ *
+ * Lives here rather than inline at the render site so main.ts (a composition
+ * root already at the source-line gate) stays a wiring file.
+ */
+export function promptCursorOffset(info: WrappedPromptCursorInfo): number | undefined {
+  if (info.visibleCursorLine < 0) return undefined;
+  const precedingChars = info.visibleLines
+    .slice(0, info.visibleCursorLine)
+    .reduce((sum: number, line: string) => sum + line.length + 1, 0);
+  return precedingChars + info.visibleCursorCol;
+}
+
 export function estimateShellFooterHeight(
   promptLineCount: number,
   contextWindow?: number,
@@ -158,6 +193,7 @@ export function buildShellFooter(
     options.permissionMode,
     options.webSurfaceUrl,
     options.powerKeepAwake,
+    options.modelNote,
   );
   // Compact posture drops the process indicator and context hint entirely so
   // the footer fits within ~5 rows on short terminals.