@pellux/goodvibes-tui 0.22.0 → 0.23.0

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

@@ -1,6 +1,7 @@
 import type { UiRuntimeEvents } from '@/runtime/index.ts';
 import { createStreamStallWatchdog } from './stream-stall-watchdog.ts';
 import { formatUserFacingErrorLine } from './format-user-error.ts';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
 
 /**
  * Live stream and tool-execution metrics maintained by wireStreamEventMetrics.
@@ -29,9 +30,28 @@ interface StreamOrchestrator {
   readonly streamingOutputTokens: number;
 }
 
-/** Minimal provider surface required for the stream stall watchdog. */
+/** Minimal provider surface required for the stream stall watchdog and failover switching. */
 interface StreamProviderRegistry {
-  getCurrentModel(): { readonly provider: string };
+  getCurrentModel(): { readonly provider: string; readonly registryKey?: string };
+  setCurrentModel(registryKey: string): void;
+}
+
+/**
+ * Minimal fallback-chain node shape returned by ProviderOptimizer.testFallback().
+ * Only the fields consumed by the failover path are declared here.
+ */
+interface FailoverChainNode {
+  readonly position: number;
+  readonly providerId: string;
+  readonly modelId: string;
+  readonly capable: boolean;
+}
+
+/** Minimal ProviderOptimizer surface required by the failover path. */
+interface FailoverOptimizer {
+  readonly enabled: boolean;
+  testFallback(profile?: Record<string, unknown>): { readonly chain: readonly FailoverChainNode[] };
+  recordFallbackTransition(from: string, to: string, reason: string): void;
 }
 
 /** Minimal system-message surface required for user-visible notifications. */
@@ -56,6 +76,32 @@ export interface WireStreamEventMetricsOptions {
    * so the render closure can read it without a forward-reference issue.
    */
   readonly metrics: StreamMetrics;
+  /**
+   * When provided and enabled, the optimizer is consulted on TURN_ERROR to
+   * attempt the next viable provider before surfacing the error to the user.
+   * When absent or optimizer.enabled is false, behaviour is identical to the
+   * pre-failover baseline: error surfaces immediately via systemMessageRouter.
+   */
+  readonly providerOptimizer?: FailoverOptimizer;
+  /**
+   * 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.
+   */
+  readonly retryTurn?: () => void;
+}
+
+/** Result of wireStreamEventMetrics. */
+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).
+   */
+  readonly clearFailoverVisited: () => void;
 }
 
 /**
@@ -64,8 +110,7 @@ export interface WireStreamEventMetricsOptions {
  * and declares it before render() so both the render closure and the returned
  * event handlers share the same reference.
  *
- * Returns an array of unsubscribe functions; push them into the parent unsubs
- * array so they are cleaned up on exit.
+ * Returns an object with unsubscribe functions and a clearFailoverVisited helper.
  *
  * Responsibilities:
  *   - Track stream start time, delta count, token speed, and TTFT
@@ -75,8 +120,11 @@ export interface WireStreamEventMetricsOptions {
  */
 export function wireStreamEventMetrics(
   options: WireStreamEventMetricsOptions,
-): ReadonlyArray<() => void> {
-  const { events, metrics, orchestrator, providerRegistry, systemMessageRouter, render } = options;
+): WireStreamEventMetricsResult {
+  const {
+    events, metrics, orchestrator, providerRegistry,
+    systemMessageRouter, render, providerOptimizer, retryTurn,
+  } = options;
 
   const unsubs: Array<() => void> = [];
 
@@ -103,8 +151,78 @@ export function wireStreamEventMetrics(
     metrics.tokenSpeed = elapsed > 0 ? tokenCount / elapsed : 0;
   }));
 
