@pellux/goodvibes-tui 0.23.0 → 0.24.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-tui",
-  "version": "0.23.0",
+  "version": "0.24.1",
   "description": "Terminal-native GoodVibes product for coding, operations, automation, knowledge, channels, and daemon-backed control-plane workflows.",
   "type": "module",
   "main": "src/main.ts",
@@ -99,7 +99,7 @@
     "@anthropic-ai/vertex-sdk": "^0.16.0",
     "@ast-grep/napi": "^0.42.0",
     "@aws/bedrock-token-generator": "^1.1.0",
-    "@pellux/goodvibes-sdk": "0.33.36",
+    "@pellux/goodvibes-sdk": "0.33.38",
     "bash-language-server": "^5.6.0",
     "fuse.js": "^7.1.0",
     "graphql": "^16.13.2",

package/src/cli/management.ts

@@ -6,6 +6,7 @@ import { formatProviderModel, getModelIdFromProviderModel } from '../config/prov
 import { SecretsManager } from '../config/secrets.ts';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 import { listProviderRuntimeSnapshots } from '@pellux/goodvibes-sdk/platform/providers';
+import type { CanonicalModel } from '@pellux/goodvibes-sdk/platform/providers';
 import { BUILTIN_SECRET_PROVIDER_SOURCES, describeSecretRef, isSecretRefInput, resolveSecretRef } from '@pellux/goodvibes-sdk/platform/config';
 import { getSubscriptionProviderConfig, listAvailableSubscriptionProviders } from '@pellux/goodvibes-sdk/platform/config';
 import { beginOpenAICodexLogin, exchangeOpenAICodexCode } from '@pellux/goodvibes-sdk/platform/config';
@@ -173,6 +174,40 @@ async function renderProviders(runtime: CliCommandRuntime): Promise<string> {
   });
 }
 
+/**
+ * Build the synthetic chain entry list for `goodvibes models chain` output.
+ * Pure transformation: accepts canonical model data and an optional lowercase filter key,
+ * returns a serializable array suitable for both JSON and text formatting.
+ *
+ * @internal exported for unit testing
+ */
+export function buildSyntheticChainEntries(
+  canonicalModels: readonly CanonicalModel[],
+  filterKey?: string,
+): Array<{
+  id: string;
+  tier: string;
+  backendCount: number;
+  keyedBackendCount: number;
+  backends: Array<{ position: number; provider: string; model: string; registryKey: string }>;
+}> {
+  const filtered = filterKey
+    ? canonicalModels.filter((m) => m.id.toLowerCase().includes(filterKey))
+    : canonicalModels;
+  return filtered.map((m) => ({
+    id: m.id,
+    tier: m.tier,
+    backendCount: m.backendCount,
+    keyedBackendCount: m.keyedBackendCount,
+    backends: m.backends.map((b, idx) => ({
+      position: idx,
+      provider: b.providerName,
+      model: b.modelId,
+      registryKey: b.registryKey ?? `${b.providerName}:${b.modelId}`,
+    })),
+  }));
+}
+
 async function renderModels(runtime: CliCommandRuntime): Promise<string> {
   return await withRuntimeServices(runtime, async (services) => {
     const [subOrFilter, ...rest] = runtime.cli.commandArgs;
@@ -246,23 +281,58 @@ async function renderModels(runtime: CliCommandRuntime): Promise<string> {
         ...recent.map((model) => `  ${model}`),
       ].join('\n'));
     }
+    if (subOrFilter === 'chain' || subOrFilter === 'chains') {
+      // List synthetic model fallback ladders — backend composition for each synthetic model.
+      const canonicalModels = services.providerRegistry.getSyntheticCanonicalModels();
+      if (canonicalModels.length === 0) {
+        return formatJsonOrText(runtime.cli)([], 'No synthetic models found in the current catalog.');
+      }
+      const filterKey = rest[0]?.toLowerCase();
+      const filtered = filterKey
+        ? canonicalModels.filter((m) => m.id.toLowerCase().includes(filterKey))
+        : canonicalModels;
+      const value = buildSyntheticChainEntries(filtered);
+      return formatJsonOrText(runtime.cli)(value, [
+        `GoodVibes synthetic model chains${filterKey ? ` (${filterKey})` : ''}`,
+        ...value.flatMap((m) => [
+          `  ${m.id}  [${m.tier}]  ${m.keyedBackendCount}/${m.backendCount} backends configured`,
+          ...m.backends.map((b) => `    ${b.position}. ${b.provider}/${b.model}`),
+        ]),
+      ].join('\n'));
+    }
     const filter = subOrFilter === 'list' ? rest[0]?.toLowerCase() : subOrFilter?.toLowerCase();
     const models = services.providerRegistry
       .getSelectableModels()
       .filter((model) => !filter || model.provider.toLowerCase() === filter || model.registryKey.toLowerCase().includes(filter))
       .slice(0, 200);
-    const value = models.map((model) => ({
-      registryKey: model.registryKey,
-      provider: model.provider,
-      ...classifyModelProvider(model.provider),
-      id: model.id,
-      displayName: model.displayName,
-      contextWindow: services.providerRegistry.getContextWindowForModel(model),
-      current: model.registryKey === current,
-    }));
+    const value = models.map((model) => {
+      const synthInfo = model.provider === 'synthetic'
+        ? services.providerRegistry.getSyntheticModelInfoFromCatalog(model.id)
+        : null;
+      return {
+        registryKey: model.registryKey,
+        provider: model.provider,
+        ...classifyModelProvider(model.provider),
+        id: model.id,
+        displayName: model.displayName,
+        contextWindow: services.providerRegistry.getContextWindowForModel(model),
+        current: model.registryKey === current,
+        ...(synthInfo !== null ? {
+          isSynthetic: true,
+          syntheticTier: synthInfo.tier,
+          syntheticBackends: synthInfo.backendCount,
+          syntheticConfiguredBackends: synthInfo.keyedBackendCount,
+        } : {}),
+      };
+    });
     return formatJsonOrText(runtime.cli)(value, [
       `GoodVibes models${filter ? ` (${filter})` : ''}`,
-      ...value.map((model) => `  ${model.current ? '*' : ' '} ${model.registryKey.padEnd(42)} setup=${model.setupClass} ctx=${model.contextWindow.toLocaleString()} ${model.displayName}`),
+      ...value.map((model) => {
+        const synthLabel = model.isSynthetic
+          ? ` [synthetic ${model.syntheticConfiguredBackends}/${model.syntheticBackends}p]`
+          : '';
+        return `  ${model.current ? '*' : ' '} ${model.registryKey.padEnd(42)} setup=${model.setupClass} ctx=${model.contextWindow.toLocaleString()}${synthLabel} ${model.displayName}`;
+      }),
     ].join('\n'));
   });
 }