+  // Per-turn visited-provider set: tracks providers already attempted this turn
+  // so failover cannot ping-pong between two mutually-failing providers.
+  // True invariant: at most one retry per provider per turn; exhaustion fires
+  // after the chain is consumed.
+  // Cleared on TURN_COMPLETED (see handler below) and on new user submission
+  // (caller clears via clearFailoverVisited(), wired in main.ts).
+  const failoverVisited = new Set<string>();
+
+  unsubs.push(events.turns.on('TURN_COMPLETED', () => {
+    failoverVisited.clear();
+  }));
+
   unsubs.push(events.turns.on('TURN_ERROR', (event) => {
     const errVal: string = event.error;
+
+    // --- Optimizer-gated failover path ---
+    // When the optimizer is present and enabled, attempt to advance to the next
+    // viable provider in the fallback chain before surfacing the error.  When
+    // the optimizer is absent or disabled, behaviour is identical to baseline:
+    // error surfaces immediately.
+    if (providerOptimizer?.enabled && retryTurn) {
+      const fromProvider = providerRegistry.getCurrentModel().provider;
+      // Mark the failing provider as visited so it will never be selected again
+      // in this turn, even if a second TURN_ERROR arrives (e.g. ping-pong).
+      failoverVisited.add(fromProvider);
+      const result = providerOptimizer.testFallback({});
+      // Find the first capable node that is NOT already visited this turn and
+      // is NOT synthetic. Synthetic nodes are skipped permanently by design:
+      // a synthetic model is itself a fallback ladder over real backends, so
+      // failing over INTO one after a real backend already failed is unsound
+      // double-indirection (it can route straight back to the failed provider).
+      const next = result.chain.find(
+        (node) =>
+          node.capable &&
+          !failoverVisited.has(node.providerId) &&
+          node.providerId !== 'synthetic',
+      );
+
+      if (next) {
+        const toRegistryKey = `${next.providerId}:${next.modelId}`;
+        const errorClass = formatUserFacingErrorLine(errVal);
+        try {
+          providerRegistry.setCurrentModel(toRegistryKey);
+        } catch (switchErr) {
+          // Switch failed — fall through to honest error display.
+          logger.debug('failover setCurrentModel failed', { toRegistryKey, error: String(switchErr) });
+          systemMessageRouter.high(`[Error] ${errorClass}`);
+          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);
+        providerOptimizer.recordFallbackTransition(fromProvider, next.providerId, errorClass);
+        systemMessageRouter.high(
+          `[Failover] ${fromProvider} -> ${next.providerId} (${errorClass})`,
+        );
+        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(
+        `[Failover] Chain exhausted — no alternative provider available. Original error: ${formatUserFacingErrorLine(errVal)}`,
+      );
+      render();
+      return;
+    }
+
+    // Baseline: optimizer disabled or not wired — surface error immediately.
     const formatted = formatUserFacingErrorLine(errVal);
     systemMessageRouter.high(`[Error] ${formatted}`);
     render();
@@ -140,5 +258,5 @@ export function wireStreamEventMetrics(
     metrics.activeToolName = undefined;
   }));
 
-  return unsubs;
+  return { unsubs, clearFailoverVisited: () => failoverVisited.clear() };
 }

package/src/input/commands/channel-runtime.ts

@@ -0,0 +1,139 @@
+import type { CommandRegistry } from '../command-registry.ts';
+import { requireIntegrationHelpers } from './runtime-services.ts';
+
+export function registerChannelRuntimeCommands(registry: CommandRegistry): void {
+  registry.register({
+    name: 'channel',
+    aliases: [],
+    description: 'Inspect channel routes, delivery strategies, and ingress policies',
+    usage: '[status|routes|delivery|policy] [--json]',
+    argsHint: 'status | routes | delivery | policy',
+    handler(args, ctx) {
+      const sub = args[0];
+      const asJson = args.includes('--json');
+
+      if (!sub || sub === 'open' || sub === 'panel') {
+        if (ctx.showPanel) ctx.showPanel('routes');
+        return;
+      }
+
+      const helpers = requireIntegrationHelpers(ctx);
+
+      if (sub === 'status') {
+        const review = helpers.buildReview();
+        if (asJson) {
+          ctx.print(JSON.stringify(review, null, 2));
+          return;
+        }
+        const lines: string[] = [
+          'Channel Status',
+          `  routes:            ${review.routes.length}`,
+          `  api families:      ${review.apiFamilies.join(', ') || '(none)'}`,
+          `  sessions:          ${review.sessions}`,
+          `  tasks:             ${review.tasks}`,
+          `  pending approvals: ${review.pendingApprovals}`,
+          `  remote contracts:  ${review.remoteContracts}`,
+          '',
+          `Active route families: ${review.routes.join(', ') || '(none)'}`,
+          '',
+          'Use /channel routes for delivery binding details.',
+          'Use /channel delivery for outbound delivery snapshot.',
+          'Use /channel policy for ingress policy snapshot.',
+        ];
+        ctx.print(lines.join('\n'));
+        return;
+      }
+
+      if (sub === 'routes') {
+        const snapshot = helpers.getRouteSnapshot();
+        if (asJson) {
+          ctx.print(JSON.stringify(snapshot, null, 2));
+          return;
+        }
+        const entries = Object.entries(snapshot);
+        if (entries.length === 0) {
+          ctx.print('No route bindings active.\n\nRoutes become active when channel surfaces (slack, discord, ntfy, webhook, etc.) are configured and the daemon is running.');
+          return;
+        }
+        const lines: string[] = ['Channel Routes'];
+        for (const [key, value] of entries) {
+          lines.push(`  ${String(key).padEnd(28)} ${JSON.stringify(value)}`);
+        }
+        lines.push('');
+        lines.push('Route bindings reflect active daemon surface registrations.');
+        ctx.print(lines.join('\n'));
+        return;
+      }
+
+      if (sub === 'delivery') {
+        const snapshot = helpers.getDeliverySnapshot();
+        if (asJson) {
+          ctx.print(JSON.stringify(snapshot, null, 2));
+          return;
+        }
+        const entries = Object.entries(snapshot);
+        if (entries.length === 0) {
+          ctx.print('No delivery snapshot available.\n\nDelivery state is populated when the daemon handles outbound channel messages.');
+          return;
+        }
+        const lines: string[] = ['Channel Delivery Snapshot'];
+        for (const [key, value] of entries) {
+          lines.push(`  ${String(key).padEnd(28)} ${JSON.stringify(value)}`);
+        }
+        ctx.print(lines.join('\n'));
+        return;
+      }
+
+      if (sub === 'policy') {
+        const configManager = ctx.platform.configManager;
+        // Channel policy is persisted by ChannelPolicyManager in
+        // .goodvibes/tui/channels/policies.json — surface via configManager
+        // category (runtime-accessible without a daemon round-trip).
+        const surfaces = [
+          'slack', 'discord', 'ntfy', 'webhook', 'homeassistant',
+          'telegram', 'google-chat', 'signal', 'whatsapp',
+          'imessage', 'msteams', 'bluebubbles', 'mattermost', 'matrix',
+        ];
+        const lines: string[] = ['Channel Ingress Policies'];
+        let found = false;
+        for (const surface of surfaces) {
+          const key = `surfaces.${surface}.enabled` as Parameters<typeof configManager.get>[0];
+          const enabled = configManager.get(key);
+          if (enabled !== undefined && enabled !== null) {
+            found = true;
+            lines.push(`  ${surface.padEnd(20)} enabled=${String(enabled)}`);
+          }
+        }
+        if (!found) {
+          lines.push('  No channel surfaces configured.');
+          lines.push('');
+          lines.push('  Configure surfaces via /onboarding or Settings > Surfaces.');
+          lines.push('  Fine-grained ingress policies (allowedCommands, requireMention, groupPolicies)');
+          lines.push('  are managed by ChannelPolicyManager in .goodvibes/tui/channels/policies.json.');
+        } else {
+          lines.push('');
+          lines.push('  Fine-grained ingress policies (allowedCommands, requireMention, groupPolicies)');
+          lines.push('  are managed by ChannelPolicyManager in .goodvibes/tui/channels/policies.json.');
+        }
+        if (asJson) {
+          ctx.print(JSON.stringify({ surfaces: Object.fromEntries(surfaces.map((s) => [s, configManager.get(`surfaces.${s}.enabled` as Parameters<typeof configManager.get>[0])])) }, null, 2));
+          return;
+        }
+        ctx.print(lines.join('\n'));
+        return;
+      }
+
+      ctx.print(
+        'Usage: /channel <subcommand>\n'
+        + '  (no args)  — open the Routes panel\n'
+        + '  status     — channel overview: routes, sessions, tasks, pending approvals\n'
+        + '  routes     — active route binding snapshot\n'
+        + '  delivery   — outbound delivery snapshot\n'
+        + '  policy     — configured channel surfaces and ingress policy location\n'
+        + '\n'
+        + 'Options:\n'
+        + '  --json  Output raw JSON for scripting'
+      );
+    },
+  });
+}

package/src/input/commands/runtime-services.ts

@@ -7,6 +7,8 @@ import type {
   CommandSessionServices,
   CommandWorkspaceServices,
 } from '../command-registry.ts';
+import { getLastCompactionEvent } from '@pellux/goodvibes-sdk/platform/core';
+import type { CompactionContext, CompactionEvent } from '@pellux/goodvibes-sdk/platform/core';
 import type { UiReadModels } from '../../runtime/ui-read-models.ts';
 import type { ShellPathService } from '@/runtime/index.ts';
 import type { EcosystemCatalogPathOptions } from '@/runtime/index.ts';
@@ -236,13 +238,40 @@ export function requireProviderApi(context: CommandContext): ProviderApi {
   return requireContextValue(context.clients?.providerApi, 'clients.providerApi');
 }
 
-export async function compactConversation(context: CommandContext): Promise<void> {
+/**
+ * Compact the conversation and return the CompactionEvent recorded by the SDK,
+ * or null if no event was recorded (e.g. compaction was skipped or produced no
+ * change).
+ */
+export async function compactConversation(context: CommandContext): Promise<CompactionEvent | null> {
+  const eventBefore = getLastCompactionEvent();
+  const sessionMemories = context.session.sessionMemoryStore?.list() ?? [];
+  const compactionCtx: CompactionContext = {
+    messages: context.session.conversationManager.getMessagesForLLM(),
+    sessionMemories,
+    agents: [],
+    wrfcChains: [],
+    activePlan: null,
+    lineageEntries: [],
+    compactionCount: 0,
+    contextWindow: 0,
+    trigger: 'manual',
+    extractionModelId: context.session.runtime.model,
+    extractionProvider: context.session.runtime.provider,
+  };
   await context.session.conversationManager.compact(
     context.provider.providerRegistry,
     context.session.runtime.model,
     'manual',
     context.session.runtime.provider,
+    compactionCtx,
   );
+  const eventAfter = getLastCompactionEvent();
+  // Return the new event only if it differs from the one recorded before the call.
+  if (eventAfter !== null && eventAfter !== eventBefore) {
+    return eventAfter;
+  }
+  return null;
 }
 
 export function requireKnowledgeApi(context: CommandContext): KnowledgeApi {

package/src/input/commands/share-runtime.ts

@@ -17,7 +17,7 @@ import {
   resolveGithubToken,
 } from '../../export/gist-uploader.ts';
 import { copyToClipboard } from '../../utils/clipboard.ts';
-import { openBrowser } from '../../cli/management.ts';
+import { openBrowser } from '../../utils/browser.ts';
 
 export function registerShareRuntimeCommands(registry: CommandRegistry): void {
   registry.register({

package/src/input/commands/shell-core.ts

@@ -3,7 +3,9 @@ import type { SelectionItem } from '../selection-modal.ts';
 import { EFFORT_DESCRIPTIONS } from '@pellux/goodvibes-sdk/platform/providers';
 import { REASONING_BUDGET_MAP } from '@pellux/goodvibes-sdk/platform/providers';
 import { executeWriteQuit } from './quit-shared.ts';
-import { compactConversation, requireKeybindingsManager, requireProviderApi } from './runtime-services.ts';
+import { compactConversation, requireKeybindingsManager, requireProviderApi, requireSessionMemoryStore } from './runtime-services.ts';
+import { buildCompactionPreview, buildCompactionAfterNotice, buildPinUsageText, buildPinSuccessText } from '../../renderer/compaction-preview.ts';
+import { buildCompactionHistoryText } from '../../renderer/compaction-history-modal.ts';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 import { logger } from '@pellux/goodvibes-sdk/platform/utils';
 
@@ -204,9 +206,57 @@ export function registerShellCoreCommands(registry: CommandRegistry): void {
     aliases: [],
     description: 'Summarize conversation to free context window',
     async handler(_args, ctx) {
-      ctx.print('Compacting conversation...');
-      await compactConversation(ctx);
-      ctx.print('Conversation compacted.');
+      const messages = ctx.session.conversationManager.getMessagesForLLM();
+      // contextWindow is not on CommandContext; preview shows message/token counts
+      // without the capacity-% clause (still honest; no fabricated value).
+      const contextWindow = 0;
+      const memStore = ctx.session.sessionMemoryStore;
+      const pinnedMemoryCount = memStore ? memStore.list().length : 0;
+      // Pre-compact preview: honest estimate, clearly labelled.
+      const preview = buildCompactionPreview({ messages, contextWindow, pinnedMemoryCount, trigger: 'manual' });
+      ctx.print(preview);
+      const event = await compactConversation(ctx);
+      if (event) {
+        // Post-compact notice: uses real CompactionEvent figures.
+        ctx.print(buildCompactionAfterNotice({ event, pinnedMemoryCount }));
+      } else {
+        ctx.print('[Context] Compact complete.');
+      }
+      ctx.renderRequest();
+    },
+  });
+
+  registry.register({
+    name: 'compact-history',
+    aliases: ['compaction-history'],
+    description: 'Show compaction history for this session',
+    handler(_args, ctx) {
+      ctx.print(buildCompactionHistoryText());
+      ctx.renderRequest();
+    },
+  });
+
+  registry.register({
+    name: 'keep',
+    aliases: [],
+    description: 'Pin text to session memory (survives compaction)',
+    usage: '<text>',
+    argsHint: '<text to preserve>',
+    handler(args, ctx) {
+      const text = args.join(' ').trim();
+      if (!text) {
+        ctx.print(buildPinUsageText());
+        ctx.renderRequest();
+        return;
+      }
+      const memStore = requireSessionMemoryStore(ctx);
+      const id = memStore.add(text);
+      if (!id) {
+        ctx.print('[Pin] Nothing pinned — text was blank.');
+      } else {
+        const count = memStore.list().length;
+        ctx.print(buildPinSuccessText(id, text, count));
+      }
       ctx.renderRequest();
     },
   });

package/src/input/commands.ts

@@ -18,6 +18,7 @@ import { registerGitRuntimeCommands } from './commands/git-runtime.ts';
 import { registerNotifyRuntimeCommands } from './commands/notify-runtime.ts';
 import { registerReplayRuntimeCommands } from './commands/replay-runtime.ts';
 import { registerShareRuntimeCommands } from './commands/share-runtime.ts';
+import { registerChannelRuntimeCommands } from './commands/channel-runtime.ts';
 import { registerLocalSetupCommands } from './commands/local-setup.ts';
 import { registerProductRuntimeCommands } from './commands/product-runtime.ts';
 import { registerPlatformRuntimeCommands } from './commands/platform-runtime.ts';
@@ -70,6 +71,7 @@ export function registerBuiltinCommands(registry: CommandRegistry): void {
   registerNotifyRuntimeCommands(registry);
   registerReplayRuntimeCommands(registry);
   registerShareRuntimeCommands(registry);
+  registerChannelRuntimeCommands(registry);
   registerLocalSetupCommands(registry);
   registerProductRuntimeCommands(registry);
   registerPlatformRuntimeCommands(registry);

package/src/main.ts

@@ -54,22 +54,16 @@ import { allowTerminalWrite, installTuiTerminalOutputGuard } from './runtime/ter
 import { buildCommandArgsHint } from './input/command-args-hint.ts';
 import { summarizeRunningAgents } from './renderer/process-summary.ts';
 import { formatUserFacingErrorLine } from './core/format-user-error.ts';
-import { wireStreamEventMetrics, type StreamMetrics } from './core/stream-event-wiring.ts';
+import { wireStreamEventMetrics, type StreamMetrics, type WireStreamEventMetricsResult } from './core/stream-event-wiring.ts';
 import { wireTurnEventHandlers } from './core/turn-event-wiring.ts';
 import { buildContextStatusHint } from './renderer/context-status-hint.ts';
 import { evaluateSessionMaintenance } from './panels/session-maintenance.ts';
 
-const ALT_SCREEN_ENTER = '\x1b[?1049h';
-const ALT_SCREEN_EXIT  = '\x1b[?1049l';
-const MOUSE_ENABLE     = '\x1b[?1000h\x1b[?1002h\x1b[?1006h';
-const MOUSE_DISABLE    = '\x1b[?1006l\x1b[?1002l\x1b[?1000l';
-const CURSOR_HIDE      = '\x1b[?25l';
-const CURSOR_SHOW      = '\x1b[?25h';
-const CLEAR_SCREEN     = '\x1b[2J\x1b[3J\x1b[H';
-const KEYBOARD_EXT_ENABLE  = '\x1b[>4;2m' + '\x1b[?1u';
-const KEYBOARD_EXT_DISABLE = '\x1b[>4;0m' + '\x1b[?1l';
-const PASTE_ENABLE     = '\x1b[?2004h';
-const PASTE_DISABLE    = '\x1b[?2004l';
+const ALT_SCREEN_ENTER = '\x1b[?1049h'; const ALT_SCREEN_EXIT  = '\x1b[?1049l';
+const MOUSE_ENABLE     = '\x1b[?1000h\x1b[?1002h\x1b[?1006h'; const MOUSE_DISABLE    = '\x1b[?1006l\x1b[?1002l\x1b[?1000l';
+const CURSOR_HIDE      = '\x1b[?25l'; const CURSOR_SHOW = '\x1b[?25h'; const CLEAR_SCREEN = '\x1b[2J\x1b[3J\x1b[H';
+const KEYBOARD_EXT_ENABLE  = '\x1b[>4;2m' + '\x1b[?1u'; const KEYBOARD_EXT_DISABLE = '\x1b[>4;0m' + '\x1b[?1l';
+const PASTE_ENABLE = '\x1b[?2004h'; const PASTE_DISABLE = '\x1b[?2004l';
 
 async function main() {
   const stdout = process.stdout;
@@ -315,10 +309,11 @@ async function main() {
     }
     if (processedText || content) {
       void (async () => {
-        let inputOptions = options.spokenOutput ? createSpokenTurnInputOptions() : undefined;
-        if (options.spokenOutput && processedText) {
-          spokenTurns.submitNextTurn(processedText);
-        }
+        const inputOptions = options.spokenOutput ? createSpokenTurnInputOptions() : undefined;
+        if (options.spokenOutput && processedText) { spokenTurns.submitNextTurn(processedText); }
+        // Snapshot pre-submission state for failover retryTurn; also clears visited set.
+        retryCtx = { count: conversation.getMessageCount(), text: processedText, content, opts: inputOptions };
+        streamResult.clearFailoverVisited();
         orchestrator.handleUserInput(processedText, content, inputOptions).catch((err: unknown) => {
           logger.debug('handleUserInput safety catch (already handled by runTurn)', { error: summarizeError(err) });
         });
@@ -689,7 +684,6 @@ async function main() {
     render,
   });
 
-  // --- Turn-completed / git-refresh event wiring ---
   const { refreshGit, unsubs: turnUnsubs } = wireTurnEventHandlers({
     events: uiServices.events,
     conversation,
@@ -709,16 +703,22 @@ async function main() {
   });
   unsubs.push(...turnUnsubs);
 
-  // --- Stream metrics + tool-timer event wiring ---
-  const streamUnsubs = wireStreamEventMetrics({
-    events: uiServices.events,
-    orchestrator,
-    providerRegistry,
-    systemMessageRouter,
-    render,
-    metrics: streamMetrics,
+  // Stable turn context for failover retry — set in submitInput, read by retryTurn.
+  let retryCtx: { count: number; text: string; content?: ContentPart[]; opts?: Parameters<typeof orchestrator.handleUserInput>[2] } | null = null;
+  const streamResult: WireStreamEventMetricsResult = wireStreamEventMetrics({
+    events: uiServices.events, orchestrator, providerRegistry,
+    systemMessageRouter, render, metrics: streamMetrics,
+    providerOptimizer: ctx.services.providerOptimizer,
+    retryTurn: () => {
+      if (!retryCtx) return;
+      const { count, text, content: rContent, opts: rOpts } = retryCtx;
+      // Roll back to pre-submission count (strips error system messages), then
+      // re-submit. SDK gap — no retry-in-place; see HANDOFF item (Issue 2).
+      conversation.removeMessagesAfter(count);
+      orchestrator.handleUserInput(text, rContent, rOpts).catch((e: unknown) => logger.debug('retryTurn', { error: summarizeError(e) }));
+    },
   });
-  unsubs.push(...streamUnsubs);
+  unsubs.push(...streamResult.unsubs);
 
   // --- Terminal setup ---
   stdin.setRawMode(true);

package/src/renderer/compaction-history-modal.ts

@@ -0,0 +1,55 @@
+/**
+ * Compaction history text builder.
+ *
+ * Renders a read-only list of past compaction events sourced from the SDK's
+ * module-level compaction event log (`getCompactionEvents()`).
+ *
+ * The SDK records CompactionEvent data (timestamps, token counts,
+ * trigger, message counts) but does not expose a snapshot restore API.
+ * Restore is list-only; users can view what compactions ran but cannot roll back.
+ */
+
+import { getCompactionEvents } from '@pellux/goodvibes-sdk/platform/core';
+import type { CompactionEvent } from '@pellux/goodvibes-sdk/platform/core';
+
+// ─── formatCompactionEvent ────────────────────────────────────────────────────
+
+function formatCompactionEvent(ev: CompactionEvent, n: number): string {
+  const date = new Date(ev.timestamp);
+  const timeStr = date.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+  const savings = Math.max(0, ev.tokensBeforeEstimate - ev.tokensAfterEstimate);
+  const savingsPct = ev.tokensBeforeEstimate > 0
+    ? Math.round((savings / ev.tokensBeforeEstimate) * 100)
+    : 0;
+  const trigger = ev.trigger === 'auto' ? 'auto' : 'manual';
+  return (
+    `#${n} ${timeStr} [${trigger}]  ` +
+    `${ev.messagesBeforeCompaction}→${ev.messagesAfterCompaction} msgs  ` +
+    `~${fmtN(ev.tokensBeforeEstimate)}→~${fmtN(ev.tokensAfterEstimate)} tok  ` +
+    `saved ${savingsPct}%`
+  );
+}
+
+function fmtN(n: number): string {
+  return n.toLocaleString();
+}
+
+/**
+ * Build a plain-text compaction history summary suitable for ctx.print().
+ * Useful as the output of /compact-history when not in overlay mode.
+ */
+export function buildCompactionHistoryText(): string {
+  const events = getCompactionEvents();
+  if (events.length === 0) {
+    return '[Context] No compactions recorded this session. (Restore is not available — the SDK does not yet expose a snapshot restore API.)';
+  }
+  const lines: string[] = [
+    `[Context] Compaction history (${events.length} total, most recent first):`,
+  ];
+  const ordered = [...events].reverse();
+  for (let i = 0; i < ordered.length; i++) {
+    lines.push('  ' + formatCompactionEvent(ordered[i], ordered.length - i));
+  }
+  lines.push('  (Restore not available — the SDK does not yet expose a snapshot restore API.)');
+  return lines.join('\n');
+}