package/src/core/long-task-notifier.ts

@@ -0,0 +1,145 @@
+/**
+ * long-task-notifier — fires push notifications when a turn or agent task
+ * completes after running longer than the configured threshold.
+ *
+ * PRIVACY GUARANTEE: Notification text must never include conversation content
+ * (user messages, assistant replies, tool outputs). Only metadata is included:
+ * task kind, elapsed time, ok/fail status, and session id. This module enforces
+ * that constraint by construction — it receives no conversation object and
+ * builds all message text from structural metadata only.
+ *
+ * Delivery targets (in preference order):
+ *   1. Desktop notification (linux notify-send / mac osascript) via SDK
+ *      notifyCompletion — detected and dispatched by the SDK; silently
+ *      no-ops when the platform does not support it.
+ *   2. Configured outbound webhook channel (ntfy topic / webhook URL) via
+ *      WebhookNotifier.send() — only fires when the user has URLs configured.
+ *
+ * When neither target is available the function is an honest no-op (debug log
+ * only; no user-facing error spam).
+ *
+ * Focus tracking: terminal focus state is not tracked anywhere in the TUI.
+ * Notifications therefore fire regardless of whether the terminal window is
+ * focused. A future implementation may suppress notifications when the TUI is
+ * in the foreground by reading a focus-state ref. // seam: wire focus ref here.
+ */
+
+import { notifyCompletion } from '@pellux/goodvibes-sdk/platform/utils';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+import type { WebhookNotifier } from '@pellux/goodvibes-sdk/platform/integrations';
+
+/** Default threshold in seconds. Turns shorter than this do not notify. */
+export const NOTIFY_AFTER_SECONDS_DEFAULT = 60;
+
+/**
+ * Sentinel value for the off-state. When behavior.notifyAfterSeconds is 0,
+ * push notifications are disabled (same convention as other numeric-off keys
+ * in the config schema).
+ */
+export const NOTIFY_AFTER_SECONDS_OFF = 0;
+
+/** Accepted task kinds for notification messages. */
+export type LongTaskKind = 'turn' | 'agent';
+
+/** Completion status for notification messages. */
+export type LongTaskStatus = 'ok' | 'fail';
+
+export interface MaybeNotifyLongTaskOptions {
+  /**
+   * Elapsed milliseconds for the turn or agent task.
+   * Must not include any conversation content.
+   */
+  readonly elapsedMs: number;
+
+  /** Whether the task completed successfully or failed. */
+  readonly status: LongTaskStatus;
+
+  /** Task kind label for the notification body. */
+  readonly kind: LongTaskKind;
+
+  /** Session id for correlation. Must not be a PII value. */
+  readonly sessionId: string;
+
+  /**
+   * Threshold in seconds from config (behavior.notifyAfterSeconds).
+   * 0 means off; notifications are suppressed entirely.
+   * Should be the raw config value; this function normalises it.
+   */
+  readonly thresholdSeconds: number;
+
+  /**
+   * Outbound webhook notifier. When provided and the user has URLs
+   * configured, the notification is also sent to all configured endpoints
+   * (e.g. ntfy.sh topics). Optional — absent means outbound delivery is
+   * skipped silently.
+   */
+  readonly webhookNotifier?: WebhookNotifier | null;
+}
+
+/**
+ * Fires push notifications for a completed long task if the elapsed time
+ * exceeds the configured threshold.
+ *
+ * Returns true when at least one delivery was attempted, false when the
+ * call was a no-op (threshold not reached, or off-state).
+ *
+ * PRIVACY: builds message text from structural metadata only (kind, elapsed,
+ * status, sessionId). Never includes conversation content.
+ */
+export function maybeNotifyLongTask(opts: MaybeNotifyLongTaskOptions): boolean {
+  const { elapsedMs, status, kind, sessionId, thresholdSeconds, webhookNotifier } = opts;
+
+  // Off-state: 0 disables notifications entirely.
+  if (thresholdSeconds === NOTIFY_AFTER_SECONDS_OFF) {
+    logger.debug('long-task-notifier: disabled (threshold=0)');
+    return false;
+  }
+
+  // Gate: only notify when the task exceeded the threshold.
+  const elapsedSeconds = Math.floor(elapsedMs / 1000);
+  if (elapsedSeconds < thresholdSeconds) {
+    logger.debug('long-task-notifier: below threshold', { elapsedSeconds, thresholdSeconds });
+    return false;
+  }
+
+  // Build concise, metadata-only message. No conversation text.
+  const statusLabel = status === 'ok' ? 'completed' : 'failed';
+  const title = `GoodVibes — ${kind} ${statusLabel}`;
+  // PRIVACY: message contains only structural metadata, never conversation content.
+  const message = `${kind} ${statusLabel} in ${elapsedSeconds}s  ·  session ${sessionId.slice(0, 8)}`;
+
+  // Delivery 1: desktop notification (notify-send on linux, osascript on mac).
+  // notifyCompletion is non-throwing; SDK handles platform absence silently.
+  try {
+    notifyCompletion(title, message, elapsedMs);
+  } catch (err) {
+    logger.debug('long-task-notifier: desktop notify error', { error: String(err) });
+  }
+
+  // Delivery 2: outbound webhook (ntfy / generic endpoint) if configured.
+  if (webhookNotifier) {
+    const urls = webhookNotifier.getUrls();
+    if (urls.length > 0) {
+      webhookNotifier.send(message).catch((err: unknown) => {
+        logger.debug('long-task-notifier: webhook send error', { error: String(err) });
+      });
+    } else {
+      logger.debug('long-task-notifier: no webhook URLs configured, skipping outbound delivery');
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Read behavior.notifyAfterSeconds from a config manager.
+ * Returns NOTIFY_AFTER_SECONDS_DEFAULT when the key is absent or invalid.
+ * Returns NOTIFY_AFTER_SECONDS_OFF (0) when explicitly set to 0.
+ */
+export function readNotifyAfterSeconds(configGet: (key: string) => unknown): number {
+  const raw = configGet('behavior.notifyAfterSeconds');
+  if (raw === 0) return NOTIFY_AFTER_SECONDS_OFF;
+  const parsed = typeof raw === 'number' ? raw : Number(raw);
+  if (Number.isFinite(parsed) && parsed >= 0) return parsed;
+  return NOTIFY_AFTER_SECONDS_DEFAULT;
+}

package/src/core/session-recovery.ts

@@ -0,0 +1,147 @@
+/**
+ * session-recovery.ts — Journal replay at session resume.
+ *
+ * Purpose
+ * ───────
+ * When a session is resumed, this module checks whether a transcript journal
+ * exists for that session whose records post-date the loaded snapshot. If so,
+ * it replays those records onto the live conversation and writes a fresh
+ * snapshot so the gap is permanently closed.
+ *
+ * Seams (all three must call replayJournalForSession)
+ * ────────────────────────────────────────────────────
+ * 1. CLI / command resume — session-workflow.ts, after `fromJSON` +
+ *    `rebuildHistory` complete. Handles --continue, --resume, /session resume,
+ *    and --fork.
+ * 2. Ctrl+R crash recovery — blocking-input.ts, after `conversation.fromJSON`
+ *    in the Ctrl+R branch. Handles SIGKILL-era recovery files.
+ * 3. In-TUI panel resume — bootstrap-hook-bridge.ts
+ *    `createResumeSessionHandler`, after `options.runtime.sessionId` is
+ *    assigned. Handles the session browser / panel-driven resume.
+ *
+ * Recovery protocol
+ * ─────────────────
+ * 1. Call replayJournal() with the journal path and the snapshot timestamp.
+ * 2. If no records are newer than the snapshot, rotate the (now-stale)
+ *    journal silently and return.
+ * 3. If records are found, apply the final record's messages — each journal
+ *    record carries the full conversation snapshot at that moment, so the
+ *    last record by seq is the authoritative post-crash state.
+ * 4. Rebuild the conversation history and call the snapshot writer so the
+ *    gap is durably closed before the user sees the restored conversation.
+ * 5. Rotate the journal (it is no longer needed as a gap-filler).
+ * 6. Return a result so the caller can emit an honest notice.
+ */
+
+import { journalPathFor, openTranscriptJournal, replayJournal } from './transcript-journal.ts';
+import type { ConversationManager } from './conversation.ts';
+import type { ConversationMessageSnapshot } from '@pellux/goodvibes-sdk/platform/core';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface ReplayIntoConversationOptions {
+  /** Absolute path to the journal file for this session. */
+  readonly journalPath: string;
+  /**
+   * The `timestamp` field from the loaded session snapshot (SessionMeta).
+   * Only journal records with ts > snapshotTimestamp are replayed.
+   */
+  readonly snapshotTimestamp: number;
+  /** The live conversation manager to mutate with replayed messages. */
+  readonly conversation: ConversationManager;
+  /** Session ID — used when creating the post-replay journal instance for rotate(). */
+  readonly sessionId: string;
+  /**
+   * Persist the restored conversation so the gap is durably closed.
+   * Called with the final replayed message list. Best-effort — failures
+   * are swallowed so recovery never hard-fails a resume.
+   */
+  readonly persistSnapshot: (messages: ConversationMessageSnapshot[]) => void;
+}
+
+export interface ReplayIntoConversationResult {
+  /** Number of journal records that post-dated the snapshot. 0 if nothing to replay. */
+  readonly replayed: number;
+  /** True if the journal tail was corrupt (quarantined). */
+  readonly hadCorruptTail: boolean;
+  /** True if the journal had an unrecognised schema version (quarantined). */
+  readonly hadVersionMismatch: boolean;
+}
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Replay journal records newer than `snapshotTimestamp` onto `conversation`.
+ *
+ * Returns a result object so the caller can emit an appropriate notice.
+ * Never throws — all errors are swallowed to preserve the "best-effort"
+ * recovery contract.
+ */
+export function replayJournalIntoConversation(
+  options: ReplayIntoConversationOptions,
+): ReplayIntoConversationResult {
+  const { journalPath, snapshotTimestamp, conversation, sessionId, persistSnapshot } = options;
+
+  try {
+    const { records, hadCorruptTail } = replayJournal(journalPath, snapshotTimestamp);
+
+    // Detect version mismatch: replayJournal quarantines and returns
+    // hadCorruptTail=true + 0 records when the header version is wrong.
+    // We distinguish it from a genuine corrupt tail by checking whether the
+    // journal file still exists (quarantine renames it away in both cases,
+    // so we cannot inspect the header at this point). We surface both cases
+    // through hadCorruptTail to the caller; hadVersionMismatch is derived
+    // from it to give the caller a distinct notice option.
+    const hadVersionMismatch = hadCorruptTail && records.length === 0;
+
+    const journal = openTranscriptJournal(journalPath, sessionId);
+
+    if (records.length === 0) {
+      // Nothing to replay — rotate the (now-stale) journal silently.
+      journal.rotate();
+      return { replayed: 0, hadCorruptTail, hadVersionMismatch };
+    }
+
+    // The last record (highest seq) holds the most recent full conversation
+    // state captured before the crash. Apply it.
+    const lastRecord = records[records.length - 1]!;
+    const replayedMessages = lastRecord.messages as ConversationMessageSnapshot[];
+
+    conversation.fromJSON({
+      messages: replayedMessages as never[],
+    });
+    conversation.rebuildHistory();
+
+    // Write a fresh snapshot so the gap is durably closed even if the
+    // process is killed again before the next turn-complete snapshot.
+    try {
+      persistSnapshot(replayedMessages);
+    } catch {
+      // Best-effort — never hard-fail recovery due to snapshot write failure.
+    }
+
+    // Rotate the journal — it is no longer needed as a gap-filler.
+    journal.rotate();
+
+    return { replayed: records.length, hadCorruptTail, hadVersionMismatch: false };
+  } catch {
+    // Absolute last-resort guard — recovery must never crash a resume.
+    return { replayed: 0, hadCorruptTail: false, hadVersionMismatch: false };
+  }
+}
+
+/**
+ * Build the journal path for a given session and home directory, then call
+ * replayJournalIntoConversation().
+ *
+ * Convenience wrapper used by session-workflow.ts so it does not need to
+ * import journalPathFor directly.
+ */
+export function replayJournalForSession(
+  options: Omit<ReplayIntoConversationOptions, 'journalPath'> & {
+    readonly homeDirectory: string;
+  },
+): ReplayIntoConversationResult {
+  const journalPath = journalPathFor(options.homeDirectory, options.sessionId);
+  return replayJournalIntoConversation({ ...options, journalPath });
+}

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

@@ -60,6 +60,15 @@ interface StreamSystemMessageRouter {
   low(message: string): void;
 }
 
+/**
+ * Minimal cost lookup surface for attaching cost-delta information to failover notices.
+ * Returns USD-per-1M-token pricing for the given model ID.
+ * The implementation may consult a catalog; if the model is unknown both fields are 0.
+ */
+export interface FailoverCostLookup {
+  getCostFromCatalog(modelId: string): { readonly input: number; readonly output: number };
+}
+
 export interface WireStreamEventMetricsOptions {
   /** The UI runtime event bus (turns + tools sub-buses). */
   readonly events: UiRuntimeEvents;
@@ -89,6 +98,13 @@ export interface WireStreamEventMetricsOptions {
    * the optimizer is enabled and a viable next provider exists in the chain.
    */
   readonly retryTurn?: () => void;
+  /**
+   * Optional cost catalog for attaching per-1M-token cost information to
+   * the failover notice.  When provided and both models have non-zero pricing,
+   * the notice includes input and output cost comparisons.  When absent or pricing is
+   * unavailable for either model, the notice honestly states "cost data unavailable".
+   */
+  readonly costLookup?: FailoverCostLookup;
 }
 
 /** Result of wireStreamEventMetrics. */
@@ -102,6 +118,53 @@ export interface WireStreamEventMetricsResult {
    * TURN_COMPLETED, but a new submission may arrive before TURN_COMPLETED fires).
    */
   readonly clearFailoverVisited: () => void;
+  /**
+   * Register a callback that fires whenever a TURN_ERROR is surfaced to the
+   * user — either immediately (no optimizer) or after chain exhaustion.
+   * Does NOT fire when the optimizer performs a successful automatic failover
+   * (in that case the user sees a [Failover] notice, not an error).
+   * Used by main.ts to activate the one-key retry affordance. The callback
+   * receives exhausted=true when the failover chain was exhausted first, so
+   * the notice can say honestly that a retry reuses the same failed provider.
+   */
+  readonly onErrorSurfaced: (cb: (exhausted: boolean) => void) => void;
+}
+
+/**
+ * Build the cost-delta suffix for a failover notice.
+ *
+ * Extracts the model ID from registry keys (format: `provider:modelId`),
+ * queries the cost catalog for both, and formats a human-readable comparison.
+ * If the lookup is absent or either model returns zero pricing (unknown),
+ * returns an honest "cost data unavailable" suffix instead of fabricating values.
+ *
+ * @param lookup - Optional cost catalog; when absent, returns unavailable notice.
+ * @param fromRegistryKey - Registry key of the provider being abandoned (may be undefined).
+ * @param toRegistryKey - Registry key of the provider being selected.
+ * @returns A parenthesised suffix string or empty string.
+ */
+function buildCostDeltaSuffix(
+  lookup: FailoverCostLookup | undefined,
+  fromRegistryKey: string | undefined,
+  toRegistryKey: string,
+): string {
+  if (!lookup) return '';
+  // Registry key format: `provider:modelId` — modelId may itself contain `:`.
+  const fromModelId = fromRegistryKey ? fromRegistryKey.split(':').slice(1).join(':') : '';
+  const toModelId = toRegistryKey.split(':').slice(1).join(':');
+  const fromCost = fromModelId ? lookup.getCostFromCatalog(fromModelId) : { input: 0, output: 0 };
+  const toCost = lookup.getCostFromCatalog(toModelId);
+  // Report unavailable when either side has zero pricing (unknown model).
+  if (fromCost.input === 0 && fromCost.output === 0 && !fromModelId) {
+    return ' [cost data unavailable]';
+  }
+  const hasFromData = fromCost.input > 0 || fromCost.output > 0;
+  const hasToData = toCost.input > 0 || toCost.output > 0;
+  if (!hasFromData || !hasToData) {
+    return ' [cost data unavailable]';
+  }
+  const fmt = (n: number) => `$${n.toFixed(2)}`;
+  return ` [cost/1M: input ${fmt(fromCost.input)}→${fmt(toCost.input)}, output ${fmt(fromCost.output)}→${fmt(toCost.output)}]`;
 }
 
 /**
@@ -123,7 +186,7 @@ export function wireStreamEventMetrics(
 ): WireStreamEventMetricsResult {
   const {
     events, metrics, orchestrator, providerRegistry,
-    systemMessageRouter, render, providerOptimizer, retryTurn,
+    systemMessageRouter, render, providerOptimizer, retryTurn, costLookup,
   } = options;
 
   const unsubs: Array<() => void> = [];
@@ -192,6 +255,8 @@ export function wireStreamEventMetrics(
       if (next) {
         const toRegistryKey = `${next.providerId}:${next.modelId}`;
         const errorClass = formatUserFacingErrorLine(errVal);
+        // Capture FROM registry key before switching — needed for cost comparison.
+        const fromRegistryKey = providerRegistry.getCurrentModel().registryKey;
         try {
           providerRegistry.setCurrentModel(toRegistryKey);
         } catch (switchErr) {
@@ -205,8 +270,9 @@ export function wireStreamEventMetrics(
         // a subsequent TURN_ERROR from that provider also skips it.
         failoverVisited.add(next.providerId);
         providerOptimizer.recordFallbackTransition(fromProvider, next.providerId, errorClass);
+        const costSuffix = buildCostDeltaSuffix(costLookup, fromRegistryKey, toRegistryKey);
         systemMessageRouter.high(
-          `[Failover] ${fromProvider} -> ${next.providerId} (${errorClass})`,
+          `[Failover] ${fromProvider} -> ${next.providerId} (${errorClass})${costSuffix}`,
         );
         render();
         // Re-submit the last user turn on the new provider.
@@ -218,6 +284,7 @@ export function wireStreamEventMetrics(
       systemMessageRouter.high(
         `[Failover] Chain exhausted — no alternative provider available. Original error: ${formatUserFacingErrorLine(errVal)}`,
       );
+      notifyErrorSurfaced(true);
       render();
       return;
     }
@@ -225,6 +292,7 @@ export function wireStreamEventMetrics(
     // Baseline: optimizer disabled or not wired — surface error immediately.
     const formatted = formatUserFacingErrorLine(errVal);
     systemMessageRouter.high(`[Error] ${formatted}`);
+    notifyErrorSurfaced(false);
     render();
   }));
 
@@ -258,5 +326,11 @@ export function wireStreamEventMetrics(
     metrics.activeToolName = undefined;
   }));
 
-  return { unsubs, clearFailoverVisited: () => failoverVisited.clear() };
+  let _errorSurfacedCb: ((exhausted: boolean) => void) | undefined;
+  function notifyErrorSurfaced(exhausted: boolean) { _errorSurfacedCb?.(exhausted); }
+  return {
+    unsubs,
+    clearFailoverVisited: () => failoverVisited.clear(),
+    onErrorSurfaced: (cb: (exhausted: boolean) => void) => { _errorSurfacedCb = cb; },
+  };
 }